From 3600f3fcd9ab9a0e01984d65c09a0ed95244ac5d Mon Sep 17 00:00:00 2001 From: kurihada Date: Fri, 20 Mar 2026 14:39:03 +0800 Subject: [PATCH] chore: refresh registry metadata and docs --- README.md | 8 +++++++ docs/registry.md | 4 ++++ docs/rfcs/data-table.md | 52 ++++++++++++++++++++++++----------------- registry/index.json | 15 +++++++++--- roadmap.md | 49 +++++++++++++++++++++++++++++++++++--- 5 files changed, 101 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 479da94..ebb01ab 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,13 @@ default styling with its own tokens, motion recipes, and component contract. - `registry`: generated registry metadata plus the source-copy install contract - `tests/e2e`: Playwright smoke coverage for high-value Storybook flows +## Current status + +- The foundation, token layer, authoring contract, Storybook docs, and unit coverage are in place. +- The public UI surface now includes the core form and overlay set plus advanced patterns such as `DataTable`, `Command`, `Combobox`, `Sheet`, and `EmptyState`. +- The internal source-copy registry flow is live and validated with `pnpm registry:check` and `pnpm test:registry:consumer`. +- The main remaining release work is publish policy and tagging automation, not initial component bootstrapping. + ## System principles - Source owned: components live in this repo and are modified directly. @@ -128,6 +135,7 @@ Consumers pin this repo to a reviewed commit or tag, then run the local installe copy selected items into their own codebase. - Registry metadata lives in `registry/index.json` and is generated by `pnpm registry:build`. +- The generated index tracks transitive local helpers in addition to component entrypoints, so helper-import changes need a registry rebuild before merge. - The installer copies components into `src/cadence-ui`, adds missing package dependencies, and writes `src/cadence-ui/.install-manifest.json` so upgrades can reuse the same item set. - `pnpm test:registry:consumer` creates a temporary consumer app, runs the installer, and diff --git a/docs/registry.md b/docs/registry.md index 00c93dc..85a76c7 100644 --- a/docs/registry.md +++ b/docs/registry.md @@ -37,6 +37,10 @@ pnpm registry:check The pull request workflow now runs `pnpm registry:check`, and the release version PR workflow refreshes the registry automatically via `pnpm release:version`. +The generated index includes transitive local helpers, not just component entrypoints. If a +component starts importing a shared file such as `packages/ui/src/lib/icons.tsx`, rebuild the +index before merge so source-copy consumers receive the full dependency graph. + To validate the end-to-end consumer flow locally: ```bash diff --git a/docs/rfcs/data-table.md b/docs/rfcs/data-table.md index 5f3d7de..146d669 100644 --- a/docs/rfcs/data-table.md +++ b/docs/rfcs/data-table.md @@ -2,11 +2,16 @@ ## Status -Proposed +Implemented + +The first `DataTable` slice now ships in `packages/ui` with stories, tests, and registry +distribution support. This RFC remains as the design record for the shipped scope and the +guardrails for future follow-up work. ## Summary -`DataTable` is the next high-value advanced pattern for `@ai-ui/ui`, but it should not ship as a giant "kitchen sink" component. +`DataTable` is now a shipped advanced pattern for `@ai-ui/ui`, and it should continue to avoid +turning into a giant "kitchen sink" component. The recommended path is: @@ -34,11 +39,13 @@ Relevant current building blocks already exist in `packages/ui`: - overflow and contextual actions: `DropdownMenu`, `Popover`, `Tooltip`, `Sheet`, `Dialog`, `Toast` - empty and first-run states: `EmptyState` -That means the main missing piece for list-heavy product surfaces is not another primitive. It is a stable data presentation pattern. +At RFC authoring time, the main missing piece for list-heavy product surfaces was not another primitive. +It was a stable data presentation pattern. ## Problem statement -Today the design system can express forms, overlays, command/search, and empty states, but it cannot yet express a reusable operational list surface such as: +Before this work, the design system could express forms, overlays, command/search, and empty +states, but it could not yet express a reusable operational list surface such as: - release queues - approval backlogs @@ -94,14 +101,16 @@ This RFC is anchored in the current repo, not an idealized future state. ### Dependency constraints -Current `packages/ui/package.json` has no table model dependency, no date library, and no grid engine. +When this RFC was written, `packages/ui/package.json` had no table model dependency, no date +library, and no grid engine. -That means the first `DataTable` implementation must either: +That meant the first `DataTable` implementation had to either: - hand-roll row modeling, sorting, selection, and visibility management, or - adopt a focused headless dependency -Hand-rolling is not recommended for this repo stage. +Hand-rolling was not recommended for this repo stage, and the shipped implementation now uses +`@tanstack/react-table` internally. ## Recommendation @@ -353,7 +362,7 @@ At least one smoke scenario should cover: - selecting rows reveals a bulk-action affordance - opening row detail in `Sheet` still works -## Release plan +## Original release plan ### Stage 0: RFC and composition rehearsal @@ -392,9 +401,9 @@ Only if justified by real product usage: - virtualization - advanced filters -## Likely file layout +## Implemented file layout -When implementation begins, the initial table slice should probably live in: +The initial table slice now lives in: ```txt packages/ui/src/components/data-table.tsx @@ -403,13 +412,14 @@ packages/ui/src/components/data-table.test.tsx apps/docs/src/components/data-table.stories.tsx ``` -If the implementation grows into a larger family, the repo may eventually want a dedicated component folder, but the first slice should stay consistent with the current flat component layout. +If the implementation grows into a larger family, the repo may eventually want a dedicated +component folder, but the current slice still follows the flat component layout. ## Dependency recommendation -### Recommended +### Current choice -- add `@tanstack/react-table` to `packages/ui` +- use `@tanstack/react-table` inside `packages/ui` ### Not recommended for the first slice @@ -420,7 +430,7 @@ If the implementation grows into a larger family, the repo may eventually want a The first implementation should minimize dependency expansion and keep the complexity budget focused on a single new capability. -## Open questions +## Follow-up questions 1. Should the public column type stay fully source-owned, or should the first release expose a thin alias around TanStack column defs? 2. Should the first release include client-side search/filter state inside `DataTable`, or should filtering remain externally controlled? @@ -428,12 +438,12 @@ The first implementation should minimize dependency expansion and keep the compl 4. Should pagination UI be part of the root component family, or remain a separate companion component? 5. Should row selection be opt-in only, or should the root always reserve structure for it? -## Decision +## Result -The next `DataTable` implementation should: +The shipped `DataTable` implementation: -- be built as an advanced pattern, not a primitive -- be source-owned at the public API layer -- use TanStack Table internally from the first implementation -- ship as a narrow, headless/core-first operational table -- defer scale features until real usage proves they are necessary +- is built as an advanced pattern, not a primitive +- is source-owned at the public API layer +- uses TanStack Table internally from the first implementation +- ships as a narrow, headless/core-first operational table +- defers scale features until real usage proves they are necessary diff --git a/registry/index.json b/registry/index.json index 9de1ea7..aa3ad1f 100644 --- a/registry/index.json +++ b/registry/index.json @@ -188,6 +188,7 @@ "packages/ui/src/lib/cn.ts", "packages/ui/src/lib/contracts.ts", "packages/ui/src/lib/cva.ts", + "packages/ui/src/lib/icons.tsx", "packages/ui/src/lib/motion.ts" ], "kind": "component", @@ -220,6 +221,7 @@ "packages/ui/src/lib/cn.ts", "packages/ui/src/lib/contracts.ts", "packages/ui/src/lib/cva.ts", + "packages/ui/src/lib/icons.tsx", "packages/ui/src/lib/motion.ts" ], "kind": "component", @@ -252,6 +254,7 @@ "packages/ui/src/lib/cn.ts", "packages/ui/src/lib/contracts.ts", "packages/ui/src/lib/cva.ts", + "packages/ui/src/lib/icons.tsx", "packages/ui/src/lib/motion.ts" ], "kind": "component", @@ -297,6 +300,7 @@ "packages/ui/src/lib/cn.ts", "packages/ui/src/lib/contracts.ts", "packages/ui/src/lib/cva.ts", + "packages/ui/src/lib/icons.tsx", "packages/ui/src/lib/motion.ts" ], "kind": "component", @@ -330,7 +334,8 @@ "packages/ui/src/components/dialog.variants.ts", "packages/ui/src/lib/cn.ts", "packages/ui/src/lib/contracts.ts", - "packages/ui/src/lib/cva.ts" + "packages/ui/src/lib/cva.ts", + "packages/ui/src/lib/icons.tsx" ], "kind": "component", "name": "dialog", @@ -359,7 +364,8 @@ "packages/ui/src/components/dropdown-menu.variants.ts", "packages/ui/src/lib/cn.ts", "packages/ui/src/lib/contracts.ts", - "packages/ui/src/lib/cva.ts" + "packages/ui/src/lib/cva.ts", + "packages/ui/src/lib/icons.tsx" ], "kind": "component", "name": "dropdown-menu", @@ -621,6 +627,7 @@ "packages/ui/src/lib/cn.ts", "packages/ui/src/lib/contracts.ts", "packages/ui/src/lib/cva.ts", + "packages/ui/src/lib/icons.tsx", "packages/ui/src/lib/motion.ts" ], "kind": "component", @@ -679,7 +686,8 @@ "packages/ui/src/components/sheet.variants.ts", "packages/ui/src/lib/cn.ts", "packages/ui/src/lib/contracts.ts", - "packages/ui/src/lib/cva.ts" + "packages/ui/src/lib/cva.ts", + "packages/ui/src/lib/icons.tsx" ], "kind": "component", "name": "sheet", @@ -854,6 +862,7 @@ "packages/ui/src/lib/cn.ts", "packages/ui/src/lib/contracts.ts", "packages/ui/src/lib/cva.ts", + "packages/ui/src/lib/icons.tsx", "packages/ui/src/lib/motion.ts" ], "kind": "component", diff --git a/roadmap.md b/roadmap.md index ec04749..330b3e6 100644 --- a/roadmap.md +++ b/roadmap.md @@ -1,4 +1,4 @@ -# AI UI Roadmap +# Cadence UI Roadmap ## Goal @@ -7,7 +7,22 @@ Build a long-term maintainable component system inspired by `shadcn/ui`, but own - keep the `Radix + Tailwind + source-owned components` model - replace default styling with our own tokens and component rules - make motion a first-class system layer, not ad hoc transitions -- support theming, accessibility, testing, and future internal registry distribution +- support theming, accessibility, testing, and internal registry distribution + +## Status Snapshot + +This document began as the build-out plan for the system. The current repo has already +completed most of that baseline work: + +- phases 0 through 4 are effectively in place: workspace, tokens, authoring contract, core components, Storybook docs, and baseline tests +- phase 5 has shipped its first advanced-pattern slice with `DataTable`, alongside `Command`, `Combobox`, `Sheet`, and `EmptyState` +- phase 6 has shipped its baseline source-copy registry flow, Changesets gating, and version PR automation + +The next work is mostly hardening and distribution: + +- keep the registry metadata and consumer smoke flow reliable +- decide publish and tagging policy +- expand advanced patterns only where real product usage justifies them ## Product Principles @@ -70,7 +85,7 @@ packages/ tokens/ # design + motion tokens icons/ # optional icon wrappers config/ # shared ts/eslint/tailwind config, optional -registry/ # future internal shadcn-like registry +registry/ # internal source-copy registry ``` ### `packages/ui` structure @@ -319,6 +334,9 @@ Exit criteria: ## Phase 5: Advanced Patterns +Status: +Baseline shipped. + Objective: Build higher-level patterns only after the base layer is stable. @@ -333,6 +351,15 @@ Candidate patterns: - `Sheet` - `Empty State` +Current shipped patterns: + +- `Form` +- `Data Table` +- `Command` +- `Combobox` +- `Sheet` +- `Empty State` + Exit criteria: - patterns reuse existing component contracts @@ -340,6 +367,9 @@ Exit criteria: ## Phase 6: Internal Registry and Distribution +Status: +Baseline source-copy distribution is shipped. Publish automation is still open. + Objective: Create an internal distribution model similar to `shadcn`, but based on our own rules. @@ -350,6 +380,19 @@ Deliverables: - documentation for install and upgrade paths - versioning and release process +Delivered so far: + +- generated `registry/index.json` +- local `pnpm registry:install` copy-in workflow +- `pnpm test:registry:consumer` validation +- Changesets status checks and version PR automation + +Remaining follow-up: + +- publish decision and package registry posture +- tagging policy for stable install points +- any automation beyond source-copy installs + Exit criteria: - consumers can pull components from our registry