@driftengine/ui2d 3.62.0 → 4.0.0

package/src/uiPointer.ts

@@ -0,0 +1,84 @@
+/**
+ * Who the pointer belongs to, and what a drag is carrying.
+ *
+ * **Capture is the half without which every slider in the interface is wrong in the same way.** A
+ * control being dragged has to keep receiving motion after the pointer leaves its rectangle — that
+ * is what dragging *is* — and a framework that routes purely by hit test cannot express it.
+ *
+ * **A drag records its target as the pointer moves**, rather than hit-testing once at release,
+ * because the release position is the only thing a drop handler could otherwise use and a pointer
+ * that leaves the window never produces one.
+ */
+import type { UiNode } from './uiNode.ts';
+import { uiHitTest } from './uiFocus.ts';
+
+export interface PointerState {
+  /** The node holding the pointer, or null. */
+  captured: UiNode | null;
+  /** Where a drag began, or null when none is in progress. */
+  dragSource: UiNode | null;
+  /** The last node the drag was over, excluding the source itself. */
+  dragTarget: UiNode | null;
+  /** What the drag is carrying. Opaque to this module. */
+  dragPayload: string;
+}
+
+export function createPointerState(): PointerState {
+  return { captured: null, dragSource: null, dragTarget: null, dragPayload: '' };
+}
+
+export function capturePointer(state: PointerState, node: UiNode): void {
+  state.captured = node;
+}
+
+export function releasePointer(state: PointerState): void {
+  state.captured = null;
+}
+
+/**
+ * Who should receive pointer input at this position.
+ *
+ * A captured node receives it wherever the pointer is, including outside the window. Otherwise it
+ * is an ordinary hit test — and while a drag is in progress, the result is remembered as the
+ * prospective drop target.
+ */
+export function pointerTarget(
+  state: PointerState,
+  root: UiNode,
+  x: number,
+  y: number,
+): UiNode | null {
+  if (state.captured !== null) return state.captured;
+  const hit = uiHitTest(root, x, y);
+  if (state.dragSource !== null) state.dragTarget = hit === state.dragSource ? null : hit;
+  return hit;
+}
+
+export function beginDrag(state: PointerState, source: UiNode, payload: string): void {
+  state.dragSource = source;
+  state.dragTarget = null;
+  state.dragPayload = payload;
+}
+
+/** The node a drop would land on, or null. */
+export function dropTarget(state: PointerState): UiNode | null {
+  return state.dragTarget;
+}
+
+/**
+ * Finish a drag and report where it landed. Null when no drag was in progress.
+ *
+ * A null `target` is an ordinary outcome — a drop on nothing — and is reported rather than
+ * suppressed, because a caller often wants to know a drag ended even where it achieved nothing.
+ */
+export function endDrag(
+  state: PointerState,
+): { source: UiNode; target: UiNode | null; payload: string } | null {
+  const source = state.dragSource;
+  if (source === null) return null;
+  const result = { source, target: state.dragTarget, payload: state.dragPayload };
+  state.dragSource = null;
+  state.dragTarget = null;
+  state.dragPayload = '';
+  return result;
+}

package/src/uiScroll.ts

@@ -0,0 +1,90 @@
+/**
+ * Moving a clipping node's contents underneath it.
+ *
+ * **Scrolling is an offset applied at placement, not a transform applied at draw.** `uiLayout.ts`
+ * subtracts it from the content origin, so a scrolled child's rectangle simply is where it is —
+ * and hit testing, focus and clipping keep working without any of them knowing that scrolling
+ * exists. Applied at draw, each of those would need the inverse and one of them would eventually
+ * get it wrong in one direction only.
+ *
+ * **A scroll that moves nothing says so.** Nested containers are the case: a wheel over an inner
+ * list that has reached its end should scroll the outer one rather than stopping dead, and a
+ * caller that cannot tell "consumed" from "already at the end" cannot implement that. The boolean
+ * is the whole mechanism.
+ */
+import type { UiNode } from './uiNode.ts';
+import { uiRectHolds } from './uiNode.ts';
+
+/**
+ * How far this node's contents extend past its own box, along each axis.
+ *
+ * Read from the span `layoutUiTree` measured, which is relative to the content origin and so does
+ * not change as the node scrolls. **Deriving it from placed rectangles plus the live scroll value
+ * is wrong**, and wrong in the one situation it is asked about: after a caller has moved the
+ * scroll, the rectangles still reflect the previous value and the two no longer agree.
+ */
+export function scrollExtent(node: UiNode): { x: number; y: number } {
+  const contentW = Math.max(0, node.rect.w - node.paddingLeft - node.paddingRight);
+  const contentH = Math.max(0, node.rect.h - node.paddingTop - node.paddingBottom);
+  return {
+    x: Math.max(0, node.contentSpanX - contentW),
+    y: Math.max(0, node.contentSpanY - contentH),
+  };
+}
+
+export function clampScroll(node: UiNode): void {
+  const extent = scrollExtent(node);
+  node.scrollX = Math.min(Math.max(0, node.scrollX), extent.x);
+  node.scrollY = Math.min(Math.max(0, node.scrollY), extent.y);
+}
+
+/** Scroll, clamped. Returns whether anything actually moved — see the header for why. */
+export function scrollBy(node: UiNode, dx: number, dy: number): boolean {
+  const beforeX = node.scrollX;
+  const beforeY = node.scrollY;
+  node.scrollX += dx;
+  node.scrollY += dy;
+  clampScroll(node);
+  return node.scrollX !== beforeX || node.scrollY !== beforeY;
+}
+
+/* Reused across calls: this runs per wheel event and the chain is its only allocation. */
+const CHAIN: UiNode[] = [];
+
+/**
+ * Give a wheel to the innermost container under the pointer that can use it, then outwards.
+ *
+ * Innermost first is the order a person expects and the opposite of the order the tree makes
+ * convenient, so the chain is collected on the way down and walked back up. Returns the node that
+ * consumed it, or null when nothing did — which is a caller's signal to let the page have it.
+ */
+export function routeScrollWheel(
+  root: UiNode,
+  x: number,
+  y: number,
+  dx: number,
+  dy: number,
+): UiNode | null {
+  let depth = 0;
+  let walk: UiNode | null = root;
+  while (walk !== null) {
+    CHAIN[depth] = walk;
+    depth += 1;
+    let next: UiNode | null = null;
+    for (let i = walk.children.length - 1; i >= 0; i -= 1) {
+      const child = walk.children[i] as UiNode;
+      if (!child.hidden && uiRectHolds(child, x, y)) {
+        next = child;
+        break;
+      }
+    }
+    walk = next;
+  }
+
+  for (let i = depth - 1; i >= 0; i -= 1) {
+    const node = CHAIN[i] as UiNode;
+    if (!node.clip) continue;
+    if (scrollBy(node, dx, dy)) return node;
+  }
+  return null;
+}

package/src/uiSlice.ts

@@ -0,0 +1,90 @@
+/**
+ * A panel background that stretches without stretching its corners.
+ *
+ * Nine cells: the four corners keep their source size, the four edges stretch along one axis, and
+ * the middle stretches along both. Written into a caller's array as
+ * `x, y, w, h, u0, v0, u1, v1` per cell, in row-major order — top-left, top, top-right, left,
+ * middle, right, bottom-left, bottom, bottom-right — so the middle is always index 4.
+ *
+ * **A box narrower than its own insets scales them down rather than letting them overlap.**
+ * Overlapping corners draw the same alpha twice, which on a translucent panel is a visible seam
+ * exactly where the design was trying to be careful.
+ *
+ * **The source size is a parameter because `SpriteFrame` carries only texture coordinates.** The
+ * insets are in texels, so splitting the frame needs to know what the frame's texels span.
+ */
+import type { SpriteFrame } from './spriteSheet.ts';
+
+/** Floats per placement: x, y, w, h, u0, v0, u1, v1. */
+export const SLICE_STRIDE = 8;
+
+export interface SliceInset {
+  readonly left: number;
+  readonly top: number;
+  readonly right: number;
+  readonly bottom: number;
+}
+
+export function sliceInto(
+  out: Float32Array,
+  frame: SpriteFrame,
+  sourceWidth: number,
+  sourceHeight: number,
+  inset: SliceInset,
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+): number {
+  /*
+   * Scaled down together when the box cannot hold both, so the two corners meet exactly at the
+   * midpoint instead of overlapping. The texture coordinates are deliberately *not* scaled with
+   * them: the corner draws a smaller piece of the box out of the same piece of the source, which
+   * is squashing rather than seaming and is the better of the two wrong pictures available.
+   */
+  const sideX = inset.left + inset.right;
+  const kx = sideX > w && sideX > 0 ? w / sideX : 1;
+  const left = inset.left * kx;
+  const right = inset.right * kx;
+
+  const sideY = inset.top + inset.bottom;
+  const ky = sideY > h && sideY > 0 ? h / sideY : 1;
+  const top = inset.top * ky;
+  const bottom = inset.bottom * ky;
+
+  const colX = [x, x + left, x + w - right];
+  const colW = [left, Math.max(0, w - left - right), right];
+  const rowY = [y, y + top, y + h - bottom];
+  const rowH = [top, Math.max(0, h - top - bottom), bottom];
+
+  const du = frame.u1 - frame.u0;
+  const dv = frame.v1 - frame.v0;
+  const uAt = [
+    frame.u0,
+    frame.u0 + (inset.left / sourceWidth) * du,
+    frame.u1 - (inset.right / sourceWidth) * du,
+    frame.u1,
+  ];
+  const vAt = [
+    frame.v0,
+    frame.v0 + (inset.top / sourceHeight) * dv,
+    frame.v1 - (inset.bottom / sourceHeight) * dv,
+    frame.v1,
+  ];
+
+  let at = 0;
+  for (let r = 0; r < 3; r += 1) {
+    for (let c = 0; c < 3; c += 1) {
+      out[at] = colX[c] as number;
+      out[at + 1] = rowY[r] as number;
+      out[at + 2] = colW[c] as number;
+      out[at + 3] = rowH[r] as number;
+      out[at + 4] = uAt[c] as number;
+      out[at + 5] = vAt[r] as number;
+      out[at + 6] = uAt[c + 1] as number;
+      out[at + 7] = vAt[r + 1] as number;
+      at += SLICE_STRIDE;
+    }
+  }
+  return 9;
+}

package/src/virtualList.ts

@@ -0,0 +1,74 @@
+/**
+ * Which rows a scroll offset makes visible, so that a list costs a screenful rather than a list.
+ *
+ * An asset browser with ten thousand entries has to cost what a screenful costs. Without this the
+ * scene tree is unusable the first time somebody opens a real project, which is the moment nobody
+ * wants to discover it.
+ *
+ * **Overscan is applied before clamping, not after.** Applied after, a window near either end
+ * runs past the row count and a caller indexes rows that do not exist.
+ */
+export interface RowWindow {
+  first: number;
+  count: number;
+}
+
+function clampWindow(first: number, lastExclusive: number, rowCount: number): RowWindow {
+  const lo = Math.max(0, Math.min(rowCount, first));
+  const hi = Math.max(lo, Math.min(rowCount, lastExclusive));
+  return { first: lo, count: hi - lo };
+}
+
+/** Uniform row heights, which is arithmetic. */
+export function visibleRange(
+  scrollY: number,
+  viewHeight: number,
+  rowHeight: number,
+  rowCount: number,
+  overscan: number,
+): RowWindow {
+  if (rowHeight <= 0 || rowCount <= 0) return { first: 0, count: 0 };
+  const top = Math.max(0, scrollY);
+  const first = Math.floor(top / rowHeight) - overscan;
+  const lastExclusive = Math.ceil((top + viewHeight) / rowHeight) + overscan;
+  return clampWindow(first, lastExclusive, rowCount);
+}
+
+/**
+ * Variable row heights, through a prefix-sum table of row tops the caller owns.
+ *
+ * **The caller owns the table** because only the caller knows when a row's height changed, and
+ * recomputing it here every frame would be the cost this module exists to avoid. `offsets` holds
+ * `rowCount + 1` entries: the top of each row, then the bottom of the last.
+ */
+export function visibleRangeVariable(
+  scrollY: number,
+  viewHeight: number,
+  offsets: Float64Array,
+  rowCount: number,
+  overscan: number,
+): RowWindow {
+  if (rowCount <= 0) return { first: 0, count: 0 };
+  const top = Math.max(0, scrollY);
+  const bottom = top + viewHeight;
+
+  /* Largest index whose top is at or before the window's top. */
+  let lo = 0;
+  let hi = rowCount;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if ((offsets[mid] ?? 0) <= top) lo = mid;
+    else hi = mid - 1;
+  }
+  const first = lo - overscan;
+
+  /* Smallest index whose top is at or after the window's bottom. */
+  let a = 0;
+  let b = rowCount;
+  while (a < b) {
+    const mid = (a + b) >> 1;
+    if ((offsets[mid] ?? 0) >= bottom) b = mid;
+    else a = mid + 1;
+  }
+  return clampWindow(first, a + overscan, rowCount);
+}