@atscript/vue-table 0.1.132 → 0.1.134

package/dist/{types-ByU4O0Yf.d.mts → types--ex8BJIO.d.cts}

@@ -1,8 +1,54 @@
+import { Component, ComputedRef, MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+import { ClientError, PageResult, TDbActionInfo, TDbActionProcessor, TDbDeleteResult } from "@atscript/db-client";
+import { Uniquery } from "@uniqu/core";
 import { ColumnDef, PaginationControl, SortControl, TableDef } from "@atscript/ui";
-import { Component, ComputedRef, Ref, ShallowRef } from "vue";
 import { AsPresetEntryRow, AspectMask, ColumnWidthsMap, ConfigTab, FieldFilters, PresetAspect, PresetCapabilities, PresetSnapshot, SelectionMode, SystemPreset, SystemPresetInput, TableStateMethods } from "@atscript/ui-table";
-import { ClientError, TDbActionInfo, TDbActionProcessor, TDbDeleteResult } from "@atscript/db-client";
 
+//#region src/composables/state/intent-scope.d.ts
+interface ActionBuckets {
+  default: TVueTableActionInfo | undefined;
+  others: TVueTableActionInfo[];
+  rows: TVueTableActionInfo[];
+}
+/**
+ * Build the identifier object to forward to `client.action` / `client.remove`.
+ *
+ * Per `@atscript/db-client` invariant #11, identifier bodies are object-only
+ * — never bare scalars, even for single-field PK tables. This helper accepts:
+ * - a row-shaped object (default `rowValueFn`) → picks `preferredId` fields;
+ * - a scalar value when `preferredId` has exactly one field (consumers that
+ *   override `rowValueFn` to return the PK scalar) → wraps it.
+ *
+ * Returns `undefined` when no `preferredId` is declared, the source is
+ * `null`/`undefined`, or a scalar can't be paired with a single-field
+ * identifier.
+ */
+declare function extractIdentifier(source: unknown, preferredId: readonly string[]): Record<string, unknown> | undefined;
+//#endregion
+//#region src/composables/state/row-actions-config.d.ts
+/**
+ * A {@link RowActionsConfig} compiled into the two passes a surface runs per
+ * row. Built once per config change (not once per row per render), so the
+ * `include` / `exclude` sets and the override lookups exist once.
+ */
+interface RowActionsPolicy {
+  /**
+   * Narrow + relabel already backend-gated buckets. Callers run
+   * `applyRowGate` FIRST — that order is the whole safety story: `include`
+   * can only narrow what the server allowed for the row, and `overrides`
+   * (presentation only) cannot resurrect an action the server gated away.
+   * Returns the input reference when the policy touches nothing.
+   */
+  apply: (buckets: ActionBuckets) => ActionBuckets;
+  /**
+   * The app-owned actions for `row`. `include` lists SERVER action names —
+   * being listed in `extra` IS an app action's opt-in — so only `exclude` and
+   * the action's own `enabled(row)` apply here. Pass no row to skip the
+   * per-row gate (a surface with no row in hand).
+   */
+  extra: (row?: Record<string, unknown>) => TVueTableActionInfo[];
+}
+//#endregion
 //#region src/types.d.ts
 /** UI-side sentinel for the synthesised row-delete processor. */
 declare const REMOVE_PROCESSOR = "__remove";
@@ -28,6 +74,52 @@ interface InvokeOpts {
    * actions without a form.
    */
   input?: unknown;
+  /**
+   * The row the action was triggered from. Only consumed by client-only row
+   * actions (`RowActionsConfig.extra`), whose `onInvoke(row, pk)` receives it.
+   * Since 0.1.134.
+   */
+  row?: Record<string, unknown>;
+}
+/**
+ * A row action the APP owns — it has no server counterpart, so the backend
+ * never gates it. Either `href` (rendered as a real anchor, mapped through
+ * `state.resolveHref`) or `onInvoke` (runs locally, then settles as an
+ * `@action` emit with `kind: 'custom'`). Since 0.1.134.
+ */
+interface LocalRowAction {
+  /** Unique among the row actions; also the `@action` emit's `action.name`. */
+  name: string;
+  label: string;
+  icon?: string;
+  intent?: TDbActionInfo["intent"];
+  /** Confirmation copy — same `$1` / `$N` substitution as a server action. */
+  promptText?: string | [string, string];
+  /** Link target for the row. Rendered as an anchor, mapped through `state.resolveHref`. */
+  href?: (row: Record<string, unknown>) => string;
+  /** Local handler. Awaited; a rejection settles the action as an error result. */
+  onInvoke?: (row: Record<string, unknown>, pk?: Record<string, unknown>) => void | Promise<void>;
+  /** Per-row gate. Returning `false` hides the action for that row. */
+  enabled?: (row: Record<string, unknown>) => boolean;
+}
+/**
+ * Per-screen presentation policy for the row-actions cell. Narrows and
+ * relabels what the server declared, and appends app-owned actions.
+ *
+ * Backend eligibility stays authoritative: `include` / `exclude` can only
+ * narrow the set a row's `$actions` already allows, and `overrides` only
+ * change how an action looks — neither can surface an action the server
+ * gated away. Since 0.1.134.
+ */
+interface RowActionsConfig {
+  /** Allowlist of server action names. Omitted = every eligible action. */
+  include?: string[];
+  /** Denylist of server action names, applied after `include`. */
+  exclude?: string[];
+  /** Presentation overrides keyed by server action name. */
+  overrides?: Record<string, Partial<Pick<TVueTableActionInfo, "label" | "icon" | "intent" | "promptText">>>;
+  /** App-owned actions appended after the server ones. */
+  extra?: LocalRowAction[];
 }
 /** Discriminated result returned by `state.actions.invoke`. Never throws. */
 type ActionResult = {
@@ -190,14 +282,62 @@ interface PresetConfig {
    * Add `'itemsPerPage'` for paginated tables; drop any aspect this app doesn't use.
    */
   aspects?: PresetAspect[];
+  /**
+   * Aspects a SYSTEM preset owns. Intersected with `aspects`; defaults to all
+   * of them. Narrow it to e.g. `['filterOps']` when system presets are
+   * filter-only views that must not reset the user's columns, displayed
+   * filters, sorters or page size. Since 0.1.133.
+   */
+  systemAspects?: PresetAspect[];
   /**
    * Opt-in localStorage overlay for the user's in-flight tweaks (default
    * `false`). Persists `columns` / `filters` / `sorters` / opt-in
    * `itemsPerPage`; `filterOps` / `searchTerm` / pagination are NOT persisted.
    */
   persistDrafts?: boolean;
+  /**
+   * Identity the draft is stored under — pass the signed-in user's id
+   * whenever `persistDrafts` is on, so a shared browser never restores the
+   * previous user's draft. Omitted keeps the pre-0.1.133 unscoped key.
+   * Since 0.1.133.
+   */
+  draftScope?: MaybeRefOrGetter<string | undefined>;
 }
 type QueryErrorKind = "initial" | "query" | "queryNext" | "loadRange";
+/**
+ * Context handed to the per-row hooks of `<AsTable>` (`rowSelectable`,
+ * `rowClass`, `rowAttrs`). Since 0.1.133.
+ */
+interface RowHookContext {
+  /** Position of the row in the rows the renderer is currently rendering. */
+  index: number;
+  /**
+   * Whether the row's pk is in `state.selectedRows` right now. A getter —
+   * reading it subscribes that hook call to the selection, so predicates
+   * that ignore it are not re-run when the selection changes.
+   */
+  readonly selected: boolean;
+}
+/**
+ * Per-row selectability predicate. Return `false` — or a string, which is
+ * surfaced as the disabled reason on the selection control — to make the row
+ * not selectable; `true` (or omitting the prop) keeps it selectable.
+ * Since 0.1.133.
+ */
+type RowSelectableHook = (row: Record<string, unknown>, ctx: RowHookContext) => boolean | string | undefined | void;
+/** Extra classes for the row element. Since 0.1.133. */
+type RowClassHook = (row: Record<string, unknown>, ctx: RowHookContext) => string | string[] | Record<string, boolean> | undefined;
+/**
+ * Extra attributes for the row element. The framework's own `id`, `role`,
+ * `aria-*`, `data-*`, `class` and `style` always win. Since 0.1.133.
+ */
+type RowAttrsHook = (row: Record<string, unknown>, ctx: RowHookContext) => Record<string, unknown> | undefined;
+/** Normalised {@link RowSelectableHook} verdict. */
+interface RowSelectableVerdict {
+  ok: boolean;
+  /** Disabled reason, when the predicate returned a string. */
+  reason?: string;
+}
 /** Controls which sections appear in the column header dropdown menu. */
 interface ColumnMenuConfig {
   sort?: boolean;
@@ -358,6 +498,13 @@ interface ReactiveTableState extends TableStateMethods {
    * remounting.
    */
   rowDelete: Ref<boolean | RowDeleteOpt>;
+  /**
+   * Per-screen row-action policy — writable ref owned by `<AsTableRoot>`,
+   * like {@link rowDelete}. `<AsRowActions>` reads it from the context, so a
+   * standalone `<AsRowActions>` inside the table honours it too (an explicit
+   * `:actions` prop on that component wins). Since 0.1.134.
+   */
+  rowActions: Ref<RowActionsConfig | undefined>;
   /**
    * `?$actions=true` opt-in — writable ref owned by the renderer.
    * `<AsTable>` / `<AsWindowTable>` flip this on whenever their
@@ -373,6 +520,31 @@ interface ReactiveTableState extends TableStateMethods {
    * naturally without consulting mode.
    */
   isPkSelected: (pk: unknown) => boolean;
+  /**
+   * Per-row selectability predicate — writable ref owned by the renderer,
+   * like {@link rowDelete}. `<AsTable>` / `<AsWindowTable>` push their
+   * `:row-selectable` prop into it, and every selection path in the model
+   * gates on it. Since 0.1.133.
+   */
+  rowSelectable: Ref<RowSelectableHook | undefined>;
+  /**
+   * Normalised `rowSelectable` verdict for one row. `index` is the row's
+   * position in what the renderer renders (absolute in window mode).
+   * Since 0.1.133.
+   */
+  isRowSelectable: (row: Record<string, unknown>, index: number) => RowSelectableVerdict;
+  /** The subset of `rows` the `rowSelectable` predicate lets through. Since 0.1.133. */
+  selectableRows: (rows: readonly Record<string, unknown>[]) => Record<string, unknown>[];
+  /** How many of `rows` the `rowSelectable` predicate lets through. Since 0.1.133. */
+  selectableCount: (rows: readonly Record<string, unknown>[]) => number;
+  /**
+   * Select every eligible row in `rows`. An ineligible row that is already
+   * selected stays selected. `indexOf` maps a position in `rows` to the
+   * index the `rowSelectable` predicate sees — windowed callers pass it
+   * because their rows come from a cache keyed by absolute index.
+   * Since 0.1.133.
+   */
+  selectAll: (rows: readonly Record<string, unknown>[], indexOf?: (position: number) => number) => void;
   /** Column currently open in the filter dialog (null when closed). */
   filterDialogColumn: Ref<ColumnDef | null>;
   /** Absolute index of the keyboard-active row. -1 = nothing active. */
@@ -398,7 +570,10 @@ interface ReactiveTableState extends TableStateMethods {
   setActive: (absIndex: number) => void;
   /** Reset the active-row index to `-1`. */
   clearActive: () => void;
-  /** Toggle selection of the active row's PK in `selectedRows`. */
+  /**
+   * Toggle selection of the active row's PK in `selectedRows`. No-op in
+   * `select="none"` and on a row the `rowSelectable` predicate rejects.
+   */
   toggleActiveSelection: (mode: SelectionMode) => void;
   /** Ask the rendering component to emit `main-action` for the active row. */
   requestMainAction: (event: KeyboardEvent | MouseEvent) => void;
@@ -415,6 +590,12 @@ interface ReactiveTableState extends TableStateMethods {
    * consumers should not mutate directly.
    */
   confirmRequest: Ref<ConfirmRequest | null>;
+  /**
+   * The prompt request the dialog SURFACE renders: the last non-null
+   * `confirmRequest`, retained after it is answered so the copy survives the
+   * exit animation. Internal — used by the dialog. @since 0.1.133
+   */
+  confirmDisplay: Ref<ConfirmRequest | null>;
   /**
    * Open the in-app confirm dialog with `message` as the body. Resolves
    * `true` on accept, `false` on cancel/dismiss. Public — consumers can
@@ -431,12 +612,24 @@ interface ReactiveTableState extends TableStateMethods {
   acceptPrompt: () => void;
   /** Resolve the active prompt with `false`. Internal — used by the dialog. */
   dismissPrompt: () => void;
+  /**
+   * Clear `confirmDisplay` once the dialog surface has left (bound to the
+   * content's `after-leave`). A no-op while a prompt is pending. Internal.
+   * @since 0.1.133
+   */
+  releaseConfirm: () => void;
   /**
    * Currently pending action-form request — `null` when no form is open.
    * Writes are owned by `requestActionInput()` / `acceptActionForm()` /
    * `dismissActionForm()`; consumers should not mutate directly.
    */
   actionFormRequest: Ref<ActionFormRequest | null>;
+  /**
+   * The form request the dialog SURFACE renders: the last non-null
+   * `actionFormRequest`, retained after it is answered so the title, id chips
+   * and form survive the exit animation. Internal. @since 0.1.133
+   */
+  actionFormDisplay: Ref<ActionFormRequest | null>;
   /**
    * Open the action-form dialog. Resolves with the submitted form payload
    * on accept, or `null` on cancel/dismiss.
@@ -449,6 +642,12 @@ interface ReactiveTableState extends TableStateMethods {
   acceptActionForm: (input: unknown) => void;
   /** Resolve the active form request with `null`. Internal — used by the dialog. */
   dismissActionForm: () => void;
+  /**
+   * Clear `actionFormDisplay` (and the loaded schema/draft) once the dialog
+   * surface has left. A no-op while a request is pending. Internal.
+   * @since 0.1.133
+   */
+  releaseActionForm: () => void;
   /**
    * Hydrate state from a URL query string produced by `stateToUrlQueryString`.
    * Replaces filters / sorters / search / pagination with values decoded from
@@ -457,6 +656,43 @@ interface ReactiveTableState extends TableStateMethods {
    * watchers refetch in reaction to the writes.
    */
   applyUrlQuery: (urlString: string) => void;
+  /**
+   * Build the Uniquery the table's own fetch would send right now — same
+   * filters, sorters, search, force-filters and `$select` projection. Used by
+   * `useTableExport` so an export never drifts from what is on screen.
+   * Since 0.1.134.
+   */
+  buildQuery: (opts?: {
+    columnPaths?: string[];
+    includeActions?: boolean;
+  }) => Uniquery;
+  /**
+   * Run one page through the table's configured query function (or its
+   * client). The single fetch path — a custom `queryFn` is honoured here too.
+   * Since 0.1.134.
+   */
+  fetchPage: (query: Uniquery, page: number, size: number) => Promise<PageResult<Record<string, unknown>>>;
+  /**
+   * Paths of the client-owned (`local`) columns — the ones no server field
+   * backs, so they never enter `$select`, `$sort` or filters. Since 0.1.134.
+   */
+  localColumnPaths: ComputedRef<Set<string>>;
+  /**
+   * Re-order already-loaded rows so a sorter on a client-owned column takes
+   * effect: the page is sorted by the FULL sorter list, which leaves the
+   * server's own ordering intact and slots the local sorter in at its real
+   * priority. Page-local by definition — it can only order what is loaded —
+   * and a no-op (returns the input reference) without a local sorter, in
+   * window mode, or when the rows arrive pre-sorted. Since 0.1.134.
+   */
+  applyLocalSort: <T extends Record<string, unknown>>(rows: T[]) => T[];
+  /**
+   * The row-action policy from {@link rowActions}, compiled once per config
+   * change. Every surface that renders row actions reads it — the row-actions
+   * cell and the selection toolbar — so they cannot show different sets.
+   * Since 0.1.134.
+   */
+  rowActionsPolicy: ComputedRef<RowActionsPolicy>;
   /**
    * Preset feature surface. Always present; inert (`available=false`,
    * mutators throw) when `useTable({ preset })` was not configured.
@@ -487,9 +723,22 @@ interface PresetSurface {
    * `['columns', 'filters', 'filterOps', 'sorters']`.
    */
   availableAspects: PresetAspect[];
+  /**
+   * Aspects a SYSTEM preset owns — subset of `availableAspects`, equal to it
+   * unless `preset.systemAspects` narrowed it. Drives apply/reset, the dirty
+   * baseline, the picker/dialog badges and the Save-As defaults for system
+   * presets. Since 0.1.133.
+   */
+  systemAspects: PresetAspect[];
+  /**
+   * Aspects the preset `id` owns — the ones applying it writes. System →
+   * `systemAspects`, stored → what its snapshot claims, `null` (or an id
+   * with no row) → `availableAspects`. Since 0.1.133.
+   */
+  ownedAspects: (id: string | null) => PresetAspect[];
   /**
    * False when `preset` config is absent OR the initial load returned
-   * 401/403 OR any other error. The picker / dialog should hide their UI.
+   * 401/403/404 OR any other error. The picker / dialog should hide their UI.
    */
   available: ComputedRef<boolean>;
   /** Currently active preset id (system `'sys:*'` or stored). null = no active. */
@@ -548,6 +797,15 @@ interface PresetSurface {
    * feature is off.
    */
   batch: <T>(fn: () => Promise<T>) => Promise<T>;
+  /**
+   * Error thrown by the most recent mutator, or null — the SINGLE channel
+   * for preset write failures. Cleared when an OUTERMOST mutator starts, so
+   * a `batch()` counts as one user action: a failure early in a batch is not
+   * wiped by a later write inside it, and the batch's last failure wins.
+   * Mutators rethrow as well, so a caller can handle a single call; this ref
+   * is for UI that only needs to render the failure. Since 0.1.133.
+   */
+  lastError: Ref<Error | null>;
 }
 //#endregion
-export { TableNavBridge as _, EnterAction as a, NavKeyOptions as c, ReactiveTableState as d, RowDeleteOpt as f, TableActionsState as g, TVueTableActionInfo as h, ConfirmOptions as i, PresetConfig as l, TAsTableControls as m, ColumnMenuConfig as n, InvokeOpts as o, TAsCellTypeComponents as p, ConfigTab as r, MainActionRequest as s, ActionResult as t, QueryErrorKind as u };
+export { TableActionsState as C, TVueTableActionInfo as S, extractIdentifier as T, RowHookContext as _, EnterAction as a, TAsCellTypeComponents as b, MainActionRequest as c, QueryErrorKind as d, ReactiveTableState as f, RowDeleteOpt as g, RowClassHook as h, ConfirmOptions as i, NavKeyOptions as l, RowAttrsHook as m, ColumnMenuConfig as n, InvokeOpts as o, RowActionsConfig as p, ConfigTab as r, LocalRowAction as s, ActionResult as t, PresetConfig as u, RowSelectableHook as v, TableNavBridge as w, TAsTableControls as x, RowSelectableVerdict as y };