CSS: justify-content maintenance updates

files/en-us/web/css/justify-content/index.md

@@ -7,44 +7,32 @@ browser-compat: css.properties.justify-content
 
 {{CSSRef}}
 
-The [CSS](/en-US/docs/Web/CSS) **`justify-content`** property defines how the browser distributes space between and around content items along the {{Glossary("Main Axis", "main-axis")}} of a flex container, and the inline axis of a grid container.
+The [CSS](/en-US/docs/Web/CSS) **`justify-content`** property defines how the browser distributes space between and around content items along the {{Glossary("main axis")}} of a flex container and the [inline axis](/en-US/docs/Glossary/Logical_properties#inline_direction) of grid and multicol containers.
 
-The interactive example below demonstrates some of the values using grid layout.
+The interactive example below demonstrates some `justify-content` values using grid layout.
 
 {{EmbedInteractiveExample("pages/css/justify-content.html")}}
 
-The alignment is done after the lengths and auto margins are applied, meaning that, if in a [Flexbox layout](/en-US/docs/Web/CSS/CSS_flexible_box_layout) there is at least one flexible element, with {{cssxref("flex-grow")}} different from `0`, it will have no effect as there won't be any available space.
-
 ## Syntax
 
 ```css
 /* Positional alignment */
-justify-content: center; /* Pack items around the center */
-justify-content: start; /* Pack items from the start */
-justify-content: end; /* Pack items from the end */
-justify-content: flex-start; /* Pack flex items from the start */
-justify-content: flex-end; /* Pack flex items from the end */
-justify-content: left; /* Pack items from the left */
-justify-content: right; /* Pack items from the right */
-
-/* Baseline alignment */
-/* justify-content does not take baseline values */
+justify-content: center;
+justify-content: start;
+justify-content: end;
+justify-content: flex-start;
+justify-content: flex-end;
+justify-content: left;
+justify-content: right;
 
 /* Normal alignment */
 justify-content: normal;
 
 /* Distributed alignment */
-justify-content: space-between; /* Distribute items evenly
-                                   The first item is flush with the start,
-                                   the last is flush with the end */
-justify-content: space-around; /* Distribute items evenly
-                                   Start and end gaps are half the size of the space
-                                   between each item */
-justify-content: space-evenly; /* Distribute items evenly
-                                   Start, in-between, and end gaps have equal sizes */
-justify-content: stretch; /* Distribute items evenly
-                                   Stretch 'auto'-sized items to fit
-                                   the container */
+justify-content: space-between;
+justify-content: space-around;
+justify-content: space-evenly;
+justify-content: stretch;
 
 /* Overflow alignment */
 justify-content: safe center;
@@ -61,40 +49,77 @@ justify-content: unset;
 ### Values
 
 - `start`
+
   - : The items are packed flush to each other toward the start edge of the alignment container in the main axis.
+
 - `end`
+
   - : The items are packed flush to each other toward the end edge of the alignment container in the main axis.
+
 - `flex-start`
+
   - : The items are packed flush to each other toward the edge of the alignment container depending on the flex container's main-start side.
     This only applies to flex layout items. For items that are not children of a flex container, this value is treated like `start`.
+
 - `flex-end`
+
   - : The items are packed flush to each other toward the edge of the alignment container depending on the flex container's main-end side.
     This only applies to flex layout items. For items that are not children of a flex container, this value is treated like `end`.
+
 - `center`
+
   - : The items are packed flush to each other toward the center of the alignment container along the main axis.
+
 - `left`
+
   - : The items are packed flush with each other toward the left edge of the alignment container. When the property's horizontal axis is not parallel with the inline axis, such as when [`flex-direction: column;`](/en-US/docs/Web/CSS/flex-direction) is set, this value behaves like `start`.
+
 - `right`
+
   - : The items are packed flush to each other toward the right edge of the alignment container in the appropriate axis. If the property's axis is not parallel with the inline axis (in a grid container) or the main-axis (in a flexbox container), this value behaves like `start`.
+
 - `normal`
+
   - : Behaves as `stretch`, except in the case of multi-column containers with a non-`auto` [`column-width`](/en-US/docs/Web/CSS/column-width), in which case the columns take their specified `column-width` rather than stretching to fill the container. As `stretch` behaves as `start` in flex containers, `normal` also behaves as `start`.
+
 - `space-between`
+
   - : The items are evenly distributed within the alignment container along the main axis. The spacing between each pair of adjacent items is the same. The first item is flush with the main-start edge, and the last item is flush with the main-end edge.
+
 - `space-around`
-  - : The items are evenly distributed within the alignment container along the main axis. The spacing between each pair of adjacent items is the same. The empty space before the first and after the last item equals half of the space between each pair of adjacent items.
+
+  - : The items are evenly distributed within the alignment container along the main axis. The spacing between each pair of adjacent items is the same. The empty space before the first and after the last item equals half of the space between each pair of adjacent items. If there is only one item, it will be centered.
+
 - `space-evenly`
+
   - : The items are evenly distributed within the alignment container along the main axis. The spacing between each pair of adjacent items, the main-start edge and the first item, and the main-end edge and the last item, are all exactly the same.
+
 - `stretch`
 
   - : If the combined size of the items along the main axis is less than the size of the alignment container, any `auto`-sized items have their size increased equally (not proportionally), while still respecting the constraints imposed by {{cssxref("max-height")}}/{{cssxref("max-width")}} (or equivalent functionality), so that the combined size exactly fills the alignment container along the main axis.
 
     > **Note:** For [flexboxes](/en-US/docs/Web/CSS/CSS_flexible_box_layout/Basic_concepts_of_flexbox), the `stretch` value behaves as `flex-start` or `start`. This is because, in flexboxes, stretching is controlled using the {{CSSXref("flex-grow")}} property.
 
 - `safe`
+
   - : If the item overflows the alignment container, then the item is aligned as if the alignment mode is `start`. The desired alignment will not be implemented.
+
 - `unsafe`
+
   - : Even if the item overflows the alignment container, the desired alignment will be implemented. Unlike `safe`, which will ignore the desired alignment in favor of preventing overflow.
 
+## Description
+
+Defined in the [CSS box alignment](/en-US/docs/Web/CSS/CSS_box_alignment) module, `justify-content` applies to multicol containers, flex containers, and grid containers. The property does not apply to and has no effect on block containers.
+
+This property shares many keyword values with the {{cssxref("align-content")}} property, but not all! The `justify-content` isn't involved in baseline alignment, and therefore does not take baseline values.
+
+In [flex layouts](/en-US/docs/Web/CSS/CSS_flexible_box_layout), the property defines how positive free space in each flex line is distributed between or around flex items, along the main axis. This property impacts the elements in a line, not between lines. The alignment is done after the lengths and auto margins are applied, which means that when one or more flex items in a line have a {{cssxref("flex-grow")}} factor greater than `0` the property has no effect on flex lines as that line has no available space to distribute. Also, as stretching in the main axis is controlled by {{cssxref("flex")}}, the `stretch` value behaves as `flex-start`.
+
+With [grid layout](/en-US/docs/Web/CSS/CSS_grid_layout), this property distributes available space between or around grid columns, not grid items. If the grid container is larger than the grid itself, the `justify-content` property can be used to justify the grid along the inline axis, aligning the grid columns.
+
+Grid `auto` track sizes (and only `auto` track sizes) can be stretched by the `align-content` and `justify-content` properties. Therefore by default, an `auto` sized track will take up any remaining space in the grid container. As the grid's inline size has to be less than the grid container's inline size for there to be space to distribute, in this case the property has no effect.
+
 ## Formal definition
 
 {{cssinfo}}
@@ -105,29 +130,225 @@ justify-content: unset;
 
 ## Examples
 
-### Setting flex item distribution
+### Basic grid example
+
+In this example, we have a grid that is narrower than its grid container, and we use `justify-content` to distribute the available space evenly around and between the grid columns.
+
+#### HTML
+
+The {{htmlelement("section")}} container, our to-be grid container, has 16 nested {{htmlelement("div")}} to-be flex item elements.
+
+```html
+<section class="container">
+  <div>A</div>
+  <div>B</div>
+  <div>C</div>
+  <div>D</div>
+  <div>E</div>
+  <div>F</div>
+  <div>G</div>
+  <div>H</div>
+  <div>I</div>
+  <div>J</div>
+  <div>K</div>
+  <div>L</div>
+  <div>M</div>
+  <div>N</div>
+  <div>O</div>
+  <div>P</div>
+</section>
+```
 
 #### CSS
 
+```css hidden
+.container {
+  margin: 5px;
+  border: 1px solid;
+  box-sizing: border-box;
+}
+
+div {
+  line-height: 2em;
+  border: 1px solid;
+  box-sizing: border-box;
+  text-align: center;
+}
+```
+
+We set the width of the container to `500px` but only have three columns that are each `80px` wide, meaning there is `260px` of available space to distribute between or around the grid columns. We set `justify-content: space-evenly`, which means there will be `65px` of space before, between, and after each column.
+
+We set different widths (and background colors) to demonstrate how the justification is applied to the columns.
+
+```css
+.container {
+  display: grid;
+  grid: auto-flow / repeat(3, 80px);
+  width: 500px;
+  justify-content: space-evenly;
+}
+
+div {
+  background-color: pink;
+  width: 80px;
+}
+
+div:nth-of-type(n + 9) {
+  width: 35px;
+  background-color: lightgreen;
+}
+
+div:nth-last-of-type(3) {
+  width: 250px;
+  background-color: lightblue;
+}
+```
+
+#### Result
+
+{{EmbedLiveSample("Basic grid example", "100%", 220)}}
+
+Note that `justify-contents` aligns the columns and has no effect on the items or alignment in grid areas. Grid items, even those that overflow their grid cell, do not impact column justification.
+
+### The safe keyword
+
+This example demonstrates the `safe` keyterm. Four centered flex items are not allowed to wrap, overflow their single flex-line container. By adding `safe` to `center` in the `justify-content` property, overflowing content behaves as if the alignment mode is `start`
+
+```html hidden
+<p><code>justify-content: center;</code></p>
+<section class="container safe">
+  <div>A</div>
+  <div>B</div>
+  <div>C</div>
+  <div>D</div>
+</section>
+<p><code>justify-content: safe center;</code></p>
+<section class="container safe-center">
+  <div>A</div>
+  <div>B</div>
+  <div>C</div>
+  <div>D</div>
+</section>
+<p><code>justify-content: safe center;</code> with 3 items</p>
+<section class="container">
+  <div>A</div>
+  <div>B</div>
+  <div>C</div>
+</section>
+```
+
+```css hidden
+.container {
+  margin: 5px auto;
+  border: 1px dashed;
+  box-sizing: border-box;
+  background-color: lightblue;
+}
+
+div {
+  line-height: 1em;
+  border: 1px solid;
+  box-sizing: border-box;
+  text-align: center;
+  background-color: pink;
+}
+```
+
+The container is set to `center`, with every container other than the first having the `safe` keyword added:
+
+```css
+.container {
+  justify-content: center;
+  align-items: baseline;
+  display: flex;
+  width: 350px;
+  height: 2em;
+}
+
+.safe-center {
+  justify-content: safe center;
+}
+
+div {
+  flex: 0 0 100px;
+}
+```
+
+#### Result
+
+{{EmbedLiveSample("the safe keyword", "100%", 260)}}
+
+As an item overflows the alignment container, with `safe` included, the alignment mode is `start` and the `center` alignment is not implemented. The `safe` keyterm has no effect if the items do not overflow the container.
+
+### Visualizing flex item distribution
+
+This example includes a multi-line wrapping flex layout. The second flex item has a positive flex growth factor, consuming all the available free space in the first flex line.
+
+#### CSS
+
+```css hidden
+#container {
+  margin: 5px auto;
+  border: 1px dashed black;
+  box-sizing: border-box;
+}
+
+div {
+  line-height: 2em;
+  border: 1px solid;
+  box-sizing: border-box;
+  text-align: center;
+}
+```
+
 ```css
 #container {
   display: flex;
+  flex-flow: row wrap;
   justify-content: space-between; /* Can be changed in the live sample */
+  width: 510px;
 }
 
-#container > div {
-  width: 100px;
-  height: 100px;
-  background: linear-gradient(-45deg, #788cff, #b4c8ff);
+div {
+  line-height: 2em;
+  flex: 0 0 120px;
+  background-color: pink;
+}
+
+div:nth-of-type(2) {
+  flex-grow: 1;
+  background-color: yellow;
+}
+
+div:nth-of-type(n + 9) {
+  flex: 0 0 35px;
+  background-color: lightgreen;
+}
+div:last-of-type {
+  flex: 0 0 300px;
+  background-color: lightblue;
 }
 ```
 
 ```html hidden
-<div id="container">
-  <div></div>
-  <div></div>
-  <div></div>
-</div>
+<section id="container">
+  <div>A</div>
+  <div>GROW</div>
+  <div>C</div>
+  <div>D</div>
+  <div>E</div>
+  <div>F</div>
+  <div>G</div>
+  <div>H</div>
+  <div>I</div>
+  <div>J</div>
+  <div>K</div>
+  <div>L</div>
+  <div>M</div>
+  <div>N</div>
+  <div>O</div>
+  <div>P</div>
+</section>
 <select id="justifyContent">
   <option value="start">start</option>
   <option value="end">end</option>
@@ -152,7 +373,9 @@ justifyContent.addEventListener("change", (evt) => {
 
 #### Result
 
-{{EmbedLiveSample("Setting_flex_item_distribution", "100%", 180)}}
+{{EmbedLiveSample("Visualizing_flex_item_distribution", "100%", 180)}}
+
+Select different keywords from the drop-down menu to visualize the different `justify-content` keyword values. Because an item on the first line can grow, there is no available space for the `justify-content` property to distribute on that line only. With the `space-between` value, the first item on each line is flush with the main-start edge, and the last item is flush with the main-end edge; this means if a line has only one item, it will be at the main-start edge (as seen in the last line). This is not the case for other `space-*` values, such as `space-evenly` and `space-around`, which centers one-item flex-lines.
 
 ## Specifications