@sharedex/ui 0.0.0-stage → 0.9.0

package/dist/carousel/engine/useCarouselEngine.js

@@ -0,0 +1,543 @@
+"use client";
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
+import { animate, frameData, frameSteps, useMotionValue } from "motion/react";
+import { flushSync } from "react-dom";
+import { DEFAULT_CONFIG, resolveConfig, } from "../config.js";
+import { defaultFilterPredicate, } from "../types.js";
+import { buildRing, mountHalfFor, ringLengthFor, shortestDelta, wrapIndex } from "./ring.js";
+import { isStaticFor, minSlotsFor, useMetrics } from "./useMetrics.js";
+import { clamp } from "./math.js";
+import { clearSlotNames, nameVisibleSlots, viewNamePrefix, viewTransitionStarter } from "./viewSwap.js";
+import { DEFAULT_MORPH, morphCurve } from "./morph.js";
+import { INSTANT_FADE, REDUCED_FADE, presenceCurve } from "./presence.js";
+// Cross-fade and reveal timings, unchanged from 0.1.0.
+const FADE_OUT_MS = 180;
+const FADE_IN_MS = 300;
+const FADE_IN_DELAY_MS = 60;
+const REVEAL_MS = 250;
+export function useCarouselEngine({ items, filters, options, base = DEFAULT_CONFIG, }) {
+    const id = useId();
+    const baseConfig = useMemo(() => resolveConfig(base, options), [base, options]);
+    // While a card is open the open view's layout stands in for the carousel's
+    // own. Everything downstream (mount range, morph, writers) reads this config,
+    // so opening and closing are ordinary layout changes and morph like one.
+    const [isOpen, setIsOpen] = useState(false);
+    const view = baseConfig.engine.open;
+    const config = useMemo(() => (isOpen && view ? { ...baseConfig, layout: view.layout(baseConfig.layout) } : baseConfig), [baseConfig, isOpen, view]);
+    const resolvedFilters = useMemo(() => filters ?? [], [filters]);
+    // ---------- 1. the one source of truth ----------
+    // No pos/smooth pair. 0.1.0 needed a spring because `pos` was a step function
+    // and something had to turn steps into motion; with real settle policies the
+    // motion is already correct, and a second filter on top is only lag.
+    const position = useMotionValue(0);
+    const opacity = useMotionValue(0);
+    const autoplayProgress = useMotionValue(0);
+    const mode = useMotionValue("idle");
+    // ---------- 2. dom ----------
+    const viewportRef = useRef(null);
+    const trackRef = useRef(null);
+    const probeRef = useRef(null);
+    // ---------- 3. interaction flags (refs, never state) ----------
+    // In 0.1.0 hover and touch were useState in the provider, so a pointer
+    // entering the carousel changed the context value and re-rendered every
+    // mounted slot. Their only reader is autoplay, which runs inside rAF where a
+    // re-render buys nothing.
+    const hovering = useRef(false);
+    const focused = useRef(false);
+    const visible = useRef(true);
+    const reducedMotion = useRef(false);
+    const autoplayClock = useRef(0);
+    // Layout morphs (section 5b): one clock, shared state the slot writers read.
+    const morphClock = useMotionValue(0);
+    const morph = useRef({
+        gen: 0,
+        active: false,
+        curve: morphCurve(DEFAULT_MORPH),
+        stagger: 0,
+        end: 0,
+        fromHalf: 0,
+    });
+    const lastLayout = useRef(null);
+    const lastHalf = useRef(0);
+    const [, morphEnded] = useState(0);
+    // Enter / exit (section 6c). -1 = no run; every run starts by jumping to 0, a change the writers see.
+    const presenceClock = useMotionValue(-1);
+    const presence = useRef({
+        phase: config.engine.enter ? "hidden" : "shown",
+        preset: config.engine.enter || null,
+        curve: presenceCurve(INSTANT_FADE),
+        stagger: 0,
+        end: 0,
+        run: 0,
+    });
+    const presenceRun = useRef(null);
+    // ---------- 4. filtering ----------
+    // State, not a ref: a filter change is a user action a few times a minute,
+    // and it genuinely must re-render (the ring changes shape).
+    const [filter, setFilterState] = useState(() => resolvedFilters[0]?.value ?? "all");
+    const visibleIndices = useMemo(() => {
+        const active = resolvedFilters.find((f) => f.value === filter);
+        const out = [];
+        for (let i = 0; i < items.length; i++) {
+            const item = items[i];
+            const keep = active?.predicate
+                ? active.predicate(item, i)
+                : defaultFilterPredicate(item, filter);
+            if (keep)
+                out.push(i);
+        }
+        return out;
+    }, [items, resolvedFilters, filter]);
+    const itemCount = visibleIndices.length;
+    // ---------- 5. measurement and derived layout ----------
+    const metrics = useMetrics(viewportRef, probeRef, config.engine.axis, config.engine.sizing, config.engine.gap);
+    // A closed layout (a barrel, a dial) wraps the items into a full circle: no
+    // padding in the ring, and it always turns, however few cards fit the viewport.
+    const closed = config.layout.ring === "closed";
+    const minSlots = minSlotsFor(metrics.viewportMain, metrics.pitch);
+    const count = ringLengthFor(itemCount, minSlots, closed);
+    const layoutHalf = mountHalfFor(minSlots, config.engine.buffer, count, config.layout.reach, closed);
+    // ---------- 5b. morph ----------
+    // Noticed during render, so the very render that swaps the layout already
+    // keeps the old mount range (its cards must morph, not vanish) and the slot
+    // writers, which run in this same render, see the new generation and
+    // snapshot their pose before the new layout lands.
+    if (lastLayout.current !== config.layout) {
+        const previous = lastLayout.current;
+        lastLayout.current = config.layout;
+        const options = config.engine.morph;
+        if (previous !== null && options && metrics.ready && !reducedMotion.current) {
+            const m = morph.current;
+            m.gen += 1;
+            m.active = true;
+            m.curve = morphCurve(options);
+            m.stagger = options.stagger * 1000;
+            m.fromHalf = lastHalf.current;
+            m.end = m.curve.duration + m.stagger * (Math.max(layoutHalf, m.fromHalf) + 1);
+            morphClock.jump(0);
+        }
+    }
+    const half = morph.current.active ? Math.max(layoutHalf, morph.current.fromHalf) : layoutHalf;
+    lastHalf.current = half;
+    const isStatic = closed ? itemCount <= 1 : isStaticFor(itemCount, metrics.viewportMain, metrics.pitch);
+    const ring = useMemo(() => buildRing(itemCount, count), [itemCount, count]);
+    /** itemIndex (into `items`) to ringIndex. Only goTo needs this direction. */
+    const ringIndexByItem = useMemo(() => {
+        const map = new Map();
+        for (let r = 0; r < ring.length; r++) {
+            const slot = ring[r];
+            if (slot === undefined || slot < 0)
+                continue;
+            const itemIndex = visibleIndices[slot];
+            if (itemIndex !== undefined)
+                map.set(itemIndex, r);
+        }
+        return map;
+    }, [ring, visibleIndices]);
+    // ---------- 6. zero-allocation frame reads ----------
+    const frameRef = useRef({
+        axis: "x",
+        position: 0,
+        velocity: 0,
+        mode: "idle",
+        slotMain: 0,
+        slotCross: 0,
+        viewportMain: 0,
+        viewportCross: 0,
+        gap: 0,
+        pitch: 0,
+        centerOffset: 0,
+        ready: false,
+        count: 1,
+        itemCount: 0,
+    });
+    // Refresh the static half during render, so readFrame() only has to touch the
+    // three values that actually change per frame.
+    const staticFrame = frameRef.current;
+    staticFrame.axis = config.engine.axis;
+    staticFrame.slotMain = metrics.slotMain;
+    staticFrame.slotCross = metrics.slotCross;
+    staticFrame.viewportMain = metrics.viewportMain;
+    staticFrame.viewportCross = metrics.viewportCross;
+    staticFrame.gap = metrics.gap;
+    staticFrame.pitch = metrics.pitch;
+    staticFrame.centerOffset = metrics.centerOffset;
+    staticFrame.ready = metrics.ready;
+    staticFrame.count = count;
+    staticFrame.itemCount = itemCount;
+    const readFrame = useCallback(() => {
+        const frame = frameRef.current;
+        frame.position = position.get();
+        frame.velocity = position.getVelocity();
+        frame.mode = mode.get();
+        return frame;
+    }, [position, mode]);
+    // `ring`/`visibleIndices` behind refs, refreshed below alongside `frameRef`'s
+    // static fields, so `readSlot`'s own identity can be stable forever. Without
+    // this, `readSlot` would carry a `[ring, visibleIndices]` dependency array and
+    // get a new reference on every filter change -- which would force the "motion"
+    // context slice (see handle.ts) to also change identity on a filter click,
+    // defeating the whole point of splitting it away from the "data" slice.
+    //
+    // The correctness half, not just the perf half: reading through a ref instead
+    // of closing over the value is what makes it SAFE for `readSlot` to be stable.
+    // A stable closure that still read the ORIGINAL `ring`/`visibleIndices` would
+    // silently keep mapping slots against a stale ring after a filter swap. This
+    // mirrors the pattern `frameRef`'s static fields already use two lines above:
+    // refreshed synchronously in the render body, read later by a caller.
+    const ringRef = useRef(ring);
+    const visibleIndicesRef = useRef(visibleIndices);
+    ringRef.current = ring;
+    visibleIndicesRef.current = visibleIndices;
+    const readSlot = useCallback((out, index) => {
+        const frame = frameRef.current;
+        const currentRing = ringRef.current;
+        const currentVisible = visibleIndicesRef.current;
+        out.index = index;
+        out.ringIndex = wrapIndex(index, frame.count);
+        const slot = currentRing[out.ringIndex];
+        out.itemIndex =
+            slot === undefined || slot < 0 ? null : (currentVisible[slot] ?? null);
+        out.distance = index - frame.position;
+        return out;
+    }, []);
+    /**
+     * Mount-range centre, pushed ahead by however far the current velocity will
+     * carry within `lookahead` seconds.
+     *
+     * 0.1.0 got this for free: Window read `pos` (the target) while slots
+     * rendered at `smooth` (the display), so mounting always ran ahead. Collapsing
+     * to one value gives that lead back explicitly, and finally makes `buffer`
+     * mean something instead of being a magic 2.
+     */
+    const getMountCentre = useCallback(() => {
+        const lead = position.getVelocity() * config.engine.lookahead;
+        return Math.round(position.get() + clamp(-(half - 1), half - 1, lead));
+    }, [position, half, config.engine.lookahead]);
+    // The morph clock: linear milliseconds; each writer reads the spring at its
+    // own delayed time. A new layout change stops this run (cleanup) and starts
+    // the next from 0; the writers' snapshots make that seamless.
+    const morphGen = morph.current.active ? morph.current.gen : 0;
+    useEffect(() => {
+        const m = morph.current;
+        if (!m.active)
+            return;
+        const gen = m.gen;
+        const run = animate(morphClock, m.end, { duration: m.end / 1000, ease: "linear" });
+        void run.then(() => {
+            if (morph.current.gen !== gen)
+                return;
+            morph.current.active = false;
+            // re-render: the mount range shrinks back to the new layout's own
+            morphEnded(gen);
+        });
+        return () => run.stop();
+    }, [morphGen, morphClock]);
+    // ---------- 6c. enter / exit ----------
+    // Cards arrive or leave on one clock (ms), each `stagger` ms per card of
+    // distance later; the writers read the phase and apply the preset after the
+    // layout. A newer run supersedes an older one: the older stops and resolves.
+    const playPresence = useCallback(async (direction, wanted) => {
+        const p = presence.current;
+        const run = ++p.run;
+        presenceRun.current?.stop();
+        const preset = !wanted ? INSTANT_FADE : reducedMotion.current ? REDUCED_FADE : wanted;
+        p.preset = preset;
+        p.phase = direction === "in" ? "entering" : "exiting";
+        p.curve = presenceCurve(preset);
+        p.stagger = preset.stagger * 1000;
+        p.end = p.curve.duration + p.stagger * (lastHalf.current + 1);
+        presenceClock.jump(0);
+        if (p.end > 0) {
+            const controls = animate(presenceClock, p.end, { duration: p.end / 1000, ease: "linear" });
+            presenceRun.current = controls;
+            await controls;
+        }
+        if (p.run !== run)
+            return;
+        p.phase = direction === "in" ? "shown" : "hidden";
+        if (p.phase === "shown")
+            p.preset = null;
+        // one more write with the final phase
+        presenceClock.jump(-1);
+    }, [presenceClock]);
+    const hide = useCallback(() => playPresence("out", config.engine.exit), [playPresence, config.engine.exit]);
+    const show = useCallback(() => playPresence("in", config.engine.enter), [playPresence, config.engine.enter]);
+    // ---------- 7. reveal ----------
+    // The first paint runs before any measurement, so centerOffset is 0 and every
+    // card would stack on one edge for a frame. With an `enter` preset the cards
+    // start hidden and arrive with it instead of the whole-carousel fade.
+    const hasRevealed = useRef(false);
+    useEffect(() => {
+        if (hasRevealed.current || !metrics.ready)
+            return;
+        hasRevealed.current = true;
+        if (presence.current.phase === "hidden" && config.engine.enter) {
+            opacity.jump(1);
+            void playPresence("in", config.engine.enter);
+            return;
+        }
+        animate(opacity, 1, { duration: REVEAL_MS / 1000, ease: "easeOut" });
+    }, [metrics.ready, opacity, config.engine.enter, playPresence]);
+    // ---------- 8. environment ----------
+    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);
+    }, []);
+    useEffect(() => {
+        const el = viewportRef.current;
+        if (!el || typeof IntersectionObserver === "undefined")
+            return;
+        const io = new IntersectionObserver((entries) => {
+            const entry = entries[0];
+            if (entry)
+                visible.current = entry.isIntersecting;
+        }, { threshold: 0 });
+        io.observe(el);
+        return () => io.disconnect();
+    }, []);
+    // ---------- 9. writes ----------
+    const resetAutoplayClock = useCallback(() => {
+        autoplayClock.current = 0;
+        autoplayProgress.set(0);
+    }, [autoplayProgress]);
+    const animateTo = useCallback((target, shouldAnimate) => {
+        if (!shouldAnimate || reducedMotion.current) {
+            position.jump(target);
+            return;
+        }
+        mode.set("animating");
+        // Arrow / pagination / autoplay steps use `physics.stepSpring`. Drag
+        // release goes through the configured SettlePolicy instead.
+        void animate(position, target, {
+            type: "spring",
+            ...config.physics.stepSpring,
+        }).then(() => {
+            if (mode.get() === "animating")
+                mode.set("idle");
+        });
+    }, [position, mode, config.physics.stepSpring]);
+    const stepBy = useCallback((direction) => {
+        animateTo(Math.round(position.get()) + direction, true);
+        resetAutoplayClock();
+    }, [animateTo, position, resetAutoplayClock]);
+    const goTo = useCallback((itemIndex, opts) => {
+        const targetRing = ringIndexByItem.get(itemIndex);
+        if (targetRing === undefined)
+            return;
+        const current = Math.round(position.get());
+        const delta = shortestDelta(wrapIndex(current, count), targetRing, count);
+        animateTo(current + delta, opts?.animate ?? true);
+        resetAutoplayClock();
+    }, [ringIndexByItem, position, count, animateTo, resetAutoplayClock]);
+    /**
+     * Fade out, swap while invisible, jump home, fade back in.
+     *
+     * One implementation serves both the built-in filter pills and any external
+     * driver (URL params, a server refetch), because all three of the swap,
+     * `position.jump(0)` and the autoplay clock have to be coordinated. Splitting
+     * them is how a progress bar ends up resuming mid-fill against a position
+     * that no longer exists.
+     */
+    const resetWithTransition = useCallback(async (swap) => {
+        if (mode.get() === "swapping")
+            return;
+        mode.set("swapping");
+        // engine.filterTransition "view": the browser morphs the cards instead.
+        // Without support (or under reduced motion) the fade below plays.
+        const start = config.engine.filterTransition === "view" && !reducedMotion.current ? viewTransitionStarter() : null;
+        const viewport = viewportRef.current;
+        if (start && viewport) {
+            const prefix = viewNamePrefix(id);
+            nameVisibleSlots(viewport, prefix);
+            try {
+                await start(() => {
+                    // the new list, the new mount range and position 0 in one commit
+                    flushSync(() => {
+                        swap();
+                        position.jump(0);
+                    });
+                    resetAutoplayClock();
+                    // Motion writes the slots' styles on its next frame, but no frame runs
+                    // before the browser captures the new state (measured: a rAF queued
+                    // here fires after it). Run the two steps that write them now.
+                    frameSteps.preRender.process(frameData);
+                    frameSteps.render.process(frameData);
+                    nameVisibleSlots(viewport, prefix);
+                }).finished;
+            }
+            catch {
+                // the update itself threw: the swap may be half done, nothing to undo here
+            }
+            finally {
+                clearSlotNames(viewport);
+                if (mode.get() === "swapping")
+                    mode.set("idle");
+            }
+            return;
+        }
+        // enter / exit presets: the cards leave, the list swaps while they are
+        // gone, the new ones arrive. A missing side is instant.
+        const { enter, exit } = config.engine;
+        if (enter || exit) {
+            await playPresence("out", exit);
+            swap();
+            position.jump(0);
+            resetAutoplayClock();
+            // sets the "entering" phase now, before React renders the new cards
+            await playPresence("in", enter);
+            if (mode.get() === "swapping")
+                mode.set("idle");
+            return;
+        }
+        await animate(opacity, 0, {
+            duration: FADE_OUT_MS / 1000,
+            ease: "easeIn",
+        });
+        swap();
+        // jump() teleports. set() would let the settle animation slide from card
+        // 14 back to card 0, a long ugly spin.
+        position.jump(0);
+        resetAutoplayClock();
+        await animate(opacity, 1, {
+            duration: FADE_IN_MS / 1000,
+            ease: "easeOut",
+            delay: FADE_IN_DELAY_MS / 1000,
+        });
+        if (mode.get() === "swapping")
+            mode.set("idle");
+    }, [mode, opacity, position, resetAutoplayClock, config.engine, id, playPresence]);
+    const setFilter = useCallback((next) => {
+        if (next === filter)
+            return;
+        void resetWithTransition(() => setFilterState(next));
+    }, [filter, resetWithTransition]);
+    // ---------- 9b. open views ----------
+    const openProgress = useMotionValue(0);
+    const animateOpen = useCallback((to) => {
+        if (reducedMotion.current)
+            openProgress.jump(to);
+        else
+            void animate(openProgress, to, { type: "spring", visualDuration: 0.6, bounce: 0 });
+    }, [openProgress]);
+    /** Open an item (default: the focused one). It comes to the focus and the open view takes over. */
+    const open = useCallback((itemIndex) => {
+        if (!view)
+            return;
+        if (itemIndex !== undefined)
+            goTo(itemIndex);
+        setIsOpen(true);
+        animateOpen(1);
+    }, [view, goTo, animateOpen]);
+    const close = useCallback(() => {
+        setIsOpen(false);
+        animateOpen(0);
+    }, [animateOpen]);
+    // Esc closes; so does scrolling the page past `closeOnScroll` px.
+    useEffect(() => {
+        if (!isOpen || typeof window === "undefined")
+            return;
+        const onKey = (e) => {
+            if (e.key === "Escape")
+                close();
+        };
+        const limit = view ? view.closeOnScroll : 0;
+        const from = window.scrollY;
+        const onScroll = () => {
+            if (Math.abs(window.scrollY - from) > limit)
+                close();
+        };
+        window.addEventListener("keydown", onKey);
+        if (limit > 0)
+            window.addEventListener("scroll", onScroll, { passive: true });
+        return () => {
+            window.removeEventListener("keydown", onKey);
+            window.removeEventListener("scroll", onScroll);
+        };
+    }, [isOpen, view, close]);
+    // ---------- 10. the handle ----------
+    return useMemo(() => ({
+        id,
+        config,
+        position,
+        opacity,
+        autoplayProgress,
+        mode,
+        viewportRef,
+        trackRef,
+        probeRef,
+        items,
+        visibleIndices,
+        ring,
+        count,
+        itemCount,
+        filters: resolvedFilters,
+        filter,
+        metrics,
+        half,
+        isStatic,
+        hovering,
+        focused,
+        visible,
+        reducedMotion,
+        autoplayClock,
+        morph,
+        morphClock,
+        presence,
+        presenceClock,
+        hide,
+        show,
+        isOpen,
+        openProgress,
+        open,
+        close,
+        readFrame,
+        readSlot,
+        getMountCentre,
+        stepBy,
+        goTo,
+        setFilter,
+        resetWithTransition,
+        resetAutoplayClock,
+    }), [
+        id,
+        config,
+        position,
+        opacity,
+        autoplayProgress,
+        mode,
+        items,
+        visibleIndices,
+        ring,
+        count,
+        itemCount,
+        resolvedFilters,
+        filter,
+        metrics,
+        half,
+        isStatic,
+        morphClock,
+        presenceClock,
+        hide,
+        show,
+        isOpen,
+        openProgress,
+        open,
+        close,
+        readFrame,
+        readSlot,
+        getMountCentre,
+        stepBy,
+        goTo,
+        setFilter,
+        resetWithTransition,
+        resetAutoplayClock,
+    ]);
+}

package/dist/carousel/engine/useMetrics.d.ts

@@ -0,0 +1,35 @@
+import type { Axis, Metrics, SlotSizing } from "./types.js";
+/**
+ * How much an ancestor scales the element on screen (CSS `zoom`, a scale
+ * transform): its on-screen width over its layout width. 1 when nothing does,
+ * or within 1% of it, so an unscaled viewport keeps its exact sub-pixel
+ * measures. Pure; tested.
+ */
+export declare function screenScale(rectWidth: number, layoutWidth: number): number;
+/**
+ * Measure the viewport and one engine-owned probe element.
+ *
+ * 0.1.0 read `trackRef.current.firstElementChild` -- whichever slot happened to
+ * be leftmost -- so pitch came from the *card's* root, and silently included a
+ * 16px divider that lived inside the card. Whether pitch was 300 or 316 was
+ * decided by Tailwind's utility ordering. That is what made "pass any card
+ * design" impossible.
+ *
+ * The probe replaces it: one element the engine renders and owns, sized by the
+ * same CSS rule as the slots, which never unmounts. So its ResizeObserver is
+ * stable, item-vs-placeholder divergence is structurally impossible, and a card
+ * cannot reach the layout maths at all. Responsiveness stays in CSS (the probe
+ * carries the breakpoint classes) rather than being duplicated in TypeScript.
+ */
+export declare function useMetrics(viewportRef: React.RefObject<HTMLElement | null>, probeRef: React.RefObject<HTMLElement | null>, axis: Axis, sizing: SlotSizing, gap: number): Metrics;
+/**
+ * How many slots touch the viewport. `+1` because the two edges each cut a
+ * card in half, so one more slot is on screen than fits whole.
+ */
+export declare function minSlotsFor(viewportMain: number, pitch: number): number;
+/**
+ * True when every real card is already fully visible, so there is nothing to
+ * scroll. `Math.floor` so only WHOLE cards count as fitting -- counting the
+ * half-cut edge slots froze carousels whose cards genuinely overflowed.
+ */
+export declare function isStaticFor(itemCount: number, viewportMain: number, pitch: number): boolean;