@saasicat/ui-vue 0.15.0 → 0.16.0

package/dist/{messages-BIYw32u1.d.ts → messages-DetB75lX.d.cts}

@@ -25,8 +25,11 @@ interface KvStore {
     remove(key: string): void;
 }
 /**
- * Returns a `KvStore` wrapper around `localStorage` (or `null` under SSR).
- * Tests may pass an in-memory stub.
+ * Returns a `KvStore` wrapper around `localStorage`, or a no-op store when the
+ * environment has none or refuses access. Tests may pass an in-memory stub.
+ *
+ * Every persistence built on this is a convenience — losing it must never take
+ * the app down, so no failure mode is allowed to escape.
  */
 declare function defaultKvStore(): KvStore;
 /**
@@ -40,6 +43,14 @@ declare const SA_LOCALES: readonly SaLocale[];
 declare const DEFAULT_SA_LOCALE: SaLocale;
 /** BCP-47 tags used for `Intl`/`toLocaleString` formatting per UI locale. */
 declare const SA_INTL_LOCALES: Record<SaLocale, string>;
+/**
+ * Names for the language switcher. Endonyms — a language is listed in its own
+ * language, so the entries stay readable no matter which locale is active and
+ * never need translating.
+ */
+declare const SA_LOCALE_LABELS: Record<SaLocale, string>;
+/** Narrows untrusted input (persisted preference, query parameter) to a locale. */
+declare function isSaLocale(value: unknown): value is SaLocale;
 
 /** Consumer implementation; receives the action inputs as a generic object. */
 type ActionHandler<TInput = unknown, TResult = unknown> = (input: TInput) => Promise<TResult>;
@@ -1405,6 +1416,7 @@ declare const shellMessages: Record<SaLocale, {
         subtitle: string;
         roleBadge: string;
         logout: string;
+        language: string;
     };
     drawer: {
         docs: string;
@@ -1582,4 +1594,4 @@ declare const SA_MESSAGES: Record<SaLocale, SaMessages>;
  */
 declare function resolveMessages(locale: SaLocale, overrides?: SaMessagesOverrides): SaMessages;
 
-export { type ActionHandler as A, DEFAULT_SA_LOCALE as D, type HttpClient as H, type KvStore as K, type MessageTree as M, type PartialMessages as P, type ResolvedAction as R, type SaLocale as S, type TranslationOf as T, type SaMessages as a, type SaMessagesOverrides as b, ActionRegistry as c, ActionDefNotInManifestError as d, type HttpResponse as e, MissingHandlerError as f, SA_INTL_LOCALES as g, SA_LOCALES as h, SA_MESSAGES as i, defaultHttpClient as j, defaultKvStore as k, defineMessages as l, mergeMessages as m, resolveMessages as r };
+export { type ActionHandler as A, DEFAULT_SA_LOCALE as D, type HttpClient as H, type KvStore as K, type MessageTree as M, type PartialMessages as P, type ResolvedAction as R, type SaLocale as S, type TranslationOf as T, type SaMessages as a, type SaMessagesOverrides as b, ActionRegistry as c, ActionDefNotInManifestError as d, type HttpResponse as e, MissingHandlerError as f, SA_INTL_LOCALES as g, SA_LOCALES as h, SA_LOCALE_LABELS as i, SA_MESSAGES as j, defaultHttpClient as k, defaultKvStore as l, defineMessages as m, isSaLocale as n, mergeMessages as o, resolveMessages as r };

package/dist/{messages-BIYw32u1.d.cts → messages-DetB75lX.d.ts}

@@ -25,8 +25,11 @@ interface KvStore {
     remove(key: string): void;
 }
 /**
- * Returns a `KvStore` wrapper around `localStorage` (or `null` under SSR).
- * Tests may pass an in-memory stub.
+ * Returns a `KvStore` wrapper around `localStorage`, or a no-op store when the
+ * environment has none or refuses access. Tests may pass an in-memory stub.
+ *
+ * Every persistence built on this is a convenience — losing it must never take
+ * the app down, so no failure mode is allowed to escape.
  */
 declare function defaultKvStore(): KvStore;
 /**
@@ -40,6 +43,14 @@ declare const SA_LOCALES: readonly SaLocale[];
 declare const DEFAULT_SA_LOCALE: SaLocale;
 /** BCP-47 tags used for `Intl`/`toLocaleString` formatting per UI locale. */
 declare const SA_INTL_LOCALES: Record<SaLocale, string>;
+/**
+ * Names for the language switcher. Endonyms — a language is listed in its own
+ * language, so the entries stay readable no matter which locale is active and
+ * never need translating.
+ */
+declare const SA_LOCALE_LABELS: Record<SaLocale, string>;
+/** Narrows untrusted input (persisted preference, query parameter) to a locale. */
+declare function isSaLocale(value: unknown): value is SaLocale;
 
 /** Consumer implementation; receives the action inputs as a generic object. */
 type ActionHandler<TInput = unknown, TResult = unknown> = (input: TInput) => Promise<TResult>;
@@ -1405,6 +1416,7 @@ declare const shellMessages: Record<SaLocale, {
         subtitle: string;
         roleBadge: string;
         logout: string;
+        language: string;
     };
     drawer: {
         docs: string;
@@ -1582,4 +1594,4 @@ declare const SA_MESSAGES: Record<SaLocale, SaMessages>;
  */
 declare function resolveMessages(locale: SaLocale, overrides?: SaMessagesOverrides): SaMessages;
 
-export { type ActionHandler as A, DEFAULT_SA_LOCALE as D, type HttpClient as H, type KvStore as K, type MessageTree as M, type PartialMessages as P, type ResolvedAction as R, type SaLocale as S, type TranslationOf as T, type SaMessages as a, type SaMessagesOverrides as b, ActionRegistry as c, ActionDefNotInManifestError as d, type HttpResponse as e, MissingHandlerError as f, SA_INTL_LOCALES as g, SA_LOCALES as h, SA_MESSAGES as i, defaultHttpClient as j, defaultKvStore as k, defineMessages as l, mergeMessages as m, resolveMessages as r };
+export { type ActionHandler as A, DEFAULT_SA_LOCALE as D, type HttpClient as H, type KvStore as K, type MessageTree as M, type PartialMessages as P, type ResolvedAction as R, type SaLocale as S, type TranslationOf as T, type SaMessages as a, type SaMessagesOverrides as b, ActionRegistry as c, ActionDefNotInManifestError as d, type HttpResponse as e, MissingHandlerError as f, SA_INTL_LOCALES as g, SA_LOCALES as h, SA_LOCALE_LABELS as i, SA_MESSAGES as j, defaultHttpClient as k, defaultKvStore as l, defineMessages as m, isSaLocale as n, mergeMessages as o, resolveMessages as r };

package/dist/quasar/index.cjs

@@ -33,6 +33,45 @@ var import_pinia = require("pinia");
 var import_vue_router = require("vue-router");
 
 // src/client/types.ts
+var NOOP_KV_STORE = {
+  get: () => null,
+  set: () => {
+  },
+  remove: () => {
+  }
+};
+function defaultKvStore() {
+  const ls = resolveLocalStorage();
+  if (!ls) return NOOP_KV_STORE;
+  return {
+    get: (k) => {
+      try {
+        return ls.getItem(k);
+      } catch {
+        return null;
+      }
+    },
+    set: (k, v) => {
+      try {
+        ls.setItem(k, v);
+      } catch {
+      }
+    },
+    remove: (k) => {
+      try {
+        ls.removeItem(k);
+      } catch {
+      }
+    }
+  };
+}
+function resolveLocalStorage() {
+  try {
+    return globalThis.localStorage ?? null;
+  } catch {
+    return null;
+  }
+}
 function defaultHttpClient() {
   return (url, init) => fetch(url, init);
 }
@@ -93,11 +132,15 @@ var SUPER_ADMIN_NOTIFY_KEY = /* @__PURE__ */ Symbol.for(
 var import_vue = require("vue");
 
 // src/client/i18n/locale.ts
+var SA_LOCALES = ["de", "en"];
 var DEFAULT_SA_LOCALE = "de";
 var SA_INTL_LOCALES = {
   de: "de-DE",
   en: "en-US"
 };
+function isSaLocale(value) {
+  return typeof value === "string" && SA_LOCALES.includes(value);
+}
 
 // src/client/i18n/define.ts
 function defineMessages(de, en) {
@@ -2777,7 +2820,8 @@ var shellMessages = defineMessages(
       productionWarning: "Aktionen wirken sich sofort auf alle Mandanten aus.",
       subtitle: "SuperAdmin \xB7 Plattform-Verwaltung",
       roleBadge: "SUPER ADMIN",
-      logout: "Abmelden"
+      logout: "Abmelden",
+      language: "Sprache"
     },
     drawer: {
       docs: "Doku \xF6ffnen"
@@ -2845,7 +2889,8 @@ var shellMessages = defineMessages(
       productionWarning: "Actions take effect immediately for all tenants.",
       subtitle: "SuperAdmin \xB7 Platform administration",
       roleBadge: "SUPER ADMIN",
-      logout: "Sign out"
+      logout: "Sign out",
+      language: "Language"
     },
     drawer: {
       docs: "Open documentation"
@@ -3119,16 +3164,33 @@ function resolveMessages(locale, overrides) {
 }
 
 // src/vue/use-super-admin-i18n.ts
+var SA_LOCALE_STORAGE_KEY = "sa:locale";
 var SUPER_ADMIN_I18N_KEY = /* @__PURE__ */ Symbol.for(
   "@saasicat/ui-vue/SUPER_ADMIN_I18N"
 );
 function createSuperAdminI18n(options = {}) {
-  const locale = (0, import_vue.isRef)(options.locale) ? options.locale : (0, import_vue.ref)(options.locale ?? DEFAULT_SA_LOCALE);
+  const locale = (0, import_vue.isRef)(options.locale) ? options.locale : createOwnedLocale(options);
   const messages = (0, import_vue.computed)(
     () => resolveMessages(locale.value, options.overrides?.[locale.value])
   );
   const intlLocale = (0, import_vue.computed)(() => SA_INTL_LOCALES[locale.value]);
-  return { locale, messages, intlLocale };
+  const writable = !(0, import_vue.isReadonly)(locale);
+  return {
+    locale,
+    messages,
+    intlLocale,
+    switcherEnabled: (options.switcher ?? true) && writable
+  };
+}
+function createOwnedLocale(options) {
+  if (options.persist === false) {
+    return (0, import_vue.ref)(options.locale ?? DEFAULT_SA_LOCALE);
+  }
+  const storage = options.storage ?? defaultKvStore();
+  const stored = storage.get(SA_LOCALE_STORAGE_KEY);
+  const locale = (0, import_vue.ref)(isSaLocale(stored) ? stored : options.locale ?? DEFAULT_SA_LOCALE);
+  (0, import_vue.watch)(locale, (next) => storage.set(SA_LOCALE_STORAGE_KEY, next));
+  return locale;
 }
 
 // src/quasar/notify.ts

package/dist/quasar/index.d.cts

@@ -2,8 +2,8 @@ import { Component, App } from 'vue';
 import { QuasarPluginOptions } from 'quasar';
 import { Pinia } from 'pinia';
 import { RouteRecordRaw, RouterHistory, Router } from 'vue-router';
-import { H as HttpClient } from '../messages-BIYw32u1.cjs';
-import { S as SuperAdminGuardOptions, a as SuperAdminBrand, b as SuperAdminEndpoints, E as ExtensionsMap, A as ActionsMap, c as SuperAdminLoginAdapter, U as UiNotify, I as InstallPlugin, d as SuperAdminI18nOptions, e as SuperAdminI18n } from '../use-super-admin-i18n-DL_qI1BY.cjs';
+import { H as HttpClient } from '../messages-DetB75lX.cjs';
+import { S as SuperAdminGuardOptions, a as SuperAdminBrand, b as SuperAdminEndpoints, E as ExtensionsMap, A as ActionsMap, c as SuperAdminLoginAdapter, U as UiNotify, I as InstallPlugin, d as SuperAdminI18nOptions, e as SuperAdminI18n } from '../use-super-admin-i18n-DokHhkS_.cjs';
 import '@saasicat/types';
 
 interface CreateSuperAdminAppOptions extends SuperAdminGuardOptions {

package/dist/quasar/index.d.ts

@@ -2,8 +2,8 @@ import { Component, App } from 'vue';
 import { QuasarPluginOptions } from 'quasar';
 import { Pinia } from 'pinia';
 import { RouteRecordRaw, RouterHistory, Router } from 'vue-router';
-import { H as HttpClient } from '../messages-BIYw32u1.js';
-import { S as SuperAdminGuardOptions, a as SuperAdminBrand, b as SuperAdminEndpoints, E as ExtensionsMap, A as ActionsMap, c as SuperAdminLoginAdapter, U as UiNotify, I as InstallPlugin, d as SuperAdminI18nOptions, e as SuperAdminI18n } from '../use-super-admin-i18n-CWNu_W3u.js';
+import { H as HttpClient } from '../messages-DetB75lX.js';
+import { S as SuperAdminGuardOptions, a as SuperAdminBrand, b as SuperAdminEndpoints, E as ExtensionsMap, A as ActionsMap, c as SuperAdminLoginAdapter, U as UiNotify, I as InstallPlugin, d as SuperAdminI18nOptions, e as SuperAdminI18n } from '../use-super-admin-i18n-BPC-H9jz.js';
 import '@saasicat/types';
 
 interface CreateSuperAdminAppOptions extends SuperAdminGuardOptions {

package/dist/quasar/index.js

@@ -10,10 +10,10 @@ import {
   SUPER_ADMIN_NOTIFY_KEY,
   buildNavigationGuard,
   createSuperAdminI18n
-} from "../chunk-TY2WYKME.js";
+} from "../chunk-MGKJCVDU.js";
 import {
   defaultHttpClient
-} from "../chunk-TBLXKSTR.js";
+} from "../chunk-TZ2NGQXK.js";
 
 // src/quasar/create-super-admin-app.ts
 import { createApp } from "vue";

package/dist/{use-super-admin-i18n-CWNu_W3u.d.ts → use-super-admin-i18n-BPC-H9jz.d.ts}

@@ -1,7 +1,7 @@
 import { Component, App, InjectionKey, Ref, ComputedRef } from 'vue';
 import { NavigationGuardWithThis } from 'vue-router';
 import { ActionKey, ComponentKey, AdminManifest } from '@saasicat/types';
-import { A as ActionHandler, H as HttpClient, S as SaLocale, a as SaMessages, b as SaMessagesOverrides } from './messages-BIYw32u1.js';
+import { A as ActionHandler, H as HttpClient, S as SaLocale, a as SaMessages, b as SaMessagesOverrides, K as KvStore } from './messages-DetB75lX.js';
 
 /**
  * App-specific branding data that the platform `AdminLayout` and other
@@ -182,16 +182,42 @@ 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;
 }
 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. */
+declare const SA_LOCALE_STORAGE_KEY = "sa:locale";
 declare const SUPER_ADMIN_I18N_KEY: InjectionKey<SuperAdminI18n>;
 declare function createSuperAdminI18n(options?: SuperAdminI18nOptions): SuperAdminI18n;
 /**
@@ -207,4 +233,4 @@ declare function useSuperAdminI18n(): SuperAdminI18n;
  */
 declare function useSaMessages<K extends keyof SaMessages>(namespace: K): ComputedRef<SaMessages[K]>;
 
-export { type ActionsMap as A, type ExtensionsMap as E, type InstallPlugin as I, type SuperAdminGuardOptions as S, type UiNotify as U, type SuperAdminBrand as a, type SuperAdminEndpoints as b, type SuperAdminLoginAdapter as c, type SuperAdminI18nOptions as d, type SuperAdminI18n as e, type ExtensionLoader as f, SUPER_ADMIN_ACTIONS_KEY as g, SUPER_ADMIN_BRAND_KEY as h, SUPER_ADMIN_ENDPOINTS_KEY as i, SUPER_ADMIN_EXTENSIONS_KEY as j, SUPER_ADMIN_HTTP_KEY as k, SUPER_ADMIN_I18N_KEY as l, SUPER_ADMIN_LOGIN_ADAPTER_KEY as m, SUPER_ADMIN_MANIFEST_KEY as n, SUPER_ADMIN_NOTIFY_KEY as o, type SuperAdminAuthGuardOptions as p, type SuperAdminLoginResult as q, type SuperAdminManifestGuardOptions as r, type UiNotifyKind as s, type UiNotifyOptions as t, buildNavigationGuard as u, createSuperAdminI18n as v, useSaMessages as w, useSuperAdminI18n as x };
+export { type ActionsMap as A, type ExtensionsMap as E, type InstallPlugin as I, type SuperAdminGuardOptions as S, type UiNotify as U, type SuperAdminBrand as a, type SuperAdminEndpoints as b, type SuperAdminLoginAdapter as c, type SuperAdminI18nOptions as d, type SuperAdminI18n as e, type ExtensionLoader as f, SA_LOCALE_STORAGE_KEY as g, SUPER_ADMIN_ACTIONS_KEY as h, SUPER_ADMIN_BRAND_KEY as i, SUPER_ADMIN_ENDPOINTS_KEY as j, SUPER_ADMIN_EXTENSIONS_KEY as k, SUPER_ADMIN_HTTP_KEY as l, SUPER_ADMIN_I18N_KEY as m, SUPER_ADMIN_LOGIN_ADAPTER_KEY as n, SUPER_ADMIN_MANIFEST_KEY as o, SUPER_ADMIN_NOTIFY_KEY as p, type SuperAdminAuthGuardOptions as q, type SuperAdminLoginResult as r, type SuperAdminManifestGuardOptions as s, type UiNotifyKind as t, type UiNotifyOptions as u, buildNavigationGuard as v, createSuperAdminI18n as w, useSaMessages as x, useSuperAdminI18n as y };

package/dist/{use-super-admin-i18n-DL_qI1BY.d.cts → use-super-admin-i18n-DokHhkS_.d.cts}

@@ -1,7 +1,7 @@
 import { Component, App, InjectionKey, Ref, ComputedRef } from 'vue';
 import { NavigationGuardWithThis } from 'vue-router';
 import { ActionKey, ComponentKey, AdminManifest } from '@saasicat/types';
-import { A as ActionHandler, H as HttpClient, S as SaLocale, a as SaMessages, b as SaMessagesOverrides } from './messages-BIYw32u1.cjs';
+import { A as ActionHandler, H as HttpClient, S as SaLocale, a as SaMessages, b as SaMessagesOverrides, K as KvStore } from './messages-DetB75lX.cjs';
 
 /**
  * App-specific branding data that the platform `AdminLayout` and other
@@ -182,16 +182,42 @@ 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;
 }
 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. */
+declare const SA_LOCALE_STORAGE_KEY = "sa:locale";
 declare const SUPER_ADMIN_I18N_KEY: InjectionKey<SuperAdminI18n>;
 declare function createSuperAdminI18n(options?: SuperAdminI18nOptions): SuperAdminI18n;
 /**
@@ -207,4 +233,4 @@ declare function useSuperAdminI18n(): SuperAdminI18n;
  */
 declare function useSaMessages<K extends keyof SaMessages>(namespace: K): ComputedRef<SaMessages[K]>;
 
-export { type ActionsMap as A, type ExtensionsMap as E, type InstallPlugin as I, type SuperAdminGuardOptions as S, type UiNotify as U, type SuperAdminBrand as a, type SuperAdminEndpoints as b, type SuperAdminLoginAdapter as c, type SuperAdminI18nOptions as d, type SuperAdminI18n as e, type ExtensionLoader as f, SUPER_ADMIN_ACTIONS_KEY as g, SUPER_ADMIN_BRAND_KEY as h, SUPER_ADMIN_ENDPOINTS_KEY as i, SUPER_ADMIN_EXTENSIONS_KEY as j, SUPER_ADMIN_HTTP_KEY as k, SUPER_ADMIN_I18N_KEY as l, SUPER_ADMIN_LOGIN_ADAPTER_KEY as m, SUPER_ADMIN_MANIFEST_KEY as n, SUPER_ADMIN_NOTIFY_KEY as o, type SuperAdminAuthGuardOptions as p, type SuperAdminLoginResult as q, type SuperAdminManifestGuardOptions as r, type UiNotifyKind as s, type UiNotifyOptions as t, buildNavigationGuard as u, createSuperAdminI18n as v, useSaMessages as w, useSuperAdminI18n as x };
+export { type ActionsMap as A, type ExtensionsMap as E, type InstallPlugin as I, type SuperAdminGuardOptions as S, type UiNotify as U, type SuperAdminBrand as a, type SuperAdminEndpoints as b, type SuperAdminLoginAdapter as c, type SuperAdminI18nOptions as d, type SuperAdminI18n as e, type ExtensionLoader as f, SA_LOCALE_STORAGE_KEY as g, SUPER_ADMIN_ACTIONS_KEY as h, SUPER_ADMIN_BRAND_KEY as i, SUPER_ADMIN_ENDPOINTS_KEY as j, SUPER_ADMIN_EXTENSIONS_KEY as k, SUPER_ADMIN_HTTP_KEY as l, SUPER_ADMIN_I18N_KEY as m, SUPER_ADMIN_LOGIN_ADAPTER_KEY as n, SUPER_ADMIN_MANIFEST_KEY as o, SUPER_ADMIN_NOTIFY_KEY as p, type SuperAdminAuthGuardOptions as q, type SuperAdminLoginResult as r, type SuperAdminManifestGuardOptions as s, type UiNotifyKind as t, type UiNotifyOptions as u, buildNavigationGuard as v, createSuperAdminI18n as w, useSaMessages as x, useSuperAdminI18n as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saasicat/ui-vue",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Vue 3 components, resource clients and composables for the SuperAdmin UI shell. Provides boot and manifest loaders, navigation, actions and standard pages.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -53,7 +53,7 @@
     "src"
   ],
   "dependencies": {
-    "@saasicat/types": "^0.15.0"
+    "@saasicat/types": "^0.16.0"
   },
   "peerDependencies": {
     "pinia": "^2.0.0 || ^3.0.0",

package/src/client/i18n/locale.ts

@@ -13,3 +13,18 @@ export const SA_INTL_LOCALES: Record<SaLocale, string> = {
     de: 'de-DE',
     en: 'en-US',
 };
+
+/**
+ * Names for the language switcher. Endonyms — a language is listed in its own
+ * language, so the entries stay readable no matter which locale is active and
+ * never need translating.
+ */
+export const SA_LOCALE_LABELS: Record<SaLocale, string> = {
+    de: 'Deutsch',
+    en: 'English',
+};
+
+/** Narrows untrusted input (persisted preference, query parameter) to a locale. */
+export function isSaLocale(value: unknown): value is SaLocale {
+    return typeof value === 'string' && (SA_LOCALES as readonly string[]).includes(value);
+}

package/src/client/i18n/messages/shell.ts

@@ -10,6 +10,7 @@ export const shellMessages = defineMessages(
             subtitle: 'SuperAdmin · Plattform-Verwaltung',
             roleBadge: 'SUPER ADMIN',
             logout: 'Abmelden',
+            language: 'Sprache',
         },
         drawer: {
             docs: 'Doku öffnen',
@@ -81,6 +82,7 @@ export const shellMessages = defineMessages(
             subtitle: 'SuperAdmin · Platform administration',
             roleBadge: 'SUPER ADMIN',
             logout: 'Sign out',
+            language: 'Language',
         },
         drawer: {
             docs: 'Open documentation',

package/src/client/types.ts

@@ -28,27 +28,64 @@ export interface KvStore {
     remove(key: string): void;
 }
 
+/** Stand-in for when there is no usable `localStorage`. */
+const NOOP_KV_STORE: KvStore = {
+    get: () => null,
+    set: () => {},
+    remove: () => {},
+};
+
 /**
- * Returns a `KvStore` wrapper around `localStorage` (or `null` under SSR).
- * Tests may pass an in-memory stub.
+ * Returns a `KvStore` wrapper around `localStorage`, or a no-op store when the
+ * environment has none or refuses access. Tests may pass an in-memory stub.
+ *
+ * Every persistence built on this is a convenience — losing it must never take
+ * the app down, so no failure mode is allowed to escape.
  */
 export function defaultKvStore(): KvStore {
-    if (typeof globalThis.localStorage === 'undefined') {
-        // SSR / non-browser → no-op stub.
-        return {
-            get: () => null,
-            set: () => {},
-            remove: () => {},
-        };
-    }
-    const ls = globalThis.localStorage;
+    const ls = resolveLocalStorage();
+    if (!ls) return NOOP_KV_STORE;
     return {
-        get: (k) => ls.getItem(k),
-        set: (k, v) => ls.setItem(k, v),
-        remove: (k) => ls.removeItem(k),
+        get: (k) => {
+            try {
+                return ls.getItem(k);
+            } catch {
+                // See resolveLocalStorage: access can be revoked per call too.
+                return null;
+            }
+        },
+        set: (k, v) => {
+            try {
+                ls.setItem(k, v);
+            } catch {
+                // Full quota or Safari's private mode — the value is simply
+                // not remembered.
+            }
+        },
+        remove: (k) => {
+            try {
+                ls.removeItem(k);
+            } catch {
+                // Nothing to clean up if the store is unreachable.
+            }
+        },
     };
 }
 
+/**
+ * `localStorage` is a throwing getter, not a plain property: a browser that
+ * blocks site data (cookie blocking, a sandboxed iframe) raises `SecurityError`
+ * on read, and `typeof` evaluates the getter rather than guarding it. The
+ * access therefore has to happen inside `try`.
+ */
+function resolveLocalStorage(): Storage | null {
+    try {
+        return globalThis.localStorage ?? null;
+    } catch {
+        return null;
+    }
+}
+
 /**
  * Default `HttpClient` over `fetch`. Consumers pass their own variant
  * through when they need auth headers / tenant headers / retry logic.

package/src/components/LocaleSwitcher.vue

@@ -0,0 +1,68 @@
+<template>
+    <q-btn
+        v-if="visible"
+        class="sa-locale-switcher"
+        flat
+        dense
+        no-caps
+        icon="language"
+        :label="SA_LOCALE_LABELS[locale]"
+        :aria-label="msg.header.language"
+    >
+        <q-menu auto-close anchor="bottom right" self="top right">
+            <q-list dense class="sa-locale-switcher__list">
+                <q-item
+                    v-for="option in SA_LOCALES"
+                    :key="option"
+                    clickable
+                    :active="option === locale"
+                    @click="select(option)"
+                >
+                    <q-item-section>{{ SA_LOCALE_LABELS[option] }}</q-item-section>
+                    <q-item-section v-if="option === locale" side>
+                        <q-icon name="check" size="16px" />
+                    </q-item-section>
+                </q-item>
+            </q-list>
+        </q-menu>
+    </q-btn>
+</template>
+
+<script setup lang="ts">
+import { SA_LOCALES, SA_LOCALE_LABELS, type SaLocale } from '../client/i18n/index.js';
+import { useSaMessages, useSuperAdminI18n } from '../vue/use-super-admin-i18n.js';
+
+// Language switcher for the shell chrome. Writes straight to the shared i18n
+// locale, so every catalog text, the sidebar labels and `Intl` formatting
+// follow on the next render.
+//
+// The button inherits its color from the surrounding chrome (`currentColor`),
+// so it needs no variant prop — each host sets the color it wants.
+//
+// It renders nothing when the app opted out of the switcher or handed over a
+// locale it does not allow writing to; hosts therefore embed it unconditionally
+// and never have to repeat that check.
+
+const { locale, switcherEnabled } = useSuperAdminI18n();
+
+// Only an explicit `false` hides the switcher. The injection key is a
+// `Symbol.for`, so a context created by an older copy of this package resolves
+// here just as well — and that one has no `switcherEnabled` at all. Treating
+// the missing field as "off" would make every switcher vanish after such an
+// upgrade, without a warning anywhere. Chrome fails open.
+const visible = switcherEnabled !== false;
+const msg = useSaMessages('shell');
+
+function select(next: SaLocale): void {
+    locale.value = next;
+}
+</script>
+
+<style scoped>
+.sa-locale-switcher {
+    color: inherit;
+}
+.sa-locale-switcher__list {
+    min-width: 160px;
+}
+</style>

package/src/pages-standard/AdminLayout.vue

@@ -14,6 +14,7 @@
                 </q-toolbar-title>
                 <q-space />
                 <slot name="header-actions" />
+                <LocaleSwitcher class="q-mr-sm" />
                 <q-badge class="sa-admin-badge q-mr-sm">{{ msg.header.roleBadge }}</q-badge>
                 <div class="sa-admin-user">
                     <q-avatar size="32px" class="sa-admin-user__avatar">
@@ -97,6 +98,7 @@ import { computed, inject, ref } from 'vue';
 import { useRoute } from 'vue-router';
 import type { AdminManifest, StandardPageKey } from '@saasicat/types';
 import { buildRoutes, buildSidebar, defaultSectionOrder } from '../client/nav-builder.js';
+import LocaleSwitcher from '../components/LocaleSwitcher.vue';
 import { SUPER_ADMIN_BRAND_KEY, SUPER_ADMIN_MANIFEST_KEY } from '../vue/super-admin-context.js';
 import { useSaMessages, useSuperAdminI18n } from '../vue/use-super-admin-i18n.js';
 import { ADMIN_UI_VERSION } from '../client/version.js';

package/src/pages-standard/SuperAdminLoginPage.vue

@@ -18,6 +18,7 @@
                     <div class="sa-login-brand__name">{{ brandName }}</div>
                     <div class="sa-login-brand__tag">{{ tagText }}</div>
                 </div>
+                <LocaleSwitcher class="sa-login-locale" />
             </div>
 
             <h1 class="sa-login-title">{{ msg.login.signIn }}</h1>
@@ -98,6 +99,7 @@ import {
 } from '../vue/use-super-admin-context.js';
 import { getJson } from '../client/http-json.js';
 import { useSaMessages } from '../vue/use-super-admin-i18n.js';
+import LocaleSwitcher from '../components/LocaleSwitcher.vue';
 import SuperAdminSetupWizard from './SuperAdminSetupWizard.vue';
 
 interface Props {
@@ -193,6 +195,13 @@ async function handleSubmit(): Promise<void> {
 </script>
 
 <style scoped>
+.sa-login-locale {
+    /* In the card's flow rather than floating over it: a fixed overlay lands
+       on top of the centered card on short viewports. */
+    margin-left: auto;
+    align-self: flex-start;
+    color: var(--sa-login-tag-color, #475569);
+}
 .sa-login-wrap {
     min-height: 100vh;
     display: flex;

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;