@motionscript/grids
v0.4.0
Published
Grid layouts for Motion Script: rectangular, radial, path and spherical arrangements of a node's children, with staggered reveals, waves, focus and morphs between them.
Maintainers
Readme
@motionscript/grids
Grid layouts for Motion Script: a node that places
its children in a rectangular, radial, path or spherical arrangement, with
staggered reveals, waves, focus, reordering and morphs between arrangements.
Written against @motionscript/sdk, a peer dependency.
import { NODES } from '@motionscript/grids';
export const nodes = NODES; // [RectangularGrid, RadialGrid, PathGrid, SphereGrid]Importing registers nothing (see packages/components/CLAUDE.md). Each grid
is a component (component2d); ItemGrid, the module the four are built from,
is no node type and is not in NODES.
Install
npm install @motionscript/grids @motionscript/sdkExports
| Path | Source | What |
|---|---|---|
| @motionscript/grids | src/index.ts | the public surface: the four grids and NODES. A name leaves it only after a deprecation, in the next major (the next minor while on 0.x) |
| @motionscript/grids/v1 | src/v1.ts | the v1 public surface, the same names as the root today. A custom component imports this path, so a later major keeps it linking; the bare path follows the latest API |
| @motionscript/grids/kit | src/unstable.ts | everything: the ItemGrid module and what it uses (src/engine.ts, over src/kit/: slot functions per arrangement, stagger, reveal and wave styles, order helpers, seeded random) and the four grid barrels (PATH_GRID_SHAPES, …). Unstable: any release may change it |
Nodes
The items are the grid's children, in layer order; a group is one item. A grid is
hug by default, except pathGrid (640 x 400, fixed).
| Key | Arrangement props | Own commands |
|---|---|---|
| rectangularGrid | columns, fillDirection, cellMode (fit/fixed/fill), cellWidth/Height, columnGap, rowGap, lastLineAlign, rowOffset, columnOffset | columnsTo, gapTo, cellSizeTo, focusRow, focusColumn |
| radialGrid | radius, startAngle, sweep, direction, rotateItems, spinSpeed | spin, turnTo, radiusTo, sweepTo |
| pathGrid | shape (a template or custom), path, pathNode, spacing, spacingDistance, offset, flowSpeed, trimStart/End, alignToPath | flow, trimTo, setPath |
| sphereGrid | radius, yaw, pitch, roll, facing, focalLength, depthFade, cullBackfaces, spinSpeed | spin, orientTo, turnTo, radiusTo, focalLengthTo |
Every grid also has order, spread and arrangeLike, and these commands from
the ItemGrid module: reveal, conceal, wave, focus, unfocus, spreadTo, shuffle,
swap, reorder, morphInto. Per-item commands take staggerOrder (index,
reverse, random, centerOut, edgesIn, row, column, angle, path,
depth) and stagger (0 to 0.95); shuffle, swap, reorder, morphInto,
columnsTo and setPath are transitions.
Rules worth knowing
- A slot is a parent transform. Each item is laid out where its slot is, and the
rest of the slot (turn, scale, tilt, depth, fade) rides on its layout placement,
applied about the item's centre before its own transform, so an item's own
x,y,rotationand its commands keep working relative to the slot. A grid whose arrangement has depth (the sphere) opens a camera of its own with its render'sctx.space, unless it already sits in a space (ctx.inSpace). flowOpssizes; it never places. The grid's size is what its slots come to (extentOf), seen through the camera it has that frame, so a grid of grids is a grid of items.revealState,waveState,focusStateandtransitionare written by commands, not authored. They are rewritten every frame as a pure function of time and set tonullat the command's end, so a seek reproduces them.revealhides every item at its start (place it where the grid enters);concealleaves them hidden until a laterreveal.- The stagger lives inside the duration: a command lasts its row's
duration. - An arrangement is data. A transition keeps the arrangement it leaves as a
GridSnapshotand re-evaluates it each frame, so a morph can start from any arrangement, including another grid's.morphIntowritesarrangeLike(a node reference: the grid reads a view of the one it names, and where it stands) and keeps following that grid; a grid that cannot findarrangeLikeorpathNodedraws its own arrangement. Another grid's arrangement is worked out from its state by theArrangerit was defined with, so a grid is borrowable onceItemGrid.definehas seen it. - A command reads the grid as its predecessors leave it. Ranks for a stagger, the
rows
focusRowpicks and the cellcellSizeTostarts from are worked out afresh from the command's state, its children's sizes and the grid's box, against the clock the timeline builds commands at (time 0). order[k]is the child in slotk, andnormalizeOrderrepairs any order (missing, repeated or out-of-range entries), so a stale order never throws.- The kit stays an import. A copy of
rectangular-grid(orradial-grid,path-grid,sphere-grid) takes one grid's two files and rewrites their kit imports to@motionscript/grids/kit(registry.json): a second copy ofItemGridwould keep a second register of grids, and a morph would not find the grids it should.
A grid of your own
import { component2d, Types, type Values } from '@motionscript/sdk';
import { ItemGrid, type Arrangement } from '@motionscript/grids/kit';
const own = { radius: Types.number(120) };
const arranger: ItemGrid.Arranger<Values<typeof own>> = {
arrangement: (s): Arrangement => ({ kind: 'radial', radius: s.radius, startAngle: 0, sweep: 180, direction: 'clockwise', rotateItems: false, spinSpeed: 0 }),
};
export const ArcGrid = ItemGrid.define(component2d({
key: 'arcGrid',
state: { ...ItemGrid.state, ...own },
defaults: ItemGrid.defaults,
commands: { ...ItemGrid.commands },
...ItemGrid.fields(arranger),
}), arranger);define registers the arranger, which is what another grid and a host know it by:
ItemGrid.isGrid(node) tells a grid from any other node.
Development
pnpm --filter @motionscript/grids build
pnpm --filter @motionscript/grids testTests are in src/tests/ (grid.test.ts, slots.test.ts, descriptors.test.ts);
harness.ts builds, seeks and renders a document.
