@atscript/vue-table
Vue 3 smart table powered by @atscript/ui + @atscript/ui-table. Tier-1 primary components (AsTableRoot, AsTable, AsWindowTable, AsFilters, AsPresetPicker, AsTableActions) are tagged in templates; Tier-2 defaults (cells, dialogs, header cells, filter UI) are swapped via the controls / types / components prop maps. A single useTable() call returns a ReactiveTableState that every Vue piece subscribes to.
Contents
- Tier 1 — Primary components
- Tier 2 — Cells
- Tier 2 — Dialogs
- Tier 2 — Filter UI
- Tier 2 — Headers & rows
- Composables — table root
- Composables — state contracts
- Composables — features
- Composables — presets
- Factories
- Types
- Utilities
Tier 1 — Primary components
AsTableRoot
Sets up useTable() once, provides the context, and renders the table chrome. Most apps tag this at the page level.
Props (excerpt — see UseTableOptions for the full reactive surface):
interface AsTableRootProps {
/** Required unless `rows` is given (local mode). */
url?: string;
/** Local mode: render this array instead of fetching. Reactive — replacing it re-queries locally. Since 0.1.134. See [Local rows](/tables/query-function#path-c-local-rows). */
rows?: Record<string, unknown>[];
/** Local mode: the columns to render, read once at setup. Since 0.1.134. */
columns?: ColumnDef[];
/** Local mode: field paths the search term matches (substring, case-insensitive). Since 0.1.134. */
searchPaths?: string[];
/** Local mode: sort in memory from the active sorters. Default `true`. Since 0.1.134. */
localSort?: boolean;
/** Client-owned columns merged into the server's column list — never in `$select`, server sort or filters. Since 0.1.134. See [Display-only columns](/tables/customization#display-only-columns). */
displayColumns?: DisplayColumnDef[];
/** Per-screen row-action policy: `include` / `exclude` / `overrides` / `extra`. The server's per-row `$actions` gate still wins. Since 0.1.134. See [Selecting and extending row actions](/tables/actions#selecting-and-extending-row-actions). */
rowActions?: RowActionsConfig;
limit?: number;
rowValueFn?: (row: Record<string, unknown>) => unknown;
selectionPersistence?: "clear" | "trim" | "persist";
/** Offer "Select all N matching" — a query selection of every row matching the filter / search. Default `false`. Since 0.1.147. See [Select All Matching Rows](/tables/select-all-matching). */
selectAllMatching?: boolean;
/** Always-applied filter, AND-ed with the user's. Live since 0.1.148: a changed value re-queries on page 1 (structural compare, user state kept). */
forceFilters?: FilterExpr;
/** Always-applied sorters. Live since 0.1.148 (keeps the page). */
forceSorters?: SortControl[];
/** IANA zone dates are read in — "today", which instant a day filter means. Default: the cell locale's, else the browser's. Also re-provided to the subtree as the cell locale's zone. Since 0.1.148. */
timeZone?: string;
/** Opt in to suppressing user sorters while a search is active, to preserve relevance ranking. Default `false`. Also a `v-model`. See [Sorting](/tables/sorting#search-relevance-sort-suppression). */
ignoreSortersWhenSearched?: boolean;
/** Leaf paths always added to `$select`, regardless of visible columns — for renderless cell renderers. Live since 0.1.148. */
alwaysSelected?: string[];
queryFn?: (
query: Uniquery,
page: number,
size: number,
) => Promise<PageResult<Record<string, unknown>>>;
queryOnMount?: boolean;
/**
* Suppress every query trigger (`query` / `queryNext` / `loadRange`). The
* prop stays a plain boolean, but `AsTableRoot` forwards it to `useTable`
* as a getter, so it is reactive (since 0.1.133): a table mounted while
* blocked starts fetching the moment the flag clears, and an
* already-queried table replays one query for whatever state changed while
* it was blocked.
*/
blockQuery?: boolean;
blockSize?: number;
dragReleaseDebounceMs?: number;
clientFactory?: ClientFactory;
/** `/meta` revalidation key (default: the URL). The route template of a parametric mount, e.g. `"/api/db/ticket-issue/:key"`. Setup-only. Since 0.1.153 — see [Parametric mounts](/api/ui#parametric-mounts-metakey). */
metaKey?: string;
controls?: TAsTableControls;
types?: TAsCellTypeComponents;
components?: Record<string, Component>;
formTypes?: TAsTypeComponents;
formComponents?: Record<string, Component>;
preset?: PresetConfig;
refreshOnAction?: boolean;
/** Base-path href mapping for navigate-action anchors (also a `useTable` option). Applied only to the `href` attribute / new-tab target, never to the invoke path. Default: identity. See [Navigate actions](/tables/actions#navigate-actions). */
resolveHref?: (url: string) => string;
urlQuerySync?: UrlQuerySync;
}v-models: urlQuery (string), filterFields (string[]), columnNames (string[]), columnWidths (ColumnWidthsMap), sorters (SortControl[]), selectedRows (unknown[]), ignoreSortersWhenSearched (boolean), querySelection (QuerySelection | null, since 0.1.147).
Emits: action(action, ids, result, event?), main-action(row, absIndex, event), unsupported-filter(issue: UnsupportedFilter) (since 0.1.139 — once per piece of a restored URL's filter that field filters cannot express and that was left out; unbound → a dev-mode console.warn. Since 0.1.140 a piece on server-backed columns is kept as a residual condition instead and not reported — the event means "dropped"; urlQuerySync: { residual: false } restores 0.1.139. See Links the filter model cannot hold), fields-dropped(report: DroppedFieldsReport) (since 0.1.141 — once per apply of a preset (the local draft included) or a restored URL that named fields the caller cannot use, only when something was dropped; state written straight to the model is left out of the query without a report; unbound → a dev-mode console.warn. A URL piece mixing such a field with usable ones is reported here, no longer as unsupported-filter. See Fields Hidden by Role), selection-reset(event: SelectionResetEvent) (since 0.1.147 — the table dropped a query selection because the filter, search or index changed: { reason: "scope" }).
forceFilters / forceSorters are never pruned of hidden fields — keep them to fields every role reads.
Live vs setup-only props (since 0.1.148). forceFilters, forceSorters and alwaysSelected are live; the props that wire the table up (url, queryFn, clientFactory, metaKey, preset, urlQuerySync, displayColumns, limit, …) are read once and warn in development when changed after mount. See Forced scope is live.
Slot props (default slot, bound from state): tableDef, loadingMetadata, metadataError, allColumns, columnNames, columnWidths, columns, filterFields, filters, residualFilters, sorters, results, querying, queryingNext, totalCount, loadedCount, pagination, queryError, mustRefresh, searchTerm, selectedRows, selectedCount, selection, canSelectAllMatching, selectAllMatching, clearSelection (these four since 0.1.147), navBridge, query, queryNext, resetFilters, showConfigDialog, openFilterDialog, closeFilterDialog, setFieldFilter, removeFieldFilter, setResidualFilters, removeResidualFilter, addFilterField, removeFilterField, actions, prompt (residualFilters and its two mutators since 0.1.140).
AsTable
Paginated table renderer. Subscribes to useTableContext(). Use inside <AsTableRoot> or supply your own context.
interface AsTableProps {
rows?: Record<string, unknown>[];
columns?: ColumnDef[];
stickyHeader?: boolean;
virtualRowHeight?: number;
virtualOverscan?: number;
columnMenu?: ColumnMenuConfig;
reorderable?: boolean;
resizable?: boolean;
columnMinWidth?: number;
/**
* Render without a header row — omits `<thead>` entirely (not
* `display:none`). Column widths are carried by a `<colgroup>`, so data
* columns keep their `@ui.table.width` / seeded widths without a header.
* Header-driven interactions (sort/filter/reorder/resize) are unavailable.
* Not to be confused with a *renderless* table (drop `<AsTable>` and build
* your own UI from `<AsTableRoot>` state).
*/
headless?: boolean;
/** Selection mode: "none" | "single" | "multi". */
select?: SelectionMode;
/** See `SelectOn`. Since 0.1.142. */
selectOn?: SelectOn;
/** Row-delete opt-in. */
rowDelete?: boolean | RowDeleteOpt;
/**
* Synthesised row-actions pseudo-column. `'first'` / `'last'` prepend or
* append a fixed `__actions` column; `'merge-select'` only renders when
* `select === 'none'` so the row gutter shares space with the multi-select
* checkbox column. `false` (default) hides the column entirely.
*/
rowActionsColumn?: "first" | "last" | "merge-select" | false;
/**
* Per-row selectability (since 0.1.133). Return `false` — or a string,
* surfaced as the disabled reason on the row's selection control — to make
* a row not selectable. Enforced on every path: row click, Space/Enter
* toggle, and the header select-all, which also stops counting ineligible
* rows. Example:
* `:row-selectable="(row) => (row.locked ? 'Locked by another user' : true)"`.
*/
rowSelectable?: RowSelectableHook;
/**
* Extra classes for the row element (since 0.1.133) — string, array, or
* `{ class: boolean }` map, merged with the framework's own row classes.
*/
rowClass?: RowClassHook;
/**
* Extra attributes for the row element (since 0.1.133). The framework's own
* `id`, `role`, `aria-*`, `data-*`, `class` and `style` always win, so a
* hook can decorate a row but never rewrite its accessibility contract.
*/
rowAttrs?: RowAttrsHook;
}The three hooks are typed under Row hooks. AsWindowTable accepts the same three props; the gate lives in the selection model (state.rowSelectable / isRowSelectable / selectAll), so click, keyboard, select-all and the header tri-state all share it.
Emits: row-click(row, event), row-dblclick(row, event), main-action(row, absIndex, event).
Slots: cell-<path> / header-<path> per column, plus the selection pseudo-column __select (since 0.1.142):
"header-__select": (props: {
state: SelectAllState | undefined;
toggle: () => void;
selectedCount: number;
/** Since 0.1.147. */
mode: "ids" | "query";
canSelectAllMatching: boolean;
selectAllMatching: () => void;
}) => unknown;
"cell-__select": (props: {
row: Record<string, unknown>;
index: number;
selected: boolean;
selectable: boolean;
reason: string | undefined;
toggle: () => void;
}) => unknown;Since 0.1.147 both renderers also take a selection-banner slot — it replaces the content of the "Select all N matching" banner (rendered only while the banner shows):
"selection-banner": (props: {
selection: TableSelection;
canSelectAllMatching: boolean;
selectAllMatching: () => void;
clearSelection: () => void;
/** Loaded eligible rows ("all N rows on this page"). */
loadedCount: number;
}) => unknown;Behaviour and scope: Custom selection controls, What the header checkbox acts on, Select All Matching Rows.
AsWindowTable
Windowed (virtualized) renderer for million-row datasets. Uses planFetch / page-aligned blocks under the hood. Same props and selection slots as AsTable plus rowHeight?: number.
AsFilters
Renders the active-filters bar. Reads state.filterFields and state.filters, emits writes through the same refs.
interface AsFiltersProps {
/** Explicit field list; defaults to the displayed `state.filterFields`. */
filterFields?: string[];
/**
* Hard cap on how many filter fields render inline (since 0.1.133).
* Deterministic and count-based — the component never measures the toolbar,
* so width-driven responsiveness stays with the host (feed a shorter
* `filterFields` list, or a smaller `maxVisible`). Omitted (the default)
* renders every field inline, exactly as before.
*/
maxVisible?: number;
/**
* What happens to the fields past `maxVisible` (since 0.1.133). Ignored
* when `maxVisible` is omitted.
*
* - `'popover'` (the default whenever `maxVisible` is set) — they move into
* a popover behind a "More filters" trigger, badged with the number of
* ACTIVE hidden filters so nothing silently narrows the table from
* off-screen.
* - `'none'` — they are not rendered at all. Pick this only when the host
* surfaces them elsewhere (e.g. its own filter dialog); an active filter
* on a dropped field still applies to the query.
*/
overflow?: "popover" | "none";
/**
* Render `state.residualFilters` as "Custom filter" chips after the fields
* (since 0.1.140). Default `true`; always inline, never in the overflow
* popover. `false` when the host places `<AsResidualFilter>` itself.
*/
residual?: boolean;
}Since 0.1.142 — behaviour in Controlling the popover:
- v-model:
overflowOpen(boolean). - Emits:
overflow-open-auto-focus(event: Event),overflow-close-auto-focus(event: Event). - Slots:
#overflow-trigger="{ activeCount: number, open: boolean }",#overflow="{ columns: ColumnDef[], close: () => void }".
$attrs are still forwarded to every filter field: the component sets inheritAttrs: false and renders a multi-root fragment (no wrapper element), so the fields (and the overflow trigger beside them) stay direct children of the host's filter row and no existing layout changed.
AsTableActions
Toolbar action row. Reads state.actions and renders default/other actions per level. Slot-customizable — slot actions may be disabled; see Disabled with a reason.
AsPresetPicker
Dropdown picker showing the active preset, the system presets, the user's saved presets, and the favorite row. Backed by state.preset.
Tier 2 — Cells
Default cell renderers — all implement the standard cell-props contract (path, value, row, column, locale).
| Component | Default cell type | Notes |
|---|---|---|
AsTableCellValue | text, number, boolean, enum, ref | Generic value renderer with locale + value-help labels. |
AsCellNumber | number (when used explicitly) | Decimal-aware numeric cell. |
AsCellDate | date, datetime, relative | Locale-aware date renderer. |
AsCellArray | array | Pill chips for array values. |
AsCellJson | object | Collapsible JSON renderer. |
AsCellUnion | unions | Per-row dispatcher that renders the active union variant. |
Imports:
import {
AsTableCellValue,
AsCellNumber,
AsCellDate,
AsCellArray,
AsCellJson,
AsCellUnion,
} from "@atscript/vue-table";Tier 2 — Dialogs
AsConfigDialog
Tabbed config dialog (columns / filters / sorters). Open via state.configDialogOpen = true.
AsFilterDialog
Per-column filter editor. Open via state.filterDialogColumn = column.
AsPresetDialog
Manage saved presets — rename, delete, public toggle, favorite, default.
AsConfirmDialog
Pure confirm dialog driven by state.prompt(message, opts?). Replaces window.confirm().
AsActionFormDialog
Dialog for actions that declare an @InputForm schema. Opens via state.requestActionInput(action, ctx). Pulls in the full @atscript/vue-form runtime, so it is not exported from the main entry — <AsTableRoot> lazy-mounts it only when an @InputForm action is detected. Import from the dedicated subpath when you need to override or eager-load:
import AsActionFormDialog from "@atscript/vue-table/as-action-form-dialog";Tier 2 — Filter UI
AsFilterField
Single column's filter row inside the filter dialog or active-filters bar. Since 0.1.168 it is rebuilt when the app's UI locale changes, so its value pickers (dictionary, distinct values) ask in the new locale, through the table's clientFactory.
AsResidualFilter
Since 0.1.140. One custom filter condition as a chip: label, the condition in words (formatFilterExpr with column labels), and a remove button. Props: expr: FilterExpr, index: number (its position in state.residualFilters). Rendered by <AsFilters>; override via controls.residualFilter. Subpath: @atscript/vue-table/as-residual-filter.
AsFilterInput
Input control for one condition — switches between text / number / date / date-time / boolean / ref based on the column's filter kind. Props: column: ColumnDef, condition: FilterCondition, filterType: ColumnFilterType; emits update:condition.
filterType may be "datetime" (since 0.1.148 — a timestamp or ISO date-time column, see Date and time filters). A custom controls.filterInput with an exhaustive switch must handle it; falling through to a text input keeps working, because the query encoder accepts typed day, minute and ISO strings. The default input renders a number box that stays empty (never 0) when cleared, a native date input — plus a clock toggle (as-filter-input-time-toggle, aria-label="Pick a time") on date-time columns that switches to datetime-local — and a pill (as-filter-input-token) for a relative or epoch value.
Tier 2 — Headers & rows
AsTableHeaderCell
Default header cell — label, sort indicator, resize handle, column menu trigger.
AsColumnMenu
Dropdown menu shown on header click — sort, filter, hide, reset width. Configurable via ColumnMenuConfig.
AsRowActions
Per-row actions cell — single button or … dropdown. Actions the row disabled with a reason render aria-disabled with the reason (see Disabled with a reason).
Composables — table root
useTable(url, opts?)
Main entry point. Resolves table metadata, builds the TableDef, wires presets/drafts/selection, and returns the reactive state. During a server render it loads no metadata (the state stays loadingMetadata, its context client is built without asking /meta); the browser loads it after hydration.
function useTable(url: string, opts?: UseTableOptions): ReactiveTableState;UseTableOptions (key fields):
interface UseTableOptions {
limit?: number;
rowValueFn?: (row: Record<string, unknown>) => unknown;
selectionPersistence?: "clear" | "trim" | "persist";
filterFields?: Ref<string[]>;
columnNames?: Ref<string[]>;
columnWidths?: Ref<ColumnWidthsMap>;
sorters?: Ref<SortControl[]>;
selectedRows?: Ref<unknown[]>;
/** Live since 0.1.148: a ref or getter; a change re-queries on page 1 (structural compare). Plain values still work. */
forceFilters?: MaybeRefOrGetter<FilterExpr | undefined>;
/** Live since 0.1.148; a change re-queries and keeps the page. */
forceSorters?: MaybeRefOrGetter<SortControl[] | undefined>;
/** IANA zone dates are read in (date filters, "today"). Default: the cell locale's zone, else the browser's. Since 0.1.148. */
timeZone?: MaybeRefOrGetter<string | undefined>;
/** First day of the week for `week` filters, `1` Monday … `7` Sunday. Default: from the locale, else Monday. Since 0.1.148. */
weekStart?: MaybeRefOrGetter<number | undefined>;
/** Suppress user sorters while searching (preserve relevance). `boolean` = configured default; `Ref<boolean>` = external model whose initial value is the default. Default `false`. */
ignoreSortersWhenSearched?: boolean | Ref<boolean>;
/** Leaf paths always added to `$select`, regardless of visible columns — see [Custom Cells](/tables/custom-cells). */
alwaysSelected?: MaybeRefOrGetter<string[] | undefined>;
queryFn?: QueryFn;
queryOnMount?: boolean;
/** When true, all triggers (query/queryNext/loadRange) early-return. Pass a getter (or a ref) to keep it reactive — the held-back query runs once when it flips back to `false` (since 0.1.133). */
blockQuery?: boolean | (() => boolean);
blockSize?: number;
dragReleaseDebounceMs?: number;
clientFactory?: ClientFactory;
/** `/meta` revalidation key (default: the URL). The route template of a parametric mount, e.g. `"/api/db/ticket-issue/:key"`. Setup-only. Since 0.1.153 — see [Parametric mounts](/api/ui#parametric-mounts-metakey). */
metaKey?: string;
controls?: TAsTableControls;
types?: TAsCellTypeComponents;
components?: Record<string, Component>;
formTypes?: TAsTypeComponents;
formComponents?: Record<string, Component>;
provideContext?: boolean;
refreshOnAction?: () => boolean;
onActionResolved?: (action, ids, result, event?) => void;
urlQueryReady?: Ref<boolean>;
onUrlQueryChange?: (urlString: string) => void;
urlQuerySync?: UrlQuerySync;
/** Each left-out piece of a restored URL's filter (since 0.1.140: only those not carried as residual conditions). Omitted → dev-mode `console.warn`. Since 0.1.139. */
onUnsupportedFilter?: (issue: UnsupportedFilter) => void;
/** What an apply left out because it names fields the caller cannot use. Omitted → dev-mode `console.warn`. Since 0.1.141. */
onFieldsDropped?: (report: DroppedFieldsReport) => void;
preset?: PresetConfig;
}clearTableCache()
Drops the shared /meta cache (alias of resetMetaCache from @atscript/ui). For login / logout / role changes prefer setMetaCacheIdentity — see the meta cache reference.
Composables — state contracts
useTableContext() / useTableContextOptional()
Inject the context provided by AsTableRoot (or provideTableContext).
interface TableContext {
state: ReactiveTableState;
client: Client;
locale?: string; // since 0.1.165 — the UI locale `client` asks in; what it serves belongs to it
clientFactory?: ClientFactory; // since 0.1.168 — the table's; its filter pickers build their clients with it
controls: TAsTableControls;
types?: TAsCellTypeComponents;
components?: Record<string, Component>;
formTypes?: TAsTypeComponents;
formComponents?: Record<string, Component>;
}
function useTableContext(): TableContext;
function useTableContextOptional(): TableContext | undefined;createTableState(opts)
Lower-level factory used by useTable. Returns { state, internals }. Reach for this when building a custom root (e.g. a multi-table dashboard).
function createTableState(opts: CreateTableStateOptions): {
state: ReactiveTableState;
internals: TableStateInternals;
};createStaticTableState(opts)
Builds a ReactiveTableState for static / in-memory data (no server, no /meta). Useful for stubs, demos, and unit tests. <AsTableRoot :rows> uses it for local mode.
function createStaticTableState(opts: CreateStaticTableStateOptions): {
state: ReactiveTableState;
internals: TableStateInternals;
};
interface CreateStaticTableStateOptions {
/** The rows. A getter or ref keeps it reactive — each local fetch re-reads it. Since 0.1.134. */
rows: MaybeRefOrGetter<Record<string, unknown>[]>;
columns: ColumnDef[];
searchPaths?: string[];
selection?: TableSelectionOptions;
limit?: number;
/** Sort in memory from the active sorters. Default `true`. Since 0.1.134. */
localSort?: boolean;
/** Client-owned columns merged into `columns`. Since 0.1.134. */
displayColumns?: readonly DisplayColumnDef[];
/** External refs from `defineModel`. Since 0.1.134. */
model?: TableModelRefs;
queryOnMount?: boolean;
actions?: TableActionsOptions;
}provideTableContext(ctx)
Provide a TableContext to the subtree. Exported since 0.1.134 so a custom root can build any state — including createStaticTableState — and hand it to <AsTable> / <AsWindowTable>. Advanced: <AsTableRoot> already covers both the fetching and the local case.
function provideTableContext(ctx: TableContext): void;Composables — features
useTableSelection(state, opts?)
Wires the selection persistence policy onto an existing state. Called automatically by useTable; expose it for createStaticTableState consumers.
type SelectionPersistence = "clear" | "trim" | "persist";
function useTableSelection(state: ReactiveTableState, opts?: { mode?: SelectionPersistence }): void;useTableNavBridge()
Returns the keyboard nav bridge for binding external inputs (custom search box, command palette).
function useTableNavBridge(): TableNavBridge;
interface TableNavBridge {
onKeydown: (event: KeyboardEvent, opts?: NavKeyOptions) => void;
activeIndex: Ref<number>;
setActive: (absIndex: number) => void;
clearActive: () => void;
}useTableFilter()
Helpers for reading/writing the filter model from outside the dialog (toolbar chips, URL bridge, etc.).
useTableSearch()
Search-term composable — reads/writes state.searchTerm, applies debouncing.
useTableActions()
Returns state.actions (the full TableActionsState) from the closest <AsTableRoot> ancestor. Throws when called outside the provider tree.
function useTableActions(): TableActionsState;useTableUrlQuery(route, router, opts?)
Bridge <AsTableRoot v-model:url-query> to a router. Since 0.1.148 it takes structural route and router types — TableUrlQueryRoute ({ query }) and TableUrlQueryRouter ({ replace(to), push?(to) }) — so @atscript/vue-table imports nothing from vue-router: useRoute() / useRouter() type-check as they are, with or without typed-route augmentation, and a plain fake works in tests.
Scope (since 0.1.133): the bridge owns only the keys it serializes. It used to replace route.query wholesale; now every write merges into the current query. A key is table-owned iff the URL parser consumes it (urlQueryConsumesKey(key) from @atscript/ui-table: the $sort / $search / $relevance / $skip controls and operator-bearing filter keys) or the bridge wrote it before; owned keys are replaced or removed, every other key is left untouched, in place. Read and write agree: a key the parser ignores is never deleted.
Without a prefix the bridge cannot tell a plain field=value filter from a page-owned flag of the same shape: the table reads every unprefixed key, so a host key that is also a column path (?team=… on a table with a team column) becomes a user filter. Pass preserveKeys to fence such host keys off, or prefix to namespace the table (which changes its URLs) — and prefix when a route carries two tables.
interface TableUrlQueryRoute {
readonly query: UrlQueryRecordInput; // vue-router's LocationQuery fits
}
interface TableUrlQueryRouter {
replace(to: { query: UrlQueryRecord }): unknown;
push?(to: { query: UrlQueryRecord }): unknown; // required only for mode "push" (throws at setup if missing)
}
interface UseTableUrlQueryOptions {
/** `"replace"` (default) or `"push"`. */
mode?: "replace" | "push";
/**
* Namespace for this table's query keys (since 0.1.133). With
* `prefix: "t1"` every key the bridge writes becomes `t1.<key>`
* (`t1.$skip`, `t1.status`, `t1.total>100`), and only keys under that
* prefix are read back or removed — keys with no prefix, or another
* table's prefix, are foreign and preserved untouched.
*/
prefix?: string;
/**
* Host keys (wire form) the table never reads, writes or removes, even when
* a column has the same name — a list or a predicate. Since 0.1.148.
*/
preserveKeys?: readonly string[] | ((key: string) => boolean);
}
function useTableUrlQuery(
route: TableUrlQueryRoute,
router: TableUrlQueryRouter,
opts?: UseTableUrlQueryOptions,
): WritableComputedRef<string>;preserveKeys (since 0.1.148) keeps a host key that is also a column path out of the table's filters. See A host key that is also a column.
<script setup>
import { useRoute, useRouter } from "vue-router";
import { useTableUrlQuery } from "@atscript/vue-table";
const urlQuery = useTableUrlQuery(useRoute(), useRouter());
// A `?status=` the page owns, beside a `status` column:
// const urlQuery = useTableUrlQuery(useRoute(), useRouter(), { preserveKeys: ["status"] });
// Two tables on one route:
// const left = useTableUrlQuery(useRoute(), useRouter(), { prefix: "a" });
// const right = useTableUrlQuery(useRoute(), useRouter(), { prefix: "b" });
</script>
<template>
<AsTableRoot v-model:url-query="urlQuery" url="/db/products" />
</template>For links, use stateToUrlQueryRecord from @atscript/ui-table (API, Building links).
useTableExport(ctx?)
Export the table's data as it is queried right now — same filters, sorters, search and visible column order, paged over every matching row. Since 0.1.134. Full guide: Export.
function useTableExport(ctx?: TableContext): {
/** Rejects when a run is already in flight — one handle runs one export. */
exportRows: (opts?: ExportRowsOptions) => Promise<ExportResult>;
/** `true` while a run is in flight (derived from `progress`). */
exporting: ComputedRef<boolean>;
/** Progress of the in-flight run, `null` while idle. */
progress: Ref<{ done: number; total?: number } | null>;
};
interface ExportRowsOptions {
/**
* `"visible"` (default) — the visible columns minus the client-owned ones,
* unless a `formatters` entry fills them — or an explicit list of column
* paths, in export order.
*/
columns?: "visible" | string[];
/** `"csv"` (default) → `{ csv, filename }`; `"rows"` → `{ rows }`. */
format?: "csv" | "rows";
/** Rows per request. Default 500. */
pageSize?: number;
/** Aborts between pages; the promise rejects with an `AbortError`. */
signal?: AbortSignal;
onProgress?: (done: number, total?: number) => void;
/** Global cell formatter; `undefined` falls through to the default. */
formatCell?: ExportCellFormatter;
/** Per-column formatters keyed by column path. Win over `formatCell`. */
formatters?: Record<string, ExportCellFormatter>;
/** `.csv` appended when missing. Default `"export.csv"`. */
filename?: string;
/** CSV writer settings — `bom`, `escapeFormulas`, `delimiter`. Ignored by `format: "rows"`. */
csv?: CsvOptions;
maxRows?: number;
}
type ExportResult =
| {
format: "csv";
csv: string;
filename: string;
columns: string[];
columnPaths: string[];
rowCount: number;
total?: number;
}
| {
format: "rows";
rows: ExportScalar[][];
columns: string[];
columnPaths: string[];
rowCount: number;
total?: number;
};The query is built by state.buildQuery() and run through state.fetchPage(), so a custom :query-fn is honoured. The primary key(s) are appended to $sort as a tiebreaker so paging can neither skip nor duplicate rows; $actions is never requested; client-owned display columns are stripped from $select.
downloadExport(result)
Hand a finished CSV export to the browser as a file download. Returns false without doing anything when there is no DOM (SSR / worker), so it is safe to call unguarded. Throws on a format: "rows" result. Since 0.1.134.
function downloadExport(result: ExportResult): boolean;useTableComponent(key, fallback)
Resolve a single chrome skin-slot from the injected controls map, falling back to the supplied component when the consumer left that entry unset. key is one of the TAsTableControls keys (headerCell, columnMenu, filterDialog, etc.) — this is for chrome, not cell-type dispatch.
function useTableComponent<K extends keyof TAsTableControls>(
key: K,
fallback: Component,
): Component;provideCellLocale(source) / useCellLocale()
Locale source for date / number cells. The provider takes a MaybeRefOrGetter so apps can wire it to useAppPrefs or to a global store without re-providing. The consumer side returns computed locale (falls back to navigator.language, then "en-US") and timezone (undefined lets Intl pick the browser TZ).
interface CellLocale {
language?: string;
timezone?: string;
}
function provideCellLocale(source: MaybeRefOrGetter<CellLocale | undefined>): void;
function useCellLocale(): {
locale: ComputedRef<string>;
timezone: ComputedRef<string | undefined>;
};Since 0.1.148 the cell locale's timezone is also the zone the table's date filters read ("today", which instant a day means), so cells, filter inputs, chips and queries agree. <AsTableRoot :time-zone> overrides it for the table and re-provides it to the subtree.
Composables — presets
usePresets(options)
Manages preset rows, userConf, capabilities, and the apply/save plumbing. useTable instantiates this internally when preset is configured; expose it for advanced consumers.
interface UsePresetsOptions {
url: string;
/** Defaults to `inject(AS_PRESETS_APP)`. */
app?: string;
tableKey: string;
clientFactory?: ClientFactory;
systemPresets?: SystemPresetInput[];
/** Auto-load on setup. Default `true`. */
autoLoad?: boolean;
}
interface UsePresetsReturn {
presets: ShallowRef<AsPresetEntryRow[]>;
presetsById: ComputedRef<Map<string, AsPresetEntryRow>>;
userConf: ShallowRef<AsPresetEntryRow | null>;
capabilities: Ref<PresetCapabilities | null>;
systemPresets: ComputedRef<SystemPreset[]>;
systemPresetsById: ComputedRef<Map<string, SystemPreset>>;
/** False when the initial load returned 401/403/404 — UI hides itself. */
available: ComputedRef<boolean>;
/** Preset rows loading. Capabilities never hold it (since 0.1.153); a load served from the session cache never sets it. */
loading: Ref<boolean>;
/** Last failure. Since 0.1.133 the mutators write here as well as rethrowing. */
error: Ref<unknown>;
currentUser: ComputedRef<string | null>;
activePresetId: Ref<string | null>;
activePreset: ComputedRef<ActivePresetView | null>;
isOwned(id: string): boolean;
reload(): Promise<void>;
batch<T>(fn: () => Promise<T>): Promise<T>;
savePreset(snapshot: PresetSnapshot): Promise<void>;
savePresetAs(
label: string,
snapshot: PresetSnapshot,
opts?: { public?: boolean },
): Promise<string>;
renamePreset(id: string, label: string): Promise<void>;
deletePreset(id: string): Promise<void>;
togglePublic(id: string): Promise<void>;
setDefault(id: string | null): Promise<void>;
toggleFav(id: string): Promise<void>;
setFavorites(ids: string[]): Promise<void>;
}Once the app calls setMetaCacheIdentity(), loads and writes go through the presets session cache (since 0.1.153): a re-mount applies cached rows synchronously, and a write refreshes every other mounted usePresets on the same (url, app, tableKey), in this tab and others.
Since 0.1.168 the presets client asks in the app's UI locale (useAsTexts().locale() at setup, like the table): its error and preflight messages come back in that language.
Every mutator rethrows on failure; error here is the load channel only. Mutation failures are recorded on the wired state.preset.lastError (since 0.1.133), so a UI that only needs to render the failure can watch that ref instead of wrapping each call.
apply is not on usePresets — it lives on the wired state.preset surface (PresetSurface) and accepts a system id (sys:*), a stored row id, or a raw PresetSnapshot. Bypassing it and writing the underlying model arrays directly works too — the root watcher reacts either way.
useAppPrefs(options)
Manages the appConf row (app-wide user prefs: appearance, density, locale). Calls with the same (app, url) share a single underlying instance — duplicate widgets make one /query?type=appConf request total. Cross-tab sync rides BroadcastChannel; in-window sync rides a useEventBus. Since 0.1.168 each request asks in its app's UI locale of the moment — the provideAsLocale of the first caller below one (else setUiLocale's) — so error and preflight messages come back translated.
interface UseAppPrefsOptions {
/** App namespace; defaults to `inject(AS_PRESETS_APP)`. */
app?: string;
/** Presets controller URL, e.g. `"/db/_presets"`. */
url: string;
clientFactory?: ClientFactory;
/** Auto-load on setup. Default `true`. */
autoLoad?: boolean;
/** Cache most recent prefs in `localStorage` keyed by app. Default `true`. */
cache?: boolean;
}
interface UseAppPrefsReturn {
/** Reactive prefs. Always non-null; defaults to `{}` until first load resolves. */
prefs: WritableComputedRef<AppConfData>;
loading: Ref<boolean>;
/** Last error, or `null`. Unavailable responses flip `available` instead. */
error: Ref<unknown>;
/** False on 401/403/404 from initial load — hide pref-bound controls. */
available: ComputedRef<boolean>;
reload(): Promise<void>;
/** Optimistic shallow-merge save; rolls back on error. */
save(patch: Partial<AppConfData>): Promise<void>;
reset(): void;
}useLocalDraft(options)
localStorage overlay manager for table preset drafts. One overlay per (app, scope, tableKey); switching presets clears it (the caller decides when to call clear()).
interface UseLocalDraftOptions {
app: string;
tableKey: string;
enabled: Ref<boolean> | boolean;
availableAspects: readonly PresetAspect[];
/**
* Identity the draft is keyed under (since 0.1.133) — pass the signed-in
* user's id so a shared browser never restores the previous user's draft.
* Reactive: when it changes, reads and writes move to the new key and the
* old scope's draft is neither read nor overwritten. Omitted (or
* `undefined`) keeps the pre-0.1.133 unscoped key.
*/
scope?: MaybeRefOrGetter<string | undefined>;
debounceMs?: number;
storage?: StorageLike | null;
}
interface UseLocalDraftReturn {
/** Layer the persisted draft (if any) on top of `applied`. */
hydrate(applied: PresetSnapshot): PresetSnapshot;
/**
* Wire a debounced watcher that mirrors persisted aspects to localStorage.
* Returns the unwatch handle.
*/
watchAndPersist(
currentSnapshot: () => PresetSnapshot,
activePresetSnapshot: () => PresetSnapshot,
): () => void;
clear(): void;
readDraft(): PresetDraft | null;
}
interface StorageLike {
getItem(key: string): string | null;
setItem(key: string, value: string): void;
removeItem(key: string): void;
}injectPresetsApp(override?) / AS_PRESETS_APP
const AS_PRESETS_APP: InjectionKey<string>;
function injectPresetsApp(override?: string): string;AS_PRESETS_APP lets a parent component declare the active "app" id (multi-app deployments). injectPresetsApp(override) returns the override when provided, else falls back to the injected value or 'default'.
Factories
createDefaultControls()
Returns a fresh TAsTableControls map pre-filled with the eight always-on Tier-2 defaults: headerCell, columnMenu, filterInput, filterDialog, filterField, residualFilter (since 0.1.140), configDialog, confirmDialog. The other six slots are intentionally not seeded: rowActions already falls back to the types map's __actions entry and then the built-in AsRowActions (set controls.rowActions only to override explicitly — it wins over the types entry); fieldsSelector, sortersConfig, and filterValueHelp default to internal (unexported) components resolved at their mount sites; presetDialog is lazy-mounted on first open; and actionFormDialog is lazy-loaded so it only pulls in @atscript/vue-form when an @InputForm action is detected.
You rarely need this helper for :controls — every dispatch site falls back to its built-in internally, and passing defaults wholesale statically bundles (and eager-mounts) the lazy dialogs. Pass only the entries you replace:
function createDefaultControls(): TAsTableControls;
const controls = {
filterDialog: MyFilterDialog,
};createDefaultCellTypes()
Returns a pre-built TAsCellTypeComponents map with AsTableCellValue for every built-in type.
function createDefaultCellTypes(): TAsCellTypeComponents;Types
TAsTableControls
Skin-slot override map for table chrome. Set any subset — unset slots fall back to defaults.
interface TAsTableControls {
headerCell?: Component;
columnMenu?: Component;
rowActions?: Component;
filterInput?: Component;
filterDialog?: Component;
filterField?: Component;
filterValueHelp?: Component;
/** One residual-condition chip in `<AsFilters>` (props `expr`, `index`). Since 0.1.140. */
residualFilter?: Component;
configDialog?: Component;
fieldsSelector?: Component;
sortersConfig?: Component;
confirmDialog?: Component;
actionFormDialog?: Component;
presetDialog?: Component;
}TAsCellTypeComponents
type TAsCellTypeComponents = {
text: Component;
number: Component;
boolean: Component;
date: Component;
datetime?: Component;
relative?: Component;
array: Component;
object: Component;
enum: Component;
ref: Component;
__actions?: Component;
} & Record<string, Component>;ReactiveTableState
The full reactive state object (the ReactiveTableState type exported by @atscript/vue-table); the main slots are:
Metadata:
tableDef,loadingMetadata,metadataError.Columns:
columns,allColumns,columnNames,columnWidths.Forced scope (since 0.1.148):
forceFilters(ComputedRef<FilterExpr | undefined>) andforceSorters(ComputedRef<SortControl[]>) — the live app-authored scope, for chrome such as a "scoped to …" badge — andtimeZone(ComputedRef<string | undefined>;undefined= the browser's) — the zone dates are read in.Filters / sorters / search:
filters,filterFields,residualFilters(ShallowRef<FilterExpr[]>, since 0.1.140 — AND-ed conditions field filters cannot hold;setResidualFilters(exprs),removeResidualFilter(index), cleared byresetFilters(); see Custom filter conditions),sorters,searchTerm,ignoreSortersWhenSearched(Ref<boolean>— suppress user sorters while searching; see Sorting).Results:
results,windowCache,windowLoading,topIndex,viewportRowCount,totalCount,loadedCount,resultsStart.Pagination:
pagination.Selection:
selectedRows,selectedCount,rowValueFn,isPkSelected; since 0.1.133rowSelectable(renderer-pushed hook ref),isRowSelectable(row, index),selectableRows(rows),selectableCount(rows),selectAll(rows, indexOf?)— pre-selected ineligible pks survive select-all and the header tri-state counts eligible rows only; since 0.1.142deselectAll(rows),toggleAll(rows)(the header's action) andclearSelection(); since 0.1.144rowByValue(loaded rows keyed byrowValueFnvalue — lazy, rebuilt once per fetch),rowOf(value)(the loaded row behind a selection value: an object is itself, a scalar is looked up;undefinedwhen not loaded) andselectedRowObjects(the loaded rows of the selection, in order — unloaded values left out). Semantics: Selection.Query selection (since 0.1.147):
querySelection(Ref<QuerySelection | null>— "every row matching the query" minusexcluded; while setselectedRowsis empty,isPkSelectedis "not excluded",selectedCountistotal − excluded.lengthandselectedRowObjectslists the loaded non-excluded rows),selection(ComputedRef<TableSelection>— one value for both modes),canSelectAllMatching,selectAllMatching(),allowSelectAllMatching(Ref<boolean>, pushed by<AsTableRoot :select-all-matching>),selectMode(Ref<SelectionMode>, pushed by the renderers),loadedEligiblePks(keys of the loaded rowsrowSelectableadmits).clearSelection()ends a query selection too. Semantics: Select All Matching Rows.Active row / nav:
activeIndex,navMode,navViewportRowCount,hasMainActionListener,rowId,getActiveRow,setActive,clearActive,toggleActiveSelection,requestMainAction,handleNavKey,registerMainActionListener.getActiveRow(): Record<string, unknown> | undefinedresolves the currently-active row — nav-mode-aware: page-relative intoresultsfor paginated<AsTable>, absolute viawindowCachefor<AsWindowTable>. Returnsundefinedwhen no row is active (activeIndex < 0). It is the single resolver shared by selection, the@main-actionemit, and thelevel="row"toolbar.Errors:
queryError,lastError,mustRefresh.Dialog exit retention (since 0.1.133):
confirmDisplay/actionFormDisplaykeep the last non-null request while the dialog animates out;releaseConfirm()/releaseActionForm()clear them (bound to the content'safter-leave) and are no-ops when a new request was raised meanwhile.Querying flags:
querying,queryingNext.Actions namespace:
actions: TableActionsState.Prompt / action-form:
confirmRequest,prompt,acceptPrompt,dismissPrompt,actionFormRequest,requestActionInput,acceptActionForm,dismissActionForm.Presets namespace:
preset: PresetSurface— seePresetSurface.Row-action policy (since 0.1.134):
rowActions: Ref<RowActionsConfig | undefined>— renderer-pushed by<AsTableRoot :row-actions>— androwActionsPolicy, the compiled view of it. Both<AsRowActions>and<AsTableActions>read the compiled policy, so the row cell and the selection toolbar always agree.Query surface (since 0.1.134):
buildQuery(opts?)returns theUniquerythe table's own fetch would send right now ({ columnPaths?, includeActions? }overrides);fetchPage(query, page, size)runs one page through the configuredqueryFn/ client. These are the two seamsuseTableExportbuilds on.Local sorting (since 0.1.134):
localColumnPaths(paths of the client-owned columns) andapplyLocalSort(rows)—<AsTable>runs the loaded page through it, sorting by the FULL sorter list so the server's ordering survives and a local sorter lands at its real priority. Inert without display columns, in window mode, and for an in-memory table (its query function sorts the dataset itself, which is also what lets a window-mode in-memory table keep the affordance).localSortAvailable(since 0.1.135) is the single rule every sort affordance reads, so the header and the config dialog cannot offer different sets.URL bridge:
applyUrlQuery(urlString, opts?). The URL decides what happens to filters and sorters it omits, within theurlQuerySyncgates: a URL carrying$snapshot(every URL the table writes) clears them; any other URL resets them to the table's boot baseline (the owned filters and sorters it had before the first URL was applied — preset, persisted draft, props) and lays its own on top.opts.mode("merge"/"replace") overrides the marker.<AsTableRoot>calls it on every pass without a mode. Since 0.1.140 filter pieces the field model cannot hold are restored asresidualFilters, and a marker-less URL owns every path it mentions (inside such a condition too). Since 0.1.139; 0.1.137–0.1.138 merged onto the current state on the first pass and replaced on every later one — see Hydration and restoration.Query methods:
query(opts?: { silent?: boolean })(microtask-coalesced refresh;{ silent: true }runs the current query with noqueryingflip and leaves rows as-is on failure — for timer-driven live refresh),queryImmediate(opts?: { silent?: boolean })(awaitable form, samesilentsemantics),queryNext(),loadRange(),invalidate(). Every query keeps prior rows until the response settles, then swapsresults+totalCountatomically (keep-rows-until-settle contract).
TableActionsState
interface TableActionsState {
table: TVueTableActionInfo[];
row: TVueTableActionInfo[];
rows: TVueTableActionInfo[];
default: {
table?: TVueTableActionInfo;
row?: TVueTableActionInfo;
rows?: TVueTableActionInfo;
};
others: {
table: TVueTableActionInfo[];
row: TVueTableActionInfo[];
rows: TVueTableActionInfo[];
};
cellRow: TVueTableActionInfo[];
invoke: (
action: TVueTableActionInfo,
pk?: Record<string, unknown> | Record<string, unknown>[],
opts?: InvokeOpts,
) => Promise<ActionResult>;
/**
* Dry-run count of a query-targeted run (`client.countActionTarget`).
* `undefined` when it failed — settled as the action's error result
* (`lastResult` + `@action`). Since 0.1.147.
*/
countTarget: (
action: TVueTableActionInfo,
target: ActionQueryTarget,
event?: KeyboardEvent | MouseEvent,
) => Promise<number | undefined>;
invoking: ShallowRef<Set<string>>;
lastResult: ShallowRef<Map<string, ActionResult>>;
}ActionResult
type ActionResult =
| {
ok: true;
kind: "backend";
data: unknown;
message?: string;
/** A query-targeted run (since 0.1.147): rows matched + the handler's summary, if it returned one. */
target?: { matched: number; summary?: TDbActionTargetSummary };
}
| { ok: true; kind: "navigate" }
| { ok: true; kind: "custom"; dispatched: true }
| { ok: true; kind: "remove"; data: TDbDeleteResult }
| { ok: false; kind: "error"; error: ClientError | Error };RowActionsConfig / LocalRowAction
Per-screen row-action policy. Since 0.1.134 — see Selecting and extending row actions.
interface RowActionsConfig {
/** Allowlist of server action names. Omitted = every eligible action. */
include?: string[];
/** Denylist, applied after `include`. Also removes an `extra` of the same name. */
exclude?: string[];
/** Presentation patches 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[];
}
interface LocalRowAction {
name: string;
label: string;
icon?: string;
intent?: TDbActionInfo["intent"];
promptText?: string | [string, string];
/** Renders a real anchor, mapped through `state.resolveHref`. */
href?: (row: Record<string, unknown>) => string;
/** Awaited locally, then settled as an `@action` emit with `kind: 'custom'`. */
onInvoke?: (row: Record<string, unknown>, pk?: Record<string, unknown>) => void | Promise<void>;
/** Per-row gate: `false` hides, a non-empty string disables with that reason (since 0.1.144). */
enabled?: (row: Record<string, unknown>) => boolean | string;
}The server's per-row $actions gate runs before this policy, so include can only narrow what a row was already allowed and overrides never re-enable a gated action. include does not apply to extra — being listed there is the opt-in; include: [] therefore hides every server action and keeps the extras. The policy applies wherever row actions resolve: the row-actions cell, the level="row" selection toolbar and (since 0.1.144) the Enter / double-click main action — all through resolveRowActions.
ColumnMenuConfig
interface ColumnMenuConfig {
sort?: boolean;
filters?: boolean;
hide?: boolean;
/** "Reset width" entry — shown only when current ≠ default. */
resetWidth?: boolean;
}Row hooks
Exported types behind <AsTable>'s rowSelectable / rowClass / rowAttrs props. All new in 0.1.133.
/** Context handed to every per-row hook. */
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. */
selected: boolean;
}
/**
* Per-row selectability predicate. Return `false` — or a string, surfaced as
* the disabled reason on the selection control — to make the row not
* selectable; `true` (or omitting the prop) keeps it selectable.
*/
type RowSelectableHook = (row: Record<string, unknown>, ctx: RowHookContext) => boolean | string;
/** Extra classes for the row element. */
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.
*/
type RowAttrsHook = (
row: Record<string, unknown>,
ctx: RowHookContext,
) => Record<string, unknown> | undefined;
/** Normalised `RowSelectableHook` verdict. */
interface RowSelectableVerdict {
ok: boolean;
/** Disabled reason, when the predicate returned a string. */
reason?: string;
}
/** Header select-all tri-state, over the rows the header acts on. Exported since 0.1.142. */
type SelectAllState = "none" | "some" | "all";
/**
* What toggles a row's selection by pointer (`:select-on`): `"row"` — a click
* anywhere on the row (default); `"control"` — only the row's checkbox, a
* row click just moves the active row. Space / Enter behave the same in
* both. Since 0.1.142.
*/
type SelectOn = "row" | "control";A rejected row's selection control renders with as-table-checkbox-disabled (see @atscript/ui-styles), carries aria-disabled, and puts the reason in its accessible name.
PresetConfig
Preset feature configuration passed to useTable({ preset }) / <AsTableRoot :preset>. Presence of the object enables the feature; omit it entirely to disable.
interface PresetConfig {
/** Preset controller URL, e.g. `"/api/db/_presets"`. */
url: string;
/** Per-table identifier — scopes preset rows under `(app, tableKey)`. */
tableKey: string;
/** Optional override; defaults to `inject(AS_PRESETS_APP)`. */
app?: string;
/** Consumer-supplied synthetic system presets (`sys:*`, never persisted). */
systemPresets?: SystemPresetInput[];
/** App-declared aspect set. Default `['columns','filters','filterOps','sorters']`. */
aspects?: PresetAspect[];
/**
* Aspects a SYSTEM preset owns (since 0.1.133). 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.
*/
systemAspects?: PresetAspect[];
/** Opt-in localStorage overlay for in-flight tweaks. Default `false`. */
persistDrafts?: boolean;
/**
* Identity the draft is stored under (since 0.1.133) — pass the signed-in
* user's id whenever `persistDrafts` is on, so a shared browser never
* restores the previous user's draft. Reactive. Omitted keeps the
* pre-0.1.133 unscoped key.
*/
draftScope?: MaybeRefOrGetter<string | undefined>;
}PresetSurface
The preset namespace on state.preset. Always present; inert (available is false, mutators throw) when preset was not configured. Read-only refs for picker UI; mutators are pure batched writes and never call query() — the root watchers refetch.
- Rows:
presets,presetsById,userConf,capabilities,systemPresets,systemPresetsById. - Aspects:
availableAspects(app-declared; static), andsystemAspects(since 0.1.133) — the subset a SYSTEM preset owns, equal toavailableAspectsunlesspreset.systemAspectsnarrowed it. It drives apply/reset, the dirty baseline, the picker/dialog badges, and the Save-As defaults for system presets. - Status:
available(false whenpresetis absent, the initial load returned 401/403/404, or any other error — the picker / dialog hide themselves),activeId,activeSnapshot(since 0.1.141 pruned of fields the caller cannot use, so such a preset is not dirty; the stored row is untouched),isDirty,canSaveActive,currentUser,dialogOpen. - Dropped fields (since 0.1.141):
droppedFields: ComputedRef<DroppedFieldsReport | null>— what the active preset names that the caller cannot use, computed from the stored preset (alwayssource: "preset");nullwhen nothing is dropped.<AsPresetPicker>shows a quiet note while it is set.saveActiveappends those entries back after the visible ones;saveAsstores only what the caller can see. See Fields Hidden by Role. - Mutation status (since 0.1.133):
lastError: Ref<Error | null>— the error thrown by the most recent outermost mutator, cleared when the next outermost mutator starts (abatch()is one frame: the last failure inside it wins); mutators still rethrow, so a caller can handle a single call and this ref is for UI that only renders the failure. - Aspect ownership (since 0.1.133):
ownedAspects(id: string | null): PresetAspect[]—systemAspectsfor a system id, the stored row's ownaspectsfor a saved preset,availableAspectsotherwise. Apply, dirty baseline, badges and Save-as defaults all use it. - Methods:
captureSnapshot,apply,resetActive,clearLocalDraft,resolveDefaultId,saveActive,saveAs,rename,remove,togglePublic,setDefault,toggleFav,setFavorites,batch.
DroppedFieldsReport
Since 0.1.141. The @fields-dropped / onFieldsDropped payload. Extends DroppedFields from @atscript/ui-table (fields, columns, filterFields, filters, residual, sorters).
interface DroppedFieldsReport extends DroppedFields {
/** preset: a preset applied (the bootstrap default with the local draft included) · url: a restored URL (its dropped filter pieces are in `residual`). */
source: "preset" | "url";
/** The preset applied (`"preset"`). */
presetId?: string;
}RowDeleteOpt / InvokeOpts / NavKeyOptions / MainActionRequest / QueryErrorKind / TVueTableActionInfo
interface RowDeleteOpt {
label?: string;
icon?: string;
confirm?: string;
intent?: TDbActionInfo["intent"];
}
interface InvokeOpts {
suppressRefresh?: boolean;
event?: KeyboardEvent | MouseEvent;
input?: unknown;
row?: Record<string, unknown>;
/** Since 0.1.147: run a `'rows'` action on every row matching this query (`pk` = `undefined`). */
target?: ActionQueryTarget;
/** With `target`: the confirmed count — a different one answers 409 `TARGET_CHANGED`. */
expectCount?: number;
/** With `target`: asked once with the new count on `TARGET_CHANGED`; `true` runs again. */
confirmTargetChange?: (matched: number) => Promise<boolean>;
}
/** Since 0.1.147. The filter / search / index of a query + identifiers to leave out. */
type ActionQueryTarget = Pick<TDbQueryTarget, "filter" | "search" | "index" | "exclude" | "maxRows">;
/** Since 0.1.147 — `state.querySelection`. */
interface QuerySelection {
query: SelectionQuery; // { filter?, search?, index? }
signature: string; // selectionSignature(query)
excluded: unknown[]; // rowValueFn values unticked after "select all"
total: number; // rows the query matched (refreshed on same-scope refetches)
}
/** Since 0.1.147 — `state.selection`. */
type TableSelection =
| { mode: "ids"; ids: unknown[]; count: number }
| { mode: "query"; query: SelectionQuery; excluded: unknown[]; total: number; count: number };
/** Since 0.1.147 — `@selection-reset`. */
interface SelectionResetEvent {
reason: "scope";
}
interface NavKeyOptions {
enterAction?: "main-action" | "toggle-select" | "passthrough";
mode?: SelectionMode;
}
Since 0.1.133 Enter and Space are always left to native handling when the
event target (or an ancestor inside the cell) is interactive — `button`,
`a[href]`, form controls, `summary`, `[contenteditable]`, or a widget `role` —
and the row is not activated. An interactive element hands the keys back to
table navigation with the `data-as-nav-keys` attribute. Arrow and paging keys
are unaffected. The search-input bridge is not affected: its handler is bound
on the input itself.
interface MainActionRequest {
/** Active row, resolved nav-mode-aware via `state.getActiveRow()` — the reliable field on every page. */
row: Record<string, unknown>;
absIndex: number;
event: KeyboardEvent | MouseEvent;
}
type QueryErrorKind = "initial" | "query" | "queryNext" | "loadRange";
type TVueTableActionInfo = Omit<TDbActionInfo, "processor"> & {
processor: TDbActionProcessor | "__remove";
/** Set on the gated copy a surface renders when the row disabled it with a reason. Since 0.1.144. */
disabledReason?: string;
};Re-exports from @atscript/ui-table
ConfigTab, UrlQuerySync, SelectionQuery (since 0.1.147), AppConfData, AsPresetEntryRow, PresetAspect, PresetCapabilities, PresetData, PresetSnapshot, PresetSnapshotWire, SystemPreset, SystemPresetInput, UserConfData, PRESET_ASPECTS, STANDARD_PRESET_ID, SYSTEM_PRESET_PREFIX, isSystemPresetId, resolveSystemPresets. See @atscript/ui-table for definitions.
Re-exports from @atscript/ui
setDefaultClientFactory, getDefaultClientFactory, resetDefaultClientFactory, ClientFactory, TypedClientFactory.
Utilities
function getColumnWidth(column: ColumnDef, widths: ColumnWidthsMap): string;
function getCellValue(row: Record<string, unknown>, path: string): unknown;
/** Booleans read `UI_YES` / `UI_NO` through `t` (the active UI texts by default). */
function formatCellValue(value: unknown, type: string, t?: UiT): string;
function extractIdentifier(
source: unknown, // a row, or a scalar rowValueFn value
fields: readonly string[],
): Record<string, unknown> | undefined;
function identifierFieldsOf(def: TableDef | null | undefined): readonly string[]; // since 0.1.147
function actionIdentifiers(
action: Pick<TVueTableActionInfo, "idMap">,
ids: Record<string, unknown>[],
preferredId: readonly string[],
): Record<string, unknown>[]; // since 0.1.147
function queryTargetGate(count: number, t?: UiT): (a: TVueTableActionInfo) => boolean | string; // since 0.1.147
const QUERY_TARGET_UNSUPPORTED_REASON: string; // since 0.1.147 — the English text of UI_ACTION_QUERY_UNSUPPORTED
function resolveRowActions(
state: ReactiveTableState,
row: Record<string, unknown> | undefined,
opts?: { withRows?: boolean },
): ResolvedRowActions;
interface ResolvedRowActions {
default: TVueTableActionInfo | undefined; // actions.default.row
others: TVueTableActionInfo[]; // actions.others.row
rows: TVueTableActionInfo[]; // actions.rows ([] with withRows: false)
extra: TVueTableActionInfo[]; // RowActionsConfig.extra
}extractIdentifier builds the identifier object sent with action invocations and URL $1 substitution. Per @atscript/db-client invariant #11 the server rejects bare scalars — even single-field PK tables send { id: '...' }. Since 0.1.147 the built-in surfaces extract identifierFieldsOf(tableDef) — preferredId plus the columns a delegated action's idMap reads (dot paths keep their dotted key) — and actionIdentifiers narrows them per action: a delegated action keeps exactly its idMap paths (the client maps them to the owner's id), any other action exactly preferredId. See Row actions on a view.
queryTargetGate(count) is the toolbar's gate in a query selection: an action is enabled iff its queryTarget.maxRows covers count, else kept disabled with "At most N rows" (UI_ACTION_AT_MOST) or the UI_ACTION_QUERY_UNSUPPORTED text — QUERY_TARGET_UNSUPPORTED_REASON in English; pass useAsLocale().t to word them in the app's locale. Use it in a custom toolbar. See Select All Matching Rows.
resolveRowActions is the per-row pipeline every built-in surface uses (the row-actions cell, the level="row" toolbar, the main-action fallback), exported for a custom row-actions cell: the row's $actions / $disabledReasons gate and the :row-actions policy in one pass, plus the policy's extra actions. Hidden and excluded actions drop out; ones disabled with a reason come back as copies carrying disabledReason (render them disabled; state.actions.invoke does not check it). Untouched arrays keep their source reference. Since 0.1.144. See Disabled with a reason.
Cross-links
- Tables — Hello World
- Tables — Annotations Reference
- Tables — Query Function
- Tables — Filtering, Sorting
- Tables — Pagination & Virtualization
- Tables — Cells, Custom Cells
- Tables — Config Dialog
- Tables — URL State
- Tables — Presets, Server-Side Presets
- Tables — Actions & Selection
- Tables — Slot Overrides & Swaps
- @atscript/ui, @atscript/ui-table
- @atscript/moost-ui-presets