@sharedex/ui 0.0.0-stage → 0.10.0

package/dist/carousel/parts/Slot.js

@@ -0,0 +1,93 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { memo, useMemo } from "react";
+import { motion } from "motion/react";
+import { useCarouselEngineRef } from "../engine/handle.js";
+import { useSlotWriter } from "../slot/useSlotWriter.js";
+import { SlotContext } from "../slot/context.js";
+import { useCarouselStyle } from "./Root.js";
+import { TransitionNodes, transitionStyle } from "../../transitions/hosts/shared.js";
+/**
+ * The required part. It owns position, sizing and the engine contract; the
+ * child owns every pixel.
+ *
+ * The card is a 100%-by-100% tenant of a box the ENGINE sized, which is what
+ * makes an arbitrary card design safe: in 0.1.0 pitch was measured off the
+ * card's own root and silently included a 16px divider the card rendered, so
+ * swapping the card moved every other card. A card can no longer reach the
+ * layout maths at all.
+ *
+ * Three ways for a child to choreograph its own internals, cheapest first:
+ *
+ * 1. `var(--sx-distance)` in plain CSS -- no React, no hook, no context.
+ * 2. `useSlotState().distance` for a MotionValue.
+ * 3. `useSlotValue("scaleY")` for a RESOLVED layout output, materialised lazily.
+ *
+ * Reads the MERGED engine (motion + data), deliberately, not the motion-only
+ * slice. `useSlotWriter`'s render-body write only re-runs when THIS component
+ * re-renders or when `position`/`mode` change -- nothing else re-triggers it.
+ * If Slot subscribed to motion only, a metrics update (the ResizeObserver
+ * landing real numbers after mount, or a resize) would change `centerOffset`/
+ * `pitch` in the data slice while never giving an already-mounted, already-
+ * memoized Slot any reason to notice: `SlotContent`-style memoization (see the
+ * playground) correctly sees an unchanged `itemIndex` and skips calling this
+ * component again, so its write path would stay frozen at whatever geometry
+ * was current on its FIRST render -- typically all zeros, before the probe had
+ * measured anything, stacking every slot at x=0 until something UNRELATED
+ * later touches `position` (autoplay's first tick, a drag, a `stepBy` call)
+ * and finally forces a re-run. Subscribing to the merged engine means Slot's
+ * own context read fires on a metrics/filter change independent of any memo
+ * above it, so the write path always sees current geometry.
+ *
+ * This does not reopen the render-count problem `memo` exists for: the actual
+ * hot path (60fps drag/autoplay) was never about context in the first place --
+ * `position` is a MotionValue mutated in place, and `Window` only re-renders
+ * on a quantized slot-boundary crossing -- so it is unaffected either way. What
+ * changes is that Slot's own (cheap: a handful of MotionValue `.set`s, each an
+ * early-out if unchanged) body now correctly re-runs a few times a minute on a
+ * real filter click or resize, which was never the expensive part.
+ *
+ * `memo` still guards `children`: a consumer that skips the SlotContent-style
+ * memoization pattern and calls `<Carousel.Slot>` straight from Window's
+ * render-prop still benefits from `memo` on a boundary crossing that leaves
+ * this slot's index/ringIndex/itemIndex unchanged, PROVIDED their own child
+ * element is also reference-stable. `Carousel.Slot` cannot safely do that
+ * memoization FOR the consumer with a comparator that ignores `children` -- a
+ * card whose output depends on something besides `itemIndex` would then
+ * silently go stale.
+ */
+export const Slot = memo(function Slot({ index, ringIndex, itemIndex, children, className = "", engine, }) {
+    // The merged engine -- see the doc comment above for why motion-only was a
+    // bug, not an optimization, once a memo boundary sits above this component.
+    const handle = useCarouselEngineRef(engine);
+    const { slotClassName, transition } = useCarouselStyle();
+    const writer = useSlotWriter(handle, index);
+    // A CSS transition (stage(wipe())): its vars, its picture for this item, its nodes.
+    const item = itemIndex === null ? undefined : handle.items[itemIndex];
+    const image = transition?.media && item !== undefined ? transition.media(item) : undefined;
+    const slotValue = useMemo(() => ({ index, ringIndex, itemIndex, distance: writer.distance, writer }), [index, ringIndex, itemIndex, writer]);
+    // `fixed` / `fn` sizing has no CSS rule behind it (the probe is only measured
+    // under `measured`), so the slot box takes the engine's numbers directly.
+    const { sizing, axis } = handle.config.engine;
+    const { slotMain, slotCross } = handle.metrics;
+    const box = sizing.kind === "measured"
+        ? undefined
+        : axis === "x"
+            ? { width: slotMain, height: slotCross }
+            : { width: slotCross, height: slotMain };
+    // One ready-made transform string rather than a value per property; see
+    // useSlotWriter for why that is measurably cheaper under motion.
+    const style = {
+        ...box,
+        ...(transition ? transitionStyle(transition, image) : undefined),
+        transform: writer.transform,
+        opacity: writer.opacity,
+        zIndex: writer.zIndex,
+        filter: writer.filter,
+        pointerEvents: writer.pointerEvents,
+        originX: writer.originX,
+        originY: writer.originY,
+        "--sx-distance": writer.distance,
+    };
+    return (_jsx(SlotContext.Provider, { value: slotValue, children: _jsxs(motion.div, { "data-sx-slot": index, "data-sx-item": itemIndex ?? undefined, "data-sx-tr": transition?.id, "data-sx-tr-mode": transition ? "carousel" : undefined, style: style, className: `absolute top-0 left-0 ${slotClassName} ${className}`, children: [children, transition ? _jsx(TransitionNodes, { transition: transition, image: image }) : null] }) }));
+});

package/dist/carousel/parts/Track.d.ts

@@ -0,0 +1,21 @@
+import { type CarouselEngine } from "../engine/handle.js";
+export interface TrackProps {
+    readonly children?: React.ReactNode;
+    readonly className?: string;
+    readonly engine?: CarouselEngine;
+}
+/**
+ * The positioning context every slot is absolutely placed inside, and the host
+ * for the input sources that write `position`.
+ *
+ * The track itself never moves. Each slot computes an absolute offset from its
+ * own distance, so nothing accumulates, there is no ring width to measure, and
+ * there is no drift to correct.
+ *
+ * It carries the whole-carousel `opacity` -- the first-paint reveal and the
+ * filter cross-fade. That animated opacity creates a stacking context, which is
+ * exactly why 3D presets put `perspective()` on each slot's own transform
+ * rather than on a container: a container-level `preserve-3d` would flatten
+ * here, during the two moments people look hardest.
+ */
+export declare function Track({ children, className, engine }: TrackProps): import("react").JSX.Element;

package/dist/carousel/parts/Track.js

@@ -0,0 +1,26 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { motion } from "motion/react";
+import { useCarouselEngineRef } from "../engine/handle.js";
+import { useDrag } from "../input/useDrag.js";
+import { useAutoplay } from "../input/useAutoplay.js";
+/**
+ * The positioning context every slot is absolutely placed inside, and the host
+ * for the input sources that write `position`.
+ *
+ * The track itself never moves. Each slot computes an absolute offset from its
+ * own distance, so nothing accumulates, there is no ring width to measure, and
+ * there is no drift to correct.
+ *
+ * It carries the whole-carousel `opacity` -- the first-paint reveal and the
+ * filter cross-fade. That animated opacity creates a stacking context, which is
+ * exactly why 3D presets put `perspective()` on each slot's own transform
+ * rather than on a container: a container-level `preserve-3d` would flatten
+ * here, during the two moments people look hardest.
+ */
+export function Track({ children, className = "", engine }) {
+    const handle = useCarouselEngineRef(engine);
+    const drag = useDrag(handle);
+    useAutoplay(handle);
+    return (_jsx(motion.div, { ref: handle.trackRef, "data-sx-track": true, style: { opacity: handle.opacity }, className: `absolute inset-0 select-none ${drag.enabled ? "cursor-grab active:cursor-grabbing" : "cursor-default"} ${className}`, onPanStart: drag.enabled ? drag.onPanStart : undefined, onPan: drag.enabled ? drag.onPan : undefined, onPanEnd: drag.enabled ? drag.onPanEnd : undefined, onClickCapture: drag.onClickCapture, children: children }));
+}

package/dist/carousel/parts/Viewport.d.ts

@@ -0,0 +1,33 @@
+import { type CarouselEngine } from "../engine/handle.js";
+export interface ViewportProps {
+    readonly children?: React.ReactNode;
+    readonly className?: string;
+    readonly engine?: CarouselEngine;
+    /**
+     * Overrides the axis-derived default. Note `touch-action` intersects down the
+     * ancestor chain, so a cross-axis nested carousel resolves to `none` and gives
+     * up native scrolling inside its own region -- platform behaviour, not a bug.
+     */
+    readonly touchAction?: string;
+}
+/**
+ * The measured region, the gesture surface, and the owner of the sizing probe.
+ *
+ * ## The probe
+ *
+ * One `aria-hidden` element the engine renders and owns, carrying the same
+ * `slotClassName` as every slot. It does three jobs that used to be split or
+ * broken:
+ *
+ * 1. It is what `useMetrics` measures, so pitch comes from the engine rather
+ *    than from whichever card happened to be leftmost.
+ * 2. It never unmounts, so its ResizeObserver is stable and an item card and a
+ *    placeholder card can no longer report different pitches.
+ * 3. On a horizontal carousel it stays in flow and holds the region open at one
+ *    card's height -- replacing 0.1.0's separate "ghost sizer", which duplicated
+ *    the card height class as a second source of truth.
+ *
+ * On a vertical carousel the main axis IS the height, so the consumer sizes the
+ * viewport and the probe goes absolute to stay out of the way.
+ */
+export declare function Viewport({ children, className, engine, touchAction, }: ViewportProps): import("react").JSX.Element;

package/dist/carousel/parts/Viewport.js

@@ -0,0 +1,53 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCarouselMotion } from "../engine/handle.js";
+import { useCarouselStyle } from "./Root.js";
+/**
+ * The measured region, the gesture surface, and the owner of the sizing probe.
+ *
+ * ## The probe
+ *
+ * One `aria-hidden` element the engine renders and owns, carrying the same
+ * `slotClassName` as every slot. It does three jobs that used to be split or
+ * broken:
+ *
+ * 1. It is what `useMetrics` measures, so pitch comes from the engine rather
+ *    than from whichever card happened to be leftmost.
+ * 2. It never unmounts, so its ResizeObserver is stable and an item card and a
+ *    placeholder card can no longer report different pitches.
+ * 3. On a horizontal carousel it stays in flow and holds the region open at one
+ *    card's height -- replacing 0.1.0's separate "ghost sizer", which duplicated
+ *    the card height class as a second source of truth.
+ *
+ * On a vertical carousel the main axis IS the height, so the consumer sizes the
+ * viewport and the probe goes absolute to stay out of the way.
+ */
+export function Viewport({ children, className = "", engine, touchAction, }) {
+    // Motion-only: everything this component touches (config, id, viewportRef,
+    // probeRef, hovering, focused) lives in the stable slice, so a filter click
+    // or a resize never reaches this component at all.
+    const handle = useCarouselMotion(engine);
+    const { slotClassName } = useCarouselStyle();
+    const axis = handle.config.engine.axis;
+    return (_jsxs("div", { ref: handle.viewportRef, "data-sx-viewport": true, "data-sx-engine": handle.id, "data-sx-axis": axis, className: `relative overflow-hidden ${axis === "x" ? "w-full" : "h-full"} ${className}`, style: { touchAction: touchAction ?? (axis === "x" ? "pan-y" : "pan-x") }, onPointerDown: (e) => {
+            // Where the last tap landed, for transitions that start from it (iris,
+            // ripple): px inside the viewport, plus the distance to its farthest
+            // corner so a circle grown to it covers the whole box. One write per tap.
+            const el = e.currentTarget;
+            const r = el.getBoundingClientRect();
+            const x = e.clientX - r.left;
+            const y = e.clientY - r.top;
+            const far = Math.hypot(Math.max(x, r.width - x), Math.max(y, r.height - y));
+            el.style.setProperty("--sx-origin-x", `${Math.round(x)}px`);
+            el.style.setProperty("--sx-origin-y", `${Math.round(y)}px`);
+            el.style.setProperty("--sx-origin-r", `${Math.ceil(far)}px`);
+        }, onPointerEnter: () => {
+            handle.hovering.current = true;
+        }, onPointerLeave: () => {
+            handle.hovering.current = false;
+        }, onFocusCapture: () => {
+            handle.focused.current = true;
+        }, onBlurCapture: () => {
+            handle.focused.current = false;
+        }, children: [_jsx("div", { ref: handle.probeRef, "data-sx-probe": true, "aria-hidden": true, className: `pointer-events-none invisible ${axis === "y" ? "absolute top-0 left-0" : ""} ${slotClassName}` }), children] }));
+}

package/dist/carousel/parts/Window.d.ts

@@ -0,0 +1,28 @@
+import { type CarouselHandle } from "../engine/handle.js";
+export interface WindowSlot<T> {
+    /** Positional, not identity-based: React reconciles one slot in and one out. */
+    readonly key: string;
+    /** Unbounded integer line position. May be negative. */
+    readonly index: number;
+    readonly ringIndex: number;
+    readonly itemIndex: number | null;
+    /** null at a placeholder position. */
+    readonly item: T | null;
+}
+export interface WindowProps<T> {
+    readonly children: (slot: WindowSlot<T>) => React.ReactNode;
+    readonly engine?: CarouselHandle<T>;
+}
+/**
+ * Virtualization: mount `2 * half + 1` slots centred on the current position,
+ * however many items exist.
+ *
+ * A slot is a position on an unbounded integer line; an item is a data record.
+ * `wrapIndex` maps one to the other, so slot 23 on a ring of 20 shows item 3.
+ * That is the whole looping mechanism -- no cloned nodes, no scroll reset, and
+ * the teleport lives in a modulo rather than in the pixels.
+ *
+ * `centre` is quantized, so this setState fires when a slot boundary is crossed
+ * rather than sixty times a second.
+ */
+export declare function Window<T>({ children, engine }: WindowProps<T>): import("react").JSX.Element | null;

package/dist/carousel/parts/Window.js

@@ -0,0 +1,53 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useRef, useState } from "react";
+import { useMotionValueEvent } from "motion/react";
+import { useCarouselHandle } from "../engine/handle.js";
+import { mountSpanFor, wrapIndex } from "../engine/ring.js";
+/**
+ * Virtualization: mount `2 * half + 1` slots centred on the current position,
+ * however many items exist.
+ *
+ * A slot is a position on an unbounded integer line; an item is a data record.
+ * `wrapIndex` maps one to the other, so slot 23 on a ring of 20 shows item 3.
+ * That is the whole looping mechanism -- no cloned nodes, no scroll reset, and
+ * the teleport lives in a modulo rather than in the pixels.
+ *
+ * `centre` is quantized, so this setState fires when a slot boundary is crossed
+ * rather than sixty times a second.
+ */
+export function Window({ children, engine }) {
+    const handle = useCarouselHandle(engine);
+    const { count, half } = handle;
+    const [centre, setCentre] = useState(() => handle.getMountCentre());
+    // Guarded by a ref rather than by returning the same value from the setter:
+    // React still renders once before bailing out of an identical state, and the
+    // whole point here is that sub-slot motion touches React zero times.
+    const centreRef = useRef(centre);
+    useMotionValueEvent(handle.position, "change", () => {
+        const next = handle.getMountCentre();
+        if (next === centreRef.current)
+            return;
+        centreRef.current = next;
+        setCentre(next);
+    });
+    if (count === 0)
+        return null;
+    const slots = [];
+    const last = centre - half + mountSpanFor(half, count, handle.config.layout.ring === "closed") - 1;
+    for (let index = centre - half; index <= last; index++) {
+        const ringIndex = wrapIndex(index, count);
+        const ringEntry = handle.ring[ringIndex];
+        const itemIndex = ringEntry === undefined || ringEntry < 0
+            ? null
+            : (handle.visibleIndices[ringEntry] ?? null);
+        slots.push(children({
+            key: `sx-slot-${index}`,
+            index,
+            ringIndex,
+            itemIndex,
+            item: itemIndex === null ? null : (handle.items[itemIndex] ?? null),
+        }));
+    }
+    return _jsx(_Fragment, { children: slots });
+}

package/dist/carousel/parts/index.d.ts

@@ -0,0 +1,34 @@
+import { Root } from "./Root.js";
+import { Viewport } from "./Viewport.js";
+import { Track } from "./Track.js";
+import { Window } from "./Window.js";
+import { Slot } from "./Slot.js";
+import { Parallax } from "./Parallax.js";
+import { Shader } from "./Shader.js";
+import { Panel } from "./Panel.js";
+/**
+ * The compound API. Every part supplies behaviour, sizing and the engine
+ * contract; children supply the pixels.
+ *
+ * Controls, autoplay, pagination and filters land in phase 3.
+ */
+export declare const Carousel: {
+    Root: typeof Root;
+    Viewport: typeof Viewport;
+    Track: typeof Track;
+    Window: typeof Window;
+    Slot: import("react").NamedExoticComponent<import("./Slot.js").SlotProps>;
+    Parallax: typeof Parallax;
+    Shader: typeof Shader;
+    Panel: typeof Panel;
+};
+export { Root, Viewport, Track, Window, Slot, Parallax, Shader, Panel };
+export type { PanelProps } from "./Panel.js";
+export type { ShaderProps } from "./Shader.js";
+export type { ParallaxProps } from "./Parallax.js";
+export type { RootProps, CarouselStyle } from "./Root.js";
+export { useCarouselStyle } from "./Root.js";
+export type { ViewportProps } from "./Viewport.js";
+export type { TrackProps } from "./Track.js";
+export type { WindowProps, WindowSlot } from "./Window.js";
+export type { SlotProps } from "./Slot.js";

package/dist/carousel/parts/index.js

@@ -0,0 +1,26 @@
+import { Root } from "./Root.js";
+import { Viewport } from "./Viewport.js";
+import { Track } from "./Track.js";
+import { Window } from "./Window.js";
+import { Slot } from "./Slot.js";
+import { Parallax } from "./Parallax.js";
+import { Shader } from "./Shader.js";
+import { Panel } from "./Panel.js";
+/**
+ * The compound API. Every part supplies behaviour, sizing and the engine
+ * contract; children supply the pixels.
+ *
+ * Controls, autoplay, pagination and filters land in phase 3.
+ */
+export const Carousel = {
+    Root,
+    Viewport,
+    Track,
+    Window,
+    Slot,
+    Parallax,
+    Shader,
+    Panel,
+};
+export { Root, Viewport, Track, Window, Slot, Parallax, Shader, Panel };
+export { useCarouselStyle } from "./Root.js";

package/dist/carousel/physics/landing.d.ts

@@ -0,0 +1,16 @@
+import type { Release, Settle } from "./types.js";
+/**
+ * Where an inertia settle comes to rest, computed the way motion's inertia
+ * generator does: `origin + power · velocity`, passed through `modifyTarget`,
+ * and pulled back inside `bounds` when the carousel has ends.
+ *
+ * `useDrag` hands this to `animate()` as the target. The generator itself only
+ * reads the first keyframe, but motion skips an animation whose keyframes are
+ * equal unless its `type` is a generator FUNCTION (motion 12.43,
+ * `canAnimate`): `animate(position, position.get(), { type: "inertia" })` never
+ * ran, so every momentum release just stopped where the finger left. A landing
+ * equal to `release.position` means there is genuinely nothing to animate.
+ */
+export declare function inertiaLanding(release: Pick<Release, "position" | "velocity" | "bounds">, spec: Extract<Settle, {
+    kind: "inertia";
+}>): number;

package/dist/carousel/physics/landing.js

@@ -0,0 +1,25 @@
+/** motion's own default `power` for an inertia animation. */
+const DEFAULT_POWER = 0.8;
+/**
+ * Where an inertia settle comes to rest, computed the way motion's inertia
+ * generator does: `origin + power · velocity`, passed through `modifyTarget`,
+ * and pulled back inside `bounds` when the carousel has ends.
+ *
+ * `useDrag` hands this to `animate()` as the target. The generator itself only
+ * reads the first keyframe, but motion skips an animation whose keyframes are
+ * equal unless its `type` is a generator FUNCTION (motion 12.43,
+ * `canAnimate`): `animate(position, position.get(), { type: "inertia" })` never
+ * ran, so every momentum release just stopped where the finger left. A landing
+ * equal to `release.position` means there is genuinely nothing to animate.
+ */
+export function inertiaLanding(release, spec) {
+    const ideal = release.position + (spec.power ?? DEFAULT_POWER) * release.velocity;
+    let landing = spec.modifyTarget ? spec.modifyTarget(ideal) : ideal;
+    const min = spec.min ?? release.bounds?.min;
+    const max = spec.max ?? release.bounds?.max;
+    if (min !== undefined && landing < min)
+        landing = min;
+    if (max !== undefined && landing > max)
+        landing = max;
+    return landing;
+}

package/dist/carousel/physics/policies.d.ts

@@ -0,0 +1,43 @@
+import type { SettlePolicy } from "./types.js";
+export interface MomentumSnapOptions {
+    /** The most cards one flick may pass. Default `4`. */
+    readonly maxSlots?: number;
+    /** How far a flick carries. Default `0.8`. */
+    readonly power?: number;
+    /** ms the glide takes to slow down. Default `325`. */
+    readonly timeConstant?: number;
+    /** The bounce at a real end (`loop: false`). Default `200`. */
+    readonly bounceStiffness?: number;
+    /** Default `40`. */
+    readonly bounceDamping?: number;
+}
+export interface SnapToNearestOptions {
+    /** Default `110`. */
+    readonly stiffness?: number;
+    /** Default `19`. */
+    readonly damping?: number;
+    /** Default `1.05`. */
+    readonly mass?: number;
+}
+export interface FreeScrollOptions {
+    /** Default `0.8`. */
+    readonly power?: number;
+    /** Default `325`. */
+    readonly timeConstant?: number;
+}
+/**
+ * Free scroll, decay, then land on whichever slot the momentum reaches --
+ * capped so one violent flick cannot spin the whole ring.
+ *
+ * `modifyTarget` is what makes this three behaviours in one primitive: motion's
+ * `inertia` projects where the throw would naturally end, then this rounds that
+ * projection to a slot boundary. Free-scroll, inertia decay and snap-to-nearest
+ * fall out together.
+ */
+export declare function momentumSnap(options?: MomentumSnapOptions): SettlePolicy;
+/** Ignore momentum entirely and spring to the closest slot. */
+export declare function snapToNearest(options?: SnapToNearestOptions): SettlePolicy;
+/** Coast to a stop wherever the momentum runs out. No snapping. */
+export declare function freeScroll(options?: FreeScrollOptions): SettlePolicy;
+/** Advance in fixed groups -- a "page" of `n` slots at a time. */
+export declare function pagedBy(n: number, maxPages?: number): SettlePolicy;

package/dist/carousel/physics/policies.js

@@ -0,0 +1,60 @@
+import { clamp } from "../engine/math.js";
+const withBounds = (bounds) => (bounds ? { min: bounds.min, max: bounds.max } : {});
+/**
+ * Free scroll, decay, then land on whichever slot the momentum reaches --
+ * capped so one violent flick cannot spin the whole ring.
+ *
+ * `modifyTarget` is what makes this three behaviours in one primitive: motion's
+ * `inertia` projects where the throw would naturally end, then this rounds that
+ * projection to a slot boundary. Free-scroll, inertia decay and snap-to-nearest
+ * fall out together.
+ */
+export function momentumSnap(options = {}) {
+    const maxSlots = options.maxSlots ?? 4;
+    return (release) => {
+        const start = Math.round(release.position);
+        return {
+            kind: "inertia",
+            power: options.power ?? 0.8,
+            timeConstant: options.timeConstant ?? 325,
+            modifyTarget: (v) => clamp(start - maxSlots, start + maxSlots, Math.round(v)),
+            bounceStiffness: options.bounceStiffness ?? 200,
+            bounceDamping: options.bounceDamping ?? 40,
+            ...withBounds(release.bounds),
+        };
+    };
+}
+/** Ignore momentum entirely and spring to the closest slot. */
+export function snapToNearest(options = {}) {
+    return (release) => ({
+        kind: "spring",
+        to: Math.round(release.position),
+        stiffness: options.stiffness ?? 110,
+        damping: options.damping ?? 19,
+        mass: options.mass ?? 1.05,
+    });
+}
+/** Coast to a stop wherever the momentum runs out. No snapping. */
+export function freeScroll(options = {}) {
+    return (release) => ({
+        kind: "inertia",
+        power: options.power ?? 0.8,
+        timeConstant: options.timeConstant ?? 325,
+        ...withBounds(release.bounds),
+    });
+}
+/** Advance in fixed groups -- a "page" of `n` slots at a time. */
+export function pagedBy(n, maxPages = 1) {
+    const size = Math.max(1, Math.round(n));
+    return (release) => {
+        const start = Math.round(release.position);
+        return {
+            kind: "inertia",
+            modifyTarget: (v) => {
+                const pages = clamp(-maxPages, maxPages, Math.round((v - start) / size));
+                return start + pages * size;
+            },
+            ...withBounds(release.bounds),
+        };
+    };
+}

package/dist/carousel/physics/policies.schema.d.ts

@@ -0,0 +1,9 @@
+/** `pagedBy(n, maxPages)` takes positional arguments; the schema names them. */
+export interface PagedByArgs {
+    readonly n: number;
+    readonly maxPages?: number;
+}
+export declare const MOMENTUM_SNAP_SCHEMA: import("../../schema/types.js").Schema;
+export declare const SNAP_TO_NEAREST_SCHEMA: import("../../schema/types.js").Schema;
+export declare const FREE_SCROLL_SCHEMA: import("../../schema/types.js").Schema;
+export declare const PAGED_BY_SCHEMA: import("../../schema/types.js").Schema;

package/dist/carousel/physics/policies.schema.js

@@ -0,0 +1,41 @@
+import { defineSchema } from "../../schema/define.js";
+const POWER = { kind: "number", label: "Throw", min: 0.1, max: 2, step: 0.05, default: 0.8, help: "How far a flick carries." };
+const TIME = { kind: "number", label: "Glide", min: 50, max: 1000, step: 5, unit: "ms", default: 325, help: "How long the glide takes to slow down." };
+export const MOMENTUM_SNAP_SCHEMA = defineSchema()({
+    id: "momentumSnap",
+    family: "carousel-physics",
+    factory: "momentumSnap",
+    fields: {
+        maxSlots: { kind: "integer", label: "Most cards per flick", min: 1, max: 20, default: 4 },
+        power: POWER,
+        timeConstant: TIME,
+        bounceStiffness: { kind: "number", label: "End bounce stiffness", min: 50, max: 800, step: 10, default: 200, help: "Only without loop.", advanced: true },
+        bounceDamping: { kind: "number", label: "End bounce damping", min: 5, max: 100, step: 1, default: 40, help: "Only without loop.", advanced: true },
+    },
+});
+export const SNAP_TO_NEAREST_SCHEMA = defineSchema()({
+    id: "snapToNearest",
+    family: "carousel-physics",
+    factory: "snapToNearest",
+    fields: {
+        stiffness: { kind: "number", label: "Stiffness", min: 20, max: 600, step: 5, default: 110 },
+        damping: { kind: "number", label: "Damping", min: 2, max: 80, step: 1, default: 19, help: "Lower bounces more." },
+        mass: { kind: "number", label: "Mass", min: 0.1, max: 5, step: 0.05, default: 1.05 },
+    },
+});
+export const FREE_SCROLL_SCHEMA = defineSchema()({
+    id: "freeScroll",
+    family: "carousel-physics",
+    factory: "freeScroll",
+    fields: { power: POWER, timeConstant: TIME },
+});
+export const PAGED_BY_SCHEMA = defineSchema()({
+    id: "pagedBy",
+    family: "carousel-physics",
+    factory: "pagedBy",
+    args: ["n", "maxPages"],
+    fields: {
+        n: { kind: "integer", label: "Cards per page", min: 1, max: 12, required: true },
+        maxPages: { kind: "integer", label: "Most pages per flick", min: 1, max: 6, default: 1 },
+    },
+});

package/dist/carousel/physics/rubberband.d.ts

@@ -0,0 +1,10 @@
+import type { Overdrag } from "./types.js";
+/**
+ * The iOS resistance curve: `d * c * v / (v + d * c)`.
+ *
+ * Asymptotic, so the edge can be pulled a long way but never escapes -- the
+ * further past the end you drag, the less each pixel buys.
+ */
+export declare function rubberband(coefficient?: number): Overdrag;
+/** No give at all -- the carousel stops dead at its ends. */
+export declare const noOverdrag: Overdrag;

package/dist/carousel/physics/rubberband.js

@@ -0,0 +1,18 @@
+/**
+ * The iOS resistance curve: `d * c * v / (v + d * c)`.
+ *
+ * Asymptotic, so the edge can be pulled a long way but never escapes -- the
+ * further past the end you drag, the less each pixel buys.
+ */
+export function rubberband(coefficient = 0.55) {
+    return (overshoot, frame) => {
+        const limit = frame.viewportMain / Math.max(frame.pitch, 1);
+        const d = Math.abs(overshoot);
+        if (d === 0 || limit === 0)
+            return 0;
+        const resisted = (d * coefficient * limit) / (limit + d * coefficient);
+        return overshoot < 0 ? -resisted : resisted;
+    };
+}
+/** No give at all -- the carousel stops dead at its ends. */
+export const noOverdrag = () => 0;