react-x11 2.11.0 → 2.12.0

package/src/palette.js

@@ -3,7 +3,7 @@
 // Separate from `components/theme.js` because the palette is not a React
 // concern. There are two routes into the tree — `useTheme()` through React
 // context, and a `$token` resolved against the nearest `theme` **prop** by
-// walking the node tree — and the second one lives in `nodes.js`, below the
+// walking the node tree — and the second one lives in `nodes/cascade.js`, below the
 // widget layer. Both have to agree on what "no theme was given" means, so the
 // answer belongs underneath both of them.
 //

package/src/registry.js

@@ -28,8 +28,9 @@ import {
   DRAWN_KINDS,
   CUSTOM_SEMANTIC_NAMES,
   CUSTOM_SELF_DAMAGED,
-  Node,
-} from './nodes.js';
+} from './nodes/kinds.js';
+import { Node } from './nodes/node.js';
+import { markLayoutsHotReloadSession } from './layouts.js';
 
 /** kind -> definition. Insertion-ordered, which is the order errors list. */
 const registry = new Map();
@@ -54,6 +55,9 @@ let hotReloadSession = false;
 /** @internal — called by react-x11/refresh; not part of the public API. */
 export function markHotReloadSession(active = true) {
   hotReloadSession = active;
+  // the layout and placement registries follow the same rule, for the same
+  // module-scope reason
+  markLayoutsHotReloadSession(active);
 }
 
 function assertNode(node, type) {
@@ -225,7 +229,7 @@ export function createRegisteredNode(type, props, app, hostContext) {
   const definition = registry.get(type);
   if (!definition) return undefined;
   const node = assertNode(definition.create(props, app, hostContext), type);
-  // read by Node.insertBefore — carried on the instance so nodes.js needs
+  // read by Node.insertBefore — carried on the instance so src/nodes/ needs
   // no import from here
   if (!definition.childrenAllowed) node._childrenAllowed = false;
   return node;

package/src/styles.js

@@ -6,6 +6,11 @@
 import { cssColorStraight } from 'ntk';
 
 import { parseBoxShadow, parseLinearGradient } from './decorations.js';
+import {
+  validateGridValue,
+  GRID_CONTAINER_PROPS,
+  GRID_ITEM_PROPS,
+} from './grid.js';
 import { Yoga } from './yoga.js';
 
 const FLEX_DIRECTION = {
@@ -47,8 +52,34 @@ const POSITION = {
   absolute: Yoga.POSITION_TYPE_ABSOLUTE,
 };
 
+/**
+ * Yoga's position type for a `position` value. `static`, `relative` and
+ * `absolute` are yoga's own. Everything else — `sticky`, and every position
+ * registered with `registerPosition` (src/layouts.js) — is laid out in flow
+ * exactly as `relative` is and moved afterwards: placing is not something
+ * layout does (nodes/position.js, `WindowNode._placeNodes`). What differs is the
+ * insets, which are the placement's to read — thresholds, for sticky — so
+ * yoga must never see them as offsets (`applyLayoutStyle`).
+ */
+const positionTypeOf = (v) =>
+  typeof v === 'string' && Object.hasOwn(POSITION, v)
+    ? POSITION[v]
+    : Yoga.POSITION_TYPE_RELATIVE;
+
+/** Whether a `position` is placed after layout rather than by it. */
+const isPlacedPosition = (v) =>
+  v != null && !(typeof v === 'string' && Object.hasOwn(POSITION, v));
+
+/** The properties that are an offset under `relative` and `absolute`, and the
+ *  placement's to read under any other — see `applyLayoutStyle`. */
+const INSETS = new Set(['top', 'right', 'bottom', 'left', 'start', 'end']);
+
+/** `'grid'` is a flex item to yoga: the box takes its place in its parent's
+ *  line like any other, and its own children are the grid's to arrange — a
+ *  layout host (src/grid.js, nodes/layouthost.js). */
 const DISPLAY = {
   flex: Yoga.DISPLAY_FLEX,
+  grid: Yoga.DISPLAY_FLEX,
   none: Yoga.DISPLAY_NONE,
 };
 
@@ -129,10 +160,7 @@ const LAYOUT_APPLIERS = {
   flexGrow: (n, v) => n.setFlexGrow(v ?? 0),
   flexShrink: (n, v) => n.setFlexShrink(v ?? 1),
   flexBasis: (n, v) => n.setFlexBasis(v),
-  position: (n, v) =>
-    n.setPositionType(
-      pick(POSITION, v, 'position') ?? Yoga.POSITION_TYPE_RELATIVE,
-    ),
+  position: (n, v) => n.setPositionType(positionTypeOf(v)),
   // Which way the boxes under this one run. Everything else in this file is
   // physical; this is the one property that decides what "start" means, and
   // yoga inherits it down its own tree — so a `<box>` that sets it mirrors
@@ -455,6 +483,18 @@ const STYLE_PROPS = new Set([
   // the ones that say it. Neither layout nor paint: it changes nothing about
   // this node, only what the blocks under it resolve against.
   'container',
+  // A registered layout algorithm that arranges this node's children — CSS's
+  // `display: layout(name)`, with the algorithm's options written beside the
+  // name — and what a child tells the one arranging it, CSS's child input
+  // properties (docs/styling.md, "Custom layouts"). Layout in every sense
+  // but yoga's: the node side reads them (nodes/layouthost.js).
+  'layout',
+  'layoutItem',
+  // CSS grid's own properties, on a `display: 'grid'` box and on each of its
+  // children (docs/styling.md, "Grid"). Layout in every sense but yoga's, like
+  // the two above: the grid reads them off the style (src/grid.js).
+  ...GRID_CONTAINER_PROPS,
+  ...GRID_ITEM_PROPS,
 ]);
 
 export const isStyleProp = (name) => STYLE_PROPS.has(name);
@@ -497,7 +537,7 @@ const SIZE_QUERY = /^@(width|height)\s*(>=|<=|>|<)\s*(\d+(?:\.\d+)?)$/;
  * *when* it is answered — a container's size is what a layout pass
  * produces, not what one starts from, so the blocks are resolved after the
  * pass and the tree laid out once more if an answer moved
- * (nodes.js, `_resolveContainerQueries`).
+ * (nodes/queries.js, `_resolveContainerQueries`).
  */
 const CONTAINER_QUERY =
   /^@container(?:\s+([A-Za-z_][\w-]*))?\s+(width|height)\s*(>=|<=|>|<)\s*(\d+(?:\.\d+)?)$/;
@@ -618,7 +658,7 @@ export function containerQueryNames(style) {
  * Which of a style's container blocks match, as one string with a character
  * per block in declaration order. What a node remembers between layout
  * passes so a re-resolution runs only when an answer actually moved, and
- * what the oscillation check compares (nodes.js `_resolveContainerQueries`).
+ * what the oscillation check compares (nodes/queries.js `_resolveContainerQueries`).
  */
 export function containerAnswers(style, containers) {
   let out = '';
@@ -690,21 +730,27 @@ function queryMatches(q, size, supports, containers) {
   }
 }
 
+const GRID_VALUES = new Set([...GRID_CONTAINER_PROPS, ...GRID_ITEM_PROPS]);
+
 /**
- * The two style values that are a small language rather than a number, and
- * therefore the two that can be *wrong* rather than merely absent. Parsed in
+ * The style values that are a small language rather than a number — a
+ * gradient, a shadow, and grid's track lists, areas and lines — and
+ * therefore the ones that can be *wrong* rather than merely absent. Parsed in
  * development wherever they are written — including inside a state block,
  * which is the half of the surface a `continue` used to skip — so the error
  * naming the property and the expected spelling arrives at the call site
- * instead of as a blank panel three commits later.
+ * instead of as a blank panel three commits later. A grid value goes through
+ * the parser the layout itself runs (src/grid.js), so the two agree.
  *
  * Tokens are still unresolved here (`$accent` is a colour as far as the
  * grammar is concerned), so this checks the shape and never the colours.
  */
 function validateValue(key, value, where) {
-  if (key !== 'backgroundImage' && key !== 'boxShadow') return;
+  const grid = GRID_VALUES.has(key);
+  if (!grid && key !== 'backgroundImage' && key !== 'boxShadow') return;
   try {
-    if (key === 'backgroundImage') parseLinearGradient(value);
+    if (grid) validateGridValue(key, value);
+    else if (key === 'backgroundImage') parseLinearGradient(value);
     else parseBoxShadow(value);
   } catch (err) {
     // the parser names the property and the grammar; only the call site is
@@ -714,6 +760,22 @@ function validateValue(key, value, where) {
   }
 }
 
+const ALGORITHM_NAME = /^[A-Za-z_][\w-]*$/;
+
+/** A plain object of options — what `layoutItem` is, and what a `layout` or
+ *  a registered `position` written with its options is. */
+const isOptionBag = (v) =>
+  v == null || (typeof v === 'object' && !Array.isArray(v));
+
+/** A `layout` / `position` value: a name, or one written with its options —
+ *  `'masonry'`, `{ name: 'masonry', columns: 3 }`. Whether the name is
+ *  registered is the node's to find out when it resolves the style: an
+ *  algorithm may be registered after the style that names it is written. */
+const isAlgorithm = (v) =>
+  v == null ||
+  (typeof v === 'string' && ALGORITHM_NAME.test(v)) ||
+  (isOptionBag(v) && typeof v.name === 'string' && ALGORITHM_NAME.test(v.name));
+
 function validateStyle(style, where) {
   for (const key of Object.keys(style)) {
     if (isQuery(key)) {
@@ -765,6 +827,28 @@ function validateStyle(style, where) {
           "digits, '_' and '-', not starting with a digit)",
       );
     }
+    if (key === 'layout' && !isAlgorithm(style[key])) {
+      throw new Error(
+        `react-x11: invalid layout ${JSON.stringify(style[key])} in ${where} ` +
+          "(expected a registered name like 'masonry', or { name: 'masonry' } " +
+          "with the layout's options beside it)",
+      );
+    }
+    if (key === 'position' && !isAlgorithm(style[key])) {
+      throw new Error(
+        `react-x11: invalid position ${JSON.stringify(style[key])} in ` +
+          `${where} (expected 'static', 'relative', 'absolute', 'sticky', or ` +
+          'a position registered with registerPosition — its name, or ' +
+          "{ name: '…' } with its options beside it)",
+      );
+    }
+    if (key === 'layoutItem' && !isOptionBag(style[key])) {
+      throw new Error(
+        `react-x11: invalid layoutItem ${JSON.stringify(style[key])} in ` +
+          `${where} (expected an object of the options the layout arranging ` +
+          'this node reads, like { span: 2 })',
+      );
+    }
     if (key === 'flex' && !isFlexShorthand(style[key])) {
       throw new Error(
         `react-x11: invalid flex ${JSON.stringify(style[key])} in ${where} ` +
@@ -882,6 +966,10 @@ const NOT_ANIMATABLE = new Set([
   // nothing is drawn from it, so there is no frame in which a halfway value
   // would be visible — and it may be an object, which does not lerp
   'hitSlop',
+  // a grid's tracks and a child's lines: a count of 3.5 columns, or line
+  // 2.5, is no grid at all, and a track list is a string
+  ...GRID_CONTAINER_PROPS,
+  ...GRID_ITEM_PROPS,
 ]);
 
 export const isAnimatableProp = (name) =>
@@ -1364,7 +1452,7 @@ export function stripTokens(style) {
  * anyone hears about it: mistakes are pushed onto `problems` and the caller
  * decides what one costs. Resolving itself never throws — it runs from a
  * commit and from an X event alike, and only the caller knows whether React
- * is on the stack to route a throw to a boundary (src/nodes.js).
+ * is on the stack to route a throw to a boundary (src/nodes/cascade.js).
  *
  * A cache hit replays the problems it recorded, so the second node to wear a
  * misspelled shared style is reported like the first.
@@ -1658,13 +1746,21 @@ export const createLayoutNode = () => Yoga.Node.create(layoutConfig());
 export function measuringExactly(measure) {
   const cfg = layoutConfig();
   cfg.setPointScaleFactor(0);
+  exactDepth++;
   try {
     return measure();
   } finally {
+    exactDepth--;
     cfg.setPointScaleFactor(1);
   }
 }
 
+let exactDepth = 0;
+
+/** Whether yoga is measuring off the pixel grid right now: a size taken in
+ *  here is not the size the same layout comes to on it. */
+export const isMeasuringExactly = () => exactDepth > 0;
+
 /**
  * The yoga defaults that are not CSS's, written once per node.
  *
@@ -1676,7 +1772,7 @@ export function measuringExactly(measure) {
  * The pair to it is the automatic minimum size — a flex item that may shrink
  * still cannot shrink below its content unless it says so. Yoga has no such
  * rule, so the renderer measures the floors itself; see `Node`'s content
- * floors in nodes.js.
+ * floors in nodes/window/floors.js.
  */
 export function applyLayoutDefaults(yogaNode) {
   yogaNode.setFlexShrink(1);
@@ -1688,15 +1784,41 @@ export function applyLayoutDefaults(yogaNode) {
  */
 export function applyLayoutStyle(yogaNode, props, oldProps = {}) {
   let changed = false;
+  // A placed node's insets — sticky's thresholds, or whatever a registered
+  // position reads them as — are the placement's, never offsets: yoga gets
+  // `undefined` for them, and a node that becomes placed (or stops) has all
+  // six re-sent whether or not they changed. The flip still counts as a
+  // change: the pass it asks for is what places the node.
+  const placed = isPlacedPosition(props.position);
+  const flipped = placed !== isPlacedPosition(oldProps.position);
   for (const key of Object.keys(LAYOUT_APPLIERS)) {
-    if (props[key] !== oldProps[key]) {
-      LAYOUT_APPLIERS[key](yogaNode, props[key]);
+    const moved =
+      key === 'position'
+        ? !samePosition(props.position, oldProps.position)
+        : props[key] !== oldProps[key];
+    if (moved || (flipped && INSETS.has(key))) {
+      LAYOUT_APPLIERS[key](
+        yogaNode,
+        placed && INSETS.has(key) ? undefined : props[key],
+      );
       changed = true;
     }
   }
   return changed;
 }
 
+/** Two `position` values asking for the same thing. A registered one written
+ *  with its options is an object, and an inline object is a new one every
+ *  render — which must not cost a layout pass per commit. */
+function samePosition(a, b) {
+  if (a === b) return true;
+  if (!a || !b || typeof a !== 'object' || typeof b !== 'object') return false;
+  const keys = Object.keys(a);
+  if (keys.length !== Object.keys(b).length) return false;
+  for (const key of keys) if (a[key] !== b[key]) return false;
+  return true;
+}
+
 /** @returns true if any paint-only prop changed */
 export function paintPropsChanged(props, oldProps = {}) {
   for (const key of PAINT_PROPS) {

package/src/svgnodes.js

@@ -12,7 +12,8 @@
 // grain for it.
 import { SvgView } from 'ntk';
 
-import { Node, intrinsicSize } from './nodes.js';
+import { Node } from './nodes/node.js';
+import { intrinsicSize } from './nodes/layout.js';
 import { isLayoutProp, isPaintProp } from './styles.js';
 
 // SVG attributes that are camelCase in SVG itself; every other camelCase

package/src/testing/harness.js

@@ -9,7 +9,7 @@
 
 import React from 'react';
 import { createRoot } from '../Reconciler.js';
-import { setAnimationClock } from '../nodes.js';
+import { setAnimationClock } from '../nodes/animation.js';
 import { setAppearanceForTests } from '../appearance.js';
 
 // A test process must not register with the desktop's live AT-SPI registry —
@@ -383,7 +383,7 @@ let clockInstalled = false;
 /**
  * Drive transitions from a number you control instead of from wall-clock
  * time. `setAnimationClock` exists for exactly this; it was reachable only
- * through a deep import into `src/nodes.js`.
+ * through a deep import into `src/nodes/animation.js`.
  *
  * ```js
  * const clock = withFrameClock();

package/src/textselection.js

@@ -9,7 +9,7 @@
 //
 // **A surface is a `selectable` element, and its participants are whatever
 // under it can answer for its own text.** An element joins by implementing
-// the four accessors in nodes.js (`textContent`, `textIndexAt`,
+// the four accessors in nodes/selectable.js (`textContent`, `textIndexAt`,
 // `textCaretRect`, `textRangeRects`) — `<text>` does, and so does a terminal
 // or a log view written outside this package. There is no registration call
 // and no list of blessed kinds: a document is a tree, and the tree is walked.
@@ -226,7 +226,7 @@ export class TextSelection {
    * pointer is: a press landed on the wrong character and a drag stopped
    * short at half its distance. The X event underneath already carries the
    * device numbers; an event synthesized without one is multiplied up, the
-   * way every other pointer consumer in nodes.js does it.
+   * way every other pointer consumer in src/nodes/ does it.
    */
   devicePoint(ev) {
     const scale = this.node.scale > 0 ? this.node.scale : 1;
@@ -407,7 +407,9 @@ export class TextSelection {
   }
 
   /** Take PRIMARY, which in X is what "there is a selection here" means to
-   * every other application on the display. */
+   * every other application on the display. macOS has no PRIMARY, and the
+   * cocoa backend's clipboard answers the write with nothing
+   * (src/cocoa/app.js) — there, a selection is never a copy. */
   own() {
     if (this.isCollapsed) return;
     takeVisibleSelection(this.node);

package/src/trace-registry.js

@@ -1,6 +1,6 @@
 // The seam between the renderer and the optional debug module.
 //
-// Reconciler.js and nodes.js import this file, so it has to stay safe to
+// Reconciler.js and nodes/window/flush.js import this file, so it has to stay safe to
 // bundle for the browser playground: no node builtins, no side effects,
 // nothing but a registry of live connections and a pair of hook slots. The
 // heavy half (protocol parsing, sinks, file writing) lives in debug.js and

package/src/types/components.d.ts

@@ -125,6 +125,20 @@ export interface Theme {
   direction: 'ltr' | 'rtl';
   paddingX: number;
   paddingY: number;
+  /**
+   * Not a colour: whether the widgets wear the **platform's own control
+   * bezels**. `'auto'` (the default) takes them wherever the backend has
+   * them — today the Cocoa backend, never X11 — `'native'` asks for them
+   * and says so in development where there are none, and `'drawn'` keeps
+   * this library's own rendering everywhere.
+   *
+   * It lives here rather than in `style` because whether an app looks
+   * native is an app-identity decision, not a per-node one;
+   * {@link NativeControlProp.native} is the per-control override, and
+   * `useSupports('nativeControls')` is how application code asks what this
+   * backend can do. See docs/components.md and docs/macos.md.
+   */
+  controls?: 'auto' | 'native' | 'drawn';
 }
 
 export interface ThemeProviderProps {
@@ -194,6 +208,20 @@ export function useDirection(): 'ltr' | 'rtl';
 /** Props a widget passes through to the `<box>` it renders. */
 type WidgetProps = Omit<BoxProps, 'children' | 'style' | 'ref'>;
 
+/**
+ * The per-instance escape hatch from the platform's own control bezel, for
+ * the one custom-branded control in an otherwise native app.
+ *
+ * The policy proper is {@link Theme.controls}; this overrides it for this
+ * control. `false` keeps the drawn rendering — which is what a control
+ * naming its own colours in `style` should say, because a bezel the system
+ * draws ignores them. `true` asks for the bezel regardless of the theme's
+ * policy, and is a development warning on a backend that has none.
+ */
+interface NativeControlProp {
+  native?: boolean;
+}
+
 /**
  * What a value widget's `onChange` receives — one signature across the
  * library, so `onChange={formik.handleChange}` wires to a `Checkbox` exactly
@@ -279,7 +307,7 @@ export const iconNames: readonly IconName[];
 /** The default icon box for a given `fontSize`. */
 export function iconSize(fontSize: number): number;
 
-export interface ButtonProps extends WidgetProps {
+export interface ButtonProps extends WidgetProps, NativeControlProp {
   children?: ReactNode;
   label?: string;
   onPress?: (ev: MouseEvent<DrawnNode>) => void;
@@ -328,7 +356,8 @@ export interface PasswordInputProps extends WidgetProps, NamedWidget {
 }
 export const PasswordInput: ComponentType<PasswordInputProps>;
 
-export interface CheckboxProps extends WidgetProps, NamedWidget {
+export interface CheckboxProps
+  extends WidgetProps, NamedWidget, NativeControlProp {
   children?: ReactNode;
   label?: string;
   checked?: boolean;
@@ -346,7 +375,7 @@ export interface RadioGroupProps<T = unknown> extends WidgetProps, NamedWidget {
 }
 export function RadioGroup<T = unknown>(props: RadioGroupProps<T>): ReactNode;
 
-export interface RadioProps<T = unknown> {
+export interface RadioProps<T = unknown> extends NativeControlProp {
   value: T;
   children?: ReactNode;
   label?: string;
@@ -354,7 +383,8 @@ export interface RadioProps<T = unknown> {
 }
 export function Radio<T = unknown>(props: RadioProps<T>): ReactNode;
 
-export interface SwitchProps extends WidgetProps, NamedWidget {
+export interface SwitchProps
+  extends WidgetProps, NamedWidget, NativeControlProp {
   checked?: boolean;
   onChange?: (ev: WidgetChangeEvent<boolean>) => void;
   disabled?: boolean;
@@ -378,7 +408,8 @@ export interface ProgressBarProps extends WidgetProps {
 }
 export const ProgressBar: ComponentType<ProgressBarProps>;
 
-export interface SliderProps extends WidgetProps, NamedWidget {
+export interface SliderProps
+  extends WidgetProps, NamedWidget, NativeControlProp {
   value?: number;
   min?: number;
   max?: number;
@@ -462,7 +493,8 @@ export const Dialog: ComponentType<DialogProps>;
 /** An option, or a plain value used as both value and label. */
 export type SelectOption<T = unknown> = { value: T; label: string } | T;
 
-export interface SelectProps<T = unknown> extends WidgetProps, NamedWidget {
+export interface SelectProps<T = unknown>
+  extends WidgetProps, NamedWidget, NativeControlProp {
   value?: T;
   options?: readonly SelectOption<T>[];
   onChange?: (ev: WidgetChangeEvent<T>) => void;

package/src/types/elements.d.ts

@@ -222,7 +222,8 @@ export interface SelectionProps<T = DrawnNode> {
   /**
    * `true` makes this element a selection surface: a drag across the text
    * inside it selects, double and triple clicks take a word and a block,
-   * Ctrl+A and Ctrl+C work, and a release takes PRIMARY. It also makes the
+   * Ctrl+A and Ctrl+C work, and on X11 a release takes PRIMARY (macOS has
+   * none: there, only a copy reaches the pasteboard). It also makes the
    * element a focus target, so the keys have somewhere to arrive —
    * `tabIndex={-1}` keeps it out of the Tab cycle.
    *
@@ -649,6 +650,15 @@ export interface BoxProps
 
 /** What `overflow: 'scroll'` adds, on a `<box>` or a `<window>`. */
 export interface ScrollProps {
+  /**
+   * The offsets moved, by any route. The wheel, the keys, a bar and
+   * `scrollTo`/`scrollBy` report inside the call. Layout reports once its
+   * pass is over, after the frame that shows the move: a held `scrollTo`
+   * landing (one made before the pane's first layout, or past the extent
+   * the last pass measured), a `scrollIntoView` resolving, or the offset
+   * pulled back when the content shrinks or the viewport grows under it.
+   * Each report carries the offsets in force when it is delivered.
+   */
   onScroll?: (ev: ScrollEvent) => void;
   /** Fired from layout, so it arrives for a list nobody has scrolled yet. */
   onViewport?: (ev: ViewportEvent) => void;

package/src/types/nodes.d.ts

@@ -123,8 +123,22 @@ export interface ScrollableNode extends DrawnNode {
   readonly scrollY: number;
   readonly contentWidth: number;
   readonly contentHeight: number;
-  /** A number scrolls the vertical axis; an object moves either or both. */
+  /**
+   * A number scrolls the vertical axis; an object moves either or both,
+   * clamped to the content. It answers at once from the extent the last
+   * layout pass measured. While a pass is owed — before the pane's first
+   * layout, or in the commit that added its new rows — whatever it asks past
+   * that extent is held too, and the pass answers it again against the
+   * content it measures, before the frame paints: `scrollTo(Infinity)` from
+   * a layout effect follows new rows to the end in the frame that shows
+   * them. `onScroll` reports the call's answer at once, and the pass's once
+   * that pass is over.
+   */
   scrollTo(to: number | ScrollTarget): void;
+  /**
+   * The same, by a delta. Made while a `scrollTo` is held for the pass, it
+   * moves on from where the pass puts the pane.
+   */
   scrollBy(by: number | ScrollTarget): void;
   /**
    * Is there room to move on the axis a delta names? What the wheel's
@@ -135,7 +149,8 @@ export interface ScrollableNode extends DrawnNode {
   /**
    * Scroll the minimum amount on both axes that makes a descendant fully
    * visible. Safe to call right after that node mounts — the request is
-   * resolved on the next layout pass, when it has geometry.
+   * resolved on the next layout pass, when it has geometry, and `onScroll`
+   * reports the move once that pass is over.
    */
   scrollIntoView(node: DrawnNode): void;
 }

package/src/types/style.d.ts

@@ -37,8 +37,39 @@ export type Align =
   | 'space-around';
 
 export type FlexWrap = 'nowrap' | 'wrap' | 'wrap-reverse';
-export type PositionType = 'static' | 'relative' | 'absolute';
-export type Display = 'flex' | 'none';
+export type PositionType = 'static' | 'relative' | 'absolute' | 'sticky';
+/** `'grid'` lays the box's children out as a CSS grid — see docs/styling.md,
+ *  "Grid"; `'none'` hides the box and everything in it. */
+export type Display = 'flex' | 'grid' | 'none';
+
+/**
+ * A grid line, as CSS's `grid-column` / `grid-row` write it: a number
+ * counting from 1 at the start or from -1 at the end, `'span 2'`, or a
+ * start and an end — `'2 / 4'`, `'1 / -1'`, `'2 / span 3'`.
+ */
+export type GridLine =
+  | number
+  | 'auto'
+  | `span ${number}`
+  | `${number} / ${number}`
+  | `${number}/${number}`
+  | `${number} / span ${number}`
+  | `span ${number} / ${number}`
+  | `${number} / auto`
+  | `auto / ${number}`
+  | `auto / span ${number}`;
+
+export type GridAutoFlow =
+  | 'row'
+  | 'column'
+  | 'dense'
+  | 'row dense'
+  | 'column dense'
+  | 'dense row'
+  | 'dense column';
+
+export type JustifyItems = 'flex-start' | 'center' | 'flex-end' | 'stretch';
+export type JustifySelf = 'auto' | JustifyItems;
 export type Overflow = 'visible' | 'hidden' | 'scroll';
 export type BorderStyle = 'solid' | 'dashed';
 export type PointerEvents = 'auto' | 'none';
@@ -108,7 +139,67 @@ export interface LayoutStyle {
    *  say `minWidth: 0` (or an `overflow` that clips) for that. */
   flexShrink?: number;
   flexBasis?: Dimension;
-  position?: PositionType;
+  /**
+   * `'relative'` (the default) and `'absolute'` move the box by its insets.
+   * `'sticky'` lays it out in flow like `'relative'`, then holds it inside
+   * the nearest scroll pane's edges by its insets — `top: 0` keeps a header
+   * at the top of the pane until its parent scrolls away and takes it
+   * along. A position registered with `registerPosition` (react-x11/host)
+   * is written the same way, by name or with its options, and also lays the
+   * box out in flow and then moves it. Either paints over its siblings of
+   * the same `zIndex`. See docs/styling.md, "Sticky positioning" and
+   * "Custom positions".
+   */
+  position?: import('../host.js').PositionValue;
+  /**
+   * A layout algorithm arranging this box's children in place of flexbox,
+   * by name or written with its options — `'equal-row'`,
+   * `{ name: 'masonry', columns: 3 }`. It runs inside the layout pass; the
+   * box's own `gap`, `justifyContent` and `alignItems` are what it spaces
+   * and aligns by. See docs/styling.md, "Custom layouts".
+   */
+  layout?: import('../host.js').LayoutValue;
+  /** What this box tells the layout arranging it — `masonry`'s `span`. */
+  layoutItem?: import('../host.js').CustomLayoutItem;
+  /**
+   * A `display: 'grid'` box's columns: a CSS track list — `'200px 1fr'`,
+   * `'auto 1fr'`, `'repeat(auto-fill, minmax(200px, 1fr))'` — with lengths
+   * in logical pixels written `px`, `%` of the grid and `fr` shares; or a
+   * number, that many equal columns (`repeat(n, minmax(0, 1fr))`). A list
+   * that would not lay out is an error naming it. See docs/styling.md,
+   * "Grid".
+   */
+  gridTemplateColumns?: number | string;
+  /** …its rows, the same way. */
+  gridTemplateRows?: number | string;
+  /** Named areas: one quoted string per row, as CSS writes them —
+   *  `'"head head" "side main"'` — or an array of the rows. */
+  gridTemplateAreas?: string | readonly string[];
+  /** The size of a column the grid adds for an item placed past its
+   *  template: a track list taken in turn, or a number — a length, here. */
+  gridAutoColumns?: number | string;
+  /** …and of a row, the same way. */
+  gridAutoRows?: number | string;
+  /** How a child with no place of its own is placed: along the rows (the
+   *  default) or the columns — and `dense` to back-fill a hole. */
+  gridAutoFlow?: GridAutoFlow;
+  /** Where each child sits across its area when it is narrower than the
+   *  area; `alignItems` is the other axis. */
+  justifyItems?: JustifyItems;
+  /** A grid child's columns: `2`, `'span 2'`, `'1 / -1'`. */
+  gridColumn?: GridLine;
+  /** …and its rows. */
+  gridRow?: GridLine;
+  /** The name of an area in the grid's `gridTemplateAreas`, or CSS's four
+   *  lines; `gridColumn` and `gridRow` beside it win for their axis. */
+  gridArea?: string | number;
+  /** Where this child sits across its area; `'auto'` is the grid's
+   *  `justifyItems`. */
+  justifySelf?: JustifySelf;
+  /** An offset from the edge — or, under sticky or a registered position,
+   *  the scheme's to read: how close to the scroll pane's edge the box may
+   *  come, for sticky, where a percentage is of the pane's size. The same
+   *  holds for the other five. */
   top?: Length;
   right?: Length;
   bottom?: Length;

package/src/windowstate.js

@@ -3,7 +3,7 @@
 //
 // A `<window>` asks for `fullscreen` or `maximized` and the window manager
 // decides — and it decides on its own account too, when the user hits a
-// hotkey or the titlebar button. `nodes.js` sends the requests; this is the
+// hotkey or the titlebar button. `nodes/window/hints.js` sends the requests; this is the
 // half that reads back what actually happened, plus the two things an app
 // needs that are not states at all: whether it has the keyboard, and whether
 // anyone can see it.