@atscript/ui-table 0.1.58

package/dist/index.d.cts

@@ -0,0 +1,1034 @@
+import { FilterExpr, Uniquery } from "@uniqu/core";
+import { ColumnDef, PaginationControl, SortControl, TableDef } from "@atscript/ui";
+import { Client } from "@atscript/db-client";
+
+//#region src/filters/filter-types.d.ts
+/** Filter condition type identifiers. */
+type FilterConditionType = "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "contains" | "starts" | "ends" | "bw" | "null" | "notNull" | "regex";
+/**
+ * A single filter condition applied to a field.
+ *
+ * - Most conditions use `value[0]`.
+ * - `bw` (between) uses `value[0]` (low) and `value[1]` (high).
+ * - `null`/`notNull` ignore value.
+ */
+interface FilterCondition {
+  type: FilterConditionType;
+  value: (string | number | boolean)[];
+}
+/** Filter conditions grouped by field path. */
+type FieldFilters = Record<string, FilterCondition[]>;
+//#endregion
+//#region src/filters/filter-conditions.d.ts
+/** Conditions that operate purely on nullability — value is ignored. */
+declare const NULL_OPS: ReadonlySet<FilterConditionType>;
+/** Check if a condition has a filled/meaningful value. */
+declare function isFilled(condition: FilterCondition): boolean;
+/** Check if a condition type requires a second value (between). */
+declare function hasSecondValue(type: FilterConditionType): boolean;
+declare function isSimpleEq(condition: FilterCondition): boolean;
+/** Human-readable label for a condition type. */
+declare function conditionLabel(type: FilterConditionType): string;
+/** Count of fields that have at least one filled condition. */
+declare function filledFilterCount(filters: FieldFilters): number;
+/** Summarize a field's conditions into a human-readable token label. */
+declare function filterTokenLabel(path: string, conditions: FilterCondition[], columnLabel?: string): string;
+//#endregion
+//#region src/filters/filter-conditions-map.d.ts
+/** Column type categories for condition availability. */
+type ColumnFilterType = "text" | "number" | "date" | "boolean" | "enum" | "ref";
+/**
+ * Available filter conditions for a given column filter type.
+ * Non-nullable columns drop `null` / `notNull` since they can never match.
+ */
+declare function conditionsForType(type: ColumnFilterType, nullable?: boolean): readonly FilterConditionType[];
+/** Map a ColumnDef display type string to a ColumnFilterType. */
+declare function columnFilterType(columnType: string): ColumnFilterType;
+//#endregion
+//#region src/filters/escape-regex.d.ts
+/** Escape special regex characters in user input for safe embedding in $regex. */
+declare function escapeRegex(input: string): string;
+/** Reverse of {@link escapeRegex}. */
+declare function unescapeRegex(input: string): string;
+//#endregion
+//#region src/filters/filter-input-format.d.ts
+/** Default condition type when no symbol matches the input. */
+declare function defaultCondition(columnType: ColumnFilterType): FilterConditionType;
+/**
+ * Parse a user-typed filter input string into a FilterCondition.
+ *
+ * Supports operator symbols:
+ *   *text*    → contains
+ *   text*     → starts with
+ *   *text     → ends with
+ *   =value    → eq (explicit)
+ *   !=value   → ne
+ *   >=value   → gte
+ *   >value    → gt
+ *   <=value   → lte
+ *   <value    → lt
+ *   lo...hi   → bw (between)
+ *   <empty>   → null
+ *   !<empty>  → notNull
+ *   /pattern/ → regex
+ *
+ * When no symbol matches, the default depends on columnType:
+ *   text/enum/ref → contains
+ *   number/date/boolean → eq
+ *
+ * Returns undefined for empty/invalid input or if the parsed operator
+ * is not available for the column type.
+ */
+declare function parseFilterInput(text: string, columnType: ColumnFilterType, nullable?: boolean): FilterCondition | undefined;
+/**
+ * Format a FilterCondition for chip/token display using operator symbols.
+ *
+ * Round-trips with parseFilterInput:
+ *   formatFilterCondition(parseFilterInput(text, type)) ≈ text
+ */
+declare function formatFilterCondition(condition: FilterCondition): string;
+//#endregion
+//#region src/filters/filters-to-uniquery.d.ts
+/**
+ * Convert UI filter model to a Uniquery FilterExpr.
+ *
+ * Combination logic:
+ * - Per field: inclusion (positive) conditions are OR'd, exclusion (negative) conditions are AND'd.
+ * - Across fields: all groups are AND'd at the top level.
+ *
+ * Returns `undefined` when no filled conditions exist.
+ */
+declare function filtersToUniqueryFilter(fieldFilters: FieldFilters): FilterExpr | undefined;
+//#endregion
+//#region src/filters/uniquery-to-filters.d.ts
+/**
+ * Convert a Uniquery `FilterExpr` back into the UI's `FieldFilters` shape.
+ *
+ * Inverse of `filtersToUniqueryFilter`. Drops:
+ * - conditions on fields not in `knownFields` (when provided)
+ * - operators not in the supported `FilterConditionType` union
+ * - `$not` branches (no native UI representation; lossy on hand-crafted URLs)
+ *
+ * Returns `{}` for an empty/missing expression. Never throws.
+ */
+declare function uniqueryFilterToFieldFilters(expr: FilterExpr | undefined, knownFields?: Iterable<string> | Set<string>): FieldFilters;
+//#endregion
+//#region src/filters/date-shortcuts.d.ts
+/** A date shortcut produces a label and a [start, end] ISO date range. */
+interface DateShortcut {
+  label: string;
+  dates: [start: string, end: string];
+}
+/**
+ * Generate date filter shortcuts relative to the given date (defaults to now).
+ * Each shortcut produces a `bw` (between) condition range using ISO date strings (YYYY-MM-DD).
+ */
+declare function dateShortcuts(now?: Date): DateShortcut[];
+//#endregion
+//#region src/presets/preset-types.d.ts
+/**
+ * In-memory snapshot of table state for preset persistence. Dict-shaped
+ * aspects (`columns.columnWidths`, `filterOps`) match the runtime state
+ * shape. The wire form (entries-arrays for atscript validation) is
+ * `PresetSnapshotWire` in `./preset-wire-types`.
+ *
+ * Per-aspect opt-in: a key's presence claims that aspect; absent keys are
+ * left untouched on apply.
+ */
+interface PresetSnapshot {
+  columns?: {
+    columnNames: string[]; /** Override-only diff against column defaults. Never serialise the default. */
+    columnWidths?: Record<string, string>;
+  };
+  /** Displayed filter field paths (the visible-input list). */
+  filters?: string[];
+  /** Applied filter conditions, dict keyed by field path. */
+  filterOps?: FieldFilters;
+  sorters?: SortControl[];
+  itemsPerPage?: number;
+}
+//#endregion
+//#region src/presets/preset-wire-types.d.ts
+interface PresetColumnWidthEntry {
+  field: string;
+  width: string;
+}
+interface PresetFilterOpEntry {
+  field: string;
+  conditions: FilterCondition[];
+}
+interface PresetSorterEntry {
+  field: string;
+  direction: "asc" | "desc";
+}
+/**
+ * Wire-format snapshot stored in `AsPresetEntry.data.content`. Dict-shaped
+ * in-memory aspects (`columnWidths`, `filterOps`) become entries-arrays at
+ * the serializer boundary so atscript can validate them strictly — atscript
+ * has no `Record<string, T>` / `additionalProperties` construct.
+ *
+ * The client-side dict form is `PresetSnapshot` in `./preset-types`. Use
+ * `toWireSnapshot` / `fromWireSnapshot` (in `./preset-wire`) to bridge them.
+ */
+interface PresetSnapshotWire {
+  columns?: {
+    columnNames: string[];
+    columnWidths?: PresetColumnWidthEntry[];
+  };
+  filters?: string[];
+  filterOps?: PresetFilterOpEntry[];
+  sorters?: PresetSorterEntry[];
+  itemsPerPage?: number;
+}
+//#endregion
+//#region src/presets/preset-aspects.d.ts
+declare const PRESET_ASPECTS: readonly ["columns", "filters", "filterOps", "sorters", "itemsPerPage"];
+type PresetAspect = (typeof PRESET_ASPECTS)[number];
+/**
+ * Per-aspect opt-in/out for `captureSnapshot(mask)`. A `true` flag includes
+ * the aspect; `false` / absent excludes. The capture filter intersects the
+ * mask with `availablePresetAspects` so unavailable aspects never leak in.
+ */
+type AspectMask = Partial<Record<PresetAspect, boolean>>;
+declare function derivePresetAspects(content: unknown): PresetAspect[];
+//#endregion
+//#region src/presets/preset-wire.d.ts
+/**
+ * Convert in-memory dict-form snapshot to the wire form persisted on the
+ * server. Entries-arrays are sorted by `field` so consumers (server-side
+ * aspect derivation, dirty detection, equality checks) see a stable order.
+ */
+declare function toWireSnapshot(snapshot: PresetSnapshot): PresetSnapshotWire;
+declare function fromWireSnapshot(wire: PresetSnapshotWire): PresetSnapshot;
+//#endregion
+//#region src/presets/preset-data-types.d.ts
+/**
+ * Wire-shape `data` payload for `type='preset'` rows on `AsPresetEntry`. The
+ * server validates `content` against the wire shape; the client converts to
+ * dict-form `PresetSnapshot` via `fromWireSnapshot` for in-memory use.
+ */
+interface PresetData {
+  /** User-visible label. Public-name uniqueness within `(app, tableKey)`. */
+  label: string;
+  /**
+   * Wire-form snapshot. The set of present top-level keys drives the
+   * top-level `aspects` column on the row — derived automatically on every
+   * preset write so picker queries can project `aspects` without loading
+   * `data`.
+   */
+  content?: PresetSnapshotWire;
+}
+/**
+ * Per-user, per-table configuration row (`type='userConf'`, deterministic
+ * id `uc:${user}:${app}:${tableKey}`). Carries preferences that are
+ * inherently per-table (preset pins / favorites); app-wide prefs live on
+ * `AppConfData`.
+ */
+interface UserConfData {
+  /**
+   * Stable preset id (or `'sys:<id>'` for system presets) pinned as the
+   * default for this table. Resolution is tolerant — a stale id is left
+   * intact and may reactivate if the referenced preset returns.
+   */
+  defaultPresetId?: string;
+  favPresetIds?: string[];
+}
+/**
+ * Per-user, app-wide configuration row (`type='appConf'`, deterministic id
+ * `ac:${user}:${app}`). Holds preferences that are inherently app-scoped —
+ * duplicating per-table would let them drift.
+ */
+interface AppConfData {
+  appearance?: "system" | "light" | "dark";
+  /** BCP-47 language tag (`'en'`, `'en-US'`). Max 5 chars. */
+  language?: string;
+  /** IANA timezone name (`'America/New_York'`). Max 64 chars. */
+  timezone?: string;
+  density?: "compact" | "cozy" | "comfortable";
+  dateFormat?: "iso" | "us" | "eu";
+  /** 0 = Sunday, 1 = Monday, 6 = Saturday. */
+  firstDayOfWeek?: 0 | 1 | 6;
+  /** Escape hatch for app-specific user prefs. Capped at 1024 chars. */
+  customJson?: string;
+}
+type AsPresetEntryData = PresetData | UserConfData | AppConfData;
+type AsPresetsErrorCode = "preset_limit_reached" | "reserved_id" | "public_name_conflict" | "missing_scope" | "missing_id" | "invalid_type" | "type_immutable" | "identity_immutable" | "preset_not_found" | "publish_forbidden" | "action_unsupported";
+/** 409 body returned when a user's per-`(app, tableKey)` preset cap would be exceeded. */
+interface PresetLimitReachedBody {
+  code: "preset_limit_reached";
+  limit: number;
+  count: number;
+}
+/**
+ * Browser-side row shape for `AsPresetEntry`. The server-authoritative
+ * shape lives in `@atscript/moost-ui-presets`'s generated `.as.d.ts`; this
+ * type duplicates the runtime view so client code (composables, picker,
+ * dialog) never imports the server-only package.
+ */
+interface AsPresetEntryRow {
+  id: string;
+  type: "preset" | "userConf" | "appConf";
+  app: string;
+  tableKey?: string;
+  user: string;
+  /**
+   * Display label for `user` (e.g. their username) — server-stamped on every
+   * write via `AsPresetsController.getUserLabel`. Optional: when the
+   * controller doesn't override the hook, this is `undefined` and surfaces
+   * fall back to rendering `user`.
+   */
+  userLabel?: string;
+  /** Preset-only top-level mirror; controller stamps on every preset write. */
+  public?: boolean;
+  /** Preset-only top-level mirror of `data.label`; stamped by controller. */
+  label?: string;
+  /** Equals `label` when `public=true`, else absent. Composite-unique on `(app,tableKey,publicLabel)`. */
+  publicLabel?: string;
+  /** Derived by the controller from `data.content` keys. */
+  aspects?: PresetAspect[];
+  data: AsPresetEntryData;
+  createdAt: number;
+  updatedAt: number;
+}
+/**
+ * Per-`(app, tableKey, user)` capabilities surfaced to the client so the UI
+ * can hide "Save as public" / disable "Save" before the user submits. Backed
+ * by the same hooks the write path uses, so client-side checks and
+ * server-side enforcement can never diverge.
+ */
+interface PresetCapabilities {
+  /** Whether the current user may set `public: true` on presets in this scope. */
+  canPublish: boolean;
+  /** Per-`(app, tableKey, user)` preset cap. Picker derives "near limit" by counting owned rows locally. */
+  presetLimit: number;
+  /**
+   * Server-known opaque identity for the current user (whatever
+   * `getCurrentUser` returns). Used by the picker / dialog to classify rows
+   * as "owned" without needing to derive it from the presets list — which
+   * fails when a user has *only* public presets (every private-row check
+   * falls back to null and own-public rows look like others-public). The
+   * controller is the single source of truth for identity, so plumbing it
+   * here also closes a class of off-by-one bugs across surfaces.
+   */
+  userId: string;
+}
+//#endregion
+//#region src/presets/preset-id.d.ts
+/** Reserved id namespace for synthetic system presets; rejected on write. */
+declare const SYSTEM_PRESET_PREFIX = "sys:";
+/** Deterministic id prefix for `type='userConf'` rows: `uc:${user}:${app}:${tableKey}`. */
+declare const USER_CONF_PREFIX = "uc:";
+/** Deterministic id prefix for `type='appConf'` rows: `ac:${user}:${app}`. */
+declare const APP_CONF_PREFIX = "ac:";
+/** All prefixes the server owns; client-supplied ids starting with any of these are rejected. */
+declare const RESERVED_ID_PREFIXES: readonly ["sys:", "uc:", "ac:"];
+/** Always-materialised system preset id; consumer may override label/content. */
+declare const STANDARD_PRESET_ID: "sys:standard";
+declare function userConfId(user: string, app: string, tableKey: string): string;
+declare function appConfId(user: string, app: string): string;
+declare function isSystemPresetId(id: string | null | undefined): boolean;
+/**
+ * Auto-prefix a bare system-preset id (`'monitoring'` → `'sys:monitoring'`).
+ * Returns the input unchanged if it already carries the prefix.
+ */
+declare function normaliseSystemPresetId(id: string): string;
+//#endregion
+//#region src/presets/system-presets.d.ts
+/**
+ * Synthetic preset that lives only in memory — never persisted. Always
+ * present in the picker; users branch off via Save-as into a regular owned
+ * preset to evolve it.
+ */
+interface SystemPreset {
+  /** Canonical `sys:*` form after normalisation. */
+  id: string;
+  label: string;
+  /** Baseline snapshot. Empty `{}` falls through to factory defaults. */
+  content: PresetSnapshot;
+}
+/**
+ * Consumer-supplied entry. `content` is optional so a consumer can override
+ * Standard's label without supplying a snapshot.
+ */
+interface SystemPresetInput {
+  /** Bare ids are auto-prefixed (`'monitoring'` → `'sys:monitoring'`). */
+  id: string;
+  label: string;
+  content?: PresetSnapshot;
+}
+/**
+ * Resolve the consumer's `:system-presets` prop into the canonical render
+ * order: Standard at index 0 (consumer override or default empty fallback),
+ * named system presets in array order. Duplicate ids are dropped with a
+ * console.warn (first wins).
+ */
+declare function resolveSystemPresets(input?: SystemPresetInput[]): SystemPreset[];
+//#endregion
+//#region src/presets/preset-dirty.d.ts
+/**
+ * JSON-stringify with object keys sorted alphabetically at every depth so
+ * dict-shaped values (`columnWidths`, `filterOps` after deserialisation)
+ * compare structurally regardless of insertion order. Arrays preserve order.
+ *
+ * Used by the localStorage draft serializer (where a stable string is
+ * needed for storage); dirty detection prefers `isDirtyAgainst` (no
+ * stringify, short-circuits on first mismatch).
+ */
+declare function stableStringify(value: unknown): string;
+/**
+ * Per-aspect dirty check: only aspects the active preset claims (key
+ * present) are compared. A column-only preset stays clean while filters
+ * change; a filter-ops-only preset doesn't dirty when columns reorder.
+ *
+ * `current` should be the full snapshot of all available aspects (i.e.
+ * `captureSnapshot()` output) so each claimed aspect on the active preset
+ * has something to compare against.
+ */
+declare function isDirtyAgainst(active: PresetSnapshot, current: PresetSnapshot): boolean;
+//#endregion
+//#region src/presets/preset-draft.d.ts
+/**
+ * localStorage overlay shape. Subset of `PresetSnapshot` — `filterOps` is
+ * intentionally excluded (filter values are situational; restoring them on
+ * mount surprises users — see PRESETS-PHASE-2 §3.8). `itemsPerPage` is
+ * gated on `availableAspects`.
+ */
+type PresetDraft = Omit<PresetSnapshot, "filterOps">;
+/** Aspects eligible for local-draft persistence. `filterOps` is excluded by design. */
+declare const DRAFT_PERSISTED_ASPECTS: readonly ["columns", "filters", "sorters", "itemsPerPage"];
+type DraftPersistedAspect = (typeof DRAFT_PERSISTED_ASPECTS)[number];
+/**
+ * Capture the persisted-aspect subset of a full snapshot. Aspects not in
+ * `availableAspects` are skipped (forward-compat: a deploy that toggles an
+ * aspect off doesn't error on previously-saved drafts).
+ */
+declare function serializeDraft(snapshot: PresetSnapshot, availableAspects: readonly PresetAspect[]): PresetDraft;
+/**
+ * Convert a localStorage draft back to a partial snapshot suitable for
+ * `applyPreset`. Aspects no longer in `availableAspects` are silently
+ * skipped.
+ */
+declare function deserializeDraft(draft: PresetDraft, availableAspects: readonly PresetAspect[]): PresetSnapshot;
+/** True when the draft has zero persisted aspects to apply. */
+declare function isEmptyDraft(draft: PresetDraft): boolean;
+/**
+ * True when the draft's persisted aspects exactly match the active
+ * preset's persisted aspects. Used by the watcher to decide whether to
+ * `localStorage.removeItem` instead of writing — keeps storage tidy and
+ * avoids `localStorage.length` noise after the user reverts edits.
+ */
+declare function draftMatchesPreset(draft: PresetDraft, presetSnapshot: PresetSnapshot, availableAspects: readonly PresetAspect[]): boolean;
+//#endregion
+//#region src/presets/presets-client.d.ts
+/**
+ * Configuration for a `PresetsClient`. Either pass a pre-built `client`
+ * (already wired with auth/fetch by the consumer's `ClientFactory`), or
+ * pass `clientFactory + url` so the wrapper builds one. The capabilities
+ * endpoint is fetched outside the standard CRUD path; if your app uses
+ * non-cookie auth, supply `fetch` so headers/credentials propagate.
+ */
+interface PresetsClientConfig {
+  /** Controller mount URL, e.g. `"/db/_presets"`. Required. */
+  url: string;
+  app: string;
+  tableKey: string;
+  /** Pre-built Client (auth-configured by the host). Wins over `clientFactory`. */
+  client?: Client;
+  /** Builds a Client for the given URL. Defaults to the app-wide `getDefaultClientFactory()`. */
+  clientFactory?: (url: string) => Client;
+  /**
+   * Fetch implementation for the `GET /capabilities` side-channel. Defaults
+   * to `globalThis.fetch`. Cookie-based auth needs no override.
+   */
+  fetch?: typeof globalThis.fetch;
+}
+interface PresetsListResult {
+  /** type='preset' rows. */
+  presets: AsPresetEntryRow[];
+  /** type='userConf' row for this `(user, app, tableKey)`, or null. */
+  userConf: AsPresetEntryRow | null;
+  /**
+   * Server-issued capabilities. `null` when capabilities load failed (auth,
+   * network). `undefined` when this call skipped the capabilities fetch
+   * (refresh-after-mutation) — callers should leave their cached value
+   * untouched.
+   */
+  capabilities: PresetCapabilities | null | undefined;
+  /** True when the controller responded 401/403 — UI silently hides. */
+  denied: boolean;
+}
+interface PresetsSaveAsOptions {
+  public?: boolean;
+}
+interface PresetsSaveResult {
+  id: string;
+}
+/**
+ * Framework-agnostic wrapper over `@atscript/db-client`'s `Client` for the
+ * `AsPresetEntry` table. Handles wire serialisation, list-splitting by
+ * `type`, capabilities side-channel, and 401/403 → `denied` semantics.
+ *
+ * Stateless: every method is a fresh request. The Vue composable layer
+ * holds reactive state; this class only translates intent → HTTP.
+ */
+declare class PresetsClient {
+  private readonly url;
+  private readonly app;
+  private readonly tableKey;
+  private readonly client;
+  private readonly fetchImpl;
+  constructor(cfg: PresetsClientConfig);
+  /**
+   * Lists owned + public preset rows AND the user's userConf row for this
+   * `(app, tableKey)`. By default also fetches `capabilities` in parallel —
+   * pass `{ capabilities: false }` for refresh-after-mutation calls (fav
+   * toggle, default change, save/save-as, public toggle, rename, delete)
+   * where role-derived capabilities can't have changed. Auth errors
+   * (401/403) collapse to `denied: true` with empty data so the UI hides
+   * itself silently.
+   */
+  list(opts?: {
+    capabilities?: boolean;
+  }): Promise<PresetsListResult>;
+  /** GET `${url}/capabilities?app=…&tableKey=…`. Out-of-band of CRUD plumbing. */
+  loadCapabilities(): Promise<PresetCapabilities>;
+  /**
+   * Overwrite the active preset's content. Server shallow-merges `data` so
+   * `label` is preserved on the row regardless — the caller sends it
+   * anyway because the client-side validator can't pick the preset
+   * variant of the `data` union without `label` present (it's required
+   * on that variant).
+   */
+  savePreset(id: string, label: string, snapshot: PresetSnapshot): Promise<void>;
+  /**
+   * Create a new preset row. Server stamps `user`, generates a UUID `id`,
+   * and derives `aspects` from the snapshot keys.
+   */
+  savePresetAs(label: string, snapshot: PresetSnapshot, opts?: PresetsSaveAsOptions): Promise<PresetsSaveResult>;
+  /** Update only the label. Server re-stamps top-level `label` + `publicLabel`. */
+  renamePreset(id: string, label: string): Promise<void>;
+  /** Toggle `public`. Server re-stamps `publicLabel` accordingly. */
+  setPublic(id: string, value: boolean): Promise<void>;
+  deletePreset(id: string): Promise<void>;
+  /**
+   * Upsert the userConf row keyed on `${USER_CONF_PREFIX}${user}:${app}:${tableKey}`.
+   * Caller must know whether the row exists from a prior `list()` so we
+   * pick the right verb. Server forces `user` and `id` on insert.
+   */
+  upsertUserConf(existing: AsPresetEntryRow | null, patch: Partial<UserConfData>, user?: string): Promise<void>;
+}
+/**
+ * Error raised for non-2xx responses on the capabilities side-channel.
+ * Standard CRUD errors flow through `Client`'s `ClientError`.
+ */
+declare class PresetsHttpError extends Error {
+  readonly status: number;
+  constructor(status: number, message: string);
+}
+/** True for HTTP 401/403 across both `ClientError` and `PresetsHttpError`. */
+declare function isAuthError(err: unknown): boolean;
+//#endregion
+//#region src/presets/app-prefs-client.d.ts
+/**
+ * Configuration for an `AppPrefsClient`. App-wide user prefs (`appConf`)
+ * have no `tableKey` — they're scoped per `(user, app)` only.
+ */
+interface AppPrefsClientConfig {
+  /** Same controller URL the presets table is mounted on. */
+  url: string;
+  app: string;
+  /** Pre-built Client (auth-configured by host). */
+  client?: Client;
+  /** Builds a Client when `client` is absent. Defaults to the app-wide `getDefaultClientFactory()`. */
+  clientFactory?: (url: string) => Client;
+}
+interface AppPrefsLoadResult {
+  /** Full row (server-stamped id, user, timestamps), or `null` when none exists. */
+  row: AsPresetEntryRow | null;
+  /** Convenience accessor for `row.data` (the typed prefs payload), or `null`. */
+  prefs: AppConfData | null;
+  /** True when the controller responded 401/403. */
+  denied: boolean;
+}
+/**
+ * Framework-agnostic wrapper for app-wide user preferences (`type='appConf'`).
+ * Independent of the preset/userConf surface — devs use this directly to
+ * read/write `appearance`, `language`, `density`, etc., without involving
+ * any table.
+ */
+declare class AppPrefsClient {
+  private readonly app;
+  private readonly client;
+  constructor(cfg: AppPrefsClientConfig);
+  /** Fetch the single `appConf` row for `(user, app)`. */
+  load(): Promise<AppPrefsLoadResult>;
+  /**
+   * Upsert the `appConf` row. Server forces `id` from session and shallow-
+   * merges `data` so partial patches don't wipe unrelated fields. Caller
+   * passes the prior `existing` row from `load()` so we pick the right verb.
+   *
+   * Returns the row id that owns the value after the write — useful for
+   * state tracking after the first insert (subsequent saves take the
+   * update path).
+   */
+  save(existing: AsPresetEntryRow | null, patch: Partial<AppConfData>, user?: string): Promise<string | null>;
+}
+//#endregion
+//#region src/query/build-table-query.d.ts
+/** Options for building a Uniquery from table state. */
+interface BuildTableQueryOptions {
+  /** Paths of visible columns — used for `$select` projection. */
+  visibleColumnPaths: string[];
+  /** User-configured sorters. */
+  sorters: SortControl[];
+  /** Always-applied sorters (prepended before user sorters). */
+  forceSorters?: SortControl[];
+  /** User-configured field filters. */
+  filters: FieldFilters;
+  /** Always-applied Uniquery filter (AND'd with user filters). */
+  forceFilters?: FilterExpr;
+  /** Full-text search term. */
+  search?: string;
+  /** Search index name for `$search`. */
+  searchIndex?: string;
+  /**
+   * Set `controls.$actions = true` so each returned row carries
+   * `$actions: string[]` — server-evaluated names of row/rows-level actions
+   * NOT disabled for that row. Off by default; renderers flip it on when a
+   * row-actions column will render gateable actions.
+   */
+  includeActions?: boolean;
+}
+/**
+ * Build a Uniquery object from table UI state.
+ *
+ * Pure function — no framework dependencies.
+ * Combines user filters with force filters, merges sorters,
+ * projects visible columns, and applies pagination.
+ */
+declare function buildTableQuery(opts: BuildTableQueryOptions): Uniquery;
+//#endregion
+//#region src/query/merge-sorters.d.ts
+/**
+ * Merge force sorters with user sorters.
+ *
+ * Force sorters come first and take priority — if a field appears
+ * in both lists, the force entry wins and the user entry is dropped.
+ */
+declare function mergeSorters(forceSorters: SortControl[], userSorters: SortControl[]): SortControl[];
+//#endregion
+//#region src/query/merge-filters.d.ts
+/**
+ * AND-merge two filter expressions, producing a wire shape that survives
+ * `@uniqu/url`'s `mergeConjunction` parser collapse.
+ *
+ * The collapse problem: when two `$and` siblings target the same field
+ * with the same op (e.g. `{status: 'cancelled'}` AND `{status: 'shipped'}`),
+ * the parser silently merges them on the receiving end and one clause is
+ * dropped. This would let a colliding user-side filter erase a
+ * `forceFilters` clause, breaking that contract.
+ *
+ * Fix: detect same-field same-op collisions and wrap each repeat in
+ * `$not({$not: ...})`. `$not` nodes are preserved verbatim by the parser,
+ * and `!!p ≡ p` is a semantic identity, so the server evaluator sees the
+ * same AND. Non-colliding merges produce the canonical `$and` shape.
+ */
+declare function mergeFilters(a: FilterExpr | undefined, b: FilterExpr | undefined): FilterExpr | undefined;
+//#endregion
+//#region src/query/url-query.d.ts
+/** State subset that round-trips through the URL bridge. */
+interface UrlQueryStateLike {
+  filters: FieldFilters;
+  sorters: SortControl[];
+  /** 1-based page number. `1` is the default and is omitted from the URL. */
+  page?: number;
+  /** Per-page size. Omitted from the URL when equal to `defaultItemsPerPage`. */
+  itemsPerPage?: number;
+  /** Full-text search term. Omitted from the URL when empty. */
+  searchTerm?: string;
+}
+/** Snapshot recovered from a URL string — partial on purpose so callers can layer it onto state. */
+interface UrlQueryStateSnapshot {
+  filters: FieldFilters;
+  sorters: SortControl[];
+  /**
+   * Raw record offset from `$skip` (omitted when no `$skip` in URL). The
+   * decoder does NOT compute a page index — that requires `itemsPerPage`,
+   * which is the consumer's private preference. Consumers compute
+   * `page = Math.floor(skip / currentItemsPerPage) + 1`.
+   */
+  skip?: number;
+  searchTerm: string;
+}
+/**
+ * Per-aspect opt-in/out for the URL bridge. Honoured symmetrically by both
+ * `stateToUrlQueryString` (encoder) and `urlQueryStringToState` (decoder) —
+ * the same gate must apply to both directions or the `lastEmittedUrl`
+ * echo guard mismatches and produces self-echoing URLs.
+ *
+ * Default (omitted, or any field `undefined` / `true`): full sync — backward
+ * compatible with pre-`UrlQuerySync` behaviour.
+ */
+interface UrlQuerySync {
+  /**
+   * Filters round-trip.
+   * - `true` / `undefined` (default): all filters.
+   * - `false` / `[]`: no filters in URL; `applyUrlQuery` skips filter writes.
+   * - `string[]`: only listed field paths; non-allowlist filters stay private.
+   */
+  filters?: boolean | string[];
+  /** Sorters — same `boolean | string[]` semantics, allowlist matches `SortControl.field`. */
+  sorters?: boolean | string[];
+  /** Whether `searchTerm` syncs as `$search`. Default true. */
+  search?: boolean;
+  /** Whether pagination (`$skip` + `$limit`) syncs. Page and limit are coupled — one knob. */
+  pagination?: boolean;
+}
+interface UrlQueryDefaults {
+  /** Consumer's `:limit` prop. Used to omit `$limit` from the URL when state matches it. */
+  defaultItemsPerPage: number;
+  /** Per-aspect sync gates. Omitted = full sync (existing behaviour). */
+  sync?: UrlQuerySync;
+}
+/**
+ * Resolve a `boolean | string[]` aspect gate into a tri-state:
+ * - `"all"` → pass through unchanged
+ * - `"none"` → empty / off
+ * - `Set<string>` → allowlist
+ */
+type AspectGate = "all" | "none" | Set<string>;
+declare function resolveAspectGate(value: boolean | string[] | undefined): AspectGate;
+/**
+ * Serialize the table state subset into a URL query string.
+ *
+ * Reuses `buildTableQuery` for the filter/sort/search shape (no `$select`,
+ * `$actions`, `forceFilters`, `forceSorters` — those are not user state) and
+ * appends `$skip` / `$limit` for pagination.
+ *
+ * Returns `""` (no leading `?`) for the default view.
+ */
+declare function stateToUrlQueryString(state: UrlQueryStateLike, defaults: UrlQueryDefaults): string;
+interface UrlQueryParseOptions {
+  /**
+   * Field paths the table knows about. Conditions on fields outside this set
+   * are silently dropped. Omit to accept any field (useful when the table
+   * definition isn't loaded yet).
+   */
+  knownFields?: Iterable<string>;
+  /** Per-aspect sync gates — must match the encoder's config to keep the round-trip symmetric. */
+  sync?: UrlQuerySync;
+}
+/**
+ * Parse a URL query string back into the table state subset.
+ *
+ * Robust by design — schema drift and copy-paste errors must not break the
+ * recipient's view:
+ * - unknown fields (not in `knownFields`) → silently dropped
+ * - unsupported operators → silently dropped
+ * - unknown controls (e.g. `$weird=42`) → silently ignored
+ * - malformed query → `{ filters: {}, sorters: [], searchTerm: "" }`
+ *
+ * `page` and `itemsPerPage` are returned only when the URL specified them
+ * (`$skip` / `$limit`); callers compose them onto state without overwriting
+ * defaults when the URL was silent.
+ */
+declare function urlQueryStringToState(urlString: string, opts?: UrlQueryParseOptions): UrlQueryStateSnapshot;
+//#endregion
+//#region src/selection/selection-fns.d.ts
+/** Selection mode. */
+type SelectionMode = "none" | "single" | "multi";
+/**
+ * Toggle a single PK in the selection.
+ *
+ * - `"none"`: no-op (returns the same array reference).
+ * - `"single"`: replaces the selection. Toggling the already-selected PK clears it.
+ * - `"multi"`: adds when absent, removes when present. Order preserved on add (append).
+ *
+ * Always returns a new array on actual mutation; returns the same reference for `"none"`.
+ */
+declare function togglePk(selection: readonly unknown[], pk: unknown, mode: SelectionMode): unknown[];
+/**
+ * Drop every PK in `selection` that's not in `presentPks`.
+ *
+ * Returns the same `selection` reference when nothing was dropped, so callers
+ * can rely on identity comparison to detect a no-op without an explicit
+ * length check.
+ */
+declare function trimSelection(selection: readonly unknown[], presentPks: ReadonlySet<unknown>): unknown[];
+/** Map rows to their PKs via `rowValueFn`. */
+declare function rowsToPks(rows: readonly Record<string, unknown>[], rowValueFn: (row: Record<string, unknown>) => unknown): unknown[];
+//#endregion
+//#region src/columns/column-widths.d.ts
+/** Per-column width entry: `w` is the rendered width, `d` is the default. */
+interface ColumnWidthEntry {
+  w: string;
+  d: string;
+}
+/** Map keyed by `ColumnDef.path`. Always fully populated for every column. */
+type ColumnWidthsMap = Record<string, ColumnWidthEntry>;
+/** Upper bound applied only to default-width computation. Annotation widths and manual resize are not capped. */
+declare const MAX_DEFAULT_COLUMN_WIDTH_PX = 320;
+/**
+ * Computes a sane default width for a column from its type + length annotation.
+ *
+ * Resolution order:
+ *   1. col.width (`@ui.table.width` annotation) wins outright.
+ *   2. Otherwise pick from a type-based table; for `text` columns with `maxLen`,
+ *      derive from char-count using an 8px-per-char heuristic.
+ *   3. Cap the result at MAX_DEFAULT_COLUMN_WIDTH_PX (does not apply to step 1).
+ */
+declare function computeDefaultColumnWidth(col: ColumnDef): string;
+/**
+ * Reconciles a current ColumnWidthsMap against the latest column list:
+ *   - new columns get a fresh `{ w: d, d }` entry where `d = computeDefaultColumnWidth(col)`
+ *   - existing columns keep `w` (preserves manual resize) but refresh `d`
+ *   - paths no longer present are kept (preserves user widths if columns reappear)
+ *
+ * Returns a NEW map only when something actually changed; otherwise returns `current`
+ * so a shallowRef writer can short-circuit.
+ */
+declare function reconcileColumnWidthDefaults(allColumns: ColumnDef[], current: ColumnWidthsMap): ColumnWidthsMap;
+//#endregion
+//#region src/state/table-state-types.d.ts
+type ConfigTab = "columns" | "filters" | "sorters";
+/**
+ * Framework-agnostic table state data.
+ *
+ * Defines the contract that any framework wrapper (Vue/React) must implement.
+ * Values are plain — the framework wraps them in its own reactive primitives.
+ */
+interface TableStateData {
+  /** Resolved table definition (null until metadata loads). */
+  tableDef: TableDef | null;
+  /** True while the table metadata (TableDef) is being loaded. */
+  loadingMetadata: boolean;
+  /** Names of visible columns, in display order. */
+  columnNames: string[];
+  /** Current visible columns (derived from columnNames + allColumns). */
+  columns: ColumnDef[];
+  /** All columns from tableDef (including hidden). */
+  allColumns: ColumnDef[];
+  /**
+   * Per-column widths keyed by column path. Always fully populated for every
+   * column in `allColumns` once the TableDef has loaded. Each entry carries
+   * the current rendered width (`w`) and the default (`d`) it would reset to.
+   * Default sourcing: `@ui.table.width` annotation > type+@expect.maxLen-derived.
+   */
+  columnWidths: ColumnWidthsMap;
+  /** Names of filter fields displayed in the filter bar. */
+  filterFields: string[];
+  /** Active field filters. */
+  filters: FieldFilters;
+  /** Active sorters. */
+  sorters: SortControl[];
+  /**
+   * Rows of the contiguous "results island" anchored at `resultsStart`. This
+   * is a real array (not a computed view) — same row references also live in
+   * `windowCache` at their absolute indices. Writes flow through both, so
+   * extending `results` automatically updates the cache.
+   */
+  results: Record<string, unknown>[];
+  /**
+   * Absolute row index where `results[0]` sits. Reset by `query()` and
+   * `invalidate()` from `pagination.page`; shifted by backward merges in
+   * `loadRange`'s digest.
+   */
+  resultsStart: number;
+  /**
+   * Universal storage for every loaded row keyed by absolute index. Includes
+   * the rows in `results` (same row references, two indexings).
+   */
+  windowCache: Map<number, Record<string, unknown>>;
+  /**
+   * Block firstIndex values currently being fetched by `loadRange`. A row at
+   * `absIdx` is in flight when its block (`floor(absIdx / blockSize) * blockSize`)
+   * is in this set. Drives the per-row skeleton placeholder in window-mode
+   * rendering. NOT set by `query()` (uses `querying`) or `queryNext()` (uses
+   * `queryingNext`).
+   */
+  windowLoading: Set<number>;
+  /** Absolute row index at the top of a windowed renderer's visible viewport. */
+  topIndex: number;
+  /** Number of fixed-pool rows a windowed renderer is currently displaying. */
+  viewportRowCount: number;
+  /** Whether a query is currently in flight. */
+  querying: boolean;
+  /** Whether a "load more" query is in flight. */
+  queryingNext: boolean;
+  /** Total row count from the server. */
+  totalCount: number;
+  /** Number of rows currently loaded. */
+  loadedCount: number;
+  /** Pagination state. */
+  pagination: PaginationControl;
+  /** Last query error (null when successful). */
+  queryError: Error | null;
+  /** Metadata loading error (null when successful). */
+  metadataError: Error | null;
+  /** True when state changed during an in-flight query (results are stale). */
+  mustRefresh: boolean;
+  /** Full-text search term. */
+  searchTerm: string;
+}
+/**
+ * Methods that any table state implementation must provide.
+ *
+ * The table is model-driven: these mutators are thin wrappers that each touch
+ * exactly one entity (`filterFields` OR `filters`, never both). Side effects
+ * like pagination reset or re-query happen in watchers on the root state arrays,
+ * not inside the mutators — so any writer (dialog, external v-model, custom
+ * toolbar) gets identical behaviour.
+ */
+interface TableStateMethods {
+  /**
+   * Microtask-coalesced refresh. Synchronously sets `querying = true` so
+   * consumers see the loading state immediately, then schedules the actual
+   * fetch on the next microtask. Multiple `query()` calls and watcher-driven
+   * scheduleQuery calls in the same synchronous block coalesce into one
+   * fetch. Use this from dialogs / mutators where you don't need to await.
+   */
+  query(): void;
+  /**
+   * Synchronous refresh — fires the fetch now and returns a Promise that
+   * settles when the response (or error) has been processed. Cancels any
+   * pending coalesced query so we don't double-fire. Honours `blockQuery`,
+   * `forceFilters`, `forceSorters`, `queryFn`. Use this from refresh
+   * buttons / programmatic flows that need the result.
+   */
+  queryImmediate(): Promise<void>;
+  /**
+   * Append-style extension. Does NOT mutate `pagination.page` (extension
+   * runs parallel to pagination). Re-entry guarded via `queryingNext`.
+   */
+  queryNext(): void;
+  /**
+   * Page-aligned slice fetch into `windowCache` with merge-on-contiguous.
+   * Returns a Promise that settles when ALL dispatched blocks have settled
+   * (success, error, OR generation-discarded); never rejects. Resolves on
+   * the next microtask when zero blocks need dispatching.
+   */
+  loadRange(skip: number, limit: number): Promise<void>;
+  /**
+   * Explicit immediate wipe — clears results / cache / loading, resets
+   * `resultsStart` from `pagination.page`, sets `totalCount = 0`. Does NOT
+   * auto-refetch.
+   */
+  invalidate(): void;
+  /** O(1) read of `windowCache.get(absIdx)`. */
+  dataAt(absIdx: number): Record<string, unknown> | undefined;
+  /** True if the block covering `absIdx` is currently being fetched. */
+  loadingAt(absIdx: number): boolean;
+  /** Returns the last error attached to the block covering `absIdx`, or null. */
+  errorAt(absIdx: number): Error | null;
+  /** Clear all applied filters. Does not touch `filterFields`. */
+  resetFilters(): void;
+  /** Open the config dialog (optionally to a specific tab). */
+  showConfigDialog(tab?: ConfigTab): void;
+  /** Append a field to the displayed filter fields (deduped). */
+  addFilterField(path: string): void;
+  /**
+   * Remove a field from the displayed filter fields. Does NOT clear the
+   * applied filter value — display state and applied state are independent.
+   * Use `removeFieldFilter` to clear the value.
+   */
+  removeFilterField(path: string): void;
+  /** Set applied filter conditions for a field. Does not touch `filterFields`. */
+  setFieldFilter(path: string, conditions: FilterCondition[]): void;
+  /**
+   * Set the rendered width for a column. No-op if the column is unknown or
+   * the value is unchanged. Does not modify the column's default (`d`).
+   */
+  setColumnWidth(path: string, width: string): void;
+  /**
+   * Reset the rendered width back to the column's default (`d`). No-op if
+   * the column is unknown or already at default.
+   */
+  resetColumnWidth(path: string): void;
+  /**
+   * Clear the applied filter for a field. Does NOT remove the field from
+   * `filterFields` — the input row stays visible.
+   */
+  removeFieldFilter(path: string): void;
+  /** Open filter dialog for a column. */
+  openFilterDialog(column: ColumnDef): void;
+  /** Close filter dialog. */
+  closeFilterDialog(): void;
+}
+//#endregion
+//#region src/state/tokens.d.ts
+declare const DEFAULT_ROW_HEIGHT_PX = 32;
+//#endregion
+//#region src/state/window/page-aligned-blocks.d.ts
+/**
+ * Clamp a window's `topIndex` to the valid `[0, totalCount - viewport]` range.
+ * `viewport` past `totalCount` (or zero/negative totals) collapses to `0`.
+ */
+declare function clampTopIndex(topIndex: number, totalCount: number, viewport: number): number;
+/** Index of the first row in the block that contains `absIdx`. */
+declare function blockStartFor(absIdx: number, blockSize: number): number;
+interface PageAlignedBlock {
+  page: number;
+  firstIndex: number;
+}
+declare function pageAlignedBlocksFor(skip: number, limit: number, blockSize: number): PageAlignedBlock[];
+//#endregion
+//#region src/state/window/results-merge.d.ts
+type Row = Record<string, unknown>;
+interface MergeResult {
+  newResults: Row[];
+  newResultsStart: number;
+}
+declare function walkForwardAbsorb(results: Row[], resultsStart: number, cache: Map<number, Row>): MergeResult;
+declare function walkBackwardAbsorb(results: Row[], resultsStart: number, cache: Map<number, Row>): MergeResult;
+//#endregion
+//#region src/state/window/plan-fetch.d.ts
+type FetchPlanMode = "jump" | "steady";
+interface FetchPlan {
+  skip: number;
+  limit: number;
+  mode: FetchPlanMode;
+}
+interface PlanFetchArgs {
+  top: number;
+  viewport: number;
+  totalCount: number;
+  cache: Map<number, unknown>;
+  blockSize: number;
+  /** Threshold below which a steady prefetch fires. Typically `blockSize / 4`. */
+  buffer: number;
+}
+declare function planFetch(args: PlanFetchArgs): FetchPlan | null;
+//#endregion
+//#region src/utils/debounce.d.ts
+/**
+ * Creates a debounced version of a function that delays invocation
+ * until `ms` milliseconds have elapsed since the last call.
+ */
+declare function debounce<T extends (...args: unknown[]) => void>(fn: T, ms: number): T & {
+  cancel(): void;
+};
+//#endregion
+//#region src/utils/equality.d.ts
+declare function arraysEqual<T>(a: readonly T[], b: readonly T[]): boolean;
+declare function sameColumnSet<T>(a: readonly T[], b: readonly T[]): boolean;
+declare function setsEqual<T>(a: ReadonlySet<T>, b: ReadonlySet<T>): boolean;
+declare function sortersEqual(a: SortControl[], b: SortControl[]): boolean;
+//#endregion
+//#region src/utils/reorder-column-names.d.ts
+type ColumnReorderPosition = "before" | "after";
+/**
+ * Permute a column-names array: move `fromPath` next to `toPath` at the
+ * resolved insertion side. Pure: returns a new array, never mutates input.
+ *
+ * Returns the input array unchanged when:
+ *   - `fromPath === toPath`
+ *   - either path is missing from `names`
+ *   - the resolved insertion index leaves the array identical
+ *     (e.g. `[a,b,c]` from=`b` to=`a` "after" — `b` is already after `a`).
+ *
+ * The insertion index is resolved against post-removal positions to keep
+ * the math symmetric across left-to-right and right-to-left moves.
+ */
+declare function reorderColumnNames(names: string[], fromPath: string, toPath: string, position: ColumnReorderPosition): string[];
+//#endregion
+export { APP_CONF_PREFIX, type AppConfData, AppPrefsClient, type AppPrefsClientConfig, type AppPrefsLoadResult, type AsPresetEntryData, type AsPresetEntryRow, type AsPresetsErrorCode, type AspectGate, type AspectMask, type BuildTableQueryOptions, type ColumnFilterType, type ColumnReorderPosition, type ColumnWidthEntry, type ColumnWidthsMap, type ConfigTab, DEFAULT_ROW_HEIGHT_PX, DRAFT_PERSISTED_ASPECTS, type DateShortcut, type DraftPersistedAspect, type FetchPlan, type FetchPlanMode, type FieldFilters, type FilterCondition, type FilterConditionType, MAX_DEFAULT_COLUMN_WIDTH_PX, type MergeResult, NULL_OPS, PRESET_ASPECTS, type PageAlignedBlock, type PlanFetchArgs, type PresetAspect, type PresetCapabilities, type PresetColumnWidthEntry, type PresetData, type PresetDraft, type PresetFilterOpEntry, type PresetLimitReachedBody, type PresetSnapshot, type PresetSnapshotWire, type PresetSorterEntry, PresetsClient, type PresetsClientConfig, PresetsHttpError, type PresetsListResult, type PresetsSaveAsOptions, type PresetsSaveResult, RESERVED_ID_PREFIXES, STANDARD_PRESET_ID, SYSTEM_PRESET_PREFIX, type SelectionMode, type SystemPreset, type SystemPresetInput, type TableStateData, type TableStateMethods, USER_CONF_PREFIX, type UrlQueryDefaults, type UrlQueryParseOptions, type UrlQueryStateLike, type UrlQueryStateSnapshot, type UrlQuerySync, type UserConfData, appConfId, arraysEqual, blockStartFor, buildTableQuery, clampTopIndex, columnFilterType, computeDefaultColumnWidth, conditionLabel, conditionsForType, dateShortcuts, debounce, defaultCondition, derivePresetAspects, deserializeDraft, draftMatchesPreset, escapeRegex, filledFilterCount, filterTokenLabel, filtersToUniqueryFilter, formatFilterCondition, fromWireSnapshot, hasSecondValue, isAuthError, isDirtyAgainst, isEmptyDraft, isFilled, isSimpleEq, isSystemPresetId, mergeFilters, mergeSorters, normaliseSystemPresetId, pageAlignedBlocksFor, parseFilterInput, planFetch, reconcileColumnWidthDefaults, reorderColumnNames, resolveAspectGate, resolveSystemPresets, rowsToPks, sameColumnSet, serializeDraft, setsEqual, sortersEqual, stableStringify, stateToUrlQueryString, toWireSnapshot, togglePk, trimSelection, unescapeRegex, uniqueryFilterToFieldFilters, urlQueryStringToState, userConfId, walkBackwardAbsorb, walkForwardAbsorb };