@saasicat/ui-vue 0.15.1 → 0.17.0

package/src/pages-standard/SuperAdminSetupWizard.vue

@@ -7,6 +7,7 @@
                     <div class="sa-setup-title">{{ msg.setup.title }}</div>
                     <div class="sa-setup-sub">{{ subtitleText }}</div>
                 </div>
+                <LocaleSwitcher class="sa-setup-locale" />
             </div>
 
             <q-banner v-if="errorMessage" class="sa-setup-error" rounded>
@@ -160,6 +161,7 @@ import {
 import { HttpJsonError, postJson as httpPostJson } from '../client/http-json.js';
 import { formatMessage } from '../client/i18n/format.js';
 import { useSaMessages } from '../vue/use-super-admin-i18n.js';
+import LocaleSwitcher from '../components/LocaleSwitcher.vue';
 
 interface Props {
     /** Display name + badge abbreviation (override the app branding, e.g. from PublicBoot). */
@@ -288,6 +290,11 @@ async function submitConfirm(): Promise<void> {
     gap: 12px;
     margin-bottom: 20px;
 }
+.sa-setup-locale {
+    margin-left: auto;
+    align-self: flex-start;
+    color: #475569;
+}
 .sa-setup-badge {
     width: 44px;
     height: 44px;

package/src/pages-standard/discovery-page/discovery-ui.ts

@@ -4,7 +4,7 @@
 // labels/colors/coverage calculations.
 
 import type { CatalogEntryI18n, DiscoveryStatus } from '@saasicat/types';
-import { DEFAULT_SA_LOCALE, type SaLocale } from '../../client/i18n/locale.js';
+import { DEFAULT_SA_LOCALE, builtinLocaleOf, type SaLocale } from '../../client/i18n/locale.js';
 import { commonMessages } from '../../client/i18n/messages/common.js';
 import { discoveryMessages } from '../../client/i18n/messages/discovery.js';
 
@@ -43,19 +43,19 @@ export function localeFull(locale: string): string {
 }
 
 export function i18nFieldLabel(f: I18nField, locale: SaLocale = DEFAULT_SA_LOCALE): string {
-    if (f === 'label') return discoveryMessages[locale].trans.fieldLabel;
-    if (f === 'description') return commonMessages[locale].description;
-    return discoveryMessages[locale].unit;
+    if (f === 'label') return discoveryMessages[builtinLocaleOf(locale)].trans.fieldLabel;
+    if (f === 'description') return commonMessages[builtinLocaleOf(locale)].description;
+    return discoveryMessages[builtinLocaleOf(locale)].unit;
 }
 
 // ─── Approval lifecycle (#20): status display + state machine ────────────────
 
 export function statusLabel(status: DiscoveryStatus, locale: SaLocale = DEFAULT_SA_LOCALE): string {
-    return discoveryMessages[locale].statusLabels[status];
+    return discoveryMessages[builtinLocaleOf(locale)].statusLabels[status];
 }
 
 export function statusHint(status: DiscoveryStatus, locale: SaLocale = DEFAULT_SA_LOCALE): string {
-    return discoveryMessages[locale].statusHints[status];
+    return discoveryMessages[builtinLocaleOf(locale)].statusHints[status];
 }
 
 export interface ReviewAction {
@@ -71,7 +71,7 @@ export function primaryReviewAction(
     status: DiscoveryStatus,
     locale: SaLocale = DEFAULT_SA_LOCALE,
 ): ReviewAction {
-    const actions = discoveryMessages[locale].reviewActions;
+    const actions = discoveryMessages[builtinLocaleOf(locale)].reviewActions;
     switch (status) {
         case 'pending':
             return { label: actions.approve, to: 'approved', emphasized: true };
@@ -89,7 +89,7 @@ export function reviewMenuActions(
     status: DiscoveryStatus,
     locale: SaLocale = DEFAULT_SA_LOCALE,
 ): ReviewAction[] {
-    const actions = discoveryMessages[locale].reviewActions;
+    const actions = discoveryMessages[builtinLocaleOf(locale)].reviewActions;
     const markObsolete: ReviewAction = {
         label: actions.markObsolete,
         to: 'obsolete',

package/src/pages-standard/plan-versions/format.ts

@@ -1,13 +1,13 @@
 // Formatting helper retained for the reusable catalog-history timeline.
 
 import { formatMessage } from '../../client/i18n/format.js';
-import { DEFAULT_SA_LOCALE, type SaLocale } from '../../client/i18n/locale.js';
+import { DEFAULT_SA_LOCALE, builtinLocaleOf, type SaLocale } from '../../client/i18n/locale.js';
 import { planVersionsMessages } from '../../client/i18n/messages/plan-versions.js';
 
 const EMPTY_VALUE = '—';
 
 function texts(locale: SaLocale) {
-    return planVersionsMessages[locale].format;
+    return planVersionsMessages[builtinLocaleOf(locale)].format;
 }
 
 export function formatRelative(

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

@@ -2,22 +2,35 @@
 // provides one instance; pages, components and composables read it via
 // `useSuperAdminI18n()` or the namespace-focused `useSaMessages()`.
 //
-// Design: no vue-i18n dependency. The platform ships complete typed catalogs
-// (`SA_MESSAGES`, German reference + English translation) and consumers switch
-// the locale or override individual strings through the bootstrap option.
-// Without a provider the composables fall back to a shared German instance, so
+// Design: no vue-i18n dependency. The platform ships two complete typed
+// catalogs (German reference + English translation) and nothing beyond that —
+// which of them an app offers, which languages it adds and what wording it
+// prefers is decided through the bootstrap option and resolved in `SaCatalog`.
+// Without a provider the composables fall back to a shared default 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,
-    resolveMessages,
+    createSaCatalog,
+    type SaCatalog,
     type SaLocale,
+    type SaLocaleDefinition,
+    type SaLocaleOption,
     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 +39,65 @@ 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, when `locale` cannot be written to, or when only one language
+     * is on offer — a switcher that cannot change anything is worse than none.
+     */
+    switcherEnabled: boolean;
+    /** Locales the switcher offers, in order, with their display names. */
+    availableLocales: readonly SaLocaleOption[];
 }
 
 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 — the shell's switcher lets the user pick another one,
+     * and a stored pick outranks this. Defaults to `'de'` when offered,
+     * otherwise to the first entry of `locales`. 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. */
+    /**
+     * Languages to offer, in switcher order. Default: German, English and
+     * everything in `additionalLocales`. Narrow it to ship a single language —
+     * the switcher then hides itself.
+     */
+    locales?: readonly SaLocale[];
+    /**
+     * Languages the app adds on top of the two the platform ships, keyed by
+     * locale code. Untranslated keys fall back to `basedOn`, so a partial
+     * catalog is usable from the first key onwards.
+     */
+    additionalLocales?: Readonly<Record<string, SaLocaleDefinition>>;
+    /** Per-locale string overrides layered over whatever catalog applies. */
     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()`.
+     */
+    storage?: KvStore;
+    /**
+     * Prefix for the persisted key, mirroring `createPlatformLoaders`. Set it
+     * when several apps share one origin and must not inherit each other's
+     * language pick.
+     */
+    storageKeyPrefix?: string;
+    /**
+     * 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 +105,48 @@ 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 messages = computed(() =>
-        resolveMessages(locale.value, options.overrides?.[locale.value]),
+    const catalog = createSaCatalog(options);
+    const locale = isRef(options.locale) ? options.locale : createOwnedLocale(options, catalog);
+    // An unknown locale would otherwise render an empty shell. Falling back
+    // keeps the UI usable and makes the app's mistake visible as "wrong
+    // language" rather than "blank page".
+    const active = computed(() =>
+        catalog.has(locale.value) ? locale.value : catalog.defaultLocale,
     );
-    const intlLocale = computed(() => SA_INTL_LOCALES[locale.value]);
-    return { locale, messages, intlLocale };
+    const messages = computed(() => catalog.messagesFor(active.value));
+    const intlLocale = computed(() => catalog.intlLocaleFor(active.value));
+    // 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 && catalog.locales.length > 1,
+        availableLocales: catalog.locales,
+    };
+}
+
+/**
+ * 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, catalog: SaCatalog): Ref<SaLocale> {
+    const initial = options.locale ?? catalog.defaultLocale;
+    if (options.persist === false) return ref(initial);
+
+    const storage = options.storage ?? defaultKvStore();
+    const key = `${options.storageKeyPrefix ?? ''}${SA_LOCALE_STORAGE_KEY}`;
+    const stored = storage.get(key);
+    // The stored value is checked against what this app offers, not against the
+    // built-ins: an app that dropped a language must not be pushed back into it
+    // by a pick from before.
+    const locale = ref(stored && catalog.has(stored) ? stored : initial);
+    watch(locale, (next) => storage.set(key, next));
+    return locale;
 }
 
 let fallbackI18n: SuperAdminI18n | null = null;
@@ -65,7 +159,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;
 }