feat(ui): polish core component surfaces

2026-03-25 19:49:15 +08:00
parent eccaacece7
commit cc1509d2f6
64 changed files with 2707 additions and 353 deletions
@@ -0,0 +1,60 @@
+# Progress Patterns
+
+- Status: `completed`
+- Owner: `Codex`
+- Date: `2026-03-25`
+
+## Goal
+
+Extend `Progress` beyond the default linear fill so the component can also render segmented
+dashboard-style progress bars like the operational cost reduction example, without splitting the
+API into separate one-off components.
+
+## Scope
+
+- In scope:
+  - add a structural `pattern` dimension to `Progress`
+  - support a segmented dashboard meter mode
+  - keep the existing linear pattern untouched as the default
+  - update tests, exports, and Storybook docs
+- Out of scope:
+  - radial gauge visuals
+  - introducing a separate `Gauge` component
+  - modifying unrelated dashboard story drafts
+
+## Constraints
+
+- Keep `variant` reserved for semantic color intent.
+- Preserve the existing ARIA progressbar behavior.
+- Expose stable slots and `data-*` hooks for the segmented structure.
+- Stay within the current Cadence UI tonal and motion language.
+
+## Affected Surfaces
+
+- `packages/ui/src/components/progress.tsx`
+- `packages/ui/src/components/progress.variants.ts`
+- `packages/ui/src/components/progress.test.tsx`
+- `packages/ui/src/skins.css`
+- `packages/ui/src/index.ts`
+- `apps/docs/src/components/progress.stories.tsx`
+
+## Plan
+
+1. Add a `pattern` API for `linear` and `segmented` progress structures.
+2. Implement segmented rendering with stable slots and deterministic filled-state logic.
+3. Refresh docs so the segmented meter is shown in a realistic dashboard context.
+4. Run targeted validation for the package and docs surfaces.
+
+## Validation
+
+- `pnpm --filter @ai-ui/ui typecheck`
+- `pnpm --filter @ai-ui/ui test -- --run packages/ui/src/components/progress.test.tsx`
+- `pnpm harness:validate:docs`
+
+## Status Log
+
+- `2026-03-25 17:58` Confirmed the existing Progress API is linear-only and inspected the local revenue dashboard draft for the target segmented visual language.
+- `2026-03-25 18:10` Added a `pattern` dimension with segmented rendering, repeated segment slots, and progress-specific skin tokens for dashboard meters.
+- `2026-03-25 18:14` Updated Storybook docs and package exports to document and expose the segmented mode.
+- `2026-03-25 18:18` Verified `pnpm --filter @ai-ui/ui typecheck`, `pnpm --filter @ai-ui/ui exec vitest run packages/ui/src/components/progress.test.tsx --config ../../vitest.config.ts`, and targeted `eslint` on the changed files.
+- `2026-03-25 18:19` `pnpm harness:validate:docs` is currently blocked by an unrelated local Storybook draft: `apps/docs/src/components/metric-card.stories.tsx` imports `MetricCard` from `@ai-ui/ui`, but that export is not present in the built package yet.