@nanahoshi/mona-ui 0.23.3 → 0.24.1

package/types/nanahoshi-mona-ui-common.d.ts

@@ -60,7 +60,12 @@ declare class ContainsPipe implements PipeTransform {
 }
 
 declare class SlicePipe implements PipeTransform {
-    transform<T>(value: Iterable<T>, start: number, end: number): T[];
+    /**
+     * Returns the elements from `start` up to, but not including, `end`, with the semantics of `Array.prototype.slice`:
+     * negative indices count from the end, and an omitted `end` slices to the end. Returns an empty array for
+     * `null` or `undefined`, such as the first value of the `async` pipe.
+     */
+    transform<T>(value: Iterable<T> | null | undefined, start: number, end?: number): T[];
     static ɵfac: i0.ɵɵFactoryDeclaration<SlicePipe, never>;
     static ɵpipe: i0.ɵɵPipeDeclaration<SlicePipe, "monaSlice", true>;
 }
@@ -76,10 +81,12 @@ type BuiltIn = Primitive | Date | RegExp | Function | Map<unknown, unknown> | Se
 type DeepPartial<T> = T extends BuiltIn ? T : T extends Array<infer U> ? Array<DeepPartial<U>> : {
     [P in keyof T]?: DeepPartial<T[P]>;
 };
-type Path<T> = T extends object ? {
-    [K in keyof T]-?: [
-        K
-    ] | (Path<T[K]> extends infer P ? (P extends ReadonlyArray<PropertyKey> ? [K, ...P] : never) : never);
+/**
+ * Every key path into `T`. Paths stop at built-in values (dates, maps, sets, functions), and index arrays by
+ * number, so `['tags', 0]` is a path and `['tags', 'map']` is not.
+ */
+type Path<T> = T extends BuiltIn ? never : T extends ReadonlyArray<infer U> ? [number] | (Path<U> extends infer P ? (P extends ReadonlyArray<PropertyKey> ? [number, ...P] : never) : never) : T extends object ? {
+    [K in keyof T]-?: [K] | (Path<T[K]> extends infer P ? (P extends ReadonlyArray<PropertyKey> ? [K, ...P] : never) : never);
 }[keyof T] : never;
 type PathValue<T, P> = P extends readonly [infer K, ...infer R] ? K extends keyof T ? R["length"] extends 0 ? T[K] : PathValue<T[K], Extract<R, ReadonlyArray<PropertyKey>>> : never : never;
 type ArrayStrategy = {
@@ -92,18 +99,40 @@ type ArrayStrategy = {
 };
 interface DeepMergeOptions {
     arrayStrategy?: ArrayStrategy | ((key: PropertyKey, path: ReadonlyArray<PropertyKey>) => ArrayStrategy);
+    /**
+     * What an own `undefined` value in the patch does. `"skip"` (the default) keeps the base value;
+     * `"assign"` sets the field to `undefined`.
+     */
+    undefinedValues?: "assign" | "skip";
 }
 declare const isEmptyObject: (obj: Record<PropertyKey, unknown>) => boolean;
 declare const isPlainObject: (v: unknown) => v is Record<PropertyKey, unknown>;
+/**
+ * Merges `patch` into a copy of `base`. Only plain objects (object literals, `JSON.parse` output) are merged
+ * key by key. Any other value in the patch, including a class instance, a `Date`, a `Map` or a `Set`, replaces
+ * the base value as a whole, so a partial patch for a class-instance field must carry the whole value.
+ * `__proto__` keys in the patch are ignored.
+ */
 declare function deepMerge<T>(base: T, patch: DeepPartial<T>, options?: DeepMergeOptions, path?: ReadonlyArray<PropertyKey>): T;
 declare function deepMerge<T>(base: DeepPartial<T>, patch: DeepPartial<T>, options?: DeepMergeOptions, path?: ReadonlyArray<PropertyKey>): DeepPartial<T>;
 declare function mergeInto<T>(base: T, patch: DeepPartial<T>, options?: DeepMergeOptions): T;
 declare function mergePatchInto<T>(base: DeepPartial<T>, patch: DeepPartial<T>, options?: DeepMergeOptions): DeepPartial<T>;
-declare function buildNested(keys: ReadonlyArray<PropertyKey>, leaf: unknown): Record<PropertyKey, unknown>;
-declare function patchAt<T, P extends Path<T>>(path: P, value: PathValue<T, P>): DeepPartial<T>;
+/**
+ * Builds a patch that sets `leaf` at `keys`. When `current` (the value the patch will be merged into) holds an
+ * array along the path, the patch carries a copy of that array with the one element replaced, since arrays are
+ * replaced rather than merged. Without `current`, every level is an object.
+ */
+declare function buildNested(keys: ReadonlyArray<PropertyKey>, leaf: unknown, current?: unknown): Record<PropertyKey, unknown>;
+declare function patchAt<T, P extends Path<T>>(path: P, value: PathValue<T, P>, current?: T): DeepPartial<T>;
 declare function setAt<T, P extends Path<T>>(obj: T, path: P, value: PathValue<T, P>, options?: DeepMergeOptions): T;
 declare function prunePatch<T>(base: T, patch: DeepPartial<T>): DeepPartial<T> | undefined;
 declare function prunePatch<T>(base: DeepPartial<T>, patch: DeepPartial<T>): DeepPartial<T> | undefined;
+/**
+ * Structural equality for plain objects, arrays, `Date`, `RegExp`, `Map` and `Set`. Primitives are equal when
+ * `===` says so, and `NaN` equals `NaN`. Dates are equal when they hold the same time (two invalid dates are
+ * equal). Map keys and set members are matched by `SameValueZero`, like `Map.prototype.has`. Cyclic values are
+ * supported.
+ */
 declare function deepEquals<T>(o1: T, o2: T): boolean;
 
 /**
@@ -142,18 +171,6 @@ interface IObjectPatchStore<T> {
      * pending changes (i.e. the draft is an empty object).
      */
     readonly changes: Signal<DeepPartial<T> | undefined>;
-    /**
-     * `true` when the current draft is structurally equal to the last
-     * committed snapshot, i.e. no unsaved changes exist relative to the
-     * last commit point.
-     */
-    readonly pristine: Signal<boolean>;
-    /**
-     * The live merged view of base + draft. Prefer `select()` over reading
-     * this directly in computed signals when you only care about a specific
-     * slice of the object, to avoid unnecessary downstream invalidations.
-     */
-    readonly view: Signal<T>;
     /**
      * Discard the current draft without affecting the committed snapshot.
      * The view reverts to the base value.
@@ -174,7 +191,8 @@ interface IObjectPatchStore<T> {
      * Deep-merge `patch` into the current draft. Only the fields present in
      * `patch` are affected; all other fields retain their current draft or
      * base values. Automatically prunes fields that match the base value so
-     * the draft stays minimal.
+     * the draft stays minimal. A field set to `undefined` is cleared, unless
+     * `options.undefinedValues` is `"skip"`.
      */
     patch(patch: DeepPartial<T>, options?: DeepMergeOptions): void;
     /**
@@ -185,26 +203,17 @@ interface IObjectPatchStore<T> {
      * store.patchPath(['address', 'city'], 'London');
      */
     patchPath<P extends Path<T>>(path: P, value: PathValue<T, P>, options?: DeepMergeOptions): void;
+    /**
+     * `true` when the current draft is structurally equal to the last
+     * committed snapshot, i.e. no unsaved changes exist relative to the
+     * last commit point.
+     */
+    readonly pristine: Signal<boolean>;
     /**
      * Discard both the draft and the committed snapshot, fully resetting
      * the store to a pristine, empty state.
      */
     reset(): void;
-    /**
-     * Directly replace the draft with the given patch object, bypassing the
-     * merge logic. Use with care — this does not prune against the base.
-     * Prefer `patch()` for most use cases.
-     */
-    setDraft(patch: DeepPartial<T>): void;
-    /**
-     * Convenience wrapper over `patch` that sets a single path to a value.
-     * Unlike the old implementation, this merges rather than replaces the
-     * draft, so unrelated draft fields are preserved.
-     *
-     * @example
-     * store.setPath(['address', 'city'], 'London');
-     */
-    setPath<P extends Path<T>>(path: P, value: PathValue<T, P>, options?: DeepMergeOptions): void;
     /**
      * Returns a `Signal` that emits only the slice of `view` selected by
      * `projector`. Uses `deepEquals` as the equality function, so downstream
@@ -222,6 +231,28 @@ interface IObjectPatchStore<T> {
      * readonly city = store.select(v => v.address.city);
      */
     select<R>(projector: (view: T) => R, equal?: (a: R, b: R) => boolean): Signal<R>;
+    /**
+     * Directly replace the draft with the given patch object, bypassing the
+     * merge logic. Use with care — this does not prune against the base, so
+     * a field equal to its base value still counts in `changes` and
+     * `hasDraft()`, while `pristine` ignores it. Prefer `patch()` for most use
+     * cases.
+     */
+    setDraft(patch: DeepPartial<T>): void;
+    /**
+     * Same as `patchPath`: sets a single path to a value, merging into the
+     * draft, so unrelated draft fields are preserved.
+     *
+     * @example
+     * store.setPath(['address', 'city'], 'London');
+     */
+    setPath<P extends Path<T>>(path: P, value: PathValue<T, P>, options?: DeepMergeOptions): void;
+    /**
+     * The live merged view of base + draft. Prefer `select()` over reading
+     * this directly in computed signals when you only care about a specific
+     * slice of the object, to avoid unnecessary downstream invalidations.
+     */
+    readonly view: Signal<T>;
 }
 declare class ObjectPatchStore<T> implements IObjectPatchStore<T> {
     #private;
@@ -236,11 +267,16 @@ declare class ObjectPatchStore<T> implements IObjectPatchStore<T> {
     patch(patch: DeepPartial<T>, options?: DeepMergeOptions): void;
     patchPath<P extends Path<T>>(path: P, value: PathValue<T, P>, options?: DeepMergeOptions): void;
     reset(): void;
+    select<R>(projector: (view: T) => R, equal?: (a: R, b: R) => boolean): Signal<R>;
     setDraft(patch: DeepPartial<T>): void;
     setPath<P extends Path<T>>(path: P, value: PathValue<T, P>, options?: DeepMergeOptions): void;
-    select<R>(projector: (view: T) => R, equal?: (a: R, b: R) => boolean): Signal<R>;
 }
 interface IterablePatchStoreOptions<TItem, TId> {
+    /**
+     * Controls what happens to uncommitted drafts when the base signal emits
+     * a new value. Defaults to `'wipe'`.
+     */
+    baseChangeStrategy?: BaseChangeStrategy;
     /** Extracts the stable identity key from an item. */
     idOf: (item: TItem) => TId;
     /**
@@ -248,13 +284,10 @@ interface IterablePatchStoreOptions<TItem, TId> {
      * per-row edits). Accepts either a `Map` or an `ImmutableDictionary`.
      */
     initial?: () => Map<TId, DeepPartial<TItem>> | ImmutableDictionary<TId, DeepPartial<TItem>>;
+    /** Default merge options applied to all patch operations unless overridden per-call. */
+    mergeOptions?: DeepMergeOptions;
     /** Factory that returns the authoritative base signal for this store. */
     source: () => Signal<Iterable<TItem>>;
-    /**
-     * Controls what happens to uncommitted drafts when the base signal emits
-     * a new value. Defaults to `'wipe'`.
-     */
-    baseChangeStrategy?: BaseChangeStrategy;
 }
 interface IIterablePatchStore<TItem, TId> {
     /**
@@ -262,18 +295,6 @@ interface IIterablePatchStore<TItem, TId> {
      * with its current draft. Items without a draft are excluded.
      */
     readonly changes: Signal<TItem[]>;
-    /**
-     * `true` when every item's current draft is structurally equal to its
-     * last committed snapshot.
-     */
-    readonly pristine: Signal<boolean>;
-    /**
-     * The live merged view of all base items with their drafts applied.
-     * Items without a draft are returned as-is (same reference).
-     * Prefer `select()` over reading this directly in computed signals when
-     * you only care about a specific slice.
-     */
-    readonly view: Signal<TItem[]>;
     /**
      * Discard the draft for the item identified by `id`.
      * Has no effect if the item has no draft.
@@ -298,6 +319,8 @@ interface IIterablePatchStore<TItem, TId> {
      * Deep-merge `patch` into the draft for the item identified by `id`.
      * Automatically prunes fields that now match the base item so the draft
      * stays minimal. Removes the draft entry entirely if it becomes empty.
+     * A field set to `undefined` is cleared, unless `options.undefinedValues`
+     * is `"skip"`.
      */
     patch(id: TId, patch: DeepPartial<TItem>, options?: DeepMergeOptions): void;
     /**
@@ -314,26 +337,16 @@ interface IIterablePatchStore<TItem, TId> {
      * store.patchPath(itemId, ['address', 'city'], 'London');
      */
     patchPath<P extends Path<TItem>>(id: TId, path: P, value: PathValue<TItem, P>, options?: DeepMergeOptions): void;
+    /**
+     * `true` when every item's current draft is structurally equal to its
+     * last committed snapshot.
+     */
+    readonly pristine: Signal<boolean>;
     /**
      * Discard all drafts and committed snapshots, fully resetting the store
      * to a pristine, empty state.
      */
     reset(): void;
-    /**
-     * Directly replace the draft for `id` with the given patch object,
-     * bypassing the merge logic. Use with care — this does not prune against
-     * the base item. Prefer `patch()` for most use cases.
-     */
-    setDraft(id: TId, patch: DeepPartial<TItem>): void;
-    /**
-     * Convenience wrapper over `patch` that sets a single path to a value
-     * for a specific item. Merges into the existing draft rather than
-     * replacing it, so unrelated draft fields are preserved.
-     *
-     * @example
-     * store.setPath(itemId, ['address', 'city'], 'London');
-     */
-    setPath<P extends Path<TItem>>(id: TId, path: P, value: PathValue<TItem, P>, options?: DeepMergeOptions): void;
     /**
      * Returns a `Signal` that emits only the slice of `view` selected by
      * `projector`. Uses `deepEquals` as the equality function by default,
@@ -347,6 +360,30 @@ interface IIterablePatchStore<TItem, TId> {
      * readonly cities = store.select(items => items.map(i => i.address.city));
      */
     select<R>(projector: (view: TItem[]) => R, equal?: (a: R, b: R) => boolean): Signal<R>;
+    /**
+     * Directly replace the draft for `id` with the given patch object,
+     * bypassing the merge logic. An empty patch removes the draft. Use with
+     * care — this does not prune against the base item, so a field equal to
+     * its base value still counts in `changes`, `hasDraft()` and
+     * `dirtyCount()`, while `pristine` ignores it. Prefer `patch()` for most
+     * use cases.
+     */
+    setDraft(id: TId, patch: DeepPartial<TItem>): void;
+    /**
+     * Same as `patchPath`: sets a single path to a value for a specific item,
+     * merging into the existing draft, so unrelated draft fields are preserved.
+     *
+     * @example
+     * store.setPath(itemId, ['address', 'city'], 'London');
+     */
+    setPath<P extends Path<TItem>>(id: TId, path: P, value: PathValue<TItem, P>, options?: DeepMergeOptions): void;
+    /**
+     * The live merged view of all base items with their drafts applied.
+     * Items without a draft are returned as-is (same reference).
+     * Prefer `select()` over reading this directly in computed signals when
+     * you only care about a specific slice.
+     */
+    readonly view: Signal<TItem[]>;
 }
 declare class IterablePatchStore<TItem, TId> implements IIterablePatchStore<TItem, TId> {
     #private;
@@ -360,13 +397,13 @@ declare class IterablePatchStore<TItem, TId> implements IIterablePatchStore<TIte
     dirtyCount(): number;
     getCommitted(): ImmutableDictionary<TId, DeepPartial<TItem>>;
     hasDraft(id: TId): boolean;
-    patch(id: TId, patch: DeepPartial<TItem>, options?: DeepMergeOptions): void;
-    patchMany(patchTuple: Iterable<[TId, DeepPartial<TItem>]>, options?: DeepMergeOptions): void;
+    patch(id: TId, patch: DeepPartial<TItem>, options?: DeepMergeOptions | undefined): void;
+    patchMany(patchTuple: Iterable<[TId, DeepPartial<TItem>]>, options?: DeepMergeOptions | undefined): void;
     patchPath<P extends Path<TItem>>(id: TId, path: P, value: PathValue<TItem, P>, options?: DeepMergeOptions): void;
     reset(): void;
+    select<R>(projector: (view: TItem[]) => R, equal?: (a: R, b: R) => boolean): Signal<R>;
     setDraft(id: TId, patch: DeepPartial<TItem>): void;
     setPath<P extends Path<TItem>>(id: TId, path: P, value: PathValue<TItem, P>, options?: DeepMergeOptions): void;
-    select<R>(projector: (view: TItem[]) => R, equal?: (a: R, b: R) => boolean): Signal<R>;
 }
 declare const createIterablePatchStore: <TItem, TId>(options: IterablePatchStoreOptions<TItem, TId>) => IIterablePatchStore<TItem, TId>;
 declare const createObjectPatchStore: <T>(options: ObjectPatchStoreOptions<T>) => IObjectPatchStore<T>;
@@ -378,12 +415,18 @@ declare const classInputToClass: (input: ClassInputType) => string;
  * @param value The current value.
  * @param min The minimum value.
  * @param max The maximum value.
- * @param precision The number of decimal places to round the percentage to.
+ * @param precision The number of decimal places to round the percentage to, clamped to 0–100.
  * @default 2
- * @returns The percentage of the value within the range, rounded to the specified precision.
+ * @returns The percentage of the value within the range, rounded to the specified precision, or 0 when the range
+ * or the value is not finite.
  */
 declare const getPercentage: (value: number, min: number, max: number, precision?: number) => number;
 
+/**
+ * Moves the items at `indices` by `offset` positions, keeping their relative order. Returns a copy of the array
+ * unchanged when the offset is 0 or not an integer, or when any index is not an integer, is out of bounds, or would
+ * move out of bounds. Duplicate indices count once.
+ */
 declare function moveIndices<T>(array: T[], indices: number[], offset: number): T[];
 
 export { AnyPipe, ContainsPipe, FilterChangeEvent, IterablePatchStore, ObjectPatchStore, PreventableEvent, SlicePipe, TakeFirstPipe, buildNested, classInputToClass, createIterablePatchStore, createObjectPatchStore, deepEquals, deepMerge, getPercentage, isEmptyObject, isPlainObject, mergeInto, mergePatchInto, moveIndices, patchAt, prunePatch, setAt };

package/types/nanahoshi-mona-ui-i18n-icu.d.ts

@@ -0,0 +1,74 @@
+import { MonaTextDirection, MonaLocaleMessages, MonaLocale } from '@nanahoshi/mona-ui/i18n';
+
+/**
+ * The messages of a {@link MonaLocaleData}: the same namespaces and keys as `MonaLocaleMessages`, with every message
+ * written as an ICU MessageFormat string, so a catalog is plain JSON.
+ */
+type MonaLocaleDataMessages = {
+    readonly [N in keyof MonaLocaleMessages]?: {
+        readonly [K in keyof MonaLocaleMessages[N]]?: string;
+    };
+};
+/** A locale as data, such as a JSON file exported from a translation-management system. */
+interface MonaLocaleData {
+    readonly direction: MonaTextDirection;
+    readonly id: string;
+    readonly messages: MonaLocaleDataMessages;
+}
+type MonaLocaleDataIssueCode = "invalid-direction" | "invalid-id" | "invalid-structure" | "missing-other" | "not-a-string" | "parameter-type" | "syntax" | "unknown-key" | "unknown-namespace" | "unknown-parameter";
+/** A problem found in a {@link MonaLocaleData} by `validateMonaLocaleData` or `compileMonaLocale`. */
+interface MonaLocaleDataIssue {
+    readonly code: MonaLocaleDataIssueCode;
+    /** A sentence that describes the problem. */
+    readonly message: string;
+    /** Where the problem is, such as `messages.pager.pageStatus`. */
+    readonly path: string;
+}
+interface MonaCompileLocaleOptions {
+    /**
+     * Throws a `MonaLocaleDataError` listing every issue instead of skipping the messages that have one. Defaults to
+     * `false`.
+     */
+    readonly strict?: boolean;
+}
+/** A parameter of a message, from the message function's signature. */
+interface MonaMessageParameter {
+    readonly name: string;
+    readonly optional?: boolean;
+    readonly type: "number" | "string";
+}
+
+/** Thrown by `compileMonaLocale` in strict mode when the data has issues. */
+declare class MonaLocaleDataError extends Error {
+    readonly issues: readonly MonaLocaleDataIssue[];
+    constructor(issues: readonly MonaLocaleDataIssue[]);
+}
+/**
+ * Compiles locale data, such as a JSON catalog from a translation-management system, into a `MonaLocale`. Messages
+ * with parameters become functions; plain messages become strings.
+ *
+ * By default, a message with an issue (an unknown key or parameter, or a syntax error) is skipped, so components
+ * show their English default for it, and a dev-mode warning lists the issues. With `{ strict: true }`, any issue
+ * throws a {@link MonaLocaleDataError} instead.
+ *
+ * ```ts
+ * provideMonaI18n({
+ *     loadLocale: id => fetch(`/i18n/${id}.json`).then(r => r.json()).then(data => compileMonaLocale(data))
+ * });
+ * ```
+ */
+declare function compileMonaLocale(data: MonaLocaleData, options?: MonaCompileLocaleOptions): MonaLocale;
+/**
+ * Checks locale data without compiling it, for example in CI before a catalog exported from a
+ * translation-management system ships. Returns every issue; an empty array means the data compiles cleanly.
+ */
+declare function validateMonaLocaleData(data: unknown): readonly MonaLocaleDataIssue[];
+
+/**
+ * The parameters of every message, by namespace and key, in the order the message function takes them. A plain
+ * string message has `null`.
+ */
+declare const MONA_MESSAGE_PARAMETERS: Readonly<Record<string, Readonly<Record<string, readonly MonaMessageParameter[] | null>>>>;
+
+export { MONA_MESSAGE_PARAMETERS, MonaLocaleDataError, compileMonaLocale, validateMonaLocaleData };
+export type { MonaCompileLocaleOptions, MonaLocaleData, MonaLocaleDataIssue, MonaLocaleDataIssueCode, MonaLocaleDataMessages, MonaMessageParameter };

package/types/nanahoshi-mona-ui-i18n.d.ts

@@ -483,6 +483,18 @@ interface MonaLocale {
 declare const MONA_DEFAULT_LOCALE: MonaLocale;
 
 interface MonaI18nConfig {
+    /**
+     * Locale id loaded with {@link MonaI18nConfig.loadLocale} before the application starts, so the first render
+     * is already localized. When loading fails, the application starts with {@link MonaI18nConfig.locale} (or
+     * English) and the error is logged.
+     */
+    readonly initialLocale?: string;
+    /**
+     * Loads a locale by id for `MonaI18nService.load()` and {@link MonaI18nConfig.initialLocale}. Use
+     * `loadMonaLocale` from `@nanahoshi/mona-ui/locales` for the official locales, or any function that resolves
+     * to a `MonaLocale`, such as one that fetches a catalog over HTTP.
+     */
+    readonly loadLocale?: (localeId: string) => Promise<MonaLocale>;
     readonly locale?: MonaLocale;
     /**
      * Overrides applied only while the locale with that id is active, keyed by locale id such as "de-DE".
@@ -505,6 +517,10 @@ declare const MONA_I18N_CONFIG: InjectionToken<MonaI18nConfig>;
 declare class MonaI18nService {
     #private;
     readonly direction: Signal<_nanahoshi_mona_ui_i18n.MonaTextDirection>;
+    /** The error of the latest `load()` when it failed, otherwise `null`. */
+    readonly loadError: Signal<unknown>;
+    /** Whether a `load()` is in progress and has not been superseded. */
+    readonly loading: Signal<boolean>;
     readonly locale: Signal<MonaLocale>;
     /**
      * Canonical BCP 47 id of the active locale. POSIX ids such as `en_US` are converted to `en-US`,
@@ -518,6 +534,17 @@ declare class MonaI18nService {
      */
     clearMessages(options?: MonaMessageOverrideOptions): void;
     componentMessages<K extends keyof MonaLocaleMessages>(namespace: K, fallback: MonaLocaleMessages[K]): Signal<MonaLocaleMessages[K]>;
+    /**
+     * Loads a locale with the `loadLocale` function configured in `provideMonaI18n` and switches to it.
+     *
+     * - Ids are canonicalized, and each locale is loaded once: later calls reuse it, and concurrent calls for the
+     *   same id share one request.
+     * - The latest `load()` or `use()` wins. When a newer one starts before this one finishes, this one resolves
+     *   without switching.
+     * - When loading fails, the current locale stays, `loadError` is set and the promise rejects. The failed
+     *   locale is not cached, so a later call retries it.
+     */
+    load(localeId: string): Promise<void>;
     /**
      * Merges overrides into the existing ones. With `options.locale`, they apply only while that locale is
      * active, so overrides patched for German do not show after switching to English.
@@ -527,6 +554,7 @@ declare class MonaI18nService {
      * Replaces the existing overrides. With `options.locale`, only that locale's overrides are replaced.
      */
     setMessages(messages: DeepPartial<MonaLocaleMessages>, options?: MonaMessageOverrideOptions): void;
+    /** Switches to a locale that is already loaded. It supersedes a `load()` still in progress. */
     use(locale: MonaLocale): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<MonaI18nService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<MonaI18nService>;
@@ -573,7 +601,11 @@ interface NumberGroupingPattern {
 declare function getNumberGroupingPattern(locale: string): NumberGroupingPattern;
 declare function getNumberSymbols(locale: string): NumberSymbols;
 declare function getNumberFormatter(locale: string, options?: Intl.NumberFormatOptions): Intl.NumberFormat;
-declare function formatNumber(value: number, locale: string, options?: Intl.NumberFormatOptions): string;
+/**
+ * Formats a number for the locale. A decimal string, such as one returned by {@link parseLocalizedDecimal}, is
+ * formatted exactly, without converting it to a `number` first.
+ */
+declare function formatNumber(value: number | string, locale: string, options?: Intl.NumberFormatOptions): string;
 /**
  * Converts digits of any script to ASCII digits. Full-width forms typed by CJK input methods
  * ("１２．５", "－３", "１，０００") are folded to ASCII first.
@@ -602,26 +634,96 @@ interface ParseLocalizedNumberOptions {
      */
     alternateDecimal?: boolean;
 }
+/**
+ * Why a value was refused:
+ * - `"syntax"`: the text is not a number in the locale.
+ * - `"decimals"`: it has more fraction digits than allowed.
+ * - `"precision"`: a JavaScript `number` cannot hold it exactly (an integer beyond
+ *   `Number.MAX_SAFE_INTEGER`, or more than 15 significant digits), so accepting it would silently change it.
+ */
+type LocalizedNumberInvalidReason = "decimals" | "precision" | "syntax";
 interface LocalizedNumberValidationResult {
-    value: number | null;
-    valid: boolean;
     fractionDigits: number;
+    /** Set when `valid` is false. */
+    reason?: LocalizedNumberInvalidReason;
+    valid: boolean;
+    value: number | null;
 }
+/**
+ * Parses localized text to a number. Returns `null` when the text is not a number in the locale, or when a
+ * `number` cannot hold it exactly (see {@link LocalizedNumberInvalidReason}); it never rounds silently.
+ * Use {@link parseLocalizedDecimal} for values that need more precision.
+ */
 declare function parseLocalizedNumber(text: string | null | undefined, localeId: string, options?: ParseLocalizedNumberOptions): number | null;
+/**
+ * Parses localized text with the same rules as {@link parseLocalizedNumber}, but returns a canonical decimal string
+ * (`"-1234.5"`: ASCII digits, `.` as the decimal separator, no grouping, exponent, leading zeros or trailing
+ * fraction zeros) and has no precision limit. Returns `null` when the text is not a number in the locale.
+ */
+declare function parseLocalizedDecimal(text: string | null | undefined, localeId: string, options?: ParseLocalizedNumberOptions): string | null;
 declare function validateLocalizedNumber(text: string | null | undefined, localeId: string, options?: {
     mode?: LocalizedNumberParseMode;
     decimals?: number;
 }): LocalizedNumberValidationResult;
+interface LocalizedDecimalValidationResult {
+    fractionDigits: number;
+    /** Set when `valid` is false. */
+    reason?: LocalizedNumberInvalidReason;
+    valid: boolean;
+    /** A canonical decimal string, see {@link parseLocalizedDecimal}. */
+    value: string | null;
+}
+/**
+ * Validates localized text like {@link validateLocalizedNumber}, but returns a canonical decimal string and has no
+ * precision limit, so `reason` is never `"precision"`.
+ */
+declare function validateLocalizedDecimal(text: string | null | undefined, localeId: string, options?: {
+    mode?: LocalizedNumberParseMode;
+    decimals?: number;
+}): LocalizedDecimalValidationResult;
 interface LocalizedNumberEditValidationResult {
-    readonly valid: boolean;
     readonly complete: boolean;
+    /** Set when `valid` is false. */
+    readonly reason?: LocalizedNumberInvalidReason;
+    readonly valid: boolean;
     readonly value: number | null;
 }
+interface LocalizedDecimalEditValidationResult {
+    readonly complete: boolean;
+    /** Set when `valid` is false. */
+    readonly reason?: LocalizedNumberInvalidReason;
+    readonly valid: boolean;
+    /** A canonical decimal string, see {@link parseLocalizedDecimal}. */
+    readonly value: string | null;
+}
 interface ValidateLocalizedNumberEditOptions {
     readonly decimals?: number;
     readonly allowSign?: boolean;
 }
 declare function validateLocalizedNumberEdit(text: string | null | undefined, localeId: string, options?: ValidateLocalizedNumberEditOptions): LocalizedNumberEditValidationResult;
+/**
+ * Validates text while it is typed, like {@link validateLocalizedNumberEdit}, but returns a canonical decimal string
+ * and has no precision limit.
+ */
+declare function validateLocalizedDecimalEdit(text: string | null | undefined, localeId: string, options?: ValidateLocalizedNumberEditOptions): LocalizedDecimalEditValidationResult;
+
+/**
+ * Locale id used whenever a supplied id cannot be turned into a valid BCP 47 tag.
+ * Matches the id of `MONA_DEFAULT_LOCALE`.
+ */
+declare const MONA_FALLBACK_LOCALE_ID = "en-US";
+/**
+ * Converts a locale id to a canonical BCP 47 tag, or returns `null` when it is not a valid tag.
+ *
+ * POSIX/Java style ids are accepted: `en_US` becomes `en-US`, and an encoding or modifier suffix
+ * (`de_DE.UTF-8`, `de_DE@euro`) is dropped.
+ */
+declare function tryCanonicalizeLocaleId(localeId: string | null | undefined): string | null;
+/**
+ * Converts a locale id to a canonical BCP 47 tag. Ids that are empty or not valid tags resolve to
+ * {@link MONA_FALLBACK_LOCALE_ID}, so every formatter receives the same, valid locale.
+ */
+declare function canonicalizeLocaleId(localeId: string | null | undefined): string;
 
 /**
  * Normalizes a locale string to ensure it uses the Gregorian calendar system
@@ -722,5 +824,5 @@ declare function pseudoLocalizeCatalog<T extends object>(catalog: T, options?: P
  */
 declare function generatePseudoLocale(catalogs: DeepPartial<MonaLocaleMessages>, options?: GeneratePseudoLocaleOptions): MonaLocale;
 
-export { BIDI_CONTROL_REGEX, MONA_DEFAULT_LOCALE, MONA_I18N_CONFIG, MonaDirectionService, MonaI18nService, formatGregorianDateToLocaleString, formatNumber, generatePseudoLocale, getEditDecimalSeparators, getLocaleDateInputFormat, getLocaleDateTimeInputFormat, getLocaleFirstDayOfWeek, getLocaleTimeInputFormat, getNumberFormatter, getNumberGroupingPattern, getNumberSymbols, gregorianDateTime, gregorianDateTimeFromObject, injectComponentDirection, mergeMessages, mergeTwo, normalizeGregorianLocale, normalizeLocalizedDigits, normalizeLocalizedInput, normalizeLocalizedMinus, observeComponentDirection, parseGregorianDate, parseLocalizedNumber, provideMonaI18n, pseudoLocalize, pseudoLocalizeCatalog, resolveComponentDirection, sanitizeDateText, stripBidiControls, validateLocalizedNumber, validateLocalizedNumberEdit };
-export type { CalendarMessages, DatePickerMessages, DateTimePickerMessages, DeepPartial, DialogMessages, DirectionObserverHandle, FilterMessages, GeneratePseudoLocaleOptions, LocaleFirstDayOfWeek, LocaleTimeFormatOptions, LocalizedNumberEditValidationResult, LocalizedNumberParseMode, LocalizedNumberValidationResult, MonaAutoCompleteMessages, MonaBreadcrumbMessages, MonaButtonGroupMessages, MonaCalendarMessages, MonaCardMessages, MonaChartMessages, MonaChipMessages, MonaColorGradientMessages, MonaColorPaletteMessages, MonaColorPickerMessages, MonaComboBoxMessages, MonaDatePickerMessages, MonaDateTimePickerMessages, MonaDialogMessages, MonaDropdownListMessages, MonaDropdownsMessages, MonaEditorMessages, MonaFilterMessages, MonaGridMessages, MonaI18nConfig, MonaListBoxMessages, MonaListMessages, MonaLocale, MonaLocaleMessages, MonaMessageNamespace, MonaMessageOverrideOptions, MonaMultiSelectMessages, MonaNotificationMessages, MonaNumericTextBoxMessages, MonaOtpInputMessages, MonaPagerMessages, MonaRatingMessages, MonaScrollViewMessages, MonaSheetMessages, MonaSliderMessages, MonaSpinnerMessages, MonaSplitButtonMessages, MonaSplitterMessages, MonaStepperMessages, MonaTabsMessages, MonaTextBoxMessages, MonaTextDirection, MonaTimePickerMessages, MonaTimeSelectorMessages, MonaTreeViewMessages, MonaWindowMessages, NotificationMessages, NumberGroupingPattern, NumberSymbols, ParseLocalizedNumberOptions, PseudoLocalizationOptions, SheetMessages, TimePickerMessages, TimeSelectorMessages, ValidateLocalizedNumberEditOptions, WindowMessages };
+export { BIDI_CONTROL_REGEX, MONA_DEFAULT_LOCALE, MONA_FALLBACK_LOCALE_ID, MONA_I18N_CONFIG, MonaDirectionService, MonaI18nService, canonicalizeLocaleId, formatGregorianDateToLocaleString, formatNumber, generatePseudoLocale, getEditDecimalSeparators, getLocaleDateInputFormat, getLocaleDateTimeInputFormat, getLocaleFirstDayOfWeek, getLocaleTimeInputFormat, getNumberFormatter, getNumberGroupingPattern, getNumberSymbols, gregorianDateTime, gregorianDateTimeFromObject, injectComponentDirection, mergeMessages, mergeTwo, normalizeGregorianLocale, normalizeLocalizedDigits, normalizeLocalizedInput, normalizeLocalizedMinus, observeComponentDirection, parseGregorianDate, parseLocalizedDecimal, parseLocalizedNumber, provideMonaI18n, pseudoLocalize, pseudoLocalizeCatalog, resolveComponentDirection, sanitizeDateText, stripBidiControls, tryCanonicalizeLocaleId, validateLocalizedDecimal, validateLocalizedDecimalEdit, validateLocalizedNumber, validateLocalizedNumberEdit };
+export type { CalendarMessages, DatePickerMessages, DateTimePickerMessages, DeepPartial, DialogMessages, DirectionObserverHandle, FilterMessages, GeneratePseudoLocaleOptions, LocaleFirstDayOfWeek, LocaleTimeFormatOptions, LocalizedDecimalEditValidationResult, LocalizedDecimalValidationResult, LocalizedNumberEditValidationResult, LocalizedNumberInvalidReason, LocalizedNumberParseMode, LocalizedNumberValidationResult, MonaAutoCompleteMessages, MonaBreadcrumbMessages, MonaButtonGroupMessages, MonaCalendarMessages, MonaCardMessages, MonaChartMessages, MonaChipMessages, MonaColorGradientMessages, MonaColorPaletteMessages, MonaColorPickerMessages, MonaComboBoxMessages, MonaDatePickerMessages, MonaDateTimePickerMessages, MonaDialogMessages, MonaDropdownListMessages, MonaDropdownsMessages, MonaEditorMessages, MonaFilterMessages, MonaGridMessages, MonaI18nConfig, MonaListBoxMessages, MonaListMessages, MonaLocale, MonaLocaleMessages, MonaMessageNamespace, MonaMessageOverrideOptions, MonaMultiSelectMessages, MonaNotificationMessages, MonaNumericTextBoxMessages, MonaOtpInputMessages, MonaPagerMessages, MonaRatingMessages, MonaScrollViewMessages, MonaSheetMessages, MonaSliderMessages, MonaSpinnerMessages, MonaSplitButtonMessages, MonaSplitterMessages, MonaStepperMessages, MonaTabsMessages, MonaTextBoxMessages, MonaTextDirection, MonaTimePickerMessages, MonaTimeSelectorMessages, MonaTreeViewMessages, MonaWindowMessages, NotificationMessages, NumberGroupingPattern, NumberSymbols, ParseLocalizedNumberOptions, PseudoLocalizationOptions, SheetMessages, TimePickerMessages, TimeSelectorMessages, ValidateLocalizedNumberEditOptions, WindowMessages };