@saasicat/ui-vue 0.24.2 → 0.26.0

package/src/vue/resource-registry.ts

@@ -0,0 +1,211 @@
+// The registry: which resources a page can reach, and what an app may change
+// about them.
+//
+// A page asks for a resource by name and gets operations that already know the
+// endpoint, the project and the locale — so a standard page needs no data
+// props at all. An app that has to divert one call overrides that one
+// operation and keeps the rest, which is the property a prop-based page cannot
+// offer: its props are all-or-nothing.
+
+import { inject, type InjectionKey } from 'vue';
+
+import {
+    bindResource,
+    type Bound,
+    type PlatformResources,
+    type ResourceContext,
+    type ResourceDef,
+    type ResourceOps,
+} from '../client/resources/index.js';
+import type { HttpClient } from '../client/types.js';
+
+/**
+ * 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.
+ */
+export 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;
+
+export 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. */
+export type ResourceMap = Record<string, ResourceDef<ResourceOps>>;
+
+export type ResourceOverrides<TMap extends ResourceMap> = {
+    [K in keyof TMap]?: ResourceOverride<TMap[K]['ops']>;
+};
+
+export 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[];
+}
+
+export 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>;
+}
+
+function boundWithOverride<TOps extends ResourceOps>(
+    def: ResourceDef<TOps>,
+    http: HttpClient,
+    readContext: () => ResourceContext,
+    override: ResourceOverride<TOps> | undefined,
+): Bound<TOps> {
+    const context = override?.context
+        ? () => ({ ...readContext(), ...override.context })
+        : readContext;
+    const platform = bindResource(def, override?.http ?? http, context);
+    if (!override?.ops) return platform;
+
+    const result = { ...platform } as Record<string, unknown>;
+    for (const [name, wrap] of Object.entries(override.ops)) {
+        if (typeof wrap !== 'function') continue;
+        // `Object.hasOwn`, not a truthy read: indexing walks the prototype
+        // chain, so an override named `toString` or `constructor` found
+        // `Object.prototype`'s and wrapped that instead of reporting a name the
+        // resource does not offer — the one case this check exists for. A typo
+        // like `lst` failed loudly while `constructor` passed silently.
+        if (!Object.hasOwn(platform as object, name)) {
+            throw new Error(
+                `createResourceRegistry: resource "${def.key}" has no operation "${name}" to ` +
+                    `override. It offers: ${Object.keys(platform).join(', ')}.`,
+            );
+        }
+        const next = (platform as Record<string, (...args: never[]) => Promise<unknown>>)[name];
+        result[name] = (...args: never[]) =>
+            (wrap as (n: unknown, ...a: never[]) => Promise<unknown>)(next, ...args);
+    }
+    return result as Bound<TOps>;
+}
+
+export function createResourceRegistry<TMap extends ResourceMap>(
+    options: CreateResourceRegistryOptions<TMap>,
+): ResourceRegistry<TMap> {
+    if (!options?.http) {
+        throw new Error(
+            'createResourceRegistry: `http` is required. Pass the HttpClient your app already ' +
+                'uses — createAxiosHttpClient(instance) or createFetchHttpClient({ headers }) — ' +
+                'so every platform request carries its auth.',
+        );
+    }
+    const readContext =
+        typeof options.context === 'function'
+            ? options.context
+            : () => options.context as ResourceContext;
+
+    // An override for a resource that is not registered would otherwise be
+    // read by nothing: the loop below walks the resources, so a typo like
+    // `planVersion` silently drops the approval or auth wrapper it was meant to
+    // add and leaves the platform operation running. A misspelled OPERATION
+    // already fails at boot, so the two spellings of the same mistake had
+    // opposite outcomes. TypeScript catches this for a typed consumer; a
+    // JavaScript one, or a config assembled at runtime, gets nothing.
+    // `hasOwn`, not `in`: `in` walks the prototype chain, so an override named
+    // `constructor` or `toString` passed the check and was then skipped by the
+    // loop below — silently ignored, which is the outcome this validation
+    // exists to prevent.
+    const unknown = Object.keys(options.overrides ?? {}).filter(
+        (key) => !Object.hasOwn(options.resources, key),
+    );
+    if (unknown.length > 0) {
+        throw new Error(
+            `createResourceRegistry: no resource named ${unknown.map((k) => `"${k}"`).join(', ')} ` +
+                `to override. The registry holds: ${Object.keys(options.resources).join(', ')}.`,
+        );
+    }
+
+    // Bound once per resource: the context is read per call, so nothing here
+    // goes stale, and a page that asks twice gets the same operations.
+    //
+    // This loop is also where the third boot-time refusal comes from, though it
+    // is not written here: `bindResource` rejects a descriptor that declares
+    // itself project-scoped when the context names no project. It is checked
+    // per resource rather than once for the registry because being project-
+    // scoped is a property of the descriptor — one of the four platform
+    // resources reads `projectKey` and three do not, so a registry-wide demand
+    // would refuse a tenant list over a project it never asks about.
+    const bound = new Map<string, unknown>();
+    for (const [key, def] of Object.entries(options.resources)) {
+        bound.set(key, boundWithOverride(def, options.http, readContext, options.overrides?.[key]));
+    }
+
+    return {
+        get(key) {
+            const ops = bound.get(key as string);
+            if (!ops) {
+                throw new Error(
+                    `useResource("${String(key)}"): no such resource. The registry offers: ` +
+                        `${[...bound.keys()].join(', ')}.`,
+                );
+            }
+            return ops as Bound<TMap[typeof key]['ops']>;
+        },
+        keys: () => [...bound.keys()],
+    };
+}
+
+/** Vue inject key for the registry (see `Symbol.for` note in super-admin-context.ts). */
+export const SUPER_ADMIN_RESOURCES_KEY: InjectionKey<ResourceRegistry> = Symbol.for(
+    '@saasicat/ui-vue/SUPER_ADMIN_RESOURCES',
+);
+
+/**
+ * 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.
+ */
+export function useResource<
+    K extends keyof TMap & string,
+    TMap extends ResourceMap = PlatformResources,
+>(key: K): Bound<TMap[K]['ops']> {
+    const registry = inject(SUPER_ADMIN_RESOURCES_KEY, null);
+    if (!registry) {
+        throw new Error(
+            `useResource("${key}"): no resource registry in scope. Either the component was ` +
+                'not mounted inside createSuperAdminApp(), or the app did not pass an `http` ' +
+                'client — the registry is not installed without one, because a bare fetch would ' +
+                'send every request without your Authorization header and fail silently.',
+        );
+    }
+    return registry.get(key) as Bound<TMap[K]['ops']>;
+}

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

@@ -37,6 +37,21 @@ export 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;
 }
 
 export type ExtensionLoader = () => Promise<Component | { default: Component }>;
@@ -134,11 +149,11 @@ export 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.

package/src/vue/ui-confirm.ts

@@ -0,0 +1,76 @@
+// UI confirm port — the seam a page asks a question through before doing
+// something it cannot undo. The counterpart to the notify port next door:
+// pages state what they need answered, the host app decides what that looks
+// like.
+//
+// `createSuperAdminApp()` (`@saasicat/ui-vue/quasar`) provides a Quasar-backed
+// default; apps override it via `createSuperAdminApp({ confirm })` or by
+// providing the key themselves.
+//
+// The shape is taken from the six confirmations the standard pages actually
+// raise, not from what a confirm dialog could be in general. Three of them ask
+// a yes/no question; three also need a value back — an audit reason the backend
+// requires before it will reset a password or deactivate a user, and a date a
+// pilot is extended to. A port returning a bare boolean would leave those three
+// on a direct Quasar call, which is the thing this port exists to remove.
+//
+// One dialog in the pages is deliberately NOT modelled here: `UsersPage` shows
+// a generated one-time password with a single acknowledge button. It asks
+// nothing, and giving it a cancel button would let an operator dismiss a
+// password that cannot be retrieved again.
+
+import type { InjectionKey } from 'vue';
+
+/**
+ * How the confirming button is coloured. `negative` marks an action that
+ * destroys or revokes something; `primary` marks one that does not.
+ */
+export type UiConfirmTone = 'primary' | 'negative';
+
+/** Asks for a value along with the confirmation. */
+export 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';
+}
+
+export 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;
+}
+
+export 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.
+ */
+export type UiConfirm = (request: UiConfirmRequest) => Promise<UiConfirmResult>;
+
+/** Vue inject key for the confirm port (see `Symbol.for` note in super-admin-context.ts). */
+export const SUPER_ADMIN_CONFIRM_KEY: InjectionKey<UiConfirm> = Symbol.for(
+    '@saasicat/ui-vue/SUPER_ADMIN_CONFIRM',
+);

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

@@ -1,18 +1,35 @@
 // useApiList — generic reactive list composable with filter + pagination.
 //
-// Consumer components ($-table, $-list, …) consume the typed wrappers
-// (`useTenants`, `useAuditEntries`, …), which are based on `useApiList`.
-// Direct use is also allowed for custom endpoints.
+// The untyped escape hatch, for an app's own list endpoints: it takes the URL
+// per call site, so nothing needs to know the endpoint in advance.
+// `useResourceList` is the typed default over the platform's own endpoints,
+// which the resource registry already knows the base of.
+//
+// What both send is one decision and lives in `list-resource.ts` — the query
+// string, the page bounds, and how an answer is read. Only the state around it
+// differs, and it differs on purpose: this one keeps the last known `total`
+// when an answer omits it, and has no guard against a superseded load.
 
 import { ref, watch, type Ref } from 'vue';
+import {
+    LIST_FIRST_PAGE,
+    LIST_PAGE_SIZE_DEFAULT,
+    clampListPage,
+    clampListPageSize,
+    listUrl,
+    readListPage,
+    type ResourceListPage,
+} from '../client/resources/list-resource.js';
 import { defaultHttpClient, type HttpClient } from '../client/types.js';
 
-export interface ApiListResponse<T> {
-    items: T[];
-    page?: number;
-    pageSize?: number;
-    total?: number;
-}
+/**
+ * The envelope a list endpoint may answer with.
+ *
+ * @deprecated Use `ResourceListPage`, which is this shape under the name the
+ * resource layer works with. Kept as an alias so an app that typed its own
+ * endpoint against it keeps compiling; one shape, one definition.
+ */
+export type ApiListResponse<T> = ResourceListPage<T>;
 
 export interface UseApiListOptions<TFilter> {
     endpoint: string;
@@ -51,23 +68,18 @@ export function useApiList<T, TFilter extends Record<string, unknown> = Record<s
 ): UseApiListResult<T> {
     const http = options.http ?? defaultHttpClient();
     const items = ref<T[]>([]) as Ref<T[]>;
-    const page = ref(1);
-    const pageSize = ref(50);
+    const page = ref(LIST_FIRST_PAGE);
+    const pageSize = ref(LIST_PAGE_SIZE_DEFAULT);
     const total = ref(0);
     const loading = ref(false);
     const error = ref<Error | null>(null);
 
     function buildUrl(): string {
-        const params = new URLSearchParams();
-        params.set('page', String(page.value));
-        params.set('pageSize', String(pageSize.value));
-        const f = options.filter?.value ?? ({} as TFilter);
-        for (const [k, v] of Object.entries(f)) {
-            if (v === undefined || v === null || v === '') continue;
-            params.set(k, String(v));
-        }
-        const sep = options.endpoint.includes('?') ? '&' : '?';
-        return `${options.endpoint}${sep}${params.toString()}`;
+        return listUrl(options.endpoint, {
+            page: page.value,
+            pageSize: pageSize.value,
+            filter: options.filter?.value,
+        });
     }
 
     async function load() {
@@ -81,25 +93,19 @@ export function useApiList<T, TFilter extends Record<string, unknown> = Record<s
             if (res.status !== 200) {
                 throw new Error(`Endpoint ${options.endpoint} → HTTP ${res.status}`);
             }
-            // Apps deliver different shapes for list endpoints:
-            //   - raw array `[{...}, …]` (no wrapper).
-            //   - paginated: `{ items, total, page, pageSize }`.
-            // The platform composable accepts both — otherwise correctly
-            // delivered array responses would be shown as an empty list.
-            const raw = (await res.json()) as unknown;
-            if (Array.isArray(raw)) {
-                items.value = raw as T[];
-                total.value = raw.length;
-            } else if (raw !== null && typeof raw === 'object') {
-                const body = raw as ApiListResponse<T>;
-                items.value = body.items ?? [];
-                if (typeof body.page === 'number') page.value = body.page;
-                if (typeof body.pageSize === 'number') pageSize.value = body.pageSize;
-                if (typeof body.total === 'number') total.value = body.total;
-            } else {
-                items.value = [];
-                total.value = 0;
-            }
+            // Apps deliver different shapes for list endpoints — a raw array or
+            // the `{ items, total, page, pageSize }` envelope — and `readListPage`
+            // accepts both, so a correctly delivered array is not shown as an
+            // empty list.
+            //
+            // What the answer did not state is left alone rather than reset: an
+            // envelope without `total` keeps the count from the last one that
+            // carried it, which is what this composable has always done.
+            const body = readListPage<T>(await res.json());
+            items.value = body.items;
+            if (typeof body.page === 'number') page.value = body.page;
+            if (typeof body.pageSize === 'number') pageSize.value = body.pageSize;
+            if (typeof body.total === 'number') total.value = body.total;
         } catch (err) {
             error.value = err instanceof Error ? err : new Error(String(err));
             items.value = [];
@@ -110,14 +116,13 @@ export function useApiList<T, TFilter extends Record<string, unknown> = Record<s
     }
 
     async function goToPage(p: number) {
-        page.value = Math.max(1, Math.floor(p));
+        page.value = clampListPage(p);
         await load();
     }
 
     async function setPageSize(size: number) {
-        // 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;
+        pageSize.value = clampListPageSize(size);
+        page.value = LIST_FIRST_PAGE;
         await load();
     }
 
@@ -125,7 +130,7 @@ export function useApiList<T, TFilter extends Record<string, unknown> = Record<s
         watch(
             options.filter,
             () => {
-                page.value = 1;
+                page.value = LIST_FIRST_PAGE;
                 void load();
             },
             { deep: true },

package/src/vue/use-async-action.ts

@@ -0,0 +1,170 @@
+// One async mutation, with the state a page otherwise writes by hand.
+//
+// The pages hold this shape 20-odd times: a `ref(false)` set true before the
+// call and false in `finally`, an error ref cleared before and written in
+// `catch`, and a toast raised on one or both outcomes. Written out each time,
+// the parts drift — some clear the error first and some do not, some toast on
+// failure and some only render it, and each one re-derives its message from a
+// raw `unknown`.
+//
+// `run` does not re-throw. A wrapper that recorded the failure and then threw
+// it again would leave every call site with the `try`/`catch` this exists to
+// remove, so the outcome is in the return value instead.
+//
+// It is a discriminated result rather than `T | undefined`, because the second
+// shape cannot answer the question for the actions this package has most of.
+// `softDelete`, `discardDraft`, `remove` and their siblings resolve
+// `Promise<void>`: a successful call already produces `undefined`, so
+// "`undefined` means it failed" was a signal that did not exist there — and
+// TypeScript narrows the success branch of `void | undefined` to `never`, so
+// the wrong call site compiles, lints clean, and silently never runs its
+// follow-up.
+
+import { inject, ref, type Ref } from 'vue';
+
+import { adminErrorMessage, toAdminError, type AdminError } from '../client/admin-error.js';
+import { useSaMessages } from './use-super-admin-i18n.js';
+import { SUPER_ADMIN_NOTIFY_KEY, type UiNotify } from './ui-notify.js';
+
+/**
+ * What an action did. `ok` is the branch to read — it answers for a
+ * `Promise<void>` action exactly as well as for one that returns a row.
+ */
+export type AsyncActionResult<T> = { ok: true; value: T } | { ok: false; error: AdminError };
+
+export interface AsyncAction<A extends unknown[], T> {
+    /** Runs the action. Never throws; the outcome is in the result. */
+    run: (...args: A) => Promise<AsyncActionResult<T>>;
+    /** True while the call is in flight — what a submit button disables on. */
+    pending: Ref<boolean>;
+    /** The last failure, or `null`. Cleared at the start of every run. */
+    error: Ref<AdminError | null>;
+    /** Clears `error` without running anything. */
+    reset: () => void;
+}
+
+export interface UseAsyncActionOptions<T> {
+    /**
+     * Which outcomes raise a toast. Default `'error'` — a success that changed
+     * something visible needs no announcement, a failure always does.
+     */
+    notifyOn?: 'error' | 'both' | 'none';
+    /** Text for the success toast. Required for `notifyOn: 'both'` to say anything. */
+    successMessage?: string | (() => string);
+    /**
+     * Overrides how a failure is worded.
+     *
+     * Not decoration: several pages map a status and an error code to a
+     * specific sentence — a 422 carrying `STRICT_MODE_VIOLATIONS` reads out the
+     * violations, a 401 says the session expired. `AdminError` carries
+     * `status`, `code` and `body`, so that mapping is a pure function of the
+     * error, and this is where it attaches.
+     */
+    errorMessage?: (error: AdminError) => string;
+    /** Runs after a successful call, before `run` resolves. */
+    onSuccess?: (result: T) => void | Promise<void>;
+    /**
+     * Notify port to report through. Defaults to the injected one.
+     *
+     * There is no fallback beyond that: this layer must not import Quasar, so
+     * it cannot reach `quasarNotify` the way a page can. Without a bootstrap
+     * and without this option, failures are reported through `error` alone.
+     */
+    notify?: UiNotify;
+}
+
+/**
+ * Announces an outcome without being able to change it.
+ *
+ * A report is not part of the action. A notify port whose notification centre
+ * is not mounted used to throw from inside the `try`, so a mutation the server
+ * had already applied came back as a failure — and because the catch then
+ * announced *that*, the same port threw again and `run()` rejected outright. A
+ * caller answering a failed write with a retry repeated a non-idempotent
+ * request over a toast.
+ *
+ * The throw is isolated, not swallowed: it is raised again out of band, where
+ * the app's error handler still sees it and no result is left to corrupt.
+ */
+function report(announce: () => void): void {
+    try {
+        announce();
+    } catch (err: unknown) {
+        queueMicrotask(() => {
+            throw err;
+        });
+    }
+}
+
+export function useAsyncAction<A extends unknown[], T>(
+    fn: (...args: A) => Promise<T>,
+    options: UseAsyncActionOptions<T> = {},
+): AsyncAction<A, T> {
+    const pending = ref(false);
+    const error = ref<AdminError | null>(null);
+    const notify = options.notify ?? inject(SUPER_ADMIN_NOTIFY_KEY, undefined);
+    const messages = useSaMessages('errors');
+    const notifyOn = options.notifyOn ?? 'error';
+    // How many invocations are in flight. A second `run` before the first
+    // settles would otherwise let the first one's `finally` clear `pending`,
+    // and a button disabled from that ref becomes clickable again while the
+    // mutation it belongs to is still running — which is how a double submit
+    // happens.
+    let inFlight = 0;
+    // Which invocation the visible state belongs to. `error` is cleared at the
+    // start of every run, so without this an older call failing after a newer
+    // one started would write its failure into a state the newer call had
+    // already reset — and the newer success, which only clears at ITS start,
+    // never removed it. The operator was left looking at an error for an
+    // operation that had succeeded.
+    let generation = 0;
+
+    async function run(...args: A): Promise<AsyncActionResult<T>> {
+        const mine = ++generation;
+        inFlight++;
+        pending.value = true;
+        error.value = null;
+        try {
+            const result = await fn(...args);
+            // The continuation runs BEFORE the success toast. It is part of
+            // the action — a reload, a navigation — and when it fails the
+            // action failed. Announcing success first produced both toasts:
+            // "Saved" and then "reload failed", in that order.
+            await options.onSuccess?.(result);
+            if (notifyOn === 'both') {
+                report(() => {
+                    const message =
+                        typeof options.successMessage === 'function'
+                            ? options.successMessage()
+                            : options.successMessage;
+                    if (message) notify?.('positive', message);
+                });
+            }
+            return { ok: true, value: result };
+        } catch (err: unknown) {
+            const adminError = toAdminError(err);
+            if (mine === generation) error.value = adminError;
+            if (notifyOn !== 'none') {
+                report(() =>
+                    notify?.(
+                        'negative',
+                        options.errorMessage?.(adminError) ??
+                            adminErrorMessage(adminError, messages.value),
+                    ),
+                );
+            }
+            return { ok: false, error: adminError };
+        } finally {
+            if (--inFlight === 0) pending.value = false;
+        }
+    }
+
+    return {
+        run,
+        pending,
+        error,
+        reset: () => {
+            error.value = null;
+        },
+    };
+}