@sharedex/ui 0.0.0-stage → 0.10.0

package/dist/buttons/runtime/particles.js

@@ -0,0 +1,98 @@
+// Particles for the press effects: how each kind starts, how it moves, how it's drawn. Pure apart from `drawParticle`,
+// which only needs a 2D context; tested. Only the four particle effects import it.
+/** One burst throws at most this many. */
+export const PER_BURST = 30;
+/** And the page holds at most this many at once, so a fast clicker can't fill it. */
+export const MAX_LIVE = 120;
+/** How many of `wanted` may be thrown while `live` are in the air. */
+export function admit(live, wanted) {
+    return Math.max(0, Math.min(Math.floor(wanted), PER_BURST, MAX_LIVE - live));
+}
+const TAU = Math.PI * 2;
+const UP = -Math.PI / 2;
+const pick = (list, random) => list[Math.floor(random() * list.length)] ?? list[0];
+function particle(x, y, angle, speed, o, random, extra) {
+    return {
+        x, y, vx: Math.cos(angle) * speed, vy: Math.sin(angle) * speed,
+        age: 0, life: o.life, size: o.size, spin: 0, turn: 0, color: pick(o.colors, random), shape: "dot", ...extra,
+    };
+}
+/** Short lines flicked out evenly all round, quickly slowing. */
+export const SPARK = {
+    gravity: 0,
+    drag: 5,
+    spawn: (x, y, i, n, r, o) => particle(x, y, (i / n) * TAU + r() * 0.3, 260, o, r, { shape: "line" }),
+};
+/** Dots out in every direction, falling a little. */
+export const BURST = {
+    gravity: 320,
+    drag: 2.2,
+    spawn: (x, y, _i, _n, r, o) => particle(x, y, r() * TAU, 140 + r() * 240, o, r, { life: o.life * (0.7 + 0.3 * r()), size: o.size * (0.5 + r()) }),
+};
+/** Paper pieces shot upwards that turn as they fall. */
+export const CONFETTI = {
+    gravity: 900,
+    drag: 1.4,
+    spawn: (x, y, _i, _n, r, o) => particle(x, y, UP + (r() - 0.5) * 2 * (o.spread ?? 1.2), 480 + r() * 380, o, r, {
+        life: o.life * (0.75 + 0.25 * r()), size: o.size * (0.7 + 0.6 * r()), shape: "rect", spin: r() * TAU, turn: (r() - 0.5) * 16,
+    }),
+};
+/** A fountain upwards: dots, or the characters you give it. */
+export const SPRAY = {
+    gravity: 820,
+    drag: 0.8,
+    spawn: (x, y, _i, _n, r, o) => particle(x, y, UP + (r() - 0.5) * 2 * (o.spread ?? 0.6), 260 + r() * 240, o, r, {
+        life: o.life * (0.8 + 0.4 * r()), size: o.size * (0.7 + 0.6 * r()),
+        ...(o.text && o.text.length > 0 ? { shape: "text", text: pick(o.text, r) } : {}),
+    }),
+};
+/** Moves it on by `dt` seconds. False once it has lived its life. */
+export function stepParticle(p, kind, dt) {
+    const keep = Math.exp(-kind.drag * dt);
+    p.vx *= keep;
+    p.vy = p.vy * keep + kind.gravity * dt;
+    p.x += p.vx * dt;
+    p.y += p.vy * dt;
+    p.spin += p.turn * dt;
+    p.age += dt;
+    return p.age < p.life;
+}
+/** Draws it, fading out over its life. */
+export function drawParticle(ctx, p) {
+    const t = Math.min(1, p.age / p.life);
+    ctx.globalAlpha = 1 - t * t;
+    ctx.fillStyle = p.color;
+    ctx.strokeStyle = p.color;
+    switch (p.shape) {
+        case "line": {
+            const speed = Math.hypot(p.vx, p.vy) || 1;
+            const length = p.size * (1 - t);
+            ctx.lineWidth = 2;
+            ctx.lineCap = "round";
+            ctx.beginPath();
+            ctx.moveTo(p.x, p.y);
+            ctx.lineTo(p.x - (p.vx / speed) * length, p.y - (p.vy / speed) * length);
+            ctx.stroke();
+            break;
+        }
+        case "dot":
+            ctx.beginPath();
+            ctx.arc(p.x, p.y, Math.max(0.5, (p.size / 2) * (1 - 0.5 * t)), 0, TAU);
+            ctx.fill();
+            break;
+        case "rect":
+            ctx.save();
+            ctx.translate(p.x, p.y);
+            ctx.rotate(p.spin);
+            ctx.scale(1, Math.cos(p.spin * 1.7)); // the flutter of a turning piece of paper
+            ctx.fillRect(-p.size / 2, -p.size / 4, p.size, p.size / 2);
+            ctx.restore();
+            break;
+        case "text":
+            ctx.font = `${Math.round(p.size)}px system-ui, sans-serif`;
+            ctx.textAlign = "center";
+            ctx.textBaseline = "middle";
+            ctx.fillText(p.text ?? "", p.x, p.y);
+            break;
+    }
+}

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

@@ -0,0 +1,8 @@
+/** What the label says at progress `p`, 0 to 1. */
+export type LabelFrame = (text: string, p: number, random: () => number) => string;
+/**
+ * Writes each frame into the alternate label's text node (never `textContent`: React still owns that node).
+ * `data-sx-btn-playing` swaps which label shows, so the real one keeps the button's width and stays readable by screen
+ * readers. Nothing runs under reduced motion. Returns what stops it.
+ */
+export declare function playLabel(el: HTMLElement, text: string, frameAt: LabelFrame, duration: number, fps: number): () => void;

package/dist/buttons/runtime/playLabel.js

@@ -0,0 +1,49 @@
+// Plays frames of text in a button's alternate label when the pointer arrives or keyboard focus lands. Only an effect
+// with a program imports this, so a button without one doesn't download it.
+/**
+ * Writes each frame into the alternate label's text node (never `textContent`: React still owns that node).
+ * `data-sx-btn-playing` swaps which label shows, so the real one keeps the button's width and stays readable by screen
+ * readers. Nothing runs under reduced motion. Returns what stops it.
+ */
+export function playLabel(el, text, frameAt, duration, fps) {
+    const node = el.querySelector("[data-sx-btn-alt]")?.firstChild;
+    if (!node)
+        return () => { };
+    let frame = 0;
+    const stop = () => {
+        cancelAnimationFrame(frame);
+        frame = 0;
+        node.nodeValue = text;
+        el.removeAttribute("data-sx-btn-playing");
+    };
+    const play = () => {
+        if (frame || window.matchMedia("(prefers-reduced-motion: reduce)").matches)
+            return;
+        const start = performance.now();
+        let last = -Infinity;
+        el.setAttribute("data-sx-btn-playing", "");
+        const tick = (now) => {
+            const p = (now - start) / (duration * 1000);
+            if (p >= 1)
+                return stop();
+            if (now - last >= 1000 / fps) {
+                last = now;
+                node.nodeValue = frameAt(text, p, Math.random);
+            }
+            frame = requestAnimationFrame(tick);
+        };
+        frame = requestAnimationFrame(tick);
+    };
+    const onFocus = () => {
+        if (el.matches(":focus-visible"))
+            play();
+    };
+    if (window.matchMedia("(hover: hover) and (pointer: fine)").matches)
+        el.addEventListener("pointerenter", play);
+    el.addEventListener("focus", onFocus);
+    return () => {
+        stop();
+        el.removeEventListener("pointerenter", play);
+        el.removeEventListener("focus", onFocus);
+    };
+}

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

@@ -0,0 +1,13 @@
+export type ButtonSide = "top" | "right" | "bottom" | "left";
+/** The edge nearest to a point inside a `width` x `height` box. */
+export declare function nearestSide(x: number, y: number, width: number, height: number): ButtonSide;
+/** Where a layer waits so that it arrives from `side`, as fractions of its own size: `[x, y]`. */
+export declare function sideOffset(side: ButtonSide): readonly [number, number];
+/**
+ * The custom properties for a pointer at (`x`, `y`) in a `width` x `height` box. Physical on purpose: the pointer is
+ * where it is, so these never mirror in a right-to-left page.
+ * - `--sx-btn-x` / `-y`: from the top left, px.
+ * - `--sx-btn-cx` / `-cy`: from the centre, px.
+ * - `--sx-btn-dx` / `-dy`: from the centre, -1 to 1.
+ */
+export declare function pointerVars(x: number, y: number, width: number, height: number): Record<`--${string}`, string>;

package/dist/buttons/runtime/pointer.js

@@ -0,0 +1,30 @@
+// The pointer's position over a button, as numbers. Pure; tested. useButtonPointer writes them as custom properties.
+/** The edge nearest to a point inside a `width` x `height` box. */
+export function nearestSide(x, y, width, height) {
+    const distances = [["top", y], ["right", width - x], ["bottom", height - y], ["left", x]];
+    return distances.reduce((best, next) => (next[1] < best[1] ? next : best))[0];
+}
+/** Where a layer waits so that it arrives from `side`, as fractions of its own size: `[x, y]`. */
+export function sideOffset(side) {
+    return side === "top" ? [0, -1] : side === "bottom" ? [0, 1] : side === "left" ? [-1, 0] : [1, 0];
+}
+const round = (n) => Math.round(n * 1000) / 1000;
+/**
+ * The custom properties for a pointer at (`x`, `y`) in a `width` x `height` box. Physical on purpose: the pointer is
+ * where it is, so these never mirror in a right-to-left page.
+ * - `--sx-btn-x` / `-y`: from the top left, px.
+ * - `--sx-btn-cx` / `-cy`: from the centre, px.
+ * - `--sx-btn-dx` / `-dy`: from the centre, -1 to 1.
+ */
+export function pointerVars(x, y, width, height) {
+    const cx = x - width / 2;
+    const cy = y - height / 2;
+    return {
+        "--sx-btn-x": `${round(x)}px`,
+        "--sx-btn-y": `${round(y)}px`,
+        "--sx-btn-cx": `${round(cx)}px`,
+        "--sx-btn-cy": `${round(cy)}px`,
+        "--sx-btn-dx": String(width > 0 ? round(cx / (width / 2)) : 0),
+        "--sx-btn-dy": String(height > 0 ? round(cy / (height / 2)) : 0),
+    };
+}

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

@@ -0,0 +1,8 @@
+/** The distance to the farthest corner of a w × h box from (x, y): a ripple that big covers it wherever it starts. */
+export declare function rippleRadius(x: number, y: number, w: number, h: number): number;
+/** A press counts when the button is enabled and not busy, and a hold-to-confirm button has been held long enough. */
+export declare function pressCounts(el: Pick<Element, "matches" | "hasAttribute">): boolean;
+/** No motion asked for: nothing is thrown and no ripple spreads. */
+export declare const stillMotion: () => boolean;
+/** Enter or Space, as a key press that fires a button. */
+export declare const pressKey: (event: KeyboardEvent) => boolean;

package/dist/buttons/runtime/press.js

@@ -0,0 +1,13 @@
+// What the press runtime and the particle effects share. No React, no listeners; tested.
+/** The distance to the farthest corner of a w × h box from (x, y): a ripple that big covers it wherever it starts. */
+export function rippleRadius(x, y, w, h) {
+    return Math.hypot(Math.max(x, w - x), Math.max(y, h - y));
+}
+/** A press counts when the button is enabled and not busy, and a hold-to-confirm button has been held long enough. */
+export function pressCounts(el) {
+    return !el.matches('[aria-disabled="true"], :disabled') && (!el.hasAttribute("data-sx-btn-hold") || el.hasAttribute("data-sx-btn-held"));
+}
+/** No motion asked for: nothing is thrown and no ripple spreads. */
+export const stillMotion = () => window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+/** Enter or Space, as a key press that fires a button. */
+export const pressKey = (event) => event.key === "Enter" || event.key === " ";

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

@@ -0,0 +1,8 @@
+/** The lens: a rounded box whose edge bends the picture towards its middle, splits it a little into colours, and catches light. */
+export declare const REFRACT_FRAGMENT = "precision mediump float;\nvarying vec2 v_uv;\nuniform vec2 u_size;\nuniform float u_radius;\nuniform vec2 u_pointer;\nuniform float u_bend;\nuniform float u_image_on;\nuniform vec2 u_image_scale;\nuniform sampler2D u_image;\nuniform vec3 u_c0;\nuniform vec3 u_c1;\nuniform vec3 u_c2;\n\nfloat box(vec2 p, vec2 hb, float r) {\n  vec2 q = abs(p) - hb + r;\n  return length(max(q, 0.0)) + min(max(q.x, q.y), 0.0) - r;\n}\n\nvec3 picture(vec2 uv) {\n  if (u_image_on > 0.5) return texture2D(u_image, (uv - 0.5) * u_image_scale + 0.5).rgb;\n  vec3 c = mix(u_c0, u_c1, smoothstep(0.0, 1.0, uv.x));\n  c = mix(c, u_c2, smoothstep(0.45, 0.0, distance(uv, vec2(0.78, 0.25))));\n  return mix(c, u_c1, 0.6 * smoothstep(0.4, 0.0, distance(uv, vec2(0.18, 0.85))));\n}\n\nvoid main() {\n  vec2 hb = u_size * 0.5;\n  vec2 p = (v_uv - 0.5) * u_size;\n  float r = min(u_radius, min(hb.x, hb.y));\n  float d = box(p, hb, r);\n  vec2 e = vec2(1.0, 0.0);\n  vec2 n = normalize(vec2(box(p + e.xy, hb, r) - box(p - e.xy, hb, r), box(p + e.yx, hb, r) - box(p - e.yx, hb, r)) + 1e-5);\n  float rim = smoothstep(-min(hb.y * 0.9, 22.0), 0.0, d);\n  vec2 shift = -n * rim * rim * u_bend * 0.18 + (u_pointer - 0.5) * 0.05;\n  vec3 col = vec3(\n    picture(v_uv + shift * 1.08).r,\n    picture(v_uv + shift).g,\n    picture(v_uv + shift * 0.92).b\n  );\n  // the middle leans to the primary colour, so its own text colour (on-primary) reads over it\n  col = mix(col, u_c0, 0.4 * (1.0 - rim));\n  vec2 light = normalize(vec2(-0.45, 0.8) + (u_pointer - 0.5));\n  float spec = pow(rim, 5.0) * max(dot(n, light), 0.0);\n  col += spec * 0.55 + rim * 0.06;\n  gl_FragColor = vec4(min(col, 1.0), 1.0);\n}";
+export interface RefractOptions {
+    readonly image: string | undefined;
+    readonly bend: number;
+}
+/** Starts the lens on a button. Returns what stops it. */
+export declare function attachRefract(el: HTMLElement, options: RefractOptions): () => void;

package/dist/buttons/runtime/refract.js

@@ -0,0 +1,222 @@
+// glassRefract's program: one WebGL canvas in the button's `lens` layer, drawn on demand (on start, on resize, while the
+// pointer moves over it), never in a loop. Imported only by glassRefract, so a page without it downloads none of it.
+// WebGL can't read the page, so the glass bends a picture: the `image` you give it, or the theme's colours.
+import { createColorResolver, watchTheme } from "../../backgrounds/runtime/color.js";
+import { FULLSCREEN_VERTEX, fullscreenTriangle, link, setUniform } from "../../backgrounds/runtime/webgl.js";
+import { createGpuSurface } from "../../gpu/surface.js";
+/** The lens: a rounded box whose edge bends the picture towards its middle, splits it a little into colours, and catches light. */
+export const REFRACT_FRAGMENT = `precision mediump float;
+varying vec2 v_uv;
+uniform vec2 u_size;
+uniform float u_radius;
+uniform vec2 u_pointer;
+uniform float u_bend;
+uniform float u_image_on;
+uniform vec2 u_image_scale;
+uniform sampler2D u_image;
+uniform vec3 u_c0;
+uniform vec3 u_c1;
+uniform vec3 u_c2;
+
+float box(vec2 p, vec2 hb, float r) {
+  vec2 q = abs(p) - hb + r;
+  return length(max(q, 0.0)) + min(max(q.x, q.y), 0.0) - r;
+}
+
+vec3 picture(vec2 uv) {
+  if (u_image_on > 0.5) return texture2D(u_image, (uv - 0.5) * u_image_scale + 0.5).rgb;
+  vec3 c = mix(u_c0, u_c1, smoothstep(0.0, 1.0, uv.x));
+  c = mix(c, u_c2, smoothstep(0.45, 0.0, distance(uv, vec2(0.78, 0.25))));
+  return mix(c, u_c1, 0.6 * smoothstep(0.4, 0.0, distance(uv, vec2(0.18, 0.85))));
+}
+
+void main() {
+  vec2 hb = u_size * 0.5;
+  vec2 p = (v_uv - 0.5) * u_size;
+  float r = min(u_radius, min(hb.x, hb.y));
+  float d = box(p, hb, r);
+  vec2 e = vec2(1.0, 0.0);
+  vec2 n = normalize(vec2(box(p + e.xy, hb, r) - box(p - e.xy, hb, r), box(p + e.yx, hb, r) - box(p - e.yx, hb, r)) + 1e-5);
+  float rim = smoothstep(-min(hb.y * 0.9, 22.0), 0.0, d);
+  vec2 shift = -n * rim * rim * u_bend * 0.18 + (u_pointer - 0.5) * 0.05;
+  vec3 col = vec3(
+    picture(v_uv + shift * 1.08).r,
+    picture(v_uv + shift).g,
+    picture(v_uv + shift * 0.92).b
+  );
+  // the middle leans to the primary colour, so its own text colour (on-primary) reads over it
+  col = mix(col, u_c0, 0.4 * (1.0 - rim));
+  vec2 light = normalize(vec2(-0.45, 0.8) + (u_pointer - 0.5));
+  float spec = pow(rim, 5.0) * max(dot(n, light), 0.0);
+  col += spec * 0.55 + rim * 0.06;
+  gl_FragColor = vec4(min(col, 1.0), 1.0);
+}`;
+const rgb = (c) => [(c[0] ?? 0) / 255, (c[1] ?? 0) / 255, (c[2] ?? 0) / 255];
+/** Starts the lens on a button. Returns what stops it. */
+export function attachRefract(el, options) {
+    const layer = el.querySelector('[data-sx-btn-layer="glassRefract"]');
+    // reduced motion hides every layer: no point holding a GPU context for it
+    if (!layer || matchMedia("(prefers-reduced-motion: reduce)").matches)
+        return () => { };
+    const losses = { current: [] };
+    const pointer = [0.5, 0.5];
+    let visible = false;
+    let failed = false;
+    let picture = null;
+    let colors = [];
+    let canvas;
+    let surface;
+    let queued = 0;
+    const readColors = () => {
+        const resolver = createColorResolver(el);
+        colors = ["var(--color-sx-primary)", "var(--color-sx-accent)", "var(--color-sx-secondary)"].map((c) => rgb(resolver.resolve(c)));
+        resolver.dispose();
+    };
+    const draw = () => {
+        queued = 0;
+        if (!visible || failed)
+            return;
+        const live = surface.ensure();
+        if (!live)
+            return;
+        const { gl, state } = live;
+        const w = layer.clientWidth;
+        const h = layer.clientHeight;
+        const dpr = Math.min(window.devicePixelRatio || 1, 2);
+        const pw = Math.max(1, Math.round(w * dpr));
+        const ph = Math.max(1, Math.round(h * dpr));
+        if (canvas.width !== pw || canvas.height !== ph) {
+            canvas.width = pw;
+            canvas.height = ph;
+        }
+        gl.viewport(0, 0, pw, ph);
+        gl.useProgram(state.program.program);
+        const at = (name) => state.program.loc(name);
+        const face = el.querySelector("[data-sx-btn-face]");
+        setUniform(gl, at("u_size"), [w, h]);
+        setUniform(gl, at("u_radius"), face ? parseFloat(getComputedStyle(face).borderTopLeftRadius) || 0 : 0);
+        setUniform(gl, at("u_pointer"), pointer);
+        setUniform(gl, at("u_bend"), options.bend);
+        const image = picture?.complete && picture.naturalWidth > 0 && state.texture ? picture : null;
+        setUniform(gl, at("u_image_on"), image ? 1 : 0);
+        if (image) {
+            const ia = image.naturalWidth / image.naturalHeight;
+            const ba = w / Math.max(h, 1);
+            setUniform(gl, at("u_image_scale"), ia > ba ? [ba / ia, 1] : [1, ia / ba]);
+            gl.activeTexture(gl.TEXTURE0);
+            gl.bindTexture(gl.TEXTURE_2D, state.texture);
+            gl.uniform1i(at("u_image"), 0);
+        }
+        colors.forEach((c, i) => setUniform(gl, at(`u_c${i}`), c));
+        state.triangle.draw();
+    };
+    const request = () => {
+        if (!queued)
+            queued = requestAnimationFrame(draw);
+    };
+    const upload = (gl, texture) => {
+        if (!texture || !picture?.complete || picture.naturalWidth === 0)
+            return;
+        gl.bindTexture(gl.TEXTURE_2D, texture);
+        gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
+        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, picture);
+    };
+    const mount = () => {
+        canvas = document.createElement("canvas");
+        canvas.setAttribute("aria-hidden", "true");
+        layer.replaceChildren(canvas);
+        surface = createGpuSurface(canvas, {
+            api: "webgl",
+            label: "glassRefract",
+            init(gl) {
+                const program = link(gl, FULLSCREEN_VERTEX, REFRACT_FRAGMENT);
+                const triangle = fullscreenTriangle(gl);
+                let texture = null;
+                if (options.image) {
+                    texture = gl.createTexture();
+                    gl.bindTexture(gl.TEXTURE_2D, texture);
+                    for (const [k, v] of [[gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE], [gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE], [gl.TEXTURE_MIN_FILTER, gl.LINEAR], [gl.TEXTURE_MAG_FILTER, gl.LINEAR]]) {
+                        gl.texParameteri(gl.TEXTURE_2D, k, v);
+                    }
+                    upload(gl, texture);
+                }
+                return { program, triangle, texture };
+            },
+            dispose(gl, state) {
+                state.program.dispose();
+                state.triangle.dispose();
+                if (state.texture)
+                    gl.deleteTexture(state.texture);
+            },
+            isVisible: () => visible,
+            renew() {
+                surface.destroy();
+                mount();
+                request();
+            },
+            fail() {
+                // the canvas goes, and the layer's own picture (the fallback's look) shows
+                failed = true;
+                canvas.remove();
+            },
+            losses,
+        });
+    };
+    readColors();
+    mount();
+    if (options.image) {
+        picture = new Image();
+        picture.crossOrigin = "anonymous";
+        picture.decoding = "async";
+        picture.onload = () => {
+            const live = surface.live;
+            if (live)
+                upload(live.gl, live.state.texture);
+            request();
+        };
+        picture.src = options.image;
+    }
+    const io = new IntersectionObserver(([entry]) => {
+        visible = entry?.isIntersecting ?? false;
+        if (!visible)
+            surface.hidden();
+        else if (surface.shown())
+            request();
+    });
+    io.observe(el);
+    const ro = new ResizeObserver(request);
+    ro.observe(layer);
+    const stopTheme = watchTheme(() => {
+        readColors();
+        request();
+    });
+    // the glass leans with the pointer, only where there is one: a drawing per move, at most one a frame
+    const fine = matchMedia("(hover: hover) and (pointer: fine)").matches;
+    const move = (event) => {
+        const box = el.getBoundingClientRect();
+        pointer[0] = (event.clientX - box.left) / Math.max(box.width, 1);
+        pointer[1] = 1 - (event.clientY - box.top) / Math.max(box.height, 1);
+        request();
+    };
+    const leave = () => {
+        pointer[0] = 0.5;
+        pointer[1] = 0.5;
+        request();
+    };
+    if (fine) {
+        el.addEventListener("pointermove", move);
+        el.addEventListener("pointerleave", leave);
+    }
+    return () => {
+        cancelAnimationFrame(queued);
+        io.disconnect();
+        ro.disconnect();
+        stopTheme();
+        el.removeEventListener("pointermove", move);
+        el.removeEventListener("pointerleave", leave);
+        if (picture)
+            picture.onload = null;
+        surface.destroy();
+        canvas.remove();
+    };
+}

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

@@ -0,0 +1 @@
+export { graphemes, splitLabel } from "../../text/split.js";

package/dist/buttons/runtime/split.js

@@ -0,0 +1,3 @@
+// A button label cut into what can move on its own: letters where letters stand alone, words in joined or spaceless
+// scripts. The splitter lives with the text effects (text/split.ts), shared with Text and SplitText.
+export { graphemes, splitLabel } from "../../text/split.js";

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

@@ -0,0 +1,8 @@
+import type { ButtonState } from "../types.js";
+/** What can happen to a button's action: it starts, it works, it fails, or the result has shown long enough. */
+export type ButtonEvent = "start" | "resolve" | "reject" | "reset";
+/**
+ * The state after `event`. A loading button can't start again (no double submit) and isn't reset under the work; only
+ * a loading button can succeed or fail.
+ */
+export declare function nextButtonState(state: ButtonState, event: ButtonEvent): ButtonState;

package/dist/buttons/runtime/state.js

@@ -0,0 +1,17 @@
+// The state machine behind `useButtonAction`. Pure; tested.
+/**
+ * The state after `event`. A loading button can't start again (no double submit) and isn't reset under the work; only
+ * a loading button can succeed or fail.
+ */
+export function nextButtonState(state, event) {
+    switch (event) {
+        case "start":
+            return "loading";
+        case "resolve":
+            return state === "loading" ? "success" : state;
+        case "reject":
+            return state === "loading" ? "error" : state;
+        case "reset":
+            return state === "loading" ? state : "idle";
+    }
+}

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

@@ -0,0 +1,26 @@
+import type { ButtonState } from "../types.js";
+export interface ButtonActionOptions {
+    /** Milliseconds a success or an error shows before the button is idle again; `false` keeps it ("Subscribed"). Default `2000`. */
+    readonly resetAfter?: number | false;
+    /** Milliseconds the loading state shows at least, so a quick answer doesn't flash a spinner. Default `400`. */
+    readonly minLoading?: number;
+    /** Gets what the action threw. Without it the error is reported like an uncaught one, so it still shows in the console. */
+    readonly onError?: (error: unknown) => void;
+}
+/** What to spread on `Button`. */
+export interface ButtonAction {
+    readonly state: ButtonState;
+    /** 0 to 1 once the action reports it, `undefined` until then. */
+    readonly progress: number | undefined;
+    readonly onClick: () => void;
+}
+/**
+ * Runs `action` on click and gives the button its state: loading while it works, then success or error, then idle again.
+ * A second click while loading does nothing. `action` gets a function to report progress, 0 to 1.
+ *
+ * ```tsx
+ * const save = useButtonAction(async () => { await post(form); }, { resetAfter: 2000 });
+ * <Button {...save} effect={stateSwap()} labels={{ loading: "Saving", success: "Saved", error: "Try again" }}>Save</Button>
+ * ```
+ */
+export declare function useButtonAction(action: (progress: (done: number) => void) => unknown, options?: ButtonActionOptions): ButtonAction;

package/dist/buttons/runtime/useButtonAction.js

@@ -0,0 +1,83 @@
+"use client";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { nextButtonState } from "./state.js";
+/** Says what went wrong without throwing into React. */
+function report(error) {
+    if (typeof reportError === "function")
+        reportError(error);
+    else
+        console.error(error);
+}
+/**
+ * Runs `action` on click and gives the button its state: loading while it works, then success or error, then idle again.
+ * A second click while loading does nothing. `action` gets a function to report progress, 0 to 1.
+ *
+ * ```tsx
+ * const save = useButtonAction(async () => { await post(form); }, { resetAfter: 2000 });
+ * <Button {...save} effect={stateSwap()} labels={{ loading: "Saving", success: "Saved", error: "Try again" }}>Save</Button>
+ * ```
+ */
+export function useButtonAction(action, options = {}) {
+    const [state, setState] = useState("idle");
+    const [progress, setProgress] = useState(undefined);
+    // the state as of now, before React re-renders: a fast second click must already see "loading"
+    const current = useRef("idle");
+    // which click a result belongs to; bumped on unmount, so nothing settles into a button that is gone
+    const run = useRef(0);
+    const timer = useRef(undefined);
+    const latest = useRef({ action, options });
+    latest.current = { action, options };
+    useEffect(() => () => {
+        run.current++;
+        clearTimeout(timer.current);
+    }, []);
+    const onClick = useCallback(() => {
+        if (current.current === "loading")
+            return;
+        clearTimeout(timer.current);
+        const id = ++run.current;
+        const { action: act, options: opts } = latest.current;
+        const move = (event) => {
+            current.current = nextButtonState(current.current, event);
+            setState(current.current);
+        };
+        const started = Date.now();
+        move("start");
+        setProgress(undefined);
+        const settle = (event, error) => {
+            if (run.current !== id)
+                return;
+            const wait = Math.max(0, (opts.minLoading ?? 400) - (Date.now() - started));
+            timer.current = setTimeout(() => {
+                if (run.current !== id)
+                    return;
+                move(event);
+                if (event === "reject")
+                    (opts.onError ?? report)(error);
+                const after = opts.resetAfter ?? 2000;
+                if (after === false)
+                    return;
+                timer.current = setTimeout(() => {
+                    if (run.current !== id)
+                        return;
+                    move("reset");
+                    setProgress(undefined);
+                }, after);
+            }, wait);
+        };
+        const tell = (done) => {
+            if (run.current === id && current.current === "loading")
+                setProgress(Math.min(1, Math.max(0, done)));
+        };
+        let result;
+        try {
+            result = act(tell);
+        }
+        catch (error) {
+            settle("reject", error);
+            return;
+        }
+        Promise.resolve(result).then(() => settle("resolve"), (error) => settle("reject", error));
+    }, []);
+    return { state, progress, onClick };
+}

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

@@ -0,0 +1,6 @@
+import { type RefObject } from "react";
+/**
+ * Starts pointer tracking on a button whose effects read the pointer. CSS does the rest, so a cursor effect is a
+ * stylesheet like any other. Where there is no mouse nothing runs and nothing is downloaded.
+ */
+export declare function useButtonPointer(ref: RefObject<HTMLElement | null>, enabled: boolean): void;

package/dist/buttons/runtime/useButtonPointer.js

@@ -0,0 +1,23 @@
+"use client";
+import { useEffect } from "react";
+/**
+ * Starts pointer tracking on a button whose effects read the pointer. CSS does the rest, so a cursor effect is a
+ * stylesheet like any other. Where there is no mouse nothing runs and nothing is downloaded.
+ */
+export function useButtonPointer(ref, enabled) {
+    useEffect(() => {
+        const el = ref.current;
+        if (!el || !enabled || !window.matchMedia("(hover: hover) and (pointer: fine)").matches)
+            return;
+        let stop;
+        let gone = false;
+        void import("./attachPointer.js").then(({ attachPointer }) => {
+            if (!gone)
+                stop = attachPointer(el);
+        });
+        return () => {
+            gone = true;
+            stop?.();
+        };
+    }, [ref, enabled]);
+}

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

@@ -0,0 +1,6 @@
+import { type RefObject } 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 declare function useButtonPress(ref: RefObject<HTMLElement | null>, tap: boolean, hold: number | undefined): void;