Skip to content

Commit 84dceaa

Browse files
tabatkinstabatkins
committed
[css-properties-values-api] Move Behavior section up front, to give me a good place to talk about general concepts.
1 parent 2e8f571 commit 84dceaa

File tree

1 file changed

+140
-136
lines changed

1 file changed

+140
-136
lines changed

‎css-properties-values-api/Overview.bs

+140-136
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,146 @@ This specification is complementary to [[css-paint-api-1]] and [[css-layout-api-
6969
allow custom properties to directly impact paint and layout behaviours respectively.
7070

7171

72+
73+
<!--
74+
████████ ████████ ██ ██ ███ ██ ██ ████ ███████ ████████
75+
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
76+
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
77+
████████ ██████ █████████ ██ ██ ██ ██ ██ ██ ██ ████████
78+
██ ██ ██ ██ ██ █████████ ██ ██ ██ ██ ██ ██ ██
79+
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
80+
████████ ████████ ██ ██ ██ ██ ███ ████ ███████ ██ ██
81+
-->
82+
83+
Behavior of Custom Properties {#behavior-of-custom-properties}
84+
==============================================================
85+
86+
Animation Behavior of Custom Properties {#animation-behavior-of-custom-properties}
87+
----------------------------------------------------------------------------------
88+
89+
Note: As defined by [[css3-animations]] and [[css3-transitions]], it is possible to
90+
specify animations and transitions that reference custom properties.
91+
92+
When referenced by animations and transitions,
93+
custom property values [=interpolate=] [=by computed value=],
94+
in accordance with the type that they parsed as.
95+
96+
Note: This implies that a list of values,
97+
such as `<color>+` or `<color>#`,
98+
will interpolate as a simple list,
99+
matching up each component index-by-index,
100+
and failing if the number of components doesn't match.
101+
102+
As an exception to the above rule,
103+
a value that parsed as a `<transform-list>`,
104+
a `<transform-function>`,
105+
or a `<transform-function>+`
106+
instead interpolates as per the 'transform' property.
107+
108+
Note: If,
109+
for whatever reason,
110+
a custom property is defined with a syntax of `<transform-function>#`,
111+
this will thus first interpolate as a simple list,
112+
and then each list item will interpolate as a 'transform' value.
113+
114+
Conditional Rules {#conditional-rules}
115+
--------------------------------------
116+
117+
<div class=note>
118+
''@supports'' rules and the {{CSS/supports(conditionText)|CSS.supports()}} method
119+
behave as specified in [[!css-variables]],
120+
without distinguishing between registered and unregistered custom properties,
121+
and paying no attention to registered properties' syntaxes.
122+
</div>
123+
124+
Relative URLs {#relative-urls}
125+
------------------------------
126+
127+
Relative URL values that appear in registered custom properties are resolved
128+
to full URLs as described in [[!css3-values]].
129+
130+
<div class='example'>
131+
Because URLs resolve against the base URL of the stylesheet they appear in, we can
132+
end up with multiple relative URLs that resolve against different base URLs, even though
133+
they appear in the same property.
134+
135+
For example, suppose '--url-foo' and '--url-bar' are registered
136+
custom properties with ''&lt;url>'' syntax, and that we have a stylesheet at
137+
<code>/style/foo/foo.css</code>:
138+
139+
<pre class='lang-css'>
140+
div {
141+
--url-foo: url("foo.png");
142+
}
143+
</pre>
144+
145+
and another stylesheet at <code>/style/bar/bar.css</code>
146+
<pre class='lang-css'>
147+
div {
148+
--url-bar: url("bar.png");
149+
}
150+
</pre>
151+
152+
and finally a document at <code>/index.html</code>:
153+
<pre class='lang-html'>
154+
&lt;link href="/style/foo/foo.css" rel="stylesheet" type="text/css">
155+
&lt;link href="/style/bar/bar.css" rel="stylesheet" type="text/css">
156+
&lt;div style="background-image: var(--url-foo), var(---url-bar);">
157+
&lt;/div>
158+
</pre>
159+
160+
Here, the ''var(--url-foo)'' reference would produce a URL that resolves against
161+
<code>/style/foo</code>, and the ''var(--url-bar)'' reference would produce a URL that resolves
162+
against <code>/style/bar</code>.
163+
164+
</div>
165+
166+
167+
Fallbacks In ''var()'' References {#fallbacks-in-var-references}
168+
----------------------------------------------------------------
169+
170+
References to registered custom properties using the ''var()'' function may
171+
provide a fallback. However, the fallback value must match the
172+
<a>syntax definition</a> of the custom property being referenced, otherwise the
173+
declaration is <a spec=css-variables>invalid at computed-value time</a>.
174+
175+
Note: This applies regardless of whether or not the fallback is being used.
176+
177+
178+
Substitution {#substitution}
179+
----------------------------
180+
181+
Like unregistered custom properties,
182+
the value of a registered custom property can be substituted into another value with the ''var()'' function.
183+
However, registered custom properties substitute as their [[#calculation-of-computed-values|computed value]],
184+
rather than the original token sequence used to produce that value.
185+
186+
Any ''var()'' function that references a registered custom property
187+
must be replaced with an <dfn export>equivalent token sequence</dfn>,
188+
which is equal to the token sequence that would have been produced
189+
by [[cssom#serialize-a-css-value|serializing]] the computed value,
190+
and [[css-syntax-3#tokenization|tokenizing]] the resulting string.
191+
192+
<div class='example'>
193+
Suppose that '--x' is registered with ''&lt;length>'' syntax,
194+
and that '--y'is an unregistered custom property.
195+
196+
<pre class='lang-css'>
197+
198+
div {
199+
font-size: 10px;
200+
--x: 8em;
201+
--y: var(--x);
202+
}
203+
</pre>
204+
205+
Because the computed value of '--x' (when serialized) is "80px",
206+
the computed value of '--y' is
207+
a <<dimension-token>> with a value of "80" and unit "px".
208+
209+
</div>
210+
211+
72212
<!--
73213
██ ██████
74214
██ ██ ██
@@ -707,143 +847,7 @@ Parsing The Syntax String {#parsing-syntax}
707847

708848

709849

710-
<!--
711-
████████ ████████ ██ ██ ███ ██ ██ ████ ███████ ████████
712-
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
713-
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
714-
████████ ██████ █████████ ██ ██ ██ ██ ██ ██ ██ ████████
715-
██ ██ ██ ██ ██ █████████ ██ ██ ██ ██ ██ ██ ██
716-
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
717-
████████ ████████ ██ ██ ██ ██ ███ ████ ███████ ██ ██
718-
-->
719-
720-
Behavior of Custom Properties {#behavior-of-custom-properties}
721-
==============================================================
722-
723-
Animation Behavior of Custom Properties {#animation-behavior-of-custom-properties}
724-
----------------------------------------------------------------------------------
725-
726-
Note: As defined by [[css3-animations]] and [[css3-transitions]], it is possible to
727-
specify animations and transitions that reference custom properties.
728-
729-
When referenced by animations and transitions,
730-
custom property values [=interpolate=] [=by computed value=],
731-
in accordance with the type that they parsed as.
732-
733-
Note: This implies that a list of values,
734-
such as `<color>+` or `<color>#`,
735-
will interpolate as a simple list,
736-
matching up each component index-by-index,
737-
and failing if the number of components doesn't match.
738-
739-
As an exception to the above rule,
740-
a value that parsed as a `<transform-list>`,
741-
a `<transform-function>`,
742-
or a `<transform-function>+`
743-
instead interpolates as per the 'transform' property.
744-
745-
Note: If,
746-
for whatever reason,
747-
a custom property is defined with a syntax of `<transform-function>#`,
748-
this will thus first interpolate as a simple list,
749-
and then each list item will interpolate as a 'transform' value.
750-
751-
Conditional Rules {#conditional-rules}
752-
--------------------------------------
753-
754-
<div class=note>
755-
''@supports'' rules and the {{CSS/supports(conditionText)|CSS.supports()}} method
756-
behave as specified in [[!css-variables]],
757-
without distinguishing between registered and unregistered custom properties,
758-
and paying no attention to registered properties' syntaxes.
759-
</div>
760-
761-
Relative URLs {#relative-urls}
762-
------------------------------
763-
764-
Relative URL values that appear in registered custom properties are resolved
765-
to full URLs as described in [[!css3-values]].
766-
767-
<div class='example'>
768-
Because URLs resolve against the base URL of the stylesheet they appear in, we can
769-
end up with multiple relative URLs that resolve against different base URLs, even though
770-
they appear in the same property.
771-
772-
For example, suppose '--url-foo' and '--url-bar' are registered
773-
custom properties with ''&lt;url>'' syntax, and that we have a stylesheet at
774-
<code>/style/foo/foo.css</code>:
775-
776-
<pre class='lang-css'>
777-
div {
778-
--url-foo: url("foo.png");
779-
}
780-
</pre>
781-
782-
and another stylesheet at <code>/style/bar/bar.css</code>
783-
<pre class='lang-css'>
784-
div {
785-
--url-bar: url("bar.png");
786-
}
787-
</pre>
788-
789-
and finally a document at <code>/index.html</code>:
790-
<pre class='lang-html'>
791-
&lt;link href="/style/foo/foo.css" rel="stylesheet" type="text/css">
792-
&lt;link href="/style/bar/bar.css" rel="stylesheet" type="text/css">
793-
&lt;div style="background-image: var(--url-foo), var(---url-bar);">
794-
&lt;/div>
795-
</pre>
796-
797-
Here, the ''var(--url-foo)'' reference would produce a URL that resolves against
798-
<code>/style/foo</code>, and the ''var(--url-bar)'' reference would produce a URL that resolves
799-
against <code>/style/bar</code>.
800-
801-
</div>
802-
803-
804-
Fallbacks In ''var()'' References {#fallbacks-in-var-references}
805-
----------------------------------------------------------------
806-
807-
References to registered custom properties using the ''var()'' function may
808-
provide a fallback. However, the fallback value must match the
809-
<a>syntax definition</a> of the custom property being referenced, otherwise the
810-
declaration is <a spec=css-variables>invalid at computed-value time</a>.
811850

812-
Note: This applies regardless of whether or not the fallback is being used.
813-
814-
815-
Substitution {#substitution}
816-
----------------------------
817-
818-
Like unregistered custom properties,
819-
the value of a registered custom property can be substituted into another value with the ''var()'' function.
820-
However, registered custom properties substitute as their [[#calculation-of-computed-values|computed value]],
821-
rather than the original token sequence used to produce that value.
822-
823-
Any ''var()'' function that references a registered custom property
824-
must be replaced with an <dfn export>equivalent token sequence</dfn>,
825-
which is equal to the token sequence that would have been produced
826-
by [[cssom#serialize-a-css-value|serializing]] the computed value,
827-
and [[css-syntax-3#tokenization|tokenizing]] the resulting string.
828-
829-
<div class='example'>
830-
Suppose that '--x' is registered with ''&lt;length>'' syntax,
831-
and that '--y'is an unregistered custom property.
832-
833-
<pre class='lang-css'>
834-
835-
div {
836-
font-size: 10px;
837-
--x: 8em;
838-
--y: var(--x);
839-
}
840-
</pre>
841-
842-
Because the computed value of '--x' (when serialized) is "80px",
843-
the computed value of '--y' is
844-
a <<dimension-token>> with a value of "80" and unit "px".
845-
846-
</div>
847851

848852

849853

0 commit comments

Comments
 (0)