@motionscript/layout-grid 0.0.0-stage → 0.1.0-alpha.3

package/src/sphere-grid/sphere-grid.ts

@@ -0,0 +1,143 @@
+import { command, node, property, type Command, type CommandArgs, type NodeConfig } from "@motionscript/sdk"
+
+import {
+  LayoutGrid,
+  normalizeOrder,
+  SPHERE_AXES,
+  SPHERE_FACINGS,
+  sphereFaceForward,
+  wrapDegrees,
+  type LayoutGridProps,
+  type SphereArrangement,
+  type SphereAxis,
+  type SphereFacing,
+} from "../kit"
+
+export interface SphereGridProps extends LayoutGridProps {
+  radius: number
+  yaw: number
+  pitch: number
+  roll: number
+  facing: SphereFacing
+  focalLength: number
+  depthFade: number
+  cullBackfaces: boolean
+  spinSpeed: number
+}
+
+const AXIS_PROP: Record<SphereAxis, "yaw" | "pitch" | "roll"> = { x: "pitch", y: "yaw", z: "roll" }
+
+/**
+ * Children spread over a sphere — a Fibonacci lattice, as even as any number
+ * of points gets — and seen through a camera of the grid's own, so the far
+ * side is smaller, drawn first, and hidden where a face turns away.
+ *
+ * `outward` lays each item flat on the surface; `billboard` keeps each one
+ * facing the viewer, like labels on a globe. {@link turnTo} brings any item
+ * round to the front.
+ */
+@node({
+  key: "sphereGrid",
+  parentKey: "node",
+  forkable: true,
+  layout: {
+    children: "flow",
+    acceptsChildren: true,
+    defaultWidthMode: "hug",
+    defaultHeightMode: "hug",
+  },
+})
+export class SphereGrid extends LayoutGrid<SphereGridProps> {
+  @property({ default: 220, min: 0, step: 1 }) declare radius: number
+  @property({ default: 0, step: 1, unit: "°" }) declare yaw: number
+  @property({ default: 0, step: 1, unit: "°" }) declare pitch: number
+  @property({ default: 0, step: 1, unit: "°" }) declare roll: number
+  @property({ default: "outward", kind: "enum", options: SPHERE_FACINGS }) declare facing: SphereFacing
+  @property({ default: 900, min: 100, step: 10 }) declare focalLength: number
+  @property({ default: 0.5, min: 0, max: 1, step: 0.05 }) declare depthFade: number
+  @property({ default: false }) declare cullBackfaces: boolean
+  @property({ default: 0, step: 1, unit: "°/s" }) declare spinSpeed: number
+
+  constructor(props?: NodeConfig<SphereGrid, SphereGridProps>) {
+    super(props)
+  }
+
+  /** Turn the sphere about an axis by `degrees` — `y` spins it like a globe. */
+  @command({
+    args: [
+      { key: "axis", kind: "enum", options: SPHERE_AXES, default: "y" },
+      { key: "degrees", step: 15, unit: "°", default: 360 },
+    ],
+  })
+  spin(args: CommandArgs<{ axis?: SphereAxis; degrees?: number }> & { duration: number }): Command<SphereGridProps> {
+    const key = AXIS_PROP[args.data?.axis ?? "y"] ?? "yaw"
+    const degrees = args.data?.degrees ?? 360
+    return this.to({ data: { [key]: this[key] + degrees }, duration: args.duration, easing: args.easing })
+  }
+
+  /** Turn the sphere to a set orientation. */
+  @command({
+    args: [
+      { key: "yaw", unit: "°", default: 45 },
+      { key: "pitch", unit: "°", default: 20 },
+      { key: "roll", unit: "°", default: 0 },
+    ],
+  })
+  orientTo(args: CommandArgs<{ yaw?: number; pitch?: number; roll?: number }> & { duration: number }): Command<SphereGridProps> {
+    return this.to({
+      data: { yaw: args.data?.yaw ?? this.yaw, pitch: args.data?.pitch ?? this.pitch, roll: args.data?.roll ?? this.roll },
+      duration: args.duration,
+      easing: args.easing,
+    })
+  }
+
+  /** Turn the sphere the shorter way until an item (by its place in the layers) faces the viewer. */
+  @command({ args: [{ key: "item", min: 0, step: 1, default: 0 }] })
+  turnTo(args: CommandArgs<{ item?: number }> & { duration: number }): Command<SphereGridProps> {
+    const count = this._itemCount()
+    const slot = normalizeOrder(this.order, count).indexOf(Math.round(args.data?.item ?? 0))
+    if (slot < 0) return this.to({ data: {}, duration: args.duration })
+    const facing = sphereFaceForward(count, slot)
+    // The yaw the clock has added is part of where the item is now.
+    const spun = this.spinSpeed * this.time.total
+    return this.to({
+      data: {
+        yaw: this.yaw + wrapDegrees(facing.yaw - (this.yaw + spun)),
+        pitch: this.pitch + wrapDegrees(facing.pitch - this.pitch),
+        roll: 0,
+      },
+      duration: args.duration,
+      easing: args.easing,
+    })
+  }
+
+  @command({ args: [{ key: "radius", min: 0, default: 300 }] })
+  radiusTo(args: CommandArgs<{ radius: number }> & { duration: number }): Command<SphereGridProps> {
+    return this.to({ data: { radius: args.data?.radius ?? this.radius }, duration: args.duration, easing: args.easing })
+  }
+
+  /** Dolly the camera: a shorter focal length exaggerates the depth, a longer one flattens it. */
+  @command({ args: [{ key: "focalLength", min: 100, default: 600 }] })
+  focalLengthTo(args: CommandArgs<{ focalLength: number }> & { duration: number }): Command<SphereGridProps> {
+    return this.to({
+      data: { focalLength: args.data?.focalLength ?? this.focalLength },
+      duration: args.duration,
+      easing: args.easing,
+    })
+  }
+
+  protected override arrangementFor(): SphereArrangement {
+    return {
+      kind: "sphere",
+      radius: this.radius,
+      yaw: this.yaw,
+      pitch: this.pitch,
+      roll: this.roll,
+      facing: this.facing,
+      focalLength: this.focalLength,
+      depthFade: this.depthFade,
+      cullBackfaces: this.cullBackfaces,
+      spinSpeed: this.spinSpeed,
+    }
+  }
+}

package/README.md

@@ -1,4 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
-If no other versions are published within 30 days, this package and version will be deleted.