@sharedex/ui 0.0.0-stage → 0.9.0

package/dist/buttons/effects/icon/iconExpand.js

@@ -0,0 +1,33 @@
+import { at, defineButton, labelOf, textOf, v, varName, whenOn } from "../kit.js";
+import { ARROW } from "./icons.js";
+const ID = "iconExpand";
+const LABEL = labelOf(ID);
+const TEXT = textOf(ID);
+const EASING = "var(--ease-sx-out, ease-out)";
+// A grid track from 0fr to 1fr, the one way to animate to a size the text decides (and the layout, on one button).
+// It only collapses where hover exists: on a phone there would be no way to open it, so the label just shows.
+const CSS = `  ${at(LABEL)} {
+    display: inline-grid;
+    grid-template-columns: auto 1fr;
+    column-gap: 0.5em;
+    transition: grid-template-columns ${v(ID, "time")} ${EASING}, column-gap ${v(ID, "time")} ${EASING};
+  }
+  ${at(TEXT)} {
+    min-inline-size: 0;
+    overflow: hidden;
+    white-space: nowrap;
+    transition: opacity ${v(ID, "time")} ${EASING};
+  }
+  @media (hover: hover) and (pointer: fine) {
+    ${at(LABEL)} { grid-template-columns: auto 0fr; column-gap: 0; }
+    ${at(TEXT)} { opacity: 0; }
+  }
+${whenOn(ID, LABEL, "grid-template-columns: auto 1fr; column-gap: 0.5em;")}
+${whenOn(ID, TEXT, "opacity: 1;")}`;
+/** An icon-only button grows to show its label. Screen readers always read the label; on a phone it always shows. */
+export function iconExpand(options = {}) {
+    return defineButton(ID, CSS, {
+        vars: { [varName(ID, "time")]: `${options.duration ?? 0.3}s` },
+        label: { wrap: true, icon: ARROW, iconAt: "start" },
+    });
+}

package/dist/buttons/effects/icon/iconExpand.schema.d.ts

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

package/dist/buttons/effects/icon/iconExpand.schema.js

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

package/dist/buttons/effects/icon/iconMorph.d.ts

@@ -0,0 +1,15 @@
+import type { ButtonEffect } from "../../types.js";
+export interface IconMorphOptions {
+    /** `"menu"`: three lines turn into a cross. `"play"`: a triangle turns into pause bars. Default `"menu"`. */
+    readonly shape?: "menu" | "play";
+    /** Seconds it takes. Default `0.25`. */
+    readonly duration?: number;
+}
+/**
+ * The icon changes shape with the button's `aria-pressed`: menu to cross, play to pause. You own the state.
+ *
+ * ```tsx
+ * <Button effect={iconMorph()} aria-pressed={open} aria-label="Menu" onClick={() => setOpen(!open)} />
+ * ```
+ */
+export declare function iconMorph(options?: IconMorphOptions): ButtonEffect;

package/dist/buttons/effects/icon/iconMorph.js

@@ -0,0 +1,38 @@
+import { at, defineButton, hitOf, timed, v, varName } from "../kit.js";
+import { MENU, PLAY } from "./icons.js";
+const ID = "iconMorph";
+const part = (name) => `${hitOf(ID)} [data-sx-btn-svg="${name}"]`;
+const pressed = (name) => `${hitOf(ID)}[aria-pressed="true"] [data-sx-btn-svg="${name}"]`;
+const LINES = ["top", "middle", "bottom"];
+const HALVES = ["left", "right"];
+// The motion: under reduced motion the icon still changes, at once.
+const CSS = `  ${at(LINES.map(part).join(", "))} {
+    transition: translate ${v(ID, "time")} ease-out, rotate ${v(ID, "time")} ease-out, opacity ${v(ID, "time")} ease-out;
+  }
+  ${at(HALVES.map(part).join(", "))} { ${timed(ID, "clip-path")} }`;
+// The poses: what the button's state looks like. `px` in an SVG's CSS means its own units.
+const STATE = `  ${at(LINES.map(part).join(", "))} {
+    transform-box: fill-box;
+    transform-origin: center;
+  }
+  ${at(pressed("top"))} { translate: 0 5px; rotate: 45deg; }
+  ${at(pressed("middle"))} { opacity: 0; }
+  ${at(pressed("bottom"))} { translate: 0 -5px; rotate: -45deg; }
+  ${at(part("left"))} { clip-path: polygon(0 0, 100% 22%, 100% 78%, 0 100%); }
+  ${at(part("right"))} { clip-path: polygon(0 22%, 100% 50%, 100% 50%, 0 78%); }
+  ${at(pressed("left"))} { clip-path: polygon(0 0, 70% 0, 70% 100%, 0 100%); }
+  ${at(pressed("right"))} { clip-path: polygon(30% 0, 100% 0, 100% 100%, 30% 100%); }`;
+/**
+ * The icon changes shape with the button's `aria-pressed`: menu to cross, play to pause. You own the state.
+ *
+ * ```tsx
+ * <Button effect={iconMorph()} aria-pressed={open} aria-label="Menu" onClick={() => setOpen(!open)} />
+ * ```
+ */
+export function iconMorph(options = {}) {
+    return defineButton(ID, CSS, {
+        vars: { [varName(ID, "time")]: `${options.duration ?? 0.25}s` },
+        label: { wrap: true, icon: (options.shape ?? "menu") === "play" ? PLAY : MENU, iconAt: "start" },
+        state: STATE,
+    });
+}

package/dist/buttons/effects/icon/iconMorph.schema.d.ts

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

package/dist/buttons/effects/icon/iconMorph.schema.js

@@ -0,0 +1,10 @@
+import { defineSchema } from "../../../schema/define.js";
+export const ICON_MORPH_SCHEMA = defineSchema()({
+    id: "iconMorph",
+    family: "button",
+    factory: "iconMorph",
+    fields: {
+        shape: { kind: "choice", label: "Shape", values: ["menu", "play"], labels: { menu: "Menu to cross", play: "Play to pause" }, default: "menu" },
+        duration: { kind: "number", label: "Duration", min: 0.1, max: 1, step: 0.05, unit: "s", default: 0.25 },
+    },
+});

package/dist/buttons/effects/icon/iconNudge.d.ts

@@ -0,0 +1,11 @@
+import type { ButtonEffect } from "../../types.js";
+export interface IconNudgeOptions {
+    /** How far it moves, px, in reading direction. Default `4`. */
+    readonly distance?: number;
+    /** Turn the icon around in a right-to-left page, as an arrow should. Default `true`. */
+    readonly mirror?: boolean;
+    /** Seconds it takes. Default `0.2`. */
+    readonly duration?: number;
+}
+/** The icon moves a few pixels forward: a cheap way to say "this goes somewhere". Brings an arrow if the button has no icon. */
+export declare function iconNudge(options?: IconNudgeOptions): ButtonEffect;

package/dist/buttons/effects/icon/iconNudge.js

@@ -0,0 +1,21 @@
+import { DIR, at, defineButton, iconOf, timed, v, varName, whenOn } from "../kit.js";
+import { ARROW } from "./icons.js";
+const ID = "iconNudge";
+const ICON = iconOf(ID);
+const CSS = `  ${at(ICON)} {
+    scale: calc(1 + (${DIR} - 1) * ${v(ID, "mirror")}) 1;
+    ${timed(ID, "translate")}
+  }
+${whenOn(ID, ICON, `translate: calc(${DIR} * ${v(ID, "distance")} * 1px) 0;`)}`;
+/** The icon moves a few pixels forward: a cheap way to say "this goes somewhere". Brings an arrow if the button has no icon. */
+export function iconNudge(options = {}) {
+    return defineButton(ID, CSS, {
+        vars: {
+            [varName(ID, "distance")]: options.distance ?? 4,
+            [varName(ID, "mirror")]: (options.mirror ?? true) ? 1 : 0,
+            [varName(ID, "time")]: `${options.duration ?? 0.2}s`,
+        },
+        label: { wrap: true, icon: ARROW },
+        claims: ["icon"],
+    });
+}

package/dist/buttons/effects/icon/iconNudge.schema.d.ts

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

package/dist/buttons/effects/icon/iconNudge.schema.js

@@ -0,0 +1,11 @@
+import { defineSchema } from "../../../schema/define.js";
+export const ICON_NUDGE_SCHEMA = defineSchema()({
+    id: "iconNudge",
+    family: "button",
+    factory: "iconNudge",
+    fields: {
+        distance: { kind: "number", label: "Distance", min: 1, max: 16, step: 1, unit: "px", default: 4 },
+        mirror: { kind: "boolean", label: "Turn around in right-to-left pages", help: "Right for an arrow, wrong for a logo.", default: true },
+        duration: { kind: "number", label: "Duration", min: 0.05, max: 1, step: 0.05, unit: "s", default: 0.2 },
+    },
+});

package/dist/buttons/effects/icon/iconReveal.d.ts

@@ -0,0 +1,9 @@
+import type { ButtonEffect } from "../../types.js";
+export interface IconRevealOptions {
+    /** The border's colour. Default the button's text colour. */
+    readonly color?: string;
+    /** Seconds it takes. Default `0.35`. */
+    readonly duration?: number;
+}
+/** The text fades away and the icon rises through a gap that opens in the bottom edge. Brings an arrow if the button has no icon. */
+export declare function iconReveal(options?: IconRevealOptions): ButtonEffect;

package/dist/buttons/effects/icon/iconReveal.js

@@ -0,0 +1,37 @@
+import { at, defineButton, iconOf, layerOf, textOf, v, varName, whenOn } from "../kit.js";
+import { ARROW } from "./icons.js";
+const ID = "iconReveal";
+const TEXT = textOf(ID);
+const ICON = iconOf(ID);
+const EDGE = layerOf(ID);
+const MOVE = `transition: translate ${v(ID, "time")} var(--ease-sx-out, ease-out), opacity ${v(ID, "time")} var(--ease-sx-out, ease-out);`;
+/** The border with a gap in its bottom edge, `half` either side of the middle. */
+const gap = (half) => `polygon(0 0, 100% 0, 100% 100%, calc(50% + ${half}) 100%, calc(50% + ${half}) calc(100% - 4px), calc(50% - ${half}) calc(100% - 4px), calc(50% - ${half}) 100%, 0 100%)`;
+const CSS = `  ${at(TEXT)} { ${MOVE} }
+  ${at(ICON)} {
+    position: absolute;
+    inset: 0;
+    translate: 0 1.8em;
+    opacity: 0;
+    ${MOVE}
+  }
+  ${at(EDGE)} {
+    border: 1px solid ${v(ID, "color")};
+    clip-path: ${gap("0em")};
+    transition: clip-path ${v(ID, "time")} var(--ease-sx-out, ease-out);
+  }
+${whenOn(ID, TEXT, "translate: 0 -0.7em; opacity: 0;")}
+${whenOn(ID, ICON, "translate: 0 0; opacity: 1;")}
+${whenOn(ID, EDGE, `clip-path: ${gap("1em")};`)}`;
+/** The text fades away and the icon rises through a gap that opens in the bottom edge. Brings an arrow if the button has no icon. */
+export function iconReveal(options = {}) {
+    return defineButton(ID, CSS, {
+        vars: {
+            [varName(ID, "color")]: options.color ?? "currentColor",
+            [varName(ID, "time")]: `${options.duration ?? 0.35}s`,
+        },
+        layers: [{ slot: "edge" }],
+        label: { wrap: true, icon: ARROW },
+        claims: ["label", "icon"],
+    });
+}

package/dist/buttons/effects/icon/iconReveal.schema.d.ts

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

package/dist/buttons/effects/icon/iconReveal.schema.js

@@ -0,0 +1,10 @@
+import { defineSchema } from "../../../schema/define.js";
+export const ICON_REVEAL_SCHEMA = defineSchema()({
+    id: "iconReveal",
+    family: "button",
+    factory: "iconReveal",
+    fields: {
+        color: { kind: "color", label: "Border colour", default: "currentColor" },
+        duration: { kind: "number", label: "Duration", min: 0.1, max: 1, step: 0.05, unit: "s", default: 0.35 },
+    },
+});

package/dist/buttons/effects/icon/icons.d.ts

@@ -0,0 +1,4 @@
+import type { ButtonIcon } from "../../types.js";
+export declare const ARROW: ButtonIcon;
+export declare const MENU: ButtonIcon;
+export declare const PLAY: ButtonIcon;

package/dist/buttons/effects/icon/icons.js

@@ -0,0 +1,11 @@
+// The icons effects bring when a button has none of its own. Drawn as data, in the label's colour.
+export const ARROW = {
+    viewBox: "0 0 24 24",
+    children: [
+        { tag: "path", attrs: { d: "M5 12h14M13 6l6 6-6 6", fill: "none", stroke: "currentColor", "stroke-width": 2, "stroke-linecap": "round", "stroke-linejoin": "round" } },
+    ],
+};
+const bar = (part, y) => ({ tag: "rect", part, attrs: { x: 4, y, width: 16, height: 2, rx: 1, fill: "currentColor" } });
+export const MENU = { viewBox: "0 0 24 24", children: [bar("top", 6), bar("middle", 11), bar("bottom", 16)] };
+const half = (part, x) => ({ tag: "rect", part, attrs: { x, y: 4, width: 7, height: 16, fill: "currentColor" } });
+export const PLAY = { viewBox: "0 0 24 24", children: [half("left", 5), half("right", 12)] };

package/dist/buttons/effects/idle/idleBreathe.d.ts

@@ -0,0 +1,13 @@
+import type { ButtonEffect } from "../../types.js";
+export interface IdleBreatheOptions {
+    /** The glow's colour. Default `var(--color-sx-accent)`. */
+    readonly color?: string;
+    /** How soft it is, px of blur. Default `14`. */
+    readonly blur?: number;
+    /** How bright it gets at its fullest, 0-1. Default `0.7`. */
+    readonly strength?: number;
+    /** Seconds for one breath in. Default `2.4`. */
+    readonly duration?: number;
+}
+/** A soft glow behind the button slowly swells and fades, all the time. Use one per screen. */
+export declare function idleBreathe(options?: IdleBreatheOptions): ButtonEffect;

package/dist/buttons/effects/idle/idleBreathe.js

@@ -0,0 +1,28 @@
+import { at, defineButton, layerOf, v, varName } from "../kit.js";
+const ID = "idleBreathe";
+const GLOW = layerOf(ID);
+const BREATHE = "sx-btn-idleBreathe";
+// the blur is drawn once; only its opacity and size change, so the compositor runs the breath
+const CSS = `  ${at(GLOW)} {
+    background: ${v(ID, "color")};
+    filter: blur(calc(${v(ID, "blur")} * 1px));
+    opacity: 0;
+    animation: ${BREATHE} ${v(ID, "time")} ease-in-out infinite alternate;
+  }
+  @keyframes ${BREATHE} {
+    from { opacity: calc(${v(ID, "strength")} * 0.25); scale: 0.96; }
+    to { opacity: ${v(ID, "strength")}; scale: 1.04; }
+  }`;
+/** A soft glow behind the button slowly swells and fades, all the time. Use one per screen. */
+export function idleBreathe(options = {}) {
+    return defineButton(ID, CSS, {
+        vars: {
+            [varName(ID, "color")]: options.color ?? "var(--color-sx-accent)",
+            [varName(ID, "blur")]: options.blur ?? 14,
+            [varName(ID, "strength")]: options.strength ?? 0.7,
+            [varName(ID, "time")]: `${options.duration ?? 2.4}s`,
+        },
+        layers: [{ slot: "under" }],
+        needs: { inView: true },
+    });
+}

package/dist/buttons/effects/idle/idleBreathe.schema.d.ts

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

package/dist/buttons/effects/idle/idleBreathe.schema.js

@@ -0,0 +1,12 @@
+import { defineSchema } from "../../../schema/define.js";
+export const IDLE_BREATHE_SCHEMA = defineSchema()({
+    id: "idleBreathe",
+    family: "button",
+    factory: "idleBreathe",
+    fields: {
+        color: { kind: "color", label: "Colour", default: "var(--color-sx-accent)" },
+        blur: { kind: "number", label: "Softness", min: 4, max: 40, step: 1, unit: "px", default: 14 },
+        strength: { kind: "number", label: "Brightness", min: 0.1, max: 1, step: 0.05, default: 0.7 },
+        duration: { kind: "number", label: "Breath", min: 1, max: 6, step: 0.1, unit: "s", help: "Seconds for one breath in. Use one always-moving button per screen.", default: 2.4 },
+    },
+});

package/dist/buttons/effects/idle/idleGrain.d.ts

@@ -0,0 +1,13 @@
+import type { ButtonEffect } from "../../types.js";
+export interface IdleGrainOptions {
+    /** How strong the grain is, 0-1. Default `0.35`. */
+    readonly opacity?: number;
+    /** Tile size, px: bigger is coarser. Default `120`. */
+    readonly size?: number;
+    /** How fine the noise is (0.5 soft … 1.2 fine). Default `0.85`. */
+    readonly frequency?: number;
+    /** Jumps per second. Default `8`. */
+    readonly fps?: number;
+}
+/** Fine film grain flickers over the button, all the time. Use one per screen. */
+export declare function idleGrain(options?: IdleGrainOptions): ButtonEffect;

package/dist/buttons/effects/idle/idleGrain.js

@@ -0,0 +1,53 @@
+import { at, childOf, defineButton, v, varName } from "../kit.js";
+const ID = "idleGrain";
+const NOISE = childOf(ID, "noise");
+const GRAIN = "sx-btn-idleGrain";
+const STEPS = 8;
+/**
+ * The noise as an image: the browser renders the SVG filter once, and the animation only moves the picture. Only its
+ * alpha matters (it is a mask): the brighter half of the noise, as specks.
+ */
+function noiseTile(frequency) {
+    const svg = "<svg xmlns='http://www.w3.org/2000/svg' width='256' height='256'>" +
+        `<filter id='n'><feTurbulence type='fractalNoise' baseFrequency='${frequency}' numOctaves='3' stitchTiles='stitch'/>` +
+        "<feColorMatrix values='0 0 0 0 0  0 0 0 0 0  0 0 0 0 0  3 0 0 0 -1.2'/></filter><rect width='100%' height='100%' filter='url(#n)'/></svg>";
+    return `url("data:image/svg+xml,${encodeURIComponent(svg)}")`;
+}
+// The noise is twice the button (inset -50%) and jumps with `translate`. A step is a share of the noise, so it must stay
+// within 25% or an edge goes bare for a frame (the backgrounds' film grain found this); 18% keeps a margin.
+// The specks are the label's colour (currentColor), masked by the noise: they show on any face, light or dark.
+const CSS = `  ${at(NOISE)} {
+    position: absolute;
+    inset: -50%;
+    background: currentColor;
+    -webkit-mask-image: ${v(ID, "tile")};
+    mask-image: ${v(ID, "tile")};
+    -webkit-mask-size: calc(${v(ID, "size")} * 1px);
+    mask-size: calc(${v(ID, "size")} * 1px);
+    opacity: ${v(ID, "opacity")};
+    animation: ${GRAIN} ${v(ID, "time")} steps(1) infinite;
+  }
+  @keyframes ${GRAIN} {
+    0% { translate: 0 0; }
+    12.5% { translate: -5% -10%; }
+    25% { translate: -15% 5%; }
+    37.5% { translate: 7% -18%; }
+    50% { translate: -5% 18%; }
+    62.5% { translate: 15% 0; }
+    75% { translate: 0 15%; }
+    87.5% { translate: -10% 10%; }
+  }`;
+/** Fine film grain flickers over the button, all the time. Use one per screen. */
+export function idleGrain(options = {}) {
+    const fps = options.fps ?? 8;
+    return defineButton(ID, CSS, {
+        vars: {
+            [varName(ID, "tile")]: noiseTile(options.frequency ?? 0.85),
+            [varName(ID, "size")]: options.size ?? 120,
+            [varName(ID, "opacity")]: options.opacity ?? 0.35,
+            [varName(ID, "time")]: `${STEPS / Math.max(fps, 0.1)}s`,
+        },
+        layers: [{ slot: "fill", children: ["noise"] }],
+        needs: { inView: true },
+    });
+}

package/dist/buttons/effects/idle/idleGrain.schema.d.ts

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

package/dist/buttons/effects/idle/idleGrain.schema.js

@@ -0,0 +1,12 @@
+import { defineSchema } from "../../../schema/define.js";
+export const IDLE_GRAIN_SCHEMA = defineSchema()({
+    id: "idleGrain",
+    family: "button",
+    factory: "idleGrain",
+    fields: {
+        opacity: { kind: "number", label: "Strength", min: 0.05, max: 1, step: 0.05, default: 0.35 },
+        size: { kind: "number", label: "Grain size", min: 40, max: 400, step: 10, unit: "px", help: "The noise tile: bigger is coarser.", default: 120 },
+        frequency: { kind: "number", label: "Fineness", min: 0.3, max: 1.5, step: 0.05, default: 0.85 },
+        fps: { kind: "number", label: "Speed", min: 1, max: 24, step: 1, unit: "/s", help: "Jumps per second.", default: 8 },
+    },
+});

package/dist/buttons/effects/idle/idlePing.d.ts

@@ -0,0 +1,13 @@
+import type { ButtonEffect } from "../../types.js";
+export interface IdlePingOptions {
+    /** The ring's colour. Default `var(--color-sx-accent)`. */
+    readonly color?: string;
+    /** How far it travels from the edge, px. Default `10`. */
+    readonly spread?: number;
+    /** Its thickness, px. Default `2`. */
+    readonly width?: number;
+    /** Seconds between two rings. Default `2`. */
+    readonly duration?: number;
+}
+/** A ring keeps pulsing out from the edge, all the time. Use one per screen. */
+export declare function idlePing(options?: IdlePingOptions): ButtonEffect;

package/dist/buttons/effects/idle/idlePing.js

@@ -0,0 +1,29 @@
+import { at, defineButton, layerOf, v, varName } from "../kit.js";
+const ID = "idlePing";
+const RING = layerOf(ID);
+const PING = "sx-btn-idlePing";
+// The ring moves with outline-offset, which repaints one small layer: `scale` would grow a wide button's ring sideways
+// far more than up and down, and only an offset keeps the same gap all round on any shape (allowed in the test).
+const CSS = `  ${at(RING)} {
+    outline: calc(${v(ID, "width")} * 1px) solid ${v(ID, "color")};
+    outline-offset: 0px;
+    opacity: 0;
+    animation: ${PING} ${v(ID, "time")} cubic-bezier(0, 0, 0.2, 1) infinite;
+  }
+  @keyframes ${PING} {
+    0% { outline-offset: 0px; opacity: 0.8; }
+    75%, 100% { outline-offset: calc(${v(ID, "spread")} * 1px); opacity: 0; }
+  }`;
+/** A ring keeps pulsing out from the edge, all the time. Use one per screen. */
+export function idlePing(options = {}) {
+    return defineButton(ID, CSS, {
+        vars: {
+            [varName(ID, "color")]: options.color ?? "var(--color-sx-accent)",
+            [varName(ID, "spread")]: options.spread ?? 10,
+            [varName(ID, "width")]: options.width ?? 2,
+            [varName(ID, "time")]: `${options.duration ?? 2}s`,
+        },
+        layers: [{ slot: "under" }],
+        needs: { inView: true },
+    });
+}

package/dist/buttons/effects/idle/idlePing.schema.d.ts

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

package/dist/buttons/effects/idle/idlePing.schema.js

@@ -0,0 +1,12 @@
+import { defineSchema } from "../../../schema/define.js";
+export const IDLE_PING_SCHEMA = defineSchema()({
+    id: "idlePing",
+    family: "button",
+    factory: "idlePing",
+    fields: {
+        color: { kind: "color", label: "Colour", default: "var(--color-sx-accent)" },
+        spread: { kind: "number", label: "Reach", min: 2, max: 32, step: 1, unit: "px", help: "How far the ring travels from the edge.", default: 10 },
+        width: { kind: "number", label: "Thickness", min: 1, max: 6, step: 0.5, unit: "px", default: 2 },
+        duration: { kind: "number", label: "Every", min: 0.8, max: 6, step: 0.1, unit: "s", help: "Seconds between two rings. Use one always-moving button per screen.", default: 2 },
+    },
+});

package/dist/buttons/effects/idle/idleWiggle.d.ts

@@ -0,0 +1,9 @@
+import type { ButtonEffect } from "../../types.js";
+export interface IdleWiggleOptions {
+    /** How far it rocks, degrees. Default `3`. */
+    readonly angle?: number;
+    /** Seconds from one wiggle to the next. The wiggle itself is the last sixth of it. Default `4`. */
+    readonly every?: number;
+}
+/** Every few seconds the button gives a short wiggle, and holds still while you point at it. Use one per screen. */
+export declare function idleWiggle(options?: IdleWiggleOptions): ButtonEffect;

package/dist/buttons/effects/idle/idleWiggle.js

@@ -0,0 +1,28 @@
+import { at, bodyOf, defineButton, v, varName, whenOn } from "../kit.js";
+const ID = "idleWiggle";
+const BODY = bodyOf(ID);
+const WIGGLE = "sx-btn-idleWiggle";
+const DEG = (k) => `calc(${v(ID, "angle")} * ${k}deg)`;
+// it rests while hovered or focused: a button that moves away from the pointer is hard to aim at
+const CSS = `  ${at(BODY)} {
+    animation: ${WIGGLE} ${v(ID, "time")} ease-in-out infinite;
+  }
+${whenOn(ID, BODY, "animation-play-state: paused;")}
+  @keyframes ${WIGGLE} {
+    0%, 83%, 100% { rotate: 0deg; }
+    86% { rotate: ${DEG(1)}; }
+    89% { rotate: ${DEG(-1)}; }
+    92% { rotate: ${DEG(0.6)}; }
+    95% { rotate: ${DEG(-0.3)}; }
+  }`;
+/** Every few seconds the button gives a short wiggle, and holds still while you point at it. Use one per screen. */
+export function idleWiggle(options = {}) {
+    return defineButton(ID, CSS, {
+        vars: {
+            [varName(ID, "angle")]: options.angle ?? 3,
+            [varName(ID, "time")]: `${options.every ?? 4}s`,
+        },
+        claims: ["turn"],
+        needs: { inView: true },
+    });
+}

package/dist/buttons/effects/idle/idleWiggle.schema.d.ts

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

package/dist/buttons/effects/idle/idleWiggle.schema.js

@@ -0,0 +1,10 @@
+import { defineSchema } from "../../../schema/define.js";
+export const IDLE_WIGGLE_SCHEMA = defineSchema()({
+    id: "idleWiggle",
+    family: "button",
+    factory: "idleWiggle",
+    fields: {
+        angle: { kind: "number", label: "Angle", min: 1, max: 12, step: 0.5, unit: "°", default: 3 },
+        every: { kind: "number", label: "Every", min: 2, max: 12, step: 0.5, unit: "s", help: "Seconds from one wiggle to the next. Use one always-moving button per screen.", default: 4 },
+    },
+});

package/dist/buttons/effects/kit.d.ts

@@ -0,0 +1,74 @@
+import type { ButtonClaim, ButtonEffect, ButtonLabelPlan, ButtonLayer, ButtonNeeds, ButtonProgram, ButtonStatus, ButtonTier, ButtonVars } from "../types.js";
+/** An effect's option as a custom property: `--sx-btn-fillSweep-color`. */
+export declare const varName: (id: string, name: string) => `--${string}`;
+/** Read it. */
+export declare const v: (id: string, name: string) => string;
+/** 1, or -1 in a right-to-left context. Physical values multiply by it. */
+export declare const DIR = "var(--sx-btn-dir)";
+/** An effect's layer, as a raw selector (it goes inside `:where()`). */
+export declare const layerOf: (id: string, part?: string) => string;
+/** A named span inside an effect's layer, as a raw selector. */
+export declare const childOf: (id: string, part: string, layerPart?: string) => string;
+/** The label of a button wearing this effect, as a raw selector. */
+export declare const labelOf: (id: string) => string;
+/** The label's text span, as a raw selector (`label.wrap`). */
+export declare const textOf: (id: string) => string;
+/** The second label, as a raw selector (`label.alt`). */
+export declare const altOf: (id: string) => string;
+/** The box around the letters, as a raw selector (`label.split`). */
+export declare const charsOf: (id: string) => string;
+/** One letter, as a raw selector (`label.split`). `--sx-btn-i` is its position. */
+export declare const charOf: (id: string) => string;
+/** The icon, as a raw selector. */
+export declare const iconOf: (id: string) => string;
+/** The part that moves, of a button wearing this effect, as a raw selector. */
+export declare const bodyOf: (id: string) => string;
+/** The part you see, of a button wearing this effect, as a raw selector. */
+export declare const faceOf: (id: string) => string;
+/** The element you click, as a raw selector. */
+export declare const hitOf: (id: string) => string;
+/** What shows in place of the label in one status, or any of them, as a raw selector (`label.status`, `labels`). */
+export declare const statusOf: (id: string, status?: ButtonStatus) => string;
+/**
+ * `target` while the button is in `state`; `"busy"` is any state but idle. `target` is a raw selector inside a button
+ * wearing this effect (`bodyOf(id)`), or the button itself (`hitOf(id)`).
+ */
+export declare function inState(id: string, state: ButtonStatus | "idle" | "busy", target: string): string;
+/** Wrap a raw selector. */
+export declare const at: (raw: string) => string;
+/** The easing most effects use. */
+export declare const EASE = "var(--ease-sx-out, ease-out)";
+/** A springy curve that overshoots and settles. */
+export declare const SPRING = "linear(0, 0.45 12%, 0.85 25%, 1.08 38%, 1.1 46%, 1.03 62%, 0.99 78%, 1)";
+/** A `transition` for one property, at an effect's duration (its `time` var). */
+export declare const timed: (id: string, property: string, ease?: string) => string;
+/** An animation that runs all the time or only while hovered: `"none"` until the hover rule names it. */
+export type ButtonTrigger = "hover" | "loop";
+/** What `target` looks like while the button is pressed. A press rule's transition stays under 100 ms (atlas rule 2). */
+export declare function whenPressed(id: string, target: string, body: string): string;
+/**
+ * What `target` looks like while the button is hovered or focused from the keyboard. `:hover` sits inside the media
+ * query, so a tap never leaves it stuck on a phone (atlas rule 1). `target` is a raw selector inside the button.
+ */
+export declare function whenOn(id: string, target: string, body: string): string;
+export interface ButtonParts {
+    readonly vars?: ButtonVars;
+    readonly layers?: readonly ButtonLayer[];
+    readonly claims?: readonly ButtonClaim[];
+    readonly needs?: ButtonNeeds;
+    /** The weakest device that runs it, as in the registry (tested). Default `"all"`. */
+    readonly tier?: ButtonTier;
+    /** At-rules that can't sit inside a layer (`@property`). */
+    readonly head?: string;
+    /** Rules that show a state, not a motion: they apply under reduced motion too. */
+    readonly state?: string;
+    readonly label?: ButtonLabelPlan;
+    readonly program?: ButtonProgram;
+    /** What a device below `tier` wears instead. Required for a `mid` / `high` effect (tested). */
+    readonly fallback?: ButtonEffect;
+}
+/**
+ * A button effect from its registry id, its rules and its parts. Rules go in `@layer components`. It doesn't read the
+ * registry: that would put every effect's label and description in the download of any page with one button.
+ */
+export declare function defineButton(id: string, css: string, parts?: ButtonParts): ButtonEffect;