@saasicat/ui-vue 0.4.0 → 0.5.0

package/README.md

@@ -6,7 +6,50 @@ standard pages (Dashboard, Tenants, Plans, Discovery, …) and the tenant
 self-service building blocks (`FeatureGate`, `useTenantManifest`,
 `PlanChangeWizard`).
 
-Peer dependencies: `vue`, `vue-router`, `pinia`, `quasar`.
+Peer dependencies: `vue` (required); `vue-router`, `pinia`, `quasar`
+(optional — see the layers below for what actually needs them).
+
+## Layers
+
+The package is layered so that each entry only loads what it names.
+Lower layers never import upward; ESLint (`no-restricted-imports`, repo
+root config) enforces the boundaries in CI.
+
+| Entry | Source | May import | Contents |
+| --- | --- | --- | --- |
+| `@saasicat/ui-vue/client` | `src/client/` | `@saasicat/types` only | Framework-free core: `BootLoader`, `ManifestLoader` (ETag cache), nav builder, action registry, batch column fetcher, `HttpClient`/`KvStore` contract. Usable from any framework or plain Node/TypeScript. |
+| `@saasicat/ui-vue` (main) | `src/vue/` (+ client re-exports) | Vue, `vue-router`, Pinia — **no Quasar** | Composables (`useTenants`, `usePlanEditor`, …), router guards, injection keys + shell contract, notify-port type, optional Pinia store factory. |
+| `@saasicat/ui-vue/quasar` | `src/quasar/` | everything above + Quasar | `createSuperAdminApp()` bootstrap and the Quasar notify-port implementation. |
+| `@saasicat/ui-vue/pages-standard/*`, `/pages-tenant/*`, `/components/*` | SFC directories | everything | The Quasar reference UI, shipped as raw `.vue` from `src/` (compiled by the consumer's Vite). |
+
+Rules of thumb when contributing:
+
+- New page/business logic starts as a composable in `src/vue/` (or, if
+  framework-free, in `src/client/`); the `.vue` file renders it.
+- Quasar imports in `.ts` files are only allowed under `src/quasar/`.
+- A few framework-free type/i18n modules stay co-located with their SFCs
+  (`components/dialogs/types.ts`, `components/bundle-editor/catalog-i18n.ts`,
+  `pages-standard/platform-email.types.ts`,
+  `pages-standard/email-history.types.ts`, `pages-tenant/default-i18n.ts`)
+  and are whitelisted in the ESLint rules — they must not grow framework
+  imports.
+
+### Notify port
+
+Standard pages emit toasts through a single seam instead of calling
+`$q.notify` directly: the `UiNotify` port (`SUPER_ADMIN_NOTIFY_KEY`).
+`createSuperAdminApp()` provides a Quasar-backed default; apps with their
+own notification center override it:
+
+```ts
+createSuperAdminApp({
+    // ...
+    notify: (kind, message, options) => myToasts.push({ kind, message, ...options }),
+});
+```
+
+Confirm dialogs inside the reference pages intentionally keep using Quasar's
+`Dialog` — the pages *are* the Quasar layer.
 
 ## Usage
 
@@ -15,7 +58,7 @@ pnpm add @saasicat/ui-vue
 ```
 
 ```ts
-import { createSuperAdminApp } from '@saasicat/ui-vue';
+import { createSuperAdminApp } from '@saasicat/ui-vue/quasar';
 import App from './App.vue';
 import { routes } from './router/routes';
 
@@ -43,5 +86,5 @@ and the [handbook](https://github.com/uelker70/saasicat/blob/main/docs/handbook.
 pnpm --filter @saasicat/ui-vue build
 ```
 
-Produces `dist/index.{js,cjs,d.ts}` via tsup; `vue`, `vue-router`, `pinia`
-and `quasar` stay external.
+Produces `dist/{index,client/index,quasar/index}.{js,cjs,d.ts}` via tsup
+(`tsup.config.ts`); `vue`, `vue-router`, `pinia` and `quasar` stay external.

package/dist/action-registry-CQ2wL3R-.d.cts

@@ -0,0 +1,85 @@
+import { AdminManifest, TenantActionDef } from '@saasicat/types';
+
+/**
+ * Minimal abstraction over `fetch`. Consumers may pass their own
+ * implementation (e.g. an axios wrapper that already injects auth headers
+ * and tenant headers).
+ */
+type HttpClient = (url: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}) => Promise<HttpResponse>;
+interface HttpResponse {
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}
+/** Simple persistence adapter; default is `localStorage`. */
+interface KvStore {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+}
+/**
+ * Returns a `KvStore` wrapper around `localStorage` (or `null` under SSR).
+ * Tests may pass an in-memory stub.
+ */
+declare function defaultKvStore(): KvStore;
+/**
+ * Default `HttpClient` over `fetch`. Consumers pass their own variant
+ * through when they need auth headers / tenant headers / retry logic.
+ */
+declare function defaultHttpClient(): HttpClient;
+
+/** Consumer implementation; receives the action inputs as a generic object. */
+type ActionHandler<TInput = unknown, TResult = unknown> = (input: TInput) => Promise<TResult>;
+interface ResolvedAction<TInput = unknown, TResult = unknown> {
+    def: TenantActionDef;
+    handler: ActionHandler<TInput, TResult>;
+}
+declare class MissingHandlerError extends Error {
+    constructor(actionKey: string);
+}
+declare class ActionDefNotInManifestError extends Error {
+    constructor(actionKey: string);
+}
+declare class ActionRegistry {
+    private readonly defs;
+    private readonly handlers;
+    constructor(manifest: AdminManifest, handlers?: Record<string, ActionHandler>);
+    /**
+     * Registers a handler after the fact (e.g. when consumer code loads
+     * lazily). Throws `ActionDefNotInManifestError` if the `actionKey` is not
+     * declared in the manifest — prevents dead registrations.
+     */
+    register<TInput, TResult>(actionKey: string, handler: ActionHandler<TInput, TResult>): void;
+    /**
+     * Returns the `{def, handler}` pair. Throws if the key is missing from
+     * the manifest or no handler is registered. The shell's UI layer calls
+     * the method, checks `def.requiresMfa` / `def.confirmType` for the
+     * pre-flow, and then calls `handler(input)`.
+     */
+    get<TInput = unknown, TResult = unknown>(actionKey: string): ResolvedAction<TInput, TResult>;
+    /**
+     * Convenience: `get(key).handler(input)`. UI convenience for actions
+     * that need neither MFA nor confirm.
+     */
+    dispatch<TInput, TResult>(actionKey: string, input: TInput): Promise<TResult>;
+    /**
+     * List of actionKeys that are declared in the manifest but have no
+     * handler. Consumers use this in a doctor check to detect drift between
+     * the manifest and the shell build.
+     */
+    listOrphanedDefs(): string[];
+    /**
+     * List of registered handlers that are missing from the manifest. Drift
+     * in the other direction.
+     */
+    listOrphanedHandlers(): string[];
+}
+
+export { type ActionHandler as A, type HttpClient as H, type KvStore as K, MissingHandlerError as M, type ResolvedAction as R, ActionRegistry as a, ActionDefNotInManifestError as b, type HttpResponse as c, defaultHttpClient as d, defaultKvStore as e };

package/dist/action-registry-CQ2wL3R-.d.ts

@@ -0,0 +1,85 @@
+import { AdminManifest, TenantActionDef } from '@saasicat/types';
+
+/**
+ * Minimal abstraction over `fetch`. Consumers may pass their own
+ * implementation (e.g. an axios wrapper that already injects auth headers
+ * and tenant headers).
+ */
+type HttpClient = (url: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}) => Promise<HttpResponse>;
+interface HttpResponse {
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}
+/** Simple persistence adapter; default is `localStorage`. */
+interface KvStore {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+}
+/**
+ * Returns a `KvStore` wrapper around `localStorage` (or `null` under SSR).
+ * Tests may pass an in-memory stub.
+ */
+declare function defaultKvStore(): KvStore;
+/**
+ * Default `HttpClient` over `fetch`. Consumers pass their own variant
+ * through when they need auth headers / tenant headers / retry logic.
+ */
+declare function defaultHttpClient(): HttpClient;
+
+/** Consumer implementation; receives the action inputs as a generic object. */
+type ActionHandler<TInput = unknown, TResult = unknown> = (input: TInput) => Promise<TResult>;
+interface ResolvedAction<TInput = unknown, TResult = unknown> {
+    def: TenantActionDef;
+    handler: ActionHandler<TInput, TResult>;
+}
+declare class MissingHandlerError extends Error {
+    constructor(actionKey: string);
+}
+declare class ActionDefNotInManifestError extends Error {
+    constructor(actionKey: string);
+}
+declare class ActionRegistry {
+    private readonly defs;
+    private readonly handlers;
+    constructor(manifest: AdminManifest, handlers?: Record<string, ActionHandler>);
+    /**
+     * Registers a handler after the fact (e.g. when consumer code loads
+     * lazily). Throws `ActionDefNotInManifestError` if the `actionKey` is not
+     * declared in the manifest — prevents dead registrations.
+     */
+    register<TInput, TResult>(actionKey: string, handler: ActionHandler<TInput, TResult>): void;
+    /**
+     * Returns the `{def, handler}` pair. Throws if the key is missing from
+     * the manifest or no handler is registered. The shell's UI layer calls
+     * the method, checks `def.requiresMfa` / `def.confirmType` for the
+     * pre-flow, and then calls `handler(input)`.
+     */
+    get<TInput = unknown, TResult = unknown>(actionKey: string): ResolvedAction<TInput, TResult>;
+    /**
+     * Convenience: `get(key).handler(input)`. UI convenience for actions
+     * that need neither MFA nor confirm.
+     */
+    dispatch<TInput, TResult>(actionKey: string, input: TInput): Promise<TResult>;
+    /**
+     * List of actionKeys that are declared in the manifest but have no
+     * handler. Consumers use this in a doctor check to detect drift between
+     * the manifest and the shell build.
+     */
+    listOrphanedDefs(): string[];
+    /**
+     * List of registered handlers that are missing from the manifest. Drift
+     * in the other direction.
+     */
+    listOrphanedHandlers(): string[];
+}
+
+export { type ActionHandler as A, type HttpClient as H, type KvStore as K, MissingHandlerError as M, type ResolvedAction as R, ActionRegistry as a, ActionDefNotInManifestError as b, type HttpResponse as c, defaultHttpClient as d, defaultKvStore as e };

package/dist/chunk-3YP2ZAOD.js

@@ -0,0 +1,63 @@
+// src/vue/super-admin-context.ts
+var SUPER_ADMIN_BRAND_KEY = /* @__PURE__ */ Symbol.for(
+  "@saasicat/ui-vue/SUPER_ADMIN_BRAND"
+);
+var SUPER_ADMIN_ENDPOINTS_KEY = /* @__PURE__ */ Symbol.for(
+  "@saasicat/ui-vue/SUPER_ADMIN_ENDPOINTS"
+);
+var SUPER_ADMIN_EXTENSIONS_KEY = /* @__PURE__ */ Symbol.for(
+  "@saasicat/ui-vue/SUPER_ADMIN_EXTENSIONS"
+);
+var SUPER_ADMIN_ACTIONS_KEY = /* @__PURE__ */ Symbol.for(
+  "@saasicat/ui-vue/SUPER_ADMIN_ACTIONS"
+);
+var SUPER_ADMIN_MANIFEST_KEY = /* @__PURE__ */ Symbol.for(
+  "@saasicat/ui-vue/SUPER_ADMIN_MANIFEST"
+);
+var SUPER_ADMIN_LOGIN_ADAPTER_KEY = /* @__PURE__ */ Symbol.for(
+  "@saasicat/ui-vue/SUPER_ADMIN_LOGIN_ADAPTER"
+);
+var SUPER_ADMIN_HTTP_KEY = /* @__PURE__ */ Symbol.for(
+  "@saasicat/ui-vue/SUPER_ADMIN_HTTP"
+);
+function buildNavigationGuard(options) {
+  const { authGuard, manifestGuard } = options;
+  if (!authGuard && !manifestGuard) return null;
+  return async (to) => {
+    if (to.meta?.public === true) return true;
+    if (authGuard) {
+      if (!authGuard.isAuthenticated()) return authGuard.onUnauthenticated();
+      if (authGuard.isSuperAdmin && !authGuard.isSuperAdmin()) {
+        return authGuard.onUnauthenticated();
+      }
+    }
+    if (manifestGuard) {
+      try {
+        await manifestGuard.ensureLoaded();
+      } catch (err) {
+        if (manifestGuard.errorRoute && to.path !== manifestGuard.errorRoute) {
+          return manifestGuard.errorRoute;
+        }
+        console.error("[SuperAdmin] manifest load failed", err);
+      }
+    }
+    return true;
+  };
+}
+
+// src/vue/ui-notify.ts
+var SUPER_ADMIN_NOTIFY_KEY = /* @__PURE__ */ Symbol.for(
+  "@saasicat/ui-vue/SUPER_ADMIN_NOTIFY"
+);
+
+export {
+  SUPER_ADMIN_BRAND_KEY,
+  SUPER_ADMIN_ENDPOINTS_KEY,
+  SUPER_ADMIN_EXTENSIONS_KEY,
+  SUPER_ADMIN_ACTIONS_KEY,
+  SUPER_ADMIN_MANIFEST_KEY,
+  SUPER_ADMIN_LOGIN_ADAPTER_KEY,
+  SUPER_ADMIN_HTTP_KEY,
+  buildNavigationGuard,
+  SUPER_ADMIN_NOTIFY_KEY
+};