@pilotiq/pilotiq 0.1.0

package/dist/actions/Action.d.ts

@@ -0,0 +1,888 @@
+import { Element, type ElementMeta } from '../schema/Element.js';
+import type { ValidationErrors } from '../validation/index.js';
+import type { Notification, NotificationMeta } from '../notifications/Notification.js';
+import { type RelationManager, type RelationManagerContext } from '../RelationManager.js';
+/**
+ * Where an Action renders. `inline` is the default — appears wherever the
+ * Action sits in the schema tree (e.g. a button inside a Card). The other
+ * three are list-page patterns:
+ *  - `header` — top-right of a resource list (e.g. "Create new")
+ *  - `bulk`   — appears in the action bar when rows are selected
+ *  - `row`    — per-row dropdown menu entry
+ */
+export type ActionPlacement = 'inline' | 'bulk' | 'row' | 'header';
+/**
+ * Context handed to an Action's handler at dispatch time. `record` is set
+ * for row/inline actions that operate on a single entity; `records` is set
+ * for bulk actions. `values` carries any additional payload submitted with
+ * the action (useful when an action has its own confirmation dialog form).
+ * `request` is the raw `AppRequest` for handlers that need direct access
+ * (auth, headers, etc).
+ */
+export interface ActionContext {
+    record?: unknown;
+    records?: unknown[];
+    user?: unknown;
+    values?: Record<string, unknown>;
+    request?: unknown;
+    /**
+     * Row-scoped context populated when this action was dispatched as a
+     * Repeater / Builder `extraItemActions` button. `index` is the row's
+     * 0-based position; `id` is the row's stable `__id`; `values` is the
+     * row's submitted fields (the row's `data` body inside Builder); for
+     * Builder, `blockType` carries the matched block name. `fieldName`
+     * is the parent Repeater/Builder field's name — useful when a single
+     * handler is shared across multiple repeater fields.
+     *
+     * Always undefined for non-row actions. Handlers that don't care about
+     * row context just ignore this field.
+     */
+    row?: {
+        index: number;
+        id: string;
+        values: Record<string, unknown>;
+        fieldName: string;
+        blockType?: string;
+    };
+    /**
+     * Stamped by the manager-scoped `_action` route when an action is
+     * dispatched from a `RelationManager`'s table. Carries the freshly-
+     * loaded parent record + relationship key so handlers can call
+     * `parent.related(name).attach(...) / detach(...) / sync(...)`
+     * (rudder ORM accessor) without re-loading the parent themselves.
+     *
+     * Always undefined for resource-level / page-level / dashboard
+     * dispatch. M2M-aware factories (`relationAttach / relationDetach /
+     * relationBulkDetach`) consult this and `notify` an error when it's
+     * missing — that means the action got dispatched outside the manager
+     * scope (misconfiguration).
+     */
+    relation?: {
+        parent: unknown;
+        parentId: string;
+        relationship: string;
+    };
+}
+/** Convenience type: handlers can return either a built `Notification`
+ * instance, its serialized meta, or arrays of either. */
+export type NotificationLike = Notification | NotificationMeta | ReadonlyArray<Notification | NotificationMeta>;
+/** Download envelope a handler can return to ask the route layer to
+ *  stream a file back instead of issuing the standard JSON / 303
+ *  response. Used by `Action.export / Action.bulkExport`; any handler
+ *  is free to return one. The route writes `Content-Type` +
+ *  `Content-Disposition: attachment; filename="…"` and ends with
+ *  `body`; the client renderer detects the disposition header and
+ *  triggers a browser download via a synthesized `<a download>`. */
+export interface DownloadEnvelope {
+    filename: string;
+    contentType: string;
+    body: string;
+}
+/**
+ * Result a handler may return to influence the response. `void` is the
+ * default — the dispatcher 303-redirects to the page the action was
+ * triggered from. Returning `{ redirect }` overrides that with an
+ * explicit URL. Returning `{ notify }` flashes one or more toast
+ * notifications on the next render. Returning `{ download }` triggers
+ * a file download (mutually exclusive with `redirect` — the route
+ * prefers the download branch when both are set). Throw an Error to
+ * surface as a 500 with the message.
+ */
+export type ActionResult = void | {
+    redirect?: string;
+    notify?: NotificationLike;
+    download?: DownloadEnvelope;
+};
+export type ActionHandler = (ctx: ActionContext) => ActionResult | Promise<ActionResult>;
+/**
+ * A confirmation prompt shown before the handler runs. A bare string is
+ * shorthand for `{ message: string }`; the object form lets callers
+ * override the dialog title and confirm-button label.
+ */
+export interface ActionConfirm {
+    title?: string;
+    message: string;
+    confirmLabel?: string;
+}
+/** HTTP method for form-style actions. `'get'` is implied by `.href()`; the
+ *  others spawn a `<form>`-wrapped submit button at render time. */
+export type ActionMethod = 'post' | 'put' | 'patch' | 'delete';
+/** Visual color preset. Maps to a tailwind class group at render time.
+ * `destructive` is what `Action.destructive()` sugar sets; the other
+ * presets exist so users can opt-in explicitly. */
+export type ActionColor = 'primary' | 'destructive' | 'success' | 'warning' | 'info' | 'ghost';
+/** Visual size preset. Maps to button height + padding + text size. */
+export type ActionSize = 'sm' | 'md' | 'lg';
+/** Context passed to visibility / disabled callbacks. `record` is set
+ * for single-target evaluation (row actions, edit-page header actions);
+ * `records` for bulk evaluations; `user` from the request when wired.
+ *
+ * `values` is populated only when this action is being evaluated inside
+ * a Repeater / Builder row at meta-build time (via `extraItemActions`).
+ * It mirrors the resolver's row-scoped values map — predicates branch
+ * on the row's submitted fields (e.g. `({ values }) => values.status !==
+ * 'archived'`). */
+export interface ActionVisibilityContext {
+    record?: unknown;
+    records?: unknown[];
+    user?: unknown;
+    values?: Record<string, unknown>;
+}
+/** Boolean-or-callback rule used by `.visible()` / `.hidden()` /
+ * `.disabled()`. Boolean values short-circuit; functions receive the
+ * evaluation context and return the result (sync or async).
+ *
+ * Async support landed with Plan #10 authorization — `Resource.canEdit`
+ * etc. return Promise<boolean>, and the `Action.create/edit/view/delete`
+ * factories install those predicates as visibility rules. Sync rules
+ * keep working unchanged; the awaiter coerces both. */
+export type VisibilityRule = boolean | ((ctx: ActionVisibilityContext) => boolean | Promise<boolean>);
+/** Modal width preset — maps to a max-width class on the Dialog popup. */
+export type ActionModalWidth = 'sm' | 'md' | 'lg' | 'xl';
+/** Horizontal alignment applied to the modal's header / body / footer
+ *  text. Matches Filament v5's `modalAlignment()` (start / center / end). */
+export type ActionModalAlignment = 'start' | 'center' | 'end';
+/** Color preset for the icon shown next to the modal heading. Mirrors
+ *  `BadgeColor` so userspace doesn't have to learn another scale. */
+export type ActionModalIconColor = 'gray' | 'primary' | 'success' | 'warning' | 'destructive' | 'info';
+/** Context shape passed to `ReplicateOptions.getCreatedNotificationTitle`.
+ *  Single-row factories (`replicate`, `relationReplicate`) populate
+ *  `replica` (the just-created record returned by `M.create`) and
+ *  `source` (the original row). Bulk factories (`bulkReplicate`,
+ *  `relationBulkReplicate`) populate `count` (number of successful
+ *  creates) and `records` (the original selected rows). The opposite
+ *  fields are always undefined for the other call site so consumers
+ *  can branch on whichever is set. */
+export interface ReplicateNotificationContext {
+    replica?: unknown;
+    source?: unknown;
+    count?: number;
+    records?: unknown[];
+}
+/** Context shape passed to `ReplicateOptions.getRedirectUrl`. Single-row
+ *  factories only — bulk variants stay on the list / manager URL
+ *  regardless. `replica` is the freshly-created record; `source` is
+ *  the original. */
+export interface ReplicateRedirectContext {
+    replica: unknown;
+    source: unknown;
+}
+/** Options bag for `Action.replicate` and its three siblings
+ *  (`bulkReplicate`, `relationReplicate`, `relationBulkReplicate`).
+ *  Every field optional. */
+export interface ReplicateOptions {
+    /** Attribute names to drop from the replicated payload IN ADDITION TO
+     *  the always-stripped primary key + soft-delete column. Useful for
+     *  unique columns the source row holds (e.g. `slug`, `email`) so the
+     *  duplicate doesn't trip a unique constraint on save. */
+    excludeAttributes?: ReadonlyArray<string>;
+    /** Mutate the prepared replica before it's persisted. Receives the
+     *  already-stripped attributes plus the source record; must return the
+     *  attributes to persist (mutate or replace). Useful for stamping
+     *  "Copy of" prefixes onto a name column, regenerating slugs, etc. */
+    beforeReplicaSaved?: (replica: Record<string, unknown>, source: unknown) => Record<string, unknown> | Promise<Record<string, unknown>>;
+    /** Override the success notification title. Single-row factories
+     *  receive `{ replica, source }`; bulk factories receive
+     *  `{ count, records }` (`replica`/`source` undefined). Return a
+     *  string to use it; return `undefined` to fall back to the default
+     *  (`"${labelSingular} replicated"` for single-row,
+     *  `"${count} ${label(s)} replicated"` for bulk). Sync or async. */
+    getCreatedNotificationTitle?: (ctx: ReplicateNotificationContext) => string | undefined | Promise<string | undefined>;
+    /** Override the redirect URL. Single-row factories only — bulk
+     *  variants don't redirect. Receives `{ replica, source }`. Return a
+     *  string to use it; return `undefined` to fall back to the default
+     *  (the new record's edit page for `replicate`; the manager list
+     *  URL for `relationReplicate`, owned by the route layer). Sync or
+     *  async. */
+    getRedirectUrl?: (ctx: ReplicateRedirectContext) => string | undefined | Promise<string | undefined>;
+}
+/** Structural shape of a Resource class for the factory functions —
+ * matches `Resource.ts` exactly but keeps Action.ts free of an import
+ * cycle. The optional fields are the Plan #10 policy predicates; their
+ * defaults (return `true`) mean missing methods are equivalent to
+ * "always allowed." */
+interface ResourceLike {
+    labelSingular: string;
+    /** Plural label. When unset, factories fall back to
+     *  `${labelSingular}s` (naive). Used by bulk-action notification
+     *  copy so "1 Post" / "5 Posts" render correctly. */
+    label?: string;
+    getSlug(): string;
+    /** Cluster the resource belongs to, when registered via `Pilotiq.clusters`.
+     *  Action factories thread the cluster slug into URL builders so
+     *  `${basePath}/<cluster>/<slug>/...` round-trips correctly. */
+    cluster?: {
+        getSlug(): string;
+    };
+    /** Plan #13 — soft-delete opt-in flag. When true, `Action.delete`
+     *  auto-hides on already-trashed rows; `Action.restore` /
+     *  `Action.forceDelete` auto-show on trashed rows. */
+    softDeletes?: boolean;
+    /** Plan #13 — column name carrying the soft-delete timestamp.
+     *  Defaults to `'deletedAt'` when undefined. */
+    deletedAtColumn?: string;
+    canCreate?(user: unknown): boolean | Promise<boolean>;
+    canEdit?(user: unknown, record: unknown): boolean | Promise<boolean>;
+    canView?(user: unknown, record: unknown): boolean | Promise<boolean>;
+    canViewAny?(user: unknown): boolean | Promise<boolean>;
+    canDelete?(user: unknown, record: unknown): boolean | Promise<boolean>;
+    canRestore?(user: unknown, record: unknown): boolean | Promise<boolean>;
+    canForceDelete?(user: unknown, record: unknown): boolean | Promise<boolean>;
+    /** Resource model adapter (set when the resource opts into auto-CRUD
+     *  via `static model = M`). Import / Export factories need access to
+     *  `create / update / find / query` to drive their writes / reads. */
+    model?: any;
+    /** Resource table configurator. Export factory calls
+     *  `R.table(Table.make())` to discover columns + the records handler
+     *  for the "filtered" / "all" scope. */
+    table?(t: any): any;
+}
+/** Render-time meta for an action that opens a modal (with or without a
+ * form schema). When `meta.children` is also populated by the resolver,
+ * the modal renders those Elements as a form whose values pass through
+ * to the handler as `ctx.values`. */
+export interface ActionModalMeta {
+    heading?: string;
+    description?: string;
+    submitLabel?: string;
+    cancelLabel?: string;
+    icon?: string;
+    /** Color preset applied to the heading icon (`modalIconColor()`).
+     *  Renderer maps to a tailwind text-color class. */
+    iconColor?: ActionModalIconColor;
+    width?: ActionModalWidth;
+    slideOver?: boolean;
+    /** Default `true`; emitted only when the user passed `false`. The
+     *  renderer turns this into Base UI's `disablePointerDismissal`. */
+    closeByClickingAway?: boolean;
+    /** Default `true`; emitted only when `false`. Renderer cancels the
+     *  Base UI `onOpenChange` event when reason is `'escapeKey'`. */
+    closeByEscaping?: boolean;
+    /** Sticky header inside a scrolling modal body. Default `false`. */
+    stickyHeader?: boolean;
+    /** Sticky footer inside a scrolling modal body. Default `false`. */
+    stickyFooter?: boolean;
+    /** Override the default autofocus behaviour. When `false` no element
+     *  inside the modal receives focus on mount; when `true` the renderer
+     *  focuses the first form input (or the submit button when there is
+     *  no form). When omitted, the legacy default applies (the submit
+     *  button autofocuses for confirm-only modals). */
+    autofocus?: boolean;
+    /** Horizontal alignment for the heading / body / footer text. */
+    alignment?: ActionModalAlignment;
+    /** When `true`, an X close-button renders in the top-right of the
+     *  popup. Default `false`. */
+    closeButton?: boolean;
+}
+export interface ActionMeta extends ElementMeta {
+    type: 'action';
+    name: string;
+    label: string;
+    placement: ActionPlacement;
+    destructive: boolean;
+    icon?: string;
+    confirm?: ActionConfirm;
+    href?: string;
+    method?: ActionMethod;
+    action?: string;
+    /** POST URL for handler-style actions. Set server-side by the route
+     * registrar so the client knows where to dispatch. */
+    dispatchUrl?: string;
+    /** True when this action submits its enclosing `<form>` — renders as
+     * `<button type="submit">` and lets the form's `action`/`method`
+     * attributes drive the request. */
+    submit?: boolean;
+    /** When `submit` is true and this id is set, the rendered button uses
+     * the HTML `form="<id>"` attribute so it can submit a form it lives
+     * outside of (e.g. a Save action in the page header). */
+    form?: string;
+    /** When `submit` is true, attach `name`+`value` to the `<button>` so
+     * the clicked button's pair lands in the form body. Used by the
+     * "Create & create another" pattern: a secondary submit posts a
+     * sentinel like `{ _continueCreate: '1' }` that the server reads to
+     * route the redirect back to the create page. */
+    formField?: {
+        name: string;
+        value: string;
+    };
+    /** Modal-style action chrome. Present when `.schema()` and/or any of
+     * the `modalXxx` builders ran. The fields themselves arrive on
+     * `meta.children` via the schema resolver. */
+    modal?: ActionModalMeta;
+    /** Color preset — drives button colors at render time. `destructive`
+     * coincides with `destructive: true` (kept for back-compat). */
+    color?: ActionColor;
+    /** Size preset — drives button height/padding/text-size. */
+    size?: ActionSize;
+    /** Hover tooltip text. Wraps the rendered button in a Tooltip. */
+    tooltip?: string;
+    /** Outlined trigger style — replaces the solid color background with
+     * a border + transparent bg. */
+    outlined?: boolean;
+    /** Icon-only trigger style — hides the label and renders a square
+     * button. Requires `icon` to be set. */
+    iconOnly?: boolean;
+    /** Optional badge shown on the trigger (e.g. unread count). */
+    badge?: string | number;
+    badgeColor?: string;
+    /** Disabled flag set at evaluation time. The trigger renders greyed-out
+     * and skips dispatch when true. */
+    disabled?: boolean;
+    /** True when the action has `.visible()`, `.hidden()`, or `.disabled()`
+     * rules — the row renderer uses this to know whether to consult the
+     * row's `_visibleActions` / `_disabledActions` lookup. Static actions
+     * without rules render unconditionally. */
+    conditional?: boolean;
+}
+/**
+ * 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 declare class Action extends Element {
+    readonly name: string;
+    protected _label: string;
+    protected _icon?: string;
+    protected _placement: ActionPlacement;
+    protected _destructive: boolean;
+    protected _confirm?: ActionConfirm;
+    protected _handler?: ActionHandler;
+    /**
+     * 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.
+     */
+    protected _handlerName?: string;
+    /**
+     * 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`.
+     */
+    protected _payload?: Record<string, unknown>;
+    /**
+     * 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.
+     */
+    protected _markAsReadOnFire: boolean;
+    /**
+     * 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).
+     */
+    protected _openUrlInNewTab: boolean;
+    protected _href?: string;
+    protected _method?: ActionMethod;
+    protected _actionUrl?: string;
+    protected _dispatchUrl?: string;
+    protected _submit: boolean;
+    protected _formTarget?: string;
+    protected _formField?: {
+        name: string;
+        value: string;
+    };
+    protected _hasModal: boolean;
+    protected _modalHeading?: string;
+    protected _modalDescription?: string;
+    protected _modalSubmitLabel?: string;
+    protected _modalCancelLabel?: string;
+    protected _modalIcon?: string;
+    protected _modalIconColor?: ActionModalIconColor;
+    protected _modalWidth?: ActionModalWidth;
+    protected _slideOver: boolean;
+    protected _closeModalByClickingAway: boolean;
+    protected _closeModalByEscaping: boolean;
+    protected _stickyModalHeader: boolean;
+    protected _stickyModalFooter: boolean;
+    protected _modalAutofocus?: boolean;
+    protected _modalAlignment?: ActionModalAlignment;
+    protected _modalCloseButton: boolean;
+    protected _color?: ActionColor;
+    protected _size?: ActionSize;
+    protected _tooltip?: string;
+    protected _outlined: boolean;
+    protected _iconOnly: boolean;
+    protected _badge?: string | number;
+    protected _badgeColor?: string;
+    protected _visible?: VisibilityRule;
+    protected _hidden?: VisibilityRule;
+    protected _isDisabled?: VisibilityRule;
+    private constructor();
+    static make(name: string): Action;
+    /** Create-action factory — link to `${basePath}/${R.slug}/create`.
+     * Auto-hides when `R.canCreate(user)` returns false. */
+    static create(R: ResourceLike, basePath: string): Action;
+    /**
+     * 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: ResourceLike, basePath: string, recordId?: string): Action;
+    /** 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: ResourceLike, basePath: string, recordId?: string): Action;
+    /**
+     * 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: ResourceLike, basePath: string, recordId?: string): Action;
+    /**
+     * 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: ResourceLike, basePath: string, recordId?: string, opts?: ReplicateOptions): Action;
+    /**
+     * 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: ResourceLike, basePath: string, recordId?: string): Action;
+    /**
+     * 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: ResourceLike, basePath: string, recordId?: string): Action;
+    /**
+     * 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: string, notificationId?: string): Action;
+    /** 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: ResourceLike, _basePath: string): Action;
+    /** 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: ResourceLike, _basePath: string): Action;
+    /** 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: ResourceLike, _basePath: string): Action;
+    /**
+     * 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: ResourceLike, _basePath: string, opts?: ReplicateOptions): Action;
+    /** 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: ResourceLike, _basePath: string, opts?: import('./exportFactory.js').ExportOptions): Action;
+    /** 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: ResourceLike, _basePath: string, opts?: Omit<import('./exportFactory.js').ExportOptions, 'scope'>): Action;
+    /** 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: ResourceLike, _basePath: string, opts?: import('./importFactory.js').ImportOptions): Action;
+    /** 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: typeof RelationManager, ctx: RelationManagerContext): Action;
+    /** 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: typeof RelationManager, ctx: RelationManagerContext, recordId?: string): Action;
+    /** 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: typeof RelationManager, ctx: RelationManagerContext, recordId?: string): Action;
+    /**
+     * 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: typeof RelationManager, ctx: RelationManagerContext, recordId?: string): Action;
+    /**
+     * 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: typeof RelationManager, ctx: RelationManagerContext, recordId?: string): Action;
+    /**
+     * 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: typeof RelationManager, ctx: RelationManagerContext, recordId?: string, opts?: ReplicateOptions): Action;
+    /**
+     * 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: typeof RelationManager, ctx: RelationManagerContext, opts?: ReplicateOptions): Action;
+    /** 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: typeof RelationManager, ctx: RelationManagerContext): Action;
+    /** 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: typeof RelationManager, ctx: RelationManagerContext, recordId?: string): Action;
+    /** 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: typeof RelationManager, ctx: RelationManagerContext): Action;
+    label(l: string): this;
+    icon(i: string): this;
+    placement(p: ActionPlacement): this;
+    inline(): this;
+    row(): this;
+    bulk(): this;
+    header(): this;
+    destructive(v?: boolean): this;
+    /** Set the visual color. `destructive` is also set by `.destructive()`. */
+    color(c: ActionColor): this;
+    /** Set the size preset (sm | md | lg). Default is `md`. */
+    size(s: ActionSize): this;
+    /** Hover tooltip. Wraps the button in a Tooltip primitive. */
+    tooltip(t: string): this;
+    /** Outlined trigger style — border + transparent bg instead of solid color. */
+    outlined(v?: boolean): 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?: boolean): this;
+    /** Show a small badge on the trigger (e.g. unread count). */
+    badge(value: string | number): this;
+    /** Optional color class for the badge (e.g. 'bg-emerald-500'). */
+    badgeColor(c: string): this;
+    /** 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: VisibilityRule): 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: VisibilityRule): this;
+    /** Disable (render greyed-out and skip dispatch) when `rule` is truthy.
+     * Disabled actions still appear in the UI, unlike hidden ones. */
+    disabled(rule: VisibilityRule): this;
+    /** Policy-style alias for `.visible(fn)` — semantically identical
+     * but reads better when guarding by user permissions. */
+    authorize(rule: VisibilityRule): this;
+    /** 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`). */
+    evaluate(ctx?: ActionVisibilityContext): Promise<{
+        visible: boolean;
+        disabled: boolean;
+    }>;
+    /** 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(): boolean;
+    /**
+     * 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: string | ActionConfirm): 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: ActionHandler | string): 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: Record<string, unknown>): 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?: boolean): 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?: boolean): this;
+    /**
+     * 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: Element[]): this;
+    modalHeading(s: string): this;
+    modalDescription(s: string): this;
+    modalSubmitLabel(s: string): this;
+    modalCancelLabel(s: string): this;
+    /** Filament v5 alias for `modalSubmitLabel`. Reads more naturally
+     *  alongside `modalCancelActionLabel` when both are set. */
+    modalSubmitActionLabel(s: string): this;
+    /** Filament v5 alias for `modalCancelLabel`. */
+    modalCancelActionLabel(s: string): this;
+    modalIcon(i: string): this;
+    modalIconColor(c: ActionModalIconColor): this;
+    modalWidth(w: ActionModalWidth): this;
+    modalAlignment(a: ActionModalAlignment): this;
+    slideOver(v?: boolean): 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?: boolean): 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?: boolean): this;
+    /** Sticky header inside the modal body. Useful when the body scrolls
+     *  past the heading on long forms. Default: off. */
+    stickyModalHeader(v?: boolean): 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?: boolean): 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?: boolean): 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?: boolean): this;
+    /**
+     * Render this action as a link to `url`. Mutually exclusive with
+     * `.method()` — setting `href` clears any prior method/action URL.
+     */
+    href(url: string): this;
+    /**
+     * Sugar alias for `.href(url)` — matches Filament's `->url(...)` API
+     * and reads more naturally inside `Notification.actions([…])`.
+     */
+    url(href: string): this;
+    /**
+     * 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: ActionMethod): this;
+    /** Form action URL — only meaningful when `.method()` is set. */
+    action(url: string): 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: string): 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;
+    /**
+     * 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: string): 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: string, value?: string): this;
+    getLabel(): string;
+    getPlacement(): ActionPlacement;
+    isDestructive(): boolean;
+    getHandler(): ActionHandler | undefined;
+    /** Registry key set by `.handler(string)`; undefined when the handler
+     *  is a closure (or unset). Mutually exclusive with `getHandler()`. */
+    getHandlerName(): string | undefined;
+    /** Per-fire context set by `.payload({…})`. Empty `{}` when unset
+     *  (callers can spread without a null check). */
+    getPayload(): Record<string, unknown>;
+    /** Filament chain modifier — true when `.markAsRead()` was called.
+     *  Read by `Notification.actions([…])` serializer; ignored elsewhere. */
+    isMarkAsReadOnFire(): boolean;
+    /** Honored by the notification action-strip renderers; equivalent to
+     *  `target="_blank"` on the underlying anchor. */
+    isOpenUrlInNewTab(): boolean;
+    getHref(): string | undefined;
+    getMethod(): ActionMethod | undefined;
+    getActionUrl(): string | undefined;
+    getDispatchUrl(): string | undefined;
+    isSubmit(): boolean;
+    getFormTarget(): string | undefined;
+    getFormField(): {
+        name: string;
+        value: string;
+    } | undefined;
+    hasModal(): boolean;
+    /** Schema fields stored as children; `getChildren()` returns the same. */
+    getSchema(): Element[];
+    getColor(): ActionColor | undefined;
+    getIcon(): string | undefined;
+    getSize(): ActionSize | undefined;
+    getTooltip(): string | undefined;
+    isOutlined(): boolean;
+    isIconOnly(): boolean;
+    getBadge(): string | number | undefined;
+    getType(): string;
+    toMeta(): ActionMeta;
+}
+/** Re-export for routes/dispatch consumers that need to type-narrow on
+ * action validation failures. */
+export type { ValidationErrors };
+//# sourceMappingURL=Action.d.ts.map