nuxt-ui-tools-table-runtime

Use this skill when implementing, refactoring, or extending the internal table runtime inside this repository. Covers the current architecture layers, state model, composable flow, where different res

SKILL.md

GitHub

nuxt-ui-tools Table Runtime

Use this skill for internal repository work on:

  • table runtime architecture
  • table state management
  • composables
  • runtime components
  • schema/builder internals
  • adding new table capabilities
  • refactoring table internals

Read First

  • AGENTS.md
  • .agents/skills/nuxt-ui-tools-maintainer/SKILL.md
  • .agents/skills/nuxt-ui-tools-table-runtime/references/architecture.md

Current Mental Model

The current table runtime is a schema-driven system with these major layers:

  1. public schema and public entrypoints
  2. schema/building and normalization helpers
  3. reactive orchestration in composables
  4. pure or mostly pure utilities
  5. rendering components
  6. playground integration surface

The important split is:

  • public shape and schema definition
  • runtime orchestration
  • pure transformations
  • rendering

Do not collapse those layers together.

Current File Routing

Start from these depending on the task:

  • public package surface: src/runtime/table/index.ts
  • schema definition entry: src/runtime/table/schema/index.ts
  • internal orchestration root: src/runtime/table/composables/use-table-internals.ts
  • public table API shape: src/runtime/table/composables/use-table.ts src/runtime/table/composables/use-table-api.ts
  • query-state bridge: src/runtime/table/composables/use-query-state.ts
  • data orchestration: src/runtime/table/composables/use-table-data.ts
  • columns pipeline: src/runtime/table/composables/use-table-columns.tsx src/runtime/table/utils/columns/*
  • filter pipeline: src/runtime/table/composables/use-table-filters.ts src/runtime/table/composables/use-table-filter-presentation.ts src/runtime/table/composables/use-table-filter-options.ts src/runtime/table/utils/filters/*
  • rendering shell: src/runtime/table/components/DataList.vue src/runtime/table/components/data-list/*
  • data-list UI and viewport contexts: src/runtime/table/composables/use-data-list-ui.ts src/runtime/table/composables/use-data-list-viewport.ts

Important Current Reality

The current implementation works, but it is not the final shape.

There are known improvement targets:

  • reduce reactive waste
  • reduce layers of derived state
  • simplify query-state integration
  • move toward cleaner structure
  • preserve or improve inference while simplifying internals

Do not treat the current layering as sacred. If an abstraction is wasteful or too indirect, refactor it.

Feature-Addition Rules

When adding a table feature:

  1. identify the public contract first
  2. decide whether it belongs in schema, API, runtime orchestration, pure utils, or rendering
  3. keep normalized or config-driven handling when multiple variants exist
  4. isolate variant-specific behavior behind a shared contract
  5. update tests, playground, and consumer skills when the surface changes

Preferred shape:

  • schema-facing definition in types/schema/building layer
  • normalization or resolution in utils
  • orchestration in composables
  • view-only consumption in components

Avoid:

  • burying domain logic directly in components
  • feature behavior implemented only in playground
  • one giant helper handling every variant inline

Specific Internal Guidance

State

  • prefer one strong state abstraction over many computed bridges
  • avoid derivation of derivation of derivation
  • avoid temporary reactive wrappers when direct state modeling is possible
  • if local draft state exists only to mirror another reactive source, reconsider the abstraction

Columns

  • columns are a pipeline, not a flat render blob
  • runtime columns, ordering, visibility, pinning, menu items, and render adapters should stay separated

Filters

  • filters should be definition-driven
  • filter definitions currently organize around behavior, display, source, editor, and preview
  • each filter kind should have standardized behavior and isolated implementation where logic is non-trivial
  • preview generation is a good model: normalized contract plus per-kind implementation files
  • filter presentation is a separate orchestration concern from filter semantics
  • client facet counts belong to the data/query engine, not the filter render layer

Components

  • DataListRoot.vue owns provider and lifecycle behavior while rendering no mandatory wrapper
  • DataList.vue is the stable assembled recipe and must be built from the same public parts consumers compose directly
  • granular parts own rendering only and must consume prepared state from table internals
  • popup parts expose a standard custom trigger slot; full and incremental data states stay separate
  • DataListTable.vue picks the renderer for the table layout: SummaryRenderer while internals.rowSummary.active (use-table-row-summary.ts, schema table.summary, below md by default), otherwise TableRenderer. Both mirror the same states (first load, replacing, error, empty) and share TableEmptyState, TableSelectionControl, and the row-actions control, so a state fixed in one is fixed in both. DataListContent keys DataListTable by that presentation so the swap is an ordinary out-in change of its layout Transition (the rows leave, then the table enters), where unkeyed the new view cuts the old one's leave short. Keep data-list-table.vue free of template comments: in development a root comment makes the root a fragment that the transition cannot leave, and the next view never appears (test/browser/table/mobile-summary-rows.test.ts fails on it in Chromium)
  • below md, DataListRoot layers constants/mobile.ts (a registry of 44px touch-target classes per part slot) under the app's classes through utils/mobile-defaults.ts. Add a new touch control by adding its slot to that registry and a case to test/dom/components/mobile-touch-targets.test.ts; do not hard-code min-h-11 in a component
  • accessible names go through use-table-row-labels.ts (schema rowLabel, position fallback) and the table.selection/table.rowActions locale keys; never write a bare "Select row" string in a control
  • every granular part exposes a typed flat ui slot map; page defaults belong to DataListRoot.ui, while underlying Nuxt UI primitives retain application theme inheritance
  • renderer internals should consume prepared state rather than reinvent logic

Pagination

  • pagination is a none, offset, or cursor strategy selected by schema
  • only offset page and size state is URL-backed; cursor accumulation stays in TanStack infinite-query state
  • filter, search, and sorting owners call the pagination reset command instead of writing page fields
  • cursor pages flatten and de-duplicate by rowKey; loaded and total counts remain distinct
  • the public API is conditional so offset-only and cursor-only commands do not leak across schema modes

When To Reorganize

Reorganize without hesitation when:

  • a file is carrying multiple unrelated concerns
  • a feature introduces another variant into a growing domain
  • the state model is becoming layered and wasteful
  • a top-level folder should really become a subdomain under utils/

Builder-specific note:

  • existing top-level src/runtime/table/builders is transitional
  • prefer the long-term direction of utils/builders/ when touching or growing builder code