@thomasfosterau/components 0.0.0 → 0.2.0

package/dist/fields/field-types.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The control props `<FormField>` hands its `children` snippet, and every
+ * field primitive accepts by spread: `<TextInput {...control} bind:value />`.
+ * Carrying the ids this way is what keeps `aria-describedby` and
+ * `aria-invalid` on the control in step with the hint and error paragraphs
+ * `FormField` renders, without either side knowing the other's markup.
+ *
+ * The daisyUI size tables live here for the same reason `ui/tones.ts` holds
+ * the button ones: Tailwind only generates classes it can see verbatim, so a
+ * `input-${size}` template string emits nothing at build time. Every field
+ * component looks a complete class name up rather than building one.
+ *
+ * @module
+ */
+import type { Size } from '../ui/tones.ts';
+/** Wiring a field primitive receives from its enclosing `FormField`. */
+export interface FieldControl {
+    /** The control's `id`; the `FormField` label points at it. */
+    readonly id: string;
+    /**
+     * The id of the visible `<label>`. A labelable control (`input`, `select`,
+     * `textarea`, `button`, …) ignores it: `<label for>` already names it. A
+     * control `<label for>` cannot reach — a `role="slider"` thumb, a
+     * `role="group"` / `radiogroup` root, a segmented date group — points
+     * `aria-labelledby` at it instead of taking a labelling prop of its own.
+     */
+    readonly labelId: string;
+    /** Space-separated ids of the hint / error paragraphs; empty when neither is shown. */
+    readonly describedBy: string;
+    /** The field currently shows an error. */
+    readonly invalid: boolean;
+    readonly required: boolean;
+}
+/**
+ * What `<Fieldset>` hands its `children` snippet: the id of its `<legend>`,
+ * for a role-based control inside the group (which a legend names only
+ * through the `<fieldset>`, a different node) to point `aria-labelledby` at.
+ */
+export interface FieldsetControl {
+    /** The id of the `<legend>`. */
+    readonly labelId: string;
+}
+/** Size steps shared by the field primitives (daisyUI has no `xl` field). */
+export type FieldSize = 'xs' | 'sm' | 'md' | 'lg';
+/** One entry of a `Select`, `RadioGroup` or `CheckboxGroup`. */
+export interface FieldOption {
+    readonly value: string;
+    readonly label: string;
+    readonly disabled?: boolean | undefined;
+}
+/**
+ * What an options prop accepts: full options, or bare strings for the common
+ * case where the value and the label are the same word.
+ */
+export type FieldOptionInput = FieldOption | string;
+/** Widen the bare-string shorthand into full {@link FieldOption}s. */
+export declare function toFieldOptions(options: readonly FieldOptionInput[]): readonly FieldOption[];
+/** Literal daisyUI class per `FieldSize` for `TextInput`; a lookup table so Tailwind's scanner sees every class. */
+export declare const inputSize: Record<FieldSize, string>;
+/** Literal daisyUI class per `FieldSize` for `Textarea`; a lookup table so Tailwind's scanner sees every class. */
+export declare const textareaSize: Record<FieldSize, string>;
+/** Literal daisyUI class per `FieldSize` for `Select`; a lookup table so Tailwind's scanner sees every class. */
+export declare const selectSize: Record<FieldSize, string>;
+/** Literal daisyUI class per `FieldSize` for `Checkbox`; a lookup table so Tailwind's scanner sees every class. */
+export declare const checkboxSize: Record<FieldSize, string>;
+/** Literal daisyUI class per `FieldSize` for `Toggle`; a lookup table so Tailwind's scanner sees every class. */
+export declare const toggleSize: Record<FieldSize, string>;
+/** Literal daisyUI class per `FieldSize` for `FileInput`; a lookup table so Tailwind's scanner sees every class. */
+export declare const fileInputSize: Record<FieldSize, string>;
+/**
+ * Literal daisyUI class per `FieldSize` for `Slider`; a lookup table so Tailwind's scanner sees every class.
+ * Each sets `--range-thumb-size`, which the slider's thumb and track are sized from.
+ */
+export declare const rangeSize: Record<FieldSize, string>;
+/** Literal cell size and text-size classes per `FieldSize` for `PinInput`'s cells; a lookup table so Tailwind's scanner sees every class. */
+export declare const pinCellSize: Record<FieldSize, string>;
+/** Literal daisyUI button size per `FieldSize` for a button inside an `input` composite (`NumberField`'s − / +, `PasswordInput`'s reveal toggle), one step smaller than the field so it fits; a lookup table so Tailwind's scanner sees every class. */
+export declare const inputButtonSize: Record<FieldSize, string>;
+/** Literal daisyUI class per `Size` for `Rating`; each sets `--size`, the star height. A lookup table so Tailwind's scanner sees every class. */
+export declare const ratingSize: Record<Size, string>;

package/dist/fields/field-types.js

@@ -0,0 +1,92 @@
+/**
+ * The control props `<FormField>` hands its `children` snippet, and every
+ * field primitive accepts by spread: `<TextInput {...control} bind:value />`.
+ * Carrying the ids this way is what keeps `aria-describedby` and
+ * `aria-invalid` on the control in step with the hint and error paragraphs
+ * `FormField` renders, without either side knowing the other's markup.
+ *
+ * The daisyUI size tables live here for the same reason `ui/tones.ts` holds
+ * the button ones: Tailwind only generates classes it can see verbatim, so a
+ * `input-${size}` template string emits nothing at build time. Every field
+ * component looks a complete class name up rather than building one.
+ *
+ * @module
+ */
+/** Widen the bare-string shorthand into full {@link FieldOption}s. */
+export function toFieldOptions(options) {
+    return options.map((option) => typeof option === 'string' ? { value: option, label: option } : option);
+}
+/** Literal daisyUI class per `FieldSize` for `TextInput`; a lookup table so Tailwind's scanner sees every class. */
+export const inputSize = {
+    xs: 'input-xs',
+    sm: 'input-sm',
+    md: 'input-md',
+    lg: 'input-lg',
+};
+/** Literal daisyUI class per `FieldSize` for `Textarea`; a lookup table so Tailwind's scanner sees every class. */
+export const textareaSize = {
+    xs: 'textarea-xs',
+    sm: 'textarea-sm',
+    md: 'textarea-md',
+    lg: 'textarea-lg',
+};
+/** Literal daisyUI class per `FieldSize` for `Select`; a lookup table so Tailwind's scanner sees every class. */
+export const selectSize = {
+    xs: 'select-xs',
+    sm: 'select-sm',
+    md: 'select-md',
+    lg: 'select-lg',
+};
+/** Literal daisyUI class per `FieldSize` for `Checkbox`; a lookup table so Tailwind's scanner sees every class. */
+export const checkboxSize = {
+    xs: 'checkbox-xs',
+    sm: 'checkbox-sm',
+    md: 'checkbox-md',
+    lg: 'checkbox-lg',
+};
+/** Literal daisyUI class per `FieldSize` for `Toggle`; a lookup table so Tailwind's scanner sees every class. */
+export const toggleSize = {
+    xs: 'toggle-xs',
+    sm: 'toggle-sm',
+    md: 'toggle-md',
+    lg: 'toggle-lg',
+};
+/** Literal daisyUI class per `FieldSize` for `FileInput`; a lookup table so Tailwind's scanner sees every class. */
+export const fileInputSize = {
+    xs: 'file-input-xs',
+    sm: 'file-input-sm',
+    md: 'file-input-md',
+    lg: 'file-input-lg',
+};
+/**
+ * Literal daisyUI class per `FieldSize` for `Slider`; a lookup table so Tailwind's scanner sees every class.
+ * Each sets `--range-thumb-size`, which the slider's thumb and track are sized from.
+ */
+export const rangeSize = {
+    xs: 'range-xs',
+    sm: 'range-sm',
+    md: 'range-md',
+    lg: 'range-lg',
+};
+/** Literal cell size and text-size classes per `FieldSize` for `PinInput`'s cells; a lookup table so Tailwind's scanner sees every class. */
+export const pinCellSize = {
+    xs: 'size-6 text-xs',
+    sm: 'size-8 text-sm',
+    md: 'size-10 text-base',
+    lg: 'size-12 text-lg',
+};
+/** Literal daisyUI button size per `FieldSize` for a button inside an `input` composite (`NumberField`'s − / +, `PasswordInput`'s reveal toggle), one step smaller than the field so it fits; a lookup table so Tailwind's scanner sees every class. */
+export const inputButtonSize = {
+    xs: 'btn-xs',
+    sm: 'btn-xs',
+    md: 'btn-sm',
+    lg: 'btn-md',
+};
+/** Literal daisyUI class per `Size` for `Rating`; each sets `--size`, the star height. A lookup table so Tailwind's scanner sees every class. */
+export const ratingSize = {
+    xs: 'rating-xs',
+    sm: 'rating-sm',
+    md: 'rating-md',
+    lg: 'rating-lg',
+    xl: 'rating-xl',
+};

package/dist/fields/file-validation.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The client-side file checks `FileInput` and `Dropzone` share.
+ *
+ * Pure functions, so the rules are the same wherever a file comes from —
+ * the native picker or a drop, which the browser does NOT filter by
+ * `accept` — and testable without a DOM.
+ *
+ * @module
+ */
+/** Why `Dropzone` refused a file. */
+export interface FileRejection {
+    /** The refused file. */
+    readonly file: File;
+    /** Which rule refused it. */
+    readonly reason: 'too-large' | 'wrong-type' | 'too-many';
+}
+/**
+ * Whether `file` satisfies an `accept` string, with the native attribute's
+ * syntax: comma-separated `.ext` suffixes, `type/*` families and exact MIME
+ * types, all case-insensitive. An absent or empty `accept` accepts anything.
+ */
+export declare function acceptMatches(file: File, accept: string | undefined): boolean;
+/** Whether `file` is over `maxBytes`; no cap means never. */
+export declare function exceedsSize(file: File, maxBytes: number | undefined): boolean;
+/**
+ * A byte count for a file row, in the largest decimal unit that keeps the
+ * number at or above 1 ("820 kB", "4.2 MB"), through `Intl.NumberFormat`'s
+ * unit style.
+ */
+export declare function formatFileSize(bytes: number, locales: string | readonly string[] | undefined): string;

package/dist/fields/file-validation.js

@@ -0,0 +1,51 @@
+/**
+ * The client-side file checks `FileInput` and `Dropzone` share.
+ *
+ * Pure functions, so the rules are the same wherever a file comes from —
+ * the native picker or a drop, which the browser does NOT filter by
+ * `accept` — and testable without a DOM.
+ *
+ * @module
+ */
+/**
+ * Whether `file` satisfies an `accept` string, with the native attribute's
+ * syntax: comma-separated `.ext` suffixes, `type/*` families and exact MIME
+ * types, all case-insensitive. An absent or empty `accept` accepts anything.
+ */
+export function acceptMatches(file, accept) {
+    const tokens = (accept ?? '')
+        .split(',')
+        .map((token) => token.trim().toLowerCase())
+        .filter((token) => token !== '');
+    if (tokens.length === 0)
+        return true;
+    const name = file.name.toLowerCase();
+    const type = file.type.toLowerCase();
+    return tokens.some((token) => {
+        if (token.startsWith('.'))
+            return name.endsWith(token);
+        if (token.endsWith('/*'))
+            return type.startsWith(token.slice(0, -1));
+        return type === token;
+    });
+}
+/** Whether `file` is over `maxBytes`; no cap means never. */
+export function exceedsSize(file, maxBytes) {
+    return maxBytes !== undefined && file.size > maxBytes;
+}
+const UNITS = ['byte', 'kilobyte', 'megabyte', 'gigabyte'];
+/**
+ * A byte count for a file row, in the largest decimal unit that keeps the
+ * number at or above 1 ("820 kB", "4.2 MB"), through `Intl.NumberFormat`'s
+ * unit style.
+ */
+export function formatFileSize(bytes, locales) {
+    const exponent = Math.min(UNITS.length - 1, Math.max(0, Math.floor(Math.log10(Math.max(bytes, 1)) / 3)));
+    const value = bytes / 1000 ** exponent;
+    return new Intl.NumberFormat(typeof locales === 'string' || locales === undefined ? locales : [...locales], {
+        style: 'unit',
+        unit: UNITS[exponent],
+        unitDisplay: 'short',
+        maximumFractionDigits: exponent === 0 ? 0 : 1,
+    }).format(value);
+}

package/dist/fields/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * fields — form controls wired through `FormField`'s `FieldControl` contract.
+ *
+ * The shape every control in here shares: `FormField` (or `Fieldset`) owns
+ * the label, the hint and the errors, derives one `id` into a `describedBy`
+ * and an `invalid` flag, and hands that `FieldControl` to its `children`
+ * snippet. A control spreads it — `<TextInput {...control} bind:value />` —
+ * and so carries `aria-describedby`, `aria-invalid` and `required` without
+ * either side knowing the other's markup.
+ *
+ * Optional props are declared `T | undefined` rather than `prop?: T`: the
+ * workspace compiles with `exactOptionalPropertyTypes`, under which a caller
+ * forwarding its own optional prop would not compile otherwise.
+ *
+ * @module
+ */
+export { default as Checkbox } from './Checkbox.svelte';
+export { default as CheckboxGroup } from './CheckboxGroup.svelte';
+export { default as Combobox } from './Combobox.svelte';
+export { default as DateInput } from './DateInput.svelte';
+export { default as Dropzone } from './Dropzone.svelte';
+export { default as FieldErrors } from './FieldErrors.svelte';
+export { default as Fieldset } from './Fieldset.svelte';
+export { default as FileInput } from './FileInput.svelte';
+export { default as FormField } from './FormField.svelte';
+export { default as ImageInput } from './ImageInput.svelte';
+export { default as MultiSelect } from './MultiSelect.svelte';
+export { default as NumberField } from './NumberField.svelte';
+export { default as PasswordInput } from './PasswordInput.svelte';
+export { default as PinInput } from './PinInput.svelte';
+export { default as RadioGroup } from './RadioGroup.svelte';
+export { default as Rating } from './Rating.svelte';
+export { default as SearchInput } from './SearchInput.svelte';
+export { default as Select } from './Select.svelte';
+export { default as Slider } from './Slider.svelte';
+export { default as TagsInput } from './TagsInput.svelte';
+export { default as Textarea } from './Textarea.svelte';
+export { default as TextInput } from './TextInput.svelte';
+export { default as Toggle } from './Toggle.svelte';
+export { default as PushToggle, type PushDeclineReason, type PushEnableResult, } from './PushToggle.svelte';
+export { default as VideoInput } from './VideoInput.svelte';
+export * from './field-types.ts';
+export type { FileRejection } from './file-validation.ts';

package/dist/fields/index.js

@@ -0,0 +1,42 @@
+/**
+ * fields — form controls wired through `FormField`'s `FieldControl` contract.
+ *
+ * The shape every control in here shares: `FormField` (or `Fieldset`) owns
+ * the label, the hint and the errors, derives one `id` into a `describedBy`
+ * and an `invalid` flag, and hands that `FieldControl` to its `children`
+ * snippet. A control spreads it — `<TextInput {...control} bind:value />` —
+ * and so carries `aria-describedby`, `aria-invalid` and `required` without
+ * either side knowing the other's markup.
+ *
+ * Optional props are declared `T | undefined` rather than `prop?: T`: the
+ * workspace compiles with `exactOptionalPropertyTypes`, under which a caller
+ * forwarding its own optional prop would not compile otherwise.
+ *
+ * @module
+ */
+export { default as Checkbox } from './Checkbox.svelte';
+export { default as CheckboxGroup } from './CheckboxGroup.svelte';
+export { default as Combobox } from './Combobox.svelte';
+export { default as DateInput } from './DateInput.svelte';
+export { default as Dropzone } from './Dropzone.svelte';
+export { default as FieldErrors } from './FieldErrors.svelte';
+export { default as Fieldset } from './Fieldset.svelte';
+export { default as FileInput } from './FileInput.svelte';
+export { default as FormField } from './FormField.svelte';
+export { default as ImageInput } from './ImageInput.svelte';
+export { default as MultiSelect } from './MultiSelect.svelte';
+export { default as NumberField } from './NumberField.svelte';
+export { default as PasswordInput } from './PasswordInput.svelte';
+export { default as PinInput } from './PinInput.svelte';
+export { default as RadioGroup } from './RadioGroup.svelte';
+export { default as Rating } from './Rating.svelte';
+export { default as SearchInput } from './SearchInput.svelte';
+export { default as Select } from './Select.svelte';
+export { default as Slider } from './Slider.svelte';
+export { default as TagsInput } from './TagsInput.svelte';
+export { default as Textarea } from './Textarea.svelte';
+export { default as TextInput } from './TextInput.svelte';
+export { default as Toggle } from './Toggle.svelte';
+export { default as PushToggle, } from './PushToggle.svelte';
+export { default as VideoInput } from './VideoInput.svelte';
+export * from "./field-types.js";

package/dist/fields/latest-search.svelte.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The search lifecycle `Combobox` and `TagsInput` share: debounce,
+ * latest-wins and stale-while-revalidate.
+ *
+ *   debounce        a keystroke does not start a request; `debounceMs` of
+ *                   quiet does.
+ *   latest-wins     each request gets an `AbortController`, and starting a
+ *                   new one aborts the last, so a slow first response cannot
+ *                   overwrite a fast second one.
+ *   stale-while-    `results` keeps the previous answer while the next is in
+ *     revalidate    flight, with `pending` true, so a dropdown does not
+ *                   strobe on every keystroke.
+ *
+ * Reactive (`$state`) so a component reads `results`, `pending` and `error`
+ * straight into its template. Call `dispose()` from an `$effect` teardown.
+ *
+ * @module
+ */
+/** An asynchronous search: `signal` aborts when a newer query supersedes this one. */
+export type SearchFn<T> = (query: string, signal: AbortSignal) => Promise<readonly T[]>;
+/** Debounced, latest-wins search state for one input. */
+export declare class LatestSearch<T> {
+    #private;
+    /** What the last settled search returned. */
+    results: readonly T[];
+    /** A search is scheduled or in flight. */
+    pending: boolean;
+    /** The last search's failure message, if it failed. */
+    error: string | undefined;
+    /** Getters, so the component's current props are read at call time. */
+    constructor(search: () => SearchFn<T> | undefined, debounceMs: () => number);
+    /** Search for `query` after the debounce, superseding anything earlier. */
+    schedule(query: string): void;
+    /** Cancel anything scheduled or in flight and empty the results. */
+    clear(): void;
+    /** Cancel anything scheduled or in flight; for an `$effect` teardown. */
+    dispose(): void;
+}

package/dist/fields/latest-search.svelte.js

@@ -0,0 +1,85 @@
+/**
+ * The search lifecycle `Combobox` and `TagsInput` share: debounce,
+ * latest-wins and stale-while-revalidate.
+ *
+ *   debounce        a keystroke does not start a request; `debounceMs` of
+ *                   quiet does.
+ *   latest-wins     each request gets an `AbortController`, and starting a
+ *                   new one aborts the last, so a slow first response cannot
+ *                   overwrite a fast second one.
+ *   stale-while-    `results` keeps the previous answer while the next is in
+ *     revalidate    flight, with `pending` true, so a dropdown does not
+ *                   strobe on every keystroke.
+ *
+ * Reactive (`$state`) so a component reads `results`, `pending` and `error`
+ * straight into its template. Call `dispose()` from an `$effect` teardown.
+ *
+ * @module
+ */
+/** Debounced, latest-wins search state for one input. */
+export class LatestSearch {
+    /** What the last settled search returned. */
+    results = $state([]);
+    /** A search is scheduled or in flight. */
+    pending = $state(false);
+    /** The last search's failure message, if it failed. */
+    error = $state();
+    #search;
+    #debounceMs;
+    #timer;
+    #inFlight;
+    /** Getters, so the component's current props are read at call time. */
+    constructor(search, debounceMs) {
+        this.#search = search;
+        this.#debounceMs = debounceMs;
+    }
+    /** Search for `query` after the debounce, superseding anything earlier. */
+    schedule(query) {
+        if (this.#timer !== undefined)
+            clearTimeout(this.#timer);
+        this.#timer = setTimeout(() => {
+            this.#timer = undefined;
+            this.#run(query);
+        }, this.#debounceMs());
+    }
+    /** Cancel anything scheduled or in flight and empty the results. */
+    clear() {
+        this.dispose();
+        this.#inFlight = undefined;
+        this.pending = false;
+        this.results = [];
+    }
+    /** Cancel anything scheduled or in flight; for an `$effect` teardown. */
+    dispose() {
+        if (this.#timer !== undefined)
+            clearTimeout(this.#timer);
+        this.#timer = undefined;
+        this.#inFlight?.abort();
+    }
+    #run(query) {
+        const search = this.#search();
+        if (search === undefined)
+            return;
+        this.#inFlight?.abort();
+        const own = new AbortController();
+        this.#inFlight = own;
+        this.pending = true;
+        this.error = undefined;
+        // A superseded request must not write: `#inFlight` is the identity check,
+        // `signal.aborted` catches the caller aborting its own work.
+        const current = () => !own.signal.aborted && this.#inFlight === own;
+        void search(query, own.signal)
+            .then((next) => {
+            if (!current())
+                return;
+            this.results = next;
+            this.pending = false;
+        })
+            .catch((error) => {
+            if (!current())
+                return;
+            this.pending = false;
+            this.error = error instanceof Error ? error.message : String(error);
+        });
+    }
+}

package/dist/fields/number-format.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Locale-aware number formatting and parsing for `NumberField`.
+ *
+ * Formatting is `Intl.NumberFormat`. Parsing is the inverse the platform does
+ * not ship: the locale's group and decimal separators, and any literal text
+ * the options add (a unit, a currency symbol, a percent sign), are learnt
+ * from `formatToParts` on a sample number, so "1.234,5 cm" in `de-DE` and
+ * "1,234.5 cm" in `en-AU` both read back as `1234.5`.
+ *
+ * Only ASCII digits are parsed. A locale whose formatter writes other digits
+ * (Arabic-Indic, Devanagari) formats correctly but does not read its own
+ * output back; widening the parser is a later decision (#145).
+ *
+ * Pure functions, no module-level state, so the file stays tree-shakeable.
+ *
+ * @module
+ */
+/** The locales argument every function here accepts, as `Intl.NumberFormat` does. */
+export type NumberLocales = string | readonly string[] | undefined;
+/** What a locale and a set of options write around the digits. */
+export interface NumberSymbols {
+    /** The grouping separator, e.g. `','` in `en-AU`, `'.'` in `de-DE`, a narrow no-break space in `fr-FR`. */
+    readonly group: string;
+    /** The decimal separator. */
+    readonly decimal: string;
+    /** Every other non-digit string the format adds: unit, currency, percent sign, literal spacing. */
+    readonly literals: readonly string[];
+}
+/** Learn the separators and literal text a locale and options produce. */
+export declare function numberSymbols(locales: NumberLocales, options?: Intl.NumberFormatOptions): NumberSymbols;
+/** Format `value` for display; `''` for `undefined`. */
+export declare function formatNumber(value: number | undefined, locales: NumberLocales, options?: Intl.NumberFormatOptions): string;
+/**
+ * Parse text written in `locales` with `options` back into a number.
+ *
+ * Returns `undefined` for empty (or whitespace-only) text and `NaN` for text
+ * that is not a number, so a caller can tell "cleared" from "garbage".
+ * Percent-style input is divided by 100, the inverse of the formatter.
+ */
+export declare function parseNumber(text: string, locales: NumberLocales, options?: Intl.NumberFormatOptions): number | undefined;
+/** Number of decimal places in `n` as written, e.g. 2 for `0.25`, 0 for `5`. */
+export declare function decimalPlaces(n: number): number;
+/** Round `n` to `places` decimal places without binary drift (`0.1 + 0.2` → `0.3`). */
+export declare function roundTo(n: number, places: number): number;
+/**
+ * The decimal places a committed value keeps: the more of the step's and the
+ * formatter's own (a percent shows two more places of the fraction than it
+ * displays), so a value is never rounded finer than the reader can see.
+ */
+export declare function valuePrecision(step: number, locales: NumberLocales, options?: Intl.NumberFormatOptions): number;
+/** Clamp `n` into `[min, max]`; either bound may be absent. */
+export declare function clamp(n: number, min: number | undefined, max: number | undefined): number;

package/dist/fields/number-format.js

@@ -0,0 +1,89 @@
+/**
+ * Locale-aware number formatting and parsing for `NumberField`.
+ *
+ * Formatting is `Intl.NumberFormat`. Parsing is the inverse the platform does
+ * not ship: the locale's group and decimal separators, and any literal text
+ * the options add (a unit, a currency symbol, a percent sign), are learnt
+ * from `formatToParts` on a sample number, so "1.234,5 cm" in `de-DE` and
+ * "1,234.5 cm" in `en-AU` both read back as `1234.5`.
+ *
+ * Only ASCII digits are parsed. A locale whose formatter writes other digits
+ * (Arabic-Indic, Devanagari) formats correctly but does not read its own
+ * output back; widening the parser is a later decision (#145).
+ *
+ * Pure functions, no module-level state, so the file stays tree-shakeable.
+ *
+ * @module
+ */
+/** One formatter per call site; `Intl.NumberFormat` wants a mutable array. */
+function formatter(locales, options) {
+    return new Intl.NumberFormat(typeof locales === 'string' || locales === undefined ? locales : [...locales], options);
+}
+/** Learn the separators and literal text a locale and options produce. */
+export function numberSymbols(locales, options) {
+    const parts = formatter(locales, { ...options, useGrouping: true }).formatToParts(-12345.6);
+    const of = (type) => parts.find((part) => part.type === type)?.value ?? '';
+    const literals = parts
+        .filter((part) => ['literal', 'unit', 'currency', 'percentSign', 'plusSign'].includes(part.type))
+        .map((part) => part.value.trim())
+        .filter((value) => value !== '');
+    return { group: of('group'), decimal: of('decimal') || '.', literals };
+}
+/** Format `value` for display; `''` for `undefined`. */
+export function formatNumber(value, locales, options) {
+    return value === undefined ? '' : formatter(locales, options).format(value);
+}
+/** Spaces a locale may group with, all read as the same separator. */
+const SPACES = /[\s  ]/g;
+/**
+ * Parse text written in `locales` with `options` back into a number.
+ *
+ * Returns `undefined` for empty (or whitespace-only) text and `NaN` for text
+ * that is not a number, so a caller can tell "cleared" from "garbage".
+ * Percent-style input is divided by 100, the inverse of the formatter.
+ */
+export function parseNumber(text, locales, options) {
+    if (text.trim() === '')
+        return undefined;
+    const { group, decimal, literals } = numberSymbols(locales, options);
+    let rest = text;
+    // Longest first, so "US$" is removed before "$".
+    for (const literal of [...literals].sort((a, b) => b.length - a.length)) {
+        rest = rest.split(literal).join('');
+    }
+    if (group.trim() === '')
+        rest = rest.replace(SPACES, '');
+    else
+        rest = rest.split(group).join('').replace(SPACES, '');
+    rest = rest
+        .split(decimal)
+        .join('.')
+        .replace(/[−‒–]/g, '-');
+    if (!/^-?(\d+\.?\d*|\.\d+)$/.test(rest))
+        return Number.NaN;
+    const parsed = Number(rest);
+    return options?.style === 'percent' ? roundTo(parsed / 100, 15) : parsed;
+}
+/** Number of decimal places in `n` as written, e.g. 2 for `0.25`, 0 for `5`. */
+export function decimalPlaces(n) {
+    const [, fraction = ''] = String(n).split('.');
+    const exponent = /e-(\d+)$/.exec(String(n));
+    return exponent === null ? fraction.length : Number(exponent[1]) + fraction.length;
+}
+/** Round `n` to `places` decimal places without binary drift (`0.1 + 0.2` → `0.3`). */
+export function roundTo(n, places) {
+    return Number(n.toFixed(Math.min(100, Math.max(0, places))));
+}
+/**
+ * The decimal places a committed value keeps: the more of the step's and the
+ * formatter's own (a percent shows two more places of the fraction than it
+ * displays), so a value is never rounded finer than the reader can see.
+ */
+export function valuePrecision(step, locales, options) {
+    const shown = formatter(locales, options).resolvedOptions().maximumFractionDigits ?? 0;
+    return Math.max(decimalPlaces(step), shown + (options?.style === 'percent' ? 2 : 0));
+}
+/** Clamp `n` into `[min, max]`; either bound may be absent. */
+export function clamp(n, min, max) {
+    return Math.min(max ?? Number.POSITIVE_INFINITY, Math.max(min ?? Number.NEGATIVE_INFINITY, n));
+}