Title:  CSS Layout API Level 1
Status: DREAM
Group: houdini
ED: https://drafts.css-houdini.org/css-layout-api-1/
Shortname: css-layout-api
Level: 1
Abstract:
Editor: Greg Whitworth, gwhit@microsoft.com 
Editor: Ian Kilpatrick, ikilpatrick@chromium.org
Editor: Tab Atkins, jackalmage@gmail.com
Editor: Shane Stephens, shanestephens@google.com
Editor: Robert O'Callahan, robert@ocallahan.org
Editor: Rossen Atanassov, rossen.atanassov@microsoft.com

spec:css-break-3; type:dfn; text:fragment
spec:css-display-3; type:dfn; text:box
spec:css-display-3; type:value; for:display; text:none
spec:dom; type:dfn; text:element

urlPrefix: https://heycam.github.io/webidl/; type: dfn;
    text: NotSupportedError
    urlPrefix: #dfn-;
        text: callback this value
        text: exception
        text: throw
        url: throw; text: thrown
    url: es-invoking-callback-functions; text: Invoke
urlPrefix: https://tc39.github.io/ecma262/#sec-; type: dfn;
    text: constructor
    text: Construct
    text: IsArray
    text: IsCallable
    text: IsConstructor
    text: HasProperty
    url: get-o-p; text: Get
    url: terms-and-definitions-function; text: function
    urlPrefix: native-error-types-used-in-this-standard-
        text: TypeError

    Name: display
    New values: layout(<>) | inline-layout(<>)

[Exposed=LayoutWorklet]
interface LayoutChild {
    FragmentRequest layoutNextFragment(ConstraintSpace space, ChildBreakToken breakToken);
};

[Exposed=LayoutWorklet]
interface InlineLayoutChild : LayoutChild {
};

[Exposed=LayoutWorklet]
interface BoxLayoutChild : LayoutChild {
    readonly attribute StylePropertyMapReadOnly styleMap;
};

        This is a next node, <span>with some additional styling,
        that may</span> break over<br>multiple lines.
    

        ع<span style="color: blue">ع</span>ع
    

        <style>
          #box::before { content: 'hello!'; }
        </style>
        
        <div id="box">A block level box with text.</div>
        <img src="..." />
    

[Exposed=LayoutWorklet]
interface Fragment {
    readonly attribute double inlineSize;
    readonly attribute double blockSize;

    readonly attribute double inlineOverflowSize;
    readonly attribute double blockOverflowSize;

    attribute double inlineOffset;
    attribute double blockOffset;

    readonly attribute ChildBreakToken? breakToken;

    readonly attribute double dominantBaseline;
};

The layout algorithm performs a block-like layout (positioning fragments sequentically in the block direction), while centering its children in the inline direction.

registerLayout('block-like', class extends Layout {
    static blockifyChildren = true;
    static inputProperties = super.inputProperties;

    *layout(space, children, styleMap) {
        const inlineSize = resolveInlineSize(space, styleMap);

        const bordersAndPadding = resolveBordersAndPadding(constraintSpace, styleMap);
        const scrollbarSize = resolveScrollbarSize(constraintSpace, styleMap);
        const availableInlineSize = inlineSize -
                                    bordersAndPadding.inlineStart -
                                    bordersAndPadding.inlineEnd -
                                    scrollbarSize.inline;

        const availableBlockSize = resolveBlockSize(constraintSpace, styleMap) -
                                   bordersAndPadding.blockStart -
                                   bordersAndPadding.blockEnd -
                                   scrollbarSize.block;

        const childFragments = [];
        const childConstraintSpace = new ConstraintSpace({
            inlineSize: availableInlineSize,
            blockSize: availableBlockSize,
        });

        let maxChildInlineSize = 0;
        let blockOffset = bordersAndPadding.blockStart;

        for (let child of children) {
            const fragment = yield child.layoutNextFragment(childConstraintSpace);

            // Position the fragment in a block like manner, centering it in the
            // inline direction.
            fragment.blockOffset = blockOffset;
            fragment.inlineOffset = Math.max(
                bordersAndPadding.inlineStart,
                (availableInlineSize - fragment.inlineSize) / 2);

            maxChildInlineSize =
                Math.max(maxChildInlineSize, childFragments.inlineSize);
            blockOffset += fragment.blockSize;
        }

        const inlineOverflowSize = maxChildInlineSize + bordersAndPadding.inlineEnd;
        const blockOverflowSize = blockOffset + bordersAndPadding.blockEnd;
        const blockSize = resolveBlockSize(
            constraintSpace, styleMap, blockOverflowSize);

        return {
            inlineSize: inlineSize,
            blockSize: blockSize,
            inlineOverflowSize: inlineOverflowSize,
            blockOverflowSize: blockOverflowSize,
            childFragments: childFragments,
        };
    }
});

[Constructor(optional ConstraintSpaceOptions options),Exposed=LayoutWorklet]
interface ConstraintSpace {
    readonly attribute double inlineSize;
    readonly attribute double blockSize;

    readonly attribute boolean inlineSizeFixed;
    readonly attribute boolean blockSizeFixed;

    readonly attribute boolean inlineShrinkToFit;

    readonly attribute double percentageInlineSize;
    readonly attribute double percentageBlockSize;

    readonly attribute boolean inlineOverflow;
    readonly attribute boolean blockOverflow;

    readonly attribute BlockFragmentationType blockFragmentationType;
};

dictionary ConstraintSpaceOptions {
    double inlineSize = Infinity;
    double blockSize = Infinity;

    boolean inlineSizeFixed = false;
    boolean blockSizeFixed = false;

    boolean inlineShrinkToFit = false;

    double? percentageInlineSize = null;
    double? percentageBlockSize = null;

    BlockFragmentationType blockFragmentationType = "none";
};

enum BlockFragmentationType { "none", "page", "column", "region" };

The layout algorithm performs a flexbox-like distribution of spare space in the inline direction. It creates child constraint spaces which specify that a child should be a fixed inline size.

registerLayout('flex-distribution-like', class {
    *layout(space, children, styleMap, breakToken) {
        const inlineSize = resolveInlineSize(space, styleMap);

        const bordersAndPadding = resolveBordersAndPadding(constraintSpace, styleMap);
        const scrollbarSize = resolveScrollbarSize(constraintSpace, styleMap);
        const availableInlineSize = inlineSize -
                                    bordersAndPadding.inlineStart -
                                    bordersAndPadding.inlineEnd -
                                    scrollbarSize.inline;

        const availableBlockSize = resolveBlockSize(constraintSpace, styleMap) -
                                   bordersAndPadding.blockStart -
                                   bordersAndPadding.blockEnd -
                                   scrollbarSize.block;

        const unconstrainedSizes = [];
        const childConstraintSpace = new ConstraintSpace({
            inlineShrinkToFit: true,
            inlineSize: availableInlineSize,
            blockSize: availableBlockSize,
        });
        let totalSize = 0;

        // Calculate the unconstrained size for each child.
        for (let child of children) {
            const fragment = yield child.layoutNextFragment(childConstraintSpace);
            unconstrainedSizes.push(fragment.inlineSize);
            totalSize += fragment.inlineSize;
        }

        // Distribute spare space between children.
        const remainingSpace = Math.max(0, inlineSize - totalSize);
        const extraSpace = remainingSpace / children.length;
        const childFragments = [];
        let inlineOffset = 0;
        let maxChildBlockSize = 0;
        for (let i = 0; i < children.length; i++) {
            let fragment = yield child.layoutNextFragment(new ConstraintSpace({
                inlineSize: unconstrainedSizes[i] + extraSpace,
                inlineSizeFixed: true,
                blockSize: availableBlockSize
            }));

            fragment.inlineOffset = inlineOffset;
            inlineOffset += fragment.inlineSize;

            maxChildBlockSize = Math.max(maxChildBlockSize, fragment.blockSize);

            childFragments.push(fragment);
        }

        // Resolve our block size.
        const blockSize = resolveBlockSize(constraintSpace, styleMap, maxChildBlockSize);

        return {
            inlineSize: inlineSize,
            blockSize: blockSize,
            inlineOverflowSize: Math.max(inlineSize, totalSize),
            blockOverflowSize: maxChildBlockSize,
            childFragments: childFragments,
        };
    }
});

[Exposed=LayoutWorklet]
interface ChildBreakToken {
    readonly attribute BreakType breakType;
    readonly attribute LayoutChild child;
};

[Exposed=LayoutWorklet]
interface BreakToken {
    readonly attribute sequence<ChildBreakToken> childBreakTokens;
    readonly attribute Object data;
};

dictionary BreakTokenOptions {
    sequence<ChildBreakToken> childBreakTokens;
    Object data = null;
};

enum BreakType { "none", "inline", "inline-hyphen", "column", "page", "region" };

This example shows a simple inline layout which places child fragments in the inline direction. It places each of its on a line, aligning their dominant baselines. This example also demonstrates using the previous {{Fragment/breakToken}} of a {{Fragment}} to produce the next fragment for the {{LayoutChild}}. It also demonstrates using the {{BreakToken}} to respect the {{ConstraintSpace}}'s {{ConstraintSpace/blockFragmentationType}}, it resumes it layout from the previous {{BreakToken}}. It returns a {{FragmentResultOptions}} with a {{FragmentResultOptions/breakToken}} which is used to resume the layout.

registerLayout('basic-inline', class extends Layout {
    static inputProperties = super.inputProperties;

    *layout(constraintSpace, children, styleMap, breakToken) {
        // Resolve our inline size.
        const inlineSize = resolveInlineSize(constraintSpace, styleMap);

        // Determine our (inner) available size.
        const bordersAndPadding =
            resolveBordersAndPadding(constraintSpace, styleMap);
        const scrollbarSize = resolveScrollbarSize(constraintSpace, styleMap);
        const availableInlineSize = inlineSize -
                                    bordersAndPadding.inlineStart -
                                    bordersAndPadding.inlineEnd -
                                    scrollbarSize.inline;

        const availableBlockSize = resolveBlockSize(constraintSpace, styleMap) -
                                   bordersAndPadding.blockStart -
                                   bordersAndPadding.blockEnd -
                                   scrollbarSize.block;

        const childFragments = [];
        let maxInlineSize = 0;

        let currentLine = [];
        let usedInlineSize = 0;
        let maxBaseline = 0;

        let lineOffset = 0;
        let maxLineBlockSize = 0;

        // Just a small little function which will update the above variables.
        const nextLine = function() {
            if (usedInlineSize > maxInlineSize) {
                maxInlineSize = usedInlineSize;
            }

            currentLine = [];
            usedInlineSize = 0;
            maxBaseline = 0;

            lineOffset += maxLineBlockSize;
            maxLineBlockSize = 0;
        }

        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 child = children.shift();
        while (child) {
            // Make sure we actually have space on the current line.
            if (usedInlineSize > availableInlineSize) {
                nextLine();
            }

            // The constraint space here will have the inline size of the
            // remaining space on the line.
            const remainingInlineSize = availableInlineSize - usedInlineSize;
            const constraintSpace = new ConstraintSpace({
                inlineSize: availableInlineSize - usedInlineSize,
                blockSize: availableBlockSize,
                percentageInlineSize: availableInlineSize,
                inlineShrinkToFit: true,
            });

            const fragment = yield child.layoutNextFragment(constraintSpace,
                                                            childBreakToken);
            childFragments.push(fragment);

            // Check if there is still space on the current line.
            if (fragment.inlineSize > remainingInlineSize) {
                nextLine();

                // Check if we have gone over the block fragmentation limit.
                if (constraintSpace.blockFragmentationType != 'none' &&
                    lineOffset > constraintSpace.blockSize) {
                    break;
                }
            }

            // Insert fragment on the current line.
            currentLine.push(fragment);
            fragment.inlineOffset = usedInlineSize;

            if (fragment.dominantBaseline > maxBaseline) {
                maxBaseline = fragment.dominantBaseline;
            }

            // Go through each of the fragments on the line and update their
            // block offsets.
            for (let fragmentOnLine of currentLine) {
                fragmentOnLine.blockOffset = lineOffset +
                    maxBaseline - fragmentOnLine.dominantBaseline;

                const lineBlockSize =
                    fragmentOnLine.blockOffset + fragmentOnLine.blockSize;
                if (maxLineBlockSize < lineBlockSize) {
                    maxLineBlockSize = lineBlockSize;
                }
            }

            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 block size.
        nextLine();
        const blockOverflowSize = lineOffset +
                                  bordersAndPadding.blockStart +
                                  bordersAndPadding.blockEnd;
        const blockSize = resolveBlockSize(constraintSpace,
                                           styleMap,
                                           blockOverflowSize);

        // Return our fragment.
        const result = {
            inlineSize: inlineSize,
            blockSize: blockSize,
            inlineOverflowSize: maxInlineSize,
            blockOverflowSize: blockOverflowSize,
            childFragments: childFragments,
        }

        if (childBreakToken) {
            result.breakToken = {
                childBreakTokens: [childBreakToken],
            };
        }

        return result;
    }
});

[Exposed=LayoutWorklet]
interface LayoutStrut {
  readonly attribute double inlineStart;
  readonly attribute double inlineEnd;

  readonly attribute double blockStart;
  readonly attribute double blockEnd;
};

[Exposed=LayoutWorklet]
interface LayoutSize {
  readonly attribute double inline;
  readonly attribute double block;
};

partial interface LayoutWorkletGlobalScope {
    double resolveInlineSize(ConstraintSpace constraintSpace,
                             StylePropertyMapReadOnly styleMap);

    double resolveBlockSize(ConstraintSpace constraintSpace,
                            StylePropertyMapReadOnly styleMap,
                            optional double contentSize);

    LayoutStrut resolveBordersAndPadding(ConstraintSpace constraintSpace,
                                         StylePropertyMapReadOnly styleMap);

    LayoutSize resolveScrollbarSize(ConstraintSpace constraintSpace,
                                    StylePropertyMapReadOnly styleMap);
};

[Exposed=LayoutWorklet]
interface Layout {
    readonly attribute sequence<DOMString> inputProperties;
    readonly attribute sequence<DOMString> childInputProperties;
};

partial interface CSS {
    [SameObject] readonly attribute Worklet layoutWorklet;
};

[Global=(Worklet,LayoutWorklet),Exposed=LayoutWorklet]
interface LayoutWorkletGlobalScope : WorkletGlobalScope {
    void registerLayout(DOMString name, VoidFunction layoutCtor);
};

        class MyLayout {
            static get inputProperties() { return ['--foo']; }
            static get childrenInputProperties() { return ['--bar']; }

            *layout(constraintSpace, children, styleMap, breakToken) {
                // Layout code goes here.
            }
        }
    

[Exposed=LayoutWorklet]
interface FragmentRequest {
  // Has internal slots:
  // [[layoutChild]] - The layout child to generate the fragment for.
  // [[constraintSpace]] - The constraint space to perform layout in.
  // [[breakToken]] - The break token to resume the layout with.
};

class LayoutEngine {
  // This function takes the root of the box-tree, a ConstraintSpace, and a
  // BreakToken to (if paginating for printing for example) and generates a
  // Fragment.
  layoutEntry(rootBox, rootPageConstraintSpace, breakToken) {
    return layoutFragment({
      box: rootBox,
      constraintSpace: rootPageConstraintSpace,
      breakToken: breakToken,
    });
  }

  // This function takes a FragmentRequest and calls the appropriate layout
  // algorithm to generate the a Fragment.
  layoutFragment(fragmentRequest) {
    const box = fragmentRequest.box;
    const algorithm = selectLayoutAlgorithmForBox(box);
    const fragmentRequestGenerator = algorithm.layout(
        fragmentRequest.constraintSpace,
        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 Fragment.
  }
}

// This is the final return value from the author defined layout() method.
dictionary FragmentResultOptions {
    double inlineSize = 0;
    double blockSize = 0;
    double inlineOverflowSize = null;
    double blockOverflowSize = null;
    sequence<Fragment> childFragments = [];
    BreakTokenOptions breakToken = null;
    double dominantBaseline = null;
};