ChronicStone/nuxt-ui-tools / .agents/skills/nuxt-ui-tools-table-runtime
nuxt-ui-tools-table-runtime
VerifiedUse 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.5 KB |
| references/architecture.md | markdown | 6.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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |