@object-ui/i18n 17.3.0 → 17.5.0

package/dist/useDisplayLocale.js

@@ -0,0 +1,55 @@
+/**
+ * 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.
+ */
+import { useLocalization } from './LocalizationContext';
+import { useObjectTranslation } from './provider';
+/**
+ * `useDisplayLocale` — the BCP-47 tag that field / cell / metric renderers
+ * format numbers and other `Intl` values with.
+ *
+ * This composes the two locale channels this repo already has; it does not add
+ * a third. The precedence, highest first:
+ *
+ *  1. **`useLocalization().locale`** — the tenant's resolved regional default
+ *     (ADR-0053, served by `GET /api/v1/auth/me/localization`). An org that has
+ *     explicitly configured a display locale means it, so it outranks the UI
+ *     language. Frequently `undefined`: the endpoint is
+ *     cosmetic and non-blocking, so an unconfigured or still-loading tenant
+ *     simply has no answer here (the state objectui#4033 was measured in — a
+ *     fresh database, console running `zh-CN`).
+ *
+ *  2. **`useObjectTranslation().language`** — the ACTIVE UI language, i.e. what
+ *     the user picked in the language switcher. This is the channel that makes
+ *     grouping and decimal marks follow the user's language when the tenant has
+ *     stated no regional preference.
+ *
+ *  3. **`'en'`** — a concrete last resort rather than `undefined`. `undefined`
+ *     would hand `Intl` the *machine's* locale, which is invisible in review and
+ *     non-deterministic in CI; `'en'` at least fails the same way everywhere.
+ *     Note this is `'en'`, not `'en-US'`: the point of objectui#4033 is that
+ *     `en-US` is not the world's default. In practice step 2 already answers,
+ *     since `useObjectTranslation` falls back to the react-i18next global
+ *     instance and ultimately reports `'en'` itself.
+ *
+ * Provider-safe at every step: `useLocalization` returns `{}` outside its
+ * provider and `useObjectTranslation` reads an optional context, so a renderer
+ * mounted standalone (tests, docs demos) degrades instead of throwing.
+ *
+ * **This composition is also the whole `'zh'` ↔ BCP-47 story** (objectui#4468).
+ * There is no mapping table anywhere and none is needed: the UI language codes
+ * this renderer ships (`'zh'`, `'ja'`, `'de'`, …) are already well-formed
+ * BCP-47 language subtags, so `Intl` accepts them verbatim. The one thing a
+ * caller must not do is reach past this hook for the raw tenant locale and hand
+ * `Intl` the `undefined` it gets on an unconfigured workspace — `undefined`
+ * means "the MACHINE's locale", which is neither channel. Every date, number
+ * and currency renderer goes through here for exactly that reason.
+ */
+export function useDisplayLocale() {
+    const { locale } = useLocalization();
+    const { language } = useObjectTranslation();
+    return locale || language || 'en';
+}

package/dist/useObjectLabel.d.ts

@@ -151,7 +151,10 @@ export declare function useObjectLabel(): {
     }) => string;
     /**
      * 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: string, viewName: string, fallback: string) => string;
     /**
@@ -371,7 +374,10 @@ export declare function useSafeFieldLabel(): {
     }) => string;
     /**
      * 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: string, viewName: string, fallback: string) => string;
     /**

package/dist/useObjectLabel.js

@@ -188,19 +188,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 {
             /**
@@ -309,7 +326,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),
             /**

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';
+/**
+ * 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 { formatDisplayNumber, shouldGroupDisplayNumber, type DisplayNumberFormatOptions, } from './number-display';

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 { formatDisplayNumber, shouldGroupDisplayNumber, } from './number-display';

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.5.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.5.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 ."
   }
 }