From 1020589bcffc3414c40c3c007a08ab8342155eed Mon Sep 17 00:00:00 2001 From: Daniel Libby Date: Sun, 25 Jul 2021 23:50:22 -1000 Subject: [PATCH 1/6] Initial commit for viewport segments env variables --- css-env-1/Overview.bs | 84 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 81 insertions(+), 3 deletions(-) diff --git a/css-env-1/Overview.bs b/css-env-1/Overview.bs index 085867f65753..7819ea5385ad 100644 --- a/css-env-1/Overview.bs +++ b/css-env-1/Overview.bs @@ -52,6 +52,9 @@ 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. +[=Environment variables=] can be either be scalar values or array-like values which require the +author to provide 0-based indices into the available dimensions to refer to a specific value. + Environment Variables {#environment} ==================================== @@ -85,18 +88,23 @@ Safe area inset variables {#safe-area-insets} Name Value + Number of dimensions safe-area-inset-top <> + 0 (scalar) safe-area-inset-right <> + 0 (scalar) safe-area-inset-bottom <> + 0 (scalar) safe-area-inset-left <> + 0 (scalar) The safe area insets are four [=environment variables=] that define a rectangle by @@ -108,6 +116,71 @@ 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. + + +Viewport segment variables {#viewport-segments} +------------------------------------------------------------------ + + + + + + + + + +
Name + Value + Number of dimensions +
viewport-segment-width + <> + 2 +
viewport-segment-height + <> + 2 +
viewport-segment-top + <> + 2 +
viewport-segment-left + <> + 2 +
viewport-segment-bottom + <> + 2 +
viewport-segment-right + <> + 2 +
+ +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. + +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. + +
+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). +
+ +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} =================================================================== @@ -115,7 +188,7 @@ In order to substitute the value of an [=environment variable=] into a CSS conte use the ''env()'' function: 
-	env() = env( <> , <>? )
+	env() = env( <> <>{0,2}, <>? )
The ''env()'' function can be used in place of any part of a value in any property on any element, @@ -133,7 +206,10 @@ and in several other places where CSS values are allowed. 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 +232,9 @@ It is only syntax-checked after ''env()'' functions have been [=substituted=]. To substitute an env() 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 result in a valid 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, From 5756a3c5897885578ceeee32aadc835105005760 Mon Sep 17 00:00:00 2001 From: Daniel Libby Date: Mon, 30 Aug 2021 06:06:24 -1000 Subject: [PATCH 2/6] Apply suggested changes from review Co-authored-by: Tab Atkins Jr. --- css-env-1/Overview.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/css-env-1/Overview.bs b/css-env-1/Overview.bs index 7819ea5385ad..1e97d67d7612 100644 --- a/css-env-1/Overview.bs +++ b/css-env-1/Overview.bs @@ -188,7 +188,7 @@ In order to substitute the value of an [=environment variable=] into a CSS conte use the ''env()'' function: 
-	env() = env( <> <>{0,2}, <>? )
+	env() = env( <> <>*, <>? )
The ''env()'' function can be used in place of any part of a value in any property on any element, From 1e35d458312237f81fa865374693873db33ddc17 Mon Sep 17 00:00:00 2001 From: Daniel Libby Date: Mon, 30 Aug 2021 06:06:34 -1000 Subject: [PATCH 3/6] Apply suggested changes from review Co-authored-by: Tab Atkins Jr. --- css-env-1/Overview.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/css-env-1/Overview.bs b/css-env-1/Overview.bs index 1e97d67d7612..2c41e3fdeb90 100644 --- a/css-env-1/Overview.bs +++ b/css-env-1/Overview.bs @@ -234,7 +234,7 @@ It is only syntax-checked after ''env()'' functions have been [=substituted=]. 1. If the name provided by the first argument of the ''env()'' function 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 result in a valid value, + 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, From a250f893280d9e8752b44eb7cddc2539adf54814 Mon Sep 17 00:00:00 2001 From: Daniel Libby Date: Mon, 30 Aug 2021 06:06:55 -1000 Subject: [PATCH 4/6] Apply suggested changes from review Co-authored-by: Tab Atkins Jr. --- css-env-1/Overview.bs | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/css-env-1/Overview.bs b/css-env-1/Overview.bs index 2c41e3fdeb90..f54faaf213dc 100644 --- a/css-env-1/Overview.bs +++ b/css-env-1/Overview.bs @@ -52,8 +52,16 @@ 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. -[=Environment variables=] can be either be scalar values or array-like values which require the -author to provide 0-based indices into the available dimensions to refer to a specific value. +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 values[0]. Environment Variables {#environment} ==================================== From 7d53e40259d7a917479f8c9ef9c64e24db5636ef Mon Sep 17 00:00:00 2001 From: Daniel Libby Date: Mon, 30 Aug 2021 06:07:08 -1000 Subject: [PATCH 5/6] Apply suggested changes from review Co-authored-by: Tab Atkins Jr. --- css-env-1/Overview.bs | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/css-env-1/Overview.bs b/css-env-1/Overview.bs index f54faaf213dc..dc18460a07d0 100644 --- a/css-env-1/Overview.bs +++ b/css-env-1/Overview.bs @@ -176,12 +176,12 @@ space within the viewport. The dimensions of the separator can be computed by calculating the area between the position of the viewport segments.
-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). + 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).
These variables are only defined when there are at least two such segments. From 093ef1aac3e92834abf67cf98f4ad1d1bdc0029f Mon Sep 17 00:00:00 2001 From: Daniel Libby Date: Mon, 30 Aug 2021 06:07:39 -1000 Subject: [PATCH 6/6] Apply suggested changes from review Co-authored-by: Tab Atkins Jr. --- css-env-1/Overview.bs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/css-env-1/Overview.bs b/css-env-1/Overview.bs index dc18460a07d0..b0c0416faabe 100644 --- a/css-env-1/Overview.bs +++ b/css-env-1/Overview.bs @@ -170,6 +170,8 @@ 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