Atscript UI Tables

atscript-ui-tables

Install

npx skills add moostjs/atscript-ui      # installs all atscript-ui skills (this one + general + forms + wf + styles)
npx skills add moostjs/atscript         # sibling — .as language
npx skills add moostjs/atscript-db      # sibling — moost-db backs most tables

pnpm add @atscript/core @atscript/typescript @atscript/ui @atscript/ui-table @atscript/vue-table vue
pnpm add @atscript/vue-form                          # required peer (cell dispatch, action forms)
pnpm add @atscript/ui-fns                            # opt-in: dynamic @ui.table.fn.*
pnpm add @atscript/db-client                         # moost-db browser client
pnpm add @atscript/moost-ui-presets                  # server-side preset persistence (optional)

Quick start

// src/product.as
@db.table 'products'
@db.depth.limit 0
export interface Product {
    @meta.id @db.default.increment
    id: number

    @meta.label 'SKU'
    @ui.table.width '8em'
    sku: string

    @meta.label 'Name'
    @db.index.fulltext 'name_fts'
    name: string

    @meta.label 'Price'
    @db.column.precision 2
    @db.amount.currency 'USD'
    price: number

    @meta.label 'In stock'
    inStock: boolean
}

<script setup lang="ts">
import { createDefaultCellTypes } from "@atscript/vue-table";

const types = createDefaultCellTypes();
</script>

<template>
  <AsTableRoot url="/api/db/tables/products" :types="types" :limit="20">
    <AsTableActions />
    <AsFilters />
    <AsTable :column-menu="{ sort: true, filters: true, hide: true, resetWidth: true }" />
  </AsTableRoot>
</template>

Replace url= with :query-fn="..." for a custom backend. See query.md.

Invariants

Key imports

// Tier 1 — primary (auto-imported by AsResolver)
import {
  AsTableRoot,
  AsTable,
  AsWindowTable,
  AsTableActions,
  AsFilters,
  AsPresetPicker,
} from "@atscript/vue-table";

// Tier 2 — defaults (swap targets)
import {
  // cells
  AsCellArray,
  AsCellDate,
  AsCellJson,
  AsCellNumber,
  AsCellUnion,
  AsTableCellValue,
  // dialogs
  AsConfigDialog,
  AsFilterDialog,
  AsPresetDialog,
  AsConfirmDialog,
  // filter ui + headers + rows
  AsFilterField,
  AsFilterInput,
  AsTableHeaderCell,
  AsRowActions,
  AsColumnMenu,
} from "@atscript/vue-table";

// AsActionFormDialog is on a dedicated subpath — it pulls in @atscript/vue-form,
// so the table root lazy-mounts it. Import this only to override / eager-load.
import AsActionFormDialog from "@atscript/vue-table/as-action-form-dialog";

// Composables
import {
  useTable,
  useTableContext,
  useTableContextOptional,
  createTableState,
  createStaticTableState,
  useTableSelection,
  useTableNavBridge,
  useTableFilter,
  useTableSearch,
  useTableActions,
  useTableUrlQuery,
  useAppPrefs,
  usePresets,
  useLocalDraft,
  useCellLocale,
  provideCellLocale,
  useTableComponent,
} from "@atscript/vue-table";

// Factories
import { createDefaultControls, createDefaultCellTypes } from "@atscript/vue-table";

// Types (re-exported)
import type {
  TAsTableControls,
  TAsCellTypeComponents,
  ReactiveTableState,
  ColumnMenuConfig,
  ConfigTab,
  TableActionsState,
  ActionResult,
} from "@atscript/vue-table";

// Framework-agnostic table model (filter / preset / query primitives)
import {
  FilterCondition,
  FieldFilters,
  filtersToUniqueryFilter,
  PresetSnapshot,
  toWireSnapshot,
  fromWireSnapshot,
  buildTableQuery,
  mergeFilters,
  mergeSorters,
  stateToUrlQueryString,
  urlQueryStringToState,
} from "@atscript/ui-table";

// Server-side preset controller (Moost)
import { AsPresetsController, AsPresetEntry } from "@atscript/moost-ui-presets";

References — load only what's needed

Customization

Full swap-surface reference (slots, maps, dispatched control keys): customization.md.

Tables expose three swap surfaces, layered on the tier model:

• Tier 1 — <AsTableRoot>, <AsTable>, <AsWindowTable>, <AsFilters>, <AsTableActions>, <AsPresetPicker> are the integration surface. Build with useTable / createTableState directly if you need a custom shell.
• Tier 2 — default cells (AsCellArray, AsCellDate, AsCellJson, AsCellNumber, AsCellUnion, AsTableCellValue) and default dialogs (AsConfigDialog, AsFilterDialog, AsPresetDialog, AsConfirmDialog, AsRowActions, AsColumnMenu, AsTableHeaderCell). These are what you swap.
• Tier 3 — internal composition (header cells, virtualizer pieces, fields selector, sorter config). Not tagged directly; styles ride with the defaults that use them.

Swap a built-in cell renderer (:types)

:types maps built-in cell ids (per invariant 4: text, number, boolean, date, datetime, relative, array, object, union, enum, ref) to a component:

<script setup lang="ts">
import { createDefaultCellTypes } from "@atscript/vue-table";
import MyDateCell from "./MyDateCell.vue";

const types = { ...createDefaultCellTypes(), date: MyDateCell, datetime: MyDateCell };
</script>

<template>
  <AsTableRoot url="/api/db/tables/products" :types="types" />
</template>

Swap a specific cell (:components + @ui.table.component)

For column-specific cells, opt in on the .as type and supply the named component:

@ui.table.component 'price-tag'
price: number

<script setup lang="ts">
import PriceTag from "./PriceTag.vue";
const components = { "price-tag": PriceTag };
</script>

<template>
  <AsTableRoot url="..." :components="components" />
</template>

Wrap a cell in useCellLocale / provideCellLocale if it needs locale + timezone from useAppPrefs.

Swap a dialog (controls.*)

The toolbar, config, filter, and preset dialogs are swappable through controls. Pass only the entries you replace — spreading createDefaultControls() defeats dialog lazy-loading (see invariant 12):

<script setup lang="ts">
import MyFilterDialog from "./MyFilterDialog.vue";

const controls = { filterDialog: MyFilterDialog };
</script>

<template>
  <AsTableRoot url="..." :controls="controls" />
</template>

Custom dialogs just write the new arrays back to state.filterFields / state.filters / state.sorters / state.columnNames — the root watcher reconciles and re-queries (see invariants 1–3 and query.md). Don't call state.query() or run cleanup loops mirroring display state into applied state; both fight the watcher.

Style consequence

Replacing AsFilterDialog with a custom dialog that doesn't tag the as-filter-* shortcuts drops those classes out of your bundle automatically. Keep the default whenever its chrome fits — you'll spend less time on style maintenance. For granular opt-out, atscript-ui-styles ships per-domain shortcut groups (tableShortcuts, formShortcuts, …) you can compose narrower than the default allShortcuts.

See also

Reference docs: https://ui.atscript.dev/tables/. Source: https://github.com/moostjs/atscript-ui.