@sharedex/ui 0.0.0-stage → 0.9.0

package/dist/grid/math.d.ts

@@ -0,0 +1,107 @@
+import { rotX } from "../carousel/layout/presets/sphere.js";
+/** How the plane repeats when the items don't fill a whole block. */
+export type GridRepeat = "sequence" | "blank";
+export interface GridPoint {
+    readonly x: number;
+    readonly y: number;
+}
+export interface GridCellRef {
+    readonly col: number;
+    readonly row: number;
+}
+/**
+ * Which item cell (`col`, `row`) shows, or `null` for an empty cell.
+ *
+ * - `"sequence"`: reading order runs on across block rows (row 1 starts where
+ *   row 0 ended), so no cell is ever empty, whatever the item count.
+ * - `"blank"`: blocks of `columns × ceil(count / columns)` cells repeat; the
+ *   missing cells of the last row stay empty, like a carousel placeholder.
+ *
+ * Both repeat every `columns` columns.
+ */
+export declare function gridItemAt(col: number, row: number, count: number, columns: number, repeat?: GridRepeat): number | null;
+/**
+ * Columns in one repeating block. `"auto"`: enough that one block covers the
+ * viewport width, capped at the item count (more columns than items would
+ * only repeat items within a row).
+ */
+export declare function gridColumns(option: number | "auto", viewportWidth: number, pitchX: number, count: number): number;
+/** How far row `row` is shifted right, cells: `stagger` on odd rows (the brick pattern), 0 on even ones. */
+export declare function rowShift(row: number, stagger: number): number;
+/** The centre of cell (`col`, `row`), cells. */
+export declare function cellCentre(col: number, row: number, stagger?: number): GridPoint;
+/** The plane's tilt, degrees: CSS `rotateX(x) rotateY(y) rotateZ(z)` about the viewport centre. */
+export interface GridTilt {
+    readonly x?: number;
+    readonly y?: number;
+    readonly z?: number;
+}
+export interface GridView {
+    /** Viewport size, px. */
+    readonly width: number;
+    readonly height: number;
+    /** One cell plus its gap, px. */
+    readonly pitchX: number;
+    readonly pitchY: number;
+    /** The focus, cells: the plane point at the viewport centre. */
+    readonly position: GridPoint;
+    readonly stagger?: number;
+    readonly tilt?: GridTilt;
+    /** CSS `perspective` on the viewport, px. 0 = none. Default 1200. */
+    readonly perspective?: number;
+    /** Extra cells mounted on every side. Default 1. */
+    readonly margin?: number;
+    /** No cell further than this from the focus (cells) is mounted: a steep tilt shows the horizon. Default 12. */
+    readonly reach?: number;
+    /** At most this many cells mounted. Default 160. */
+    readonly maxCells?: number;
+}
+/** An inclusive range of columns and rows. */
+export interface GridRange {
+    readonly col0: number;
+    readonly col1: number;
+    readonly row0: number;
+    readonly row1: number;
+}
+type Mat = ReturnType<typeof rotX>;
+/** The tilt as one rotation matrix (row-major, CSS axes: y down, z towards the viewer). */
+export declare function tiltMatrix(tilt?: GridTilt): Mat;
+/**
+ * Where the ray through screen point (`sx`, `sy`) (px from the viewport
+ * centre) meets the tilted plane, in plane px from the focus; `null` when it
+ * misses (the plane is edge-on, or the point is above the horizon).
+ *
+ * The camera sits `perspective` px in front of the screen on the centre line,
+ * as CSS `perspective` places it; with no perspective the rays are parallel.
+ * The plane passes through the viewport centre with normal `M · (0, 0, 1)`.
+ */
+export declare function planeHit(sx: number, sy: number, m: Mat, perspective: number): GridPoint | null;
+/**
+ * The cells to mount: every cell whose pitch box shows in the viewport, plus
+ * `margin` on every side.
+ *
+ * Points along the viewport's edges are cast onto the (tilted) plane with
+ * `planeHit`; the box around the hits is the visible part of the plane. A
+ * point that misses (the horizon is on screen) is walked back towards the
+ * centre to the last point that still hits. Every hit is pulled within
+ * `reach` cells of the focus, and the range is trimmed from its far sides to
+ * `maxCells`. A flat plane gives exactly the viewport.
+ */
+export declare function visibleCells(view: GridView): GridRange;
+/**
+ * The copy of `item` whose centre is nearest `from` (cells), for `goTo`,
+ * `open` and the keyboard. Rows are searched outwards from `from.y` and the
+ * search stops once a row cannot be nearer than the best copy found; every
+ * item shows within `count` rows, so it always ends. `null` for an index
+ * outside the items.
+ */
+export declare function nearestCopy(item: number, from: GridPoint, count: number, columns: number, repeat?: GridRepeat, stagger?: number): GridCellRef | null;
+/** The cell centre a glide should land on: the nearest row first, then the nearest column in that row. */
+export declare function snapTarget(landing: GridPoint, stagger?: number): GridCellRef & GridPoint;
+/**
+ * The bulge's falloff with distance `r` from the focus: 1 at the focus,
+ * easing down to 0 at `radius` and staying 0 beyond (a raised cosine, so the
+ * dome has no crease at its top or its rim).
+ */
+export declare function bulgeAt(r: number, radius: number): number;
+export {};

package/dist/grid/math.js

@@ -0,0 +1,265 @@
+/**
+ * The Grid's pure maths: which item a cell shows, where a cell sits, which
+ * cells to mount, the copy of an item nearest the focus, the snap landing and
+ * the bulge falloff. No DOM; the Grid measures and calls these, the tests call
+ * them directly.
+ *
+ * Units: the plane is an endless lattice of cells. Positions are in **cell
+ * units** (one column / one row = 1), never px, so a resize keeps the same
+ * card centred; px = cells × pitch. A cell's centre is its column and row,
+ * plus the row's `stagger` shift. Physical mirroring for RTL is the
+ * component's job; everything here is in reading order.
+ */
+import { wrapIndex } from "../carousel/engine/ring.js";
+import { rotX, rotY, rotZ } from "../carousel/layout/presets/sphere.js";
+/**
+ * Which item cell (`col`, `row`) shows, or `null` for an empty cell.
+ *
+ * - `"sequence"`: reading order runs on across block rows (row 1 starts where
+ *   row 0 ended), so no cell is ever empty, whatever the item count.
+ * - `"blank"`: blocks of `columns × ceil(count / columns)` cells repeat; the
+ *   missing cells of the last row stay empty, like a carousel placeholder.
+ *
+ * Both repeat every `columns` columns.
+ */
+export function gridItemAt(col, row, count, columns, repeat = "sequence") {
+    if (count <= 0)
+        return null;
+    const cols = Math.max(1, Math.floor(columns));
+    const k = wrapIndex(col, cols);
+    if (repeat === "sequence")
+        return wrapIndex(row * cols + k, count);
+    const i = wrapIndex(row, Math.ceil(count / cols)) * cols + k;
+    return i < count ? i : null;
+}
+/**
+ * Columns in one repeating block. `"auto"`: enough that one block covers the
+ * viewport width, capped at the item count (more columns than items would
+ * only repeat items within a row).
+ */
+export function gridColumns(option, viewportWidth, pitchX, count) {
+    if (option !== "auto")
+        return Math.max(1, Math.floor(option));
+    if (!(pitchX > 0) || !(viewportWidth > 0))
+        return 1;
+    return Math.min(Math.max(1, Math.ceil(viewportWidth / pitchX)), Math.max(1, count));
+}
+/** How far row `row` is shifted right, cells: `stagger` on odd rows (the brick pattern), 0 on even ones. */
+export function rowShift(row, stagger) {
+    return wrapIndex(row, 2) === 1 ? stagger : 0;
+}
+/** The centre of cell (`col`, `row`), cells. */
+export function cellCentre(col, row, stagger = 0) {
+    return { x: col + rowShift(row, stagger), y: row };
+}
+const RAD = Math.PI / 180;
+/** Points cast along each viewport edge, corners included. */
+const EDGE_SAMPLES = 5;
+function mul(a, b) {
+    return [
+        a[0] * b[0] + a[1] * b[3] + a[2] * b[6], a[0] * b[1] + a[1] * b[4] + a[2] * b[7], a[0] * b[2] + a[1] * b[5] + a[2] * b[8],
+        a[3] * b[0] + a[4] * b[3] + a[5] * b[6], a[3] * b[1] + a[4] * b[4] + a[5] * b[7], a[3] * b[2] + a[4] * b[5] + a[5] * b[8],
+        a[6] * b[0] + a[7] * b[3] + a[8] * b[6], a[6] * b[1] + a[7] * b[4] + a[8] * b[7], a[6] * b[2] + a[7] * b[5] + a[8] * b[8],
+    ];
+}
+/** The tilt as one rotation matrix (row-major, CSS axes: y down, z towards the viewer). */
+export function tiltMatrix(tilt = {}) {
+    return mul(mul(rotX((tilt.x ?? 0) * RAD), rotY((tilt.y ?? 0) * RAD)), rotZ((tilt.z ?? 0) * RAD));
+}
+/**
+ * Where the ray through screen point (`sx`, `sy`) (px from the viewport
+ * centre) meets the tilted plane, in plane px from the focus; `null` when it
+ * misses (the plane is edge-on, or the point is above the horizon).
+ *
+ * The camera sits `perspective` px in front of the screen on the centre line,
+ * as CSS `perspective` places it; with no perspective the rays are parallel.
+ * The plane passes through the viewport centre with normal `M · (0, 0, 1)`.
+ */
+export function planeHit(sx, sy, m, perspective) {
+    const nx = m[2];
+    const ny = m[5];
+    const nz = m[8];
+    // ray: origin o, direction d
+    const ox = perspective > 0 ? 0 : sx;
+    const oy = perspective > 0 ? 0 : sy;
+    const oz = perspective > 0 ? perspective : 0;
+    const dx = perspective > 0 ? sx : 0;
+    const dy = perspective > 0 ? sy : 0;
+    const dz = perspective > 0 ? -perspective : -1;
+    const nd = nx * dx + ny * dy + nz * dz;
+    if (Math.abs(nd) < 1e-9)
+        return null;
+    const t = -(nx * ox + ny * oy + nz * oz) / nd;
+    // behind the camera, or (an edge-on plane through the camera) at it
+    if (perspective > 0 && t <= 1e-6)
+        return null;
+    const px = ox + t * dx;
+    const py = oy + t * dy;
+    const pz = oz + t * dz;
+    // back into plane coordinates: the inverse of a rotation is its transpose
+    return { x: m[0] * px + m[3] * py + m[6] * pz, y: m[1] * px + m[4] * py + m[7] * pz };
+}
+/**
+ * The cells to mount: every cell whose pitch box shows in the viewport, plus
+ * `margin` on every side.
+ *
+ * Points along the viewport's edges are cast onto the (tilted) plane with
+ * `planeHit`; the box around the hits is the visible part of the plane. A
+ * point that misses (the horizon is on screen) is walked back towards the
+ * centre to the last point that still hits. Every hit is pulled within
+ * `reach` cells of the focus, and the range is trimmed from its far sides to
+ * `maxCells`. A flat plane gives exactly the viewport.
+ */
+export function visibleCells(view) {
+    const { width, height, pitchX, pitchY, position } = view;
+    const stagger = view.stagger ?? 0;
+    const margin = view.margin ?? 1;
+    const reach = view.reach ?? 12;
+    const maxCells = Math.max(1, view.maxCells ?? 160);
+    const perspective = view.perspective ?? 1200;
+    const m = tiltMatrix(view.tilt);
+    let minX = 0;
+    let maxX = 0;
+    let minY = 0;
+    let maxY = 0;
+    const add = (hit) => {
+        let x = hit.x / pitchX;
+        let y = hit.y / pitchY;
+        const r = Math.hypot(x, y);
+        if (r > reach) {
+            x *= reach / r;
+            y *= reach / r;
+        }
+        if (x < minX)
+            minX = x;
+        if (x > maxX)
+            maxX = x;
+        if (y < minY)
+            minY = y;
+        if (y > maxY)
+            maxY = y;
+    };
+    const cast = (sx, sy) => {
+        const hit = planeHit(sx, sy, m, perspective);
+        if (hit)
+            return add(hit);
+        // walk back towards the centre (which always hits unless the plane is edge-on)
+        let lo = 0;
+        let hi = 1;
+        let last = null;
+        for (let i = 0; i < 24; i++) {
+            const mid = (lo + hi) / 2;
+            const h = planeHit(sx * mid, sy * mid, m, perspective);
+            if (h) {
+                last = h;
+                lo = mid;
+            }
+            else
+                hi = mid;
+        }
+        if (last)
+            add(last);
+    };
+    if (pitchX > 0 && pitchY > 0 && width > 0 && height > 0) {
+        const hw = width / 2;
+        const hh = height / 2;
+        for (let i = 0; i < EDGE_SAMPLES; i++) {
+            const f = -1 + (2 * i) / (EDGE_SAMPLES - 1);
+            cast(f * hw, -hh);
+            cast(f * hw, hh);
+            cast(-hw, f * hh);
+            cast(hw, f * hh);
+        }
+    }
+    // a cell covers its centre ± half a pitch; odd rows sit up to `stagger` further right
+    let col0 = Math.ceil(position.x + minX - 0.5 - stagger) - margin;
+    let col1 = Math.floor(position.x + maxX + 0.5) + margin;
+    let row0 = Math.ceil(position.y + minY - 0.5) - margin;
+    let row1 = Math.floor(position.y + maxY + 0.5) + margin;
+    // trim the side furthest from the focus until the range fits
+    while ((col1 - col0 + 1) * (row1 - row0 + 1) > maxCells && (col1 > col0 || row1 > row0)) {
+        const sides = [position.x - col0, col1 - position.x, position.y - row0, row1 - position.y];
+        let far = 0;
+        for (let i = 1; i < 4; i++)
+            if (sides[i] > sides[far])
+                far = i;
+        if (far === 0 && col1 > col0)
+            col0++;
+        else if (far === 1 && col1 > col0)
+            col1--;
+        else if (far === 2 && row1 > row0)
+            row0++;
+        else if (row1 > row0)
+            row1--;
+        else if (col1 > col0)
+            col0++;
+    }
+    return { col0, col1, row0, row1 };
+}
+/**
+ * The copy of `item` whose centre is nearest `from` (cells), for `goTo`,
+ * `open` and the keyboard. Rows are searched outwards from `from.y` and the
+ * search stops once a row cannot be nearer than the best copy found; every
+ * item shows within `count` rows, so it always ends. `null` for an index
+ * outside the items.
+ */
+export function nearestCopy(item, from, count, columns, repeat = "sequence", stagger = 0) {
+    if (!Number.isInteger(item) || item < 0 || item >= count)
+        return null;
+    const cols = Math.max(1, Math.floor(columns));
+    const rows = Math.ceil(count / cols);
+    const home = Math.round(from.y);
+    let best = null;
+    let bestD = Infinity;
+    const tryRow = (row) => {
+        // the columns (mod cols) of this row that show the item
+        const ks = [];
+        if (repeat === "sequence") {
+            for (let k = wrapIndex(item - row * cols, count); k < cols; k += count)
+                ks.push(k);
+        }
+        else if (wrapIndex(row, rows) === Math.floor(item / cols)) {
+            ks.push(item % cols);
+        }
+        const shift = rowShift(row, stagger);
+        for (const k of ks) {
+            const col = k + cols * Math.round((from.x - shift - k) / cols);
+            // the copies either side of the nearest can only tie or lose; check them for ties at .5
+            for (const c of [col - cols, col, col + cols]) {
+                const d = Math.hypot(c + shift - from.x, row - from.y);
+                if (d < bestD - 1e-12) {
+                    bestD = d;
+                    best = { col: c, row };
+                }
+            }
+        }
+    };
+    for (let step = 0; step <= 2 * count + 2; step++) {
+        const lowRow = home - step;
+        const highRow = home + step;
+        if (best && Math.min(Math.abs(lowRow - from.y), Math.abs(highRow - from.y)) > bestD)
+            break;
+        tryRow(highRow);
+        if (step > 0)
+            tryRow(lowRow);
+    }
+    return best;
+}
+/** The cell centre a glide should land on: the nearest row first, then the nearest column in that row. */
+export function snapTarget(landing, stagger = 0) {
+    const row = Math.round(landing.y);
+    const shift = rowShift(row, stagger);
+    const col = Math.round(landing.x - shift);
+    return { col, row, x: col + shift, y: row };
+}
+/**
+ * The bulge's falloff with distance `r` from the focus: 1 at the focus,
+ * easing down to 0 at `radius` and staying 0 beyond (a raised cosine, so the
+ * dome has no crease at its top or its rim).
+ */
+export function bulgeAt(r, radius) {
+    if (!(radius > 0))
+        return 0;
+    const t = Math.min(Math.abs(r) / radius, 1);
+    return (1 + Math.cos(Math.PI * t)) / 2;
+}

package/dist/grid/modifiers.d.ts

@@ -0,0 +1,25 @@
+import type { GridModifier } from "./types.js";
+export interface BulgeOptions {
+    /** How far the plane has sunk at `radius` and beyond, px. Default `120`. */
+    readonly height?: number;
+    /** Where the dome ends, px from the focus on the plane. Default: the viewport's larger side. */
+    readonly radius?: number;
+}
+/**
+ * The plane domes towards the viewer at the focus: the focused card stays at
+ * its real size (crisp text), the rest sink away with their distance, easing
+ * down to `height` px back at `radius`.
+ */
+export declare function bulge(options?: BulgeOptions): GridModifier;
+export interface FogOptions {
+    /** Cards closer than this to the focus (cells) are fully shown. Default `3`. */
+    readonly from?: number;
+    /** Cards this far away and beyond are gone. Default `6`. */
+    readonly to?: number;
+}
+/**
+ * Fades cards out with their distance from the focus, so the edge of the
+ * mounted area (a steep tilt shows a long way back) never shows. Faded-out
+ * cards stop taking pointer events.
+ */
+export declare function fog(options?: FogOptions): GridModifier;

package/dist/grid/modifiers.js

@@ -0,0 +1,35 @@
+/**
+ * The Grid's built-in cell modifiers. Like the carousel's, each is a factory
+ * returning a pure `(buf, cell, frame) => void`; `Grid.Root`'s `bulge` and
+ * `fog` props add them before any custom `modifiers`.
+ */
+import { bulgeAt } from "./math.js";
+/**
+ * The plane domes towards the viewer at the focus: the focused card stays at
+ * its real size (crisp text), the rest sink away with their distance, easing
+ * down to `height` px back at `radius`.
+ */
+export function bulge(options = {}) {
+    const height = options.height ?? 120;
+    return (buf, cell, frame) => {
+        const radius = options.radius ?? Math.max(frame.width, frame.height);
+        const r = Math.hypot(cell.dx * frame.pitchX, cell.dy * frame.pitchY);
+        buf.z -= height * (1 - bulgeAt(r, radius));
+    };
+}
+/**
+ * Fades cards out with their distance from the focus, so the edge of the
+ * mounted area (a steep tilt shows a long way back) never shows. Faded-out
+ * cards stop taking pointer events.
+ */
+export function fog(options = {}) {
+    const from = options.from ?? 3;
+    const to = Math.max(options.to ?? 6, from + 1e-6);
+    return (buf, cell) => {
+        const t = Math.min(1, Math.max(0, (cell.distance - from) / (to - from)));
+        const fade = 1 - t * t * (3 - 2 * t); // smoothstep
+        buf.opacity *= fade;
+        if (fade === 0)
+            buf.pointerEvents = "none";
+    };
+}

package/dist/grid/open.d.ts

@@ -0,0 +1,66 @@
+import type { SlotFrameBuffer } from "../carousel/engine/types.js";
+import type { GridCellState, GridFrame } from "./types.js";
+export interface GridOpenView {
+    readonly kind: "zoom" | "strip" | "panel";
+    /** Share of the viewport width `Grid.Panel` takes at the end side (`panel` view only, else 0). */
+    readonly panel: number;
+    /** Writes the cell's open look into a reset buffer: screen px from the viewport centre, upright. */
+    pose(buf: SlotFrameBuffer, cell: GridCellState, frame: GridFrame): void;
+}
+export interface ZoomOptions {
+    /** Share of the viewport the open card may fill. Default `0.8`. */
+    readonly size?: number;
+}
+export interface StripOptions {
+    /** Scale of the thumbnails. Default `0.49`. */
+    readonly thumb?: number;
+    /** px between thumbnails. Default `12`. */
+    readonly gap?: number;
+    /** Share of the free space the open card may fill. Default `0.9`. */
+    readonly fit?: number;
+    /** px around the strip. Default `16`. */
+    readonly margin?: number;
+}
+export interface GridPanelOptions extends StripOptions {
+    /** Share of the viewport width the panel takes, at the end side. Default `0.42`. */
+    readonly panel?: number;
+}
+/** 1 for the cell at the focus, falling to 0 one cell away in either direction. */
+export declare function focusWeight(cell: GridCellState): number;
+/**
+ * The open card grows to fill `size` of the viewport where it is; the other
+ * cards slide outwards, as if pushed by it, and fade.
+ */
+declare function zoom(options?: ZoomOptions): GridOpenView;
+/**
+ * The open card fills a large box; its row becomes a strip of thumbnails
+ * along the bottom (click one to open it, or use the arrow keys); the other
+ * rows slide away and fade.
+ */
+declare function strip(options?: StripOptions): GridOpenView;
+/**
+ * Like `strip`, with the open card moved towards the start to leave `panel`
+ * of the width for `<Grid.Panel>`, the consumer's text about the card.
+ */
+declare function panel(options?: GridPanelOptions): GridOpenView;
+/**
+ * Turns a screen-space pose (px from the viewport centre, upright) into the
+ * tilted stage's coordinates, so it shows on screen exactly as written: the
+ * point goes through the inverse tilt `Mᵀ`, and the card takes `Mᵀ` as its own
+ * turn, so the stage's turn and the card's cancel. `m` is the stage's tilt
+ * matrix (`tiltMatrix`, row-major).
+ */
+export declare function screenToStage(buf: SlotFrameBuffer, m: readonly number[]): SlotFrameBuffer;
+/**
+ * How the Grid shows an open card, for `Grid.Root`'s `open` prop:
+ *
+ * ```tsx
+ * <Grid.Root items={pieces} open={gridOpen.strip()}>  // a click opens; Esc, a drag or close() closes
+ * ```
+ */
+export declare const gridOpen: {
+    readonly zoom: typeof zoom;
+    readonly strip: typeof strip;
+    readonly panel: typeof panel;
+};
+export {};

package/dist/grid/open.js

@@ -0,0 +1,121 @@
+/**
+ * Open views: how the Grid looks while a card is open (`open()` / `close()`).
+ *
+ * Each view writes a cell's open look in **screen** px from the viewport
+ * centre, flat and facing the viewer; `screenToStage` then turns that pose
+ * into the tilted stage's coordinates (the inverse of the tilt, applied to the
+ * point and to the card's own turn), and the Viewport blends it with the
+ * cell's grid pose by `openProgress` (`blendBuffers`, as the carousel's
+ * morph). Every term is continuous in the cell's offset from the focus, so
+ * stepping between cards while open is smooth too.
+ */
+import { eulerXYZ } from "../carousel/layout/presets/sphere.js";
+/** 1 for the cell at the focus, falling to 0 one cell away in either direction. */
+export function focusWeight(cell) {
+    return Math.max(0, 1 - Math.abs(cell.dx)) * Math.max(0, 1 - Math.abs(cell.dy));
+}
+/**
+ * The open card grows to fill `size` of the viewport where it is; the other
+ * cards slide outwards, as if pushed by it, and fade.
+ */
+function zoom(options = {}) {
+    const size = options.size ?? 0.8;
+    return {
+        kind: "zoom",
+        panel: 0,
+        pose(buf, cell, frame) {
+            const w = focusWeight(cell);
+            const big = Math.max(0.05, Math.min((frame.width * size) / Math.max(frame.cellWidth, 1), (frame.height * size) / Math.max(frame.cellHeight, 1)));
+            const push = 1 + (big - 1) * 0.75;
+            buf.x = cell.dx * frame.pitchX * frame.dirX * push * (1 - w);
+            buf.y = cell.dy * frame.pitchY * push * (1 - w);
+            const s = 1 + (big - 1) * w;
+            buf.scaleX = s;
+            buf.scaleY = s;
+            buf.scaleZ = s; // uniform in 3D: the stage's turn and the card's must cancel around it
+            buf.z = 2 * w; // in front of anything flat in the scene
+            buf.opacity = w;
+            if (w === 0)
+                buf.pointerEvents = "none";
+            buf.zIndex = Math.round(1000 * w);
+        },
+    };
+}
+/** The strip geometry, shared by `strip` (no panel) and `panel` (the open card moved towards the start). */
+function stripPose(options, panel) {
+    const thumb = options.thumb ?? 0.49;
+    const gap = options.gap ?? 12;
+    const fit = options.fit ?? 0.9;
+    const margin = options.margin ?? 16;
+    return (buf, cell, frame) => {
+        const a = Math.abs(cell.dx);
+        const along = Math.min(1, a); // 0 the open card … 1 a thumbnail
+        const off = Math.min(1, Math.abs(cell.dy)); // other rows leave
+        const thumbW = frame.cellWidth * thumb;
+        const thumbH = frame.cellHeight * thumb;
+        const band = thumbH + 2 * margin;
+        const big = Math.max(0.05, Math.min((frame.width * (1 - panel) * fit) / Math.max(frame.cellWidth, 1), ((frame.height - band) * fit) / Math.max(frame.cellHeight, 1)));
+        // the open card centred in the space above the strip, beside the panel (end side)
+        const bigX = (-(frame.width * panel) / 2) * frame.dirX;
+        const bigY = -band / 2;
+        // the thumbnails: the open card's row, in reading order, along the bottom edge
+        const thumbX = cell.dx * (thumbW + gap) * frame.dirX;
+        const thumbY = frame.height / 2 - margin - thumbH / 2;
+        buf.x = bigX + (thumbX - bigX) * along;
+        buf.y = bigY + (thumbY - bigY) * along + Math.sign(cell.dy) * off * band;
+        const s = big + (thumb - big) * along;
+        buf.scaleX = s;
+        buf.scaleY = s;
+        buf.scaleZ = s; // uniform in 3D: the stage's turn and the card's must cancel around it
+        buf.z = 2 * (1 - along);
+        // thumbnails past the strip's ends, and every other row, fade out
+        const half = (frame.width / 2 - margin) / Math.max(thumbW + gap, 1);
+        const opacity = Math.min(1, Math.max(0, half + 0.5 - a)) * (1 - off);
+        buf.opacity = opacity;
+        if (opacity === 0)
+            buf.pointerEvents = "none";
+        buf.zIndex = 1000 - Math.round(a * 10) - Math.round(off * 100);
+    };
+}
+/**
+ * The open card fills a large box; its row becomes a strip of thumbnails
+ * along the bottom (click one to open it, or use the arrow keys); the other
+ * rows slide away and fade.
+ */
+function strip(options = {}) {
+    return { kind: "strip", panel: 0, pose: stripPose(options, 0) };
+}
+/**
+ * Like `strip`, with the open card moved towards the start to leave `panel`
+ * of the width for `<Grid.Panel>`, the consumer's text about the card.
+ */
+function panel(options = {}) {
+    const share = options.panel ?? 0.42;
+    return { kind: "panel", panel: share, pose: stripPose(options, share) };
+}
+/**
+ * Turns a screen-space pose (px from the viewport centre, upright) into the
+ * tilted stage's coordinates, so it shows on screen exactly as written: the
+ * point goes through the inverse tilt `Mᵀ`, and the card takes `Mᵀ` as its own
+ * turn, so the stage's turn and the card's cancel. `m` is the stage's tilt
+ * matrix (`tiltMatrix`, row-major).
+ */
+export function screenToStage(buf, m) {
+    const { x, y, z } = buf;
+    buf.x = m[0] * x + m[3] * y + m[6] * z;
+    buf.y = m[1] * x + m[4] * y + m[7] * z;
+    buf.z = m[2] * x + m[5] * y + m[8] * z;
+    const turn = eulerXYZ([m[0], m[3], m[6], m[1], m[4], m[7], m[2], m[5], m[8]]);
+    buf.rotateX = turn.x;
+    buf.rotateY = turn.y;
+    buf.rotateZ = turn.z;
+    return buf;
+}
+/**
+ * How the Grid shows an open card, for `Grid.Root`'s `open` prop:
+ *
+ * ```tsx
+ * <Grid.Root items={pieces} open={gridOpen.strip()}>  // a click opens; Esc, a drag or close() closes
+ * ```
+ */
+export const gridOpen = { zoom, strip, panel };

package/dist/grid/open.schema.d.ts

@@ -0,0 +1,3 @@
+export declare const GRID_OPEN_ZOOM_SCHEMA: import("../schema/types.js").Schema;
+export declare const GRID_OPEN_STRIP_SCHEMA: import("../schema/types.js").Schema;
+export declare const GRID_OPEN_PANEL_SCHEMA: import("../schema/types.js").Schema;

package/dist/grid/open.schema.js

@@ -0,0 +1,31 @@
+import { defineSchema } from "../schema/define.js";
+// The Grid's open views (`gridOpen.zoom / strip / panel`), one file for the three.
+const stripFields = {
+    thumb: { kind: "number", label: "Thumbnail size", min: 0.2, max: 0.8, step: 0.01, default: 0.49, help: "Of a card in the grid." },
+    gap: { kind: "number", label: "Gap between thumbnails", min: 0, max: 48, step: 1, unit: "px", default: 12 },
+    fit: { kind: "number", label: "Open card fills", min: 0.5, max: 1, step: 0.01, default: 0.9, help: "Of the space above the strip." },
+    margin: { kind: "number", label: "Space around the strip", min: 0, max: 64, step: 1, unit: "px", default: 16, advanced: true },
+};
+export const GRID_OPEN_ZOOM_SCHEMA = defineSchema()({
+    id: "zoom",
+    family: "grid-open",
+    factory: "gridOpen.zoom",
+    fields: {
+        size: { kind: "number", label: "Open card fills", min: 0.3, max: 1, step: 0.01, default: 0.8, help: "Of the viewport; the other cards slide away and fade." },
+    },
+});
+export const GRID_OPEN_STRIP_SCHEMA = defineSchema()({
+    id: "strip",
+    family: "grid-open",
+    factory: "gridOpen.strip",
+    fields: stripFields,
+});
+export const GRID_OPEN_PANEL_SCHEMA = defineSchema()({
+    id: "panel",
+    family: "grid-open",
+    factory: "gridOpen.panel",
+    fields: {
+        ...stripFields,
+        panel: { kind: "number", label: "Panel width", min: 0.25, max: 0.6, step: 0.01, default: 0.42, help: "Of the viewport, at the end side: Grid.Panel's text goes there." },
+    },
+});