@object-ui/i18n 17.3.0 → 17.6.0

package/dist/useObjectLabel.js

@@ -17,8 +17,8 @@
  * @module useObjectLabel
  */
 import { useMemo } from 'react';
-import { useObjectTranslation } from './provider';
-import { I18N_PROBE_FLAG } from './i18n';
+import { useObjectTranslation } from './provider.js';
+import { I18N_PROBE_FLAG } from './i18n.js';
 /**
  * Built-in Object UI top-level locale keys — not app namespaces.
  * Update this set when new top-level platform translation keys are added
@@ -30,6 +30,41 @@ const BUILTIN_KEYS = new Set([
     'list', 'kanban', 'chart', 'dashboard', 'configPanel',
     'appDesigner', 'console', 'errors', 'detail',
 ]);
+/**
+ * Whether `i18n` is a real i18next instance rather than react-i18next's
+ * no-instance placeholder.
+ *
+ * With nothing to bind to, `useTranslation` warns `NO_I18NEXT_INSTANCE` and
+ * builds its return value out of a fresh `{}` on every render (`const
+ * finalI18n = i18n || {}`, which then feeds that hook's own `useMemo` deps), so
+ * the `i18n` we receive has a new identity each render even though nothing
+ * about it can have changed.
+ *
+ * `getResourceBundle` is the probe because it is the only instance member the
+ * resolvers below ever touch — via `getAppNamespaces`, the single gate every
+ * `t()` call in this module sits behind.
+ */
+function hasUsableI18nInstance(i18n) {
+    return Boolean(i18n) && typeof i18n?.getResourceBundle === 'function';
+}
+/**
+ * Stand-ins pinned into the memo dependency list while no i18next instance is
+ * bound, so the memo in {@link useObjectLabel} actually holds on the
+ * no-provider path (objectui#5564). Module-level, so they carry one identity
+ * for the lifetime of the process instead of one per render.
+ *
+ * Substituting them is unobservable rather than merely convenient: every `t()`
+ * call in this module sits inside a `for (… of getAppNamespaces())` loop, and
+ * `getAppNamespaces()` returns `[]` under exactly {@link hasUsableI18nInstance}
+ * — so for as long as the substitution is in effect, the closures cannot read
+ * either value at all. `NO_INSTANCE_T` still mirrors react-i18next's own
+ * not-ready `t` (honour a string `defaultValue`, otherwise echo the key) so
+ * that if that reachability argument ever stops holding, behaviour does not
+ * change silently.
+ */
+const NO_INSTANCE_T = ((key, options) => typeof options?.defaultValue === 'string' ? options.defaultValue : key);
+/** @see NO_INSTANCE_T */
+const NO_INSTANCE_I18N = Object.freeze({});
 /**
  * Hook for convention-based auto-resolution of object and field labels.
  *
@@ -46,7 +81,21 @@ const BUILTIN_KEYS = new Set([
  * ```
  */
 export function useObjectLabel() {
-    const { t, i18n } = useObjectTranslation();
+    const { t: boundT, i18n: boundI18n } = useObjectTranslation();
+    // Pin both memo dependencies to module constants while there is no i18next
+    // instance to bind to. Without this the memo below never held on exactly the
+    // no-provider path `useSafeFieldLabel` advertises: react-i18next rebuilds its
+    // return value from a fresh `{}` each render, so `i18n` arrived with a new
+    // identity every time and re-keyed every consumer memo this hook feeds
+    // (objectui#5564 measured 4 distinct identities across 4 renders). See
+    // `hasUsableI18nInstance` for why the substitution cannot be observed.
+    //
+    // When an instance does appear these become the live values again, so a
+    // provider mounting after first render recomputes the object exactly once and
+    // resolves real translations from then on.
+    const bound = hasUsableI18nInstance(boundI18n);
+    const t = bound ? boundT : NO_INSTANCE_T;
+    const i18n = bound ? boundI18n : NO_INSTANCE_I18N;
     // Memoize the entire returned object — all closures below reference `t`/`i18n`
     // and stay valid until the language changes. Returning a fresh object on every
     // render was busting downstream `useMemo`/`useCallback` deps in heavy consumers
@@ -64,7 +113,7 @@ export function useObjectLabel() {
          * (objectui#3372).
          */
         const getAppNamespaces = () => {
-            if (!i18n || typeof i18n.getResourceBundle !== 'function')
+            if (!hasUsableI18nInstance(i18n))
                 return [];
             const lang = i18n.language || 'en';
             const bundle = i18n.getResourceBundle(lang, 'translation');
@@ -188,19 +237,36 @@ export function useObjectLabel() {
         /**
          * Build suffix candidates for a list-view scoped key.
          *
-         * The runtime uses qualified view ids (`<objectName>.<viewName>`) in URLs
-         * and metadata records, while translation bundles are keyed by the authored
-         * view name under `_views`. Resolve the unqualified name first so every
-         * surface can pass its canonical id without leaking the metadata fallback.
+         * The runtime uses qualified view ids (`<objectName>.<viewName>`) in URLs and
+         * metadata records, while translation bundles are keyed by the **bare** view
+         * name under `_views` — the runtime view identity's own name, stripped of the
+         * object prefix. That single spelling is canonical per the objectstack#5164
+         * ruling A (2026-08-06): the i18n extractor asks the view composer for the key
+         * (objectstack#6124) and `packages/lint` enforces exactly that spelling
+         * (objectstack#6038), so this resolver accepts exactly what those produce.
+         *
+         * Deliberately NOT a second candidate: the prefixed full name
+         * (`_views.<objectName>.<viewName>`). Accepting it made this client more
+         * lenient than the server-side resolver, which only ever reads the one key
+         * (objectstack#5165) — a bundle authored against the prefixed spelling showed
+         * translated labels in the Console while every consumer that does not run a
+         * second resolution pass (REST boundary, mobile, plain HTTP, SDUI) still got
+         * English. A prefixed key now simply misses, and the label falls back to the
+         * metadata default on every surface alike, so the authoring mistake is visible
+         * instead of half-hidden. It is caught at authoring time by `os lint`'s
+         * `translation-target-unknown`, not papered over here.
+         *
+         * The object-name candidates (`objects.<ns__obj>` then `objects.<obj>`) are a
+         * separate axis and stay: they let bundles written against short object names
+         * resolve when the runtime presents fully-qualified ones.
          */
         const viewSuffixes = (objectName, viewName, tail) => {
             const objectNames = [objectName, stripNamespace(objectName)];
             const matchedPrefix = objectNames
                 .map((name) => `${name}.`)
                 .find((prefix) => viewName.startsWith(prefix));
-            const shortViewName = matchedPrefix ? viewName.slice(matchedPrefix.length) : viewName;
-            const viewNames = shortViewName === viewName ? [viewName] : [shortViewName, viewName];
-            return viewNames.flatMap((name) => objectSuffixes(objectName, `_views.${name}.${tail}`));
+            const bareViewName = matchedPrefix ? viewName.slice(matchedPrefix.length) : viewName;
+            return objectSuffixes(objectName, `_views.${bareViewName}.${tail}`);
         };
         return {
             /**
@@ -250,13 +316,27 @@ export function useObjectLabel() {
                 return resolved || undefined;
             },
             /**
-             * Resolve translated label for a navigation group within an app.
-             * Convention: `{ns}.apps.{appName}.navigation.{groupId}.label`.
+             * Read `{ns}.apps.{appName}.navigation.{groupId}.label` out of the loaded
+             * CLIENT translation resources, falling back to `fallback`.
              *
-             * Mirrors `objectLabel`/`dashboardLabel` so app metadata can keep
-             * English fallbacks while translation packs supply localised
-             * sidebar group labels (e.g. "Sales" → "销售") without explicit
-             * I18nLabel `{ key, defaultValue }` annotations.
+             * ⚠️ This does NOT localize the sidebar, and adding a translation pack
+             * keyed this way will not change a single rendered nav label.
+             * **App-navigation localization is owned solely by the server-side
+             * `/meta` boundary**: `translateApp` in `@objectstack/spec`
+             * (`src/system/i18n-resolver.ts`) rewrites every navigation node's
+             * `label` by id, and `@objectstack/rest` applies it before the metadata
+             * reaches this client — so nav labels arrive already localized. One
+             * owner, not two. To translate a sidebar group, translate it there.
+             *
+             * History (objectui#5197): until then this docstring promised
+             * `"Sales" → "销售"` for sidebar groups, and `NavigationRenderer`
+             * accepted `resolveGroupLabel`/`resolveItemLabel` to wire it up. Those
+             * props could never fire — the renderer's `isCustomized` guard compared a
+             * node's authored label against its own `id` (`Workspace` vs
+             * `grp_workspace`), which never match, so the guard was true for every
+             * real entry. The props are gone; the promise was false, not merely
+             * unused. This helper is kept as a plain key reader for a consumer that
+             * renders navigation itself — it has no first-party caller.
              */
             navGroupLabel: (appName, groupId, fallback) => resolve(`apps.${appName}.navigation.${groupId}.label`, fallback),
             /**
@@ -297,6 +377,33 @@ export function useObjectLabel() {
                 const resolved = resolve(dashboardSuffixes(dashboardName, `widgets.${widgetId}.description`), fb);
                 return resolved || undefined;
             },
+            /**
+             * Resolve a translated metric-widget SUB-CAPTION within a dashboard.
+             * Convention: `{ns}.dashboards.{dashboardName}.widgets.{widgetId}.subCaption`.
+             * Returns undefined when neither metadata nor translation provides one.
+             *
+             * Deliberately its OWN key, not a second reader of `widgets.{id}.description`.
+             * The KPI card renders two authored strings from two different fields — the
+             * shared card header's `widget.description`, and the sub-caption under the
+             * value, which is authored as `widget.options.description` — and the
+             * objectstack#5428 item-4 ruling (2026-08-06) settled that they get two
+             * keys, not one: 「两个作者字段两个 key」. Collapsing them would make one
+             * translation entry silently retarget the other field on any widget type
+             * that renders both at once (`kpi`, `gauge`, `bullet` — every metric-family
+             * type except the self-contained `metric`).
+             *
+             * `subCaption` is the member objectstack#8056 added to the widget
+             * translation node for exactly this, shipped in `@objectstack/spec@17.0.0`.
+             * The server-side resolver reads the SAME key and overlays it onto
+             * `options.description` (`translateDashboard`), so a document served
+             * through `/meta` and a document translated here land on the same string —
+             * this is the client half of one convention, not a second dialect.
+             */
+            widgetSubCaption: (dashboardName, widgetId, fallback) => {
+                const fb = fallback ?? '';
+                const resolved = resolve(dashboardSuffixes(dashboardName, `widgets.${widgetId}.subCaption`), fb);
+                return resolved || undefined;
+            },
             /**
              * Resolve translated page label, falling back to pageDef.label.
              * Convention: `{ns}.pages.{pageName}.label`.
@@ -309,7 +416,10 @@ export function useObjectLabel() {
             reportLabel: (reportDef) => resolve(reportSuffixes(reportDef.name, 'label'), reportDef.label ?? reportDef.name),
             /**
              * Resolve translated list-view label.
-             * Convention (per @objectstack/spec): `{ns}.objects.{objectName}._views.{viewName}.label`.
+             * Convention (per @objectstack/spec): `{ns}.objects.{objectName}._views.{viewName}.label`,
+             * where `{viewName}` is the **bare** view name — pass either the bare name or
+             * the qualified runtime id, the object prefix is stripped either way. A key
+             * that spells the prefix out does not resolve (see `viewSuffixes`).
              */
             viewLabel: (objectName, viewName, fallback) => resolve(viewSuffixes(objectName, viewName, 'label'), fallback),
             /**
@@ -491,8 +601,11 @@ const SAFE_FIELD_LABEL_FALLBACK = {
 export function useSafeFieldLabel() {
     // useObjectLabel delegates to the provider-safe useObjectTranslation (react-
     // i18next falls back to the global instance and never throws), so it needs no
-    // try/catch — wrapping the hook call would violate rules-of-hooks. It already
-    // returns a stable memoized object; the module-level fallback stays as a
-    // defensive default, reached only if it ever returns nullish.
+    // try/catch — wrapping the hook call would violate rules-of-hooks. Its memo
+    // now holds with or without an i18next instance, so the object below is
+    // stable on both paths — it was NOT before objectui#5564, which measured a
+    // fresh object every render outside a provider, i.e. the opposite of what
+    // this wrapper advertises. The module-level fallback stays as a defensive
+    // default, reached only if it ever returns nullish.
     return useObjectLabel() ?? SAFE_FIELD_LABEL_FALLBACK;
 }

package/dist/useSafeTranslation.js

@@ -3,20 +3,68 @@
  *
  * When no I18nProvider is available (e.g., in tests or standalone usage),
  * this hook falls back to the provided default translations instead of
- * returning raw i18n keys.
+ * returning raw i18n keys — and, for a key the `defaults` map does not carry,
+ * to the call site's own inline `t(key, { defaultValue })` (objectui#3865).
+ * The lookup order is i18next's, so a provider-less host and a provider-mounted
+ * one render the same string: `defaults[key]` (the pack value's stand-in here)
+ * -> `defaultValue` -> the key.
  *
  * @param defaults - Fallback English translations keyed by i18n key
  * @param testKey - A key to test if i18n is properly configured (must be in defaults)
  */
-import { useObjectTranslation } from './provider';
+import { useObjectTranslation } from './provider.js';
+/**
+ * The i18next option that names the string to use when the lookup misses.
+ *
+ * It is a LOOKUP CONTROL, not interpolation data (objectui#3865): it chooses
+ * which string is rendered, so it must never also be spliced into a
+ * `{{defaultValue}}` hole in the string it chose — or in any other.
+ */
+const DEFAULT_VALUE_OPTION = 'defaultValue';
 export function createSafeTranslation(defaults, testKey) {
     // Factory-level fallback: one stable reference per defaults map, so
     // downstream useMemo/useCallback deps don't invalidate every render in
     // the no-translations case.
     const fallbackT = (key, options) => {
-        let value = defaults[key] || key;
+        // Lookup order: defaults table -> inline `defaultValue` -> the key itself
+        // (objectui#3865). The table is the pack value's stand-in on this path, so
+        // it takes the pack's position in i18next's own order — verified against a
+        // real i18next 26.3.6 instance configured the way `createI18n` configures
+        // it: `t('anchor', { defaultValue: 'INLINE' })` is the pack's `'Anchor
+        // value'`, `t('missing', { defaultValue: 'INLINE' })` is `'INLINE'`, and
+        // `t('missing')` is `'missing'`.
+        //
+        // Before this, the inline default was DEAD on both paths for every
+        // component behind this factory: the provider path never reaches it
+        // (the pack value always wins), and this path did not read it at all —
+        // it rendered the raw key and then treated `defaultValue` as one more
+        // interpolation variable. A census over all 26 `createSafeTranslation`
+        // hooks measured 27 keys whose table lacks them, 21 of those carrying an
+        // inline default that used to be dropped (objectui#3865; the fact is
+        // recorded on objectui#3810, whose option C rests on it).
+        //
+        // Non-strings are ignored rather than coerced — this function returns a
+        // `string`, and i18next itself declines a `null` default. `||` (not `??`)
+        // keeps the whole chain consistent with the pre-existing `defaults[key] ||`
+        // step: an empty string at any position falls through to the next.
+        const inlineDefault = options?.[DEFAULT_VALUE_OPTION];
+        let value = defaults[key] || (typeof inlineDefault === 'string' ? inlineDefault : '') || key;
         if (options) {
             for (const [k, v] of Object.entries(options)) {
+                // Reserved: see DEFAULT_VALUE_OPTION. Skipped whatever its type, so an
+                // ignored non-string default cannot re-enter through this loop.
+                //
+                // This is the one deliberate divergence from i18next on this path, and
+                // it is unreachable with today's strings: i18next passes the whole
+                // options object to its interpolator, so it WOULD render
+                // `'Fallback: {{defaultValue}}'` as `'Fallback: INLINE'` (measured on
+                // 26.3.6) — but no value in this repo spells that hole (zero hits for
+                // `{{defaultValue` across packages/apps/examples), and splicing a
+                // fallback string into a hole named after itself has no sensible
+                // reading. The alternative — letting a call site's fallback text leak
+                // into an unrelated table value — is the worse of the two.
+                if (k === DEFAULT_VALUE_OPTION)
+                    continue;
                 // `split(needle).join(value)` — deliberately not `replace`, and not
                 // `replaceAll` either (objectui#3418). This path must agree with
                 // i18next, which serves the *provider* path; any divergence is a

package/dist/utils/index.d.ts

@@ -1,3 +1,4 @@
-export { formatDate, formatDateTime, formatRelativeTime, formatCurrency, formatNumber, type DateFormatOptions, type CurrencyFormatOptions, type NumberFormatOptions, } from './formatting';
-export { resolvePlural, formatDateSpec, formatNumberSpec, applyLocaleConfig, type SpecPluralRule, type SpecDateFormat, type SpecNumberFormat, type SpecLocaleConfig, } from './spec-formatters';
-export { isSpecTranslationData, transformSpecTranslations, type SpecTranslationData, } from './spec-translations';
+export { formatDate, formatDateTime, formatRelativeTime, formatCurrency, formatNumber, type DateFormatOptions, type CurrencyFormatOptions, type NumberFormatOptions, } from './formatting.js';
+export { resolvePlural, formatDateSpec, formatNumberSpec, applyLocaleConfig, type SpecPluralRule, type SpecDateFormat, type SpecNumberFormat, type SpecLocaleConfig, } from './spec-formatters.js';
+export { isSpecTranslationData, transformSpecTranslations, type SpecTranslationData, } from './spec-translations.js';
+export { formatDisplayNumber, shouldGroupDisplayNumber, type DisplayNumberFormatOptions, } from './number-display.js';

package/dist/utils/index.js

@@ -1,3 +1,4 @@
-export { formatDate, formatDateTime, formatRelativeTime, formatCurrency, formatNumber, } from './formatting';
-export { resolvePlural, formatDateSpec, formatNumberSpec, applyLocaleConfig, } from './spec-formatters';
-export { isSpecTranslationData, transformSpecTranslations, } from './spec-translations';
+export { formatDate, formatDateTime, formatRelativeTime, formatCurrency, formatNumber, } from './formatting.js';
+export { resolvePlural, formatDateSpec, formatNumberSpec, applyLocaleConfig, } from './spec-formatters.js';
+export { isSpecTranslationData, transformSpecTranslations, } from './spec-translations.js';
+export { formatDisplayNumber, shouldGroupDisplayNumber, } from './number-display.js';

package/dist/utils/number-display.d.ts

@@ -0,0 +1,32 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * RE-EXPORT ONLY — the implementation moved to `@object-ui/core`
+ * (`utils/number-display.ts`) in objectui#4576. Read it there; nothing is
+ * redeclared here, so there is no second copy to drift.
+ *
+ * Why it moved: `@object-ui/core`'s `dataset-format.ts` needs this exact
+ * policy, and it could not import it while it lived here — `core` is the
+ * React-free engine and this package depends on `i18next`/`react-i18next` and
+ * peer-depends on React. So `formatMeasure` kept a parallel `Intl`
+ * implementation, and the two drifted apart in the one place `Intl` and a
+ * hand-built string disagree: a German session read `1.234,5 %` from a list
+ * cell beside `1.234,5%` from a dashboard measure (objectui#4576). The function
+ * is pure, so the boundary was never a property of the code — only of where the
+ * code sat. Moving it DOWN removed the obstacle; this package gained a
+ * dependency on `@object-ui/core` (no cycle: `core` imports nothing from here).
+ *
+ * This file survives as a re-export rather than being deleted so that BOTH
+ * historical import paths keep working byte-compatibly — the package entry
+ * (`@object-ui/i18n`, used by `fields`, `components` and `plugin-dashboard`)
+ * and the relative `../utils/number-display` this package's own suite uses.
+ * `number-display.reexport-identity.test.ts` pins that the two paths resolve to
+ * the SAME function object and the same type, so a future edit cannot quietly
+ * reintroduce a copy.
+ */
+export { formatDisplayNumber, shouldGroupDisplayNumber, type DisplayNumberFormatOptions, } from '@object-ui/core';

package/dist/utils/number-display.js

@@ -0,0 +1,32 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * RE-EXPORT ONLY — the implementation moved to `@object-ui/core`
+ * (`utils/number-display.ts`) in objectui#4576. Read it there; nothing is
+ * redeclared here, so there is no second copy to drift.
+ *
+ * Why it moved: `@object-ui/core`'s `dataset-format.ts` needs this exact
+ * policy, and it could not import it while it lived here — `core` is the
+ * React-free engine and this package depends on `i18next`/`react-i18next` and
+ * peer-depends on React. So `formatMeasure` kept a parallel `Intl`
+ * implementation, and the two drifted apart in the one place `Intl` and a
+ * hand-built string disagree: a German session read `1.234,5 %` from a list
+ * cell beside `1.234,5%` from a dashboard measure (objectui#4576). The function
+ * is pure, so the boundary was never a property of the code — only of where the
+ * code sat. Moving it DOWN removed the obstacle; this package gained a
+ * dependency on `@object-ui/core` (no cycle: `core` imports nothing from here).
+ *
+ * This file survives as a re-export rather than being deleted so that BOTH
+ * historical import paths keep working byte-compatibly — the package entry
+ * (`@object-ui/i18n`, used by `fields`, `components` and `plugin-dashboard`)
+ * and the relative `../utils/number-display` this package's own suite uses.
+ * `number-display.reexport-identity.test.ts` pins that the two paths resolve to
+ * the SAME function object and the same type, so a future edit cannot quietly
+ * reintroduce a copy.
+ */
+export { formatDisplayNumber, shouldGroupDisplayNumber, } from '@object-ui/core';

package/dist/utils/spec-formatters.d.ts

@@ -6,18 +6,33 @@
  * LICENSE file in the root directory of this source tree.
  */
 /**
- * @object-ui/i18n - Spec-aligned i18n utilities
+ * @object-ui/i18n - locale formatting helpers
  *
- * Runtime consumers for @objectstack/spec v2.0.7 i18n types:
- * - PluralRuleSchema → resolvePlural()
- * - DateFormatSchema → formatDateSpec()
- * - NumberFormatSchema → formatNumberSpec()
- * - LocaleConfigSchema → applyLocaleConfig()
+ * ## Provenance of the four shapes below (objectui#4597)
+ *
+ * They were authored against `@objectstack/spec/ui`, which exported
+ * `PluralRuleSchema`, `DateFormatSchema`, `NumberFormatSchema` and
+ * `LocaleConfigSchema` up to and including 17.0.0-rc.5. The pinned
+ * 17.0.0-rc.6 removed all four under ADR-0049 enforce-or-remove
+ * (objectstack#5055, maintainer ruling 2026-08-06): they carried no key on any
+ * authorable shape and nothing ever parsed them, so the vocabulary was retired
+ * rather than given a door. The key sets here were faithful to the retired
+ * schemas — this is a retirement, not a drift.
+ *
+ * Nothing in the pinned protocol models locale formatting today, so the
+ * interfaces below are declarations this package owns outright, not a view onto
+ * a protocol type. The retirement note records that localisation returns as
+ * authorable metadata through a new ADR — "the formatter that reads a
+ * LocaleConfig first, the vocabulary second" — so re-derive these at that point
+ * instead of assuming they still track anything upstream.
  *
  * @module spec-formatters
  */
 /**
- * Spec-aligned PluralRule (mirrors @objectstack/spec PluralRuleSchema).
+ * Plural forms for a single translation key, in CLDR categories.
+ *
+ * Local shape — authored against the protocol's `PluralRuleSchema`, retired in
+ * 17.0.0-rc.6 (see the module doc), so there is nothing upstream to derive from.
  */
 export interface SpecPluralRule {
     /** Translation key */
@@ -54,7 +69,10 @@ export interface SpecPluralRule {
  */
 export declare function resolvePlural(rule: SpecPluralRule, count: number, locale?: string): string;
 /**
- * Spec-aligned DateFormat (mirrors @objectstack/spec DateFormatSchema).
+ * Date/time formatting options passed through to `Intl.DateTimeFormat`.
+ *
+ * Local shape — authored against the protocol's `DateFormatSchema`, retired in
+ * 17.0.0-rc.6 (see the module doc), so there is nothing upstream to derive from.
  */
 export interface SpecDateFormat {
     dateStyle?: 'full' | 'long' | 'medium' | 'short';
@@ -63,7 +81,7 @@ export interface SpecDateFormat {
     hour12?: boolean;
 }
 /**
- * Format a date using @objectstack/spec DateFormatSchema configuration.
+ * Format a date using a {@link SpecDateFormat} configuration.
  *
  * @example
  * ```ts
@@ -76,7 +94,11 @@ export interface SpecDateFormat {
  */
 export declare function formatDateSpec(date: Date | string | number, format: SpecDateFormat, locale?: string): string;
 /**
- * Spec-aligned NumberFormat (mirrors @objectstack/spec NumberFormatSchema).
+ * Number formatting options passed through to `Intl.NumberFormat`.
+ *
+ * Local shape — authored against the protocol's `NumberFormatSchema`, retired
+ * in 17.0.0-rc.6 (see the module doc), so there is nothing upstream to derive
+ * from.
  */
 export interface SpecNumberFormat {
     style?: 'currency' | 'percent' | 'decimal' | 'unit';
@@ -87,7 +109,7 @@ export interface SpecNumberFormat {
     useGrouping?: boolean;
 }
 /**
- * Format a number using @objectstack/spec NumberFormatSchema configuration.
+ * Format a number using a {@link SpecNumberFormat} configuration.
  *
  * @example
  * ```ts
@@ -100,7 +122,11 @@ export interface SpecNumberFormat {
  */
 export declare function formatNumberSpec(value: number, format: SpecNumberFormat, locale?: string): string;
 /**
- * Spec-aligned LocaleConfig (mirrors @objectstack/spec LocaleConfigSchema).
+ * One locale's formatting defaults, resolved by `applyLocaleConfig()`.
+ *
+ * Local shape — authored against the protocol's `LocaleConfigSchema`, retired
+ * in 17.0.0-rc.6 (see the module doc), so there is nothing upstream to derive
+ * from.
  */
 export interface SpecLocaleConfig {
     /** BCP 47 language code (e.g., 'en-US', 'zh-CN') */
@@ -115,7 +141,7 @@ export interface SpecLocaleConfig {
     dateFormat?: SpecDateFormat;
 }
 /**
- * Apply a LocaleConfigSchema to configure i18n formatting defaults.
+ * Apply a {@link SpecLocaleConfig} to configure i18n formatting defaults.
  * Returns resolved formatting functions bound to the locale config.
  *
  * @example

package/dist/utils/spec-formatters.js

@@ -36,7 +36,7 @@ export function resolvePlural(rule, count, locale = 'en') {
     return template.replace(/\{count\}/g, String(count));
 }
 /**
- * Format a date using @objectstack/spec DateFormatSchema configuration.
+ * Format a date using a {@link SpecDateFormat} configuration.
  *
  * @example
  * ```ts
@@ -63,7 +63,7 @@ export function formatDateSpec(date, format, locale = 'en') {
     return new Intl.DateTimeFormat(locale, options).format(d);
 }
 /**
- * Format a number using @objectstack/spec NumberFormatSchema configuration.
+ * Format a number using a {@link SpecNumberFormat} configuration.
  *
  * @example
  * ```ts
@@ -91,7 +91,7 @@ export function formatNumberSpec(value, format, locale = 'en') {
     return new Intl.NumberFormat(locale, options).format(value);
 }
 /**
- * Apply a LocaleConfigSchema to configure i18n formatting defaults.
+ * Apply a {@link SpecLocaleConfig} to configure i18n formatting defaults.
  * Returns resolved formatting functions bound to the locale config.
  *
  * @example

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/i18n",
-  "version": "17.3.0",
+  "version": "17.6.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -31,7 +31,8 @@
   },
   "dependencies": {
     "i18next": "^26.3.6",
-    "react-i18next": "^17.0.11"
+    "react-i18next": "^17.0.11",
+    "@object-ui/core": "17.6.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0"
@@ -68,7 +69,7 @@
   "scripts": {
     "build": "tsc",
     "test": "vitest run",
-    "type-check": "tsc --noEmit",
+    "type-check": "tsc --noEmit && tsc -p tsconfig.test.json",
     "lint": "eslint ."
   }
 }