1. Introduction
This section is not normative.
The layout stage of CSS is responsible for generating and positioning fragments from the box tree.
This specification describes an API which allows developers to layout a box in response to computed style and box tree changes.
2. Layout API Containers
A new alternative value is added
to the <display-inside> production: layout(<ident>)
.
- layout()
- This value causes an element to generate a layout API container box.
A layout API container is the box generated by an element with a <display-inside> computed value layout().
A layout API container establishes a new layout API formatting context for its contents. This is the same as establishing a block formatting context, except that the layout provided by the author is used instead of the block layout. For example, floats do not intrude into the layout API container, and the layout API container’s margins do not collapse with the margins of its contents.
All inflow children of a layout API container are called layout API children and are laid out using the auther defined layout.
Layout API containers form a containing block for their contents exactly like block containers do. [CSS21]
Note: In a future level of the specification there may be a way to override the containing block behaviour.
The overflow property applies to layout API containers. This is discussed in §4.3 Overflow.
As the layout is entirely up to the author, properties which are used in other layout modes (e.g. flex, block) may not apply. For example an author may not repect the margin property on children.
2.1. Layout API Container Painting
Layout API Container children paint exactly the same as inline blocks [CSS21], except that
the order in which they are returned from the layout method (via childFragments
) is used in place of raw document order, and z-index values other than auto create a stacking context even if position is static.
2.2. Box Tree Transformations
The layout API children can act in different ways depending on the value of layout options' childDisplay
(set by layoutOptions
on the class).
If the value of layout options' childDisplay
is "block"
the display value of that child is blockified. This is similar to children of flex containers or grid containers.
See [css3-display].
If the value of layout options' childDisplay
is "normal"
, no blockification occurs. Instead
children with a <display-outside> computed value of inline (a root inline box)
will produce a single LayoutFragment
representing each line when layoutNextFragment()
is called.
Note: This allows authors to adjust the available inline size of each line, and position each line separately.
Children of a LayoutChild
which represents root inline box also have some additional
transformations.
-
A block-level box inside a inline-level box is inlinified I.e. its <display-outside> is set to inline.
-
A float inside a inline-level box is not taken out of flow. Instead it must be treated as inflow, and be inlinified.
In both of the above cases the children become atomic inlines.
Note: User agents would not perform any "inline splitting" or fragmenting when they encounter a block-level box.
LayoutChild
with
both "block" and "float" being atomic inlines.
<span id="inline-span"> Text <div id="block"></div> <div id="float"></div> Text </span>
3. Layout API Model and Terminology
This section gives an overview of the Layout API given to authors.
The current layout is the layout algorithm for the box we are currently performing layout for.
The parent layout is the layout algorithm for the box’s direct parent, (the layout algorithm which is requesting the current layout to be performed).
A child layout is the layout algorithm for a LayoutChild
of the current layout.
3.1. Layout Children
[Exposed=LayoutWorklet] interfaceLayoutChild
{ readonly attribute StylePropertyMapReadOnly styleMap; IntrinsicSizesRequest intrinsicSizes(); LayoutFragmentRequest layoutNextFragment(LayoutConstraintsconstraints
, ChildBreakTokenbreakToken
); };
The LayoutChild
has internal slot(s):
-
[[box]]
a CSS box. -
[[styleMap]]
aStylePropertyMapReadOnly
, this is the computed style for the child, it is populated with only the properties listed inchildInputProperties
.
A LayoutChild
represents either a CSS generated box before layout has occured. (The box
or boxes will all have a computed value of display that is not none).
The LayoutChild
does not contain any layout information itself (like inline or block size) but
can be used to generate LayoutFragment
s which do contain layout information.
An author cannot construct a LayoutChild
with this API, this happens at a separate stage of the
rendering engine (post style resolution).
A LayoutChild
could be generated by:
-
An element.
-
A ::before or ::after pseudo-element.
Note: Other pseudo-elements such as ::first-letter or ::first-line do not generate a
LayoutChild
for layout purposes. They are additional styling information for a text node. -
An anonymous box. For example an anonymous box may be inserted as a result of:
-
A text node which has undergone blockification. (Or more generally a root inline box which has undergone blockification).
-
An element with display: table-cell which doesn’t have a parent with display: table.
-
LayoutChild
ren:
<style> #box::before { content: 'hello!'; } </style> <div id="box">A block level box with text.</div> <img src="..." />
LayoutChild
as they share a root inline box:
This is a next node, <span>with some additional styling, that may</span> break over<br>multiple lines.
Multiple non-atomic inlines are placed within the same LayoutChild
to allow rendering
engines to perform text shaping across element boundaries.
LayoutFragment
but is from
three non-atomic inlines:
ع<span style="color: blue">ع</span>ع
An array of LayoutChild
ren is passed into the layout method which represents the children of the
current box which is being laid out.
styleMap
, on getting from a LayoutChild
this, the
user agent must perform the following steps:
-
Return this’
StylePropertyMapReadOnly
contained in the[[styleMap]]
internal slot.
layoutNextFragment(constraints, breakToken)
method is
called on a LayoutChild
this, the user agent must perform the following steps:
-
Let request be a new
LayoutFragmentRequest
with internal slot(s):-
[[layoutChild]]
set to this. -
[[layoutConstraints]]
set to constraints. -
[[breakToken]]
set to breakToken.
-
-
Return request.
intrinsicSizes()
method is called on a LayoutChild
this, the user agent must perform the following steps:
-
Let request be a new
IntrinsicSizesRequest
with internal slot(s):-
[[layoutChild]]
set to this.
-
-
Return request.
Note: Both layoutNextFragment()
and intrinsicSizes()
don’t
synchronously run. See §5.5.1 Request Objects for a full description.
3.1.1. LayoutChildren and the Box Tree
Each box has a [[layoutChildMap]]
internal slot, which is a map of LayoutWorkletGlobalScope
s to LayoutChild
ren.
-
Assert that:
-
box is currently attached to the box tree.
-
box’s containing block is a layout API container.
-
The containing block’s layout() function’s first argument is name.
-
-
Let layoutChildMap be box’s
[[layoutChildMap]]
. -
If layoutChildMap[workletGlobalScope] does not exist, run the following steps:
-
Let definition be the result of get a layout definition given name, and workletGlobalScope.
Assert that get a layout definition succeeded, and definition is not
"invalid"
. -
Let childInputProperties be definition’s child input properties.
-
Let layoutChild be a new
LayoutChild
with internal slot(s):-
[[box]]
set to box. -
[[styleMap]]
set to a newStylePropertyMapReadOnly
populated with only the computed values for properties listed in childInputProperties.
-
-
Set layoutChildMap[workletGlobalScope] to layoutChild.
-
-
Return the result of get layoutChildMap[workletGlobalScope]
When a box is inserted into the box tree the user agent may pre-populate the [[layoutChildMap]]
for all LayoutWorkletGlobalScope
s.
When a box is removed from the box tree the user agent must clear the [[layoutChildMap]]
.
-
Assert that:
-
box is currently attached to the box tree.
-
-
If box’s containing block is not a layout API container, abort all these steps.
-
Let layoutChildMap be box’s
[[layoutChildMap]]
. -
For each layoutChild in layoutChildMap:
-
Let styleMap be layoutChild’s
[[styleMap]]
. -
Update styleMap’s declarations based on the box’s new computed style.
-
When the computed style of a box changes the user agent must run the update a layout child style algorithm.
3.2. Layout Fragments
[Exposed=LayoutWorklet] interfaceLayoutFragment
{ readonly attribute doubleinlineSize
; readonly attribute doubleblockSize
; attribute doubleinlineOffset
; attribute doubleblockOffset
; readonly attribute anydata
; readonly attribute ChildBreakToken?breakToken
; };
The LayoutFragment
has internal slot(s):
-
[[layoutFragmentRequest]]
aLayoutFragmentRequest
, this is the fragment request which generated this fragment. -
[[generator]]
the generator which produced this fragment.
A LayoutFragment
represents a CSS fragment of a LayoutChild
after layout has occurred
on that child. This is produced by the layoutNextFragment()
method.
The LayoutFragment
has inlineSize
and blockSize
attributes, which are set by the respective child’s layout algorithm. They represent the border
box size of the CSS fragment, and are relative to the current layout’s writing
mode.
The inlineSize
and blockSize
attributes cannot be changed. If
the current layout requires a different inlineSize
or blockSize
the author must perform layoutNextFragment()
again with
different arguments in order to get different results.
The author inside the current layout can position a resulting LayoutFragment
by setting its inlineOffset
and blockOffset
attributes. If not set by the
author they default to zero. The inlineOffset
and blockOffset
attributes represent the position of the LayoutFragment
relative to its parent’s border
box, before transform or positioning (e.g. if a fragment is relatively positioned) has
been applied.
registerLayout('block-like', class { *intrinsicSizes(children, edges, styleMap) { const childrenSizes = yield children.map((child) => { return child.intrinsicSizes(); }); const maxContentSize = childrenSizes.reduce((max, childSizes) => { return Math.max(max, childSizes.maxContentSize); }, 0) + edges.all.inline; const minContentSize = childrenSizes.reduce((max, childSizes) => { return Math.max(max, childSizes.minContentSize); }, 0) + edges.all.inline; return {maxContentSize, minContentSize}; } *layout(children, edges, constraints, styleMap) { const availableInlineSize = constraints.fixedInlineSize - edges.all.inline; const availableBlockSize = (constraints.fixedBlockSize || Infinity) - edges.all.block; const childFragments = []; const childConstraints = { availableInlineSize, availableBlockSize }; const childFragments = yield children.map((child) => { return child.layoutNextFragment(childConstraints); }); let blockOffset = edges.all.blockStart; for (let fragment of childFragments) { // Position the fragment in a block like manner, centering it in the // inline direction. fragment.blockOffset = blockOffset; fragment.inlineOffset = Math.max( edges.all.inlineStart, (availableInlineSize - fragment.inlineSize) / 2); blockOffset += fragment.blockSize; } const autoBlockSize = blockOffset + edges.all.blockEnd; return { autoBlockSize, childFragments, }; } });
A layout API container can communicate with other layout API containers by using the data
attribute. This is set by the data
member in the FragmentResultOptions
dictionary.
The LayoutFragment
's breakToken
specifies where the LayoutChild
last
fragmented. If the breakToken
is null the LayoutChild
wont produce any more LayoutFragment
s for that token chain. The breakToken
can be passed to the layoutNextFragment()
function to produce the next LayoutFragment
for a
particular child. The breakToken
cannot be changed.
If the current layout requires a different breakToken
the author must perform layoutNextFragment()
again with different arguments.
-
Let targetRealm be generator’s Realm.
-
Let fragment be a new
LayoutFragment
with:-
The
[[layoutFragmentRequest]]
internal slot being layoutFragmentRequest. -
The
[[generator]]
internal slot being generator. -
inlineSize
being internalFragment’s inline size relative to the current layout’s writing mode. -
blockSize
being internalFragment’s block size relative to the current layout’s writing mode. -
inlineOffset
initially set to 0. -
blockOffset
initially set to 0. -
breakToken
being a newChildBreakToken
representing internalFragment’s internal break token, if any. -
If internalFragment has a clonedData object stored with it, let
data
being the result of StructuredDeserialize(clonedData, targetRealm), otherwise null.
-
-
Return fragment.
3.3. Intrinsic Sizes
[Exposed=LayoutWorklet] interfaceIntrinsicSizes
{ readonly attribute doubleminContentSize
; readonly attribute doublemaxContentSize
; };
The IntrinsicSizes
object has internal slot(s):
-
[[intrinsicSizesRequest]]
aIntrinsicSizesRequest
, this is the intrinsic sizes request which generated these intrinsic sizes.
A IntrinsicSizes
object represents the min-content size and max-content size of a
CSS box. It has minContentSize
and maxContentSize
attributes which represent the border box min/max-content contribution of the LayoutChild
for the current layout. The attributes are relative to the inline direction of the current
layout’s writing mode.
The minContentSize
and maxContentSize
cannot be changed. They
must not change for a LayoutChild
within the current layout pass.
<style> .child-0 { width: 380px; border: solid 10px; } .child-1 { border: solid 5px; } .box { display: layout(intrinsic-sizes-example); font: 25px/1 Ahem; } </style> <div class="box"> <div class="child-0"></div> <div class="child-1">XXX XXXX</div> </div>
registerLayout('intrinsic-sizes-example', class { *intrinsicSizes(children, edges, styleMap) { const childrenSizes = yield children.map((child) => { return child.intrinsicSizes(); }); childrenSizes[0].minContentSize; // 400, (380+10+10) child has a fixed size. childrenSizes[0].maxContentSize; // 400, (380+10+10) child has a fixed size. childrenSizes[1].minContentSize; // 100, size of "XXXX". childrenSizes[1].maxContentSize; // 200, size of "XXX XXXX". } *layout() {} });
-
Let intrinsicSizes be a new
IntrinsicSizes
with:-
The
[[intrinsicSizesRequest]]
internal slot being intrinsicSizesRequest. -
minContentSize
being internalIntrinsicSizes’ border box min-content contribution, relative to the current layout’s writing mode. -
maxContentSize
being internalIntrinsicSizes’s border box max-content contribution, relative to the current layout’s writing mode.
-
-
Return intrinsicSizes.
3.4. Layout Constraints
[Constructor
(optional LayoutConstraintsOptionsoptions
),Exposed=LayoutWorklet] interfaceLayoutConstraints
{ readonly attribute doubleavailableInlineSize
; readonly attribute doubleavailableBlockSize
; readonly attribute double?fixedInlineSize
; readonly attribute double?fixedBlockSize
; readonly attribute doublepercentageInlineSize
; readonly attribute doublepercentageBlockSize
; readonly attribute double?blockFragmentationOffset
; readonly attribute BlockFragmentationTypeblockFragmentationType
; readonly attribute anydata
; }; dictionaryLayoutConstraintsOptions
{ doubleavailableInlineSize
= 0; doubleavailableBlockSize
= 0; doublefixedInlineSize
; doublefixedBlockSize
; doublepercentageInlineSize
; doublepercentageBlockSize
; doubleblockFragmentationOffset
; BlockFragmentationTypeblockFragmentationType
= "none"; anydata
; }; enumBlockFragmentationType
{"none"
,"page"
,"column"
,"region"
};
A LayoutConstraints
object is passed into the layout method which represents the all the
constraints for the current layout to perform layout inside. It is also used to pass
information about the available space into a child layout.
The LayoutConstraints
object has availableInlineSize
and availableBlockSize
attributes. This represents the available space for
a LayoutFragment
which the layout should respect.
Note: Some layouts may need to produce a LayoutFragment
which exceed this size. For example a replaced element. The parent layout should expect this to occur and deal with it
appropriately.
A parent layout may require the current layout to be exactly a particular size. If
the fixedInlineSize
or fixedBlockSize
are specified the current layout should produce a LayoutFragment
with a the specified size in the
appropriate direction.
registerLayout('flex-distribution-like', class { *intrinsicSizes(children, edges, styleMap) { const childrenSizes = yield children.map((child) => { return child.intrinsicSizes(); }); const maxContentSize = childrenSizes.reduce((sum, childSizes) => { return sum + childSizes.maxContentSize; }, 0) + edges.all.inline; const minContentSize = childrenSizes.reduce((max, childSizes) => { return sum + childSizes.minContentSize; }, 0) + edges.all.inline; return {maxContentSize, minContentSize}; } *layout(children, edges, constraints, styleMap) { const availableInlineSize = constraints.fixedInlineSize - edges.all.inline; const availableBlockSize = (constraints.fixedInlineSize || Infinity) - edges.all.block; const childConstraints = { availableInlineSize, availableBlockSize }; const unconstrainedChildFragments = yield children.map((child) => { return child.layoutNextFragment(childConstraints); }); const unconstrainedSizes = []; const totalSize = unconstrainedChildFragments.reduce((sum, fragment, i) => { unconstrainedSizes[i] = fragment.inlineSize; return sum + fragment.inlineSize; }, 0); // Distribute spare space between children. const remainingSpace = Math.max(0, inlineSize - totalSize); const extraSpace = remainingSpace / children.length; const childFragments = yield children.map((child, i) => { return child.layoutNextFragment({ fixedInlineSize: unconstrainedSizes[i] + extraSpace, availableBlockSize }); }); // Position the fragments. let inlineOffset = 0; let maxChildBlockSize = 0; for (let fragment of childFragments) { fragment.inlineOffset = inlineOffset; fragment.blockOffset = edges.all.blockStart; inlineOffset += fragment.inlineSize; maxChildBlockSize = Math.max(maxChildBlockSize, fragment.blockSize); } return { autoBlockSize: maxChildBlockSize + edges.all.block, childFragments, }; } });
The LayoutConstraints
object has percentageInlineSize
and percentageBlockSize
attributes. These represent the size that a layout
percentages should be resolved against while performing layout.
The LayoutConstraints
has a blockFragmentationType
attribute. The current layout should produce a LayoutFragment
which fragments at the blockFragmentationOffset
if possible.
The current layout can choose not to fragment a LayoutChild
based on the blockFragmentationType
, for example if the child has a property like break-inside: avoid-page;.
-
If sizingMode is
"block-like"
then:-
Let fixedInlineSize be the result of calculating box’s border-box inline size (relative to box’s writing mode) exactly like block containers do.
-
Let fixedBlockSize be null if box’s block size is auto, otherwise the result of calculating box’s border-box block size exactly like block containers do.
-
Return a new
LayoutConstraints
object with:-
fixedInlineSize
, andavailableInlineSize
set to fixedInlineSize. -
percentageInlineSize
set to internalLayoutConstraints’ percentage resolution size in the inline axis (relative to box’s writing mode). -
fixedBlockSize
set to fixedBlockSize. -
availableBlockSize
set to fixedBlockSize if not null, otherwise internalLayoutConstraints’ available space in the block axis (relative to box’s writing mode). -
percentageBlockSize
set to internalLayoutConstraints’ percentage resolution size in the block axis (relative to box’s writing mode).
-
-
-
If sizingMode is
"manual"
then:-
Return a new
LayoutConstraints
object with:-
fixedInlineSize
/fixedBlockSize
set to internalLayoutConstraints’ fixed inline/block size (relative to box’s writing mode) imposed by the parent layout. Either may be null.Note: See §4.1 Sizing for different scenarios when this can occur.
-
availableInlineSize
/availableBlockSize
set to internalLayoutConstraints’ available space. -
percentageInlineSize
/percentageBlockSize
set to internalLayoutConstraints’ percentage resolution size.
-
-
3.5. Breaking and Fragmentation
[Exposed=LayoutWorklet] interfaceChildBreakToken
{ readonly attribute BreakTypebreakType
; readonly attribute LayoutChildchild
; }; [Exposed=LayoutWorklet] interfaceBreakToken
{ readonly attribute sequence<ChildBreakToken>childBreakTokens
; readonly attribute anydata
; }; dictionaryBreakTokenOptions
{ sequence<ChildBreakToken>childBreakTokens
; anydata
= null; }; enumBreakType
{"none"
,"line"
,"column"
,"page"
,"region"
};
A LayoutChild
can produce multiple LayoutFragment
s. A LayoutChild
may fragment in the
block direction if a blockFragmentationType
is not none. Additionally LayoutChild
which represents inline-level content, may fragment line by line if the layout options' childDisplay
(set by layoutOptions
) is "normal"
.
A subsequent LayoutFragment
is produced by using the previous LayoutFragment
's breakToken
. This tells the child layout to produce a LayoutFragment
starting at the point encoded in the ChildBreakToken
.
This example also demonstrates using the previous breakToken
of a LayoutFragment
to produce the next fragment for the LayoutChild
.
It also demonstrates using the BreakToken
to respect the LayoutConstraints
' blockFragmentationType
, it resumes it layout from the previous BreakToken
.
It returns a FragmentResultOptions
with a breakToken
which is used to
resume the layout.
registerLayout('indent-lines', class { static layoutOptions = {childDisplay: 'normal'}; static inputProperties = ['--indent', '--indent-lines']; *layout(children, edges, constraints, styleMap, breakToken) { // Determine our (inner) available size. const availableInlineSize = constraints.fixedInlineSize - edges.all.inline; const availableBlockSize = (constraints.fixedBlockSize || Infinity) - edges.all.block; // Detrermine the number of lines to indent, and the indent amount. const indent = resolveLength(constraints, styleMap.get('--indent')); let lines = styleMap.get('--indent-lines').value; const childFragments = []; let childBreakToken = null; if (breakToken) { childBreakToken = breakToken.childBreakTokens[0]; // Remove all the children we have already produced fragments for. children.splice(0, children.indexOf(childBreakToken.child)); } let blockOffset = edges.all.blockStart; let child = children.shift(); while (child) { const shouldIndent = lines-- > 0; // Adjust the inline size for the indent. const childAvailableInlineSize = shouldIndent ? availableInlineSize - indent : availableInlineSize; const childConstraints = { availableInlineSize: childAvailableInlineSize, availableBlockSize, percentageInlineSize: availableInlineSize, blockFragmentationType: constraints.blockFragmentationType, }; const fragment = yield child.layoutNextFragment(childConstraints, childBreakToken); childFragments.push(fragment); // Position the fragment. fragment.inlineOffset = shouldIndent ? edges.all.inlineStart + indent : edges.all.inlineStart; fragment.blockOffset = blockOffset; blockOffset += fragment.blockSize; // Check if we have gone over the block fragmentation limit. if (constraints.blockFragmentationType != 'none' && blockOffset > constraints.blockSize) { break; } if (fragment.breakToken) { childBreakToken = fragment.breakToken; } else { // If a fragment doesn’t have a break token, we move onto the // next child. child = children.shift(); childBreakToken = null; } } const autoBlockSize = blockOffset + edges.all.blockEnd; // Return our fragment. const result = { autoBlockSize, childFragments: childFragments, } if (childBreakToken) { result.breakToken = { childBreakTokens: [childBreakToken], }; } return result; } });
3.6. Edges
[Exposed=LayoutWorklet] interfaceLayoutEdgeSizes
{ readonly attribute doubleinlineStart
; readonly attribute doubleinlineEnd
; readonly attribute doubleblockStart
; readonly attribute doubleblockEnd
; // Convenience attributes for the sum in one direction. readonly attribute doubleinline
; readonly attribute doubleblock
; }; [Exposed=LayoutWorklet] interfaceLayoutEdges
{ readonly attribute LayoutEdgeSizesborder
; readonly attribute LayoutEdgeSizesscrollbar
; readonly attribute LayoutEdgeSizespadding
; readonly attribute LayoutEdgeSizesall
; };
A LayoutEdges
object is passed into the layout method. This represents the size of the box
model edges for the current box which is being laid out.
The LayoutEdges
has border
, scrollbar
, and padding
attributes. Each of these represent the width of their respective edge.
The LayoutEdges
has the all
attribute. This is a convenience attribute which
represents the sum of the border
, scrollbar
, padding
edges.
The LayoutEdgeSizes
object represents the width in CSS pixels of an edge in each of the abstract dimensions (inlineStart
, inlineEnd
, blockStart
, blockEnd
).
The inline
, and block
on the LayoutEdgeSizes
object are
convenience attributes which represent the sum in that direction.
LayoutEdges
could contain.
<style> .container { width: 50px; height: 50px; } .box { display: layout(box-edges); padding: 10%; border: solid 2px; overflow-y: scroll; } </style> <div class="container"> <div class="box"></div> </div>
registerLayout('box-edges', class { *layout(children, edges, constraints, styleMap, breakToken) { edges.padding.inlineStart; // 5 (as 10% * 50px = 5px). edges.border.blockEnd; // 2 edges.scrollbar.inlineEnd; // UA-dependent, may be 0 or >0 (e.g. 16). edges.all.block; // 14 (2 + 5 + 5 + 2). } }
4. Interactions with other Modules
This section describes how other CSS modules interact with the CSS Layout API.
4.1. Sizing
User agents must use the LayoutConstraints
object to communicate to the current layout the size they would like the fragment to be.
If the user agent wishes to force a size on the box, it can use the fixedInlineSize
and fixedBlockSize
attributes to do so.
The layout API container can be passed size information in different ways depending on the
value of layout options' sizing
(set by layoutOptions
on the class).
If the value of layout options' sizing
is "block-like"
, then the LayoutConstraints
passed to the layout API container:
-
Must calculate and set
fixedInlineSize
based off the rules specified in [css-sizing-3] and the formatting context in which it participates, e.g.-
As a block-level box in a block formatting context, it is sized like a block box that establishes a formatting context, with an auto inline size calculated as for non-replaced block boxes.
-
As an inline-level box in an inline formatting context, it is sized as an atomic inline-level box (such as an inline-block).
-
-
Must calculate and set
fixedBlockSize
based off the rules specified in [css-sizing-3], and the formatting context in which it participates. If the layout API container has an auto block size, and cannot be determined ahead of time,fixedBlockSize
must be set tonull
.
If the value of layout options' sizing
is "manual"
, then the user-agent must not pre-calculate fixedInlineSize
and/or fixedBlockSize
ahead of time,
except when it is being forced to a particular size by the formatting context in which it
participates, for example:
-
If the layout API container is within a block formatting context, is inflow, and has an auto inline size, the user agent must set the
fixedInlineSize
to the stretch-fit inline size.
<style> #container { width: 100px; height: 100px; box-sizing: border-box; padding: 5px; } #layout-api { display: layout(foo); margin: 0 20px; } </style> <div id="container"> <div id="layout-api"></div> </div>
4.1.1. Positioned layout sizing
If a layout API container is out-of-flow positioned the user agent must solve the
positioned size equations (CSS Positioned Layout 3 §8.1 The width of absolute or fixed positioned, non-replaced elements, CSS Positioned Layout 3 §8.3 The height of absolute or fixed positioned, non-replaced elements), and set the appropriate fixedInlineSize
and fixedBlockSize
.
<style> #container { position: relative; width: 100px; height: 100px; } #layout-api { display: layout(foo); top: 10px; bottom: 10px; left: 10px; right: 10px; position: absolute; } </style> <div id="container"> <div id="layout-api"></div> </div>
4.2. Positioning
All positioning in this level of the specification is handled by the user agent.
As a result:
-
Out-of-flow children do not appear as
LayoutChild
ren. -
Layout API containers establish containing blocks exactly like block containers do. [CSS21]
-
The
inlineOffset
andblockOffset
represent the position of the fragment before any positioning and transforms have occured. -
The static position of an absolutely-positioned child of a layout API container is set to the inline-start, block-start padding edge of the layout API container. Auto margins are treated as zero for the child.
-
"child-relative" would be the only child passed to the author’s layout. If it was positioned at (
inlineOffset
= 20
,blockOffset
= 30
), its final position would be (25
,40
) as the relative positioning was handled by the user agent. -
"child-absolute" would not appear as a
LayoutChild
, and instead would be laid out and positioned by the user agent. -
The examples above also apply in a similar way to sticky and fixed positioned children.
<style> #container { display: layout(foo); position: relative; /* container is a containing block */ width: 100px; height: 100px; } #child-relative { position: relative; left: 5px; top: 10px; } </style> <div id="container"> <div id="child-relative"></div> <div id="child-absolute"></div> </div>
4.3. Overflow
The scrollable overflow for a layout API container is handled by the user agent in this level of the specification.
A layout API container should calculate its scrollable overflow exactly like block containers do.
Even if the author’s layout API container positions a fragment into the scrollable overflow region, relative positioning or transforms may cause the fragment to shift such that its scrollable overflow region, causing no overflow to occur.
4.4. Fragmentation
A parent layout can ask the current layout to fragment by setting the blockFragmentationType
and blockFragmentationOffset
.
E.g. [css-multicol-1] layout would set a blockFragmentationType
to "column"
and set the blockFragmentationOffset
to where it needs the
child to fragment.
4.5. Alignment
The first/last baseline sets of a layout API container is generated exactly like block
containers do (see CSS Box Alignment 3 §9.1 Determining the Baselines of a Box). Except that the order of the in-flow children
should be determined by the in which they are returned form the layout method (via childFragments
) instead of the document order.
To query baseline information from a LayoutChild
.
const fragment = yield child.layoutNextFragment({ fixedInlineSize: availableInlineSize, baselineRequests: ['alphabetic', 'middle'], }); fragment.baselines.get('alphabetic') === 25 /* or something */;
To produce baseline information for a parent layout:
registerLayout('baseline-producing', class { *layout(children, edges, constraints, styleMap) { const result = {baselines: {}}; for (let baselineRequest of constraints.baselineRequests) { // baselineRequest === 'alphabetic', or something else. result.baselines[baselineRequest] = 25; } return result; } });
5. Layout
This section describes how the CSS Layout API interacts with the user agent’s layout engine.
5.1. Concepts
A layout definition is a struct which describes the information needed by the LayoutWorkletGlobalScope
about the author defined layout (which can be referenced by the layout() function). It consists of:
-
class constructor which is the class constructor.
-
layout generator function which is the layout generator function callback.
-
intrinsic sizes generator function which is the intrinsic sizes generator function callback.
-
constructor valid flag.
-
input properties which is a list of
DOMStrings
-
child input properties which is a list of
DOMStrings
. -
layout options a
LayoutOptions
.
A document layout definition is a struct which describes the information needed by the document about the author defined layout (which can be referenced by the layout() function). It consists of:
-
input properties which is a list of
DOMStrings
-
child input properties which is a list of
DOMStrings
. -
layout options a
LayoutOptions
.
5.2. Layout Invalidation
Each box has an associated layout valid flag. It may be either layout-valid or layout-invalid. It is initially set to layout-invalid.
Each box has an associated intrinsic sizes valid flag. If may be either intrinsic-sizes-valid or intrinsic-sizes-invalid. It is initially set to intrinsic-sizes-invalid.
-
Let layoutFunction be the layout() function of the display property on the computed style for the box if it exists. If it is a different type of value (e.g. grid) then abort all these steps.
-
Let name be the first argument of the layoutFunction.
-
Let documentDefinition be the result of get a document layout definition given name.
If get a document layout definition returned failure, or if documentDefinition is
"invalid"
, then abort all these steps. -
Let inputProperties be documentDefinition’s input properties.
-
Let childInputProperties be documentDefinition’s child input properties.
-
For each property in inputProperties, if the property’s computed value has changed, set the layout valid flag on the box to layout-invalid, and set the intrinsic sizes valid flag to intrinsic-sizes-invalid.
-
For each property in childInputProperties, if the property’s computed value has changed, set the layout valid flag on the box to layout-invalid, and set the intrinsic sizes valid flag to intrinsic-sizes-invalid.
Invalidate layout functions must be run when the user agent recalculates the computed style for a box, or when the children’s computed style of that box is recalculated.
When a child box represented by a LayoutChild
is added or removed from the box
tree or has its layout invalidated (from a computed style change, or a descendant change), and this invalidation is to be propagated up the box tree, set the layout valid flag on the current box to layout-invalid and set the intrinsic sizes valid flag on
the current box to intrinsic-sizes-invalid.
When the computed style of a layout API container changes, and this change effects
the values inside the LayoutEdges
object, set the layout valid flag of the box to layout-invalid, and set the intrinsic sizes valid flag of the box to intrinsic-sizes-invalid.
If the computed style changes effects the values inside the LayoutConstraints
object, just set
the intrinsic sizes valid flag of the box to intrinsic-sizes-invalid.
Note: As the LayoutConstraints
object is only passed into the layout function there is no need
to invalidate the intrinsic sizes.
LayoutEdges
object:
And the following properties could change the LayoutConstraints
object:
Note: This only describes layout invalidation as it relates to the CSS Layout API. All boxes conceptually have a layout valid flag and these changes are propagated through the box tree.
5.3. Layout Worklet
The layoutWorklet
attribute allows access to the Worklet
responsible for all the classes
which are related to layout.
The layoutWorklet
's worklet global scope type is LayoutWorkletGlobalScope
.
partial interface CSS {
[SameObject] readonly attribute Worklet layoutWorklet
;
};
The LayoutWorkletGlobalScope
is the global execution context of the layoutWorklet
.
[Global=(Worklet,LayoutWorklet),Exposed=LayoutWorklet] interfaceLayoutWorkletGlobalScope
: WorkletGlobalScope { void registerLayout(DOMStringname
, VoidFunctionlayoutCtor
); };
5.4. Registering A Layout
[Exposed=LayoutWorklet] dictionaryLayoutOptions
{ ChildDisplayTypechildDisplay
= "block"; LayoutSizingModesizing
= "block-like"; }; [Exposed=LayoutWorklet] enumChildDisplayType
{"block"
,"normal"
, }; [Exposed=LayoutWorklet] enumLayoutSizingMode
{"block-like"
,"manual"
, };
The document has a map of document layout definitions. Initially this map
is empty; it is populated when registerLayout(name, layoutCtor)
is called.
The LayoutWorkletGlobalScope
has a map of layout definitions. Initially this
map is empty; it is populated when registerLayout(name, layoutCtor)
is called.
Each box representing a layout API container has a map of layout class instances. Initially this map is empty; it is populated when the user agent calls either determine the intrinsic sizes or generate a fragment for a box.
registerLayout(name, layoutCtor)
method
is called, the user agent must run the following steps:
-
If the name is an empty string, throw a TypeError and abort all these steps.
-
Let layoutDefinitionMap be
LayoutWorkletGlobalScope
's layout definitions map. -
If layoutDefinitionMap[name] exists throw a "InvalidModificationError" DOMException and abort all these steps.
-
Let inputProperties be an empty
sequence<DOMString>
. -
Let inputPropertiesIterable be the result of Get(layoutCtor, "inputProperties").
-
If inputPropertiesIterable is not undefined, then set inputProperties to the result of converting inputPropertiesIterable to a
sequence<DOMString>
. If an exception is thrown, rethrow the exception and abort all these steps.Note: The list of CSS properties provided by the input properties getter can either be custom or native CSS properties.
Note: The list of CSS properties may contain shorthands.
Note: In order for a layout class to be forwards compatible, the list of CSS properties can also contains currently invalid properties for the user agent. For example
margin-bikeshed-property
. -
Let childInputProperties be an empty
sequence<DOMString>
. -
Let childInputPropertiesIterable be the result of Get(layoutCtor, "childInputProperties").
-
If childInputPropertiesIterable is not undefined, then set childInputProperties to the result of converting childInputPropertiesIterable to a
sequence<DOMString>
. If an exception is thrown, rethrow the exception and abort all these steps. -
Let layoutOptionsValue be the result of Get(layoutCtor, "layoutOptions").
-
Let layoutOptions be the result of converting layoutOptionsValue to a
LayoutOptions
. If an exception is thrown, rethrow the exception and abort all these steps. -
If the result of IsConstructor(layoutCtor) is false, throw a TypeError and abort all these steps.
-
Let prototype be the result of Get(layoutCtor, "prototype").
-
If the result of Type(prototype) is not Object, throw a TypeError and abort all these steps.
-
Let intrinsicSizes be the result of Get(prototype,
"intrinsicSizes"
). -
If the result of IsCallable(intrinsicSizes) is false, throw a TypeError and abort all these steps.
-
If intrinsicSizes’s
[[FunctionKind]]
internal slot is not"generator"
, throw a TypeError and abort all these steps. -
Let layout be the result of Get(prototype,
"layout"
). -
If the result of IsCallable(layout) is false, throw a TypeError and abort all these steps.
-
If layout’s
[[FunctionKind]]
internal slot is not"generator"
, throw a TypeError and abort all these steps. -
Let definition be a new layout definition with:
-
class constructor being layoutCtor.
-
layout generator function being layout.
-
intrinsic sizes generator function being intrinsicSizes.
-
constructor valid flag being true.
-
input properties being inputProperties.
-
child input properties being childInputProperties.
-
layout options being layoutOptions.
-
-
Set layoutDefinitionMap[name] to definition.
-
Queue a task to run the following steps:
-
Let documentLayoutDefinitionMap be the associated document’s document layout definitions map.
-
Let documentDefinition be a new document layout definition with:
-
input properties being inputProperties.
-
child input properties being childInputProperties.
-
layout options being layoutOptions.
-
-
If documentLayoutDefinitionMap[name] exists, run the following steps:
-
Let existingDocumentDefinition be the result of get documentLayoutDefinitionMap[name].
-
If existingDocumentDefinition is
"invalid"
, abort all these steps. -
If existingDocumentDefinition and documentDefinition are not equivalent, (that is input properties, child input properties, and layout options are different), then:
Set documentLayoutDefinitionMap[name] to
"invalid"
.Log an error to the debugging console stating that the same class was registered with different
inputProperties
,childInputProperties
, orlayoutOptions
.
-
-
Otherwise, set documentLayoutDefinitionMap[name] to documentDefinition.
-
class MyLayout { static get inputProperties() { return ['--foo']; } static get childrenInputProperties() { return ['--bar']; } static get layoutOptions() { return {childDisplay: 'normal', sizing: 'block-like'} } *intrinsicSizes(children, edges, styleMap) { // Intrinsic sizes code goes here. } *layout(children, edges, constraints, styleMap, breakToken) { // Layout code goes here. } }
5.5. Layout Engine
Promises
-
Better error reporting.
-
Potentially better developer ergonomics.
Generator
-
More "strict" - can only perform layout operations. Don’t have to restrict which promise APIs work each call.
-
Potentially better bindings overhead.
5.5.1. Request Objects
[Exposed=LayoutWorklet] interfaceIntrinsicSizesRequest
{ }; [Exposed=LayoutWorklet] interfaceLayoutFragmentRequest
{ }; typedef (IntrinsicSizesRequest or LayoutFragmentRequest)LayoutFragmentRequestOrIntrinsicSizesRequest
;
The IntrinsicSizesRequest
has internal slot(s):
-
[[layoutChild]]
aLayoutChild
, this is the child which the intrinsic sizes must be calculated for.
The LayoutFragmentRequest
has internal slot(s):
-
[[layoutChild]]
aLayoutChild
, this is the child which the fragment must be generated for. -
[[layoutConstraints]]
aLayoutConstraintsOptions
dictionary, these are the input constraints to theLayoutChild
's layout algorithm. -
[[breakToken]]
aChildBreakToken
object, which is the break token the layout must be resumed with.
The layout method and intrinsic sizes method on the author supplied layout class is a generator function instead of a regular javascript function. This is for user-agents to be able to support asynchronous and parallel layout engines.
When an author invokes the layoutNextFragment()
method on a LayoutChild
the
user-agent doesn’t synchronously generate a LayoutFragment
to return to the author’s code.
Instead it returns a LayoutFragmentRequest
. This is a completely opaque object to the author but
contains internal slots which encapsulates the layoutNextFragment()
method call.
When a LayoutFragmentRequest
(s) are yielded from a layout generator object the user-agent’s
layout engine may run the algorithm asynchronously with other work, and/or on a different thread of
execution. When LayoutFragment
(s) have been produced by the engine, the user-agent will "tick"
the generator object with the resulting LayoutFragment
(s).
The same applies for the intrinsicSizes()
method.
class LayoutEngine { // This function takes the root of the box-tree, a LayoutConstraints object, and a // BreakToken to (if paginating for printing for example) and generates a // LayoutFragment. layoutEntry(rootBox, rootPageConstraints, breakToken) { return layoutFragment({ box: rootBox, layoutConstraints: rootPageConstraints, breakToken: breakToken, }); } // This function takes a LayoutFragmentRequest and calls the appropriate // layout algorithm to generate the a LayoutFragment. layoutFragment(fragmentRequest) { const box = fragmentRequest.layoutChild; const algorithm = selectLayoutAlgorithmForBox(box); const fragmentRequestGenerator = algorithm.layout( fragmentRequest.layoutConstraints, box.children, box.styleMap, fragmentRequest.breakToken); let nextFragmentRequest = fragmentRequestGenerator.next(); while (!nextFragmentRequest.done) { // A user-agent may decide to perform layout to generate the fragments in // parallel on separate threads. This example performs them synchronously // in order. let fragments = nextFragmentRequest.value.map(layoutFragment); // A user-agent may decide to yield for other work (garbage collection for // example) before resuming this layout work. This example just performs // layout synchronously without any ability to yield. nextFragmentRequest = fragmentRequestGenerator.next(fragments); } return nextFragmentRequest.value; // Return the final LayoutFragment. } }
5.6. Performing Layout
// This is the final return value from the author defined layout() method. dictionaryFragmentResultOptions
{ doubleinlineSize
= 0; doubleblockSize
= 0; doubleautoBlockSize
= 0; sequence<LayoutFragment>childFragments
= []; anydata
= null; BreakTokenOptionsbreakToken
= null; }; dictionaryIntrinsicSizesResultOptions
{ doublemaxContentSize
; doubleminContentSize
; };
5.6.1. Determining Intrinsic Sizes
The determine the intrinsic sizes algorithm defines how a user agent is to query the author defined layout for a box’s intrinsic sizes information.
Note: The determine the intrinsic sizes algorithm allows for user agents to cache an arbitary number of previous invocations to reuse.
-
Let layoutFunction be the layout() for the computed value of <display-inside> for box.
-
If the intrinsic sizes valid flag for the layoutFunction is intrinsic-sizes-valid the user agent may use the intrinsic sizes from the previous invocation. If so it may abort all these steps and use the previous value for the intrinsic sizes.
-
Set the intrinsic sizes valid flag for the layoutFunction to intrinsic-sizes-valid.
-
Let name be the first argument of the layoutFunction.
-
Let documentDefinition be the result of get a document layout definition given name.
If get a document layout definition returned failure, or if documentDefinition is
"invalid"
, then let box fallback to the flow layout and abort all these steps. -
Let workletGlobalScope be a
LayoutWorkletGlobalScope
from the list of worklet’s WorkletGlobalScopes from the layoutWorklet
.The user agent must have, and select from at least two
LayoutWorkletGlobalScope
s in the worklet’s WorkletGlobalScopes list, unless the user agent is under memory constraints.Note: This is to ensure that authers do not rely on being able to store state on the global object or non-regeneratable state on the class.
The user agent may also create a WorkletGlobalScope at this time, given the layout
Worklet
. -
Run invoke a intrinsic sizes callback given name, box, childBoxes, and workletGlobalScope optionally in parallel.
Note: If the user agent runs invoke a intrinsic sizes callback on a thread in parallel, it should select a layout worklet global scope which can be used on that thread.
-
Let definition be the result of get a layout definition given name, and workletGlobalScope.
If get a layout definition returned failure, let the box fallback to the flow layout and abort all these steps.
-
Let layoutInstance be the result of get a layout class instance given box, definition, workletGlobalScope.
If get a layout class instance returned failure, let the box fallback to the flow layout and abort all these steps.
-
Let inputProperties be definition’s input properties.
-
Let children be a new list.
-
For each childBox in childBoxes perform the following substeps:
-
Let layoutChild be the result of get a layout child given workletGlobalScope, name, and childBox.
-
Append layoutChild to children.
-
-
Let edges be a new
LayoutEdgeSizes
populated with the computed value for all the box model edges for box. -
Let styleMap be a new
StylePropertyMapReadOnly
populated with only the computed values for properties listed in inputProperties for box.We may want to store styleMap on box instead, similar to layoutInstance.
-
At this stage the user agent may re-use the intrinsic sizes from a previous invocation if children, styleMap are equivalent to that previous invocation. If so let the intrinsic sizes the cached intrinsic sizes and abort all these steps.
-
Let intrinsicSizesGeneratorFunction be definition’s intrinsic sizes generator function.
-
Let intrinsicSizesGenerator be the result of Invoke(intrinsicSizesGeneratorFunction, layoutInstance, «children, edges, styleMap»).
If an exception is thrown the let box fallback to the flow layout and abort all these steps.
-
Let intrinsicSizesValue be the result of run a generator given intrinsicSizesGenerator, and
"intrinsic-sizes"
.If run a generator returned failure, then let box fallback to the flow layout and abort all these steps.
-
Let intrinsicSizes be the result of converting intrinsicSizesValue to a
IntrinsicSizesResultOptions
. If an exception is thrown, let box fallback to the flow layout and abort all these steps. -
Set the intrinsic sizes of box:
-
Let intrinsicSizes’s
minContentSize
be the min-content size of box. -
Let intrinsicSizes’s
maxContentSize
be the max-content size of box.
-
5.6.2. Generating Fragments
The generate a fragment algorithm defines how a user agent is to generate a box’s fragment for an author defined layout.
Note: The generate a fragment algorithm allows for user agents to cache an arbitary number of previous invocations to reuse.
-
Let layoutFunction be the layout() for the computed value of <display-inside> for box.
-
If the layout valid flag for the layoutFunction is layout-valid the user agent may use the intrinsic sizes from the previous invocation. If so it may abort all these steps and use the previous value for the intrinsic sizes.
-
Set the layout valid flag for the layoutFunction to layout-valid.
-
Let name be the first argument of the layoutFunction.
-
Let documentDefinition be the result of get a document layout definition given name.
If get a document layout definition returned failure, or if documentDefinition is
"invalid"
, then let box fallback to the flow layout and abort all these steps. -
Let workletGlobalScope be a
LayoutWorkletGlobalScope
from the list of worklet’s WorkletGlobalScopes from the layoutWorklet
.The user agent must have, and select from at least two
LayoutWorkletGlobalScope
s in the worklet’s WorkletGlobalScopes list, unless the user agent is under memory constraints.Note: This is to ensure that authers do not rely on being able to store state on the global object or non-regeneratable state on the class.
The user agent may also create a WorkletGlobalScope at this time, given the layout
Worklet
. -
Run invoke a layout callback given name, box, childBoxes, internalLayoutConstraints, internalBreakToken, and workletGlobalScope optionally in parallel.
Note: If the user agent runs invoke a intrinsic sizes callback on a thread in parallel, it should select a layout worklet global scope which can be used on that thread.
-
Let definition be the result of get a layout definition given name, and workletGlobalScope.
If get a layout definition returned failure, let the box fallback to the flow layout and abort all these steps.
-
Let layoutInstance be the result of get a layout class instance given box, definition, workletGlobalScope.
If get a layout class instance returned failure, let the box fallback to the flow layout and abort all these steps.
-
Let sizingMode be definition’s layout options'
sizing
property. -
Let inputProperties be definition’s input properties.
-
Let children be a new list.
-
For each childBox in childBoxes perform the following substeps:
-
Let layoutChild be the result of get a layout child given workletGlobalScope, name, and childBox.
-
Append layoutChild to children.
-
-
Let edges be a new
LayoutEdgeSizes
populated with the computed value for all the box model edges for box. -
Let layoutConstraints be the result of create a layout constraints object given internalLayoutConstraints, box, and sizingMode.
-
Let styleMap be a new
StylePropertyMapReadOnly
populated with only the computed values for properties listed in inputProperties for box.We may want to store styleMap on box instead, similar to layoutInstance.
-
Let breakToken be a new
BreakToken
populated with the appropriate information from internalBreakToken.If internalBreakToken is null, let breakToken be null.
-
At this stage the user agent may re-use a fragment from a previous invocation if children, styleMap, layoutConstraints, breakToken are equivalent to that previous invocation. If so let the fragment output be that cached fragment and abort all these steps.
-
Let layoutGeneratorFunction be definition’s layout generator function.
-
Let layoutGenerator be the result of Invoke(layoutGeneratorFunction, layoutInstance, «children, edges, layoutConstraints, styleMap, breakToken»).
If an exception is thrown the let box fallback to the flow layout and abort all these steps.
-
Let fragmentValue be the result of run a generator given layoutGenerator, and
"layout"
.If run a generator returned failure, then let box fallback to the flow layout and abort all these steps.
-
Let fragment be the result of converting fragmentValue to a
FragmentResultOptions
. If an exception is thrown, let box fallback to the flow layout and abort all these steps. -
For each childFragment in fragment’s
childFragments
, perform the following stubsteps:-
If childFragment’s
[[generator]]
internal slot is not equal to layoutGenerator, then let box fallback to the flow layout and abort all these steps.
-
-
If sizingMode is
"block-like"
:-
Then:
-
Let inlineSize be layoutConstraints’
fixedInlineSize
. (This value must be set if we are using"block-like"
sizing). -
Let blockSize be the result of calculating box’s border-box block size (relative to box’s writing mode) exactly like block containers do, given fragment’s
autoBlockSize
as the "intrinsic height".
-
-
Otherwise (sizingMode is
"manual"
):-
Let inlineSize be fragment’s
inlineSize
. -
Let blockSize be fragment’s
blockSize
.
-
-
-
Return a fragment for box with:
-
The inline size set to inlineSize.
-
The block size set to blockSize.
-
The child fragments set to fragment’s
childFragments
list. The ordering is important as this dictates their paint order (described in §2 Layout API Containers). Their position relative to the border box of the fragment should be based off the author specifiedinlineOffset
andblockOffset
. -
The fragmentation break information set to fragment’s
breakToken
. -
Let clonedData be the result of invoking StructuredSerializeForStorage on fragment’s
data
.The user agent must store clonedData with the fragment.
-
5.6.3. Utility Algorithms
The section specifies algorithms common to the determine the intrinsic sizes and generate a fragment algorithms.
-
Let documentLayoutDefinitionMap be the associated document’s document layout definitions map.
-
If documentLayoutDefinitionMap[name] does not exist, return failure and abort all these steps.
-
Return the result of get documentLayoutDefinitionMap[name].
-
Let layoutDefinitionMap be workletGlobalScope’s layout definitions map.
-
If layoutDefinitionMap[name] does not exist, run the following steps:
-
Queue a task to run the following steps:
-
Let documentLayoutDefinitionMap be the associated document’s document layout definition map.
-
Set documentLayoutDefinitionMap[name] to
"invalid"
. -
The user agent should log an error to the debugging console stating that a class wasn’t registered in all
LayoutWorkletGlobalScope
s.
-
-
Return failure, and abort all these steps.
-
-
Return the result of get layoutDefinitionMap[name].
-
Let layoutClassInstanceMap be box’s layout class instances map.
-
Let layoutInstance be the result of get layoutClassInstanceMap[workletGlobalScope]. If layoutInstance is null, run the following steps:
-
If the constructor valid flag on definition is false, then return failure and abort all these steps.
-
Let layoutCtor be the class constructor on definition.
-
Let layoutInstance be the result of Construct(layoutCtor).
If construct throws an exception, set the definition’s constructor valid flag to false, then return failure and abort all these steps.
-
Set layoutClassInstanceMap[workletGlobalScope] to layoutInstance.
-
-
Return layoutInstance.
-
Let done be a boolean initialized to
false
. -
Let nextValue be undefined.
-
Perform the following substeps until done is
true
:-
Let nextFunction be the result of Get(generator,
"next"
). -
If the result of IsCallable(nextFunction) is false, throw a TypeError and abort all these steps.
-
Let nextResult be the result of calling Invoke(nextFunction, generator, «nextValue»).
If an exception is thrown return failure, and abort all these steps.
-
If the result of Type(nextResult) is not Object, throw a TypeError and abort all these steps.
-
Let requestOrRequests be the result of Get(nextResult|,
"value"
). -
Let done be the result of Get(nextResult,
"done"
). -
If the result of GetMethod(requestOrRequests,
@@iterable
) exists then:-
Let requests be the result of converting requestOrRequests to a
sequence<LayoutFragmentRequestOrIntrinsicSizesRequest>
.If an exception is thrown, rethrow the exception and abort all these steps.
-
For each request in requests perform the following substeps:
-
Let result be the result of produce a generator result given request, generator, generatorType.
-
Append result to results.
-
-
Set nextValue to be results.
-
Continue.
-
Let request be the result of converting requestOrRequests to a
LayoutFragmentRequestOrIntrinsicSizesRequest
.If an exception is thrown, rethrow the exception and abort all these steps.
-
Let result be the result of produce a generator result given request, generator, generatorType.
If produce a generator result returns failure, return failure, and abort all these steps.
-
Set nextValue to be result.
-
Continue.
The user agent may perform the above loop out of order, and in parallel. The ordering for requests and results however must be consistent.
Note: This is to allow user agents to run the appropriate layout algorithm on a different thread, or asynchronously (e.g. time slicing layout work with other work). If the user agent performs the loop in parallel, the outside loop has to wait until all the cross thread tasks are complete before calling the generator again. It cannot return partial results to the author.
-
-
Return the result of calling Get(nextResult,
"value"
).
-
If request is a
IntrinsicSizesRequest
then:-
Let layoutChild be the result of looking up the internal slot
[[layoutChild]]
on request. -
Let box be the result of looking up the internal slot
[[box]]
on layoutChild. -
If box is not attached to the box tree, return failure and abort all these steps.
Note: The author may hold onto a
LayoutChild
from a previous invocation. It is assumed that a box is only ever attached to the box-tree once, and not re-used. -
Let internalIntrinsicSizes be the result of the user agent calculating the border box min/max content contribution of box.
-
Return the result of create an intrinsic sizes object given request, and internalIntrinsicSizes.
-
-
If request is a
LayoutFragmentRequest
and generatorType is"layout"
then:-
Let layoutChild be result of looking up the internal slot
[[layoutChild]]
on request. -
Let box be the result of looking up the internal slot
[[box]]
on layoutChild. -
If box is not attached to the box tree, return failure and abort all these steps.
Note: The author may hold onto a
LayoutChild
from a previous invocation. It is assumed that a box is only ever attached to the box-tree once, and not re-used. -
Let childLayoutConstraints be the result of looking up the internal slot
[[layoutConstraints]]
on request. -
Let childBreakToken be the result of looking up the internal slot
[[breakToken]]
on request. -
Let internalFragment be the result of the user agent producing a fragment based on box, childLayoutConstraints, and childBreakToken.
-
Return the result of create a layout fragment given generator, request, and internalFragment.
-
-
Return failure (neither of the above branches was taken).
6. Security Considerations
There are no known security issues introduced by these features.
7. Privacy Considerations
There are no known privacy issues introduced by these features.