73 lines
3.7 KiB
Markdown
73 lines
3.7 KiB
Markdown
# Sparkbar Primitive
|
|
|
|
- Status: `completed`
|
|
- Owner: `codex`
|
|
- Date: `2026-03-25`
|
|
|
|
## Goal
|
|
|
|
Add a dedicated `Sparkbar` micro-visual primitive to `@ai-ui/ui` so compact KPI cards and
|
|
dashboard tiles can render tiny bar-based trend summaries without hand-written DOM.
|
|
|
|
## Scope
|
|
|
|
- In scope:
|
|
- add a new `Sparkbar` component to `packages/ui`
|
|
- keep the API narrow and card-focused: small size, low configuration, embedded usage
|
|
- support simple bar highlighting for active ranges without turning the component into a full
|
|
charting surface
|
|
- add unit tests and Storybook docs for the public contract
|
|
- replace the hand-written sparkbar markup in `apps/docs/src/revenue-dashboard.stories.tsx`
|
|
and the related metric-card docs story
|
|
- Out of scope:
|
|
- introducing a full `Sparkline` API in the same slice
|
|
- adding axes, tooltips, interaction, or data transforms that belong to `Chart`
|
|
- expanding `Chart` itself to absorb micro-visual responsibilities
|
|
- broader dashboard contract cleanup outside the bar micro-vis use cases
|
|
|
|
## Constraints
|
|
|
|
- Follow `DESIGN.md` and keep the visual language tonal, rounded, and quiet enough for card media.
|
|
- Preserve a stable slot and `data-*` contract so docs and tests can target the primitive.
|
|
- Keep the public API additive and intentionally smaller than `Chart`.
|
|
- Avoid rewriting unrelated dirty-worktree changes while touching shared files like docs stories and
|
|
package exports.
|
|
|
|
## Affected Surfaces
|
|
|
|
- `docs/exec-plans/2026-03-25-sparkbar-primitive.md`
|
|
- `packages/ui/src/components/sparkbar.tsx`
|
|
- `packages/ui/src/components/sparkbar.variants.ts`
|
|
- `packages/ui/src/components/sparkbar.test.tsx`
|
|
- `packages/ui/src/index.ts`
|
|
- `packages/ui/src/skins.css`
|
|
- `apps/docs/src/components/sparkbar.stories.tsx`
|
|
- `apps/docs/src/components/metric-card.stories.tsx`
|
|
- `apps/docs/src/revenue-dashboard.stories.tsx`
|
|
- `registry/index.json`
|
|
|
|
## Plan
|
|
|
|
1. Define a narrow `Sparkbar` API for embedded numeric bar trends and active-range emphasis.
|
|
2. Implement the component with stable slots, tone/variant styling, and decorative-by-default
|
|
accessibility behavior.
|
|
3. Add Storybook stories that explain when to use `Sparkbar` instead of `Chart`.
|
|
4. Replace the existing hand-written bar maps in docs consumers with the new primitive.
|
|
5. Run focused package and docs validation, then record any remaining gaps.
|
|
|
|
## Validation
|
|
|
|
- `pnpm --filter @ai-ui/ui typecheck`
|
|
- `pnpm --filter @ai-ui/ui exec vitest run packages/ui/src/components/sparkbar.test.tsx --config ../../vitest.config.ts`
|
|
- `pnpm exec eslint apps/docs/src/components/sparkbar.stories.tsx apps/docs/src/components/metric-card.stories.tsx apps/docs/src/revenue-dashboard.stories.tsx packages/ui/src/components/sparkbar.tsx packages/ui/src/components/sparkbar.variants.ts packages/ui/src/components/sparkbar.test.tsx packages/ui/src/index.ts`
|
|
- `pnpm harness:validate:docs`
|
|
- `pnpm registry:build`
|
|
|
|
## Status Log
|
|
|
|
- `2026-03-25 21:15` Read the system-of-record files and confirmed the repo currently has a full `Chart` pattern but no dedicated micro bar-trend primitive.
|
|
- `2026-03-25 21:22` Scoped the new component as `Sparkbar`: low-config, non-interactive, card-embedded, and explicitly separate from `Chart`.
|
|
- `2026-03-25 23:18` Implemented `Sparkbar`, tokenized its size/tone/variant styling, exported it from `@ai-ui/ui`, and added unit coverage for slots, emphasis, and accessibility behavior.
|
|
- `2026-03-25 23:28` Added dedicated Storybook docs and migrated the handwritten spark bars in the revenue dashboard and metric-card stories to the new primitive.
|
|
- `2026-03-25 23:34` Verified `pnpm --filter @ai-ui/ui typecheck`, targeted Sparkbar Vitest coverage, targeted ESLint, `pnpm harness:validate:docs`, and `pnpm registry:build`.
|