[css-env-1] Introduce environment variable indexing and viewport segm…

…ent environment variables #5622  (#6474)

This change adds the ability to index multiple dimensions via the env() syntax. Also adds the viewport segment variables, of which there are 6 values (viewport-segment-{width, height, top, right, bottom, left}), all of which have two dimensions representing their physical location in grid-like organization of the divided viewport.

Co-authored-by: Tab Atkins Jr. <jackalmage@gmail.com>

css-env-1/Overview.bs

@@ -52,6 +52,17 @@ These "global" variables have both benefits and downsides versus cascading varia
  can be retrieved via ''env()'',
  whereas the element-specific nature of ''var()'' was not an appropriate place to pipe that information in.
 
+Most [=environment variables=] will have a single value at a time.
+Some, however, are "indexed", representing multiple values at once,
+such as the sizes and positions of several distinct panes of content 
+in the ''viewport-segment-*'' variables.
+To refer to these indexed variables, one or more integers must be provided
+alongside the variable name,
+like ''viewport-segment-width 1 0'',
+to select a single value from the list or grid of possibilities,
+similar to selecting one element from a list in a traditional programming language
+with a syntax like <code>values[0]</code>.
+
 Environment Variables {#environment}
 ====================================
 
@@ -85,18 +96,23 @@ Safe area inset variables {#safe-area-insets}
  <tr>
  <th>Name
  <th>Value
+ <th>Number of dimensions
  <tr>
  <td><dfn>safe-area-inset-top</dfn>
  <td><<length>>
+ <td>0 (scalar)
  <tr>
  <td><dfn>safe-area-inset-right</dfn>
  <td><<length>>
+ <td>0 (scalar)
  <tr>
  <td><dfn>safe-area-inset-bottom</dfn>
  <td><<length>>
+ <td>0 (scalar)
  <tr>
  <td><dfn>safe-area-inset-left</dfn>
  <td><<length>>
+ <td>0 (scalar)
 </table>
 
 The safe area insets are four [=environment variables=] that define a rectangle by
@@ -108,14 +124,81 @@ the rectangle to be invisible due to the nonrectangular nature of the display. T
 allows authors to limit the layout of essential content to the space inside of the
 safe area rectangle.
 
+<index type=value for=env()></index>
+
+Viewport segment variables {#viewport-segments}
+------------------------------------------------------------------
+
+<table dfn-type=value dfn-for="env()">
+ <tr>
+ <th>Name
+ <th>Value
+ <th>Number of dimensions
+ <tr>
+ <td><dfn>viewport-segment-width</dfn>
+ <td><<length>>
+ <td>2
+ <tr>
+ <td><dfn>viewport-segment-height</dfn>
+ <td><<length>>
+ <td>2
+ <tr>
+ <td><dfn>viewport-segment-top</dfn>
+ <td><<length>>
+ <td>2
+ <tr>
+ <td><dfn>viewport-segment-left</dfn>
+ <td><<length>>
+ <td>2
+ <tr>
+ <td><dfn>viewport-segment-bottom</dfn>
+ <td><<length>>
+ <td>2
+ <tr>
+ <td><dfn>viewport-segment-right</dfn>
+ <td><<length>>
+ <td>2
+</table>
+
+The viewport segments are [=environment variables=] that define the position and
+dimensions of a logically separate region of the viewport. Viewport
+segments are created when the viewport is split by one or more hardware features
+(such as a fold or a hinge between separate displays) that act as a divider;
+segments are the regions of the viewport that can be treated as logically distinct
+by the author.
+
+The viewport segment [=environment variables=] have two dimensions, which represent
+the x and y position, respectively, in the two dimensional grid created by the
+hardware features separating the segments.
+Segments along the left edge have x position ''0'', those in the next column to the right have x position ''1'', etc.
+Similarly, segments along the top edge have y position ''0'', etc.
+
+Note: In certain hardware configurations, the separator itself may occupy logical
+space within the viewport. The dimensions of the separator can be computed by
+calculating the area between the position of the viewport segments.
+
+<div class="example">
+ When the viewport is split into two side-by-side segments, the viewport segment on
+ the left would have indices (0, 0). It's width would be represented as
+ ''env(viewport-segment-width 0 0, 300px)''. 
+ The viewport segment on the right would have indices (1, 0).
+ Similarly, for a viewport split into two vertical segments, the viewport segment
+ on the top would have indices (0, 0) and the one on the bottom (0, 1).
+</div>
+
+These variables are only defined when there are at least two such segments.
+Viewport units should be used instead when there is no hardware feature
+splitting the viewport, otherwise content will not display as intended when
+viewed on a device with multiple segments.
+
 Using Environment Variables: the ''env()'' notation {#env-function}
 ===================================================================
 
 In order to substitute the value of an [=environment variable=] into a CSS context,
 use the ''env()'' function:
 
 <pre class=prod>
- <dfn function>env()</dfn> = env( <<custom-ident>> , <<declaration-value>>? )
+ <dfn function>env()</dfn> = env( <<custom-ident>> <<integer [0,∞]>>*, <<declaration-value>>? )
 </pre>
 
 The ''env()'' function can be used in place of any part of a value in any property on any element,
@@ -133,7 +216,10 @@ and in several other places where CSS values are allowed.
 </div>
 
 The first argument to ''env()'' provides the name of an [=environment variable=] to be substituted.
-The second argument, if provided, is a fallback value,
+Following the first argument are integers that represent indices into the
+dimensions of the [=environment variable=], if the provided name
+represents an array-like [=environment variable=].
+The argument after the comma, if provided, is a fallback value,
 which is used as the substitution value
 when the referenced [=environment variable=] does not exist.
 
@@ -156,7 +242,9 @@ It is only syntax-checked after ''env()'' functions have been [=substituted=].
  To <dfn export local-lt=substitute>substitute an env()</dfn> in a property or descriptor:
 
  1. If the name provided by the first argument of the ''env()'' function
- is a recognized [=environment variable=],
+ is a recognized [=environment variable=] name, the number of supplied integers
+ matches the number of dimensions of the [=environment variable=] referenced
+ by that name, and values of the indices correspond to a known sub-value,
  replace the ''env()'' function by the value of the named [=environment variable=].
 
  2. Otherwise, if the ''env()'' function has a fallback value as its second argument,