@saasicat/ui-vue 0.4.0 → 0.6.0

package/dist/use-super-admin-i18n-DMktRVEt.d.cts

@@ -0,0 +1,210 @@
+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-7b0P8W75.cjs';
+
+/**
+ * App-specific branding data that the platform `AdminLayout` and other
+ * consumers read via `useSuperAdminBrand()`.
+ */
+interface SuperAdminBrand {
+    /** 2-letter abbreviation in the logo badge (`'ma'`, `'da'`, …). */
+    logoText: string;
+    /** Full display name (`'DemoApp'`, `'ClubApp'`, …). */
+    name: string;
+    /** Optional: tag to the right of the name, default `'SuperAdmin'`. */
+    tag?: string;
+}
+/**
+ * Endpoint configuration. `apiBase` is the shared prefix under which
+ * `/manifest`, `/boot` and extra routes live.
+ */
+interface SuperAdminEndpoints {
+    /** Shared prefix, e.g. `'/api/admin'` or `'/api/v1/admin'`. */
+    apiBase: string;
+    /** Pre-login branding endpoint, default `${apiBase}/boot`. */
+    publicBootEndpoint?: string;
+    /** Post-login full-manifest endpoint, default `${apiBase}/manifest`. */
+    manifestEndpoint?: string;
+}
+type ExtensionLoader = () => Promise<Component | {
+    default: Component;
+}>;
+type ExtensionsMap = Record<ComponentKey, ExtensionLoader>;
+type ActionsMap = Record<ActionKey, ActionHandler>;
+interface SuperAdminAuthGuardOptions {
+    /** App provides: is the user currently logged in? */
+    isAuthenticated: () => boolean;
+    /** App provides: does the user have the SuperAdmin role? Default: only check `isAuthenticated`. */
+    isSuperAdmin?: () => boolean;
+    /** App provides: redirect path for unauthenticated calls (e.g. `'/login'`). */
+    onUnauthenticated: () => string;
+}
+/**
+ * Result of a login attempt. Apps pass this back from their auth store to the
+ * platform LoginPage; the page renders an appropriate error message.
+ *
+ * `ok: true` → login succeeded, page redirects to `redirectAfterLogin`.
+ * `ok: false` → page shows `message` or a translation derived from `code`.
+ *
+ * Known codes:
+ *   - `BAD_CREDENTIALS` — wrong email/password combination.
+ *   - `NOT_SUPER_ADMIN` — account does not have the SuperAdmin role.
+ *   - otherwise          — app-specific; `message` is displayed directly.
+ */
+type SuperAdminLoginResult = {
+    ok: true;
+} | {
+    ok: false;
+    code?: 'BAD_CREDENTIALS' | 'NOT_SUPER_ADMIN' | string;
+    message?: string;
+};
+/**
+ * Login adapter. The app passes its auth-store call through here. The platform
+ * LoginPage consumes it via `useSuperAdminLoginAdapter()`, without knowledge
+ * of app-specific stores (Pinia, auth API routes, MFA hooks).
+ */
+interface SuperAdminLoginAdapter {
+    /**
+     * Performs the login. The app store encapsulates the API call, token
+     * storage, MFA hops etc.
+     */
+    login(email: string, password: string): Promise<SuperAdminLoginResult>;
+    /**
+     * Target route after a successful login. Default: `/admin/dashboard`
+     * (platform convention for the standard pages — apps with a different
+     * default mount override this here).
+     */
+    redirectAfterLogin?: string;
+    /**
+     * Optional: dev hint (test account), shown below the form. Deliberately
+     * rendered only when `environment !== 'production'`.
+     */
+    devHint?: {
+        email: string;
+        password: string;
+    };
+}
+interface SuperAdminManifestGuardOptions {
+    /**
+     * App provides: loads the manifest into the app store. The router guard
+     * `await`s the promise before the route is resolved.
+     *
+     * **On loader error:** the promise REJECTS. The router guard catches the
+     * rejection and decides depending on `errorRoute`:
+     *   - `errorRoute` set → redirect to this route (fail-closed).
+     *   - `errorRoute` not set → `console.error` + render allowed
+     *     (defensive default behavior; the app must render the manifest gap
+     *     itself).
+     */
+    ensureLoaded: () => Promise<void>;
+    /**
+     * Optional: read accessor on the loaded manifest. When set, it is exposed
+     * via `provide(SUPER_ADMIN_MANIFEST_KEY)` — the `<ProjectPageHost>`
+     * resolves manifest `projectPages` through it against the
+     * `extensions:` map.
+     */
+    getManifest?: () => AdminManifest | null;
+    /**
+     * Optional: path that the router guard redirects to on a manifest load
+     * error (fail-closed mode). The app must register the route in `appRoutes`
+     * and mark it as `meta.public = true`, otherwise it runs through the
+     * manifest guard again and produces a redirect loop.
+     */
+    errorRoute?: string;
+}
+/**
+ * Guard configuration shared by `buildNavigationGuard()` and
+ * `createSuperAdminApp()` (which embeds both fields in its options).
+ */
+interface SuperAdminGuardOptions {
+    /**
+     * Optional: auth guard. When set, `router.beforeEach` is wired up
+     * automatically — `to.meta.public === true` bypasses the guard.
+     */
+    authGuard?: SuperAdminAuthGuardOptions;
+    /**
+     * Optional: manifest guard. Runs after a successful auth guard, blocks the
+     * render until the manifest is loaded (prevents sidebar flicker).
+     */
+    manifestGuard?: SuperAdminManifestGuardOptions;
+}
+/** Vue inject key for `useSuperAdminBrand()`. */
+declare const SUPER_ADMIN_BRAND_KEY: InjectionKey<SuperAdminBrand>;
+/** Vue inject key for `useSuperAdminEndpoints()`. */
+declare const SUPER_ADMIN_ENDPOINTS_KEY: InjectionKey<Required<SuperAdminEndpoints>>;
+/** Vue inject key for `useSuperAdminExtensions()`. */
+declare const SUPER_ADMIN_EXTENSIONS_KEY: InjectionKey<ExtensionsMap>;
+/** Vue inject key for `useSuperAdminActions()`. */
+declare const SUPER_ADMIN_ACTIONS_KEY: InjectionKey<ActionsMap>;
+/**
+ * Vue inject key for the manifest accessor. Only provided when
+ * `manifestGuard.getManifest` was passed to `createSuperAdminApp()` — the
+ * `<ProjectPageHost>` needs it to resolve project pages.
+ */
+declare const SUPER_ADMIN_MANIFEST_KEY: InjectionKey<() => AdminManifest | null>;
+/** Vue inject key for `useSuperAdminLoginAdapter()`. */
+declare const SUPER_ADMIN_LOGIN_ADAPTER_KEY: InjectionKey<SuperAdminLoginAdapter>;
+/** Vue inject key for `useSuperAdminHttp()` (pre-login HttpClient). */
+declare const SUPER_ADMIN_HTTP_KEY: InjectionKey<HttpClient>;
+/**
+ * Additional Vue plugins (e.g. an app's own NotificationCenter) that a
+ * bootstrap installs after the platform setup, before the mount.
+ */
+type InstallPlugin = (app: App) => void;
+/**
+ * Internal helper, exported for isolated unit tests of the navigation
+ * behavior (auth redirect, manifest fail-closed path). Consumers should call
+ * `createSuperAdminApp()`, not this helper directly.
+ */
+declare function buildNavigationGuard(options: SuperAdminGuardOptions): NavigationGuardWithThis<undefined> | null;
+
+/**
+ * Feedback kind, aligned with the established page conventions
+ * (`positive` = success, `negative` = error).
+ */
+type UiNotifyKind = 'positive' | 'negative' | 'warning' | 'info';
+interface UiNotifyOptions {
+    /** Secondary line below the message (e.g. changed fields, one-time password). */
+    caption?: string;
+    /** Display duration in ms; implementations fall back to their default when unset. */
+    timeoutMs?: number;
+}
+/** Notify port. Compatible with the `(kind, message)` callbacks pages already accept. */
+type UiNotify = (kind: UiNotifyKind, message: string, options?: UiNotifyOptions) => void;
+/** Vue inject key for the notify port (see `Symbol.for` note in super-admin-context.ts). */
+declare const SUPER_ADMIN_NOTIFY_KEY: InjectionKey<UiNotify>;
+
+interface SuperAdminI18n {
+    /** Active UI locale — mutable; switching re-renders all catalog texts. */
+    locale: Ref<SaLocale>;
+    /** Resolved catalog for the active locale (platform + app overrides). */
+    messages: ComputedRef<SaMessages>;
+    /** BCP-47 tag for `Intl`/`toLocaleString` formatting in the active locale. */
+    intlLocale: ComputedRef<string>;
+}
+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).
+     */
+    locale?: SaLocale | Ref<SaLocale>;
+    /** Per-locale string overrides layered over the platform catalog. */
+    overrides?: Partial<Record<SaLocale, SaMessagesOverrides>>;
+}
+declare const SUPER_ADMIN_I18N_KEY: InjectionKey<SuperAdminI18n>;
+declare function createSuperAdminI18n(options?: SuperAdminI18nOptions): SuperAdminI18n;
+/**
+ * Returns the i18n context provided by `createSuperAdminApp()`. Outside a
+ * shell (isolated mounts, tests) a shared German default instance is returned
+ * so callers never have to guard for a missing context.
+ */
+declare function useSuperAdminI18n(): SuperAdminI18n;
+/**
+ * Focused accessor for one catalog namespace:
+ * `const msg = useSaMessages('plans')` → `msg.value.title` /
+ * template `msg.title`.
+ */
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saasicat/ui-vue",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Vue 3 components + composables for the SuperAdmin UI shell. Provides boot loader, manifest loader (ETag cache), nav builder, action registry and standard pages.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -17,6 +17,26 @@
         "default": "./dist/index.cjs"
       }
     },
+    "./client": {
+      "import": {
+        "types": "./dist/client/index.d.ts",
+        "default": "./dist/client/index.js"
+      },
+      "require": {
+        "types": "./dist/client/index.d.cts",
+        "default": "./dist/client/index.cjs"
+      }
+    },
+    "./quasar": {
+      "import": {
+        "types": "./dist/quasar/index.d.ts",
+        "default": "./dist/quasar/index.js"
+      },
+      "require": {
+        "types": "./dist/quasar/index.d.cts",
+        "default": "./dist/quasar/index.cjs"
+      }
+    },
     "./pages/*": "./src/pages-standard/*",
     "./pages-standard/*": "./src/pages-standard/*",
     "./pages-tenant/*": "./src/pages-tenant/*",
@@ -33,7 +53,7 @@
     "src"
   ],
   "dependencies": {
-    "@saasicat/types": "^0.4.0"
+    "@saasicat/types": "^0.6.0"
   },
   "peerDependencies": {
     "pinia": "^2.0.0 || ^3.0.0",
@@ -78,7 +98,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts --clean --external @saasicat/types --external vue --external vue-router --external pinia --external quasar && tsup src/testing-e2e/admin-pages-suite.ts --format esm,cjs --dts --out-dir dist/testing-e2e --external @playwright/test",
+    "build": "tsup",
     "typecheck": "vue-tsc --noEmit -p tsconfig.json",
     "pretest": "pnpm run build",
     "test": "node --test tests/**/*.test.js",

package/src/{action-registry.ts → client/action-registry.ts}

@@ -27,8 +27,8 @@ export interface ResolvedAction<TInput = unknown, TResult = unknown> {
 export class MissingHandlerError extends Error {
     constructor(actionKey: string) {
         super(
-            `Kein Handler für actionKey "${actionKey}" registriert. ` +
-                `Konsument-Shell muss \`actions["${actionKey}"]\` bereitstellen.`,
+            `No handler registered for actionKey "${actionKey}". ` +
+                `The consumer shell must provide \`actions["${actionKey}"]\`.`,
         );
         this.name = 'MissingHandlerError';
     }
@@ -37,8 +37,8 @@ export class MissingHandlerError extends Error {
 export class ActionDefNotInManifestError extends Error {
     constructor(actionKey: string) {
         super(
-            `actionKey "${actionKey}" ist im Manifest nicht deklariert. ` +
-                `Bitte als TenantAction in einer ManifestContribution registrieren.`,
+            `actionKey "${actionKey}" is not declared in the manifest. ` +
+                `Register it as a TenantAction in a ManifestContribution.`,
         );
         this.name = 'ActionDefNotInManifestError';
     }

package/src/{batch-column-fetcher.ts → client/batch-column-fetcher.ts}

@@ -128,14 +128,14 @@ export class BatchColumnFetcher {
 
     private validateBatchEndpoint(col: TenantColumnDef): void {
         if (!col.endpoint || col.endpoint.trim().length === 0) {
-            throw new BatchColumnDriftError(col, 'endpoint ist leer');
+            throw new BatchColumnDriftError(col, 'endpoint is empty');
         }
         if (col.endpoint.includes('{slug}') || col.endpoint.includes('{tenantId}')) {
             throw new BatchColumnDriftError(
                 col,
-                'endpoint enthält per-Tenant-Placeholder ({slug}/{tenantId}). ' +
-                    'Spalten-Endpoints müssen batchfähig sein — bitte Backend ' +
-                    'auf `?tenantIds=...`-Parameter umstellen.',
+                'endpoint contains per-tenant placeholders ({slug}/{tenantId}). ' +
+                    'Column endpoints must be batchable — switch the backend ' +
+                    'to a `?tenantIds=...` parameter.',
             );
         }
     }

package/src/{boot-loader.ts → client/boot-loader.ts}

@@ -41,9 +41,9 @@ export class BootLoader {
     constructor(options: BootLoaderOptions) {
         if (!options?.endpoint) {
             throw new Error(
-                'BootLoader: `endpoint` ist Pflicht (z. B. "/api/admin/boot" ' +
-                    'oder "/api/v1/admin/boot"). Plattform hat keinen Default, ' +
-                    'weil Apps unterschiedliche globalPrefix-Konventionen haben.',
+                'BootLoader: `endpoint` is required (e.g. "/api/admin/boot" ' +
+                    'or "/api/v1/admin/boot"). The platform has no default ' +
+                    'because apps use different globalPrefix conventions.',
             );
         }
         this.endpoint = options.endpoint;

package/src/client/i18n/currency.ts

@@ -0,0 +1,42 @@
+// Currency formatting for the admin UI. Amounts are net euro values; the
+// grouping and decimal separator follow the active UI locale
+// (de → `12.345,60 €`, en → `€12,345.60`).
+
+import { DEFAULT_SA_LOCALE, SA_INTL_LOCALES, type SaLocale } from './locale.js';
+
+const DEFAULT_CURRENCY = 'EUR';
+
+const formatters = new Map<string, Intl.NumberFormat>();
+
+function formatterFor(locale: SaLocale, currency: string, decimals: number): Intl.NumberFormat {
+    const key = `${locale}:${currency}:${decimals}`;
+    let formatter = formatters.get(key);
+    if (!formatter) {
+        formatter = new Intl.NumberFormat(SA_INTL_LOCALES[locale], {
+            style: 'currency',
+            currency,
+            minimumFractionDigits: decimals,
+            maximumFractionDigits: decimals,
+        });
+        formatters.set(key, formatter);
+    }
+    return formatter;
+}
+
+/**
+ * Formats a net amount for display. Whole amounts drop the decimals (`29 €`
+ * rather than `29,00 €`) — the plan and bundle prices the admin UI shows are
+ * mostly round numbers, and the zeros are noise in dense tables.
+ *
+ * Returns an em dash for null/undefined and for values that are not finite
+ * numbers, so callers can pass raw API fields straight through.
+ */
+export function formatCurrency(
+    amount: number | string | null | undefined,
+    locale: SaLocale = DEFAULT_SA_LOCALE,
+    currency: string = DEFAULT_CURRENCY,
+): string {
+    const value = typeof amount === 'string' ? Number(amount) : amount;
+    if (value === null || value === undefined || !Number.isFinite(value)) return '—';
+    return formatterFor(locale, currency, Number.isInteger(value) ? 0 : 2).format(value);
+}

package/src/client/i18n/define.ts

@@ -0,0 +1,59 @@
+// Typed message-catalog helpers. Every namespace is defined once in German —
+// the reference locale that fixes the key structure — and the English variant
+// must mirror that structure exactly, enforced at compile time via
+// `TranslationOf`.
+
+import type { SaLocale } from './locale.js';
+
+/** Nested string map — the shape of every message namespace. */
+export interface MessageTree {
+    readonly [key: string]: string | MessageTree;
+}
+
+/** Maps a reference namespace to "same keys, any string values". */
+export type TranslationOf<T> = {
+    readonly [K in keyof T]: T[K] extends string ? string : TranslationOf<T[K]>;
+};
+
+/** Deep partial of a namespace — the shape consumers pass as overrides. */
+export type PartialMessages<T> = {
+    readonly [K in keyof T]?: T[K] extends string ? string : PartialMessages<T[K]>;
+};
+
+/**
+ * Couples the German reference catalog with its English translation. Missing
+ * or extra keys in the English object are compile errors.
+ */
+export function defineMessages<T extends MessageTree>(
+    de: T,
+    en: TranslationOf<T>,
+): Record<SaLocale, T> {
+    // `TranslationOf<T>` and `T` are structurally identical for string-valued
+    // trees; the cast only erases the mapped-type wrapper.
+    return { de, en: en as T };
+}
+
+/**
+ * Recursively overlays `overrides` onto `base` without mutating either side.
+ * Only string leaves are replaced; keys not present in `base` are ignored —
+ * the catalog structure is fixed by the platform.
+ */
+export function mergeMessages<T extends MessageTree>(
+    base: T,
+    overrides: PartialMessages<T> | undefined,
+): T {
+    if (!overrides) return base;
+    const result: Record<string, string | MessageTree> = {};
+    for (const [key, baseValue] of Object.entries(base)) {
+        const override = (overrides as Record<string, unknown>)[key];
+        if (typeof baseValue === 'string') {
+            result[key] = typeof override === 'string' ? override : baseValue;
+        } else {
+            result[key] = mergeMessages(
+                baseValue,
+                override as PartialMessages<MessageTree> | undefined,
+            );
+        }
+    }
+    return result as T;
+}

package/src/client/i18n/format.ts

@@ -0,0 +1,12 @@
+// Placeholder interpolation for catalog messages: `{name}` is replaced with
+// `params.name`. Unknown placeholders stay verbatim so a missing param is
+// visible in the UI instead of silently disappearing.
+
+export type MessageParams = Record<string, string | number>;
+
+export function formatMessage(template: string, params: MessageParams): string {
+    return template.replace(/\{(\w+)\}/g, (match, name: string) => {
+        const value = params[name];
+        return value === undefined ? match : String(value);
+    });
+}

package/src/client/i18n/index.ts

@@ -0,0 +1,14 @@
+// Framework-free i18n core: locale registry, typed catalogs, interpolation.
+// The reactive Vue binding lives in `src/vue/use-super-admin-i18n.ts`.
+
+export * from './locale.js';
+export {
+    defineMessages,
+    mergeMessages,
+    type MessageTree,
+    type PartialMessages,
+    type TranslationOf,
+} from './define.js';
+export * from './format.js';
+export * from './currency.js';
+export * from './messages.js';

package/src/client/i18n/locale.ts

@@ -0,0 +1,15 @@
+// Supported display locales of the SuperAdmin UI. The platform ships a German
+// (reference) and an English catalog; consumers pick the locale per app or per
+// user via `createSuperAdminApp({ i18n })`.
+
+export type SaLocale = 'de' | 'en';
+
+export const SA_LOCALES: readonly SaLocale[] = ['de', 'en'];
+
+export const DEFAULT_SA_LOCALE: SaLocale = 'de';
+
+/** BCP-47 tags used for `Intl`/`toLocaleString` formatting per UI locale. */
+export const SA_INTL_LOCALES: Record<SaLocale, string> = {
+    de: 'de-DE',
+    en: 'en-US',
+};

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

@@ -0,0 +1,42 @@
+import { defineMessages } from '../define.js';
+
+export const auditMessages = defineMessages(
+    {
+        title: 'Audit-Trail',
+        subtitle: '{count} Einträge · plattformweit.',
+        filterButton: 'Filtern',
+        detailActorPrefix: 'Actor:',
+        filters: {
+            actor: 'Actor (E-Mail)',
+            action: 'Action',
+            entity: 'Entity',
+            since: 'Seit',
+        },
+        columns: {
+            time: 'Zeit',
+            actor: 'Actor',
+            action: 'Action',
+            entity: 'Entity',
+            id: 'ID',
+        },
+    },
+    {
+        title: 'Audit trail',
+        subtitle: '{count} entries · platform-wide.',
+        filterButton: 'Filter',
+        detailActorPrefix: 'Actor:',
+        filters: {
+            actor: 'Actor (email)',
+            action: 'Action',
+            entity: 'Entity',
+            since: 'Since',
+        },
+        columns: {
+            time: 'Time',
+            actor: 'Actor',
+            action: 'Action',
+            entity: 'Entity',
+            id: 'ID',
+        },
+    },
+);