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,77 @@
+# Chart Pattern
+
+- Status: `completed`
+- Owner: `codex`
+- Date: `2026-03-25`
+
+## Goal
+
+Add a reusable `Chart` pattern to `@ai-ui/ui` that can render the kind of dashboard trend panel
+shown in the supplied reference: multi-series lines, soft area shading, an active point summary,
+and a composable card-like review surface that still follows Cadence UI's current visual language.
+
+## Scope
+
+- In scope:
+  - add a new `Chart` component to `packages/ui`
+  - keep the first release focused on cartesian trend charts for dashboard analytics surfaces
+  - support multi-series rendering, optional area fills, axes, legend, and active-point callouts
+  - add Storybook stories, including a `Sales Impact`-style showcase
+  - add unit coverage for the public contract and interactive active-point behavior
+  - refresh repo status docs to reflect the shipped pattern
+- Out of scope:
+  - introducing a third-party charting dependency
+  - building a full visualization framework with bars, pies, heatmaps, and pivoting
+  - server-driven drilldown, zooming, panning, or data transforms outside the component
+  - adding the new story to the curated browser harness unless it becomes a required regression
+    surface
+
+## Constraints
+
+- Follow `DESIGN.md` over the raw screenshot when visual details conflict.
+- Reuse existing tokens, motion rules, and card-like surface styling instead of hardcoded brand
+  treatments.
+- Keep the API source-owned and narrow, similar to the `DataTable` philosophy.
+- Preserve stable `data-slot` and `data-*` hooks so docs and tests can target the component
+  predictably.
+
+## Affected Surfaces
+
+- `docs/exec-plans/2026-03-25-chart-pattern.md`
+- `packages/ui/src/components/chart.tsx`
+- `packages/ui/src/components/chart.variants.ts`
+- `packages/ui/src/components/chart.test.tsx`
+- `packages/ui/src/index.ts`
+- `apps/docs/src/components/chart.stories.tsx`
+- `README.md`
+- `roadmap.md`
+- `registry/index.json`
+
+## Plan
+
+1. Add an execution plan and update repo status docs for the new public pattern.
+2. Implement a source-owned `Chart` component that supports multi-series dashboard trend charts
+   without adding an external chart library.
+3. Add Storybook stories that explain anatomy and demonstrate a `Sales Impact`-style analytics
+   panel.
+4. Add unit tests for slots, legend rendering, active-point updates, and controlled state.
+5. Run the narrowest useful validation suites, then record any remaining gaps.
+
+## Validation
+
+- `pnpm test -- --runInBand`
+- `pnpm harness:validate:docs`
+- `pnpm registry:build`
+
+## Orchestration Task Sketch
+
+- `T1`: implement the Chart component and export surface
+- `T2 -> T1`: add docs stories and validate the rendered showcase
+- `T3 -> T1`: add tests and registry updates
+
+## Status Log
+
+- `2026-03-25 19:08` Read the system-of-record files and confirmed the repo does not yet ship a chart pattern.
+- `2026-03-25 19:18` Started the chart implementation plan for a new dashboard-focused analytics pattern.
+- `2026-03-25 19:42` Implemented the new `Chart` component, public exports, stories, tests, and status-doc updates.
+- `2026-03-25 19:55` Validated `packages/ui` typecheck, targeted chart tests, package builds, Storybook docs build, and registry generation. `pnpm harness:validate:changed` still failed because the dirty worktree already contains unrelated `apps/docs/src/revenue-dashboard.stories.tsx` type errors and existing `react-refresh/only-export-components` warnings in `packages/ui/src/components/context-menu.tsx`.