@object-ui/i18n 17.2.0 → 17.5.0

package/dist/pickLocalized.d.ts

@@ -11,5 +11,26 @@
  *
  * 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;

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,30 @@ 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);
 }

package/dist/provider.d.ts

@@ -6,6 +6,72 @@
 import React from 'react';
 import type { i18n as I18nInstance } from 'i18next';
 import { type I18nConfig } from './i18n';
+/**
+ * `localStorage` key holding the user's explicit language choice.
+ *
+ * Follows the console's existing preference-key convention
+ * (`objectui-favorites`, `objectui-recent-items`), and sits beside the theme
+ * preference the same avatar menu writes — a language switch is a preference,
+ * not ephemeral UI state, so it belongs in storage (AGENTS.md §5 #8).
+ *
+ * Exported so an app that builds its own i18next instance (and therefore owns
+ * its bootstrap language — see {@link I18nProviderProps.instance}) can honour
+ * the same preference, and so a sign-out flow can clear it.
+ */
+export declare const LOCALE_STORAGE_KEY = "objectui-locale";
+/**
+ * Read the persisted language choice, or `null` when nothing is stored.
+ *
+ * Defensive by design: `localStorage` does not exist under SSR and *throws* on
+ * access in Safari private mode / partitioned iframes. A language preference is
+ * never worth taking the app down for, so every failure degrades to "nothing
+ * 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;
@@ -15,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 */
@@ -39,6 +118,44 @@ 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`.
+     *
+     * Every language change on the instance is persisted — whether it came from
+     * this provider's `changeLanguage`, a switcher calling
+     * `i18n.changeLanguage()` directly, or app code — because the promise the UI
+     * makes ("this is my language now") must not depend on which API the caller
+     * reached for.
+     *
+     * The *restore* half only applies to an instance this provider creates: when
+     * you pass your own {@link I18nProviderProps.instance}, its bootstrap
+     * language is yours to choose (call {@link readStoredLanguage} if you want
+     * the same preference honoured).
+     *
+     * Set `false` for surfaces that must stay on a fixed language regardless of
+     * what the user picked elsewhere on the origin — previews, demos, screenshot
+     * harnesses.
+     */
+    persistLanguage?: boolean;
     /** Children to render */
     children: React.ReactNode;
 }
@@ -52,7 +169,7 @@ export interface I18nProviderProps {
  * </I18nProvider>
  * ```
  */
-export declare function I18nProvider({ config, instance: externalInstance, loadLanguage, 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
  *
@@ -75,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