@sveltier/ui 0.0.0-stage → 0.1.0-alpha.1

package/dist/core/display/display.js

@@ -0,0 +1,53 @@
+import { getContext, hasContext, setContext } from 'svelte';
+import { MediaQuery } from 'svelte/reactivity';
+import { sveltierError } from '../errors/errors.js';
+/** Breakpoints, from the narrowest viewport to the widest. */
+export const BREAKPOINTS = ['xs', 'sm', 'md', 'lg', 'xl', 'xxl'];
+const DEFAULT_THRESHOLDS = { sm: 600, md: 960, lg: 1280, xl: 1920, xxl: 2560 };
+/**
+ * Builds the breakpoint flags on one `MediaQuery` per threshold. Each flag reads only the
+ * queries it needs, so a component is updated only when its own threshold is crossed.
+ */
+export function createDisplay({ thresholds: custom, mobileBreakpoint = 'md', ssrWidth = 0 } = {}) {
+    const thresholds = { ...DEFAULT_THRESHOLDS, ...custom };
+    const widths = BREAKPOINTS.slice(1).map((name) => thresholds[name]);
+    if (widths.some((width, i) => i > 0 && width <= widths[i - 1])) {
+        throw sveltierError('SV2001', `Display thresholds must increase from sm to xxl; got ${widths.join(', ')}.`);
+    }
+    const queries = widths.map((min) => new MediaQuery(`(min-width: ${min}px)`, ssrWidth >= min));
+    // Whether the viewport is at breakpoint `i` or wider; every viewport is at least xs.
+    const atLeast = (i) => i === 0 || (queries[i - 1]?.current ?? false);
+    const mobile = BREAKPOINTS.indexOf(mobileBreakpoint);
+    const display = {
+        get name() {
+            let i = queries.length;
+            while (i > 0 && !atLeast(i))
+                i--;
+            return BREAKPOINTS[i];
+        },
+        get mobile() {
+            return !atLeast(mobile);
+        },
+        thresholds
+    };
+    BREAKPOINTS.forEach((name, i) => {
+        const define = (key, get) => Object.defineProperty(display, key, { get, enumerable: true });
+        define(name, () => atLeast(i) && !atLeast(i + 1));
+        if (i > 0 && i < queries.length) {
+            define(`${name}AndUp`, () => atLeast(i));
+            define(`${name}AndDown`, () => !atLeast(i + 1));
+        }
+    });
+    return display;
+}
+const KEY = Symbol('sveltier.display');
+let shared;
+/** Gives a subtree its display instance, built from the root's options. */
+export const setDisplayContext = (display) => setContext(KEY, display);
+/**
+ * Returns the viewport breakpoints. Call it during component initialisation. Without a
+ * provider it returns one shared instance with the default options.
+ */
+export function useDisplay() {
+    return hasContext(KEY) ? getContext(KEY) : (shared ??= createDisplay());
+}

package/dist/core/errors/codes.d.ts

@@ -0,0 +1,124 @@
+/**
+ * What an error code means: shown on the docs' errors page and in llms-full.txt. Code is marked
+ * with backticks, as in Markdown.
+ */
+export interface ErrorEntry {
+    /** `error` is thrown in every build; `warning` is logged in development only. */
+    kind: 'error' | 'warning';
+    /** The problem in a few words. */
+    title: string;
+    /** Why the library refuses. */
+    cause: string;
+    /** What to change. */
+    fix: string;
+}
+/**
+ * Every error Sveltier throws or warns with, by stable code. Thrown messages start with
+ * `[sveltier SVxxxx]` and end with a link to the code's entry in the docs. A code keeps its
+ * meaning forever; its words may improve. Codes group by area: 1xxx themes, 2xxx the core
+ * engine, 3xxx primitives, 4xxx components, 5xxx forms.
+ *
+ * @example
+ * import { ERROR_CODES } from '@sveltier/ui';
+ * ERROR_CODES.SV1001.fix; // "Pass at least one theme pack: …"
+ */
+export declare const ERROR_CODES: {
+    readonly SV1001: {
+        readonly kind: "error";
+        readonly title: "The root ThemeProvider has no themes";
+        readonly cause: "The outermost `<ThemeProvider>`, which `<UIProvider>` renders, registers the themes an app can show. None were passed, so there is nothing to paint.";
+        readonly fix: "Pass at least one theme pack: `themes={monolith}` from `'@sveltier/ui/themes/monolith'`, or several at once: `themes={{ ...monolith, ...maison }}`.";
+    };
+    readonly SV1002: {
+        readonly kind: "error";
+        readonly title: "Unknown theme";
+        readonly cause: "A theme was chosen by a name that is not registered: through the `theme` prop, `useTheme().set()`, or the `light`, `dark` or `fallback` options of `themeCss()`.";
+        readonly fix: "Use a registered name, such as `\"monolith-light\"`, or `\"system\"` to follow the operating system. To offer another theme, register it in the `themes` of the root provider.";
+    };
+    readonly SV1003: {
+        readonly kind: "error";
+        readonly title: "Invalid colour or variable name";
+        readonly cause: "The colours and variables of a theme become CSS custom properties, so their names must be valid identifiers.";
+        readonly fix: "Start the name with a letter and use only letters, digits, `-` and `_`, for example `brand` or `radius-card`.";
+    };
+    readonly SV1004: {
+        readonly kind: "error";
+        readonly title: "Unsafe theme value";
+        readonly cause: "Theme values are written into a `<style>` element. A value containing `<`, `>`, `{`, `}` or `;` could end the rule or the element early.";
+        readonly fix: "Use a plain CSS value, such as `oklch(0.62 0.19 255)` or `8px`.";
+    };
+    readonly SV1005: {
+        readonly kind: "error";
+        readonly title: "Invalid theme name";
+        readonly cause: "Theme names are written into the `data-sv-theme` attribute and its CSS selectors.";
+        readonly fix: "Start the name with a letter and use only letters, digits, `-` and `_`. `\"system\"` is reserved for following the operating system.";
+    };
+    readonly SV1006: {
+        readonly kind: "error";
+        readonly title: "Invalid nonce";
+        readonly cause: "The nonce is copied into the attributes of the theme's `<style>` and `<script>`, so it must be a plain base64 value.";
+        readonly fix: "Pass the nonce of your Content Security Policy as it is, for example SvelteKit's `%sveltekit.nonce%`.";
+    };
+    readonly SV1007: {
+        readonly kind: "error";
+        readonly title: "useTheme() outside a ThemeProvider";
+        readonly cause: "`useTheme()` reads the theme from the component tree, and there is no `<UIProvider>` or `<ThemeProvider>` above the component that called it.";
+        readonly fix: "Wrap the app in `<UIProvider>` in the root layout, and call `useTheme()` while a component inside it initialises.";
+    };
+    readonly SV2001: {
+        readonly kind: "error";
+        readonly title: "Display thresholds out of order";
+        readonly cause: "Breakpoints are minimum widths, so each one must be wider than the one before it.";
+        readonly fix: "Give widths that increase from `sm` to `xxl`, for example `{ sm: 600, md: 960, lg: 1280, xl: 1920, xxl: 2560 }`.";
+    };
+    readonly SV2002: {
+        readonly kind: "warning";
+        readonly title: "Invalid prop value";
+        readonly cause: "A prop that takes one of a fixed set of values got another one, for example `variant=\"primary\"` on a `Button`. Types catch this when the code is checked; the warning catches values that get past them, such as data from an API.";
+        readonly fix: "Use one of the values the message lists. The type of the prop and the props table of the component list them too.";
+    };
+    readonly SV3001: {
+        readonly kind: "error";
+        readonly title: "Portal target not found";
+        readonly cause: "A Portal moves its content into its target, and no element matched the target selector when the Portal mounted.";
+        readonly fix: "Render the target before the Portal, correct the selector, or pass the element itself.";
+    };
+    readonly SV3002: {
+        readonly kind: "error";
+        readonly title: "Invalid item size";
+        readonly cause: "`virtualList` places items by their sizes, so every size must be a positive number of pixels.";
+        readonly fix: "Pass a positive number, or a function that returns one for every index. For items whose size is unknown, pass an estimate and measure them with `{@attach list.measure}`.";
+    };
+    readonly SV3003: {
+        readonly kind: "error";
+        readonly title: "Measured item without an index";
+        readonly cause: "`list.measure` reads the index of each measured element from its `data-index` attribute.";
+        readonly fix: "Add `data-index={item.index}` to every element that has `{@attach list.measure}`.";
+    };
+    readonly SV4001: {
+        readonly kind: "error";
+        readonly title: "Closable chip that is also a button or a link";
+        readonly cause: "A closable chip contains a close button, and a button cannot be placed inside another button or a link.";
+        readonly fix: "Keep the chip `closable` and put its action in a `Button` next to it, or remove `closable`.";
+    };
+    readonly SV4002: {
+        readonly kind: "warning";
+        readonly title: "Tooltip on a control without an accessible name";
+        readonly cause: "A tooltip describes the control it is on; it does not name it. A control with no text, `aria-label` or `aria-labelledby`, such as an icon-only button, is announced without a name.";
+        readonly fix: "Give the control `aria-label`, as every icon-only button needs, or visible text. The tooltip can then say more than the name.";
+    };
+    readonly SV4003: {
+        readonly kind: "error";
+        readonly title: "useToast() outside a UIProvider";
+        readonly cause: "`useToast()` reads the toasts from the component tree, and there is no `<UIProvider>` or `<ToastProvider>` above the component that called it.";
+        readonly fix: "Wrap the app in `<UIProvider>` in the root layout, or in `<ToastProvider>` when it uses `<ThemeProvider>` alone, and call `useToast()` while a component inside it initialises.";
+    };
+    readonly SV5001: {
+        readonly kind: "warning";
+        readonly title: "Field or dialog without an accessible name";
+        readonly cause: "Assistive technology announces a form control or a dialog by its name, and this one has no label, title, `aria-label` or `aria-labelledby`.";
+        readonly fix: "Give a field a `label` and a dialog a `title`, or name it with `aria-label`, or with `aria-labelledby` when its name is visible elsewhere.";
+    };
+};
+/** A stable error code, such as `'SV1001'`. */
+export type ErrorCode = keyof typeof ERROR_CODES;

package/dist/core/errors/codes.js

@@ -0,0 +1,108 @@
+/**
+ * Every error Sveltier throws or warns with, by stable code. Thrown messages start with
+ * `[sveltier SVxxxx]` and end with a link to the code's entry in the docs. A code keeps its
+ * meaning forever; its words may improve. Codes group by area: 1xxx themes, 2xxx the core
+ * engine, 3xxx primitives, 4xxx components, 5xxx forms.
+ *
+ * @example
+ * import { ERROR_CODES } from '@sveltier/ui';
+ * ERROR_CODES.SV1001.fix; // "Pass at least one theme pack: …"
+ */
+export const ERROR_CODES = {
+    SV1001: {
+        kind: 'error',
+        title: 'The root ThemeProvider has no themes',
+        cause: 'The outermost `<ThemeProvider>`, which `<UIProvider>` renders, registers the themes an app can show. None were passed, so there is nothing to paint.',
+        fix: "Pass at least one theme pack: `themes={monolith}` from `'@sveltier/ui/themes/monolith'`, or several at once: `themes={{ ...monolith, ...maison }}`."
+    },
+    SV1002: {
+        kind: 'error',
+        title: 'Unknown theme',
+        cause: 'A theme was chosen by a name that is not registered: through the `theme` prop, `useTheme().set()`, or the `light`, `dark` or `fallback` options of `themeCss()`.',
+        fix: 'Use a registered name, such as `"monolith-light"`, or `"system"` to follow the operating system. To offer another theme, register it in the `themes` of the root provider.'
+    },
+    SV1003: {
+        kind: 'error',
+        title: 'Invalid colour or variable name',
+        cause: 'The colours and variables of a theme become CSS custom properties, so their names must be valid identifiers.',
+        fix: 'Start the name with a letter and use only letters, digits, `-` and `_`, for example `brand` or `radius-card`.'
+    },
+    SV1004: {
+        kind: 'error',
+        title: 'Unsafe theme value',
+        cause: 'Theme values are written into a `<style>` element. A value containing `<`, `>`, `{`, `}` or `;` could end the rule or the element early.',
+        fix: 'Use a plain CSS value, such as `oklch(0.62 0.19 255)` or `8px`.'
+    },
+    SV1005: {
+        kind: 'error',
+        title: 'Invalid theme name',
+        cause: 'Theme names are written into the `data-sv-theme` attribute and its CSS selectors.',
+        fix: 'Start the name with a letter and use only letters, digits, `-` and `_`. `"system"` is reserved for following the operating system.'
+    },
+    SV1006: {
+        kind: 'error',
+        title: 'Invalid nonce',
+        cause: "The nonce is copied into the attributes of the theme's `<style>` and `<script>`, so it must be a plain base64 value.",
+        fix: "Pass the nonce of your Content Security Policy as it is, for example SvelteKit's `%sveltekit.nonce%`."
+    },
+    SV1007: {
+        kind: 'error',
+        title: 'useTheme() outside a ThemeProvider',
+        cause: '`useTheme()` reads the theme from the component tree, and there is no `<UIProvider>` or `<ThemeProvider>` above the component that called it.',
+        fix: 'Wrap the app in `<UIProvider>` in the root layout, and call `useTheme()` while a component inside it initialises.'
+    },
+    SV2001: {
+        kind: 'error',
+        title: 'Display thresholds out of order',
+        cause: 'Breakpoints are minimum widths, so each one must be wider than the one before it.',
+        fix: 'Give widths that increase from `sm` to `xxl`, for example `{ sm: 600, md: 960, lg: 1280, xl: 1920, xxl: 2560 }`.'
+    },
+    SV2002: {
+        kind: 'warning',
+        title: 'Invalid prop value',
+        cause: 'A prop that takes one of a fixed set of values got another one, for example `variant="primary"` on a `Button`. Types catch this when the code is checked; the warning catches values that get past them, such as data from an API.',
+        fix: 'Use one of the values the message lists. The type of the prop and the props table of the component list them too.'
+    },
+    SV3001: {
+        kind: 'error',
+        title: 'Portal target not found',
+        cause: 'A Portal moves its content into its target, and no element matched the target selector when the Portal mounted.',
+        fix: 'Render the target before the Portal, correct the selector, or pass the element itself.'
+    },
+    SV3002: {
+        kind: 'error',
+        title: 'Invalid item size',
+        cause: '`virtualList` places items by their sizes, so every size must be a positive number of pixels.',
+        fix: 'Pass a positive number, or a function that returns one for every index. For items whose size is unknown, pass an estimate and measure them with `{@attach list.measure}`.'
+    },
+    SV3003: {
+        kind: 'error',
+        title: 'Measured item without an index',
+        cause: '`list.measure` reads the index of each measured element from its `data-index` attribute.',
+        fix: 'Add `data-index={item.index}` to every element that has `{@attach list.measure}`.'
+    },
+    SV4001: {
+        kind: 'error',
+        title: 'Closable chip that is also a button or a link',
+        cause: 'A closable chip contains a close button, and a button cannot be placed inside another button or a link.',
+        fix: 'Keep the chip `closable` and put its action in a `Button` next to it, or remove `closable`.'
+    },
+    SV4002: {
+        kind: 'warning',
+        title: 'Tooltip on a control without an accessible name',
+        cause: 'A tooltip describes the control it is on; it does not name it. A control with no text, `aria-label` or `aria-labelledby`, such as an icon-only button, is announced without a name.',
+        fix: 'Give the control `aria-label`, as every icon-only button needs, or visible text. The tooltip can then say more than the name.'
+    },
+    SV4003: {
+        kind: 'error',
+        title: 'useToast() outside a UIProvider',
+        cause: '`useToast()` reads the toasts from the component tree, and there is no `<UIProvider>` or `<ToastProvider>` above the component that called it.',
+        fix: 'Wrap the app in `<UIProvider>` in the root layout, or in `<ToastProvider>` when it uses `<ThemeProvider>` alone, and call `useToast()` while a component inside it initialises.'
+    },
+    SV5001: {
+        kind: 'warning',
+        title: 'Field or dialog without an accessible name',
+        cause: 'Assistive technology announces a form control or a dialog by its name, and this one has no label, title, `aria-label` or `aria-labelledby`.',
+        fix: 'Give a field a `label` and a dialog a `title`, or name it with `aria-label`, or with `aria-labelledby` when its name is visible elsewhere.'
+    }
+};

package/dist/core/errors/errors.d.ts

@@ -0,0 +1,8 @@
+import type { ErrorCode } from './codes.js';
+/** The docs page that explains every error code, each under its own anchor. */
+export declare const ERRORS_URL = "https://sveltier.com/errors";
+/**
+ * An error of the library: `[sveltier SV4001] What happened and what to do. <link>`. The
+ * message carries the values involved; the linked entry explains the code.
+ */
+export declare const sveltierError: (code: ErrorCode, message: string) => Error;

package/dist/core/errors/errors.js

@@ -0,0 +1,7 @@
+/** The docs page that explains every error code, each under its own anchor. */
+export const ERRORS_URL = 'https://sveltier.com/errors';
+/**
+ * An error of the library: `[sveltier SV4001] What happened and what to do. <link>`. The
+ * message carries the values involved; the linked entry explains the code.
+ */
+export const sveltierError = (code, message) => new Error(`[sveltier ${code}] ${message} ${ERRORS_URL}#${code}`);

package/dist/core/form/constraints.d.ts

@@ -0,0 +1,15 @@
+import type { LocaleInstance } from '../locale/locale.js';
+/** The HTML constraints of a text control. */
+export interface TextConstraints {
+    required?: boolean | null;
+    minlength?: number | null;
+    maxlength?: number | null;
+    pattern?: string | null;
+    type?: string | null;
+}
+/**
+ * The message for the first HTML constraint that `value` breaks, worded by the locale. As in
+ * HTML, an empty value can only break `required`. Lengths are counted here rather than read
+ * from `validity`, which browsers only update after typing.
+ */
+export declare function textConstraintMessage(value: string, constraints: TextConstraints, t: LocaleInstance['t']): string | undefined;

package/dist/core/form/constraints.js

@@ -0,0 +1,42 @@
+// The valid e-mail address of the HTML specification.
+const EMAIL = /^[\w.!#$%&'*+/=?^`{|}~-]+@[a-z\d](?:[a-z\d-]{0,61}[a-z\d])?(?:\.[a-z\d](?:[a-z\d-]{0,61}[a-z\d])?)*$/i;
+// Compiled the way browsers compile the pattern attribute. Keys are the app's own patterns, not
+// user input, so the cache is safe to share across server requests. An invalid pattern checks
+// nothing, as in browsers.
+const patterns = new Map();
+function compile(pattern) {
+    let regexp = patterns.get(pattern);
+    if (regexp === undefined) {
+        try {
+            regexp = new RegExp(`^(?:${pattern})$`, 'v');
+        }
+        catch {
+            regexp = null;
+        }
+        patterns.set(pattern, regexp);
+    }
+    return regexp;
+}
+/**
+ * The message for the first HTML constraint that `value` breaks, worded by the locale. As in
+ * HTML, an empty value can only break `required`. Lengths are counted here rather than read
+ * from `validity`, which browsers only update after typing.
+ */
+export function textConstraintMessage(value, constraints, t) {
+    const { required, minlength, maxlength, pattern, type } = constraints;
+    if (value === '')
+        return required ? t('required') : undefined;
+    if (minlength != null && value.length < Number(minlength)) {
+        return t('tooShort', { min: Number(minlength) });
+    }
+    if (maxlength != null && maxlength >= 0 && value.length > Number(maxlength)) {
+        return t('tooLong', { max: Number(maxlength) });
+    }
+    if (type === 'email' && !EMAIL.test(value))
+        return t('typeEmail');
+    if (type === 'url' && !URL.canParse(value))
+        return t('typeUrl');
+    if (pattern && compile(pattern)?.test(value) === false)
+        return t('patternMismatch');
+    return undefined;
+}

package/dist/core/form/context.d.ts

@@ -0,0 +1,19 @@
+import type { ValidateOn } from './types.js';
+/** What a field gives the form it is in. */
+export interface FormField {
+    /** Shows the field's message; `true` when its value passes its own checks. */
+    validate(): boolean;
+    /** Hides the message and forgets that the user changed the value. */
+    resetValidation(): void;
+    /** The control, focused when it is the first invalid one. */
+    control(): HTMLElement | null | undefined;
+}
+/** What a `Form` gives its fields. */
+export interface FormContext {
+    /** When fields without their own `validateOn` show their messages. */
+    readonly validateOn: ValidateOn | undefined;
+    /** Adds a field; returns the function that removes it. */
+    register(field: FormField): () => void;
+}
+export declare const getFormContext: () => FormContext | undefined;
+export declare const setFormContext: (context: FormContext) => FormContext;

package/dist/core/form/context.js

@@ -0,0 +1,4 @@
+import { getContext, hasContext, setContext } from 'svelte';
+const KEY = Symbol('sveltier.form');
+export const getFormContext = () => hasContext(KEY) ? getContext(KEY) : undefined;
+export const setFormContext = (context) => setContext(KEY, context);

package/dist/core/form/field.svelte.d.ts

@@ -0,0 +1,34 @@
+import type { FieldError, Rule, ValidateOn } from './types.js';
+type Control = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
+export interface FieldOptions<T> {
+    /** The current value. */
+    value: () => T;
+    /** Whether a value counts as empty. Rules do not run on an empty value. */
+    empty: (value: T) => boolean;
+    /** The control's own checks (`required` and the HTML constraints): a message or undefined. */
+    check: (value: T) => string | undefined;
+    rules: () => readonly Rule<T>[] | null | undefined;
+    error: () => FieldError | undefined;
+    validateOn: () => ValidateOn | null | undefined;
+    /** The native control, kept in step with `setCustomValidity()`. */
+    control: () => Control | null | undefined;
+}
+export interface FieldState {
+    /**
+     * What the field shows: the outside error, else its own message once shown; `true` for an
+     * invalid state without a message, `false` when valid.
+     */
+    readonly error: string | boolean;
+    /** Call when the user changes the value. */
+    changed(): void;
+    /** Call when focus leaves the field. */
+    left(): void;
+}
+/** A FieldError as a message, `true` for invalid without one, or `false`. */
+export declare function readError(error: FieldError | undefined): string | boolean;
+/**
+ * The validation of one field. Its message is always derived from the current value; the
+ * timing (`validateOn`) only decides when it is shown. Call during component initialisation.
+ */
+export declare function createField<T>(options: FieldOptions<T>): FieldState;
+export {};

package/dist/core/form/field.svelte.js

@@ -0,0 +1,66 @@
+import { getFormContext } from './context.js';
+/** A FieldError as a message, `true` for invalid without one, or `false`. */
+export function readError(error) {
+    if (typeof error === 'string')
+        return error || false;
+    if (Array.isArray(error))
+        return error[0] || false;
+    return error === true;
+}
+/**
+ * The validation of one field. Its message is always derived from the current value; the
+ * timing (`validateOn`) only decides when it is shown. Call during component initialisation.
+ */
+export function createField(options) {
+    const form = getFormContext();
+    let shown = $state(false);
+    let dirty = false;
+    // First problem: the control's own checks, then the rules, which skip empty values.
+    const problem = $derived.by(() => {
+        const value = options.value();
+        const own = options.check(value);
+        if (own !== undefined || options.empty(value))
+            return own;
+        for (const rule of options.rules() ?? []) {
+            const result = rule(value);
+            if (result !== true)
+                return result;
+        }
+        return undefined;
+    });
+    const outside = $derived(readError(options.error()));
+    const mode = $derived(options.validateOn() ?? form?.validateOn ?? 'blur');
+    // A plain <form> refuses to submit with the same words. Errors from outside are left out,
+    // so a server's answer never blocks submitting again.
+    $effect(() => {
+        options.control()?.setCustomValidity(problem ?? '');
+    });
+    // In a Form, the field takes part in its submit and reset.
+    $effect(() => form?.register({
+        validate() {
+            shown = true;
+            return problem === undefined;
+        },
+        resetValidation() {
+            shown = false;
+            dirty = false;
+        },
+        control: options.control
+    }));
+    return {
+        get error() {
+            if (typeof outside === 'string')
+                return outside;
+            return (shown && problem) || outside;
+        },
+        changed() {
+            dirty = true;
+            if (mode === 'input')
+                shown = true;
+        },
+        left() {
+            if (dirty && mode !== 'submit')
+                shown = true;
+        }
+    };
+}

package/dist/core/form/number.d.ts

@@ -0,0 +1,24 @@
+import type { LocaleInstance } from '../locale/locale.js';
+/**
+ * Reads what the user typed as a number written in `locale`: group separators and spaces are
+ * ignored, the locale's decimal separator and minus sign are understood. `null` when nothing was
+ * typed, `NaN` when the text is not a number.
+ *
+ * @example
+ * parseNumber('1,234.5', 'en-US'); // 1234.5
+ * parseNumber('1.234,5', 'de-DE'); // 1234.5
+ * parseNumber('', 'en-US'); // null
+ */
+export declare function parseNumber(text: string, locale: string): number | null;
+/** The HTML constraints of a number field. */
+export interface NumberConstraints {
+    required?: boolean | null;
+    min?: number | null;
+    max?: number | null;
+    step?: number | null;
+}
+/**
+ * The message for the first constraint `value` breaks, worded by the locale, with numbers in its
+ * format. `NaN` stands for text that is not a number. As in HTML, steps count from `min`.
+ */
+export declare function numberConstraintMessage(value: number | null, constraints: NumberConstraints, locale: LocaleInstance): string | undefined;

package/dist/core/form/number.js

@@ -0,0 +1,71 @@
+// The separators each locale writes numbers with, read once per locale from Intl. Keys are
+// locale tags, not user data, so the cache is safe to share across server requests.
+const symbols = new Map();
+function symbolsOf(locale) {
+    let found = symbols.get(locale);
+    if (!found) {
+        const parts = new Intl.NumberFormat(locale).formatToParts(-12345.6);
+        const part = (type) => parts.find((item) => item.type === type)?.value;
+        found = {
+            group: part('group') ?? ',',
+            decimal: part('decimal') ?? '.',
+            minus: part('minusSign') ?? '-'
+        };
+        symbols.set(locale, found);
+    }
+    return found;
+}
+const SPACE = /[\s\u00a0\u202f]/;
+const SPACES = /[\s\u00a0\u202f]/g;
+const PLAIN = /^[-+]?(?:\d+(?:\.\d*)?|\.\d+)$/;
+/**
+ * Reads what the user typed as a number written in `locale`: group separators and spaces are
+ * ignored, the locale's decimal separator and minus sign are understood. `null` when nothing was
+ * typed, `NaN` when the text is not a number.
+ *
+ * @example
+ * parseNumber('1,234.5', 'en-US'); // 1234.5
+ * parseNumber('1.234,5', 'de-DE'); // 1234.5
+ * parseNumber('', 'en-US'); // null
+ */
+export function parseNumber(text, locale) {
+    const { group, decimal, minus } = symbolsOf(locale);
+    let plain = text.trim();
+    if (plain === '')
+        return null;
+    if (!SPACE.test(group))
+        plain = plain.split(group).join('');
+    plain = plain
+        .replace(SPACES, '')
+        .split(minus)
+        .join('-')
+        .replace('\u2212', '-')
+        .split(decimal)
+        .join('.');
+    return PLAIN.test(plain) ? Number(plain) : Number.NaN;
+}
+/** Whether `value` is a whole number of steps from `base`, allowing for binary rounding. */
+function onStep(value, step, base) {
+    const steps = (value - base) / step;
+    return Math.abs(steps - Math.round(steps)) < 1e-9;
+}
+/**
+ * The message for the first constraint `value` breaks, worded by the locale, with numbers in its
+ * format. `NaN` stands for text that is not a number. As in HTML, steps count from `min`.
+ */
+export function numberConstraintMessage(value, constraints, locale) {
+    const { required, min, max, step } = constraints;
+    if (value === null)
+        return required ? locale.t('required') : undefined;
+    if (Number.isNaN(value))
+        return locale.t('badInput');
+    const format = (number) => locale.formatNumber(number, { maximumFractionDigits: 20 });
+    if (min != null && value < min)
+        return locale.t('rangeUnderflow', { min: format(min) });
+    if (max != null && value > max)
+        return locale.t('rangeOverflow', { max: format(max) });
+    if (step != null && step > 0 && !onStep(value, step, min ?? 0)) {
+        return locale.t('stepMismatch', { step: format(step) });
+    }
+    return undefined;
+}

package/dist/core/form/types.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A validation rule: `true` when the value is valid, otherwise the message to show. Rules run
+ * in order after the control's HTML constraints, and the first message wins. They are
+ * synchronous: a check that needs the server belongs in the submit handler, whose answer comes
+ * back through the field's `error`.
+ *
+ * @example
+ * const rules = [(value: string) => value.endsWith('.com') || 'Use a .com address'];
+ */
+export type Rule<T> = (value: T) => true | string;
+export declare const VALIDATE_ON: readonly ["blur", "input", "submit"];
+/**
+ * When a field shows its message: `'blur'` once the user has changed the value and leaves the
+ * field, `'input'` from the first change, `'submit'` when the form is submitted. Once shown, the
+ * message follows every change, so fixing the value clears it at once.
+ */
+export type ValidateOn = (typeof VALIDATE_ON)[number];
+/**
+ * An error from outside the field, such as the server's answer: a message, a list of messages
+ * of which the first is shown, or `true` for an invalid state described elsewhere.
+ */
+export type FieldError = string | readonly string[] | boolean | null;

package/dist/core/form/types.js

@@ -0,0 +1 @@
+export const VALIDATE_ON = ['blur', 'input', 'submit'];