@uniflowed/tui 0.0.0-alpha.18 → 0.14.1

package/layout.js

@@ -24,8 +24,8 @@
 //
 // So this implements the subset a terminal uses, in whole cells. What it does
 // *not* implement is written down at the bottom of this file rather than
-// discovered: no wrapping, no absolute positioning, no aspect ratio, no `auto`
-// margins. Those are ubugeeei-prod/uf#314.
+// discovered: no aspect ratio, and no wrapping or positioning inside a
+// scrolling box. Those are ubugeeei-prod/uf#314.
 //
 // # Whole cells, and where the remainder goes
 //
@@ -45,6 +45,9 @@
  */
 export type Dimension = number | string;
 
+/** A margin: a number of cells, or `"auto"` inside a flex container. */
+export type Margin = number | "auto";
+
 /** Main-axis direction. `"column"` is the default, as in OpenTUI. */
 export type FlexDirection = "row" | "row-reverse" | "column" | "column-reverse";
 
@@ -63,6 +66,45 @@ export type AlignItems = "flex-start" | "center" | "flex-end" | "stretch";
 /** Cross-axis alignment of one child, or `"auto"` to follow the parent. */
 export type AlignSelf = "auto" | AlignItems;
 
+/**
+ * Whether children that do not fit on one line go on to another.
+ *
+ * `"no-wrap"` — the default, OpenTUI's and Yoga's — keeps them on one and
+ * shrinks them. `"wrap"` starts a new line below (or, in a column, to the
+ * right), and `"wrap-reverse"` stacks the lines from the other side.
+ */
+export type FlexWrap = "no-wrap" | "wrap" | "wrap-reverse";
+
+/** Where the lines of a wrapping box go in the space they leave over. */
+export type AlignContent =
+  | "flex-start"
+  | "center"
+  | "flex-end"
+  | "stretch"
+  | "space-between"
+  | "space-around"
+  | "space-evenly";
+
+/**
+ * Whether a node takes part in its parent's flex line, and whether it is a
+ * containing block for the absolutely positioned boxes under it.
+ *
+ * `"relative"` — the default, as it is in OpenTUI and Yoga — takes part, and
+ * its `top`/`right`/`bottom`/`left` then nudge where it is drawn without
+ * moving anything around it. `"absolute"` does not: its parent lays out as if
+ * it were not there, and it is placed by those four offsets against the inside
+ * of its containing block's border. Both are *positioned*, which is what makes
+ * a box a containing block.
+ *
+ * `"static"` takes part in the line like `"relative"`, ignores the four
+ * offsets, and is not a containing block: an absolutely positioned box under
+ * it looks past it to the nearest ancestor that is positioned, or to the root.
+ * That is CSS's rule and Yoga 3's, and it is the only way for a box to be
+ * placed against something other than its parent — which is what a tooltip
+ * inside a row of a panel needs to sit against the panel.
+ */
+export type Position = "static" | "relative" | "absolute";
+
 /**
  * What happens to content larger than its box.
  *
@@ -83,8 +125,10 @@ export type Overflow = "visible" | "hidden" | "scroll";
  */
 export type LayoutStyle = {
   readonly flexDirection?: FlexDirection,
+  readonly flexWrap?: FlexWrap,
   readonly justifyContent?: JustifyContent,
   readonly alignItems?: AlignItems,
+  readonly alignContent?: AlignContent,
   readonly alignSelf?: AlignSelf,
   readonly flexGrow?: number,
   readonly flexShrink?: number,
@@ -100,15 +144,21 @@ export type LayoutStyle = {
   readonly paddingRight?: number,
   readonly paddingBottom?: number,
   readonly paddingLeft?: number,
-  readonly margin?: number,
-  readonly marginTop?: number,
-  readonly marginRight?: number,
-  readonly marginBottom?: number,
-  readonly marginLeft?: number,
+  readonly margin?: Margin,
+  readonly marginTop?: Margin,
+  readonly marginRight?: Margin,
+  readonly marginBottom?: Margin,
+  readonly marginLeft?: Margin,
   readonly gap?: number,
   readonly rowGap?: number,
   readonly columnGap?: number,
   readonly overflow?: Overflow,
+  readonly position?: Position,
+  /** Offsets: cells, or a percentage of the parent's inside. Negative is allowed. */
+  readonly top?: Dimension,
+  readonly right?: Dimension,
+  readonly bottom?: Dimension,
+  readonly left?: Dimension,
   /**
    * The first content row a scrolling box shows.
    *
@@ -132,7 +182,12 @@ export type LayoutStyle = {
  */
 export type LayoutNode = {
   style: LayoutStyle,
-  children: Array<LayoutNode>,
+  /**
+   * Read-only here because layout never adds or removes a child. That is also
+   * what lets the renderer's `TuiNode`, whose children are `TuiNode`s, be laid
+   * out as a `LayoutNode`: a mutable array would be invariant in its element.
+   */
+  readonly children: $ReadOnlyArray<LayoutNode>,
   /** Cells the node's own frame occupies on each edge; a border is 1. */
   borderWidth: number,
   measure: ((availableWidth: number, availableHeight: number) => Size) | null,
@@ -235,6 +290,8 @@ export type Size = { readonly width: number, readonly height: number };
 const clamp = (value: number, low: number, high: number): number =>
   Math.min(Math.max(value, low), high);
 
+type Edges<T> = [T, T, T, T];
+
 /** Whether the main axis is horizontal. */
 const isRow = (direction: FlexDirection): boolean =>
   direction === "row" || direction === "row-reverse";
@@ -260,8 +317,73 @@ function resolve(value: Dimension | void, basis: number): number | null {
   return null;
 }
 
+/**
+ * Resolve an offset, which unlike a length may be negative.
+ *
+ * `top: -1` on a badge is how it sits on its parent's border, so the clamp
+ * {@link resolve} applies to a size would move it back inside.
+ */
+function resolveOffset(value: Dimension | void, basis: number): number | null {
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? Math.round(value) : null;
+  }
+  if (typeof value === "string" && value.endsWith("%")) {
+    const percent = Number.parseFloat(value.slice(0, -1));
+    return Number.isFinite(percent) ? Math.round((basis * percent) / 100) : null;
+  }
+  return null;
+}
+
+/** Whether a child is out of its parent's flex line. */
+const isAbsolute = (node: LayoutNode): boolean => node.style.position === "absolute";
+
+/** Whether a node is a containing block for the absolute boxes under it. */
+const isPositioned = (node: LayoutNode): boolean => node.style.position !== "static";
+
+/**
+ * The box an absolutely positioned descendant is placed against: the padding
+ * box of its nearest positioned ancestor, in frame coordinates.
+ */
+type ContainingBlock = {
+  readonly x: number,
+  readonly y: number,
+  readonly width: number,
+  readonly height: number,
+};
+
+/** A node's padding box — inside its border, not inside its padding. */
+function paddingBox(node: LayoutNode): ContainingBlock {
+  const border = node.borderWidth;
+  return {
+    x: node.x + border,
+    y: node.y + border,
+    width: Math.max(0, node.width - border * 2),
+    height: Math.max(0, node.height - border * 2),
+  };
+}
+
+/**
+ * How far a relatively positioned child is drawn from where the line put it.
+ *
+ * `left` wins over `right` and `top` over `bottom` when both are given, which
+ * is CSS's rule for a box whose width is already decided.
+ */
+function relativeShift(style: LayoutStyle, width: number, height: number): [number, number] {
+  // A static box is exactly where its line put it. The offsets are not an
+  // error on one, only unread — which is what lets a caller flip `position`
+  // without also deleting the props it had.
+  if (style.position === "static") {
+    return [0, 0];
+  }
+  const left = resolveOffset(style.left, width);
+  const right = resolveOffset(style.right, width);
+  const top = resolveOffset(style.top, height);
+  const bottom = resolveOffset(style.bottom, height);
+  return [left ?? (right != null ? -right : 0), top ?? (bottom != null ? -bottom : 0)];
+}
+
 /** Padding on each edge, with the shorthand applied first. */
-function padding(style: LayoutStyle): [number, number, number, number] {
+function padding(style: LayoutStyle): Edges<number> {
   const all = style.padding ?? 0;
   return [
     style.paddingTop ?? all,
@@ -272,7 +394,7 @@ function padding(style: LayoutStyle): [number, number, number, number] {
 }
 
 /** Margin on each edge, with the shorthand applied first. */
-function margin(style: LayoutStyle): [number, number, number, number] {
+function margin(style: LayoutStyle): Edges<Margin> {
   const all = style.margin ?? 0;
   return [
     style.marginTop ?? all,
@@ -282,6 +404,21 @@ function margin(style: LayoutStyle): [number, number, number, number] {
   ];
 }
 
+/** The fixed part of a margin. `auto` is resolved only by the flex parent. */
+function marginCells(value: Margin): number {
+  return value === "auto" ? 0 : value;
+}
+
+/** A margin tuple with every `auto` edge treated as zero cells. */
+function fixedMargins(edges: Edges<Margin>): Edges<number> {
+  return [
+    marginCells(edges[0]),
+    marginCells(edges[1]),
+    marginCells(edges[2]),
+    marginCells(edges[3]),
+  ];
+}
+
 /** The cells between two children along the main axis. */
 function gapOf(style: LayoutStyle, row: boolean): number {
   const specific = row ? style.columnGap : style.rowGap;
@@ -384,6 +521,16 @@ function measureIntrinsic(node: LayoutNode, availableWidth: number, availableHei
       fixedHeight != null
         ? 0
         : scrollStack(node, innerAvailableWidth, innerAvailableHeight).content;
+  } else if (wraps(style)) {
+    const size = wrappedSize(
+      node,
+      fixedWidth != null ? Math.max(0, fixedWidth - insetLeft - insetRight) : innerAvailableWidth,
+      fixedHeight != null
+        ? Math.max(0, fixedHeight - insetTop - insetBottom)
+        : innerAvailableHeight,
+    );
+    contentWidth = size.width;
+    contentHeight = size.height;
   } else {
     const row = isRow(direction(node.style));
     const gap = gapOf(style, row);
@@ -391,7 +538,12 @@ function measureIntrinsic(node: LayoutNode, availableWidth: number, availableHei
     let cross = 0;
     let counted = 0;
     for (const child of node.children) {
-      const [marginTop, marginRight, marginBottom, marginLeft] = margin(child.style);
+      // A child out of the line takes no room in it, so it cannot make its
+      // parent any larger — which is the whole of what `absolute` means.
+      if (isAbsolute(child)) {
+        continue;
+      }
+      const [marginTop, marginRight, marginBottom, marginLeft] = fixedMargins(margin(child.style));
       const size = intrinsicSize(
         child,
         Math.max(0, innerAvailableWidth - marginLeft - marginRight),
@@ -416,6 +568,55 @@ function measureIntrinsic(node: LayoutNode, availableWidth: number, availableHei
   };
 }
 
+/**
+ * The content size of a box that wraps, in the space it is offered.
+ *
+ * The lines it would break into there, each as long as its children and as
+ * deep as its deepest, stacked with the gap between lines. Which is why a
+ * wrapping row offered forty columns can come back narrower than forty and
+ * taller than one line: it is as wide as its widest line.
+ */
+function wrappedSize(node: LayoutNode, width: number, height: number): Size {
+  const row = isRow(direction(node.style));
+  const gap = gapOf(node.style, row);
+  const outer: Array<{ main: number, cross: number }> = [];
+  for (const child of node.children) {
+    if (isAbsolute(child)) {
+      continue;
+    }
+    const [marginTop, marginRight, marginBottom, marginLeft] = fixedMargins(margin(child.style));
+    const size = intrinsicSize(
+      child,
+      Math.max(0, width - marginLeft - marginRight),
+      Math.max(0, height - marginTop - marginBottom),
+    );
+    const outerWidth = size.width + marginLeft + marginRight;
+    const outerHeight = size.height + marginTop + marginBottom;
+    outer.push(
+      row ? { main: outerWidth, cross: outerHeight } : { main: outerHeight, cross: outerWidth },
+    );
+  }
+  const lines = breakLines(
+    outer.map((each) => each.main),
+    row ? width : height,
+    gap,
+  );
+  let main = 0;
+  let cross = 0;
+  for (const line of lines) {
+    let length = Math.max(0, line.length - 1) * gap;
+    let depth = 0;
+    for (const index of line) {
+      length += outer[index].main;
+      depth = Math.max(depth, outer[index].cross);
+    }
+    main = Math.max(main, length);
+    cross += depth;
+  }
+  cross += Math.max(0, lines.length - 1) * gapOf(node.style, !row);
+  return row ? { width: main, height: cross } : { width: cross, height: main };
+}
+
 /** Apply `min*`/`max*` to a resolved length. */
 function clampDimension(
   value: number,
@@ -437,7 +638,7 @@ function clampDimension(
  */
 function distribute(total: number, weights: $ReadOnlyArray<number>): Array<number> {
   const sum = weights.reduce((a, b) => a + b, 0);
-  const out = new Array(weights.length).fill(0);
+  const out = new Array<number>(weights.length).fill(0);
   if (sum <= 0 || total === 0) {
     return out;
   }
@@ -452,11 +653,88 @@ function distribute(total: number, weights: $ReadOnlyArray<number>): Array<numbe
   return out;
 }
 
+/** Whether a box breaks its children onto more than one line. */
+const wraps = (style: LayoutStyle): boolean =>
+  style.flexWrap === "wrap" || style.flexWrap === "wrap-reverse";
+
+/**
+ * Break children, given as their outer main sizes, into lines of `space`.
+ *
+ * Greedy, which is what flexbox specifies: a line takes children until the
+ * next would overflow it. A child larger than a whole line still starts one,
+ * so no child is ever left without a line to be on.
+ */
+function breakLines(
+  sizes: $ReadOnlyArray<number>,
+  space: number,
+  gap: number,
+): Array<Array<number>> {
+  const lines: Array<Array<number>> = [];
+  let line: Array<number> = [];
+  let used = 0;
+  for (let index = 0; index < sizes.length; index += 1) {
+    const size = sizes[index];
+    if (line.length > 0 && used + gap + size > space) {
+      lines.push(line);
+      line = [];
+      used = 0;
+    }
+    used += (line.length > 0 ? gap : 0) + size;
+    line.push(index);
+  }
+  if (line.length > 0) {
+    lines.push(line);
+  }
+  return lines;
+}
+
+/**
+ * Where `alignContent` puts the lines of a wrapping box, given the cross-axis
+ * space they leave: the first line's offset, the extra space between two
+ * lines, and the space `"stretch"` hands out to the lines themselves.
+ *
+ * `"flex-start"` is the default, which is Yoga's and so OpenTUI's; CSS's is
+ * `"stretch"`, and a box copied from a stylesheet with no `alignContent` will
+ * pack its lines at the top here where a browser would spread them.
+ */
+function alignLines(
+  alignment: AlignContent | void,
+  spare: number,
+  count: number,
+): [number, number, number] {
+  const free = Math.max(0, spare);
+  switch (alignment) {
+    case "center":
+      return [Math.floor(free / 2), 0, 0];
+    case "flex-end":
+      return [free, 0, 0];
+    case "stretch":
+      return [0, 0, free];
+    case "space-between":
+      return count > 1 ? [0, Math.floor(free / (count - 1)), 0] : [0, 0, 0];
+    case "space-around": {
+      const each = count > 0 ? Math.floor(free / count) : 0;
+      return [Math.floor(each / 2), each, 0];
+    }
+    case "space-evenly": {
+      const each = Math.floor(free / (count + 1));
+      return [each, each, 0];
+    }
+    default:
+      return [0, 0, 0];
+  }
+}
+
 /**
  * Lay `node` out into the border box at `x`, `y`, `width` by `height`.
  *
  * Writes `x`, `y`, `width` and `height` onto every node in the subtree. The
  * caller decides the root's box, which for a terminal is the whole screen.
+ *
+ * `containing` is the containing block the nearest positioned ancestor offers,
+ * and only this module passes it: a caller laying out a root has no ancestor,
+ * and a root that is `"static"` is then its own containing block — the screen,
+ * which is where a box with no positioned ancestor is placed in CSS as well.
  */
 export function layout(
   node: LayoutNode,
@@ -464,6 +742,7 @@ export function layout(
   y: number,
   width: number,
   height: number,
+  containing: ContainingBlock | null = null,
 ): void {
   node.x = x;
   node.y = y;
@@ -485,6 +764,10 @@ export function layout(
   }
 
   const style = node.style;
+  // What an absolute box anywhere under this one is placed against, until a
+  // positioned descendant offers another. Decided here, after this node's own
+  // box is, because a containing block is a box and not a promise of one.
+  const block = isPositioned(node) || containing == null ? paddingBox(node) : containing;
   const [insetTop, insetRight, insetBottom, insetLeft] = insets(node);
   const contentX = x + insetLeft;
   const contentY = y + insetTop;
@@ -492,7 +775,7 @@ export function layout(
   const contentHeight = Math.max(0, height - insetTop - insetBottom);
 
   if (style.overflow === "scroll") {
-    layoutScroll(node, contentX, contentY, contentWidth, contentHeight);
+    layoutScroll(node, contentX, contentY, contentWidth, contentHeight, block);
     return;
   }
 
@@ -502,141 +785,360 @@ export function layout(
   const mainSpace = row ? contentWidth : contentHeight;
   const crossSpace = row ? contentHeight : contentWidth;
   const gap = gapOf(style, row);
-  const children = node.children;
+  // The flex line is the children that are in it. The filter is skipped when
+  // there is nothing to filter, which is every box that has no absolutely
+  // positioned child: a list rebuilt per frame per box would be the cost of a
+  // feature most trees do not use.
+  const children = node.children.some(isAbsolute)
+    ? node.children.filter((child) => !isAbsolute(child))
+    : node.children;
 
   // Pass one: every child's base main size, and the outer margins around it.
   const margins = children.map((child) => margin(child.style));
+  const resolvedMargins = margins.map((edges) => fixedMargins(edges));
   const bases = children.map((child, index) => {
-    const [marginTop, marginRight, marginBottom, marginLeft] = margins[index];
+    const [marginTop, marginRight, marginBottom, marginLeft] = resolvedMargins[index];
     const availableWidth = Math.max(0, contentWidth - marginLeft - marginRight);
     const availableHeight = Math.max(0, contentHeight - marginTop - marginBottom);
     const basis = resolve(child.style.flexBasis, mainSpace);
     if (basis != null) {
       return basis;
     }
-    const fixed = resolve(row ? child.style.width : child.style.height, mainSpace);
-    if (fixed != null) {
-      return fixed;
+    const fixedMain = resolve(row ? child.style.width : child.style.height, mainSpace);
+    if (fixedMain != null) {
+      return fixedMain;
     }
     const size = intrinsicSize(child, availableWidth, availableHeight);
     return row ? size.width : size.height;
   });
 
   const outerMain = (index: number): number => {
-    const [marginTop, marginRight, marginBottom, marginLeft] = margins[index];
+    const [marginTop, marginRight, marginBottom, marginLeft] = resolvedMargins[index];
     return bases[index] + (row ? marginLeft + marginRight : marginTop + marginBottom);
   };
 
-  const used =
-    children.reduce((total, _, index) => total + outerMain(index), 0) +
-    Math.max(0, children.length - 1) * gap;
-  const free = mainSpace - used;
-
-  // Pass two: grow into the space left over, or shrink to fit into what there
-  // is. Shrinking is weighted by the base size as CSS specifies, so a wide
-  // child gives up more columns than a narrow one with the same `flexShrink`.
-  const mainSizes = bases.slice();
-  if (free > 0) {
-    const grow = children.map((child) => Math.max(0, child.style.flexGrow ?? 0));
-    const shares = distribute(free, grow);
-    for (let i = 0; i < children.length; i += 1) {
-      mainSizes[i] += shares[i];
+  const justify = style.justifyContent ?? "flex-start";
+  const parentAlign = style.alignItems ?? "stretch";
+
+  // Lay one flex line out: grow or shrink it into the main axis, distribute
+  // what is left, and align each child within the line's share of the cross
+  // axis, which starts `crossOrigin` cells in and is `lineCross` deep. A box
+  // that does not wrap has one line, all of it.
+  const placeLine = (line: $ReadOnlyArray<number>, crossOrigin: number, lineCross: number) => {
+    const used =
+      line.reduce((total, index) => total + outerMain(index), 0) +
+      Math.max(0, line.length - 1) * gap;
+    const free = mainSpace - used;
+
+    // Pass two: grow into the space left over, or shrink to fit into what there
+    // is. Shrinking is weighted by the base size as CSS specifies, so a wide
+    // child gives up more columns than a narrow one with the same `flexShrink`.
+    const mainSizes = bases.slice();
+    if (free > 0) {
+      const grow = line.map((index) => Math.max(0, children[index].style.flexGrow ?? 0));
+      const shares = distribute(free, grow);
+      for (let i = 0; i < line.length; i += 1) {
+        mainSizes[line[i]] += shares[i];
+      }
+    } else if (free < 0) {
+      const weights = line.map((index) => shrinkOf(children[index].style, row) * bases[index]);
+      const shares = distribute(-free, weights);
+      for (let i = 0; i < line.length; i += 1) {
+        mainSizes[line[i]] = Math.max(0, mainSizes[line[i]] - shares[i]);
+      }
+    }
+
+    // Whatever main-axis space the children did not take, `justifyContent`
+    // decides what to do with.
+    const consumed =
+      line.reduce(
+        (total, index) =>
+          total +
+          mainSizes[index] +
+          (row
+            ? resolvedMargins[index][3] + resolvedMargins[index][1]
+            : resolvedMargins[index][0] + resolvedMargins[index][2]),
+        0,
+      ) +
+      Math.max(0, line.length - 1) * gap;
+    const slack = Math.max(0, mainSpace - consumed);
+
+    const placed = resolvedMargins.map((edges) => edges.slice());
+    const autoMain: Array<[number, number]> = [];
+    if (slack > 0) {
+      for (const index of line) {
+        const edges = margins[index];
+        if (row) {
+          if (edges[3] === "auto") autoMain.push([index, 3]);
+          if (edges[1] === "auto") autoMain.push([index, 1]);
+        } else {
+          if (edges[0] === "auto") autoMain.push([index, 0]);
+          if (edges[2] === "auto") autoMain.push([index, 2]);
+        }
+      }
     }
-  } else if (free < 0) {
-    const weights = children.map((child, index) => shrinkOf(child.style, row) * bases[index]);
-    const shares = distribute(-free, weights);
-    for (let i = 0; i < children.length; i += 1) {
-      mainSizes[i] = Math.max(0, mainSizes[i] - shares[i]);
+    const justifySlack = autoMain.length === 0 ? slack : 0;
+    const autoMainShares = distribute(
+      slack,
+      autoMain.map(() => 1),
+    );
+    for (let index = 0; index < autoMain.length; index += 1) {
+      const [childIndex, edge] = autoMain[index];
+      placed[childIndex][edge] += autoMainShares[index];
     }
-  }
 
-  // Whatever main-axis space the children did not take, `justifyContent`
-  // decides what to do with.
-  const consumed =
-    mainSizes.reduce(
-      (total, size, index) =>
-        total +
-        size +
-        (row ? margins[index][3] + margins[index][1] : margins[index][0] + margins[index][2]),
-      0,
-    ) +
-    Math.max(0, children.length - 1) * gap;
-  const slack = Math.max(0, mainSpace - consumed);
-  const justify = style.justifyContent ?? "flex-start";
-  let cursor = 0;
-  let between = gap;
-  if (justify === "center") {
-    cursor = Math.floor(slack / 2);
-  } else if (justify === "flex-end") {
-    cursor = slack;
-  } else if (justify === "space-between" && children.length > 1) {
-    between = gap + Math.floor(slack / (children.length - 1));
-  } else if (justify === "space-around" && children.length > 0) {
-    const each = Math.floor(slack / children.length);
-    cursor = Math.floor(each / 2);
-    between = gap + each;
-  } else if (justify === "space-evenly" && children.length > 0) {
-    const each = Math.floor(slack / (children.length + 1));
-    cursor = each;
-    between = gap + each;
-  }
+    let cursor = 0;
+    let between = gap;
+    if (justify === "center") {
+      cursor = Math.floor(justifySlack / 2);
+    } else if (justify === "flex-end") {
+      cursor = justifySlack;
+    } else if (justify === "space-between" && line.length > 1) {
+      between = gap + Math.floor(justifySlack / (line.length - 1));
+    } else if (justify === "space-around" && line.length > 0) {
+      const each = Math.floor(justifySlack / line.length);
+      cursor = Math.floor(each / 2);
+      between = gap + each;
+    } else if (justify === "space-evenly" && line.length > 0) {
+      const each = Math.floor(justifySlack / (line.length + 1));
+      cursor = each;
+      between = gap + each;
+    }
 
-  const order = reverse ? children.map((_, i) => i).reverse() : children.map((_, i) => i);
-  const parentAlign = style.alignItems ?? "stretch";
+    const order = reverse ? line.slice().reverse() : line;
 
-  for (const index of order) {
-    const child = children[index];
-    const [marginTop, marginRight, marginBottom, marginLeft] = margins[index];
-    const mainMarginStart = row ? marginLeft : marginTop;
-    const mainMarginEnd = row ? marginRight : marginBottom;
-    const crossMarginStart = row ? marginTop : marginLeft;
-    const crossMarginEnd = row ? marginBottom : marginRight;
-
-    const align = (() => {
-      const own = child.style.alignSelf ?? "auto";
-      return own === "auto" ? parentAlign : own;
-    })();
-
-    const crossAvailable = Math.max(0, crossSpace - crossMarginStart - crossMarginEnd);
-    const fixedCross = resolve(row ? child.style.height : child.style.width, crossSpace);
-    let crossSize: number;
-    if (fixedCross != null) {
-      crossSize = fixedCross;
-    } else if (align === "stretch") {
-      crossSize = crossAvailable;
-    } else {
-      const size = intrinsicSize(
+    for (const index of order) {
+      const child = children[index];
+      const [marginTop, marginRight, marginBottom, marginLeft] = placed[index];
+      const mainMarginStart = row ? marginLeft : marginTop;
+      const mainMarginEnd = row ? marginRight : marginBottom;
+      const crossMarginStart = row ? marginTop : marginLeft;
+      const crossMarginEnd = row ? marginBottom : marginRight;
+      const crossStartEdge = row ? 0 : 3;
+      const crossEndEdge = row ? 2 : 1;
+      const autoCrossStart = margins[index][crossStartEdge] === "auto";
+      const autoCrossEnd = margins[index][crossEndEdge] === "auto";
+      const hasAutoCross = autoCrossStart || autoCrossEnd;
+
+      const align = (() => {
+        const own = child.style.alignSelf ?? "auto";
+        return own === "auto" ? parentAlign : own;
+      })();
+
+      const crossAvailable = Math.max(0, lineCross - crossMarginStart - crossMarginEnd);
+      const fixedCross = resolve(row ? child.style.height : child.style.width, crossSpace);
+      let crossSize: number;
+      if (fixedCross != null) {
+        crossSize = fixedCross;
+      } else if (align === "stretch" && !hasAutoCross) {
+        crossSize = crossAvailable;
+      } else {
+        const size = intrinsicSize(
+          child,
+          row ? mainSizes[index] : crossAvailable,
+          row ? crossAvailable : mainSizes[index],
+        );
+        crossSize = row ? size.height : size.width;
+      }
+      crossSize = Math.min(crossSize, crossAvailable);
+
+      let crossOffset = crossOrigin + crossMarginStart;
+      if (hasAutoCross) {
+        const remaining = Math.max(0, lineCross - crossSize - crossMarginStart - crossMarginEnd);
+        const autoCrossShares = distribute(remaining, [
+          autoCrossStart ? 1 : 0,
+          autoCrossEnd ? 1 : 0,
+        ]);
+        crossOffset += autoCrossShares[0];
+      } else if (align === "center") {
+        crossOffset += Math.floor((crossAvailable - crossSize) / 2);
+      } else if (align === "flex-end") {
+        crossOffset += crossAvailable - crossSize;
+      }
+
+      const mainStart = cursor + mainMarginStart;
+      const childWidth = row ? mainSizes[index] : crossSize;
+      const childHeight = row ? crossSize : mainSizes[index];
+      const [shiftX, shiftY] = relativeShift(child.style, contentWidth, contentHeight);
+      const childX = (row ? contentX + mainStart : contentX + crossOffset) + shiftX;
+      const childY = (row ? contentY + crossOffset : contentY + mainStart) + shiftY;
+
+      layout(
         child,
-        row ? mainSizes[index] : crossAvailable,
-        row ? crossAvailable : mainSizes[index],
+        childX,
+        childY,
+        clampDimension(childWidth, child.style.minWidth, child.style.maxWidth, contentWidth),
+        clampDimension(childHeight, child.style.minHeight, child.style.maxHeight, contentHeight),
+        block,
       );
-      crossSize = row ? size.height : size.width;
+
+      cursor = mainStart + mainSizes[index] + mainMarginEnd + between;
     }
-    crossSize = Math.min(crossSize, crossAvailable);
+  };
 
-    let crossOffset = crossMarginStart;
-    if (align === "center") {
-      crossOffset += Math.floor((crossAvailable - crossSize) / 2);
-    } else if (align === "flex-end") {
-      crossOffset += crossAvailable - crossSize;
+  if (!wraps(style)) {
+    placeLine(
+      children.map((_, index) => index),
+      0,
+      crossSpace,
+    );
+  } else {
+    // Lines are filled in order until the next child's outer size would not
+    // fit, and a child wider than the whole line gets a line of its own
+    // rather than none. Each line is as deep as its deepest child asks to be,
+    // measured at the main size it started with.
+    const lines = breakLines(
+      bases.map((_, index) => outerMain(index)),
+      mainSpace,
+      gap,
+    );
+    const depths = lines.map((line) =>
+      line.reduce((deepest, index) => {
+        const child = children[index];
+        const [marginTop, marginRight, marginBottom, marginLeft] = resolvedMargins[index];
+        const fixedCross = resolve(row ? child.style.height : child.style.width, crossSpace);
+        const cross =
+          fixedCross ??
+          (row
+            ? intrinsicSize(child, bases[index], Math.max(0, crossSpace - marginTop - marginBottom))
+                .height
+            : intrinsicSize(child, Math.max(0, crossSpace - marginLeft - marginRight), bases[index])
+                .width);
+        return Math.max(
+          deepest,
+          cross + (row ? marginTop + marginBottom : marginLeft + marginRight),
+        );
+      }, 0),
+    );
+    const lineGap = gapOf(style, !row);
+    const spare =
+      crossSpace -
+      depths.reduce((total, depth) => total + depth, 0) -
+      Math.max(0, lines.length - 1) * lineGap;
+    const [first, between, stretch] = alignLines(style.alignContent, spare, lines.length);
+    const extra = distribute(
+      stretch,
+      lines.map(() => 1),
+    );
+    let origin = first;
+    for (let index = 0; index < lines.length; index += 1) {
+      const depth = depths[index] + (extra[index] ?? 0);
+      // `wrap-reverse` stacks the lines from the far edge of the cross axis,
+      // and keeps each line's own contents the right way round.
+      const at = style.flexWrap === "wrap-reverse" ? crossSpace - origin - depth : origin;
+      placeLine(lines[index], at, depth);
+      origin += depth + lineGap + between;
     }
+  }
 
-    const mainStart = cursor + mainMarginStart;
-    const childWidth = row ? mainSizes[index] : crossSize;
-    const childHeight = row ? crossSize : mainSizes[index];
-    const childX = row ? contentX + mainStart : contentX + crossOffset;
-    const childY = row ? contentY + crossOffset : contentY + mainStart;
+  if (children !== node.children) {
+    for (const child of node.children) {
+      if (isAbsolute(child)) {
+        layoutAbsolute(node, child, block);
+      }
+    }
+  }
+}
 
-    layout(
-      child,
-      childX,
-      childY,
-      clampDimension(childWidth, child.style.minWidth, child.style.maxWidth, contentWidth),
-      clampDimension(childHeight, child.style.minHeight, child.style.maxHeight, contentHeight),
-    );
+/**
+ * Place a child that is out of its parent's line.
+ *
+ * Its containing block is the *padding* box — inside the border, not inside
+ * the padding — of its nearest positioned ancestor, which is CSS's rule and
+ * Yoga's, and the reason `top: 0` puts it on the first row inside a frame
+ * rather than on the frame. Every node is positioned unless it says
+ * `position: "static"`, as in OpenTUI, so that ancestor is the parent unless a
+ * static box is in the way.
+ *
+ * Each axis is decided the same way. A size given is that size, and a
+ * percentage is of the containing block. Otherwise both offsets on an axis
+ * stretch it between them, and one or none leaves it the size of its content.
+ * The start offset places it, or failing that the end one; with neither, it
+ * goes where its *parent's* `justifyContent` and `alignItems` would have put a
+ * lone child — Yoga's static position, which is about the line the box was
+ * taken out of and so is the parent's even when the containing block is
+ * further up — and not at the corner, which is what makes `position:
+ * "absolute"` with no offsets an overlay centred by the same props that
+ * centre anything else.
+ */
+function layoutAbsolute(parent: LayoutNode, child: LayoutNode, block: ContainingBlock): void {
+  const boxX = block.x;
+  const boxY = block.y;
+  const boxWidth = block.width;
+  const boxHeight = block.height;
+  const style = child.style;
+  const [marginTop, marginRight, marginBottom, marginLeft] = fixedMargins(margin(style));
+  const left = resolveOffset(style.left, boxWidth);
+  const right = resolveOffset(style.right, boxWidth);
+  const top = resolveOffset(style.top, boxHeight);
+  const bottom = resolveOffset(style.bottom, boxHeight);
+
+  const spanWidth = Math.max(0, boxWidth - (left ?? 0) - (right ?? 0) - marginLeft - marginRight);
+  const spanHeight = Math.max(0, boxHeight - (top ?? 0) - (bottom ?? 0) - marginTop - marginBottom);
+  let childWidth = resolve(style.width, boxWidth);
+  let childHeight = resolve(style.height, boxHeight);
+  if (childWidth == null && left != null && right != null) {
+    childWidth = spanWidth;
+  }
+  if (childHeight == null && top != null && bottom != null) {
+    childHeight = spanHeight;
+  }
+  if (childWidth == null || childHeight == null) {
+    const size = intrinsicSize(child, childWidth ?? spanWidth, childHeight ?? spanHeight);
+    childWidth = childWidth ?? Math.min(size.width, spanWidth);
+    childHeight = childHeight ?? size.height;
+  }
+  childWidth = clampDimension(childWidth, style.minWidth, style.maxWidth, boxWidth);
+  childHeight = clampDimension(childHeight, style.minHeight, style.maxHeight, boxHeight);
+
+  // The static position, for an axis with no offset on it: where the parent's
+  // own alignment would put a child of this size inside its padding.
+  const own = paddingBox(parent);
+  const [padTop, padRight, padBottom, padLeft] = padding(parent.style);
+  const flexDirection = direction(parent.style);
+  const row = isRow(flexDirection);
+  const reverse = flexDirection === "row-reverse" || flexDirection === "column-reverse";
+  const place = (
+    alignment: string,
+    flipped: boolean,
+    start: number,
+    space: number,
+    size: number,
+    marginStart: number,
+    marginEnd: number,
+  ): number => {
+    const free = space - size - marginStart - marginEnd;
+    const toEnd = alignment === "flex-end" ? !flipped : alignment !== "center" && flipped;
+    if (alignment === "center") {
+      return start + marginStart + Math.floor(free / 2);
+    }
+    return toEnd ? start + marginStart + free : start + marginStart;
+  };
+  const justify = parent.style.justifyContent ?? "flex-start";
+  const ownAlign = style.alignSelf ?? "auto";
+  const align = ownAlign === "auto" ? (parent.style.alignItems ?? "stretch") : ownAlign;
+  const innerWidth = Math.max(0, own.width - padLeft - padRight);
+  const innerHeight = Math.max(0, own.height - padTop - padBottom);
+  const staticX = row
+    ? place(justify, reverse, own.x + padLeft, innerWidth, childWidth, marginLeft, marginRight)
+    : place(align, false, own.x + padLeft, innerWidth, childWidth, marginLeft, marginRight);
+  const staticY = row
+    ? place(align, false, own.y + padTop, innerHeight, childHeight, marginTop, marginBottom)
+    : place(justify, reverse, own.y + padTop, innerHeight, childHeight, marginTop, marginBottom);
 
-    cursor = mainStart + mainSizes[index] + mainMarginEnd + between;
+  let childX = staticX;
+  if (left != null) {
+    childX = boxX + left + marginLeft;
+  } else if (right != null) {
+    childX = boxX + boxWidth - right - marginRight - childWidth;
+  }
+  let childY = staticY;
+  if (top != null) {
+    childY = boxY + top + marginTop;
+  } else if (bottom != null) {
+    childY = boxY + boxHeight - bottom - marginBottom - childHeight;
   }
+  layout(child, childX, childY, childWidth, childHeight, block);
 }
 
 /**
@@ -668,7 +1170,14 @@ export function layout(
  * seventy-six are — which is the property the whole component exists for, and
  * the reason this is not `overflow: "hidden"` with a margin on top.
  */
-function layoutScroll(node: LayoutNode, x: number, y: number, width: number, height: number): void {
+function layoutScroll(
+  node: LayoutNode,
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+  block: ContainingBlock,
+): void {
   const children = node.children;
   const stack = scrollStack(node, width, height);
   const content = stack.content;
@@ -696,10 +1205,10 @@ function layoutScroll(node: LayoutNode, x: number, y: number, width: number, hei
       break;
     }
     const child = children[index];
-    const [, marginRight, , marginLeft] = margin(child.style);
+    const [, marginRight, , marginLeft] = fixedMargins(margin(child.style));
     const available = Math.max(0, width - marginLeft - marginRight);
     const childWidth = Math.min(available, resolve(child.style.width, width) ?? available);
-    layout(child, x + marginLeft, y + top - offset, childWidth, stack.heights[index]);
+    layout(child, x + marginLeft, y + top - offset, childWidth, stack.heights[index], block);
     count += 1;
   }
   node.scrollFirst = first;
@@ -747,7 +1256,9 @@ function scrollStack(node: LayoutNode, width: number, height: number): ScrollInd
   const gap = gapOf(node.style, false);
   let stack = node.scrollIndex;
   if (stack == null || stack.width !== width || stack.view !== height || stack.gap !== gap) {
-    stack = {
+    // Annotated rather than inferred: a literal's `from: 0` would otherwise
+    // be typed as the number zero for the rest of this function.
+    const fresh: ScrollIndex = {
       width,
       view: height,
       gap,
@@ -756,6 +1267,7 @@ function scrollStack(node: LayoutNode, width: number, height: number): ScrollInd
       heights: [],
       content: 0,
     };
+    stack = fresh;
     node.scrollIndex = stack;
   }
 
@@ -796,15 +1308,15 @@ function scrollStack(node: LayoutNode, width: number, height: number): ScrollInd
     let cursor = 0;
     if (stack.from > 0) {
       const previous = children[stack.from - 1];
-      const [, , previousBottom] = margin(previous.style);
+      const [, , previousBottom] = fixedMargins(margin(previous.style));
       cursor = stack.tops[stack.from - 1] + stack.heights[stack.from - 1] + previousBottom + gap;
     }
     for (let index = stack.from; index < children.length; index += 1) {
       const child = children[index];
-      const [marginTop, marginRight, marginBottom, marginLeft] = margin(child.style);
+      const [marginTop, marginRight, marginBottom, marginLeft] = fixedMargins(margin(child.style));
       const available = Math.max(0, width - marginLeft - marginRight);
-      const fixed = resolve(child.style.height, height);
-      const own = fixed ?? intrinsicSize(child, available, unbounded).height;
+      const fixedHeight = resolve(child.style.height, height);
+      const own = fixedHeight ?? intrinsicSize(child, available, unbounded).height;
       stack.tops[index] = cursor + marginTop;
       stack.heights[index] = own;
       cursor += marginTop + own + marginBottom + gap;
@@ -819,15 +1331,24 @@ function scrollStack(node: LayoutNode, width: number, height: number): ScrollInd
   return stack;
 }
 
+// Implemented, and asserted as cells in `npm/tui/tui.test.js`: `flexWrap`
+// with `alignContent`; `auto` margins on both axes; and `position` in all
+// three of Yoga 3's values, with an absolute box placed against the padding
+// box of its nearest ancestor that is not `"static"` (or the root). Paint, and
+// so the hit grid, still follow the *tree*: an absolute box is drawn when its
+// parent is, under its parent's `zIndex` order and inside its parent's clip —
+// which is OpenTUI's rule, and CSS's is different: there, `overflow: hidden`
+// on a static box between an absolute one and its containing block does not
+// clip it. Here it does.
+//
 // Not implemented here, on purpose, and tracked rather than discovered:
 //
-// - `flexWrap`. OpenTUI's default is `"no-wrap"` and a terminal layout that
-//   wraps its flex line is rare enough that guessing at the semantics would be
-//   worse than not having them.
-// - `position: "absolute"`. It needs a containing-block concept that nothing
-//   in this package has yet, and every use of it so far has been better served
-//   by a box that grows.
-// - `auto` margins, which are how CSS centres a single child, and which
-//   `justifyContent: "center"` already covers here.
+// - `aspectRatio`. A terminal resolves whole cells, and nothing here has a
+//   fractional layout pass to lean on.
+// - `position` and `flexWrap` inside a scrolling box. Its children are one
+//   column whose heights are kept between frames (see {@link ScrollIndex}),
+//   and a child that is out of it, drawn somewhere other than where it says,
+//   or sharing a row with another, is a second answer to "which rows are in
+//   the window". Both are read there as if they were not given.
 //
-// All three are ubugeeei-prod/uf#314.
+// Both are ubugeeei-prod/uf#314.