@saasicat/ui-vue 0.24.2 → 0.26.0

package/dist/{use-sa-theme-B5t7oXph.d.cts → resource-registry-TaR7rtq0.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 SaLocaleOption, c as SaLocaleDefinition, d as SaMessagesOverrides, K as KvStore } from './catalog-DJcfm5N2.cjs';
+import { A as ActionHandler, H as HttpClient, S as SaLocale, a as SaMessages, b as SaLocaleOption, c as SaLocaleDefinition, d as SaMessagesOverrides, K as KvStore, R as ResourceDef, e as ResourceOps, f as ResourceContext, B as Bound, P as PlatformResources } from './catalog-Dch1Ryw0.js';
 
 /**
  * App-specific branding data that the platform `AdminLayout` and other
@@ -26,6 +26,21 @@ interface SuperAdminEndpoints {
     publicBootEndpoint?: string;
     /** Post-login full-manifest endpoint, default `${apiBase}/manifest`. */
     manifestEndpoint?: string;
+    /**
+     * The project whose catalogue this admin administers.
+     *
+     * App-wide and constant, which is why it belongs here. Today each page
+     * takes it as a prop and each consumer passes it again per route — the
+     * same value, written out once per page, with nothing keeping the copies
+     * in step.
+     *
+     * Optional in the type, but required in practice for an app that also
+     * passes `http`: that app gets the resource registry, the registry holds
+     * the plan catalogue, and binding a project-scoped resource without a
+     * project is refused at boot rather than sent as `?projectKey=`. An app
+     * that names no client gets no registry and needs no project.
+     */
+    projectKey?: string;
 }
 type ExtensionLoader = () => Promise<Component | {
     default: Component;
@@ -127,11 +142,11 @@ interface SuperAdminManifestGuardOptions {
      * Discards the cached manifest, so the next `ensureLoaded()` fetches a
      * fresh body instead of revalidating.
      *
-     * Needed because the loader keeps an ETag in storage. Its own documented
-     * failure — "server returned 304 but the cache body is missing" — survives
-     * a full page reload: the next request sends the same `If-None-Match`,
-     * gets another 304, and lands back on the error page. Retry is a dead end
-     * for that case unless something clears the ETag first.
+     * Needed because the loader keeps an ETag in storage, which a full page
+     * reload does not touch. A plain retry therefore sends `If-None-Match`,
+     * and a 304 hands back the very manifest the app already had — so an
+     * operator retrying after a deployment would keep looking at the old one.
+     * Clearing first is what makes the retry ask an open question.
      *
      * `ManifestLoader.clearCache()` and the manifest store's reset both fit;
      * pass whichever the app uses.
@@ -202,6 +217,53 @@ type UiNotify = (kind: UiNotifyKind, message: string, options?: UiNotifyOptions)
 /** Vue inject key for the notify port (see `Symbol.for` note in super-admin-context.ts). */
 declare const SUPER_ADMIN_NOTIFY_KEY: InjectionKey<UiNotify>;
 
+/**
+ * How the confirming button is coloured. `negative` marks an action that
+ * destroys or revokes something; `primary` marks one that does not.
+ */
+type UiConfirmTone = 'primary' | 'negative';
+/** Asks for a value along with the confirmation. */
+interface UiConfirmPrompt {
+    /** Pre-filled value, e.g. the date a pilot currently ends on. */
+    initial?: string;
+    /** Input kind. Only the two the standard pages need. */
+    type?: 'text' | 'date';
+}
+interface UiConfirmRequest {
+    /** What is about to happen, naming the subject. */
+    title: string;
+    /**
+     * The consequence, in a sentence. For an action that cannot be reversed,
+     * say so here rather than asking "are you sure".
+     */
+    message: string;
+    /** Label of the confirming button — a verb, not "OK". */
+    confirmLabel: string;
+    /** Label of the dismissing button. */
+    cancelLabel: string;
+    /** Default `primary`. Destructive actions pass `negative`. */
+    tone?: UiConfirmTone;
+    /** When set, the operator is asked for a value as well. */
+    prompt?: UiConfirmPrompt;
+}
+interface UiConfirmResult {
+    /** Whether the operator confirmed. Dismissing counts as `false`. */
+    ok: boolean;
+    /**
+     * What the operator entered, when the request carried a `prompt`.
+     * `undefined` otherwise, and whenever `ok` is `false`.
+     */
+    value?: string;
+}
+/**
+ * Confirm port. Resolves once the operator has answered — an implementation
+ * that resolves `{ ok: true }` without asking would turn every guarded action
+ * into an unguarded one, so there is no such default.
+ */
+type UiConfirm = (request: UiConfirmRequest) => Promise<UiConfirmResult>;
+/** Vue inject key for the confirm port (see `Symbol.for` note in super-admin-context.ts). */
+declare const SUPER_ADMIN_CONFIRM_KEY: InjectionKey<UiConfirm>;
+
 interface SuperAdminI18n {
     /** Active UI locale — mutable; switching re-renders all catalog texts. */
     locale: Ref<SaLocale>;
@@ -282,11 +344,21 @@ declare function useSaMessages<K extends keyof SaMessages>(namespace: K): Comput
 
 type SaColorScheme = 'light' | 'dark' | 'system';
 type SaResolvedScheme = 'light' | 'dark';
+/** The schemes the switcher offers, in the order it lists them. */
+declare const SA_COLOR_SCHEMES: readonly SaColorScheme[];
+/** `KvStore` key holding the scheme the operator picked in the switcher. */
+declare const SA_THEME_STORAGE_KEY = "saasicat.theme.scheme";
 interface SaTheme {
     /** What the operator picked. Writable — assigning switches the theme. */
     scheme: Ref<SaColorScheme>;
     /** What that means right now: `'system'` resolved against the OS. */
     resolved: ComputedRef<SaResolvedScheme>;
+    /**
+     * Whether the shell renders its theme switcher. `false` when the app opted
+     * out or when `scheme` cannot be written to — a switcher that cannot change
+     * anything is worse than none.
+     */
+    switcherEnabled: boolean;
     /**
      * Releases the `prefers-color-scheme` subscription and the persistence
      * watcher. Idempotent.
@@ -312,6 +384,18 @@ interface SaThemeOptions {
     persist?: boolean;
     /** Injection seam for tests. */
     storage?: KvStore;
+    /**
+     * Prefix for the persisted key, mirroring `createSuperAdminI18n`. Set it
+     * when several admin apps share one origin and must not inherit each
+     * other's colour scheme.
+     */
+    storageKeyPrefix?: string;
+    /**
+     * Renders the theme switcher in the shell chrome, default `true`. Set
+     * `false` for a deployment that ships one appearance. A readonly `scheme`
+     * ref disables it on its own — no need to set this as well.
+     */
+    switcher?: boolean;
 }
 /**
  * Creates the theme context. `createSuperAdminApp()` makes one and the Quasar
@@ -330,4 +414,70 @@ declare const SA_THEME_KEY: InjectionKey<SaTheme>;
  */
 declare function useSaTheme(): SaTheme;
 
-export { type ActionsMap as A, type UiNotifyOptions as B, buildNavigationGuard as C, createSaTheme as D, type ExtensionsMap as E, createSuperAdminI18n as F, useSaMessages as G, useSaTheme as H, type InstallPlugin as I, useSuperAdminI18n as J, 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 SaThemeOptions as e, type SuperAdminI18n as f, type SaTheme as g, type ExtensionLoader as h, SA_LOCALE_STORAGE_KEY as i, SA_THEME_KEY as j, SUPER_ADMIN_ACTIONS_KEY as k, SUPER_ADMIN_BRAND_KEY as l, SUPER_ADMIN_ENDPOINTS_KEY as m, SUPER_ADMIN_EXTENSIONS_KEY as n, SUPER_ADMIN_HTTP_KEY as o, SUPER_ADMIN_I18N_KEY as p, SUPER_ADMIN_LOGIN_ADAPTER_KEY as q, SUPER_ADMIN_MANIFEST_CLEAR_CACHE_KEY as r, SUPER_ADMIN_MANIFEST_KEY as s, SUPER_ADMIN_NOTIFY_KEY as t, type SaColorScheme as u, type SaResolvedScheme as v, type SuperAdminAuthGuardOptions as w, type SuperAdminLoginResult as x, type SuperAdminManifestGuardOptions as y, type UiNotifyKind as z };
+/**
+ * An override receives the platform's own implementation as `next`, so it
+ * wraps rather than replaces. Recording an approval before a publish is three
+ * lines; rewriting the publish is not.
+ */
+type OpOverride<TOp> = TOp extends (http: HttpClient, ctx: ResourceContext, ...args: infer A) => Promise<infer R> ? (next: (...args: A) => Promise<R>, ...args: A) => Promise<R> : never;
+interface ResourceOverride<TOps extends ResourceOps> {
+    /** Only the endpoint, project or locale this resource is read under. */
+    context?: Partial<ResourceContext>;
+    /** Only the transport, e.g. a client with a different auth. */
+    http?: HttpClient;
+    /** Individual operations, each wrapping the platform's. */
+    ops?: {
+        [K in keyof TOps]?: OpOverride<TOps[K]>;
+    };
+}
+/** Resources by key, in the shape a registry holds them. */
+type ResourceMap = Record<string, ResourceDef<ResourceOps>>;
+type ResourceOverrides<TMap extends ResourceMap> = {
+    [K in keyof TMap]?: ResourceOverride<TMap[K]['ops']>;
+};
+interface ResourceRegistry<TMap extends ResourceMap = ResourceMap> {
+    /** The bound operations of one resource. Throws for an unknown key. */
+    get<K extends keyof TMap>(key: K): Bound<TMap[K]['ops']>;
+    /** Every key the registry can answer for. */
+    keys(): string[];
+}
+interface CreateResourceRegistryOptions<TMap extends ResourceMap> {
+    /**
+     * Required — there is deliberately no fallback.
+     *
+     * A registry that quietly reached for `fetch` when nobody passed a client
+     * would send every request without the app's `Authorization` header, and
+     * the failure is silent: the call 401s, one card renders an em dash, and
+     * nothing is logged. Three such call sites existed in this package and had
+     * to be found by reading. Asking for the client makes them unwritable.
+     */
+    http: HttpClient;
+    /** Read per call, so a switched locale or project applies to what follows. */
+    context: ResourceContext | (() => ResourceContext);
+    /** The resources on offer. */
+    resources: TMap;
+    /** Per-resource adjustments from the app. */
+    overrides?: ResourceOverrides<TMap>;
+}
+declare function createResourceRegistry<TMap extends ResourceMap>(options: CreateResourceRegistryOptions<TMap>): ResourceRegistry<TMap>;
+/** Vue inject key for the registry (see `Symbol.for` note in super-admin-context.ts). */
+declare const SUPER_ADMIN_RESOURCES_KEY: InjectionKey<ResourceRegistry>;
+/**
+ * The operations of one resource, ready to call.
+ *
+ * Typed against the platform roster, so `useResource('plans').update(id, data)`
+ * carries the argument types the descriptor declares and an unknown key is a
+ * compile error. Without that mapping the key parameter erased the operations
+ * to `ResourceOps`, whose `never[]` constraint made *every* call with an
+ * argument a type error while accepting any misspelled resource name — the
+ * exact opposite of the guarantee the registry exists for.
+ *
+ * An app with its own resources passes its map as the second type argument.
+ *
+ * Throws when the shell has no registry rather than returning something
+ * inert — a page whose data silently never arrives is harder to diagnose than
+ * one that says what is missing.
+ */
+declare function useResource<K extends keyof TMap & string, TMap extends ResourceMap = PlatformResources>(key: K): Bound<TMap[K]['ops']>;
+
+export { useSaTheme as $, type ActionsMap as A, SUPER_ADMIN_MANIFEST_KEY as B, type CreateResourceRegistryOptions as C, SUPER_ADMIN_NOTIFY_KEY as D, type ExtensionsMap as E, SUPER_ADMIN_RESOURCES_KEY as F, type SaColorScheme as G, type SaResolvedScheme as H, type InstallPlugin as I, type SuperAdminAuthGuardOptions as J, type SuperAdminLoginResult as K, type SuperAdminManifestGuardOptions as L, type UiConfirmPrompt as M, type UiConfirmResult as N, type OpOverride as O, type UiConfirmTone as P, type UiNotifyKind as Q, type ResourceOverrides as R, type SuperAdminGuardOptions as S, type UiNotifyOptions as T, type UiNotify as U, buildNavigationGuard as V, createResourceRegistry as W, createSaTheme as X, createSuperAdminI18n as Y, useResource as Z, useSaMessages as _, type SuperAdminBrand as a, useSuperAdminI18n as a0, type SuperAdminEndpoints as b, type SuperAdminLoginAdapter as c, type UiConfirm as d, type SuperAdminI18nOptions as e, type SaThemeOptions as f, type SuperAdminI18n as g, type SaTheme as h, type UiConfirmRequest as i, type ResourceMap as j, type ExtensionLoader as k, type ResourceOverride as l, type ResourceRegistry as m, SA_COLOR_SCHEMES as n, SA_LOCALE_STORAGE_KEY as o, SA_THEME_KEY as p, SA_THEME_STORAGE_KEY as q, SUPER_ADMIN_ACTIONS_KEY as r, SUPER_ADMIN_BRAND_KEY as s, SUPER_ADMIN_CONFIRM_KEY as t, SUPER_ADMIN_ENDPOINTS_KEY as u, SUPER_ADMIN_EXTENSIONS_KEY as v, SUPER_ADMIN_HTTP_KEY as w, SUPER_ADMIN_I18N_KEY as x, SUPER_ADMIN_LOGIN_ADAPTER_KEY as y, SUPER_ADMIN_MANIFEST_CLEAR_CACHE_KEY as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saasicat/ui-vue",
-  "version": "0.24.2",
+  "version": "0.26.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",
@@ -61,7 +61,7 @@
     "src"
   ],
   "dependencies": {
-    "@saasicat/types": "^0.24.2"
+    "@saasicat/types": "^0.26.0"
   },
   "peerDependencies": {
     "pinia": "^2.0.0 || ^3.0.0",
@@ -86,6 +86,7 @@
     "@types/node": "^25.6.0",
     "@vitejs/plugin-vue": "^6.0.8",
     "@vue/test-utils": "^2.4.11",
+    "axios": "^1.15.0",
     "jsdom": "^30.0.1",
     "pinia": "^3.0.0",
     "quasar": "^2.24.0",
@@ -113,7 +114,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsup",
+    "build": "node ../../scripts/build-and-prune.mjs tsup",
     "typecheck": "vue-tsc --noEmit -p tsconfig.json && vue-tsc --noEmit -p tsconfig.tests.json",
     "pretest": "pnpm run build",
     "test": "node --test tests/**/*.test.js",