@sharedex/ui 0.0.0-stage → 0.10.0

package/dist/buttons/runtime/useButtonPress.js

@@ -0,0 +1,23 @@
+"use client";
+import { useEffect } from "react";
+/**
+ * Starts the press runtime on a button whose effects need it: ripples and taps (`needs.tap`), or hold to confirm
+ * (`needs.hold`, seconds). Until it loads, `Button` already blocks the clicks of a hold-to-confirm button.
+ */
+export function useButtonPress(ref, tap, hold) {
+    useEffect(() => {
+        const el = ref.current;
+        if (!el || (!tap && hold === undefined))
+            return;
+        let stop;
+        let gone = false;
+        void import("./attachPress.js").then(({ attachPress }) => {
+            if (!gone)
+                stop = attachPress(el, { tap, hold });
+        });
+        return () => {
+            gone = true;
+            stop?.();
+        };
+    }, [ref, tap, hold]);
+}

package/dist/buttons/runtime/useButtonTier.d.ts

@@ -0,0 +1,7 @@
+import type { ButtonDevice } from "../pick.js";
+/**
+ * The device tier, when an effect on this button needs one (`enabled`). The server and the first render say `low`, so
+ * a heavier effect starts on its fallback and upgrades after mount: no hydration mismatch. The check is loaded only
+ * then, so a page of plain buttons never downloads it.
+ */
+export declare function useButtonTier(enabled: boolean): ButtonDevice;

package/dist/buttons/runtime/useButtonTier.js

@@ -0,0 +1,30 @@
+"use client";
+import { useEffect, useState } from "react";
+/** Detected once per page: the check makes a throwaway WebGL context. */
+let detected;
+/**
+ * The device tier, when an effect on this button needs one (`enabled`). The server and the first render say `low`, so
+ * a heavier effect starts on its fallback and upgrades after mount: no hydration mismatch. The check is loaded only
+ * then, so a page of plain buttons never downloads it.
+ */
+export function useButtonTier(enabled) {
+    const [device, setDevice] = useState(enabled ? (detected ?? "low") : "high");
+    useEffect(() => {
+        if (!enabled)
+            return;
+        if (detected) {
+            setDevice(detected);
+            return;
+        }
+        let gone = false;
+        void import("../../backgrounds/runtime/tier.js").then(({ classifyTier, readTierSignals }) => {
+            detected ?? (detected = classifyTier(readTierSignals()));
+            if (!gone)
+                setDevice(detected);
+        });
+        return () => {
+            gone = true;
+        };
+    }, [enabled]);
+    return device;
+}

package/dist/buttons/runtime/useIdlePause.d.ts

@@ -0,0 +1,6 @@
+import { type RefObject } from "react";
+/**
+ * Pauses a button's endless effects while it is off screen (`data-sx-btn-off`: CSS stops them), and warns when more
+ * than one is on screen: if five buttons pulse, none of them stands out (atlas rule 5).
+ */
+export declare function useIdlePause(ref: RefObject<HTMLElement | null>, enabled: boolean): void;

package/dist/buttons/runtime/useIdlePause.js

@@ -0,0 +1,32 @@
+"use client";
+import { useEffect } from "react";
+import { warnOnce } from "./dev.js";
+/** Buttons with an endless effect on screen right now. */
+const onScreen = new Set();
+/**
+ * Pauses a button's endless effects while it is off screen (`data-sx-btn-off`: CSS stops them), and warns when more
+ * than one is on screen: if five buttons pulse, none of them stands out (atlas rule 5).
+ */
+export function useIdlePause(ref, enabled) {
+    useEffect(() => {
+        const el = ref.current;
+        if (!el || !enabled || typeof IntersectionObserver === "undefined")
+            return;
+        const io = new IntersectionObserver((entries) => {
+            for (const entry of entries) {
+                el.toggleAttribute("data-sx-btn-off", !entry.isIntersecting);
+                if (entry.isIntersecting)
+                    onScreen.add(el);
+                else
+                    onScreen.delete(el);
+            }
+            if (onScreen.size > 1)
+                warnOnce("more than one button with an endless effect is on screen. Use one per screen, or none of them stands out.");
+        });
+        io.observe(el);
+        return () => {
+            io.disconnect();
+            onScreen.delete(el);
+        };
+    }, [ref, enabled]);
+}

package/dist/buttons/types.d.ts

@@ -0,0 +1,127 @@
+import type { SvgElement } from "../backgrounds/types.js";
+/** The atlas's groups. */
+export declare const BUTTON_GROUPS: readonly ["fill", "border", "glow", "depth", "cursor", "label", "press", "state", "idle", "glass"];
+export type ButtonGroup = (typeof BUTTON_GROUPS)[number];
+/** When an effect fires. */
+export type ButtonFires = "hover" | "press" | "state" | "idle";
+/** What it is built with. */
+export type ButtonTech = "css" | "svg" | "js" | "canvas" | "webgl";
+/** The lowest device tier that runs it (same scale as backgrounds and transitions). */
+export type ButtonTier = "all" | "mid" | "high";
+/**
+ * The transform channels of a button. Two effects can't write the same one.
+ * - `press`: `scale` on the hit element.
+ * - `move`: `translate` on the body (lift, magnet).
+ * - `turn`: `rotate` / `transform` on the body (tilt, flip).
+ * - `grow`: `scale` on the body.
+ * - `label`: `transform` / `translate` on the label, its text or its letters.
+ * - `icon`: `translate` on the icon.
+ */
+export type ButtonClaim = "press" | "move" | "turn" | "grow" | "label" | "icon";
+/** What a button is doing: `idle`, or one of the statuses below. `useButtonAction` gives it, or your own code. */
+export type ButtonState = "idle" | ButtonStatus;
+/** The states that have something to show in place of the label. */
+export declare const BUTTON_STATUSES: readonly ["loading", "success", "error"];
+export type ButtonStatus = (typeof BUTTON_STATUSES)[number];
+/** CSS custom properties, written inline on the hit element. Names start with `--sx-btn-<id>-`. */
+export type ButtonVars = Readonly<Record<`--${string}`, string | number>>;
+/**
+ * Where a layer sits.
+ * - `under`: below the face's background (glows, shadows).
+ * - `fill`: on the background, clipped to the radius (sweeps, shine).
+ * - `edge`: above the fill, not clipped (borders).
+ * - `body`: beside the face, inside the part that moves (the back of a flip).
+ */
+export type ButtonSlot = "under" | "fill" | "edge" | "body";
+/** A generated span. An effect never uses pseudo-elements, or two effects on one button would fight over them. */
+export interface ButtonLayer {
+    readonly slot: ButtonSlot;
+    /** Tells an effect's layers apart in its CSS (`data-sx-btn-part`). */
+    readonly part?: string;
+    /** Empty spans inside the layer, named by part (the thing that spins inside a ring). */
+    readonly children?: readonly string[];
+    /** Words inside the layer (the back of a flip). Hidden from screen readers, like every layer. */
+    readonly text?: string;
+    /** Repeats the button's own label inside the layer, when there is no `text`. */
+    readonly copy?: boolean;
+    /** An inline `<svg>` inside the layer. Colours come from the CSS, never attributes. */
+    readonly svg?: {
+        readonly viewBox?: string;
+        readonly preserveAspectRatio?: string;
+        readonly children: readonly SvgElement[];
+    };
+    /** It shows a state (a progress bar), so it stays under reduced motion, when every other layer goes. */
+    readonly keep?: boolean;
+}
+/** Plain flags the runtime reads. */
+export interface ButtonNeeds {
+    /** It runs without end: pause it off screen (atlas rule 5). */
+    readonly inView?: boolean;
+    /** It reads where the pointer is (`--sx-btn-x`, `--sx-btn-dx` …). Needs a mouse: nothing runs on a touch screen. */
+    readonly pointer?: boolean;
+    /** It reacts to each press: the runtime drops ripples into a `ripples` layer and restarts `data-sx-btn-tap`. */
+    readonly tap?: boolean;
+    /** Seconds the button must be held before a click counts (`stateHold`). Clicks before that are blocked. */
+    readonly hold?: number;
+}
+/** An SVG drawn with data: an effect's default icon. */
+export interface ButtonIcon {
+    readonly viewBox: string;
+    readonly children: readonly SvgElement[];
+}
+/** What an effect needs from the label. Effects that ask for the same thing share it. */
+export interface ButtonLabelPlan {
+    /** Cut a text label into letters (`data-sx-btn-char`), or whole words in a joined script. */
+    readonly split?: boolean;
+    /** Keep the text in its own span (`data-sx-btn-text`). */
+    readonly wrap?: boolean;
+    /** A second label (`data-sx-btn-alt`), hidden from screen readers: these words, or `true` to repeat the label. */
+    readonly alt?: string | true;
+    /** The icon when the button has none of its own. */
+    readonly icon?: ButtonIcon;
+    /** Which side the icon goes on, unless the button says. Default `"end"`. */
+    readonly iconAt?: "start" | "end";
+    /** An icon per status, shown in place of the label with the button's `labels` (a spinner while loading). */
+    readonly status?: Partial<Record<ButtonStatus, ButtonIcon>>;
+}
+/**
+ * Code an effect brings with it (`labelScramble`). Only an effect that can't be CSS has one. An effect with one can't
+ * cross from a Server Component, so the page needs `"use client"`; in exchange, a page without it downloads none of it.
+ */
+export interface ButtonProgram {
+    /** Starts it on the button. `text` is its plain label, if it has one. Returns what stops it. */
+    readonly attach: (el: HTMLElement, text: string | undefined) => () => void;
+    /** Stable string of the options: `Button` restarts it only when this or the label changes. */
+    readonly signature: string;
+}
+export interface ButtonMeta {
+    /** The factory's name in the barrel (`fillSweep`, `borderConic` …). */
+    readonly id: string;
+    readonly label: string;
+    readonly group: ButtonGroup;
+    readonly fires: readonly ButtonFires[];
+    readonly tech: ButtonTech;
+    readonly tier: ButtonTier;
+    /** It shows on a touch screen: fires on press, state or idle, and needs no mouse. */
+    readonly touch: boolean;
+    /** One line for the docs table. */
+    readonly description: string;
+}
+/** One effect on a button: plain data, so a Server Component can pass it to `Button`. */
+export interface ButtonEffect {
+    /** The `data-sx-btn` value its stylesheet is keyed on: its registry id. */
+    readonly id: string;
+    readonly tier: ButtonTier;
+    /** Its stylesheet, one per id. Empty when it only sets vars (`pressScale`). */
+    readonly css: string;
+    readonly vars: ButtonVars;
+    readonly layers: readonly ButtonLayer[];
+    readonly claims: readonly ButtonClaim[];
+    readonly needs: ButtonNeeds;
+    /** Rules that show a state rather than a motion, shipped under reduced motion too (`iconMorph`'s pressed pose). */
+    readonly stateCss?: string;
+    readonly label?: ButtonLabelPlan;
+    readonly program?: ButtonProgram;
+    /** What a weaker device wears instead (every `mid` / `high` effect has one). Its id ends in `-lite`. */
+    readonly fallback?: ButtonEffect;
+}

package/dist/buttons/types.js

@@ -0,0 +1,7 @@
+// ---------------------------------------------------------------------------
+// Button effect descriptors and their metadata. See ./CLAUDE.md.
+// ---------------------------------------------------------------------------
+/** The atlas's groups. */
+export const BUTTON_GROUPS = ["fill", "border", "glow", "depth", "cursor", "label", "press", "state", "idle", "glass"];
+/** The states that have something to show in place of the label. */
+export const BUTTON_STATUSES = ["loading", "success", "error"];

package/dist/carousel/config.d.ts

@@ -0,0 +1,120 @@
+import type { CarouselLayout } from "./layout/types.js";
+import type { Axis, SlotSizing } from "./engine/types.js";
+import type { Overdrag, SettlePolicy } from "./physics/types.js";
+import { type LayoutMorphOptions } from "./engine/morph.js";
+import type { PresencePreset } from "./layout/presence.js";
+import type { OpenView } from "./layout/open.js";
+/**
+ * One config object, five sections.
+ *
+ * The rule that keeps this out of deep-merge hell: **no section may contain a
+ * nested object to merge into.** Sections hold scalars and *atomic* values --
+ * functions, tagged unions, a layout -- and atomic values are replaced whole,
+ * never merged. So `resolveConfig` is five spreads and stays readable forever.
+ *
+ * It is also why this config file doubles as the extension mechanism: a field
+ * can hold a function, so "change the physics" and "write a new layout" are
+ * both just config, with no enum to extend and nothing in the bundle you did
+ * not ask for.
+ */
+export interface CarouselConfig {
+    readonly engine: {
+        readonly axis: Axis;
+        /** Infinite wrap-around. Off gives real ends, bounds and rubber-banding. */
+        readonly loop: boolean;
+        /** Engine-owned gutter between slot boxes, px. Cards can never affect it. */
+        readonly gap: number;
+        readonly sizing: SlotSizing;
+        /** Extra slots mounted beyond the visible range, each side. */
+        readonly buffer: number;
+        /**
+         * Seconds of velocity to look ahead when choosing the mount range, so a
+         * fast coast cannot outrun the buffer and pop cards in at the edges.
+         */
+        readonly lookahead: number;
+        /**
+         * How a filter swap (`setFilter`, `resetWithTransition`) plays. `"fade"`
+         * fades the whole carousel out and back in. `"view"` hands it to the
+         * browser's View Transitions API: cards in both lists move to their new
+         * place, the rest fade. Falls back to `"fade"` where the API is missing and
+         * under reduced motion.
+         */
+        readonly filterTransition: "fade" | "view";
+        /**
+         * How a change of `layout` plays: every card blends from where it is to
+         * where the new layout puts it, on one spring, cards further from the focus
+         * a little later. `false` switches instantly. Replaced whole. Off under
+         * reduced motion.
+         */
+        readonly morph: LayoutMorphOptions | false;
+        /**
+         * How the cards arrive: at the first reveal, after a filter swap and on
+         * `engine.show()`. A preset from `presence` (`presence.contract()` …).
+         * `false`: the first reveal fades the whole carousel in, as before.
+         */
+        readonly enter: PresencePreset | false;
+        /**
+         * How the cards leave: before a filter swap and on `engine.hide()`.
+         * Setting `enter` or `exit` replaces the filter swap's whole-carousel fade
+         * (unless `filterTransition` is `"view"`). Under reduced motion both play as
+         * a short fade.
+         */
+        readonly exit: PresencePreset | false;
+        /**
+         * How an open card shows (`engine.open(itemIndex)`): a view from `openView`
+         * (`inline`, `detail`, `panel`). Opening swaps in the view's layout, so
+         * `morph` animates it. `false`: `open()` does nothing.
+         */
+        readonly open: OpenView | false;
+    };
+    readonly physics: {
+        readonly drag: boolean;
+        readonly settle: SettlePolicy;
+        readonly overdrag: Overdrag;
+        /** Movement past this many px counts as a drag, not a click. */
+        readonly dragThresholdPx: number;
+        /**
+         * The spring for arrow, pagination and autoplay steps (drag release uses
+         * `settle`). Replaced whole. Lower damping gives the bouncy "spring" look.
+         */
+        readonly stepSpring: StepSpring;
+    };
+    readonly autoplay: {
+        readonly enabled: boolean;
+        readonly delayMs: number;
+        readonly direction: 1 | -1;
+        readonly pauseOnHover: boolean;
+        readonly pauseOnFocus: boolean;
+        readonly pauseOffscreen: boolean;
+    };
+    readonly layout: CarouselLayout;
+    readonly a11y: {
+        readonly label: string;
+        readonly itemLabel: (index: number, total: number) => string;
+        readonly announce: "polite" | "off";
+        readonly respectReducedMotion: boolean;
+    };
+}
+/** A motion spring, as `animate(value, target, { type: "spring", ...spring })` takes it. */
+export interface StepSpring {
+    readonly stiffness: number;
+    readonly damping: number;
+    readonly mass: number;
+}
+/** Every section partial; atomic-valued sections replaced whole. */
+export interface CarouselOptions {
+    readonly engine?: Partial<CarouselConfig["engine"]>;
+    readonly physics?: Partial<CarouselConfig["physics"]>;
+    readonly autoplay?: Partial<CarouselConfig["autoplay"]>;
+    readonly layout?: CarouselLayout;
+    readonly a11y?: Partial<CarouselConfig["a11y"]>;
+}
+export declare const DEFAULT_CONFIG: CarouselConfig;
+/** Exactly one level of merge. Read it once and you know it forever. */
+export declare function resolveConfig(base: CarouselConfig, options?: CarouselOptions): CarouselConfig;
+/**
+ * Build a project-wide default once, then pass per-instance overrides to
+ * `<Carousel.Root config={...}>`. This is the "carousel config file" -- import
+ * it, spread it, tune it in one place.
+ */
+export declare function defineCarouselDefaults(options: CarouselOptions): CarouselConfig;

package/dist/carousel/config.js

@@ -0,0 +1,61 @@
+import { wave } from "./layout/presets/wave.js";
+import { momentumSnap } from "./physics/policies.js";
+import { rubberband } from "./physics/rubberband.js";
+import { DEFAULT_MORPH } from "./engine/morph.js";
+export const DEFAULT_CONFIG = {
+    engine: {
+        axis: "x",
+        loop: true,
+        gap: 16,
+        sizing: { kind: "measured" },
+        buffer: 2,
+        lookahead: 0.12,
+        filterTransition: "fade",
+        morph: DEFAULT_MORPH,
+        enter: false,
+        exit: false,
+        open: false,
+    },
+    physics: {
+        drag: true,
+        settle: momentumSnap(),
+        overdrag: rubberband(),
+        dragThresholdPx: 4,
+        stepSpring: { stiffness: 110, damping: 19, mass: 1.05 },
+    },
+    autoplay: {
+        enabled: true,
+        delayMs: 3000,
+        direction: 1,
+        pauseOnHover: true,
+        pauseOnFocus: true,
+        pauseOffscreen: true,
+    },
+    layout: wave(),
+    a11y: {
+        label: "Carousel",
+        itemLabel: (index, total) => `${index + 1} of ${total}`,
+        announce: "polite",
+        respectReducedMotion: true,
+    },
+};
+/** Exactly one level of merge. Read it once and you know it forever. */
+export function resolveConfig(base, options) {
+    if (!options)
+        return base;
+    return {
+        engine: { ...base.engine, ...options.engine },
+        physics: { ...base.physics, ...options.physics },
+        autoplay: { ...base.autoplay, ...options.autoplay },
+        layout: options.layout ?? base.layout,
+        a11y: { ...base.a11y, ...options.a11y },
+    };
+}
+/**
+ * Build a project-wide default once, then pass per-instance overrides to
+ * `<Carousel.Root config={...}>`. This is the "carousel config file" -- import
+ * it, spread it, tune it in one place.
+ */
+export function defineCarouselDefaults(options) {
+    return resolveConfig(DEFAULT_CONFIG, options);
+}

package/dist/carousel/config.schema.d.ts

@@ -0,0 +1,21 @@
+import type { CarouselConfig } from "./config.js";
+import type { SlotModifier } from "./layout/types.js";
+type Sections = CarouselConfig["engine"] & CarouselConfig["physics"] & CarouselConfig["autoplay"] & CarouselConfig["a11y"];
+/**
+ * `CarouselOptions` flattened for a form. Besides every section's keys and
+ * `layout`: `speed`, a speed effect added to the layout with `modify()`, and
+ * `overdrag` as `rubberband()`'s coefficient (0 is `noOverdrag`).
+ */
+export interface CarouselSettings extends Omit<Sections, "overdrag"> {
+    readonly layout: CarouselConfig["layout"];
+    readonly speed: SlotModifier;
+    readonly overdrag: number;
+}
+/** Where each setting goes in `CarouselOptions`; `layout` covers `speed` too (`modify(layout, speed)`). */
+export type CarouselSection = "engine" | "physics" | "autoplay" | "a11y" | "layout";
+export declare const CAROUSEL_SECTIONS: {
+    readonly [K in keyof CarouselSettings]-?: CarouselSection;
+};
+/** The settings of `<Carousel.Root config>`: written out as a `CarouselOptions` object, not a call. */
+export declare const CAROUSEL_SCHEMA: import("../schema/types.js").Schema;
+export {};

package/dist/carousel/config.schema.js

@@ -0,0 +1,95 @@
+import { defineSchema } from "../schema/define.js";
+export const CAROUSEL_SECTIONS = {
+    layout: "layout",
+    speed: "layout",
+    axis: "engine",
+    loop: "engine",
+    gap: "engine",
+    sizing: "engine",
+    buffer: "engine",
+    lookahead: "engine",
+    filterTransition: "engine",
+    morph: "engine",
+    enter: "engine",
+    exit: "engine",
+    open: "engine",
+    drag: "physics",
+    settle: "physics",
+    overdrag: "physics",
+    dragThresholdPx: "physics",
+    stepSpring: "physics",
+    enabled: "autoplay",
+    delayMs: "autoplay",
+    direction: "autoplay",
+    pauseOnHover: "autoplay",
+    pauseOnFocus: "autoplay",
+    pauseOffscreen: "autoplay",
+    label: "a11y",
+    itemLabel: "a11y",
+    announce: "a11y",
+    respectReducedMotion: "a11y",
+};
+/** The settings of `<Carousel.Root config>`: written out as a `CarouselOptions` object, not a call. */
+export const CAROUSEL_SCHEMA = defineSchema()({
+    id: "carousel",
+    family: "carousel",
+    factory: "defineCarouselDefaults",
+    code: ["sizing", "itemLabel"],
+    fields: {
+        // the look
+        layout: { kind: "effect", label: "Layout", family: "carousel-layout", default: { id: "wave", options: {} } },
+        speed: { kind: "effect", label: "While it moves", family: "carousel-modifier", autoNote: "nothing extra", help: "A wave or a lean that grows with the speed." },
+        // cards in and out
+        enter: { kind: "effect", label: "Cards arrive", family: "carousel-presence", autoNote: "the carousel fades in", help: "On the first reveal, after a filter swap and on engine.show()." },
+        exit: { kind: "effect", label: "Cards leave", family: "carousel-presence", autoNote: "the carousel fades out", help: "Before a filter swap and on engine.hide()." },
+        open: { kind: "effect", label: "Open a card", family: "carousel-open", autoNote: "off", help: "What engine.open() shows; clicking a card opens it." },
+        morph: {
+            kind: "group", label: "Layout change", off: "Switch instantly",
+            help: "How the cards move to a new layout (opening a card included).",
+            default: { visualDuration: 0.7, bounce: 0.15, stagger: 0.015 },
+            fields: {
+                visualDuration: { kind: "number", label: "Duration", min: 0.1, max: 2, step: 0.05, unit: "s", default: 0.7 },
+                bounce: { kind: "number", label: "Bounce", min: 0, max: 0.6, step: 0.01, default: 0.15 },
+                stagger: { kind: "number", label: "Stagger", min: 0, max: 0.1, step: 0.005, unit: "s", default: 0.015, help: "Extra delay per card away from the focus." },
+            },
+        },
+        // movement
+        axis: { kind: "choice", label: "Direction", values: ["x", "y"], labels: { x: "Horizontal", y: "Vertical" }, default: "x", help: "Vertical needs a box with a height." },
+        loop: { kind: "boolean", label: "Loop", default: true, help: "Off: real ends that stretch when pulled." },
+        gap: { kind: "number", label: "Gap", min: 0, max: 96, step: 1, unit: "px", default: 16 },
+        drag: { kind: "boolean", label: "Drag", default: true },
+        settle: { kind: "effect", label: "After a drag", family: "carousel-physics", default: { id: "momentumSnap", options: {} } },
+        overdrag: { kind: "number", label: "Pull past the ends", min: 0, max: 1, step: 0.05, default: 0.55, help: "Only without loop; 0 stops dead." },
+        stepSpring: {
+            kind: "group", label: "Arrow and autoplay spring", help: "Lower damping gives a bouncy step.",
+            default: { stiffness: 110, damping: 19, mass: 1.05 },
+            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 },
+                mass: { kind: "number", label: "Mass", min: 0.1, max: 5, step: 0.05, default: 1.05 },
+            },
+            advanced: true,
+        },
+        dragThresholdPx: { kind: "integer", label: "Drag starts after", min: 0, max: 24, unit: "px", default: 4, help: "Less movement counts as a click.", advanced: true },
+        buffer: { kind: "integer", label: "Extra cards mounted", min: 0, max: 8, default: 2, help: "Beyond the visible ones, each side.", advanced: true },
+        lookahead: { kind: "number", label: "Look ahead", min: 0, max: 0.5, step: 0.01, unit: "s", default: 0.12, help: "Of speed, when choosing which cards to mount.", advanced: true },
+        filterTransition: {
+            kind: "choice", label: "Filter swap", values: ["fade", "view"], labels: { fade: "Fade", view: "Cards move (View Transitions)" }, default: "fade",
+            help: "Only with filter pills.", advanced: true,
+        },
+        // autoplay
+        enabled: { kind: "boolean", label: "Autoplay", default: true },
+        delayMs: { kind: "integer", label: "Delay", min: 500, max: 15000, unit: "ms", default: 3000 },
+        direction: { kind: "choice", label: "Plays", values: [1, -1], labels: { "1": "Forward", "-1": "Backward" }, default: 1 },
+        pauseOnHover: { kind: "boolean", label: "Pause under the pointer", default: true },
+        pauseOnFocus: { kind: "boolean", label: "Pause while focused", default: true, advanced: true },
+        pauseOffscreen: { kind: "boolean", label: "Pause off screen", default: true, advanced: true },
+        // accessibility
+        label: { kind: "text", label: "Name for screen readers", default: "Carousel", advanced: true, help: "Not read out yet: the carousel doesn't render it (planned)." },
+        announce: {
+            kind: "choice", label: "Announce changes", values: ["polite", "off"], labels: { polite: "Politely", off: "Off" }, default: "polite", advanced: true,
+            help: "Not read out yet (planned).",
+        },
+        respectReducedMotion: { kind: "boolean", label: "Respect reduced motion", default: true, advanced: true },
+    },
+});