@sharedex/ui 0.0.0-stage → 0.10.0

package/dist/forms/range.js

@@ -0,0 +1,223 @@
+// The structural sheet of Range: the head (label, value), the drawn rail and thumbs, and the real range inputs on top at
+// opacity 0, their own thumbs the same size as the drawn ones so a press lands where it looks. One or two thumbs,
+// across or upright. Positioning only; the look is styles/form.css. The thumbs and the rail's layers glide to a new value
+// (a key, a click on the rail) and follow a drag at once; effects tune that through variables, never `transition`:
+// `--sx-range-glide`, `--sx-range-drag-glide` (ticks spring from step to step), `--sx-range-grow` (a thumb's scale).
+import { LAYER_ORDER } from "../backgrounds/runtime/rootCss.js";
+const CONTROL = "[data-sx-range-control]";
+const THUMB = "[data-sx-range-thumb]";
+const TRACK = "[data-sx-range-track]";
+const UPRIGHT = "[data-sx-vertical]";
+const SPRING = "linear(0, 0.45 12%, 0.85 25%, 1.08 38%, 1.1 46%, 1.03 62%, 0.99 78%, 1)";
+/** The real thumbs, one rule per engine: a browser drops a whole selector list that names another engine's part. */
+const NATIVE = ["::-webkit-slider-thumb", "::-moz-range-thumb"];
+/** How many gaps an auto tick row (`rangeTicks`) shows: every step up to 20, else the largest count up to 20 that lands on steps. */
+export function autoTicks(steps) {
+    if (!Number.isFinite(steps) || steps <= 0)
+        return 1;
+    const whole = Math.round(steps);
+    if (whole <= 20)
+        return whole;
+    for (let n = 20; n >= 2; n--)
+        if (whole % n === 0)
+            return n;
+    return 10;
+}
+export const RANGE_BASE_CSS = `${LAYER_ORDER}
+@layer components {
+  :where([data-sx-range]) {
+    --sx-form-dir: 1;
+    --sx-range-thumb: 1.25rem;
+    --sx-range-h: 0.375rem;
+    --sx-range-length: 10rem;
+    display: grid;
+    grid-template-columns: minmax(0, 1fr);
+    grid-template-areas: "head" "box" "description" "message";
+    align-content: start;
+    min-inline-size: 0;
+    position: relative;
+    isolation: isolate;
+  }
+  :where([data-sx-range]:dir(rtl)) {
+    --sx-form-dir: -1;
+  }
+  :where([data-sx-range-head]) {
+    grid-area: head;
+    display: flex;
+    align-items: baseline;
+    justify-content: space-between;
+    gap: 0.75rem;
+    margin-block-end: 0.5rem;
+  }
+  :where([data-sx-range-output]) {
+    font-variant-numeric: tabular-nums;
+  }
+  :where([data-sx-range-box]) {
+    grid-area: box;
+    position: relative;
+    container-type: inline-size;
+    block-size: max(1.5rem, var(--sx-range-thumb));
+    min-inline-size: 0;
+    touch-action: pan-y;
+  }
+  :where(${TRACK}) {
+    position: absolute;
+    inset-inline: calc(var(--sx-range-thumb) / 2);
+    inset-block: 0;
+    margin-block: auto;
+    block-size: var(--sx-range-h);
+    border-radius: 999px;
+    pointer-events: none;
+  }
+  :where(${TRACK} > [data-sx-choice-layer]) {
+    position: absolute;
+    pointer-events: none;
+  }
+  :where(${THUMB}) {
+    position: absolute;
+    inset-inline-start: 0;
+    inset-block: 0;
+    margin-block: auto;
+    display: grid;
+    place-items: center;
+    inline-size: var(--sx-range-thumb);
+    block-size: var(--sx-range-thumb);
+    box-sizing: border-box;
+    border-radius: 50%;
+    pointer-events: none;
+    translate: calc((var(--sx-at) * (100cqi - var(--sx-range-thumb)) + var(--sx-range-pull, 0px)) * var(--sx-form-dir)) 0;
+  }
+  :where(${THUMB} > [data-sx-choice-layer]) {
+    position: absolute;
+    pointer-events: none;
+  }
+  :where([data-sx-range-says]) {
+    display: none;
+  }
+  :where(${CONTROL}) {
+    position: absolute;
+    inset: 0;
+    z-index: 1;
+    inline-size: 100%;
+    block-size: 100%;
+    margin: 0;
+    padding: 0;
+    opacity: 0;
+    appearance: none;
+    background: transparent;
+    cursor: pointer;
+  }
+  :where(${CONTROL}:disabled) {
+    cursor: not-allowed;
+  }
+${NATIVE.map((part) => `  :where(${CONTROL})${part} {
+    appearance: none;
+    inline-size: var(--sx-range-thumb);
+    block-size: var(--sx-range-thumb);
+    border: 0;
+    border-radius: 50%;
+  }`).join("\n")}
+  :where([data-sx-dual] ${CONTROL}) {
+    pointer-events: none;
+  }
+${NATIVE.map((part) => `  :where([data-sx-dual] ${CONTROL})${part} {
+    pointer-events: auto;
+  }`).join("\n")}
+  :where([data-sx-dual][data-sx-top="a"] ${CONTROL}[data-sx-thumb="a"]) {
+    z-index: 2;
+  }
+  :where([data-sx-range]:has(${CONTROL}[data-sx-thumb="a"]:focus-visible) ${THUMB}[data-sx-thumb="a"],
+    [data-sx-range]:has(${CONTROL}[data-sx-thumb="b"]:focus-visible) ${THUMB}[data-sx-thumb="b"]) {
+    outline: 2px solid var(--color-sx-primary, currentColor);
+    outline-offset: 2px;
+  }
+
+  :where(${UPRIGHT}) {
+    justify-items: start;
+  }
+  :where(${UPRIGHT} > [data-sx-range-box]) {
+    container-type: size;
+    inline-size: max(1.5rem, var(--sx-range-thumb));
+    block-size: var(--sx-range-length);
+    touch-action: pan-x;
+  }
+  :where(${UPRIGHT} ${TRACK}) {
+    inset-inline: 0;
+    inset-block: calc(var(--sx-range-thumb) / 2);
+    margin-inline: auto;
+    margin-block: 0;
+    inline-size: var(--sx-range-h);
+    block-size: auto;
+  }
+  :where(${UPRIGHT} ${THUMB}) {
+    inset-block: 0 auto;
+    inset-inline: 0;
+    margin: 0 auto;
+    translate: 0 calc((1 - var(--sx-at)) * (100cqb - var(--sx-range-thumb)) - var(--sx-range-pull, 0px));
+  }
+  :where(${UPRIGHT} ${CONTROL}) {
+    writing-mode: vertical-lr;
+    direction: rtl;
+  }
+
+  :where([data-sx-range-description]) {
+    grid-area: description;
+    margin: 0.5rem 0 0;
+  }
+  :where([data-sx-range-message]) {
+    grid-area: message;
+    display: grid;
+    grid-template-rows: 0fr;
+  }
+  :where([data-sx-range-message]:has(> [data-sx-range-error]:not(:empty))) {
+    grid-template-rows: 1fr;
+  }
+  :where([data-sx-range-error]) {
+    min-block-size: 0;
+    margin: 0;
+    overflow: hidden;
+  }
+  :where([data-sx-range-says-error]) {
+    display: block;
+    padding-block-start: 0.375rem;
+  }
+  :where([data-sx-range-name]) {
+    display: none;
+  }
+
+  @media (prefers-reduced-motion: no-preference) {
+    :where(${THUMB}) {
+      transition-property: translate, scale;
+      transition-duration: var(--sx-range-glide, 0.12s), var(--sx-range-grow, 0.2s);
+      transition-timing-function: ${SPRING};
+    }
+    :where(${TRACK} > [data-sx-choice-layer]) {
+      transition-property: translate, scale, clip-path;
+      transition-duration: var(--sx-range-glide, 0.12s);
+      transition-timing-function: ${SPRING};
+    }
+    :where([data-sx-dragging] ${THUMB}) {
+      transition-duration: var(--sx-range-drag-glide, 0s), var(--sx-range-grow, 0.2s);
+    }
+    :where([data-sx-dragging] ${TRACK} > [data-sx-choice-layer]) {
+      transition-duration: var(--sx-range-drag-glide, 0s);
+    }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    :where([data-sx-range] [data-sx-choice-layer]:not([data-sx-choice-keep])) {
+      display: none;
+    }
+  }
+  @media (forced-colors: active) {
+    :where(${TRACK}) {
+      border: 1px solid CanvasText;
+    }
+    :where(${THUMB}) {
+      forced-color-adjust: none;
+      background: CanvasText;
+    }
+    :where([data-sx-range]:has(${CONTROL}:disabled) ${THUMB}) {
+      background: GrayText;
+    }
+  }
+}`;

package/dist/forms/registry.d.ts

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

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;