@sharedex/ui 0.0.0-stage → 0.9.0

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

@@ -0,0 +1,154 @@
+import type { MotionValue } from "motion/react";
+import type { CarouselConfig } from "../config.js";
+import type { CarouselFilter, FilterValue } from "../types.js";
+import type { CarouselFrame, EngineMode, Metrics, SlotState } from "./types.js";
+import type { Ring } from "./ring.js";
+import type { MorphState } from "./morph.js";
+import type { PresenceState } from "./presence.js";
+/** The T-free half of a filter, all any part outside Root actually reads. */
+export interface CarouselFilterMeta {
+    readonly label: string;
+    readonly value: FilterValue;
+}
+/**
+ * The engine surface that does not mention the item type.
+ *
+ * Most parts -- Viewport, Track, Slot, controls, autoplay -- never touch an
+ * item, so typing their optional `engine` override as `CarouselHandle<T>`
+ * would force a meaningless type parameter through the whole tree. Worse,
+ * `CarouselFilter<T>` is contravariant in T through its `predicate`, so there
+ * is no single T that means "any engine". This is that type.
+ */
+export interface CarouselEngine {
+    /** Stable per instance. Used by the dev-time containment check. */
+    readonly id: string;
+    readonly config: CarouselConfig;
+    /** Unbounded float in index space. The ONLY value that means "where am I". */
+    readonly position: MotionValue<number>;
+    /** Whole-carousel opacity: the first-paint reveal and the filter cross-fade. */
+    readonly opacity: MotionValue<number>;
+    /** 0..1, written every frame by autoplay. Bind it, never read it per frame. */
+    readonly autoplayProgress: MotionValue<number>;
+    readonly mode: MotionValue<EngineMode>;
+    readonly viewportRef: React.RefObject<HTMLDivElement | null>;
+    readonly trackRef: React.RefObject<HTMLDivElement | null>;
+    /** The engine-owned sizing probe. Never a card. */
+    readonly probeRef: React.RefObject<HTMLDivElement | null>;
+    readonly items: readonly unknown[];
+    /** Indices into `items` that survive the active filter, in order. */
+    readonly visibleIndices: readonly number[];
+    readonly ring: Ring;
+    /** Ring length. NOT the number of items -- pagination must use itemCount. */
+    readonly count: number;
+    readonly itemCount: number;
+    readonly filters: readonly CarouselFilterMeta[];
+    readonly filter: FilterValue;
+    readonly metrics: Metrics;
+    /** Slots mounted each side of centre. Depends on the viewport, never on item count. */
+    readonly half: number;
+    /** Every real card already fits: nothing to scroll, nothing to autoplay. */
+    readonly isStatic: boolean;
+    readonly hovering: React.RefObject<boolean>;
+    readonly focused: React.RefObject<boolean>;
+    readonly visible: React.RefObject<boolean>;
+    readonly reducedMotion: React.RefObject<boolean>;
+    /**
+     * The current frame.
+     *
+     * Returns a SHARED, MUTATED object -- cheap enough to call once per slot per
+     * frame with zero allocation. Never hold the reference across frames; read
+     * what you need and drop it.
+     */
+    readFrame(): CarouselFrame;
+    /** Fills and returns a caller-owned SlotState. Also zero allocation. */
+    readSlot(out: MutableSlotState, index: number): SlotState;
+    /** Where to centre the mount range, with velocity lookahead applied. */
+    getMountCentre(): number;
+    stepBy(direction: 1 | -1): void;
+    /** Move to an item by its index in `items`, taking the short way round. */
+    goTo(itemIndex: number, options?: {
+        animate?: boolean;
+    }): void;
+    setFilter(next: FilterValue): void;
+    /**
+     * The escape hatch: run an arbitrary swap (URL-driven filtering, a server
+     * refetch) inside the same fade-out -> jump -> fade-in the pills use.
+     */
+    resetWithTransition(swap: () => void): Promise<void>;
+    resetAutoplayClock(): void;
+    /** ms accumulated toward the next autoplay advance. Owned by useAutoplay. */
+    readonly autoplayClock: React.RefObject<number>;
+    /** Shared with the slot writers while a layout change plays. Mutated in place. */
+    readonly morph: React.RefObject<EngineMorphState>;
+    /** Milliseconds since the last layout change, while it plays. Writers re-run on its change. */
+    readonly morphClock: MotionValue<number>;
+    /** Shared with the slot writers: the phase and the preset playing. Mutated in place. */
+    readonly presence: React.RefObject<PresenceState>;
+    /** Milliseconds since the current enter / exit run started; -1 between runs. */
+    readonly presenceClock: MotionValue<number>;
+    /** Play `engine.exit` (instant without one). Resolves when every card has gone. */
+    hide(): Promise<void>;
+    /** Play `engine.enter` (instant without one). Resolves when every card is back. */
+    show(): Promise<void>;
+    /** A card is open: `engine.open`'s view is the layout. */
+    readonly isOpen: boolean;
+    /** 0 closed … 1 open, on a spring. For `Carousel.Panel` and `useSlotOpen`. */
+    readonly openProgress: MotionValue<number>;
+    /** Open an item (default: the focused one); it comes to the focus. Needs `engine.open`. */
+    open(itemIndex?: number): void;
+    /** Close the open card. Esc does the same. */
+    close(): void;
+}
+/** The engine's morph state: the writers' part plus the mount range the morph started from. */
+export interface EngineMorphState extends MorphState {
+    /** `half` before the change; the mount range keeps it until the morph ends. */
+    fromHalf: number;
+}
+/** The engine, with items and filters typed. Only Root and Window need this. */
+export interface CarouselHandle<T = unknown> extends Omit<CarouselEngine, "items" | "filters"> {
+    readonly items: readonly T[];
+    readonly filters: readonly CarouselFilter<T>[];
+}
+/** Writable twin of SlotState, so readSlot can fill a reused object. */
+export interface MutableSlotState {
+    index: number;
+    ringIndex: number;
+    itemIndex: number | null;
+    distance: number;
+}
+export declare function createMutableSlotState(): MutableSlotState;
+export type CarouselMotionSlice = Pick<CarouselEngine, "id" | "config" | "position" | "opacity" | "autoplayProgress" | "mode" | "viewportRef" | "trackRef" | "probeRef" | "hovering" | "focused" | "visible" | "reducedMotion" | "autoplayClock" | "morph" | "morphClock" | "presence" | "presenceClock" | "hide" | "show" | "openProgress" | "readFrame" | "readSlot" | "stepBy" | "resetAutoplayClock" | "resetWithTransition">;
+export type CarouselDataSlice = Pick<CarouselEngine, "items" | "visibleIndices" | "ring" | "count" | "itemCount" | "filters" | "filter" | "metrics" | "half" | "isStatic" | "getMountCentre" | "goTo" | "setFilter" | "isOpen" | "open" | "close">;
+export declare const CarouselMotionContext: import("react").Context<CarouselMotionSlice | null>;
+export declare const CarouselDataContext: import("react").Context<CarouselDataSlice | null>;
+/**
+ * The stable slice: position, mode, config, refs. Never changes identity for
+ * the life of a `<Carousel.Root>` instance, so subscribing to only this is how
+ * `Slot` and `Viewport` avoid rerendering on a filter click or a resize.
+ */
+export declare function useCarouselMotion(override?: CarouselEngine): CarouselMotionSlice;
+/**
+ * The changing slice: items, filter, ring, metrics. A component that reads
+ * this should expect to rerender whenever the ring reshapes or the viewport
+ * is remeasured -- that's correct, not a cost to fight.
+ */
+export declare function useCarouselData(override?: CarouselEngine): CarouselDataSlice;
+/**
+ * Both slices merged back into one object, for a part that genuinely needs
+ * both (Track needs `isStatic` to gate dragging; Window needs `ring`/`count`
+ * to virtualize) or for a consumer that just wants the whole engine.
+ *
+ * This still subscribes to CarouselDataContext, so it still rerenders on a
+ * filter click -- correctly, for the parts that use it. The win from splitting
+ * only reaches a component that calls `useCarouselMotion` directly instead.
+ */
+export declare function useCarouselEngineRef(override?: CarouselEngine): CarouselEngine;
+/**
+ * Same resolution, with the item type reapplied.
+ *
+ * The cast is the one place generic typing is restored: React context cannot
+ * carry a type parameter, so `Root<T>` publishes the erased engine and the
+ * parts that render items assert T back. Passing the wrong T is a consumer
+ * error the compiler cannot see, which is why only Window uses it.
+ */
+export declare function useCarouselHandle<T = unknown>(override?: CarouselHandle<T>): CarouselHandle<T>;

package/dist/carousel/engine/handle.js

@@ -0,0 +1,114 @@
+"use client";
+import { createContext, useContext, useMemo } from "react";
+export function createMutableSlotState() {
+    return { index: 0, ringIndex: 0, itemIndex: null, distance: 0 };
+}
+function sliceMotion(engine) {
+    const { id, config, position, opacity, autoplayProgress, mode, viewportRef, trackRef, probeRef, hovering, focused, visible, reducedMotion, autoplayClock, morph, morphClock, presence, presenceClock, hide, show, openProgress, readFrame, readSlot, stepBy, resetAutoplayClock, resetWithTransition, } = engine;
+    return {
+        morph,
+        morphClock,
+        presence,
+        presenceClock,
+        hide,
+        show,
+        openProgress,
+        id,
+        config,
+        position,
+        opacity,
+        autoplayProgress,
+        mode,
+        viewportRef,
+        trackRef,
+        probeRef,
+        hovering,
+        focused,
+        visible,
+        reducedMotion,
+        autoplayClock,
+        readFrame,
+        readSlot,
+        stepBy,
+        resetAutoplayClock,
+        resetWithTransition,
+    };
+}
+function sliceData(engine) {
+    const { items, visibleIndices, ring, count, itemCount, filters, filter, metrics, half, isStatic, getMountCentre, goTo, setFilter, isOpen, open, close, } = engine;
+    return {
+        items,
+        visibleIndices,
+        ring,
+        count,
+        itemCount,
+        filters,
+        filter,
+        metrics,
+        half,
+        isStatic,
+        getMountCentre,
+        goTo,
+        setFilter,
+        isOpen,
+        open,
+        close,
+    };
+}
+export const CarouselMotionContext = createContext(null);
+export const CarouselDataContext = createContext(null);
+const NO_ENGINE_MESSAGE = "[@sharedex/ui] No carousel engine in scope. Render this inside <Carousel.Root>, or pass an `engine` prop.";
+/**
+ * The stable slice: position, mode, config, refs. Never changes identity for
+ * the life of a `<Carousel.Root>` instance, so subscribing to only this is how
+ * `Slot` and `Viewport` avoid rerendering on a filter click or a resize.
+ */
+export function useCarouselMotion(override) {
+    const fromContext = useContext(CarouselMotionContext);
+    // Hooks must run unconditionally, so this always runs; it only allocates
+    // when an override is actually passed (the nested-carousel escape hatch),
+    // which is not the hot path this split exists for.
+    const fromOverride = useMemo(() => (override ? sliceMotion(override) : null), [override]);
+    const resolved = fromOverride ?? fromContext;
+    if (!resolved)
+        throw new Error(NO_ENGINE_MESSAGE);
+    return resolved;
+}
+/**
+ * The changing slice: items, filter, ring, metrics. A component that reads
+ * this should expect to rerender whenever the ring reshapes or the viewport
+ * is remeasured -- that's correct, not a cost to fight.
+ */
+export function useCarouselData(override) {
+    const fromContext = useContext(CarouselDataContext);
+    const fromOverride = useMemo(() => (override ? sliceData(override) : null), [override]);
+    const resolved = fromOverride ?? fromContext;
+    if (!resolved)
+        throw new Error(NO_ENGINE_MESSAGE);
+    return resolved;
+}
+/**
+ * Both slices merged back into one object, for a part that genuinely needs
+ * both (Track needs `isStatic` to gate dragging; Window needs `ring`/`count`
+ * to virtualize) or for a consumer that just wants the whole engine.
+ *
+ * This still subscribes to CarouselDataContext, so it still rerenders on a
+ * filter click -- correctly, for the parts that use it. The win from splitting
+ * only reaches a component that calls `useCarouselMotion` directly instead.
+ */
+export function useCarouselEngineRef(override) {
+    const motion = useCarouselMotion(override);
+    const data = useCarouselData(override);
+    return useMemo(() => ({ ...motion, ...data }), [motion, data]);
+}
+/**
+ * Same resolution, with the item type reapplied.
+ *
+ * The cast is the one place generic typing is restored: React context cannot
+ * carry a type parameter, so `Root<T>` publishes the erased engine and the
+ * parts that render items assert T back. Passing the wrong T is a consumer
+ * error the compiler cannot see, which is why only Window uses it.
+ */
+export function useCarouselHandle(override) {
+    return useCarouselEngineRef(override);
+}

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

@@ -0,0 +1 @@
+export declare const clamp: (min: number, max: number, v: number) => number;

package/dist/carousel/engine/math.js

@@ -0,0 +1 @@
+export const clamp = (min, max, v) => v > max ? max : v < min ? min : v;

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

@@ -0,0 +1,55 @@
+/**
+ * Morphing between layouts: when `config.layout` changes, every card blends
+ * from where it was to where the new layout puts it, on one spring, the cards
+ * further from the focus starting a little later.
+ *
+ * Pure: the spring curve and the buffer blend. The engine owns the clock (one
+ * MotionValue of milliseconds since the change); each slot writer snapshots its
+ * own last pose when a morph starts and blends that snapshot into the new
+ * layout's pose. Snapshotting the live pose, not re-evaluating the old layout,
+ * is what lets a second change interrupt a morph without a jump, and keeps the
+ * old layout's ring length and mount range out of the new frame.
+ */
+import type { SlotFrameBuffer } from "./types.js";
+/** How a layout change plays. `false` in `engine.morph` switches instantly. */
+export interface LayoutMorphOptions {
+    /** Seconds the spring takes to look settled (motion's `visualDuration`). */
+    readonly visualDuration: number;
+    /** 0 = no overshoot; 0.15 overshoots a touch. */
+    readonly bounce: number;
+    /** Seconds of extra delay per card of distance from the focus. */
+    readonly stagger: number;
+}
+/** Measured on Motion's gallery (2026-10-25): spring 0.7 s, bounce 0.15, 15 ms a card. */
+export declare const DEFAULT_MORPH: LayoutMorphOptions;
+/** The spring as a function of time: progress (0 → 1, may overshoot) at `ms`. */
+export interface MorphCurve {
+    /** Milliseconds until the spring has settled. */
+    readonly duration: number;
+    at(ms: number): number;
+}
+/** Sample motion's own spring once (120 samples a second); reads interpolate. */
+export declare function morphCurve(options: Pick<LayoutMorphOptions, "visualDuration" | "bounce">): MorphCurve;
+/** What the engine and the writers share while a morph runs. Mutated in place. */
+export interface MorphState {
+    /** Bumped on every layout change; a writer snapshots its pose when it sees a new one. */
+    gen: number;
+    active: boolean;
+    curve: MorphCurve;
+    /** Milliseconds of delay per card of distance. */
+    stagger: number;
+    /** Milliseconds until the last card has settled. */
+    end: number;
+}
+/**
+ * `out = from → to at t` (0 = from, 1 = to; t may overshoot with a bouncy
+ * spring). `out` may be `to` itself.
+ *
+ * - Numbers lerp, including the rotations (shapes keep theirs in (−180°, 180°]).
+ * - `perspective` blends as `1 / p` (0 = none): none → 1200 passes through
+ *   very weak perspective, never through a tiny value that would bend the card
+ *   to extremes.
+ * - `zIndex` and `pointerEvents` switch half-way.
+ * - `filter` blends when both sides are a plain blur (or none), else switches half-way.
+ */
+export declare function blendBuffers(out: SlotFrameBuffer, from: SlotFrameBuffer, to: SlotFrameBuffer, t: number): void;

package/dist/carousel/engine/morph.js

@@ -0,0 +1,95 @@
+/**
+ * Morphing between layouts: when `config.layout` changes, every card blends
+ * from where it was to where the new layout puts it, on one spring, the cards
+ * further from the focus starting a little later.
+ *
+ * Pure: the spring curve and the buffer blend. The engine owns the clock (one
+ * MotionValue of milliseconds since the change); each slot writer snapshots its
+ * own last pose when a morph starts and blends that snapshot into the new
+ * layout's pose. Snapshotting the live pose, not re-evaluating the old layout,
+ * is what lets a second change interrupt a morph without a jump, and keeps the
+ * old layout's ring length and mount range out of the new frame.
+ */
+import { spring } from "motion/react";
+/** Measured on Motion's gallery (2026-10-25): spring 0.7 s, bounce 0.15, 15 ms a card. */
+export const DEFAULT_MORPH = { visualDuration: 0.7, bounce: 0.15, stagger: 0.015 };
+const STEP_MS = 1000 / 120;
+/** Sample motion's own spring once (120 samples a second); reads interpolate. */
+export function morphCurve(options) {
+    const gen = spring({ keyframes: [0, 1], visualDuration: options.visualDuration, bounce: options.bounce });
+    const samples = [];
+    let t = 0;
+    for (;;) {
+        const s = gen.next(t);
+        samples.push(s.done ? 1 : s.value);
+        if (s.done || t > 10000)
+            break;
+        t += STEP_MS;
+    }
+    const duration = (samples.length - 1) * STEP_MS;
+    return {
+        duration,
+        at(ms) {
+            if (ms <= 0)
+                return 0;
+            if (ms >= duration)
+                return 1;
+            const i = ms / STEP_MS;
+            const k = Math.floor(i);
+            const a = samples[k] ?? 1;
+            const b = samples[k + 1] ?? 1;
+            return a + (b - a) * (i - k);
+        },
+    };
+}
+const BLUR = /^blur\(([-\d.e]+)px\)$/;
+function blurPx(filter) {
+    if (filter === "none")
+        return 0;
+    const m = BLUR.exec(filter);
+    return m ? Number(m[1]) : null;
+}
+const lerp = (a, b, t) => a + (b - a) * t;
+/**
+ * `out = from → to at t` (0 = from, 1 = to; t may overshoot with a bouncy
+ * spring). `out` may be `to` itself.
+ *
+ * - Numbers lerp, including the rotations (shapes keep theirs in (−180°, 180°]).
+ * - `perspective` blends as `1 / p` (0 = none): none → 1200 passes through
+ *   very weak perspective, never through a tiny value that would bend the card
+ *   to extremes.
+ * - `zIndex` and `pointerEvents` switch half-way.
+ * - `filter` blends when both sides are a plain blur (or none), else switches half-way.
+ */
+export function blendBuffers(out, from, to, t) {
+    const pa = from.perspective === 0 ? 0 : 1 / from.perspective;
+    const pb = to.perspective === 0 ? 0 : 1 / to.perspective;
+    const p = lerp(pa, pb, t);
+    out.perspective = p <= 0 ? 0 : 1 / p;
+    out.x = lerp(from.x, to.x, t);
+    out.y = lerp(from.y, to.y, t);
+    out.z = lerp(from.z, to.z, t);
+    out.scaleX = lerp(from.scaleX, to.scaleX, t);
+    out.scaleY = lerp(from.scaleY, to.scaleY, t);
+    out.scaleZ = lerp(from.scaleZ, to.scaleZ, t);
+    out.rotateX = lerp(from.rotateX, to.rotateX, t);
+    out.rotateY = lerp(from.rotateY, to.rotateY, t);
+    out.rotateZ = lerp(from.rotateZ, to.rotateZ, t);
+    out.skewX = lerp(from.skewX, to.skewX, t);
+    out.skewY = lerp(from.skewY, to.skewY, t);
+    out.originX = lerp(from.originX, to.originX, t);
+    out.originY = lerp(from.originY, to.originY, t);
+    out.opacity = Math.min(1, Math.max(0, lerp(from.opacity, to.opacity, t)));
+    const half = t < 0.5;
+    out.zIndex = half ? from.zIndex : to.zIndex;
+    out.pointerEvents = half ? from.pointerEvents : to.pointerEvents;
+    const fa = blurPx(from.filter);
+    const fb = blurPx(to.filter);
+    if (fa !== null && fb !== null) {
+        const px = Math.max(0, lerp(fa, fb, t));
+        out.filter = px < 0.01 ? "none" : `blur(${px.toFixed(2)}px)`;
+    }
+    else {
+        out.filter = half ? from.filter : to.filter;
+    }
+}

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

@@ -0,0 +1,27 @@
+import type { PresencePreset } from "../layout/presence.js";
+import { type MorphCurve } from "./morph.js";
+export type PresencePhase = "shown" | "hidden" | "entering" | "exiting";
+/** Shared by the engine and the writers while cards enter or leave. Mutated in place. */
+export interface PresenceState {
+    phase: PresencePhase;
+    /** The preset playing (or that hid the cards). null while shown. */
+    preset: PresencePreset | null;
+    curve: MorphCurve;
+    /** Milliseconds of delay per card of distance. */
+    stagger: number;
+    /** Milliseconds until the last card has finished. */
+    end: number;
+    /** Bumped by every run; a run that finds a newer one stops quietly. */
+    run: number;
+}
+/** No preset: the cards just appear or vanish (opacity), at once. */
+export declare const INSTANT_FADE: PresencePreset;
+/** Under reduced motion every preset plays as this: a short opacity fade, no movement, no stagger. */
+export declare const REDUCED_FADE: PresencePreset;
+/** The preset's spring, sampled once per preset object. */
+export declare function presenceCurve(preset: PresencePreset): MorphCurve;
+/**
+ * A card's `p` (0 hidden … 1 shown) at `clock` ms. Cards further from the
+ * focus run `stagger` ms per card later, entering and leaving alike.
+ */
+export declare function presenceProgress(state: PresenceState, clock: number, distance: number): number;

package/dist/carousel/engine/presence.js

@@ -0,0 +1,41 @@
+// The engine half of enter / exit (the presets live in layout/presence.ts):
+// the state the engine and the slot writers share, and each card's progress.
+// Pure; the engine owns the clock (ms since the run started), like the morph.
+import { morphCurve } from "./morph.js";
+const INSTANT = { duration: 0, at: () => 1 };
+/** No preset: the cards just appear or vanish (opacity), at once. */
+export const INSTANT_FADE = {
+    id: "instant",
+    apply(buf, _slot, _frame, p) {
+        buf.opacity *= p;
+    },
+    visualDuration: 0,
+    bounce: 0,
+    stagger: 0,
+};
+/** Under reduced motion every preset plays as this: a short opacity fade, no movement, no stagger. */
+export const REDUCED_FADE = { ...INSTANT_FADE, id: "reduced", visualDuration: 0.25 };
+const curves = new WeakMap();
+/** The preset's spring, sampled once per preset object. */
+export function presenceCurve(preset) {
+    if (preset.visualDuration <= 0)
+        return INSTANT;
+    let c = curves.get(preset);
+    if (!c) {
+        c = morphCurve({ visualDuration: preset.visualDuration, bounce: preset.bounce });
+        curves.set(preset, c);
+    }
+    return c;
+}
+/**
+ * A card's `p` (0 hidden … 1 shown) at `clock` ms. Cards further from the
+ * focus run `stagger` ms per card later, entering and leaving alike.
+ */
+export function presenceProgress(state, clock, distance) {
+    if (state.phase === "shown")
+        return 1;
+    if (state.phase === "hidden")
+        return 0;
+    const u = state.curve.at(clock - state.stagger * Math.abs(distance));
+    return state.phase === "entering" ? u : 1 - u;
+}

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

@@ -0,0 +1,72 @@
+/**
+ * The data ring.
+ *
+ * A "slot" is a position on an unbounded integer line; an "item" is a data
+ * record. `buildRing` is the map between them. Because slot -> item wraps via
+ * modulo, the carousel loops forever with no cloned nodes and no scroll reset:
+ * the teleport lives in the data lookup, never in the pixels.
+ *
+ * The ring stores only INDICES into `items` (-1 for a placeholder), so it
+ * depends on two numbers and nothing else. That keeps its memo stable across
+ * item-identity changes and keeps this whole file free of generics.
+ */
+/** `ring[ringIndex]` is an index into `items`, or -1 for a placeholder. */
+export type Ring = Int32Array;
+export declare const PLACEHOLDER = -1;
+/**
+ * Build the ring for `itemCount` items padded out to `ringLength` positions.
+ *
+ * Ring index 0 is the viewport centre at rest, so the padding must land as far
+ * from index 0 as possible or the resting view is bracketed by empty cards.
+ * The first half of the items runs forward from index 0 and the second half
+ * runs backward from the end, which puts the placeholder block diametrically
+ * opposite the centre:
+ *
+ *     itemCount 3, ringLength 8  ->  [i0, i1, __, __, __, __, __, i2]
+ *                                      ^centre           placeholders^
+ *
+ * When no padding is needed this degenerates to `items` in order, so item 0 is
+ * centred at rest in BOTH cases. (0.1.0 rotated by `mid` only when padding was
+ * needed, so which item started centred silently depended on the item count.)
+ */
+export declare function buildRing(itemCount: number, ringLength: number): Ring;
+/** Positive modulo. `-1` on a ring of 8 is 7, not -1. */
+export declare function wrapIndex(index: number, count: number): number;
+/**
+ * Signed shortest step count from `from` to `to` on a ring of `count`.
+ *
+ * Without this, clicking pagination dot 0 while sitting on dot n-1 spins the
+ * entire ring backwards instead of stepping forward by one -- the single most
+ * common carousel bug. Also what a URL-driven `goTo(id)` needs.
+ */
+export declare function shortestDelta(from: number, to: number, count: number): number;
+/**
+ * How many slots must exist before the data repeats.
+ *
+ * At least `minSlots` so the viewport is never short of cards, and at least
+ * `itemCount` so no item appears twice on screen. A closed ring (a barrel, a
+ * dial) is exactly the items: padding would show as gaps in the circle.
+ */
+export declare function ringLengthFor(itemCount: number, minSlots: number, closed?: boolean): number;
+/**
+ * Slots mounted on each side of the mount centre.
+ *
+ * The viewport's need (`minSlots`) plus `buffer`, raised to `reach + 1` when a
+ * layout shows cards further out than the viewport math expects (a barrel
+ * folds many cards into a narrow strip). `Infinity` asks for the whole ring.
+ * An open ring stops at `count` each side, which already covers every item. A
+ * closed ring stops at `floor(count / 2)`: further out, a slot would be a
+ * second copy of a card already mounted on the other side (`mountSpanFor`
+ * trims the one extra slot an even count would still give).
+ */
+export declare function mountHalfFor(minSlots: number, buffer: number, count: number, reach?: number, closed?: boolean): number;
+/**
+ * How many consecutive slots `Window` mounts, starting at `centre - half`.
+ *
+ * Usually `2 · half + 1`. A closed ring never mounts more than `count`: the
+ * slots are consecutive, so `count` of them hold every card exactly once,
+ * wherever the centre is (even pushed ahead by the speed lookahead). With an
+ * even count and the whole ring mounted, that drops the last slot, a second
+ * copy of the card straight opposite the first.
+ */
+export declare function mountSpanFor(half: number, count: number, closed?: boolean): number;

package/dist/carousel/engine/ring.js

@@ -0,0 +1,105 @@
+/**
+ * The data ring.
+ *
+ * A "slot" is a position on an unbounded integer line; an "item" is a data
+ * record. `buildRing` is the map between them. Because slot -> item wraps via
+ * modulo, the carousel loops forever with no cloned nodes and no scroll reset:
+ * the teleport lives in the data lookup, never in the pixels.
+ *
+ * The ring stores only INDICES into `items` (-1 for a placeholder), so it
+ * depends on two numbers and nothing else. That keeps its memo stable across
+ * item-identity changes and keeps this whole file free of generics.
+ */
+export const PLACEHOLDER = -1;
+/**
+ * Build the ring for `itemCount` items padded out to `ringLength` positions.
+ *
+ * Ring index 0 is the viewport centre at rest, so the padding must land as far
+ * from index 0 as possible or the resting view is bracketed by empty cards.
+ * The first half of the items runs forward from index 0 and the second half
+ * runs backward from the end, which puts the placeholder block diametrically
+ * opposite the centre:
+ *
+ *     itemCount 3, ringLength 8  ->  [i0, i1, __, __, __, __, __, i2]
+ *                                      ^centre           placeholders^
+ *
+ * When no padding is needed this degenerates to `items` in order, so item 0 is
+ * centred at rest in BOTH cases. (0.1.0 rotated by `mid` only when padding was
+ * needed, so which item started centred silently depended on the item count.)
+ */
+export function buildRing(itemCount, ringLength) {
+    const n = Math.max(ringLength, 1);
+    const ring = new Int32Array(n).fill(PLACEHOLDER);
+    if (itemCount <= 0)
+        return ring;
+    const total = Math.min(itemCount, n);
+    const head = Math.ceil(total / 2);
+    for (let i = 0; i < head; i++)
+        ring[i] = i;
+    for (let i = head; i < total; i++)
+        ring[n - total + i] = i;
+    return ring;
+}
+/** Positive modulo. `-1` on a ring of 8 is 7, not -1. */
+export function wrapIndex(index, count) {
+    if (count <= 0)
+        return 0;
+    return ((index % count) + count) % count;
+}
+/**
+ * Signed shortest step count from `from` to `to` on a ring of `count`.
+ *
+ * Without this, clicking pagination dot 0 while sitting on dot n-1 spins the
+ * entire ring backwards instead of stepping forward by one -- the single most
+ * common carousel bug. Also what a URL-driven `goTo(id)` needs.
+ */
+export function shortestDelta(from, to, count) {
+    if (count <= 0)
+        return 0;
+    let d = (to - from) % count;
+    if (d > count / 2)
+        d -= count;
+    else if (d < -count / 2)
+        d += count;
+    return d;
+}
+/**
+ * How many slots must exist before the data repeats.
+ *
+ * At least `minSlots` so the viewport is never short of cards, and at least
+ * `itemCount` so no item appears twice on screen. A closed ring (a barrel, a
+ * dial) is exactly the items: padding would show as gaps in the circle.
+ */
+export function ringLengthFor(itemCount, minSlots, closed = false) {
+    return closed ? Math.max(itemCount, 1) : Math.max(itemCount, minSlots, 1);
+}
+/**
+ * Slots mounted on each side of the mount centre.
+ *
+ * The viewport's need (`minSlots`) plus `buffer`, raised to `reach + 1` when a
+ * layout shows cards further out than the viewport math expects (a barrel
+ * folds many cards into a narrow strip). `Infinity` asks for the whole ring.
+ * An open ring stops at `count` each side, which already covers every item. A
+ * closed ring stops at `floor(count / 2)`: further out, a slot would be a
+ * second copy of a card already mounted on the other side (`mountSpanFor`
+ * trims the one extra slot an even count would still give).
+ */
+export function mountHalfFor(minSlots, buffer, count, reach, closed = false) {
+    const base = Math.ceil((minSlots - 1) / 2) + buffer;
+    const wanted = reach === undefined ? 0 : Number.isFinite(reach) ? Math.ceil(reach) + 1 : count;
+    const half = Math.max(base, Math.min(wanted, count));
+    return closed ? Math.min(half, Math.floor(count / 2)) : half;
+}
+/**
+ * How many consecutive slots `Window` mounts, starting at `centre - half`.
+ *
+ * Usually `2 · half + 1`. A closed ring never mounts more than `count`: the
+ * slots are consecutive, so `count` of them hold every card exactly once,
+ * wherever the centre is (even pushed ahead by the speed lookahead). With an
+ * even count and the whole ring mounted, that drops the last slot, a second
+ * copy of the card straight opposite the first.
+ */
+export function mountSpanFor(half, count, closed = false) {
+    const span = 2 * half + 1;
+    return closed ? Math.min(span, Math.max(count, 1)) : span;
+}