@object-ui/i18n 17.6.0 → 17.7.0

package/dist/pickLocalized.d.ts

@@ -71,3 +71,33 @@ export declare function pickLocalized(value: unknown, language: string | undefin
  * this area survived unread.
  */
 export declare function setLocalized(value: unknown, language: string | undefined | null, next: string): string | Record<string, unknown>;
+/**
+ * Remove the `language` entry from a possibly-localized value — the CLEAR arm
+ * of the same editor {@link setLocalized} serves, and the reason it cannot be
+ * spelled as `setLocalized(value, language, '')`.
+ *
+ * A single-line authoring input has three actions, not two: type, retype, and
+ * clear. `setLocalized` answers the first two. Answering the third with "write
+ * the empty string" stores `{ en: '' }` — an entry that claims "English has a
+ * title and it is blank", which then SHADOWS every display fallback: a viewer
+ * in `en` sees nothing where the map's other locales would have been offered.
+ * Answering it with "drop the whole value" is the objectui#9274 data loss
+ * itself, arriving through the clearing door instead of the typing door.
+ *
+ * So clearing removes exactly one entry — the same entry {@link setLocalized}
+ * would have written, chosen by the same {@link localeWriteKey} limbs, which is
+ * what keeps the cleared entry the one the author was actually looking at.
+ *
+ * - Plain string / `null` / `undefined` / array: there is no map, so there is
+ *   nothing localized left — `undefined`. The caller decides how its own field
+ *   spells empty (`undefined` for an optional key, `''` for a required one).
+ * - Map with the active entry present: that entry is removed and every other
+ *   locale is carried across untouched. When it was the LAST entry the result
+ *   is `undefined` rather than `{}`, because an empty map is not a title.
+ * - Map WITHOUT an entry for the active locale: returned unchanged. The box was
+ *   showing a display fallback borrowed from another locale, and clearing a
+ *   borrowed string must not delete the locale it was borrowed from — the same
+ *   refusal {@link localeWriteKey} enforces on the write side, which is why
+ *   both read the same limbs from the same file.
+ */
+export declare function clearLocalized(value: unknown, language: string | undefined | null): Record<string, unknown> | undefined;

package/dist/pickLocalized.js

@@ -144,3 +144,42 @@ export function setLocalized(value, language, next) {
     const o = value;
     return { ...o, [localeWriteKey(o, language)]: next };
 }
+/**
+ * Remove the `language` entry from a possibly-localized value — the CLEAR arm
+ * of the same editor {@link setLocalized} serves, and the reason it cannot be
+ * spelled as `setLocalized(value, language, '')`.
+ *
+ * A single-line authoring input has three actions, not two: type, retype, and
+ * clear. `setLocalized` answers the first two. Answering the third with "write
+ * the empty string" stores `{ en: '' }` — an entry that claims "English has a
+ * title and it is blank", which then SHADOWS every display fallback: a viewer
+ * in `en` sees nothing where the map's other locales would have been offered.
+ * Answering it with "drop the whole value" is the objectui#9274 data loss
+ * itself, arriving through the clearing door instead of the typing door.
+ *
+ * So clearing removes exactly one entry — the same entry {@link setLocalized}
+ * would have written, chosen by the same {@link localeWriteKey} limbs, which is
+ * what keeps the cleared entry the one the author was actually looking at.
+ *
+ * - Plain string / `null` / `undefined` / array: there is no map, so there is
+ *   nothing localized left — `undefined`. The caller decides how its own field
+ *   spells empty (`undefined` for an optional key, `''` for a required one).
+ * - Map with the active entry present: that entry is removed and every other
+ *   locale is carried across untouched. When it was the LAST entry the result
+ *   is `undefined` rather than `{}`, because an empty map is not a title.
+ * - Map WITHOUT an entry for the active locale: returned unchanged. The box was
+ *   showing a display fallback borrowed from another locale, and clearing a
+ *   borrowed string must not delete the locale it was borrowed from — the same
+ *   refusal {@link localeWriteKey} enforces on the write side, which is why
+ *   both read the same limbs from the same file.
+ */
+export function clearLocalized(value, language) {
+    if (value == null || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const o = value;
+    const key = localeWriteKey(o, language);
+    if (!Object.prototype.hasOwnProperty.call(o, key))
+        return o;
+    const rest = Object.fromEntries(Object.entries(o).filter(([k]) => k !== key));
+    return Object.keys(rest).length > 0 ? rest : undefined;
+}

package/dist/provider.d.ts

@@ -17,6 +17,22 @@ import { type I18nConfig } from './i18n.js';
  * 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.
+ *
+ * ⚠️ **What this slot means changed for a SIGNED-IN user (objectui#10059).**
+ * A signed-in user's language has one source of truth and it is not on the
+ * device: it is the server column `sys_user.locale`, read back through
+ * `GET /auth/me/localization` and written by both the profile page's language
+ * card and the console's globe menu. For that user this slot is a CACHE of the
+ * column — it still decides the first paint, because the column cannot be read
+ * synchronously, and it is then overwritten by whatever the column says. It
+ * decides on its own only BEFORE sign-in, which is the case this provider can
+ * see and the only one it adjudicates.
+ *
+ * This provider deliberately does not implement that rule: reading a `sys_user`
+ * row needs an authenticated data adapter, which is a host concern and not a
+ * dependency a renderer package takes. The host applies the column through
+ * {@link I18nContextValue.changeLanguage} like any other switch — in this
+ * repository, `@object-ui/app-shell`'s `useUserLocale`.
  */
 export declare const LOCALE_STORAGE_KEY = "objectui-locale";
 /**
@@ -29,28 +45,53 @@ export declare const LOCALE_STORAGE_KEY = "objectui-locale";
  */
 export declare function readStoredLanguage(): string | null;
 /**
- * `localStorage` key caching the TENANT's server-side locale — a *seed*, not a
- * choice (objectui#4035).
+ * `localStorage` key caching the server's resolved locale for the signed-in
+ * caller — a *seed*, not a choice (objectui#4035).
+ *
+ * ⚠️ **The value is per-USER; the slot is per-DEVICE (objectui#10193).**
+ * `GET /auth/me/localization` answers `locale` as the caller's own
+ * `sys_user.locale` when set, else the request's `Accept-Language`, else the
+ * deployment default — and answers no locale at all before sign-in. It is not
+ * a tenant setting, whatever earlier prose here said. The slot is deliberately
+ * NOT keyed by user: the boot reads it before anyone is signed in, when no
+ * user id exists to key by. What bounds it to one owner is
+ * `@object-ui/auth`'s change-of-owner purge (objectui#5664), which deletes it
+ * when a different user adopts the browser, and which the host answers by
+ * re-resolving the live language (`@object-ui/app-shell`'s
+ * `useSignedInUserLocale`).
+ *
+ * **What a visitor who is not signed in reads**, declared as device behaviour:
+ * the language the LAST signed-in owner of this browser was served, until
+ * someone else signs in. That is the only server answer this device has ever
+ * received — the endpoint gives none before sign-in — and the sign-in page is
+ * the one surface it paints.
  *
  * 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).
+ * - {@link LOCALE_STORAGE_KEY} is what the *user* picked on this device. It
+ *   outranks everything this provider can see and must survive a change in
+ *   what the server answers for the seed below. ⚠️ It does NOT outrank the signed-in user's own
+ *   `sys_user.locale`, which no tier here represents — see that key's own
+ *   docblock (objectui#10059).
+ * - This slot is what the server resolved for the signed-in caller, 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
+ * deliberate user choice, so it would (a) outrank a later server-side 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.
+ * Read the cached locale seed — the server's last resolved locale for this
+ * browser's last signed-in caller (see {@link LOCALE_SEED_STORAGE_KEY}) — 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,
@@ -58,12 +99,13 @@ export declare const LOCALE_SEED_STORAGE_KEY = "objectui-locale-seed";
  */
 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).
+ * Cache the locale the server just resolved for the signed-in caller — 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
+ * than leaving the old value: a server answer that drops the 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.
  *
@@ -72,6 +114,53 @@ export declare function readCachedLanguageSeed(): string | null;
  * cannot complete.
  */
 export declare function cacheLanguageSeed(locale: string | null | undefined): void;
+/**
+ * Options shared by {@link resolveBootstrapLanguage} and
+ * {@link preloadBootstrapLocale}. Each field mirrors the {@link I18nProvider}
+ * prop of the same name, because the two must answer identically — a host that
+ * preloads one catalogue while the provider boots into another has bought a
+ * flash of `en` instead of avoiding one.
+ */
+export interface BootstrapLocaleOptions {
+    /** The `config` you will pass to {@link I18nProvider}. */
+    config?: I18nConfig;
+    /** The `persistLanguage` you will pass to {@link I18nProvider}. Default `true`. */
+    persistLanguage?: boolean;
+    /** Whether you will pass a `loadLanguage` loader. Default `false`. */
+    hasLoader?: boolean;
+}
+/**
+ * The language {@link I18nProvider} will boot in, computed WITHOUT creating an
+ * i18next instance (objectui#7479).
+ *
+ * The full precedence chain, unchanged: explicit choice → seed →
+ * browser language → `defaultLanguage` → `en`.
+ */
+export declare function resolveBootstrapLanguage(options?: BootstrapLocaleOptions): string;
+/**
+ * Fetch the catalogue {@link I18nProvider} will boot in, BEFORE you render it.
+ *
+ * ## Why a host would await this
+ *
+ * Built-in catalogues are lazy since objectui#7479, so the provider can be in
+ * one of two states on its first render, and the difference is visible:
+ *
+ *   - **catalogue already resident** — the first paint is in the user's
+ *     language, exactly as it was when all ten packs shipped eagerly;
+ *   - **catalogue still in flight** — the first paint renders through
+ *     `fallbackLng: 'en'` and re-renders in the user's language when the fetch
+ *     lands. Correct, never blank, and a flash of English for a `zh-CN` viewer.
+ *
+ * ⇒ any host that owns an await before `createRoot().render()` should spend it
+ * here; `apps/console/src/main.tsx` does, alongside the runtime-config and auth
+ * preflight round-trips it already waits on. A host that has no such seam gets
+ * the documented `en`-while-loading behaviour instead, which is why this is a
+ * function a host CALLS rather than a requirement the provider imposes.
+ *
+ * Never rejects: a catalogue that will not download must not take the boot
+ * down, and the provider retries on mount.
+ */
+export declare function preloadBootstrapLocale(options?: BootstrapLocaleOptions): Promise<void>;
 interface I18nContextValue {
     /** Current language code */
     language: string;