@baseline-ui/core 2.2.0 → 3.0.0

package/dist/index.d.ts

@@ -1507,6 +1507,21 @@ interface AutocompleteProps<T = object> extends AriaAutocompleteProps<T>, SlotPr
  */
 declare function Autocomplete<T>(props: AutocompleteProps<T>): JSX.Element;
 
+interface Filter {
+    /** Returns whether a string starts with a given substring. */
+    startsWith: (string: string, substring: string) => boolean;
+    /** Returns whether a string ends with a given substring. */
+    endsWith: (string: string, substring: string) => boolean;
+    /** Returns whether a string contains a given substring. */
+    contains: (string: string, substring: string) => boolean;
+}
+/**
+ * Provides localized string search functionality that is useful for filtering or matching items in
+ * a list. Options can be provided to adjust the sensitivity to case, diacritics, and other
+ * parameters.
+ */
+declare function useFilter(options?: Intl.CollatorOptions): Filter;
+
 interface LinkProps$1 extends PressEvents, FocusableProps$1 {
 }
 interface AriaLinkProps extends LinkProps$1, LinkDOMProps, AriaLabelingProps {
@@ -5544,21 +5559,6 @@ interface I18nProviderProps$1 {
  */
 declare function useLocale(): Locale;
 
-interface Filter {
-    /** Returns whether a string starts with a given substring. */
-    startsWith: (string: string, substring: string) => boolean;
-    /** Returns whether a string ends with a given substring. */
-    endsWith: (string: string, substring: string) => boolean;
-    /** Returns whether a string contains a given substring. */
-    contains: (string: string, substring: string) => boolean;
-}
-/**
- * Provides localized string search functionality that is useful for filtering or matching items in
- * a list. Options can be provided to adjust the sensitivity to case, diacritics, and other
- * parameters.
- */
-declare function useFilter(options?: Intl.CollatorOptions): Filter;
-
 interface PressProps extends PressEvents {
     /** Whether the target is in a controlled press state (e.g. an overlay it triggers is open). */
     isPressed?: boolean;
@@ -7298,7 +7298,7 @@ interface IconColorInputProps extends StylingProps, Omit<ColorInputProps, "rende
 
 declare const ColorInput: React__default.ForwardRefExoticComponent<ColorInputProps & React__default.RefAttributes<HTMLDivElement>>;
 
-declare const IconColorInputButton: React__default.ForwardRefExoticComponent<Omit<ColorInputButtonProps, "children" | "color" | "labelPosition" | "noneLabel"> & {
+declare const IconColorInputButton: React__default.ForwardRefExoticComponent<Omit<ColorInputButtonProps, "color" | "children" | "labelPosition" | "noneLabel"> & {
     icon: React__default.FC<IconProps>;
     color?: string | null;
 } & React__default.RefAttributes<HTMLButtonElement>>;
@@ -7841,19 +7841,135 @@ interface PaginationProps extends Omit<AriaNumberFieldProps, Excluded>, Omit<Num
 
 declare const Pagination: React__default.ForwardRefExoticComponent<PaginationProps & React__default.RefAttributes<HTMLDivElement>>;
 
+interface MessageIssueBase {
+    /**
+     * The active locale, except for `locale-alias-collision` — there it is the
+     * hyphenated catalog key that won. For a malformed `defaultMessage` it is
+     * still the active locale, though that template is locale-independent.
+     */
+    locale: string;
+    /**
+     * Human-readable description of the failure. Some issues name detail no field
+     * carries, so this is what the console channel prints — but its **wording is
+     * not part of the public contract**: branch on `code` and the fields beside
+     * it rather than parsing this.
+     */
+    message: string;
+}
+/**
+ * A single message-resolution failure, as reported to `onMessageIssue`.
+ * Discriminated on `code`, so `id` is guaranteed on the issues that name one
+ * and `error` is reachable only where something actually threw.
+ *
+ * The `?: undefined` members are what let a consumer read `issue.id` before
+ * narrowing on `code`; declaring them absent instead would make that a type
+ * error on the codes that carry no id.
+ */
+type MessageIssue = (MessageIssueBase & {
+    code: "missing-message" | "deprecated-message-id";
+    id: string;
+    source?: undefined;
+    error?: undefined;
+}) | (MessageIssueBase & {
+    code: "malformed-message";
+    id: string;
+    /**
+     * Which template would not format: `"catalog"` is an entry from the
+     * `messages` you supplied, `"defaultMessage"` the English fallback on the
+     * descriptor passed to `formatMessage`. They route differently — one is a
+     * translation to fix, the other a defect in the declaring code.
+     */
+    source: "catalog" | "defaultMessage";
+    /**
+     * Whatever the formatter threw. Untyped because nothing guarantees an
+     * `Error` — narrow with `error instanceof Error ? error.message :
+     * String(error)`.
+     */
+    error: unknown;
+}) | (MessageIssueBase & {
+    code: "no-catalog-for-locale" | "locale-alias-collision";
+    id?: undefined;
+    source?: undefined;
+    error?: undefined;
+});
+/**
+ * The kinds of message-resolution failure `I18nProvider` reports.
+ *
+ * - `missing-message` — no supplied catalog answers for the id, so its
+ *   `defaultMessage` renders instead (or the id itself, when it declares none).
+ *   Reported for any id, an app's own as much as Baseline UI's. Supplying no
+ *   catalogs at all is the English-only mode rather than a gap, so there a
+ *   descriptor carrying a `defaultMessage` reports nothing; a bare id, which
+ *   reaches the screen raw, still does.
+ * - `malformed-message` — a catalog entry (or a `defaultMessage`) could not be
+ *   parsed or formatted as an ICU template; `source` says which. Covers a
+ *   template that will not parse and a placeholder value the caller did not
+ *   supply, for any id, since whoever wrote the template can act on it.
+ * - `deprecated-message-id` — the id resolved only through the deprecated
+ *   bare-id fallback (`bui.editor.bold` answered by `bold`). Reported for
+ *   Baseline UI's own `bui.*` ids only, the only ones that migration covers. In
+ *   development, `message` also names the other ids that bare id answers for;
+ *   production builds drop that detail to keep the id map out of the bundle.
+ * - `no-catalog-for-locale` — catalogs were supplied, but none of them covers
+ *   the active locale, so every message falls back to its `defaultMessage`, or
+ *   to its id where it has none. Raised once for the locale rather than per
+ *   message, so it carries no `id`, and no longer gated on the `bui.` prefix.
+ *   Not raised when the active locale is itself English, where falling back is
+ *   the intended result.
+ * - `locale-alias-collision` — the same locale was supplied under two ID
+ *   formats (`pt_BR` and `pt-BR`); the hyphenated entry wins.
+ *
+ * Further codes may be added in a minor release. Handle the ones you care
+ * about and let the rest fall through to a default branch.
+ */
+type MessageIssueCode = MessageIssue["code"];
 interface I18nProviderProps extends I18nProviderProps$1 {
     messages?: LocalizedStrings;
     children: React__default.ReactNode;
     locale?: string;
     /**
-     * Whether to `console.warn` about message ids that resolve through the
-     * deprecated bare-id fallback or fall all the way through to their
-     * `defaultMessage`. These warnings are development guidance, so they are off
-     * in production builds — pass `true` to opt back in.
+     * Whether to `console.warn` about message-resolution failures — see
+     * {@link MessageIssueCode} for the kinds. These warnings are development
+     * guidance, so they are off in production builds — pass `true` to opt back
+     * in. Ignored when `onMessageIssue` is supplied.
      *
      * @default process.env.NODE_ENV !== "production"
      */
     shouldLogMissingMessages?: boolean;
+    /**
+     * Called for every message-resolution failure, with enough detail to tell an
+     * unresolved id from a malformed message and route either into your own
+     * diagnostics.
+     *
+     * Supplying a handler takes ownership of these failures: Baseline UI reports
+     * to it instead of writing to the console, so `shouldLogMissingMessages` no
+     * longer applies. Unlike the console warnings, the handler is also called in
+     * production builds.
+     *
+     * Issues are deduplicated: after mount, each distinct failure is reported
+     * once per locale rather than once per render, and changing the locale starts
+     * a fresh set.
+     *
+     * Called **during render** — except `locale-alias-collision`, which is
+     * reported from an effect — so it must not set state synchronously. Collect
+     * into a ref, or defer with `queueMicrotask`, if a failure needs to reach the
+     * UI. A handler that throws is caught and its own error logged, so a broken
+     * handler cannot take the tree down.
+     *
+     * @example
+     *   ```tsx
+     *   <I18nProvider
+     *     messages={messages}
+     *     onMessageIssue={(issue) => {
+     *       if (issue.code === "missing-message") return;
+     *       telemetry.report(issue.code, { id: issue.id, locale: issue.locale });
+     *     }}
+     *   >
+     *     {children}
+     *   </I18nProvider>
+     *   ```;
+     */
+    onMessageIssue?: (issue: MessageIssue) => void;
 }
 
 declare const I18nProvider: React__default.FC<I18nProviderProps>;
@@ -8802,10 +8918,27 @@ interface MessageFormatProps {
      * (e.g., 'div')
      */
     elementType?: React__default.ElementType | "div" | "span";
-    /** The id of the message to format. */
+    /**
+     * The id of the message to format. Spread a `defineMessages` descriptor to
+     * pass this and `defaultMessage` together rather than as separate props.
+     */
     id: string;
-    /** The default message to use if the message id is not found. */
+    /**
+     * The message to render when no supplied catalog answers for `id`. Without
+     * it an unanswered `id` renders as itself, so pass one for any message the
+     * active catalog might not cover.
+     *
+     * Write it as a literal — the only form the extraction pipeline can read.
+     * Distinct templates are compiled once and cached, so one built per render —
+     * per file name, per row — churns that cache and recompiles the templates it
+     * displaces.
+     */
     defaultMessage?: string;
+    /**
+     * Values for the message's ICU placeholders, e.g. `{ arg0: 2, arg1: 10 }` for
+     * `"Page {arg0} of {arg1}"`.
+     */
+    values?: Record<string, any>;
 }
 
 declare const MessageFormat: React__default.FC<MessageFormatProps>;
@@ -9415,7 +9548,18 @@ declare class EditorCore {
     private doc;
     /** The last serialized HTML known to us (including setValue calls). */
     private lastKnownHtml;
+    /**
+     * Raw string last applied by {@link setValue}; `lastKnownHtml` holds only the
+     * canonical form, which a non-canonical `value` never matches. Cleared on the
+     * editor's own edits, so re-sending an unchanged `value` still reverts it.
+     */
+    private lastAppliedValue;
     private cachedRange;
+    /**
+     * A doc replacement landed while the editor was unfocused, so `cachedRange`
+     * was never written to the DOM. Replayed by the focus handler.
+     */
+    private needsSelectionRestore;
     private composing;
     private pending;
     /**
@@ -9458,6 +9602,7 @@ declare class EditorCore {
     private readonly handleInputBound;
     private readonly handlePasteBound;
     private readonly handlePointerDownBound;
+    private readonly handleFocusBound;
     private readonly handleCompositionStartBound;
     private readonly handleCompositionEndBound;
     private readonly handleSelectionChangeBound;
@@ -9494,6 +9639,7 @@ declare class EditorCore {
     canUndo(): boolean;
     canRedo(): boolean;
     focus(): void;
+    private hasFocus;
     setCaretPosition(absoluteOffset: number): void;
     /**
      * Restores a model selection: focuses the editor and writes the range to
@@ -10423,7 +10569,7 @@ interface ColorSwatchPickerProps extends StylingProps, Pick<RadioGroupProps, "op
 
 declare const ColorSwatchPicker: React__default.ForwardRefExoticComponent<ColorSwatchPickerProps & React__default.RefAttributes<HTMLDivElement>>;
 
-declare const TimeField: React__default.ForwardRefExoticComponent<StylingProps & Omit<Omit<TimeFieldStateOptions<TimeValue>, "locale"> & AriaTimeFieldProps<TimeValue>, "validationState" | "isRequired" | "validate" | "isInvalid"> & Pick<SharedInputProps, "label" | "variant" | "validationState" | "labelPosition"> & InputMessage & React__default.RefAttributes<HTMLDivElement>>;
+declare const TimeField: React__default.ForwardRefExoticComponent<StylingProps & Omit<Omit<TimeFieldStateOptions<TimeValue>, "locale"> & AriaTimeFieldProps<TimeValue>, "isRequired" | "validate" | "validationState" | "isInvalid"> & Pick<SharedInputProps, "label" | "variant" | "validationState" | "labelPosition"> & InputMessage & React__default.RefAttributes<HTMLDivElement>>;
 
 type TimeFieldProps = StylingProps & Omit<Omit<TimeFieldStateOptions, "locale"> & AriaTimeFieldProps<TimeValue>, "validationState" | "isInvalid" | "isRequired" | "validate"> & Pick<SharedInputProps, "variant" | "labelPosition" | "validationState" | "label"> & InputMessage;
 
@@ -10702,7 +10848,7 @@ type DateFieldProps = StylingProps & Omit<Omit<DateFieldStateOptions, "locale">
     openCalendarLabel?: string;
 };
 
-declare const DateField: React__default.ForwardRefExoticComponent<StylingProps & Omit<Omit<DateFieldStateOptions<DateValue>, "locale"> & AriaDateFieldProps<DateValue>, "validationState" | "isRequired" | "validate" | "isInvalid" | "createCalendar"> & Pick<SharedInputProps, "label" | "variant" | "validationState" | "labelPosition"> & InputMessage & {
+declare const DateField: React__default.ForwardRefExoticComponent<StylingProps & Omit<Omit<DateFieldStateOptions<DateValue>, "locale"> & AriaDateFieldProps<DateValue>, "isRequired" | "validate" | "validationState" | "isInvalid" | "createCalendar"> & Pick<SharedInputProps, "label" | "variant" | "validationState" | "labelPosition"> & InputMessage & {
     pickerType?: DateFieldPickerType;
     openCalendarLabel?: string;
 } & React__default.RefAttributes<HTMLDivElement>>;
@@ -11504,6 +11650,135 @@ declare const useUndoRedo: <T>(initialState: T | undefined, { isDisabled, onActi
  */
 declare function useIsFirstRender(): boolean;
 
+/**
+ * Every message id Baseline UI can ask an `I18nProvider` to resolve.
+ *
+ * Use it to derive translation coverage instead of maintaining a hand-written
+ * copy that goes stale on each upgrade:
+ *
+ * @example
+ *   ```ts
+ *   import { messageIds } from "@baseline-ui/core";
+ *
+ *   const uncovered = messageIds.filter((id) => !(id in ourCatalog.en));
+ *   ```;
+ */
+declare const messageIds: readonly ["bui.alertDialog.close", "bui.audioPlayer.audioTimeline", "bui.audioPlayer.pause", "bui.audioPlayer.play", "bui.buttonSelect.more", "bui.buttonSelect.moreWithLabel", "bui.calendar.nextMonth", "bui.calendar.nextYear", "bui.calendar.previousMonth", "bui.calendar.previousYear", "bui.calendar.selectMonth", "bui.calendar.selectYear", "bui.colorInput.add", "bui.colorInput.addColor", "bui.colorInput.cancel", "bui.colorInput.colorFormat", "bui.colorInput.colorPresets", "bui.colorInput.customColors", "bui.colorInput.indeterminate", "bui.colorInput.newColor", "bui.colorInput.noColor", "bui.colorInput.removeColor", "bui.colorInput.transparent", "bui.colorSwatch.none", "bui.dateField.openCalendar", "bui.drawer.close", "bui.editor.action", "bui.editor.addLink", "bui.editor.backgroundColor", "bui.editor.bold", "bui.editor.cancel", "bui.editor.close", "bui.editor.copy", "bui.editor.cut", "bui.editor.editLink", "bui.editor.fontColor", "bui.editor.help", "bui.editor.italic", "bui.editor.linkAnnotation", "bui.editor.mention", "bui.editor.openHelpDialog", "bui.editor.paste", "bui.editor.redo", "bui.editor.removeLink", "bui.editor.save", "bui.editor.selectAll", "bui.editor.shortcut", "bui.editor.submit", "bui.editor.toolbarFocus", "bui.editor.underline", "bui.editor.undo", "bui.fileList.loading", "bui.fileList.removeHint", "bui.freehandCanvas.redo", "bui.freehandCanvas.undo", "bui.imageDropZone.selectImage", "bui.imageGallery.cancel", "bui.imageGallery.delete", "bui.imageGallery.loading", "bui.inlineAlert.close", "bui.pagination.goToPage", "bui.pagination.nextPage", "bui.pagination.pageXofY", "bui.pagination.prevPage", "bui.select.clear", "bui.select.more", "bui.select.search", "bui.select.selectAll", "bui.stepper.completed", "bui.stepper.label", "bui.stepper.step", "bui.table.loading", "bui.toolbar.more", "bui.treeView.collapse", "bui.treeView.expand", "bui.treeView.rename", "bui.useMedia.paused", "bui.useMedia.playing"];
+type MessageId = (typeof messageIds)[number];
+/**
+ * Maps each deprecated bare id — the last dot-segment of a namespaced id — to
+ * every id that claims it, so a catalog keyed the old way can be re-keyed
+ * mechanically. Each key is kept alongside the ids it maps to: a bare key may
+ * also be one your own app looks up, and the namespaced entry is what Baseline
+ * UI resolves against either way.
+ *
+ * @example
+ *   ```ts
+ *   import { legacyMessageIdMap } from "@baseline-ui/core";
+ *
+ *   const migrated = Object.fromEntries(
+ *     Object.entries(oldCatalog).flatMap(([key, value]) => [
+ *       [key, value],
+ *       ...(legacyMessageIdMap[key] ?? []).map((id) => [id, value]),
+ *     ]),
+ *   );
+ *   ```;
+ *
+ * @remarks An entry with more than one id is ambiguous: overriding that bare id
+ *   overrides every component listed, which forecloses any language where the
+ *   word inflects differently per context. Those need a per-id translation.
+ *   The bare-id fallback is deprecated and will be removed in a future major.
+ */
+declare const legacyMessageIdMap: Readonly<Partial<Record<string, readonly MessageId[]>>>;
+
+/**
+ * Builds a message formatter outside of a React render.
+ *
+ * The returned function is the same engine `useI18n` runs on, so for a given
+ * locale, catalog and set of values it produces exactly the string a component
+ * would render — including the `defaultMessage` fallback for ids a catalog
+ * omits, and the deprecated bare-id fallback for older catalogs.
+ *
+ * Use it wherever no component is rendering: an alert raised from an async
+ * task, a label composed in a plain utility module, a string handed to a
+ * non-React API. Inside a component, use `useI18n` instead so the message
+ * follows the locale of the surrounding `I18nProvider`.
+ *
+ * @example
+ *   ```ts
+ *   import { createMessageFormatter } from "@baseline-ui/core";
+ *   import de from "@baseline-ui/core/intl/de.json";
+ *
+ *   const formatMessage = createMessageFormatter({
+ *     locale: "de-DE",
+ *     messages: { de },
+ *   });
+ *
+ *   window.alert(
+ *     formatMessage(
+ *       {
+ *         id: "bui.fileList.removeHint",
+ *         defaultMessage: "{fileName}, press Delete or Backspace to remove",
+ *       },
+ *       { fileName: "photo.png" },
+ *     ),
+ *   );
+ *   ```;
+ *
+ * @template T - The shape of one locale's messages, when you want the returned
+ *   function to accept only that catalog's ids. Pass it explicitly — it is not
+ *   inferred from `messages`, since a partial catalog would then reject the
+ *   `bui.*` ids it does not itself translate. Defaults to any string id.
+ * @param options.locale - The BCP 47 locale to format in. Unlike `useI18n`
+ *   there is no surrounding provider to read it from, so it is required.
+ * @param options.messages - Locale-keyed catalogs, in the same shape
+ *   `I18nProvider` takes, plus keys that came straight from an `import.meta.glob`
+ *   (`./intl/de.json`) which are reduced to their locale. Omit them and every
+ *   message formatted from a descriptor renders its English `defaultMessage`,
+ *   while a bare id renders as itself. There is no provider here to merge with
+ *   — these catalogs are the only ones consulted.
+ * @param options.shouldLogMissingMessages - Whether to report missing
+ *   translations to the console. Defaults to off in production builds, on
+ *   everywhere else, matching `I18nProvider`. Ignored when `onMessageIssue` is
+ *   supplied.
+ * @param options.onMessageIssue - Called for every message-resolution failure
+ *   instead of writing to the console, exactly as the `I18nProvider` prop of the
+ *   same name.
+ * @returns A `formatMessage` function bound to that locale and those messages.
+ * @throws If `locale` is not a valid BCP 47 language tag.
+ */
+declare function createMessageFormatter<T extends Record<string, string> = Record<string, string>>({ locale, messages, shouldLogMissingMessages, onMessageIssue, }: CreateMessageFormatterOptions): MessageFormatter<T>;
+/**
+ * A hook that provides internationalization functionality, reading its messages
+ * entirely from the surrounding `I18nProvider`. It returns a function to format
+ * messages and the current locale.
+ *
+ * With no catalog of your own, `formatMessage` takes a built-in `MessageId` or
+ * a `MessageDescriptor`, so a misspelled id is a compile error. A bare
+ * `MessageId` still needs a catalog to answer for it — pass the descriptor to
+ * render Baseline UI's English without one. To put your application's own
+ * string ids through the hook, pass their catalog or name it —
+ * `useI18n<MyMessages>()`.
+ *
+ * To format a message outside of a render, use `createMessageFormatter`.
+ *
+ * @example
+ *   ```tsx
+ *   import { useI18n } from "@baseline-ui/core";
+ *
+ *   const MyComponent = () => {
+ *    const { formatMessage } = useI18n();
+ *
+ *    return (
+ *      <p>{formatMessage({ id: "bui.editor.bold", defaultMessage: "Bold" })}</p>
+ *    );
+ *   };
+ *   ```;
+ *
+ * @returns An object containing a function to format messages and the current
+ *   locale.
+ */
+declare function useI18n(messages?: undefined): I18nResult<Record<MessageId, string>>;
 /**
  * A hook that provides internationalization functionality. It returns a
  * function to format messages and the current locale.
@@ -11513,6 +11788,8 @@ declare function useIsFirstRender(): boolean;
  * win on key conflicts, while unmatched local keys are preserved. When only one
  * source is present the behavior is unchanged (backwards compatible).
  *
+ * To format a message outside of a render, use `createMessageFormatter`.
+ *
  * @example
  *   ```tsx
  *   import { useI18n } from "@baseline-ui/core";
@@ -11534,16 +11811,56 @@ declare function useIsFirstRender(): boolean;
  *   ```;
  *
  * @template T - A type that represents the shape of the translation messages.
+ *   Naming it — `useI18n<MyMessages>()` — is also how an application declares
+ *   its own ids when it registers them through `I18nProvider` and passes no
+ *   catalog here.
  * @param messages - An optional object containing translation messages for
  *   different locales. When provider messages (from `I18nProvider`) are also
  *   present, local and provider messages are merged per locale — provider
  *   values take precedence on key conflicts. If omitted, the hook reads
- *   entirely from the provider.
+ *   entirely from the provider, and `formatMessage` still takes the ids of
+ *   `T`. Omitting it *without* naming `T` selects the overload above, whose
+ *   ids are the built-in `MessageId` union.
  * @returns {I18nResult<T>} An object containing a function to format messages
  *   and the current locale.
  */
 declare function useI18n<T extends Record<string, string>>(messages?: Record<string, T>): I18nResult<T>;
 type MessageFormatter<T> = (id: keyof T | MessageDescriptor, values?: Record<string, any>) => string;
+/** The `I18nProvider` props that apply outside a render, as a plain object. */
+interface CreateMessageFormatterOptions {
+    /**
+     * The BCP 47 locale to format in. Required — there is no surrounding
+     * `I18nProvider` to inherit it from.
+     */
+    locale: string;
+    /**
+     * Locale-keyed catalogs, in the shape `I18nProvider` takes. These are the only
+     * catalogs consulted; nothing is merged in from a provider. Omit them and
+     * every message formatted from a descriptor renders its English
+     * `defaultMessage`, while a bare id renders as itself.
+     */
+    messages?: LocalizedStrings;
+    /**
+     * Whether to report missing translations to the console. Defaults to off in
+     * production builds and on everywhere else, matching `I18nProvider`. Ignored
+     * when `onMessageIssue` is supplied.
+     */
+    shouldLogMissingMessages?: boolean;
+    /**
+     * Called for every message-resolution failure, the standalone counterpart of
+     * the `I18nProvider` prop — see `MessageIssueCode` for the kinds.
+     *
+     * The ownership rule is the same: supplying a handler routes failures to it
+     * instead of the console, in production builds too, and
+     * `shouldLogMissingMessages` no longer applies. A handler that throws is
+     * caught and its own error logged.
+     *
+     * Deduplication is per formatter rather than per provider: each distinct
+     * failure reaches the handler once for the life of this `formatMessage`.
+     * Build a second formatter to hear them again.
+     */
+    onMessageIssue?: (issue: MessageIssue) => void;
+}
 interface I18nResult<T extends LocalizedStrings[keyof LocalizedStrings]> {
     formatMessage: MessageFormatter<T>;
     locale: Locale;
@@ -11558,13 +11875,13 @@ interface MessageDescriptor {
     description?: string;
 }
 /**
- * Defines a set of messages for use with the `useI18n` hook.
+ * Marks a set of message descriptors for `eslint-plugin-formatjs` and the
+ * extraction pipeline that produces `messages.json`. A pure identity function
+ * at runtime — call it for the tooling, not for an effect it has on
+ * formatting.
  *
  * @param messages An object containing message descriptors.
- * @returns An object containing the message descriptors with their keys as
- *   property names.
- * @remarks Registers each `defaultMessage` so the no-catalog path can format it
- *   as ICU rather than rendering the template verbatim.
+ * @returns The same object, unchanged.
  */
 declare const defineMessages: <T extends Record<string, MessageDescriptor>>(messages: T) => T;
 
@@ -11709,47 +12026,6 @@ declare function usePreventFocus({ ref, isDisabled, }: {
     isDisabled?: boolean;
 }): void;
 
-/**
- * Every message id Baseline UI can ask an `I18nProvider` to resolve.
- *
- * Use it to derive translation coverage instead of maintaining a hand-written
- * copy that goes stale on each upgrade:
- *
- * @example
- *   ```ts
- *   import { messageIds } from "@baseline-ui/core";
- *
- *   const uncovered = messageIds.filter((id) => !(id in ourCatalog.en));
- *   ```;
- */
-declare const messageIds: readonly ["bui.alertDialog.close", "bui.audioPlayer.audioTimeline", "bui.audioPlayer.pause", "bui.audioPlayer.play", "bui.buttonSelect.more", "bui.buttonSelect.moreWithLabel", "bui.calendar.nextMonth", "bui.calendar.nextYear", "bui.calendar.previousMonth", "bui.calendar.previousYear", "bui.calendar.selectMonth", "bui.calendar.selectYear", "bui.colorInput.add", "bui.colorInput.addColor", "bui.colorInput.cancel", "bui.colorInput.colorFormat", "bui.colorInput.colorPresets", "bui.colorInput.customColors", "bui.colorInput.indeterminate", "bui.colorInput.newColor", "bui.colorInput.noColor", "bui.colorInput.removeColor", "bui.colorInput.transparent", "bui.colorSwatch.none", "bui.dateField.openCalendar", "bui.drawer.close", "bui.editor.action", "bui.editor.addLink", "bui.editor.backgroundColor", "bui.editor.bold", "bui.editor.cancel", "bui.editor.close", "bui.editor.copy", "bui.editor.cut", "bui.editor.editLink", "bui.editor.fontColor", "bui.editor.help", "bui.editor.italic", "bui.editor.linkAnnotation", "bui.editor.mention", "bui.editor.openHelpDialog", "bui.editor.paste", "bui.editor.redo", "bui.editor.removeLink", "bui.editor.save", "bui.editor.selectAll", "bui.editor.shortcut", "bui.editor.submit", "bui.editor.toolbarFocus", "bui.editor.underline", "bui.editor.undo", "bui.fileList.loading", "bui.fileList.removeHint", "bui.freehandCanvas.redo", "bui.freehandCanvas.undo", "bui.imageDropZone.selectImage", "bui.imageGallery.cancel", "bui.imageGallery.delete", "bui.imageGallery.loading", "bui.inlineAlert.close", "bui.pagination.goToPage", "bui.pagination.nextPage", "bui.pagination.pageXofY", "bui.pagination.prevPage", "bui.select.clear", "bui.select.more", "bui.select.search", "bui.select.selectAll", "bui.stepper.completed", "bui.stepper.label", "bui.stepper.step", "bui.table.loading", "bui.toolbar.more", "bui.treeView.collapse", "bui.treeView.expand", "bui.treeView.rename", "bui.useMedia.paused", "bui.useMedia.playing"];
-type MessageId = (typeof messageIds)[number];
-/**
- * Maps each deprecated bare id — the last dot-segment of a namespaced id — to
- * every id that claims it, so a catalog keyed the old way can be re-keyed
- * mechanically. Each key is kept alongside the ids it maps to: a bare key may
- * also be one your own app looks up, and the namespaced entry is what Baseline
- * UI resolves against either way.
- *
- * @example
- *   ```ts
- *   import { legacyMessageIdMap } from "@baseline-ui/core";
- *
- *   const migrated = Object.fromEntries(
- *     Object.entries(oldCatalog).flatMap(([key, value]) => [
- *       [key, value],
- *       ...(legacyMessageIdMap[key] ?? []).map((id) => [id, value]),
- *     ]),
- *   );
- *   ```;
- *
- * @remarks An entry with more than one id is ambiguous: overriding that bare id
- *   overrides every component listed, which forecloses any language where the
- *   word inflects differently per context. Those need a per-id translation.
- *   The bare-id fallback is deprecated and will be removed in a future major.
- */
-declare const legacyMessageIdMap: Readonly<Partial<Record<string, readonly MessageId[]>>>;
-
 type Assertiveness = 'assertive' | 'polite';
 type Message = string | {
     'aria-labelledby': string;
@@ -11816,5 +12092,5 @@ declare namespace reactStately {
   export type { reactStately_Color as Color, reactStately_ListData as ListData, reactStately_TreeData as TreeData };
 }
 
-export { Accordion, AccordionItem, ActionButton, ActionGroup, ActionGroupItem, ActionIconButton, Actionable, AlertDialog, AudioPlayer, Autocomplete, Avatar, Box, ButtonSelect, Calendar, Cell, Checkbox, Code, ColorInput, ColorSwatch, ColorSwatchPicker, Column, ComboBox, DateField, DateFormat, DefaultListOption, DeviceProvider, DeviceProviderContext, Dialog, DialogTitle, Disclosure, DomNodeRenderer, Drawer, EMPTY_SELECTION_STATE, Editor, EditorCore, EditorProvider, FileInput, FileList$1 as FileList, FileUploader, FocusScope, Focusable, FrameProvider, FreehandCanvas, GlobalToastRegion, GridLayout, GridList, Group, I18nProvider, Icon, IconColorInput, IconColorInputButton, IconSelect, IconSlider, ImageDropZone, ImageGallery, InlineAlert, Kbd, Link, ListBox, ListLayout, LocaleAwareGridLayout, Markdown, Menu, MessageFormat, Modal, ModalClose, ModalContent, ModalTrigger, NumberFormat, NumberInput, Pagination, Panel, PanelGroup, PanelResizeHandle, PointPicker, PointPickerContent, PointPickerDisplay, Popover, PopoverContent, PopoverTrigger, Portal, PortalContainerProvider, Pressable, Preview, ProgressBar, ProgressSpinner, REACT_ARIA_INCOMPATIBLE_KEYS, RadioGroup, RangeCalendar, Reaction, Row, ScrollControlButton, SearchInput, Select, Separator, Size, Skeleton, Slider, StatusCard, Stepper, Switch, TabItem, Table, TableBody, TableHeader, TableLayout, Tabs, Tag, TagGroup, TaggedPagination, Text, TextInput, ThemeProvider, TimeField, ToastQueue, ToggleButton, ToggleIconButton, Toolbar, Tooltip, TreeView, UNSAFE_ListBox, reactAria as UNSAFE_aria, reactStately as UNSAFE_stately, VIRTUALIZER_LAYOUT_DEFAULT_OPTIONS, Virtualizer, VisuallyHidden, WaterfallLayout, announce, areColorsEqual, booleanOrObjectToConfig, calculateFontSizeToFitWidth, capitalize, clamp, classNames, cleanKeyFromGlobImport, clearAnnouncer, defineMessages, destroyAnnouncer, devWarnOnce, directionVar, disableAnimations, enableAnimations, filterDOMProps, filterTruthyValues, findFocusableElements, getAbsoluteBounds, getAbsolutePosition, getActiveElement, getHTMLElement, getOsSpecificKeyboardShortcutLabel, getOwnerDocument, getPlainText, getSvgPathFromStroke, getTextDimensions, handleEditorShortcut, iconMap, invariant, isFocusableElement, isInIframe, isInShadowDOM, isInputThatOpensKeyboard, isInsideOverlayContent, isRect, isUrl, legacyMessageIdMap, lightenColor, mergeProps, mergeRefs, messageIds, onDropOrPaste, parseColor, safeSpreadProps, useCollator, useDateFormatter, useDevice, useDragAndDrop, useEditable, useEditor, useEditorContext, useFilter, useFocusRing, useFocusVisible, useFrameDimensions, useI18n, useId, useImage, useInteractionModality, useIntersectionObserver, useIsFirstRender, useKeyboard, useListData, useLiveInteractionModality, useLocalStorage, useLocale, useMutationObserver, useNumberFormatter, useObjectRef, usePointProximity, usePortalContainer, usePreventFocus, useResizeObserver, useTableDragAndDrop, useTextSelection, useUndoRedo, useUserPreferences };
-export type { AccordionItemProps, AccordionProps, ActionButtonProps, ActionGroupProps, ActionIconButtonProps, ActionableProps, ActiveMarks, AlertDialogProps, AudioPlayerProps, AutocompleteProps, AvatarProps, BlockProps, BoundaryAxis, BoxProps, ButtonSelectProps, CalendarHeaderVariant, CalendarProps, CalendarSize, CellProps, CheckboxProps, CodeProps, ColorInputProps, ColorPreset, ColorSwatchPickerProps, ColorSwatchProps, ColumnProps, ComboBoxProps, CommandArgs, CommandName, DateFieldPickerType, DateFieldProps, DateFormatProps, Device, DeviceProviderProps, DialogProps, DialogTitleProps, DisclosureProps, DomNodeRendererProps, DrawerProps, EditableProps, EditorCoreOptions, EditorHandle, EditorProps, EditorProviderProps, EditorState, FileInputProps, FileListItem, FileListProps, FileUploaderProps, FocusableProps, FrameProviderProps, FreehandCanvasProps, GridListProps, GroupProps, HorizontalBoundaryBehavior, I18nProviderProps, I18nResult, IconColorInputProps, IconComponentProps$1 as IconComponentProps, IconProps, IconSelectProps, IconSliderProps, ImageDropZoneProps, ImageGalleryProps, ImperativePanelGroupHandle, ImperativePanelHandle, InlineAlertProps, IntersectionObserverOptions, KbdProps, Key, LinkProps, ListBoxProps, ListHandle$1 as ListHandle, ListOption, MarkName, MarkdownProps, MenuItem, MenuProps, MessageDescriptor, MessageFormatProps, MessageFormatter, MessageId, ModalContentProps, ModalProps, ModelPoint, ModelRange, NumberFormatProps, NumberInputProps, PaginationProps, PanelGroupProps, PanelProps, PanelResizeHandleProps, PointPickerContentProps, PointPickerDisplayProps, PointPickerProps, PopoverContentHandle, PopoverContentProps, PopoverProps, PopoverTriggerProps, PortalProps, PressEvent, PreviewProps, ProgressBarProps, ProgressSpinnerProps, RadioGroupProps, RangeCalendarProps, ReactAriaIncompatibleKey, ReactionProps, Rect, ResizeObserverOptions, RichTextEditorDoc, RichTextEditorInline, RichTextEditorLink, RichTextEditorMention, RichTextEditorMentionInput, RichTextEditorParagraph, RichTextEditorText, RowProps, SVGRProps, SafeDOMAttributes, ScrollControlButtonProps, SearchInputProps, SelectProps, SelectionState, SeparatorProps, SetValue, SkeletonProps, SliderProps, StatusCardProps, StepperItem, StepperProps, StylingProps, SwitchProps, TabItemProps, TableBodyProps, TableHeaderProps, TableProps, TabsProps, TagGroupProps, TagProps, TagVariant, TaggedPaginationProps, TextInputProps, TextProps, TextSelectionProps, ThemeProviderProps, TimeFieldProps, ToastProps, ToggleButtonProps, ToggleIconButtonProps, ToolbarProps, TooltipProps, TreeListItem, TreeViewProps, UNSAFE_ListBoxProps, UseEditableOptions, UseEditorOptions, UseTableDragAndDropOptions, VirtualizerProps };
+export { Accordion, AccordionItem, ActionButton, ActionGroup, ActionGroupItem, ActionIconButton, Actionable, AlertDialog, AudioPlayer, Autocomplete, Avatar, Box, ButtonSelect, Calendar, Cell, Checkbox, Code, ColorInput, ColorSwatch, ColorSwatchPicker, Column, ComboBox, DateField, DateFormat, DefaultListOption, DeviceProvider, DeviceProviderContext, Dialog, DialogTitle, Disclosure, DomNodeRenderer, Drawer, EMPTY_SELECTION_STATE, Editor, EditorCore, EditorProvider, FileInput, FileList$1 as FileList, FileUploader, FocusScope, Focusable, FrameProvider, FreehandCanvas, GlobalToastRegion, GridLayout, GridList, Group, I18nProvider, Icon, IconColorInput, IconColorInputButton, IconSelect, IconSlider, ImageDropZone, ImageGallery, InlineAlert, Kbd, Link, ListBox, ListLayout, LocaleAwareGridLayout, Markdown, Menu, MessageFormat, Modal, ModalClose, ModalContent, ModalTrigger, NumberFormat, NumberInput, Pagination, Panel, PanelGroup, PanelResizeHandle, PointPicker, PointPickerContent, PointPickerDisplay, Popover, PopoverContent, PopoverTrigger, Portal, PortalContainerProvider, Pressable, Preview, ProgressBar, ProgressSpinner, REACT_ARIA_INCOMPATIBLE_KEYS, RadioGroup, RangeCalendar, Reaction, Row, ScrollControlButton, SearchInput, Select, Separator, Size, Skeleton, Slider, StatusCard, Stepper, Switch, TabItem, Table, TableBody, TableHeader, TableLayout, Tabs, Tag, TagGroup, TaggedPagination, Text, TextInput, ThemeProvider, TimeField, ToastQueue, ToggleButton, ToggleIconButton, Toolbar, Tooltip, TreeView, UNSAFE_ListBox, reactAria as UNSAFE_aria, reactStately as UNSAFE_stately, VIRTUALIZER_LAYOUT_DEFAULT_OPTIONS, Virtualizer, VisuallyHidden, WaterfallLayout, announce, areColorsEqual, booleanOrObjectToConfig, calculateFontSizeToFitWidth, capitalize, clamp, classNames, cleanKeyFromGlobImport, clearAnnouncer, createMessageFormatter, defineMessages, destroyAnnouncer, devWarnOnce, directionVar, disableAnimations, enableAnimations, filterDOMProps, filterTruthyValues, findFocusableElements, getAbsoluteBounds, getAbsolutePosition, getActiveElement, getHTMLElement, getOsSpecificKeyboardShortcutLabel, getOwnerDocument, getPlainText, getSvgPathFromStroke, getTextDimensions, handleEditorShortcut, iconMap, invariant, isFocusableElement, isInIframe, isInShadowDOM, isInputThatOpensKeyboard, isInsideOverlayContent, isRect, isUrl, legacyMessageIdMap, lightenColor, mergeProps, mergeRefs, messageIds, onDropOrPaste, parseColor, safeSpreadProps, useCollator, useDateFormatter, useDevice, useDragAndDrop, useEditable, useEditor, useEditorContext, useFilter, useFocusRing, useFocusVisible, useFrameDimensions, useI18n, useId, useImage, useInteractionModality, useIntersectionObserver, useIsFirstRender, useKeyboard, useListData, useLiveInteractionModality, useLocalStorage, useLocale, useMutationObserver, useNumberFormatter, useObjectRef, usePointProximity, usePortalContainer, usePreventFocus, useResizeObserver, useTableDragAndDrop, useTextSelection, useUndoRedo, useUserPreferences };
+export type { AccordionItemProps, AccordionProps, ActionButtonProps, ActionGroupProps, ActionIconButtonProps, ActionableProps, ActiveMarks, AlertDialogProps, AudioPlayerProps, AutocompleteProps, AvatarProps, BlockProps, BoundaryAxis, BoxProps, ButtonSelectProps, CalendarHeaderVariant, CalendarProps, CalendarSize, CellProps, CheckboxProps, CodeProps, ColorInputProps, ColorPreset, ColorSwatchPickerProps, ColorSwatchProps, ColumnProps, ComboBoxProps, CommandArgs, CommandName, CreateMessageFormatterOptions, DateFieldPickerType, DateFieldProps, DateFormatProps, Device, DeviceProviderProps, DialogProps, DialogTitleProps, DisclosureProps, DomNodeRendererProps, DrawerProps, EditableProps, EditorCoreOptions, EditorHandle, EditorProps, EditorProviderProps, EditorState, FileInputProps, FileListItem, FileListProps, FileUploaderProps, FocusableProps, FrameProviderProps, FreehandCanvasProps, GridListProps, GroupProps, HorizontalBoundaryBehavior, I18nProviderProps, I18nResult, IconColorInputProps, IconComponentProps$1 as IconComponentProps, IconProps, IconSelectProps, IconSliderProps, ImageDropZoneProps, ImageGalleryProps, ImperativePanelGroupHandle, ImperativePanelHandle, InlineAlertProps, IntersectionObserverOptions, KbdProps, Key, LinkProps, ListBoxProps, ListHandle$1 as ListHandle, ListOption, MarkName, MarkdownProps, MenuItem, MenuProps, MessageDescriptor, MessageFormatProps, MessageFormatter, MessageId, MessageIssue, MessageIssueCode, ModalContentProps, ModalProps, ModelPoint, ModelRange, NumberFormatProps, NumberInputProps, PaginationProps, PanelGroupProps, PanelProps, PanelResizeHandleProps, PointPickerContentProps, PointPickerDisplayProps, PointPickerProps, PopoverContentHandle, PopoverContentProps, PopoverProps, PopoverTriggerProps, PortalProps, PressEvent, PreviewProps, ProgressBarProps, ProgressSpinnerProps, RadioGroupProps, RangeCalendarProps, ReactAriaIncompatibleKey, ReactionProps, Rect, ResizeObserverOptions, RichTextEditorDoc, RichTextEditorInline, RichTextEditorLink, RichTextEditorMention, RichTextEditorMentionInput, RichTextEditorParagraph, RichTextEditorText, RowProps, SVGRProps, SafeDOMAttributes, ScrollControlButtonProps, SearchInputProps, SelectProps, SelectionState, SeparatorProps, SetValue, SkeletonProps, SliderProps, StatusCardProps, StepperItem, StepperProps, StylingProps, SwitchProps, TabItemProps, TableBodyProps, TableHeaderProps, TableProps, TabsProps, TagGroupProps, TagProps, TagVariant, TaggedPaginationProps, TextInputProps, TextProps, TextSelectionProps, ThemeProviderProps, TimeFieldProps, ToastProps, ToggleButtonProps, ToggleIconButtonProps, ToolbarProps, TooltipProps, TreeListItem, TreeViewProps, UNSAFE_ListBoxProps, UseEditableOptions, UseEditorOptions, UseTableDragAndDropOptions, VirtualizerProps };