@driftengine/ui2d 3.61.0

package/src/uiInput.ts

@@ -0,0 +1,115 @@
+/** Routing: a pointer and a keyboard turned into hover, press, focus and one activation. */
+
+import { uiFocusNext, uiFocusPrevious, uiHitTest } from './uiFocus.ts';
+import type { UiNode } from './uiNode.ts';
+
+/**
+ * What the router remembers between calls.
+ *
+ * Held by the caller rather than by the tree, because a tree can be shown in two places — a HUD and
+ * an editor preview of the same tree — and each has its own pointer. It is also what makes the
+ * router testable without a tree at all.
+ */
+export interface UiInput {
+  hovered: UiNode | null;
+  /** The node the pointer went down on, until it comes up again. */
+  pressed: UiNode | null;
+  focused: UiNode | null;
+  /** Whether the pointer was down at the previous call, so an edge can be found. */
+  wasDown: boolean;
+}
+
+export function createUiInput(): UiInput {
+  return { hovered: null, pressed: null, focused: null, wasDown: false };
+}
+
+/**
+ * Route a pointer. Returns the node this call activated, or `null`.
+ *
+ * **An activation is a press and a release on the same node**, which is what every pointer
+ * convention worth copying does and what lets somebody who has pressed the wrong button slide off
+ * it and let go. A release somewhere else clears the press and activates nothing.
+ *
+ * Press moves focus to the node pressed when that node is focusable, and **leaves focus alone
+ * otherwise** — clicking the background should not silently take the keyboard away from a field.
+ *
+ * Allocates nothing, and is meant to be called once per frame with whatever the pointer is doing.
+ */
+export function routeUiPointer(
+  input: UiInput,
+  root: UiNode,
+  x: number,
+  y: number,
+  down: boolean,
+): UiNode | null {
+  const over = uiHitTest(root, x, y);
+  if (input.hovered !== over) {
+    if (input.hovered !== null) input.hovered.hovered = false;
+    if (over !== null) over.hovered = true;
+    input.hovered = over;
+  }
+
+  let activated: UiNode | null = null;
+  if (down && !input.wasDown) {
+    input.pressed = over;
+    if (over !== null) {
+      over.pressed = true;
+      if (over.focusable) setUiFocus(input, over);
+    }
+  } else if (!down && input.wasDown) {
+    if (input.pressed !== null) {
+      input.pressed.pressed = false;
+      if (input.pressed === over) activated = input.pressed;
+    }
+    input.pressed = null;
+  }
+  input.wasDown = down;
+  return activated;
+}
+
+/** Move focus, clearing whatever had it. `null` focuses nothing. */
+export function setUiFocus(input: UiInput, node: UiNode | null): void {
+  input.focused = node;
+}
+
+/**
+ * Route a key. Returns the node it activated, or `null`.
+ *
+ * Three keys and no more: `Tab` and `Shift+Tab` move focus, `Enter` and `' '` activate what has it.
+ * Everything else is the caller's — a text field's own characters, a game's own bindings — and is
+ * reported as unhandled by returning `null` so the caller can tell.
+ *
+ * `key` is a DOM `KeyboardEvent.key`, because that is what a consumer already has and inventing a
+ * second spelling of `Tab` would be a table to keep in step.
+ */
+export function routeUiKey(
+  input: UiInput,
+  root: UiNode,
+  key: string,
+  shift = false,
+): UiNode | null {
+  if (key === 'Tab') {
+    setUiFocus(
+      input,
+      shift ? uiFocusPrevious(root, input.focused) : uiFocusNext(root, input.focused),
+    );
+    return null;
+  }
+  if ((key === 'Enter' || key === ' ') && input.focused !== null) return input.focused;
+  return null;
+}
+
+/**
+ * Forget everything, and clear the flags this router set on the tree.
+ *
+ * For a tree going away or a pointer leaving the window. Without it a node keeps the `hovered` it
+ * had when the cursor left, and draws lit for ever.
+ */
+export function resetUiInput(input: UiInput): void {
+  if (input.hovered !== null) input.hovered.hovered = false;
+  if (input.pressed !== null) input.pressed.pressed = false;
+  input.hovered = null;
+  input.pressed = null;
+  input.focused = null;
+  input.wasDown = false;
+}

package/src/uiLayout.ts

@@ -0,0 +1,157 @@
+/** Two passes over an interface tree: measure what wants a size, then place what got one. */
+
+import type { UiNode } from './uiNode.ts';
+
+/**
+ * Lay a tree out into `x`, `y`, `w`, `h`.
+ *
+ * **Two passes, bottom-up then top-down, and no third.** The measure pass answers what every node
+ * comes to on its own; the place pass hands out the space that exists and distributes what is left
+ * over. A `fit` size that depended on the space it was given would need a third pass and a rule for
+ * when to stop, which is where a layout engine stops being explicable.
+ *
+ * **Allocates nothing.** Every number it produces is written into a `UiRect` the node already owns,
+ * so a tree laid out every frame costs no garbage. That is the rule this whole module is shaped by,
+ * and it is why the node is an object with fields rather than a description that gets resolved into
+ * one.
+ *
+ * **The box is what is *available*, and the root resolves its own size against it** like any other
+ * node: `grow` fills it, a number is that number, and `fit` — the default — comes to whatever its
+ * contents do. So the same call lays out a full-screen HUD and a tooltip, and a caller does not
+ * have to measure a menu itself before it can place one. Nothing is clamped to the box: a `fit`
+ * root with more in it than fits reports the size it really is, because a silently truncated
+ * layout is worse than one that visibly overflows.
+ */
+export function layoutUiTree(root: UiNode, x: number, y: number, w: number, h: number): void {
+  measure(root);
+  place(
+    root,
+    x,
+    y,
+    root.width === 'grow' ? w : root.measuredWidth,
+    root.height === 'grow' ? h : root.measuredHeight,
+  );
+}
+
+/**
+ * What a node comes to on its own, written into `measuredWidth` and `measuredHeight`.
+ *
+ * A `grow` child measures as `fit` here, which is what lets a menu sized to its contents hold a row
+ * that fills it: at measure time there is nothing to take a share of, so the honest answer is the
+ * child's own natural size. The place pass is where `grow` means anything.
+ */
+function measure(node: UiNode): void {
+  let along = 0;
+  let across = 0;
+  let counted = 0;
+  const row = node.direction === 'row';
+  for (const child of node.children) {
+    if (child.hidden) continue;
+    measure(child);
+    if (child.absolute) continue;
+    const childAlong = row ? child.measuredWidth : child.measuredHeight;
+    const childAcross = row ? child.measuredHeight : child.measuredWidth;
+    along += childAlong;
+    if (childAcross > across) across = childAcross;
+    counted += 1;
+  }
+  if (counted > 1) along += node.gap * (counted - 1);
+
+  const padX = node.paddingLeft + node.paddingRight;
+  const padY = node.paddingTop + node.paddingBottom;
+  const contentAlong = counted === 0 ? (row ? node.contentWidth : node.contentHeight) : along;
+  const contentAcross = counted === 0 ? (row ? node.contentHeight : node.contentWidth) : across;
+
+  const fitWidth = (row ? contentAlong : contentAcross) + padX;
+  const fitHeight = (row ? contentAcross : contentAlong) + padY;
+  node.measuredWidth = typeof node.width === 'number' ? node.width : fitWidth;
+  node.measuredHeight = typeof node.height === 'number' ? node.height : fitHeight;
+}
+
+/** Put a node in a box, then put its children in what is left of it. */
+function place(node: UiNode, x: number, y: number, w: number, h: number): void {
+  node.rect.x = x;
+  node.rect.y = y;
+  node.rect.w = w;
+  node.rect.h = h;
+
+  const row = node.direction === 'row';
+  const contentX = x + node.paddingLeft;
+  const contentY = y + node.paddingTop;
+  const contentW = Math.max(0, w - node.paddingLeft - node.paddingRight);
+  const contentH = Math.max(0, h - node.paddingTop - node.paddingBottom);
+  const contentAlong = row ? contentW : contentH;
+  const contentAcross = row ? contentH : contentW;
+
+  /* What the flow children take before anything grows, and how many of them want to grow. */
+  let taken = 0;
+  let growers = 0;
+  let counted = 0;
+  for (const child of node.children) {
+    if (child.hidden || child.absolute) continue;
+    const asked = row ? child.width : child.height;
+    if (asked === 'grow') growers += 1;
+    else taken += row ? child.measuredWidth : child.measuredHeight;
+    counted += 1;
+  }
+  const gaps = counted > 1 ? node.gap * (counted - 1) : 0;
+  const spare = Math.max(0, contentAlong - taken - gaps);
+  const share = growers > 0 ? spare / growers : 0;
+
+  /*
+   * `justify` spends what is left over, and there is nothing left over once something has grown —
+   * which is why a growing child and a `center` on the same node are not a contradiction: the
+   * growing child ate the leftover, so centring has nothing to move.
+   */
+  let cursor = 0;
+  let between = 0;
+  if (growers === 0) {
+    if (node.justify === 'center') cursor = spare / 2;
+    else if (node.justify === 'end') cursor = spare;
+    else if (node.justify === 'between' && counted > 1) between = spare / (counted - 1);
+  }
+
+  for (const child of node.children) {
+    if (child.hidden) continue;
+    if (child.absolute) {
+      placeAbsolute(child, contentX, contentY, contentW, contentH);
+      continue;
+    }
+    const askedAlong = row ? child.width : child.height;
+    const sizeAlong =
+      askedAlong === 'grow' ? share : row ? child.measuredWidth : child.measuredHeight;
+    const askedAcross = row ? child.height : child.width;
+    const naturalAcross = row ? child.measuredHeight : child.measuredWidth;
+    const sizeAcross =
+      node.align === 'stretch' || askedAcross === 'grow' ? contentAcross : naturalAcross;
+    let offAcross = 0;
+    if (node.align === 'center') offAcross = (contentAcross - sizeAcross) / 2;
+    else if (node.align === 'end') offAcross = contentAcross - sizeAcross;
+
+    if (row) {
+      place(child, contentX + cursor, contentY + offAcross, sizeAlong, sizeAcross);
+    } else {
+      place(child, contentX + offAcross, contentY + cursor, sizeAcross, sizeAlong);
+    }
+    cursor += sizeAlong + node.gap + between;
+  }
+}
+
+/**
+ * A child taken out of the flow: at its own offset inside the parent's content box.
+ *
+ * Inside the content box rather than the border box, so an absolute badge in a padded panel sits
+ * where the panel's contents start — which is where a caller reading the padding expects it, and
+ * the only reading under which `x: 0` means the same thing for an absolute child as for a flow one.
+ */
+function placeAbsolute(
+  child: UiNode,
+  contentX: number,
+  contentY: number,
+  contentW: number,
+  contentH: number,
+): void {
+  const w = child.width === 'grow' ? contentW : child.measuredWidth;
+  const h = child.height === 'grow' ? contentH : child.measuredHeight;
+  place(child, contentX + child.x, contentY + child.y, w, h);
+}

package/src/uiNode.ts

@@ -0,0 +1,186 @@
+/** A node of the retained interface tree: what it is, where it wants to be, and what it draws. */
+
+import type { SpriteFrame } from './spriteSheet.ts';
+
+/**
+ * How big a node asks to be along one axis.
+ *
+ * A number is that many units. `fit` is whatever its own contents come to. `grow` takes an equal
+ * share of what is left along the parent's main axis, and behaves as `fit` across it.
+ *
+ * **Three cases rather than a percentage or a flex factor**, and the omission is deliberate: a
+ * percentage of a parent that is itself `fit` is a cycle, and a weighted `grow` is a fourth case
+ * whose only caller so far would be a two-to-one split that two nested nodes already express.
+ */
+export type UiSize = number | 'fit' | 'grow';
+
+/** Where children sit across the parent's main axis. `stretch` gives them the whole cross extent. */
+export type UiAlign = 'start' | 'center' | 'end' | 'stretch';
+
+/** How the leftover along the main axis is spent when no child asked to `grow`. */
+export type UiJustify = 'start' | 'center' | 'end' | 'between';
+
+/** A resolved box, in whatever units the tree is laid out in. Written by `layoutUiTree`. */
+export interface UiRect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+export interface UiNodeOptions {
+  readonly direction?: 'row' | 'column';
+  readonly width?: UiSize;
+  readonly height?: UiSize;
+  /** One number for all four sides. Set the four fields for anything else. */
+  readonly padding?: number;
+  readonly gap?: number;
+  readonly align?: UiAlign;
+  readonly justify?: UiJustify;
+  /** Taken out of the flow and placed at `x`, `y` inside the parent's content box. */
+  readonly absolute?: boolean;
+  readonly x?: number;
+  readonly y?: number;
+  /** What a `fit` node measures when it has no children: a label's text, an icon's size. */
+  readonly contentWidth?: number;
+  readonly contentHeight?: number;
+  readonly hidden?: boolean;
+  readonly background?: ArrayLike<number> | null;
+  /** The sprite slot this node draws from, or `-1` for none. */
+  readonly texture?: number;
+  readonly frame?: SpriteFrame | null;
+  readonly tint?: ArrayLike<number> | null;
+  readonly text?: string;
+  readonly interactive?: boolean;
+  readonly focusable?: boolean;
+  /** For a caller to find its own node again. Not read by anything here. */
+  readonly name?: string;
+}
+
+/**
+ * A node.
+ *
+ * **An object with mutable fields rather than a row of typed arrays**, and this is the one place in
+ * this package where that is the right answer. An interface tree is tens or hundreds of nodes built
+ * once and mutated, not thousands rebuilt per frame — the case struct-of-arrays exists for. What
+ * the hot path needs is that laying one out and drawing it allocates nothing, and both write into
+ * fields that already exist.
+ */
+export interface UiNode {
+  readonly children: UiNode[];
+  parent: UiNode | null;
+
+  direction: 'row' | 'column';
+  width: UiSize;
+  height: UiSize;
+  paddingLeft: number;
+  paddingTop: number;
+  paddingRight: number;
+  paddingBottom: number;
+  gap: number;
+  align: UiAlign;
+  justify: UiJustify;
+  absolute: boolean;
+  x: number;
+  y: number;
+  contentWidth: number;
+  contentHeight: number;
+  hidden: boolean;
+
+  /** Where this node ended up. Meaningless until `layoutUiTree` has run over its root. */
+  readonly rect: UiRect;
+  /** What it measured to along each axis, before the parent distributed anything. */
+  measuredWidth: number;
+  measuredHeight: number;
+
+  background: Float32Array | null;
+  texture: number;
+  frame: SpriteFrame | null;
+  tint: Float32Array | null;
+  text: string;
+
+  interactive: boolean;
+  focusable: boolean;
+  hovered: boolean;
+  pressed: boolean;
+  name: string;
+}
+
+function rgba(source: ArrayLike<number> | null | undefined): Float32Array | null {
+  if (source === null || source === undefined) return null;
+  const out = new Float32Array(4);
+  out[0] = source[0] as number;
+  out[1] = source[1] as number;
+  out[2] = source[2] as number;
+  out[3] = (source[3] ?? 1) as number;
+  return out;
+}
+
+export function createUiNode(options: UiNodeOptions = {}): UiNode {
+  const padding = options.padding ?? 0;
+  return {
+    children: [],
+    parent: null,
+    direction: options.direction ?? 'column',
+    width: options.width ?? 'fit',
+    height: options.height ?? 'fit',
+    paddingLeft: padding,
+    paddingTop: padding,
+    paddingRight: padding,
+    paddingBottom: padding,
+    gap: options.gap ?? 0,
+    align: options.align ?? 'start',
+    justify: options.justify ?? 'start',
+    absolute: options.absolute ?? false,
+    x: options.x ?? 0,
+    y: options.y ?? 0,
+    contentWidth: options.contentWidth ?? 0,
+    contentHeight: options.contentHeight ?? 0,
+    hidden: options.hidden ?? false,
+    rect: { x: 0, y: 0, w: 0, h: 0 },
+    measuredWidth: 0,
+    measuredHeight: 0,
+    background: rgba(options.background),
+    texture: options.texture ?? -1,
+    frame: options.frame ?? null,
+    tint: rgba(options.tint),
+    text: options.text ?? '',
+    interactive: options.interactive ?? false,
+    focusable: options.focusable ?? false,
+    hovered: false,
+    pressed: false,
+    name: options.name ?? '',
+  };
+}
+
+/** Put `child` at the end of `parent`'s children, detaching it from wherever it was. */
+export function addUiChild(parent: UiNode, child: UiNode): UiNode {
+  if (child.parent !== null) removeUiChild(child.parent, child);
+  child.parent = parent;
+  parent.children.push(child);
+  return child;
+}
+
+/** Take `child` out of `parent`. A child that is not there is left alone. */
+export function removeUiChild(parent: UiNode, child: UiNode): void {
+  const at = parent.children.indexOf(child);
+  if (at < 0) return;
+  parent.children.splice(at, 1);
+  child.parent = null;
+}
+
+/** The node named, depth-first from `root`, or `null`. For a caller finding its own tree again. */
+export function uiNodeNamed(root: UiNode, name: string): UiNode | null {
+  if (root.name === name) return root;
+  for (const child of root.children) {
+    const hit = uiNodeNamed(child, name);
+    if (hit !== null) return hit;
+  }
+  return null;
+}
+
+/** Whether a point is inside a node's resolved box. */
+export function uiRectHolds(node: UiNode, x: number, y: number): boolean {
+  const r = node.rect;
+  return x >= r.x && x < r.x + r.w && y >= r.y && y < r.y + r.h;
+}