@motionscript/grids 0.0.0-stage → 0.1.0-alpha.4

package/src/kit/slots/sphere.ts

@@ -0,0 +1,94 @@
+import { slot, type Slot, type SlotInput } from "./slot"
+
+/** `outward` lays each item on the sphere's surface; `billboard` keeps every item facing the viewer. */
+export const SPHERE_FACINGS = ["outward", "billboard"] as const
+export type SphereFacing = (typeof SPHERE_FACINGS)[number]
+
+export const SPHERE_AXES = ["x", "y", "z"] as const
+export type SphereAxis = (typeof SPHERE_AXES)[number]
+
+export interface SphereArrangement {
+  kind: "sphere"
+  radius: number
+  /** Turn about the vertical axis, degrees — positive carries the front to the right. */
+  yaw: number
+  /** Turn about the horizontal axis, degrees — positive brings the top toward the viewer. */
+  pitch: number
+  /** Turn about the view axis, degrees clockwise. */
+  roll: number
+  facing: SphereFacing
+  /** The camera's distance from the sphere's centre plane, px — smaller is more dramatic. */
+  focalLength: number
+  /** How much the back half fades, `0..1`. */
+  depthFade: number
+  /** Hide the items whose faces point away from the viewer. */
+  cullBackfaces: boolean
+  /** Degrees per second of yaw the sphere turns on its own. */
+  spinSpeed: number
+}
+
+const GOLDEN_ANGLE = Math.PI * (3 - Math.sqrt(5))
+const DEG = 180 / Math.PI
+
+/** Point `k` of `count` on the unit sphere — a Fibonacci lattice, as even as `count` points get. */
+export function fibonacciPoint(k: number, count: number): [number, number, number] {
+  if (count <= 1) return [0, 0, 1]
+  const y = 1 - (2 * (k + 0.5)) / count
+  const r = Math.sqrt(Math.max(0, 1 - y * y))
+  const theta = k * GOLDEN_ANGLE
+  return [Math.cos(theta) * r, y, Math.sin(theta) * r]
+}
+
+/** `p` turned by yaw, then pitch, then roll — y-up, z toward the viewer. */
+export function orient(p: readonly [number, number, number], yaw: number, pitch: number, roll: number): [number, number, number] {
+  const [x0, y0, z0] = p
+  const ya = yaw / DEG, pa = pitch / DEG, ra = roll / DEG
+  const x1 = x0 * Math.cos(ya) + z0 * Math.sin(ya)
+  const z1 = -x0 * Math.sin(ya) + z0 * Math.cos(ya)
+  const y2 = y0 * Math.cos(pa) - z1 * Math.sin(pa)
+  const z2 = y0 * Math.sin(pa) + z1 * Math.cos(pa)
+  return [x1 * Math.cos(ra) + y2 * Math.sin(ra), -x1 * Math.sin(ra) + y2 * Math.cos(ra), z2]
+}
+
+export function sphereSlots(arrangement: SphereArrangement, input: SlotInput): Slot[] {
+  const { count } = input
+  const radius = arrangement.radius
+  const yaw = arrangement.yaw + arrangement.spinSpeed * input.time
+  const outward = arrangement.facing === "outward"
+  const slots: Slot[] = []
+  for (let k = 0; k < count; k++) {
+    const q = fibonacciPoint(k, count)
+    const [nx, ny, nz] = orient(q, yaw, arrangement.pitch, arrangement.roll)
+    const s = slot(nx * radius, ny * radius, {
+      kind: "sphere",
+      lat: Math.asin(Math.max(-1, Math.min(1, q[1]))) * DEG,
+      lon: Math.atan2(q[2], q[0]) * DEG,
+      depth: nz,
+    })
+    s.depth = nz * radius
+    if (outward) {
+      // The tilt whose `Rx · Ry` turns a face's normal onto the surface normal.
+      s.rotationY = Math.asin(Math.max(-1, Math.min(1, nx))) * DEG
+      s.rotationX = Math.atan2(ny, nz) * DEG
+    }
+    s.opacity = 1 - arrangement.depthFade * (1 - (nz + 1) / 2)
+    if (outward && arrangement.cullBackfaces && facesAway(s, [nx, ny, nz], arrangement.focalLength)) s.opacity = 0
+    slots.push(s)
+  }
+  return slots
+}
+
+/** Whether an outward face at `s` shows its back to a viewer `focal` px in front of the centre. */
+function facesAway(s: Slot, normal: readonly [number, number, number], focal: number): boolean {
+  if (focal <= 0) return normal[2] < 0
+  return normal[0] * -s.x + normal[1] * -s.y + normal[2] * (focal - s.depth) < 0
+}
+
+/** The yaw and pitch that bring point `index` of `count` round to face the viewer. */
+export function sphereFaceForward(count: number, index: number): { yaw: number; pitch: number } {
+  const [x, y, z] = fibonacciPoint(index, count)
+  return {
+    yaw: -Math.atan2(x, z) * DEG,
+    pitch: Math.atan2(y, Math.hypot(x, z)) * DEG,
+  }
+}

package/src/kit/stagger.ts

@@ -0,0 +1,96 @@
+import { shuffled } from "./random"
+import type { Slot } from "./slots"
+
+/**
+ * The order a per-item effect sweeps through a grid's items. The first five
+ * work on any grid; the rest follow one arrangement's own geometry — rows and
+ * columns of a rectangular grid (or top-to-bottom and left-to-right of any
+ * other), the way round a ring, the way along a path, front to back of a sphere
+ * — and fall back to item order where the grid has no such thing.
+ */
+export const STAGGER_ORDERS = [
+  "index",
+  "reverse",
+  "random",
+  "centerOut",
+  "edgesIn",
+  "row",
+  "column",
+  "angle",
+  "path",
+  "depth",
+] as const
+export type StaggerOrder = (typeof STAGGER_ORDERS)[number]
+
+/** The most of a command's length the offsets may take; the rest is each item's own motion. */
+const MAX_STAGGER = 0.95
+
+/**
+ * Each item's start, `0..1`, as a share of the stagger: `0` goes first, `1`
+ * last, and items that tie go together — a ring revealed `centerOut` from its
+ * centre appears all at once, which is what that means.
+ */
+export function staggerRanks(order: StaggerOrder, slots: readonly Slot[], seed: number): number[] {
+  const n = slots.length
+  const keys = keysOf(order, slots, seed)
+  let min = Infinity
+  let max = -Infinity
+  for (const key of keys) {
+    if (key < min) min = key
+    if (key > max) max = key
+  }
+  const range = max - min
+  if (!(range > 1e-9)) return new Array<number>(n).fill(0)
+  return keys.map((key) => (key - min) / range)
+}
+
+/**
+ * Item progress at command time `t`: each item runs over the same length of
+ * time, starting `rank · stagger` in. The stagger lives inside the command's
+ * duration, so a one-second reveal takes one second for four items or four
+ * hundred.
+ */
+export function staggerProgress(rank: number, t: number, stagger: number): number {
+  const s = Math.max(0, Math.min(MAX_STAGGER, stagger))
+  const p = s === 0 ? t : (t - rank * s) / (1 - s)
+  return p < 0 ? 0 : p > 1 ? 1 : p
+}
+
+function keysOf(order: StaggerOrder, slots: readonly Slot[], seed: number): number[] {
+  switch (order) {
+    case "reverse":
+      return slots.map((_, i) => -i)
+    case "random": {
+      const sequence = shuffled(slots.map((_, i) => i), seed)
+      const keys = new Array<number>(slots.length)
+      sequence.forEach((item, rank) => {
+        keys[item] = rank
+      })
+      return keys
+    }
+    case "centerOut":
+      return slots.map((s) => Math.round(Math.hypot(s.x, s.y, s.depth) * 1000) / 1000)
+    case "edgesIn":
+      return slots.map((s) => -Math.round(Math.hypot(s.x, s.y, s.depth) * 1000) / 1000)
+    case "row":
+      return slots.map((s) => (s.meta.kind === "rectangular" ? s.meta.row : -Math.round(s.y)))
+    case "column":
+      return slots.map((s) => (s.meta.kind === "rectangular" ? s.meta.column : Math.round(s.x)))
+    case "angle":
+      return slots.map((s, i) =>
+        s.meta.kind === "radial" ? s.meta.angle : s.meta.kind === "rectangular" || s.meta.kind === "sphere" ? clockAngle(s) : i
+      )
+    case "path":
+      return slots.map((s, i) => (s.meta.kind === "path" ? s.meta.t : i))
+    case "depth":
+      return slots.map((s, i) => (s.meta.kind === "sphere" ? -s.meta.depth : i))
+    default:
+      return slots.map((_, i) => i)
+  }
+}
+
+/** Degrees clockwise from twelve o'clock to where `s` sits. */
+function clockAngle(s: Slot): number {
+  const angle = (Math.atan2(s.x, s.y) * 180) / Math.PI
+  return angle < 0 ? angle + 360 : angle
+}

package/src/nodes.ts

@@ -0,0 +1,15 @@
+import { PathGrid } from "./path-grid"
+import { RadialGrid } from "./radial-grid"
+import { RectangularGrid } from "./rectangular-grid"
+import { SphereGrid } from "./sphere-grid"
+
+/**
+ * Every node type this package publishes.
+ *
+ * A host registers these by handing the array to an engine —
+ * `new Engine(platform, { nodes: NODES })` — which reads each class's `@node()`
+ * key. Listing class **values** is also what survives bundling: this package
+ * declares `sideEffects: false`, and a document names a node type by string, so
+ * an import kept only for its side effect is exactly what gets shaken out.
+ */
+export const NODES = [RectangularGrid, RadialGrid, PathGrid, SphereGrid]

package/src/path-grid/index.ts

@@ -0,0 +1 @@
+export * from "./path-grid"

package/src/path-grid/path-grid.ts

@@ -0,0 +1,213 @@
+import {
+  command,
+  node,
+  Path,
+  pathOps,
+  PathShape,
+  pathProperty,
+  property,
+  type Command,
+  type CommandArgs,
+  type NodeConfig,
+  type PathData,
+  type Size2D,
+} from "@motionscript/sdk"
+
+import {
+  findNode2D,
+  frameIn,
+  ItemGrid,
+  PATH_SPACINGS,
+  PATH_TEMPLATES,
+  staggerArgs,
+  TRANSITION_STAGGER,
+  templatePath,
+  type ItemGridProps,
+  type PathArrangement,
+  type PathPlacement,
+  type PathSpacing,
+  type PathTemplate,
+  type StaggerArgs,
+} from "../kit"
+
+/** A template, or `custom` for the grid's own {@link PathGrid.path}. */
+export const PATH_GRID_SHAPES = [...PATH_TEMPLATES, "custom"] as const
+export type PathGridShape = (typeof PATH_GRID_SHAPES)[number]
+
+export interface PathGridProps extends ItemGridProps {
+  shape: PathGridShape
+  path: PathData
+  pathNode: string
+  spacing: PathSpacing
+  spacingDistance: number
+  offset: number
+  flowSpeed: number
+  trimStart: number
+  trimEnd: number
+  alignToPath: boolean
+}
+
+const AT_ORIGIN: PathPlacement = { originX: 0, originY: 0, x: 0, y: 0, rotation: 0, scale: 1 }
+
+/** The size a path grid is placed at when nothing says otherwise, since a template is drawn to fill it. */
+const DEFAULT_SIZE = { width: 640, height: 400 }
+
+/**
+ * Children along a path: one of the templates drawn to fill the node's box,
+ * a path of the grid's own, or a `Path` node elsewhere in the scene, followed
+ * wherever it is.
+ *
+ * Items are spaced by distance along the curve, so they sit evenly on a tight
+ * bend and a straight alike. Animating {@link offset} moves them along it — on
+ * a closed path they come round again, which is a conveyor belt for free.
+ */
+@node({
+  key: "pathGrid",
+  parentKey: "node",
+  forkable: true,
+  layout: {
+    children: "freeform",
+    acceptsChildren: true,
+    defaultWidthMode: "fixed",
+    defaultHeightMode: "fixed",
+    defaultWidth: DEFAULT_SIZE.width,
+    defaultHeight: DEFAULT_SIZE.height,
+  },
+  seed: { ...DEFAULT_SIZE },
+})
+export class PathGrid extends ItemGrid<PathGridProps> {
+  @property({ default: "circle", kind: "enum", options: PATH_GRID_SHAPES }) declare shape: PathGridShape
+  /** Used when {@link shape} is `custom`: an SVG path, y-down as SVG writes one, centred on its own bounds. */
+  @pathProperty() declare path: PathData
+  /** A path node to follow instead, by id — the items track it wherever it goes. */
+  @property({ default: "", kind: "nodeRef", nodeTypes: ["path"], animatable: false }) declare pathNode: string
+  @property({ default: "distribute", kind: "enum", options: PATH_SPACINGS }) declare spacing: PathSpacing
+  @property({ default: 80, min: 0, step: 1 }) declare spacingDistance: number
+  /** Share of the path the items are moved along — `1` is once round. */
+  @property({ default: 0, step: 0.01 }) declare offset: number
+  /** Share of the path per second the items travel on their own. */
+  @property({ default: 0, step: 0.01, unit: "/s" }) declare flowSpeed: number
+  @property({ default: 0, min: 0, max: 1, step: 0.01 }) declare trimStart: number
+  @property({ default: 1, min: 0, max: 1, step: 0.01 }) declare trimEnd: number
+  @property({ default: true }) declare alignToPath: boolean
+
+  constructor(props?: NodeConfig<PathGrid, PathGridProps>) {
+    super(props)
+  }
+
+  /** Move the items along the path by `loops` — `1` is once round, and they keep their spacing. */
+  @command({ args: [{ key: "loops", step: 0.25, default: 1 }] })
+  flow(args: CommandArgs<{ loops?: number }> & { duration: number }): Command<PathGridProps> {
+    const loops = args.data?.loops ?? 1
+    return this.to({ data: { offset: this.offset + loops }, duration: args.duration, easing: args.easing })
+  }
+
+  /** Squeeze the items into part of the path, between two shares of its length. */
+  @command({
+    args: [
+      { key: "trimStart", min: 0, max: 1, step: 0.01, default: 0.25 },
+      { key: "trimEnd", min: 0, max: 1, step: 0.01, default: 0.75 },
+    ],
+  })
+  trimTo(args: CommandArgs<{ trimStart?: number; trimEnd?: number }> & { duration: number }): Command<PathGridProps> {
+    return this.to({
+      data: { trimStart: args.data?.trimStart ?? this.trimStart, trimEnd: args.data?.trimEnd ?? this.trimEnd },
+      duration: args.duration,
+      easing: args.easing,
+    })
+  }
+
+  /**
+   * Move the items onto another path — a template, or a `Path` node in the
+   * scene. Each item travels from its place on the old path to its place on the
+   * new one; the path itself is not morphed.
+   */
+  @command({
+    args: [
+      { key: "shape", kind: "enum", options: PATH_GRID_SHAPES, default: "heart" },
+      { key: "pathNode", kind: "nodeRef", nodeTypes: ["path"] },
+      ...staggerArgs(TRANSITION_STAGGER),
+    ],
+  })
+  setPath(args: CommandArgs<{ shape?: PathGridShape; pathNode?: string } & StaggerArgs> & { duration: number }): Command<PathGridProps> {
+    const pathNode = args.data?.pathNode ?? ""
+    const changes: Partial<PathGridProps> = pathNode ? { pathNode } : { shape: args.data?.shape ?? this.shape, pathNode: "" }
+    return this._transitionTo(changes, args)
+  }
+
+  protected override arrangementFor(box: Size2D): PathArrangement {
+    const { path, placement } = this._pathIn(box)
+    return {
+      kind: "path",
+      path,
+      placement,
+      spacing: this.spacing,
+      spacingDistance: this.spacingDistance,
+      offset: this.offset,
+      flowSpeed: this.flowSpeed,
+      trimStart: this.trimStart,
+      trimEnd: this.trimEnd,
+      alignToPath: this.alignToPath,
+    }
+  }
+
+  // A template is drawn to fill the box, so a path grid needs one of its own
+  // rather than hugging items whose places depend on it.
+  protected override applyDefaultSize(props?: { readonly width?: unknown; readonly height?: unknown }): void {
+    if (!props || props.width === undefined) this.applyProp("width", DEFAULT_SIZE.width)
+    if (!props || props.height === undefined) this.applyProp("height", DEFAULT_SIZE.height)
+  }
+
+  private _linked: { data: PathData; width: number; height: number; path: PathData } | null = null
+
+  /** The path the items follow, and where its coordinates land in this grid's frame. */
+  private _pathIn(box: Size2D): { path: PathData; placement: PathPlacement } {
+    const linked = this.pathNode ? findNode2D(this, this.pathNode) : null
+    if (linked instanceof PathShape) {
+      return { path: this._unitPath(linked), placement: { ...AT_ORIGIN, ...frameIn(this, linked) } }
+    }
+    if (linked instanceof Path && pathOps.bounds(linked.data)) {
+      // A `Path` draws its data centred on the data's own bounds, at its own position.
+      const bounds = pathOps.bounds(linked.data)!
+      const frame = frameIn(this, linked)
+      return {
+        path: linked.data,
+        placement: {
+          originX: (bounds.minX + bounds.maxX) / 2,
+          originY: (bounds.minY + bounds.maxY) / 2,
+          ...frame,
+        },
+      }
+    }
+    if (this.shape === "custom") {
+      const bounds = pathOps.bounds(this.path)
+      if (bounds) {
+        return {
+          path: this.path,
+          placement: {
+            ...AT_ORIGIN,
+            originX: (bounds.minX + bounds.maxX) / 2,
+            originY: (bounds.minY + bounds.maxY) / 2,
+            flipY: true,
+          },
+        }
+      }
+    }
+    const template: PathTemplate = this.shape === "custom" ? "circle" : this.shape
+    return { path: templatePath(template, box), placement: AT_ORIGIN }
+  }
+
+  /**
+   * A path node's geometry as it draws it: stored in its unit box, y-down, and
+   * scaled to its laid-out size — kept while neither changes, so the path's
+   * measurement is kept with it.
+   */
+  private _unitPath(shape: PathShape): PathData {
+    const { width, height } = shape.layoutBounds
+    const cached = this._linked
+    if (cached && cached.data === shape.data && cached.width === width && cached.height === height) return cached.path
+    const path = pathOps.anchorCommands(pathOps.anchors(shape.data), (p) => ({ x: p.x * width, y: -p.y * height }))
+    this._linked = { data: shape.data, width, height, path }
+    return path
+  }
+}

package/src/radial-grid/index.ts

@@ -0,0 +1 @@
+export * from "./radial-grid"

package/src/radial-grid/radial-grid.ts

@@ -0,0 +1,90 @@
+import { command, node, property, type Command, type CommandArgs, type NodeConfig } from "@motionscript/sdk"
+
+import {
+  ItemGrid,
+  normalizeOrder,
+  RADIAL_DIRECTIONS,
+  radialTurnToTop,
+  type ItemGridProps,
+  type RadialArrangement,
+  type RadialDirection,
+} from "../kit"
+
+export interface RadialGridProps extends ItemGridProps {
+  radius: number
+  startAngle: number
+  sweep: number
+  direction: RadialDirection
+  rotateItems: boolean
+  spinSpeed: number
+}
+
+/**
+ * Children round a circle, or along an arc of one.
+ *
+ * A full circle spaces the items evenly with none on top of another; an arc
+ * puts one at each end. Angles run clockwise from twelve o'clock, so
+ * {@link turnTo} can bring any item to the top like a dial.
+ */
+@node({
+  key: "radialGrid",
+  parentKey: "node",
+  forkable: true,
+  layout: {
+    children: "freeform",
+    acceptsChildren: true,
+    defaultWidthMode: "hug",
+    defaultHeightMode: "hug",
+  },
+})
+export class RadialGrid extends ItemGrid<RadialGridProps> {
+  @property({ default: 200, min: 0, step: 1 }) declare radius: number
+  @property({ default: 0, step: 1, unit: "°" }) declare startAngle: number
+  @property({ default: 360, min: -360, max: 360, step: 1, unit: "°" }) declare sweep: number
+  @property({ default: "clockwise", kind: "enum", options: RADIAL_DIRECTIONS }) declare direction: RadialDirection
+  @property({ default: false }) declare rotateItems: boolean
+  @property({ default: 0, step: 1, unit: "°/s" }) declare spinSpeed: number
+
+  constructor(props?: NodeConfig<RadialGrid, RadialGridProps>) {
+    super(props)
+  }
+
+  /** Orbit the items round the centre by `degrees` — `360` is one full turn. */
+  @command({ args: [{ key: "degrees", step: 15, unit: "°", default: 360 }] })
+  spin(args: CommandArgs<{ degrees?: number }> & { duration: number }): Command<RadialGridProps> {
+    const degrees = args.data?.degrees ?? 360
+    return this.to({ data: { startAngle: this.startAngle + degrees }, duration: args.duration, easing: args.easing })
+  }
+
+  /** Turn the ring the shorter way round until an item (by its place in the layers) sits at the top. */
+  @command({ args: [{ key: "item", min: 0, step: 1, default: 0 }] })
+  turnTo(args: CommandArgs<{ item?: number }> & { duration: number }): Command<RadialGridProps> {
+    const count = this._itemCount()
+    const slot = normalizeOrder(this.order, count).indexOf(Math.round(args.data?.item ?? 0))
+    const turn = slot < 0 ? 0 : radialTurnToTop(this.arrangementFor(), count, slot)
+    return this.to({ data: { startAngle: this.startAngle + turn }, duration: args.duration, easing: args.easing })
+  }
+
+  @command({ args: [{ key: "radius", min: 0, default: 280 }] })
+  radiusTo(args: CommandArgs<{ radius: number }> & { duration: number }): Command<RadialGridProps> {
+    return this.to({ data: { radius: args.data?.radius ?? this.radius }, duration: args.duration, easing: args.easing })
+  }
+
+  /** Open or close the arc like a fan — from `0` to `360` is a reveal of its own. */
+  @command({ args: [{ key: "sweep", min: -360, max: 360, unit: "°", default: 360 }] })
+  sweepTo(args: CommandArgs<{ sweep: number }> & { duration: number }): Command<RadialGridProps> {
+    return this.to({ data: { sweep: args.data?.sweep ?? this.sweep }, duration: args.duration, easing: args.easing })
+  }
+
+  protected override arrangementFor(): RadialArrangement {
+    return {
+      kind: "radial",
+      radius: this.radius,
+      startAngle: this.startAngle,
+      sweep: this.sweep,
+      direction: this.direction,
+      rotateItems: this.rotateItems,
+      spinSpeed: this.spinSpeed,
+    }
+  }
+}

package/src/rectangular-grid/index.ts

@@ -0,0 +1 @@
+export * from "./rectangular-grid"

package/src/rectangular-grid/rectangular-grid.ts

@@ -0,0 +1,160 @@
+import {
+  command,
+  easeInOut,
+  node,
+  property,
+  type Command,
+  type CommandArgs,
+  type NodeConfig,
+  type Size2D,
+} from "@motionscript/sdk"
+
+import {
+  CELL_MODES,
+  contentBoxOf,
+  FILL_DIRECTIONS,
+  LINE_ALIGNS,
+  ItemGrid,
+  rectangularCell,
+  staggerArgs,
+  TRANSITION_STAGGER,
+  type CellMode,
+  type FillDirection,
+  type ItemGridProps,
+  type LineAlign,
+  type RectangularArrangement,
+  type StaggerArgs,
+} from "../kit"
+
+export interface RectangularGridProps extends ItemGridProps {
+  columns: number
+  fillDirection: FillDirection
+  cellMode: CellMode
+  cellWidth: number
+  cellHeight: number
+  columnGap: number
+  rowGap: number
+  lastLineAlign: LineAlign
+  rowOffset: number
+  columnOffset: number
+}
+
+/**
+ * Children in rows and columns — the grid the other three are variations on.
+ *
+ * Cells are as big as the largest child (`fit`), a size of their own
+ * (`fixed`), or an equal share of the node's box (`fill`), which is also the
+ * room a child set to fill grows into. Shift every other row by half a cell
+ * for a brick bond or a hex pack.
+ */
+@node({
+  key: "rectangularGrid",
+  parentKey: "node",
+  forkable: true,
+  layout: {
+    children: "freeform",
+    acceptsChildren: true,
+    defaultWidthMode: "hug",
+    defaultHeightMode: "hug",
+  },
+})
+export class RectangularGrid extends ItemGrid<RectangularGridProps> {
+  @property({ default: 3, min: 1, step: 1 }) declare columns: number
+  @property({ default: "row", kind: "enum", options: FILL_DIRECTIONS }) declare fillDirection: FillDirection
+  @property({ default: "fit", kind: "enum", options: CELL_MODES }) declare cellMode: CellMode
+  @property({ default: 120, min: 0, step: 1 }) declare cellWidth: number
+  @property({ default: 120, min: 0, step: 1 }) declare cellHeight: number
+  @property({ default: 24, step: 1 }) declare columnGap: number
+  @property({ default: 24, step: 1 }) declare rowGap: number
+  @property({ default: "start", kind: "enum", options: LINE_ALIGNS }) declare lastLineAlign: LineAlign
+  @property({ default: 0, min: -1, max: 1, step: 0.05 }) declare rowOffset: number
+  @property({ default: 0, min: -1, max: 1, step: 0.05 }) declare columnOffset: number
+
+  constructor(props?: NodeConfig<RectangularGrid, RectangularGridProps>) {
+    super(props)
+  }
+
+  /** Re-flow the items into `columns` columns, each moving to its new cell. */
+  @command({ args: [{ key: "columns", min: 1, step: 1, default: 4 }, ...staggerArgs(TRANSITION_STAGGER)] })
+  columnsTo(args: CommandArgs<{ columns: number } & StaggerArgs> & { duration: number }): Command<RectangularGridProps> {
+    const columns = Math.max(1, Math.round(args.data?.columns ?? this.columns))
+    return this._transitionTo({ columns }, args)
+  }
+
+  /** Animate the spacing between columns and rows. */
+  @command({ args: [{ key: "columnGap", default: 48 }, { key: "rowGap", default: 48 }] })
+  gapTo(args: CommandArgs<{ columnGap?: number; rowGap?: number }> & { duration: number }): Command<RectangularGridProps> {
+    const data: Partial<RectangularGridProps> = {}
+    if (args.data?.columnGap !== undefined) data.columnGap = args.data.columnGap
+    if (args.data?.rowGap !== undefined) data.rowGap = args.data.rowGap
+    return this.to({ data, duration: args.duration, easing: args.easing })
+  }
+
+  /**
+   * Animate the cell size, from whatever the cells measure now. The grid
+   * switches to `fixed` cells as it starts, since a size of its own is what
+   * `fixed` means.
+   */
+  @command({ args: [{ key: "cellWidth", min: 0, default: 160 }, { key: "cellHeight", min: 0, default: 160 }] })
+  cellSizeTo(args: CommandArgs<{ cellWidth?: number; cellHeight?: number }> & { duration: number }): Command<RectangularGridProps> {
+    const sizes = this._itemSizes()
+    const from = rectangularCell(this.arrangementFor(), sizes.length, sizes, contentBoxOf(this))
+    const width = args.data?.cellWidth ?? from.width
+    const height = args.data?.cellHeight ?? from.height
+    return this.command<RectangularGridProps>((t) => ({
+      cellMode: "fixed",
+      cellWidth: from.width + (width - from.width) * t,
+      cellHeight: from.height + (height - from.height) * t,
+    }), args.duration, args.easing ?? easeInOut("cubic"))
+  }
+
+  /** Bring one row (from 0 at the top) forward and push the rest back. */
+  @command({
+    args: [
+      { key: "row", min: 0, step: 1, default: 0 },
+      { key: "dim", min: 0, max: 1, step: 0.05, default: 0.7 },
+      { key: "grow", min: 0, max: 1, step: 0.05, default: 0.1 },
+    ],
+  })
+  focusRow(args: CommandArgs<{ row?: number; dim?: number; grow?: number }> & { duration: number }): Command<ItemGridProps> {
+    const slots = this._itemSlots()
+    const row = Math.round(args.data?.row ?? 0)
+    return this._focusOn((i) => slots[i]?.meta.kind === "rectangular" && slots[i].meta.row === row, slots.length, args)
+  }
+
+  /** Bring one column (from 0 at the left) forward and push the rest back. */
+  @command({
+    args: [
+      { key: "column", min: 0, step: 1, default: 0 },
+      { key: "dim", min: 0, max: 1, step: 0.05, default: 0.7 },
+      { key: "grow", min: 0, max: 1, step: 0.05, default: 0.1 },
+    ],
+  })
+  focusColumn(args: CommandArgs<{ column?: number; dim?: number; grow?: number }> & { duration: number }): Command<ItemGridProps> {
+    const slots = this._itemSlots()
+    const column = Math.round(args.data?.column ?? 0)
+    return this._focusOn((i) => slots[i]?.meta.kind === "rectangular" && slots[i].meta.column === column, slots.length, args)
+  }
+
+  protected override arrangementFor(): RectangularArrangement {
+    return {
+      kind: "rectangular",
+      columns: this.columns,
+      fillDirection: this.fillDirection,
+      cellMode: this.cellMode,
+      cellWidth: this.cellWidth,
+      cellHeight: this.cellHeight,
+      columnGap: this.columnGap,
+      rowGap: this.rowGap,
+      lastLineAlign: this.lastLineAlign,
+      rowOffset: this.rowOffset,
+      columnOffset: this.columnOffset,
+    }
+  }
+
+  /** A child set to fill takes its cell, where the cell is not simply the largest child. */
+  protected override itemSpace(count: number, space: Size2D): Size2D {
+    if (this.cellMode === "fit") return space
+    return rectangularCell(this.arrangementFor(), count, [], space)
+  }
+}

package/src/sphere-grid/index.ts

@@ -0,0 +1 @@
+export * from "./sphere-grid"