@sharedex/ui 0.0.0-stage → 0.10.0

package/dist/carousel/layout/open.js

@@ -0,0 +1,118 @@
+// Open views: how a carousel looks while one card is open (engine.open() /
+// close()). Each view is a layout the engine swaps in while open, so the
+// layout morph animates opening and closing, and the arrows / drag move
+// between cards inside the view, like a lightbox. The open card is always the
+// focused one (distance 0); every term is continuous in distance, so moving
+// between cards while open is smooth too.
+import { modify } from "./types.js";
+function place(buf, frame, main, cross) {
+    if (frame.axis === "x") {
+        buf.x = main;
+        buf.y = cross;
+    }
+    else {
+        buf.y = main;
+        buf.x = cross;
+    }
+}
+/**
+ * The open card grows in place (`size`) and its neighbours step aside to make
+ * room; the carousel's own layout stays. Best on flat layouts: the growth is a
+ * scale around the card's transform origin.
+ */
+function inline(options = {}) {
+    const size = options.size ?? 1.5;
+    const room = options.room ?? 24;
+    const grow = (buf, slot, frame) => {
+        const d = slot.distance;
+        const near = Math.max(0, 1 - Math.abs(d));
+        const k = 1 + (size - 1) * near;
+        buf.scaleX *= k;
+        buf.scaleY *= k;
+        const push = Math.sign(d) * Math.min(1, Math.abs(d)) * (((size - 1) * frame.slotMain) / 2 + room);
+        if (frame.axis === "x")
+            buf.x += push;
+        else
+            buf.y += push;
+        buf.zIndex += Math.round(1000 * near);
+    };
+    const made = new WeakMap();
+    return {
+        kind: "inline",
+        panel: 0,
+        closeOnScroll: options.closeOnScroll ?? 0,
+        layout(base) {
+            let l = made.get(base);
+            if (!l) {
+                l = { ...modify(base, grow), name: `${base.name}+open` };
+                made.set(base, l);
+            }
+            return l;
+        },
+    };
+}
+/** The detail geometry, shared by `detail` (shift 0) and `panel` (shifted towards the start). */
+function stripLayout(name, options, panel) {
+    const strip = options.strip ?? 0.49;
+    const gap = options.gap ?? 12;
+    const fit = options.fit ?? 0.9;
+    const margin = options.margin ?? 16;
+    const reach = options.reach ?? 8;
+    const open = (buf, slot, frame) => {
+        const d = slot.distance;
+        const a = Math.abs(d);
+        const w = Math.min(1, a);
+        const thumbMain = frame.slotMain * strip;
+        const thumbCross = frame.slotCross * strip;
+        const band = thumbCross + 2 * margin;
+        // the open card: as large as fits the space beside the panel and above the strip
+        const roomMain = frame.viewportMain * (1 - panel);
+        const big = Math.max(0.05, Math.min((roomMain * fit) / Math.max(frame.slotMain, 1), ((frame.viewportCross - band) * fit) / Math.max(frame.slotCross, 1)));
+        const bigMain = -(frame.viewportMain * panel) / 2;
+        const bigCross = (frame.viewportCross - band) / 2;
+        // the thumbnails: one strip along the far edge, the open card's place left free
+        const thumbMainAt = d * (thumbMain + gap);
+        const thumbCrossAt = frame.viewportCross - margin - thumbCross / 2;
+        const mainAt = bigMain + (thumbMainAt - bigMain) * w;
+        const crossAt = bigCross + (thumbCrossAt - bigCross) * w;
+        const s = big + (strip - big) * w;
+        place(buf, frame, frame.centerOffset + mainAt, crossAt - frame.slotCross / 2);
+        buf.scaleX = s;
+        buf.scaleY = s;
+        // thumbnails past the strip's ends fade out
+        const half = (frame.viewportMain / 2 - margin) / Math.max(thumbMain + gap, 1);
+        const opacity = Math.min(1, Math.max(0, half + 0.5 - a));
+        buf.opacity = opacity;
+        if (opacity === 0)
+            buf.pointerEvents = "none";
+        buf.zIndex = 1000 - Math.round(a * 10);
+    };
+    return { name, modifiers: [open], reach };
+}
+/**
+ * The open card fills a large box; every other card shrinks into a strip of
+ * thumbnails along the far edge (the bottom on a horizontal carousel). Give the
+ * viewport room for both: its height, not one card's.
+ */
+function detail(options = {}) {
+    const layout = stripLayout("detail", options, 0);
+    return { kind: "detail", panel: 0, closeOnScroll: options.closeOnScroll ?? 0, layout: () => layout };
+}
+/**
+ * Like `detail`, with the open card moved towards the start to leave `panel`
+ * of the width for `<Carousel.Panel>`, the consumer's text about the card.
+ */
+function panel(options = {}) {
+    const share = options.panel ?? 0.42;
+    const layout = stripLayout("panel", options, share);
+    return { kind: "panel", panel: share, closeOnScroll: options.closeOnScroll ?? 0, layout: () => layout };
+}
+/**
+ * How a carousel shows an open card, for `engine.open`:
+ *
+ * ```ts
+ * config={{ engine: { open: openView.detail() } }}
+ * // in a card: onClick={() => engine.open(itemIndex)}; Esc or engine.close() closes
+ * ```
+ */
+export const openView = { inline, detail, panel };

package/dist/carousel/layout/open.schema.d.ts

@@ -0,0 +1,3 @@
+export declare const OPEN_INLINE_SCHEMA: import("../../schema/types.js").Schema;
+export declare const OPEN_DETAIL_SCHEMA: import("../../schema/types.js").Schema;
+export declare const OPEN_PANEL_SCHEMA: import("../../schema/types.js").Schema;

package/dist/carousel/layout/open.schema.js

@@ -0,0 +1,38 @@
+import { defineSchema } from "../../schema/define.js";
+// The open views (`openView.inline()` …), all in open.ts, so their schemas share this file.
+const closeOnScroll = () => ({
+    kind: "integer", label: "Close after scrolling", min: 0, max: 2000, unit: "px", default: 0, help: "Page scroll while open; 0 never closes.",
+});
+const detail = () => ({
+    strip: { kind: "number", label: "Thumbnail size", min: 0.2, max: 0.8, step: 0.01, default: 0.49, help: "As a share of a card." },
+    gap: { kind: "number", label: "Thumbnail gap", min: 0, max: 48, step: 1, unit: "px", default: 12 },
+    fit: { kind: "number", label: "Open card fills", min: 0.5, max: 1, step: 0.01, default: 0.9, help: "Share of the free space above the strip." },
+    margin: { kind: "number", label: "Margin", min: 0, max: 64, step: 1, unit: "px", default: 16, help: "Around the strip.", advanced: true },
+    reach: { kind: "integer", label: "Thumbnails mounted", min: 2, max: 20, default: 8, help: "On each side.", advanced: true },
+    closeOnScroll: closeOnScroll(),
+});
+export const OPEN_INLINE_SCHEMA = defineSchema()({
+    id: "inline",
+    family: "carousel-open",
+    factory: "openView.inline",
+    fields: {
+        size: { kind: "number", label: "Open size", min: 1, max: 3, step: 0.05, default: 1.5, help: "Scale of the open card." },
+        room: { kind: "number", label: "Room", min: 0, max: 120, step: 1, unit: "px", default: 24, help: "Extra space between the open card and its neighbours." },
+        closeOnScroll: closeOnScroll(),
+    },
+});
+export const OPEN_DETAIL_SCHEMA = defineSchema()({
+    id: "detail",
+    family: "carousel-open",
+    factory: "openView.detail",
+    fields: detail(),
+});
+export const OPEN_PANEL_SCHEMA = defineSchema()({
+    id: "panel",
+    family: "carousel-open",
+    factory: "openView.panel",
+    fields: {
+        panel: { kind: "number", label: "Panel width", min: 0.2, max: 0.7, step: 0.01, default: 0.42, help: "Share of the carousel the panel takes, at the end side." },
+        ...detail(),
+    },
+});

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

@@ -0,0 +1,64 @@
+import type { CarouselFrame, SlotFrameBuffer, SlotState } from "../engine/types.js";
+/** One enter / exit preset. A plain object, so it fits `engine.enter` / `engine.exit` whole. */
+export interface PresencePreset {
+    readonly id: string;
+    /** Move `buf` (already the card's resting pose) to how it looks at `p` (0 hidden … 1 shown). */
+    apply(buf: SlotFrameBuffer, slot: SlotState, frame: CarouselFrame, p: number): void;
+    /** Seconds the spring takes to look settled. */
+    readonly visualDuration: number;
+    /** 0 = no overshoot. */
+    readonly bounce: number;
+    /** Seconds of extra delay per card of distance from the focus. */
+    readonly stagger: number;
+}
+export interface PresenceTiming {
+    /** Seconds. Default `0.6`. */
+    readonly visualDuration?: number;
+    /** Default `0`. */
+    readonly bounce?: number;
+    /** Seconds per card of distance. Default `0.015`. */
+    readonly stagger?: number;
+}
+export interface ScatterOptions extends PresenceTiming {
+    /** How far a card is thrown, px, at most, on each axis. Default `320`. */
+    readonly distance?: number;
+    /** How far it tumbles, degrees, at most, around each axis. Default `55`. */
+    readonly turn?: number;
+    /** Same seed, same throw. Default `1`. */
+    readonly seed?: number;
+}
+export interface ExpandOptions extends PresenceTiming {
+    /** Scale a card grows to as it goes. Default `2`. */
+    readonly to?: number;
+}
+export interface SlideAlongOptions extends PresenceTiming {
+    /** How far a card slides along the track, in pitches. Default `0.6`. */
+    readonly distance?: number;
+}
+/** Opacity only. */
+declare function fade(timing?: PresenceTiming): PresencePreset;
+/** Every card shrinks to nothing as it slides into the focus point; fully opaque until it is gone. */
+declare function contract(timing?: PresenceTiming): PresencePreset;
+/** Every card grows (to `to`, 2× by default) and fades, as if flying past the viewer. */
+declare function expand(options?: ExpandOptions): PresencePreset;
+/** Every card is thrown its own way in 3D, tumbling, and fades. Seeded per item, so it repeats. */
+declare function scatter(options?: ScatterOptions): PresencePreset;
+/** Every card slides along the track, away from the focus, and fades. */
+declare function slideAlong(options?: SlideAlongOptions): PresencePreset;
+/**
+ * The enter / exit presets, for `engine.enter` and `engine.exit`:
+ *
+ * ```ts
+ * config={{ engine: { exit: presence.scatter(), enter: presence.contract() } }}
+ * ```
+ *
+ * Grouped under one name because `fade` is already a one-card stage look.
+ */
+export declare const presence: {
+    readonly fade: typeof fade;
+    readonly contract: typeof contract;
+    readonly expand: typeof expand;
+    readonly scatter: typeof scatter;
+    readonly slideAlong: typeof slideAlong;
+};
+export {};

package/dist/carousel/layout/presence.js

@@ -0,0 +1,102 @@
+// Enter / exit presets: how the cards arrive and leave as a whole (the first
+// reveal, a filter swap, engine.hide() / show()). Pure functions of `p`, 0 =
+// hidden, 1 = shown, applied after the layout (and any layout morph), so every
+// preset works on every shape. The engine owns the clock and the per-card stagger.
+import { turnInPlace } from "./modifiers/place3d.js";
+const preset = (id, timing, apply) => ({
+    id,
+    apply,
+    visualDuration: timing.visualDuration ?? 0.6,
+    bounce: timing.bounce ?? 0,
+    stagger: timing.stagger ?? 0.015,
+});
+/** A stable 0..1 for (seed, card, key), no allocation: one round of a 32-bit integer hash. */
+function hash01(seed, card, key) {
+    let h = Math.imul(seed ^ 0x9e3779b9, 0x85ebca6b) ^ Math.imul(card + 0x632be5ab, 0xc2b2ae35) ^ Math.imul(key + 1, 0x27d4eb2f);
+    h ^= h >>> 15;
+    h = Math.imul(h, 0x2c1b3c6d);
+    h ^= h >>> 12;
+    h = Math.imul(h, 0x297a2d39);
+    h ^= h >>> 15;
+    return (h >>> 0) / 4294967296;
+}
+/** Opacity only. */
+function fade(timing = {}) {
+    return preset("fade", timing, (buf, _slot, _frame, p) => {
+        buf.opacity *= p;
+    });
+}
+/** Every card shrinks to nothing as it slides into the focus point; fully opaque until it is gone. */
+function contract(timing = {}) {
+    return preset("contract", timing, (buf, _slot, frame, p) => {
+        const q = 1 - p;
+        // towards where the focused card sits: the viewport centre on the main axis
+        if (frame.axis === "x") {
+            buf.x += (frame.centerOffset - buf.x) * q;
+            buf.y -= buf.y * q;
+        }
+        else {
+            buf.y += (frame.centerOffset - buf.y) * q;
+            buf.x -= buf.x * q;
+        }
+        buf.z -= buf.z * q;
+        buf.scaleX *= p;
+        buf.scaleY *= p;
+        buf.scaleZ *= p;
+        if (p === 0)
+            buf.pointerEvents = "none";
+    });
+}
+/** Every card grows (to `to`, 2× by default) and fades, as if flying past the viewer. */
+function expand(options = {}) {
+    const to = options.to ?? 2;
+    return preset("expand", options, (buf, _slot, _frame, p) => {
+        const s = 1 + (to - 1) * (1 - p);
+        buf.scaleX *= s;
+        buf.scaleY *= s;
+        buf.opacity *= p;
+    });
+}
+/** Every card is thrown its own way in 3D, tumbling, and fades. Seeded per item, so it repeats. */
+function scatter(options = {}) {
+    const distance = options.distance ?? 320;
+    const turn = options.turn ?? 55;
+    const seed = options.seed ?? 1;
+    return preset("scatter", options, (buf, slot, frame, p) => {
+        const q = 1 - p;
+        if (q === 0)
+            return;
+        const card = slot.itemIndex ?? slot.ringIndex;
+        const r = (k) => hash01(seed, card, k) * 2 - 1;
+        if (buf.perspective === 0)
+            buf.perspective = 1000;
+        buf.x += r(0) * distance * q;
+        buf.y += r(1) * distance * q;
+        buf.z += r(2) * distance * q;
+        turnInPlace(buf, frame, r(3) * turn * q, r(4) * turn * q);
+        buf.rotateZ += r(5) * turn * q;
+        buf.opacity *= p;
+    });
+}
+/** Every card slides along the track, away from the focus, and fades. */
+function slideAlong(options = {}) {
+    const distance = options.distance ?? 0.6;
+    return preset("slideAlong", options, (buf, slot, frame, p) => {
+        const away = (slot.distance < 0 ? -1 : 1) * distance * frame.pitch * (1 - p);
+        if (frame.axis === "x")
+            buf.x += away;
+        else
+            buf.y += away;
+        buf.opacity *= p;
+    });
+}
+/**
+ * The enter / exit presets, for `engine.enter` and `engine.exit`:
+ *
+ * ```ts
+ * config={{ engine: { exit: presence.scatter(), enter: presence.contract() } }}
+ * ```
+ *
+ * Grouped under one name because `fade` is already a one-card stage look.
+ */
+export const presence = { fade, contract, expand, scatter, slideAlong };

package/dist/carousel/layout/presence.schema.d.ts

@@ -0,0 +1,5 @@
+export declare const PRESENCE_FADE_SCHEMA: import("../../schema/types.js").Schema;
+export declare const PRESENCE_CONTRACT_SCHEMA: import("../../schema/types.js").Schema;
+export declare const PRESENCE_EXPAND_SCHEMA: import("../../schema/types.js").Schema;
+export declare const PRESENCE_SCATTER_SCHEMA: import("../../schema/types.js").Schema;
+export declare const PRESENCE_SLIDE_ALONG_SCHEMA: import("../../schema/types.js").Schema;

package/dist/carousel/layout/presence.schema.js

@@ -0,0 +1,49 @@
+import { defineSchema } from "../../schema/define.js";
+// The enter / exit presets (`presence.fade()` …), all in presence.ts, so their
+// schemas share this file. Each takes the spring timing; some add their own.
+const timing = () => ({
+    visualDuration: { kind: "number", label: "Duration", min: 0.1, max: 2, step: 0.05, unit: "s", default: 0.6, help: "How long the spring takes to look settled." },
+    bounce: { kind: "number", label: "Bounce", min: 0, max: 0.6, step: 0.01, default: 0 },
+    stagger: { kind: "number", label: "Stagger", min: 0, max: 0.15, step: 0.005, unit: "s", default: 0.015, help: "Extra delay per card away from the focus." },
+});
+export const PRESENCE_FADE_SCHEMA = defineSchema()({
+    id: "fade",
+    family: "carousel-presence",
+    factory: "presence.fade",
+    fields: timing(),
+});
+export const PRESENCE_CONTRACT_SCHEMA = defineSchema()({
+    id: "contract",
+    family: "carousel-presence",
+    factory: "presence.contract",
+    fields: timing(),
+});
+export const PRESENCE_EXPAND_SCHEMA = defineSchema()({
+    id: "expand",
+    family: "carousel-presence",
+    factory: "presence.expand",
+    fields: {
+        to: { kind: "number", label: "Grows to", min: 1, max: 5, step: 0.1, default: 2, help: "Scale a card reaches as it goes." },
+        ...timing(),
+    },
+});
+export const PRESENCE_SCATTER_SCHEMA = defineSchema()({
+    id: "scatter",
+    family: "carousel-presence",
+    factory: "presence.scatter",
+    fields: {
+        distance: { kind: "number", label: "Throw", min: 0, max: 1000, step: 10, unit: "px", default: 320, help: "At most, on each axis." },
+        turn: { kind: "number", label: "Tumble", min: 0, max: 180, step: 1, unit: "°", default: 55, help: "At most, around each axis." },
+        seed: { kind: "seed", label: "Seed", default: 1, help: "Same seed, same throw." },
+        ...timing(),
+    },
+});
+export const PRESENCE_SLIDE_ALONG_SCHEMA = defineSchema()({
+    id: "slideAlong",
+    family: "carousel-presence",
+    factory: "presence.slideAlong",
+    fields: {
+        distance: { kind: "number", label: "Slide", min: 0, max: 3, step: 0.05, default: 0.6, help: "Along the track, in card steps." },
+        ...timing(),
+    },
+});

package/dist/carousel/layout/presets/barrel.d.ts

@@ -0,0 +1,33 @@
+import { type CarouselLayout } from "../types.js";
+export interface BarrelOptions {
+    /**
+     * Degrees between neighbours. Default: 360 / the number of cards, so they
+     * close into a full cylinder that turns forever. Set it to bend an open strip
+     * instead; cards turning past the side then fade out.
+     */
+    readonly angle?: number;
+    /** Cylinder radius, px. Default: neighbours one pitch apart around it (`pitch / angle`). */
+    readonly radius?: number;
+    /** The camera looks down on a horizontal barrel by this many degrees (negative = from above). Default `-8`. */
+    readonly tilt?: number;
+    /** Distance from the viewer, px (CSS `perspective`). Default `1200`. */
+    readonly perspective?: number;
+    /**
+     * `"hide"`: cards fade out as they turn away (70° to 90°), so only the front
+     * of the barrel shows. `"show"`: the far side stays visible, seen from behind.
+     * Default `"hide"`.
+     */
+    readonly back?: "hide" | "show";
+}
+/**
+ * Cards on the outside of a cylinder, like labels around a can: the focused
+ * card faces you, its neighbours turn away around the barrel's axis and sink
+ * back. Horizontal carousels turn around a vertical axis, vertical ones around
+ * a horizontal axis.
+ *
+ * With no `angle` the cards close into a full circle (`ring: "closed"`): the
+ * ring is exactly the items and every card is mounted, so the far side is
+ * already there when it turns round. The arc between two cards is one pitch,
+ * so dragging moves the front of the barrel with the finger.
+ */
+export declare function barrel(options?: BarrelOptions): CarouselLayout;

package/dist/carousel/layout/presets/barrel.js

@@ -0,0 +1,62 @@
+import { composeLayout } from "../types.js";
+import { place3d } from "../modifiers/place3d.js";
+const RAD = Math.PI / 180;
+const FADE_FROM = 70 * RAD;
+const GONE_AT = 90 * RAD;
+/**
+ * Cards on the outside of a cylinder, like labels around a can: the focused
+ * card faces you, its neighbours turn away around the barrel's axis and sink
+ * back. Horizontal carousels turn around a vertical axis, vertical ones around
+ * a horizontal axis.
+ *
+ * With no `angle` the cards close into a full circle (`ring: "closed"`): the
+ * ring is exactly the items and every card is mounted, so the far side is
+ * already there when it turns round. The arc between two cards is one pitch,
+ * so dragging moves the front of the barrel with the finger.
+ */
+export function barrel(options = {}) {
+    const fixed = options.angle === undefined ? undefined : options.angle * RAD;
+    const hide = (options.back ?? "hide") === "hide";
+    const perspective = options.perspective ?? 1200;
+    const tilted = { perspective, tilt: options.tilt ?? -8 };
+    const level = { perspective };
+    const at = { x: 0, y: 0, z: 0, rotateX: 0, rotateY: 0, rotateZ: 0, scale: 1 };
+    const layout = composeLayout("barrel", (buf, slot, frame) => {
+        const step = fixed ?? (2 * Math.PI) / Math.max(frame.count, 1);
+        const radius = options.radius ?? frame.pitch / step;
+        const phi = slot.distance * step;
+        const sin = Math.sin(phi);
+        const cos = Math.cos(phi);
+        // the same angle in (-180°, 180°]: a card one turn round writes the same numbers
+        const wrapped = Math.atan2(sin, cos) / RAD;
+        at.z = radius * (cos - 1);
+        if (frame.axis === "x") {
+            at.x = radius * sin;
+            at.y = 0;
+            at.rotateX = 0;
+            at.rotateY = wrapped;
+        }
+        else {
+            at.x = 0;
+            at.y = radius * sin;
+            at.rotateX = -wrapped;
+            at.rotateY = 0;
+        }
+        place3d(buf, frame, at, frame.axis === "x" ? tilted : level);
+        buf.zIndex = Math.round(100 + 100 * cos);
+        if (!hide)
+            return;
+        const turned = Math.abs(wrapped) * RAD;
+        if (turned >= GONE_AT) {
+            buf.opacity = 0;
+            buf.pointerEvents = "none";
+        }
+        else if (turned > FADE_FROM) {
+            buf.opacity = (GONE_AT - turned) / (GONE_AT - FADE_FROM);
+        }
+    });
+    if (options.angle === undefined)
+        return { ...layout, ring: "closed", reach: Infinity };
+    const seen = hide ? 90 : 180;
+    return { ...layout, reach: Math.ceil(seen / Math.max(Math.abs(options.angle), 1)) + 1 };
+}

package/dist/carousel/layout/presets/barrel.schema.d.ts

@@ -0,0 +1 @@
+export declare const BARREL_SCHEMA: import("../../../schema/types.js").Schema;

package/dist/carousel/layout/presets/barrel.schema.js

@@ -0,0 +1,17 @@
+import { defineSchema } from "../../../schema/define.js";
+export const BARREL_SCHEMA = defineSchema()({
+    id: "barrel",
+    family: "carousel-layout",
+    factory: "barrel",
+    fields: {
+        angle: {
+            kind: "number", label: "Angle between cards", min: 5, max: 90, step: 1, unit: "°", autoValue: 30,
+            autoNote: "a full circle of all the cards",
+            help: "Set it to bend an open strip instead of a closed cylinder; cards turning past the side fade out.",
+        },
+        radius: { kind: "number", label: "Radius", min: 100, max: 2000, step: 10, unit: "px", autoValue: 500, autoNote: "neighbours one card apart", advanced: true },
+        tilt: { kind: "number", label: "Camera tilt", min: -45, max: 45, step: 1, unit: "°", default: -8, help: "Negative looks down on it (horizontal carousels only)." },
+        perspective: { kind: "number", label: "Perspective", min: 300, max: 4000, step: 50, unit: "px", default: 1200, advanced: true },
+        back: { kind: "choice", label: "Far side", values: ["hide", "show"], labels: { hide: "Hidden", show: "Seen from behind" }, default: "hide" },
+    },
+});

package/dist/carousel/layout/presets/coverflow.d.ts

@@ -0,0 +1,26 @@
+import { type CarouselLayout } from "../types.js";
+export interface CoverflowOptions {
+    /** Fraction of pitch removed so cards overlap. Default `0.5`. */
+    readonly overlap?: number;
+    /** Degrees the first neighbour is turned away. Default `45`. */
+    readonly angle?: number;
+    /** Pixels the first neighbour sinks back on z. Default `140`. */
+    readonly depth?: number;
+    /** Per-slot perspective, px. Default `1200`. */
+    readonly perspective?: number;
+}
+/**
+ * The iTunes / Apple TV look: the centre card faces you, its neighbours turn
+ * away in 3D and sink back on the z-axis.
+ *
+ * Placement is `converge()`, not `track()` -- past the second neighbour the
+ * offset asymptotes, so on a wide viewport the far cards fold into a stack
+ * *behind* the centre (helped by a descending `zIndex` and a quick opacity
+ * falloff) instead of stringing out across the screen as flat, same-angle
+ * ghosts.
+ *
+ * `perspective` rides on each slot's own transform, never a container -- the
+ * Track carries an animated opacity, and that flattens `preserve-3d` exactly
+ * during the reveal and filter cross-fade.
+ */
+export declare function coverflow(options?: CoverflowOptions): CarouselLayout;

package/dist/carousel/layout/presets/coverflow.js

@@ -0,0 +1,31 @@
+import { composeLayout } from "../types.js";
+import { converge } from "../modifiers/converge.js";
+import { curve } from "../modifiers/curve.js";
+const RANGE = [-2, -1, 0, 1, 2];
+/**
+ * The iTunes / Apple TV look: the centre card faces you, its neighbours turn
+ * away in 3D and sink back on the z-axis.
+ *
+ * Placement is `converge()`, not `track()` -- past the second neighbour the
+ * offset asymptotes, so on a wide viewport the far cards fold into a stack
+ * *behind* the centre (helped by a descending `zIndex` and a quick opacity
+ * falloff) instead of stringing out across the screen as flat, same-angle
+ * ghosts.
+ *
+ * `perspective` rides on each slot's own transform, never a container -- the
+ * Track carries an animated opacity, and that flattens `preserve-3d` exactly
+ * during the reveal and filter cross-fade.
+ */
+export function coverflow(options = {}) {
+    const overlap = options.overlap ?? 0.5;
+    const angle = options.angle ?? 45;
+    const depth = options.depth ?? 140;
+    const perspective = options.perspective ?? 1200;
+    return composeLayout("coverflow", converge({ overlap }), curve("rotateY", RANGE, [angle, angle, 0, -angle, -angle]), curve("z", RANGE, [-depth, -depth, 0, -depth, -depth]), (buf, slot) => {
+        const a = Math.abs(slot.distance);
+        buf.perspective = perspective;
+        buf.scaleX = buf.scaleY = a < 1 ? 1 - a * 0.06 : 0.94;
+        buf.zIndex = 100 - Math.round(a * 10);
+        buf.opacity = a <= 1 ? 1 : Math.max(1 - (a - 1) * 0.5, 0.15);
+    });
+}

package/dist/carousel/layout/presets/coverflow.schema.d.ts

@@ -0,0 +1 @@
+export declare const COVERFLOW_SCHEMA: import("../../../schema/types.js").Schema;

package/dist/carousel/layout/presets/coverflow.schema.js

@@ -0,0 +1,12 @@
+import { defineSchema } from "../../../schema/define.js";
+export const COVERFLOW_SCHEMA = defineSchema()({
+    id: "coverflow",
+    family: "carousel-layout",
+    factory: "coverflow",
+    fields: {
+        overlap: { kind: "number", label: "Overlap", min: 0, max: 0.9, step: 0.01, default: 0.5, help: "Share of a card's step removed, so cards overlap." },
+        angle: { kind: "number", label: "Turn", min: 0, max: 80, step: 1, unit: "°", default: 45, help: "How far the neighbours turn away." },
+        depth: { kind: "number", label: "Depth", min: 0, max: 500, step: 5, unit: "px", default: 140, help: "How far the neighbours sink back." },
+        perspective: { kind: "number", label: "Perspective", min: 300, max: 4000, step: 50, unit: "px", default: 1200, advanced: true },
+    },
+});

package/dist/carousel/layout/presets/deck.d.ts

@@ -0,0 +1,14 @@
+import { type CarouselLayout } from "../types.js";
+export interface DeckOptions {
+    /** Pixels each card behind the top one drops down. Default `14`. */
+    readonly offset?: number;
+    /** Degrees of tilt each card behind the top one gains. Default `4`. */
+    readonly angle?: number;
+}
+/**
+ * A near-solid pile: cards sit almost fully on top of each other, the ones
+ * behind nudged down and tilted a few degrees. `converge()` with a heavy
+ * overlap and a short tail keeps even a distant card within a few pixels of the
+ * stack, so a wide viewport still shows one deck, not a fan.
+ */
+export declare function deck(options?: DeckOptions): CarouselLayout;

package/dist/carousel/layout/presets/deck.js

@@ -0,0 +1,19 @@
+import { composeLayout } from "../types.js";
+import { converge } from "../modifiers/converge.js";
+import { curve } from "../modifiers/curve.js";
+const SPREAD = [-3, -2, -1, 0, 1, 2, 3];
+const NEAR = [-2, -1, 0, 1, 2];
+/**
+ * A near-solid pile: cards sit almost fully on top of each other, the ones
+ * behind nudged down and tilted a few degrees. `converge()` with a heavy
+ * overlap and a short tail keeps even a distant card within a few pixels of the
+ * stack, so a wide viewport still shows one deck, not a fan.
+ */
+export function deck(options = {}) {
+    const o = options.offset ?? 14;
+    const a = options.angle ?? 4;
+    return composeLayout("deck", converge({ overlap: 0.85, tail: 0.4 }), curve("y", SPREAD, [3 * o, 2 * o, o, 0, o, 2 * o, 3 * o]), curve("rotateZ", NEAR, [2 * a, a, 0, -a, -2 * a]), (buf, slot) => {
+        buf.zIndex = 100 - Math.round(Math.abs(slot.distance) * 10);
+        buf.opacity = Math.max(1 - Math.abs(slot.distance) * 0.16, 0.3);
+    });
+}

package/dist/carousel/layout/presets/deck.schema.d.ts

@@ -0,0 +1 @@
+export declare const DECK_SCHEMA: import("../../../schema/types.js").Schema;

package/dist/carousel/layout/presets/deck.schema.js

@@ -0,0 +1,10 @@
+import { defineSchema } from "../../../schema/define.js";
+export const DECK_SCHEMA = defineSchema()({
+    id: "deck",
+    family: "carousel-layout",
+    factory: "deck",
+    fields: {
+        offset: { kind: "number", label: "Drop", min: 0, max: 60, step: 1, unit: "px", default: 14, help: "How far each card behind the top one drops." },
+        angle: { kind: "number", label: "Tilt", min: 0, max: 20, step: 0.5, unit: "°", default: 4, help: "Added per card behind the top one." },
+    },
+});

package/dist/carousel/layout/presets/expo.d.ts

@@ -0,0 +1,16 @@
+import { type CarouselLayout } from "../types.js";
+export interface ExpoOptions {
+    /** Size of the cards beside the open one, as a fraction of it. Default `0.55`. */
+    readonly small?: number;
+    /** Neighbours shown on each side; the next one fades out. Default `3`. */
+    readonly side?: number;
+    /** Opacity of the neighbours. Default `0.75`. */
+    readonly dim?: number;
+}
+/**
+ * An exhibition shelf: small cards stand side by side on one line and the
+ * active one opens to full size, pushing its neighbours aside. Cards are
+ * packed by their visible size (`pack()`), so the gap stays the same while one
+ * grows and the other shrinks, and they scale from their bottom edge.
+ */
+export declare function expo(options?: ExpoOptions): CarouselLayout;