Ooidget Component Format 0.1Editor's Draft

Layout

The algorithm in this chapter is normative as code: layout.js in the web runtime, plain JavaScript written to be translated line for line. A runtime in another language translates it (the Rust core does, function for function) and MUST place every box it places: the conformance suite’s random layout cases, generated from it, hold every runtime to that. Where this prose and that file differ, the file is right, and this prose is wrong.

Absolute placement

A widget without layout places each child by its frame or frameItem (computed as a frame inside the widget’s box) or, without one, at x, y at the child’s design size.

Flex layout

A widget’s layout arranges its children in a row or a column, with the semantics of a CSS flex container [CSS-FLEXBOX-1], or in a grid (below). The properties are those a design tool’s layouts have (Penpot’s flex and grid layouts map onto them one to one), written as CSS writes them:

Items

Children are not shrunk below their basis (flex-shrink: 0). Children whose when is false take no space. The cross size of a non-stretched child is its design size on the cross axis.

A runtime MUST produce the boxes CSS would produce for an equivalent flex container whose items have the given flex-basis, flex-grow, flex-shrink: 0, min-*, max-* and align-self, then apply collapsing.

Collapsing

When the items’ sizes after growing, with their gaps, exceed the container’s main size, the excess is taken from the items that have an importance, least important first (array order among equals). Importance is relative to the item’s siblings only: each container ranks its own parts. An item with yield: "shrink" first gives up the part of its main size above its min, laid out smaller. Then it gives up its room, and the gap beside it (the one before it, or after it when it is first) in proportion, continuously, until it has none; only then does the next start. An item left with a share f of its room (0 < f < 1) is laid out at its own size, centred on what it has left, and drawn scaled by f about that centre while it fades: with the item’s minScale m (0.7 when absent), its opacity is ((f − m) ⁄ (1 − m))², and at f = m it is gone. Its room goes on shrinking to nothing for its siblings to take, so a part is never shown smaller than m of its size and never overlaps another. Below f = ½ it takes no input.

When even that leaves too much, every item still there shrinks in proportion, below its min if it must: items never overlap one another. (Where CSS would let them overflow, Ooidget does not.)

So a component sheds its least important parts one at a time as its room shrinks, and takes them back in reverse, with no jumps: the same size always gives the same picture, and a resize animates by itself.

Adapting to the container

A root instance in a host area that the host resizes (a window, a panel, a plug-in editor) adapts in three steps. The widget declares its limits:

Every one of these is the author’s choice: a widget that declares none of them is laid out at its area’s size and nothing in it scales, shrinks or hides; one that wants a fixed picture declares minSize and maxSize equal to its size. Only parts given an importance ever give way.

1. Scale. The runtime finds the factor k = √((W ⁄ basew) × (H ⁄ baseh)) for an area of W × H, clamped to [min, max]; base is scaling.base, else the widget’s size. Type, controls, strokes and displays are all in design units, so they all grow and shrink by k together, in proportion, as design tokens scaled as one.
2. Reflow. The layout is computed at W ⁄ k × H ⁄ k design units, held within minSize, maxSize and aspect: flex items grow, frames anchored to edges follow them, and expressions read the new size as ui.w and ui.h.
3. Collapse. Where even the minimums do not fit, parts give way by importance.

The picture is shown at k (or smaller, when held at minSize in too small an area). These steps are continuous in the area’s size: there are no breakpoints, and growing back retraces shrinking.

The model follows CSS: steps 1 and 2 are what clamp() sizes and a flex container give a page; collapsing is the part CSS has no property for, and is written here so that every runtime sheds parts in the same order. Size classes remain for designs that are different, not just smaller, at a size.

Size classes

A root instance is shown in an area of the host’s size. The runtime sets env.sizeClass from the area’s width in design units:

A component adapts to size by conditions on env in when, in frames and in expressions. A component MAY also give variants, whole widgets for a size class, in extensions.OOIDGET_variants (see Extensions).