@usetheo/ui 0.6.2-next.0 → 0.7.0-next.0

package/CHANGELOG.md

@@ -7,6 +7,135 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+by the TheoKit framework team (2026-05-23): every SSR'd app using
+`<ThemeSwitcher>` threw `Hydration failed because the server rendered
+text didn't match the client` on every page reload after a user had
+changed themes, then re-rendered the entire React tree client-side,
+defeating SSR.
+
+### Fixed
+
+- **SSR hydration mismatch on `<ThemeProvider>`** — three `useState`
+  calls (`themeName`, `mode`, `density`) previously ran their initializer
+  on BOTH server (no `window`, returned default) AND client at hydration
+  time (with `window`, returned `localStorage.getItem(…)`). The two
+  diverged → React threw + discarded the SSR'd tree on every page load.
+  Fixed by initializing with the SSR default ALWAYS, then promoting to
+  the stored value via a post-mount `useEffect` after hydration. The
+  visible-text nodes the React reconciler compares (switcher label,
+  `sr-only` announcement, `aria-label`) now match server → client.
+  Stored preferences still apply within one render tick of mount;
+  `<ThemeScript>` continues to set `data-theme` / `data-mode` /
+  `data-density` on `<html>` before React mounts to suppress the
+  1-frame visual flicker. (#TBD)
+- **Persist effect first-mount guard** — a `useRef`-based skip-first
+  flag prevents the persist effect from writing the SSR-safe defaults
+  to `localStorage` between mount and the post-mount hydration
+  setState. Previously, the brief window between commit and the
+  hydration effect could clobber the user's stored preference if the
+  page closed mid-render. After the first call, every subsequent
+  change (user-driven OR hydration-promoted) persists normally. (#TBD)
+
+### Added
+
+- **`<ThemeScript defaultDensity>` prop** — the inline `<script>`
+  bootstrap now also sets `data-density` on `<html>` from
+  `localStorage.getItem(":density")` (or `defaultDensity`, default
+  `"comfortable"`) so density-driven layouts have zero FOUC at first
+  paint. Mirrors `ThemeProvider`'s `defaultDensity`. (#TBD)
+
+### Notes
+
+- Pattern mirrors `next-themes` (Vercel), `MantineProvider`, and
+  shadcn/ui's theme scaffold. The 1-frame state-promotion delay is the
+  React-canonical price for SSR-safe client-only state. `<ThemeScript>`
+  pre-paints the `<html>` attributes so the visible layer doesn't
+  flicker.
+- Two new unit tests guard the regression:
+  - `does NOT write to localStorage on first mount when nothing changes
+    (persist gate)` — verifies the skip-first guard.
+  - `writes to localStorage AFTER a user-driven change (persist fires
+    post-hydration)` — verifies the gate releases after the first call.
+- Existing `reads initial theme name from localStorage` and `reads
+  initial mode from localStorage` tests continue to pass because
+  testing-library's `render()` flushes effects synchronously inside
+  `act()`, so by the assertion phase the post-mount hydration effect
+  has already promoted the stored value.
+
 ## [0.6.2-next.0] - 2026-05-23
 
 Patch — restore `cursor: pointer` on interactive buttons. Tailwind v4

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-1174%20passing-success?style=flat-square)](#quality-gates)
+[![components](https://img.shields.io/badge/components-124-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.
+**124 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** (81) — building blocks
 <!-- END:primitives-count -->
 </summary>
 
@@ -151,13 +151,13 @@ import { ThemeProvider, ThemeScript } from "@usetheo/ui";
 `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`
+`ModelSelector` · `PermissionMatrix` · `PlanBadge` · `Progress` · `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`
 <!-- END:primitives -->
 
 </details>
@@ -165,12 +165,12 @@ import { ThemeProvider, ThemeScript } from "@usetheo/ui";
 <details>
 <summary>
 <!-- BEGIN:composites-count -->
-**Composites** (41) — assembled flows
+**Composites** (43) — 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` · `CommandPalette` · `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>