@saasicat/ui-vue 0.15.0 → 0.16.0

package/src/vue/use-super-admin-i18n.ts

@@ -8,16 +8,28 @@
 // Without a provider the composables fall back to a shared German instance, so
 // isolated mounts and unit tests need no setup.
 
-import { computed, inject, isRef, ref, type ComputedRef, type InjectionKey, type Ref } from 'vue';
+import {
+    computed,
+    inject,
+    isReadonly,
+    isRef,
+    ref,
+    watch,
+    type ComputedRef,
+    type InjectionKey,
+    type Ref,
+} from 'vue';
 
 import {
     DEFAULT_SA_LOCALE,
     SA_INTL_LOCALES,
+    isSaLocale,
     resolveMessages,
     type SaLocale,
     type SaMessages,
     type SaMessagesOverrides,
 } from '../client/i18n/index.js';
+import { defaultKvStore, type KvStore } from '../client/types.js';
 
 export interface SuperAdminI18n {
     /** Active UI locale — mutable; switching re-renders all catalog texts. */
@@ -26,18 +38,45 @@ export interface SuperAdminI18n {
     messages: ComputedRef<SaMessages>;
     /** BCP-47 tag for `Intl`/`toLocaleString` formatting in the active locale. */
     intlLocale: ComputedRef<string>;
+    /**
+     * Whether the shell renders its language switcher. `false` when the app
+     * opted out or when `locale` cannot be written to — a switcher that cannot
+     * change anything is worse than none.
+     */
+    switcherEnabled: boolean;
 }
 
 export interface SuperAdminI18nOptions {
     /**
-     * Initial UI locale, default `'de'`. Pass a `Ref` when the app wants to
-     * keep control (e.g. a user-profile setting or a header switcher).
+     * Starting UI locale, default `'de'` — the shell's switcher lets the user
+     * pick another one, and a stored pick outranks this. Pass a `Ref` when the
+     * app wants to keep control (e.g. a user-profile setting).
      */
     locale?: SaLocale | Ref<SaLocale>;
     /** Per-locale string overrides layered over the platform catalog. */
     overrides?: Partial<Record<SaLocale, SaMessagesOverrides>>;
+    /**
+     * Remembers the locale picked in the header switcher across reloads,
+     * default `true`. Ignored when `locale` is a `Ref`: the app owns that value
+     * and persists it wherever it belongs (user profile, its own store).
+     */
+    persist?: boolean;
+    /**
+     * Storage adapter for `persist`. Defaults to `defaultKvStore()`. Pass a
+     * key-prefixing wrapper when several apps share one origin.
+     */
+    storage?: KvStore;
+    /**
+     * Renders the language switcher in the shell chrome, default `true`. Set
+     * `false` for a deployment that ships one language. A readonly `locale`
+     * ref disables it on its own — no need to set this as well.
+     */
+    switcher?: boolean;
 }
 
+/** `KvStore` key holding the locale the user picked in the switcher. */
+export const SA_LOCALE_STORAGE_KEY = 'sa:locale';
+
 // `Symbol.for` — see super-admin-context.ts: dist- and src-imported module
 // instances must resolve to the same injection key.
 export const SUPER_ADMIN_I18N_KEY: InjectionKey<SuperAdminI18n> = Symbol.for(
@@ -45,14 +84,38 @@ export const SUPER_ADMIN_I18N_KEY: InjectionKey<SuperAdminI18n> = Symbol.for(
 );
 
 export function createSuperAdminI18n(options: SuperAdminI18nOptions = {}): SuperAdminI18n {
-    const locale = isRef(options.locale)
-        ? options.locale
-        : ref(options.locale ?? DEFAULT_SA_LOCALE);
+    const locale = isRef(options.locale) ? options.locale : createOwnedLocale(options);
     const messages = computed(() =>
         resolveMessages(locale.value, options.overrides?.[locale.value]),
     );
     const intlLocale = computed(() => SA_INTL_LOCALES[locale.value]);
-    return { locale, messages, intlLocale };
+    // A readonly ref (typically a `computed` derived from a profile setting)
+    // silently swallows writes, so the switcher would be a dead control. The
+    // type system permits it — TypeScript ignores `readonly` when checking
+    // assignability — so the guard has to be a runtime one.
+    const writable = !isReadonly(locale);
+    return {
+        locale,
+        messages,
+        intlLocale,
+        switcherEnabled: (options.switcher ?? true) && writable,
+    };
+}
+
+/**
+ * Builds the locale ref the platform owns. A stored choice outranks the
+ * `locale` option, because that option is the app's default while the stored
+ * value is the user's explicit pick in the switcher.
+ */
+function createOwnedLocale(options: SuperAdminI18nOptions): Ref<SaLocale> {
+    if (options.persist === false) {
+        return ref(options.locale ?? DEFAULT_SA_LOCALE);
+    }
+    const storage = options.storage ?? defaultKvStore();
+    const stored = storage.get(SA_LOCALE_STORAGE_KEY);
+    const locale = ref(isSaLocale(stored) ? stored : (options.locale ?? DEFAULT_SA_LOCALE));
+    watch(locale, (next) => storage.set(SA_LOCALE_STORAGE_KEY, next));
+    return locale;
 }
 
 let fallbackI18n: SuperAdminI18n | null = null;
@@ -65,7 +128,10 @@ let fallbackI18n: SuperAdminI18n | null = null;
 export function useSuperAdminI18n(): SuperAdminI18n {
     const injected = inject(SUPER_ADMIN_I18N_KEY, null);
     if (injected) return injected;
-    fallbackI18n ??= createSuperAdminI18n();
+    // Deliberately not persisted: this instance exists for mounts outside a
+    // shell, and a shared singleton that reads and writes real storage would
+    // make test outcomes depend on their order.
+    fallbackI18n ??= createSuperAdminI18n({ persist: false });
     return fallbackI18n;
 }