Skip to content

ChronicStone/nuxt-ui-tools / .agents/skills/nuxt-ui-tools-table-runtime

nuxt-ui-tools-table-runtime

Verified

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 responsibilities live, how to add features cleanly, and what kinds of refactors are encouraged.

FileKindSize
SKILL.mdskill md7.5 KB
references/architecture.mdmarkdown6.8 KB

references/architecture.md

View on GitHub
# Table Runtime Architecture

This reference explains the current internal table runtime shape in more concrete detail.

## 1. Public Entry Layer

Main entrypoints:

- `src/runtime/table/index.ts`
- `src/runtime/table/schema/index.ts`
- `src/runtime/table/utils/builders/table-source.ts`
- `src/runtime/table/composables/use-table.ts`

What they do:

- expose the package-facing surface
- seal source query-result inference with inline `tableSource(...)`
- let consumers define a schema
- let consumers instantiate a table object

This layer should stay clean and inference-friendly.
If internals are awkward, fix the internals instead of leaking complexity outward.

`tableSource(...)` is an inline inference boundary, not a separately declared source factory. Keep
usage inside `defineTableSchema({ source: tableSource({ ... }) })`; schema context remains available
to static filters, while page context derives after the source row has been inferred.

## 2. Orchestration Root

The internal composition root is:

- `src/runtime/table/composables/use-table-internals.ts`

Today it wires together:

- layout
- query state
- resolved filters
- data loading
- filter presentation
- column state
- selection
- public API
- filter helpers
- controls
- table columns
- pagination helpers

This file is the best high-level map of how the table runtime currently fits together.

## 3. State Model

Current state is distributed across several composables:

- `use-table-layout.ts`
- `use-table-state.ts`
- `use-query-state.ts`
- `use-table-data.ts`
- `use-table-selection.ts`
- `use-table-tree.ts`
- `use-table-controls.ts`
- `use-table-columns.tsx`

Current design strengths:

- responsibilities are already somewhat split
- the system is not trapped in one monolithic composable

Current design weakness:

- there is still too much reactive layering in places
- some abstractions are created, then remapped, then re-derived again
- table/query-state integration should likely be simplified further

Target bias:

- fewer layers
- fewer bridge computeds
- clearer state ownership
- better direct abstractions

## 4. Query-State Bridge

The current table URL state bridge is:

- `src/runtime/table/composables/use-query-state.ts`

It currently composes:

- pagination grouped state
- sorting grouped state plus nullable mapping
- filters grouped state plus dynamic filter query state

This is a live pain-point area.
When extending or refactoring it, prefer:

- direct domain state modeling
- less mirrored state
- fewer conversion layers

## 5. Data Flow

The current data pipeline centers around:

- `use-table-data.ts`

Responsibilities include:

- context queries
- request context creation
- data query execution
- client-side query execution when needed
- client-side facet execution when filters opt into `source.facet`
- page-context queries
- loading/error aggregation

This layer should own data orchestration, not rendering components.

Important current rule:

- client facet counts belong to the data/query engine layer
- `use-table-filter-options.ts` should consume prepared facet results, not compute client counts itself
- option loading and facet computation are separate concerns

## 6. Filter Flow

Important files:

- `use-table-filters.ts`
- `use-table-filter-presentation.ts`
- `utils/filters/*`
- `utils/resolved-filters.ts`
- `utils/query-state.ts`
- `components/filters/*`

Good current pattern:

- filter preview logic is split per kind under `utils/filters/preview/*`
- filter presentation has dedicated orchestration for `tag`, `panel`, and `tag-dynamic`
- panel state is staged at the panel level and applied together
- filter definitions use one unified top-level contract: `behavior`, `display`, `source`, `editor`, `preview`

This is the kind of organization to continue:

- shared normalized contract
- per-kind isolated implementation
- orchestration layer consuming prepared outputs

Important ownership split:

- `use-table-filters.ts` owns filter semantics and query-state operations
- `use-table-filter-presentation.ts` owns filter surface behavior and panel draft state
- `use-table-filter-options.ts` owns option-source consumption and merges in facet results
- `use-option-filter-editor-state.ts` owns option editor state derivation shared by tag and panel surfaces
- `use-filter-tag-session.ts` owns transient tag session activation/open/close behavior for tag and tag-dynamic flows
- rendering components should consume those prepared layers instead of rebuilding filter logic locally

Current renderer cleanup direction:

- searchable popover structure should be shared through `components/filters/shared/FilterSearchablePanel.vue`
- option picker content should be shared through `components/filters/shared/FilterOptionPickerContent.vue`
- tag and panel wrappers should stay thin and mostly own surface-specific commit behavior
- when adding a new filter kind, prefer a shared editor-state composable plus thin surface wrappers over duplicating tag/panel implementations

## 7. Column Flow

Important files:

- `use-table-columns.tsx`
- `utils/columns/*`

This area already behaves like a pipeline:

- create runtime columns
- order them
- filter by visibility
- sync runtime state
- compute menu items
- produce final table columns

When growing it, preserve pipeline structure instead of centralizing everything into one render utility.

## 8. Rendering Layer

Main files:

- `components/DataList.vue`
- `components/table/*`
- `components/summary/*`
- `components/grid/*`
- `components/layout/*`

`DataList.vue` is primarily the shell/composition boundary.
It should consume orchestrated state rather than become the domain brain.

The table layout has two renderers. `components/table/*` draws columns; `components/summary/*` draws one
compact row per record while `rowSummary.active` is true (`use-table-row-summary.ts`: `available` is
what the schema and viewport allow, `active` adds the reader's cookie-backed choice). The view toggle
lives in the offset footer, or in the default toolbar for cursor and unpaginated lists. Summary rows
keep the table's selection, row actions, query state, and pagination; they drop columns, column
sorting, and the totals row, so the sort menu stands in for column headers while they are active.

## 9. Playground Role

Current package usage examples live mainly in:

- `playground/app/pages/table/client.vue`
- `playground/app/pages/table/remote.vue`
- `playground/app/pages/table/summary-rows.vue` and `first-use.vue` for summary rows and the first-use empty state

Use them to validate package-facing behavior, but do not move reusable logic there.

## 10. Safe Extension Workflow

When adding a feature:

1. identify the schema/public contract
2. decide whether a normalized utility contract is needed
3. keep orchestration in composables
4. keep heavy domain transforms in utils
5. keep renderers thin
6. update tests, playground, and consumer skills if the package surface changed
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall