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/AccessibleCaret.rst | 80 + layout/docs/AccessibleCaretEventHubStates.dot | 37 + layout/docs/AccessibleCaretEventHubStates.png | Bin 0 -> 80049 bytes layout/docs/LayoutDebugger.md | 12 + layout/docs/Reftest.rst | 774 ++++ layout/docs/css-gap-decorations/Overview.bs | 1228 +++++++ layout/docs/css-gap-decorations/Overview.html | 3803 ++++++++++++++++++++ .../examples/flexbox-coupon-rule.html | 23 + .../examples/flexbox-extent-001.html | 42 + .../examples/flexbox-extent-all-long-001.html | 42 + .../flexbox-extent-all-long-allow-overlap-001.html | 42 + .../examples/flexbox-extent-all-short-001.html | 42 + .../examples/flexbox-extent-end-001.html | 42 + .../examples/flexbox-extent-long-001.html | 42 + .../examples/flexbox-extent-start-001.html | 42 + .../examples/grid-align-001.html | 83 + .../examples/grid-extent-001.html | 80 + .../examples/grid-gradient-001.html | 45 + .../examples/grid-gradient-002.html | 60 + .../examples/grid-image-001.html | 49 + .../examples/grid-image-002.html | 62 + .../examples/grid-lateral-001.html | 103 + .../examples/grid-lateral-002.html | 66 + .../examples/grid-lateral-003.html | 66 + .../examples/grid-lateral-004.html | 63 + .../examples/grid-longitudinal-001.html | 95 + .../examples/grid-longitudinal-002.html | 57 + .../examples/grid-longitudinal-003.html | 46 + .../examples/grid-masonry-001.html | 77 + .../examples/grid-masonry-002.html | 78 + .../examples/grid-masonry-003.html | 70 + .../examples/grid-segment-001.html | 35 + .../examples/grid-segment-002.html | 38 + .../examples/grid-subgrid-001.html | 73 + .../examples/h-diagonal-blue-16.png | Bin 0 -> 274 bytes .../examples/multicol-row-rule-001.html | 72 + .../examples/table-row-group-rules-001.html | 105 + .../examples/table-rules-001.html | 66 + .../examples/v-diagonal-blue-16.png | Bin 0 -> 273 bytes .../media/flexbox-coupon-rule.png | Bin 0 -> 8508 bytes .../media/flexbox-extent-all-long-001.png | Bin 0 -> 2495 bytes .../flexbox-extent-all-long-allow-overlap-001.png | Bin 0 -> 2514 bytes .../media/flexbox-extent-all-short-001.png | Bin 0 -> 2493 bytes .../media/flexbox-extent-end-001.png | Bin 0 -> 2498 bytes .../media/flexbox-extent-long-001.png | Bin 0 -> 2501 bytes .../media/flexbox-extent-start-001.png | Bin 0 -> 2495 bytes .../css-gap-decorations/media/grid-align-001.png | Bin 0 -> 19211 bytes .../css-gap-decorations/media/grid-extent-001.png | Bin 0 -> 41929 bytes .../media/grid-gradient-001.png | Bin 0 -> 7407 bytes .../css-gap-decorations/media/grid-image-001.png | Bin 0 -> 12390 bytes .../css-gap-decorations/media/grid-image-002.webm | Bin 0 -> 125209 bytes .../css-gap-decorations/media/grid-lateral-001.png | Bin 0 -> 24497 bytes .../css-gap-decorations/media/grid-lateral-002.png | Bin 0 -> 10753 bytes .../css-gap-decorations/media/grid-lateral-003.png | Bin 0 -> 10655 bytes .../css-gap-decorations/media/grid-lateral-004.png | Bin 0 -> 15826 bytes .../media/grid-longitudinal-001.png | Bin 0 -> 27929 bytes .../media/grid-longitudinal-002.webm | Bin 0 -> 68334 bytes .../media/grid-longitudinal-003.png | Bin 0 -> 11902 bytes .../css-gap-decorations/media/grid-masonry-001.png | Bin 0 -> 25674 bytes .../css-gap-decorations/media/grid-masonry-002.png | Bin 0 -> 24112 bytes .../css-gap-decorations/media/grid-segment-001.png | Bin 0 -> 6309 bytes .../css-gap-decorations/media/grid-segment-002.png | Bin 0 -> 9297 bytes .../css-gap-decorations/media/grid-subgrid-001.png | Bin 0 -> 22632 bytes .../media/masonry-all-shorter.png | Bin 0 -> 13835 bytes .../media/multicol-colspan-2.png | Bin 0 -> 7021 bytes .../media/multicol-row-rule-001.png | Bin 0 -> 36374 bytes .../media/rule-alignment-values.png | Bin 0 -> 43128 bytes .../media/rule-containing-rectangle.png | Bin 0 -> 13367 bytes .../media/table-row-group-rules-001.png | Bin 0 -> 31026 bytes .../css-gap-decorations/media/table-rules-001.png | Bin 0 -> 12135 bytes layout/docs/index.rst | 15 + 71 files changed, 7755 insertions(+) create mode 100644 layout/docs/AccessibleCaret.rst create mode 100644 layout/docs/AccessibleCaretEventHubStates.dot create mode 100644 layout/docs/AccessibleCaretEventHubStates.png create mode 100644 layout/docs/LayoutDebugger.md create mode 100644 layout/docs/Reftest.rst create mode 100644 layout/docs/css-gap-decorations/Overview.bs create mode 100644 layout/docs/css-gap-decorations/Overview.html create mode 100644 layout/docs/css-gap-decorations/examples/flexbox-coupon-rule.html create mode 100644 layout/docs/css-gap-decorations/examples/flexbox-extent-001.html create mode 100644 layout/docs/css-gap-decorations/examples/flexbox-extent-all-long-001.html create mode 100644 layout/docs/css-gap-decorations/examples/flexbox-extent-all-long-allow-overlap-001.html create mode 100644 layout/docs/css-gap-decorations/examples/flexbox-extent-all-short-001.html create mode 100644 layout/docs/css-gap-decorations/examples/flexbox-extent-end-001.html create mode 100644 layout/docs/css-gap-decorations/examples/flexbox-extent-long-001.html create mode 100644 layout/docs/css-gap-decorations/examples/flexbox-extent-start-001.html create mode 100644 layout/docs/css-gap-decorations/examples/grid-align-001.html create mode 100644 layout/docs/css-gap-decorations/examples/grid-extent-001.html create mode 100644 layout/docs/css-gap-decorations/examples/grid-gradient-001.html create mode 100644 layout/docs/css-gap-decorations/examples/grid-gradient-002.html create mode 100644 layout/docs/css-gap-decorations/examples/grid-image-001.html create mode 100644 layout/docs/css-gap-decorations/examples/grid-image-002.html create mode 100644 layout/docs/css-gap-decorations/examples/grid-lateral-001.html create mode 100644 layout/docs/css-gap-decorations/examples/grid-lateral-002.html create mode 100644 layout/docs/css-gap-decorations/examples/grid-lateral-003.html create mode 100644 layout/docs/css-gap-decorations/examples/grid-lateral-004.html create mode 100644 layout/docs/css-gap-decorations/examples/grid-longitudinal-001.html create mode 100644 layout/docs/css-gap-decorations/examples/grid-longitudinal-002.html create mode 100644 layout/docs/css-gap-decorations/examples/grid-longitudinal-003.html create mode 100644 layout/docs/css-gap-decorations/examples/grid-masonry-001.html create mode 100644 layout/docs/css-gap-decorations/examples/grid-masonry-002.html create mode 100644 layout/docs/css-gap-decorations/examples/grid-masonry-003.html create mode 100644 layout/docs/css-gap-decorations/examples/grid-segment-001.html create mode 100644 layout/docs/css-gap-decorations/examples/grid-segment-002.html create mode 100644 layout/docs/css-gap-decorations/examples/grid-subgrid-001.html create mode 100644 layout/docs/css-gap-decorations/examples/h-diagonal-blue-16.png create mode 100644 layout/docs/css-gap-decorations/examples/multicol-row-rule-001.html create mode 100644 layout/docs/css-gap-decorations/examples/table-row-group-rules-001.html create mode 100644 layout/docs/css-gap-decorations/examples/table-rules-001.html create mode 100644 layout/docs/css-gap-decorations/examples/v-diagonal-blue-16.png create mode 100644 layout/docs/css-gap-decorations/media/flexbox-coupon-rule.png create mode 100644 layout/docs/css-gap-decorations/media/flexbox-extent-all-long-001.png create mode 100644 layout/docs/css-gap-decorations/media/flexbox-extent-all-long-allow-overlap-001.png create mode 100644 layout/docs/css-gap-decorations/media/flexbox-extent-all-short-001.png create mode 100644 layout/docs/css-gap-decorations/media/flexbox-extent-end-001.png create mode 100644 layout/docs/css-gap-decorations/media/flexbox-extent-long-001.png create mode 100644 layout/docs/css-gap-decorations/media/flexbox-extent-start-001.png create mode 100644 layout/docs/css-gap-decorations/media/grid-align-001.png create mode 100644 layout/docs/css-gap-decorations/media/grid-extent-001.png create mode 100644 layout/docs/css-gap-decorations/media/grid-gradient-001.png create mode 100644 layout/docs/css-gap-decorations/media/grid-image-001.png create mode 100644 layout/docs/css-gap-decorations/media/grid-image-002.webm create mode 100644 layout/docs/css-gap-decorations/media/grid-lateral-001.png create mode 100644 layout/docs/css-gap-decorations/media/grid-lateral-002.png create mode 100644 layout/docs/css-gap-decorations/media/grid-lateral-003.png create mode 100644 layout/docs/css-gap-decorations/media/grid-lateral-004.png create mode 100644 layout/docs/css-gap-decorations/media/grid-longitudinal-001.png create mode 100644 layout/docs/css-gap-decorations/media/grid-longitudinal-002.webm create mode 100644 layout/docs/css-gap-decorations/media/grid-longitudinal-003.png create mode 100644 layout/docs/css-gap-decorations/media/grid-masonry-001.png create mode 100644 layout/docs/css-gap-decorations/media/grid-masonry-002.png create mode 100644 layout/docs/css-gap-decorations/media/grid-segment-001.png create mode 100644 layout/docs/css-gap-decorations/media/grid-segment-002.png create mode 100644 layout/docs/css-gap-decorations/media/grid-subgrid-001.png create mode 100644 layout/docs/css-gap-decorations/media/masonry-all-shorter.png create mode 100644 layout/docs/css-gap-decorations/media/multicol-colspan-2.png create mode 100644 layout/docs/css-gap-decorations/media/multicol-row-rule-001.png create mode 100644 layout/docs/css-gap-decorations/media/rule-alignment-values.png create mode 100644 layout/docs/css-gap-decorations/media/rule-containing-rectangle.png create mode 100644 layout/docs/css-gap-decorations/media/table-row-group-rules-001.png create mode 100644 layout/docs/css-gap-decorations/media/table-rules-001.png create mode 100644 layout/docs/index.rst (limited to 'layout/docs') diff --git a/layout/docs/AccessibleCaret.rst b/layout/docs/AccessibleCaret.rst new file mode 100644 index 0000000000..8644e4327b --- /dev/null +++ b/layout/docs/AccessibleCaret.rst @@ -0,0 +1,80 @@ +*************** +AccessibleCaret +*************** + +AccessibleCaret is a pair of raindrop shape handles at both ends of selection +highlight, or it is a single handle at the blinking caret in a text area. It +assists the user to change the range of the selection highlight or the position +of the blinking caret on platforms with touch-event support. + + +Meta Bug +======== + +`Bug 1124074 `__ tracks all the open issues. + + +Gecko implementation details +============================ + +Preferences +----------- +* ``layout.accessiblecaret.enabled_on_touch`` (Enabled on Firefox with touch-event support since 51.) +* ``layout.accessiblecaret.enabled`` (Defaults off, but it can be turn on to force enable AccessibleCaret.) +* ``layout.accessiblecaret.hide_carets_for_mouse_input`` (Defaults on. Turn + this on to debug AccessibleCaret on desktop browser with mouse events.) + +AccessibleCaretEventHub State Transition Diagram +------------------------------------------------ + +This diagram depicts the state transition of the state machine in +AccessibleCaretEventHub, which handles external events and callbacks. + +Note that the diagram omits some callbacks which do not cause a state transition +such as ``NotifySelectionChanged`` or ``Reflow``. + +This table is a mapping of the real events and callback to the actions described +on the edge of the diagram: + ++---------------------------------------------------+--------------+ +| Real events or callbacks | Actions | ++===================================================+==============+ +| ``eMouseDown`` or ``eTouchStart`` | Press | ++---------------------------------------------------+--------------+ +| ``eMouseMove`` or ``eTouchMove`` | Move | ++---------------------------------------------------+--------------+ +| ``eMouseUp`` or ``eTouchEnd`` or ``eTouchCancel`` | Release | ++---------------------------------------------------+--------------+ +| ``eMouseLongTap`` | Long tap | ++---------------------------------------------------+--------------+ +| ``AsyncPanZoomStarted()`` | Scroll start | ++---------------------------------------------------+--------------+ +| ``AsyncPanZoomStopped()`` | Scroll end | ++---------------------------------------------------+--------------+ +| ``NotifyBlur()`` | Blur | ++---------------------------------------------------+--------------+ + +.. image:: AccessibleCaretEventHubStates.png + +Debug Tips +---------- + +* Dump AccessibleCaret log from command line: run ``MOZ_LOG=AccessibleCaret:5 ./mach run``. +* Dump AccessibleCaret log by using a preference: Open ``about:config`` and add a pref ``logging.AccessibleCaret`` with value ``debug`` or ``verbose`` (case matters). +* ``AC_LOG()`` is useful to add new logs. + + +Developers +========== + +Current maintainer +------------------ + +* Ting-Yu Lin + +Developers Emeritus +------------------- + +* Morris Tseng +* Jeremy Chen +* Boris Chiou * diff --git a/layout/docs/AccessibleCaretEventHubStates.dot b/layout/docs/AccessibleCaretEventHubStates.dot new file mode 100644 index 0000000000..e1af363692 --- /dev/null +++ b/layout/docs/AccessibleCaretEventHubStates.dot @@ -0,0 +1,37 @@ +// Steps to generate AccessibleCaretEventHubStates.png +// 1. Install Graphviz +// 2. dot -T png -o AccessibleCaretEventHubStates.png AccessibleCaretEventHubStates.dot +// +// Note: If the edge has 'constraint=false', it is not used in ranking the +// nodes. http://www.graphviz.org/doc/info/attrs.html#d:constraint + +digraph event_hub_states { + node [style=filled]; + edge [color="gray30", fontcolor="gray20", fontsize=12] + + NoAction [label="NoAction\n(Initial)"color="#96FF2F"]; + NoAction -> PressCaret [label="Press & on a caret"]; + NoAction -> PressNoCaret [label="Press & not on a caret"]; + NoAction -> Scroll [label="Scroll start"]; + + PressCaret [color="#84D8FF"]; + PressCaret -> DragCaret [label="Move & distance is large"]; + PressCaret -> NoAction [label="Release (synthesizing a tap)"]; + + DragCaret [color="#84D8FF"]; + DragCaret -> DragCaret [label="Move"]; + DragCaret -> NoAction [label="Release"]; + + PressNoCaret [color="#E8C516"]; + PressNoCaret -> NoAction [label="Move & distance is large or\nRelease or\nBlur"]; + PressNoCaret -> LongTap [label="Long tap"]; + PressNoCaret -> Scroll [label="Scroll start", constraint=false]; + + LongTap [color="#E8C516"] + LongTap -> NoAction [label="Release"]; + LongTap -> Scroll [label="Scroll start", constraint=false]; + + Scroll [color="#FF9022"] + Scroll -> NoAction [label="Scroll end"]; + Scroll -> NoAction [label="Blur"]; +} diff --git a/layout/docs/AccessibleCaretEventHubStates.png b/layout/docs/AccessibleCaretEventHubStates.png new file mode 100644 index 0000000000..b3ccc69bd5 Binary files /dev/null and b/layout/docs/AccessibleCaretEventHubStates.png differ diff --git a/layout/docs/LayoutDebugger.md b/layout/docs/LayoutDebugger.md new file mode 100644 index 0000000000..911c365cbd --- /dev/null +++ b/layout/docs/LayoutDebugger.md @@ -0,0 +1,12 @@ +# Layout Debugger + +## Overview + +The layout debugger can dump a variety of things including: +- Matched CSS Rules +- Text Runs +- Frames + +## Usage +- Use a debug build or add `ac_add_options --enable-layout-debugger` to your mozconfig. +- Run with `./mach run --layoutdebug [filename]` diff --git a/layout/docs/Reftest.rst b/layout/docs/Reftest.rst new file mode 100644 index 0000000000..18a1c20d93 --- /dev/null +++ b/layout/docs/Reftest.rst @@ -0,0 +1,774 @@ +Layout Engine Visual Tests (reftest) +==================================== + +Layout Engine Visual Tests (reftest) +L. David Baron , Mozilla Corporation +July 19, 2006 + +This code is designed to run tests of Mozilla's layout engine. These +tests consist of an HTML (or other format) file along with a reference +in the same format. The tests are run based on a manifest file, and for +each test, PASS or FAIL is reported, and UNEXPECTED is reported if the +result (PASS or FAIL) was not the expected result noted in the manifest. + +Images of the display of both tests are captured, and most test types +involve comparing these images (e.g., test types == or !=) to determine +whether the test passed. The captures of the tests are taken in a +viewport that is 800 pixels wide and 1000 pixels tall, so any content +outside that area will be ignored (except for any scrollbars that are +displayed). Ideally, however, tests should be written so that they fit +within 600x600, since we may in the future want to switch to 600x600 to +match http://lists.w3.org/Archives/Public/www-style/2012Sep/0562.html . + +Why this way? +------------- + +Writing HTML tests where the reference rendering is also in HTML is +harder than simply writing bits of HTML that can be regression-tested by +comparing the rendering of an older build to that of a newer build +(perhaps using stored reference images from the older build). However, +comparing across time has major disadvantages: + + * Comparisons across time either require two runs for every test, or + they require stored reference images appropriate for the platform and + configuration (often limiting testing to a very specific + configuration). + + * Comparisons across time may fail due to expected changes, for + example, changes in the default style sheet for HTML, changes in the + appearance of form controls, or changes in default preferences like + default font size or default colors. + +Using tests for which the pass criteria were explicitly chosen allows +running tests at any time to see whether they still pass. + +Manifest Format +--------------- + +The test manifest format is a plain text file. A line starting with a +``"#"`` is a comment. Lines may be commented using whitespace followed by +a ``"#"`` and the comment. Each non-blank line (after removal of comments) +must be one of the following: + +Inclusion of another manifest +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + ``* include `` + + ```` is one of the skip or skip-if items (see their definitions + in ```` below). If any of the skip types evaluate to true (i.e. + they are a plain ``skip`` or they are a ``skip-if`` with a condition that + evaluates to true), then the include statement is skipped. Otherwise, + reftests in the specified manifest are included in the set of reftests + that are run. + +A test item +~~~~~~~~~~~ + + ``[ | ]* [] `` + + where + + a. ```` (optional) is one of the following: + + ``fails`` + The test passes if the images of the two renderings DO NOT meet the + conditions specified in the ````. + + ``fails-if(condition)`` + If the condition is met, the test passes if the images of the two + renderings DO NOT meet the conditions of ````. If the condition + is not met, the test passes if the conditions of ```` are met. + + ``needs-focus`` + The test fails or times out if the reftest window is not focused. + + ``random`` + The results of the test are random and therefore not to be considered in the output. + + ``random-if(condition)`` + The results of the test are random if a given condition is met. + + ``silentfail`` + This test may fail silently, and if that happens it should count as if + the test passed. This is useful for cases where silent failure is the + intended behavior (for example, in an out of memory situation in + JavaScript, we stop running the script silently and immediately, in + hopes of reclaiming enough memory to keep the browser functioning). + + ``silentfail-if(condition)`` + This test may fail silently if the condition is met. + + ``skip`` + This test should not be run. This is useful when a test fails in a + catastrophic way, such as crashing or hanging the browser. Using + ``skip`` is preferred to simply commenting out the test because we + want to report the test failure at the end of the test run. + + ``skip-if(condition)`` + If the condition is met, the test is not run. This is useful if, for + example, the test crashes only on a particular platform (i.e. it + allows us to get test coverage on the other platforms). + + ``slow`` + The test may take a long time to run, so run it if slow tests are + either enabled or not disabled (test manifest interpreters may choose + whether or not to run such tests by default). + + ``slow-if(condition)`` + If the condition is met, the test is treated as if ``slow`` had been + specified. This is useful for tests which are slow only on particular + platforms (e.g. a test which exercised out-of-memory behavior might be + fast on a 32-bit system but inordinately slow on a 64-bit system). + + ``fuzzy(minDiff-maxDiff,minPixelCount-maxPixelCount)`` + This allows a test to pass if the pixel value differences are between + ``minDiff`` and ``maxDiff``, inclusive, and the total number of + different pixels is between ``minPixelCount`` and ``maxPixelCount``, + inclusive. It can also be used with ``!=`` to ensure that the + difference is outside the specified interval. Note that with ``!=`` + tests the minimum bounds of the ranges must be zero. + + Fuzzy tends to be used for two different sorts of cases. The main + case is tests that are expected to be equal, but actually fail in a + minor way (e.g., an antialiasing difference), and we want to ensure + that the test doesn't regress further so we don't want to mark the + test as failing. For these cases, test annotations should be the + tightest bounds possible: if the behavior is entirely deterministic + this means a range like ``fuzzy(1-1,8-8)``, and if at all possible, + the ranges should not include 0. In cases where the test only + sometimes fails, this unfortunately requires using 0 in both ranges, + which means that we won't get reports of an unexpected pass if the + problem is fixed (allowing us to remove the ``fuzzy()`` annotation + and expect the test to pass from then on). + + The second case where fuzzy is used is tests that are supposed + to allow some amount of variability (i.e., tests where the + specification allows variability such that we can't assert + that all pixels are the same). Such tests should generally be + avoided (for example, by covering up the pixels that can vary + with another element), but when they are needed, the ranges in + the ``fuzzy()`` annotation should generally include 0. + + ``fuzzy-if(condition,minDiff-maxDiff,minPixelCount-maxPixelCount)`` + If the condition is met, the test is treated as if ``fuzzy`` had been + specified. This is useful if there are differences on particular + platforms. See ``fuzzy()`` above. + + ``require-or(cond1&&cond2&&...,fallback)`` + Require some particular setup be performed or environmental + condition(s) made true (eg setting debug mode) before the test + is run. If any condition is unknown, unimplemented, or fails, + revert to the fallback failure-type. + Example: ``require-or(debugMode,skip)`` + + ``asserts(count)`` + Loading the test and reference is known to assert exactly + ``count`` times. + NOTE: An asserts() notation with a non-zero count or maxCount + suppresses use of a cached canvas for the test with the + annotation. However, if later occurrences of the same test + are not annotated, they will use the cached canvas + (potentially from the load that asserted). This allows + repeated use of the same test or reference to be annotated + correctly (which may be particularly useful when the uses are + in different subdirectories that can be tested independently), + but does not force them to be, nor does it force suppression + of caching for a common reference when it is the test that + asserts. + + ``asserts-if(condition,count)`` + Same as above, but only if condition is true. + + ``asserts(minCount-maxCount)`` + Loading the test and reference is known to assert between + minCount and maxCount times, inclusive. + NOTE: See above regarding canvas caching. + + ``asserts-if(condition,minCount-maxCount)`` + Same as above, but only if condition is true. + + ``noautofuzz`` + Disables the autofuzzing behaviour hard-coded in the reftest harness + for specific platform configurations. The autofuzzing is intended to + compensate for inherent nondeterminism that results in intermittently + fuzzy results (with small amounts of fuzz) across many/all tests on + a given platform. Specifying 'noautofuzz' on the test will disable + the autofuzzing for that test and require an exact match. + + Conditions are JavaScript expressions *without spaces* in them. + They are evaluated in a sandbox in which a limited set of + variables are defined. See the BuildConditionSandbox function in + ``layout/tools/reftest.js`` for details. + + Examples of using conditions: :: + + + fails-if(winWidget) == test reference + asserts-if(cocoaWidget,2) load crashtest + + + b. ```` (optional) is a string of the form + + ``pref(,)`` + + ``test-pref(,)`` + + ``ref-pref(,)`` + + where ```` is the name of a preference setting, as seen in + about:config, and ```` is the value to which this preference + should be set. ```` may be a boolean (true/false), an integer, + or a quoted string *without spaces*, according to the type of the + preference. + + The preference will be set to the specified value prior to + rendering the test and/or reference canvases (pref() applies to + both, test-pref() only to the test, and ref-pref() only to the + reference), and will be restored afterwards so that following + tests are not affected. Note that this feature is only useful for + "live" preferences that take effect immediately, without requiring + a browser restart. + + c. ````, if present, is one of the strings (sans quotes) "HTTP" or + "HTTP(..)" or "HTTP(../..)" or "HTTP(../../..)", etc. , indicating that + the test should be run over an HTTP server because it requires certain + HTTP headers or a particular HTTP status. (Don't use this if your test + doesn't require this functionality, because it unnecessarily slows down + the test.) + + With "HTTP", HTTP tests have the restriction that any resource an HTTP + test accesses must be accessed using a relative URL, and the test and + the resource must be within the directory containing the reftest + manifest that describes the test (or within a descendant directory). + The variants "HTTP(..)", etc., can be used to relax this restriction by + allowing resources in the parent directory, etc. + + To modify the HTTP status or headers of a resource named FOO, create a + sibling file named FOO^headers^ with the following contents: + + ``[]`` + + ``*`` + + ```` + A line of the form "HTTP ###[ ]", where ### indicates + the desired HTTP status and indicates a desired HTTP + status description, if any. If this line is omitted, the default is + "HTTP 200 OK". + + ```` + A line in standard HTTP header line format, i.e. + "Field-Name: field-value". You may not repeat the use of a Field-Name + and must coalesce such headers together, and each header must be + specified on a single line, but otherwise the format exactly matches + that from HTTP itself. + + HTTP tests may also incorporate SJS files. SJS files provide similar + functionality to CGI scripts, in that the response they produce can be + dependent on properties of the incoming request. Currently these + properties are restricted to method type and headers, but eventually + it should be possible to examine data in the body of the request as + well when computing the generated response. An SJS file is a JavaScript + file with a .sjs extension which defines a global `handleRequest` + function (called every time that file is loaded during reftests) in this + format: :: + + function handleRequest(request, response) + { + response.setStatusLine(request.httpVersion, 200, "OK"); + + // You *probably* want this, or else you'll get bitten if you run + // reftest multiple times with the same profile. + response.setHeader("Cache-Control", "no-cache"); + + response.write("any ASCII data you want"); + + var outputStream = response.bodyOutputStream; + // ...anything else you want to do, synchronously... + } + + For more details on exactly which functions and properties are available + on request/response in handleRequest, see the nsIHttpRe(quest|sponse) + definitions in ``netwerk/test/httpserver/nsIHttpServer.idl``. + + HTTP tests can also make use of example.org URIs in order to test cross + site behaviour. "example.org/filename" will access filename in the same + directly as the current reftest. (Not currently implemented for android.) + + d. ```` is one of the following: + + ``==`` + The test passes if the images of the two renderings are the SAME. + + ``!=`` + The test passes if the images of the two renderings are DIFFERENT. + + ``load`` + The test passes unconditionally if the page loads. url_ref must be + omitted, and the test cannot be marked as fails or random. (Used to + test for crashes, hangs, assertions, and leaks.) + + ``script`` + The loaded page records the test's pass or failure status in a + JavaScript data structure accessible through the following API. + + ``getTestCases()`` returns an array of test result objects + representing the results of the tests performed by the page. + + Each test result object has two methods: + + ``testPassed()`` returns true if the test result object passed, + otherwise it returns false. + + ``testDescription()`` returns a string describing the test + result. + + ``url_ref`` must be omitted. The test may be marked as fails or + random. (Used to test the JavaScript Engine.) + + ``print`` + The test passes if the printouts (as PDF) of the two renderings + are the SAME by applying the following comparisons: + + - The number of pages generated for both printouts must match. + - The text content of both printouts must match (rasterized text + does not match real text). + + You can specify a print range by setting the reftest-print-range + attribute on the document element. Example: :: + + + ... + + + The following example would lead to a single page print: :: + + + ... + + You can also print selected elements only: :: + + + ... + + Make sure to include code in your test that actually selects something. + + Future additions to the set of comparisons might include: + + - Matching the paper size + - Validating printed headers and footers + - Testing (fuzzy) position of elements + - Testing specific print related CSS properties + + The main difference between ``print`` and ``==/!=`` reftests is that + ``print`` makes us compare the structure of print results (by parsing + the output PDF) rather than taking screenshots and comparing pixel + values. This allows us to test for common printing related issues + like text being rasterized when it shouldn't. This difference in + behavior is also why this is its own reftest operator, rather than + a flavor of ``==/!=``. It would be somewhat misleading to list these + print reftests as ``==/!=``, because they don't actually check for + pixel matching. + + See the chapter about Pagination Tests if you are looking for testing + layout in pagination mode. + + e. ```` is either a relative file path or an absolute URL for the + test page + + f. ```` is either a relative file path or an absolute URL for + the reference page + + The only difference between ```` and ```` is that results of + the test are reported using ```` only. + +Specification of a url prefix +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + ``url-prefix `` + + ```` will be prepended to relative ```` and ```` for + all following test items in the manifest. + + ```` will not be prepended to the relative path when including + another manifest, e.g. ``include .`` + + ```` will not be prepended to any ```` or ```` matching + the pattern ``/^\w+:/``. This will prevent the prefix from being applied to + any absolute url containing a protocol such as ``data:``, ``about:``, or + ``http:``. + + While the typical use of url-prefix is expected to be as the first line of + a manifest, it is legal to use it anywhere in a manifest. Subsequent uses + of url-prefix overwrite any existing values. + +Specification of defaults +~~~~~~~~~~~~~~~~~~~~~~~~~ + + ``defaults [ | | ]`` + + where ````, ````, and ```` are defined above. + + The default settings will be used for all following test items in the manifest. + Any test specific settings will override the defaults, just as later items + within a line override earlier ones. + + A defaults line with no settings will reset the defaults to be empty. + + As with url-prefix, defaults will often be used at the start of a manifest file + so that it applies to all test items, but it is legal for defaults to appear + anywhere in the manifest. A subsequent defaults will reset any previous default + settings and overwrite them with the new settings. + + It is invalid to set non-skip defaults before an include line, just as it is + invalid to specify non-skip settings directly on the include line itself. If a + manifest needs to use both defaults and include, the include should appear + before the defaults. If it's important to specify the include later on in the + manifest, a blank defaults line directly preceding the include can be used to + reset the defaults. + +This test manifest format could be used by other harnesses, such as ones +that do not depend on XUL, or even ones testing other layout engines. + +Running Tests +------------- + +To run a given reftest use something like the following :: + +./mach reftest + +As an example, if we wanted to run the reftests relevant to async scrolling, +run something like the following:: + +./mach reftest ./layout/reftest/async-scrolling &> reftest.out + +and then search/grep reftest.out for "UNEXPECTED". + +There are two scripts provided to convert the reftest.out to HTML. +clean-reftest-output.pl converts reftest.out into simple HTML, stripping +lines from the log that aren't relevant. reftest-to-html.pl converts +the output into html that makes it easier to visually check for +failures. See :ref:`debugging failures ` for +more details on making sense of reftest results. + +Testable Areas +-------------- + +This framework is capable of testing many areas of the layout engine. +It is particularly well-suited to testing dynamic change handling (by +comparison to the static end-result as a reference) and incremental +layout (comparison of a script-interrupted layout to one that was not). +However, it is also possible to write tests for many other things that +can be described in terms of equivalence, for example: + + * CSS cascading could be tested by comparing the result of a + complicated set of style rules that makes a word green to word. + + * compositing operators could be tested by comparing the + result of drawing using canvas to a block-level element with the + desired color as a CSS background-color. + + * CSS counters could be tested by comparing the text output by counters + with a page containing the text written out + + * complex margin collapsing could be tested by comparing the complex + case to a case where the margin is written out, or where the margin + space is created by an element with 'height' and transparent + background + +When it is not possible to test by equivalence, it may be possible to +test by non-equivalence. For example, testing justification in cases +with more than two words, or more than three different words, is +difficult. However, it is simple to test that justified text is at +least displayed differently from left-, center-, or right-aligned text. + +Writing Tests +------------- + +When writing tests for this framework, it is important for the test to +depend only on behaviors that are known to be correct and permanent. +For example, tests should not depend on default font sizes, default +margins of the body element, the default style sheet used for HTML, the +default appearance of form controls, or anything else that can be +avoided. + +In general, the best way to achieve this is to make the test and the +reference identical in as many aspects as possible. For example: + +Good test markup: :: + +
green +
+ +Good reference markup: :: + +
green +
+ +BAD reference markup: :: + + +
green +
+ +BAD test markup: :: + + +
green +
+ +Asynchronous Tests: class="reftest-wait" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Normally reftest takes a snapshot of the given markup's rendering right +after the load event fires for content. If your test needs to postpone +the moment the snapshot is taken, it should make sure a class +'reftest-wait' is on the root element by the moment the load event +fires. The easiest way to do this is to put it in the markup, e.g.: :: + + + +When your test is ready, you should remove this class from the root +element, for example using this code: :: + + document.documentElement.className = ""; + + +Note that in layout tests it is often enough to trigger layout using :: + + document.body.offsetWidth // HTML example + +When possible, you should use this technique instead of making your +test async. + +Invalidation Tests: MozReftestInvalidate Event +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When a test (or reference) uses reftest-wait, reftest tracks invalidation +via MozAfterPaint and updates the test image in the same way that +a regular window would be repainted. Therefore it is possible to test +invalidation-related bugs by setting up initial content and then +dynamically modifying it before removing reftest-wait. However, it is +important to get the timing of these dynamic modifications right so that +the test doesn't accidentally pass because a full repaint of the window +was already pending. To help with this, reftest fires one MozReftestInvalidate +event at the document root element for a reftest-wait test when it is safe to +make changes that should test invalidation. The event bubbles up to the +document and window so you can set listeners there too. For example, :: + + function doTest() { + document.body.style.border = ""; + document.documentElement.removeAttribute('class'); + } + document.addEventListener("MozReftestInvalidate", doTest, false); + +Painting Tests: class="reftest-no-paint" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If an element shouldn't be painted, set the class "reftest-no-paint" on it +when doing an invalidation test. Causing a repaint in your +MozReftestInvalidate handler (for example, by changing the body's background +colour) will accurately test whether the element is painted. + +Display List Tests: class="reftest-[no-]display-list" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These classes work similarly to reftest-no-paint, but check if the element has +display items created or not. These classes are useful for checking the behaviour +of retained display lists, where the display list is incrementally updated by +changes, rather than thrown out and rebuilt from scratch. + +Opaque Layer Tests: class="reftest-opaque-layer" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If an element should be assigned to a PaintedLayer that's opaque, set the class +"reftest-opaque-layer" on it. This checks whether the layer is opaque during +the last paint of the test, and it works whether your test is an invalidation +test or not. In order to pass the test, the element has to have a primary +frame, and that frame's display items must all be assigned to a single painted +layer and no other layers, so it can't be used on elements that create stacking +contexts (active or inactive). + +Layerization Tests: reftest-assigned-layer="layer-name" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If two elements should be assigned to the same PaintedLayer, choose any string +value as the layer name and set the attribute reftest-assigned-layer="yourname" +on both elements. Reftest will check whether all elements with the same +reftest-assigned-layer value share the same layer. It will also test whether +elements with different reftest-assigned-layer values are assigned to different +layers. +The same restrictions as with class="reftest-opaque-layer" apply: All elements +must have a primary frame, and that frame's display items must all be assigned +to the same PaintedLayer and no other layers. If these requirements are not +met, the test will fail. + +Snapshot The Whole Window: class="reftest-snapshot-all" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In a reftest-wait test, to disable testing of invalidation and force the final +snapshot to be taken of the whole window, set the "reftest-snapshot-all" +class on the root element. + +Avoid triggering flushes: class="reftest-no-flush" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The reftest harness normally triggers flushes by calling +getBoundingClientRect on the root element. If the root element of the +test has class="reftest-no-flush", it doesn't do this. + +This is useful for testing animations on the compositor thread, since +the flushing will cause a main thread style update. + +Zoom Tests: reftest-zoom="" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When the root element of a test has a "reftest-zoom" attribute, that zoom +factor is applied when rendering the test. The corresponds to the desktop "full +zoom" style zoom. The reftest document will be 800 device pixels wide by 1000 +device pixels high. The reftest harness assumes that the CSS pixel dimensions +are 800/zoom and 1000/zoom. For best results therefore, choose zoom factors +that do not require rounding when we calculate the number of appunits per +device pixel; i.e. the zoom factor should divide 60, so 60/zoom is an integer. + +Setting Scrollport Size: reftest-scrollport-w/h="" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If either of the "reftest-scrollport-w" and "reftest-scrollport-h" attributes on +the root element are non-zero, sets the scroll-position-clamping scroll-port +size to the given size in CSS pixels. This does not affect the size of the +snapshot that is taken. + +Setting Resolution: reftest-resolution="" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If the root element of a test has a "reftest-resolution" attribute, the page +is rendered with the specified resolution (as if the user pinch-zoomed in +to that scale). Note that the difference between reftest-async-zoom and +reftest-resolution is that reftest-async-zoom only applies the scale in +the compositor, while reftest-resolution causes the page to be paint at that +resolution. This attribute can be used together with initial-scale in meta +viewport tag, in such cases initial-scale is applied first then +reftest-resolution changes the scale. + +This attributes requires the pref apz.allow_zooming=true to have an effect. + +Setting Async Scroll Mode: reftest-async-scroll attribute +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If the "reftest-async-scroll" attribute is set on the root element, we try to +enable async scrolling and zooming for the document. This is unsupported in many +configurations. + +Setting Displayport Dimensions: reftest-displayport-x/y/w/h="" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If any of the "reftest-displayport-x", "reftest-displayport-y", +"reftest-displayport-w" and "reftest-displayport-h" attributes on the root +element are nonzero, sets the displayport dimensions to the given bounds in +CSS pixels. This does not affect the size of the snapshot that is taken. + +When the "reftest-async-scroll" attribute is set on the root element, *all* +elements in the document are checked for "reftest-displayport-x/y/w/h" and have +displayports set on them when those attributes are present. + +Testing Async Scrolling: reftest-async-scroll-x/y="" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When the "reftest-async-scroll" attribute is set on the root element, for any +element where either the "reftest-async-scroll-x" or "reftest-async-scroll-y +attributes are nonzero, at the end of the test take the snapshot with the given +offset (in CSS pixels) added to the async scroll offset. + +Testing Async Zooming: reftest-async-zoom="" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When the "reftest-async-zoom" attribute is present on the root element then at +the end of the test take the snapshot with the given async zoom on top of any +existing zoom. Content is not re-rendered at the new zoom level. This +corresponds to the mobile style "pinch zoom" style of zoom. This is unsupported +in many configurations, and any tests using this will probably want to have +pref(apz.allow_zooming,true) on them. + +Pagination Tests: class="reftest-paged" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Now that the patch for bug 374050 has landed +(https://bugzilla.mozilla.org/show_bug.cgi?id=374050), it is possible to +create reftests that run in a paginated context. + +The page size used is 5in wide and 3in tall (with the default half-inch +margins). This is to allow tests to have less text and to make the +entire test fit on the screen. + +There is a layout/reftests/printing directory for pagination reftests; however, +there is nothing special about this directory. You can put pagination reftests +anywhere that is appropriate. + +The suggested first lines for any pagination test is: :: + + + + +The reftest-paged class on the root element triggers the reftest to +switch into page mode. Fixing the font size is suggested, although not +required, because the pages are a fixed size in inches. The switch to page mode +happens on load if the reftest-wait class is not present; otherwise it happens +immediately after firing the MozReftestInvalidate event. + +The underlying layout support for this mode isn't really complete; it +doesn't use exactly the same codepath as real print preview/print. In +particular, scripting and frames are likely to cause problems; it is untested, +though. That said, it should be sufficient for testing layout issues related +to pagination. + +Process Crash Tests: class="reftest-expect-process-crash" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you are running a test that causes a process +under Electrolysis to crash as part of a reftest, this will cause process +crash minidump files to be left in the profile directory. The test +infrastructure that runs the reftests will notice these minidump files and +dump out information from them, and these additional error messages in the logs +can end up erroneously being associated with other errors from the reftest run. +They are also confusing, since the appearance of "PROCESS-CRASH" messages in +the test run output can seem like a real problem, when in fact it is the +expected behavior. + +To indicate to the reftest framework that a test is expecting a +process to crash, have the test include "reftest-expect-process-crash" as +one of the root element's classes by the time the test has finished. This will +cause any minidump files that are generated while running the test to be removed +and they won't cause any error messages in the test run output. + +Skip Forcing A Content Process Layer-Tree Update: reftest-no-sync-layers attribute +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Normally when an multi-process reftest test ends, we force the content process +to push a layer-tree update to the compositor before taking the snapshot. +Setting the "reftest-no-sync-layers" attribute on the root element skips this +step, enabling testing that layer-tree updates are being correctly generated. +However the test must manually wait for a MozAfterPaint event before ending. + +SpecialPowers +------------- + +Some tests may require synthesized user input events or other functions that +normally cannot be run from a typical script. Layout reftests have access to +`SpecialPowers` for such cases. + +Test authors have ability to access the privilegd `nsIDOMWindowUtils` interface +using `SpecialPowers.getDOMWindowUtils(window)`. The interface contains many +interesting abilities, including event synthesization. + +Debugging Failures +------------------ + +The Reftest Analyzer has been created to make debugging reftests a bit easier. +If a reftest is failing, upload the log to the Reftest Analyzer to view the +differences between the expected result and the actual outcome of the reftest. +The Reftest Analyzer can be found at the following url: + +https://hg.mozilla.org/mozilla-central/raw-file/tip/layout/tools/reftest/reftest-analyzer.xhtml 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. diff --git a/layout/docs/css-gap-decorations/Overview.html b/layout/docs/css-gap-decorations/Overview.html new file mode 100644 index 0000000000..56c46a3468 --- /dev/null +++ b/layout/docs/css-gap-decorations/Overview.html @@ -0,0 +1,3803 @@ + + + + CSS Gap Decorations + + + + + + + + + + + + + + + + + + + + + + +
+

+

CSS Gap Decorations

+

Editor’s Draft,

+
+ Specification Metadata + +
+
+

Copyright © 2021 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.

+
+
+
+

Abstract

+

This is a proposal to extend CSS Box Alignment to support gap decorations.

+ CSS is a language for describing the rendering of structured documents +(such as HTML and XML) +on screen, on paper, etc. +
+

Status of this document

+
+

This is a public copy of the editors’ draft. + It is provided for discussion only and may change at any moment. + Its publication here does not imply endorsement of its contents by W3C. + Don’t cite this document other than as work in progress.

+

Please send feedback + by filing issues in GitHub (preferred), + including the spec code “css-gap-decorations” in the title, like this: + “[css-gap-decorations] …summary of comment…”. + All issues and comments are archived. + Alternately, feedback can be sent to the (archived) public mailing list www-style@w3.org.

+

This document is governed by the 2 November 2021 W3C Process Document.

+

+
+
+ +
+

1. Introduction

+

This section is not normative.

+

1.1. 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.

+

1.2. Module Interactions

+

This module extends the definition of the column-rule-width property, + adding <percentage> and 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.

+

1.3. 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.

+

2. Rule Images and Gradients

+

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.

+

2.1. The column-rule-image-source and row-rule-image-source Properties

+ + + + + + + + + + + +
Name: + column-rule-image-source, row-rule-image-source +
Value: + none | <image> +
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 none or the computed <image> +
Canonical order: + per grammar +
Animation type: + discrete +
+

These properties specify an <image> 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 none.

+

2.2. The column-rule-image-slice and row-rule-image-slice Properties

+ + + + + + + + + + + +
Name: + column-rule-image-slice, row-rule-image-slice +
Value: + [<number [0,∞]> | <percentage [0,∞]>]{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 +
Canonical order: + per grammar +
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.

+
+
<percentage [0,∞]> +
Percentages are relative to the image size in the rule’s longitudinal axis +
<number [0,∞]> +
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 § 4.3.1 Default Sizing Algorithm 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.

+

2.3. The column-rule-image-repeat and row-rule-image-repeat Properties

+ + + + + + + + + + + +
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 +
Canonical order: + per grammar +
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.

+

2.4. The column-rule-image and row-rule-image Shorthands

+ + + + + + + + + + + +
Name: + column-rule-image, row-rule-image +
Value: + <'column-rule-image-source'> || <'column-rule-image-slice'> || <'column-rule-image-repeat'> +
Initial: + see individual properties +
Applies to: + multi-column containers, flex containers, grid containers, table and table-row-group containers +
Inherited: + see individual properties +
Percentages: + see individual properties +
Computed value: + see individual properties +
Animation type: + see individual properties +
Canonical order: + per grammar +
+ + + + +

3. Rule Positioning and Sizing

+

3.1. The column-rule-width and row-rule-width Properties

+ + + + + + + + + + +
Name: + column-rule-width +
New values: + <percentage> | 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 <line-width>; 0px if the column rule style is none or hidden. Otherwise, the specified value. +
Animation type: + by computed value type +
+ + + + + + + + + + + +
Name: + row-rule-width +
Value: + <line-width> | <percentage> | 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 <line-width>; 0px if the column rule style is none or hidden. Otherwise, the specified value. +
Canonical order: + per grammar +
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 § 3.4 Resolving a rule’s position and size below for how auto is resolved.

+

3.2. The column-rule-length and row-rule-length Properties

+ + + + + + + + + + + +
Name: + column-rule-length, row-rule-length +
Value: + <length-percentage> | 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 +
Canonical order: + per grammar +
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 § 3.4 Resolving a rule’s position and size 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.

+

3.3. The Rule Lateral Inset Properties

+ + + + + + + + + + + +
Name: + column-rule-lateral-inset-start, column-rule-lateral-inset-end, row-rule-lateral-inset-start, row-rule-lateral-inset-end +
Value: + <length-percentage> | 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 +
Canonical order: + per grammar +
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.

+

3.4. Resolving a rule’s position and size

+

Given a triplet of values: inset-start/end and a size for an axis, 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 auto then set both inset values to zero and solve for size +
  2. if none of the values are auto then the situation is over-constrained: solve by + treating the end inset value as auto +
  3. if both inset properties are 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 auto and only one of the inset values is auto then set the auto inset value to zero + and solve for size, if that makes size negative then set the size to zero and solve for the 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-auto inset edge) +
  5. if the size is auto and both inset values are non-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 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.

+ +

3.5. The column-rule-lateral-inset and row-rule-lateral-inset Shorthands

+ + + + + + + + + + + +
Name: + column-rule-lateral-inset +
Value: + <'column-rule-lateral-inset-start'> <'column-rule-lateral-inset-end'>? +
Initial: + see individual properties +
Applies to: + see individual properties +
Inherited: + see individual properties +
Percentages: + see individual properties +
Computed value: + see individual properties +
Animation type: + see individual properties +
Canonical order: + per grammar +
+ + + + + + + + + + + +
Name: + row-rule-lateral-inset +
Value: + <'row-rule-lateral-inset-start'> <'row-rule-lateral-inset-end'>? +
Initial: + see individual properties +
Applies to: + see individual properties +
Inherited: + see individual properties +
Percentages: + see individual properties +
Computed value: + see individual properties +
Animation type: + see individual properties +
Canonical order: + per grammar +
+

These are shortands for specifying the corresponding start/end values. + If one value is specified it is used for both start and end.

+

3.6. The Rule Longitudinal Inset Properties

+ + + + + + + + + + + +
Name: + column-rule-longitudinal-inset-start, column-rule-longitudinal-inset-end, row-rule-longitudinal-inset-start, row-rule-longitudinal-inset-end +
Value: + <length-percentage> | 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 +
Canonical order: + per grammar +
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.

+ + +

3.7. The column-rule-longitudinal-inset and row-rule-longitudinal-inset Shorthands

+ + + + + + + + + + + +
Name: + column-rule-longitudinal-inset +
Value: + <'column-rule-longitudinal-inset-start'> <'column-rule-longitudinal-inset-end'>? +
Initial: + see individual properties +
Applies to: + see individual properties +
Inherited: + see individual properties +
Percentages: + see individual properties +
Computed value: + see individual properties +
Animation type: + see individual properties +
Canonical order: + per grammar +
+ + + + + + + + + + + +
Name: + row-rule-longitudinal-inset +
Value: + <'row-rule-longitudinal-inset-start'> <'row-rule-longitudinal-inset-end'>? +
Initial: + see individual properties +
Applies to: + see individual properties +
Inherited: + see individual properties +
Percentages: + see individual properties +
Computed value: + see individual properties +
Animation type: + see individual properties +
Canonical order: + per grammar +
+

These shortands specify the corresponding start/end values. If one value is specified it is used for both start/end.

+

3.8. The Rule Longitudinal Edge Inset Properties

+ + + + + + + + + + + +
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: + <length-percentage> | 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 +
Canonical order: + per grammar +
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.

+

3.9. The column-rule-longitudinal-edge-inset and row-rule-longitudinal-edge-inset Shorthands

+ + + + + + + + + + + +
Name: + column-rule-longitudinal-edge-inset +
Value: + <'column-rule-longitudinal-edge-inset-start'> <'column-rule-longitudinal-edge-inset-end'>? +
Initial: + see individual properties +
Applies to: + see individual properties +
Inherited: + see individual properties +
Percentages: + see individual properties +
Computed value: + see individual properties +
Animation type: + see individual properties +
Canonical order: + per grammar +
+ + + + + + + + + + + +
Name: + row-rule-longitudinal-edge-inset +
Value: + <'row-rule-longitudinal-edge-inset-start'> <'row-rule-longitudinal-edge-inset-end'>? +
Initial: + see individual properties +
Applies to: + see individual properties +
Inherited: + see individual properties +
Percentages: + see individual properties +
Computed value: + see individual properties +
Animation type: + see individual properties +
Canonical order: + per grammar +
+

These shortands specify the corresponding start/end values. If one value is specified it is used for both start/end.

+

4. Row Rule Style and Color

+

4.1. The row-rule-style and row-rule-color Properties

+ + + + + + + + + + + +
Name: + row-rule-style +
Value: + <line-style> +
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 +
Canonical order: + per grammar +
Animation type: + discrete +
+ + + + + + + + + + + +
Name: + row-rule-color +
Value: + <color> +
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 +
Canonical order: + per grammar +
Animation type: + by computed value type +
+

These properties are the same as the column- properties but for the row rules.

+

4.2. The row-rule Shorthand

+

This shorthand works the same as column-rule.

+ + + + + + + + + + + +
Name: + row-rule +
Value: + <'row-rule-width'> || <'row-rule-style'> || <'row-rule-color'> +
Initial: + see individual properties +
Applies to: + see individual properties +
Inherited: + see individual properties +
Percentages: + see individual properties +
Computed value: + see individual properties +
Animation type: + see individual properties +
Canonical order: + per grammar +
+

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: <row-rule-foo> <column-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...

+

5. Rule Alignment

+

5.1. The column-rule-align and row-rule-align Properties

+ + + + + + + + + + + +
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 +
Canonical order: + per grammar +
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, 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).

+ +

5.2. The column-rule-edge-align and row-rule-edge-align Properties

+ + + + + + + + + + + +
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 +
Canonical order: + per grammar +
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 rule/rule-center/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 gap / gap-over and rule / rule-over are swapped. It’s only the + center values that are shared. Also note that gap-center isn’t necessarily aligned with 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:

+
    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 (gap) + so they align with the inline axis gap edges.

+

Are there use cases for other box-related edge attachment points? + e.g. 'padding | padding-center | padding-over | border...'

+

6. Rule Extent

+

6.1. The column-rule-extent and row-rule-extent Properties

+ + + + + + + + + + + +
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 +
Canonical order: + per grammar +
Animation type: + discrete +
+

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 segment in more detail in the container-specific sub-sections that follow.

+

The 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 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 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.

+

6.1.1. Grid Containers

+

In a grid container, gaps are placed between tracks, so the segment value maps to the extent of a grid cell.

+

This example illustrates 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 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 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 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 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 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 short(long), + the extent size is the length of the shortest(longest) of + the two next grid cell spans +
    2. for start(end), + the extent size is the length of the next grid cell span of the start-most(end-most) track +
    3. for 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. +
+ +
6.1.1.1. 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.

+

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.

+ +
6.1.1.2. 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.

+ + +

TODO: add definition list and algorithm here...

+

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 short/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...

+

6.1.2. Flex Containers

+

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 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 allow-overlap is used (together with + one the 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.

+

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.

+

Authors are advised to not use the 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 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 short(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)

+ + +

6.1.3. Table Containers

+

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 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 short/long/start/end keywords behave the same. Ditto for the all-* keywords.

+ +

sort out if non-collapsed column-groups that only contain collapsed columns should generate rules, ditto row-groups/rows

+

6.1.4. Table Row Group Containers

+

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. 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.

+

6.1.5. Multi-Column Containers

+

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.

+

this proposal makes the assumption that the related proposal that row-gap should apply to multi-column containers is also adopted + (issue #6746).

+ + +

7. The 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:

+
      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 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 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.)

+

8. 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.

+

9. 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.

+
+

Conformance

+

Document conventions

+

Conformance requirements are expressed with a combination of + descriptive assertions and RFC 2119 terminology. The key words “MUST”, + “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, + “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this + document are to be interpreted as described in RFC 2119. + However, for readability, these words do not appear in all uppercase + letters in this specification.

+

All of the text of this specification is normative except sections + explicitly marked as non-normative, examples, and notes. [RFC2119]

+

Examples in this specification are introduced with the words “for example” + or are set apart from the normative text with class="example", + like this:

+
+ +

This is an example of an informative example.

+
+

Informative notes begin with the word “Note” and are set apart from the + normative text with class="note", like this:

+

Note, this is an informative note.

+

+ Advisements are normative sections styled to evoke special attention and are + set apart from other normative text with <strong class="advisement">, like + this: UAs MUST provide an accessible alternative. +

+ Tests +

Tests relating to the content of this specification + may be documented in “Tests” blocks like this one. + Any such block is non-normative.

+
    +
    +
    +

    +

    Conformance classes

    +

    Conformance to this specification + is defined for three conformance classes:

    +
    +
    style sheet +
    A CSS + style sheet. +
    renderer +
    A UA that interprets the semantics of a style sheet and renders + documents that use them. +
    authoring tool +
    A UA that writes a style sheet. +
    +

    A style sheet is conformant to this specification + if all of its statements that use syntax defined in this module are valid + according to the generic CSS grammar and the individual grammars of each + feature defined in this module.

    +

    A renderer is conformant to this specification + if, in addition to interpreting the style sheet as defined by the + appropriate specifications, it supports all the features defined + by this specification by parsing them correctly + and rendering the document accordingly. However, the inability of a + UA to correctly render a document due to limitations of the device + does not make the UA non-conformant. (For example, a UA is not + required to render color on a monochrome monitor.)

    +

    An authoring tool is conformant to this specification + if it writes style sheets that are syntactically correct according to the + generic CSS grammar and the individual grammars of each feature in + this module, and meet all other conformance requirements of style sheets + as described in this module.

    +

    Partial implementations

    +

    So that authors can exploit the forward-compatible parsing rules to + assign fallback values, CSS renderers must treat as invalid (and ignore + as appropriate) any at-rules, properties, property values, keywords, + and other syntactic constructs for which they have no usable level of + support. In particular, user agents must not selectively + ignore unsupported component values and honor supported values in a single + multi-value property declaration: if any value is considered invalid + (as unsupported values must be), CSS requires that the entire declaration + be ignored.

    +

    Implementations of Unstable and Proprietary Features

    +

    To avoid clashes with future stable CSS features, + the CSSWG recommends following best practices for the implementation of unstable features and proprietary extensions to CSS.

    +

    Non-experimental implementations

    +

    Once a specification reaches the Candidate Recommendation stage, + non-experimental implementations are possible, and implementors should + release an unprefixed implementation of any CR-level feature they + can demonstrate to be correctly implemented according to spec.

    +

    To establish and maintain the interoperability of CSS across + implementations, the CSS Working Group requests that non-experimental + CSS renderers submit an implementation report (and, if necessary, the + testcases used for that implementation report) to the W3C before + releasing an unprefixed implementation of any CSS features. Testcases + submitted to W3C are subject to review and correction by the CSS + Working Group.

    +

    Further information on submitting testcases and implementation reports + can be found from on the CSS Working Group’s website at http://www.w3.org/Style/CSS/Test/. + Questions should be directed to the public-css-testsuite@w3.org mailing list.

    + +

    Index

    +

    Terms defined by this specification

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

    Terms defined by reference

    +
      +
    • + [css-backgrounds-3] defines the following terms: +
        +
      • <line-style> +
      • <line-width> +
      • border-style +
      +
    • + [css-box-4] defines the following terms: +
        +
      • all +
      • margin-box +
      +
    • + [css-cascade-5] defines the following terms: +
        +
      • used value +
      +
    • + [css-color-4] defines the following terms: +
        +
      • <color> +
      • opacity +
      +
    • + [css-display-3] defines the following terms: +
        +
      • order-modified document order +
      +
    • + [css-flexbox-1] defines the following terms: +
        +
      • flex container +
      +
    • + [css-grid-2] defines the following terms: +
        +
      • collapsed track +
      • grid +
      • grid cell +
      • grid container +
      • grid-column +
      • grid-row +
      • implicit grid +
      • subgrid +
      +
    • + [css-grid-3] defines the following terms: +
        +
      • masonry axis +
      +
    • + [css-images-3] defines the following terms: +
        +
      • <image> +
      • default object size +
      • specified size +
      +
    • + [css-multicol-1] defines the following terms: +
        +
      • column-rule-width +
      • multi-column container +
      • multi-column layout +
      • spanner +
      +
    • + [css-multicol-2] defines the following terms: +
        +
      • column-span +
      +
    • + [css-overflow-3] defines the following terms: +
        +
      • ink overflow +
      • overflow +
      +
    • + [css-position-3] defines the following terms: +
        +
      • left +
      • right +
      +
    • + [css-sizing-3] defines the following terms: +
        +
      • outer size +
      • width +
      +
    • + [css-tables-3] defines the following terms: +
        +
      • span +
      • table +
      • table-cell +
      • table-column +
      • table-column-group +
      • table-row +
      • table-row-group +
      +
    • + [css-values-4] defines the following terms: +
        +
      • <integer> +
      • <length-percentage> +
      • <number> +
      • <percentage> +
      • ? +
      • {a,b} +
      • | +
      • || +
      +
    • + [css-writing-modes-4] defines the following terms: +
        +
      • writing-mode +
      +
    +

    References

    +

    Normative References

    +
    +
    [CSS-BACKGROUNDS-3] +
    Bert Bos; Elika Etemad; Brad Kemper. CSS Backgrounds and Borders Module Level 3. 26 July 2021. CR. URL: https://www.w3.org/TR/css-backgrounds-3/ +
    [CSS-BOX-4] +
    Elika Etemad. CSS Box Model Module Level 4. 21 April 2020. WD. URL: https://www.w3.org/TR/css-box-4/ +
    [CSS-CASCADE-5] +
    Elika Etemad; Miriam Suzanne; Tab Atkins Jr.. CSS Cascading and Inheritance Level 5. 15 October 2021. WD. URL: https://www.w3.org/TR/css-cascade-5/ +
    [CSS-COLOR-4] +
    Tab Atkins Jr.; Chris Lilley. CSS Color Module Level 4. 1 June 2021. WD. URL: https://www.w3.org/TR/css-color-4/ +
    [CSS-DISPLAY-3] +
    Tab Atkins Jr.; Elika Etemad. CSS Display Module Level 3. 3 September 2021. CR. URL: https://www.w3.org/TR/css-display-3/ +
    [CSS-FLEXBOX-1] +
    Tab Atkins Jr.; et al. CSS Flexible Box Layout Module Level 1. 19 November 2018. CR. URL: https://www.w3.org/TR/css-flexbox-1/ +
    [CSS-GRID-2] +
    Tab Atkins Jr.; Elika Etemad; Rossen Atanassov. CSS Grid Layout Module Level 2. 18 December 2020. CR. URL: https://www.w3.org/TR/css-grid-2/ +
    [CSS-GRID-3] +
    CSS Grid Layout Level 3 URL: https://drafts.csswg.org/css-grid-3/ +
    [CSS-IMAGES-3] +
    Tab Atkins Jr.; Elika Etemad; Lea Verou. CSS Images Module Level 3. 17 December 2020. CR. URL: https://www.w3.org/TR/css-images-3/ +
    [CSS-MULTICOL-1] +
    Florian Rivoal; Rachel Andrew. CSS Multi-column Layout Module Level 1. 12 October 2021. CR. URL: https://www.w3.org/TR/css-multicol-1/ +
    [CSS-OVERFLOW-3] +
    David Baron; Elika Etemad; Florian Rivoal. CSS Overflow Module Level 3. 3 June 2020. WD. URL: https://www.w3.org/TR/css-overflow-3/ +
    [CSS-SIZING-3] +
    Tab Atkins Jr.; Elika Etemad. CSS Box Sizing Module Level 3. 17 March 2021. WD. URL: https://www.w3.org/TR/css-sizing-3/ +
    [CSS-TABLES-3] +
    François Remy; Greg Whitworth; David Baron. CSS Table Module Level 3. 27 July 2019. WD. URL: https://www.w3.org/TR/css-tables-3/ +
    [CSS-VALUES-4] +
    Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 4. 16 October 2021. WD. URL: https://www.w3.org/TR/css-values-4/ +
    [CSS-WRITING-MODES-4] +
    Elika Etemad; Koji Ishii. CSS Writing Modes Level 4. 30 July 2019. CR. URL: https://www.w3.org/TR/css-writing-modes-4/ +
    [RFC2119] +
    S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119 +
    +

    Informative References

    +
    +
    [CSS-MULTICOL-2] +
    CSS Multi-column Layout Module Level 2 URL: https://drafts.csswg.org/css-multicol-2/ +
    [CSS-POSITION-3] +
    Elika Etemad; et al. CSS Positioned Layout Module Level 3. 19 May 2020. WD. URL: https://www.w3.org/TR/css-position-3/ +
    +

    Property Index

    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Name + Value + Initial + Applies to + Inh. + %ages + Anim­ation type + Canonical order + Com­puted value +
    column-rule-align + [gap | gap-center | gap-over | rule | rule-center | rule-over]{1,2} + gap + multi-column containers, flex containers, grid containers, table and table-row-group containers + no + N/A + discrete + per grammar + the specified value +
    column-rule-edge-align + [gap | gap-center | gap-over]{1,2} + gap + multi-column containers, flex containers, grid containers, table and table-row-group containers + no + N/A + discrete + per grammar + the specified value +
    column-rule-extent + [segment | start | end | short | long | all-start | all-end | all-short | all-long ] allow-overlap? + long + multi-column containers, flex containers, grid containers, table and table-row-group containers + no + N/A + discrete + per grammar + the specified value +
    column-rule-image + <'column-rule-image-source'> || <'column-rule-image-slice'> || <'column-rule-image-repeat'> + see individual properties + multi-column containers, flex containers, grid containers, table and table-row-group containers + see individual properties + see individual properties + see individual properties + per grammar + see individual properties +
    column-rule-image-repeat + stretch | repeat | round | space + stretch + multi-column containers, flex containers, grid containers, table and table-row-group containers + no + N/A + discrete + per grammar + the specified keyword +
    column-rule-image-slice + [<number [0,∞]> | <percentage [0,∞]>]{1,2} + 0 + multi-column containers, flex containers, grid containers, table and table-row-group containers + no + refer to image size in the rule’s longitudinal axis + discrete + per grammar + one or two values, each either a number or percentage +
    column-rule-image-source + none | <image> + none + multi-column containers, flex containers, grid containers, table and table-row-group containers + no + N/A + discrete + per grammar + the keyword none or the computed <image> +
    column-rule-lateral-inset + <'column-rule-lateral-inset-start'> <'column-rule-lateral-inset-end'>? + see individual properties + see individual properties + see individual properties + see individual properties + see individual properties + per grammar + see individual properties +
    column-rule-lateral-inset-end + <length-percentage> | auto + auto + multi-column containers, flex containers, grid containers, table and table-row-group containers + no + refer to the rule containing rectangle’s size in the rule’s lateral axis + by computed value type + per grammar + the specified value +
    column-rule-lateral-inset-start + <length-percentage> | auto + auto + multi-column containers, flex containers, grid containers, table and table-row-group containers + no + refer to the rule containing rectangle’s size in the rule’s lateral axis + by computed value type + per grammar + the specified value +
    column-rule-length + <length-percentage> | auto + auto + multi-column containers, flex containers, grid containers, table and table-row-group containers + no + refer to the rule containing rectangle’s size in the rule’s longitudinal axis + by computed value type + per grammar + the specified value +
    column-rule-longitudinal-edge-inset + <'column-rule-longitudinal-edge-inset-start'> <'column-rule-longitudinal-edge-inset-end'>? + see individual properties + see individual properties + see individual properties + see individual properties + see individual properties + per grammar + see individual properties +
    column-rule-longitudinal-edge-inset-end + <length-percentage> | auto + 0 + multi-column containers, flex containers, grid containers, table and table-row-group containers + no + refer to the rule containing rectangle’s size in the rule’s longitudinal axis + by computed value type + per grammar + the specified value +
    column-rule-longitudinal-edge-inset-start + <length-percentage> | auto + 0 + multi-column containers, flex containers, grid containers, table and table-row-group containers + no + refer to the rule containing rectangle’s size in the rule’s longitudinal axis + by computed value type + per grammar + the specified value +
    column-rule-longitudinal-inset + <'column-rule-longitudinal-inset-start'> <'column-rule-longitudinal-inset-end'>? + see individual properties + see individual properties + see individual properties + see individual properties + see individual properties + per grammar + see individual properties +
    column-rule-longitudinal-inset-end + <length-percentage> | auto + 0 + multi-column containers, flex containers, grid containers, table and table-row-group containers + no + refer to the rule containing rectangle’s size in the rule’s longitudinal axis + by computed value type + per grammar + the specified value +
    column-rule-longitudinal-inset-start + <length-percentage> | auto + 0 + multi-column containers, flex containers, grid containers, table and table-row-group containers + no + refer to the rule containing rectangle’s size in the rule’s longitudinal axis + by computed value type + per grammar + the specified value +
    row-rule + <'row-rule-width'> || <'row-rule-style'> || <'row-rule-color'> + see individual properties + see individual properties + see individual properties + see individual properties + see individual properties + per grammar + see individual properties +
    row-rule-align + [gap | gap-center | gap-over | rule | rule-center | rule-over]{1,2} + gap + multi-column containers, flex containers, grid containers, table and table-row-group containers + no + N/A + discrete + per grammar + the specified value +
    row-rule-color + <color> + currentcolor + multi-column containers, flex containers, grid containers, table and table-row-group containers + no + N/A + by computed value type + per grammar + computed color +
    row-rule-edge-align + [gap | gap-center | gap-over]{1,2} + gap + multi-column containers, flex containers, grid containers, table and table-row-group containers + no + N/A + discrete + per grammar + the specified value +
    row-rule-extent + [segment | start | end | short | long | all-start | all-end | all-short | all-long ] allow-overlap? + long + multi-column containers, flex containers, grid containers, table and table-row-group containers + no + N/A + discrete + per grammar + the specified value +
    row-rule-image + <'column-rule-image-source'> || <'column-rule-image-slice'> || <'column-rule-image-repeat'> + see individual properties + multi-column containers, flex containers, grid containers, table and table-row-group containers + see individual properties + see individual properties + see individual properties + per grammar + see individual properties +
    row-rule-image-repeat + stretch | repeat | round | space + stretch + multi-column containers, flex containers, grid containers, table and table-row-group containers + no + N/A + discrete + per grammar + the specified keyword +
    row-rule-image-slice + [<number [0,∞]> | <percentage [0,∞]>]{1,2} + 0 + multi-column containers, flex containers, grid containers, table and table-row-group containers + no + refer to image size in the rule’s longitudinal axis + discrete + per grammar + one or two values, each either a number or percentage +
    row-rule-image-source + none | <image> + none + multi-column containers, flex containers, grid containers, table and table-row-group containers + no + N/A + discrete + per grammar + the keyword none or the computed <image> +
    row-rule-lateral-inset + <'row-rule-lateral-inset-start'> <'row-rule-lateral-inset-end'>? + see individual properties + see individual properties + see individual properties + see individual properties + see individual properties + per grammar + see individual properties +
    row-rule-lateral-inset-end + <length-percentage> | auto + auto + multi-column containers, flex containers, grid containers, table and table-row-group containers + no + refer to the rule containing rectangle’s size in the rule’s lateral axis + by computed value type + per grammar + the specified value +
    row-rule-lateral-inset-start + <length-percentage> | auto + auto + multi-column containers, flex containers, grid containers, table and table-row-group containers + no + refer to the rule containing rectangle’s size in the rule’s lateral axis + by computed value type + per grammar + the specified value +
    row-rule-length + <length-percentage> | auto + auto + multi-column containers, flex containers, grid containers, table and table-row-group containers + no + refer to the rule containing rectangle’s size in the rule’s longitudinal axis + by computed value type + per grammar + the specified value +
    row-rule-longitudinal-edge-inset + <'row-rule-longitudinal-edge-inset-start'> <'row-rule-longitudinal-edge-inset-end'>? + see individual properties + see individual properties + see individual properties + see individual properties + see individual properties + per grammar + see individual properties +
    row-rule-longitudinal-edge-inset-end + <length-percentage> | auto + 0 + multi-column containers, flex containers, grid containers, table and table-row-group containers + no + refer to the rule containing rectangle’s size in the rule’s longitudinal axis + by computed value type + per grammar + the specified value +
    row-rule-longitudinal-edge-inset-start + <length-percentage> | auto + 0 + multi-column containers, flex containers, grid containers, table and table-row-group containers + no + refer to the rule containing rectangle’s size in the rule’s longitudinal axis + by computed value type + per grammar + the specified value +
    row-rule-longitudinal-inset + <'row-rule-longitudinal-inset-start'> <'row-rule-longitudinal-inset-end'>? + see individual properties + see individual properties + see individual properties + see individual properties + see individual properties + per grammar + see individual properties +
    row-rule-longitudinal-inset-end + <length-percentage> | auto + 0 + multi-column containers, flex containers, grid containers, table and table-row-group containers + no + refer to the rule containing rectangle’s size in the rule’s longitudinal axis + by computed value type + per grammar + the specified value +
    row-rule-longitudinal-inset-start + <length-percentage> | auto + 0 + multi-column containers, flex containers, grid containers, table and table-row-group containers + no + refer to the rule containing rectangle’s size in the rule’s longitudinal axis + by computed value type + per grammar + the specified value +
    row-rule-style + <line-style> + none + multi-column containers, flex containers, grid containers, table and table-row-group containers + no + N/A + discrete + per grammar + specified keyword +
    row-rule-width + <line-width> | <percentage> | auto + medium + multi-column containers, flex containers, grid containers, table and table-row-group containers + no + refer to the rule containing rectangle’s size in the rule’s lateral axis + by computed value type + per grammar + absolute length if the specified value is <line-width>; 0px if the column rule style is none or hidden. Otherwise, the specified value. +
    +
    +

    Issues Index

    +
    +
    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: <row-rule-foo> <column-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... ↵
    +
    Are there use cases for other box-related edge attachment points? + e.g. 'padding | padding-center | padding-over | border...' ↵
    +
    perhaps make all a separate keyword? like so: [segment | [[start | end | short | long] all?] ] allow-overlap? ↵
    +
    TODO: add definition list and algorithm here... ↵
    +
    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 short/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... ↵
    +
    sort out if non-collapsed column-groups that only contain collapsed columns should generate rules, ditto row-groups/rows ↵
    +
    this proposal makes the assumption that the related proposal that row-gap should apply to multi-column containers is also adopted + (issue #6746). ↵
    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/layout/docs/css-gap-decorations/examples/flexbox-coupon-rule.html b/layout/docs/css-gap-decorations/examples/flexbox-coupon-rule.html new file mode 100644 index 0000000000..505ad756dd --- /dev/null +++ b/layout/docs/css-gap-decorations/examples/flexbox-coupon-rule.html @@ -0,0 +1,23 @@ + + + + + Coupon example + + + +
    满 100减 20
    diff --git a/layout/docs/css-gap-decorations/examples/flexbox-extent-001.html b/layout/docs/css-gap-decorations/examples/flexbox-extent-001.html new file mode 100644 index 0000000000..76de01fe8d --- /dev/null +++ b/layout/docs/css-gap-decorations/examples/flexbox-extent-001.html @@ -0,0 +1,42 @@ + + +A 'row-rule-extent: end' example + + +
    12345
    diff --git a/layout/docs/css-gap-decorations/examples/flexbox-extent-all-long-001.html b/layout/docs/css-gap-decorations/examples/flexbox-extent-all-long-001.html new file mode 100644 index 0000000000..92f5075882 --- /dev/null +++ b/layout/docs/css-gap-decorations/examples/flexbox-extent-all-long-001.html @@ -0,0 +1,42 @@ + + +An example of 'row-rule-extent: all-long' + + +
    12345
    diff --git a/layout/docs/css-gap-decorations/examples/flexbox-extent-all-long-allow-overlap-001.html b/layout/docs/css-gap-decorations/examples/flexbox-extent-all-long-allow-overlap-001.html new file mode 100644 index 0000000000..80404c44da --- /dev/null +++ b/layout/docs/css-gap-decorations/examples/flexbox-extent-all-long-allow-overlap-001.html @@ -0,0 +1,42 @@ + + +An example of 'column-rule-extent: all-long allow-overlap' + + +
    12345
    diff --git a/layout/docs/css-gap-decorations/examples/flexbox-extent-all-short-001.html b/layout/docs/css-gap-decorations/examples/flexbox-extent-all-short-001.html new file mode 100644 index 0000000000..211e7d0bd1 --- /dev/null +++ b/layout/docs/css-gap-decorations/examples/flexbox-extent-all-short-001.html @@ -0,0 +1,42 @@ + + +An example of 'row-rule-extent: all-short' + + +
    12345
    diff --git a/layout/docs/css-gap-decorations/examples/flexbox-extent-end-001.html b/layout/docs/css-gap-decorations/examples/flexbox-extent-end-001.html new file mode 100644 index 0000000000..e049ec632b --- /dev/null +++ b/layout/docs/css-gap-decorations/examples/flexbox-extent-end-001.html @@ -0,0 +1,42 @@ + + +An example of 'row-rule-extent: end' + + +
    12345
    diff --git a/layout/docs/css-gap-decorations/examples/flexbox-extent-long-001.html b/layout/docs/css-gap-decorations/examples/flexbox-extent-long-001.html new file mode 100644 index 0000000000..e29274eda9 --- /dev/null +++ b/layout/docs/css-gap-decorations/examples/flexbox-extent-long-001.html @@ -0,0 +1,42 @@ + + +An example of 'row-rule-extent: long' + + +
    12345
    diff --git a/layout/docs/css-gap-decorations/examples/flexbox-extent-start-001.html b/layout/docs/css-gap-decorations/examples/flexbox-extent-start-001.html new file mode 100644 index 0000000000..06688a6605 --- /dev/null +++ b/layout/docs/css-gap-decorations/examples/flexbox-extent-start-001.html @@ -0,0 +1,42 @@ + + +An example of 'row-rule-extent: start' + + +
    12345
    diff --git a/layout/docs/css-gap-decorations/examples/grid-align-001.html b/layout/docs/css-gap-decorations/examples/grid-align-001.html new file mode 100644 index 0000000000..c334785183 --- /dev/null +++ b/layout/docs/css-gap-decorations/examples/grid-align-001.html @@ -0,0 +1,83 @@ + + +Examples of 'row-rule-align' values. + + +
    Note that the row rules all have a 1px longitudinal inset
+to separate the individual rule segments. ('rule-center',
+for example, would otherwise look like one long rule)
+
+Note also that the column rule is intentionally not centered in
+the gap (to separate 'rule-center' from 'gap-center').
+
    + +
    12345
    +
    12345

    +
    12345
    +
    12345

    +
    12345
    +
    12345

    + + diff --git a/layout/docs/css-gap-decorations/examples/grid-extent-001.html b/layout/docs/css-gap-decorations/examples/grid-extent-001.html new file mode 100644 index 0000000000..c5576bb995 --- /dev/null +++ b/layout/docs/css-gap-decorations/examples/grid-extent-001.html @@ -0,0 +1,80 @@ + + +Examples of 'column-rule-extent' on a grid container + + + +
    Test of various 'row-rule-extent' values:
    + +
    12345678
    +
    12345678

    +
    12345678
    +
    12345678

    +
    12345678
    +
    12345678

    +
    12345678
    +
    12345678

    +
    12345678
    +
    12345678

    + + diff --git a/layout/docs/css-gap-decorations/examples/grid-gradient-001.html b/layout/docs/css-gap-decorations/examples/grid-gradient-001.html new file mode 100644 index 0000000000..52240f4025 --- /dev/null +++ b/layout/docs/css-gap-decorations/examples/grid-gradient-001.html @@ -0,0 +1,45 @@ + + +Example of a gradient rule image + + + +
    1234567
    diff --git a/layout/docs/css-gap-decorations/examples/grid-gradient-002.html b/layout/docs/css-gap-decorations/examples/grid-gradient-002.html new file mode 100644 index 0000000000..0a39053ed4 --- /dev/null +++ b/layout/docs/css-gap-decorations/examples/grid-gradient-002.html @@ -0,0 +1,60 @@ + + +Examples of rule image properties + + + +
    1234567
    diff --git a/layout/docs/css-gap-decorations/examples/grid-image-001.html b/layout/docs/css-gap-decorations/examples/grid-image-001.html new file mode 100644 index 0000000000..5d265ef9e7 --- /dev/null +++ b/layout/docs/css-gap-decorations/examples/grid-image-001.html @@ -0,0 +1,49 @@ + + +Example of rule image properties + + + +
    1234567
    diff --git a/layout/docs/css-gap-decorations/examples/grid-image-002.html b/layout/docs/css-gap-decorations/examples/grid-image-002.html new file mode 100644 index 0000000000..2f1b7eb56a --- /dev/null +++ b/layout/docs/css-gap-decorations/examples/grid-image-002.html @@ -0,0 +1,62 @@ + + +Example of rule image with animated container size + + + +
    1234567
    diff --git a/layout/docs/css-gap-decorations/examples/grid-lateral-001.html b/layout/docs/css-gap-decorations/examples/grid-lateral-001.html new file mode 100644 index 0000000000..05f80265f6 --- /dev/null +++ b/layout/docs/css-gap-decorations/examples/grid-lateral-001.html @@ -0,0 +1,103 @@ + + +Examples of rule lateral properties + + +
    +The triplet of values below each grid container are:
+column-rule-lateral-inset-start, column-rule-width, column-rule-lateral-inset-end
+
    +
    12
    +
    12
    +
    12

    +
    12
    +
    12

    +
    1234
    +
    1234
    + + + diff --git a/layout/docs/css-gap-decorations/examples/grid-lateral-002.html b/layout/docs/css-gap-decorations/examples/grid-lateral-002.html new file mode 100644 index 0000000000..66ea9c2a38 --- /dev/null +++ b/layout/docs/css-gap-decorations/examples/grid-lateral-002.html @@ -0,0 +1,66 @@ + + +Examples of column-rule-lateral-inset-start + + +
    +Examples of aligning a rule at the start of the gap with a lateral offset:
+
    +
    12
    +
    12
    + + + diff --git a/layout/docs/css-gap-decorations/examples/grid-lateral-003.html b/layout/docs/css-gap-decorations/examples/grid-lateral-003.html new file mode 100644 index 0000000000..f478280820 --- /dev/null +++ b/layout/docs/css-gap-decorations/examples/grid-lateral-003.html @@ -0,0 +1,66 @@ + + +Examples of column-rule-lateral-inset-end + + +
    +Examples of aligning a rule at the end of the gap with a lateral offset:
+
    +
    12
    +
    12
    + + + diff --git a/layout/docs/css-gap-decorations/examples/grid-lateral-004.html b/layout/docs/css-gap-decorations/examples/grid-lateral-004.html new file mode 100644 index 0000000000..7c9a249085 --- /dev/null +++ b/layout/docs/css-gap-decorations/examples/grid-lateral-004.html @@ -0,0 +1,63 @@ + + +Example of default rule alignment and size + + +
    +Example showing the default rule alignment and size:
+
    +
    12
    + + + diff --git a/layout/docs/css-gap-decorations/examples/grid-longitudinal-001.html b/layout/docs/css-gap-decorations/examples/grid-longitudinal-001.html new file mode 100644 index 0000000000..d1eea4188c --- /dev/null +++ b/layout/docs/css-gap-decorations/examples/grid-longitudinal-001.html @@ -0,0 +1,95 @@ + + +Examples of rule longitudinal properties + +
    Note that the grid items have 'opacity: 0.5' to show
+any rules underneath them.
    +
    12345
    +
    12345

    +
    12345
    +
    12345

    +
    12345
    diff --git a/layout/docs/css-gap-decorations/examples/grid-longitudinal-002.html b/layout/docs/css-gap-decorations/examples/grid-longitudinal-002.html new file mode 100644 index 0000000000..750fd24a70 --- /dev/null +++ b/layout/docs/css-gap-decorations/examples/grid-longitudinal-002.html @@ -0,0 +1,57 @@ + + +Examples of rule longitudinal properties + + +
    1234567
    diff --git a/layout/docs/css-gap-decorations/examples/grid-longitudinal-003.html b/layout/docs/css-gap-decorations/examples/grid-longitudinal-003.html new file mode 100644 index 0000000000..925ce3018b --- /dev/null +++ b/layout/docs/css-gap-decorations/examples/grid-longitudinal-003.html @@ -0,0 +1,46 @@ + + +Examples of rule overflow and clipping. + + +
    Both grids have '*-edge-inset: min(-100vw, -100vh)'.
+The right grid has 'overflow: hidden' which clips its rules at the padding edge.
    +
    1234
    +
    1234
    + diff --git a/layout/docs/css-gap-decorations/examples/grid-masonry-001.html b/layout/docs/css-gap-decorations/examples/grid-masonry-001.html new file mode 100644 index 0000000000..e47dfae1fb --- /dev/null +++ b/layout/docs/css-gap-decorations/examples/grid-masonry-001.html @@ -0,0 +1,77 @@ + + +Examples of 'column-rule-extent' values in a Masonry grid layout. + + +
    All have 'column-rule-edge-align: gap-over' to extend
+the edge rules out to the content-box edge.
    + +
    12345678
    +
    12345678

    +
    12345678
    +
    12345678

    + + diff --git a/layout/docs/css-gap-decorations/examples/grid-masonry-002.html b/layout/docs/css-gap-decorations/examples/grid-masonry-002.html new file mode 100644 index 0000000000..f984ea36aa --- /dev/null +++ b/layout/docs/css-gap-decorations/examples/grid-masonry-002.html @@ -0,0 +1,78 @@ + + +Examples of 'column-rule-extent: all-*' values in a Masonry grid layout. + + +
    All have 'row-rule-align: rule' to make the purple rules
+align with the nearest edge of the blue column rules.
+
+In the bottom two grids, 'column-rule-lateral-inset-start/end'
+is zero, respectively, to make the blue rule attach to the side
+of the track that it used for its longitudinal sizing.
+
    + +
    12345678
    +
    12345678

    +
    12345678
    +
    12345678

    + + diff --git a/layout/docs/css-gap-decorations/examples/grid-masonry-003.html b/layout/docs/css-gap-decorations/examples/grid-masonry-003.html new file mode 100644 index 0000000000..aa0e0c5f6a --- /dev/null +++ b/layout/docs/css-gap-decorations/examples/grid-masonry-003.html @@ -0,0 +1,70 @@ + + +Examples of 'column-rule-extent' values in a Masonry grid layout. + + +
    
+
+
    1234567
    
+
    1234567

    
+
+
diff --git a/layout/docs/css-gap-decorations/examples/grid-segment-001.html b/layout/docs/css-gap-decorations/examples/grid-segment-001.html
new file mode 100644
index 0000000000..8be5060d58
--- /dev/null
+++ b/layout/docs/css-gap-decorations/examples/grid-segment-001.html
@@ -0,0 +1,35 @@
+
+
+Example of 'column-rule-extent: segment' on a grid container
+
+
+
    row 1row 2row 3
    
diff --git a/layout/docs/css-gap-decorations/examples/grid-segment-002.html b/layout/docs/css-gap-decorations/examples/grid-segment-002.html
new file mode 100644
index 0000000000..2e64062c4a
--- /dev/null
+++ b/layout/docs/css-gap-decorations/examples/grid-segment-002.html
@@ -0,0 +1,38 @@
+
+
+Example of 'column-rule-extent: segment' on a grid container with collapsed tracks
+
+
+
    row 1row 2row 3column 3
    
diff --git a/layout/docs/css-gap-decorations/examples/grid-subgrid-001.html b/layout/docs/css-gap-decorations/examples/grid-subgrid-001.html
new file mode 100644
index 0000000000..7c34e9e938
--- /dev/null
+++ b/layout/docs/css-gap-decorations/examples/grid-subgrid-001.html
@@ -0,0 +1,73 @@
+
+
+Examples of subgrid rules.
+
+
+
    
+  123
+  
    456
    
+  78
+
    
+
+
    
+  123
+  
    456
    
+  78
+
    
diff --git a/layout/docs/css-gap-decorations/examples/h-diagonal-blue-16.png b/layout/docs/css-gap-decorations/examples/h-diagonal-blue-16.png
new file mode 100644
index 0000000000..5478ae2e28
Binary files /dev/null and b/layout/docs/css-gap-decorations/examples/h-diagonal-blue-16.png differ
diff --git a/layout/docs/css-gap-decorations/examples/multicol-row-rule-001.html b/layout/docs/css-gap-decorations/examples/multicol-row-rule-001.html
new file mode 100644
index 0000000000..f44cd2c906
--- /dev/null
+++ b/layout/docs/css-gap-decorations/examples/multicol-row-rule-001.html
@@ -0,0 +1,72 @@
+
+
+Examples of column and row rules in a multi-column container
+
+
    123column-span: all45
    
+
    123column-span: all45

    
+
    123column-span: all45
    
+
    123column-span: all45

    
+
    123column-span: all45
    
+
    123column-span: all45

    
+
    123column-span: all45
    
+
    12column-span: all34567

    
+
    12column-span: all34567

    
+
+
diff --git a/layout/docs/css-gap-decorations/examples/table-row-group-rules-001.html b/layout/docs/css-gap-decorations/examples/table-row-group-rules-001.html
new file mode 100644
index 0000000000..b5a693f0ab
--- /dev/null
+++ b/layout/docs/css-gap-decorations/examples/table-row-group-rules-001.html
@@ -0,0 +1,105 @@
+
+
+Example of rules between table-rows and table-cells
+
+
+
+  
+  
+  
+  
+    
+  
+  
+    
+    
+  
+
    *-rule-extent: long
    12345
    12345
    1,234
    
+
+
+  
+  
+  
+  
+    
+  
+  
+    
+    
+  
+
    *-rule-extent: all-long;
    row-rule-align: rule-over
    12345
    12345
    1,234
    
+
+
    
+
    
+
    Same thing, now with table rules from the last example also applied:
    
+
+
+  
+  
+  
+  
+    
+  
+  
+    
+    
+  
+
    *-rule-extent: long
    12345
    12345
    1,234
    
+
+
+  
+  
+  
+  
+    
+  
+  
+    
+    
+  
+
    *-rule-extent: all-long;
    row-rule-align: rule-over
    12345
    12345
    1,234
    
diff --git a/layout/docs/css-gap-decorations/examples/table-rules-001.html b/layout/docs/css-gap-decorations/examples/table-rules-001.html
new file mode 100644
index 0000000000..f909a19839
--- /dev/null
+++ b/layout/docs/css-gap-decorations/examples/table-rules-001.html
@@ -0,0 +1,66 @@
+
+
+Example of rules between table-column-groups and table-row-groups
+
+
+
    Note: column 2 is collapsed.
    
+
+
+  
+  +    +    +  
+  
+  
+  
+    
+  
+  
+    
+    
+  
+
    column-rule-extent: long



    12345
    12345
    12345
    
+
+
+  
+  +    +    +  
+  
+  
+  
+    
+  
+  
+    
+    
+  
+
    column-rule-extent: all-long;
    column-rule-edge-align: gap-over    



    12345
    12345
    12345
    
diff --git a/layout/docs/css-gap-decorations/examples/v-diagonal-blue-16.png b/layout/docs/css-gap-decorations/examples/v-diagonal-blue-16.png
new file mode 100644
index 0000000000..420a9a0ccc
Binary files /dev/null and b/layout/docs/css-gap-decorations/examples/v-diagonal-blue-16.png differ
diff --git a/layout/docs/css-gap-decorations/media/flexbox-coupon-rule.png b/layout/docs/css-gap-decorations/media/flexbox-coupon-rule.png
new file mode 100644
index 0000000000..033f15c002
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/flexbox-coupon-rule.png differ
diff --git a/layout/docs/css-gap-decorations/media/flexbox-extent-all-long-001.png b/layout/docs/css-gap-decorations/media/flexbox-extent-all-long-001.png
new file mode 100644
index 0000000000..53b45068c9
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/flexbox-extent-all-long-001.png differ
diff --git a/layout/docs/css-gap-decorations/media/flexbox-extent-all-long-allow-overlap-001.png b/layout/docs/css-gap-decorations/media/flexbox-extent-all-long-allow-overlap-001.png
new file mode 100644
index 0000000000..dd8e220582
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/flexbox-extent-all-long-allow-overlap-001.png differ
diff --git a/layout/docs/css-gap-decorations/media/flexbox-extent-all-short-001.png b/layout/docs/css-gap-decorations/media/flexbox-extent-all-short-001.png
new file mode 100644
index 0000000000..dd01a6a9e3
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/flexbox-extent-all-short-001.png differ
diff --git a/layout/docs/css-gap-decorations/media/flexbox-extent-end-001.png b/layout/docs/css-gap-decorations/media/flexbox-extent-end-001.png
new file mode 100644
index 0000000000..595ea211bd
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/flexbox-extent-end-001.png differ
diff --git a/layout/docs/css-gap-decorations/media/flexbox-extent-long-001.png b/layout/docs/css-gap-decorations/media/flexbox-extent-long-001.png
new file mode 100644
index 0000000000..b6a46cc2d1
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/flexbox-extent-long-001.png differ
diff --git a/layout/docs/css-gap-decorations/media/flexbox-extent-start-001.png b/layout/docs/css-gap-decorations/media/flexbox-extent-start-001.png
new file mode 100644
index 0000000000..faccd739c4
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/flexbox-extent-start-001.png differ
diff --git a/layout/docs/css-gap-decorations/media/grid-align-001.png b/layout/docs/css-gap-decorations/media/grid-align-001.png
new file mode 100644
index 0000000000..40d32c37c0
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/grid-align-001.png differ
diff --git a/layout/docs/css-gap-decorations/media/grid-extent-001.png b/layout/docs/css-gap-decorations/media/grid-extent-001.png
new file mode 100644
index 0000000000..d2a229ee51
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/grid-extent-001.png differ
diff --git a/layout/docs/css-gap-decorations/media/grid-gradient-001.png b/layout/docs/css-gap-decorations/media/grid-gradient-001.png
new file mode 100644
index 0000000000..0999f16269
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/grid-gradient-001.png differ
diff --git a/layout/docs/css-gap-decorations/media/grid-image-001.png b/layout/docs/css-gap-decorations/media/grid-image-001.png
new file mode 100644
index 0000000000..7b59b9eb3e
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/grid-image-001.png differ
diff --git a/layout/docs/css-gap-decorations/media/grid-image-002.webm b/layout/docs/css-gap-decorations/media/grid-image-002.webm
new file mode 100644
index 0000000000..4548a73d2c
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/grid-image-002.webm differ
diff --git a/layout/docs/css-gap-decorations/media/grid-lateral-001.png b/layout/docs/css-gap-decorations/media/grid-lateral-001.png
new file mode 100644
index 0000000000..366f3d7d43
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/grid-lateral-001.png differ
diff --git a/layout/docs/css-gap-decorations/media/grid-lateral-002.png b/layout/docs/css-gap-decorations/media/grid-lateral-002.png
new file mode 100644
index 0000000000..e706b9106f
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/grid-lateral-002.png differ
diff --git a/layout/docs/css-gap-decorations/media/grid-lateral-003.png b/layout/docs/css-gap-decorations/media/grid-lateral-003.png
new file mode 100644
index 0000000000..57a2aede39
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/grid-lateral-003.png differ
diff --git a/layout/docs/css-gap-decorations/media/grid-lateral-004.png b/layout/docs/css-gap-decorations/media/grid-lateral-004.png
new file mode 100644
index 0000000000..57fcf28f36
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/grid-lateral-004.png differ
diff --git a/layout/docs/css-gap-decorations/media/grid-longitudinal-001.png b/layout/docs/css-gap-decorations/media/grid-longitudinal-001.png
new file mode 100644
index 0000000000..0b9d20cae2
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/grid-longitudinal-001.png differ
diff --git a/layout/docs/css-gap-decorations/media/grid-longitudinal-002.webm b/layout/docs/css-gap-decorations/media/grid-longitudinal-002.webm
new file mode 100644
index 0000000000..ae81b079ca
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/grid-longitudinal-002.webm differ
diff --git a/layout/docs/css-gap-decorations/media/grid-longitudinal-003.png b/layout/docs/css-gap-decorations/media/grid-longitudinal-003.png
new file mode 100644
index 0000000000..2a588dec54
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/grid-longitudinal-003.png differ
diff --git a/layout/docs/css-gap-decorations/media/grid-masonry-001.png b/layout/docs/css-gap-decorations/media/grid-masonry-001.png
new file mode 100644
index 0000000000..c7eb0add9a
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/grid-masonry-001.png differ
diff --git a/layout/docs/css-gap-decorations/media/grid-masonry-002.png b/layout/docs/css-gap-decorations/media/grid-masonry-002.png
new file mode 100644
index 0000000000..1b7cd1a779
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/grid-masonry-002.png differ
diff --git a/layout/docs/css-gap-decorations/media/grid-segment-001.png b/layout/docs/css-gap-decorations/media/grid-segment-001.png
new file mode 100644
index 0000000000..b6551e4805
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/grid-segment-001.png differ
diff --git a/layout/docs/css-gap-decorations/media/grid-segment-002.png b/layout/docs/css-gap-decorations/media/grid-segment-002.png
new file mode 100644
index 0000000000..ed0c07ac5c
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/grid-segment-002.png differ
diff --git a/layout/docs/css-gap-decorations/media/grid-subgrid-001.png b/layout/docs/css-gap-decorations/media/grid-subgrid-001.png
new file mode 100644
index 0000000000..0cd819d9ea
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/grid-subgrid-001.png differ
diff --git a/layout/docs/css-gap-decorations/media/masonry-all-shorter.png b/layout/docs/css-gap-decorations/media/masonry-all-shorter.png
new file mode 100644
index 0000000000..04c17f051c
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/masonry-all-shorter.png differ
diff --git a/layout/docs/css-gap-decorations/media/multicol-colspan-2.png b/layout/docs/css-gap-decorations/media/multicol-colspan-2.png
new file mode 100644
index 0000000000..4ba57b8c71
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/multicol-colspan-2.png differ
diff --git a/layout/docs/css-gap-decorations/media/multicol-row-rule-001.png b/layout/docs/css-gap-decorations/media/multicol-row-rule-001.png
new file mode 100644
index 0000000000..eba8394add
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/multicol-row-rule-001.png differ
diff --git a/layout/docs/css-gap-decorations/media/rule-alignment-values.png b/layout/docs/css-gap-decorations/media/rule-alignment-values.png
new file mode 100644
index 0000000000..ffcbad9d46
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/rule-alignment-values.png differ
diff --git a/layout/docs/css-gap-decorations/media/rule-containing-rectangle.png b/layout/docs/css-gap-decorations/media/rule-containing-rectangle.png
new file mode 100644
index 0000000000..a7e306eb75
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/rule-containing-rectangle.png differ
diff --git a/layout/docs/css-gap-decorations/media/table-row-group-rules-001.png b/layout/docs/css-gap-decorations/media/table-row-group-rules-001.png
new file mode 100644
index 0000000000..0586f3fc70
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/table-row-group-rules-001.png differ
diff --git a/layout/docs/css-gap-decorations/media/table-rules-001.png b/layout/docs/css-gap-decorations/media/table-rules-001.png
new file mode 100644
index 0000000000..19cc58f3ac
Binary files /dev/null and b/layout/docs/css-gap-decorations/media/table-rules-001.png differ
diff --git a/layout/docs/index.rst b/layout/docs/index.rst
new file mode 100644
index 0000000000..16d9df8b05
--- /dev/null
+++ b/layout/docs/index.rst
@@ -0,0 +1,15 @@
+Layout & CSS
+============
+
+Here contains design documents for the Gecko's style system and layout engine.
+They live in the mozilla-central repository under layout/docs directory.
+
+`Layout page `__ on mozilla wiki
+contains general information about layout and the layout team at Mozilla.
+
+.. toctree::
+   :maxdepth: 1
+
+   AccessibleCaret
+   Reftest
+   LayoutDebugger
-- 
cgit v1.2.3