Overview.bs

<pre class='metadata'>
Title: CSS Environment Variables Module Level 1
Shortname: css-env
Level: 1
Status: ED
Work Status: exploring
Group: CSSWG
URL: https://drafts.csswg.org/css-env-1/
Editor: Tab Atkins-Bittner, Google, w3cid 42199
Editor: Dean Jackson, Apple, w3cid 42080
Abstract: This specification defines the concept of [=environment variables=] and the ''env()'' function, which work similarly to custom properties and the ''var()'' function, but are defined globally for a document. These can be defined either by the user agent, providing values that can be used on the page based on information the UA has special access to, or provided by the author for "global" variables that are guaranteed to be the same no matter where in the document they're used.
</pre>

<pre class=link-defaults>
spec:dom; type:interface; text:Document
spec:css-variables-1; type:dfn; text:invalid at computed-value time
</pre>

Introduction {#intro}
=====================

The [[css-variables-1]] specification defined the concept of "cascading variables",
author-defined variables created from the value of [=custom properties=],
capable of being substituted into arbitrary other properties via the ''var()'' function.

This specification defines a related, but simpler, concept of [=environment variables=].
Unlike "cascading variables",
which can change throughout the page as their corresponding [=custom property=] takes on different values,
an [=environment variable=] is "global" to a particular document--
its value is the same everywhere.
The ''env()'' function can then be used to substitute the value into arbitrary locations,
similar to the ''var()'' function.

These "global" variables have both benefits and downsides versus cascading variables:

* Many variables aren't meant to change over the course of a page;
	they set up themes,
	or are helpers for particular numerical values.
	Using [=environment variables=] instead of [=custom properties=] to define these
	communicates the proper intent,
	which is good both for the author of the document
	(particularly when multiple people are collaborating on a single document),
	and for the user agent,
	as it can store these variables in a more optimal way.
* Because [=environment variables=] don't depend on the value of anything drawn from a particular element,
	they can be used in places where there is no obvious element to draw from,
	such as in ''@media'' rules,
	where the ''var()'' function would not be valid.
* Information from the user agent itself,
	such as the margin of the viewport to avoid laying out in by default
	(for example, to avoid overlapping a "notch" in the screen),
	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}
====================================

A CSS <dfn export for=CSS>environment variable</dfn> is a name associated with a <<declaration-value>>
(a sequence of zero more CSS tokens, with almost no restrictions on what tokens can exist),
similar to a [=custom property=].
[=Environment variables=] can be defined by the user agent,
or by the user.
(In the latter case, the names are <<custom-property-name>>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.

<index type=value for=env()></index>

Safe area inset variables {#safe-area-insets}
------------------------------------------------------------------

<table dfn-type=value dfn-for="env()">
	<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
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.

<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>> <<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,
or any part of a value in any descriptor on any [=at-rule=],
and in several other places where CSS values are allowed.

<div class=issue>
	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?
</div>

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

<div algorithm>
	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=] 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=].
</div>

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