`. E.g.
```html
```
This is important as the above `centering` layout would have to deal with text _fragmentation_, a
few native layouts use this trick to simplify their algorithms, for example grid and flexbox.
### Text Fragmentation ###
In the above `centering` example, we forced each `LayoutChild` to produce exactly one
`LayoutFragment`.
We are able to ensure children do not blockify by setting the `childDisplay` to `normal`, e.g.
```js
registerLayout('example', class {
static layoutOptions = {childDisplay: 'normal'};
});
```
Now a `LayoutChild` which represents some text is able to produce more than one `Fragment`. E.g.
```text
|---- Inline Available Size ----|
The quick brown fox jumped over the lazy dog.
```
```js
child instanceof LayoutChild;
const fragment1 = yield child.layoutNextFragment(constraints);
const fragment2 = yield child.layoutNextFragment(constraints, fragment1.breakToken);
fragment2.breakToken == null;
```
In the above example the text child produces two fragments. Containing:
1. `The quick brown fox jumped over`
2. `the lazy dog.`
The critical detail here to be aware of is the concept of a `BreakToken`. The `BreakToken` contains
all of the information necessary to continue/resume the layout where the child finished.
We pass the `BreakToken` to add back into the `layout()` call in order to produce the next fragment.
### A Basic Text Layout ###
```js
registerLayout('basic-inline', class {
static layoutOptions = {childDisplay: 'normal'};
async layout(children, edges, constraints, styleMap) {
// Determine our (inner) available size.
const availableInlineSize = constraints.fixedInlineSize - edges.inline;
const availableBlockSize = constraints.fixedBlockSize !== null ?
constraints.fixedBlockSize - edges.block : null;
const constraints = {
availableInlineSize,
availableBlockSize,
};
const childFragments = [];
let blockOffset = edges.blockStart;
let child = children.shift();
let childBreakToken = null;
while (child) {
// Layout the next line, the produced line will try and respect the
// availableInlineSize given, you could use this to achieve a column
// effect or similar.
const fragment = await child.layoutNextFragment(constraints, childBreakToken);
childFragments.push(fragment);
// Position the fragment, note we coulld do something special here, like
// placing all the lines on a "rythimic grid", or similar.
fragment.inlineOffset = edges.inlineStart;
fragment.blockOffset = blockOffset;
blockOffset += fragment.blockSize;
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;
}
}
// Determine our "auto" block size.
const autoBlockSize = blockOffset + edges.blockEnd;
// Return our fragment.
return {
autoBlockSize,
childFragments,
};
}
});
```
The above example is slightly more complex than the previous centering layout because of the ability
for text children to fragment.
That said it has all the same steps as before:
1. Resolving the (inner) available size.
2. Performing layout and positioning children fragments.
3. Resolving the "auto" block size.
4. Returning the fragment.
Scrolling
---------
We have been handling scrolling in the above example but we haven't talked about it yet.
The `edges` object passed into `layout()` respects the `overflow` property.
For example if we are `overflow: hidden`, `edges` object won't include the scrollbar width.
For `overflow: auto` the engine will typically perform a layout without a scrollbar, then if it
detects overflow, with a scrollbar. As long as you respect the layout "edges" your layout algorithm
should work as expected.
Block Fragmentation
-------------------
Some native layouts on the web support what is known as block fragmentation. For example:
```html
This is some text.
This is some more text.
```
In the above example the `multicol` div may produce three (3) fragments.
1. `{fragment}This is some text.{/fragment}`
2. `{fragment}{fragment type=table}{/fragment} This is{/fragment}`
3. `{fragment}some more text.{/fragment}`
We can make our children fragment by passing them a constraint space with a fragmentation line. E.g.
```js
registerLayout('special-multi-col', class {
async layout(children, edges, constraints, styleMap, breakToken) {
for (let child of children) {
// Create a constraint space with a fragmentation line.
const childConstraints = {
availableInlineSize,
availableBlockSize,
blockFragmentationOffset: availableBlockSize,
blockFragmentationType: 'column',
});
const fragment = await child.layoutNextFragment(childConstraints);
}
// ...
}
});
```
In the above example each of the children will attempt to fragment in the block direction when they
exceed `blockFragmentationOffset`. The type is a `'column'` which will mean it works in conjunction
with rules like `break-inside: avoid-column`.
We can also allow our own layout to be fragmented by respecting the fragmentation line. E.g.
```js
registerLayout('basic-inline', class {
async layout(children, edges, constraints, styleMap, breakToken) {
// We can check if we need to fragment in the block direction.
if (constraints.blockFragmentationType != 'none') {
// We need to fragment!
}
// We can get the start child to start layout at with the breakToken. E.g.
let child = null;
let childToken = null;
if (breakToken) {
childToken = breakToken.childTokens[0]; // We can actually have multiple
// children break. But for now
// we'll just use one.
child = childToken.child;
} else {
child = children[0];
}
// SNIP!
return {
autoBlockSize,
childFragments,
breakToken: {
data: /* you can place arbitary data here */,
childTokens: [childToken]
}
}
}
});
```
The additional complexity here is that you need to create and receive your own break tokens.
Closing Words
-------------
This is a complex API and it uses foreign terminology. But we really want to give you, the web
developer, the power that the rendering engines have when it comes to layout. Enjoy! :)