@happyvertical/smrt-ui 0.51.39 → 0.53.0

package/dist/components/forms/insert-text.js

@@ -0,0 +1,38 @@
+/**
+ * Put text into a text field at the cursor, the way typing would.
+ *
+ * - Replaces the selection, if any.
+ * - A field that has never had the cursor in it gets the text at the end.
+ * - Adds a space before the text when it would otherwise run into a word,
+ *   and after it when the next character is a letter or digit.
+ * - Leaves the cursor after the inserted text and fires `input`, so bound
+ *   values (`bind:value`) and listeners see the change.
+ */
+export function insertTextAtCursor(field, text) {
+    const words = text.trim();
+    if (!words)
+        return;
+    const value = field.value;
+    const focused = typeof document !== 'undefined' && document.activeElement === field;
+    let start = field.selectionStart ?? value.length;
+    let end = field.selectionEnd ?? value.length;
+    // An untouched field reports 0/0; dictation then belongs at the end.
+    if (!focused && start === 0 && end === 0 && value.length > 0) {
+        start = value.length;
+        end = value.length;
+    }
+    const before = value.slice(0, start);
+    const after = value.slice(end);
+    const lead = before.length > 0 && !/\s$/.test(before) ? ' ' : '';
+    const trail = /^[\p{L}\p{N}]/u.test(after) ? ' ' : '';
+    const inserted = `${lead}${words}${trail}`;
+    field.value = `${before}${inserted}${after}`;
+    const caret = before.length + inserted.length;
+    try {
+        field.setSelectionRange(caret, caret);
+    }
+    catch {
+        // Some input types do not support selection; the value is still set.
+    }
+    field.dispatchEvent(new Event('input', { bubbles: true }));
+}

package/dist/components/forms/long-press.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Long-press detection for pointer (mouse, pen) and touch input.
+ *
+ * A press counts as a long press when the primary pointer stays down, and
+ * within `moveTolerance` pixels of where it went down, for `delay`
+ * milliseconds (default 500ms, 10px). Moving further first is a drag or a
+ * scroll, never a long press, so a host's own drag gestures keep working.
+ * A native `dragstart` cancels a pending press for the same reason.
+ *
+ * - Only the primary button (left mouse, a finger, a pen tip) starts one; a
+ *   right click is left alone, and so is the context menu it opens.
+ * - The `click` that follows a fired long press is swallowed so the release
+ *   does not also "tap" the target.
+ * - `preventContextMenu` suppresses the context menu a touch long press
+ *   opens (Android, desktop touch screens) — but only during a press this
+ *   detector is tracking. Opt in only where the long press replaces that
+ *   menu (for example on a picture), never on a text field.
+ *
+ * Framework-free: `createLongPress` returns handlers a host wires itself, and
+ * `longPress` is the Svelte action (`use:longPress={options}`) that wires
+ * them to an element.
+ */
+/** What a long press was made on. */
+export interface LongPressDetail {
+    /** The element the press is about (from `filter`, else the event target). */
+    target: Element;
+    /** `mouse`, `pen` or `touch`. */
+    pointerType: string;
+    clientX: number;
+    clientY: number;
+}
+export interface LongPressOptions {
+    /** How long the pointer must stay down, in ms. Default 500. */
+    delay?: number;
+    /** How far (px) the pointer may move before it is a drag instead. Default 10. */
+    moveTolerance?: number;
+    /**
+     * Which presses count. Return the element the press is about, or `null` /
+     * `false` to ignore the press (for example: only pictures inside an
+     * editor). Default: every press, about its event target.
+     */
+    filter?: (event: PointerEvent) => Element | null | boolean;
+    /** The pointer stayed down long enough. */
+    onLongPress: (detail: LongPressDetail) => void;
+    /** The pointer came up after a long press fired (a user gesture). */
+    onRelease?: (detail: LongPressDetail) => void;
+    /** The pointer went down on a counted target (before the delay). */
+    onPressStart?: (detail: LongPressDetail) => void;
+    /** A pending press ended without firing (a tap, a drag, a scroll). */
+    onCancel?: () => void;
+    /** Suppress the context menu during a tracked press. Default false. */
+    preventContextMenu?: boolean;
+    /** Ignore every press. */
+    disabled?: boolean;
+}
+export declare const LONG_PRESS_DEFAULT_DELAY_MS = 500;
+export declare const LONG_PRESS_DEFAULT_MOVE_TOLERANCE_PX = 10;
+export interface LongPressController {
+    handlePointerDown(event: PointerEvent): void;
+    handlePointerMove(event: PointerEvent): void;
+    handlePointerUp(event: PointerEvent): void;
+    handlePointerCancel(event: PointerEvent): void;
+    handleDragStart(): void;
+    handleContextMenu(event: Event): void;
+    /** Wire in the capture phase so the swallowed click never reaches the target. */
+    handleClick(event: Event): void;
+    /** Forget any press in progress (no callbacks). */
+    cancel(): void;
+    update(options: LongPressOptions): void;
+    /** A press is down and waiting for the delay. */
+    readonly pending: boolean;
+    /** The current press already fired (until the pointer comes up). */
+    readonly fired: boolean;
+}
+/** Long-press state and handlers (see the module comment). */
+export declare function createLongPress(initial: LongPressOptions): LongPressController;
+/**
+ * Svelte action: `use:longPress={{ onLongPress: () => … }}`.
+ *
+ * Listens on the element (presses bubble up from its children, so wrapping a
+ * field or an editor works). Pointer moves and releases are also tracked on
+ * the window so a release outside the element still ends the press.
+ */
+export declare function longPress(node: HTMLElement, options: LongPressOptions): {
+    update(next: LongPressOptions): void;
+    destroy(): void;
+};
+//# sourceMappingURL=long-press.d.ts.map

package/dist/components/forms/long-press.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"long-press.d.ts","sourceRoot":"","sources":["../../../src/components/forms/long-press.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,qCAAqC;AACrC,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,MAAM,EAAE,OAAO,CAAC;IAChB,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC;IAC3D,2CAA2C;IAC3C,WAAW,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;IAC/C,qEAAqE;IACrE,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;IAC9C,oEAAoE;IACpE,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;IACjD,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,uEAAuE;IACvE,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAC/C,eAAO,MAAM,oCAAoC,KAAK,CAAC;AAEvD,MAAM,WAAW,mBAAmB;IAClC,iBAAiB,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IAC7C,iBAAiB,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IAC7C,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IAC3C,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IAC/C,eAAe,IAAI,IAAI,CAAC;IACxB,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACtC,iFAAiF;IACjF,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAChC,mDAAmD;IACnD,MAAM,IAAI,IAAI,CAAC;IACf,MAAM,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACxC,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,8DAA8D;AAC9D,wBAAgB,eAAe,CAC7B,OAAO,EAAE,gBAAgB,GACxB,mBAAmB,CA6IrB;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,gBAAgB;iBAmBrD,gBAAgB;;EAchC"}

package/dist/components/forms/long-press.js

@@ -0,0 +1,213 @@
+/**
+ * Long-press detection for pointer (mouse, pen) and touch input.
+ *
+ * A press counts as a long press when the primary pointer stays down, and
+ * within `moveTolerance` pixels of where it went down, for `delay`
+ * milliseconds (default 500ms, 10px). Moving further first is a drag or a
+ * scroll, never a long press, so a host's own drag gestures keep working.
+ * A native `dragstart` cancels a pending press for the same reason.
+ *
+ * - Only the primary button (left mouse, a finger, a pen tip) starts one; a
+ *   right click is left alone, and so is the context menu it opens.
+ * - The `click` that follows a fired long press is swallowed so the release
+ *   does not also "tap" the target.
+ * - `preventContextMenu` suppresses the context menu a touch long press
+ *   opens (Android, desktop touch screens) — but only during a press this
+ *   detector is tracking. Opt in only where the long press replaces that
+ *   menu (for example on a picture), never on a text field.
+ *
+ * Framework-free: `createLongPress` returns handlers a host wires itself, and
+ * `longPress` is the Svelte action (`use:longPress={options}`) that wires
+ * them to an element.
+ */
+export const LONG_PRESS_DEFAULT_DELAY_MS = 500;
+export const LONG_PRESS_DEFAULT_MOVE_TOLERANCE_PX = 10;
+/** Long-press state and handlers (see the module comment). */
+export function createLongPress(initial) {
+    let options = initial;
+    let timer = null;
+    let pointerId = null;
+    let startX = 0;
+    let startY = 0;
+    let detail = null;
+    let fired = false;
+    let swallowClick = false;
+    let swallowTimer = null;
+    function clearTimer() {
+        if (timer)
+            clearTimeout(timer);
+        timer = null;
+    }
+    function reset() {
+        clearTimer();
+        pointerId = null;
+        detail = null;
+        fired = false;
+    }
+    function cancelPending() {
+        if (!timer)
+            return;
+        reset();
+        options.onCancel?.();
+    }
+    function resolveTarget(event) {
+        const picked = options.filter ? options.filter(event) : true;
+        if (!picked)
+            return null;
+        if (picked === true) {
+            return event.target instanceof Element ? event.target : null;
+        }
+        return picked;
+    }
+    function armClickSwallow() {
+        swallowClick = true;
+        if (swallowTimer)
+            clearTimeout(swallowTimer);
+        // A click that never comes (the pointer moved off) must not eat a later one.
+        swallowTimer = setTimeout(() => {
+            swallowClick = false;
+            swallowTimer = null;
+        }, 400);
+    }
+    return {
+        handlePointerDown(event) {
+            if (options.disabled)
+                return;
+            if (!event.isPrimary)
+                return;
+            if (event.pointerType === 'mouse' && event.button !== 0)
+                return;
+            const target = resolveTarget(event);
+            if (!target)
+                return;
+            reset();
+            pointerId = event.pointerId;
+            startX = event.clientX;
+            startY = event.clientY;
+            detail = {
+                target,
+                pointerType: event.pointerType || 'mouse',
+                clientX: event.clientX,
+                clientY: event.clientY,
+            };
+            options.onPressStart?.(detail);
+            const pressed = detail;
+            timer = setTimeout(() => {
+                timer = null;
+                fired = true;
+                options.onLongPress(pressed);
+            }, options.delay ?? LONG_PRESS_DEFAULT_DELAY_MS);
+        },
+        handlePointerMove(event) {
+            if (!timer || event.pointerId !== pointerId)
+                return;
+            const tolerance = options.moveTolerance ?? LONG_PRESS_DEFAULT_MOVE_TOLERANCE_PX;
+            if (Math.hypot(event.clientX - startX, event.clientY - startY) > tolerance) {
+                cancelPending();
+            }
+        },
+        handlePointerUp(event) {
+            if (event.pointerId !== pointerId)
+                return;
+            if (timer) {
+                cancelPending();
+                return;
+            }
+            if (fired && detail) {
+                const released = detail;
+                armClickSwallow();
+                reset();
+                options.onRelease?.(released);
+                return;
+            }
+            reset();
+        },
+        handlePointerCancel(event) {
+            if (event.pointerId !== pointerId)
+                return;
+            if (timer) {
+                cancelPending();
+                return;
+            }
+            if (fired && detail) {
+                const released = detail;
+                reset();
+                options.onRelease?.(released);
+                return;
+            }
+            reset();
+        },
+        handleDragStart() {
+            cancelPending();
+        },
+        handleContextMenu(event) {
+            if (!options.preventContextMenu)
+                return;
+            if (timer || fired)
+                event.preventDefault();
+        },
+        handleClick(event) {
+            if (!swallowClick)
+                return;
+            swallowClick = false;
+            if (swallowTimer)
+                clearTimeout(swallowTimer);
+            swallowTimer = null;
+            event.preventDefault();
+            event.stopPropagation();
+        },
+        cancel() {
+            reset();
+        },
+        update(next) {
+            options = next;
+            if (next.disabled)
+                reset();
+        },
+        get pending() {
+            return timer !== null;
+        },
+        get fired() {
+            return fired;
+        },
+    };
+}
+/**
+ * Svelte action: `use:longPress={{ onLongPress: () => … }}`.
+ *
+ * Listens on the element (presses bubble up from its children, so wrapping a
+ * field or an editor works). Pointer moves and releases are also tracked on
+ * the window so a release outside the element still ends the press.
+ */
+export function longPress(node, options) {
+    const controller = createLongPress(options);
+    const down = (event) => controller.handlePointerDown(event);
+    const move = (event) => controller.handlePointerMove(event);
+    const up = (event) => controller.handlePointerUp(event);
+    const cancel = (event) => controller.handlePointerCancel(event);
+    const drag = () => controller.handleDragStart();
+    const menu = (event) => controller.handleContextMenu(event);
+    const click = (event) => controller.handleClick(event);
+    node.addEventListener('pointerdown', down);
+    node.addEventListener('dragstart', drag);
+    node.addEventListener('contextmenu', menu);
+    node.addEventListener('click', click, true);
+    window.addEventListener('pointermove', move);
+    window.addEventListener('pointerup', up);
+    window.addEventListener('pointercancel', cancel);
+    return {
+        update(next) {
+            controller.update(next);
+        },
+        destroy() {
+            controller.cancel();
+            node.removeEventListener('pointerdown', down);
+            node.removeEventListener('dragstart', drag);
+            node.removeEventListener('contextmenu', menu);
+            node.removeEventListener('click', click, true);
+            window.removeEventListener('pointermove', move);
+            window.removeEventListener('pointerup', up);
+            window.removeEventListener('pointercancel', cancel);
+        },
+    };
+}

package/dist/components/forms/native-file-field.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Framework-free helpers that let a capture component (`CameraCapture`,
+ * `SignaturePad`) post a `File` it created through a plain
+ * `<form method="POST" enctype="multipart/form-data">`, without the caller
+ * wiring a hidden input or intercepting submit.
+ *
+ * Two strategies, chosen once per page by {@link detectNativeFileFieldStrategy}:
+ *
+ * - `data-transfer` (preferred): the component renders a hidden
+ *   `<input type="file" name>` and fills it with `new DataTransfer()`, so the
+ *   browser posts the file exactly like a user-picked one. Needs a constructible
+ *   `DataTransfer` whose `files` an input accepts (Chrome 60+, Firefox 62+,
+ *   Safari 14.1+).
+ * - `formdata-event` (fallback when `DataTransfer` is unavailable): the hidden
+ *   input carries no `name`, and a capture-phase `formdata` listener appends the
+ *   file to the form's entry list while the browser builds it. The browser fires
+ *   `formdata` for native navigation submits as well as `new FormData(form)`, so
+ *   the request is the same.
+ * - `none`: neither API exists. Nothing is posted for the field; the
+ *   component's `onCapture` callback remains the only channel. Components expose
+ *   the active strategy as `data-smrt-file-field` for diagnostics.
+ *
+ * In both posting strategies an uncommitted field posts what an empty native
+ * file input posts (an empty, unnamed `application/octet-stream` file), so the
+ * server sees one shape regardless of strategy; inside a disabled `<fieldset>`
+ * both post nothing, as a disabled native control does. A reset of the owning form
+ * empties the field like a native file input ({@link attachFormResetListener}).
+ */
+/** How a capture component posts its file in a native form. */
+export type NativeFileFieldStrategy = 'data-transfer' | 'formdata-event' | 'none';
+/** Globals the strategy probe reads; injectable for tests. */
+export interface NativeFileFieldEnvironment {
+    DataTransfer?: unknown;
+    FormDataEvent?: unknown;
+    File?: unknown;
+    /** Creates a detached `<input type="file">` for the assignment probe. */
+    createFileInput?: () => HTMLInputElement;
+}
+/**
+ * Put `file` into `input` through a fresh `DataTransfer`. Returns `true` only
+ * when the input now holds exactly one file. Old engines expose a
+ * `DataTransfer` interface whose constructor throws ("Illegal constructor"), or
+ * reject the `files` assignment; both report `false`.
+ */
+export declare function assignFileWithDataTransfer(input: HTMLInputElement, file: File, DataTransferCtor?: unknown): boolean;
+/**
+ * Empty a file input so it posts the native "no file chosen" entry. Scripts may
+ * always set a file input's value to the empty string (only non-empty values
+ * throw).
+ */
+export declare function clearFileInput(input: HTMLInputElement): void;
+/** Pick the strategy for this page. Safe during SSR (returns `none`). */
+export declare function detectNativeFileFieldStrategy(env?: NativeFileFieldEnvironment): NativeFileFieldStrategy;
+/** The entry a `formdata`-event field contributes, read at submit time. */
+export interface FormDataFieldEntry {
+    /** The form whose entry list receives the file (the hidden input's `form`). */
+    form: HTMLFormElement | null;
+    name: string;
+    /** The committed file, or `null` to post the native empty-file entry. */
+    file: File | null;
+    /**
+     * The component's hidden input. While it is `:disabled` (inside a disabled
+     * `<fieldset>`), nothing is appended — the browser leaves a disabled native
+     * control out of the entry list, and this appended entry must match.
+     */
+    source?: Element | null;
+}
+/** The native "no file chosen" entry: an empty, unnamed octet-stream file. */
+export declare function emptyFileEntry(): File;
+/**
+ * Install the `formdata`-event fallback. The listener runs in the capture
+ * phase on `target` (normally `document`), so it sees the event whichever form
+ * currently owns the field, then appends only for that form. Returns a disposer.
+ */
+export declare function attachFormDataFallback(target: Pick<EventTarget, 'addEventListener' | 'removeEventListener'>, readEntry: () => FormDataFieldEntry | null): () => void;
+/**
+ * Call `onReset` whenever the form returned by `readForm` resets
+ * (`form.reset()`, a reset button, or SvelteKit `enhance`'s `update()` after a
+ * success). A native file input is emptied by its form's reset; a capture
+ * component must empty its own committed state at the same moment, or it keeps
+ * showing a file that no longer posts.
+ *
+ * Like {@link attachFormDataFallback}, the listener runs in the capture phase
+ * on `target` (normally `document`) and reads the owning form at dispatch
+ * time, so a field moved between forms needs no re-wiring and a page listener
+ * that stops propagation cannot hide the reset. `reset` fires before the
+ * browser resets the controls, and `onReset` runs even if a later listener
+ * cancels it: the component and the posted entry are then both empty, which
+ * keeps what is shown equal to what posts. Returns a disposer.
+ */
+export declare function attachFormResetListener(target: Pick<EventTarget, 'addEventListener' | 'removeEventListener'>, readForm: () => HTMLFormElement | null | undefined, onReset: () => void): () => void;
+/** `photo` + `image/png` → `photo.png`; unknown types fall back to `bin`. */
+export declare function fileNameForType(base: string, type: string): string;
+//# sourceMappingURL=native-file-field.d.ts.map

package/dist/components/forms/native-file-field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-file-field.d.ts","sourceRoot":"","sources":["../../../src/components/forms/native-file-field.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,+DAA+D;AAC/D,MAAM,MAAM,uBAAuB,GAC/B,eAAe,GACf,gBAAgB,GAChB,MAAM,CAAC;AAEX,8DAA8D;AAC9D,MAAM,WAAW,0BAA0B;IACzC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,yEAAyE;IACzE,eAAe,CAAC,EAAE,MAAM,gBAAgB,CAAC;CAC1C;AAqBD;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,gBAAgB,EACvB,IAAI,EAAE,IAAI,EACV,gBAAgB,GAAE,OACH,GACd,OAAO,CAUT;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAE5D;AAED,yEAAyE;AACzE,wBAAgB,6BAA6B,CAC3C,GAAG,GAAE,0BAAiD,GACrD,uBAAuB,CAoBzB;AAED,2EAA2E;AAC3E,MAAM,WAAW,kBAAkB;IACjC,+EAA+E;IAC/E,IAAI,EAAE,eAAe,GAAG,IAAI,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IAClB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CACzB;AAED,8EAA8E;AAC9E,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,kBAAkB,GAAG,qBAAqB,CAAC,EACrE,SAAS,EAAE,MAAM,kBAAkB,GAAG,IAAI,GACzC,MAAM,IAAI,CAYZ;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,kBAAkB,GAAG,qBAAqB,CAAC,EACrE,QAAQ,EAAE,MAAM,eAAe,GAAG,IAAI,GAAG,SAAS,EAClD,OAAO,EAAE,MAAM,IAAI,GAClB,MAAM,IAAI,CAOZ;AAQD,6EAA6E;AAC7E,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAElE"}

package/dist/components/forms/native-file-field.js

@@ -0,0 +1,147 @@
+/**
+ * Framework-free helpers that let a capture component (`CameraCapture`,
+ * `SignaturePad`) post a `File` it created through a plain
+ * `<form method="POST" enctype="multipart/form-data">`, without the caller
+ * wiring a hidden input or intercepting submit.
+ *
+ * Two strategies, chosen once per page by {@link detectNativeFileFieldStrategy}:
+ *
+ * - `data-transfer` (preferred): the component renders a hidden
+ *   `<input type="file" name>` and fills it with `new DataTransfer()`, so the
+ *   browser posts the file exactly like a user-picked one. Needs a constructible
+ *   `DataTransfer` whose `files` an input accepts (Chrome 60+, Firefox 62+,
+ *   Safari 14.1+).
+ * - `formdata-event` (fallback when `DataTransfer` is unavailable): the hidden
+ *   input carries no `name`, and a capture-phase `formdata` listener appends the
+ *   file to the form's entry list while the browser builds it. The browser fires
+ *   `formdata` for native navigation submits as well as `new FormData(form)`, so
+ *   the request is the same.
+ * - `none`: neither API exists. Nothing is posted for the field; the
+ *   component's `onCapture` callback remains the only channel. Components expose
+ *   the active strategy as `data-smrt-file-field` for diagnostics.
+ *
+ * In both posting strategies an uncommitted field posts what an empty native
+ * file input posts (an empty, unnamed `application/octet-stream` file), so the
+ * server sees one shape regardless of strategy; inside a disabled `<fieldset>`
+ * both post nothing, as a disabled native control does. A reset of the owning form
+ * empties the field like a native file input ({@link attachFormResetListener}).
+ */
+function browserEnvironment() {
+    const scope = globalThis;
+    return {
+        DataTransfer: scope.DataTransfer,
+        FormDataEvent: scope.FormDataEvent,
+        File: scope.File,
+        createFileInput: typeof document === 'undefined'
+            ? undefined
+            : () => {
+                const input = document.createElement('input');
+                input.type = 'file';
+                return input;
+            },
+    };
+}
+/**
+ * Put `file` into `input` through a fresh `DataTransfer`. Returns `true` only
+ * when the input now holds exactly one file. Old engines expose a
+ * `DataTransfer` interface whose constructor throws ("Illegal constructor"), or
+ * reject the `files` assignment; both report `false`.
+ */
+export function assignFileWithDataTransfer(input, file, DataTransferCtor = globalThis
+    .DataTransfer) {
+    if (typeof DataTransferCtor !== 'function')
+        return false;
+    try {
+        const transfer = new DataTransferCtor();
+        transfer.items.add(file);
+        input.files = transfer.files;
+        return input.files?.length === 1;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Empty a file input so it posts the native "no file chosen" entry. Scripts may
+ * always set a file input's value to the empty string (only non-empty values
+ * throw).
+ */
+export function clearFileInput(input) {
+    input.value = '';
+}
+/** Pick the strategy for this page. Safe during SSR (returns `none`). */
+export function detectNativeFileFieldStrategy(env = browserEnvironment()) {
+    const FileCtor = env.File;
+    if (env.createFileInput && typeof FileCtor === 'function') {
+        try {
+            const probe = new FileCtor([], 'probe.bin');
+            if (assignFileWithDataTransfer(env.createFileInput(), probe, env.DataTransfer)) {
+                return 'data-transfer';
+            }
+        }
+        catch {
+            // Fall through to the next strategy.
+        }
+    }
+    if (typeof env.FormDataEvent === 'function')
+        return 'formdata-event';
+    return 'none';
+}
+/** The native "no file chosen" entry: an empty, unnamed octet-stream file. */
+export function emptyFileEntry() {
+    return new File([], '', { type: 'application/octet-stream' });
+}
+/**
+ * Install the `formdata`-event fallback. The listener runs in the capture
+ * phase on `target` (normally `document`), so it sees the event whichever form
+ * currently owns the field, then appends only for that form. Returns a disposer.
+ */
+export function attachFormDataFallback(target, readEntry) {
+    const listener = (event) => {
+        const entry = readEntry();
+        if (!entry?.form || !entry.name || event.target !== entry.form)
+            return;
+        if (entry.source?.matches(':disabled'))
+            return;
+        const formData = event.formData;
+        if (!formData)
+            return;
+        const file = entry.file ?? emptyFileEntry();
+        formData.append(entry.name, file, file.name);
+    };
+    target.addEventListener('formdata', listener, true);
+    return () => target.removeEventListener('formdata', listener, true);
+}
+/**
+ * Call `onReset` whenever the form returned by `readForm` resets
+ * (`form.reset()`, a reset button, or SvelteKit `enhance`'s `update()` after a
+ * success). A native file input is emptied by its form's reset; a capture
+ * component must empty its own committed state at the same moment, or it keeps
+ * showing a file that no longer posts.
+ *
+ * Like {@link attachFormDataFallback}, the listener runs in the capture phase
+ * on `target` (normally `document`) and reads the owning form at dispatch
+ * time, so a field moved between forms needs no re-wiring and a page listener
+ * that stops propagation cannot hide the reset. `reset` fires before the
+ * browser resets the controls, and `onReset` runs even if a later listener
+ * cancels it: the component and the posted entry are then both empty, which
+ * keeps what is shown equal to what posts. Returns a disposer.
+ */
+export function attachFormResetListener(target, readForm, onReset) {
+    const listener = (event) => {
+        const form = readForm();
+        if (form && event.target === form)
+            onReset();
+    };
+    target.addEventListener('reset', listener, true);
+    return () => target.removeEventListener('reset', listener, true);
+}
+const EXTENSIONS = {
+    'image/jpeg': 'jpg',
+    'image/png': 'png',
+    'image/webp': 'webp',
+};
+/** `photo` + `image/png` → `photo.png`; unknown types fall back to `bin`. */
+export function fileNameForType(base, type) {
+    return `${base}.${EXTENSIONS[type] ?? 'bin'}`;
+}

package/dist/components/forms/ready-beep.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A short "ready" beep, made with the Web Audio API (no sound files).
+ *
+ * Browsers only start audio after a user gesture. A long press fires from a
+ * timer while the finger is still down, which on touch screens is not a
+ * gesture yet, so `playReadyBeep` resolves `false` when the audio could not
+ * start; the host plays it again from the release (`pointerup` is a gesture).
+ * `primeReadyBeep` creates the audio context early, from a gesture, so later
+ * beeps start immediately.
+ */
+/** Create (or wake) the audio context; call from a user gesture. */
+export declare function primeReadyBeep(): void;
+export interface ReadyBeepOptions {
+    /** Volume, 0–1. Default 0.12. */
+    volume?: number;
+}
+/**
+ * Play two quick rising tones (about 0.2s). Resolves `true` when it played,
+ * `false` when audio is unavailable or not allowed yet.
+ */
+export declare function playReadyBeep(options?: ReadyBeepOptions): Promise<boolean>;
+/** Tests: forget the shared audio context. */
+export declare function resetReadyBeepForTests(): void;
+//# sourceMappingURL=ready-beep.d.ts.map

package/dist/components/forms/ready-beep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ready-beep.d.ts","sourceRoot":"","sources":["../../../src/components/forms/ready-beep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA4BH,oEAAoE;AACpE,wBAAgB,cAAc,IAAI,IAAI,CAKrC;AAED,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,OAAO,CAAC,CA6BlB;AAED,8CAA8C;AAC9C,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}