@sharedex/ui 0.0.0-stage → 0.10.0

package/dist/gpu/surface.d.ts

@@ -0,0 +1,46 @@
+import type { GpuContext } from "../backgrounds/types.js";
+/** How long a host may sit off screen before its context is handed back. */
+export declare const RELEASE_AFTER_MS = 3000;
+/** More context losses than this while on screen (within LOSS_WINDOW_MS) and the host settles on its fallback. */
+export declare const MAX_LOSSES = 3;
+export declare const LOSS_WINDOW_MS = 10000;
+export declare const CONTEXT_ATTRIBUTES: WebGLContextAttributes;
+export interface SurfaceHooks<S> {
+    readonly api: "webgl" | "webgl2";
+    /** Named in the console when a shader does not compile. */
+    readonly label: string;
+    /** Compile and allocate on a fresh context. Throw `WebglUnavailable` when the device cannot. */
+    init(gl: GpuContext): S;
+    dispose(gl: GpuContext, state: S): void;
+    /** Is the host on screen now? Asked again before a delayed release and after a loss. */
+    isVisible(): boolean;
+    /** The context is about to go: stop drawing. */
+    onRelease?(): void;
+    /** A fresh canvas is needed (the context was released or lost and the host is on screen again). */
+    renew(): void;
+    /** The device cannot run it: show the fallback. */
+    fail(): void;
+    /** Loss times, kept by the host across canvases (each renew is a new surface). */
+    readonly losses: {
+        current: number[];
+    };
+}
+export interface GpuSurface<S> {
+    /** The live context and its state, or null. */
+    readonly live: {
+        readonly gl: GpuContext;
+        readonly state: S;
+    } | null;
+    /** The live context, created on first call. Null when the device cannot (`fail` was called). */
+    ensure(): {
+        readonly gl: GpuContext;
+        readonly state: S;
+    } | null;
+    /** The host went off screen: release the context after RELEASE_AFTER_MS unless it comes back. */
+    hidden(): void;
+    /** The host is on screen. False when the context is gone and `renew` was called: stop, a new canvas is coming. */
+    shown(): boolean;
+    /** Unmount: free everything now. */
+    destroy(): void;
+}
+export declare function createGpuSurface<S>(canvas: HTMLCanvasElement, hooks: SurfaceHooks<S>): GpuSurface<S>;

package/dist/gpu/surface.js

@@ -0,0 +1,127 @@
+// ---------------------------------------------------------------------------
+// The WebGL context lifecycle, shared by every host that draws with WebGL
+// (backgrounds' WebglHost, transitions' ShaderStage). No React: the host keeps
+// the canvas generation and the "failed" flag in its own state and hands this
+// the callbacks that change them.
+//
+// A page gets only ~16 live WebGL contexts, so a surface:
+// - creates its context on first need (the host calls `ensure()` once it is on
+//   screen), not on mount;
+// - hands it back (`loseContext`) after RELEASE_AFTER_MS off screen; a released
+//   or lost context cannot be revived, so the host renders a fresh canvas
+//   (`renew`) when it returns;
+// - gives up (`fail`, the host shows its fallback) when WebGL, an extension or
+//   a compile is missing, or after MAX_LOSSES losses within LOSS_WINDOW_MS.
+// ---------------------------------------------------------------------------
+import { WebglUnavailable } from "../backgrounds/runtime/webgl.js";
+/** How long a host may sit off screen before its context is handed back. */
+export const RELEASE_AFTER_MS = 3000;
+/** More context losses than this while on screen (within LOSS_WINDOW_MS) and the host settles on its fallback. */
+export const MAX_LOSSES = 3;
+export const LOSS_WINDOW_MS = 10000;
+export const CONTEXT_ATTRIBUTES = {
+    alpha: true,
+    premultipliedAlpha: true,
+    antialias: false,
+    depth: false,
+    stencil: false,
+    preserveDrawingBuffer: false,
+    powerPreference: "low-power",
+};
+/**
+ * Canvases whose context a surface handed back. A host's effect can run again
+ * on the same canvas element (React StrictMode mounts twice; an option change
+ * re-runs the effect), and `getContext` then returns the dead context: Three.js
+ * throws on it, so the host must renew instead.
+ */
+const spent = new WeakSet();
+export function createGpuSurface(canvas, hooks) {
+    let live = null;
+    let released = false;
+    let timer;
+    const ensure = () => {
+        if (live)
+            return live;
+        if (spent.has(canvas)) {
+            released = true;
+            hooks.renew();
+            return null;
+        }
+        try {
+            const context = (hooks.api === "webgl2" ? canvas.getContext("webgl2", CONTEXT_ATTRIBUTES) : canvas.getContext("webgl", CONTEXT_ATTRIBUTES));
+            if (!context)
+                throw new WebglUnavailable(`${hooks.api === "webgl2" ? "WebGL2" : "WebGL"} is not available`);
+            live = { gl: context, state: hooks.init(context) };
+            return live;
+        }
+        catch (error) {
+            if (!(error instanceof WebglUnavailable)) {
+                console.warn(`[@sharedex/ui] ${hooks.label}: could not start (${String(error)}). Showing its fallback.`);
+            }
+            else if (/compile|link/.test(error.message)) {
+                console.warn(`[@sharedex/ui] ${hooks.label}: ${error.message} Showing its fallback.`);
+            }
+            hooks.fail();
+            return null;
+        }
+    };
+    /** Free the program and hand the context back now instead of waiting for garbage collection. */
+    const free = () => {
+        if (live && !live.gl.isContextLost()) {
+            hooks.dispose(live.gl, live.state);
+            live.gl.getExtension("WEBGL_lose_context")?.loseContext();
+            spent.add(canvas);
+        }
+        live = null;
+    };
+    const release = () => {
+        hooks.onRelease?.();
+        free();
+        released = true;
+    };
+    const lost = (event) => {
+        event.preventDefault();
+        // the late event of a context an earlier surface on this canvas handed back: not a loss of ours
+        if (!live)
+            return;
+        live = null; // its resources died with it
+        release();
+        if (!hooks.isVisible())
+            return;
+        const now = performance.now();
+        hooks.losses.current = [...hooks.losses.current.filter((t) => now - t < LOSS_WINDOW_MS), now];
+        if (hooks.losses.current.length > MAX_LOSSES)
+            hooks.fail();
+        else
+            hooks.renew();
+    };
+    canvas.addEventListener("webglcontextlost", lost);
+    return {
+        get live() {
+            return live;
+        },
+        ensure,
+        hidden() {
+            if (!live || timer !== undefined)
+                return;
+            timer = setTimeout(() => {
+                timer = undefined;
+                if (!hooks.isVisible())
+                    release();
+            }, RELEASE_AFTER_MS);
+        },
+        shown() {
+            clearTimeout(timer);
+            timer = undefined;
+            if (!released)
+                return true;
+            hooks.renew(); // back on screen: a fresh canvas and context
+            return false;
+        },
+        destroy() {
+            clearTimeout(timer);
+            canvas.removeEventListener("webglcontextlost", lost);
+            free();
+        },
+    };
+}

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

@@ -0,0 +1,6 @@
+import type { GridRootProps } from "./Root.js";
+/** `GridRootProps` for a form: `columns` is a number, unset meaning `"auto"`. */
+export interface GridSettings extends Omit<GridRootProps<unknown>, "columns"> {
+    readonly columns: number;
+}
+export declare const GRID_SCHEMA: import("../schema/types.js").Schema;

package/dist/grid/Grid.schema.js

@@ -0,0 +1,66 @@
+import { defineSchema } from "../schema/define.js";
+const deg = { kind: "number", min: -60, max: 60, step: 1, unit: "°", default: 0 };
+export const GRID_SCHEMA = defineSchema()({
+    id: "grid",
+    family: "grid",
+    factory: "Grid.Root",
+    code: ["items", "children", "cellClassName", "modifiers", "onActivate", "itemLabel"],
+    fields: {
+        // the lattice
+        columns: {
+            kind: "integer", label: "Columns", min: 1, max: 24, autoValue: 6, autoNote: "one block as wide as the screen",
+            help: "Cards in one repeating block, before the pattern starts again.",
+        },
+        gap: { kind: "number", label: "Gap", min: 0, max: 96, step: 1, unit: "px", default: 24 },
+        stagger: { kind: "number", label: "Brick offset", min: 0, max: 1, step: 0.05, default: 0, help: "Every other row shifts by this share of a card." },
+        repeat: {
+            kind: "choice", label: "Fewer cards than a block", values: ["sequence", "blank"],
+            labels: { sequence: "Keep going in order", blank: "Leave the rest empty" }, default: "sequence",
+        },
+        initial: { kind: "integer", label: "Centred first", min: 0, max: 50, default: 0, help: "The card in the middle at the start.", advanced: true },
+        // the plane
+        tilt: {
+            kind: "group", label: "Lean", default: { x: 0, y: 0, z: 0 }, help: "Tips the whole plane: back, sideways, then turned.",
+            fields: {
+                x: { ...deg, label: "Back" },
+                y: { ...deg, label: "Sideways" },
+                z: { ...deg, label: "Turn", min: -45, max: 45 },
+            },
+        },
+        perspective: { kind: "integer", label: "Perspective", min: 0, max: 4000, unit: "px", default: 1200, help: "Smaller is a stronger 3D look; 0 is none." },
+        bulge: {
+            kind: "group", label: "Dome", autoNote: "off: the plane stays flat",
+            help: "The plane rises towards the viewer at the centre card; the rest sink away.",
+            fields: {
+                height: { kind: "number", label: "Depth", min: 0, max: 400, step: 5, unit: "px", default: 120, help: "How far the plane has sunk at the edge." },
+                radius: { kind: "number", label: "Edge", min: 100, max: 3000, step: 10, unit: "px", autoValue: 1200, autoNote: "the screen's larger side", help: "Where the dome ends." },
+            },
+        },
+        fog: {
+            kind: "group", label: "Fog", autoNote: "off: every card is shown",
+            help: "Cards fade out with their distance from the centre card.",
+            fields: {
+                from: { kind: "number", label: "Clear up to", min: 0, max: 20, step: 0.5, unit: "cards", default: 3 },
+                to: { kind: "number", label: "Gone at", min: 1, max: 24, step: 0.5, unit: "cards", default: 6 },
+            },
+        },
+        // moving it
+        drag: { kind: "boolean", label: "Drag", default: true },
+        snap: { kind: "boolean", label: "Land on a card", default: false, help: "A glide stops with a card in the centre." },
+        wheel: { kind: "boolean", label: "Mouse wheel", default: false, help: "Off keeps the wheel for the page scroll." },
+        drift: {
+            kind: "group", label: "Drift", default: { x: 0, y: 0 }, help: "It pans on its own while nobody touches it.",
+            fields: {
+                x: { kind: "number", label: "Across", min: -80, max: 80, step: 1, unit: "px/s", default: 0 },
+                y: { kind: "number", label: "Down", min: -80, max: 80, step: 1, unit: "px/s", default: 0 },
+            },
+        },
+        driftDelay: { kind: "integer", label: "Drift resumes after", min: 0, max: 10000, unit: "ms", default: 2000, advanced: true },
+        // opening a card
+        open: { kind: "effect", label: "Open a card", family: "grid-open", autoNote: "off: a click only calls onActivate", help: "Clicking a card (or Enter) opens it." },
+        // how much is mounted
+        margin: { kind: "integer", label: "Extra cells mounted", min: 0, max: 4, default: 1, help: "Beyond the visible ones, each side.", advanced: true },
+        reach: { kind: "integer", label: "Mounted up to", min: 2, max: 40, unit: "cards", default: 12, help: "From the centre; a steep lean shows a long way back.", advanced: true },
+        maxCells: { kind: "integer", label: "Cells at most", min: 20, max: 400, default: 160, advanced: true },
+    },
+});

package/dist/grid/Panel.d.ts

@@ -0,0 +1,19 @@
+import { type CSSProperties } from "react";
+export interface GridPanelProps<T> {
+    /** The panel's content for the open item (its index into `items` too). */
+    readonly children: (item: T, itemIndex: number) => React.ReactNode;
+    readonly className?: string;
+    readonly style?: CSSProperties;
+}
+/**
+ * The consumer's content about the open card (a title, a description, a spec
+ * sheet), shown while a card is open: it fades and slides in with
+ * `openProgress`, follows the focus when the arrow keys or a thumbnail move to
+ * another card, and fades out on close.
+ *
+ * It renders into `Grid.Viewport` (a portal), above the plane. With
+ * `gridOpen.panel()` it takes the panel's share of the width at the end side;
+ * with the other views it is not positioned, so place it with `className`.
+ * Clicks inside it never close the open card. Render it inside `Grid.Root`.
+ */
+export declare function Panel<T>({ children, className, style }: GridPanelProps<T>): import("react").ReactPortal | null;

package/dist/grid/Panel.js

@@ -0,0 +1,32 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import { createPortal } from "react-dom";
+import { motion, useTransform } from "motion/react";
+import { useGridContext } from "./context.js";
+/**
+ * The consumer's content about the open card (a title, a description, a spec
+ * sheet), shown while a card is open: it fades and slides in with
+ * `openProgress`, follows the focus when the arrow keys or a thumbnail move to
+ * another card, and fades out on close.
+ *
+ * It renders into `Grid.Viewport` (a portal), above the plane. With
+ * `gridOpen.panel()` it takes the panel's share of the width at the end side;
+ * with the other views it is not positioned, so place it with `className`.
+ * Clicks inside it never close the open card. Render it inside `Grid.Root`.
+ */
+export function Panel({ children, className, style }) {
+    const { handle } = useGridContext();
+    const { showing, focus, options, openProgress, viewportRef, items } = handle;
+    // slides in from the end side: the right in LTR, the left in RTL
+    const shift = useTransform(openProgress, (v) => (1 - v) * 32 * (handle.rtl.current ? -1 : 1));
+    const [host, setHost] = useState(null);
+    useEffect(() => setHost(viewportRef.current), [viewportRef]);
+    if (!host || !showing || focus.item === null)
+        return null;
+    const share = options.open?.panel ?? 0;
+    const box = share > 0 ? { position: "absolute", insetBlock: 0, insetInlineEnd: 0, inlineSize: `${share * 100}%` } : {};
+    return createPortal(_jsx(motion.div, { "data-sx-grid-panel": "", "aria-live": "polite", className: className, 
+        // a drag that starts here is not a pan of the plane
+        onPointerDown: (e) => e.stopPropagation(), style: { ...box, zIndex: 2000, opacity: openProgress, x: shift, ...style }, children: children(items[focus.item], focus.item) }), host);
+}

package/dist/grid/Root.d.ts

@@ -0,0 +1,17 @@
+import { type GridHandle, type GridOptions } from "./useGridEngine.js";
+export interface GridRootProps<T> extends GridOptions<T> {
+    readonly items: readonly T[];
+    /**
+     * Sizes every cell AND the hidden probe the Grid measures, so the pitch and
+     * the cell box can never disagree: `"w-[200px] h-[250px]"`. Responsive
+     * classes work; the Grid re-measures on resize.
+     */
+    readonly cellClassName?: string;
+    /** Render-prop form hands you the handle (focus, `goTo`) without an extra component. */
+    readonly children: React.ReactNode | ((handle: GridHandle<T>) => React.ReactNode);
+}
+/**
+ * An endless plane of cards you pan in any direction. Holds the state; the
+ * picture is `Grid.Viewport`.
+ */
+export declare function Root<T>({ items, cellClassName, children, ...options }: GridRootProps<T>): import("react").JSX.Element;

package/dist/grid/Root.js

@@ -0,0 +1,14 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { GridContext } from "./context.js";
+import { useGridEngine } from "./useGridEngine.js";
+/**
+ * An endless plane of cards you pan in any direction. Holds the state; the
+ * picture is `Grid.Viewport`.
+ */
+export function Root({ items, cellClassName = "", children, ...options }) {
+    const handle = useGridEngine(items, options);
+    const value = useMemo(() => ({ handle, cellClassName }), [handle, cellClassName]);
+    return (_jsx(GridContext.Provider, { value: value, children: typeof children === "function" ? children(handle) : children }));
+}

package/dist/grid/Viewport.d.ts

@@ -0,0 +1,49 @@
+import type { GridCell } from "./types.js";
+export interface GridViewportProps<T> {
+    /** Renders one cell's content. Cells of empty lattice points (`repeat: "blank"`) are not rendered. */
+    readonly children: (cell: GridCell<T>) => React.ReactNode;
+    /** The Viewport needs a height: `"h-[80vh]"`, `"aspect-video"` … */
+    readonly className?: string;
+    readonly style?: React.CSSProperties;
+    readonly "aria-label"?: string;
+}
+/**
+ * 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 declare function Viewport<T>({ children, className, style, "aria-label": ariaLabel }: GridViewportProps<T>): import("react").JSX.Element;