@pilotiq/pilotiq 0.1.0

package/dist/actions/Action.js

@@ -0,0 +1,1652 @@
+import { Element } from '../schema/Element.js';
+import { safeManagerPolicy, } from '../RelationManager.js';
+import { computeMorphPayload, getMorphRelationDescriptor, getParentRelationDescriptor, } from '../orm/modelDefaults.js';
+import { resolveM2MAccessor } from '../orm/m2mAccessor.js';
+import { buildImportSchema as buildImportModalSchema } from './importFactory.js';
+import { buildAttachModalSchema } from './attachFactory.js';
+/** Cluster-aware resource base path. Mirrors `clusterPaths.resourceBasePath`
+ *  but uses the structural `ResourceLike` shape so `Action.ts` stays
+ *  cycle-free against `Resource.ts`. */
+function resourceBase(basePath, R) {
+    if (R.cluster)
+        return `${basePath}/${R.cluster.getSlug()}/${R.getSlug()}`;
+    return `${basePath}/${R.getSlug()}`;
+}
+/** Pick the right label form for a count — `labelSingular` for 1,
+ *  `label` (plural, lowercased) for any other count. Fall back to a
+ *  naive `${labelSingular}s` when no plural label is set. Used by bulk
+ *  notification copy so we don't ship "1 posts moved to trash". */
+function labelForCount(R, n) {
+    if (n === 1)
+        return R.labelSingular.toLowerCase();
+    const plural = R.label?.toLowerCase();
+    return plural ?? `${R.labelSingular.toLowerCase()}s`;
+}
+/** True when a `RelationManagerContext.mode` denotes a pivot-mutation
+ *  shape — i.e. a many-to-many relation. All three modes share the
+ *  `attach` / `detach` / `sync` accessor surface (the rudder ORM stamps
+ *  + filters the polymorphic discriminator transparently for the morph
+ *  variants). The `relationCreate / Edit / Delete` factories auto-hide
+ *  under any of these modes because per-pivot-row create / edit / delete
+ *  is meaningless — users create the related record via its own Resource,
+ *  then attach via `relationAttach`. */
+function isM2MMode(mode) {
+    return mode === 'belongsToMany' || mode === 'morphToMany' || mode === 'morphedByMany';
+}
+/**
+ * Phase B — build the URL prefix for a relation factory action. Without
+ * a `chain` (depth-1 manager), this is the familiar
+ * `${base}/${parentSlug}/${parentId}/${relationship}`. With a chain
+ * (depth-2 nested manager), it threads the outer record + relationship
+ * between the parent slug and the leaf parent id:
+ *
+ *   `${base}/${parentSlug}/${chain[0].recordId}/${chain[0].relationship}/${parentId}/${relationship}`
+ *
+ * Pure; takes a `RelationManagerContext` and emits a string. The leaf
+ * record id (and trailing `/edit`, `/delete`, etc.) gets appended by
+ * the caller.
+ */
+function relationUrlPrefix(ctx) {
+    const head = `${ctx.basePath}/${ctx.parentSlug}`;
+    const chain = ctx.chain ?? [];
+    let mid = '';
+    for (const step of chain) {
+        mid += `/${step.recordId}/${step.relationship}`;
+    }
+    return `${head}${mid}/${ctx.parentId}/${ctx.relationship}`;
+}
+/**
+ * Compute the parent-attachment payload to force-pin onto a relation
+ * replica. For `hasMany`, returns `{ [foreignKey]: parentId }` from the
+ * parent's `static relations[name]` descriptor. For `morphMany` /
+ * `morphOne`, returns `{ <morphName>Id, <morphName>Type }` via
+ * `computeMorphPayload(parentRecord)`. Returns `{}` when no descriptor
+ * matches — the route dispatcher already auto-hides under M2M / morphTo,
+ * so missing descriptors there are a no-op rather than an error. Pure;
+ * exported for tests and re-used by both factories.
+ */
+function computeRelationPin(ctx) {
+    const parentModel = ctx.parentRecord?.constructor;
+    if (!parentModel)
+        return {};
+    const rel = ctx.relationship;
+    // Polymorphic owner side first — `morphMany` carries no foreignKey
+    // and would fail the hasMany descriptor's gate.
+    if (ctx.mode === 'morphMany') {
+        const morph = getMorphRelationDescriptor(parentModel, rel);
+        if (!morph)
+            return {};
+        try {
+            return computeMorphPayload(ctx.parentRecord, morph);
+        }
+        catch {
+            return {};
+        }
+    }
+    const desc = getParentRelationDescriptor(parentModel, rel);
+    if (!desc)
+        return {};
+    return { [desc.foreignKey]: ctx.parentId };
+}
+/**
+ * Build + persist a single relation replica. Runs the strip set
+ * (PK + soft-delete column on the **related** Resource +
+ * `opts.excludeAttributes`), force-pins the parent attachment columns,
+ * runs the optional `beforeReplicaSaved` hook, and calls
+ * `Related.model.create(...)`. Returns the model's create result so
+ * callers can read its primary key for redirect targeting.
+ *
+ * Throws when the related Resource has no model — caller (single-row
+ * factory) catches and surfaces an error notification; bulk caller
+ * checks the model presence ahead of the loop.
+ */
+async function persistRelationReplica(_M, ctx, source, opts) {
+    const Related = ctx.related;
+    if (!Related?.model || typeof Related.model.create !== 'function') {
+        throw new Error('Related Resource has no model.create');
+    }
+    const M2 = Related.model;
+    const pkCol = M2.primaryKey ?? 'id';
+    const trashedCol = Related.deletedAtColumn ?? 'deletedAt';
+    const skip = new Set([pkCol, trashedCol, ...(opts.excludeAttributes ?? [])]);
+    let replica = {};
+    for (const [k, v] of Object.entries(source)) {
+        if (skip.has(k))
+            continue;
+        replica[k] = v;
+    }
+    // Force-pin the parent attachment AFTER the strip but BEFORE the
+    // user mutator, so `beforeReplicaSaved` can read / override the FK
+    // if it really wants to (rare). Tampered source rows can't slip a
+    // different parent in by riding their own FK column — the pin
+    // overwrites whatever value was there.
+    Object.assign(replica, computeRelationPin(ctx));
+    if (opts.beforeReplicaSaved) {
+        replica = await opts.beforeReplicaSaved(replica, source);
+    }
+    return M2.create(replica);
+}
+/**
+ * Single-row dispatch for `Action.relationReplicate`. Resolves
+ * `ctx.record` (loaded by the route's resolveRecord hook), validates,
+ * persists the replica, and shapes the success notification. Errors
+ * are caught and surfaced as error toasts.
+ */
+async function runRelationReplicateRow(M, ctx, hctx, opts) {
+    const source = hctx.record;
+    if (!source || typeof source !== 'object') {
+        return { notify: { title: 'Replicate failed: source record missing', type: 'error' } };
+    }
+    const Related = ctx.related;
+    if (!Related?.model || typeof Related.model.create !== 'function') {
+        return { notify: { title: 'Replicate not configured (related Resource has no model.create)', type: 'error' } };
+    }
+    let created;
+    try {
+        created = await persistRelationReplica(M, ctx, source, opts);
+    }
+    catch (err) {
+        return { notify: { title: `Replicate failed: ${err instanceof Error ? err.message : String(err)}`, type: 'error' } };
+    }
+    const overrideTitle = opts.getCreatedNotificationTitle
+        ? await opts.getCreatedNotificationTitle({ replica: created, source })
+        : undefined;
+    const title = overrideTitle !== undefined ? overrideTitle : `${M.getLabelSingular()} replicated`;
+    // The manager-scoped `_action/:actionName` route falls back to the
+    // manager list URL when `result.redirect` is undefined, so we only
+    // emit `redirect` when the user override returned a string. That
+    // way default behavior (route owns the fallback) is unchanged.
+    const overrideRedirect = opts.getRedirectUrl
+        ? await opts.getRedirectUrl({ replica: created, source })
+        : undefined;
+    return {
+        ...(overrideRedirect !== undefined ? { redirect: overrideRedirect } : {}),
+        notify: { title, type: 'success' },
+    };
+}
+/** Read `record[R.deletedAtColumn ?? 'deletedAt']` and return true when
+ *  the row is currently trashed (soft-deleted). Permissive on shape —
+ *  bare `null` / `undefined` count as live; any other truthy value is
+ *  trashed. */
+function isTrashed(record, R) {
+    if (!record || typeof record !== 'object')
+        return false;
+    const col = R.deletedAtColumn ?? 'deletedAt';
+    const v = record[col];
+    return v !== null && v !== undefined;
+}
+/** Lazy-load the `Table` class for use inside Action handlers. Direct
+ *  module-level import would cycle (Table → Action → Table); dynamic
+ *  import inside a handler runs after both modules have finished
+ *  loading. Cached after first call so we don't pay the import cost
+ *  on every dispatched export. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let _TableClass;
+async function loadTableClass() {
+    if (_TableClass !== undefined)
+        return _TableClass.make();
+    const mod = await import('../elements/Table.js');
+    _TableClass = mod.Table;
+    return _TableClass.make();
+}
+/** Call a (possibly undefined) Resource predicate. When unset, the
+ * predicate is treated as "allowed" (returns true) so the factory
+ * doesn't hide actions on Resources that haven't opted into Plan #10. */
+function callPredicate(fn, user, record) {
+    if (!fn)
+        return true;
+    return fn(user, record);
+}
+/**
+ * Action — a button-or-menu-entry that performs work when clicked.
+ *
+ * One class for all four placements; pick one via `.inline()` / `.row()` /
+ * `.bulk()` / `.header()` (or `.placement(...)`). Actions can sit inline
+ * inside any container Element (Card, Section, etc.) or attach to a
+ * Resource's list page.
+ *
+ * Phase 1.4 ships the shape + serialization. Handler dispatch and
+ * confirmation-form support land in Phase 2 alongside Resource lifecycle.
+ */
+export class Action extends Element {
+    name;
+    _label;
+    _icon;
+    _placement = 'inline';
+    _destructive = false;
+    _confirm;
+    _handler;
+    /**
+     * Notification-registry handler key — set by `.handler(string)`. The
+     * notification-action route looks this up against
+     * `Pilotiq.notificationHandlers({…})` at request time. Mutually
+     * exclusive with the closure `_handler` — passing a string clears
+     * `_handler`, passing a function clears `_handlerName`. Closures can't
+     * round-trip through a `data` JSON column; the registry path is the
+     * persisted-notification escape hatch.
+     */
+    _handlerName;
+    /**
+     * Per-fire context for registry-handler dispatch. Round-trips through
+     * the notification's `data.actions` JSON column verbatim and arrives
+     * on the handler's `ctx.payload`.
+     */
+    _payload;
+    /**
+     * Filament-style chain modifier — when set on an action used inside a
+     * `Notification.actions([…])` slot, firing the action also flips the
+     * notification's `read_at`. No-op when the action isn't in a
+     * notification context.
+     */
+    _markAsReadOnFire = false;
+    /**
+     * When set, click-through opens in a new tab. Honored by the
+     * notification action strip renderers (bell + toast); ignored by
+     * everything else (Resource action triggers don't expose this knob —
+     * use `target` on the underlying anchor if you need it elsewhere).
+     */
+    _openUrlInNewTab = false;
+    _href;
+    _method;
+    _actionUrl;
+    _dispatchUrl;
+    _submit = false;
+    _formTarget;
+    _formField;
+    // Modal chrome — present whenever `.schema()` or any of the modal
+    // builders below have been called.
+    _hasModal = false;
+    _modalHeading;
+    _modalDescription;
+    _modalSubmitLabel;
+    _modalCancelLabel;
+    _modalIcon;
+    _modalIconColor;
+    _modalWidth;
+    _slideOver = false;
+    // Defaults match the existing renderer behaviour (closeable both ways,
+    // no sticky chrome, no X button). Setters with a default arg of `false`
+    // / `true` mirror Filament's call shapes — `closeModalByClickingAway()`
+    // disables pointer dismiss, `stickyModalHeader()` enables sticky.
+    _closeModalByClickingAway = true;
+    _closeModalByEscaping = true;
+    _stickyModalHeader = false;
+    _stickyModalFooter = false;
+    _modalAutofocus;
+    _modalAlignment;
+    _modalCloseButton = false;
+    // Trigger variants & cosmetics
+    _color;
+    _size;
+    _tooltip;
+    _outlined = false;
+    _iconOnly = false;
+    _badge;
+    _badgeColor;
+    // Conditional visibility / disabled rules
+    _visible;
+    _hidden;
+    _isDisabled;
+    constructor(name) {
+        super();
+        this.name = name;
+        this._label = name.charAt(0).toUpperCase() + name.slice(1);
+    }
+    static make(name) {
+        return new Action(name);
+    }
+    // ─── Resource-aware factories ─────────────────────────
+    //
+    // Pre-configured Action shapes that target a Resource's standard CRUD
+    // pages. Drop into `Table.recordActions([…])`, `headerActions([…])`,
+    // or `ViewPage.getActions(...)` — placement is stamped by the slot.
+    // Filament-style: explicit, but ergonomic.
+    //
+    // Each factory uses `:id` template substitution for row context; the
+    // renderer fills in the row's id when rendering. Header / view actions
+    // ignore the template (no `:id` needed for create / list URLs).
+    //
+    // Plan #10 — each factory auto-attaches a visibility rule that
+    // delegates to the Resource's matching policy method (`R.canCreate`
+    // for `Action.create`, etc). When `R.canX` is unset (default returns
+    // `true`) the action stays visible. Pass an explicit `.visible(...)`
+    // after the factory to override.
+    /** Create-action factory — link to `${basePath}/${R.slug}/create`.
+     * Auto-hides when `R.canCreate(user)` returns false. */
+    static create(R, basePath) {
+        return Action.make('create')
+            .label(`New ${R.labelSingular}`)
+            .href(`${resourceBase(basePath, R)}/create`)
+            .visible(({ user }) => callPredicate(R.canCreate, user));
+    }
+    /**
+     * Edit-action factory — link to the resource's edit page.
+     *
+     * Pass `recordId` when building actions for a single-record context
+     * (e.g. `ViewPage.getActions()`); the URL is baked at config time.
+     * Omit `recordId` for row context (`Table.recordActions(...)`); the
+     * URL keeps the `:id` template and the renderer substitutes per-row.
+     *
+     * Auto-hides when `R.canEdit(user, record)` returns false. For row
+     * context the per-row record threads in via `loadTableRecords`'s
+     * per-row eval; for view-page context, `resolveSchema` provides the
+     * resolved record on the eval context.
+     */
+    static edit(R, basePath, recordId) {
+        const id = recordId ?? ':id';
+        return Action.make('edit')
+            .label('Edit')
+            .href(`${resourceBase(basePath, R)}/${id}/edit`)
+            .visible(({ user, record }) => callPredicate(R.canEdit, user, record));
+    }
+    /** View-action factory — link to the resource's view page. See `Action.edit` for the `recordId` semantics.
+     * Auto-hides when `R.canView(user, record)` returns false. */
+    static view(R, basePath, recordId) {
+        const id = recordId ?? ':id';
+        return Action.make('view')
+            .label('View')
+            .href(`${resourceBase(basePath, R)}/${id}`)
+            .visible(({ user, record }) => callPredicate(R.canView, user, record));
+    }
+    /**
+     * Delete-action factory — POSTs to the resource's delete route,
+     * destructive style, with a confirmation prompt referencing the
+     * resource label. Same `recordId` semantics as `Action.edit`.
+     * Auto-hides when `R.canDelete(user, record)` returns false.
+     *
+     * Plan #13 — when `R.softDeletes = true`, additionally hides on
+     * rows whose `deletedAtColumn` is set (already-trashed rows get the
+     * Restore + ForceDelete pair instead, surfaced via the matching
+     * factories below).
+     */
+    static delete(R, basePath, recordId) {
+        const id = recordId ?? ':id';
+        return Action.make('delete')
+            .label('Delete')
+            .destructive()
+            .method('post')
+            .action(`${resourceBase(basePath, R)}/${id}/delete`)
+            .confirm(`Delete this ${R.labelSingular.toLowerCase()}?`)
+            .visible(async ({ user, record }) => {
+            if (R.softDeletes && isTrashed(record, R))
+                return false;
+            return callPredicate(R.canDelete, user, record);
+        });
+    }
+    /**
+     * Replicate-action factory — handler-style. Loads the source record
+     * from `ctx.record` (the `_action/:actionName` route already resolves
+     * it through `R.query(ctx)` for row + single-target placements),
+     * strips PK + soft-delete column + any `opts.excludeAttributes`,
+     * optionally runs `opts.beforeReplicaSaved`, and creates a new row
+     * via `R.model.create(...)`. Redirects to the new record's edit page
+     * on success so the user can review + tweak before saving again.
+     *
+     * `recordId` kept in the signature for parity with `delete / edit /
+     * view` so users can swap factories without rewriting call sites; the
+     * dispatcher resolves the source record from the URL and hands it to
+     * the handler as `ctx.record`, so we don't reference `recordId` here.
+     *
+     * Auto-hides when `R.canCreate(user)` returns false — replicating
+     * writes a new row, so the gate is `canCreate`, not `canView`.
+     */
+    static replicate(R, basePath, recordId, opts = {}) {
+        void recordId;
+        return Action.make('replicate')
+            .label('Replicate')
+            .handler(async (ctx) => {
+            const source = ctx.record;
+            if (!source || typeof source !== 'object') {
+                return { notify: { title: 'Replicate failed: source record missing', type: 'error' } };
+            }
+            const M = R.model;
+            if (!M || typeof M.create !== 'function') {
+                return { notify: { title: 'Replicate not configured (resource has no model.create)', type: 'error' } };
+            }
+            const pkCol = M.primaryKey ?? 'id';
+            const trashedCol = R.deletedAtColumn ?? 'deletedAt';
+            const skip = new Set([pkCol, trashedCol, ...(opts.excludeAttributes ?? [])]);
+            let replica = {};
+            for (const [k, v] of Object.entries(source)) {
+                if (skip.has(k))
+                    continue;
+                replica[k] = v;
+            }
+            if (opts.beforeReplicaSaved) {
+                try {
+                    replica = await opts.beforeReplicaSaved(replica, source);
+                }
+                catch (err) {
+                    return { notify: { title: `Replicate failed: ${err instanceof Error ? err.message : String(err)}`, type: 'error' } };
+                }
+            }
+            let created;
+            try {
+                created = await M.create(replica);
+            }
+            catch (err) {
+                return { notify: { title: `Replicate failed: ${err instanceof Error ? err.message : String(err)}`, type: 'error' } };
+            }
+            const newId = created?.[pkCol];
+            const defaultRedirect = newId !== undefined && newId !== null
+                ? `${resourceBase(basePath, R)}/${String(newId)}/edit`
+                : `${resourceBase(basePath, R)}`;
+            // `!== undefined` rather than `??` so an override returning
+            // `null`/empty-string isn't silently swallowed (see
+            // feedback_nullish_swallows_explicit_null).
+            const overrideRedirect = opts.getRedirectUrl
+                ? await opts.getRedirectUrl({ replica: created, source })
+                : undefined;
+            const redirect = overrideRedirect !== undefined ? overrideRedirect : defaultRedirect;
+            const overrideTitle = opts.getCreatedNotificationTitle
+                ? await opts.getCreatedNotificationTitle({ replica: created, source })
+                : undefined;
+            const title = overrideTitle !== undefined ? overrideTitle : `${R.labelSingular} replicated`;
+            return {
+                redirect,
+                notify: { title, type: 'success' },
+            };
+        })
+            .visible(({ user }) => callPredicate(R.canCreate, user));
+    }
+    /**
+     * Plan #13 — Restore factory. POSTs to the resource's restore route,
+     * success-styled, no confirm prompt (restoration is reversible).
+     * Auto-hides on live (non-trashed) rows AND when `R.canRestore(user,
+     * record)` returns false. Same `recordId` semantics as `Action.edit`.
+     */
+    static restore(R, basePath, recordId) {
+        const id = recordId ?? ':id';
+        return Action.make('restore')
+            .label('Restore')
+            .color('success')
+            .method('post')
+            .action(`${resourceBase(basePath, R)}/${id}/restore`)
+            .visible(async ({ user, record }) => {
+            if (!isTrashed(record, R))
+                return false;
+            return callPredicate(R.canRestore, user, record);
+        });
+    }
+    /**
+     * Plan #13 — Force-delete factory. POSTs to the resource's
+     * force-delete route, destructive-styled, with a stricter confirm
+     * prompt referencing permanence. Auto-hides on live (non-trashed)
+     * rows AND when `R.canForceDelete(user, record)` returns false.
+     */
+    static forceDelete(R, basePath, recordId) {
+        const id = recordId ?? ':id';
+        return Action.make('forceDelete')
+            .label('Delete forever')
+            .destructive()
+            .method('post')
+            .action(`${resourceBase(basePath, R)}/${id}/force-delete`)
+            .confirm(`Permanently delete this ${R.labelSingular.toLowerCase()}? This cannot be undone.`)
+            .visible(async ({ user, record }) => {
+            if (!isTrashed(record, R))
+                return false;
+            return callPredicate(R.canForceDelete, user, record);
+        });
+    }
+    // ─── Notification factories ───────────────────────────────────
+    //
+    // Pre-configured Action shapes that target the bell-table read /
+    // unread endpoints mounted by `Pilotiq.databaseNotifications()`. Use
+    // inside a custom notification inbox page's `recordActions(...)` (or
+    // alongside a `Notification.actions([…])` slot when one ships) to
+    // give end-users explicit "Mark as read" / "Mark as unread" buttons.
+    //
+    // Filament-style chain modifier `Action::make('view')->markAsRead()`
+    // is a separate concern — it'd add an implicit mark-read side-effect
+    // to a custom action. v1 ships only the explicit factory; the chain
+    // modifier is deferred until a consumer asks.
+    /**
+     * Mark-as-read factory — POSTs to the panel's notification read
+     * endpoint for the given notification id. The endpoint
+     * (`${base}/_notifications/:id/read`) is mounted by
+     * `Pilotiq.databaseNotifications()`, so calling this without
+     * opting into the bell surface produces an Action whose POST 404s.
+     *
+     * `notificationId` is baked at config time. For row context where
+     * the id varies per row, omit it and the URL keeps the `:id`
+     * template; the renderer substitutes per-row at render time
+     * (parallel to `Action.edit`'s row form).
+     *
+     * No auto-visibility. Wrap in `.visible(({ record }) => !record.readAt)`
+     * to hide on already-read rows.
+     */
+    static markAsRead(basePath, notificationId) {
+        const id = notificationId ?? ':id';
+        return Action.make('markAsRead')
+            .label('Mark as read')
+            .method('post')
+            .action(`${basePath}/_notifications/${id}/read`);
+    }
+    // ─── Bulk factories (Plan #13) ────────────────────────────────
+    //
+    // Handler-style bulk actions that iterate `ctx.records`, run policy
+    // per-row, and call the matching Resource / Model method. No new
+    // routes — the existing `/_action/:actionName` dispatcher already
+    // handles bulk via `ctx.records`. Drop into `bulkActions([...])`
+    // from inside `Resource.table()`.
+    //
+    // Each returns a notification with the count succeeded; rows whose
+    // policy denied (or whose call threw) are silently skipped — surface
+    // them via your own logging if needed.
+    /** Bulk delete — calls `R.deleteRecord(id)` per row. On a
+     *  soft-delete resource that hits `Model.delete()` which writes
+     *  `deletedAt`. Notification: "N posts moved to trash" / "N posts
+     *  deleted" depending on `R.softDeletes`. */
+    static bulkDelete(R, _basePath) {
+        return Action.make('bulkDelete')
+            .label('Delete selected')
+            .destructive()
+            .bulk()
+            .confirm(`Delete the selected ${labelForCount(R, 0)}?`)
+            .handler(async (ctx) => {
+            const records = ctx.records ?? [];
+            const Rfull = R;
+            let n = 0;
+            for (const record of records) {
+                const id = String(record.id ?? '');
+                if (!id)
+                    continue;
+                const allowed = await callPredicate(R.canDelete, ctx.user, record);
+                if (!allowed)
+                    continue;
+                try {
+                    await Rfull.deleteRecord(id);
+                    n++;
+                }
+                catch { /* skip — agg notify shows total */ }
+            }
+            const verb = R.softDeletes ? 'moved to trash' : 'deleted';
+            return { notify: { title: `${n} ${labelForCount(R, n)} ${verb}`, type: 'success' } };
+        });
+    }
+    /** Bulk restore — calls `R.model.restore(id)` per row. Visible only
+     *  on soft-delete resources (the entire bulk-restore concept is
+     *  specific to them). */
+    static bulkRestore(R, _basePath) {
+        return Action.make('bulkRestore')
+            .label('Restore selected')
+            .color('success')
+            .bulk()
+            .confirm(`Restore the selected ${labelForCount(R, 0)}?`)
+            .handler(async (ctx) => {
+            const records = ctx.records ?? [];
+            const Rfull = R;
+            const restore = Rfull.model?.restore;
+            if (!restore) {
+                return { notify: { title: 'Restore not configured', type: 'error' } };
+            }
+            let n = 0;
+            for (const record of records) {
+                const id = String(record.id ?? '');
+                if (!id)
+                    continue;
+                const allowed = await callPredicate(R.canRestore, ctx.user, record);
+                if (!allowed)
+                    continue;
+                try {
+                    await restore(id);
+                    n++;
+                }
+                catch { /* skip */ }
+            }
+            return { notify: { title: `${n} ${labelForCount(R, n)} restored`, type: 'success' } };
+        });
+    }
+    /** Bulk force-delete — calls `R.model.forceDelete(id)` per row. Same
+     *  destructive confirm as the per-row variant. Visible only on
+     *  soft-delete resources. */
+    static bulkForceDelete(R, _basePath) {
+        return Action.make('bulkForceDelete')
+            .label('Delete forever')
+            .destructive()
+            .bulk()
+            .confirm(`Permanently delete the selected ${labelForCount(R, 0)}? This cannot be undone.`)
+            .handler(async (ctx) => {
+            const records = ctx.records ?? [];
+            const Rfull = R;
+            const forceDelete = Rfull.model?.forceDelete;
+            if (!forceDelete) {
+                return { notify: { title: 'Force-delete not configured', type: 'error' } };
+            }
+            let n = 0;
+            for (const record of records) {
+                const id = String(record.id ?? '');
+                if (!id)
+                    continue;
+                const allowed = await callPredicate(R.canForceDelete, ctx.user, record);
+                if (!allowed)
+                    continue;
+                try {
+                    await forceDelete(id);
+                    n++;
+                }
+                catch { /* skip */ }
+            }
+            return { notify: { title: `${n} ${labelForCount(R, n)} permanently deleted`, type: 'success' } };
+        });
+    }
+    /**
+     * Bulk replicate — calls `R.model.create(...)` once per selected row
+     * with the source row's attributes minus PK / soft-delete column /
+     * `opts.excludeAttributes`. Optional `opts.beforeReplicaSaved(replica,
+     * source)` runs per-row. Rows that throw during create are skipped
+     * silently so a single bad row doesn't abort the batch (the user sees
+     * the success count on the toast). Visibility delegates to
+     * `R.canCreate(user)`.
+     *
+     * Sibling of `Action.replicate` — same options bag, same strip set,
+     * same authorization gate. Stays on the list page (no per-row
+     * redirect possible for N rows).
+     */
+    static bulkReplicate(R, _basePath, opts = {}) {
+        return Action.make('bulkReplicate')
+            .label('Replicate selected')
+            .bulk()
+            .confirm(`Replicate the selected ${labelForCount(R, 0)}?`)
+            .handler(async (ctx) => {
+            const M = R.model;
+            if (!M || typeof M.create !== 'function') {
+                return { notify: { title: 'Replicate not configured (resource has no model.create)', type: 'error' } };
+            }
+            const records = ctx.records ?? [];
+            const pkCol = M.primaryKey ?? 'id';
+            const trashedCol = R.deletedAtColumn ?? 'deletedAt';
+            const skip = new Set([pkCol, trashedCol, ...(opts.excludeAttributes ?? [])]);
+            let n = 0;
+            for (const source of records) {
+                if (!source || typeof source !== 'object')
+                    continue;
+                const allowed = await callPredicate(R.canCreate, ctx.user);
+                if (!allowed)
+                    continue;
+                let replica = {};
+                for (const [k, v] of Object.entries(source)) {
+                    if (skip.has(k))
+                        continue;
+                    replica[k] = v;
+                }
+                if (opts.beforeReplicaSaved) {
+                    try {
+                        replica = await opts.beforeReplicaSaved(replica, source);
+                    }
+                    catch {
+                        continue;
+                    }
+                }
+                try {
+                    await M.create(replica);
+                    n++;
+                }
+                catch { /* skip — agg notify shows total */ }
+            }
+            const defaultTitle = `${n} ${labelForCount(R, n)} replicated`;
+            const overrideTitle = opts.getCreatedNotificationTitle
+                ? await opts.getCreatedNotificationTitle({ count: n, records })
+                : undefined;
+            const title = overrideTitle !== undefined ? overrideTitle : defaultTitle;
+            return { notify: { title, type: 'success' } };
+        })
+            .visible(({ user }) => callPredicate(R.canCreate, user));
+    }
+    // ─── Import / Export factories ────────────────────────────────
+    //
+    // Pre-built CSV / JSON in/out for any Resource that has `R.model`.
+    // `Action.export` walks the configured `R.table()` records handler
+    // in pages (so it picks up the active filter/search/sort by default,
+    // and stays consistent with what the user is looking at). The bulk
+    // variant exports `ctx.records` instead. `Action.import` opens a
+    // form-modal with a `FileUpload`, parses the uploaded file, and runs
+    // create / upsert through `R.model`.
+    //
+    // Internals live in `./exportFactory.ts` and `./importFactory.ts`
+    // — kept out of this file because they need to import `Table` /
+    // field types that themselves import `Action`. Lazy-import inside
+    // the handler avoids the cycle (handlers run at request-time, well
+    // after module load).
+    /** Header-placement export — downloads the table as CSV (default) or
+     *  JSON. Visibility defaults to `R.canViewAny(user)`. Drop into
+     *  `headerActions([...])` from inside `Resource.table()`. See
+     *  `docs/plans/import-export-actions.md` for the full options bag. */
+    static export(R, _basePath, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    opts = {}) {
+        return Action.make('export')
+            .label('Export')
+            .handler(async (ctx) => {
+            const ef = await import('./exportFactory.js');
+            const tableInst = R.table?.(await loadTableClass());
+            if (!tableInst) {
+                return { notify: { title: 'Export not configured (resource has no table())', type: 'error' } };
+            }
+            const cols = ef.resolveExportColumns(opts.columns, R);
+            if (cols.length === 0) {
+                return { notify: { title: 'Export has no columns', type: 'error' } };
+            }
+            const maxRows = opts.maxRows ?? 50_000;
+            const records = await ef.collectExportRows(tableInst, ctx, opts.scope ?? 'filtered', maxRows, opts.chunkSize);
+            if (records.length > maxRows) {
+                return { notify: { title: `Export exceeded ${maxRows} rows`, type: 'error' } };
+            }
+            const rows = records.map(r => ef.buildExportRow(r, cols));
+            const format = opts.format ?? 'csv';
+            const { body, contentType } = ef.encodeExport(rows, cols, format);
+            const filename = typeof opts.filename === 'function'
+                ? opts.filename(ctx)
+                : (opts.filename ?? ef.defaultExportFilename(R.getSlug(), format));
+            return { download: { filename, contentType, body } };
+        })
+            .visible(({ user }) => callPredicate(R.canViewAny, user));
+    }
+    /** Bulk-placement export — downloads the rows the user selected via
+     *  the bulk-select checkboxes. Same options as `Action.export` minus
+     *  `scope` (always operates on `ctx.records`). Drop into
+     *  `bulkActions([...])`. */
+    static bulkExport(R, _basePath, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    opts = {}) {
+        return Action.make('bulkExport')
+            .label('Export selected')
+            .bulk()
+            .handler(async (ctx) => {
+            const ef = await import('./exportFactory.js');
+            const cols = ef.resolveExportColumns(opts.columns, R);
+            if (cols.length === 0) {
+                return { notify: { title: 'Export has no columns', type: 'error' } };
+            }
+            const records = ctx.records ?? [];
+            const maxRows = opts.maxRows ?? 50_000;
+            if (records.length > maxRows) {
+                return { notify: { title: `Export exceeded ${maxRows} rows`, type: 'error' } };
+            }
+            const rows = records.map(r => ef.buildExportRow(r, cols));
+            const format = opts.format ?? 'csv';
+            const { body, contentType } = ef.encodeExport(rows, cols, format);
+            const filename = typeof opts.filename === 'function'
+                ? opts.filename(ctx)
+                : (opts.filename ?? ef.defaultExportFilename(R.getSlug(), format));
+            return { download: { filename, contentType, body } };
+        })
+            .visible(({ user }) => callPredicate(R.canViewAny, user));
+    }
+    /** Header-placement import — opens a modal with a `FileUpload` (and a
+     *  Mode select when `upsertBy` is set), parses the uploaded file, and
+     *  walks each row through `R.model.create` / `R.model.update`.
+     *  Visibility defaults to `R.canCreate(user)`. Drop into
+     *  `headerActions([...])` from inside `Resource.table()`. See
+     *  `docs/plans/import-export-actions.md` for the full options bag. */
+    static import(R, _basePath, opts = {}) {
+        const upsertable = typeof opts.upsertBy === 'string' && opts.upsertBy.length > 0;
+        const a = Action.make('import')
+            .label('Import')
+            .modalHeading(`Import ${R.label ?? `${R.labelSingular}s`}`)
+            .modalSubmitLabel('Import')
+            .modalCancelLabel('Cancel')
+            .handler(async (ctx) => {
+            const M = R.model;
+            if (!M || typeof M.create !== 'function') {
+                return { notify: { title: 'Import not configured (resource has no model.create)', type: 'error' } };
+            }
+            if (upsertable && typeof M.update !== 'function') {
+                return { notify: { title: 'Upsert import requires model.update', type: 'error' } };
+            }
+            const fileUrl = String(ctx.values?.['file'] ?? '');
+            if (fileUrl.length === 0) {
+                return { notify: { title: 'No file uploaded', type: 'error' } };
+            }
+            const ifac = await import('./importFactory.js');
+            let text;
+            try {
+                const r = await fetch(fileUrl);
+                if (!r.ok) {
+                    return { notify: { title: `Failed to fetch upload (${r.status})`, type: 'error' } };
+                }
+                text = await r.text();
+            }
+            catch (err) {
+                return { notify: { title: `Failed to read upload: ${err instanceof Error ? err.message : String(err)}`, type: 'error' } };
+            }
+            const format = opts.format ?? (fileUrl.toLowerCase().endsWith('.json') ? 'json' : 'csv');
+            let rows;
+            try {
+                rows = ifac.parseImportText(text, format, opts.columns);
+            }
+            catch (err) {
+                return { notify: { title: `Failed to parse ${format.toUpperCase()}: ${err instanceof Error ? err.message : String(err)}`, type: 'error' } };
+            }
+            const maxRows = opts.maxRows ?? 10_000;
+            if (rows.length > maxRows) {
+                return { notify: { title: `Import too large (${rows.length} > ${maxRows})`, type: 'error' } };
+            }
+            const mode = upsertable && (ctx.values?.['mode'] === 'upsert') ? 'upsert' : 'create';
+            const summary = await ifac.runImport(rows, M, mode, opts, ctx);
+            return { notify: ifac.buildImportNotification(summary, { upsert: upsertable }) };
+        })
+            .visible(({ user }) => callPredicate(R.canCreate, user));
+        // Build the modal-form schema synchronously. importFactory has no
+        // runtime import edge back to Action.ts (only a type-import, erased
+        // at compile time), so the top-of-file static import below is
+        // cycle-free.
+        a.schema(buildImportModalSchema(opts));
+        return a;
+    }
+    // ─── Relation-manager factories (Plan #11 polish) ─────────────
+    //
+    // Mirror `Action.create / edit / delete` but build URLs under the
+    // parent record: `${base}/${parentSlug}/${parentId}/${rel}/...`.
+    // Designed to be called inside `RelationManager.static table()` —
+    // the page-data builder pipes `RelationManagerContext` into that
+    // configurator so users get `basePath`, `parentId`, and the
+    // discovered Related resource without threading them by hand.
+    //
+    // Visibility predicates use `safeManagerPolicy` so the manager's
+    // `canX` (when overridden) wins, otherwise falls through to the
+    // related Resource's `canX`. Throws absorb as `false`.
+    //
+    // `:id` template substitution still happens at render time for row
+    // context — the same mechanism that drives `Action.edit / delete`.
+    // The parent's id is baked into the URL at config time (it's known
+    // upfront from `ctx.parentId`), so `:id` unambiguously refers to
+    // the row's *child* id.
+    /** Relation create-action factory — link to
+     * `${base}/${parentSlug}/${parentId}/${relationship}/create`.
+     *
+     * Visibility delegates to `M.canCreate(user, parentRecord)` (or the
+     * related Resource's `canCreate(user)` when the manager hasn't
+     * overridden). Drop into `headerActions([...])` from inside
+     * `RelationManager.table(table, ctx)`.
+     */
+    static relationCreate(M, ctx) {
+        const labelSingular = M.getLabelSingular();
+        return Action.make('create')
+            .label(`New ${labelSingular}`)
+            .href(`${relationUrlPrefix(ctx)}/create`)
+            .visible(({ user }) => {
+            // M2M managers don't have a per-pivot-row create surface — the
+            // related record is created via its own Resource, then attached
+            // via `relationAttach`. Auto-hide so dropping this factory into
+            // any M2M manager (belongsToMany / morphToMany / morphedByMany)
+            // is a no-op (visible=false) instead of a 404-on-click foot-gun.
+            if (isM2MMode(ctx.mode))
+                return false;
+            return safeManagerPolicy(M, 'canCreate', ctx.related, user, ctx.parentRecord);
+        });
+    }
+    /** Relation edit-action factory — link to
+     * `${base}/${parentSlug}/${parentId}/${relationship}/${recordId ?? ':id'}/edit`.
+     *
+     * Same `recordId` semantics as `Action.edit`: omit for row context
+     * so the renderer substitutes `:id` per row; pass explicitly when
+     * building actions for a single-record context. Visibility delegates
+     * to `M.canEdit(user, child, parentRecord)` with fall-through to the
+     * related Resource's `canEdit(user, record)`.
+     */
+    static relationEdit(M, ctx, recordId) {
+        const id = recordId ?? ':id';
+        return Action.make('edit')
+            .label('Edit')
+            .href(`${relationUrlPrefix(ctx)}/${id}/edit`)
+            .visible(({ user, record }) => {
+            // M2M: per-pivot-row "edit" doesn't exist; users edit the
+            // related record via its own Resource. Auto-hide for every M2M
+            // mode (belongsToMany / morphToMany / morphedByMany).
+            if (isM2MMode(ctx.mode))
+                return false;
+            return safeManagerPolicy(M, 'canEdit', ctx.related, user, ctx.parentRecord, record);
+        });
+    }
+    /** Relation delete-action factory — POST to
+     * `${base}/${parentSlug}/${parentId}/${relationship}/${recordId ?? ':id'}/delete`,
+     * destructive style with a labeled confirmation. Visibility delegates
+     * to `M.canDelete(user, child, parentRecord)` with fall-through to the
+     * related Resource's `canDelete(user, record)`.
+     */
+    static relationDelete(M, ctx, recordId) {
+        const id = recordId ?? ':id';
+        const singular = M.getLabelSingular().toLowerCase();
+        return Action.make('delete')
+            .label('Delete')
+            .destructive()
+            .method('post')
+            .action(`${relationUrlPrefix(ctx)}/${id}/delete`)
+            .confirm(`Delete this ${singular}?`)
+            .visible(async ({ user, record }) => {
+            // M2M: "delete" of the related record is destructive in a way
+            // that "detach" isn't — surface only `relationDetach` on every
+            // M2M manager (belongsToMany / morphToMany / morphedByMany).
+            // Users who genuinely want to delete the related record reach
+            // for `Action.delete(R)` on the related Resource instead.
+            if (isM2MMode(ctx.mode))
+                return false;
+            if (ctx.related?.softDeletes && isTrashed(record, ctx.related))
+                return false;
+            return safeManagerPolicy(M, 'canDelete', ctx.related, user, ctx.parentRecord, record);
+        });
+    }
+    /**
+     * Plan #13 polish — Restore factory for relation managers. POSTs to
+     * `${base}/${parentSlug}/${parentId}/${relationship}/${recordId ?? ':id'}/restore`,
+     * success-styled, no confirm prompt. Auto-hides on live (non-trashed)
+     * rows AND when `M.canRestore` (or related Resource fall-through)
+     * denies. Drop into `recordActions([...])` from `RelationManager.table(table, ctx)`.
+     */
+    static relationRestore(M, ctx, recordId) {
+        const id = recordId ?? ':id';
+        return Action.make('restore')
+            .label('Restore')
+            .color('success')
+            .method('post')
+            .action(`${relationUrlPrefix(ctx)}/${id}/restore`)
+            .visible(async ({ user, record }) => {
+            if (!ctx.related?.softDeletes)
+                return false;
+            if (!isTrashed(record, ctx.related))
+                return false;
+            return safeManagerPolicy(M, 'canRestore', ctx.related, user, ctx.parentRecord, record);
+        });
+    }
+    /**
+     * Plan #13 polish — Force-delete factory for relation managers. POSTs
+     * to `${base}/${parentSlug}/${parentId}/${relationship}/${recordId ?? ':id'}/force-delete`,
+     * destructive style with a permanence-aware confirmation. Auto-hides on
+     * live (non-trashed) rows and when policy denies.
+     */
+    static relationForceDelete(M, ctx, recordId) {
+        const id = recordId ?? ':id';
+        const singular = M.getLabelSingular().toLowerCase();
+        return Action.make('forceDelete')
+            .label('Delete forever')
+            .destructive()
+            .method('post')
+            .action(`${relationUrlPrefix(ctx)}/${id}/force-delete`)
+            .confirm(`Permanently delete this ${singular}? This cannot be undone.`)
+            .visible(async ({ user, record }) => {
+            if (!ctx.related?.softDeletes)
+                return false;
+            if (!isTrashed(record, ctx.related))
+                return false;
+            return safeManagerPolicy(M, 'canForceDelete', ctx.related, user, ctx.parentRecord, record);
+        });
+    }
+    // ─── Relation-manager replicate factories ─────────────────
+    //
+    // Sibling of `Action.replicate / bulkReplicate` scoped to a
+    // RelationManager. Operates on the **related** Resource's model and
+    // **forces** the parent attachment back onto the replica:
+    //
+    // - `hasMany` — re-stamps `<foreignKey> = ctx.parentId` from the
+    //   parent's `static relations[name]` descriptor. Defends against a
+    //   tampered POST body (or a source row loaded from a different
+    //   parent's children) silently re-attaching the new row to a
+    //   different parent.
+    // - `morphMany` — re-stamps `<morphName>Id` + `<morphName>Type` via
+    //   `computeMorphPayload(parentRecord, descriptor)`, same auto-fill
+    //   the relation-create POST handler uses on the create form.
+    // - M2M (`belongsToMany / morphToMany / morphedByMany`) — auto-hides.
+    //   Replicate doesn't fit pivot semantics; users create the related
+    //   record via its own Resource, then attach via `relationAttach`.
+    // - `morphTo` — auto-hides. Child-side polymorphic relations don't
+    //   have a single owner to pin to (the row's existing morph cols
+    //   already point somewhere; cloning is the user's job, not ours).
+    //
+    // Both factories dispatch through the manager-scoped
+    // `_action/:actionName` route already wired in `routes.ts`. The route
+    // resolves `ctx.record` (and `ctx.records` for bulk) via
+    // `Related.model.find(id)`, and stamps `ctx.relation = { parent,
+    // parentId, relationship }` so the handlers can read the live parent
+    // without re-loading.
+    //
+    // Visibility delegates to `safeManagerPolicy(M, 'canCreate', Related,
+    // user, parentRecord)` — the manager's `canCreate` (when overridden)
+    // wins, otherwise falls through to the related Resource's `canCreate`.
+    /**
+     * Relation row-replicate factory. Clones the row's child record
+     * inside the manager's parent scope.
+     *
+     * Strips the related model's primary key, soft-delete column, and
+     * `opts.excludeAttributes`. Re-applies the parent attachment columns
+     * after the strip + before the optional `beforeReplicaSaved` hook,
+     * so user code can still mutate non-FK fields without accidentally
+     * unlinking the replica.
+     *
+     * On success the manager-scoped route falls back to the manager
+     * list URL (`${base}/${parentSlug}/${parentId}/${relationship}`)
+     * because no explicit `redirect` is returned — same default as the
+     * other handler-style relation factories.
+     *
+     * `recordId` kept in the signature for parity with the rest of the
+     * relation factory family. The dispatcher resolves the source row
+     * from the request body, so it isn't referenced here.
+     */
+    static relationReplicate(M, ctx, recordId, opts = {}) {
+        void recordId;
+        return Action.make('relationReplicate')
+            .label('Replicate')
+            .row()
+            .handler(async (hctx) => {
+            const result = await runRelationReplicateRow(M, ctx, hctx, opts);
+            return result;
+        })
+            .visible(({ user }) => {
+            if (isM2MMode(ctx.mode) || ctx.mode === 'morphTo')
+                return false;
+            return safeManagerPolicy(M, 'canCreate', ctx.related, user, ctx.parentRecord);
+        });
+    }
+    /**
+     * Bulk sibling — replicates every selected child row inside the
+     * manager's parent scope. Same strip + force-pin pipeline applied
+     * per row. Per-row `safeManagerPolicy(M, 'canCreate', …)` runs
+     * inside the loop so a partially-permitted selection still proceeds
+     * for the rows that pass. Rows that throw are skipped silently —
+     * the toast count reflects only successful creates.
+     */
+    static relationBulkReplicate(M, ctx, opts = {}) {
+        return Action.make('relationBulkReplicate')
+            .label('Replicate selected')
+            .bulk()
+            .confirm(`Replicate the selected ${M.getLabel().toLowerCase()}?`)
+            .handler(async (hctx) => {
+            const Related = ctx.related;
+            if (!Related?.model || typeof Related.model.create !== 'function') {
+                return { notify: { title: 'Replicate not configured (related Resource has no model.create)', type: 'error' } };
+            }
+            const records = hctx.records ?? [];
+            let n = 0;
+            for (const source of records) {
+                if (!source || typeof source !== 'object')
+                    continue;
+                const allowed = await safeManagerPolicy(M, 'canCreate', Related, hctx.user, ctx.parentRecord);
+                if (!allowed)
+                    continue;
+                try {
+                    await persistRelationReplica(M, ctx, source, opts);
+                    n++;
+                }
+                catch { /* skip — agg notify shows total */ }
+            }
+            const labelPlural = M.getLabel().toLowerCase();
+            const labelSingular = M.getLabelSingular().toLowerCase();
+            const defaultTitle = `${n} ${n === 1 ? labelSingular : labelPlural} replicated`;
+            const overrideTitle = opts.getCreatedNotificationTitle
+                ? await opts.getCreatedNotificationTitle({ count: n, records })
+                : undefined;
+            const title = overrideTitle !== undefined ? overrideTitle : defaultTitle;
+            return {
+                notify: { title, type: 'success' },
+            };
+        })
+            .visible(({ user }) => {
+            if (isM2MMode(ctx.mode) || ctx.mode === 'morphTo')
+                return false;
+            return safeManagerPolicy(M, 'canCreate', ctx.related, user, ctx.parentRecord);
+        });
+    }
+    // ─── M2M relation factories ───────────────────────────────
+    //
+    // Sibling of `relationCreate / Edit / Delete` for every M2M mode
+    // (`belongsToMany`, `morphToMany` (owning polymorphic side),
+    // `morphedByMany` (inverse polymorphic side)). All three modes share
+    // the same `attach` / `detach` / `sync` accessor surface — the rudder
+    // ORM stamps + filters the polymorphic discriminator on the morph
+    // variants automatically, so pilotiq's pivot factories are mode-agnostic
+    // beyond the visibility gate.
+    //
+    // Three factories: `relationAttach` (header, modal-form picker →
+    // POST `_action/relationAttach`), `relationDetach` (row, direct POST
+    // to `_detach/:childId`), `relationBulkDetach` (bulk, handler-
+    // dispatched). The first and third route through the manager-scoped
+    // `_action/:actionName` endpoint (added in routes.ts) so handlers
+    // see `ctx.relation = { parent, parentId, relationship }`.
+    //
+    // All three auto-hide outside any M2M mode so dropping a factory into
+    // a non-M2M manager is a no-op (visible=false) instead of a confusing
+    // 404.
+    /** Header-placement attach factory — opens a modal with a SelectField
+     *  listing related records that aren't already attached, and POSTs the
+     *  selected id to the manager's `_action/relationAttach` endpoint.
+     *
+     *  Visibility delegates to `M.canAttach(user, parentRecord)` AND
+     *  guards against being dropped into a non-M2M manager. */
+    static relationAttach(M, ctx) {
+        const labelSingular = M.getLabelSingular();
+        const a = Action.make('relationAttach')
+            .label(`Attach ${labelSingular}`)
+            .header()
+            .modalHeading(`Attach ${labelSingular}`)
+            .modalSubmitLabel('Attach')
+            .modalCancelLabel('Cancel')
+            .handler(async (hctx) => {
+            const rel = hctx.relation;
+            if (!rel) {
+                return { notify: { title: 'Attach handler missing parent context — manager-scoped _action route not wired', type: 'error' } };
+            }
+            const Related = ctx.related;
+            if (!Related?.model) {
+                return { notify: { title: 'Cannot attach: related Resource has no model', type: 'error' } };
+            }
+            const idStr = String(hctx.values?.['_attachId'] ?? '');
+            if (idStr.length === 0) {
+                return { notify: { title: 'Pick a record to attach', type: 'error' } };
+            }
+            const accessor = resolveM2MAccessor(rel.parent, rel.relationship);
+            if (!accessor || typeof accessor.attach !== 'function') {
+                return { notify: { title: `Pivot accessor missing on ${rel.relationship} — wrong relation type or ORM version?`, type: 'error' } };
+            }
+            try {
+                await accessor.attach([idStr]);
+            }
+            catch (err) {
+                return { notify: { title: `Attach failed: ${err instanceof Error ? err.message : String(err)}`, type: 'error' } };
+            }
+            return { notify: { title: `${labelSingular} attached`, type: 'success' } };
+        })
+            .visible(({ user }) => {
+            if (!isM2MMode(ctx.mode))
+                return false;
+            return safeManagerPolicy(M, 'canAttach', ctx.related, user, ctx.parentRecord);
+        });
+        // Build the modal-form schema only when this is actually an M2M
+        // manager — non-M2M drops keep the action hidden via the visibility
+        // predicate, but still need a schema-less Action so the meta walker
+        // doesn't blow up. Static import is fine: `attachFactory` only
+        // depends on `SelectField` + ORM helpers, no cycle back to Action.
+        if (isM2MMode(ctx.mode) && ctx.related?.model) {
+            a.schema(buildAttachModalSchema({
+                Related: ctx.related,
+                relationship: ctx.relationship,
+                recordTitleAttr: M.getRecordTitleAttribute() ?? ctx.related.recordTitleAttribute,
+                labelSingular,
+            }));
+        }
+        return a;
+    }
+    /** Row-placement detach factory — POSTs to
+     *  `${base}/${parentSlug}/${parentId}/${relationship}/${recordId ?? ':id'}/_detach`,
+     *  destructive style with a confirmation prompt that says "Detach"
+     *  (not "Delete") so users understand the target record stays.
+     *  Visibility delegates to `M.canDetach`. */
+    static relationDetach(M, ctx, recordId) {
+        const id = recordId ?? ':id';
+        const singular = M.getLabelSingular().toLowerCase();
+        return Action.make('relationDetach')
+            .label('Detach')
+            .destructive()
+            .method('post')
+            .action(`${relationUrlPrefix(ctx)}/${id}/_detach`)
+            .confirm(`Detach this ${singular}? The ${singular} record stays in place; only the link is removed.`)
+            .visible(async ({ user, record }) => {
+            if (!isM2MMode(ctx.mode))
+                return false;
+            return safeManagerPolicy(M, 'canDetach', ctx.related, user, ctx.parentRecord, record);
+        });
+    }
+    /** Bulk-placement bulk-detach factory — handler-dispatched. Calls
+     *  `parent.related(rel).detach(ids)` for the selected rows. Visibility
+     *  delegates to `M.canAttach` (acts like a "manager admin" gate; we
+     *  intentionally don't enforce per-row `canDetach` on the visibility
+     *  side because the bulk button needs to be visible before the user
+     *  has selected anything — per-row gating happens inside the handler). */
+    static relationBulkDetach(M, ctx) {
+        const labelPlural = M.getLabel().toLowerCase();
+        return Action.make('relationBulkDetach')
+            .label('Detach selected')
+            .destructive()
+            .bulk()
+            .confirm(`Detach the selected ${labelPlural}? The records stay in place; only the links are removed.`)
+            .handler(async (hctx) => {
+            const rel = hctx.relation;
+            if (!rel) {
+                return { notify: { title: 'Bulk-detach handler missing parent context — manager-scoped _action route not wired', type: 'error' } };
+            }
+            const records = hctx.records ?? [];
+            const ids = [];
+            for (const r of records) {
+                const id = String(r.id ?? '');
+                if (!id)
+                    continue;
+                const allowed = await safeManagerPolicy(M, 'canDetach', ctx.related, hctx.user, ctx.parentRecord, r);
+                if (!allowed)
+                    continue;
+                ids.push(id);
+            }
+            if (ids.length === 0) {
+                return { notify: { title: 'Nothing to detach (no permitted rows)', type: 'warning' } };
+            }
+            const accessor = resolveM2MAccessor(rel.parent, rel.relationship);
+            if (!accessor || typeof accessor.detach !== 'function') {
+                return { notify: { title: `Pivot accessor missing on ${rel.relationship} — wrong relation type or ORM version?`, type: 'error' } };
+            }
+            try {
+                await accessor.detach(ids);
+            }
+            catch (err) {
+                return { notify: { title: `Bulk detach failed: ${err instanceof Error ? err.message : String(err)}`, type: 'error' } };
+            }
+            return { notify: { title: `${ids.length} ${labelPlural} detached`, type: 'success' } };
+        })
+            .visible(({ user }) => {
+            if (!isM2MMode(ctx.mode))
+                return false;
+            // Bulk gate uses canAttach as a stand-in for "manager admin" —
+            // per-row canDetach is enforced inside the handler.
+            return safeManagerPolicy(M, 'canAttach', ctx.related, user, ctx.parentRecord);
+        });
+    }
+    label(l) { this._label = l; return this; }
+    icon(i) { this._icon = i; return this; }
+    // ─── Placement ────────────────────────────────────────
+    placement(p) { this._placement = p; return this; }
+    inline() { return this.placement('inline'); }
+    row() { return this.placement('row'); }
+    bulk() { return this.placement('bulk'); }
+    header() { return this.placement('header'); }
+    // ─── Behavior ─────────────────────────────────────────
+    destructive(v = true) {
+        this._destructive = v;
+        if (v && this._color === undefined)
+            this._color = 'destructive';
+        return this;
+    }
+    /** Set the visual color. `destructive` is also set by `.destructive()`. */
+    color(c) { this._color = c; return this; }
+    /** Set the size preset (sm | md | lg). Default is `md`. */
+    size(s) { this._size = s; return this; }
+    /** Hover tooltip. Wraps the button in a Tooltip primitive. */
+    tooltip(t) { this._tooltip = t; return this; }
+    /** Outlined trigger style — border + transparent bg instead of solid color. */
+    outlined(v = true) { this._outlined = v; return this; }
+    /** Icon-only trigger style. Renders a square button with just the icon;
+     * the label is used as `aria-label`. Requires `.icon()` to be set. */
+    iconButton(v = true) { this._iconOnly = v; return this; }
+    /** Show a small badge on the trigger (e.g. unread count). */
+    badge(value) { this._badge = value; return this; }
+    /** Optional color class for the badge (e.g. 'bg-emerald-500'). */
+    badgeColor(c) { this._badgeColor = c; return this; }
+    // ─── Conditional visibility / disabled ───────────────
+    /** Show the action only when `rule` is truthy. Pair with a function for
+     * record-aware visibility (e.g. `({ record }) => !record.archived`).
+     * Row-placement actions are evaluated per-row at table-load time;
+     * other placements are evaluated at schema-resolve time with the
+     * page-level context. */
+    visible(rule) { this._visible = rule; return this; }
+    /** Inverse of `visible` — hide the action when `rule` is truthy.
+     * Both rules combine via AND: visible if `visible !== false` AND
+     * `hidden !== true`. */
+    hidden(rule) { this._hidden = rule; return this; }
+    /** Disable (render greyed-out and skip dispatch) when `rule` is truthy.
+     * Disabled actions still appear in the UI, unlike hidden ones. */
+    disabled(rule) { this._isDisabled = rule; return this; }
+    /** Policy-style alias for `.visible(fn)` — semantically identical
+     * but reads better when guarding by user permissions. */
+    authorize(rule) { return this.visible(rule); }
+    /** Evaluate the visibility / disabled rules with the given context.
+     * Defaults: visible = true, disabled = false. Both `visible` and
+     * `hidden` are folded in: `visible: visible !== false && hidden !== true`.
+     *
+     * Async to support Plan #10 — visibility rules can return Promise<bool>
+     * (for `Resource.canX(user, record)` integration). Throwing rules are
+     * treated as fail-closed (`visible: false` / `disabled: true`). */
+    async evaluate(ctx = {}) {
+        const evalRule = async (rule, fallback) => {
+            if (rule === undefined)
+                return fallback;
+            if (typeof rule !== 'function')
+                return rule;
+            try {
+                return await rule(ctx);
+            }
+            catch {
+                // Fail closed — a throwing rule shouldn't accidentally show a
+                // destructive action.
+                return !fallback;
+            }
+        };
+        const [visibleRaw, hiddenRaw, disabledRaw] = await Promise.all([
+            evalRule(this._visible, true),
+            evalRule(this._hidden, false),
+            evalRule(this._isDisabled, false),
+        ]);
+        return {
+            visible: visibleRaw && !hiddenRaw,
+            disabled: disabledRaw,
+        };
+    }
+    /** True when any visibility / hidden / disabled rule is set. Useful for
+     * the resolver to know whether per-row evaluation is needed for a
+     * row-placement action. */
+    hasVisibilityRules() {
+        return this._visible !== undefined || this._hidden !== undefined || this._isDisabled !== undefined;
+    }
+    /**
+     * Prompt the user before running the handler. Pass a string for a simple
+     * "are you sure?" message, or an object for full control.
+     */
+    confirm(prompt) {
+        this._confirm = typeof prompt === 'string' ? { message: prompt } : prompt;
+        return this;
+    }
+    /**
+     * Server-side handler. Two shapes:
+     *
+     * - **Closure** — `handler(async ctx => …)`. Dispatched against the
+     *   current page's `_action/:name` endpoint. Closures don't survive
+     *   serialization, so they can't ride a persisted notification —
+     *   `Notification.toDatabase()` rejects them with a clear error.
+     *
+     * - **Registry key** — `handler('archive-project')`. Looked up against
+     *   `Pilotiq.notificationHandlers({…})` at request time. Round-trips
+     *   through a `Notification`'s `data.actions` JSON column, so this is
+     *   the path to take when an action lives on a row that may be
+     *   clicked days later.
+     *
+     * Mutually exclusive — setting one clears the other.
+     */
+    handler(fnOrName) {
+        if (typeof fnOrName === 'string') {
+            this._handlerName = fnOrName;
+            delete this._handler;
+        }
+        else {
+            this._handler = fnOrName;
+            delete this._handlerName;
+        }
+        return this;
+    }
+    /**
+     * Per-fire context for registry-handler dispatch. JSON-serializable
+     * keys only — values flow through the notification's `data.actions`
+     * column and arrive on the handler's `ctx.payload`.
+     *
+     *   Action.make('archive')
+     *     .handler('archive-project')
+     *     .payload({ projectId: 123 })
+     */
+    payload(data) {
+        this._payload = data;
+        return this;
+    }
+    /**
+     * Filament-style chain modifier — when this action lives inside a
+     * `Notification.actions([…])` slot, firing it also flips the
+     * notification's `read_at`. No-op for actions used outside the
+     * notification context (Resource actions, etc).
+     *
+     *   Action.make('view').url('/projects/123').markAsRead()
+     *
+     * On url/post actions the bell client fires the read POST as a
+     * client-side side-effect *before* navigating/submitting; on
+     * registry-handler actions the route flips `read_at` server-side
+     * after the handler runs (one round-trip, not two).
+     */
+    markAsRead(v = true) {
+        this._markAsReadOnFire = v;
+        return this;
+    }
+    /**
+     * Open the action's url in a new tab. Honored by the notification
+     * action-strip renderers; equivalent to `target="_blank"` on the
+     * underlying anchor.
+     */
+    openUrlInNewTab(v = true) {
+        this._openUrlInNewTab = v;
+        return this;
+    }
+    // ─── Modal / form-modal action ────────────────────────
+    /**
+     * Attach a form schema that opens in a modal Dialog when the action is
+     * triggered. The submitted values flow through validation + coercion
+     * server-side and arrive on the handler's `ctx.values`. Triggers modal
+     * chrome (heading / submit button / cancel button) if not configured
+     * via the other modal builders below.
+     */
+    schema(elements) {
+        this._children = elements;
+        this._hasModal = true;
+        return this;
+    }
+    modalHeading(s) { this._modalHeading = s; this._hasModal = true; return this; }
+    modalDescription(s) { this._modalDescription = s; this._hasModal = true; return this; }
+    modalSubmitLabel(s) { this._modalSubmitLabel = s; this._hasModal = true; return this; }
+    modalCancelLabel(s) { this._modalCancelLabel = s; this._hasModal = true; return this; }
+    /** Filament v5 alias for `modalSubmitLabel`. Reads more naturally
+     *  alongside `modalCancelActionLabel` when both are set. */
+    modalSubmitActionLabel(s) { return this.modalSubmitLabel(s); }
+    /** Filament v5 alias for `modalCancelLabel`. */
+    modalCancelActionLabel(s) { return this.modalCancelLabel(s); }
+    modalIcon(i) { this._modalIcon = i; this._hasModal = true; return this; }
+    modalIconColor(c) {
+        this._modalIconColor = c;
+        this._hasModal = true;
+        return this;
+    }
+    modalWidth(w) { this._modalWidth = w; this._hasModal = true; return this; }
+    modalAlignment(a) {
+        this._modalAlignment = a;
+        this._hasModal = true;
+        return this;
+    }
+    slideOver(v = true) { this._slideOver = v; this._hasModal = true; return this; }
+    /**
+     * Disable / re-enable closing the modal by clicking outside the popup.
+     * Default: enabled. Calling without an arg disables (matches Filament's
+     * `->closeModalByClickingAway(false)` shape — most uses are to gate
+     * accidental dismissal of important modals).
+     */
+    closeModalByClickingAway(v = false) {
+        this._closeModalByClickingAway = v;
+        this._hasModal = true;
+        return this;
+    }
+    /**
+     * Disable / re-enable closing the modal with the Escape key. Default:
+     * enabled. Same shape as `closeModalByClickingAway`. Useful when a
+     * partially-completed multi-step modal would lose work on a stray Esc.
+     */
+    closeModalByEscaping(v = false) {
+        this._closeModalByEscaping = v;
+        this._hasModal = true;
+        return this;
+    }
+    /** Sticky header inside the modal body. Useful when the body scrolls
+     *  past the heading on long forms. Default: off. */
+    stickyModalHeader(v = true) {
+        this._stickyModalHeader = v;
+        this._hasModal = true;
+        return this;
+    }
+    /** Sticky footer inside the modal body. Pairs naturally with
+     *  `stickyModalHeader` on long forms — keeps the Submit / Cancel
+     *  buttons visible while the user scrolls. Default: off. */
+    stickyModalFooter(v = true) {
+        this._stickyModalFooter = v;
+        this._hasModal = true;
+        return this;
+    }
+    /**
+     * Override the default autofocus behaviour. `true` focuses the first
+     * form input on mount (or the submit button when there is no form);
+     * `false` disables autofocus entirely. Omit to keep the legacy default
+     * (submit button autofocuses for confirm-only modals).
+     */
+    modalAutofocus(v = true) {
+        this._modalAutofocus = v;
+        this._hasModal = true;
+        return this;
+    }
+    /** Render an X close button in the top-right corner of the popup.
+     *  Default: off (the Cancel button in the footer is the documented
+     *  affordance). Useful for slide-over panels where the footer is
+     *  far from the top of the viewport. */
+    modalCloseButton(v = true) {
+        this._modalCloseButton = v;
+        this._hasModal = true;
+        return this;
+    }
+    // ─── Link / form modes ────────────────────────────────
+    /**
+     * Render this action as a link to `url`. Mutually exclusive with
+     * `.method()` — setting `href` clears any prior method/action URL.
+     */
+    href(url) {
+        this._href = url;
+        delete this._method;
+        delete this._actionUrl;
+        return this;
+    }
+    /**
+     * Sugar alias for `.href(url)` — matches Filament's `->url(...)` API
+     * and reads more naturally inside `Notification.actions([…])`.
+     */
+    url(href) { return this.href(href); }
+    /**
+     * Render this action as a form-style submit button using `method`. Pair
+     * with `.action(url)` to set the form's action URL — falls back to the
+     * current page URL otherwise.
+     */
+    method(m) {
+        this._method = m;
+        delete this._href;
+        return this;
+    }
+    /** Form action URL — only meaningful when `.method()` is set. */
+    action(url) {
+        this._actionUrl = url;
+        delete this._href;
+        return this;
+    }
+    /**
+     * Render-time URL the client should POST to when invoking this
+     * action's handler. Set by the route registrar — users don't normally
+     * call this directly. Format: `${pageUrl}/_action/${action.name}`.
+     */
+    dispatchUrl(url) {
+        this._dispatchUrl = url;
+        return this;
+    }
+    /**
+     * Mark this action as the form-submit button for its enclosing
+     * `<form>`. Renders as `<button type="submit">` and relies on the form
+     * itself to carry `action` + `method`. Mutually exclusive with
+     * `.href()` / `.method()` / handler-style.
+     */
+    submit() {
+        this._submit = true;
+        delete this._href;
+        delete this._method;
+        delete this._actionUrl;
+        delete this._dispatchUrl;
+        return this;
+    }
+    /**
+     * Target a specific `<form id="">` when this is a submit action — uses
+     * the HTML `form` attribute so the button can submit a form it doesn't
+     * live inside. Required when the submit action sits in the page
+     * header (outside the form's DOM subtree).
+     */
+    form(formId) {
+        this._formTarget = formId;
+        return this;
+    }
+    /**
+     * Attach a `name`+`value` pair to a submit button so it round-trips
+     * through the form body when this specific button is clicked. Wires
+     * the "Create & create another" pattern: the secondary submit posts
+     * `{ _continueCreate: '1' }` and the server routes the redirect back
+     * to the create page. Browsers natively only include the clicked
+     * submit button's name/value in `FormData`; the FormRenderer threads
+     * `event.submitter` into the `FormData` constructor to preserve that.
+     */
+    formField(name, value = '1') {
+        this._formField = { name, value };
+        return this;
+    }
+    // ─── Getters ──────────────────────────────────────────
+    getLabel() { return this._label; }
+    getPlacement() { return this._placement; }
+    isDestructive() { return this._destructive; }
+    getHandler() { return this._handler; }
+    /** Registry key set by `.handler(string)`; undefined when the handler
+     *  is a closure (or unset). Mutually exclusive with `getHandler()`. */
+    getHandlerName() { return this._handlerName; }
+    /** Per-fire context set by `.payload({…})`. Empty `{}` when unset
+     *  (callers can spread without a null check). */
+    getPayload() { return this._payload ?? {}; }
+    /** Filament chain modifier — true when `.markAsRead()` was called.
+     *  Read by `Notification.actions([…])` serializer; ignored elsewhere. */
+    isMarkAsReadOnFire() { return this._markAsReadOnFire; }
+    /** Honored by the notification action-strip renderers; equivalent to
+     *  `target="_blank"` on the underlying anchor. */
+    isOpenUrlInNewTab() { return this._openUrlInNewTab; }
+    getHref() { return this._href; }
+    getMethod() { return this._method; }
+    getActionUrl() { return this._actionUrl; }
+    getDispatchUrl() { return this._dispatchUrl; }
+    isSubmit() { return this._submit; }
+    getFormTarget() { return this._formTarget; }
+    getFormField() { return this._formField; }
+    hasModal() { return this._hasModal; }
+    /** Schema fields stored as children; `getChildren()` returns the same. */
+    getSchema() { return this._children ?? []; }
+    getColor() { return this._color; }
+    getIcon() { return this._icon; }
+    getSize() { return this._size; }
+    getTooltip() { return this._tooltip; }
+    isOutlined() { return this._outlined; }
+    isIconOnly() { return this._iconOnly; }
+    getBadge() { return this._badge; }
+    // ─── Element contract ────────────────────────────────
+    getType() { return 'action'; }
+    toMeta() {
+        const modal = this._hasModal ? {
+            ...(this._modalHeading !== undefined ? { heading: this._modalHeading } : {}),
+            ...(this._modalDescription !== undefined ? { description: this._modalDescription } : {}),
+            ...(this._modalSubmitLabel !== undefined ? { submitLabel: this._modalSubmitLabel } : {}),
+            ...(this._modalCancelLabel !== undefined ? { cancelLabel: this._modalCancelLabel } : {}),
+            ...(this._modalIcon !== undefined ? { icon: this._modalIcon } : {}),
+            ...(this._modalIconColor !== undefined ? { iconColor: this._modalIconColor } : {}),
+            ...(this._modalWidth !== undefined ? { width: this._modalWidth } : {}),
+            ...(this._modalAlignment !== undefined ? { alignment: this._modalAlignment } : {}),
+            ...(this._slideOver ? { slideOver: true } : {}),
+            // Boolean defaults are emitted only when the user has flipped them
+            // away from the default — keeps the wire-shape unchanged for the
+            // common case (no setter ever called).
+            ...(this._closeModalByClickingAway === false ? { closeByClickingAway: false } : {}),
+            ...(this._closeModalByEscaping === false ? { closeByEscaping: false } : {}),
+            ...(this._stickyModalHeader ? { stickyHeader: true } : {}),
+            ...(this._stickyModalFooter ? { stickyFooter: true } : {}),
+            ...(this._modalCloseButton ? { closeButton: true } : {}),
+            ...(this._modalAutofocus !== undefined ? { autofocus: this._modalAutofocus } : {}),
+        } : undefined;
+        return {
+            type: 'action',
+            name: this.name,
+            label: this._label,
+            placement: this._placement,
+            destructive: this._destructive,
+            ...(this._icon ? { icon: this._icon } : {}),
+            ...(this._confirm ? { confirm: this._confirm } : {}),
+            ...(this._href ? { href: this._href } : {}),
+            ...(this._method ? { method: this._method } : {}),
+            ...(this._actionUrl ? { action: this._actionUrl } : {}),
+            ...(this._dispatchUrl ? { dispatchUrl: this._dispatchUrl } : {}),
+            ...(this._submit ? { submit: true } : {}),
+            ...(this._formTarget ? { form: this._formTarget } : {}),
+            ...(this._formField ? { formField: this._formField } : {}),
+            ...(modal ? { modal } : {}),
+            ...(this._color ? { color: this._color } : {}),
+            ...(this._size ? { size: this._size } : {}),
+            ...(this._tooltip ? { tooltip: this._tooltip } : {}),
+            ...(this._outlined ? { outlined: true } : {}),
+            ...(this._iconOnly ? { iconOnly: true } : {}),
+            ...(this._badge !== undefined ? { badge: this._badge } : {}),
+            ...(this._badgeColor ? { badgeColor: this._badgeColor } : {}),
+            ...(this.hasVisibilityRules() ? { conditional: true } : {}),
+        };
+    }
+}
+//# sourceMappingURL=Action.js.map