>s,
and start with `--` per standard for custom identifiers.)
Issue: Is the set of UA-defined [=environment variables=] visible to script?
If so, define an API on {{Document}} to expose them.
Issue: Define how authors can add [=environment variables=],
preferably both via JS
and via CSS.
Note that mixing CSS rules and JS-defined stuff can easily get messy,
as demonstrated by CSSFontFaceRule vs FontFace...
The following UA-defined [=environment variables=] are officially defined and must be supported.
Additional UA-defined [=environment variables=] must not be supported
unless/until they are added to this list.
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
its top, right, bottom, and left insets from the edge of the viewport. For rectangular
displays, these must all be zero, but for nonrectangular displays they must form a
rectangle, chosen by the user agent, such that all content inside the rectangle is
visible, and such that reducing any of the insets would cause some content inside of
the rectangle to be invisible due to the nonrectangular nature of the display. This
allows authors to limit the layout of essential content to the space inside of the
safe area rectangle.
Safe area maximum inset variables {#safe-area-max-insets}
------------------------------------------------------------------
| Name
| Value
| Number of dimensions
|
| safe-area-max-inset-top
| <>
| 0 (scalar)
|
| safe-area-max-inset-right
| <>
| 0 (scalar)
|
| safe-area-max-inset-bottom
| <>
| 0 (scalar)
|
| safe-area-max-inset-left
| <>
| 0 (scalar)
| | | | |
The safe area maximum insets are four [=environment variables=]
that are tied to the safe area inset variables.
Unlike the safe area inset variables which are dynamic values,
the safe area maximum insets are static values
that represent the maximum value of their dynamic counterpart
when dynamic UA interfaces are retracted,
making the [=layout viewport=] size the [=large viewport size=].
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.
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.
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}
===================================================================
In order to substitute the value of an [=environment variable=] into a CSS context,
use the ''env()'' function:
env() = env( <> <>*, <>? )
The ''env()'' function can be used in place of any part of a value in any property on any element,
or any part of a value in any descriptor on any [=at-rule=],
and in several other places where CSS values are allowed.
Define the full set of places ''env()'' can be used.
* Should be able to replace any subset of MQ syntax, for example.
* Should be able to replace selectors, maybe?
* Should it work on a rule level,
so you can insert arbitrary stuff into a rule,
like reusing a block of declarations?
The first argument to ''env()'' provides the name of an [=environment variable=] to be substituted.
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.
Note: The syntax of the fallback, like that of custom properties, allows commas.
For example, ''env(foo, red, blue)'' defines a fallback of ''red, blue'';
that is, anything between the first comma and the end of the function is considered a fallback value.
If a property contains one or more ''env()'' functions,
and those functions are syntactically valid,
the entire property's grammar must be assumed to be valid at parse time.
It is only syntax-checked at computed-time,
after ''env()'' functions have been [=substituted=].
If a descriptor contains one or more ''env()'' functions,
and those functions are syntactically valid,
the entire declaration's grammar must be assumed to be valid at parse time.
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=] 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,
replace the ''env()'' function by the fallback value.
If there are any ''env()'' references in the fallback,
[=substitute=] them as well.
3. Otherwise, the property or descriptor containing the ''env()'' function is [=invalid at computed-value time=].
Issue: Define when substitution happens.
It has to be before ''var()'' substitution.
Alternately, should ''env()'' substitution happen at parse time,
so unknown variable names cause it to fail syntax checking?
There's no particular reason to have it happen at computed-value time,
like ''var()'' does--
that was to ensure that [=custom properties=] could inherit their value down
before they were picked up by a ''var()''.
Issue: When I figure out where else ''env()'' can go,
define how/when it substitutes.
Environment Variables in Shorthand Properties {#env-in-shorthands}
------------------------------------------------------------------
Issue: If ''env()'' substitution happens during parsing,
then this is unnecessary.
The ''env()'' function causes the same difficulties with [=shorthand properties=]
as the ''var()'' function does.
When an ''env()'' is used in a [=shorthand property=],
then,
it has the same effects as defined in [[css-variables-1#variables-in-shorthands]].
Privacy Considerations
The [=environment variables=] defined by this specification
are potentially privacy-sensitive,
since they represent additional information
potentially not already avaialble to the page.
In particular, they potentially represent a fingerprinting vector,
by exposing additional information
about the device a user is viewing the page with.
So far, the [=environment variables=] defined by this specifcation
have been reviewed and deemed acceptable to expose
by the CSSWG.
Security Considerations
This specification provides read-only access
to some new types of information about the device.
The [=environment variables=] defined by this specification
do not expose any security-sensitive information.