feat(ui): add analytics primitives and layout patterns

2026-03-25 19:49:49 +08:00
parent cc1509d2f6
commit a5d75f42e9
63 changed files with 7751 additions and 2 deletions
@@ -0,0 +1,73 @@
+# Grid Primitives
+
+- Status: `completed`
+- Owner: `codex`
+- Date: `2026-03-25`
+
+## Goal
+
+Add Cadence UI source-owned `Row` / `Col` grid primitives so product and docs surfaces can build
+responsive split layouts and dashboard sections without repeating ad hoc width math, alignment
+fixes, or one-off `grid-cols-*` strings.
+
+## Scope
+
+- In scope:
+  - add public `Row` and `Col` primitives to `packages/ui`
+  - support a 12-column responsive layout model with tokenized gaps
+  - support base plus breakpoint-specific `span` and `offset` placement on `Col`
+  - expose stable slot and `data-*` hooks
+  - document the primitives in Storybook
+  - add unit coverage for the main layout contract
+- Out of scope:
+  - nested layout orchestration helpers such as `SplitPanel` or dialog-specific shells
+  - CSS container-query driven layout APIs
+  - ordering, push/pull, or visual reordering props that can drift from DOM order
+  - replacing every existing docs layout in this pass
+
+## Constraints
+
+- Keep the API small and familiar to teams coming from Ant Design / Element style `Row` / `Col`.
+- Stay token-first for spacing instead of baking new hardcoded per-story gutters.
+- Preserve DOM order as the semantic order; layout props should not encourage accessibility drift.
+- Avoid introducing an external layout framework or dependency for this capability.
+
+## Affected Surfaces
+
+- `packages/ui/src/components`
+- `packages/ui/src/index.ts`
+- `packages/ui/src/lib/contracts.ts`
+- `packages/ui/src/skins.css`
+- `apps/docs/src/components`
+- `docs/exec-plans`
+- `registry/index.json`
+
+## Plan
+
+1. Add the execution plan and define a minimal Cadence UI grid contract.
+2. Implement `Row` and `Col` with a 12-column base, tokenized gap sizes, and responsive
+   `span` / `offset` placement.
+3. Export the primitives on the public surface and document them in Storybook with usage,
+   anatomy, and accessibility guidance.
+4. Add focused unit coverage, run narrow validation, then rebuild registry metadata for the
+   new public entrypoint.
+
+## Validation
+
+- `pnpm --filter @ai-ui/ui test -- grid`
+- `pnpm build:docs`
+- `pnpm registry:build`
+
+## Orchestration Task Sketch
+
+- `T1`: implement the grid primitives, skins, and public exports
+- `T2 -> T1`: add Storybook docs, tests, and rebuild registry metadata
+
+## Status Log
+
+- `2026-03-25 16:18` started after confirming the repo has many direct grid utility usages but no
+  reusable source-owned layout primitive for responsive row/column composition
+- `2026-03-25 18:54` implemented public `Row` / `Col` primitives, exported them from `@ai-ui/ui`,
+  added Storybook coverage, and registered the new source-owned `grid` entrypoint
+- `2026-03-25 18:56` validated with `pnpm --filter @ai-ui/ui test -- grid`,
+  `pnpm --filter @ai-ui/ui build`, `pnpm build:docs`, and `pnpm registry:build`