@object-ui/i18n 17.2.0 → 17.5.0

package/dist/useSafeTranslation.js

@@ -3,21 +3,85 @@
  *
  * 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)) {
-                value = value.replace(`{{${k}}}`, String(v));
+                // 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
+                // silent fork that only shows up on provider-less hosts, where we are
+                // least likely to see it:
+                //   1. `replace` with a string needle substitutes only the FIRST
+                //      occurrence. i18next substitutes every one, so a sentence that
+                //      repeats a placeholder ("Selected {{count}} of {{count}} items"
+                //      — natural in many locales, and often required by RTL /
+                //      agglutinative word order) leaked literal braces to users.
+                //   2. `replace` AND `replaceAll` both interpret `$&`, `` $` ``, `$'`
+                //      and `$$` in the *replacement* string. i18next does not. Values
+                //      here are runtime data — record labels, search terms — so this
+                //      one is reachable today, unlike (1).
+                // split/join is literal on both sides, which is exactly i18next's
+                // behaviour, and needs no regex escaping of the placeholder name.
+                value = value.split(`{{${k}}}`).join(String(v));
             }
         }
         return value;

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.2.0",
+  "version": "17.5.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -31,13 +31,14 @@
   },
   "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"
   },
   "devDependencies": {
-    "@types/react": "19.2.17",
+    "@types/react": "19.2.18",
     "react": "19.2.8",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
@@ -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 ."
   }
 }