-
Notifications
You must be signed in to change notification settings - Fork 143
/
Copy pathOverview.bs
1378 lines (1108 loc) · 51.3 KB
/
Overview.bs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<pre class='metadata'>
Title: CSS Properties and Values API Level 1
Status: ED
Group: houdini
ED: https://drafts.css-houdini.org/css-properties-values-api-1/
TR: https://www.w3.org/TR/css-properties-values-api-1/
Previous Version: https://www.w3.org/TR/2020/WD-css-properties-values-api-1-20201013/
Previous Version: https://www.w3.org/TR/2019/WD-css-properties-values-api-1-20191025/
Previous Version: https://www.w3.org/TR/2017/WD-css-properties-values-api-1-20171109/
Previous Version: https://www.w3.org/TR/2016/WD-css-properties-values-api-1-20160607/
Shortname: css-properties-values-api
Level: 1
Abstract: This CSS module defines an API for registering new CSS properties. Properties registered using this API are provided with a parse syntax that defines a type, inheritance behaviour, and an initial value.
Editor: Tab Atkins-Bittner, Google, http://xanthir.com/contact/, w3cid 42199
Former Editor: Shane Stephens, [email protected], w3cid 47691
Editor: Daniel Glazman, [email protected], w3cid 13329
Editor: Alan Stearns, [email protected], w3cid 46659
Former Editor: Elliot Sprehn, [email protected]
Editor: Greg Whitworth, [email protected], w3cid 69511
Ignored Terms: boolean, Animatable, Map, Context, isolated worker, SyntaxError,
Ignored Terms: InvalidModificationError, NotFoundError, StylePropertyMapReadOnly,
Ignored Terms: worklet global scope
Ignored Terms: throw, NotSupportedError, isconstructor, get, iscallable,
Ignored Terms: construct, name map of inputs
Ignored Vars: arguments, methodPropertyKey, inputStyleMap, workletGlobalScope
Ignored Terms: WorkletGlobalContext
Repository: w3c/css-houdini-drafts
Markup Shorthands: css on, markdown on
</pre>
<pre class='link-defaults'>
spec:css-color-4; type:property; text:color
spec:css-syntax-3; type:dfn;
text:input stream
text:starts with an ident sequence
text:consume an ident sequence
spec:css-transforms-1; type:type; text:<transform-function>
spec:css-values-4;
type:value;
text:ex
text:cap
type:dfn
text:identifier
spec:cssom-1; type:interface; text:CSS
spec:dom;
type:interface; text:Document
type:dfn; text:shadow tree
spec:infra; type:dfn;
text:string
text:list
</pre>
Introduction {#intro}
=====================
CSS defines a comprehensive set of properties that can be manipulated in order
to modify the layout, paint, or behaviour of a web document. However, web authors
frequently wish to extend this set with additional properties.
[[css-variables]] provides primitive means for defining user-controlled properties,
however these properties always take token lists as values, must always inherit, and
can only impact document layout or paint by being re-incorporated into the value
of other properties via a var() reference.
This specification extends [[css-variables]], allowing the registration of properties
that have a value type, an initial value, and a defined inheritance behaviour,
via two methods:
* A JS API, the {{registerProperty()}} method
* A CSS at-rule, the ''@property'' rule
This specification is complementary to [[css-paint-api-1]] and [[css-layout-api-1]], which
allow custom properties to directly impact paint and layout behaviours respectively.
<!--
████████ ████████ ██ ██ ███ ██ ██ ████ ███████ ████████
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
████████ ██████ █████████ ██ ██ ██ ██ ██ ██ ██ ████████
██ ██ ██ ██ ██ █████████ ██ ██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
████████ ████████ ██ ██ ██ ██ ███ ████ ███████ ██ ██
-->
Registered Custom Properties {#behavior-of-custom-properties}
=============================================================
A [=custom property=] can become a <dfn export local-lt="registered">registered custom property</dfn>,
making it act more like a UA-defined property:
giving it a syntax that's checked by the UA,
an initial value,
and a specific inheritance behavior.
This can be done by the ''@property'' rule,
or the {{registerProperty()}} JS function.
A [=custom property=] is considered to be registered for a {{Document}}
if there is a valid ''@property'' rule
defined for its name
in one of the document's stylesheets,
or its name is [=map/contains|contained=]
in the document's {{[[registeredPropertySet]]}} slot
(that is, {{registerProperty()}} was called to register it).
A [=registered custom property=] acts similarly to an unregistered [=custom property=],
except as defined below.
Determining the Registration {#determining-registration}
--------------------------------------------------------
A [=registered custom property=] has a <dfn export local-lt="registration">custom property registration</dfn>
that contains all the data necessary to treat it like a real property.
It's a [=struct=] consisting of:
* a property name (a [=custom property name string=])
* a syntax (a [=syntax string=])
* an inherit flag (a [=boolean=])
* optionally, an initial value (a [=string=] which successfully [=CSS/parses=] according to the syntax)
If the {{Document}}’s {{[[registeredPropertySet]]}} slot
[=set/contains=] a record with the [=custom property’s=] name,
the registration is that record.
Otherwise,
if the {{Document}}’s active stylesheets contain at least one valid ''@property'' rule
representing a registration with the [=custom property’s=] name,
the last such one in document order is the registration.
Otherwise there is no registration,
and the [=custom property=] is <em>not</em> a [=registered custom property=].
Parse-Time Behavior {#parsing-custom-properties}
------------------------------------------------
[=Registered custom properties=] parse exactly like unregistered [=custom properties=];
almost anything is allowed.
The registered syntax of the property is <em>not</em> checked at parse time.
Note: However,
the syntax is checked at computed-value time,
before substitution via ''var()''.
See [[#calculation-of-computed-values]].
<details class=note>
<summary>Why aren't custom properties syntax-checked?</summary>
When parsing a page's CSS,
UAs commonly make a number of optimizations
to help with both speed and memory.
One of those optimizations
is that they only store the properties that will actually have an effect;
they throw away invalid properties,
and if you write the same property multiple times in a single declaration block,
all but the last valid one will be thrown away.
(This is an important part of CSS's error-recovery
and forward-compatibility behavior.)
This works fine if the syntax of a property never changes over the lifetime of a page.
If a custom property is registered, however,
it can change its syntax,
so that a property that was previously invalid
suddenly becomes valid.
The only ways to handle this are to either store every declaration,
even those that were initially invalid
(increasing the memory cost of pages),
or to re-parse the entire page's CSS
with the new syntax rules
(increasing the processing cost of registering a custom property).
Neither of these are very desirable.
Further,
UA-defined properties have their syntax determined
by the version of the UA the user is viewing the page with;
this is out of the page author's control,
which is the entire reason for CSS's error-recovery behavior
and the practice of writing multiple declarations for varying levels of support.
A custom property, on the other hand,
has its syntax controlled by the page author,
according to whatever stylesheet or script they've included in the page;
there's no unpredictability to be managed.
Throwing away syntax-violating custom properties
would thus only be, at best, a convenience for the page author,
not a necessity like for UA-defined properties.
</details>
[=Specified Value=]-Time Behavior {#specified-value}
----------------------------------------------------
Just like unregistered [=custom properties=],
all [=registered custom properties=], regardless of registered syntax,
accept the [=CSS-wide keywords=],
such as ''inherit'' or ''revert''.
Their behavior is defined in [[css-cascade-4#defaulting-keywords]].
[=Computed Value=]-Time Behavior {#calculation-of-computed-values}
------------------------------------------------------------------
The [=computed value=] of a [=registered custom property=]
is determined by the syntax of its [=registration=].
If the [=registration’s=] syntax is the [=universal syntax definition=],
the [=computed value=] is the same as for unregistered [=custom properties=]
(either the specified value with variables substituted,
or the [=guaranteed-invalid value=]).
Otherwise, attempt to [=CSS/parse=] the property's value
according to its registered syntax.
If this fails,
the declaration is [=invalid at computed-value time=]
and the [=computed value=] is determined accordingly.
If it succeeds,
the [=computed value=] depends on the specifics of the syntax:
For <code>"<length>"</code>,
<code>"<length-percentage>"</code>,
<code>"<angle>"</code>,
<code>"<time>"</code>,
<code>"<resolution>"</code>,
<code>"<integer>"</code>,
<code>"<number>"</code>,
and <code>"<percentage>"</code> values:
* If the specified value is a [=dimension=] literal
(such as ''50em'' or ''.2s''),
the computed value is the same value,
but with the unit converted to the corresponding [=canonical unit=]
for the type of value.
* If the specified value is any other numeric literal
(such as ''5'' or ''20%''),
the computed value is as specified.
(In particular, percentages are never resolved against anything.)
* If the specified value is a function that evaluates to one of those types
(such as a [=math function=]),
the computed value is defined by that function.
For <code>"<color>"</code> values,
the value is computed by [=resolving color values=].
For <code>"<custom-ident>"</code>, ident, or <code>"*"</code> values,
the computed value is as specified.
For <code>"<url>"</code> values,
the computed value is one of the following:
* if the URL is a relative URL,
the computed value is the resolved absolute URL as described in [[!css3-values]].
* otherwise, the computed value is as specified.
<details class=note>
<summary>URL behavior examples</summary>
<div class='example'>
Because URLs resolve against the base URL of the stylesheet they appear in, we can
end up with multiple relative URLs that resolve against different base URLs, even though
they appear in the same property.
For example, suppose '--url-foo' and '--url-bar' are registered
custom properties with ''<url>'' syntax, and that we have a stylesheet at
<code>/style/foo/foo.css</code>:
<pre class='lang-css'>
div {
--url-foo: url("foo.png");
}
</pre>
and another stylesheet at <code>/style/bar/bar.css</code>
<pre class='lang-css'>
div {
--url-bar: url("bar.png");
}
</pre>
and finally a document at <code>/index.html</code>:
<pre class='lang-html'>
<link href="/style/foo/foo.css" rel="stylesheet" type="text/css">
<link href="/style/bar/bar.css" rel="stylesheet" type="text/css">
<div style="background-image: var(--url-foo), var(---url-bar);">
</div>
</pre>
Here, the ''var(--url-foo)'' reference would produce a URL that resolves against
<code>/style/foo</code>, and the ''var(--url-bar)'' reference would produce a URL that resolves
against <code>/style/bar</code>.
On the other hand,
if both '--url-foo' and '--url-bar' were <em>un</em>registered,
they would substitute their literal values
(relative URLs)
into the <code>/index.html</code> stylesheet,
which would then resolve the URLs against <code>/index.html</code> instead.
</div>
</details>
For <code>"<image>"</code> values,
the computed value is the [=computed <image>=].
For <code>"<transform-function>"</code> and <code>"<transform-list>"</code> values,
the computed value is as specified but with all lengths resolved to their computed values.
For values with [[#multipliers|multipliers]],
the computed value is a list of the computed values of the base type.
For syntaxes specified with [[#combinator|the | combinator]],
the computed value is given by applying the computed-value rules
for the first clause that matches the value.
Animation Behavior {#animation-behavior-of-custom-properties}
-------------------------------------------------------------
Note: As defined by [[css3-animations]] and [[css3-transitions]], it is possible to
specify animations and transitions that reference custom properties.
When referenced by animations and transitions,
custom property values [=interpolate=] [=by computed value=],
in accordance with the type that they parsed as.
Note: This implies that a list of values,
such as `<color>+` or `<color>#`,
will interpolate as a simple list,
matching up each component index-by-index,
and failing if the number of components doesn't match.
As an exception to the above rule,
a value that parsed as a `<transform-list>`,
a `<transform-function>`,
or a `<transform-function>+`
instead interpolates as per the 'transform' property.
Note: If,
for whatever reason,
a custom property is defined with a syntax of `<transform-function>#`,
this will thus first interpolate as a simple list,
and then each list item will interpolate as a 'transform' value.
Note: Registering (or changing the registration) of a custom property
can change its computed value,
which can start or interrupt a CSS transition.
Conditional Rules {#conditional-rules}
--------------------------------------
As stated in [[#parsing-custom-properties]],
both unregistered and [=registered=] [=custom properties=]
accept (almost) all possible values at parse-time.
[=Registered=] [=custom properties=] only apply their syntax at [=computed value=] time.
So, all [=custom properties=],
regardless of whether they're [=registered=] or unregistered,
will test as "true" in an ''@supports'' rule,
so long as you don't violate the (very liberal) generic syntax for [=custom properties=].
<div class=example>
For example,
even if a custom property is registered
with <code highlight=css>syntax: "<color>";</code>,
a rule like `@supports (--foo: 1em) {...}`
will still evaluate as true and apply those styles,
because the declaration <em>does</em> successfully parse as a valid property.
</div>
Substitution via ''var()'' {#substitution}
------------------------------------------
Like unregistered custom properties,
the value of a registered custom property can be substituted into another value with the ''var()'' function.
However, registered custom properties substitute as their [[#calculation-of-computed-values|computed value]],
rather than the original token sequence used to produce that value.
Any ''var()'' function that references a registered custom property
must be replaced with an <dfn export>equivalent token sequence</dfn>,
which is equal to the token sequence that would have been produced
by [=serialize a CSS value|serializing=] the computed value,
and [[css-syntax-3#tokenization|tokenizing]] the resulting string.
<div class='example'>
Suppose that '--x' is registered with ''<length>'' syntax,
and that '--y'is an unregistered custom property.
<pre class='lang-css'>
div {
font-size: 10px;
--x: 8em;
--y: var(--x);
}
</pre>
Because the computed value of '--x' (when serialized) is "80px",
the computed value of '--y' is
a <<dimension-token>> with a value of "80" and unit "px".
</div>
### Fallbacks In ''var()'' References ### {#fallbacks-in-var-references}
References to registered custom properties using the ''var()'' function may
provide a fallback. However, the fallback value must match the
<a>syntax definition</a> of the custom property being referenced, otherwise the
declaration is <a spec=css-variables>invalid at computed-value time</a>.
Note: This applies regardless of whether or not the fallback is being used.
### Dependency Cycles via Relative Units ### {#dependency-cycles}
[=Registered custom properties=] follow the same rules for dependency cycle resolution
as unregistered [=custom properties=],
with the following additional constraints:
For any registered custom property
with a <<length>> or <<length-percentage>> syntax component:
* If the property contains any of the following units:
''em'', ''ex'', ''cap'', ''ch'', ''ic'', ''lh'';
then add an edge between the property
and the ''font-size'' of the current element.
* If the property contains the ''lh'' unit,
add an edge between the property
and the ''line-height'' of the current element.
* If the property contains any of the following units: ''rem'', ''rlh'';
then add an edge between the property
and the 'font-size'' of the root element.
* If the property contains the ''rlh'' unit,
add an edge between the property
and the 'line-height'' of the root element.
<div class='example'>
For example, given this registration:
<pre class='lang-javascript'>
CSS.registerProperty({
name: "--my-font-size",
syntax: "<length>",
initialValue: "0px",
inherits: false
});
</pre>
the following will produce a dependency cycle:
<pre class='lang-css'>
div {
--my-font-size: 10em;
font-size: var(--my-font-size);
}
</pre>
and ''font-size'' will behave as if the value ''unset'' was specified.
</div>
Shadow DOM {#shadow-dom}
------------------------
Unlike many concepts in CSS
(see [[css-scoping-1#shadow-names]]),
property registrations are <strong>not</strong> scoped to a tree scope.
All registrations,
whether they appear in the outermost document
or within a shadow tree,
interact in a single global registration map for the {{Document}}.
<details class=note>
<summary>Why can't registrations be scoped?</summary>
There are clear use-cases for property registrations to be scoped--
a component using Shadow DOM
and registering some custom properties
for its own internal use
probably doesn't intend for the outer page
to see the registration,
since the outer page doesn't even know the component is using that property.
However, there are also reasons to not scope the registration--
custom properties are used to pipe data <em>into</em> a component,
and it's useful for the outer page
to be able to set such custom properties
and have them syntax-checked by the registration;
similarly, concepts such as a property's initial value
don't make much sense
unless the property registration exists globally,
so it applies to the property even at the document's root.
But the above just means that registration scope
might be something that should be controllable,
not that it should be forced to be global.
The reason registrations must be global
is because elements can exist in multiple tree scopes
at the same time,
with styles from each tree scope
intermingling and cascading together.
This applies to the [=host element=],
which lives in the outer tree
but is stylable from the shadow tree
by the '':host'' selector,
but also elements inside a shadow DOM
that are targetable from the outer tree
by the ''::part()'' pseudo-element.
If registrations could be scoped to a tree scope,
and a single property was registered
both inside and outside,
it's not clear which registration should be applied
to parse the value.
Even if we tracked which tree a value came from
(something we do for other tree-scoped values)
and applied the corresponding registration,
it's not clear that this would give a reasonable result--
the shadow DOM might expect a property to have a particular value space,
and be surprised when it receives something completely different
due to the outer tree winning the cascade
and applying its own registration.
</details>
When custom properties are exposed
as part of a Shadow DOM-using component's public API,
this global registration behavior works as intended.
If the outer page is using a custom property of the same name
for different purposes,
that is already a conflict that needs to be resolved,
and the registration behavior does not make it worse.
If a custom property is intended for private internal usage for a component, however,
it is recommended that the property
be given a likely-unique name,
to minimize the possibility of a clash with any other context.
This can be done, for example,
by including the project name,
or some short random string of text,
in the name of the property.
<!--
███████ ████████ ████████ ███████ ████████ ████████ ████████ ████████ ██ ██
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
██ ███ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ████
██ ███ ██ ████████ ████████ ██ ██ ████████ ██████ ████████ ██ ██
██ █████ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
███████ ██ ██ ██ ███████ ██ ████████ ██ ██ ██ ██
-->
The <dfn>@property</dfn> Rule {#at-property-rule}
=================================================
The ''@property'' rule represents a [=custom property registration=]
directly in a stylesheet
without having to run any JS.
Valid ''@property'' rules result in a [=registered custom property=],
as if {{registerProperty()}} had been called with equivalent parameters.
The syntax of ''@property'' is:
<pre class="prod def" nohighlight>
@property <<custom-property-name>> {
<<declaration-list>>
}
</pre>
A valid ''@property'' rule represents a [=custom property registration=],
with the property name being the serialization of the <<custom-property-name>>
in the rule's prelude.
''@property'' rules require a '@property/syntax' and '@property/inherits' descriptor;
if either are missing,
the entire rule is invalid and must be ignored.
The '@property/initial-value' descriptor is optional
only if the syntax is the [=universal syntax definition=],
otherwise the descriptor is required;
if it's missing, the entire rule is invalid and must be ignored.
Unknown descriptors are invalid and ignored,
but do not invalidate the ''@property'' rule.
Note: As specified in [[#determining-registration]],
if multiple valid ''@property'' rules are defined for the same <<custom-property-name>>,
the last one in stylesheet order "wins".
A custom property registration from {{registerProperty()|CSS.registerProperty()}}
further wins over any ''@property'' rules
for the same <<custom-property-name>>.
The '@property/syntax' Descriptor {#the-syntax-descriptor}
------------------------------------------------
<pre class='descdef'>
Name: syntax
Value: <<string>>
For: @property
Initial: n/a (see prose)
</pre>
Specifies the syntax of the [=custom property registration=]
represented by the ''@property'' rule,
controlling how the property's value is parsed at [=computed value=] time.
The '@property/syntax' descriptor is required for the ''@property'' rule to be valid;
if it's missing, the ''@property'' rule is invalid.
If the provided string is not a valid [=syntax string=]
(if it returns failure when [=consume a syntax definition=] is called on it),
the descriptor is invalid and must be ignored.
The '@property/inherits' Descriptor {#inherits-descriptor}
------------------------------------------------
<pre class='descdef'>
Name: inherits
Value: true | false
For: @property
Initial: n/a (see prose)
</pre>
Specifies the inherit flag of the [=custom property registration=]
represented by the ''@property'' rule,
controlling whether or not the property inherits by default.
The '@property/inherits' descriptor is required for the ''@property'' rule to be valid;
if it's missing, the ''@property'' rule is invalid.
The '@property/initial-value' Descriptor {#initial-value-descriptor}
----------------------------------------------------------
<pre class='descdef'>
Name: initial-value
Value: <<declaration-value>>?
For: @property
Initial: the [=guaranteed-invalid value=] (but see prose)
</pre>
Specifies the initial value of the [=custom property registration=]
represented by the ''@property'' rule,
controlling the property’s [=initial value=].
If the value of the '@property/syntax' descriptor is the [=universal syntax definition=],
then the '@property/initial-value' descriptor is optional.
If omitted, the [=initial value=] of the property is the [=guaranteed-invalid value=].
Otherwise,
if the value of the '@property/syntax' descriptor is not the [=universal syntax definition=],
the following conditions must be met for the ''@property'' rule to be valid:
* The '@property/initial-value' descriptor must be present.
* The '@property/initial-value' descriptor's value must [=parse=] successfully
according to the grammar specified by the [=syntax definition=].
* The '@property/initial-value' must be [=computationally independent=].
If the above conditions are not met, the ''@property'' rule is invalid.
<!--
██ ██████
██ ██ ██
██ ██
██ ██████
██ ██ ██
██ ██ ██ ██
██████ ██████
-->
Registering Custom Properties in JS {#registering-custom-properties}
====================================================================
To register a custom property via JS,
the {{CSS}} object is extended with a {{registerProperty()}} method:
<pre class='idl'>
dictionary PropertyDefinition {
required DOMString name;
DOMString syntax = "*";
required boolean inherits;
DOMString initialValue;
};
partial namespace CSS {
undefined registerProperty(PropertyDefinition definition);
};
</pre>
Additional, the {{Document}} object gains a new <dfn attribute for=Window>\[[registeredPropertySet]]</dfn> private slot,
which is a set of records that describe registered custom properties.
The {{registerProperty()}} Function {#the-registerproperty-function}
--------------------------------------------------------------------
The <dfn method for=CSS>registerProperty(PropertyDefinition definition)</dfn> method
registers a custom property according to the configuration options provided in
<code>definition</code>.
When it is called,
it executes the <a>register a custom property</a> algorithm,
passing the options in its <code>definition</code> argument
as arguments of the same names.
<div algorithm>
To <dfn>register a custom property</dfn>
with |name| being a string,
and optionally
|syntax| being a string,
|inherits| being a boolean,
and |initialValue| being a string,
execute these steps:
1. Let |property set|
be the value of the
<a>current global object's</a>
<a>associated <code>Document</code></a>'s
{{[[registeredPropertySet]]}} slot.
2. If |name| is not a [=custom property name string=],
<a>throw</a> a {{SyntaxError}}
and exit this algorithm.
If |property set|
already contains an entry with |name| as its property name
(compared codepoint-wise),
<a>throw</a> an {{InvalidModificationError}}
and exit this algorithm.
3. Attempt to [=consume a syntax definition=] from |syntax|.
If it returns failure, <a>throw</a> a {{SyntaxError}}.
Otherwise, let |syntax definition| be the returned <a>syntax definition</a>.
4. If |syntax definition| is the <a>universal syntax definition</a>,
and |initialValue| is not present,
let |parsed initial value| be empty.
This must be treated identically to the "default" initial value of custom properties,
as defined in [[!css-variables]].
Skip to the next step of this algorithm.
Otherwise,
if |syntax definition| is the <a>universal syntax definition</a>,
[=CSS/parse=] |initialValue| as a <<declaration-value>>.
If this fails,
<a>throw</a> a {{SyntaxError}}
and exit this algorithm.
Otherwise,
let |parsed initial value| be the parsed result.
Skip to the next step of this algorithm.
Otherwise, if |initialValue| is not present,
<a>throw</a> a {{SyntaxError}}
and exit this algorithm.
Otherwise,
[=CSS/parse=] {{PropertyDefinition/initialValue}}
according to |syntax definition|.
If this fails,
<a>throw</a> a {{SyntaxError}}
and exit this algorithm.
Otherwise, let |parsed initial value| be the parsed result.
If |parsed initial value| is not <a>computationally independent</a>,
<a>throw</a> a {{SyntaxError}}
and exit this algorithm.
5. Set |inherit flag| to the value of |inherits|.
6. Let |registered property| be a [=struct=]
with a property name of |name|,
a syntax of |syntax definition|,
an initial value of |parsed initial value|,
and an inherit flag of |inherit flag|.
[=set/Append=] |registered property|
to |property set|.
</div>
A property value is <dfn export>computationally independent</dfn>
if it can be converted into a computed value
using only the value of the property on the element,
and "global" information that cannot be changed by CSS.
<div class='example'>
For example, ''5px'' is <a>computationally independent</a>,
as converting it into a computed value doesn't change it at all.
Similarly, ''1in'' is <a>computationally independent</a>,
as converting it into a computed value
relies only on the "global knowledge" that ''1in'' is ''96px'',
which can't be altered or adjusted by anything in CSS.
On the other hand, ''3em'' is not <a>computationally independent</a>,
because it relies on the value of 'font-size' on the element
(or the element's parent).
Neither is a value with a ''var()'' function,
because it relies on the value of a <a>custom property</a>.
</div>
When a custom property is registered with a given type,
the process via which specified values for that property are turned into computed values
is defined fully by the type selected,
as described in [[#calculation-of-computed-values]].
Note: A way to unregister properties may be added in the future.
Registering a custom property must <strong>not</strong> affect the [=cascade=] in any way.
Regardless of what syntax is specified for a registered property,
at parse time it is still parsed as normal for a [=custom property=],
accepting nearly anything.
If the [=specified value=] for a [=registered custom property=]
violates the registered syntax,
however,
the property becomes [=invalid at computed-value time=]
(and thus resets to the registered initial value).
<div class='example'>
By default, all custom property declarations that can be parsed as a sequence of tokens
are valid. Hence, the result of this stylesheet:
<pre class='lang-css'>
.thing {
--my-color: green;
--my-color: url("not-a-color");
color: var(--my-color);
}
</pre>
is to set the 'color' property of elements of class "thing" to ''inherit''.
The second '--my-color' declaration overrides the first at parse time (both are valid),
and the ''var()'' reference in the 'color' property is found to be <a spec=css-variables>invalid at computed-value time</a>
(because ''url("not-a-color")'' is not a color).
At this stage of the CSS pipeline (computation time),
the only available fallback is the initial value of the property,
which in the case of color is ''inherit''.
Although there was a valid usable value (green),
this was removed during parsing because it was superseded by the URL.
If we call:
<pre class='lang-javascript'>
CSS.registerProperty({
name: "--my-color",
syntax: "<color>",
initialValue: "black",
inherits: false
});
</pre>
the parsing doesn't significantly change,
regardless of whether the registration occurs before or after the stylesheet above.
The only difference is that it's the '--my-color' property that becomes [=invalid at computed-value time=] instead
and gets set to its initial value of ''black'';
then 'color' is validly set to ''black'',
rather than being [=invalid at computed-value time=]
and becoming ''inherit''.
</div>
The {{PropertyDefinition}} Dictionary {#the-propertydefinition-dictionary}
--------------------------------------------------------------------------
A <dfn dictionary>PropertyDefinition</dfn> dictionary represents author-specified configuration
options for a custom property. {{PropertyDefinition}} dictionaries contain the
following members:
: <dfn dict-member for=PropertyDefinition>name</dfn>
:: The name of the custom property being defined.
: <dfn dict-member for=PropertyDefinition>syntax</dfn>
:: A string representing how this custom property is parsed.
: <dfn dict-member for=PropertyDefinition>inherits</dfn>
:: True if this custom property should inherit down the DOM tree; False otherwise.
: <dfn dict-member for=PropertyDefinition>initialValue</dfn>
:: The initial value of this custom property.
<!--
██████ ██ ██ ██ ██ ████████ ███ ██ ██
██ ██ ██ ██ ███ ██ ██ ██ ██ ██ ██
██ ████ ████ ██ ██ ██ ██ ██ ██
██████ ██ ██ ██ ██ ██ ██ ██ ███
██ ██ ██ ████ ██ █████████ ██ ██
██ ██ ██ ██ ███ ██ ██ ██ ██ ██
██████ ██ ██ ██ ██ ██ ██ ██ ██
-->
Syntax Strings {#syntax-strings}
================================
A <dfn>syntax string</dfn> describes the value types accepted by a registered
custom property. Syntax strings consists of
[=syntax component names=], that are
optionally [[#multipliers|multiplied]] and [[#combinator|combined]].
A syntax string can be parsed into a <a>syntax definition</a>, which is either:
1. A list of <a>syntax components</a>, each of which accept the value types
specified in [[#supported-names]], or
2. The <a>universal syntax definition</a> ('*'), which accepts any valid token
stream.
Note: Regardless of the syntax specified, all custom properties accept
<a>CSS-wide keywords</a>, and process these values
appropriately.
<div class='example'>
For example, the following are all valid syntax strings.
: <code>"<length>"</code>
:: accepts length values
: <code>"<length> | <percentage>"</code>
:: accepts lengths, percentages, percentage calc expressions, and length calc
expressions, but not calc expressions containing a combination of length
and percentage values.
: <code>"<length-percentage>"</code>
:: accepts all values that <code>"<length> | <percentage>"</code> would
accept, as well as calc expressions containing a combination of both length
and percentage values.
: <code>"big | bigger | BIGGER"</code>
:: accepts the ident <code>big</code>, or the ident <code>bigger</code>, or
the ident <code>BIGGER</code>.
: <code>"<length>+"</code>
:: accepts a space-separated list of length values.
: "*"
:: accepts any valid token stream
</div>
Note: The internal grammar of syntax strings is a subset of
[[css-values-3#value-defs|the CSS Value Definition Syntax]]. Future levels of this specification are expected
to expand the complexity of the allowed grammar, allowing custom properties
that more closely resemble the full breadth of what CSS properties allow.
The remainder of this chapter describes the internal grammar of the syntax
strings.
Supported Names {#supported-names}
----------------------------------
This section defines the <dfn for=CSS lt="supported syntax component name">supported syntax component names</dfn>, and the
corresponding types accepted by the resulting <a>syntax component</a>.
: "<length>"
:: Any valid <<length>> value
: "<number>"
:: <<number>> values
: "<percentage>"
:: Any valid <<percentage>> value
: "<length-percentage>"
:: Any valid <<length>> or <<percentage>> value, any valid <<calc()>>
expression combining <<length>> and <<percentage>> components.
: "<color>"
:: Any valid <<color>> value
: "<image>"
:: Any valid <<image>> value
: "<url>"
:: Any valid <<url>> value
: "<integer>"
:: Any valid <<integer>> value
: "<angle>"
:: Any valid <<angle>> value
: "<time>"
:: Any valid <<time>> value
: "<resolution>"
:: Any valid <<resolution>> value
: "<transform-function>"
:: Any valid <<transform-function>> value
: "<custom-ident>"
:: Any valid <<custom-ident>> value
: Any sequence which [[css-syntax-3#would-start-an-identifier|starts an identifier]],
[[css-syntax-3#consume-name|can be consumed as a name]], and matches the <<custom-ident>> production
:: That identifier
Note: <<custom-ident>>s are compared codepoint-wise with each other;
this is different than the normal behavior of UA-defined CSS
which limits itself to ASCII
and is <a>ASCII case-insensitive</a>.
So, specifying an ident like <code>Red</code>
means that the precise value ''Red'' is accepted;
''red'', ''RED'', and any other casing variants are not matched by this.
It is recommended that idents be restricted to ASCII and written in lower-case,
to match CSS conventions.
: "<transform-list>"
:: A list of valid <<transform-function>> values. Note that
<code>"<transform-list>"</code> is a <a>pre-multiplied data type name</a>
equivalent to <code>"<transform-function>+"</code>
Note: A syntax string of <code>"*"</code> will produce the
<a>universal syntax definition</a>, which is not a <a>syntax component</a>.
Therefore, <code>"*"</code> may not be [[#multipliers|multiplied]] or
[[#combinator|combined]] with anything else.
The '+' and '#' Multipliers {#multipliers}
------------------------------------------
Any <a>syntax component name</a> except
<a>pre-multiplied data type names</a> may be immediately followed by a multiplier:
: U+002B PLUS SIGN (+)
:: Indicates a space-separated list.
: U+0023 NUMBER SIGN (#)
:: Indicates a comma-separated list.
<div class='example'>