Skip to content

Commit 05b03fc

Browse files
committed
Define list-valued and single-valued, and slightly rewrite the note about this as well. Add issue for explicitly listing which properties are which.
1 parent 05018ed commit 05b03fc

File tree

1 file changed

+26
-7
lines changed

1 file changed

+26
-7
lines changed

css-typed-om/Overview.bs

Lines changed: 26 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -223,14 +223,33 @@ This list is initialized differently depending on where the {{CSSStyleValue}} is
223223

224224
All properties stored on the [=contained properties map=] in {{StylePropertyMapReadOnly}} are [=ASCII case-insensitive=].
225225

226-
<div class='note'>
227-
The sequence of {{CSSStyleValue}}s associated with a property
228-
do not represent multiple successive definitions of that property's value.
229-
Instead, sequences represent values associated with [=list-valued properties=].
226+
Some CSS properties are <dfn export local-lt="list-valued">list-valued properties</dfn>,
227+
such as 'background-image' or 'animation';
228+
their value is a list of parallel grammar terms,
229+
almost always comma-separated
230+
(the only exceptions are certain legacy properties like 'counter-reset'),
231+
indicating multiple distinct "values" interpreted in the same way.
232+
Other properties,
233+
such as 'color',
234+
are <dfn export local-lt="single-valued">single-valued properties</dfn>;
235+
they take only a single (possibly complex) value.
236+
237+
Issue: Define precisely which properties are list-valued and which aren't,
238+
probably in an appendix.
230239

231-
This approach allows single-valued properties to become list-valued in the future
232-
without breaking code that relies on calling {{StylePropertyMapReadOnly/get()}}
233-
and/or {{StylePropertyMap/set()}} for those properties.
240+
<div class='note'>
241+
There are multiple examples of CSS properties
242+
that have transitioned from being [=single-valued=] to [=list-valued=].
243+
To ensure that code written at a time when a property was [=single-valued=]
244+
does not break when it becomes [=list-valued=] in the future,
245+
the {{CSSPropertyMap}} is a <b>multi-map</b>;
246+
it stores <em>list</em> of values for each key,
247+
but allows you to interact with it as if there was only a single value for each key as well.
248+
249+
This means that multiple values for a single property in a {{CSSPropertyMap}}
250+
do not represent multiple successive definition of that property's value;
251+
instead, they represent multiple comma-separated sub-values in a single property value,
252+
like each "layer" in a 'background-image' property.
234253
</div>
235254

236255
The <dfn method for=StylePropertyMap>append(DOMString <var>property</var>,

0 commit comments

Comments
 (0)