@sharedex/ui 0.9.0 → 0.10.0

package/dist/forms/registry.js

@@ -0,0 +1,133 @@
+// ---------------------------------------------------------------------------
+// Every form effect's metadata, from the Form Effects Atlas and the rows found
+// online. 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/forms-atlas.mjs.
+// ---------------------------------------------------------------------------
+function row(id, label, group, fits, fires, tech, description, extra = {}) {
+    return { id, label, group, fits, fires, tech, tier: extra.tier ?? "all", description, ...(extra.limited ? { limited: extra.limited } : {}) };
+}
+const FIELD = ["field"];
+const CHECK = ["checkbox"];
+const RADIO = ["radio"];
+const SWITCH = ["switch"];
+const PICKER = ["picker"];
+const RANGE = ["range"];
+const CHIP = ["chip"];
+const FILE = ["file"];
+const STEPS = ["steps"];
+export const FORM_EFFECTS = [
+    row("inputFloat", "Floating label", "input", FIELD, ["focus", "typing"], "css", "The label sits in the field and moves up, smaller, on focus or once there is text."),
+    row("inputUnderline", "Underline grow", "input", FIELD, ["focus"], "css", "A line grows along the bottom edge on focus: from a side, the centre or where you clicked."),
+    row("inputDraw", "Border draw-around", "input", FIELD, ["focus"], "svg", "The outline draws itself around the field on focus."),
+    row("inputRise", "Background rise", "input", FIELD, ["focus"], "css", "A colour rises from the bottom and fills the field on focus."),
+    row("inputAside", "Label slides aside", "input", FIELD, ["focus", "typing"], "css", "The label's panel covers the field, then shrinks to its start side so you can type."),
+    row("inputWavy", "Wavy line", "input", FIELD, ["focus"], "svg", "The bottom line wobbles like jelly on focus, then settles flat."),
+    row("inputRing", "Focus glow ring", "input", FIELD, ["focus"], "css", "A soft ring grows out from the field, or shrinks onto it, on focus."),
+    row("inputSpotlight", "Spotlight on focus", "input", FIELD, ["focus"], "css", "The other fields of the form dim while one has the focus."),
+    row("inputIcon", "Icon reacts on focus", "input", FIELD, ["focus"], "css", "The field's icon takes the colour and grows a little on focus."),
+    row("inputSearch", "Expanding search", "input", FIELD, ["focus", "typing"], "css", "A search icon opens into a full field on focus, and closes again when left empty."),
+    row("inputNotch", "Notched outline", "input", FIELD, ["focus", "typing"], "css", "The label floats onto the border, which opens a gap for it."),
+    row("inputSwap", "Label text swap", "input", FIELD, ["focus"], "css", "The label's words roll up, and other words (or a coloured copy) roll in."),
+    row("inputFrame", "Frame split", "input", FIELD, ["focus"], "css", "Bars meet and slide apart to frame the field, or its two bracket halves pull apart."),
+    row("inputFlap", "Flap fold", "input", FIELD, ["focus"], "css", "A coloured flap swings down from the top edge on focus."),
+    row("inputFlood", "Icon flood", "input", FIELD, ["focus"], "css", "A circle grows out of the icon until it floods the field."),
+    row("inputWave", "Wave label", "input", FIELD, ["focus"], "css", "The label's letters hop up one after another on focus."),
+    row("inputBeam", "Border beam", "input", FIELD, ["focus", "idle"], "css", "A light with a tail runs around the edge while the field has focus, or all the time."),
+    row("inputDepth", "Depth sink / lift", "input", FIELD, ["focus"], "css", "The field sinks into the page, or lifts off a hard shadow, on focus."),
+    row("inputSkeleton", "Skeleton while loading", "input", FIELD, ["idle"], "css", "A shimmering placeholder covers the field while its value loads (`busy`)."),
+    row("inputCaret", "Caret shape and blink", "input", FIELD, ["focus"], "native", "A coloured caret, a block or underscore shape, a soft or steady blink.", {
+        limited: "caret-shape and caret-animation: Chrome only; other browsers keep the colour and their own caret.",
+    }),
+    row("inputCounter", "Character counter ring", "input", FIELD, ["typing"], "svg", "A ring fills as you type, turns amber near the limit and red past it (`counter`)."),
+    row("inputReveal", "Password reveal", "input", FIELD, ["change"], "svg", "The show-password eye blinks and is crossed out, or a flashlight beam lights the password (`reveal`)."),
+    row("inputStrength", "Strength meter fill", "input", FIELD, ["typing"], "css", "The strength meter's bars fill one after another, and the new word drops in (`strength`)."),
+    row("inputCycle", "Cycling placeholders + vanish", "input", FIELD, ["idle", "submit"], "js", "The empty field's placeholder cycles through phrases; the text you send breaks into dust and the field empties."),
+    row("validColor", "Red / green border", "valid", FIELD, ["validate"], "css", "The border turns red when the field is wrong and green when it is right, once the user has left it."),
+    row("validShake", "Shake on error", "valid", FIELD, ["validate", "submit"], "css", "The field shakes when it turns wrong, and again when the user is sent back to it."),
+    row("validMessage", "Error message slide-down", "valid", FIELD, ["validate"], "css", "The error slides down under the field as its row opens smoothly."),
+    row("validCheck", "Check draws in", "valid", FIELD, ["validate"], "svg", "A check mark draws itself at the end of the field once it is right."),
+    row("validSwap", "Help → error swap", "valid", FIELD, ["validate"], "css", "The help text rolls away and the error rolls into its place."),
+    row("validBubble", "Anchored error bubble", "valid", FIELD, ["validate"], "css", "The error pops up in a bubble tied to the field, over the page, so nothing moves.", {
+        limited: "anchor positioning: without it the bubble sits under the whole field.",
+    }),
+    row("validFlash", "Flash the first error", "valid", FIELD, ["submit"], "css", "The field blinks twice when the user is sent to it (`focusFirstError`, `ErrorSummary`)."),
+    row("validAsync", "Async check mark", "valid", FIELD, ["validate"], "svg", "The async check's spinner closes into a ring and a check or a cross draws inside (`status`)."),
+    row("checkDraw", "Check mark draw", "check", CHECK, ["change"], "svg", "The tick draws itself into the box, a moment after the box fills."),
+    row("checkPop", "Scale pop", "check", CHECK, ["change"], "css", "The box squeezes while pressed and springs back; the tick grows in."),
+    row("checkMorph", "Box → tick morph", "check", CHECK, ["change"], "svg", "The box's outline runs off and folds into the tick: one line becomes the other."),
+    row("checkJelly", "Jelly bounce", "check", CHECK, ["change"], "css", "The box wobbles like jelly when checked by hand."),
+    row("checkScribble", "Hand-drawn scribble", "check", CHECK, ["change"], "svg", "A loose hand-drawn tick, or a cross, scribbles itself over the box."),
+    row("checkStrike", "To-do strikethrough", "check", CHECK, ["change"], "css", "A line strikes the words through and they go quiet; or the box flattens into the line."),
+    row("checkMixed", "Indeterminate dash", "check", CHECK, ["change"], "css", "The mixed dash grows out from the middle and gives way to the tick."),
+    row("checkCard", "Selectable card", "check", CHECK, ["change"], "css", "The option is a card holding box, words and help, lit when checked."),
+    row("checkConfetti", "Confetti on check", "check", CHECK, ["change"], "canvas", "Confetti bursts from the box when it is checked by hand (the page's one burst canvas)."),
+    row("checkRipple", "State layer and ripple", "check", CHECK, ["focus", "change"], "css", "A soft disc behind the box answers the mouse, the keyboard's focus and a press."),
+    row("checkHeart", "Heart like with burst", "check", CHECK, ["change"], "svg", "The box is a heart: liked, it fills, pops and throws a ring of dots."),
+    row("checkMerge", "Merging neighbours", "check", CHECK, ["change"], "css", "Checked neighbours' highlights join into one block."),
+    row("radioDot", "Dot scale-in", "radio", RADIO, ["change"], "css", "The dot springs in on the chosen radio and shrinks away on the one left."),
+    row("radioPulse", "Ring pulse", "radio", RADIO, ["change"], "css", "A ring pulses out once from the radio the user chose."),
+    row("radioCircle", "Hand-drawn circle", "radio", RADIO, ["change"], "svg", "A pen circles the chosen option's words."),
+    row("radioSegment", "Segmented control", "radio", RADIO, ["change"], "css", "Options in a tray, a thumb sliding under the chosen one."),
+    row("radioCard", "Radio cards", "radio", RADIO, ["change"], "css", "Each option is a card holding circle, words and help; the chosen one lit."),
+    row("radioStars", "Star rating", "radio", RADIO, ["change"], "svg", "Stars fill up to the choice; half stars, a wave under the mouse, a burst of sparks."),
+    row("radioEmoji", "Emoji rating", "radio", RADIO, ["change"], "svg", "Five faces, frown to smile: the chosen one lights up and wobbles."),
+    row("radioTravel", "Travelling dot", "radio", RADIO, ["change"], "css", "One dot travels from the old choice to the new one.", {
+        limited: "anchor positioning: Firefox moves the dot at once; without it, each circle keeps its own dot.",
+    }),
+    row("radioUnderline", "Tab underline", "radio", RADIO, ["change"], "css", "Tabs: an underline follows the chosen option.", {
+        limited: "anchor positioning: Firefox moves the line at once; without it, the chosen tab is underlined on its own.",
+    }),
+    row("radioScale", "NPS 0-10 scale", "radio", RADIO, ["change"], "css", "Numbered cells, the chosen one filled; groups marked by a quiet bar."),
+    row("switchSlide", "iOS-style slide", "switch", SWITCH, ["change"], "css", "The thumb slides across with a little overshoot."),
+    row("switchStretch", "Thumb stretch", "switch", SWITCH, ["change"], "css", "The thumb stretches toward the other side while pressed, then springs back."),
+    row("switchDayNight", "Day / night toggle", "switch", SWITCH, ["change"], "css", "The sun turns into a moon, clouds drift off and stars come out."),
+    row("switchBulb", "Light bulb", "switch", SWITCH, ["change"], "svg", "The thumb is a bulb: on, it lights up, catching with a stutter, and glows."),
+    row("switchNeon", "Neon switch", "switch", SWITCH, ["change", "idle"], "css", "A neon tube strikes with a flicker, then hums (an endless glow: it pauses off screen)."),
+    row("switchFlip", "3D coin flip", "switch", SWITCH, ["change"], "css", "The thumb is a coin that turns over: a cross on one face, a tick on the other."),
+    row("switchMorph", "Shape-morph thumb", "switch", SWITCH, ["change"], "css", "The thumb morphs from a circle into a rounded square, turning as it crosses."),
+    row("switchGoo", "Gooey switch", "switch", SWITCH, ["change"], "svg", "The thumb is a drop that stretches into a bridge and snaps round on the other side.", { tier: "mid" }),
+    row("switchFace", "Character switch", "switch", SWITCH, ["change"], "svg", "A sleeping face wakes up when switched on: eyes open, a smile, a blink."),
+    row("switchIcon", "Thumb grows with ✓ / ✗", "switch", SWITCH, ["change"], "css", "The thumb grows when on and shows a tick; off, it shrinks and shows a cross."),
+    row("switchLabels", "ON / OFF in the track", "switch", SWITCH, ["change"], "css", "A short word inside the track on the side the thumb has left."),
+    row("pickerArrow", "Arrow rotate on open", "select", PICKER, ["focus"], "css", "The arrow turns over while the list is open, and back when it closes."),
+    row("pickerOpen", "Popover fade / scale / unroll", "select", PICKER, ["focus"], "css", "The list grows, fades or unrolls into view as it opens, and back as it closes.", {
+        limited: "a Select's own list only where it can be styled (appearance: base-select, Chrome 135+, Safari 27); a Combobox everywhere. Firefox shows a list that flips above at once.",
+    }),
+    row("pickerStagger", "Staggered options", "select", PICKER, ["focus"], "css", "The options drop into the list one after another as it opens.", {
+        limited: "a Select's options need sibling-index() and a stylable list; elsewhere they arrive together.",
+    }),
+    row("listHighlight", "Highlight slide", "select", PICKER, ["typing"], "css", "One highlight slides from option to option as you move through the list. A Combobox's only.", {
+        limited: "anchor positioning: Firefox moves the highlight at once; without it, each option lights on its own.",
+    }),
+    row("chipPop", "Chips pop in and out", "select", PICKER, ["change"], "css", "Chips pop in when picked and shrink away when removed; the others glide into place. A Combobox's only."),
+    row("pickerCheck", "Option checkmark", "select", PICKER, ["change"], "svg", "The chosen option's tick draws itself in, at the end of the option."),
+    row("pickerSheet", "Bottom sheet on phones", "select", PICKER, ["focus"], "css", "On a phone the list docks at the bottom of the screen and slides up, within reach of a thumb."),
+    row("listMatch", "Typed text marked", "select", PICKER, ["typing"], "js", "The typed text is marked inside each option as you filter (the Custom Highlight API). A Combobox's only."),
+    row("rangeThumb", "Thumb grow on drag", "range", RANGE, ["drag"], "css", "The thumb grows under the finger, with a soft halo round it."),
+    row("rangeFill", "Filled track", "range", RANGE, ["drag"], "css", "The rail fills up to the thumb, or between the two thumbs."),
+    row("rangeBubble", "Value bubble", "range", RANGE, ["drag"], "css", "A bubble above the thumb shows the value while you drag (or always)."),
+    row("rangeElastic", "Elastic slider", "range", RANGE, ["drag"], "js", "Pull past the end and the rail stretches after the finger, then springs back."),
+    row("rangeTicks", "Snap ticks", "range", RANGE, ["drag"], "css", "Ticks under the rail, one per step; the thumb springs from tick to tick."),
+    row("rangeFace", "Face slider", "range", RANGE, ["drag"], "svg", "The thumb is a face that frowns at the low end and smiles at the high end."),
+    row("rangeHistogram", "Histogram range", "range", RANGE, ["drag"], "svg", "Bars above the rail show how the values spread; the chosen stretch lights up.", {
+        limited: "across only: an upright Range hides the bars.",
+    }),
+    row("chipCheck", "Filter chip check slides in", "select", CHIP, ["change"], "css", "A chip's check slides in from its start as it turns on, the words making room, and its tick draws."),
+    row("chipMerge", "Merging filter chips", "select", CHIP, ["change"], "css", "Chips that are on next to each other merge into one block: the gap fills, the corners that meet square off."),
+    row("fileDrag", "Drag-over highlight", "file", FILE, ["drag"], "css", "While files are dragged over the zone it takes a tint, grows a little and its icon hops; red for files it won't take."),
+    row("fileButton", "Styled file button", "file", FILE, ["change"], "css", "The browser's own file button, dressed as a solid pill that lifts on hover and dips on a press."),
+    row("fileCards", "File cards + micro interactions", "file", FILE, ["change"], "css", "Cards rise in as files are added, slide out when removed, and the others glide into place."),
+    row("fileProgress", "Upload progress", "file", FILE, ["submit"], "css", "Each file's upload fills a bar (or a ring) smoothly, ending in a check that draws itself."),
+    row("filePreview", "Image preview fade-in", "file", FILE, ["change"], "css", "Image files show a thumbnail in their card, fading in once it has loaded."),
+    row("filePage", "Page-wide drop overlay", "file", FILE, ["drag"], "css", "The page-wide drop overlay (`page`) fades in, its dashed frame settling and its words rising."),
+    row("fileReject", "Reject shake", "file", FILE, ["drag"], "css", "A refused file shakes the zone and turns its line red; so do files it won't take, while dragged over it."),
+    row("stepSlide", "Step slide (next / back)", "flow", STEPS, ["submit"], "css", "Steps slide in from the end and out toward the start (back the other way), or rise and fall one question at a time."),
+    row("stepProgress", "Progress stepper", "flow", STEPS, ["submit"], "css", "The progress rail fills smoothly, finished steps' checks draw themselves, the new current step pops."),
+];
+export const FORM_IDS = new Set(FORM_EFFECTS.map((m) => m.id));
+export function formMetaOf(id) {
+    const meta = FORM_EFFECTS.find((m) => m.id === id);
+    if (!meta)
+        throw new Error(`[@sharedex/ui] unknown form effect "${id}"`);
+    return meta;
+}

package/dist/forms/reveal.d.ts

@@ -0,0 +1,6 @@
+export declare const REVEAL_CSS = "@layer theme, base, components, utilities;\n@layer components {\n  :where([data-sx-reveal]) {\n    display: grid;\n    grid-template-rows: 0fr;\n    min-inline-size: 0;\n  }\n  :where([data-sx-reveal][data-sx-open]) {\n    grid-template-rows: 1fr;\n  }\n  :where([data-sx-reveal-body]) {\n    display: grid;\n    gap: 1rem;\n    min-block-size: 0;\n    min-inline-size: 0;\n    margin: 0;\n    padding: 0;\n    border: 0;\n    overflow: hidden;\n  }\n  :where([data-sx-reveal][data-sx-open] > [data-sx-reveal-body]) {\n    overflow: visible;\n  }\n  :where([data-sx-reveal-body] > legend) {\n    padding: 0;\n  }\n}";
+/**
+ * What moves: the row eases open and shut (the one repaint it needs), the fields fade in from a little above. The body
+ * clips while it moves and lets focus rings out once open (overflow flips at the end, as a discrete transition).
+ */
+export declare const REVEAL_MOTION = "@layer components {\n  :where([data-sx-reveal]) {\n    transition: grid-template-rows 0.3s var(--ease-sx-out, ease-out);\n  }\n  :where([data-sx-reveal-body]) {\n    transition: opacity 0.25s ease-out, translate 0.3s var(--ease-sx-out, ease-out), overflow 0s;\n    transition-behavior: allow-discrete;\n  }\n  :where([data-sx-reveal]:not([data-sx-open]) > [data-sx-reveal-body]) {\n    translate: 0 -0.5rem;\n    opacity: 0;\n  }\n  :where([data-sx-reveal][data-sx-open] > [data-sx-reveal-body]) {\n    transition-delay: 0s, 0s, 0.3s;\n  }\n}";

package/dist/forms/reveal.js

@@ -0,0 +1,51 @@
+// The sheets of FormReveal: fields that open below a choice. A grid row that grows from 0fr to 1fr round a fieldset
+// that is disabled (and inert) while closed, so its fields are neither submitted nor checked until they show. Pure strings.
+import { LAYER_ORDER } from "../backgrounds/runtime/rootCss.js";
+const OPEN = "[data-sx-reveal][data-sx-open]";
+export const REVEAL_CSS = `${LAYER_ORDER}
+@layer components {
+  :where([data-sx-reveal]) {
+    display: grid;
+    grid-template-rows: 0fr;
+    min-inline-size: 0;
+  }
+  :where(${OPEN}) {
+    grid-template-rows: 1fr;
+  }
+  :where([data-sx-reveal-body]) {
+    display: grid;
+    gap: 1rem;
+    min-block-size: 0;
+    min-inline-size: 0;
+    margin: 0;
+    padding: 0;
+    border: 0;
+    overflow: hidden;
+  }
+  :where(${OPEN} > [data-sx-reveal-body]) {
+    overflow: visible;
+  }
+  :where([data-sx-reveal-body] > legend) {
+    padding: 0;
+  }
+}`;
+/**
+ * What moves: the row eases open and shut (the one repaint it needs), the fields fade in from a little above. The body
+ * clips while it moves and lets focus rings out once open (overflow flips at the end, as a discrete transition).
+ */
+export const REVEAL_MOTION = `@layer components {
+  :where([data-sx-reveal]) {
+    transition: grid-template-rows 0.3s var(--ease-sx-out, ease-out);
+  }
+  :where([data-sx-reveal-body]) {
+    transition: opacity 0.25s ease-out, translate 0.3s var(--ease-sx-out, ease-out), overflow 0s;
+    transition-behavior: allow-discrete;
+  }
+  :where([data-sx-reveal]:not([data-sx-open]) > [data-sx-reveal-body]) {
+    translate: 0 -0.5rem;
+    opacity: 0;
+  }
+  :where(${OPEN} > [data-sx-reveal-body]) {
+    transition-delay: 0s, 0s, 0.3s;
+  }
+}`;

package/dist/forms/runtime/focus.d.ts

@@ -0,0 +1,16 @@
+/** Marks the control's field `data-sx-flash` for one flash, restarting it when it is already flashing. */
+export declare function flashField(control: Element): void;
+/** Scrolls a control to the middle of the screen (no glide under reduced motion), focuses it and flashes its field. */
+export declare function goToField(control: HTMLElement, flash?: boolean): void;
+/**
+ * After a failed submit: moves the focus to the first wrong field (in page order), scrolled to the middle of the
+ * screen, and flashes it. It waits two frames first, so the `aria-invalid` your app just set is on the page. Resolves
+ * to the control, or `null` when nothing is wrong.
+ *
+ * ```ts
+ * const onSubmit = form.handleSubmit(save, () => focusFirstError(formRef.current));
+ * ```
+ */
+export declare function focusFirstError(within?: ParentNode | null, options?: {
+    readonly flash?: boolean;
+}): Promise<HTMLElement | null>;

package/dist/forms/runtime/focus.js

@@ -0,0 +1,55 @@
+// Sending the user to a field: scroll it to the middle of the screen, move the focus there, and flash it once
+// (`validFlash`, `validShake` play on `data-sx-flash`). Plain functions, no React: `focusFirstError` is called from a
+// submit handler. Safe to import on the server: nothing runs until it is called.
+const FLASH_MS = 1200;
+const timers = new WeakMap();
+/** Marks the control's field `data-sx-flash` for one flash, restarting it when it is already flashing. */
+export function flashField(control) {
+    const root = control.closest("[data-sx-field]");
+    if (!root)
+        return;
+    root.removeAttribute("data-sx-flash");
+    // read a size so the browser sees the attribute go, and plays the animation again when it comes back
+    void root.offsetWidth;
+    root.setAttribute("data-sx-flash", "");
+    clearTimeout(timers.get(root));
+    timers.set(root, setTimeout(() => root.removeAttribute("data-sx-flash"), FLASH_MS));
+}
+/** Scrolls a control to the middle of the screen (no glide under reduced motion), focuses it and flashes its field. */
+export function goToField(control, flash = true) {
+    const still = typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
+    control.scrollIntoView({ block: "center", behavior: still ? "auto" : "smooth" });
+    control.focus({ preventScroll: true });
+    if (flash)
+        flashField(control);
+}
+/** The app said it's wrong, or the browser did once the user had a go at it. Never `:invalid`: an untouched field isn't. */
+const WRONG = '[aria-invalid="true"], input:user-invalid, textarea:user-invalid, select:user-invalid';
+const frame = () => new Promise((resolve) => requestAnimationFrame(() => resolve()));
+/**
+ * After a failed submit: moves the focus to the first wrong field (in page order), scrolled to the middle of the
+ * screen, and flashes it. It waits two frames first, so the `aria-invalid` your app just set is on the page. Resolves
+ * to the control, or `null` when nothing is wrong.
+ *
+ * ```ts
+ * const onSubmit = form.handleSubmit(save, () => focusFirstError(formRef.current));
+ * ```
+ */
+export async function focusFirstError(within, options = {}) {
+    if (typeof document === "undefined")
+        return null;
+    await frame();
+    await frame();
+    const scope = within ?? document;
+    let control;
+    try {
+        control = scope.querySelector(WRONG);
+    }
+    catch {
+        // a browser without :user-invalid
+        control = scope.querySelector('[aria-invalid="true"]');
+    }
+    if (control)
+        goToField(control, options.flash !== false);
+    return control;
+}

package/dist/forms/runtime/listMatch.d.ts

@@ -0,0 +1,2 @@
+/** Replaces this list's marked ranges with the places `query` appears in its options' words. Returns the new ranges. */
+export declare function markMatches(list: HTMLElement | null, query: string, previous: readonly Range[]): Range[];

package/dist/forms/runtime/listMatch.js

@@ -0,0 +1,33 @@
+// Marks the typed text inside a combobox's options with the Custom Highlight API: no extra elements, no re-render, and
+// the option's words stay one text node for screen readers. One highlight (`sx-list-match`) serves every combobox on the
+// page; each adds its own ranges and takes them back. A browser without the API marks nothing.
+let shared = null;
+/** Replaces this list's marked ranges with the places `query` appears in its options' words. Returns the new ranges. */
+export function markMatches(list, query, previous) {
+    if (typeof Highlight === "undefined" || typeof CSS === "undefined" || !("highlights" in CSS))
+        return [];
+    if (!shared) {
+        shared = new Highlight();
+        CSS.highlights.set("sx-list-match", shared);
+    }
+    for (const range of previous)
+        shared.delete(range);
+    const needle = query.trim().toLowerCase();
+    if (!list || !needle)
+        return [];
+    const ranges = [];
+    for (const words of list.querySelectorAll("[data-sx-option-text]")) {
+        const walk = document.createTreeWalker(words, NodeFilter.SHOW_TEXT);
+        for (let node = walk.nextNode(); node; node = walk.nextNode()) {
+            const hay = node.data.toLowerCase();
+            for (let at = hay.indexOf(needle); at !== -1; at = hay.indexOf(needle, at + needle.length)) {
+                const range = new Range();
+                range.setStart(node, at);
+                range.setEnd(node, at + needle.length);
+                ranges.push(range);
+                shared.add(range);
+            }
+        }
+    }
+    return ranges;
+}

package/dist/forms/runtime/origin.d.ts

@@ -0,0 +1,10 @@
+/** The press's position across the box, 0 (left edge) to 1 (right edge). Pure; tested. */
+export declare function originOf(clientX: number, rect: {
+    readonly left: number;
+    readonly width: number;
+}): number;
+/**
+ * Writes `--sx-field-ox` on `root` on each press inside `box`, and removes it when the field loses the focus, so the
+ * next keyboard focus grows from the effect's own default. Returns what stops it.
+ */
+export declare function attachOrigin(root: HTMLElement, box: HTMLElement): () => void;

package/dist/forms/runtime/origin.js

@@ -0,0 +1,25 @@
+// Where a field was pressed, for effects that grow from that point (`inputUnderline({ from: "pointer" })`). Plain
+// module: one listener on the box, attached only while such an effect is on the field.
+/** The press's position across the box, 0 (left edge) to 1 (right edge). Pure; tested. */
+export function originOf(clientX, rect) {
+    if (rect.width <= 0)
+        return 0.5;
+    return Math.min(1, Math.max(0, (clientX - rect.left) / rect.width));
+}
+/**
+ * Writes `--sx-field-ox` on `root` on each press inside `box`, and removes it when the field loses the focus, so the
+ * next keyboard focus grows from the effect's own default. Returns what stops it.
+ */
+export function attachOrigin(root, box) {
+    const press = (event) => root.style.setProperty("--sx-field-ox", String(originOf(event.clientX, box.getBoundingClientRect())));
+    const leave = (event) => {
+        if (!root.contains(event.relatedTarget))
+            root.style.removeProperty("--sx-field-ox");
+    };
+    box.addEventListener("pointerdown", press);
+    root.addEventListener("focusout", leave);
+    return () => {
+        box.removeEventListener("pointerdown", press);
+        root.removeEventListener("focusout", leave);
+    };
+}

package/dist/forms/runtime/placePopup.d.ts

@@ -0,0 +1,10 @@
+/** Starts placing `popup` against `box`. Returns what stops it. */
+export declare function placeByHand(popup: HTMLElement, box: HTMLElement): () => void;
+/**
+ * A popup docked at the bottom of a phone's screen (`pickerSheet`, which sets `--sx-picker-docked: 1` there) must not
+ * cover the box being typed into, nor sit behind the on-screen keyboard (a phone shrinks only the visible part of the
+ * page for it, so `bottom: 0` is behind the keys). So, while it is open: the box scrolls to the top of the screen once,
+ * the keyboard's height goes in `--sx-picker-keyboard`, and the room left between the box and the keyboard in
+ * `--sx-picker-room`, which caps the sheet. Elsewhere it does nothing. Returns what stops it.
+ */
+export declare function dockSheet(popup: HTMLElement, box: HTMLElement): () => void;

package/dist/forms/runtime/placePopup.js

@@ -0,0 +1,55 @@
+// Places a combobox's popup by hand in a browser without anchor positioning: under the box, as wide as it, flipped
+// above when the screen has no room below, kept in place on scroll and resize. Where anchor positioning exists (every
+// current engine), CSS does it all and this does nothing.
+/** Starts placing `popup` against `box`. Returns what stops it. */
+export function placeByHand(popup, box) {
+    if (typeof CSS === "undefined" || CSS.supports("position-area: block-end"))
+        return () => { };
+    const place = () => {
+        const r = box.getBoundingClientRect();
+        const high = popup.offsetHeight;
+        const below = innerHeight - r.bottom;
+        const up = below < high + 8 && r.top > below;
+        Object.assign(popup.style, {
+            position: "fixed",
+            margin: "0",
+            left: `${r.left}px`,
+            width: `${r.width}px`,
+            top: `${up ? r.top - high - 4 : r.bottom + 4}px`,
+        });
+    };
+    place();
+    addEventListener("scroll", place, true);
+    addEventListener("resize", place);
+    return () => {
+        removeEventListener("scroll", place, true);
+        removeEventListener("resize", place);
+    };
+}
+/**
+ * A popup docked at the bottom of a phone's screen (`pickerSheet`, which sets `--sx-picker-docked: 1` there) must not
+ * cover the box being typed into, nor sit behind the on-screen keyboard (a phone shrinks only the visible part of the
+ * page for it, so `bottom: 0` is behind the keys). So, while it is open: the box scrolls to the top of the screen once,
+ * the keyboard's height goes in `--sx-picker-keyboard`, and the room left between the box and the keyboard in
+ * `--sx-picker-room`, which caps the sheet. Elsewhere it does nothing. Returns what stops it.
+ */
+export function dockSheet(popup, box) {
+    const view = typeof visualViewport === "undefined" ? null : visualViewport;
+    if (!view || getComputedStyle(popup).getPropertyValue("--sx-picker-docked").trim() !== "1")
+        return () => { };
+    box.scrollIntoView({ block: "start", behavior: "instant" });
+    const place = () => {
+        const keys = Math.max(0, innerHeight - view.height - view.offsetTop);
+        popup.style.setProperty("--sx-picker-keyboard", `${keys}px`);
+        popup.style.setProperty("--sx-picker-room", `${Math.max(160, innerHeight - keys - box.getBoundingClientRect().bottom - 8)}px`);
+    };
+    place();
+    view.addEventListener("resize", place);
+    view.addEventListener("scroll", place);
+    addEventListener("scroll", place, true);
+    return () => {
+        view.removeEventListener("resize", place);
+        view.removeEventListener("scroll", place);
+        removeEventListener("scroll", place, true);
+    };
+}

package/dist/forms/runtime/useFlip.d.ts

@@ -0,0 +1,7 @@
+import { type RefObject } from "react";
+/**
+ * FLIP for a row of items keyed by `data-key` (a combobox's chips): after each render, an item that moved starts where
+ * it was (an inline `translate` with no transition) and, one frame later, glides to its new place through the
+ * transition an effect gives it (`chipPop`). Items leaving (`data-sx-leaving`) stay put. Off unless `enabled`.
+ */
+export declare function useFlip(container: RefObject<HTMLElement | null>, enabled: boolean, selector: string): void;

package/dist/forms/runtime/useFlip.js

@@ -0,0 +1,38 @@
+"use client";
+import { useLayoutEffect, useRef } from "react";
+/**
+ * FLIP for a row of items keyed by `data-key` (a combobox's chips): after each render, an item that moved starts where
+ * it was (an inline `translate` with no transition) and, one frame later, glides to its new place through the
+ * transition an effect gives it (`chipPop`). Items leaving (`data-sx-leaving`) stay put. Off unless `enabled`.
+ */
+export function useFlip(container, enabled, selector) {
+    const last = useRef(new Map());
+    useLayoutEffect(() => {
+        const root = container.current;
+        if (!root || !enabled)
+            return;
+        const now = new Map();
+        for (const item of root.querySelectorAll(selector)) {
+            const key = item.dataset.key;
+            if (!key)
+                continue;
+            const rect = item.getBoundingClientRect();
+            now.set(key, rect);
+            const before = last.current.get(key);
+            if (!before || item.hasAttribute("data-sx-leaving"))
+                continue;
+            const dx = before.left - rect.left;
+            const dy = before.top - rect.top;
+            if (!dx && !dy)
+                continue;
+            item.style.transition = "none";
+            item.style.translate = `${dx}px ${dy}px`;
+            void item.offsetWidth;
+            requestAnimationFrame(() => {
+                item.style.transition = "";
+                item.style.translate = "";
+            });
+        }
+        last.current = now;
+    });
+}

package/dist/forms/runtime/useMorph.d.ts

@@ -0,0 +1,8 @@
+import { type RefObject } from "react";
+/**
+ * A box that eases from its old height to its new one when `key` changes (a step, a swapped view), instead of jumping:
+ * the old height is kept from the last commit (and from a ResizeObserver as the content changes in between), the box
+ * is held there before the browser paints, then let go to the new height through a transition of `block-size`, the one
+ * repaint the plan allows for this. Nothing under reduced motion, or with `on` false.
+ */
+export declare function useMorph(ref: RefObject<HTMLElement | null>, key: unknown, on: boolean): void;

package/dist/forms/runtime/useMorph.js

@@ -0,0 +1,56 @@
+"use client";
+import { useEffect, useLayoutEffect, useRef } from "react";
+import { stillMotion } from "../../buttons/runtime/press.js";
+/**
+ * A box that eases from its old height to its new one when `key` changes (a step, a swapped view), instead of jumping:
+ * the old height is kept from the last commit (and from a ResizeObserver as the content changes in between), the box
+ * is held there before the browser paints, then let go to the new height through a transition of `block-size`, the one
+ * repaint the plan allows for this. Nothing under reduced motion, or with `on` false.
+ */
+export function useMorph(ref, key, on) {
+    const last = useRef(0);
+    const busy = useRef(false);
+    useLayoutEffect(() => {
+        const el = ref.current;
+        if (!el)
+            return;
+        const to = el.offsetHeight;
+        const from = last.current;
+        last.current = to;
+        if (!on || !from || Math.abs(to - from) < 2 || stillMotion())
+            return;
+        busy.current = true;
+        el.style.overflow = "clip";
+        el.style.blockSize = `${from}px`;
+        void el.offsetHeight;
+        el.style.transition = "block-size var(--sx-morph-time, 0.32s) var(--ease-sx-out, ease-out)";
+        el.style.blockSize = `${to}px`;
+        let timer = 0;
+        const done = (e) => {
+            if (e && (e.target !== el || e.propertyName !== "block-size"))
+                return;
+            window.clearTimeout(timer);
+            el.removeEventListener("transitionend", done);
+            el.style.blockSize = "";
+            el.style.transition = "";
+            el.style.overflow = "";
+            busy.current = false;
+            last.current = el.offsetHeight;
+        };
+        el.addEventListener("transitionend", done);
+        timer = window.setTimeout(done, 700);
+        return () => done();
+    }, [key]); // eslint-disable-line react-hooks/exhaustive-deps
+    // the content grows and shrinks between changes (a message opens, a textarea grows): keep the height fresh
+    useEffect(() => {
+        const el = ref.current;
+        if (!el || typeof ResizeObserver === "undefined")
+            return;
+        const watch = new ResizeObserver(() => {
+            if (!busy.current)
+                last.current = el.offsetHeight;
+        });
+        watch.observe(el);
+        return () => watch.disconnect();
+    }, [ref]);
+}

package/dist/forms/runtime/useOffScreen.d.ts

@@ -0,0 +1,3 @@
+import { type RefObject } from "react";
+/** Marks a control `data-sx-field-off` while it is off screen, so CSS pauses its endless effects. */
+export declare function useOffScreen(ref: RefObject<HTMLElement | null>, enabled: boolean): void;

package/dist/forms/runtime/useOffScreen.js

@@ -0,0 +1,16 @@
+"use client";
+import { useEffect } from "react";
+/** Marks a control `data-sx-field-off` while it is off screen, so CSS pauses its endless effects. */
+export function useOffScreen(ref, enabled) {
+    useEffect(() => {
+        const el = ref.current;
+        if (!el || !enabled || typeof IntersectionObserver === "undefined")
+            return;
+        const io = new IntersectionObserver((entries) => {
+            for (const entry of entries)
+                el.toggleAttribute("data-sx-field-off", !entry.isIntersecting);
+        });
+        io.observe(el);
+        return () => io.disconnect();
+    }, [ref, enabled]);
+}

package/dist/forms/runtime/useSwitchDrag.d.ts

@@ -0,0 +1,8 @@
+import { type RefObject } from "react";
+/**
+ * Drag a switch's thumb with a finger or the mouse; let go past halfway and it toggles, short of it and it snaps back.
+ * A tap still toggles as always, and the value still commits on the click, never on the press: the drag only decides
+ * whether that click goes through. While dragging, the root carries `data-sx-dragging` and `--sx-switch-drag` (0-1),
+ * which the base sheet turns into the thumb's place.
+ */
+export declare function useSwitchDrag(root: RefObject<HTMLElement | null>, enabled: boolean): void;