diff --git a/CSSGapDecorations/explainer.md b/CSSGapDecorations/explainer.md index fea42c0a..e5dd25cd 100644 --- a/CSSGapDecorations/explainer.md +++ b/CSSGapDecorations/explainer.md @@ -1,4 +1,4 @@ -# CSS Gap Decorations Level 1 +# CSS Gap Decorations ## Authors @@ -28,7 +28,7 @@ content location of future work and discussions. -- [CSS Gap Decorations Level 1](#css-gap-decorations-level-1) +- [CSS Gap Decorations](#css-gap-decorations) - [Authors](#authors) - [Participate](#participate) - [Status of this Document](#status-of-this-document) @@ -38,22 +38,22 @@ content location of future work and discussions. - [Non-goals](#non-goals) - [User research](#user-research) - [Properties](#properties) - - [Placement of gap decorations](#placement-of-gap-decorations) - - [Grid](#grid) - - [Flex, multi-column, and masonry](#flex-multi-column-and-masonry) - [Width, style, and color](#width-style-and-color) - [Extending or shortening gap decoration segments](#extending-or-shortening-gap-decoration-segments) - - [Interaction with spanning items in grid](#interaction-with-spanning-items-in-grid) - - [Logical properties for flex and masonry containers](#logical-properties-for-flex-and-masonry-containers) + - [Interaction with spanning items](#interaction-with-spanning-items) - [Paint order](#paint-order) - - [Bi-directional shorthands](#bi-directional-shorthands) - [Key scenarios](#key-scenarios) - [Scenario 1: Horizontal lines between CSS grid rows](#scenario-1-horizontal-lines-between-css-grid-rows) - [Scenario 2: Lines dividing items in both directions of a grid](#scenario-2-lines-dividing-items-in-both-directions-of-a-grid) - - [Scenario 3: Defining different lines for different gaps, applied to a sub-area of the grid](#scenario-3-defining-different-lines-for-different-gaps-applied-to-a-sub-area-of-the-grid) - - [Scenario 4: Responsive Flex layout](#scenario-4-responsive-flex-layout) - - [Scenario 5: Segmented gap decorations](#scenario-5-segmented-gap-decorations) + - [Scenario 3: Segmented gap decorations](#scenario-3-segmented-gap-decorations) - [Open questions](#open-questions) + - [Future ideas](#future-ideas) + - [Placement of gap decorations](#placement-of-gap-decorations) + - [Grid](#grid) + - [Flex, multi-column, and masonry](#flex-multi-column-and-masonry) + - [Scenario: Defining different lines for different gaps, applied to a sub-area of the grid](#scenario-defining-different-lines-for-different-gaps-applied-to-a-sub-area-of-the-grid) + - [Dropped ideas](#dropped-ideas) + - [Logical properties for flex and masonry containers](#logical-properties-for-flex-and-masonry-containers) - [Considered alternatives](#considered-alternatives) - [Alternative 1: 2021 draft specification](#alternative-1-2021-draft-specification) - [References \& acknowledgements](#references--acknowledgements) @@ -125,57 +125,11 @@ was drawn from discussions in issues ## Properties Unless otherwise noted, corresponding `row-` and `column-` properties should be -assumed to have identical syntax. Maintaining symmetry between `row-` and -`column-` properties is important for responsive flex and masonry scenarios. +assumed to have identical syntax. All such pairs of properties also have `gap-` +shorthands that apply the same values in both directions. For property grammar details, please see the -[draft specification](https://kbabbitt.github.io/css-gap-decorations/). - -### Placement of gap decorations - -These properties allow authors to specify where gap decorations start and end -within a container. - -An author may specify more than one such region and apply a different set of gap -decorations to each. Within this document, we refer to such a region as a *gap -decoration area*. Much like CSS Transitions and Animations, all gap decoration -properties may take a comma-delimited list of values. Each entry in such a list -is applied to the corresponding entry in the list of gap decoration areas. If a -given property's list length is shorter than the gap decoration area list -length, the shorter list cycles back to the beginning as needed. - -Gap decoration area properties are defined per container type. - -#### Grid - -In grid containers, the author may specify any grid line based placement, as in -[the 'grid-row-start', 'grid-row-end', 'grid-column-start', and -'grid-column-end' -properties](https://drafts.csswg.org/css-grid-2/#line-placement). The -corresponding width-style-color gap decoration tuples in the row and column -directions will apply in that area. The initial value is `1 / 1 / -1 / -1` to -cover the entire grid. - -```css -.grid-multiple-decoration-areas { - display: grid; - grid-template-rows: [top] 30px [main-top] repeat(6, 30px) [bottom]; - grid-template-columns: [left] 100px [main-left] repeat(3, 100px) [right]; - grid-gap: 10px; - grid-row-rule-area: left / top / main-left / bottom, - main-left / main-top / right / bottom; - row-rule: 1px solid lightblue, - 1px solid black; - grid-column-rule-area: main-left / top / main-left / bottom; - column-rule: 1px solid lightblue; -} -``` - - - -#### Flex, multi-column, and masonry - -Gap decoration area properties for these container types are not yet defined. +[Editor's Draft](https://drafts.csswg.org/css-gaps-1/). ### Width, style, and color @@ -189,12 +143,7 @@ and masonry containers. If the number of specified values (after expanding any repeats) in a given list is less than the number of gaps in the corresponding direction in the gap -decoration area, the list cycles back to the beginning. This cycling applies -*within* a given gap decoration area, in contrast to the cycling described -previously which applies different sets of values to *multiple* gap decoration -areas. Having a second level of cycling preserves backward compatibility with -existing `column-rule` declarations that only specify single values, while also -enabling authors to specify simple alternating patterns. +decoration area, the list cycles back to the beginning. Shorthands are also available to combine the width, style, and color properties. @@ -278,111 +227,60 @@ default; changing this behavior is covered in a later section of this document. ``` -Authors may specify that decorations are instead segmented between all gap -intersections. In such cases, each segment starts at the edge of a given gap -intersection and proceeds to the edge of the next gap intersection. The -endpoints may be offset from those endpoints using the segment outset -properties. +Authors may adjust the positions of endpoints relative to gap intersections, +either as a fixed distance or as a percentage of the width of the intersection. +The "zero point" is the edge of the intersection, with positive values extending +into the intersection and negative values receding from it. ```css -row-rule-outset: [ | join ]# -column-rule-outset: [ | join ]# -``` - -The initial value is `join` which "joins together" segments to give the default -"T intersections" behavior. Any other value gives the "all intersections" -behavior. Positive values extend into the neighboring intersection; negative -values recede from it. The percentage basis is the width of the gap in the -perpendicular direction. These offsets also apply at the edges of the container, -where negative values may extend into the padding area. - -To facilitate animation of segment outset values, `join` computes to `50%`. - -```css -.segment-outset-0px { - row-rule: 3px solid purple; - column-rule: 3px solid green; +.outset-0px { column-rule-outset: 0px; } ``` - - + ```css -.segment-outset-plus-5px { - row-rule: 3px solid purple; - column-rule: 3px solid green; +.outset-5px { column-rule-outset: 5px; } ``` - - + ```css -.segment-outset-minus-5px { - row-rule: 3px solid purple; - column-rule: 3px solid green; +.outset-negative-5px { column-rule-outset: -5px; } ``` + - - -### Interaction with spanning items in grid +### Interaction with spanning items -For grid containers, authors may control how gap decorations interact with -spanning items within a given gap decoration area. +Authors may also change the set of intersections where gap decorations break, +from the default "T intersections" behavior to either "all intersections" or "no intersections." +In the latter case, gap decorations paint "behind" items in the container. ```css -grid-row-rule-break: [ none | span ]# -grid-column-rule-break: [ none | span ]# -grid-rule-break: [ none | span ]# +.t-intersections { + gap-rule-break: spanning-item; + gap-rule-outset: 0px; +} ``` - -The initial value is `span` which can give either the "T intersections" or "all -intersections" behavior described previously, depending on the value of the -corresponding `rule-outset` property. A value of `none` causes gap decorations -to cross behind spanning items and receive the "T intersection" behavior at the -edges of the gap decoration area. - -In any case, as with existing [column rules in -multi-column](https://drafts.csswg.org/css-multicol-1/#column-gaps-and-rules), -gap decorations are painted just above the border of the container, and -specifically below any items placed within the container. + ```css -.rule-break-none { - grid-rule-break: none; +.all-intersections { + gap-rule-break: intersection; + gap-rule-outset: 0px; } ``` + - - -### Logical properties for flex and masonry containers - -These are designed to enable scenarios where authors wish to switch -`flex-direction` or `masonry-direction` based on space constraints or other -factors. - -| Property | row or row-reverse direction | column or column-reverse direction | -|------------------|------------------------------|------------------------------------| -| main-rule-width | row-rule-width | column-rule-width | -| main-rule-style | row-rule-style | column-rule-style | -| main-rule-color | row-rule-color | column-rule-color | -| main-rule | row-rule | column-rule | -| cross-rule-width | column-rule-width | row-rule-width | -| cross-rule-style | column-rule-style | row-rule-style | -| cross-rule-color | column-rule-color | row-rule-color | -| cross-rule | column-rule | row-rule | - -And so on for other properties. - -For flex and masonry containers, the logical properties map based on -`flex-direction` or `masonry-direction` following the convention above. - -For grid containers, `main` maps to `row`, and `cross` maps to `column`. - -For multi-column containers, `main` maps to `column`, and `cross` maps to `row`. +```css +.no-intersections { + gap-rule-break: none; +} +``` + ### Paint order @@ -390,15 +288,9 @@ When row and column gap decorations overlap, authors can control their painting order. ```css -gap-rule-paint-order: [ row-over-column | column-over-row | main-over-cross | cross-over-main ]# +gap-rule-paint-order: [ row-over-column | column-over-row ] ``` -The `main-over-cross` and `cross-over-main` values are logical alternates for -`row-over-column` and `column-over-row`. They map similarly to properties -described in the previous section. - -The initial value for gap-rule-paint-order is `main-over-cross`. - ```css .row-over-column { row-rule: 6px solid red; @@ -417,21 +309,6 @@ The initial value for gap-rule-paint-order is `main-over-cross`. ``` -### Bi-directional shorthands - -These shorthands apply the same values in both the `main` and `cross` -directions. - -```css -gap-rule-width: [ <'main-rule-width'> ]# -gap-rule-style: [ <'main-rule-style'> ]# -gap-rule-color: [ <'main-rule-color'> ]# - -gap-rule: [ <'main-rule'> ]# - -grid-gap-rule-area: [ <'grid-row-rule-area'> ]# -``` - ## Key scenarios ### Scenario 1: Horizontal lines between CSS grid rows @@ -465,62 +342,119 @@ https://github.com/w3c/csswg-drafts/issues/2748#issuecomment-595663212 -### Scenario 3: Defining different lines for different gaps, applied to a sub-area of the grid +### Scenario 3: Segmented gap decorations -https://github.com/w3c/csswg-drafts/issues/2748#issuecomment-595889781 +https://github.com/w3c/csswg-drafts/issues/2748#issuecomment-446781218 - last +example ```css .container { - gap-rule-style: solid: - gap-rule-color: lightgray; - column-rule-width: 1px repeat(auto, 2px) 1px; - row-rule-width: 0px repeat(auto, 2px 1px); - grid-gap-rule-area: 2 / 2 / -1 / -1; + gap-rule: 1px solid black; + column-rule-outset: 0px; } ``` - + -### Scenario 4: Responsive Flex layout +## Open questions -https://github.com/w3c/csswg-drafts/issues/2748#issuecomment-1765376966 +- How do gap decorations apply to subgrids? +- Can we construct an all-encompassing `gap-rule` shorthand? The challenge here + is that `/` is already heavily loaded in the longhands. + +## Future ideas + +### Placement of gap decorations -> My use case for this is a left-and-right view in landscape that becomes a -> top-and-bottom view in portrait – with a divider in the middle (think split -> screen on a phone). Currently I have to use border-right in landscape, and -> switch to border-bottom in portrait. I would prefer setting a gap rule so the -> line automatically adjusts depending on the flex-direction. +Allow authors to specify where gap decorations start and end within a container. + +An author may specify more than one such region and apply a different set of gap +decorations to each. Within this document, we refer to such a region as a *gap +decoration area*. Much like CSS Transitions and Animations, all gap decoration +properties may take a comma-delimited list of values. Each entry in such a list +is applied to the corresponding entry in the list of gap decoration areas. If a +given property's list length is shorter than the gap decoration area list +length, the shorter list cycles back to the beginning as needed. + +Gap decoration area properties are defined per container type. + +#### Grid + +In grid containers, the author may specify any grid line based placement, as in +[the 'grid-row-start', 'grid-row-end', 'grid-column-start', and +'grid-column-end' +properties](https://drafts.csswg.org/css-grid-2/#line-placement). The +corresponding width-style-color gap decoration tuples in the row and column +directions will apply in that area. The initial value is `1 / 1 / -1 / -1` to +cover the entire grid. ```css -.container { - display: flex; - cross-gap-rule: 1px solid black; +.grid-multiple-decoration-areas { + display: grid; + grid-template-rows: [top] 30px [main-top] repeat(6, 30px) [bottom]; + grid-template-columns: [left] 100px [main-left] repeat(3, 100px) [right]; + grid-gap: 10px; + grid-row-rule-area: left / top / main-left / bottom, + main-left / main-top / right / bottom; + row-rule: 1px solid lightblue, + 1px solid black; + grid-column-rule-area: main-left / top / main-left / bottom; + column-rule: 1px solid lightblue; } ``` - - + -### Scenario 5: Segmented gap decorations +#### Flex, multi-column, and masonry -https://github.com/w3c/csswg-drafts/issues/2748#issuecomment-446781218 - last -example +Gap decoration area properties for these container types are not yet defined. + +#### Scenario: Defining different lines for different gaps, applied to a sub-area of the grid + +https://github.com/w3c/csswg-drafts/issues/2748#issuecomment-595889781 ```css .container { - gap-rule: 1px solid black; - column-rule-outset: 0px; + gap-rule-style: solid: + gap-rule-color: lightgray; + column-rule-width: 1px repeat(auto, 2px) 1px; + row-rule-width: 0px repeat(auto, 2px 1px); + grid-gap-rule-area: 2 / 2 / -1 / -1; } ``` - + -## Open questions +## Dropped ideas -- How do gap decorations apply to subgrids? -- Can we construct an all-encompassing `gap-rule` shorthand? The challenge here - is that `/` is already heavily loaded in the longhands. +### Logical properties for flex and masonry containers + +*This idea was dropped based on feedback raised in the [initial proposal discussion](https://github.com/w3c/csswg-drafts/issues/10393).* + +These are designed to enable scenarios where authors wish to switch +`flex-direction` or `masonry-direction` based on space constraints or other +factors. + +| Property | row or row-reverse direction | column or column-reverse direction | +|------------------|------------------------------|------------------------------------| +| main-rule-width | row-rule-width | column-rule-width | +| main-rule-style | row-rule-style | column-rule-style | +| main-rule-color | row-rule-color | column-rule-color | +| main-rule | row-rule | column-rule | +| cross-rule-width | column-rule-width | row-rule-width | +| cross-rule-style | column-rule-style | row-rule-style | +| cross-rule-color | column-rule-color | row-rule-color | +| cross-rule | column-rule | row-rule | + +And so on for other properties. + +For flex and masonry containers, the logical properties map based on +`flex-direction` or `masonry-direction` following the convention above. + +For grid containers, `main` maps to `row`, and `cross` maps to `column`. + +For multi-column containers, `main` maps to `column`, and `cross` maps to `row`. ## Considered alternatives @@ -539,5 +473,11 @@ even absent support for gap decoration images; see Scenario 3 for one example. Many thanks for valuable feedback and advice from: - Alison Maher +- Benoît Rouleau - Ian Kilpatrick +- Josh Thumath - Kurt Catti-Schmidt +- Lea Verou +- Rachel Andrew +- Sebastian Zartner +- Tab Atkins-Bittner