@sharedex/ui 0.0.0-stage → 0.10.0

package/dist/carousel/engine/useMetrics.js

@@ -0,0 +1,120 @@
+"use client";
+import { useEffect, useState } from "react";
+const EMPTY = {
+    slotMain: 0,
+    slotCross: 0,
+    viewportMain: 0,
+    viewportCross: 0,
+    gap: 0,
+    pitch: 0,
+    centerOffset: 0,
+    ready: false,
+};
+/**
+ * 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 function screenScale(rectWidth, layoutWidth) {
+    if (!(layoutWidth > 0) || !(rectWidth > 0))
+        return 1;
+    const k = rectWidth / layoutWidth;
+    return Math.abs(k - 1) < 0.01 ? 1 : k;
+}
+const same = (a, b) => a.slotMain === b.slotMain &&
+    a.slotCross === b.slotCross &&
+    a.viewportMain === b.viewportMain &&
+    a.viewportCross === b.viewportCross &&
+    a.gap === b.gap;
+/**
+ * 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 function useMetrics(viewportRef, probeRef, axis, sizing, gap) {
+    const [metrics, setMetrics] = useState(EMPTY);
+    useEffect(() => {
+        const viewport = viewportRef.current;
+        if (!viewport)
+            return;
+        const measure = () => {
+            const vp = viewport.getBoundingClientRect();
+            // the layout works in CSS px; a scaled ancestor (a zoomed preview, a modal
+            // scaling in) shrinks the on-screen rect, which would shrink every card
+            const k = screenScale(vp.width, viewport.offsetWidth);
+            const viewportMain = (axis === "x" ? vp.width : vp.height) / k;
+            const viewportCross = (axis === "x" ? vp.height : vp.width) / k;
+            let slotMain = 0;
+            let slotCross = 0;
+            if (sizing.kind === "fixed") {
+                slotMain = sizing.main;
+                slotCross = sizing.cross;
+            }
+            else if (sizing.kind === "fn") {
+                const s = sizing.of({ main: viewportMain, cross: viewportCross });
+                slotMain = s.main;
+                slotCross = s.cross;
+            }
+            else {
+                const probe = probeRef.current;
+                if (probe) {
+                    const r = probe.getBoundingClientRect();
+                    slotMain = (axis === "x" ? r.width : r.height) / k;
+                    slotCross = (axis === "x" ? r.height : r.width) / k;
+                }
+            }
+            const next = {
+                slotMain,
+                slotCross,
+                viewportMain,
+                viewportCross,
+                gap,
+                pitch: slotMain + gap,
+                centerOffset: (viewportMain - slotMain) / 2,
+                ready: slotMain > 0 && viewportMain > 0,
+            };
+            // Guard on equality: a ResizeObserver fires far more often than the
+            // numbers actually change, and every accepted update re-renders the
+            // whole slot tree.
+            setMetrics((prev) => (same(prev, next) ? prev : next));
+        };
+        measure();
+        const ro = new ResizeObserver(measure);
+        ro.observe(viewport);
+        const probe = probeRef.current;
+        if (probe)
+            ro.observe(probe);
+        return () => ro.disconnect();
+    }, [viewportRef, probeRef, axis, sizing, gap]);
+    return 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 function minSlotsFor(viewportMain, pitch) {
+    if (pitch <= 0 || viewportMain <= 0)
+        return 1;
+    return Math.ceil(viewportMain / pitch) + 1;
+}
+/**
+ * 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 function isStaticFor(itemCount, viewportMain, pitch) {
+    if (pitch <= 0 || viewportMain <= 0)
+        return itemCount <= 1;
+    return itemCount <= Math.floor(viewportMain / pitch);
+}

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

@@ -0,0 +1,15 @@
+type StartViewTransition = (update: () => void) => {
+    readonly finished: Promise<void>;
+};
+/** `document.startViewTransition`, or null (no support, or on the server). */
+export declare function viewTransitionStarter(): StartViewTransition | null;
+/** A view-transition-name prefix from React's useId (`:r1:` is not a valid name). */
+export declare function viewNamePrefix(id: string): string;
+/**
+ * Name every visible card after its item, once per item: a name may appear only
+ * once on the page, or the browser skips the whole transition. Cards outside
+ * the viewport stay unnamed (their snapshots are not clipped by it).
+ */
+export declare function nameVisibleSlots(viewport: HTMLElement, prefix: string): void;
+export declare function clearSlotNames(viewport: HTMLElement): void;
+export {};

package/dist/carousel/engine/viewSwap.js

@@ -0,0 +1,45 @@
+// The DOM half of `engine.filterTransition: "view"`: a filter swap played by the
+// browser's View Transitions API. Each card on screen gets a
+// `view-transition-name` from its item before and after the swap, so a card in
+// both lists moves to its new place, and the others fade out or in.
+/** `document.startViewTransition`, or null (no support, or on the server). */
+export function viewTransitionStarter() {
+    if (typeof document === "undefined")
+        return null;
+    const doc = document;
+    return typeof doc.startViewTransition === "function" ? doc.startViewTransition.bind(doc) : null;
+}
+/** A view-transition-name prefix from React's useId (`:r1:` is not a valid name). */
+export function viewNamePrefix(id) {
+    return `sx-vt${id.replace(/[^\w-]/g, "")}`;
+}
+/** This carousel's own slots (not those of a carousel nested in a card). */
+function ownSlots(viewport) {
+    return [...viewport.querySelectorAll("[data-sx-slot]")].filter((el) => el.closest("[data-sx-viewport]") === viewport);
+}
+/**
+ * Name every visible card after its item, once per item: a name may appear only
+ * once on the page, or the browser skips the whole transition. Cards outside
+ * the viewport stay unnamed (their snapshots are not clipped by it).
+ */
+export function nameVisibleSlots(viewport, prefix) {
+    const box = viewport.getBoundingClientRect();
+    const seen = new Set();
+    for (const el of ownSlots(viewport)) {
+        el.style.viewTransitionName = "";
+        const item = el.dataset.sxItem;
+        if (item === undefined || seen.has(item))
+            continue;
+        const r = el.getBoundingClientRect();
+        if (r.right <= box.left || r.left >= box.right || r.bottom <= box.top || r.top >= box.bottom)
+            continue;
+        if (el.style.opacity === "0" || el.style.pointerEvents === "none")
+            continue;
+        seen.add(item);
+        el.style.viewTransitionName = `${prefix}-${item}`;
+    }
+}
+export function clearSlotNames(viewport) {
+    for (const el of ownSlots(viewport))
+        el.style.viewTransitionName = "";
+}

package/dist/carousel/input/useAutoplay.d.ts

@@ -0,0 +1,16 @@
+import type { CarouselEngine } from "../engine/handle.js";
+/**
+ * Time-driven advance.
+ *
+ * A delta accumulator on motion's frame loop rather than setInterval, so it
+ * self-corrects for frame drift and stops with the tab for free.
+ *
+ * Pausing ZEROES the clock every frame instead of freezing it, so leaving hover
+ * always buys a full delay rather than resuming a nearly-finished bar.
+ *
+ * Every pause condition reads a ref, never React state. In 0.1.0 hover was
+ * `useState` in the provider, so moving the pointer over the carousel
+ * re-rendered every mounted slot to tell a rAF callback something it could have
+ * read directly.
+ */
+export declare function useAutoplay(handle: CarouselEngine): void;

package/dist/carousel/input/useAutoplay.js

@@ -0,0 +1,43 @@
+"use client";
+import { useAnimationFrame } from "motion/react";
+/**
+ * Time-driven advance.
+ *
+ * A delta accumulator on motion's frame loop rather than setInterval, so it
+ * self-corrects for frame drift and stops with the tab for free.
+ *
+ * Pausing ZEROES the clock every frame instead of freezing it, so leaving hover
+ * always buys a full delay rather than resuming a nearly-finished bar.
+ *
+ * Every pause condition reads a ref, never React state. In 0.1.0 hover was
+ * `useState` in the provider, so moving the pointer over the carousel
+ * re-rendered every mounted slot to tell a rAF callback something it could have
+ * read directly.
+ */
+export function useAutoplay(handle) {
+    const { enabled, delayMs, direction, pauseOnHover, pauseOnFocus, pauseOffscreen, } = handle.config.autoplay;
+    // Floor at 1ms so a stray delayMs of 0 cannot advance on every frame.
+    const ms = Math.max(delayMs, 1);
+    useAnimationFrame((_time, delta) => {
+        if (!enabled || handle.isStatic)
+            return;
+        const mode = handle.mode.get();
+        const paused = mode === "dragging" ||
+            mode === "swapping" ||
+            handle.isOpen ||
+            (pauseOnHover && handle.hovering.current) ||
+            (pauseOnFocus && handle.focused.current) ||
+            (pauseOffscreen && !handle.visible.current) ||
+            (handle.config.a11y.respectReducedMotion && handle.reducedMotion.current);
+        if (paused) {
+            handle.resetAutoplayClock();
+            return;
+        }
+        handle.autoplayClock.current += delta;
+        if (handle.autoplayClock.current >= ms) {
+            handle.stepBy(direction);
+            return;
+        }
+        handle.autoplayProgress.set(handle.autoplayClock.current / ms);
+    });
+}

package/dist/carousel/input/useDrag.d.ts

@@ -0,0 +1,19 @@
+import { type PanInfo } from "motion/react";
+import type { CarouselEngine } from "../engine/handle.js";
+export interface DragHandlers {
+    readonly onPanStart: (event: PointerEvent, info: PanInfo) => void;
+    readonly onPan: (event: PointerEvent, info: PanInfo) => void;
+    readonly onPanEnd: (event: PointerEvent, info: PanInfo) => void;
+    /** Swallows the click that ends a drag, so a card link is not followed. */
+    readonly onClickCapture: (event: React.MouseEvent) => void;
+    /** True while a drag is in flight. */
+    readonly enabled: boolean;
+}
+/**
+ * Pointer dragging, in index space.
+ *
+ * There is no pixel offset stored anywhere: pan offset is divided by the pitch
+ * on the spot, so the engine only ever holds one number in one unit. Sign
+ * follows 0.1.0 -- dragging right lowers `position`, which pushes cards right.
+ */
+export declare function useDrag(handle: CarouselEngine): DragHandlers;

package/dist/carousel/input/useDrag.js

@@ -0,0 +1,125 @@
+"use client";
+import { useCallback, useRef } from "react";
+import { animate } from "motion/react";
+import { inertiaLanding } from "../physics/landing.js";
+/** Cards. An inertia glide ends this close to its target (about a third of a px). */
+const REST_DELTA = 0.001;
+/** Cards per second, for the bounce spring at an end. */
+const REST_SPEED = 0.01;
+/**
+ * Pointer dragging, in index space.
+ *
+ * There is no pixel offset stored anywhere: pan offset is divided by the pitch
+ * on the spot, so the engine only ever holds one number in one unit. Sign
+ * follows 0.1.0 -- dragging right lowers `position`, which pushes cards right.
+ */
+export function useDrag(handle) {
+    const origin = useRef(0);
+    const moved = useRef(false);
+    const { drag, dragThresholdPx, settle, overdrag } = handle.config.physics;
+    const { loop, axis } = handle.config.engine;
+    const enabled = drag && !handle.isStatic;
+    const mainOf = useCallback((v) => (axis === "x" ? v.x : v.y), [axis]);
+    const bounds = useCallback(() => {
+        if (loop)
+            return null;
+        return { min: 0, max: Math.max(handle.itemCount - 1, 0) };
+    }, [loop, handle.itemCount]);
+    const runSettle = useCallback((spec, velocity) => {
+        if (spec.kind === "none") {
+            handle.mode.set("idle");
+            return;
+        }
+        handle.mode.set("settling");
+        const done = () => {
+            if (handle.mode.get() === "settling")
+                handle.mode.set("idle");
+        };
+        if (spec.kind === "spring") {
+            void animate(handle.position, spec.to, {
+                type: "spring",
+                stiffness: spec.stiffness,
+                damping: spec.damping,
+                mass: spec.mass,
+            }).then(done);
+            return;
+        }
+        // inertia derives its own target from velocity and modifyTarget, but motion
+        // skips an animation whose two keyframes are equal (see inertiaLanding), so
+        // the target argument is where it will land, not the current position.
+        const landing = inertiaLanding({ position: handle.position.get(), velocity, bounds: null }, spec);
+        if (landing === handle.position.get()) {
+            done();
+            return;
+        }
+        void animate(handle.position, landing, {
+            type: "inertia",
+            velocity,
+            power: spec.power,
+            timeConstant: spec.timeConstant,
+            modifyTarget: spec.modifyTarget,
+            min: spec.min,
+            max: spec.max,
+            bounceStiffness: spec.bounceStiffness,
+            bounceDamping: spec.bounceDamping,
+            // motion's default (0.5) is meant for pixels; here it is half a card, so
+            // the last half of every glide was a jump onto the card.
+            restDelta: spec.restDelta ?? REST_DELTA,
+            restSpeed: spec.restSpeed ?? REST_SPEED,
+        }).then(done);
+    }, [handle]);
+    const onPanStart = useCallback(() => {
+        if (!enabled)
+            return;
+        origin.current = handle.position.get();
+        moved.current = false;
+        handle.mode.set("dragging");
+    }, [enabled, handle]);
+    const onPan = useCallback((_event, info) => {
+        if (!enabled)
+            return;
+        const frame = handle.readFrame();
+        if (frame.pitch <= 0)
+            return;
+        const offset = mainOf(info.offset);
+        if (Math.abs(offset) > dragThresholdPx)
+            moved.current = true;
+        let next = origin.current - offset / frame.pitch;
+        // Past an end, resistance replaces motion. Looping carousels have no ends.
+        const b = bounds();
+        if (b) {
+            if (next < b.min)
+                next = b.min + overdrag(next - b.min, frame);
+            else if (next > b.max)
+                next = b.max + overdrag(next - b.max, frame);
+        }
+        handle.position.set(next);
+    }, [enabled, handle, mainOf, dragThresholdPx, bounds, overdrag]);
+    const onPanEnd = useCallback((_event, info) => {
+        if (!enabled)
+            return;
+        const frame = handle.readFrame();
+        if (frame.pitch <= 0) {
+            handle.mode.set("idle");
+            return;
+        }
+        const velocity = -mainOf(info.velocity) / frame.pitch;
+        runSettle(settle({
+            position: handle.position.get(),
+            velocity,
+            frame,
+            bounds: bounds(),
+        }), velocity);
+        handle.resetAutoplayClock();
+    }, [enabled, handle, mainOf, settle, bounds, runSettle]);
+    const onClickCapture = useCallback((event) => {
+        if (!moved.current)
+            return;
+        event.preventDefault();
+        event.stopPropagation();
+        // Cleared here, not at the next pan start, so one swallowed click does not
+        // disarm every later click until the user drags again.
+        moved.current = false;
+    }, []);
+    return { onPanStart, onPan, onPanEnd, onClickCapture, enabled };
+}

package/dist/carousel/input/useScrollLink.d.ts

@@ -0,0 +1,37 @@
+import { type RefObject } from "react";
+import type { CarouselEngine } from "../engine/handle.js";
+export interface ScrollLinkOptions {
+    /** Pixels of scroll per card. Default `300`. */
+    readonly pxPerCard?: number;
+    /**
+     * Count the scroll from this element instead of the page top: the first
+     * card is in focus when the element's top edge reaches the top of the
+     * viewport (a tall section with a sticky carousel inside, say).
+     */
+    readonly target?: RefObject<HTMLElement | null>;
+    /** The card in focus before any scrolling, as a position. Default `0`. */
+    readonly start?: number;
+    /** `false` leaves the carousel alone. Default `true`. */
+    readonly enabled?: boolean;
+}
+/** The carousel position for `scrolled` px of scroll. Pure. */
+export declare function scrollLinkPosition(scrolled: number, pxPerCard: number, start?: number): number;
+/**
+ * Scroll drives the carousel: page scroll (or a section's) sets `position`
+ * directly, with no snapping, so the cards follow the scroll like a scrubbed
+ * timeline (a helix that turns as you scroll down the page).
+ *
+ * While the page scrolls the engine's `mode` is `"dragging"`: autoplay pauses
+ * and speed effects (`speedWave`, `speedTilt`, `superFlow`) react to the scroll
+ * speed; 150 ms after the last scroll event it is `"idle"` again, so they settle.
+ * Turn `physics.drag` and autoplay off on a linked carousel, or a drag and the
+ * next scroll event fight over the position.
+ *
+ * ```tsx
+ * <Carousel.Root items={looks} config={config}>
+ *   {(engine) => <Linked engine={engine} />}
+ * </Carousel.Root>
+ * function Linked({ engine }) { useScrollLink(engine, { pxPerCard: 330 }); return … }
+ * ```
+ */
+export declare function useScrollLink(engine: Pick<CarouselEngine, "position" | "mode">, options?: ScrollLinkOptions): void;

package/dist/carousel/input/useScrollLink.js

@@ -0,0 +1,69 @@
+"use client";
+import { useEffect } from "react";
+import { cancelFrame, frame } from "motion/react";
+/** How long after the last scroll event the carousel counts as still, ms. */
+const SETTLE_MS = 150;
+/** The carousel position for `scrolled` px of scroll. Pure. */
+export function scrollLinkPosition(scrolled, pxPerCard, start = 0) {
+    return start + scrolled / Math.max(pxPerCard, 1);
+}
+/**
+ * Scroll drives the carousel: page scroll (or a section's) sets `position`
+ * directly, with no snapping, so the cards follow the scroll like a scrubbed
+ * timeline (a helix that turns as you scroll down the page).
+ *
+ * While the page scrolls the engine's `mode` is `"dragging"`: autoplay pauses
+ * and speed effects (`speedWave`, `speedTilt`, `superFlow`) react to the scroll
+ * speed; 150 ms after the last scroll event it is `"idle"` again, so they settle.
+ * Turn `physics.drag` and autoplay off on a linked carousel, or a drag and the
+ * next scroll event fight over the position.
+ *
+ * ```tsx
+ * <Carousel.Root items={looks} config={config}>
+ *   {(engine) => <Linked engine={engine} />}
+ * </Carousel.Root>
+ * function Linked({ engine }) { useScrollLink(engine, { pxPerCard: 330 }); return … }
+ * ```
+ */
+export function useScrollLink(engine, options = {}) {
+    const { pxPerCard = 300, target, start = 0, enabled = true } = options;
+    const { position, mode } = engine;
+    useEffect(() => {
+        if (!enabled || typeof window === "undefined")
+            return;
+        let idle;
+        let scheduled = false;
+        const scrolled = () => {
+            const el = target?.current;
+            return el ? -el.getBoundingClientRect().top : window.scrollY;
+        };
+        const update = () => {
+            scheduled = false;
+            position.stop();
+            if (mode.get() !== "dragging")
+                mode.set("dragging");
+            position.set(scrollLinkPosition(scrolled(), pxPerCard, start));
+            clearTimeout(idle);
+            idle = setTimeout(() => {
+                if (mode.get() === "dragging")
+                    mode.set("idle");
+            }, SETTLE_MS);
+        };
+        const onScroll = () => {
+            if (scheduled)
+                return;
+            scheduled = true;
+            frame.read(update);
+        };
+        // where the page already is, without counting it as movement
+        position.jump(scrollLinkPosition(scrolled(), pxPerCard, start));
+        window.addEventListener("scroll", onScroll, { passive: true });
+        return () => {
+            window.removeEventListener("scroll", onScroll);
+            cancelFrame(update);
+            clearTimeout(idle);
+            if (mode.get() === "dragging")
+                mode.set("idle");
+        };
+    }, [enabled, pxPerCard, start, target, position, mode]);
+}

package/dist/carousel/layout/curve.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Piecewise-linear clamped interpolation.
+ *
+ * Deliberately NOT `transform` from motion-dom, for two reasons: `motion-dom`
+ * reaches this package only transitively through `framer-motion` (it is not a
+ * declared peer), and layout modifiers must stay importable by a plain
+ * `node:test` run with no React or DOM in scope.
+ *
+ * The arithmetic below is a line-for-line replica of motion 12.43's
+ * `interpolate` (motion-dom/utils/interpolate.mjs) composed with `progress`
+ * and `mixNumber` (motion-utils), in that order and with that association:
+ *
+ *     v = clamp(in[0], in[last], v)
+ *     i = first index where v < in[i+1]           (capped at length-2)
+ *     p = (v - in[i]) / (in[i+1] - in[i])         (1 when the range is zero)
+ *     out[i] + (out[i+1] - out[i]) * p
+ *
+ * Matching the association exactly -- not just the maths -- is what lets the
+ * identity gate in test/wave-curve.test.ts assert bit-equality against motion's
+ * own interpolator rather than settling for a tolerance.
+ */
+export type Curve = (v: number) => number;
+export declare function makeCurve(inputRange: readonly number[], outputRange: readonly number[]): Curve;

package/dist/carousel/layout/curve.js

@@ -0,0 +1,35 @@
+export function makeCurve(inputRange, outputRange) {
+    if (inputRange.length !== outputRange.length) {
+        throw new Error(`[@sharedex/ui] curve: input and output ranges must be the same length (got ${inputRange.length} and ${outputRange.length})`);
+    }
+    const len = inputRange.length;
+    if (len === 0)
+        return () => 0;
+    // Reverse both when the input runs highest -> lowest, as motion does.
+    let input = inputRange;
+    let output = outputRange;
+    if ((input[0] ?? 0) > (input[len - 1] ?? 0)) {
+        input = [...input].reverse();
+        output = [...output].reverse();
+    }
+    const first = input[0] ?? 0;
+    const last = input[len - 1] ?? 0;
+    const out0 = output[0] ?? 0;
+    if (len === 1)
+        return () => out0;
+    return (raw) => {
+        const v = raw > last ? last : raw < first ? first : raw;
+        let i = 0;
+        for (; i < len - 2; i++) {
+            if (v < (input[i + 1] ?? 0))
+                break;
+        }
+        const a = input[i] ?? 0;
+        const b = input[i + 1] ?? 0;
+        const range = b - a;
+        const p = range ? (v - a) / range : 1;
+        const oa = output[i] ?? 0;
+        const ob = output[i + 1] ?? 0;
+        return oa + (ob - oa) * p;
+    };
+}

package/dist/carousel/layout/modifiers/converge.d.ts

@@ -0,0 +1,33 @@
+import type { SlotModifier } from "../types.js";
+export interface ConvergeOptions {
+    /**
+     * Fraction of the pitch to remove, 0..1 -- identical meaning to `track()`'s
+     * `overlap`. Sets the step between adjacent cards near the centre.
+     */
+    readonly overlap?: number;
+    /**
+     * How far past the first neighbour the far-card asymptote sits, measured in
+     * steps. `0.6` means a card 5 away and a card 50 away both land at roughly
+     * `1.6` steps from centre. Larger = a wider but still bounded spread.
+     */
+    readonly tail?: number;
+}
+/**
+ * Main-axis placement that **converges** instead of running linear.
+ *
+ * `track()` places a card at `distance * pitch`, which is unbounded: on a wide
+ * viewport the engine mounts more slots, and cards 4, 5, 6... march off toward
+ * the edges as a flat string. Effects that stack their far cards behind the
+ * centre (coverflow, deck) want the opposite -- the offset should approach a
+ * fixed horizon so a card 3 away and a card 8 away sit in nearly the same place
+ * and read as one pile.
+ *
+ * For `|distance| <= 1` this is byte-identical to `track()` (a card at distance
+ * 1 is one step out). Past that, each further unit of distance adds
+ * `tanh`-shaped, ever-smaller amounts, so the offset asymptotes to
+ * `(1 + tail) * step`.
+ *
+ * Like `track()`, this is the one placement modifier and it reads `frame.axis`,
+ * so it works on either axis and every decorator after it composes unchanged.
+ */
+export declare function converge(options?: ConvergeOptions): SlotModifier;

package/dist/carousel/layout/modifiers/converge.js

@@ -0,0 +1,34 @@
+/**
+ * Main-axis placement that **converges** instead of running linear.
+ *
+ * `track()` places a card at `distance * pitch`, which is unbounded: on a wide
+ * viewport the engine mounts more slots, and cards 4, 5, 6... march off toward
+ * the edges as a flat string. Effects that stack their far cards behind the
+ * centre (coverflow, deck) want the opposite -- the offset should approach a
+ * fixed horizon so a card 3 away and a card 8 away sit in nearly the same place
+ * and read as one pile.
+ *
+ * For `|distance| <= 1` this is byte-identical to `track()` (a card at distance
+ * 1 is one step out). Past that, each further unit of distance adds
+ * `tanh`-shaped, ever-smaller amounts, so the offset asymptotes to
+ * `(1 + tail) * step`.
+ *
+ * Like `track()`, this is the one placement modifier and it reads `frame.axis`,
+ * so it works on either axis and every decorator after it composes unchanged.
+ */
+export function converge(options = {}) {
+    const factor = 1 - (options.overlap ?? 0);
+    const tail = options.tail ?? 0.6;
+    return (buf, slot, frame) => {
+        const d = slot.distance;
+        const abs = Math.abs(d);
+        const sign = d < 0 ? -1 : 1;
+        const near = abs < 1 ? abs : 1;
+        const far = abs > 1 ? Math.tanh(abs - 1) * tail : 0;
+        const main = frame.centerOffset + sign * (near + far) * frame.pitch * factor;
+        if (frame.axis === "x")
+            buf.x = main;
+        else
+            buf.y = main;
+    };
+}

package/dist/carousel/layout/modifiers/curve.d.ts

@@ -0,0 +1,20 @@
+import type { SlotFrameBuffer } from "../../engine/types.js";
+import type { SlotModifier } from "../types.js";
+/**
+ * Any numeric field of the slot buffer. `filter` and `pointerEvents` are the
+ * two non-numeric fields and a curve can't drive them.
+ */
+export type CurveTarget = Exclude<keyof SlotFrameBuffer, "filter" | "pointerEvents">;
+/**
+ * Interpolate one buffer field off `distance` along a keyframed curve.
+ *
+ * The generalisation of `scaleCurve`: `curve("rotateY", [-2,-1,0,1,2], [40,20,0,-20,-40])`
+ * is what coverflow's tilt is, `curve("opacity", [-1,0,1], [0.4,1,0.4])` dims
+ * neighbours, and so on -- all evaluated inside the single per-slot write, never
+ * as their own MotionValue.
+ *
+ * This is Swiper's "creative effect" (explicit values for prev / active / next)
+ * with the keyframes at distance -1 / 0 / 1, generalised to any number of
+ * neighbours and sampled continuously as the carousel moves.
+ */
+export declare function curve(target: CurveTarget, inputRange: readonly number[], outputRange: readonly number[]): SlotModifier;

package/dist/carousel/layout/modifiers/curve.js

@@ -0,0 +1,19 @@
+import { makeCurve } from "../curve.js";
+/**
+ * Interpolate one buffer field off `distance` along a keyframed curve.
+ *
+ * The generalisation of `scaleCurve`: `curve("rotateY", [-2,-1,0,1,2], [40,20,0,-20,-40])`
+ * is what coverflow's tilt is, `curve("opacity", [-1,0,1], [0.4,1,0.4])` dims
+ * neighbours, and so on -- all evaluated inside the single per-slot write, never
+ * as their own MotionValue.
+ *
+ * This is Swiper's "creative effect" (explicit values for prev / active / next)
+ * with the keyframes at distance -1 / 0 / 1, generalised to any number of
+ * neighbours and sampled continuously as the carousel moves.
+ */
+export function curve(target, inputRange, outputRange) {
+    const shape = makeCurve(inputRange, outputRange);
+    return (buf, slot) => {
+        buf[target] = shape(slot.distance);
+    };
+}