[css-properties-values] More strictly define what a property registration is, in Infra terms, and refer to that in @Property. Also define how JS and CSS registrations resolve collisions.

Author: tabatkins

css-properties-values-api/Overview.bs

@@ -83,14 +83,13 @@ allow custom properties to directly impact paint and layout behaviours respectiv
 Registered Custom Properties {#behavior-of-custom-properties}
 =============================================================
 
-A [=custom property=] can,
-with the methods defined in this specification,
-become a <dfn>registered custom property</dfn>,
+A [=custom property=] can become a <dfn>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,
-making the [=custom property=]
-act more like a UA-defined property.
+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
@@ -103,6 +102,30 @@ in the document's {{[[registeredPropertySet]]}} slot
 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=].
+
 Parsing Custom Properties {#parsing-custom-properties}
 ------------------------------------------------------
 
@@ -164,7 +187,7 @@ Calculation of Computed Values {#calculation-of-computed-values}
 ----------------------------------------------------------------
 
 The [=computed value=] of a [=registered custom property=]
-is determined by the syntax it's registered with.
+is determined by the syntax of its [=registration=].
 
 Note: All properties, regardless of registered syntax,
 accept the [=CSS-wide keywords=],
@@ -365,18 +388,12 @@ and [[css-syntax-3#tokenization|tokenizing]] the resulting string.
 The <dfn>@property</dfn> Rule {#at-property-rule}
 =================================================
 
-The ''@property'' rule provides an alternative way to register a custom property,
+The ''@property'' rule represents a [=custom property registration=]
 directly in a stylesheet
 without having to run any JS.
-Valid ''@property'' rules result in a [=register a custom property|registered custom property=],
+Valid ''@property'' rules result in a [=registered custom property=],
 as if {{registerProperty()}} had been called with equivalent parameters.
 
-The semantics of registered properties are the same
-regardless of the mechanism used to perform the registration.
-This means that, once registered,
-it does not matter whether the registration originated from {{registerProperty()}} or ''@property'':
-the property has the same behavior either way.
-
 The syntax of ''@property'' is:
 
 	<pre class="prod def" nohighlight>
@@ -385,6 +402,10 @@ The syntax of ''@property'' is:
 	}
 	</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 'syntax' and 'inherits' descriptor;
 if either are missing,
 the entire rule is invalid and must be ignored.
@@ -396,7 +417,8 @@ 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.
 
-If multiple valid ''@property'' rules are defined for the same <<custom-property-name>>,
+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
@@ -405,7 +427,7 @@ for the same <<custom-property-name>>.
 A ''@property'' is invalid if it occurs in a stylesheet inside of a [=shadow tree=],
 and must be ignored.
 
-Note: This might change in the future,
+Issue(939): This will likely change in the future,
 as the behavior of concept-defining at-rules in shadow trees
 becomes more consistently defined.
 
@@ -419,14 +441,15 @@ The 'syntax' Descriptor {#the-syntax-descriptor}
 	Initial: n/a (see prose)
 	</pre>
 
-Specifies the syntax of the custom property,
-in the form defined by [[#syntax-strings]].
-This descriptor is equivalent to the {{PropertyDescriptor/syntax|syntax}} member of {{PropertyDescriptor}}.
+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 'syntax' descriptor is required for the ''@property'' rule to be valid;
 if it's missing, the ''@property'' rule is invalid.
 
-If the provided string does not successfully [=consume a syntax definition|parse as a syntax definition=],
+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.
 
 
@@ -440,10 +463,11 @@ The 'inherits' Descriptor {#inherits-descriptor}
 	Initial: n/a (see prose)
 	</pre>
 
-Specifies whether or not the custom property inherits.
-This is equivalent to the {{PropertyDescriptor/inherits}} member of {{PropertyDescriptor}}.
+Specifies the inherit flag of the [=custom property registration=]
+represented by the ''@property'' rule,
+controlling whether or not the property inherits by default.
 
-The inherits descriptor is required for the ''@property'' rule to be valid;
+The 'inherits' descriptor is required for the ''@property'' rule to be valid;
 if it's missing, the ''@property'' rule is invalid.
 
 
@@ -457,12 +481,13 @@ The 'initial-value' Descriptor {#initial-value-descriptor}
 	Initial: the [=guaranteed-invalid value=] (but see prose)
 	</pre>
 
-Specifies the [=initial value=] of the custom property.
-This is equivalent to the {{PropertyDescriptor/initialValue}} member of {{PropertyDescriptor}}.
+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 'syntax' descriptor is the [=universal syntax definition=],
 then the 'initial-value' descriptor is optional.
-If omitted, the initial value of the property is the [=guaranteed-invalid value=].
+If omitted, the [=initial value=] of the property is the [=guaranteed-invalid value=].
 
 Otherwise,
 if the value of the 'syntax' descriptor is not the [=universal syntax definition=],