@sharedex/ui 0.0.0-stage → 0.9.0

package/dist/buttons/effects/state/stateRing.js

@@ -0,0 +1,32 @@
+import { EASE, at, defineButton, hitOf, inState, statusOf, v, varName } from "../kit.js";
+import { CHECK, RING } from "./icons.js";
+const ID = "stateRing";
+const ARC = `${statusOf(ID, "loading")} [data-sx-btn-svg="ring"]`;
+const UNKNOWN = `${hitOf(ID)}[data-sx-btn-state="loading"]:not([data-sx-btn-progress]) [data-sx-btn-status="loading"] > svg`;
+const CHECKED = `${statusOf(ID, "success")} [data-sx-btn-svg="check"]`;
+// Poses: the arc is as long as the progress, from the top. With no number it is a quarter, which the motion turns.
+const STATE = `  ${at(ARC)} {
+    stroke-dasharray: 1 1;
+    stroke-dashoffset: calc(1 - var(--sx-btn-progress, 0.25));
+    rotate: -90deg;
+    transform-box: fill-box;
+    transform-origin: center;
+  }`;
+const CSS = `  ${at(ARC)} { transition: stroke-dashoffset ${v(ID, "time")} ${EASE}; }
+  ${at(UNKNOWN)} { animation: sx-btn-stateRing-spin 0.9s linear infinite; }
+  ${at(CHECKED)} { stroke-dasharray: 1 1; }
+  ${at(inState(ID, "success", CHECKED))} { animation: sx-btn-stateRing-draw 0.3s ease-out backwards; }
+  @keyframes sx-btn-stateRing-spin {
+    to { rotate: 1turn; }
+  }
+  @keyframes sx-btn-stateRing-draw {
+    from { stroke-dashoffset: 1; }
+  }`;
+/** A ring fills up in place of the label as the work goes on, then turns into a check mark. Words from `labels` sit beside it. */
+export function stateRing(options = {}) {
+    return defineButton(ID, CSS, {
+        vars: { [varName(ID, "time")]: `${options.duration ?? 0.3}s` },
+        label: { status: { loading: RING, success: CHECK } },
+        state: STATE,
+    });
+}

package/dist/buttons/effects/state/stateRing.schema.d.ts

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

package/dist/buttons/effects/state/stateRing.schema.js

@@ -0,0 +1,9 @@
+import { defineSchema } from "../../../schema/define.js";
+export const STATE_RING_SCHEMA = defineSchema()({
+    id: "stateRing",
+    family: "button",
+    factory: "stateRing",
+    fields: {
+        duration: { kind: "number", label: "Duration", min: 0.1, max: 0.8, step: 0.05, unit: "s", default: 0.3 },
+    },
+});

package/dist/buttons/effects/state/stateSpinner.d.ts

@@ -0,0 +1,7 @@
+import type { ButtonEffect } from "../../types.js";
+export interface StateSpinnerOptions {
+    /** Seconds per turn. Default `0.8`. */
+    readonly duration?: number;
+}
+/** A spinner takes the label's place while the button is loading. The button keeps its width. */
+export declare function stateSpinner(options?: StateSpinnerOptions): ButtonEffect;

package/dist/buttons/effects/state/stateSpinner.js

@@ -0,0 +1,17 @@
+import { at, defineButton, inState, statusOf, v, varName } from "../kit.js";
+import { SPINNER } from "./icons.js";
+const ID = "stateSpinner";
+// the swap itself is the base sheet's: the spinner stands in the label's grid cell, so the width stays
+const CSS = `  ${at(inState(ID, "loading", `${statusOf(ID, "loading")} > svg`))} {
+    animation: sx-btn-stateSpinner ${v(ID, "time")} linear infinite;
+  }
+  @keyframes sx-btn-stateSpinner {
+    to { rotate: 1turn; }
+  }`;
+/** A spinner takes the label's place while the button is loading. The button keeps its width. */
+export function stateSpinner(options = {}) {
+    return defineButton(ID, CSS, {
+        vars: { [varName(ID, "time")]: `${options.duration ?? 0.8}s` },
+        label: { status: { loading: SPINNER } },
+    });
+}

package/dist/buttons/effects/state/stateSpinner.schema.d.ts

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

package/dist/buttons/effects/state/stateSpinner.schema.js

@@ -0,0 +1,9 @@
+import { defineSchema } from "../../../schema/define.js";
+export const STATE_SPINNER_SCHEMA = defineSchema()({
+    id: "stateSpinner",
+    family: "button",
+    factory: "stateSpinner",
+    fields: {
+        duration: { kind: "number", label: "Seconds per turn", min: 0.4, max: 2, step: 0.1, unit: "s", default: 0.8 },
+    },
+});

package/dist/buttons/effects/state/stateSwap.d.ts

@@ -0,0 +1,10 @@
+import { type ButtonEffect } from "../../types.js";
+export interface StateSwapOptions {
+    /** Seconds each change takes. Default `0.3`. */
+    readonly duration?: number;
+}
+/**
+ * Loading, done and failed each slide in with their own icon: a spinner, a check mark, a cross. Your words come from
+ * `labels`; with `useButtonAction(…, { resetAfter: false })` the done state stays ("Subscribe" to "Subscribed").
+ */
+export declare function stateSwap(options?: StateSwapOptions): ButtonEffect;

package/dist/buttons/effects/state/stateSwap.js

@@ -0,0 +1,29 @@
+import { BUTTON_STATUSES } from "../../types.js";
+import { EASE, at, defineButton, inState, labelOf, statusOf, v, varName } from "../kit.js";
+import { CHECK, CROSS, SPINNER } from "./icons.js";
+import { drawMarks } from "./kit.js";
+const ID = "stateSwap";
+const T = v(ID, "time");
+// The base sheet already swaps what shows (at once, under reduced motion). This adds the motion: the old words rise
+// and fade, the new ones come up from below. `visibility` waits for the fade before it hides anything.
+const CSS = `  ${at(`${labelOf(ID)}, ${statusOf(ID)}`)} {
+    transition: translate ${T} ${EASE}, opacity ${T} ${EASE}, visibility ${T};
+  }
+  ${at(statusOf(ID))} {
+    translate: 0 0.6em;
+    opacity: 0;
+  }
+${BUTTON_STATUSES.map((s) => `  ${at(inState(ID, s, statusOf(ID, s)))} { translate: 0 0; opacity: 1; }
+  ${at(inState(ID, s, `${statusOf(ID, s)} ~ [data-sx-btn-label]`))} { translate: 0 -0.6em; opacity: 0; }`).join("\n")}
+${drawMarks(ID)}`;
+/**
+ * Loading, done and failed each slide in with their own icon: a spinner, a check mark, a cross. Your words come from
+ * `labels`; with `useButtonAction(…, { resetAfter: false })` the done state stays ("Subscribe" to "Subscribed").
+ */
+export function stateSwap(options = {}) {
+    return defineButton(ID, CSS, {
+        vars: { [varName(ID, "time")]: `${options.duration ?? 0.3}s` },
+        label: { status: { loading: SPINNER, success: CHECK, error: CROSS } },
+        claims: ["label"],
+    });
+}

package/dist/buttons/effects/state/stateSwap.schema.d.ts

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

package/dist/buttons/effects/state/stateSwap.schema.js

@@ -0,0 +1,9 @@
+import { defineSchema } from "../../../schema/define.js";
+export const STATE_SWAP_SCHEMA = defineSchema()({
+    id: "stateSwap",
+    family: "button",
+    factory: "stateSwap",
+    fields: {
+        duration: { kind: "number", label: "Duration", min: 0.15, max: 0.8, step: 0.05, unit: "s", default: 0.3 },
+    },
+});

package/dist/buttons/pick.d.ts

@@ -0,0 +1,5 @@
+import type { ButtonEffect } from "./types.js";
+/** What a device can carry, as the backgrounds and transitions guess it. */
+export type ButtonDevice = "low" | "mid" | "high";
+/** The first link in the fallback chain this device runs; the last link when none does (it is always `all`). */
+export declare function pickEffect(effect: ButtonEffect, device: ButtonDevice): ButtonEffect;

package/dist/buttons/pick.js

@@ -0,0 +1,16 @@
+// Which effect a device wears: the effect, or the first fallback its tier allows. Pure; tested. Its own ranks rather
+// than backgrounds/runtime/tier.ts, so a plain button doesn't download the device check.
+const DEVICE = { low: 0, mid: 1, high: 2 };
+const NEEDS = { all: 0, mid: 1, high: 2 };
+/** The first link in the fallback chain this device runs; the last link when none does (it is always `all`). */
+export function pickEffect(effect, device) {
+    let link = effect;
+    let last = effect;
+    while (link) {
+        if (DEVICE[device] >= NEEDS[link.tier])
+            return link;
+        last = link;
+        link = link.fallback;
+    }
+    return last;
+}

package/dist/buttons/registry.d.ts

@@ -0,0 +1,4 @@
+import type { ButtonMeta } from "./types.js";
+export declare const BUTTON_EFFECTS: readonly ButtonMeta[];
+export declare const BUTTON_IDS: ReadonlySet<string>;
+export declare function metaOf(id: string): ButtonMeta;

package/dist/buttons/registry.js

@@ -0,0 +1,91 @@
+// ---------------------------------------------------------------------------
+// Every button effect's metadata, from the Button Effects Atlas. The docs and the
+// schemas read it. Factories live in the barrel; this file imports none of them.
+// Keep it in step with test/fixtures/buttons-atlas.mjs.
+// ---------------------------------------------------------------------------
+function row(id, label, group, fires, tech, description, extra = {}) {
+    const touch = !extra.desktop && fires.some((f) => f !== "hover");
+    return { id, label, group, fires, tech, tier: extra.tier ?? "all", touch, description };
+}
+export const BUTTON_EFFECTS = [
+    row("fillFade", "Color fade", "fill", ["hover"], "css", "A second colour fades in over the button."),
+    row("fillSweep", "Sweep fill", "fill", ["hover"], "css", "A colour slides in from one edge."),
+    row("fillRadial", "Radial fill", "fill", ["hover"], "css", "A circle grows from the centre, or closes in from the edges."),
+    row("fillShutter", "Shutter fill", "fill", ["hover"], "css", "Two halves meet in the middle, or a box closes in."),
+    row("fillSlash", "Diagonal slash", "fill", ["hover"], "css", "A slanted block slides across."),
+    row("fillDirectional", "Direction-aware fill", "fill", ["hover"], "js", "The colour comes in by the edge the pointer came through.", { desktop: true }),
+    row("fillSpotlight", "Cursor spotlight", "fill", ["hover"], "js", "A soft light follows the pointer inside the button.", { desktop: true }),
+    row("fillGradient", "Gradient shift", "fill", ["hover", "idle"], "css", "A long gradient drifts sideways, on hover or all the time."),
+    row("fillWave", "Liquid wave", "fill", ["hover"], "svg", "The button fills up with water from below."),
+    row("fillGoo", "Gooey blob fill", "fill", ["hover"], "svg", "Blobs rise and melt into each other until they fill the button.", { tier: "mid" }),
+    row("borderUnderline", "Underline grow", "border", ["hover"], "css", "A line grows along the bottom edge."),
+    row("borderDraw", "Border draw-around", "border", ["hover"], "svg", "The outline draws itself around the button."),
+    row("borderOutline", "Outline", "border", ["hover"], "css", "A second outline moves out, ripples away or sits inside the edge."),
+    row("borderRound", "Round corners", "border", ["hover"], "css", "The corners round off into a pill."),
+    row("borderConic", "Rotating gradient border", "border", ["hover", "idle"], "css", "A gradient ring turns around the button."),
+    row("borderRunner", "Moving border", "border", ["idle"], "css", "A bright dot travels along the edge."),
+    row("borderSpread", "Hover border gradient", "border", ["hover"], "css", "An arc of gradient on the top edge spreads around the button."),
+    row("borderBeam", "Border beam", "border", ["idle"], "css", "A beam of light with a tail circles the edge."),
+    row("borderStar", "Star border", "border", ["idle"], "css", "Two soft lights glide along the top and bottom edges."),
+    row("borderElectric", "Electric border", "border", ["idle"], "svg", "The edge crackles like a live wire.", { tier: "mid" }),
+    row("borderAnts", "Marching ants", "border", ["idle"], "svg", "A dashed line marches around the edge."),
+    row("glowHover", "Glow on hover", "glow", ["hover"], "css", "A soft glow fades in around the button."),
+    row("glowLift", "Lift with shadow", "glow", ["hover"], "css", "The button rises and a shadow fades in under it."),
+    row("glowShine", "Shine sweep", "glow", ["hover", "idle"], "css", "A diagonal light crosses the button."),
+    row("glowShimmer", "Shimmer", "glow", ["idle"], "css", "A spark of light circles just inside the edge."),
+    row("glowRainbow", "Rainbow", "glow", ["idle"], "css", "A rainbow drifts around the edge, with a blurred copy below."),
+    row("glowShiny", "Shiny", "glow", ["hover", "idle"], "css", "A broad, soft sheen slides across the button."),
+    row("glowGlare", "Glare", "glow", ["hover"], "css", "A metallic highlight passes over the button."),
+    row("glowNeon", "Neon", "glow", ["hover", "idle"], "css", "The button lights up like a neon tube, with the odd flicker."),
+    row("glowAura", "Blurred aura", "glow", ["hover", "idle"], "css", "A soft cloud of colour sits behind the button."),
+    row("depthPushable", "3D pushable", "depth", ["hover", "press"], "css", "A 3D block: the front rises on hover and sinks under a press."),
+    row("pressScale", "Press scale", "depth", ["press"], "css", "The button shrinks a little under a click or a tap. On by default."),
+    row("depthGrow", "Grow / shrink / pop", "depth", ["hover"], "css", "The button changes size, bumps once or beats."),
+    row("depthFloat", "Float / sink / bob / hang", "depth", ["hover"], "css", "The button rises or drops; bob and hang keep moving."),
+    row("depthJiggle", "Skew / wobble / buzz", "depth", ["hover"], "css", "The button leans, rocks or trembles."),
+    row("depthTilt", "3D tilt toward cursor", "depth", ["hover"], "js", "The button leans towards the pointer in 3D.", { desktop: true }),
+    row("depthFlip", "Flip", "depth", ["hover"], "css", "The button flips over; the back can say something else."),
+    row("depthCube", "Cube-roll label", "depth", ["hover"], "css", "The label rolls a quarter turn on a 3D box."),
+    row("depthNeumorph", "Neumorphic press", "depth", ["press"], "css", "Soft shadows lift the button out of its surface; a press sinks it."),
+    row("cursorMagnet", "Magnetic", "cursor", ["hover"], "js", "The button leans towards the pointer and springs back.", { desktop: true }),
+    row("cursorBlob", "Cursor-follow blob", "cursor", ["hover"], "js", "A soft circle inside the button follows the pointer.", { desktop: true }),
+    row("labelRoll", "Text roll", "label", ["hover"], "css", "Each letter slides up and a copy slides in after it."),
+    row("labelSwap", "Text swap", "label", ["hover"], "css", "One label slides out and another slides in."),
+    row("labelFall", "Text fall", "label", ["hover"], "css", "The letters drop out one after another and come back."),
+    row("labelScramble", "Text scramble", "label", ["hover"], "js", "Random characters settle into the word."),
+    row("labelShiny", "Shiny text", "label", ["idle"], "css", "A light keeps passing through the label's text."),
+    row("iconNudge", "Arrow nudge", "label", ["hover"], "css", "The icon moves a few pixels forward."),
+    row("iconReveal", "Icon reveal", "label", ["hover"], "css", "The text fades and the icon rises through a gap in the border."),
+    row("iconExpand", "Expand to show label", "label", ["hover"], "css", "An icon-only button grows to show its label."),
+    row("iconMorph", "Icon morph", "label", ["press"], "svg", "The icon changes shape with the button's pressed state."),
+    row("pressRipple", "Ripple", "press", ["press"], "js", "A circle spreads from where you pressed."),
+    row("pressSpark", "Click spark", "press", ["press"], "canvas", "Short lines flick out from the click."),
+    row("pressBurst", "Particle burst", "press", ["press"], "canvas", "Dots burst out from the click and fall away."),
+    row("pressConfetti", "Confetti", "press", ["press"], "canvas", "Confetti shoots up from the click and flutters down."),
+    row("pressSpray", "Cool mode", "press", ["press"], "canvas", "Particles spray out for as long as the button is held."),
+    row("pressJelly", "Jelly", "press", ["press"], "js", "After a click the button squashes and wobbles back."),
+    row("stateShake", "Shake on error", "press", ["state"], "css", "The button shakes when its action fails."),
+    row("stateSpinner", "Spinner inside", "state", ["state"], "css", "A spinner takes the label's place while it loads."),
+    row("stateSwap", "Stateful button", "state", ["state"], "css", "Loading, done and failed slide in, each with its icon and words."),
+    row("stateMorph", "Morph to circle", "state", ["state"], "css", "The button closes to a circle while it loads, then shows a check mark."),
+    row("stateProgress", "Progress fill", "state", ["state"], "css", "A bar fills the button as the work goes on."),
+    row("stateRing", "Circular progress", "state", ["state"], "svg", "A ring fills up in place of the label."),
+    row("stateHold", "Hold to confirm", "state", ["press"], "js", "Hold until the button fills: only then does it act."),
+    row("stateCopy", "Copy → copied", "state", ["state"], "css", "A copy icon turns into a check mark once copied."),
+    row("idlePing", "Pulse ring", "idle", ["idle"], "css", "A ring keeps pulsing out from the edge."),
+    row("idleBreathe", "Breathing glow", "idle", ["idle"], "css", "A soft glow behind the button slowly swells and fades."),
+    row("idleWiggle", "Periodic wiggle", "idle", ["idle"], "css", "Every few seconds the button gives a short wiggle."),
+    row("idleGrain", "Noise / grain", "idle", ["idle"], "css", "Fine film grain flickers over the button."),
+    row("glassBlur", "Glassmorphism", "glass", ["hover"], "css", "Frosted glass: the button blurs and tints what lies behind it."),
+    row("glassLiquid", "Liquid glass", "glass", ["hover", "idle"], "svg", "Glass that bends what lies behind it (Chromium); frosted glass elsewhere.", { tier: "mid" }),
+    row("glassNative", "Native glass material", "glass", ["hover"], "css", "Apple's system glass where WebKit offers it, a close copy elsewhere."),
+    row("glassRefract", "WebGL refraction glass", "glass", ["hover", "idle"], "webgl", "A picture or the theme's colours, bent through a glass lens.", { tier: "high" }),
+    row("glassDistort", "Distorted button", "glass", ["hover"], "svg", "The button warps as if seen through moving water.", { tier: "mid" }),
+];
+export const BUTTON_IDS = new Set(BUTTON_EFFECTS.map((m) => m.id));
+export function metaOf(id) {
+    const meta = BUTTON_EFFECTS.find((m) => m.id === id);
+    if (!meta)
+        throw new Error(`[@sharedex/ui] unknown button effect "${id}"`);
+    return meta;
+}

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

@@ -0,0 +1,2 @@
+/** Returns what stops it. No `pointermove` listener exists until the pointer is over this button. */
+export declare function attachPointer(el: HTMLElement): () => void;

package/dist/buttons/runtime/attachPointer.js

@@ -0,0 +1,59 @@
+// Follows the pointer over one button and writes where it is as custom properties, at most once per frame. A chunk of
+// its own (useButtonPointer imports it when needed), so a button with no cursor effect doesn't download it, and neither
+// does a touch screen.
+//
+// On the way in it also places fills on the side the pointer came from: `data-sx-btn-jump` stops their transition for
+// one style pass (hover has already moved them on, so the jump rule has to win that pass), then they slide in. On the
+// way out they wait on the side it left by, so they slide out there.
+import { nearestSide, pointerVars, sideOffset } from "./pointer.js";
+/** Returns what stops it. No `pointermove` listener exists until the pointer is over this button. */
+export function attachPointer(el) {
+    let rect;
+    let frame = 0;
+    let last;
+    const at = (e, box) => [e.clientX - box.left, e.clientY - box.top];
+    const writeSide = (e, box) => {
+        const [x, y] = at(e, box);
+        const [sx, sy] = sideOffset(nearestSide(x, y, box.width, box.height));
+        el.style.setProperty("--sx-btn-sx", String(sx));
+        el.style.setProperty("--sx-btn-sy", String(sy));
+    };
+    const write = () => {
+        frame = 0;
+        if (!last || !rect)
+            return;
+        const [x, y] = at(last, rect);
+        for (const [name, value] of Object.entries(pointerVars(x, y, rect.width, rect.height)))
+            el.style.setProperty(name, value);
+    };
+    const onMove = (e) => {
+        last = e;
+        if (!frame)
+            frame = requestAnimationFrame(write);
+    };
+    const onEnter = (e) => {
+        rect = el.getBoundingClientRect();
+        last = e;
+        write();
+        writeSide(e, rect);
+        el.setAttribute("data-sx-btn-jump", "");
+        void el.offsetHeight; // apply the jump before it ends
+        el.removeAttribute("data-sx-btn-jump");
+        el.addEventListener("pointermove", onMove, { passive: true });
+    };
+    const onLeave = (e) => {
+        el.removeEventListener("pointermove", onMove);
+        cancelAnimationFrame(frame);
+        frame = 0;
+        if (rect)
+            writeSide(e, rect);
+    };
+    el.addEventListener("pointerenter", onEnter);
+    el.addEventListener("pointerleave", onLeave);
+    return () => {
+        cancelAnimationFrame(frame);
+        el.removeEventListener("pointerenter", onEnter);
+        el.removeEventListener("pointerleave", onLeave);
+        el.removeEventListener("pointermove", onMove);
+    };
+}

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

@@ -0,0 +1,4 @@
+export declare function attachPress(el: HTMLElement, needs: {
+    readonly tap: boolean;
+    readonly hold: number | undefined;
+}): () => void;

package/dist/buttons/runtime/attachPress.js

@@ -0,0 +1,94 @@
+// The press runtime: ripples, the tap that restarts a one-shot animation, and hold to confirm. Loaded by
+// useButtonPress only when an effect needs it, so a plain button downloads none of it.
+import { pressCounts, pressKey, rippleRadius, stillMotion } from "./press.js";
+/** At most this many ripples at once: a fast clicker gets the newest ones. */
+const RIPPLES = 3;
+export function attachPress(el, needs) {
+    const off = [];
+    const on = (type, fn) => {
+        el.addEventListener(type, fn);
+        off.push(() => el.removeEventListener(type, fn));
+    };
+    const enabled = () => !el.matches('[aria-disabled="true"], :disabled');
+    if (needs.tap) {
+        // a ripple from (x, y) in viewport pixels, or from the centre for a key
+        const ripple = (x, y) => {
+            const layer = el.querySelector('[data-sx-btn-layer][data-sx-btn-part="ripples"]');
+            if (!layer || stillMotion())
+                return;
+            const box = layer.getBoundingClientRect();
+            const px = x === undefined ? box.width / 2 : x - box.left;
+            const py = y === undefined ? box.height / 2 : y - box.top;
+            const dot = document.createElement("span");
+            dot.setAttribute("data-sx-btn-ripple", "");
+            dot.style.setProperty("--sx-btn-tap-x", `${px}px`);
+            dot.style.setProperty("--sx-btn-tap-y", `${py}px`);
+            dot.style.setProperty("--sx-btn-tap-r", `${rippleRadius(px, py, box.width, box.height)}px`);
+            // React renders the layer empty and never touches its children, so these spans are ours alone
+            layer.appendChild(dot);
+            while (layer.childElementCount > RIPPLES)
+                layer.firstElementChild?.remove();
+            const done = () => dot.remove();
+            dot.addEventListener("animationend", done, { once: true });
+            setTimeout(done, 3000); // a hidden tab never ends the animation
+        };
+        on("pointerdown", (e) => {
+            if (e.button === 0 && enabled())
+                ripple(e.clientX, e.clientY);
+        });
+        on("keydown", (e) => {
+            if (!e.repeat && pressKey(e) && enabled())
+                ripple();
+        });
+        // a click restarts what plays once after it (`pressJelly`): off, one forced style pass, on again
+        on("click", () => {
+            if (!pressCounts(el))
+                return;
+            el.removeAttribute("data-sx-btn-tap");
+            void el.offsetWidth;
+            el.setAttribute("data-sx-btn-tap", "");
+        });
+    }
+    if (needs.hold !== undefined) {
+        const ms = needs.hold * 1000;
+        let timer = 0;
+        const start = () => {
+            if (el.hasAttribute("data-sx-btn-holding") || !enabled())
+                return;
+            el.setAttribute("data-sx-btn-holding", "");
+            timer = window.setTimeout(() => {
+                // Button lets this one click through to onClick, and only while held
+                el.setAttribute("data-sx-btn-held", "");
+                el.click();
+            }, ms);
+        };
+        const cancel = () => {
+            clearTimeout(timer);
+            el.removeAttribute("data-sx-btn-holding");
+            el.removeAttribute("data-sx-btn-held");
+        };
+        on("pointerdown", (e) => {
+            if (e.button === 0)
+                start();
+        });
+        on("pointerup", cancel);
+        on("pointerleave", cancel);
+        on("pointercancel", cancel);
+        on("keydown", (e) => {
+            if (!e.repeat && pressKey(e))
+                start();
+        });
+        on("keyup", (e) => {
+            if (pressKey(e))
+                cancel();
+        });
+        on("blur", cancel);
+        // a long press on a phone opens a menu over the button
+        on("contextmenu", (e) => {
+            if (el.hasAttribute("data-sx-btn-holding"))
+                e.preventDefault();
+        });
+        off.push(cancel);
+    }
+    return () => off.forEach((stop) => stop());
+}

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

@@ -0,0 +1,3 @@
+import { type ParticleKind, type SpawnOptions } from "./particles.js";
+/** Throws `count` particles of `kind` from (x, y) in viewport pixels, within the caps. Returns how many it threw. */
+export declare function emit(kind: ParticleKind, x: number, y: number, count: number, o: SpawnOptions): number;

package/dist/buttons/runtime/burst.js

@@ -0,0 +1,76 @@
+// The one canvas every button's particles share: fixed over the page, made by the first burst and removed when the
+// last particle is gone, so a page with no burst in the air has no canvas and no frame loop. Only the particle
+// effects import it.
+import { admit, drawParticle, stepParticle } from "./particles.js";
+let canvas = null;
+let ctx = null;
+let live = [];
+let frame = 0;
+let last = 0;
+/** The canvas sized to the viewport, sharp on a dense screen (capped at 2×: particles don't need more). */
+function fit() {
+    if (!canvas || !ctx)
+        return;
+    const dpr = Math.min(window.devicePixelRatio || 1, 2);
+    const w = Math.round(window.innerWidth * dpr);
+    const h = Math.round(window.innerHeight * dpr);
+    if (canvas.width !== w || canvas.height !== h) {
+        canvas.width = w;
+        canvas.height = h;
+    }
+    ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+}
+function open() {
+    if (ctx)
+        return ctx;
+    canvas = document.createElement("canvas");
+    canvas.setAttribute("aria-hidden", "true");
+    canvas.setAttribute("data-sx-btn-burst", "");
+    Object.assign(canvas.style, { position: "fixed", inset: "0", width: "100%", height: "100%", pointerEvents: "none", zIndex: "2147483647" });
+    ctx = canvas.getContext("2d");
+    if (!ctx) {
+        canvas = null;
+        return null;
+    }
+    document.body.appendChild(canvas);
+    fit();
+    return ctx;
+}
+function close() {
+    frame = 0;
+    canvas?.remove();
+    canvas = null;
+    ctx = null;
+}
+function tick(now) {
+    if (!ctx)
+        return;
+    const dt = Math.min(0.05, (now - last) / 1000); // a tab coming back doesn't jump the particles
+    last = now;
+    fit();
+    ctx.clearRect(0, 0, window.innerWidth, window.innerHeight);
+    live = live.filter(({ p, kind }) => {
+        const on = stepParticle(p, kind, dt);
+        if (on)
+            drawParticle(ctx, p);
+        return on;
+    });
+    ctx.globalAlpha = 1;
+    if (live.length > 0)
+        frame = requestAnimationFrame(tick);
+    else
+        close();
+}
+/** Throws `count` particles of `kind` from (x, y) in viewport pixels, within the caps. Returns how many it threw. */
+export function emit(kind, x, y, count, o) {
+    const n = admit(live.length, count);
+    if (n === 0 || o.colors.length === 0 || !open())
+        return 0;
+    for (let i = 0; i < n; i++)
+        live.push({ p: kind.spawn(x, y, i, n, Math.random, o), kind });
+    if (!frame) {
+        last = performance.now();
+        frame = requestAnimationFrame(tick);
+    }
+    return n;
+}

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

@@ -0,0 +1,2 @@
+/** Once per message, and only in development. */
+export declare function warnOnce(message: string): void;

package/dist/buttons/runtime/dev.js

@@ -0,0 +1,8 @@
+const seen = new Set();
+/** Once per message, and only in development. */
+export function warnOnce(message) {
+    if (process.env.NODE_ENV === "production" || seen.has(message))
+        return;
+    seen.add(message);
+    console.warn(`[@sharedex/ui] ${message}`);
+}

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

@@ -0,0 +1,55 @@
+export type ParticleShape = "line" | "dot" | "rect" | "text";
+export interface Particle {
+    x: number;
+    y: number;
+    /** px per second. */
+    vx: number;
+    vy: number;
+    /** Seconds lived, and seconds it lives. */
+    age: number;
+    life: number;
+    /** px: a line's length, a dot's or a piece's width, a character's size. */
+    size: number;
+    /** Radians, and radians per second. */
+    spin: number;
+    turn: number;
+    color: string;
+    shape: ParticleShape;
+    text?: string;
+}
+/** What a burst is made of: canvas colours (resolved), a size and a life in seconds, characters for `text`. */
+export interface SpawnOptions {
+    readonly colors: readonly string[];
+    readonly size: number;
+    readonly life: number;
+    /** Characters to throw instead of dots (`pressSpray`). */
+    readonly text?: readonly string[];
+    /** Radians either side of straight up (`pressConfetti`, `pressSpray`). */
+    readonly spread?: number;
+}
+export interface ParticleKind {
+    /** px per second², downwards. */
+    readonly gravity: number;
+    /** How fast it slows: speed is multiplied by e^(-drag · seconds). */
+    readonly drag: number;
+    /** Particle `i` of `n` thrown from (x, y). */
+    spawn(x: number, y: number, i: number, n: number, random: () => number, o: SpawnOptions): Particle;
+}
+/** One burst throws at most this many. */
+export declare const PER_BURST = 30;
+/** And the page holds at most this many at once, so a fast clicker can't fill it. */
+export declare const MAX_LIVE = 120;
+/** How many of `wanted` may be thrown while `live` are in the air. */
+export declare function admit(live: number, wanted: number): number;
+/** Short lines flicked out evenly all round, quickly slowing. */
+export declare const SPARK: ParticleKind;
+/** Dots out in every direction, falling a little. */
+export declare const BURST: ParticleKind;
+/** Paper pieces shot upwards that turn as they fall. */
+export declare const CONFETTI: ParticleKind;
+/** A fountain upwards: dots, or the characters you give it. */
+export declare const SPRAY: ParticleKind;
+/** Moves it on by `dt` seconds. False once it has lived its life. */
+export declare function stepParticle(p: Particle, kind: ParticleKind, dt: number): boolean;
+/** Draws it, fading out over its life. */
+export declare function drawParticle(ctx: CanvasRenderingContext2D, p: Particle): void;