@motionscript/grids 0.1.0-alpha.5 → 0.1.0-alpha.7

package/src/nodes.ts

@@ -7,9 +7,24 @@ 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
+ * `new Engine(platform, { nodes: NODES })` — which reads each component's key.
+ * Defining a component only *declares* that key: nothing is registered by
+ * importing a module, so a registry holds exactly what its owner asked for.
+ *
+ * Listing the component **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]
+// Typed by name, so the declaration names each component rather than spelling out its type through core.
+type KitNode =
+  | typeof RectangularGrid
+  | typeof RadialGrid
+  | typeof PathGrid
+  | typeof SphereGrid
+
+export const NODES: KitNode[] = [
+  RectangularGrid,
+  RadialGrid,
+  PathGrid,
+  SphereGrid,
+]

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

@@ -1,213 +1,186 @@
 import {
-  command,
-  node,
-  Path,
+  component2d,
   pathOps,
-  PathShape,
-  pathProperty,
-  property,
-  type Command,
-  type CommandArgs,
-  type NodeConfig,
+  Types,
+  type NodeOf,
+  type NodeView,
   type PathData,
   type Size2D,
+  type Values,
+  // Named so the emitted declaration reaches these through the sdk, not core.
+  type Node2D as _Node2D,
+  type Node2DProps as _Node2DProps,
 } 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}. */
+/** A template, or `custom` for the grid's own `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 own = {
+  shape: Types.oneOf(PATH_GRID_SHAPES, { default: "circle" }),
+  /** Used when `shape` is `custom`: an SVG path, y-down as SVG writes one, centred on its own bounds. */
+  path: Types.path,
+  /** A path node to follow instead, by id — the items track it wherever it goes. */
+  pathNode: ItemGrid.nodeRef(["path"]),
+  spacing: Types.oneOf(PATH_SPACINGS, { default: "distribute" }),
+  spacingDistance: Types.number(80, { min: 0, step: 1 }),
+  /** Share of the path the items are moved along — `1` is once round. */
+  offset: Types.number(0, { step: 0.01 }),
+  /** Share of the path per second the items travel on their own. */
+  flowSpeed: Types.number(0, { step: 0.01, unit: "/s" }),
+  trimStart: Types.number(0, { min: 0, max: 1, step: 0.01 }),
+  trimEnd: Types.number(1, { min: 0, max: 1, step: 0.01 }),
+  alignToPath: true,
 }
 
+type Own = Values<typeof own>
+
 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 }
 
+const arranger: ItemGrid.Arranger<Own> = {
+  arrangement: (s, box): PathArrangement => {
+    const { path, placement } = pathIn(s, box)
+    return {
+      kind: "path",
+      path,
+      placement,
+      spacing: s.spacing,
+      spacingDistance: s.spacingDistance,
+      offset: s.offset,
+      flowSpeed: s.flowSpeed,
+      trimStart: s.trimStart,
+      trimEnd: s.trimEnd,
+      alignToPath: s.alignToPath,
+    }
+  },
+}
+
 /**
  * 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
+ * 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.
+ * bend and a straight alike. Animating `offset` moves them along it — on a
+ * closed path they come round again, which is a conveyor belt for free.
  */
-@node({
+export const PathGrid = ItemGrid.define(component2d({
   key: "pathGrid",
-  parentKey: "node",
-  forkable: true,
-  layout: {
-    children: "freeform",
-    acceptsChildren: true,
-    defaultWidthMode: "fixed",
-    defaultHeightMode: "fixed",
-    defaultWidth: DEFAULT_SIZE.width,
-    defaultHeight: DEFAULT_SIZE.height,
+  state: { ...ItemGrid.state, ...own },
+  // 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.
+  defaults: { ...DEFAULT_SIZE },
+  commands: {
+    ...ItemGrid.commands,
+    /** Move the items along the path by `loops` — `1` is once round, and they keep their spacing. */
+    flow: {
+      args: { loops: Types.number(1, { step: 0.25 }) },
+      run: (timeline, s) => timeline.tween({ offset: s.offset + (timeline.args.loops ?? 1) }),
+    },
+    /** Squeeze the items into part of the path, between two shares of its length. */
+    trimTo: {
+      args: {
+        trimStart: ItemGrid.hinted(0.25, { min: 0, max: 1, step: 0.01 }),
+        trimEnd: ItemGrid.hinted(0.75, { min: 0, max: 1, step: 0.01 }),
+      },
+      run: (timeline, s) => timeline.tween({
+        trimStart: timeline.args.trimStart ?? s.trimStart,
+        trimEnd: timeline.args.trimEnd ?? s.trimEnd,
+      }),
+    },
+    /**
+     * 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.
+     */
+    setPath: {
+      args: {
+        shape: ItemGrid.hinted("heart", { kind: "enum", options: PATH_GRID_SHAPES }),
+        pathNode: ItemGrid.nodeRefArg(["path"]),
+        ...staggerArgs(TRANSITION_STAGGER),
+      },
+      run: (timeline, s, children) => {
+        const pathNode = timeline.args.pathNode ?? ""
+        const changes = pathNode ? { pathNode } : { shape: timeline.args.shape ?? s.shape, pathNode: "" }
+        return ItemGrid.transitionTo(timeline as never, s, children, changes)
+      },
+    },
   },
-  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
+  ...ItemGrid.fields(arranger),
+}), arranger)
 
-  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,
-    })
-  }
+export type PathGrid = NodeOf<typeof PathGrid>
+/** What a call or a document row may set. */
+export type PathGridProps = NonNullable<Parameters<typeof PathGrid>[0]>
 
-  /**
-   * 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)
+/** The path the items follow, and where its coordinates land in this grid's frame. */
+function pathIn(s: Own, box: Size2D): { path: PathData; placement: PathPlacement } {
+  const linked = s.pathNode
+  // A document `path` draws its data in its own unit box, at its own position.
+  if (linked?.key === "path") return { path: unitPath(linked), placement: { ...AT_ORIGIN, ...linked.frame } }
+  // A face-value path draws its data centred on the data's own bounds, at its own position.
+  const data = linked?.key === "facePath" ? dataOf(linked) : undefined
+  const bounds = data !== undefined ? pathOps.bounds(data) : null
+  if (linked && data !== undefined && bounds) {
     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,
+      path: data,
+      placement: {
+        originX: (bounds.minX + bounds.maxX) / 2,
+        originY: (bounds.minY + bounds.maxY) / 2,
+        ...linked.frame,
+      },
     }
   }
-
-  // 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)
+  if (s.shape === "custom") {
+    const own = pathOps.bounds(s.path)
+    if (own) {
       return {
-        path: linked.data,
+        path: s.path,
         placement: {
-          originX: (bounds.minX + bounds.maxX) / 2,
-          originY: (bounds.minY + bounds.maxY) / 2,
-          ...frame,
+          ...AT_ORIGIN,
+          originX: (own.minX + own.maxX) / 2,
+          originY: (own.minY + own.maxY) / 2,
+          flipY: true,
         },
       }
     }
-    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 }
   }
+  const template: PathTemplate = s.shape === "custom" ? "circle" : s.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
-  }
+function dataOf(view: NodeView): PathData {
+  return (view.state as { readonly data: PathData }).data
+}
+
+const unitPaths = new WeakMap<NodeView, { data: PathData; width: number; height: number; path: PathData }>()
+
+/**
+ * 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.
+ */
+function unitPath(view: NodeView): PathData {
+  const data = dataOf(view)
+  const { width, height } = view.size
+  const cached = unitPaths.get(view)
+  if (cached && cached.data === data && cached.width === width && cached.height === height) return cached.path
+  const path = pathOps.anchorCommands(pathOps.anchors(data), (p) => ({ x: p.x * width, y: -p.y * height }))
+  unitPaths.set(view, { data, width, height, path })
+  return path
 }

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

@@ -1,90 +1,81 @@
-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"
+  component2d,
+  Types,
+  type NodeOf,
+  type Values,
+  // Named so the emitted declaration reaches these through the sdk, not core.
+  type Node2D as _Node2D,
+  type Node2DProps as _Node2DProps,
+} from "@motionscript/sdk"
+
+import { ItemGrid, normalizeOrder, RADIAL_DIRECTIONS, radialTurnToTop, type RadialArrangement } from "../kit"
+
+const own = {
+  radius: Types.number(200, { min: 0, step: 1 }),
+  startAngle: Types.number(0, { step: 1, unit: "°" }),
+  sweep: Types.number(360, { min: -360, max: 360, step: 1, unit: "°" }),
+  direction: Types.oneOf(RADIAL_DIRECTIONS, { default: "clockwise" }),
+  rotateItems: false,
+  spinSpeed: Types.number(0, { step: 1, unit: "°/s" }),
+}
+
+type Own = Values<typeof own>
 
-export interface RadialGridProps extends ItemGridProps {
-  radius: number
-  startAngle: number
-  sweep: number
-  direction: RadialDirection
-  rotateItems: boolean
-  spinSpeed: number
+function arrangement(s: Own): RadialArrangement {
+  return {
+    kind: "radial",
+    radius: s.radius,
+    startAngle: s.startAngle,
+    sweep: s.sweep,
+    direction: s.direction,
+    rotateItems: s.rotateItems,
+    spinSpeed: s.spinSpeed,
+  }
 }
 
+const arranger: ItemGrid.Arranger<Own> = { arrangement }
+
 /**
  * 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.
+ * puts one at each end. Angles run clockwise from twelve o'clock, so `turnTo`
+ * can bring any item to the top like a dial.
  */
-@node({
+export const RadialGrid = ItemGrid.define(component2d({
   key: "radialGrid",
-  parentKey: "node",
-  forkable: true,
-  layout: {
-    children: "freeform",
-    acceptsChildren: true,
-    defaultWidthMode: "hug",
-    defaultHeightMode: "hug",
+  state: { ...ItemGrid.state, ...own },
+  defaults: ItemGrid.defaults,
+  commands: {
+    ...ItemGrid.commands,
+    /** Orbit the items round the centre by `degrees` — `360` is one full turn. */
+    spin: {
+      args: { degrees: Types.number(360, { step: 15, unit: "°" }) },
+      run: (timeline, s) => timeline.tween({ startAngle: s.startAngle + (timeline.args.degrees ?? 360) }),
+    },
+    /** Turn the ring the shorter way round until an item (by its place in the layers) sits at the top. */
+    turnTo: {
+      args: { item: Types.number(0, { min: 0, step: 1 }) },
+      run: (timeline, s, children) => {
+        const count = children.length
+        const slot = normalizeOrder(s.order, count).indexOf(Math.round(timeline.args.item ?? 0))
+        const turn = slot < 0 ? 0 : radialTurnToTop(arrangement(s), count, slot)
+        return timeline.tween({ startAngle: s.startAngle + turn })
+      },
+    },
+    radiusTo: {
+      args: { radius: ItemGrid.hinted(280, { min: 0 }) },
+      run: (timeline, s) => timeline.tween({ radius: timeline.args.radius ?? s.radius }),
+    },
+    /** Open or close the arc like a fan — from `0` to `360` is a reveal of its own. */
+    sweepTo: {
+      args: { sweep: ItemGrid.hinted(360, { min: -360, max: 360, unit: "°" }) },
+      run: (timeline, s) => timeline.tween({ sweep: timeline.args.sweep ?? s.sweep }),
+    },
   },
-})
-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
+  ...ItemGrid.fields(arranger),
+}), arranger)
 
-  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,
-    }
-  }
-}
+export type RadialGrid = NodeOf<typeof RadialGrid>
+/** What a call or a document row may set. */
+export type RadialGridProps = NonNullable<Parameters<typeof RadialGrid>[0]>