@saasicat/ui-vue 0.19.0 → 0.22.0

package/src/pages-standard/tenant-detail/TenantMasterData.vue

@@ -0,0 +1,28 @@
+<template>
+    <div class="sa-kv-grid">
+        <KvBlock :label="labels.plan" :value="data.subscription?.plan ?? EMPTY" />
+        <KvBlock :label="labels.status" :value="data.subscription?.status ?? EMPTY" />
+        <KvBlock :label="labels.pilot" :value="data.subscription?.isPilot ? yes : no" />
+        <KvBlock :label="labels.trialEnd" :value="formatDate(data.subscription?.trialEndsAt)" />
+        <KvBlock :label="labels.pilotEnd" :value="formatDate(data.subscription?.pilotEndsAt)" />
+        <KvBlock v-if="data.vatId" :label="labels.vatId" :value="data.vatId" />
+        <slot />
+    </div>
+</template>
+
+<script setup lang="ts">
+import KvBlock from '../../components/KvBlock.vue';
+import type { TenantDetailData, TenantMasterDataLabels } from './types.js';
+
+// The subscription facts of a tenant. Pure presentation: the page resolves the
+// labels and the date format, so this block has no i18n and no data access.
+defineProps<{
+    data: TenantDetailData;
+    labels: TenantMasterDataLabels;
+    formatDate: (value: string | null | undefined) => string;
+    yes: string;
+    no: string;
+}>();
+
+const EMPTY = '—';
+</script>

package/src/pages-standard/tenant-detail/TenantUsage.vue

@@ -0,0 +1,31 @@
+<template>
+    <div class="sa-kv-grid">
+        <KvBlock
+            v-for="(field, i) in fields"
+            :key="field.label + i"
+            :label="field.label"
+            :value="resolve(field)"
+        />
+    </div>
+</template>
+
+<script setup lang="ts">
+import KvBlock from '../../components/KvBlock.vue';
+import type { TenantDetailData, VerbrauchField } from './types.js';
+
+// Usage counters. A field either names a key in `data.counts` or brings its own
+// getter, so a consumer can surface a number the platform knows nothing about.
+const props = defineProps<{
+    data: TenantDetailData;
+    fields: readonly VerbrauchField[];
+}>();
+
+const EMPTY = '—';
+
+function resolve(field: VerbrauchField): string {
+    if (field.getter) return String(field.getter(props.data));
+    if (!field.key) return EMPTY;
+    const value = props.data.counts?.[field.key];
+    return value === undefined || value === null ? '0' : String(value);
+}
+</script>

package/src/pages-standard/tenant-detail/TenantUsers.vue

@@ -0,0 +1,15 @@
+<template>
+    <AdminTable :rows="users" :columns="columns" storage-key="tenant-users" />
+</template>
+
+<script setup lang="ts">
+import AdminTable from '../../components/admin-page/AdminTable.vue';
+import type { QTableColumn } from 'quasar';
+
+// The tenant's users. The column set comes from the page, which falls back to
+// the platform default when the consumer supplies none.
+defineProps<{
+    users: Array<Record<string, unknown> & { id: string }>;
+    columns: QTableColumn[];
+}>();
+</script>

package/src/pages-standard/tenant-detail/types.ts

@@ -0,0 +1,38 @@
+export interface TenantDetailData {
+    id: string;
+    slug: string;
+    name: string;
+    isActive: boolean;
+    vatId?: string | null;
+    subscription?: {
+        plan?: string | null;
+        status?: string | null;
+        isPilot?: boolean | null;
+        trialEndsAt?: string | null;
+        pilotEndsAt?: string | null;
+    } | null;
+    users?: Array<Record<string, unknown> & { id: string }>;
+    /** Freely selectable usage numbers — the page renders them via `verbrauchFields`. */
+    counts?: Record<string, number | string>;
+}
+
+export interface VerbrauchField {
+    label: string;
+    /** Lookup key in `data.counts`. */
+    key?: string;
+    /** Alternative: custom getter. Takes precedence over `key`. */
+    getter?: (data: TenantDetailData) => string | number;
+}
+
+/**
+ * The resolved labels for the master-data block. The page owns the i18n
+ * lookup and the per-label prop overrides; the block only renders them.
+ */
+export interface TenantMasterDataLabels {
+    plan: string;
+    status: string;
+    pilot: string;
+    trialEnd: string;
+    pilotEnd: string;
+    vatId: string;
+}

package/src/pages-standard/tenants/StatusPill.vue

@@ -48,8 +48,8 @@ defineProps<{
     color: var(--sa-negative, #dc2626);
 }
 .sa-pill--muted {
-    background: #f1f5f9;
-    color: var(--sa-muted, #64748b);
+    background: var(--sa-border-soft);
+    color: var(--sa-muted, var(--sa-muted));
 }
 .sa-pill--primary {
     background: var(--sa-primary-soft, rgba(63, 107, 255, 0.08));

package/src/pages-tenant/MySubscriptionBundlesPage.vue

@@ -400,7 +400,7 @@ function formatDate(date: Date | string | null | undefined): string {
         BlinkMacSystemFont,
         system-ui,
         sans-serif;
-    color: #0f172a;
+    color: var(--sa-heading);
 }
 .msb-head {
     display: flex;
@@ -416,7 +416,7 @@ function formatDate(date: Date | string | null | undefined): string {
 }
 .msb-sub {
     margin: 4px 0 0;
-    color: #64748b;
+    color: var(--sa-muted);
     font-size: 13px;
     max-width: 580px;
     line-height: 1.5;
@@ -424,7 +424,7 @@ function formatDate(date: Date | string | null | undefined): string {
 .msb-loading {
     padding: 32px;
     text-align: center;
-    color: #64748b;
+    color: var(--sa-muted);
 }
 .msb-empty {
     padding: 32px 24px;
@@ -432,12 +432,12 @@ function formatDate(date: Date | string | null | undefined): string {
     background: #fff;
     border: 1px dashed #cbd5e1;
     border-radius: 12px;
-    color: #475569;
+    color: var(--sa-muted-dark);
 }
 .msb-empty-link {
     background: transparent;
     border: 0;
-    color: #2563eb;
+    color: var(--sa-primary);
     cursor: pointer;
     font: inherit;
     text-decoration: underline;
@@ -457,13 +457,13 @@ function formatDate(date: Date | string | null | undefined): string {
 }
 .msb-card {
     background: #fff;
-    border: 1px solid #e2e8f0;
+    border: 1px solid var(--sa-border);
     border-radius: 12px;
     padding: 14px 18px;
 }
 .msb-card--canceled-pending {
     border-color: #fde68a;
-    background: #fffbeb;
+    background: var(--sa-warning-bg);
 }
 .msb-card--canceled {
     opacity: 0.65;
@@ -490,7 +490,7 @@ function formatDate(date: Date | string | null | undefined): string {
 .msb-card-meta {
     margin-top: 4px;
     font-size: 12.5px;
-    color: #64748b;
+    color: var(--sa-muted);
 }
 .msb-chip {
     font-size: 10.5px;
@@ -509,13 +509,13 @@ function formatDate(date: Date | string | null | undefined): string {
     color: #92400e;
 }
 .msb-chip--canceled {
-    background: #e2e8f0;
-    color: #475569;
+    background: var(--sa-border);
+    color: var(--sa-muted-dark);
 }
 .msb-cancel-info {
     margin-top: 10px;
     padding: 8px 12px;
-    background: #fffbeb;
+    background: var(--sa-warning-bg);
     border: 1px solid #fde68a;
     border-radius: 6px;
     color: #92400e;
@@ -533,22 +533,22 @@ function formatDate(date: Date | string | null | undefined): string {
     cursor: pointer;
     font-family: inherit;
     font-size: 13px;
-    color: #0f172a;
+    color: var(--sa-heading);
 }
 .msb-btn:hover:not(:disabled) {
-    background: #f8fafc;
+    background: var(--sa-bg-surface-2);
 }
 .msb-btn:disabled {
     cursor: not-allowed;
     opacity: 0.55;
 }
 .msb-btn--primary {
-    background: #2563eb;
-    border-color: #2563eb;
+    background: var(--sa-primary);
+    border-color: var(--sa-primary);
     color: #fff;
 }
 .msb-btn--primary:hover:not(:disabled) {
-    background: #1d4ed8;
+    background: var(--sa-primary-strong);
 }
 .msb-btn--ghost {
     background: transparent;
@@ -580,7 +580,7 @@ function formatDate(date: Date | string | null | undefined): string {
     align-items: center;
     justify-content: space-between;
     padding: 16px 20px 10px;
-    border-bottom: 1px solid #e2e8f0;
+    border-bottom: 1px solid var(--sa-border);
 }
 .msb-modal-title {
     font-size: 16px;
@@ -590,13 +590,13 @@ function formatDate(date: Date | string | null | undefined): string {
     background: transparent;
     border: 0;
     cursor: pointer;
-    color: #64748b;
+    color: var(--sa-muted);
     padding: 4px;
     border-radius: 4px;
 }
 .msb-modal-x:hover {
-    background: #f1f5f9;
-    color: #0f172a;
+    background: var(--sa-border-soft);
+    color: var(--sa-heading);
 }
 .msb-modal-body {
     padding: 16px 20px;
@@ -606,8 +606,8 @@ function formatDate(date: Date | string | null | undefined): string {
 }
 .msb-modal-foot {
     padding: 12px 20px;
-    border-top: 1px solid #e2e8f0;
-    background: #f8fafc;
+    border-top: 1px solid var(--sa-border);
+    background: var(--sa-bg-surface-2);
     border-radius: 0 0 12px 12px;
     display: flex;
     justify-content: flex-end;
@@ -621,11 +621,11 @@ function formatDate(date: Date | string | null | undefined): string {
 .msb-field-label {
     font-size: 12px;
     font-weight: 600;
-    color: #475569;
+    color: var(--sa-muted-dark);
 }
 .msb-field-hint {
     font-size: 11px;
-    color: #94a3b8;
+    color: var(--sa-muted-light);
 }
 .msb-input {
     padding: 7px 10px;
@@ -633,7 +633,7 @@ function formatDate(date: Date | string | null | undefined): string {
     border-radius: 6px;
     font-family: inherit;
     font-size: 13px;
-    color: #0f172a;
+    color: var(--sa-heading);
     background: #fff;
 }
 </style>

package/src/pages-tenant/OnboardingConfigurator.vue

@@ -100,11 +100,7 @@ import PlanGrid from '../components/plan/PlanGrid.vue';
 import PublicBundleGrid from '../components/plan/PublicBundleGrid.vue';
 import PromoCodeInput from '../components/plan/PromoCodeInput.vue';
 import PriceSummary from '../components/plan/PriceSummary.vue';
-import {
-    useSubscriptionDraft,
-    type PromoState,
-    type SubscriptionDraft,
-} from '../vue/use-subscription-draft.js';
+import { useSubscriptionDraft, type SubscriptionDraft } from '../vue/use-subscription-draft.js';
 import type { CatalogPlan } from '../vue/use-tenant-billing-catalog.js';
 import type { BillingCycleStr } from '../vue/use-tenant-billing.js';
 import type {

package/src/pages-tenant/PackageSnapshotPanel.vue

@@ -108,7 +108,7 @@ import { computed, ref } from 'vue';
 import type { PackageSnapshotShape } from '../vue/use-tenant-billing.js';
 import type { TenantPlanSectionI18n } from './default-i18n.js';
 
-// PackageSnapshotPanel — P11.4 (METAMODELL §17a):
+// PackageSnapshotPanel — P11.4:
 // Read-only display of `Subscription.packageSnapshot`. Shows the
 // tenant the frozen website offer (offer snapshot) — plan,
 // bundles, prices, capture timestamp. No actions, no diff against

package/src/pages-tenant/TenantPlanSection.vue

@@ -64,8 +64,8 @@
                     :usage="usage"
                     :i18n="effectiveI18n"
                     :catalog-quota-keys="catalogQuotaKeys"
-                    :quota-label="quotaLabel"
-                    :is-fractional-quota="isFractionalQuota"
+                    :quota-label="quotaLabelResolved"
+                    :is-fractional-quota="isFractionalQuotaResolved"
                     :usage-bar-formatter="usageBarFormatter"
                 />
 
@@ -179,11 +179,11 @@
                 :catalog-quota-keys="catalogQuotaKeys"
                 :format-currency="formatCurrency"
                 :format-date="formatDate"
-                :format-quota-label="formatQuotaLabel"
+                :format-quota-label="formatQuotaLabelResolved"
                 :format-quota-value="formatQuotaValue"
-                :quota-label="quotaLabel"
+                :quota-label="quotaLabelResolved"
                 :feature-label="featureLabelResolved"
-                :is-fractional-quota="isFractionalQuota"
+                :is-fractional-quota="isFractionalQuotaResolved"
                 :preview-plan-change="previewPlanChange"
                 :change-plan="changePlan"
                 :i18n="wizardI18n"
@@ -478,30 +478,22 @@ const wizardI18n = computed(() => ({
 }));
 
 // Helper hooks with defaults
-function quotaLabel(key: string): string {
+function quotaLabelResolved(key: string): string {
     return props.quotaLabel?.(key) ?? key;
 }
 
-function featureLabel(key: string): string {
+function featureLabelFromProps(key: string): string {
     return props.featureLabel?.(key) ?? key;
 }
 
-function isFractionalQuota(key: string): boolean {
+function isFractionalQuotaResolved(key: string): boolean {
     return props.isFractionalQuota?.(key) ?? key.toLowerCase().includes('storage');
 }
 
-function formatDate(input: string | Date): string {
-    return props.formatDate(input);
-}
-
-function formatCurrency(n: number): string {
-    return props.formatCurrency(n);
-}
-
-function formatQuotaLabel(key: string, value: number): string {
+function formatQuotaLabelResolved(key: string, value: number): string {
     if (props.formatQuotaLabel) return props.formatQuotaLabel(key, value);
-    if (value === -1) return `${quotaLabel(key)}: ∞`;
-    return `${value} ${quotaLabel(key)}`;
+    if (value === -1) return `${quotaLabelResolved(key)}: ∞`;
+    return `${value} ${quotaLabelResolved(key)}`;
 }
 
 function usageBarFormatter(key: string): ((value: number) => string) | undefined {
@@ -596,7 +588,7 @@ async function onConfirmBundlePreview() {
 // Feature label with registry translation (#18): the registry label takes
 // precedence, then the consumer hook, and finally the raw key.
 function featureLabelResolved(key: string): string {
-    return catalog.featureRegistry.value?.[key]?.label ?? featureLabel(key);
+    return catalog.featureRegistry.value?.[key]?.label ?? featureLabelFromProps(key);
 }
 
 // Mutation handlers

package/src/quasar/create-super-admin-app.ts

@@ -32,6 +32,7 @@ import {
     SUPER_ADMIN_EXTENSIONS_KEY,
     SUPER_ADMIN_HTTP_KEY,
     SUPER_ADMIN_LOGIN_ADAPTER_KEY,
+    SUPER_ADMIN_MANIFEST_CLEAR_CACHE_KEY,
     SUPER_ADMIN_MANIFEST_KEY,
     buildNavigationGuard,
     type ActionsMap,
@@ -173,6 +174,9 @@ export function createSuperAdminApp(options: CreateSuperAdminAppOptions): SuperA
     if (options.manifestGuard?.getManifest) {
         app.provide(SUPER_ADMIN_MANIFEST_KEY, options.manifestGuard.getManifest);
     }
+    if (options.manifestGuard?.clearCache) {
+        app.provide(SUPER_ADMIN_MANIFEST_CLEAR_CACHE_KEY, options.manifestGuard.clearCache);
+    }
     if (options.loginAdapter) {
         app.provide(SUPER_ADMIN_LOGIN_ADAPTER_KEY, options.loginAdapter);
     }

package/src/vue/entitlement-provider.ts

@@ -9,7 +9,6 @@
 // resolve to the same identity — analogous to the inject keys in
 // create-super-admin-app.
 //
-// Spec: handoff/superadmin/QUICKSTART_SIMPLIFICATIONS.md §P8.
 
 import { inject, type App, type InjectionKey } from 'vue';
 import type { UseEntitlementResult } from './use-entitlement.js';

package/src/vue/feature-router-guard.ts

@@ -19,7 +19,6 @@
 // { path: '/x',   component: XPage,   meta: { requiresFeature: ['DMS', 'STORAGE_PRO'] } }
 // ```
 //
-// Spec: handoff/superadmin/QUICKSTART_SIMPLIFICATIONS.md §P8.
 
 import type { NavigationGuardWithThis, RouteLocationNormalized } from 'vue-router';
 import type { UseEntitlementResult } from './use-entitlement.js';

package/src/vue/super-admin-context.ts

@@ -79,6 +79,17 @@ export interface SuperAdminLoginAdapter {
      * storage, MFA hops etc.
      */
     login(email: string, password: string): Promise<SuperAdminLoginResult>;
+    /**
+     * Undoes what `login` established — token, session storage, app store.
+     *
+     * Whoever knows how to start a session is the only one who knows how to
+     * end it, so it belongs next to `login` rather than in a second seam. The
+     * platform's own sign-out affordances call it; without it they can only
+     * navigate to `/login`, and an app whose `isAuthenticated()` reads a
+     * surviving token lets the operator straight back in — a sign-out button
+     * that does not sign out.
+     */
+    logout?(): void | Promise<void>;
     /**
      * Target route after a successful login. Default: `/admin/dashboard`
      * (platform convention for the standard pages — apps with a different
@@ -119,6 +130,20 @@ export interface SuperAdminManifestGuardOptions {
      * manifest guard again and produces a redirect loop.
      */
     errorRoute?: string;
+    /**
+     * 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.
+     *
+     * `ManifestLoader.clearCache()` and the manifest store's reset both fit;
+     * pass whichever the app uses.
+     */
+    clearCache?: () => void | Promise<void>;
 }
 
 /**
@@ -170,6 +195,14 @@ export const SUPER_ADMIN_ACTIONS_KEY: InjectionKey<ActionsMap> = Symbol.for(
 export const SUPER_ADMIN_MANIFEST_KEY: InjectionKey<() => AdminManifest | null> = Symbol.for(
     '@saasicat/ui-vue/SUPER_ADMIN_MANIFEST',
 );
+/**
+ * Vue inject key for `manifestGuard.clearCache`.
+ *
+ * The fail-closed error page is route-mounted and gets no props, so the only
+ * way it can reach the app's cache is through the shell.
+ */
+export const SUPER_ADMIN_MANIFEST_CLEAR_CACHE_KEY: InjectionKey<() => void | Promise<void>> =
+    Symbol.for('@saasicat/ui-vue/SUPER_ADMIN_MANIFEST_CLEAR_CACHE');
 /** Vue inject key for `useSuperAdminLoginAdapter()`. */
 export const SUPER_ADMIN_LOGIN_ADAPTER_KEY: InjectionKey<SuperAdminLoginAdapter> = Symbol.for(
     '@saasicat/ui-vue/SUPER_ADMIN_LOGIN_ADAPTER',
@@ -190,14 +223,52 @@ export type InstallPlugin = (app: App) => void;
  * behavior (auth redirect, manifest fail-closed path). Consumers should call
  * `createSuperAdminApp()`, not this helper directly.
  */
+/**
+ * Recognises "your session is gone" among manifest-load failures.
+ *
+ * Structural rather than `instanceof`: the manifest loader lives in the
+ * framework-free client layer, and a consumer store may wrap or re-throw the
+ * error (or use its own loader entirely). What all of them carry is a numeric
+ * `status`.
+ */
+function isUnauthorizedError(err: unknown): boolean {
+    const status = (err as { status?: unknown } | null)?.status;
+    return status === 401 || status === 403;
+}
+
 export function buildNavigationGuard(
     options: SuperAdminGuardOptions,
 ): NavigationGuardWithThis<undefined> | null {
     const { authGuard, manifestGuard } = options;
     if (!authGuard && !manifestGuard) return null;
 
+    // Set when a manifest 401/403 already sent the user to `onUnauthenticated()`.
+    // Cleared as soon as any navigation gets through, so a later expiry is
+    // handled again — see the loop note below.
+    let redirectedForUnauthorized = false;
+    // ...and whether they actually got there.
+    //
+    // This is the question the budget is really asking: has the operator had a
+    // chance to log in since we sent them away? Concurrent navigations have
+    // not, so they belong to the same episode and follow the first one to
+    // login rather than spending a second attempt.
+    //
+    // Deliberately NOT an identity comparison on the rejection or on the
+    // promise `ensureLoaded()` returned. Both were tried and both are
+    // implementation artefacts a valid consumer can change: a store may cache
+    // one `Error` and rethrow it, and `async () => { await store.ensure(); }`
+    // wraps one shared request in a fresh promise per call. The contract
+    // promises `Promise<void>`, nothing more. A navigation to a public route,
+    // by contrast, is something this guard observes directly.
+    let reachedLoginAfterRedirect = false;
+
     return async (to: RouteLocationNormalized) => {
-        if (to.meta?.public === true) return true;
+        if (to.meta?.public === true) {
+            // `onUnauthenticated()` sends them to the login route, which is
+            // public — so this is the guard seeing the redirect land.
+            if (redirectedForUnauthorized) reachedLoginAfterRedirect = true;
+            return true;
+        }
 
         if (authGuard) {
             if (!authGuard.isAuthenticated()) return authGuard.onUnauthenticated();
@@ -209,7 +280,41 @@ export function buildNavigationGuard(
         if (manifestGuard) {
             try {
                 await manifestGuard.ensureLoaded();
+                redirectedForUnauthorized = false;
+                reachedLoginAfterRedirect = false;
             } catch (err) {
+                // A 401/403 is usually an expired or missing session, not a
+                // broken manifest. Sending it to the fail-closed error page
+                // tells the operator "the manifest could not be loaded" and
+                // leaves them on a dead end, when the truth is "log in again".
+                //
+                // This happens whenever `isAuthenticated()` only checks that a
+                // token exists (the common implementation) while the token has
+                // expired: auth passes, the manifest request does not.
+                //
+                // Exactly ONCE, though. `onUnauthenticated()` commonly clears
+                // the session (`authStore.logout(); return '/login'`), so if
+                // the manifest keeps rejecting for a reason the login cannot
+                // fix — the account lacks the admin role, the endpoint is
+                // misconfigured, the backend is down — retrying it produces
+                // an unbreakable loop: log in → /admin → 401 → logged out →
+                // /login. The second time we fail closed to the error page
+                // instead, which at least says something and keeps the session.
+                //
+                // "Once" means once per LOGIN OPPORTUNITY, not once per guard
+                // call.
+                // Two protected navigations can overlap, and `ensureLoaded()`
+                // hands both of them the same in-flight promise — so both land
+                // here before either navigation completes. Counting that as
+                // two attempts would send the second, newer navigation to the
+                // error page over an ordinary expired session.
+                if (authGuard && isUnauthorizedError(err)) {
+                    if (!redirectedForUnauthorized || !reachedLoginAfterRedirect) {
+                        redirectedForUnauthorized = true;
+                        return authGuard.onUnauthenticated();
+                    }
+                }
+
                 if (manifestGuard.errorRoute && to.path !== manifestGuard.errorRoute) {
                     return manifestGuard.errorRoute;
                 }

package/src/vue/use-api-list.ts

@@ -115,7 +115,8 @@ export function useApiList<T, TFilter extends Record<string, unknown> = Record<s
     }
 
     async function setPageSize(size: number) {
-        pageSize.value = Math.max(1, Math.floor(size));
+        // The admin API's pageSize is 1..200; there is no "all" to pass on.
+        pageSize.value = Math.min(200, Math.max(1, Math.floor(size)));
         page.value = 1;
         await load();
     }

package/src/vue/use-mfa-prompt.ts

@@ -0,0 +1,72 @@
+import { ref, type Ref } from 'vue';
+
+/**
+ * Turns the MFA dialog into an awaitable step.
+ *
+ * A write flow that needs a second factor wants to read as one function:
+ * ask for the code, then call the API with it. What that needs is a promise
+ * the dialog resolves — and the plumbing for that (a visibility flag, an
+ * error slot, a description, and a resolver held between two event handlers)
+ * was spelled out identically on five standard pages.
+ *
+ * Cancelling resolves to `null` rather than rejecting: a user closing the
+ * dialog is an outcome, not an error, and `if (!code) return` reads better at
+ * the call site than a try/catch around the happy path.
+ */
+export interface MfaPrompt {
+    /** Bind to the dialog's `model-value`. */
+    readonly show: Ref<boolean>;
+    /** Bind to the dialog's `description`. */
+    readonly description: Ref<string>;
+    /** Bind to the dialog's `error`; set it to keep the dialog open on a failed code. */
+    readonly error: Ref<string>;
+    /** Resolves with the entered code, or `null` when the user cancels. */
+    prompt: (description: string) => Promise<string | null>;
+    /** Bind to the dialog's `confirm` event. */
+    onConfirm: (code: string) => void;
+    /** Bind to the dialog's `update:model-value` event. */
+    onVisibility: (open: boolean) => void;
+    /** Closes the dialog and cancels a pending prompt. */
+    close: () => void;
+}
+
+export function useMfaPrompt(): MfaPrompt {
+    const show = ref(false);
+    const description = ref('');
+    const error = ref('');
+    let pendingResolve: ((code: string | null) => void) | null = null;
+
+    function settle(code: string | null): void {
+        const resolve = pendingResolve;
+        pendingResolve = null;
+        resolve?.(code);
+    }
+
+    return {
+        show,
+        description,
+        error,
+        prompt(next: string): Promise<string | null> {
+            // A prompt opening while another is pending would strand the first
+            // caller's promise forever; cancel it rather than leak it.
+            settle(null);
+            description.value = next;
+            error.value = '';
+            show.value = true;
+            return new Promise((resolve) => {
+                pendingResolve = resolve;
+            });
+        },
+        onConfirm(code: string): void {
+            settle(code);
+        },
+        onVisibility(open: boolean): void {
+            show.value = open;
+            if (!open) settle(null);
+        },
+        close(): void {
+            show.value = false;
+            settle(null);
+        },
+    };
+}