@@ -223,14 +223,33 @@ This list is initialized differently depending on where the {{CSSStyleValue}} is
223
223
224
224
All properties stored on the [=contained properties map=] in {{StylePropertyMapReadOnly}} are [=ASCII case-insensitive=] .
225
225
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.
230
239
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.
234
253
</div>
235
254
236
255
The <dfn method for=StylePropertyMap>append(DOMString <var>property</var>,
0 commit comments