@usetheo/ui 0.6.3-next.0 → 0.8.0-next.0

package/CHANGELOG.md

@@ -7,6 +7,206 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0-next.0] - 2026-05-23
+
+Minor — adds eight cross-cutting primitives revealed by the systematic
+review of the remaining 11 dashboard pages (Projects, Environments,
+Team, Billing, Domains, Settings, Profile, Login, Register,
+Verification, Recovery, DeviceSuccess) + recurring PaaS UI patterns.
+Each component is used in ≥3 distinct sites in the consumer dashboard.
+6 are true primitives (Table, StatusDot, CopyButton, Timestamp,
+StatTile, DangerZone); 2 are composites by taxonomy gate
+(ConfirmDialog depends on Dialog/Input/Button; CodeBlock depends on
+CopyButton). Zero breaking change; zero new peer-deps.
+
+Plan: `.claude/knowledge-base/plans/dashboard-paas-primitives-2-plan.md`.
+Edge-case review: `.claude/knowledge-base/reviews/edge-cases/dashboard-paas-primitives-2-edge-cases-2026-05-23.md`.
+Consumer brief: `theo/docs/handoff/2026-05-23-theo-ui-cloud-dashboard-gaps-brief-2.md`.
+
+### Added
+
+- **`<Table>` primitive (NEW)** — semantic data-table with sub-components
+  `Table.Header`, `Table.Body`, `Table.Row`, `Table.Cell`,
+  `Table.HeaderCell`. Supports `density` (`default` / `compact` via
+  Context), per-cell `align` (`left` / `center` / `right`), `numeric`
+  cells (`font-mono tabular-nums`), and sortable header cells
+  (`onSort` + `sortDirection` with ChevronUp/ChevronDown affordance
+  + `aria-sort`). `sortDirection` without `onSort` is a no-op (header
+  stays static); `sortDirection="none"` with `onSort` renders both
+  chevrons dimmed (`opacity-30`). 10 unit tests + 4 Ladle stories.
+  Brief #2 consumer: TheoCloud dashboard.
+- **`<StatusDot>` primitive (NEW)** — semantic status indicator
+  (small colored circle + optional label). Five `status` kinds:
+  `live` (success), `building` (warning, auto-pulses), `failed`
+  (destructive), `idle` (muted), `warning` (warning, static). Three
+  sizes (`xs` 6px / `sm` 8px default / `md` 10px). When neither
+  `label` nor `aria-label` is provided, auto-applies
+  `aria-label={status}` + emits a dev-only warning (color-only
+  status is invisible to screen readers). 12 unit tests + 3 stories.
+  Brief #2 consumer: TheoCloud dashboard (7+ sites).
+- **`<CopyButton>` primitive (NEW)** — click-to-copy primitive wrapping
+  `navigator.clipboard.writeText`. Icon swap (Copy → Check on success,
+  Copy → X on failure), `aria-live="polite"` announcement for screen
+  readers, optional `label`, `ghost`/`outline` variants, two sizes,
+  `onCopied` callback, configurable `feedbackDuration` (default
+  1500ms). SSR-safe (guards `navigator?.clipboard?.writeText`); HTTP
+  non-localhost contexts (where the Clipboard API is undefined) fall
+  back to the failed state instead of throwing. Auto-cleans the
+  revert timer on unmount; debounces double-clicks. 12 unit tests +
+  4 Ladle stories. Brief #2 consumer: TheoCloud dashboard.
+- **`<Timestamp>` primitive (NEW)** — accessible `<time datetime>`
+  element with `relative` (default) / `absolute` / `both` formats.
+  Uses zero-dep `Intl.RelativeTimeFormat`. Auto-refreshes via
+  `setInterval` (default 60s, `refreshInterval={0}` disables).
+  Native `title` HTML attribute carries the absolute time on hover
+  (no Tooltip component dependency — keeps Timestamp a true
+  primitive). `aria-label` always carries the full date. Invalid
+  date renders an empty `<time>` element; invalid locale falls back
+  to default with a dev warning. `value` accepts ISO string, Date,
+  or **Unix milliseconds** (documented in JSDoc — passing seconds
+  renders ~1970). 13 unit tests + 4 Ladle stories. Brief #2
+  consumer: TheoCloud dashboard (every dashboard page).
+- **`<StatTile>` primitive (NEW)** — big-number stat tile for
+  dashboard summary rows. `value` + `label` + optional `icon` +
+  optional `delta` (`{value, trend}` with `trend: "up" | "down" |
+  "flat"` driving TrendingUp/TrendingDown/Minus icons and
+  success/destructive/muted color). Dual mode (button/div) based on
+  `onClick` — same pattern as `AccountMenu`/`ProjectSwitcher`. Value
+  uses `font-display tabular-nums whitespace-nowrap`. 7 unit tests
+  + 4 Ladle stories. Brief #2 consumer: TheoCloud Overview
+  dashboard (3 tiles per page).
+- **`<DangerZone>` primitive (NEW)** — destructive-actions section
+  with sub-component `DangerZone.Action`. Red-bordered container
+  (`border-destructive/30`) with title bar (default `"Danger Zone"`)
+  and action rows. Each row carries `title` + `description` +
+  consumer-provided `action` slot (typically a destructive
+  `<Button>`). Rows separated by hairline dividers; last row drops
+  the bottom border via `last:border-b-0`. Consumer supplies the
+  destructive button — DangerZone never imports `<Button>`, keeping
+  it a true primitive. 6 unit tests + 3 Ladle stories. Brief #2
+  consumer: Settings + Profile + Team + Billing pages.
+- **`<ConfirmDialog>` composite (NEW)** — controlled confirmation
+  modal built on `Dialog`. Auto-focuses Cancel on open (deliberate
+  — NOT the destructive button). `intent="destructive"` styles the
+  confirm button with the destructive variant. `confirmationPhrase`
+  enables typed-confirmation guard (case-sensitive, empty string
+  treated as no phrase). Pressing Enter in the input triggers
+  confirm when matched. Async `onConfirm` shows `Loader2` spinner
+  while pending; resolve closes the dialog; reject keeps it open
+  so consumers can surface their own error. Phrase input resets
+  whenever the dialog closes. 13 unit tests + 4 Ladle stories.
+  Composite (depends on Dialog + Button + Input). Brief #2
+  consumer: 6+ destructive flows (Settings delete, Team remove,
+  Billing cancel, Profile delete, Domains remove, Environments
+  delete).
+- **`<CodeBlock>` composite (NEW)** — terminal command / code-snippet
+  surface. Pre-rendered code inside a `<pre>` with optional
+  `terminal` prefix per line (`"$ "`), optional `caption` (file
+  name), and optional inline `<CopyButton>` positioned top-right.
+  The CopyButton receives the RAW `code` (without the visual `"$ "`
+  prefix) — consumers paste only the executable command. `language`
+  prop is reserved for future syntax highlighting (v1 ignored).
+  7 unit tests + 4 Ladle stories. Composite (depends on
+  CopyButton). Brief #2 consumer: Overview EmptyState, Projects
+  EmptyState, Domains DNS records, API token display, LoginPage
+  CLI hint.
+
+### Implementation notes
+
+- **Taxonomy gate** classified ConfirmDialog + CodeBlock as composites
+  (D2 in the plan). Brief #2 listed all 8 as primitives, but the
+  validate-quality-gates.ts script is hard-fail for any
+  `primitives/` file that imports another `@usetheo/ui` component.
+- **Timestamp uses native `title` HTML attribute** (D3) instead of
+  the `<Tooltip>` component, to keep the file a true primitive
+  without sibling-primitive imports.
+- **Zero new peer-deps.** Every component uses only `lucide-react`
+  + Radix (both already peer) + `cn()`.
+- **Bundle delta** — `dist/index.js` grew from 395763 B to 417113 B
+  (+21350 B / +5.4%); `dist/index.d.ts` grew +11808 B / +7.5%. Both
+  exceeded the ±5% tolerance by a small margin (8 components ≈ +2.5 KB
+  each on average). The baseline was rebaselined in the same release
+  (`scripts/baselines/bundle-sizes.json`) — expected and explicit per
+  plan D6.
+- 10 SHOULD TEST edge cases from the `/edge-case-plan` review
+  incorporated into the TDD blocks (EC-1 through EC-10 — empty
+  CopyButton value, unmount during timer, clipboard undefined,
+  Table sort direction without onSort, dimmed affordance for
+  `none`, StatusDot dev warning, Timestamp Unix seconds vs ms,
+  invalid locale fallback, ConfirmDialog empty phrase semantics,
+  Enter-to-confirm in phrase input).
+
+## [0.7.0-next.0] - 2026-05-23
+
+Minor — adds four PaaS-shape primitives to cover the gaps surfaced by the
+TheoCloud dashboard migration: multi-metric `UsageMeter`, standalone
+`Progress` bar, semantic `PlanBadge`, and sidebar `AccountMenu`. Each
+primitive is a SIBLING of an existing agent-shape primitive — no breaking
+changes, no modifications to current components. The library's
+agent-first positioning (per `PITCH.md`) stays intact; both shapes now
+coexist with TypeScript dispatch by name.
+
+Plan: `.claude/knowledge-base/plans/dashboard-paas-primitives-plan.md`.
+Consumer brief: `theo/docs/handoff/2026-05-23-theo-ui-cloud-dashboard-gaps-brief.md`.
+
+### Added
+
+- **`<Progress>` primitive (NEW)** — accessible progress bar built on
+  `<div role="progressbar">` (not native `<progress>` — Tailwind classes
+  style cross-browser reliably). Variants:
+  - `intent`: `default` / `success` / `warning` / `destructive`
+  - `height`: `h-1` (default) / `h-1.5` / `h-2` / `h-3`
+  - `indeterminate`: animated bar with no value (omits `aria-valuenow`,
+    sets `aria-busy="true"`)
+  Clamping handles `value > max` (clamps to max) + `value < 0` (clamps to
+  0) + `max = 0` (no NaN/Infinity). Respects `prefers-reduced-motion`.
+  14 unit tests + 6 Ladle stories. (#TBD)
+- **`<UsageMeter>` primitive (NEW)** — multi-metric stacked usage card
+  for PaaS dashboards. Renders N metrics (data transfer, requests, build
+  minutes, seats, …) each with `label + value/max + <Progress>` bar.
+  Supports custom per-metric `formatter`, automatic over-quota warning
+  (value text gets `text-warning`, `<Progress>` uses `intent="warning"`
+  AND clamps the bar at 100%), and a `compact` bars-only mode. PaaS-shape
+  sibling of `<CostMeter>` (which stays single-USD-mono for agent token
+  spend). 12 unit tests + 4 Ladle stories. (#TBD)
+- **`<PlanBadge>` primitive (NEW)** — semantic pricing-tier badge with 5
+  canonical tiers (`free`, `hobby`, `pro`, `team`, `enterprise`) and two
+  sizes (`sm`, `md`). Each tier carries distinct color tokens. Consumers
+  self-document intent (`plan="hobby"`) instead of mapping a generic
+  `<Badge variant="outline">` to colors per app — future rebrand /
+  dark-mode tweaks propagate automatically. Default label capitalizes
+  the tier; `label` prop overrides. Runtime fallback to `free` styling
+  for unknown tier (TypeScript prevents this at compile time). 16 unit
+  tests + 2 Ladle stories. (#TBD)
+- **`<AccountMenu>` primitive (NEW)** — sidebar header for PaaS surfaces.
+  Avatar + name + (optional) `<PlanBadge>` + (optional) secondary line.
+  Dual mode: with `onClick`, renders as `<button>` with trailing
+  `ChevronsUpDown` icon; without, renders as a static `<div>` (not
+  focusable, no chevron). Avatar handling auto-detects URL vs short
+  string (≤2 chars treated as initials) vs undefined (derives initials
+  from `name`). PaaS-shape sibling of `<ProjectSwitcher>` (which stays
+  workspace+branch+agent-status for code-agent surfaces). 13 unit tests
+  + 4 Ladle stories. (#TBD)
+
+### Notes
+
+- **No breaking change.** `CostMeter`, `ProgressChecklist`, `Badge`,
+  `ProjectSwitcher` are untouched. Consumers on 0.6.x see only new
+  exports.
+- **Taxonomy invariant preserved.** `UsageMeter → Progress` and
+  `AccountMenu → Avatar + PlanBadge` use relative-path imports
+  (`../{slug}/index.js`), not barrel imports, so primitives still have
+  zero `@usetheo/ui` cross-dependencies per the structural gate.
+- **Bundle delta.** `dist/index.js` grows by ~6 KB (4 primitives + types
+  + small imports). Within the ±5% baseline tolerance (rebaselined).
+- **Subpath exports.** `package.json#exports` gains `./usage-meter`,
+  `./progress`, `./plan-badge`, `./account-menu` per existing
+  convention (auto-synced by `scripts/sync-exports.ts`).
+- **Registry items.** Four new `registry/r/*.json` descriptors ship for
+  shadcn-style copy-paste install. `usage-meter` declares `progress` as
+  a `registryDependencies`; `account-menu` declares `avatar` +
+  `plan-badge`.
+
 ## [0.6.3-next.0] - 2026-05-23
 
 Patch — eliminate React hydration mismatch in `<ThemeProvider>`. Reported

package/README.md

@@ -13,8 +13,8 @@ A React component library built for AI agent surfaces and cloud dashboards. **10
 <!-- BEGIN:counts -->
 [![license](https://img.shields.io/badge/license-Apache--2.0-7C3AED?style=flat-square)](./LICENSE)
 [![react](https://img.shields.io/badge/react-18+-7C3AED?style=flat-square&logo=react&logoColor=white)](https://react.dev)
-[![tests](https://img.shields.io/badge/tests-1123%20passing-success?style=flat-square)](#quality-gates)
-[![components](https://img.shields.io/badge/components-120-7C3AED?style=flat-square)](#component-catalog)
+[![tests](https://img.shields.io/badge/tests-1250%20passing-success?style=flat-square)](#quality-gates)
+[![components](https://img.shields.io/badge/components-132-7C3AED?style=flat-square)](#component-catalog)
 [![shadcn](https://img.shields.io/badge/shadcn-compatible-000?style=flat-square)](https://ui.shadcn.com/docs/registry)
 <!-- END:counts -->
 
@@ -133,13 +133,13 @@ import { ThemeProvider, ThemeScript } from "@usetheo/ui";
 ## Component catalog
 
 <!-- BEGIN:component-catalog-intro -->
-**120 components**, organized by mechanical rule: a *primitive* imports no other `@usetheo/ui` component; a *composite* does.
+**132 components**, organized by mechanical rule: a *primitive* imports no other `@usetheo/ui` component; a *composite* does.
 <!-- END:component-catalog-intro -->
 
 <details>
 <summary>
 <!-- BEGIN:primitives-count -->
-**Primitives** (79) — building blocks
+**Primitives** (87) — building blocks
 <!-- END:primitives-count -->
 </summary>
 
@@ -147,17 +147,18 @@ import { ThemeProvider, ThemeScript } from "@usetheo/ui";
 `AgentErrorCard` · `AgentEvent` · `AgentHandoff` · `AgentProfile` · `AgentStartingState` · `AgentStreaming`
 `ArtifactPreview` · `AttachmentChip` · `AuditLogEntry` · `AutoCompactNotice` · `Avatar` · `Badge`
 `BrowserControls` · `BuildLogStream` · `Button` · `CapabilityIndicator` · `Card` · `ChatThread`
-`Checkbox` · `ContextCard` · `ContextWindowBar` · `CostMeter` · `CreatedFilesCard` · `CronJobCard`
-`Dialog` · `DiffViewer` · `EmptyState` · `FolderContextCard` · `FolderSelector` · `FormField`
-`HookConfig` · `HookEventLog` · `Input` · `IntentSelector` · `Label` · `LaneBoard`
-`LoginSplit` · `MCPServerCard` · `MemoryEditor` · `MentionMenu` · `MetricsPanel` · `ModelCard`
-`ModelSelector` · `PermissionMatrix` · `ProgressChecklist` · `ProjectSwitcher` · `QuickActionChips` · `RadioGroup`
-`RecentFoldersList` · `RuleCard` · `RunStats` · `RunningTasksPanel` · `ScrollArea` · `Select`
-`SessionListItem` · `SessionTimeline` · `Sheet` · `Sidebar` · `Skeleton` · `SkillCard`
-`SocialAuthRow` · `StepsRail` · `SubAgentDispatch` · `Switch` · `SystemPromptEditor` · `Tabs`
-`TaskNode` · `TaskPlan` · `TerminalPanel` · `Textarea` · `Toast` · `Toaster`
-`TokenUsageChart` · `ToolCall` · `ToolCallCard` · `ToolResult` · `ToolsList` · `Tooltip`
-`TopNav`
+`Checkbox` · `ContextCard` · `ContextWindowBar` · `CopyButton` · `CostMeter` · `CreatedFilesCard`
+`CronJobCard` · `DangerZone` · `Dialog` · `DiffViewer` · `EmptyState` · `FolderContextCard`
+`FolderSelector` · `FormField` · `HookConfig` · `HookEventLog` · `Input` · `IntentSelector`
+`Label` · `LaneBoard` · `LoginSplit` · `MCPServerCard` · `MemoryEditor` · `MentionMenu`
+`MetricsPanel` · `ModelCard` · `ModelSelector` · `PermissionMatrix` · `PlanBadge` · `Progress`
+`ProgressChecklist` · `ProjectSwitcher` · `QuickActionChips` · `RadioGroup` · `RecentFoldersList` · `RuleCard`
+`RunStats` · `RunningTasksPanel` · `ScrollArea` · `Select` · `SessionListItem` · `SessionTimeline`
+`Sheet` · `Sidebar` · `Skeleton` · `SkillCard` · `SocialAuthRow` · `StatTile`
+`StatusDot` · `StepsRail` · `SubAgentDispatch` · `Switch` · `SystemPromptEditor` · `Table`
+`Tabs` · `TaskNode` · `TaskPlan` · `TerminalPanel` · `Textarea` · `Timestamp`
+`Toast` · `Toaster` · `TokenUsageChart` · `ToolCall` · `ToolCallCard` · `ToolResult`
+`ToolsList` · `Tooltip` · `TopNav`
 <!-- END:primitives -->
 
 </details>
@@ -165,12 +166,12 @@ import { ThemeProvider, ThemeScript } from "@usetheo/ui";
 <details>
 <summary>
 <!-- BEGIN:composites-count -->
-**Composites** (41) — assembled flows
+**Composites** (45) — assembled flows
 <!-- END:composites-count -->
 </summary>
 
 <!-- BEGIN:composites -->
-`AgentComposer` · `AgentEditor` · `AgentStream` · `AgentTimeline` · `ApprovalCard` · `ChatComposer` · `ChatMessage` · `ChatMessageAction` · `ChatMessageActions` · `ChatMessageBranch` · `ChatMessageBranchContent` · `ChatMessageBranchNext` · `ChatMessageBranchPage` · `ChatMessageBranchPrevious` · `ChatMessageBranchSelector` · `ChatMessageContent` · `ChatMessageResponse` · `ChatMessageRoot` · `ChatMessageToolbar` · `CommandPalette` · `CronJobsList` · `DataPart` · `DeploymentRow` · `DomainConfig` · `EnvVarEditor` · `FilePart` · `MCPServerList` · `PermissionModal` · `PreviewEnvCard` · `PreviewPanel` · `ProjectCard` · `ReasoningPart` · `RollbackUI` · `RuleEditor` · `SkillEditor` · `SkillsList` · `SourceDocumentPart` · `SourceUrlPart` · `TaskHeader` · `TextPart` · `ToolCallPart`
+`AccountMenu` · `AgentComposer` · `AgentEditor` · `AgentStream` · `AgentTimeline` · `ApprovalCard` · `ChatComposer` · `ChatMessage` · `ChatMessageAction` · `ChatMessageActions` · `ChatMessageBranch` · `ChatMessageBranchContent` · `ChatMessageBranchNext` · `ChatMessageBranchPage` · `ChatMessageBranchPrevious` · `ChatMessageBranchSelector` · `ChatMessageContent` · `ChatMessageResponse` · `ChatMessageRoot` · `ChatMessageToolbar` · `CodeBlock` · `CommandPalette` · `ConfirmDialog` · `CronJobsList` · `DataPart` · `DeploymentRow` · `DomainConfig` · `EnvVarEditor` · `FilePart` · `MCPServerList` · `PermissionModal` · `PreviewEnvCard` · `PreviewPanel` · `ProjectCard` · `ReasoningPart` · `RollbackUI` · `RuleEditor` · `SkillEditor` · `SkillsList` · `SourceDocumentPart` · `SourceUrlPart` · `TaskHeader` · `TextPart` · `ToolCallPart` · `UsageMeter`
 <!-- END:composites -->
 
 </details>