@sharedex/ui 0.0.0-stage → 0.9.0

package/dist/grid/pose.d.ts

@@ -0,0 +1,35 @@
+/**
+ * How a cell is drawn: pure, so the tests check it against `dist/` and the
+ * Viewport's two write paths share one definition.
+ *
+ * - **Plane path** (no modifiers): each cell sits still at its lattice point
+ *   (`latticeOffset`) and one transform on the plane (`planeOffset`) moves
+ *   them all.
+ * - **Cell path** (modifiers): each cell's buffer is reset, placed relative to
+ *   the focus (`poseCell`), handed to the modifiers, and written.
+ *
+ * Both give the same picture: lattice − focus, in px, mirrored in RTL.
+ */
+import { type SlotFrameBuffer } from "../carousel/engine/types.js";
+import type { GridCellState, GridFrame, GridModifier } from "./types.js";
+/** A cell's resting offset on the plane, px from the plane's origin. */
+export declare function latticeOffset(col: number, row: number, stagger: number, frame: GridFrame): {
+    x: number;
+    y: number;
+};
+/** The plane's offset that brings the focus to the viewport centre, px. */
+export declare function planeOffset(frame: GridFrame): {
+    x: number;
+    y: number;
+};
+/** Fills `out` for cell (`col`, `row`) this frame. Mutates and returns `out`. */
+export declare function readCell(out: {
+    col: number;
+    row: number;
+    itemIndex: number | null;
+    dx: number;
+    dy: number;
+    distance: number;
+}, col: number, row: number, itemIndex: number | null, stagger: number, frame: GridFrame): GridCellState;
+/** The cell path: identity, then the lattice point relative to the focus, then the modifiers. */
+export declare function poseCell(buf: SlotFrameBuffer, cell: GridCellState, frame: GridFrame, modifiers: readonly GridModifier[]): SlotFrameBuffer;

package/dist/grid/pose.js

@@ -0,0 +1,41 @@
+/**
+ * How a cell is drawn: pure, so the tests check it against `dist/` and the
+ * Viewport's two write paths share one definition.
+ *
+ * - **Plane path** (no modifiers): each cell sits still at its lattice point
+ *   (`latticeOffset`) and one transform on the plane (`planeOffset`) moves
+ *   them all.
+ * - **Cell path** (modifiers): each cell's buffer is reset, placed relative to
+ *   the focus (`poseCell`), handed to the modifiers, and written.
+ *
+ * Both give the same picture: lattice − focus, in px, mirrored in RTL.
+ */
+import { resetSlotFrameBuffer } from "../carousel/engine/types.js";
+import { rowShift } from "./math.js";
+/** A cell's resting offset on the plane, px from the plane's origin. */
+export function latticeOffset(col, row, stagger, frame) {
+    return { x: (col + rowShift(row, stagger)) * frame.pitchX * frame.dirX, y: row * frame.pitchY };
+}
+/** The plane's offset that brings the focus to the viewport centre, px. */
+export function planeOffset(frame) {
+    return { x: -frame.x * frame.pitchX * frame.dirX, y: -frame.y * frame.pitchY };
+}
+/** Fills `out` for cell (`col`, `row`) this frame. Mutates and returns `out`. */
+export function readCell(out, col, row, itemIndex, stagger, frame) {
+    out.col = col;
+    out.row = row;
+    out.itemIndex = itemIndex;
+    out.dx = col + rowShift(row, stagger) - frame.x;
+    out.dy = row - frame.y;
+    out.distance = Math.hypot(out.dx, out.dy);
+    return out;
+}
+/** The cell path: identity, then the lattice point relative to the focus, then the modifiers. */
+export function poseCell(buf, cell, frame, modifiers) {
+    resetSlotFrameBuffer(buf);
+    buf.x = cell.dx * frame.pitchX * frame.dirX;
+    buf.y = cell.dy * frame.pitchY;
+    for (const modify of modifiers)
+        modify(buf, cell, frame);
+    return buf;
+}

package/dist/grid/types.d.ts

@@ -0,0 +1,50 @@
+import type { SlotFrameBuffer } from "../carousel/engine/types.js";
+/** Sizes the Grid measured, px. */
+export interface GridMetrics {
+    readonly width: number;
+    readonly height: number;
+    readonly cellWidth: number;
+    readonly cellHeight: number;
+    /** Cell plus gap. */
+    readonly pitchX: number;
+    readonly pitchY: number;
+    readonly ready: boolean;
+}
+/** What every cell modifier sees this frame. Shared and mutated: never hold it across frames. */
+export interface GridFrame extends GridMetrics {
+    /** The focus, cells (reading order: x grows towards the end of a row). */
+    readonly x: number;
+    readonly y: number;
+    /** Cells per second. */
+    readonly velocityX: number;
+    readonly velocityY: number;
+    readonly columns: number;
+    readonly count: number;
+    /** Physical x = reading x × `dirX` (-1 in RTL). */
+    readonly dirX: 1 | -1;
+}
+/** One mounted cell this frame. Shared and mutated: never hold it across frames. */
+export interface GridCellState {
+    readonly col: number;
+    readonly row: number;
+    readonly itemIndex: number | null;
+    /** From the focus to this cell's centre, cells, reading order (stagger included). */
+    readonly dx: number;
+    readonly dy: number;
+    /** `hypot(dx, dy)`. */
+    readonly distance: number;
+}
+/**
+ * Writes a cell's look into the buffer, like a carousel `SlotModifier`. The
+ * Grid's own placement runs first (the cell at its lattice point, px from the
+ * viewport centre); modifiers add to it.
+ */
+export type GridModifier = (buf: SlotFrameBuffer, cell: GridCellState, frame: GridFrame) => void;
+/** One cell handed to the Viewport's render function. */
+export interface GridCell<T> {
+    readonly key: string;
+    readonly col: number;
+    readonly row: number;
+    readonly itemIndex: number;
+    readonly item: T;
+}

package/dist/grid/types.js

@@ -0,0 +1 @@
+export {};

package/dist/grid/useGridEngine.d.ts

@@ -0,0 +1,126 @@
+import { type MotionValue } from "motion/react";
+import { type GridCellRef, type GridRange, type GridRepeat, type GridTilt } from "./math.js";
+import { type BulgeOptions, type FogOptions } from "./modifiers.js";
+import type { GridOpenView } from "./open.js";
+import type { GridMetrics, GridModifier } from "./types.js";
+export interface GridOptions<T = unknown> {
+    /** Columns in one repeating block. `"auto"`: one block covers the viewport width. Default `"auto"`. */
+    readonly columns?: number | "auto";
+    /** px between cells, both ways. Default `24`. */
+    readonly gap?: number;
+    /** Shift of every other row, a fraction of a cell (the brick pattern). Default `0`. */
+    readonly stagger?: number;
+    /** When the items don't fill a block: `"sequence"` runs on, `"blank"` leaves cells empty. Default `"sequence"`. */
+    readonly repeat?: GridRepeat;
+    /** Lean the plane, degrees: `{ x: 24, z: -8 }` leans it back and turns it. */
+    readonly tilt?: GridTilt;
+    /** CSS perspective, px. Default `1200`; `0` for none. */
+    readonly perspective?: number;
+    /** Drag to pan, with a glide on release. Default `true`. */
+    readonly drag?: boolean;
+    /** Land the glide on a cell centre. Default `false`. */
+    readonly snap?: boolean;
+    /** The item centred first. Default `0`. */
+    readonly initial?: number;
+    /** Per-cell looks, after the Grid's own placement and `bulge` / `fog`. Memoize the array. */
+    readonly modifiers?: readonly GridModifier[];
+    /** Dome the plane towards the viewer at the focus: the edge sinks this many px (or `BulgeOptions`). */
+    readonly bulge?: number | BulgeOptions;
+    /** Fade cards out with their distance from the focus: `true`, or `FogOptions` in cells. */
+    readonly fog?: boolean | FogOptions;
+    /** Pan with the mouse wheel / trackpad. Off by default, so the page scroll is never taken. */
+    readonly wheel?: boolean;
+    /** Idle pan, px per second on the plane: `{ x: 12, y: 6 }`. Pauses while hovered, focused or dragged. */
+    readonly drift?: {
+        readonly x?: number;
+        readonly y?: number;
+    };
+    /** ms after the last touch, scroll, key or hover before the drift resumes. Default `2000`. */
+    readonly driftDelay?: number;
+    /** Called on a click on a card (not after a drag), and on Enter / Space for the focused card. */
+    readonly onActivate?: (item: T, index: number) => void;
+    /** What a screen reader announces as the focus moves. Default: "Item 3 of 30". */
+    readonly itemLabel?: (item: T, index: number) => string;
+    /** How a card opens (`gridOpen.zoom()` / `strip()` / `panel()`). With it, a click or Enter opens the card. */
+    readonly open?: GridOpenView;
+    /** Extra cells mounted on every side. Default `1`. */
+    readonly margin?: number;
+    /** Cells further than this from the focus are not mounted (a steep tilt shows the horizon). Default `12`. */
+    readonly reach?: number;
+    /** At most this many cells mounted. Default `160`. */
+    readonly maxCells?: number;
+}
+export type GridMode = "idle" | "dragging" | "settling";
+export interface ResolvedGridOptions {
+    readonly columns: number | "auto";
+    readonly gap: number;
+    readonly stagger: number;
+    readonly repeat: GridRepeat;
+    readonly perspective: number;
+    readonly drag: boolean;
+    readonly snap: boolean;
+    readonly margin: number;
+    readonly reach: number;
+    readonly maxCells: number;
+    readonly tilt: Required<GridTilt>;
+    /** `bulge`, `fog`, then the custom modifiers: everything the cell path runs. */
+    readonly modifiers: readonly GridModifier[];
+    readonly wheel: boolean;
+    readonly drift: {
+        readonly x: number;
+        readonly y: number;
+    };
+    readonly driftDelay: number;
+    readonly open: GridOpenView | undefined;
+}
+/** The focused cell: the lattice point nearest the focus, and its item. */
+export interface GridFocus extends GridCellRef {
+    readonly item: number | null;
+}
+/** The Grid's state and controls. `x` / `y` are the focus in cells. */
+export interface GridHandle<T> {
+    readonly items: readonly T[];
+    readonly count: number;
+    readonly columns: number;
+    readonly metrics: GridMetrics;
+    /** The mounted lattice range (changes only when a row or column crosses the edge). */
+    readonly range: GridRange;
+    readonly x: MotionValue<number>;
+    readonly y: MotionValue<number>;
+    readonly mode: MotionValue<GridMode>;
+    /** Pan to the nearest copy of `item` (spring; a jump under reduced motion). */
+    goTo(item: number): void;
+    /** Move the focus by whole cells (arrow keys), from where the last move was aimed. */
+    step(cols: number, rows: number): void;
+    /** The item at the focus. */
+    focusItem(): number | null;
+    /** The focused cell; changes only when the focus crosses into another cell. */
+    readonly focus: GridFocus;
+    /** Calls `onActivate` for the focused item. */
+    activate(): void;
+    readonly onActivate: ((item: T, index: number) => void) | undefined;
+    readonly itemLabel: (item: T, index: number) => string;
+    /** True from `open()` until `close()`. */
+    readonly isOpen: boolean;
+    /** True while any part of the open view shows: from `open()` until the close animation ends. */
+    readonly showing: boolean;
+    /** 0 closed … 1 open; springs both ways (a jump under reduced motion). */
+    readonly openProgress: MotionValue<number>;
+    /** Open `item` (its nearest copy), or the focused card. Needs the `open` view. */
+    open(item?: number): void;
+    /** Open the card at this lattice point (a click on a cell). */
+    openCell(cell: GridCellRef): void;
+    close(): void;
+    readonly options: ResolvedGridOptions;
+    readonly viewportRef: React.RefObject<HTMLDivElement | null>;
+    readonly probeRef: React.RefObject<HTMLDivElement | null>;
+    /** True in a right-to-left context: column 0 sits at the right. */
+    readonly rtl: React.RefObject<boolean>;
+    readonly reducedMotion: React.RefObject<boolean>;
+}
+/**
+ * The Grid's engine: measures, holds the focus as two MotionValues in cell
+ * units, and keeps the mounted range in step with them. Rendering and input
+ * live in `Grid.Viewport`.
+ */
+export declare function useGridEngine<T>(items: readonly T[], options?: GridOptions<T>): GridHandle<T>;

package/dist/grid/useGridEngine.js

@@ -0,0 +1,270 @@
+"use client";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { animate, useMotionValue } from "motion/react";
+import { cellCentre, gridColumns, gridItemAt, nearestCopy, snapTarget, visibleCells, } from "./math.js";
+import { bulge as bulgeModifier, fog as fogModifier } from "./modifiers.js";
+import { screenScale } from "../carousel/engine/useMetrics.js";
+import { GRID_DEFAULTS } from "./defaults.js";
+const EMPTY = { width: 0, height: 0, cellWidth: 0, cellHeight: 0, pitchX: 0, pitchY: 0, ready: false };
+const NO_RANGE = { col0: 0, col1: -1, row0: 0, row1: -1 };
+const NO_MODIFIERS = [];
+const GO_TO = { type: "spring", visualDuration: 0.5, bounce: 0.1 };
+const NO_FOCUS = { col: 0, row: 0, item: null };
+const sameRange = (a, b) => a.col0 === b.col0 && a.col1 === b.col1 && a.row0 === b.row0 && a.row1 === b.row1;
+/**
+ * The Grid's engine: measures, holds the focus as two MotionValues in cell
+ * units, and keeps the mounted range in step with them. Rendering and input
+ * live in `Grid.Viewport`.
+ */
+export function useGridEngine(items, options = {}) {
+    const D = GRID_DEFAULTS;
+    const gap = options.gap ?? D.gap;
+    const tilt = options.tilt;
+    const bulgeOption = options.bulge;
+    const fogOption = options.fog;
+    // bulge / fog compared by value, so an inline object doesn't rebuild the modifiers every render
+    const bulgeKey = typeof bulgeOption === "object" ? `${bulgeOption.height}/${bulgeOption.radius}` : bulgeOption;
+    const fogKey = typeof fogOption === "object" ? `${fogOption.from}/${fogOption.to}` : fogOption;
+    const resolved = useMemo(() => ({
+        columns: options.columns ?? D.columns,
+        gap,
+        stagger: options.stagger ?? D.stagger,
+        repeat: options.repeat ?? D.repeat,
+        perspective: options.perspective ?? D.perspective,
+        drag: options.drag ?? D.drag,
+        snap: options.snap ?? D.snap,
+        margin: options.margin ?? D.margin,
+        reach: options.reach ?? D.reach,
+        maxCells: options.maxCells ?? D.maxCells,
+        tilt: { x: tilt?.x ?? D.tilt, y: tilt?.y ?? D.tilt, z: tilt?.z ?? D.tilt },
+        modifiers: [
+            ...(bulgeOption ? [bulgeModifier(typeof bulgeOption === "number" ? { height: bulgeOption } : bulgeOption)] : []),
+            ...(fogOption ? [fogModifier(fogOption === true ? {} : fogOption)] : []),
+            ...(options.modifiers ?? NO_MODIFIERS),
+        ],
+        wheel: options.wheel ?? D.wheel,
+        drift: { x: options.drift?.x ?? D.drift, y: options.drift?.y ?? D.drift },
+        driftDelay: options.driftDelay ?? D.driftDelay,
+        open: options.open,
+    }), [
+        options.columns, gap, options.stagger, options.repeat, options.perspective, options.drag, options.snap,
+        options.margin, options.reach, options.maxCells, tilt?.x, tilt?.y, tilt?.z, options.modifiers,
+        bulgeKey, fogKey, options.wheel, options.drift?.x, options.drift?.y, options.driftDelay, options.open,
+    ]);
+    const viewportRef = useRef(null);
+    const probeRef = useRef(null);
+    const rtl = useRef(false);
+    const reducedMotion = useRef(false);
+    const x = useMotionValue(0);
+    const y = useMotionValue(0);
+    const mode = useMotionValue("idle");
+    const [metrics, setMetrics] = useState(EMPTY);
+    const [range, setRange] = useState(NO_RANGE);
+    const [focus, setFocus] = useState(NO_FOCUS);
+    /** Where the last pan (goTo, a key) is headed, so quick repeated keys add up. */
+    const aim = useRef(null);
+    const count = items.length;
+    const columns = gridColumns(resolved.columns, metrics.width, metrics.pitchX, count);
+    // ---------- measuring ----------
+    useEffect(() => {
+        const viewport = viewportRef.current;
+        if (!viewport)
+            return;
+        const measure = () => {
+            rtl.current = getComputedStyle(viewport).direction === "rtl";
+            const vp = viewport.getBoundingClientRect();
+            const probe = probeRef.current?.getBoundingClientRect();
+            // the plane works in CSS px; a scaled ancestor (a zoomed preview, a modal scaling in) shrinks the
+            // on-screen rects, which would bunch the cards together (as the carousel's useMetrics)
+            const k = screenScale(vp.width, viewport.offsetWidth);
+            const cellWidth = (probe?.width ?? 0) / k;
+            const cellHeight = (probe?.height ?? 0) / k;
+            const next = {
+                width: vp.width / k,
+                height: vp.height / k,
+                cellWidth,
+                cellHeight,
+                pitchX: cellWidth + gap,
+                pitchY: cellHeight + gap,
+                ready: cellWidth > 0 && cellHeight > 0 && vp.width > 0 && vp.height > 0,
+            };
+            setMetrics((prev) => prev.width === next.width && prev.height === next.height && prev.cellWidth === next.cellWidth &&
+                prev.cellHeight === next.cellHeight && prev.pitchX === next.pitchX
+                ? prev
+                : next);
+        };
+        measure();
+        if (typeof ResizeObserver === "undefined")
+            return;
+        const ro = new ResizeObserver(measure);
+        ro.observe(viewport);
+        if (probeRef.current)
+            ro.observe(probeRef.current);
+        return () => ro.disconnect();
+    }, [gap]);
+    useEffect(() => {
+        if (typeof window === "undefined" || !window.matchMedia)
+            return;
+        const mq = window.matchMedia("(prefers-reduced-motion: reduce)");
+        const sync = () => {
+            reducedMotion.current = mq.matches;
+        };
+        sync();
+        mq.addEventListener("change", sync);
+        return () => mq.removeEventListener("change", sync);
+    }, []);
+    // ---------- the first focus ----------
+    const placed = useRef(false);
+    useEffect(() => {
+        if (placed.current || !metrics.ready || count === 0)
+            return;
+        placed.current = true;
+        const i = Math.min(Math.max(0, Math.floor(options.initial ?? D.initial)), count - 1);
+        const home = cellCentre(i % columns, Math.floor(i / columns), resolved.stagger);
+        x.jump(home.x);
+        y.jump(home.y);
+    }, [metrics.ready, count, columns, options.initial, resolved.stagger, x, y]);
+    // ---------- the mounted range ----------
+    const syncRange = useCallback(() => {
+        if (!metrics.ready)
+            return;
+        const next = visibleCells({
+            width: metrics.width,
+            height: metrics.height,
+            pitchX: metrics.pitchX,
+            pitchY: metrics.pitchY,
+            position: { x: x.get(), y: y.get() },
+            stagger: resolved.stagger,
+            // the range is in reading order; a mirrored plane mirrors its turn about the vertical axis
+            tilt: rtl.current ? { x: resolved.tilt.x, y: -resolved.tilt.y, z: -resolved.tilt.z } : resolved.tilt,
+            perspective: resolved.perspective,
+            margin: resolved.margin,
+            reach: resolved.reach,
+            maxCells: resolved.maxCells,
+        });
+        setRange((prev) => (sameRange(prev, next) ? prev : next));
+        const at = snapTarget({ x: x.get(), y: y.get() }, resolved.stagger);
+        const item = gridItemAt(at.col, at.row, count, columns, resolved.repeat);
+        setFocus((prev) => (prev.col === at.col && prev.row === at.row && prev.item === item ? prev : { col: at.col, row: at.row, item }));
+    }, [metrics, resolved, x, y, count, columns]);
+    useEffect(() => {
+        syncRange();
+        const a = x.on("change", syncRange);
+        const b = y.on("change", syncRange);
+        return () => {
+            a();
+            b();
+        };
+    }, [syncRange, x, y]);
+    // ---------- controls ----------
+    /** Spring the focus to a cell centre (a jump under reduced motion). */
+    const panTo = useCallback((cell) => {
+        aim.current = cell;
+        const to = cellCentre(cell.col, cell.row, resolved.stagger);
+        if (reducedMotion.current) {
+            x.stop();
+            y.stop();
+            x.set(to.x);
+            y.set(to.y);
+            return;
+        }
+        mode.set("settling");
+        void Promise.all([animate(x, to.x, GO_TO), animate(y, to.y, GO_TO)]).then(() => {
+            if (mode.get() === "settling")
+                mode.set("idle");
+        });
+    }, [x, y, mode, resolved.stagger]);
+    const goTo = useCallback((item) => {
+        const cell = nearestCopy(item, { x: x.get(), y: y.get() }, count, columns, resolved.repeat, resolved.stagger);
+        if (cell)
+            panTo(cell);
+    }, [x, y, count, columns, resolved.repeat, resolved.stagger, panTo]);
+    const step = useCallback((cols, rows) => {
+        // mid-pan, step on from where it is headed; otherwise from the cell at the focus
+        const from = mode.get() === "settling" && aim.current ? aim.current : snapTarget({ x: x.get(), y: y.get() }, resolved.stagger);
+        panTo({ col: from.col + cols, row: from.row + rows });
+    }, [x, y, mode, resolved.stagger, panTo]);
+    const focusItem = useCallback(() => {
+        const at = snapTarget({ x: x.get(), y: y.get() }, resolved.stagger);
+        return gridItemAt(at.col, at.row, count, columns, resolved.repeat);
+    }, [x, y, count, columns, resolved.repeat, resolved.stagger]);
+    // ---------- open views ----------
+    const openProgress = useMotionValue(0);
+    const [isOpen, setIsOpen] = useState(false);
+    const [showing, setShowing] = useState(false);
+    useEffect(() => openProgress.on("change", (v) => {
+        const on = v > 0.001;
+        setShowing((prev) => (prev === on ? prev : on));
+    }), [openProgress]);
+    const playOpen = useCallback((to) => {
+        if (to === 1)
+            setShowing(true);
+        if (reducedMotion.current)
+            openProgress.jump(to);
+        else
+            void animate(openProgress, to, { type: "spring", visualDuration: 0.6, bounce: 0 });
+    }, [openProgress]);
+    const openCell = useCallback((cell) => {
+        if (!resolved.open)
+            return;
+        panTo(cell);
+        setIsOpen(true);
+        playOpen(1);
+    }, [resolved.open, panTo, playOpen]);
+    const open = useCallback((item) => {
+        const cell = item === undefined
+            ? snapTarget({ x: x.get(), y: y.get() }, resolved.stagger)
+            : nearestCopy(item, { x: x.get(), y: y.get() }, count, columns, resolved.repeat, resolved.stagger);
+        if (cell)
+            openCell(cell);
+    }, [x, y, count, columns, resolved.repeat, resolved.stagger, openCell]);
+    const close = useCallback(() => {
+        setIsOpen(false);
+        playOpen(0);
+    }, [playOpen]);
+    // without an open view nothing can be open
+    useEffect(() => {
+        if (!resolved.open && (isOpen || openProgress.get() > 0)) {
+            setIsOpen(false);
+            openProgress.jump(0);
+        }
+    }, [resolved.open, isOpen, openProgress]);
+    const onActivate = options.onActivate;
+    const itemLabel = options.itemLabel;
+    const activate = useCallback(() => {
+        const i = focusItem();
+        if (i !== null && onActivate)
+            onActivate(items[i], i);
+        if (i !== null && resolved.open && !isOpen)
+            open();
+    }, [focusItem, onActivate, items, resolved.open, isOpen, open]);
+    const label = useCallback((item, index) => (itemLabel ? itemLabel(item, index) : `Item ${index + 1} of ${count}`), [itemLabel, count]);
+    return useMemo(() => ({
+        items,
+        count,
+        columns,
+        metrics,
+        range,
+        x,
+        y,
+        mode,
+        goTo,
+        step,
+        focusItem,
+        focus,
+        activate,
+        onActivate,
+        itemLabel: label,
+        isOpen,
+        showing,
+        openProgress,
+        open,
+        openCell,
+        close,
+        options: resolved,
+        viewportRef,
+        probeRef,
+        rtl,
+        reducedMotion,
+    }), [items, count, columns, metrics, range, x, y, mode, goTo, step, focusItem, focus, activate, onActivate, label, isOpen, showing, openProgress, open, openCell, close, resolved]);
+}