@sharedex/ui 0.0.0-stage → 0.10.0

package/dist/backgrounds/types.d.ts

@@ -0,0 +1,295 @@
+/** The atlas categories, in the atlas's order. */
+export declare const BACKGROUND_CATEGORIES: readonly ["texture", "glitch", "glass", "shader", "grid", "wave", "particle", "cursor", "scroll", "pattern", "media"];
+export type BackgroundCategory = (typeof BACKGROUND_CATEGORIES)[number];
+/** The technology an effect is built with (the atlas's "Technology" filter). */
+export declare const BACKGROUND_FAMILIES: readonly ["css", "svg", "canvas", "webgl", "three", "motion", "media"];
+export type BackgroundFamily = (typeof BACKGROUND_FAMILIES)[number];
+/**
+ * The weakest device an effect runs smoothly on: `all` (budget phones too),
+ * `mid` (recent mid phones, any laptop), `high` (flagships, good GPUs).
+ */
+export declare const EFFECT_TIERS: readonly ["all", "mid", "high"];
+export type EffectTier = (typeof EFFECT_TIERS)[number];
+/** What a device can carry. `low` runs only `all`-tier effects. */
+export declare const DEVICE_TIERS: readonly ["low", "mid", "high"];
+export type DeviceTier = (typeof DEVICE_TIERS)[number];
+/** 1 = low … 4 = very high, per frame. */
+export type CostLevel = 1 | 2 | 3 | 4;
+export interface EffectCost {
+    /** Extra download, gzipped, as the atlas states it ("<1 KB", "5–15 KB"). */
+    readonly kb: string;
+    readonly cpu: CostLevel;
+    readonly gpu: CostLevel;
+}
+export interface EffectMeta {
+    /** Kebab-case id; also the `data-sx-bg` attribute value. */
+    readonly id: string;
+    /** The atlas row name. */
+    readonly label: string;
+    readonly category: BackgroundCategory;
+    readonly family: BackgroundFamily;
+    readonly cost: EffectCost;
+    readonly tier: EffectTier;
+    readonly needs?: {
+        /** Reacts to the cursor; touch devices get the idle or drag path. */
+        readonly pointer?: boolean;
+        /**
+         * Reads the root's scroll progress (`--sx-scroll`, `--sx-scroll-exit`).
+         * `"native"`: the effect's CSS uses a native scroll timeline and needs the
+         * JS numbers only where that cannot work (no support, or a clipping
+         * `overflow: hidden` ancestor); the host then sets `data-sx-scroll="js"`.
+         */
+        readonly scroll?: boolean | "native";
+    };
+    /** One line of advice from the atlas. */
+    readonly note?: string;
+}
+/** CSS custom properties, written as inline style on an element. */
+export type CssVars = Readonly<Record<`--${string}`, string | number>>;
+/** One generated element of a CSS effect (a blob, a meteor, a ring). */
+export interface BackgroundNode {
+    /** `data-sx-bg-part` value the effect's CSS keys on. */
+    readonly part: string;
+    readonly vars: CssVars;
+    /**
+     * Nodes inside this one. Lets one animated parent move many static
+     * children: Chrome restyles every separately animated element on every
+     * frame, even when the compositor draws the animation.
+     */
+    readonly children?: readonly BackgroundNode[];
+}
+/** Drawn entirely by a stylesheet plus optional generated elements. */
+export interface CssEffect {
+    readonly kind: "css";
+    readonly meta: EffectMeta;
+    /** The effect's stylesheet. Rendered once per page, only when mounted. */
+    readonly css: string;
+    /** Inline custom properties on the layer element. */
+    readonly vars: CssVars;
+    readonly nodes: readonly BackgroundNode[];
+    readonly fallback?: FallbackEffect;
+}
+export interface ImageSource {
+    readonly type: "image";
+    readonly src: string;
+    readonly srcSet?: string;
+    readonly sizes?: string;
+    /** `tile` repeats the image at `tileSize`. */
+    readonly fit: "cover" | "contain" | "tile";
+    readonly tileSize?: string;
+    /** CSS `object-position` / `background-position`. */
+    readonly position?: string;
+    readonly loading: "lazy" | "eager";
+}
+export interface VideoSource {
+    readonly type: "video";
+    /** One source, or several (`{ src, type }`) for format fallbacks. */
+    readonly sources: readonly {
+        readonly src: string;
+        readonly type?: string;
+    }[];
+    /** Shown before the first frame, under reduced motion, and when paused. */
+    readonly poster?: string;
+    readonly fit: "cover" | "contain";
+    readonly position?: string;
+    readonly playbackRate: number;
+}
+/** Which scroll progress a scroll effect follows. See `ScrollState`. */
+export type ScrollRange = "cover" | "exit";
+/** A video, or a sequence of images, whose frame follows the scroll position. */
+export interface ScrubSource {
+    readonly type: "scrub";
+    /** Video sources; ignored when `frames` is given. */
+    readonly sources: readonly {
+        readonly src: string;
+        readonly type?: string;
+    }[];
+    /** Image URLs, one per frame, drawn on a canvas (the Apple-style image sequence). */
+    readonly frames?: readonly string[];
+    readonly poster?: string;
+    readonly fit: "cover" | "contain";
+    readonly position?: string;
+    readonly range: ScrollRange;
+}
+/** The consumer's own file. */
+export interface MediaEffect {
+    readonly kind: "media";
+    readonly meta: EffectMeta;
+    readonly media: ImageSource | VideoSource | ScrubSource;
+    readonly vars: CssVars;
+    /** What stands in on weaker devices (scrub only: plain images and videos run everywhere). */
+    readonly fallback?: CssEffect | MediaEffect;
+}
+/** A colour resolved to numbers: red, green, blue 0–255 and alpha 0–1. */
+export type Rgb = readonly [r: number, g: number, b: number, a: number];
+/** What a canvas program knows about its surface. Sizes are CSS px. */
+export interface CanvasEnv {
+    readonly width: number;
+    readonly height: number;
+    /** The capped devicePixelRatio actually used for the backing store. */
+    readonly dpr: number;
+    readonly rtl: boolean;
+    /** A touch screen is the main input (no hover). */
+    readonly coarse: boolean;
+    /** The effect's colours, resolved in the layer's theme. Never empty. */
+    readonly palette: readonly Rgb[];
+}
+/** The pointer in layer coordinates (CSS px). */
+export interface CanvasPointer {
+    readonly x: number;
+    readonly y: number;
+    /** Over the layer right now. When false, x/y are the last known position. */
+    readonly inside: boolean;
+}
+/**
+ * A canvas effect's three pure-ish functions. `init` builds the state for a
+ * surface, `step` advances it (no drawing: unit-tested in Node), `draw`
+ * paints it. The host owns the canvas, the loop, resizing and pausing.
+ */
+export interface CanvasProgram<S> {
+    init(env: CanvasEnv, random: () => number): S;
+    step(state: S, deltaMs: number, pointer: CanvasPointer, env: CanvasEnv): void;
+    draw(ctx: CanvasRenderingContext2D, state: S, env: CanvasEnv): void;
+}
+/** Drawn by script on a 2D canvas the host owns. */
+export interface CanvasEffect {
+    readonly kind: "canvas";
+    readonly meta: EffectMeta;
+    readonly program: CanvasProgram<any>;
+    /** CSS colours (var() allowed) resolved into `env.palette`. */
+    readonly colors: readonly string[];
+    /** The effect's own frame-rate cap (0 = the display's rate); `Root fps` can lower it. */
+    readonly fps: number;
+    readonly seed: number;
+    /** Stable string of the options: the host rebuilds the state only when it changes. */
+    readonly signature: string;
+    /** Inline custom properties on the layer (opacity, blend, mask). */
+    readonly vars: CssVars;
+    readonly fallback?: FallbackEffect;
+}
+/**
+ * One element of an SVG effect, as data. Attribute names are written the SVG
+ * way (`stroke-width`); the host converts them for React. Any `{uid}` in a
+ * value or an `id` becomes an id unique to the layer, so two layers' filters
+ * and gradients never collide. Colours never go in attributes (presentation
+ * attributes cannot read var()): they come from the effect's CSS, keyed on
+ * `part`.
+ */
+export interface SvgElement {
+    readonly tag: SvgTag;
+    readonly attrs?: Readonly<Record<string, string | number>>;
+    /** `data-sx-bg-part` value the effect's CSS keys on. */
+    readonly part?: string;
+    /** Inline custom properties on this element. */
+    readonly vars?: CssVars;
+    readonly children?: readonly SvgElement[];
+}
+export type SvgTag = "g" | "path" | "circle" | "ellipse" | "rect" | "line" | "polyline" | "polygon" | "defs" | "clipPath" | "linearGradient" | "radialGradient" | "stop" | "filter" | "feGaussianBlur" | "feColorMatrix" | "feComposite" | "feBlend" | "feTurbulence" | "feDisplacementMap";
+/** Drawn as one inline `<svg>` plus a stylesheet. */
+export interface SvgEffect {
+    readonly kind: "svg";
+    readonly meta: EffectMeta;
+    readonly css: string;
+    /** Inline custom properties on the layer element. */
+    readonly vars: CssVars;
+    readonly svg: {
+        readonly viewBox: string;
+        /** `none` stretches (waves), `xMidYMid slice` covers (shapes keep their proportions). */
+        readonly preserveAspectRatio: string;
+        readonly children: readonly SvgElement[];
+    };
+    readonly fallback?: FallbackEffect;
+}
+/** A uniform value: a float or a vec2 / vec3 / vec4. */
+export type UniformValue = number | readonly [number, number] | readonly [number, number, number] | readonly [number, number, number, number];
+/** A colour for the GPU: red, green, blue, alpha, all 0–1. */
+export type Rgba01 = readonly [r: number, g: number, b: number, a: number];
+/** What a GPU program gets each frame. Positions are 0–1 across the layer, y up. */
+export interface GpuFrame {
+    /** Seconds of effect time (slowed under reduced motion `slow`). */
+    readonly time: number;
+    /** Seconds since the previous frame (0 on the first). */
+    readonly delta: number;
+    /** Drawing-buffer size in px. The host sizes the canvas; programs size their own targets. */
+    readonly width: number;
+    readonly height: number;
+    /** Drawing-buffer px per CSS px (capped DPR × `resolution`): multiply any CSS size by it. */
+    readonly dpr: number;
+    readonly pointer: readonly [number, number];
+    readonly pointerIn: boolean;
+    /** Taps / clicks inside the layer since the previous frame. */
+    readonly taps: readonly (readonly [number, number])[];
+    readonly rtl: boolean;
+    /** A touch screen is the main input: programs lower their cost. */
+    readonly coarse: boolean;
+    /** The effect's `colors`, resolved. */
+    readonly colors: readonly Rgba01[];
+}
+/** The GL context a program asked for. */
+export type GpuContext = WebGLRenderingContext | WebGL2RenderingContext;
+/**
+ * A WebGL effect's GPU work, like a canvas program: `init` compiles and
+ * allocates (throw `WebglUnavailable` when the device cannot), `frame` draws
+ * one frame, `dispose` frees everything. The host owns the context, its
+ * release while off screen, the canvas size, the loop, pausing and input.
+ */
+export interface GpuProgram<S> {
+    readonly api: "webgl" | "webgl2";
+    /**
+     * Frames simulated (at 60 fps, no input) before a still frame under reduced
+     * motion, so a simulation shows something. 0 for stateless shaders.
+     */
+    readonly warmup: number;
+    init(gl: GpuContext, frame: GpuFrame, random: () => number): S;
+    frame(gl: GpuContext, state: S, frame: GpuFrame): void;
+    dispose(gl: GpuContext, state: S): void;
+}
+/**
+ * Drawn with WebGL. Most effects are one fragment shader over the whole layer
+ * (`fragment` + `uniforms`, see `defineWebglEffect`): the runner prepends the
+ * precision line, `varying vec2 v_uv` (0–1, y up) and the standard uniforms
+ * `u_time`, `u_resolution`, `u_dpr`, `u_pointer`, `u_pointer_in`, `u_rtl`; the
+ * shader declares each key of `uniforms` and `uniform vec4 u_c0 … u_cN` for
+ * `colors`. Effects that need more (several passes, simulation state, point
+ * or line meshes) bring their own `program`. Output is premultiplied alpha.
+ */
+export interface WebglEffect {
+    readonly kind: "webgl";
+    readonly meta: EffectMeta;
+    readonly program: GpuProgram<any>;
+    /** The single fragment shader, for one-pass effects. */
+    readonly fragment?: string;
+    readonly uniforms?: Readonly<Record<string, UniformValue>>;
+    /** CSS colours (var() allowed), resolved for the program (`u_c0`, `u_c1` … for one-pass shaders). */
+    readonly colors: readonly string[];
+    /** Render size as a fraction of the capped backing size (0.5 = a quarter of the pixels, upscaled). */
+    readonly resolution: number;
+    /** The effect's own frame-rate cap (0 = the display's rate); `Root fps` can lower it. */
+    readonly fps: number;
+    /** Seconds of effect time shown as the still frame (reduced motion `still`). */
+    readonly stillTime: number;
+    readonly seed: number;
+    /** Stable string of the options: the host rebuilds only when it changes. */
+    readonly signature: string;
+    readonly vars: CssVars;
+    /** Every WebGL effect has one: no WebGL, a failed compile, or a weaker device. */
+    readonly fallback: FallbackEffect;
+}
+/**
+ * What a heavier effect falls back to on a weaker device. A fallback can have
+ * its own fallback; `Background.Layer` follows the chain to the first one the
+ * device can run.
+ */
+export type FallbackEffect = CssEffect | MediaEffect | SvgEffect;
+export type BackgroundEffect = CssEffect | MediaEffect | CanvasEffect | SvgEffect | WebglEffect;
+/** How a layer is cut off at the edges. A preset, or any CSS `mask-image` value. */
+export type BackgroundMask = "radial" | "fade-top" | "fade-bottom" | "fade-edges" | (string & {});
+export type BlendMode = "normal" | "multiply" | "screen" | "overlay" | "darken" | "lighten" | "color-dodge" | "color-burn" | "hard-light" | "soft-light" | "difference" | "exclusion" | "hue" | "saturation" | "color" | "luminosity";
+/** Options every effect factory accepts. */
+export interface LayerOptions {
+    /** 0–1, the whole layer. */
+    readonly opacity?: number;
+    /** How the layer mixes with the layers below it. */
+    readonly blend?: BlendMode;
+    readonly mask?: BackgroundMask;
+}

package/dist/backgrounds/types.js

@@ -0,0 +1,20 @@
+// ---------------------------------------------------------------------------
+// Background effects: the descriptor types. Pure: no React, no DOM.
+//
+// An effect factory (`aurora(options)`) returns a plain descriptor. A host
+// (CssHost, MediaHost, later Canvas/WebGL/Three) knows how to draw each `kind`.
+// ---------------------------------------------------------------------------
+/** The atlas categories, in the atlas's order. */
+export const BACKGROUND_CATEGORIES = [
+    "texture", "glitch", "glass", "shader", "grid", "wave",
+    "particle", "cursor", "scroll", "pattern", "media",
+];
+/** The technology an effect is built with (the atlas's "Technology" filter). */
+export const BACKGROUND_FAMILIES = ["css", "svg", "canvas", "webgl", "three", "motion", "media"];
+/**
+ * The weakest device an effect runs smoothly on: `all` (budget phones too),
+ * `mid` (recent mid phones, any laptop), `high` (flagships, good GPUs).
+ */
+export const EFFECT_TIERS = ["all", "mid", "high"];
+/** What a device can carry. `low` runs only `all`-tier effects. */
+export const DEVICE_TIERS = ["low", "mid", "high"];

package/dist/buttons/Button.d.ts

@@ -0,0 +1,46 @@
+import { type ComponentPropsWithRef, type CSSProperties, type ElementType, type MouseEvent, type ReactNode } from "react";
+import { type ButtonEffect, type ButtonState, type ButtonStatus } from "./types.js";
+interface ButtonOwnProps<E extends ElementType> {
+    /** The element to render: a link (`"a"`) or a framework's `Link`. Default `button`. */
+    readonly as?: E;
+    /** One effect or a list; they stack. */
+    readonly effect?: ButtonEffect | readonly ButtonEffect[];
+    /** The default look, from the sx tokens (`styles/button.css`). Default `"solid"`. */
+    readonly variant?: "solid" | "outline" | "ghost";
+    /** Drop the default look. */
+    readonly unstyled?: boolean;
+    /** `false` turns off the press every button gets by default. */
+    readonly press?: boolean;
+    /** An icon beside the label. Icon effects (`iconNudge` …) bring their own when this is left out. */
+    readonly icon?: ReactNode;
+    /** Which side of the label the icon sits on, in reading direction. Default `"end"`. */
+    readonly iconPosition?: "start" | "end";
+    /**
+     * What the button is doing; `useButtonAction` gives it. While loading it sets `aria-busy`, ignores clicks and keeps
+     * its focus (`aria-disabled`, never `disabled`). State effects (`stateSwap` …) show it.
+     */
+    readonly state?: ButtonState;
+    /** How far the work is, 0 to 1 (`stateProgress`, `stateRing`). Left out, they show that it's working, with no number. */
+    readonly progress?: number;
+    /** Words per status, shown in place of the label and announced to screen readers: `{ loading: "Saving" }`. */
+    readonly labels?: Partial<Record<ButtonStatus, string>>;
+    readonly onClick?: (event: MouseEvent<HTMLElement>) => void;
+    /** Goes on the part you see (background, padding, radius). */
+    readonly className?: string;
+    /** Goes on the outer element, which stays still and takes the clicks (`w-full`). */
+    readonly hitClassName?: string;
+    readonly style?: CSSProperties;
+    readonly children?: ReactNode;
+}
+export type ButtonProps<E extends ElementType = "button"> = ButtonOwnProps<E> & Omit<ComponentPropsWithRef<E>, keyof ButtonOwnProps<E>>;
+/**
+ * A button that wears any number of effects. The element you click stays still and paints nothing; the part you see
+ * sits inside it and can move freely, so hover never flickers.
+ *
+ * ```tsx
+ * <Button effect={[fillSweep(), pressScale({ scale: 0.94 })]}>Book now</Button>
+ * <Button as="a" href="/shop" variant="outline" effect={iconNudge()}>Shop</Button>
+ * ```
+ */
+export declare function Button<E extends ElementType = "button">(props: ButtonProps<E>): import("react").JSX.Element;
+export {};

package/dist/buttons/Button.js

@@ -0,0 +1,136 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useCallback, useEffect, useId, useMemo, useRef, } from "react";
+import { styleHref } from "../backgrounds/hosts/CssHost.js";
+import { renderSvgElement } from "../backgrounds/hosts/svgElement.js";
+import { motionOnly } from "../transitions/progress.js";
+import { BUTTON_BASE_CSS } from "./base.js";
+import { claimConflicts } from "./claims.js";
+import { pickEffect } from "./pick.js";
+import { warnOnce } from "./runtime/dev.js";
+import { splitLabel } from "./runtime/split.js";
+import { useButtonPointer } from "./runtime/useButtonPointer.js";
+import { useButtonPress } from "./runtime/useButtonPress.js";
+import { useButtonTier } from "./runtime/useButtonTier.js";
+import { useIdlePause } from "./runtime/useIdlePause.js";
+import { BUTTON_STATUSES } from "./types.js";
+/** The effects as a list, each id once (the last one wins). */
+function effectList(effect) {
+    if (!effect)
+        return [];
+    const list = Array.isArray(effect) ? effect : [effect];
+    return [...new Map(list.map((e) => [e.id, e])).values()];
+}
+/** `{uid}` in a var's value becomes this button's id prefix (`url(#{uid}-goo)` for a filter in one of its layers). */
+function withUid(vars, uid) {
+    const out = {};
+    for (const [k, value] of Object.entries(vars))
+        out[k] = typeof value === "string" ? value.split("{uid}").join(uid) : value;
+    return out;
+}
+/** Every layer of these effects in one slot, in the effects' order. */
+function layersIn(effects, slot, uid, label) {
+    return effects.flatMap((effect) => effect.layers.filter((l) => l.slot === slot).map((layer, i) => _jsx(Layer, { effect: effect, layer: layer, uid: uid, label: label }, `${effect.id}-${i}`)));
+}
+function Layer({ effect, layer, uid, label }) {
+    return (_jsxs("span", { "data-sx-btn-layer": effect.id, "data-sx-btn-part": layer.part, "data-sx-btn-slot": layer.slot, "data-sx-btn-keep": layer.keep ? "" : undefined, "aria-hidden": true, children: [layer.svg ? (_jsx("svg", { viewBox: layer.svg.viewBox, preserveAspectRatio: layer.svg.preserveAspectRatio, focusable: "false", children: layer.svg.children.map((el, i) => renderSvgElement(el, uid, i, "data-sx-btn-svg")) })) : null, layer.children?.map((part) => _jsx("span", { "data-sx-btn-part": part }, part)), layer.text ?? (layer.copy ? label : null)] }));
+}
+/** An icon drawn with data, in the label's colour. */
+function Drawn({ icon, uid }) {
+    return (_jsx("svg", { viewBox: icon.viewBox, focusable: "false", "aria-hidden": true, children: icon.children.map((el, i) => renderSvgElement(el, uid, i, "data-sx-btn-svg")) }));
+}
+/**
+ * What shows in place of the label in each status: an effect's icon and the button's words. They come before the
+ * label and share its grid cell, so the button keeps the width of the widest and the base sheet can hide the label.
+ */
+function Statuses({ plan, labels, uid }) {
+    return BUTTON_STATUSES.map((status) => {
+        const icon = plan?.status?.[status];
+        const words = labels?.[status];
+        if (!icon && !words)
+            return null;
+        return (_jsxs("span", { "data-sx-btn-status": status, "aria-hidden": true, children: [icon ? _jsx(Drawn, { icon: icon, uid: uid }) : null, words ? _jsx("span", { "data-sx-btn-says": "", children: words }) : null] }, status));
+    });
+}
+/** The effects' label plans as one; each status keeps the icon of the last effect that brings one. */
+function mergePlans(effects) {
+    const plans = effects.flatMap((e) => (e.label ? [e.label] : []));
+    if (plans.length === 0)
+        return undefined;
+    const status = Object.assign({}, ...plans.map((p) => p.status));
+    return { ...Object.assign({}, ...plans), ...(Object.keys(status).length > 0 ? { status } : {}) };
+}
+const blockClick = (event) => event.preventDefault();
+/** The label: plain children, unless an effect or an icon asks for more. */
+function Label({ plan, text, icon, iconPosition, uid, children }) {
+    const pieces = useMemo(() => (plan?.split && text !== undefined ? splitLabel(text) : undefined), [plan?.split, text]);
+    const iconNode = icon ?? (plan?.icon ? _jsx(Drawn, { icon: plan.icon, uid: uid }) : null);
+    if (!plan && !iconNode)
+        return _jsx("span", { "data-sx-btn-label": "", children: children });
+    const iconSpan = iconNode ? _jsx("span", { "data-sx-btn-icon": "", children: iconNode }) : null;
+    const start = (iconPosition ?? plan?.iconAt ?? "end") === "start";
+    return (_jsxs("span", { "data-sx-btn-label": "", children: [start ? iconSpan : null, _jsx("span", { "data-sx-btn-text": "", children: pieces ? (_jsxs(_Fragment, { children: [_jsx("span", { "data-sx-btn-sr": "", children: text }), _jsx("span", { "data-sx-btn-chars": "", "aria-hidden": true, children: pieces.map((piece, i) => (_jsx("span", { "data-sx-btn-char": "", style: { "--sx-btn-i": i }, children: piece }, i))) })] })) : (children) }), plan?.alt !== undefined ? (_jsx("span", { "data-sx-btn-alt": "", "aria-hidden": true, children: plan.alt === true ? children : plan.alt })) : null, start ? null : iconSpan] }));
+}
+/**
+ * A button that wears any number of effects. The element you click stays still and paints nothing; the part you see
+ * sits inside it and can move freely, so hover never flickers.
+ *
+ * ```tsx
+ * <Button effect={[fillSweep(), pressScale({ scale: 0.94 })]}>Book now</Button>
+ * <Button as="a" href="/shop" variant="outline" effect={iconNudge()}>Shop</Button>
+ * ```
+ */
+export function Button(props) {
+    const { as, effect, variant = "solid", unstyled, press = true, icon, iconPosition, state, progress, labels, onClick, className, hitClassName, style, children, ref, ...rest } = props;
+    const Hit = as ?? "button";
+    const wanted = effectList(effect);
+    // a weaker device wears each heavy effect's fallback; the check runs only when one is heavy
+    const device = useButtonTier(wanted.some((e) => e.tier !== "all"));
+    const effects = wanted.map((e) => pickEffect(e, device));
+    for (const { claim, ids } of claimConflicts(effects)) {
+        warnOnce(`button effects ${ids.join(" and ")} both write the "${claim}" channel: the last one wins. Keep one of them.`);
+    }
+    const own = useRef(null);
+    const setRef = useCallback((el) => {
+        own.current = el;
+        if (typeof ref === "function")
+            ref(el);
+        else if (ref)
+            ref.current = el;
+    }, [ref]);
+    const plan = mergePlans(effects);
+    const text = typeof children === "string" ? children : typeof children === "number" ? String(children) : undefined;
+    if (text === undefined && (plan?.split || effects.some((e) => e.program))) {
+        warnOnce("a button effect that moves letters needs a plain text label: with anything else, the label stays still.");
+    }
+    const hold = effects.find((e) => e.needs.hold)?.needs.hold;
+    useIdlePause(own, effects.some((e) => e.needs.inView));
+    useButtonPointer(own, effects.some((e) => e.needs.pointer));
+    useButtonPress(own, effects.some((e) => e.needs.tap), hold);
+    const programs = effects.filter((e) => e.program);
+    const programKey = programs.map((e) => `${e.id}:${e.program.signature}`).join(" ");
+    useEffect(() => {
+        const el = own.current;
+        if (!el || programs.length === 0)
+            return;
+        const stops = programs.map((e) => e.program.attach(el, text));
+        return () => stops.forEach((stop) => stop());
+        // a factory called during render makes a new program every time: only its options and the label restart it
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [programKey, text]);
+    // a busy button ignores clicks; a hold-to-confirm one takes only the click its runtime sends once held
+    const busy = state === "loading";
+    const handleClick = busy ? blockClick
+        : hold ? (event) => (event.currentTarget.hasAttribute("data-sx-btn-held") ? onClick?.(event) : blockClick(event))
+            : onClick;
+    // ids for filters and gradients inside layers, unique per button and valid in url(#…)
+    const uid = `sx${useId().replace(/[^\w-]/g, "")}`;
+    const fills = layersIn(effects, "fill", uid, children);
+    const keepFill = effects.some((e) => e.layers.some((l) => l.slot === "fill" && l.keep));
+    const progressVar = progress === undefined ? {} : { "--sx-btn-progress": Math.min(1, Math.max(0, progress)) };
+    const vars = { ...withUid(Object.assign({}, ...effects.map((e) => e.vars)), uid), ...progressVar, ...style };
+    return (_jsxs(_Fragment, { children: [_jsx("style", { href: styleHref("btn-base", BUTTON_BASE_CSS), precedence: "sx", children: BUTTON_BASE_CSS }), effects.filter((e) => e.css).map((e) => {
+                const css = motionOnly(e.css);
+                return (_jsx("style", { href: styleHref(`btn-${e.id}`, css), precedence: "sx", children: css }, e.id));
+            }), effects.filter((e) => e.stateCss).map((e) => (_jsx("style", { href: styleHref(`btn-${e.id}-state`, e.stateCss), precedence: "sx", children: e.stateCss }, e.id))), _jsx(Hit, { ...(Hit === "button" ? { type: "button" } : {}), ...rest, ref: setRef, "data-sx-btn": effects.map((e) => e.id).join(" "), "data-sx-styled": unstyled ? undefined : "", "data-sx-variant": unstyled ? undefined : variant, "data-sx-btn-press": press ? undefined : "off", "data-sx-btn-state": state, "data-sx-btn-progress": progress === undefined ? undefined : "", "data-sx-btn-hold": hold ? "" : undefined, "aria-busy": busy || undefined, "aria-disabled": busy || rest["aria-disabled"] || undefined, onClick: handleClick, className: hitClassName, style: vars, children: _jsxs("span", { "data-sx-btn-body": "", children: [_jsxs("span", { "data-sx-btn-face": "", className: className, children: [layersIn(effects, "under", uid, children), fills.length > 0 ? (_jsx("span", { "data-sx-btn-clip": "", "data-sx-btn-keep": keepFill ? "" : undefined, "aria-hidden": true, children: fills })) : null, _jsx(Statuses, { plan: plan, labels: labels, uid: uid }), _jsx(Label, { plan: plan, text: text, icon: icon, iconPosition: iconPosition, uid: uid, children: children }), layersIn(effects, "edge", uid, children)] }), layersIn(effects, "body", uid, children)] }) }), state !== undefined ? (_jsx("span", { role: "status", "data-sx-btn-sr": "", children: state === "idle" ? "" : (labels?.[state] ?? "") })) : null] }));
+}

package/dist/buttons/base.d.ts

@@ -0,0 +1 @@
+export declare const BUTTON_BASE_CSS: string;

package/dist/buttons/base.js

@@ -0,0 +1,162 @@
+// The structural sheet every Button ships: the anatomy, the press, the focus ring, the reduced-motion and
+// off-screen switches. Positioning only, no colours of its own: the look is styles/button.css (or the consumer's
+// className). Pure string, so it works without theme.css. See ./CLAUDE.md.
+import { LAYER_ORDER } from "../backgrounds/runtime/rootCss.js";
+// The live region (`role="status"`) sits beside the button, often with no positioned parent. Absolute, it escaped a
+// table's scroll box and widened the docs page by 279px on a phone; a fixed box never adds to a page's scroll width.
+/**
+ * What shows in each status: its icon and words (`labels`) stack on the label in one grid cell, so the button is as
+ * wide as the widest of them and never jumps. A status comes before the label in the face, so it can hide the label.
+ */
+const SHOWN = ["loading", "success", "error"].map((s) => `[data-sx-btn-state="${s}"] [data-sx-btn-status="${s}"]`).join(", ");
+export const BUTTON_BASE_CSS = `${LAYER_ORDER}
+@layer components {
+  :where([data-sx-btn]) {
+    --sx-btn-dir: 1;
+    position: relative;
+    display: inline-grid;
+    grid-template-columns: minmax(0, 1fr);
+    padding: 0;
+    border: 0;
+    outline: none;
+    appearance: none;
+    background: none;
+    color: inherit;
+    font: inherit;
+    text-align: center;
+    text-decoration: none;
+    cursor: pointer;
+    touch-action: manipulation;
+    -webkit-tap-highlight-color: transparent;
+    transition: scale var(--sx-btn-pressScale-time, 80ms) ease-out;
+  }
+  :where([data-sx-btn]:dir(rtl)) {
+    --sx-btn-dir: -1;
+  }
+  :where([data-sx-btn]:not([data-sx-btn-press="off"], [aria-disabled="true"], :disabled):active) {
+    scale: var(--sx-btn-pressScale-scale, 0.97);
+  }
+  :where([data-sx-btn]:is([aria-disabled="true"], :disabled)) {
+    cursor: not-allowed;
+  }
+  :where([data-sx-btn][data-sx-btn-state="loading"]) {
+    cursor: progress;
+  }
+  :where([data-sx-btn-body]) {
+    display: grid;
+    position: relative;
+    isolation: isolate;
+    pointer-events: none;
+  }
+  :where([data-sx-btn-face]) {
+    position: relative;
+    display: grid;
+    place-items: center;
+    box-sizing: border-box;
+  }
+  :where([data-sx-btn]:focus-visible [data-sx-btn-face]) {
+    outline: 2px solid var(--color-sx-primary, currentColor);
+    outline-offset: 2px;
+  }
+  :where([data-sx-btn-label]) {
+    position: relative;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0.5em;
+  }
+  :where([data-sx-btn-text]:empty) {
+    display: none;
+  }
+  :where([data-sx-btn-sr]) {
+    position: absolute;
+    inline-size: 1px;
+    block-size: 1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
+  :where([role="status"][data-sx-btn-sr]) {
+    position: fixed;
+  }
+  :where([data-sx-btn-chars]) {
+    display: inline-flex;
+  }
+  :where([data-sx-btn-char]) {
+    display: inline-block;
+    white-space: pre;
+  }
+  :where([data-sx-btn-alt]) {
+    display: none;
+  }
+  :where([data-sx-btn-icon]) {
+    display: inline-grid;
+    place-items: center;
+  }
+  :where([data-sx-btn-icon] > svg) {
+    display: block;
+    inline-size: 1.15em;
+    block-size: 1.15em;
+  }
+  :where([data-sx-btn-face] > :is([data-sx-btn-label], [data-sx-btn-status])) {
+    grid-area: 1 / 1;
+  }
+  :where([data-sx-btn-status]) {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0.5em;
+    visibility: hidden;
+  }
+  :where([data-sx-btn-status] > svg) {
+    display: block;
+    inline-size: 1.15em;
+    block-size: 1.15em;
+  }
+  :where(${SHOWN}) {
+    visibility: visible;
+  }
+  :where(${SHOWN.split(", ").map((s) => `${s} ~ [data-sx-btn-label]`).join(", ")}) {
+    visibility: hidden;
+  }
+  :where([data-sx-btn-clip]) {
+    position: absolute;
+    inset: calc(var(--sx-btn-bw, 0px) * -1);
+    overflow: hidden;
+    border-radius: inherit;
+    container-type: size;
+  }
+  :where([data-sx-btn-layer]) {
+    position: absolute;
+    inset: 0;
+    border-radius: inherit;
+  }
+  :where([data-sx-btn-clip] > [data-sx-btn-layer]) {
+    border-radius: 0;
+  }
+  :where([data-sx-btn-layer]:is([data-sx-btn-slot="under"], [data-sx-btn-slot="edge"])) {
+    inset: calc(var(--sx-btn-bw, 0px) * -1);
+  }
+  :where([data-sx-btn-layer][data-sx-btn-slot="under"]) {
+    z-index: -1;
+  }
+  :where([data-sx-btn-layer] > svg) {
+    position: absolute;
+    inset: 0;
+    display: block;
+    inline-size: 100%;
+    block-size: 100%;
+    overflow: visible;
+  }
+  :where([data-sx-btn-off] *) {
+    animation-play-state: paused !important;
+  }
+  @media (prefers-reduced-motion: reduce) {
+    :where([data-sx-btn]) {
+      transition: none;
+    }
+    :where([data-sx-btn-clip]:not([data-sx-btn-keep]), [data-sx-btn-layer]:not([data-sx-btn-keep])) {
+      display: none;
+    }
+  }
+}`;