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,59 @@
+# Gauge Component
+
+- Status: `completed`
+- Owner: `Codex`
+- Date: `2026-03-25`
+
+## Goal
+
+Add a true radial `Gauge` component to `packages/ui` so the system supports meter-style KPI
+visuals in addition to linear `Progress` and segmented progress bars.
+
+## Scope
+
+- In scope:
+  - add a new `Gauge` component with radial SVG rendering
+  - support dial and semi-circle shapes
+  - cover the component with tests and Storybook docs
+  - export the component from `@ai-ui/ui`
+- Out of scope:
+  - registry metadata refresh while the worktree already contains unrelated registry edits
+  - retrofitting local draft dashboard stories to use the new component
+  - animated needle / pointer gauges
+
+## Constraints
+
+- `Gauge` should use `role="meter"` rather than overloading `Progress`.
+- Keep `variant` semantic and reserve geometry differences for a dedicated shape dimension.
+- Follow the current Cadence UI tonal and motion language.
+- Preserve the existing dirty worktree and avoid rewriting unrelated draft files.
+
+## Affected Surfaces
+
+- `packages/ui/src/components/gauge.tsx`
+- `packages/ui/src/components/gauge.variants.ts`
+- `packages/ui/src/components/gauge.test.tsx`
+- `packages/ui/src/skins.css`
+- `packages/ui/src/index.ts`
+- `apps/docs/src/components/gauge.stories.tsx`
+
+## Plan
+
+1. Define the Gauge API, rendering geometry, and stable slots.
+2. Implement the component with skin tokens and SVG arc math.
+3. Add tests and Storybook docs for geometry, states, and accessibility guidance.
+4. Run targeted validation for the package surface and changed files.
+
+## Validation
+
+- `pnpm --filter @ai-ui/ui typecheck`
+- `pnpm --filter @ai-ui/ui build`
+- `pnpm --filter @ai-ui/ui exec vitest run packages/ui/src/components/gauge.test.tsx --config ../../vitest.config.ts`
+- `pnpm exec eslint apps/docs/src/components/gauge.stories.tsx packages/ui/src/components/gauge.tsx packages/ui/src/components/gauge.variants.ts packages/ui/src/components/gauge.test.tsx packages/ui/src/index.ts`
+
+## Status Log
+
+- `2026-03-25 18:30` Read the closest dashboard-oriented component and story patterns, and scoped Gauge as a separate meter primitive rather than an extension of Progress.
+- `2026-03-25 18:42` Implemented the `Gauge` component with radial SVG geometry, dial and semi-circle shapes, meter semantics, and stable slots.
+- `2026-03-25 18:47` Added package exports, skin tokens, unit coverage, and a dedicated Storybook docs page for Gauge.
+- `2026-03-25 18:51` Verified `pnpm --filter @ai-ui/ui typecheck`, `pnpm --filter @ai-ui/ui build`, `pnpm --filter @ai-ui/ui exec vitest run packages/ui/src/components/gauge.test.tsx --config ../../vitest.config.ts`, targeted `eslint`, and `pnpm harness:validate:docs`.