Skip to content

Presets ​

Presets save a table view by name. The view is durable: a user can build the perfect column / filter / sort combination, save it as "My open orders", and recall it across reloads, devices, and sessions. Public presets share the view across all users on the same table.

The client side lives in @atscript/vue-table. The persistence layer is @atscript/moost-ui-presets — see Server-Side Presets for the controller setup.

The snapshot model ​

A preset is a partial PresetSnapshot:

ts
interface PresetSnapshot {
  columns?: {
    columnNames: string[];
    columnWidths?: Record<string, string>;
  };
  filters?: string[]; // displayed filter field paths
  filterOps?: FieldFilters; // applied filter conditions
  sorters?: SortControl[];
  itemsPerPage?: number;
}

Every key is optional. A preset that names only sorters claims only the sort aspect — on apply, the table writes new sorters and leaves columns / filters / itemsPerPage untouched. This per-aspect opt-in is the entire reason presets are useful: a "sort by priority" preset doesn't fight a "show financial columns" preset.

Each aspect's presence on the snapshot is the claim that the preset owns it. The wire form (PresetSnapshotWire with entries-arrays for atscript validation) is converted via toWireSnapshot() / fromWireSnapshot() from @atscript/ui-table.

Present-but-empty is not the same as absent. filterOps: {} says "this preset owns the filters and there are none" — applying it clears whatever was filtered. Omitting the key entirely leaves the current filters alone. Both directions of the wire conversion preserve that distinction since 0.1.133, so a saved unfiltered view really does clear the filters it was saved without.

Custom filter conditions (state.residualFilters, since 0.1.140) are not an aspect — a preset cannot store them, and Save / Save as… leave them out (the Save-as popover says so while one is active). A preset that owns filterOps defines the whole filter population, so applying it — or Reset — clears them, and while one is active the view counts as changed against that preset.

A preset reaches every role that can see it, as written. Entries on fields the current role cannot read are dropped on apply, the preset does not count as changed for lacking them, and Save keeps them in the stored row. See Fields Hidden by Role.

What counts as a change ​

The picker's unsaved marker (state.preset.isDirty) compares the table against the active preset's claimed aspects. Since 0.1.142 state.preset.activeSnapshot is canonical — spelled the way the table holds state — so spelling out a default is not a change:

  • A width in columns.columnWidths equal to that column's default width — or on a path that is not a column — is the same as no width. A system preset can pin { name: '10em' } on a column whose default is 10em and stays clean after apply. Resizing the column away from it, or a preset width that differs from the default, still counts.
  • A filterOps entry with no filled condition ({ status: [] }, an empty value) is the same as no entry; applying the preset does not write it. Typing into that field and clearing it again leaves the preset clean; clearing a field the preset filled does not.

The stored preset is never rewritten, and capture still writes widths as overrides only, so a preset keeps following a column's default when the metadata changes. Hosts that diff a stored snapshot themselves use canonicalPresetSnapshot from @atscript/ui-table (signature).

What a system preset owns ​

By default a system preset owns every available aspect: applying one resets columns, displayed filters, filter conditions, sorters and page size to the preset's values or the factory defaults. When your system presets are filter-only views ("Open", "Closed", "Mine"), that is too much — switching between them throws away the user's column layout. Narrow it with systemAspects (since 0.1.133):

vue
<AsTableRoot
  :preset="{
    url: '/api/db/_presets',
    tableKey: 'tickets',
    systemPresets,
    systemAspects: ['filterOps'],
  }"
/>

systemAspects is intersected with aspects and applies to system presets only — user and public presets keep owning whatever their snapshot claims. It also scopes the dirty indicator: with systemAspects: ['filterOps'], reordering columns while a system preset is active does not mark it unsaved.

Three preset kinds ​

KindID prefixPersistedScope
Systemsys:NoBuilt into the app
User(uuid)YesOne user, one table
Public(uuid)YesAll users, one table

System presets are declared by the app, never round-trip to the server, and always render in the picker at index 0 onwards. The standard "All rows" entry is STANDARD_PRESET_ID = 'sys:standard'.

User presets are private to the creator. Public presets show in every user's picker on the same (app, tableKey). Public preset labels are unique within (app, tableKey) — race-safe at the DB layer via a unique index.

User config (userConf) ​

Per-user, per-table preferences keyed deterministically as uc:${user}:${app}:${tableKey}:

ts
interface UserConfData {
  defaultPresetId?: string; // applied at first load
  favPresetIds?: string[]; // pinned in the picker
}

The userConf row is auto-stamped by the server when a write arrives, and the client surfaces it as state.preset.userConf. Its shape is exactly two fields, but they're load-bearing — setDefault and toggleFav are atomic operations on this row.

App config (appConf) ​

App-wide, one row per (user, app) — not per table. Carries appearance, language, timezone, density, date format, custom JSON. useAppPrefs() is the composable that owns it:

ts
import { useAppPrefs, provideCellLocale } from "@atscript/vue-table";

const { prefs, save } = useAppPrefs({ url: "/api/db/_presets" });

provideCellLocale(() => ({
  language: prefs.value.language,
  timezone: prefs.value.timezone,
}));

await save({ appearance: "dark" }); // optimistic shallow merge

save() is optimistic: the local prefs updates immediately, the server roundtrip happens in the background, and a failure rolls back to the previous value.

The Vue composables ​

usePresets(opts) ​

Wraps PresetsClient (in ui-table) and exposes a reactive surface — the same one mounted under state.preset when the table root is configured with :preset. Direct use is for custom pickers; most apps just pass the preset prop and let <AsPresetPicker> consume state.preset.

ts
const presets = usePresets({
  url: "/api/db/_presets",
  tableKey: "orders",
  systemPresets: [
    {
      id: "open",
      label: "Open",
      content: { filterOps: { status: [{ type: "eq", value: ["pending"] }] } },
    },
  ],
});

useLocalDraft(opts) ​

Overlays in-progress edits on localStorage. The user fiddles with filters, refreshes the tab, and the table opens in the same state. The draft is per (app, tableKey), debounced 300ms, and cleared automatically when the live snapshot matches the active preset's claimed aspects (so the URL bar stays clean once you're "done" editing).

Pass draftScope (since 0.1.133) with the signed-in user's id whenever drafts are on — the draft key includes it, so a shared browser never restores the previous user's draft. Changing it at runtime moves reads and writes to the new key without touching the old one.

Wired automatically when <AsTableRoot :preset="{ ..., persistDrafts: true }"> is set; direct use is for programmatic setups.

useAppPrefs(opts) ​

App-wide user prefs, as above. One round-trip on mount, optimistic writes via save(), optional localStorage cache for cold paint without a flash of defaults.

The picker ​

<AsPresetPicker> is a Tier-1 component — a dropdown that lists system + user + public presets, with Save, Save as…, Reset, and Manage… actions. It reads state.preset so the root has to be configured with :preset:

vue
<AsTableRoot
  url="/api/db/tables/orders"
  :preset="{ url: '/api/db/_presets', tableKey: 'orders', systemPresets }"
>
  <AsTableActions>
    <AsPresetPicker />
  </AsTableActions>
  <AsTable />
</AsTableRoot>

When the picker is not configured (omit :preset), the preset surface stays inert: state.preset.available === false, every mutator throws, and the picker hides itself. This makes presets a zero-cost opt-in.

Date shortcuts ​

The filter dialog's date inputs render quick-pick buttons from temporalShortcuts() (since 0.1.148): Today, Yesterday, Last 7 days, Last 30 days, This week, Last week, This month, Last month, This year. Their conditions carry relative tokens (today-6 … today), so a preset or a shared link that stores one keeps meaning "the last 7 days" when it is applied — a user who wants fixed dates picks an absolute range instead. See Date and time filters.

ts
import { temporalShortcuts } from "@atscript/ui-table";

for (const sc of temporalShortcuts()) {
  // { id: 'last-7-days', label: 'Last 7 days',
  //   conditions: [{ type: 'bw', value: ['today-6', 'today'] }] }
}

dateShortcuts() — a fixed list of absolute [start, end] ISO date pairs (Last 7 Days, Month to Date, …) — is deprecated: absolute dates go stale inside a saved preset and ignore the table's time zone. It stays exported and unchanged, and will be removed in a future breaking release.

End-to-end wiring ​

A typical table page shows the whole flow:

vue
<AsTableRoot
  :key="path"
  v-model:url-query="urlQuery"
  :url="`/api/db/tables/${apiPath}`"
  :controls="controls"
  :preset="{
    url: '/api/db/_presets',
    tableKey: path,
    systemPresets,
    systemAspects: ['filterOps'],
    persistDrafts: true,
    draftScope: userId,
  }"
>
  <AsTableActions>
    <AsPresetPicker />
  </AsTableActions>
  <AsTable />
</AsTableRoot>

Note :preset.systemPresets is per-table — each table can declare its own built-in views. systemAspects keeps those built-in views from resetting the user's layout, and draftScope keeps local drafts private to the signed-in user.

Session cache ​

Since 0.1.153. Once the app binds the signed-in viewer with setMetaCacheIdentity(), preset loads go through a browser session cache keyed by (presets url, app, tableKey):

  • Re-mounts are free. A table that mounts again (SPA navigation) applies the cached preset rows synchronously — the default preset resolves and the first data query fires with no presets request. Rows older than the max age (30 s by default) are still applied from the cache, then refreshed in the background. A refresh updates the picker's list and favourites but never re-applies the default preset mid-session.
  • Capabilities load once per session, and never hold the first data query (also without the cache): only the preset rows and the table definition do. Until they arrive, save / publish controls may briefly read as not permitted.
  • Writes stay in sync. A save, rename, delete, public toggle, default or favourite change refreshes the shared entry, so every other mounted table on the same scope updates its list, and other tabs of the same viewer are told through a BroadcastChannel.
  • One db Client per presets URL serves every table, so the first write validates against one _presets/meta, not one per mount.
  • Failures are never cached — a failed or denied load is retried on the next mount.
  • Bounded (since 0.1.154). The cache keeps the 100 most recently used scopes; a scope a mounted table uses is never dropped. A table whose scope was dropped loads its presets again on its next mount.

Identity scoping:

SituationBehaviour
App never calls setMetaCacheIdentity()No cache — every mount loads, as before 0.1.153
Server rendering (no window)No cache
setMetaCacheIdentity() with a new keyCache dropped (with the meta cache, resetMetaCache())
Rows owned by a user other than the one the capabilities nameCache dropped, mounted tables reload

Tune or turn it off with setPresetsCacheMaxAge(ms) from @atscript/ui-table (0 = refresh in the background on every mount, negative = off). Call invalidatePresetsCache() after changing presets outside the presets API (e.g. a server-side import). Do bind the identity on login, logout and every reload of the current user — the cache relies on it to never show one user's private presets to the next.

When a preset write fails ​

Every mutator on state.preset (saveActive, saveAs, rename, remove, togglePublic, setDefault, toggleFav, setFavorites) rejects on failure and records the reason on state.preset.lastError — the single channel for write failures. It is cleared when an outermost mutator starts, so a state.preset.batch(...) counts as one user action: a failure early in a batch is not wiped by a later write inside it, and the batch's last failure is what remains.

The built-in picker keeps its Save-as popover open and shows the message, and the manage dialog keeps the failed edits staged, stays open and closes only once every write has succeeded. Custom UI must handle the rejection — nothing is swallowed since 0.1.133.

Next steps ​

Released under the MIT License.