@sharedex/ui 0.0.0-stage → 0.9.0

package/dist/grid/Viewport.js

@@ -0,0 +1,479 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useId, useLayoutEffect, useRef, useState } from "react";
+import { animate, cancelFrame, frame as scheduler, motion } from "motion/react";
+import { createSlotFrameBuffer, resetSlotFrameBuffer } from "../carousel/engine/types.js";
+import { blendBuffers } from "../carousel/engine/morph.js";
+import { screenScale } from "../carousel/engine/useMetrics.js";
+import { serializeTransform } from "../carousel/layout/types.js";
+import { useGridContext } from "./context.js";
+import { gridItemAt, planeHit, snapTarget, tiltMatrix } from "./math.js";
+import { latticeOffset, planeOffset, poseCell, readCell } from "./pose.js";
+import { screenToStage } from "./open.js";
+import { GridCellContext } from "./context.js";
+/** The glide after a drag: px travelled = power · velocity, easing out over about 3 time constants. */
+const GLIDE = { power: 0.8, timeConstant: 350 };
+/** The glide ends this close to its landing, px: an exponential tail otherwise creeps on for seconds. */
+const REST_PX = 0.4;
+/** After the last wheel event, this long before a snapping grid settles on a card, ms. */
+const WHEEL_SETTLE_MS = 160;
+/** Read by screen readers, never seen. */
+const VISUALLY_HIDDEN = {
+    position: "absolute", width: 1, height: 1, margin: -1, padding: 0, overflow: "hidden",
+    clip: "rect(0 0 0 0)", whiteSpace: "nowrap", border: 0,
+};
+/**
+ * The picture and the gesture surface: a perspective box, one stage that
+ * carries the tilt (`preserve-3d`, safe here because the Grid owns the whole
+ * tree), one plane, and the mounted cells, keyed by their lattice point.
+ *
+ * ## Two write paths, one picture
+ *
+ * With no modifiers every cell sits still at its lattice point and ONE
+ * transform on the plane pans them all. With modifiers, each cell is posed
+ * relative to the focus and writes its own transform. Either way one loop,
+ * scheduled once per frame while the focus moves, does all the writing;
+ * nothing runs at rest, and React renders only when a row or column crosses
+ * the edge of the mounted range.
+ *
+ * ## Dragging a tilted plane
+ *
+ * The pointer's screen motion is cast onto the plane (`planeHit`), so the card
+ * under the finger stays under it however the plane leans. Above the horizon,
+ * where a ray misses the plane, the screen motion is used as it is.
+ *
+ * ## Keyboard and screen readers
+ *
+ * The plane repeats every card forever, so its cells can't each be a tab stop
+ * (Tab would never leave). The Viewport is the one tab stop: arrow keys move
+ * the focus a card at a time, Home / End go to the first / last item, Enter /
+ * Space activate the focused card (`onActivate`, the same call a click makes).
+ * Cells are `aria-hidden`; a polite live region names the focused item while
+ * focus is inside. So card markup should not contain links or buttons of its
+ * own: handle them in `onActivate`.
+ *
+ * ## Open views
+ *
+ * With an `open` view, a click (or Enter) opens a card: the focus pans to it
+ * and `openProgress` springs to 1. While any part of the view shows, every
+ * cell takes the cell path, and its grid pose is blended with the view's pose
+ * (written in screen px, turned into the stage by `screenToStage`). A click
+ * on a thumbnail opens that card; a click beside the cards, Esc, a drag or
+ * the wheel close it.
+ */
+export function Viewport({ children, className, style, "aria-label": ariaLabel }) {
+    const { handle, cellClassName } = useGridContext();
+    const { metrics, range, options, count, columns, items, x, y, mode } = handle;
+    const { stagger, repeat, modifiers, tilt, perspective } = options;
+    const view = options.open;
+    const { openProgress, showing } = handle;
+    // while an open view shows, every cell is posed and blended: the cell path
+    const perCell = modifiers.length > 0 || (showing && view !== undefined);
+    const tilted = tilt.x !== 0 || tilt.y !== 0 || tilt.z !== 0;
+    const deep = tilted || perCell;
+    const planeRef = useRef(null);
+    const cells = useRef(new Map()).current;
+    const frameRef = useRef(null);
+    const readFrame = useCallback(() => {
+        const f = (frameRef.current ?? (frameRef.current = { ...metrics, x: 0, y: 0, velocityX: 0, velocityY: 0, columns, count, dirX: 1 }));
+        Object.assign(f, metrics);
+        f.x = x.get();
+        f.y = y.get();
+        // at rest the speed is 0, whatever the last frame of a glide measured (speed looks must settle flat)
+        const moving = mode.get() !== "idle";
+        f.velocityX = moving ? x.getVelocity() : 0;
+        f.velocityY = moving ? y.getVelocity() : 0;
+        f.columns = columns;
+        f.count = count;
+        f.dirX = handle.rtl.current ? -1 : 1;
+        return f;
+    }, [metrics, columns, count, x, y, mode, handle.rtl]);
+    const write = useCallback(() => {
+        if (!metrics.ready)
+            return;
+        const frame = readFrame();
+        const plane = planeRef.current;
+        if (!perCell) {
+            if (!plane)
+                return;
+            const o = planeOffset(frame);
+            plane.style.transform = `translate3d(${o.x}px, ${o.y}px, 0)`;
+            return;
+        }
+        if (plane && plane.style.transform)
+            plane.style.transform = "";
+        const p = view ? openProgress.get() : 0;
+        const m = p > 0 ? tiltMatrix(tilt) : null;
+        // While the open view animates, every card changes size each frame: without a hint the browser redraws each
+        // one at every size (on a phone at DPR 3.5, a flat strip dropped to 55 fps). With `will-change` it reuses each
+        // card's drawn image; the hint comes off at rest, so the open card is redrawn sharp once it stops.
+        const animating = p > 0 && p < 1;
+        for (const rec of cells.values()) {
+            const cell = readCell(rec.state, rec.col, rec.row, rec.itemIndex, stagger, frame);
+            const b = poseCell(rec.buf, cell, frame, modifiers);
+            if (view && m) {
+                resetSlotFrameBuffer(rec.openBuf);
+                view.pose(rec.openBuf, cell, frame);
+                screenToStage(rec.openBuf, m);
+                blendBuffers(b, b, rec.openBuf, Math.min(1, p));
+            }
+            const s = rec.el.style;
+            const transform = serializeTransform(b);
+            if (transform !== rec.transform)
+                s.transform = rec.transform = transform;
+            if (b.opacity !== rec.opacity)
+                s.opacity = String((rec.opacity = b.opacity));
+            if (b.zIndex !== rec.zIndex)
+                s.zIndex = String((rec.zIndex = b.zIndex));
+            if (b.filter !== rec.filter)
+                s.filter = rec.filter = b.filter;
+            if (b.pointerEvents !== rec.pointerEvents)
+                s.pointerEvents = rec.pointerEvents = b.pointerEvents;
+            const origin = `${b.originX * 100}% ${b.originY * 100}%`;
+            if (origin !== rec.origin)
+                s.transformOrigin = rec.origin = origin;
+            if (animating !== rec.willChange)
+                s.willChange = (rec.willChange = animating) ? "transform" : "";
+        }
+    }, [metrics.ready, readFrame, perCell, cells, stagger, modifiers, view, openProgress, tilt]);
+    // after every render (new cells mounted, options changed), before paint
+    useLayoutEffect(() => {
+        write();
+    });
+    useLayoutEffect(() => {
+        const schedule = () => scheduler.preRender(write, false, true);
+        const a = x.on("change", schedule);
+        const b = y.on("change", schedule);
+        const c = openProgress.on("change", schedule);
+        // one more frame when the plane comes to rest, for looks that read the speed
+        const d = mode.on("change", schedule);
+        return () => {
+            a();
+            b();
+            c();
+            d();
+            cancelFrame(write);
+        };
+    }, [write, x, y, openProgress, mode]);
+    // ---------- drag ----------
+    const rect = useRef(null);
+    /** On-screen px per CSS px (a zoomed preview, a scaling modal): pointer offsets are divided by it. */
+    const scale = useRef(1);
+    /** Takes the viewport's on-screen box (and its scale) for the gesture that is starting. */
+    const grab = (el) => {
+        rect.current = el?.getBoundingClientRect() ?? null;
+        scale.current = el && rect.current ? screenScale(rect.current.width, el.offsetWidth) : 1;
+    };
+    const last = useRef({ x: 0, y: 0 });
+    /** Where the pointer went down: a pan starts a few px later, and those px count too. */
+    const down = useRef({ x: 0, y: 0 });
+    const moved = useRef(false);
+    /** Screen point (client px) → plane px from the focus, or null above the horizon. */
+    const toPlane = (cx, cy) => {
+        const r = rect.current;
+        if (!r)
+            return null;
+        const k = scale.current;
+        return planeHit((cx - (r.left + r.width / 2)) / k, (cy - (r.top + r.height / 2)) / k, tiltMatrix(tilt), perspective);
+    };
+    /** Plane (or, failing that, screen) motion between two screen points, CSS px. */
+    const planeDelta = (ax, ay, bx, by) => {
+        const a = toPlane(ax, ay);
+        const b = toPlane(bx, by);
+        return a && b ? { x: b.x - a.x, y: b.y - a.y } : { x: (bx - ax) / scale.current, y: (by - ay) / scale.current };
+    };
+    const dirX = () => (handle.rtl.current ? -1 : 1);
+    const onPan = (event) => {
+        if (!metrics.ready)
+            return;
+        const d = planeDelta(last.current.x, last.current.y, event.clientX, event.clientY);
+        last.current = { x: event.clientX, y: event.clientY };
+        x.set(x.get() - (d.x / metrics.pitchX) * dirX());
+        y.set(y.get() - d.y / metrics.pitchY);
+    };
+    const onPanStart = (event) => {
+        if (handle.isOpen)
+            handle.close();
+        x.stop();
+        y.stop();
+        mode.set("dragging");
+        moved.current = true;
+        grab(handle.viewportRef.current);
+        last.current = down.current;
+        onPan(event);
+    };
+    const onPanEnd = (event, info) => {
+        if (!metrics.ready)
+            return;
+        const settle = () => {
+            if (mode.get() === "settling")
+                mode.set("idle");
+        };
+        // the release velocity, cast onto the plane at the pointer (16 ms of travel)
+        const dt = 0.016;
+        const d = planeDelta(event.clientX, event.clientY, event.clientX + info.velocity.x * dt, event.clientY + info.velocity.y * dt);
+        const vx = -(d.x / dt / metrics.pitchX) * dirX();
+        const vy = -(d.y / dt) / metrics.pitchY;
+        const from = { x: x.get(), y: y.get() };
+        if (handle.reducedMotion.current) {
+            if (options.snap) {
+                const at = snapTarget(from, stagger);
+                x.set(at.x);
+                y.set(at.y);
+            }
+            mode.set("idle");
+            return;
+        }
+        const ideal = { x: from.x + GLIDE.power * vx, y: from.y + GLIDE.power * vy };
+        const to = options.snap ? snapTarget(ideal, stagger) : ideal;
+        if (Math.abs(to.x - from.x) < 1e-4 && Math.abs(to.y - from.y) < 1e-4) {
+            mode.set("idle");
+            return;
+        }
+        mode.set("settling");
+        // motion skips an animation whose two keyframes are equal (carousel/physics/landing.ts), so the
+        // keyframe is the landing; modifyTarget makes the glide end there, snapped or not
+        const glide = (v, velocity, target, pitch) => animate(v, target, { type: "inertia", velocity, ...GLIDE, restDelta: REST_PX / pitch, modifyTarget: () => target });
+        void Promise.all([glide(x, vx, to.x, metrics.pitchX), glide(y, vy, to.y, metrics.pitchY)]).then(settle);
+    };
+    // ---------- hover, focus, the last touch (they pause the drift) ----------
+    const hovered = useRef(false);
+    const [focusWithin, setFocusWithin] = useState(false);
+    const focusWithinRef = useRef(false);
+    const lastInput = useRef(0);
+    const touch = () => {
+        lastInput.current = performance.now();
+    };
+    // ---------- keyboard ----------
+    const onKeyDown = (event) => {
+        if (event.target !== event.currentTarget)
+            return; // keys inside the consumer's own controls are theirs
+        const rows = Math.max(1, Math.floor(metrics.height / Math.max(metrics.pitchY, 1)) - 1);
+        const right = dirX();
+        const keys = {
+            ArrowRight: () => handle.step(right, 0),
+            ArrowLeft: () => handle.step(-right, 0),
+            ArrowDown: () => handle.step(0, 1),
+            ArrowUp: () => handle.step(0, -1),
+            PageDown: () => handle.step(0, rows),
+            PageUp: () => handle.step(0, -rows),
+            Home: () => handle.goTo(0),
+            End: () => handle.goTo(count - 1),
+            Enter: () => handle.activate(),
+            " ": () => handle.activate(),
+        };
+        const run = keys[event.key];
+        if (!run || !metrics.ready || count === 0)
+            return;
+        event.preventDefault();
+        touch();
+        run();
+    };
+    // ---------- Esc closes an open card, wherever focus is ----------
+    const { isOpen, close } = handle;
+    useEffect(() => {
+        if (!isOpen)
+            return;
+        const onKey = (event) => {
+            if (event.key === "Escape")
+                close();
+        };
+        document.addEventListener("keydown", onKey);
+        return () => document.removeEventListener("keydown", onKey);
+    }, [isOpen, close]);
+    // ---------- wheel (opt-in) ----------
+    // the settle timer outlives the listener: the listener is re-attached on every render (fresh closure),
+    // and a re-render (a row mounting) must not cancel a pending settle
+    const wheelSettle = useRef(0);
+    useEffect(() => () => window.clearTimeout(wheelSettle.current), []);
+    useEffect(() => {
+        const el = handle.viewportRef.current;
+        if (!el || !options.wheel || !metrics.ready)
+            return;
+        const onWheel = (event) => {
+            event.preventDefault();
+            touch();
+            if (handle.isOpen)
+                handle.close();
+            if (mode.get() !== "idle") {
+                x.stop();
+                y.stop();
+                mode.set("idle");
+            }
+            const unit = event.deltaMode === 1 ? 16 : event.deltaMode === 2 ? metrics.height : 1;
+            // shift + wheel scrolls sideways on a mouse with one wheel
+            grab(el);
+            // the deltas are CSS px of scroll: as screen px under a scaled ancestor, so planeDelta's conversion keeps them
+            const k = scale.current;
+            const dx = (event.shiftKey && event.deltaX === 0 ? event.deltaY : event.deltaX) * unit * k;
+            const dy = (event.shiftKey && event.deltaX === 0 ? 0 : event.deltaY) * unit * k;
+            const r = rect.current;
+            const cx = r.left + r.width / 2;
+            const cy = r.top + r.height / 2;
+            const d = planeDelta(cx, cy, cx + dx, cy + dy);
+            x.set(x.get() + (d.x / metrics.pitchX) * dirX());
+            y.set(y.get() + d.y / metrics.pitchY);
+            if (options.snap) {
+                window.clearTimeout(wheelSettle.current);
+                wheelSettle.current = window.setTimeout(() => handle.step(0, 0), WHEEL_SETTLE_MS);
+            }
+        };
+        el.addEventListener("wheel", onWheel, { passive: false });
+        return () => el.removeEventListener("wheel", onWheel);
+    });
+    // ---------- drift (opt-in) ----------
+    const [visible, setVisible] = useState(true);
+    useEffect(() => {
+        const el = handle.viewportRef.current;
+        if (!el || typeof IntersectionObserver === "undefined")
+            return;
+        const io = new IntersectionObserver((entries) => {
+            const entry = entries[0];
+            if (entry)
+                setVisible(entry.isIntersecting);
+        });
+        io.observe(el);
+        return () => io.disconnect();
+    }, [handle.viewportRef]);
+    const { drift, driftDelay } = options;
+    useEffect(() => {
+        if ((drift.x === 0 && drift.y === 0) || !visible || !metrics.ready)
+            return;
+        let last = 0;
+        let id = requestAnimationFrame(function tick(now) {
+            const dt = last === 0 ? 0 : Math.min(now - last, 100) / 1000;
+            last = now;
+            const paused = handle.reducedMotion.current ||
+                hovered.current ||
+                focusWithinRef.current ||
+                mode.get() !== "idle" ||
+                openProgress.get() > 0 ||
+                now - lastInput.current < driftDelay;
+            if (!paused && dt > 0) {
+                x.set(x.get() + (drift.x / metrics.pitchX) * dt);
+                y.set(y.get() + (drift.y / metrics.pitchY) * dt);
+            }
+            id = requestAnimationFrame(tick);
+        });
+        return () => cancelAnimationFrame(id);
+    }, [drift.x, drift.y, driftDelay, visible, metrics.ready, metrics.pitchX, metrics.pitchY, x, y, mode, handle.reducedMotion]);
+    const hintId = useId();
+    const focused = handle.focus;
+    const announce = focusWithin && focused.item !== null ? handle.itemLabel(items[focused.item], focused.item) : "";
+    // ---------- cells ----------
+    const cellValues = useRef(new Map()).current;
+    const cellValue = (key, col, row, itemIndex, item) => {
+        const open = handle.isOpen && col === focused.col && row === focused.row;
+        const prev = cellValues.get(key);
+        if (prev && prev.itemIndex === itemIndex && prev.item === item && prev.open === open && prev.openProgress === openProgress)
+            return prev;
+        const next = { key, col, row, itemIndex, item, open, openProgress };
+        cellValues.set(key, next);
+        return next;
+    };
+    const nodes = [];
+    if (metrics.ready && count > 0) {
+        const left = (metrics.width - metrics.cellWidth) / 2;
+        const top = (metrics.height - metrics.cellHeight) / 2;
+        const frame = readFrame();
+        for (let row = range.row0; row <= range.row1; row++) {
+            for (let col = range.col0; col <= range.col1; col++) {
+                const itemIndex = gridItemAt(col, row, count, columns, repeat);
+                if (itemIndex === null)
+                    continue;
+                const key = `${col}:${row}`;
+                const at = latticeOffset(col, row, stagger, frame);
+                nodes.push(_jsx("div", { ref: (el) => {
+                        if (!el)
+                            return;
+                        const rec = cells.get(key);
+                        if (rec && rec.el === el) {
+                            rec.itemIndex = itemIndex;
+                        }
+                        else {
+                            cells.set(key, {
+                                el, col, row, itemIndex,
+                                state: { col, row, itemIndex, dx: 0, dy: 0, distance: 0 },
+                                buf: createSlotFrameBuffer(),
+                                openBuf: createSlotFrameBuffer(),
+                                transform: "", opacity: 1, zIndex: 0, filter: "none", pointerEvents: "auto", origin: "50% 50%", willChange: false,
+                            });
+                        }
+                        return () => {
+                            if (cells.get(key)?.el === el)
+                                cells.delete(key);
+                        };
+                    }, "data-sx-grid-cell": "", "data-col": col, "data-row": row, "data-sx-grid-focus": col === focused.col && row === focused.row ? "" : undefined, "aria-hidden": true, onClick: handle.onActivate || view
+                        ? () => {
+                            const centre = col === focused.col && row === focused.row;
+                            // open: a thumbnail opens its card; the open card itself only activates
+                            if (handle.isOpen && !centre)
+                                return handle.openCell({ col, row });
+                            handle.onActivate?.(items[itemIndex], itemIndex);
+                            if (view && !handle.isOpen)
+                                handle.openCell({ col, row });
+                        }
+                        : undefined, className: cellClassName, style: {
+                        position: "absolute",
+                        left,
+                        top,
+                        pointerEvents: "auto",
+                        transform: perCell ? undefined : `translate3d(${at.x}px, ${at.y}px, 0)`,
+                        transformStyle: deep ? "preserve-3d" : undefined,
+                    }, children: _jsx(GridCellContext.Provider, { value: cellValue(key, col, row, itemIndex, items[itemIndex]), children: children({ key, col, row, itemIndex, item: items[itemIndex] }) }) }, key));
+            }
+        }
+    }
+    const stageTransform = tilted ? `rotateX(${tilt.x}deg) rotateY(${tilt.y}deg) rotateZ(${tilt.z}deg)` : undefined;
+    return (_jsxs(motion.div, { ref: handle.viewportRef, "data-sx-grid": "", role: "region", "aria-label": ariaLabel, "aria-describedby": hintId, tabIndex: count > 0 ? 0 : undefined, onKeyDown: onKeyDown, onFocus: () => {
+            focusWithinRef.current = true;
+            setFocusWithin(true);
+        }, onBlur: (e) => {
+            if (e.currentTarget.contains(e.relatedTarget))
+                return;
+            focusWithinRef.current = false;
+            setFocusWithin(false);
+            touch();
+        }, onPointerEnter: (e) => {
+            if (e.pointerType === "mouse")
+                hovered.current = true;
+        }, onPointerLeave: () => {
+            hovered.current = false;
+            touch();
+        }, className: className, style: {
+            position: "relative",
+            overflow: "hidden",
+            perspective: deep && perspective > 0 ? perspective : undefined,
+            touchAction: options.drag ? "none" : undefined,
+            cursor: options.drag ? "grab" : undefined,
+            userSelect: options.drag ? "none" : undefined,
+            ...style,
+        }, onPointerDown: (e) => {
+            touch();
+            moved.current = false;
+            down.current = { x: e.clientX, y: e.clientY };
+            // a tap catches a glide
+            if (mode.get() === "settling") {
+                x.stop();
+                y.stop();
+                mode.set("idle");
+            }
+        }, onClick: (e) => {
+            // a click beside the cards closes an open card
+            if (handle.isOpen && !e.target.closest("[data-sx-grid-cell]"))
+                handle.close();
+        }, onClickCapture: (e) => {
+            if (moved.current) {
+                e.preventDefault();
+                e.stopPropagation();
+            }
+        }, onPanStart: options.drag ? onPanStart : undefined, onPan: options.drag ? onPan : undefined, onPanEnd: options.drag ? onPanEnd : undefined, children: [_jsxs("p", { id: hintId, style: VISUALLY_HIDDEN, children: ["Drag or use the arrow keys to move through the cards", view ? "; Enter opens the card in the middle, Escape closes it" : handle.onActivate ? "; Enter opens the card in the middle" : "", "."] }), _jsx("p", { "aria-live": "polite", style: VISUALLY_HIDDEN, children: announce }), _jsx("div", { ref: handle.probeRef, "aria-hidden": true, "data-sx-grid-probe": "", className: cellClassName, style: { position: "absolute", visibility: "hidden", pointerEvents: "none" } }), _jsx("div", { "data-sx-grid-stage": "", style: {
+                    position: "absolute",
+                    inset: 0,
+                    transform: stageTransform,
+                    transformStyle: deep ? "preserve-3d" : undefined,
+                    // the stage and plane are full-size boxes in the 3D scene: sunk (bulged) cards sit behind them, so
+                    // only the cells take the pointer; gaps fall through to the Viewport, which handles the drag
+                    pointerEvents: "none",
+                }, children: _jsx("div", { ref: planeRef, "data-sx-grid-plane": "", style: { position: "absolute", inset: 0, transformStyle: deep ? "preserve-3d" : undefined, willChange: perCell ? undefined : "transform" }, children: nodes }) })] }));
+}

package/dist/grid/context.d.ts

@@ -0,0 +1,26 @@
+import type { MotionValue } from "motion/react";
+import type { GridHandle } from "./useGridEngine.js";
+export interface GridContextValue<T> {
+    readonly handle: GridHandle<T>;
+    /** On the sizing probe AND every cell, so the measured pitch and the cell box agree. */
+    readonly cellClassName: string;
+}
+export declare const GridContext: import("react").Context<GridContextValue<unknown> | null>;
+export declare function useGridContext<T>(): GridContextValue<T>;
+/** The Grid's handle (focus, controls, measurements) from inside `<Grid.Root>`. */
+export declare function useGrid<T = unknown>(): GridHandle<T>;
+/** One mounted cell, as `useGridCell()` hands it to the card inside. */
+export interface GridCellInfo<T> {
+    readonly key: string;
+    readonly col: number;
+    readonly row: number;
+    readonly itemIndex: number;
+    readonly item: T;
+    /** True when this cell is the open card. */
+    readonly open: boolean;
+    /** The Grid's open progress, 0 closed … 1 open (load a larger image as it rises). */
+    readonly openProgress: MotionValue<number>;
+}
+export declare const GridCellContext: import("react").Context<GridCellInfo<unknown> | null>;
+/** The cell a card is rendered in: its lattice point, item, and whether it is the open card. */
+export declare function useGridCell<T = unknown>(): GridCellInfo<T>;

package/dist/grid/context.js

@@ -0,0 +1,21 @@
+"use client";
+import { createContext, useContext } from "react";
+export const GridContext = createContext(null);
+export function useGridContext() {
+    const value = useContext(GridContext);
+    if (!value)
+        throw new Error("Grid parts must be rendered inside <Grid.Root>.");
+    return value;
+}
+/** The Grid's handle (focus, controls, measurements) from inside `<Grid.Root>`. */
+export function useGrid() {
+    return useGridContext().handle;
+}
+export const GridCellContext = createContext(null);
+/** The cell a card is rendered in: its lattice point, item, and whether it is the open card. */
+export function useGridCell() {
+    const value = useContext(GridCellContext);
+    if (!value)
+        throw new Error("useGridCell() must be called inside a Grid.Viewport cell.");
+    return value;
+}

package/dist/grid/defaults.d.ts

@@ -0,0 +1,21 @@
+/**
+ * What an unset option means, in one place: the engine (useGridEngine) reads these, and the
+ * option schema's defaults are tested against them. `tilt` and `drift` are per axis.
+ */
+export declare const GRID_DEFAULTS: {
+    readonly columns: "auto";
+    readonly gap: 24;
+    readonly stagger: 0;
+    readonly repeat: "sequence";
+    readonly perspective: 1200;
+    readonly drag: true;
+    readonly snap: false;
+    readonly initial: 0;
+    readonly margin: 1;
+    readonly reach: 12;
+    readonly maxCells: 160;
+    readonly tilt: 0;
+    readonly wheel: false;
+    readonly drift: 0;
+    readonly driftDelay: 2000;
+};

package/dist/grid/defaults.js

@@ -0,0 +1,23 @@
+// A plain module (no "use client"): a constant exported from the engine's client module would reach a Server
+// Component as an opaque reference, not as its value.
+/**
+ * What an unset option means, in one place: the engine (useGridEngine) reads these, and the
+ * option schema's defaults are tested against them. `tilt` and `drift` are per axis.
+ */
+export const GRID_DEFAULTS = {
+    columns: "auto",
+    gap: 24,
+    stagger: 0,
+    repeat: "sequence",
+    perspective: 1200,
+    drag: true,
+    snap: false,
+    initial: 0,
+    margin: 1,
+    reach: 12,
+    maxCells: 160,
+    tilt: 0,
+    wheel: false,
+    drift: 0,
+    driftDelay: 2000,
+};

package/dist/grid/index.d.ts

@@ -0,0 +1,17 @@
+import { Root } from "./Root.js";
+import { Viewport } from "./Viewport.js";
+import { Panel } from "./Panel.js";
+/**
+ * An endless plane of cards you pan in any direction: `Grid.Root` holds the
+ * state, `Grid.Viewport` draws it and takes the gestures. Children supply the
+ * pixels, as with the carousel.
+ */
+export declare const Grid: {
+    Root: typeof Root;
+    Viewport: typeof Viewport;
+    Panel: typeof Panel;
+};
+export { Root as GridRoot, Viewport as GridViewport, Panel as GridPanel };
+export type { GridPanelProps } from "./Panel.js";
+export type { GridRootProps } from "./Root.js";
+export type { GridViewportProps } from "./Viewport.js";

package/dist/grid/index.js

@@ -0,0 +1,10 @@
+import { Root } from "./Root.js";
+import { Viewport } from "./Viewport.js";
+import { Panel } from "./Panel.js";
+/**
+ * An endless plane of cards you pan in any direction: `Grid.Root` holds the
+ * state, `Grid.Viewport` draws it and takes the gestures. Children supply the
+ * pixels, as with the carousel.
+ */
+export const Grid = { Root, Viewport, Panel };
+export { Root as GridRoot, Viewport as GridViewport, Panel as GridPanel };