Skip to content

Commit cd9e5fb

Browse files
bfgeekbfgeek
committed
[css-layout-api] Rework of registerLayout, document/non-document definitions.
1 parent 71413c4 commit cd9e5fb

File tree

2 files changed

+140
-63
lines changed

2 files changed

+140
-63
lines changed

‎css-layout-api/Overview.bs‎

Lines changed: 139 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -37,16 +37,18 @@ spec:css-display-3; type:dfn; text:box
3737
spec:css-display-3; type:value; for:display; text:none
3838
spec:css-display-3; type:value; for:<display-inside>; text:grid
3939
spec:dom; type:dfn; for:/; text:element
40+
spec:infra; type:dfn; text:list
4041
</pre>
4142

4243
<pre class="anchors">
4344
urlPrefix: https://heycam.github.io/webidl/; type: dfn;
44-
text: NotSupportedError
45+
text: InvalidModificationError
4546
urlPrefix: #dfn-;
46-
text: callback this value
47-
text: exception
48-
text: throw
4947
url: throw; text: thrown
48+
urlPrefix: #idl-;
49+
text: boolean
50+
text: DOMException
51+
url: es-type-mapping; text: converting
5052
url: es-invoking-callback-functions; text: Invoke
5153
urlPrefix: https://tc39.github.io/ecma262/#sec-; type: dfn;
5254
text: constructor
@@ -785,6 +787,40 @@ Note: This only describes layout invalidation as it relates to the CSS Layout AP
785787
<a>boxes</a> conceptually have a <a>layout valid flag</a> and these changes are propagated
786788
through the <a>box tree</a>.
787789

790+
Concepts {#concepts}
791+
--------------------
792+
793+
A <dfn>layout definition</dfn> is a <a>struct</a> which describes the information needed by the
794+
{{LayoutWorkletGlobalScope}} about hte author defined layout (which can be referenced by the
795+
<<layout()>> function). It consists of:
796+
797+
- <dfn for="layout definition">class constructor</dfn> which is the class <a>constructor</a>.
798+
799+
- <dfn for="layout definition">layout generator function</dfn> which is the layout <a>generator
800+
function</a> callback.
801+
802+
- <dfn for="layout definition">constructor valid flag</dfn>.
803+
804+
- <dfn for="layout definition">input properties</dfn> which is a <a>list</a> of
805+
<code>DOMStrings</code>
806+
807+
- <dfn for="layout definition">child input properties</dfn> which is a <a>list</a> of
808+
<code>DOMStrings</code>.
809+
810+
- <dfn for="layout definition">child display</dfn> a {{ChildDisplayType}}.
811+
812+
A <dfn>document layout definition</dfn> is a <a>struct</a> which describes the information needed by
813+
the <a>document</a> about the author defined layout (which can be referenced by the <<layout()>>
814+
function). It consists of:
815+
816+
- <dfn for="document layout definition">input properties</dfn> which is a <a>list</a> of
817+
<code>DOMStrings</code>
818+
819+
- <dfn for="document layout definition">child input properties</dfn> which is a <a>list</a> of
820+
<code>DOMStrings</code>.
821+
822+
- <dfn for="document layout definition">child display</dfn> a {{ChildDisplayType}}.
823+
788824
Layout Worklet {#layout-worklet}
789825
--------------------------------
790826

@@ -811,101 +847,143 @@ interface LayoutWorkletGlobalScope : WorkletGlobalScope {
811847
Registering A Layout {#registering-layout}
812848
------------------------------------------
813849

814-
A <dfn>layout definition</dfn> describes an author defined layout which can be referenced by the
815-
<<layout()>> or <<inline-layout()>> functions. It consists of:
816-
817-
- A <dfn>layout name</dfn>.
850+
<pre class='idl'>
851+
[Exposed=LayoutWorklet]
852+
enum ChildDisplayType {
853+
"block",
854+
"normal",
855+
};
856+
</pre>
818857

819-
- A <dfn>layout class constructor</dfn> which is the class <a>constructor</a>.
858+
Issue: "normal" is a bad name?
820859

821-
- A <dfn>layout generator function</dfn> which is the layout <a>generator function</a> callback.
860+
The <a>document</a> has a <a>map</a> of <dfn>document layout definitions</dfn>. Initially this map
861+
is empty; it is populated when {{registerLayout(name, layoutCtor)}} is called.
822862

823-
- A <dfn>layout class constructor valid flag</dfn>.
863+
The {{LayoutWorkletGlobalScope}} has a <a>map</a> of <dfn>layout definitions</dfn>. Initially this
864+
map is empty; it is populated when {{registerLayout(name, layoutCtor)}} is called.
824865

825-
The {{LayoutWorkletGlobalScope}} has a map of <dfn>layout name to layout definition map</dfn>. Initially
866+
The {{LayoutWorkletGlobalScope}} has a <a>map</a> of <dfn>layout class instances</dfn>. Initially
826867
this map is empty; it is populated when {{registerLayout(name, layoutCtor)}} is called.
827868

828869
When the <dfn method for=LayoutWorkletGlobalScope>registerLayout(|name|, |layoutCtor|)</dfn> method
829870
is called, the user agent <em>must</em> run the following steps:
830-
1. If the |name| exists as a key in the <a>layout name to layout definition map</a>,
831-
<a>throw</a> a <a>NotSupportedError</a> and abort all these steps.
871+
1. If the |name| is an empty string, <a>throw</a> a <a>TypeError</a> and abort all these steps.
832872

833-
2. If the |name| is an empty string, <a>throw</a> a <a>TypeError</a> and abort all these steps.
873+
2. Let |layoutDefinitionMap| be {{LayoutWorkletGlobalScope}}'s <a>layout definitions</a> map.
834874

835-
3. Let |inputProperties| be the result of <a>Get</a>(|layoutCtor|,
836-
<code>"inputProperties"</code>).
875+
3. If |layoutDefinitionMap|[|name|] <a for=map>exists</a> <a>throw</a> a
876+
"<a>InvalidModificationError</a>" <a>DOMException</a> and abort all these steps.
837877

838-
4. If |inputProperties| is not undefined, and the result of <a>IsArray</a>(|inputProperties|) is
839-
false, <a>throw</a> a <a>TypeError</a> and abort all these steps.
878+
4. Let |inputProperties| be an empty <code>sequence&lt;DOMString></code>.
840879

841-
If |inputProperties| is undefined, let |inputProperties| be a new empty array.
880+
5. Let |inputPropertiesIterable| be the result of <a>Get</a>(|layoutCtor|, "inputProperties").
842881

843-
5. For each |item| in |inputProperties| perform the following substeps:
882+
6. If |inputPropertiesIterable| is not undefined, then set |inputProperties| to the result of
883+
<a>converting</a> |inputPropertiesIterable| to a <code>sequence&lt;DOMString></code>. If an
884+
exception is <a>thrown</a>, rethrow the exception and abort all these steps.
844885

845-
1. If the result of <a>Type</a>(|item|) is not String, <a>throw</a> a <a>TypeError</a> and
846-
abort all these steps.
886+
Note: The list of CSS properties provided by the input properties getter can either be
887+
custom or native CSS properties.
847888

848-
6. Let |childInputProperties| be the result of <a>Get</a>(|layoutCtor|,
849-
<code>"childInputProperties"</code>).
889+
Note: The list of CSS properties may contain shorthands.
850890

851-
7. If |childInputProperties| is not undefined, and the result of
852-
<a>IsArray</a>(|childInputProperties|) is false, <a>throw</a> a <a>TypeError</a> and abort
853-
all these steps.
891+
Note: In order for a layout class to be forwards compatible, the list of CSS properties can
892+
also contains currently invalid properties for the user agent. For example
893+
<code>margin-bikeshed-property</code>.
854894

855-
If |childInputProperties| is undefined, let |childInputProperties| be a new empty array.
895+
7. Let |childInputProperties| be an empty <code>sequence&lt;DOMString></code>.
856896

857-
8. For each |item| in |childInputProperties| perform the following substeps:
897+
8. Let |childInputPropertiesIterable| be the result of <a>Get</a>(|layoutCtor|,
898+
"childInputProperties").
858899

859-
1. If the result of <a>Type</a>(|item|) is not String, <a>throw</a> a <a>TypeError</a> and
860-
abort these steps.
900+
9. If |childInputPropertiesIterable| is not undefined, then set |childInputProperties| to the
901+
result of <a>converting</a> |childInputPropertiesIterable| to a
902+
<code>sequence&lt;DOMString></code>. If an exception is <a>thrown</a>, rethrow the exception
903+
and abort all these steps.
861904

862-
Note: The list of CSS properties provided by "inputProperties" or "childInputProperties" can
863-
either by custom or native CSS properties.
905+
10. Let |childDisplay| be a {{ChildDisplayType}} set to <code>"block"</code>.
864906

865-
Note: The list of CSS properties may contain shorthands.
907+
11. Let |childDisplayValue| be the result of <a>Get</a>(|layoutCtor|, "childDisplay").
866908

867-
Note: In order for a layout class to be forwards compatible, the list of CSS properties can also
868-
contain currently invalid properties for the user agent. For example
869-
<code>margin-bikeshed-property</code>.
909+
12. If |childDisplayValue| if not undefined, then then |childDisplay| to the result of
910+
<a>converting</a> |childDisplayValue| to a {{ChildDisplayType}}. If an exception is
911+
<a>thrown</a>, rethrow the exception and abort all these steps.
870912

871-
9. Let |prototype| be the result of <a>Get</a>(|layoutCtor|, <code>"prototype"</code>).
913+
13. If the result of <a>IsConstructor</a>(|layoutCtor|) is false, <a>throw</a> a
914+
<a>TypeError</a> and abort all these steps.
872915

873-
10. If the result of <a>Type</a>(|prototype|) is not Object, <a>throw</a> a <a>TypeError</a> and
916+
14. Let |prototype| be the result of <a>Get</a>(|layoutCtor|, "prototype").
917+
918+
15. If the result of <a>Type</a>(|prototype|) is not Object, <a>throw</a> a <a>TypeError</a> and
874919
abort all these steps.
875920

876-
11. Let |layout| be the result of <a>Get</a>(|prototype|, <code>"layout"</code>).
921+
16. Let |layout| be the result of <a>Get</a>(|prototype|, <code>"layout"</code>).
877922

878-
12. If the result of <a>IsCallable</a>(|layout|) is false, <a>throw</a> a <a>TypeError</a> and
923+
17. If the result of <a>IsCallable</a>(|layout|) is false, <a>throw</a> a <a>TypeError</a> and
879924
abort all these steps.
880925

881-
13. If |layout|'s <code>\[[FunctionKind]]</code> internal slot is not <code>"generator"</code>,
926+
18. If |layout|'s <code>\[[FunctionKind]]</code> internal slot is not <code>"generator"</code>,
882927
<a>throw</a> a <a>TypeError</a> and abort all these steps.
883928

884-
14. Let |definition| be a new <a>layout definition</a> with:
885-
886-
- <a>layout name</a> being |name|.
929+
19. Let |definition| be a new <a>layout definition</a> with:
887930

888-
- <a>layout class constructor</a> being |layoutCtor|.
931+
- <a>class constructor</a> being |layoutCtor|.
889932

890933
- <a>layout generator function</a> being |layout|.
891934

892-
- <a>layout class constructor valid flag</a> being true
935+
- <a>constructor valid flag</a> being <b>true</b>.
936+
937+
- <a for="layout definition">input properties</a> being |inputProperties|.
938+
939+
- <a for="layout definition">child input properties</a> being |childInputProperties|.
940+
941+
- <a for="layout definition">child display</a> being |childDisplay|.
942+
943+
20. <a for=map>Set</a> |layoutDefinitionMap|[|name|] to |definition|.
944+
945+
21. <a>Queue a task</a> to run the following steps:
946+
947+
1. Let |documentLayoutDefinitionMap| be the associated <a>document's</a> <a>document layout
948+
definitions</a> <a>map</a>.
949+
950+
2. Let |documentDefinition| be a new <a>document layout definition</a> with:
893951

894-
15. Add the key-value pair (|name| - |inputProperties|) to the <a>layout name to input
895-
properties map</a> of the associated <a>document</a>.
952+
- <a for="document layout definition">input properties</a> being |inputProperties|.
896953

897-
16. Add the key-value pair (|name| - |childInputProperties|) to the <a>layout name to child
898-
input properties map</a> of the associated <a>document</a>.
954+
- <a for="document layout definition">child input properties</a> being
955+
|childInputProperties|.
899956

900-
17. Add the key-value pair (|name| - |definition|) to the <a>layout name to layout definition
901-
map</a> of the associated <a>document</a>.
957+
- <a for="document layout definition">child display</a> being |childDisplay|.
958+
959+
3. If |documentLayoutDefinitionMap|[|name|] <a for=map>exists</a>, run the following steps:
960+
961+
1. Let |existingDocumentDefinition| be the result of <a for=map>get</a>
962+
|documentLayoutDefinitionMap|[|name|].
963+
964+
2. If |existingDocumentDefinition| is <code>"invalid"</code>, abort all these steps.
965+
966+
3. If |existingDocumentDefinition| and |documentDefinition| are not equivalent, (that is
967+
<a for="document layout definition">input properties</a>, <a for="document layout
968+
definition">child input properties</a>, and <a for="document layout
969+
definition">child display</a> are different), then:
970+
971+
<a for=map>Set</a> |documentLayoutDefinitionMap|[|name|] to <code>"invalid"</code>.
972+
973+
Log an error to the debugging console stating that the same class was registered
974+
with different <code>inputProperties</code>, <code>childInputProperties</code>, or
975+
<code>childDisplay</code>.
976+
977+
4. Otherwise, <a for=map>set</a> |documentLayoutDefinitionMap|[|name|] to
978+
|documentDefinition|.
902979

903980
<div class='note'>
904981
Note: The shape of the class should be:
905982
<pre class='lang-javascript'>
906983
class MyLayout {
907984
static get inputProperties() { return ['--foo']; }
908985
static get childrenInputProperties() { return ['--bar']; }
986+
static get childDisplay() { return 'normal'; }
909987

910988
*layout(constraintSpace, children, styleMap, breakToken) {
911989
// Layout code goes here.
@@ -1042,7 +1120,7 @@ context</a> for a given |box|, |constraintSpace|, |children| and an optional |br
10421120
randomly assign between them.
10431121

10441122
5. Let |definition| be the result of looking up |name| on the |workletGlobalScope|'s <a>layout
1045-
name to layout definition map</a>.
1123+
definitions</a> <a>map</a>.
10461124

10471125
If |definition| does not exist, let the fragment output be an <a>invalid fragment</a> and
10481126
abort all these steps.
@@ -1053,16 +1131,16 @@ context</a> for a given |box|, |constraintSpace|, |children| and an optional |br
10531131
6. Let |layoutInstance| be the result of looking up the <a>layout instance</a> on the |box|. If
10541132
|layoutInstance| is null run the following substeps.
10551133

1056-
1. If the <a>layout class constructor valid flag</a> on |definition| is false, let the
1134+
1. If the <a>constructor valid flag</a> on |definition| is false, let the
10571135
fragment output be an <a>invalid fragment</a> and abort all these steps.
10581136

1059-
2. Let |layoutCtor| be the <a>layout class constructor</a> on |definition|.
1137+
2. Let |layoutCtor| be the <a>class constructor</a> on |definition|.
10601138

10611139
3. Let |layoutInstance| be the result of <a>Construct</a>(|layoutCtor|).
10621140

1063-
If <a>Construct</a> throws an exception, set the |definition|'s <a>layout class
1064-
constructor valid flag</a> to false, let the fragment output be an <a>invalid
1065-
fragment</a> and abort all these steps.
1141+
If <a>Construct</a> throws an exception, set the |definition|'s <a>constructor valid
1142+
flag</a> to false, let the fragment output be an <a>invalid fragment</a> and abort all
1143+
these steps.
10661144

10671145
4. Set <a>layout instance</a> on |box| to |layoutInstance|.
10681146

@@ -1073,7 +1151,7 @@ context</a> for a given |box|, |constraintSpace|, |children| and an optional |br
10731151
function</a>.
10741152

10751153
8. Let |inputProperties| be the result of looking up |name| on the associated <a>document</a>'s
1076-
<a>layout name to input properties map</a>.
1154+
<a>document layout definitions</a> <a>map</a>.
10771155

10781156
9. Let |styleMap| be a new {{StylePropertyMapReadOnly}} populated with <em>only</em> the
10791157
<a>computed value</a>'s for properties listed in |inputProperties|.
@@ -1167,4 +1245,3 @@ context</a> for a given |box|, |constraintSpace|, |children| and an optional |br
11671245
- The {{FragmentResultOptions/blockSize}} of the fragment.
11681246

11691247
15. Return |fragment|.
1170-

‎css-paint-api/Overview.bs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -209,7 +209,7 @@ called, the user agent <em>must</em> run the following steps:
209209
3. If |paintDefinitionMap|[|name|] <a for=map>exists</a> <a>throw</a> a
210210
"<a>InvalidModificationError</a>" <a>DOMException</a> and abort all these steps.
211211

212-
4. Let |inputProperties| be an empty <code>sequence&lt;DOMString></code>
212+
4. Let |inputProperties| be an empty <code>sequence&lt;DOMString></code>.
213213

214214
5. Let |inputPropertiesIterable| be the result of <a>Get</a>(|paintCtor|, "inputProperties").
215215

0 commit comments

Comments
 (0)