@object-ui/i18n 17.3.0 → 17.6.0

package/dist/pickLocalized.d.ts

@@ -11,5 +11,63 @@
  *
  * Pure — pair it with `useObjectTranslation().language` (or any current-locale
  * source) at the call site.
+ *
+ * Every limb reads **own properties only** and accepts **only `string` values**
+ * (objectui#3907). Both guards used to hold on the regional and last-resort
+ * limbs alone, which left the other four able to resolve a locale against
+ * `Object.prototype` — `pickLocalized({ en: 'Pricing' }, 'constructor')`
+ * rendered the constructor's source text as the label — and able to
+ * short-circuit the chain with a non-string value, rendering `[object Object]`.
+ * Neither is reachable by an input the contract admits (no BCP-47 tag is an
+ * `Object.prototype` member, and `InlineLocaleMapSchema` is
+ * `z.record(<tag>, z.string())`), so applying them uniformly changes nothing
+ * for any real language tag. It makes this function agree limb for limb with
+ * the backend twin `resolveI18nLabel` (`@objectstack/spec`, objectstack#6765),
+ * whose locale can arrive from an untrusted `Accept-Language` header and which
+ * shipped with exactly these two narrowings recorded as deliberate departures.
+ * The only remaining difference between the two is how each spells a miss —
+ * `''` here for a text node, `undefined` there for a producer's `?? name` chain
+ * — pinned in `plugin-list/src/__tests__/i18nLabel-resolver-parity.test.ts`.
+ *
+ * A guard makes its limb **miss**; it never aborts the resolution. An unusable
+ * entry falls through to the next limb exactly as an absent one does, so
+ * `pickLocalized({ en: 'Pricing' }, 'constructor')` is `'Pricing'`, not `''`.
  */
 export declare function pickLocalized(value: unknown, language: string | undefined | null): string;
+/**
+ * Write `next` back into a possibly-localized value as the `language` entry,
+ * preserving every other locale — the write-side inverse of
+ * {@link pickLocalized}.
+ *
+ * An authoring surface that shows one locale in one text input has to answer
+ * two questions, and they are not the same question: which entry to DISPLAY
+ * (`pickLocalized`) and which entry a save REPLACES. Answering the second with
+ * "the whole value" is the data-loss shape this function exists to remove —
+ * `onChange(e.target.value)` straight back over `{ en, zh-CN }` destroys every
+ * locale the author was not looking at, silently, on the first keystroke.
+ *
+ * - Plain string / `null` / `undefined` / array input: there is no map to
+ *   preserve, so the result is `next` itself. A string-valued label keeps
+ *   behaving exactly as it always has.
+ * - Inline locale map: the result is the same map with exactly one entry
+ *   replaced (or added — see {@link localeWriteKey}). Non-string entries and
+ *   unrelated locales are carried across untouched.
+ *
+ * The pairing with `pickLocalized` is the invariant that matters and it is
+ * pinned in `__tests__/setLocalized.test.ts`: for any map and any language,
+ * `pickLocalized(setLocalized(map, lang, s), lang) === s`. If the two functions
+ * ever drift apart, an edit lands in an entry the panel does not display and
+ * the "saved" string vanishes — which is why they live in one file.
+ *
+ * ⚠️ This is the minimal non-destructive write for a SINGLE-locale editor. It
+ * is not a multi-locale authoring UI and does not pretend to be: an author can
+ * only ever reach the entry for the locale they are in.
+ *
+ * Authoring every locale from one surface remains an OPEN product question, and
+ * is deliberately not deferred to a tracker here: the deferral this replaced
+ * named objectui#4163, which closed as completed on 2026-08-15 with the question
+ * still unanswered. A comment pointing at a closed card reads as though the
+ * question were settled somewhere, which is how the previous stale premise in
+ * this area survived unread.
+ */
+export declare function setLocalized(value: unknown, language: string | undefined | null, next: string): string | Record<string, unknown>;

package/dist/pickLocalized.js

@@ -11,6 +11,27 @@
  *
  * Pure — pair it with `useObjectTranslation().language` (or any current-locale
  * source) at the call site.
+ *
+ * Every limb reads **own properties only** and accepts **only `string` values**
+ * (objectui#3907). Both guards used to hold on the regional and last-resort
+ * limbs alone, which left the other four able to resolve a locale against
+ * `Object.prototype` — `pickLocalized({ en: 'Pricing' }, 'constructor')`
+ * rendered the constructor's source text as the label — and able to
+ * short-circuit the chain with a non-string value, rendering `[object Object]`.
+ * Neither is reachable by an input the contract admits (no BCP-47 tag is an
+ * `Object.prototype` member, and `InlineLocaleMapSchema` is
+ * `z.record(<tag>, z.string())`), so applying them uniformly changes nothing
+ * for any real language tag. It makes this function agree limb for limb with
+ * the backend twin `resolveI18nLabel` (`@objectstack/spec`, objectstack#6765),
+ * whose locale can arrive from an untrusted `Accept-Language` header and which
+ * shipped with exactly these two narrowings recorded as deliberate departures.
+ * The only remaining difference between the two is how each spells a miss —
+ * `''` here for a text node, `undefined` there for a producer's `?? name` chain
+ * — pinned in `plugin-list/src/__tests__/i18nLabel-resolver-parity.test.ts`.
+ *
+ * A guard makes its limb **miss**; it never aborts the resolution. An unusable
+ * entry falls through to the next limb exactly as an absent one does, so
+ * `pickLocalized({ en: 'Pricing' }, 'constructor')` is `'Pricing'`, not `''`.
  */
 export function pickLocalized(value, language) {
     if (value == null)
@@ -21,18 +42,105 @@ export function pickLocalized(value, language) {
         return String(value);
     if (typeof value === 'object') {
         const o = value;
+        /**
+         * One entry, or `undefined` when this limb does not hit — which is what
+         * lets the limbs keep chaining through `??` in the same order as before.
+         */
+        const read = (key) => {
+            if (!Object.prototype.hasOwnProperty.call(o, key))
+                return undefined;
+            const entry = o[key];
+            return typeof entry === 'string' ? entry : undefined;
+        };
         const lang = (language || 'en').trim();
         const base = lang.split('-')[0];
         // Runtime language is often a bare base code ('zh') while metadata authors
         // write full BCP-47 tags ('zh-CN') — upgrade to any key sharing the base.
-        const regional = Object.keys(o).find((k) => k.split('-')[0] === base && typeof o[k] === 'string');
-        const pick = o[lang] ??
-            o[base] ??
-            (regional !== undefined ? o[regional] : undefined) ??
-            o.default ??
-            o.en ??
+        // `Object.keys` is already own-and-enumerable, so `read` here is uniformity
+        // rather than a second guard.
+        const regional = Object.keys(o).find((k) => k.split('-')[0] === base && read(k) !== undefined);
+        const pick = read(lang) ??
+            read(base) ??
+            (regional !== undefined ? read(regional) : undefined) ??
+            read('default') ??
+            read('en') ??
             Object.values(o).find((v) => typeof v === 'string');
-        return pick == null ? '' : String(pick);
+        return pick == null ? '' : pick;
     }
     return String(value);
 }
+/**
+ * The map key an edit made in `language` must be WRITTEN to — the write-side
+ * twin of {@link pickLocalized}'s read limbs.
+ *
+ * It deliberately implements only the first three limbs (exact tag, base
+ * language, region-qualified sibling) and then STOPS. `pickLocalized` continues
+ * into `default` -> `en` -> first value, and those last three limbs must never
+ * be write targets: they are DISPLAY fallbacks that hand back *another*
+ * locale's string. Following them would mean an author editing in `fr`, shown
+ * the `en` entry because the map has no French, saves and overwrites English.
+ * When no entry for the active locale exists the edit ADDS one under the active
+ * tag and every stored entry survives untouched.
+ *
+ * The first three limbs are followed exactly because they identify the entry
+ * the author was actually looking at. Writing `zh` when the map stores `zh-CN`
+ * would leave the edited-away `zh-CN` string in place — invisible in the panel
+ * that just "changed" it, still live for any consumer that asks for `zh-CN`.
+ *
+ * Own properties only, `string` values only, for the same reason every
+ * `pickLocalized` limb narrowed that way in objectui#3907: a locale tag that
+ * names an `Object.prototype` member is not an entry, so it cannot be the entry
+ * the author edited.
+ */
+function localeWriteKey(o, language) {
+    const lang = (language || 'en').trim() || 'en';
+    const base = lang.split('-')[0];
+    const has = (key) => Object.prototype.hasOwnProperty.call(o, key) && typeof o[key] === 'string';
+    if (has(lang))
+        return lang;
+    if (has(base))
+        return base;
+    return Object.keys(o).find((k) => k.split('-')[0] === base && has(k)) ?? lang;
+}
+/**
+ * Write `next` back into a possibly-localized value as the `language` entry,
+ * preserving every other locale — the write-side inverse of
+ * {@link pickLocalized}.
+ *
+ * An authoring surface that shows one locale in one text input has to answer
+ * two questions, and they are not the same question: which entry to DISPLAY
+ * (`pickLocalized`) and which entry a save REPLACES. Answering the second with
+ * "the whole value" is the data-loss shape this function exists to remove —
+ * `onChange(e.target.value)` straight back over `{ en, zh-CN }` destroys every
+ * locale the author was not looking at, silently, on the first keystroke.
+ *
+ * - Plain string / `null` / `undefined` / array input: there is no map to
+ *   preserve, so the result is `next` itself. A string-valued label keeps
+ *   behaving exactly as it always has.
+ * - Inline locale map: the result is the same map with exactly one entry
+ *   replaced (or added — see {@link localeWriteKey}). Non-string entries and
+ *   unrelated locales are carried across untouched.
+ *
+ * The pairing with `pickLocalized` is the invariant that matters and it is
+ * pinned in `__tests__/setLocalized.test.ts`: for any map and any language,
+ * `pickLocalized(setLocalized(map, lang, s), lang) === s`. If the two functions
+ * ever drift apart, an edit lands in an entry the panel does not display and
+ * the "saved" string vanishes — which is why they live in one file.
+ *
+ * ⚠️ This is the minimal non-destructive write for a SINGLE-locale editor. It
+ * is not a multi-locale authoring UI and does not pretend to be: an author can
+ * only ever reach the entry for the locale they are in.
+ *
+ * Authoring every locale from one surface remains an OPEN product question, and
+ * is deliberately not deferred to a tracker here: the deferral this replaced
+ * named objectui#4163, which closed as completed on 2026-08-15 with the question
+ * still unanswered. A comment pointing at a closed card reads as though the
+ * question were settled somewhere, which is how the previous stale premise in
+ * this area survived unread.
+ */
+export function setLocalized(value, language, next) {
+    if (value == null || typeof value !== 'object' || Array.isArray(value))
+        return next;
+    const o = value;
+    return { ...o, [localeWriteKey(o, language)]: next };
+}

package/dist/provider.d.ts

@@ -5,7 +5,7 @@
  */
 import React from 'react';
 import type { i18n as I18nInstance } from 'i18next';
-import { type I18nConfig } from './i18n';
+import { type I18nConfig } from './i18n.js';
 /**
  * `localStorage` key holding the user's explicit language choice.
  *
@@ -28,6 +28,50 @@ export declare const LOCALE_STORAGE_KEY = "objectui-locale";
  * stored".
  */
 export declare function readStoredLanguage(): string | null;
+/**
+ * `localStorage` key caching the TENANT's server-side locale — a *seed*, not a
+ * choice (objectui#4035).
+ *
+ * Deliberately a separate slot from {@link LOCALE_STORAGE_KEY}, and that
+ * separation is the whole point rather than a tidiness preference. The two
+ * values have different provenance and therefore different rights:
+ *
+ * - {@link LOCALE_STORAGE_KEY} is what the *user* picked. It outranks
+ *   everything and must survive a tenant reconfiguration.
+ * - This slot is what the *admin* configured, cached so the next boot can apply
+ *   it synchronously. It outranks only the environment (browser language).
+ *
+ * Writing the server seed into the explicit-choice slot would erase that
+ * difference permanently: the seed would then be indistinguishable from a
+ * deliberate user choice, so it would (a) outrank a later tenant change and pin
+ * the device to a stale locale forever, and (b) suppress browser detection for
+ * a user who never expressed a preference. Only a real switch promotes a
+ * language to the explicit slot — see the `languageChanged` choke point.
+ */
+export declare const LOCALE_SEED_STORAGE_KEY = "objectui-locale-seed";
+/**
+ * Read the cached tenant locale seed, or `null` when nothing is cached.
+ *
+ * Same defensive posture as {@link readStoredLanguage}: `localStorage` is
+ * absent under SSR and *throws* in Safari private mode / partitioned iframes,
+ * and a language seed is never worth taking the app down for.
+ */
+export declare function readCachedLanguageSeed(): string | null;
+/**
+ * Cache the tenant locale the server just answered with — the "revalidate" half
+ * of the stale-while-revalidate contract (objectstack#5419, ruling point 2).
+ *
+ * Call this with whatever `/auth/me/localization` actually returned for an
+ * authenticated caller. A `null`/`undefined` locale CLEARS the cache rather
+ * than leaving the old value: a tenant that unsets its locale must reach
+ * choice-less devices on their next boot, and "keep the last good seed forever"
+ * is precisely the being-pinned-by-a-stale-seed failure the ruling forbids.
+ *
+ * A *failed* fetch must simply not call this — the cache is then left intact,
+ * which is the correct stale-while-revalidate behaviour when revalidation
+ * cannot complete.
+ */
+export declare function cacheLanguageSeed(locale: string | null | undefined): void;
 interface I18nContextValue {
     /** Current language code */
     language: string;
@@ -37,6 +81,19 @@ interface I18nContextValue {
     direction: 'ltr' | 'rtl';
     /** The underlying i18next instance */
     i18n: I18nInstance;
+    /**
+     * The languages a switcher may offer (objectui#4039): the app's own locale
+     * list ∩ what this renderer can resolve. Computed here because only the
+     * provider knows both sides — the built-in packs, `config.resources` and
+     * whether a dynamic loader is wired.
+     *
+     * `null` means "still asking the app". Consumers render nothing (or a
+     * skeleton) rather than a list they will have to retract a tick later.
+     * Without {@link I18nProviderProps.loadLocales} wiring, or when the app's
+     * endpoint cannot be reached, this is the offline fallback: the built-in
+     * packs plus `config.resources`.
+     */
+    offerableLanguages: readonly string[] | null;
 }
 export interface I18nProviderProps {
     /** i18n configuration options */
@@ -61,6 +118,24 @@ export interface I18nProviderProps {
      * ```
      */
     loadLanguage?: (lang: string) => Promise<Record<string, unknown>>;
+    /**
+     * The app's own locale list — the codes it actually ships translations for
+     * (objectui#4039). Wired the same way as {@link I18nProviderProps.loadLanguage}:
+     * the app owns the transport, the provider owns what is done with the answer.
+     *
+     * The console reads `GET /api/v1/i18n/locales`; see
+     * `apps/console/src/loadLocales.ts`. Without this prop the switcher keeps
+     * offering the built-in packs (plus `config.resources`) exactly as before, so
+     * an app that never wires it is unaffected.
+     *
+     * @example
+     * ```tsx
+     * <I18nProvider loadLanguage={loadLanguage} loadLocales={loadLocales}>
+     *   <App />
+     * </I18nProvider>
+     * ```
+     */
+    loadLocales?: () => Promise<string[]>;
     /**
      * Remember the active language in `localStorage` ({@link LOCALE_STORAGE_KEY})
      * and restore it on the next mount. Default: `true`.
@@ -94,7 +169,7 @@ export interface I18nProviderProps {
  * </I18nProvider>
  * ```
  */
-export declare function I18nProvider({ config, instance: externalInstance, loadLanguage, persistLanguage, children, }: I18nProviderProps): React.FunctionComponentElement<React.ProviderProps<I18nContextValue | null>>;
+export declare function I18nProvider({ config, instance: externalInstance, loadLanguage, loadLocales, persistLanguage, children, }: I18nProviderProps): React.FunctionComponentElement<React.ProviderProps<I18nContextValue | null>>;
 /**
  * Hook to access Object UI i18n context
  *
@@ -117,6 +192,13 @@ export declare function useObjectTranslation(ns?: string): {
     direction: "ltr" | "rtl";
     /** The underlying i18next instance */
     i18n: I18nInstance;
+    /**
+     * Languages a switcher may offer (objectui#4039). `null` while the app's
+     * locale list is in flight. Outside a provider there is nobody to ask, so
+     * the built-in packs are the answer — not `null`, which would leave a
+     * standalone switcher permanently blank.
+     */
+    offerableLanguages: readonly string[] | null;
 };
 /**
  * Hook to access the i18n context directly