@motionscript/grids 0.1.0-alpha.8 → 0.1.0

package/src/kit/slots/path.ts

@@ -1,120 +1,120 @@
-import { pathOps, type PathData, type PathSampler } from "@motionscript/sdk"
-
-import { slot, type Slot, type SlotInput } from "./slot"
-
-/** `distribute` spreads the items over the path; `fixed` sets them a distance apart. */
-export const PATH_SPACINGS = ["distribute", "fixed"] as const
-export type PathSpacing = (typeof PATH_SPACINGS)[number]
-
-/** How path coordinates land in the grid's frame: `origin` of the path goes to `(x, y)`, turned and scaled. */
-export interface PathPlacement {
-  originX: number
-  originY: number
-  /** The path is y-down, as SVG and the editor write one. */
-  flipY?: boolean
-  x: number
-  y: number
-  /** Degrees clockwise. */
-  rotation: number
-  scale: number
-}
-
-export interface PathArrangement {
-  kind: "path"
-  /** y-up, like every path in the library, unless its placement says otherwise. */
-  path: PathData
-  placement: PathPlacement
-  spacing: PathSpacing
-  /** Pixels between items when `spacing` is `fixed`. */
-  spacingDistance: number
-  /** Share of the path the items are moved along; wraps on a closed path. */
-  offset: number
-  /** Share of the path per second the items travel on their own. */
-  flowSpeed: number
-  trimStart: number
-  trimEnd: number
-  /** Turn each item to follow the path's direction. */
-  alignToPath: boolean
-}
-
-const SAMPLERS = new Map<PathData, { sampler: PathSampler; closed: boolean }>()
-const SAMPLER_CACHE = 32
-
-/** A sampler for `path`, kept while the same value keeps arriving — a path is re-read every frame. */
-function measured(path: PathData): { sampler: PathSampler; closed: boolean } {
-  const hit = SAMPLERS.get(path)
-  if (hit) return hit
-  const contours = pathOps.contours(path)
-  const entry = {
-    sampler: pathOps.sampler(path),
-    closed: contours.length === 1 && contours[0].closed,
-  }
-  if (SAMPLERS.size >= SAMPLER_CACHE) SAMPLERS.delete(SAMPLERS.keys().next().value!)
-  SAMPLERS.set(path, entry)
-  return entry
-}
-
-/**
- * Items at even arc-length steps — by distance along the curve rather than the
- * path's own parameter, which bunches them up wherever a curve is tight.
- *
- * On a closed path used whole, `n` items take `n` equal steps and `offset`
- * wraps round, so an animated offset is a loop. Anywhere else the ends are
- * ends: `n` items take `n - 1` steps so both get one, and an item moved past
- * either is hidden rather than piled on it.
- */
-export function pathSlots(arrangement: PathArrangement, input: SlotInput): Slot[] {
-  const { count } = input
-  if (count === 0) return []
-  const { sampler, closed } = measured(arrangement.path)
-  const length = sampler.length
-  const a = clamp01(Math.min(arrangement.trimStart, arrangement.trimEnd))
-  const b = clamp01(Math.max(arrangement.trimStart, arrangement.trimEnd))
-  const start = a * length
-  const span = (b - a) * length
-  const loops = closed && a === 0 && b === 1
-  const offset = arrangement.offset + arrangement.flowSpeed * input.time
-  const place = arrangement.placement
-  const rad = (place.rotation * Math.PI) / 180
-  const cos = Math.cos(rad)
-  const sin = Math.sin(rad)
-
-  const slots: Slot[] = []
-  for (let k = 0; k < count; k++) {
-    let u: number
-    if (arrangement.spacing === "fixed" && span > 0) {
-      u = offset + (k * arrangement.spacingDistance) / span
-    } else if (loops) {
-      u = offset + k / count
-    } else {
-      u = offset + (count === 1 ? 0.5 : k / (count - 1))
-    }
-    let visible = true
-    if (loops) u = u - Math.floor(u)
-    else if (u < -1e-9 || u > 1 + 1e-9) visible = false
-    const at = sampler.frameAt(start + clamp01(u) * span)
-    if (!at) {
-      const s = slot(0, 0, { kind: "path", t: clamp01(u) })
-      s.opacity = 0
-      slots.push(s)
-      continue
-    }
-    // Into the grid's frame: about the path's origin, turned clockwise (y-up).
-    const flip = place.flipY ? -1 : 1
-    const px = (at.x - place.originX) * place.scale
-    const py = (at.y - place.originY) * place.scale * flip
-    const s = slot(
-      place.x + px * cos + py * sin,
-      place.y - px * sin + py * cos,
-      { kind: "path", t: clamp01(u) },
-    )
-    if (arrangement.alignToPath) s.rotation = (-Math.atan2(at.ty * flip, at.tx) * 180) / Math.PI + place.rotation
-    if (!visible) s.opacity = 0
-    slots.push(s)
-  }
-  return slots
-}
-
-function clamp01(v: number): number {
-  return v < 0 ? 0 : v > 1 ? 1 : v
-}
+import { pathOps, type PathData, type PathSampler } from "@motionscript/sdk"
+
+import { slot, type Slot, type SlotInput } from "./slot"
+
+/** `distribute` spreads the items over the path; `fixed` sets them a distance apart. */
+export const PATH_SPACINGS = ["distribute", "fixed"] as const
+export type PathSpacing = (typeof PATH_SPACINGS)[number]
+
+/** How path coordinates land in the grid's frame: `origin` of the path goes to `(x, y)`, turned and scaled. */
+export interface PathPlacement {
+  originX: number
+  originY: number
+  /** The path is y-down, as SVG and the editor write one. */
+  flipY?: boolean
+  x: number
+  y: number
+  /** Degrees clockwise. */
+  rotation: number
+  scale: number
+}
+
+export interface PathArrangement {
+  kind: "path"
+  /** y-up, like every path in the library, unless its placement says otherwise. */
+  path: PathData
+  placement: PathPlacement
+  spacing: PathSpacing
+  /** Pixels between items when `spacing` is `fixed`. */
+  spacingDistance: number
+  /** Share of the path the items are moved along; wraps on a closed path. */
+  offset: number
+  /** Share of the path per second the items travel on their own. */
+  flowSpeed: number
+  trimStart: number
+  trimEnd: number
+  /** Turn each item to follow the path's direction. */
+  alignToPath: boolean
+}
+
+const SAMPLERS = new Map<PathData, { sampler: PathSampler; closed: boolean }>()
+const SAMPLER_CACHE = 32
+
+/** A sampler for `path`, kept while the same value keeps arriving — a path is re-read every frame. */
+function measured(path: PathData): { sampler: PathSampler; closed: boolean } {
+  const hit = SAMPLERS.get(path)
+  if (hit) return hit
+  const contours = pathOps.contours(path)
+  const entry = {
+    sampler: pathOps.sampler(path),
+    closed: contours.length === 1 && contours[0].closed,
+  }
+  if (SAMPLERS.size >= SAMPLER_CACHE) SAMPLERS.delete(SAMPLERS.keys().next().value!)
+  SAMPLERS.set(path, entry)
+  return entry
+}
+
+/**
+ * Items at even arc-length steps — by distance along the curve rather than the
+ * path's own parameter, which bunches them up wherever a curve is tight.
+ *
+ * On a closed path used whole, `n` items take `n` equal steps and `offset`
+ * wraps round, so an animated offset is a loop. Anywhere else the ends are
+ * ends: `n` items take `n - 1` steps so both get one, and an item moved past
+ * either is hidden rather than piled on it.
+ */
+export function pathSlots(arrangement: PathArrangement, input: SlotInput): Slot[] {
+  const { count } = input
+  if (count === 0) return []
+  const { sampler, closed } = measured(arrangement.path)
+  const length = sampler.length
+  const a = clamp01(Math.min(arrangement.trimStart, arrangement.trimEnd))
+  const b = clamp01(Math.max(arrangement.trimStart, arrangement.trimEnd))
+  const start = a * length
+  const span = (b - a) * length
+  const loops = closed && a === 0 && b === 1
+  const offset = arrangement.offset + arrangement.flowSpeed * input.time
+  const place = arrangement.placement
+  const rad = (place.rotation * Math.PI) / 180
+  const cos = Math.cos(rad)
+  const sin = Math.sin(rad)
+
+  const slots: Slot[] = []
+  for (let k = 0; k < count; k++) {
+    let u: number
+    if (arrangement.spacing === "fixed" && span > 0) {
+      u = offset + (k * arrangement.spacingDistance) / span
+    } else if (loops) {
+      u = offset + k / count
+    } else {
+      u = offset + (count === 1 ? 0.5 : k / (count - 1))
+    }
+    let visible = true
+    if (loops) u = u - Math.floor(u)
+    else if (u < -1e-9 || u > 1 + 1e-9) visible = false
+    const at = sampler.frameAt(start + clamp01(u) * span)
+    if (!at) {
+      const s = slot(0, 0, { kind: "path", t: clamp01(u) })
+      s.opacity = 0
+      slots.push(s)
+      continue
+    }
+    // Into the grid's frame: about the path's origin, turned clockwise (y-up).
+    const flip = place.flipY ? -1 : 1
+    const px = (at.x - place.originX) * place.scale
+    const py = (at.y - place.originY) * place.scale * flip
+    const s = slot(
+      place.x + px * cos + py * sin,
+      place.y - px * sin + py * cos,
+      { kind: "path", t: clamp01(u) },
+    )
+    if (arrangement.alignToPath) s.rotation = (-Math.atan2(at.ty * flip, at.tx) * 180) / Math.PI + place.rotation
+    if (!visible) s.opacity = 0
+    slots.push(s)
+  }
+  return slots
+}
+
+function clamp01(v: number): number {
+  return v < 0 ? 0 : v > 1 ? 1 : v
+}

package/src/kit/slots/radial.ts

@@ -1,62 +1,62 @@
-import { slot, type Slot, type SlotInput } from "./slot"
-
-export const RADIAL_DIRECTIONS = ["clockwise", "counterclockwise"] as const
-export type RadialDirection = (typeof RADIAL_DIRECTIONS)[number]
-
-export interface RadialArrangement {
-  kind: "radial"
-  radius: number
-  /** Where the first item sits, degrees clockwise from twelve o'clock. */
-  startAngle: number
-  /** How much of the circle the items span, degrees. */
-  sweep: number
-  direction: RadialDirection
-  /** Turn each item so its top faces away from the centre. */
-  rotateItems: boolean
-  /** Degrees per second the ring turns on its own. */
-  spinSpeed: number
-}
-
-/**
- * The angle of each of `count` slots, clockwise from twelve o'clock. A full
- * circle divides by the count, so the last item does not land on the first; an
- * arc divides by one less, so both ends get an item. In between the divisor
- * slides from one to the other as the arc closes — steeply, so an arc is an arc
- * until it is nearly whole, and a sweep animated to 360 lands without a jump.
- */
-export function radialAngles(arrangement: RadialArrangement, count: number, time: number): number[] {
-  const sweep = arrangement.sweep
-  const closing = Math.min(1, Math.abs(sweep) / 360) ** 8
-  const step = count <= 1 ? 0 : sweep / (count - 1 + closing)
-  const sign = arrangement.direction === "counterclockwise" ? -1 : 1
-  const start = arrangement.startAngle + arrangement.spinSpeed * time
-  const angles: number[] = []
-  for (let k = 0; k < count; k++) angles.push(start + sign * k * step)
-  return angles
-}
-
-export function radialSlots(arrangement: RadialArrangement, input: SlotInput): Slot[] {
-  const angles = radialAngles(arrangement, input.count, input.time)
-  const start = angles[0] ?? 0
-  return angles.map((angle) => {
-    const rad = (angle * Math.PI) / 180
-    const s = slot(arrangement.radius * Math.sin(rad), arrangement.radius * Math.cos(rad), {
-      kind: "radial",
-      angle: Math.abs(angle - start),
-    })
-    if (arrangement.rotateItems) s.rotation = angle
-    return s
-  })
-}
-
-/** The change to `startAngle` that brings slot `index` to twelve o'clock by the shorter way round. */
-export function radialTurnToTop(arrangement: RadialArrangement, count: number, index: number): number {
-  const angle = radialAngles({ ...arrangement, spinSpeed: 0 }, count, 0)[index] ?? arrangement.startAngle
-  return -wrapDegrees(angle)
-}
-
-/** `degrees` folded into `(-180, 180]`. */
-export function wrapDegrees(degrees: number): number {
-  const wrapped = ((degrees % 360) + 360) % 360
-  return wrapped > 180 ? wrapped - 360 : wrapped
-}
+import { slot, type Slot, type SlotInput } from "./slot"
+
+export const RADIAL_DIRECTIONS = ["clockwise", "counterclockwise"] as const
+export type RadialDirection = (typeof RADIAL_DIRECTIONS)[number]
+
+export interface RadialArrangement {
+  kind: "radial"
+  radius: number
+  /** Where the first item sits, degrees clockwise from twelve o'clock. */
+  startAngle: number
+  /** How much of the circle the items span, degrees. */
+  sweep: number
+  direction: RadialDirection
+  /** Turn each item so its top faces away from the centre. */
+  rotateItems: boolean
+  /** Degrees per second the ring turns on its own. */
+  spinSpeed: number
+}
+
+/**
+ * The angle of each of `count` slots, clockwise from twelve o'clock. A full
+ * circle divides by the count, so the last item does not land on the first; an
+ * arc divides by one less, so both ends get an item. In between the divisor
+ * slides from one to the other as the arc closes — steeply, so an arc is an arc
+ * until it is nearly whole, and a sweep animated to 360 lands without a jump.
+ */
+export function radialAngles(arrangement: RadialArrangement, count: number, time: number): number[] {
+  const sweep = arrangement.sweep
+  const closing = Math.min(1, Math.abs(sweep) / 360) ** 8
+  const step = count <= 1 ? 0 : sweep / (count - 1 + closing)
+  const sign = arrangement.direction === "counterclockwise" ? -1 : 1
+  const start = arrangement.startAngle + arrangement.spinSpeed * time
+  const angles: number[] = []
+  for (let k = 0; k < count; k++) angles.push(start + sign * k * step)
+  return angles
+}
+
+export function radialSlots(arrangement: RadialArrangement, input: SlotInput): Slot[] {
+  const angles = radialAngles(arrangement, input.count, input.time)
+  const start = angles[0] ?? 0
+  return angles.map((angle) => {
+    const rad = (angle * Math.PI) / 180
+    const s = slot(arrangement.radius * Math.sin(rad), arrangement.radius * Math.cos(rad), {
+      kind: "radial",
+      angle: Math.abs(angle - start),
+    })
+    if (arrangement.rotateItems) s.rotation = angle
+    return s
+  })
+}
+
+/** The change to `startAngle` that brings slot `index` to twelve o'clock by the shorter way round. */
+export function radialTurnToTop(arrangement: RadialArrangement, count: number, index: number): number {
+  const angle = radialAngles({ ...arrangement, spinSpeed: 0 }, count, 0)[index] ?? arrangement.startAngle
+  return -wrapDegrees(angle)
+}
+
+/** `degrees` folded into `(-180, 180]`. */
+export function wrapDegrees(degrees: number): number {
+  const wrapped = ((degrees % 360) + 360) % 360
+  return wrapped > 180 ? wrapped - 360 : wrapped
+}

package/src/kit/slots/rectangular.ts

@@ -1,108 +1,108 @@
-import type { Size2D } from "@motionscript/sdk"
-
-import { largest, slot, type Slot, type SlotInput } from "./slot"
-
-export const FILL_DIRECTIONS = ["row", "column"] as const
-export type FillDirection = (typeof FILL_DIRECTIONS)[number]
-
-/**
- * How big a cell is: the largest child (`fit`), a size of its own (`fixed`), or
- * an equal share of the grid's box (`fill`), which is also the room a child set
- * to `fill` grows into.
- */
-export const CELL_MODES = ["fit", "fixed", "fill"] as const
-export type CellMode = (typeof CELL_MODES)[number]
-
-/** Where a short last row (or column, filling by column) sits. */
-export const LINE_ALIGNS = ["start", "center", "end"] as const
-export type LineAlign = (typeof LINE_ALIGNS)[number]
-
-export interface RectangularArrangement {
-  kind: "rectangular"
-  columns: number
-  fillDirection: FillDirection
-  cellMode: CellMode
-  cellWidth: number
-  cellHeight: number
-  columnGap: number
-  rowGap: number
-  lastLineAlign: LineAlign
-  /** Share of a column's pitch every other row shifts right — `0.5` is a brick bond. */
-  rowOffset: number
-  /** Share of a row's pitch every other column shifts down. */
-  columnOffset: number
-}
-
-/** Rows and columns `count` items make, `columns` wide. */
-export function rectangularShape(arrangement: RectangularArrangement, count: number): { rows: number; columns: number } {
-  const columns = Math.max(1, Math.round(arrangement.columns))
-  const rows = Math.max(1, Math.ceil(count / columns))
-  // Filling by column, the rows are set by the count, and a column the items
-  // never reach would pull the block off centre.
-  if (arrangement.fillDirection === "column") return { rows, columns: Math.max(1, Math.ceil(count / rows)) }
-  return { rows, columns }
-}
-
-/** The cell every item is laid out in — what a `fill` child is measured against. */
-export function rectangularCell(
-  arrangement: RectangularArrangement,
-  count: number,
-  sizes: readonly Size2D[],
-  box: Size2D,
-): Size2D {
-  const { rows, columns } = rectangularShape(arrangement, count)
-  switch (arrangement.cellMode) {
-    case "fixed":
-      return { width: Math.max(0, arrangement.cellWidth), height: Math.max(0, arrangement.cellHeight) }
-    case "fill":
-      return {
-        width: Math.max(0, (box.width - arrangement.columnGap * (columns - 1)) / columns),
-        height: Math.max(0, (box.height - arrangement.rowGap * (rows - 1)) / rows),
-      }
-    default:
-      return largest(sizes)
-  }
-}
-
-/**
- * Items fill rows left to right, top to bottom (or columns top to bottom, left to
- * right), and the whole block is centred on the grid.
- */
-export function rectangularSlots(arrangement: RectangularArrangement, input: SlotInput): Slot[] {
-  const { count } = input
-  if (count === 0) return []
-  const { rows, columns } = rectangularShape(arrangement, count)
-  const byColumn = arrangement.fillDirection === "column"
-  // Filling by column keeps the column count and lets the rows follow from it.
-  const lines = byColumn ? columns : rows
-  const perLine = byColumn ? rows : columns
-  const cell = rectangularCell(arrangement, count, input.sizes, input.box)
-  const pitchX = cell.width + arrangement.columnGap
-  const pitchY = cell.height + arrangement.rowGap
-  const lastLine = lines - 1
-  const lastCount = count - lastLine * perLine
-  const shortBy = perLine - lastCount
-  const lead = arrangement.lastLineAlign === "center" ? shortBy / 2 : arrangement.lastLineAlign === "end" ? shortBy : 0
-  // Shifting every other row by a share of a pitch moves the block's centre by
-  // half that share; taking it back keeps the block centred on the grid.
-  const shiftX = arrangement.rowOffset * pitchX
-  const shiftY = arrangement.columnOffset * pitchY
-
-  const slots: Slot[] = []
-  for (let i = 0; i < count; i++) {
-    const line = Math.floor(i / perLine)
-    let along = i % perLine
-    if (line === lastLine) along += lead
-    const row = byColumn ? along : line
-    const column = byColumn ? line : along
-    // A centred short line sits between whole cells; its parity is the cell it covers most.
-    const rowIndex = Math.round(row)
-    const columnIndex = Math.round(column)
-    const x = (column - (columns - 1) / 2) * pitchX
-      + (rowIndex % 2 === 1 ? shiftX : 0) - (rows > 1 ? shiftX / 2 : 0)
-    const y = ((rows - 1) / 2 - row) * pitchY
-      - (columnIndex % 2 === 1 ? shiftY : 0) + (columns > 1 ? shiftY / 2 : 0)
-    slots.push(slot(x, y, { kind: "rectangular", row: rowIndex, column: columnIndex }))
-  }
-  return slots
-}
+import type { Size2D } from "@motionscript/sdk"
+
+import { largest, slot, type Slot, type SlotInput } from "./slot"
+
+export const FILL_DIRECTIONS = ["row", "column"] as const
+export type FillDirection = (typeof FILL_DIRECTIONS)[number]
+
+/**
+ * How big a cell is: the largest child (`fit`), a size of its own (`fixed`), or
+ * an equal share of the grid's box (`fill`), which is also the room a child set
+ * to `fill` grows into.
+ */
+export const CELL_MODES = ["fit", "fixed", "fill"] as const
+export type CellMode = (typeof CELL_MODES)[number]
+
+/** Where a short last row (or column, filling by column) sits. */
+export const LINE_ALIGNS = ["start", "center", "end"] as const
+export type LineAlign = (typeof LINE_ALIGNS)[number]
+
+export interface RectangularArrangement {
+  kind: "rectangular"
+  columns: number
+  fillDirection: FillDirection
+  cellMode: CellMode
+  cellWidth: number
+  cellHeight: number
+  columnGap: number
+  rowGap: number
+  lastLineAlign: LineAlign
+  /** Share of a column's pitch every other row shifts right — `0.5` is a brick bond. */
+  rowOffset: number
+  /** Share of a row's pitch every other column shifts down. */
+  columnOffset: number
+}
+
+/** Rows and columns `count` items make, `columns` wide. */
+export function rectangularShape(arrangement: RectangularArrangement, count: number): { rows: number; columns: number } {
+  const columns = Math.max(1, Math.round(arrangement.columns))
+  const rows = Math.max(1, Math.ceil(count / columns))
+  // Filling by column, the rows are set by the count, and a column the items
+  // never reach would pull the block off centre.
+  if (arrangement.fillDirection === "column") return { rows, columns: Math.max(1, Math.ceil(count / rows)) }
+  return { rows, columns }
+}
+
+/** The cell every item is laid out in — what a `fill` child is measured against. */
+export function rectangularCell(
+  arrangement: RectangularArrangement,
+  count: number,
+  sizes: readonly Size2D[],
+  box: Size2D,
+): Size2D {
+  const { rows, columns } = rectangularShape(arrangement, count)
+  switch (arrangement.cellMode) {
+    case "fixed":
+      return { width: Math.max(0, arrangement.cellWidth), height: Math.max(0, arrangement.cellHeight) }
+    case "fill":
+      return {
+        width: Math.max(0, (box.width - arrangement.columnGap * (columns - 1)) / columns),
+        height: Math.max(0, (box.height - arrangement.rowGap * (rows - 1)) / rows),
+      }
+    default:
+      return largest(sizes)
+  }
+}
+
+/**
+ * Items fill rows left to right, top to bottom (or columns top to bottom, left to
+ * right), and the whole block is centred on the grid.
+ */
+export function rectangularSlots(arrangement: RectangularArrangement, input: SlotInput): Slot[] {
+  const { count } = input
+  if (count === 0) return []
+  const { rows, columns } = rectangularShape(arrangement, count)
+  const byColumn = arrangement.fillDirection === "column"
+  // Filling by column keeps the column count and lets the rows follow from it.
+  const lines = byColumn ? columns : rows
+  const perLine = byColumn ? rows : columns
+  const cell = rectangularCell(arrangement, count, input.sizes, input.box)
+  const pitchX = cell.width + arrangement.columnGap
+  const pitchY = cell.height + arrangement.rowGap
+  const lastLine = lines - 1
+  const lastCount = count - lastLine * perLine
+  const shortBy = perLine - lastCount
+  const lead = arrangement.lastLineAlign === "center" ? shortBy / 2 : arrangement.lastLineAlign === "end" ? shortBy : 0
+  // Shifting every other row by a share of a pitch moves the block's centre by
+  // half that share; taking it back keeps the block centred on the grid.
+  const shiftX = arrangement.rowOffset * pitchX
+  const shiftY = arrangement.columnOffset * pitchY
+
+  const slots: Slot[] = []
+  for (let i = 0; i < count; i++) {
+    const line = Math.floor(i / perLine)
+    let along = i % perLine
+    if (line === lastLine) along += lead
+    const row = byColumn ? along : line
+    const column = byColumn ? line : along
+    // A centred short line sits between whole cells; its parity is the cell it covers most.
+    const rowIndex = Math.round(row)
+    const columnIndex = Math.round(column)
+    const x = (column - (columns - 1) / 2) * pitchX
+      + (rowIndex % 2 === 1 ? shiftX : 0) - (rows > 1 ? shiftX / 2 : 0)
+    const y = ((rows - 1) / 2 - row) * pitchY
+      - (columnIndex % 2 === 1 ? shiftY : 0) + (columns > 1 ? shiftY / 2 : 0)
+    slots.push(slot(x, y, { kind: "rectangular", row: rowIndex, column: columnIndex }))
+  }
+  return slots
+}