From 26a029d407be480d791972afb5975cf62c9360a6 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 19 Apr 2024 02:47:55 +0200 Subject: Adding upstream version 124.0.1. Signed-off-by: Daniel Baumann --- layout/docs/css-gap-decorations/Overview.bs | 1228 +++++++++++++++++++++++++++ 1 file changed, 1228 insertions(+) create mode 100644 layout/docs/css-gap-decorations/Overview.bs (limited to 'layout/docs/css-gap-decorations/Overview.bs') diff --git a/layout/docs/css-gap-decorations/Overview.bs b/layout/docs/css-gap-decorations/Overview.bs new file mode 100644 index 0000000000..982ec7dd3e --- /dev/null +++ b/layout/docs/css-gap-decorations/Overview.bs @@ -0,0 +1,1228 @@ + + +
+Title: CSS Gap Decorations
+Shortname: css-gap-decorations
+Level: 1
+Status: ED
+Work Status: exploring
+Group: CSSWG
+URL: https://matspalmgren.github.io/css-gap-decorations/Overview.html
+Editor: Mats Palmgren, Mozilla Corporation http://mozilla.com, mats@mozilla.com
+Abstract: This is a proposal to extend CSS Box Alignment to support gap decorations.
+Markup Shorthands: biblio yes
+Markup Shorthands: css yes
+Markup Shorthands: dfn yes
+Boilerplate: repository-issue-tracking off
+Issue Tracking: CSSWG github issue #6748 https://github.com/w3c/csswg-drafts/issues/6748
+
+
+spec:css-box-4; type:value; for:; text:margin-box
+spec:css-grid-3; type:dfn; text:masonry axis
+spec:css-grid-2; type:dfn; text:collapsed track
+
+ +Introduction {#intro} +===================== + + This section is not normative. + +Overview {#overview} +-------------------- + + + This is a proposal to add CSS features for decorating gaps. + (Some use cases and background discussion can be found in issue #2748.) + We propose to extend the 'column-rule-width' property with new values. + Add properties to support images and gradients. + Add properties for aligning the rule to specific anchor points, + specifying its extent area, and to control its position and length within that area. + We add support for row rules by adding the corresponding 'row-*' properties. + We also widen the scope of these properties so that they can be used in + flex containers, grid containers, + table and table-row-group containers, + as well as multi-column containers. + + +Module Interactions {#placement} +-------------------------------- + + This module extends the definition of the 'column-rule-width' property, + adding <> and ''row-rule-width/auto'' values. + We also generalize the existing ''column-rule-*'' properties to apply to other + types of containers. + Accordingly, we propose to move the existing ''column-rule'' properties from + the Multi-column spec to + the Box Alignment spec. + Additionally, all new properties and shorthands in this proposal are intended + as additions to the Box Alignment spec. + + +Definitions {#definitions} +-------------------------------- + + In this specification, we will use the term lateral axis to refer to + the axis in which the rule's thickness grows (i.e. the axis ''column-rule-width'' + use). The other axis is the rule's longitudinal axis and + its size in this axis is the rule length. + These definitions are relative to the rule itself and does not depend on if + the rule is a row or column rule, or what the 'writing-mode' is. + +Rule Images and Gradients {#rule-image} +======================================= + + Authors may specify an image or gradient to be used in place of the ''column-rule-style''. + These properties are loosely modeled after the corresponding + 'border-image-*' properties. + Rules are one-dimensional though, as opposed to borders which have four sides around an area. + A rule is like a border with just one side rendered with the other sides having ''border-style: none''. + +The 'column-rule-image-source' and 'row-rule-image-source' Properties {#column-rule-image-source} +------------------------------------------------------------------------------------------------- + + 
+        Name: column-rule-image-source, row-rule-image-source
+        Value: none | <>
+        Initial: none
+        Applies to: multi-column containers, flex containers, grid containers, table and table-row-group containers
+        Inherited: no
+        Percentages: N/A
+        Computed value: the keyword ''column-rule-image-source/none'' or the computed <>
+        Animation type: discrete
+
+ + These properties specify an <> to use in place of the rendering specified + by the ''column-rule-style''/''row-rule-style'' properties. + + As for borders, a rule image is not rendered when the corresponding ''column-rule-style''/''row-rule-style'' is ''column-rule-style/none''. + +The 'column-rule-image-slice' and 'row-rule-image-slice' Properties {#column-rule-image-slice} +---------------------------------------------------------------------------------------------- + + 
+        Name: column-rule-image-slice, row-rule-image-slice
+        Value: [<> | <>]{1,2}
+        Initial: 0
+        Applies to: multi-column containers, flex containers, grid containers, table and table-row-group containers
+        Inherited: no
+        Percentages: refer to image size in the rule's longitudinal axis
+        Computed value: one or two values, each either a number or percentage
+        Animation type: discrete
+
+ + 'column-rule-image-slice' specify inward offsets from the start and end edges + of the image in the rule's longitudinal axis, dividing it into three regions: + two edge areas and one middle area. + + When two values are specified, they set the offsets on the start and end sides in + that order. If the end value is missing, it is the same as the start value. + +
+
<> +
Percentages are relative to the image size in the rule's longitudinal axis + +
<> +
Numbers represent pixels in the image (if the image is a raster + image) or vector coordinates (if the image is a vector image). +
+ + Negative values are not allowed. + Computed values larger than the size of the image are interpreted as ''100%''. + + If the image must be sized to determine the slices + (for example, for SVG images with no intrinsic size), + then it is sized using the [[css-images-3#default-sizing]] + with no [=specified size=] and the [=rule containing rectangle=] as the [=default object size=]. + + The regions given by the 'column-rule-image-slice' values may overlap. + However if the sum of the start and end values is equal to or greater than + the size of the image, the middle part becomes empty. + + +The 'column-rule-image-repeat' and 'row-rule-image-repeat' Properties {#column-rule-image-repeat} +------------------------------------------------------------------------------------------------- + + 
+        Name: column-rule-image-repeat, row-rule-image-repeat
+        Value: stretch | repeat | round | space
+        Initial: stretch
+        Applies to: multi-column containers, flex containers, grid containers, table and table-row-group containers
+        Inherited: no
+        Percentages: N/A
+        Computed value: the specified keyword
+        Animation type: discrete
+
+ + These properties specify how the middle part of a sliced rule image is scaled and tiled. + Values have the following meanings: + +
+
stretch
+
The image is stretched to fill the area. +
repeat
+
The image is tiled (repeated) to fill the area. +
round
+
The image is tiled (repeated) to fill the area. If it does not + fill the area with a whole number of tiles, the image is rescaled + so that it does. +
space
+
The image is tiled (repeated) to fill the area. If it does not + fill the area with a whole number of tiles, the extra space is + distributed around the tiles. +
+ + The exact process for scaling and tiling the image parts is defined by drawing the equivalent + ''border-image'' with the top and bottom ''border-image-slice'' values set from the corresponding + ''column-rule-image-slice'' values, and the ''border-image-slice'' left value set to ''100%'' and + the right value set to ''0''. The ''border-image-width'' top value set to the ''column-rule-image-slice'' + top value. The ''border-image-width'' top value set to the ''column-rule-image-slice'' + bottom value. The ''border-image-width'' top value set to zero. + + + +The 'column-rule-image' and 'row-rule-image' Shorthands {#column-rule-image} +---------------------------------------------------------------------------- + + 
+        Name: column-rule-image, row-rule-image
+        Value: <<'column-rule-image-source'>> || <<'column-rule-image-slice'>> || <<'column-rule-image-repeat'>>
+        Applies to: multi-column containers, flex containers, grid containers, table and table-row-group containers
+
+ + + + + + + + + + + +Rule Positioning and Sizing {#size} +=================================== + +The 'column-rule-width' and 'row-rule-width' Properties {#column-rule-width} +---------------------------------------------------------------------------- + + 
+        Name: column-rule-width
+        New Values: <> | auto
+        Initial: medium
+        Applies to: multi-column containers, flex containers, grid containers, table and table-row-group containers
+        Inherited: no
+        Percentages: refer to the [=rule containing rectangle's=] size in the rule's [=lateral axis=]
+        Computed value: absolute length if the specified value is <>; ''0px'' if the column rule style is ''column-rule-style/none'' or ''column-rule-style/hidden''. Otherwise, the specified value.
+        Animation type: by computed value type
+
+ + 
+        Name: row-rule-width
+        Value: <> | <> | auto
+        Initial: medium
+        Applies to: multi-column containers, flex containers, grid containers, table and table-row-group containers
+        Inherited: no
+        Percentages: refer to the [=rule containing rectangle's=] size in the rule's [=lateral axis=]
+        Computed value: absolute length if the specified value is <>; ''0px'' if the column rule style is ''row-rule-style/none'' or ''row-rule-style/hidden''. Otherwise, the specified value.
+        Animation type: by computed value type
+
+ + These properties sets the thickness (lateral size) of a rule in the column and row axis, respectively. + Negative specified values are not allowed. + The [=used value=] is floored at zero (in case a 'calc()' expression evaluates to a negative value for example). + + See [[#resolving-position-and-size-algo]] below for how 'auto' is resolved. + + +The 'column-rule-length' and 'row-rule-length' Properties {#column-rule-length} +------------------------------------------------------------------------------- + + 
+        Name: column-rule-length, row-rule-length
+        Value: <> | auto
+        Initial: auto
+        Applies to: multi-column containers, flex containers, grid containers, table and table-row-group containers
+        Inherited: no
+        Percentages: refer to the [=rule containing rectangle's=] size in the rule's [=longitudinal axis=]
+        Computed value: the specified value
+        Animation type: by computed value type
+
+ + These properties sets the [=rule length=] (longitudinal size) of a rule in the column and row axis, respectively. + Negative specified values are not allowed. + The [=used value=] is floored at zero (in case a 'calc()' expression evaluates to a negative value for example). + + See [[#resolving-position-and-size-algo]] below for how 'auto' is resolved. + + Note: These properties work the same as the '*-rule-width' properties in the [=lateral axis=], except that they have a different initial value. + + +The Rule Lateral Inset Properties {#column-rule-lateral-inset-start} +-------------------------------------------------------------------- + + 
+        Name: column-rule-lateral-inset-start, column-rule-lateral-inset-end, row-rule-lateral-inset-start, row-rule-lateral-inset-end
+        Value: <> | auto
+        Initial: auto
+        Applies to: multi-column containers, flex containers, grid containers, table and table-row-group containers
+        Inherited: no
+        Percentages: refer to the [=rule containing rectangle's=] size in the rule's [=lateral axis=]
+        Computed value: the specified value
+        Animation type: by computed value type
+
+ + These properties sets the lateral start/end offset of the rule in the column and row axis, respectively. + A positive value moves the position inward and a negative value outward from the corresponding [=rule containing rectangle's=] edge. + + + + + + NOTE: The ''column-rule-lateral-inset'' and ''column-rule-width'' [=used values=] are calculated in a similar way to how 'left'/'right' and + 'width' are calculated for an absolutely positioned + box. The precise algorithm is described next. + + +Resolving a rule's position and size {#resolving-position-and-size-algo} +------------------------------------------------------------------------ + + Given a triplet of values: inset-start/end and a size for an axis, ''column-rule-width/auto'' values + are resolved so that the sum of the three values equals the [=rule containing rectangle=] size in + the same axis. These are the rules for resolving them: +
    +
  1. if all the values are ''column-rule-width/auto'' then set both inset values to zero and solve for size +
  2. if none of the values are ''column-rule-width/auto'' then the situation is over-constrained: solve by + treating the end inset value as ''column-rule-width/auto'' +
  3. if both inset properties are ''column-rule-width/auto'', but the size is not, then solve with the additional constraint + that the inset values must have equal values (resulting in the rule being centered) +
  4. if the size is ''column-rule-width/auto'' and only one of the inset values is ''column-rule-width/auto'' then set the ''column-rule-width/auto'' inset value to zero + and solve for size, if that makes size negative then set the size to zero and solve for the ''column-rule-width/auto'' + inset value instead (i.e. the rule is sized to fill the remaining space, until it becomes zero in + which case its positioned at the non-''column-rule-width/auto'' inset edge) +
  5. if the size is ''column-rule-width/auto'' and both inset values are non-''column-rule-width/auto'' then solve for size, + if that makes the size negative then set the size to zero and solve again by + treating the end inset value as ''column-rule-width/auto'' +
+ + These rules resolves the ''column-rule-width'', ''column-rule-lateral-inset-start'', and ''column-rule-lateral-inset-end'' triplet + of values in a rule's lateral axis. + + The same rules are also used to resolve ''column-rule-length'', ''column-rule-longitudinal-[edge-]inset-start'', and ''column-rule-longitudinal-[edge-]inset-end'' triplet of values in a rule's longitudinal axis (see the longitudinal property + descriptions below for which of the "edge" or non-"edge" values is used). + + Ditto for the corresponding ''row-rule-*'' properties. + + + + +The 'column-rule-lateral-inset' and 'row-rule-lateral-inset' Shorthands {#column-rule-lateral-inset} +---------------------------------------------------------------------------------------------------- + + 
+        Name: column-rule-lateral-inset
+        Value: <<'column-rule-lateral-inset-start'>> <<'column-rule-lateral-inset-end'>>?
+
+ + 
+        Name: row-rule-lateral-inset
+        Value: <<'row-rule-lateral-inset-start'>> <<'row-rule-lateral-inset-end'>>?
+
+ + These are shortands for specifying the corresponding start/end values. + If one value is specified it is used for both start and end. + + +The Rule Longitudinal Inset Properties {#column-rule-longitudinal-inset-start} +------------------------------------------------------------------------------ + + 
+        Name: column-rule-longitudinal-inset-start, column-rule-longitudinal-inset-end, row-rule-longitudinal-inset-start, row-rule-longitudinal-inset-end
+        Value: <> | auto
+        Initial: 0
+        Applies to: multi-column containers, flex containers, grid containers, table and table-row-group containers
+        Inherited: no
+        Percentages: refer to the [=rule containing rectangle's=] size in the rule's [=longitudinal axis=]
+        Computed value: the specified value
+        Animation type: by computed value type
+
+ + These properties sets the longitudinal start/end inset of the rule in the column + and row axis, respectively. They are only used on a rule's edges that are interior. + The *-rule-longitudinal-edge-inset + properties are used for rule edges that are on the outer edges of an axis. + The [=used values=] are calculated the same as for the lateral properties above. + + + + Note: These have a different initial value than the lateral inset properties, meaning the rule will stretch to fill the [=rule containing rectangle=] in this axis. The initial values as specified above are backward compatible with how column rules are sized and positioned in legacy multi-column layout. + + + + + + +The 'column-rule-longitudinal-inset' and 'row-rule-longitudinal-inset' Shorthands {#column-rule-longitudinal-inset} +------------------------------------------------------------------------------------------------------------------- + + 
+        Name: column-rule-longitudinal-inset
+        Value: <<'column-rule-longitudinal-inset-start'>> <<'column-rule-longitudinal-inset-end'>>?
+
+ + 
+        Name: row-rule-longitudinal-inset
+        Value: <<'row-rule-longitudinal-inset-start'>> <<'row-rule-longitudinal-inset-end'>>?
+
+ + These shortands specify the corresponding start/end values. If one value is specified it is used for both start/end. + + +The Rule Longitudinal Edge Inset Properties {#column-rule-longitudinal-edge-inset-start} +------------------------------------------------------------------------------ + + 
+        Name: column-rule-longitudinal-edge-inset-start, column-rule-longitudinal-edge-inset-end, row-rule-longitudinal-edge-inset-start, row-rule-longitudinal-edge-inset-end
+        Value: <> | auto
+        Initial: 0
+        Applies to: multi-column containers, flex containers, grid containers, table and table-row-group containers
+        Inherited: no
+        Percentages: refer to the [=rule containing rectangle's=] size in the rule's [=longitudinal axis=]
+        Computed value: the specified value
+        Animation type: by computed value type
+
+ + These properties are identical to their non-"edge" counter-parts. These properties are used + on the start edge of the first rule that on the container's start edge in its + [=longitudinal axis=], and the end edge of the last rule at the end of the container. + For interior rule edges, the non-"edge" properties are used. + In other words, these properties are used together with the ''*-rule-edge-align'' + properties (defined below) and the ''*-rule-longitudinal-inset'' properties are used together with ''*-rule-align''. + + +The 'column-rule-longitudinal-edge-inset' and 'row-rule-longitudinal-edge-inset' Shorthands {#column-rule-longitudinal-edge-inset} +------------------------------------------------------------------------------------------------------------------- + + 
+        Name: column-rule-longitudinal-edge-inset
+        Value: <<'column-rule-longitudinal-edge-inset-start'>> <<'column-rule-longitudinal-edge-inset-end'>>?
+
+ + 
+        Name: row-rule-longitudinal-edge-inset
+        Value: <<'row-rule-longitudinal-edge-inset-start'>> <<'row-rule-longitudinal-edge-inset-end'>>?
+
+ + These shortands specify the corresponding start/end values. If one value is specified it is used for both start/end. + + +Row Rule Style and Color {#row-rule-props} +=============================================== + +The 'row-rule-style' and 'row-rule-color' Properties {#row-rule-style} +-------------------------------------------------- + + 
+        Name: row-rule-style
+        Value: <>
+        Initial: none
+        Applies to: multi-column containers, flex containers, grid containers, table and table-row-group containers
+        Inherited: no
+        Percentages: N/A
+        Computed value: specified keyword
+        Animation type: discrete
+
+ + 
+        Name: row-rule-color
+        Value: <>
+        Initial: currentcolor
+        Applies to: multi-column containers, flex containers, grid containers, table and table-row-group containers
+        Inherited: no
+        Percentages: N/A
+        Computed value: computed color
+        Animation type: by computed value type
+
+ + These properties are the same as the ''column-'' properties but for the row rules. + +The 'row-rule' Shorthand {#row-rule} +-------------------------------------------------- + + This shorthand works the same as ''column-rule''. + + 
+        Name: row-rule
+        Value: <<'row-rule-width'>> || <<'row-rule-style'>> || <<'row-rule-color'>>
+
+ + ISSUE: lots of new possible shorthands... we now have many + properties (and shorthands) with a ''column-rule'' and ''row-rule'' prefix. + Should we add shorthands for some of those with a 'rule' prefix to specify + both axes, like so: 'rule-foo: <> <>?'. + As usual, we have to be careful with the separator though, to make it + forward-compatible with any changes we might want to make... + + +Rule Alignment {#rule-align} +============================ + +The 'column-rule-align' and 'row-rule-align' Properties {#column-rule-align} +-------------------------------------------------- + + 
+        Name: column-rule-align, row-rule-align
+        Value: [gap | gap-center | gap-over | rule | rule-center | rule-over]{1,2}
+        Initial: gap
+        Applies to: multi-column containers, flex containers, grid containers, table and table-row-group containers
+        Inherited: no
+        Percentages: N/A
+        Computed value: the specified value
+        Animation type: discrete
+
+ + These properties specify the start/end attachment point of the [=rule containing rectangle=] + in the [=longitudinal axis=]. The start value is specified first, the end value second. + If only one value is specified it is used for both start and end. + These properties are only used for interior edges. The '*-rule-edge-align' properties + described below specify the alignment on the outer edges. The initial value, ''column-rule-align/gap'', + means that, by default, a rule will stretch its longitudinal size to fill the space + from the end of the gap "above" to the start of the gap "below" ("above" meaning the gap + in the orthogonal axis on the rule's start side). + + + +The 'column-rule-edge-align' and 'row-rule-edge-align' Properties {#column-rule-edge-align} +------------------------------------------------------------ + + 
+        Name: column-rule-edge-align, row-rule-edge-align
+        Value: [gap | gap-center | gap-over]{1,2}
+        Initial: gap
+        Applies to: multi-column containers, flex containers, grid containers, table and table-row-group containers
+        Inherited: no
+        Percentages: N/A
+        Computed value: the specified value
+        Animation type: discrete
+
+ + These properties specify the start/end attachment point of the [=rule containing rectangle=] + in the [=longitudinal axis=] for the outer edges only. That is, the start edge of the first rule + and the end edge of the last rule (which may be the same rule). + The start value is specified first, the end value second. If only one value is specified it + is used for both start and end. (Attachment points for the interior rule edges are + specified with the '*-rule-align' properties above.) + + Note: The ''column-rule-align/rule''/''column-rule-align/rule-center''/''column-rule-align/rule-over'' + keywords are omitted here (compared with + ''column-rule-align'') since there are no rules in the edge gutters. + + + The figure below illustrates the alignment values. + The red values are used for the top column rule's start edge and the yellow + values are used for its end edge. The yellow values are also used for the bottom + column rule's start edge. However, in this + case the roles of ''column-rule-align/gap'' / ''column-rule-align/gap-over'' and + ''column-rule-align/rule'' / ''column-rule-align/rule-over'' are swapped. It's only the + center values that are shared. Also note that ''column-rule-align/gap-center'' + isn't necessarily aligned with ''column-rule-align/rule-center''. In this case they aren't + aligned because the row rule (purple) is using a lateral start inset. The cyan colored + values are used for the bottom column border's end edge. (If the top border were to + stretch over the entire grid, then they would be used for its end edge.) + + ''column-rule-edge-align'' controls which of the red and cyan colored + attachment points should be used. ''column-rule-edge-align'' the yellow colored + ones (and all other interior edges if there were more rows). + +
+ +
+ Illustration of rule alignment values. +
+
+ + Here's the rule styling used for the above example: + ```css + column-rule: 14px solid blue; + column-rule-align: rule-center rule; + column-rule-edge-align: gap-center gap-over; + + row-rule: 16px solid #7000ff; + row-rule-lateral-inset-start: 30px; + ``` + + The alignment points follow the same pattern in the other axis for the row rules. + In this case the row rule is using the initial values (''column-rule-align/gap'') + so they align with the inline axis gap edges. + + ISSUE: Are there use cases for other box-related edge attachment points? + e.g. 'padding | padding-center | padding-over | border...' + + +Rule Extent {#rule-extent} +============================== + +The 'column-rule-extent' and 'row-rule-extent' Properties {#column-rule-extent} +------------------------------------------------------------------------------- + + 
+        Name: column-rule-extent, row-rule-extent
+        Value: [segment | start | end | short | long | all-start | all-end | all-short | all-long ] allow-overlap?
+        Initial: long
+        Applies to: multi-column containers, flex containers, grid containers, table and table-row-group containers
+        Inherited: no
+        Percentages: N/A
+        Computed value: the specified value
+        Animation type: discrete
+
+ + ISSUE: perhaps make ''all'' a separate keyword? like so: ''[segment | [[start | end | short | long] all?] ] allow-overlap?'' + + These properties specify the extent of the rule in its [=longitudinal axis=]. + segment is an abstract term to describe the distance between two consecutive gaps. + An extent can cover one or more segments and the extent size is the distance between + the start position of the first of those segments and the end position of the last segment. + We'll define ''column-rule-extent/segment'' in more detail in the container-specific sub-sections that follow. + + The ''column-rule-extent/allow-overlap'' only affects rules in grid and table layout with spanning items/cells. + It controls whether a rule should continue through such a span. + + Note: It's only an item's grid span + that are considered when determining if an item is spanning or not, not its layout position or size. + + The ''column-rule-extent/all-*'' values makes a rule extend over all segments in an axis, + subject to not being interrupted by a span. In grid and table layout, where the tracks/table groups/rows + all have the same length in a rule's longitudinal axis, all the ''column-rule-extent/all-*'' have + the same behavior. They are intended for flexbox and masonry layout, where the gaps may fall at different + positions in adjacent flex lines and masonry tracks. + + The lateral position of a rule is determined by its first segment. + + The following sub-sections will describe the rule extent for each type of layout container in more detail. + + +### Grid Containers ### {#rule-extent-grid} + + In a [=grid container=], gaps are placed between tracks, so the ''column-rule-extent/segment'' + value maps to the extent of a [=grid cell=]. + + This example illustrates ''column-rule-extent/segment'' rules. + Note that rules are generated in all gaps, whether there are items in a grid cell or not. + + + + [=Collapsed tracks=] don't count -- they don't generate gaps and thus don't have gap rules. + They generally behave as if they don't exist as far as rules are concerned. + The example below also + illustrates that the position and size of the items don't affect the rules; it's only the position and size + of the [=grid cells=] that count. + + + Rules behave symmetrically in the grid axes, but a [=masonry axis=] in a + masonry grid layout behaves + differently; we'll cover that case in a separate section later. + + In a grid axis, rules are created between adjacent (non-collapsed) tracks and their [=extent sizes=] + are controlled by the ''column-rule-extent''/''row-rule-extent'' values as follows: +
+
segment
+
the [=extent size=] is the size of [=grid cell=] in the relevant axis +
start
+
the [=extent size=] is the size of the [=next grid cell span=] in the start-most of the two adjacent tracks +
end
+
the [=extent size=] is the size of the [=next grid cell span=] in the end-most of the two adjacent tracks +
short
+
the [=extent size=] is the smaller of the [=next grid cell span=] sizes of the two adjacent tracks +
long
+
the [=extent size=] is the larger of the [=next grid cell span=] sizes of the two adjacent tracks +
all-start, all-end, all-short, all-long
+
the [=extent size=] is the length of the track in the relevant axis + (they all behave the same because all tracks in a [=grid=] axis have the same size) +
allow-overlap
+
controls whether the [=next grid cell span=] stops short of a cell which has an item spanning + over the gap (see the algorithm below) +
+ + The following algorithm determines the rule segments to create in an axis and their [=extent sizes=]. + For each pair of adjacent tracks, we first find the next grid cell span for + each track. Then select one of those per the property values above. + + For each pair of adjacent tracks, start by setting each track's current cell to + be its first cell in the [=implicit grid=], then: + +
    +
  1. if ''column-rule-extent/allow-overlap'' was not specified, and the current cell in + the start-most of the pair of tracks contains an item that spans into the end-most of the tracks, + then skip this cell and let the current cell of each track be the cell after it, + then go to step 1 or exit if there are no more cells +
  2. if the ''*-rule-extent'' is one of the ''column-rule-extent/all-*'' values, + then the [=next grid cell span=] is the span of cells from the current cell to + last cell in the track (inclusive); if ''column-rule-extent/allow-overlap'' was not specified, + then stop before the first (opposite axis) track that contains an item spanning between this + pair of tracks +
  3. otherwise, if the current cell is empty, or ''*-rule-extent'' is ''column-rule-extent/segment'', + then the [=next grid cell span=] of that track is the current cell +
  4. otherwise, if the current cell contains items that are spanning in the same axis, + then that track's [=next grid cell span=] is the longest of those spans; + if ''column-rule-extent/allow-overlap'' was not specified, then stop before + the first (opposite axis) track that contains an item spanning between this pair of tracks +
  5. create a rule segment with the following [=extent size=]: +
      +
    1. for ''column-rule-extent/short''(''column-rule-extent/long''), + the [=extent size=] is the length of the shortest(longest) of + the two [=next grid cell spans=] +
    2. for ''column-rule-extent/start''(''column-rule-extent/end''), + the [=extent size=] is the length of the [=next grid cell span=] + of the start-most(end-most) track +
    3. for ''column-rule-extent/all-*'', + the [=extent size=] is the length of the [=next grid cell span=] + (which is always the same for the two tracks) +
    +
  6. set the current cell to the next cell, in each track, that is after the last cell + of the [=next grid cell span=] that we picked in the steps above; exit if there are no more cells; + otherwise, go to step 1. +
+ + + + +#### Subgrid #### {#rule-extent-subgrid} + + A subgrid creates its own set of gap rules. It uses its own gaps, which are centered with, but + may have a different size than the ancestor grid(s), as described in + subgrids. + Other than that, rules are created inside a subgrid in the same way as in a regular grid. + + A grid item that is a subgrid affects its parent grid's rule formation exactly as + a regular non-subgrid item would (whether the parent is also a subgrid or not), + i.e. its span (if any) affects the algorithm + above in the same way. + + ''column-rule-extent/allow-overlap'' can be used in the parent to extend its rules under + the subgrid. The subgrid's rules, if any, are rendered by the subgrid and thus render + on top of the parent, as usual. + + When the subgrid determines its rule extents, it does not consider any items that + aren't its own grid items, i.e. any items in an ancestor grid that have been placed into + the same grid cell that the subgrid occupies are not considered. Furthermore, it only uses + its own local gap and rule metrics for positioning and sizing its rules. It doesn't + consider any gaps or rules that originate outside of the subgrid. + + + + +#### Masonry #### {#rule-extent-masonry} + + Masonry layout has one grid axis (which may be [=subgridded=]) and one [=masonry axis=]. + The grid axis works the same as has been described above. The masonry axis is special + since an item is placed into a grid track based on the layout size of the items before + it, so they are typically not aligned over the tracks. Furthermore, + the grid tracks may have a different start position + (due to [=masonry axis=] alignment) + and size. + + + + + + ISSUE: TODO: add definition list and algorithm here... + + ISSUE: is it useful to be able to create a rule extent for the intersection or union between two tracks, like so: It's pretty easy to implement, fwiw... (I accidently implemented ''column-rule-extent/short''/''column-rule-extent/long'' like that before I realized it was inconsistent with how they work elsewhere). I think it's a case that is unique to a masonry axis though, at least currently... + +### Flex Containers ### {#rule-extent-flexbox} + + In a row-oriented flex container, + the ''row-rule-*'' properties creates rules between flex lines, + and the ''column-rule-*'' properties creates rules between flex items + within a flex line. + + In column-oriented flex container, + the roles of ''row-rule-extent'' and ''column-rule-extent'' are swapped. For the rest of this sub-section we + will describe the row-oriented case (just swap column/row in the text below to get the column-oriented case). + + Flex items can't span multiple lines so there are no collisions possible for the main axis rules, + hence the ''column-rule-extent/allow-overlap'' keyword is ignored in flex layout in the main axis. + A subsequent flex line is considered as a collision for the cross axis rules, i.e. a cross axis rule + has the extent of one flex line, unless ''column-rule-extent/allow-overlap'' is used (together with + one the ''column-rule-extent/all-*'' values). The reason is that items in different lines + typically don't line up in a way that the gaps between items are aligned across the lines + (unless an author is very careful to arrange that), so this is to have a safe default behavior. + + ''column-rule-extent/all-long allow-overlap'' can be used to override that and + the [=extent size=] is then from the cross axis start edge of the first flex line + to the cross axis end edge of the last flex line (all the ''all-*'' behave the same). + Only the first flex line creates column rules in this case, + and the rule's lateral position is taken from the gap in the first line. + + Advisement: Authors are advised to not use the ''column-rule-extent/allow-overlap'' value in + the main axis of a multi-line flex container since it's likely to make items + on subsequent lines overlap the rules. It may be used when all flex items are + guaranteed to have the exact same main axis [=outer size=] and align such that + the gaps are aligned between all the lines. + + Rules are created between adjacent flex lines, and their [=extent sizes=] are controlled by + the ''row-rule-extent'' values defined as follows: +
+
segment
+
behaves as ''row-rule-extent/short'' +
start
+
use the [=outer size=] of the items in the flex line on the block axis start side +
end
+
use the [=outer size=] of the items in the flex line on the block axis end side +
short
+
use the [=outer size=] of the [=next flex line item=] which has the smaller size (see detailed algorithm below) +
long
+
use the [=outer size=] of the [=next flex line item=] which has the larger size (see detailed algorithm below) +
all-start
+
the distance between the start position of the first item to the end position of the last item on the start side flex line +
all-end
+
the distance between the start position of the first item to the end position of the last item on the end side flex line +
all-short
+
the distance between the end-most start position of the first item on each flex line to the start-most end position of the last item on each flex line +
all-long
+
the distance between the start-most start position of the first item on each flex line to the end-most end position of the last item on each flex line +
allow-overlap
+
is ignored in this axis since flex items can't span between flex lines so there are no collisions (as defined in this spec) +
+ + The next flex line item is assigned by the following algorithm. + For each pair of adjacent flex lines, start with assigning the [=next flex line item=] to + the first item (in [=order-modified document order=]) on the respective line, then: + +
    +
  1. exit if neither line has a [=next flex line item=] +
  2. +
      +
    1. if only one line has a [=next flex line item=] then pick that item and go to 2 +
    2. if either of the two [=next flex line items=] has a start position that is + beyond the other item's end position, then pick the start-most item and go to 2. +
    3. otherwise, pick the item with the smallest(largest) [=outer size=] + for ''row-rule-extent/short''(''row-rule-extent/long'') +
    +
  3. use the picked item's [=outer size=] as this rule segment's [=extent size=], then change + the [=next flex line item=] for the picked item's line to the next item on its line +
  4. assign the [=next flex line item=] for the other line to the next item on this line + that has an inline start position that is greater than the end position of the picked item +
+ + (start/end position and sizes above are referring to the item's margin-box in + the rule's longitudinal axis; the phrase "next item" refers to the next item + in [=order-modified document order=]) + + + + + + + +### Table Containers ### {#rule-extent-table} + + A table container creates rules between its + table-column-groups and table-row-groups. + Collapsed + column-groups and row-groups are treated as if they don't exist. + Column rules (between table-column-groups) collide with table-row-groups. + Row rules (between table-row-groups) collide with table-column-groups. + The ''column-rule-extent/allow-overlap'' can be used to create rules that extend over + the entire column/row length. Given that all table-column-groups have the same block + axis size and all table-row-groups have same the inline axis size, + the ''column-rule-extent/short''/''column-rule-extent/long''/''column-rule-extent/start''/''column-rule-extent/end'' + keywords behave the same. Ditto for the ''column-rule-extent/all-*'' keywords. + + + + ISSUE: sort out if non-collapsed column-groups that only contain collapsed columns should generate rules, ditto row-groups/rows + + +### Table Row Group Containers ### {#rule-extent-table-row-group} + + A table-row-group container creates rules between its table-rows and between each + table-cell in a row. Collapsed table-rows are treated as if they don't exist. + Collapsed table-columns are treated as if they don't exist. + + Row rules (between table-rows) collide with cells that have + a row span crossing it. + Column rules (between table-cells) collide with cells that have + a column span crossing it. + ''column-rule-extent/allow-overlap'' can be used to create rules that + extend over such spanning cells. + + + + ''visibility:collapse'' on table-cells does not affect the rules in any way. + + +### Multi-Column Containers ### {#rule-extent-multicol} + + Multi-column containers already support rendering column rules between their columns. + That's now extended with all the new features described above. The changes described + above are backwards-compatible with existing web content that use valid ''column-rule'' + style values. Some previously invalid ''column-rule'' values are now valid + though, which could cause problems. For example, ''column-rule-width: 100%'', which + previously would not parse, will now start doing something. + + The ''row-rule-*'' properties apply to multi-column containers, and create + row rules between multicol lines and spanners, + separating them in the block axis. + + The [=segments=] are the columns and the ''margin-box'' of spanners. + + ISSUE: this proposal makes the assumption that the related proposal that + ''row-gap'' should apply to multi-column containers is also adopted + (issue #6746). + + + + + + + + +The Rule Containing Rectangle {#rule-containing-rectangle} +========================================================== + + The rule containing rectangle is formed by the rule extent + and alignment in the [=longitudinal axis=], and by the size of the + gutter in the [=lateral axis=]. + (For clarity, the size of the gutter is calculated from the gap + properties plus any extra space contributed by alignment distribution + but does not include any item margins.) + + It is important to note that the [=rule containing rectangle's=] size in an axis isn't affected by any of + the inset properties in the same axis as that would lead to a circular + dependency when resolving inset percentage values. (The [=rule containing rectangle=] is the percentage basis + for all the rule properties which take percentage values.) However, a rule that uses + ''column-rule-align: rule | rule-center | rule-over'' is affected by the lateral inset properties + of the rule it aligns to in the opposite axis. + + Here's an illustration of the [=rule containing rectangle=] (the dashed green rectangle) for the top blue rule. + This is a 2x2 grid using the default extent, so the [=extent size=] is the row's block size. + It has the following non-default rule properties: + ```css + column-rule: 14px solid blue; + column-rule-align: rule; + column-rule-edge-align: gap-center; + column-rule-longitudinal-inset-end: 8px; + + row-rule: 6px solid black; + row-rule-lateral-inset-start: 20px; + ``` + +
+ +
+ The Rule Containing Rectangle +
+
+ + Note that the [=rule containing rectangle=] extends to the start of the black horizontal rule, which has a ''row-rule-lateral-inset-start/20px'' + lateral inset (making it non-centered). We align to its start with ''column-rule-align: rule''. From there, + we move the bottom edge of the blue rule up by ''column-rule-longitudinal-inset-end/8px'' with ''column-rule-longitudinal-inset-end: 8px''. + The default ''column-rule-length: auto'' then fills the resulting area. If we were to use + ''column-rule-length: 100%'' here instead, then the rule would fill the [=rule containing rectangle=] + vertically, since that's its percentage basis. (The end inset would then be ignored since the start inset + is zero by default so the situation is over-constrained, and we resolve by ignoring the end inset, per the + sizing rules.) + + +Rule Painting Order {#rule-painting-order} +========================================== + + Column and row rules are painted in the same layer as the element's border. + They are painted after (on top of) the element's border. + All column rules for an element are painted first, then all of its row rules. + The rules for an axis are painted in the order they were generated by + the rule extent algorithms described above. + Typically from the logical start to the end of the axis. + + For table layout, all the table rules (in both axes) + are painted before the rules for the row-groups. The painting order between + multiple row-groups is whatever the table spec + specifies. For an individual row-group, the rules are painted in logical + start to end order in both axes. + + Again, note that for a specific fragment, + all the column rules are painted before all the row rules, + the above merely tries to clarify the painting order of the rules for + a specific axis. + + +Rule Overflow {#rule-overflow} +============================== + + The column and row rule areas contributes to a fragment's [=ink overflow=]. + Note that they can overflow an fragment's border-box due to negative inset + values etc. + + + + For clarity, none of the properties in this spec affects layout in any way. + Column and row rules are purely a painting effect. -- cgit v1.2.3