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,71 @@
+# Dashboard Contract Hardening
+
+- Status: `completed`
+- Owner: `codex`
+- Date: `2026-03-25`
+
+## Goal
+
+Harden the new dashboard-oriented component contracts so the `Revenue Dashboard` scene no longer
+needs to bypass them for high-emphasis KPI cards or for custom chart header layouts.
+
+## Scope
+
+- In scope:
+  - extend `MetricCard` with high-emphasis tones suitable for dark or hero KPI panels
+  - add structured `MetricCard` header slots for leading and aside content
+  - make the `Chart` header composable without breaking the current convenience props
+  - refresh docs stories, tests, and the revenue dashboard consumer to use the stronger contracts
+- Out of scope:
+  - introducing a full dashboard layout or navigation system
+  - expanding the chart surface beyond the existing cartesian trend pattern
+  - extracting new sparkline or sparkbar primitives in this slice
+
+## Constraints
+
+- Preserve the current Material-inspired design direction in `DESIGN.md`.
+- Keep the API additive and source-owned instead of replacing existing stories with one-off markup.
+- Preserve the stable slot and `data-*` review surface so tests and docs stay predictable.
+- Keep the current `title` / `description` / `value` / `valueChange` chart props working while
+  adding the more composable header path.
+
+## Affected Surfaces
+
+- `docs/exec-plans`
+- `packages/ui/src/components/metric-card.tsx`
+- `packages/ui/src/components/metric-card.variants.ts`
+- `packages/ui/src/components/chart.tsx`
+- `packages/ui/src/components/chart.variants.ts`
+- `packages/ui/src/index.ts`
+- `packages/ui/src/components/*.test.tsx`
+- `apps/docs/src/components/*.stories.tsx`
+- `apps/docs/src/revenue-dashboard.stories.tsx`
+
+## Plan
+
+1. Extend `MetricCard` with `inverse` and `hero` visual tones plus stable `leading` and `aside`
+   header slots.
+2. Refactor `Chart` to accept a composed header while keeping the current prop-based header API as
+   a convenience fallback.
+3. Update stories and the revenue dashboard scene so the new contracts are exercised by real
+   compositions instead of only isolated tests.
+4. Run focused component and docs validation, then record any residual issues.
+
+## Validation
+
+- `pnpm --filter @ai-ui/ui test -- metric-card chart`
+- `pnpm --filter @ai-ui/ui typecheck`
+- `pnpm build:docs`
+
+## Orchestration Task Sketch
+
+- `T1`: harden `MetricCard` tone and header composition contract
+- `T2 -> T1`: harden `Chart` header composition contract
+- `T3 -> T2`: refresh stories, revenue dashboard usage, and focused validation
+
+## Status Log
+
+- `2026-03-25 20:36` started the contract-hardening slice after reviewing the revenue dashboard and confirming that `Sales Growth` and `Sales Impact` still rely on API workarounds rather than first-class component affordances
+- `2026-03-25 20:49` extended `MetricCard` with `inverse` and `hero` tones plus `leading` and `aside` header slots, then refactored the docs story and revenue dashboard consumer to use them
+- `2026-03-25 20:56` refactored `Chart` to support a composed header path while preserving the legacy prop-driven header contract, and updated stories and tests to cover both paths
+- `2026-03-25 20:59` validated focused `MetricCard` and `Chart` tests plus `build:docs`; `pnpm --filter @ai-ui/ui typecheck` is still blocked by unrelated pre-existing `packages/ui/src/components/sparkbar.tsx` type errors outside this slice