harebear-ui 0.6.0 → 0.7.0

package/AGENTS.md

@@ -14,6 +14,7 @@ Consumers get compiled ESM + types from `dist/` and a Tailwind stylesheet (`hare
 | `pnpm gen`               | Regenerate `src/index.ts` from component export lists. Run after adding or renaming exports.      |
 | `pnpm format`            | Biome format + safe fixes.                                                                        |
 | `pnpm shadcn add <name>` | Pull a new shadcn component into `src/components/ui/`.                                            |
+| `pnpm shots [filter]`    | Regenerate README images in `.github/assets/` (needs `pnpm dev` running, Chrome and `cwebp`).     |
 
 ## Layout
 
@@ -31,8 +32,11 @@ src/
   hooks/, lib/utils.ts  Shared hooks and cn().
 playground/screens/     Reference screens that use only public exports (#admin, #chat, #records, #home, #auth, #catalog). Visual spec and usage examples.
 docs/COMPONENTS.md      Consumer-facing catalog. Shipped. Test-enforced to mention every export.
+docs/guides/            Getting started (per framework), theming, working with agents. Shipped.
 llms.txt, skills/       Consumer-facing agent docs. Shipped.
-bin/harebear-ui.mjs     `npx harebear-ui init|docs` for consuming apps.
+bin/harebear-ui.mjs     `npx harebear-ui init|docs [name...]` for consuming apps. Zero dependencies.
+scripts/screenshots.mjs `pnpm shots`: captures playground screens and renders .github/assets/art/*.html to images.
+.github/assets/         README imagery (not shipped): logo.svg, screens/*.webp, hero/light-dark/agents art, social.png.
 test/                   Vitest: API snapshot, docs coverage, token integrity, behavior.
 ```
 
@@ -41,11 +45,24 @@ test/                   Vitest: API snapshot, docs coverage, token integrity, be
 1. Pick the folder by purpose (`admin`, `data`, `ai`, `auth`; `ui` only for shadcn primitives).
 2. Follow the existing files: `"use client"` first line, named function component, props interface exported as `<Name>Props`, `data-slot="<kebab-name>"` on the root, `className` merged last with `cn()`, rest props spread on the root.
 3. Style only with tokens (`bg-card`, `text-muted-foreground`, `bg-primary-soft`, `shadow-card`, `rounded-xl`). No hex, no palette colors. Status takes a `tone` (`success | warning | danger | info | neutral`).
-4. `pnpm gen`, then add the component to `docs/COMPONENTS.md` (the docs test fails otherwise) and to the index in `llms.txt`.
+4. `pnpm gen`, then add the component to `docs/COMPONENTS.md` (the docs test fails otherwise) and to the index in `llms.txt`. Use a heading like ``### `Name` `` or a table row with the name in backticks, so `npx harebear-ui docs Name` finds it.
 5. Use it in a playground screen if it is visual, and look at it in light and dark mode and at 375px width.
 6. Add a behavior test in `test/components.test.tsx` if it has logic. `pnpm test -u` to accept the new export in the snapshot.
 7. `pnpm check`.
 
+## Looking at your work
+
+- `pnpm dev`, then open http://localhost:5199/#admin (or `#chat`, `#agent`, `#records`, `#home`, `#auth`, `#catalog`).
+- `?mode=dark` or `?mode=light` pins the theme without touching localStorage; `?shot` hides the screen switcher. Example: http://localhost:5199/?mode=dark&shot#agent
+- A headless capture: `pnpm shots admin` writes `.github/assets/screens/admin-*.webp`.
+
+## README imagery
+
+- `.github/assets/logo.svg` is the mark. It is hand-written SVG; edit it directly. `logo.png` is exported from it.
+- Screens are real playground captures. Art (`hero`, `light-dark`, `agents`) is HTML in `.github/assets/art/` that composes those captures, rendered by `pnpm shots`. `social.png` is the hero at 1x for GitHub's social preview (upload it by hand in repo Settings).
+- After a visible change to a screen or the theme, run `pnpm shots` and commit the images with the change. Check the results by eye before committing.
+- If `npx harebear-ui init` output changes, update the terminal text in `art/agents.html` to match.
+
 ## Changing shadcn primitives
 
 - Keep upstream file structure so `pnpm shadcn add <name> -o` diffs stay readable. Change class strings, add variants; avoid restructuring.

package/README.md

@@ -1,28 +1,72 @@
-# harebear-ui
-
-Pre-themed React components for admin tools, data apps, and AI chat. shadcn/ui primitives restyled to one opinionated design system, plus the composites you end up building every time: app shell, KPI cards, data table, trend charts, chat thread, prompt composer, model picker.
-
-React 19 · Tailwind CSS v4 · Radix · TanStack Table v9 · Recharts 3 · TypeScript
-
-## Install
+<p align="center">
+  <img src=".github/assets/logo.svg" width="72" height="72" alt="harebear-ui logo" />
+</p>
+
+<h1 align="center">harebear-ui</h1>
+
+<p align="center">
+  Pre-themed React components for admin tools, data apps and AI chat.<br />
+  shadcn/ui restyled to one design system, plus the composites you build every time. Agent-ready out of the box.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/harebear-ui"><img src="https://img.shields.io/npm/v/harebear-ui?style=flat-square&color=5b84ff&labelColor=101012" alt="npm version" /></a>
+  <a href="https://github.com/HMilbradt/harebear-ui/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/HMilbradt/harebear-ui/ci.yml?branch=main&style=flat-square&labelColor=101012&label=CI" alt="CI status" /></a>
+  <img src="https://img.shields.io/badge/React-19-5b84ff?style=flat-square&labelColor=101012" alt="React 19" />
+  <img src="https://img.shields.io/badge/Tailwind_CSS-v4-a98ae0?style=flat-square&labelColor=101012" alt="Tailwind CSS v4" />
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/harebear-ui?style=flat-square&color=3cb8a8&labelColor=101012" alt="MIT license" /></a>
+</p>
+
+<p align="center">
+  <img src=".github/assets/hero.webp" alt="harebear-ui: an admin dashboard, an agent chat with approvals and a records table, all in dark mode" />
+</p>
+
+<p align="center">
+  <a href="docs/guides/getting-started.md"><b>Get started</b></a> ·
+  <a href="docs/COMPONENTS.md"><b>Components</b></a> ·
+  <a href="docs/guides/theming.md"><b>Theming</b></a> ·
+  <a href="docs/guides/agents.md"><b>AI agents</b></a> ·
+  <a href="playground/screens"><b>Reference screens</b></a>
+</p>
+
+## Why
+
+Every internal tool, dashboard and chat app ends up needing the same pieces: an app shell with a collapsible sidebar, KPI cards, a sortable table with a detail panel, trend charts, a chat thread with a composer and tool calls. shadcn/ui gives you primitives to build them. harebear-ui gives you them built, in one consistent look, so you (or your agent) spend the time on the product.
+
+- **Every shadcn/ui primitive**, same names and props, restyled to one set of tokens.
+- **Composites on top:** `AppShell`, `StatCard`, `DataTable`, `TrendChart`, `ChatShell`, `PromptInput`, `ToolStep`, `ApprovalCard`, `LoginForm` and more.
+- **Light and dark from one accent.** Change the brand color, radius and font with props or CSS variables.
+- **Docs agents can use.** `npx harebear-ui init` installs project rules and a Claude Code skill; `npx harebear-ui docs DataTable` prints one component's API.
+
+## Screens
+
+Built only from public exports. Each one is a file in [`playground/screens/`](playground/screens) you can copy from.
+
+<table>
+  <tr>
+    <td width="50%"><a href="playground/screens/admin.tsx"><img src=".github/assets/screens/admin-dark.webp" alt="Admin dashboard with KPI cards, a visitors trend chart and traffic sources" /></a><br /><b>Admin dashboard</b>: <code>AppShell</code>, <code>StatCard</code>, <code>TrendChart</code>, <code>BarList</code></td>
+    <td width="50%"><a href="playground/screens/agent.tsx"><img src=".github/assets/screens/agent-dark.webp" alt="Agent chat waiting on a command approval, with a details panel" /></a><br /><b>Agent with approvals</b>: <code>ChatShell</code>, <code>ToolGroup</code>, <code>ApprovalCard</code></td>
+  </tr>
+  <tr>
+    <td width="50%"><a href="playground/screens/chat.tsx"><img src=".github/assets/screens/chat-dark.webp" alt="AI chat with a conversation list, highlighted code and a prompt composer" /></a><br /><b>AI chat</b>: <code>ChatPanel</code>, <code>ChatMessage</code>, <code>CodeSnippet</code>, <code>PromptInput</code></td>
+    <td width="50%"><a href="playground/screens/records.tsx"><img src=".github/assets/screens/records-dark.webp" alt="Customer table with status badges and a detail panel for the selected row" /></a><br /><b>Records</b>: <code>DataTable</code>, <code>KeyValueGrid</code>, <code>Timeline</code></td>
+  </tr>
+  <tr>
+    <td width="50%"><a href="playground/screens/home.tsx"><img src=".github/assets/screens/home-dark.webp" alt="Status home page with service tiles and uptime bars" /></a><br /><b>Status home</b>: <code>LinkTile</code>, <code>StatusBars</code>, <code>Sparkline</code></td>
+    <td width="50%"><a href="playground/screens/auth.tsx"><img src=".github/assets/screens/auth-dark.webp" alt="Sign-in page" /></a><br /><b>Auth</b>: <code>AuthLayout</code>, <code>LoginForm</code>, <code>SignupForm</code></td>
+  </tr>
+</table>
+
+## Quick start
+
+Needs React 19 and Tailwind CSS v4.
 
 ```bash
 npm i harebear-ui
-```
-
-```bash
 npx harebear-ui init
 ```
 
-`init` adds the stylesheet import to your Tailwind entry CSS, writes a harebear-ui section into `AGENTS.md` (or `CLAUDE.md`), and installs a Claude Code skill in `.claude/skills/`. Flags: `--css <file>`, `--no-agents`, `--no-skill`.
-
-Manual setup, if you prefer:
-
-```css
-/* app.css */
-@import "tailwindcss";
-@import "harebear-ui/styles.css";
-```
+`init` adds the stylesheet import after `@import "tailwindcss"`, writes a harebear-ui section into `AGENTS.md` (or `CLAUDE.md`), and installs a Claude Code skill. Then wrap your root:
 
 ```tsx
 import { ThemeProvider, Toaster, TooltipProvider } from "harebear-ui"
@@ -39,24 +83,26 @@ export function Root() {
 }
 ```
 
-Requires Tailwind CSS v4 in the app. Geist and Geist Mono are bundled.
-
-## Use
+And build:
 
 ```tsx
-import { AppShell, PageHeader, StatCard, Button, DataTable } from "harebear-ui"
+import { AppShell, Button, DataTable, PageHeader, StatCard } from "harebear-ui"
 ```
 
-Everything imports from the package root. Primitives keep shadcn/ui names and props.
+Everything imports from the package root. Geist and Geist Mono are bundled.
 
-- **Component catalog:** [docs/COMPONENTS.md](docs/COMPONENTS.md), also at `node_modules/harebear-ui/docs/COMPONENTS.md` or `npx harebear-ui docs`.
-- **Reference screens:** [playground/screens](playground/screens) has an admin dashboard, an AI chat, a data table with detail panel, and a status home page built only from public exports.
+Step-by-step setup for **Vite**, **Next.js** and **React Router**, plus troubleshooting: [Getting started](docs/guides/getting-started.md).
 
 ## Theming
 
-Light and dark mode, accent, radius, and font are runtime props on `ThemeProvider` (`useTheme()` changes them live). Every component reads shadcn-named tokens, so you can override any of them in CSS:
+<img src=".github/assets/light-dark.webp" alt="The same admin dashboard split diagonally between light and dark mode" />
+
+Light, dark and system modes, accent, radius and font are `ThemeProvider` props, changeable live with `useTheme()`. Every component reads shadcn-named tokens, so you can override any of them in CSS:
 
 ```css
+@import "tailwindcss";
+@import "harebear-ui/styles.css";
+
 :root {
   --brand: #0f8a7e;
   --radius: 0.625rem;
@@ -66,19 +112,42 @@ Light and dark mode, accent, radius, and font are runtime props on `ThemeProvide
 }
 ```
 
-For SSR apps, render `<ThemeScript />` in `<head>` to avoid a flash of the wrong mode.
+SSR apps render `<ThemeScript />` in `<head>` to avoid a flash of the wrong mode. More in [Theming](docs/guides/theming.md).
 
-## For AI agents
+## Built for AI agents
 
-The package ships its own agent docs:
+<img src=".github/assets/agents.webp" alt="Terminal running harebear-ui init and docs, with the four agent files it sets up" />
 
-| File                          | For                                                    |
-| ----------------------------- | ------------------------------------------------------ |
-| `llms.txt`                    | Short index: setup, rules, component list.             |
-| `docs/COMPONENTS.md`          | Every export with props and examples.                  |
-| `skills/harebear-ui/SKILL.md` | Claude Code skill; `npx harebear-ui init` installs it. |
+The package carries its own agent docs, so Claude Code, Codex, Cursor and friends know what exists and how to use it:
 
-Working on this repo with an agent: see [AGENTS.md](AGENTS.md).
+| File                          | For                                                                   |
+| ----------------------------- | --------------------------------------------------------------------- |
+| `llms.txt`                    | Short index: setup, rules, every export by group.                     |
+| `docs/COMPONENTS.md`          | Every export with props and examples. Test-enforced to stay complete. |
+| `docs/guides/`                | Setup per framework, theming, working with agents.                    |
+| `skills/harebear-ui/SKILL.md` | Claude Code skill; `npx harebear-ui init` installs it.                |
+
+Agents look up one component at a time instead of reading the whole catalog:
+
+```bash
+npx harebear-ui docs DataTable StatCard   # exports
+npx harebear-ui docs Prompt               # prefix: PromptInput, PromptInputChip, PromptInputSelect
+npx harebear-ui docs Tokens               # a section
+```
+
+Prompts that work, and what to check before you accept an agent's UI: [Working with AI agents](docs/guides/agents.md).
+
+## What's inside
+
+| Group         | Exports                                                                                                                     |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| Layout, admin | `SidebarLayout`, `AppShell`, `PageHeader`, `StatCard`, `StatusBadge`, `UsageMeter`, `Timeline`, `UserMenu`, `ConfirmDialog` |
+| Data          | `DataTable`, `TrendChart`, `BarList`, `Sparkline`, `StatusBars`                                                             |
+| AI and chat   | `ChatShell`, `ChatPanel`, `ChatMessage`, `PromptInput`, `ModelPicker`, `ToolGroup`, `ApprovalCard`, `CodeSnippet`, `Prose`  |
+| Auth          | `AuthLayout`, `LoginForm`, `SignupForm`                                                                                     |
+| Primitives    | The full shadcn/ui registry: `Button`, `Dialog`, `Select`, `Sidebar`, `Tabs`, `Command`, `Chart`, and the rest              |
+
+The full list with props: [docs/COMPONENTS.md](docs/COMPONENTS.md).
 
 ## Develop
 
@@ -86,8 +155,11 @@ Working on this repo with an agent: see [AGENTS.md](AGENTS.md).
 pnpm install
 pnpm dev     # playground on :5199
 pnpm check   # lint, typecheck, test, build, package lint
+pnpm shots   # regenerate the README images (needs pnpm dev running, Chrome and cwebp)
 ```
 
+Working on this repo with an agent: see [AGENTS.md](AGENTS.md).
+
 ## License
 
 MIT

package/bin/harebear-ui.mjs

@@ -24,6 +24,7 @@ const AGENT_BLOCK = `${START}
 All UI in this project uses the \`harebear-ui\` component library (pre-themed shadcn/ui on Tailwind v4, plus admin, data table, chart, and AI chat components).
 
 - Read \`node_modules/harebear-ui/docs/COMPONENTS.md\` before building UI. It lists every component with props and examples.
+- Look up single entries with \`npx harebear-ui docs DataTable PromptInput\` (export names, a prefix, or a section such as \`Tokens\`).
 - Import from the package root: \`import { Button, Card, DataTable } from "harebear-ui"\`.
 - Style only with theme tokens (\`bg-card\`, \`bg-muted\`, \`text-muted-foreground\`, \`bg-primary-soft\`, \`text-success\`, \`shadow-card\`, \`rounded-xl\`). No hex or Tailwind palette colors.
 - Check new screens in light and dark mode and at phone width.
@@ -86,6 +87,50 @@ function installSkill() {
   console.log(`✓ Installed Claude Code skill to ${relative(cwd, destDir)}/SKILL.md`)
 }
 
+// Backticked identifiers in a heading or table cell: "`ChatMessage`" -> "chatmessage".
+const namesIn = (text) => [...text.matchAll(/`([A-Za-z]\w*)/g)].map((m) => m[1].toLowerCase())
+
+// The parts of the catalog about one export or section: "### `Name`" sections, primitive table rows
+// (with their table header), or a whole "## Section" by title. Exact names first, then prefix matches.
+function lookup(catalog, query) {
+  const q = query.toLowerCase()
+  const blocks = catalog.split(/^(?=#{2,3} )/m)
+  const section = blocks.find((b) => b.startsWith("## ") && b.split("\n", 1)[0].slice(3).toLowerCase() === q)
+  if (section) {
+    // A "## Section" block stops at its first "###"; take the subsections that follow it too.
+    const start = blocks.indexOf(section)
+    const end = blocks.findIndex((b, i) => i > start && b.startsWith("## "))
+    return blocks
+      .slice(start, end < 0 ? undefined : end)
+      .join("")
+      .trimEnd()
+  }
+  for (const match of [(n) => n === q, (n) => n.startsWith(q)]) {
+    const out = blocks.filter((b) => b.startsWith("### ") && namesIn(b.split("\n", 1)[0]).some(match))
+    let header = []
+    let headerShown = null
+    const rows = []
+    for (const line of catalog.split("\n")) {
+      if (!line.startsWith("|")) {
+        header = []
+        continue
+      }
+      if (header.length < 2) {
+        header.push(line)
+        continue
+      }
+      const [, first = "", second = ""] = line.split("|")
+      if (!namesIn(first + second).some(match)) continue
+      if (headerShown !== header) rows.push(...header)
+      headerShown = header
+      rows.push(line)
+    }
+    if (rows.length) out.push(rows.join("\n"))
+    if (out.length) return out.map((b) => b.trimEnd()).join("\n\n")
+  }
+  return undefined
+}
+
 switch (cmd) {
   case "init": {
     if (!existsSync(join(cwd, "package.json"))) {
@@ -109,9 +154,25 @@ Next: wrap your app root.
 `)
     break
   }
-  case "docs":
-    process.stdout.write(readFileSync(join(pkgRoot, "docs/COMPONENTS.md"), "utf8"))
+  case "docs": {
+    const catalog = readFileSync(join(pkgRoot, "docs/COMPONENTS.md"), "utf8")
+    const queries = args.filter((a) => !a.startsWith("--"))
+    if (queries.length === 0) {
+      process.stdout.write(catalog)
+      break
+    }
+    let missed = false
+    for (const q of queries) {
+      const found = lookup(catalog, q)
+      if (found) process.stdout.write(`${found}\n\n`)
+      else {
+        missed = true
+        console.error(`! Nothing in the catalog for "${q}". Run \`npx harebear-ui docs\` for the full catalog.`)
+      }
+    }
+    if (missed) process.exitCode = 1
     break
+  }
   default:
     console.log(`harebear-ui
 
@@ -119,7 +180,9 @@ Next: wrap your app root.
       Add the stylesheet import after @import "tailwindcss", add a harebear-ui
       section to AGENTS.md (or CLAUDE.md), and install the Claude Code skill.
 
-  npx harebear-ui docs
+  npx harebear-ui docs [name...]
       Print the component catalog (props and examples for every export).
+      With names, print only those entries: an export (DataTable, Button),
+      a name prefix (Prompt), or a section title (Tokens, Auth).
 `)
 }

package/dist/components/layout/media-item.d.ts

@@ -0,0 +1,13 @@
+import * as React from "react";
+export interface MediaItemProps extends Omit<React.ComponentProps<"div">, "title"> {
+  title: React.ReactNode;
+  /** Opens in a new tab. */
+  href?: string;
+  image?: string;
+  imageShape?: "poster" | "square" | "wide";
+  meta?: React.ReactNode;
+  description?: React.ReactNode;
+}
+/** Thumbnail, title, a meta line and a two-line description. For media, articles, releases. */
+declare function MediaItem({ title, href, image, imageShape, meta, description, className, ...props }: MediaItemProps): React.JSX.Element;
+export { MediaItem };

package/dist/components/layout/media-item.js

@@ -0,0 +1,54 @@
+"use client";
+import { cn } from "../../lib/utils.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+// src/components/layout/media-item.tsx
+const shapeClass = {
+	poster: "aspect-[2/3] w-14",
+	square: "aspect-square w-12",
+	wide: "aspect-video w-24"
+};
+/** Thumbnail, title, a meta line and a two-line description. For media, articles, releases. */
+function MediaItem({ title, href, image, imageShape = "poster", meta, description, className, ...props }) {
+	const img = image ? /* @__PURE__ */ jsx("img", {
+		src: image,
+		alt: "",
+		loading: "lazy",
+		className: cn("shrink-0 rounded-md bg-muted object-cover", shapeClass[imageShape])
+	}) : null;
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "media-item",
+		className: cn("flex min-w-0 items-start gap-3", className),
+		...props,
+		children: [img && href ? /* @__PURE__ */ jsx("a", {
+			href,
+			target: "_blank",
+			rel: "noreferrer",
+			tabIndex: -1,
+			className: "shrink-0",
+			children: img
+		}) : img, /* @__PURE__ */ jsxs("div", {
+			className: "flex min-w-0 flex-col gap-0.5",
+			children: [
+				/* @__PURE__ */ jsx("span", {
+					className: "line-clamp-2 font-medium",
+					children: href ? /* @__PURE__ */ jsx("a", {
+						href,
+						target: "_blank",
+						rel: "noreferrer",
+						className: "outline-none hover:underline focus-visible:underline",
+						children: title
+					}) : title
+				}),
+				meta && /* @__PURE__ */ jsx("span", {
+					className: "text-xs text-muted-foreground",
+					children: meta
+				}),
+				description && /* @__PURE__ */ jsx("span", {
+					className: "line-clamp-2 text-[13px] text-muted-foreground",
+					children: description
+				})
+			]
+		})]
+	});
+}
+export { MediaItem };

package/dist/components/layout/metric.d.ts

@@ -0,0 +1,15 @@
+import * as React from "react";
+export interface MetricProps extends Omit<React.ComponentProps<"div">, "children"> {
+  label: React.ReactNode;
+  value: React.ReactNode;
+  unit?: React.ReactNode;
+  /** Percent change. Positive reads as good unless `lowerIsBetter`. */
+  delta?: number;
+  lowerIsBetter?: boolean;
+  align?: "start" | "center";
+}
+/** A number with a unit, a label under it, and an optional percent change over it. */
+declare function Metric({ label, value, unit, delta, lowerIsBetter, align, className, ...props }: MetricProps): React.JSX.Element;
+/** Metrics side by side, evenly spaced. */
+declare function MetricGroup({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+export { Metric, MetricGroup };

package/dist/components/layout/metric.js

@@ -0,0 +1,51 @@
+"use client";
+import { cn } from "../../lib/utils.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { ArrowDownRightIcon, ArrowUpRightIcon } from "lucide-react";
+// src/components/layout/metric.tsx
+/** A number with a unit, a label under it, and an optional percent change over it. */
+function Metric({ label, value, unit, delta, lowerIsBetter, align = "center", className, ...props }) {
+	const good = delta === void 0 || delta === 0 ? void 0 : lowerIsBetter ? delta < 0 : delta > 0;
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "metric",
+		className: cn("flex min-w-0 flex-col gap-0.5", align === "center" ? "items-center text-center" : "items-start", className),
+		...props,
+		children: [
+			delta !== void 0 && Number.isFinite(delta) && /* @__PURE__ */ jsxs("span", {
+				className: cn("inline-flex items-center gap-0.5 text-xs font-medium tabular-nums", good === void 0 ? "text-muted-foreground" : good ? "text-success" : "text-destructive"),
+				children: [
+					delta > 0 ? "+" : "",
+					delta.toFixed(1),
+					"%",
+					delta > 0 ? /* @__PURE__ */ jsx(ArrowUpRightIcon, {
+						"aria-hidden": true,
+						className: "size-3.5"
+					}) : delta < 0 ? /* @__PURE__ */ jsx(ArrowDownRightIcon, {
+						"aria-hidden": true,
+						className: "size-3.5"
+					}) : null
+				]
+			}),
+			/* @__PURE__ */ jsxs("span", {
+				className: "text-xl font-semibold tracking-tight whitespace-nowrap tabular-nums @sm:text-2xl",
+				children: [value, unit && /* @__PURE__ */ jsx("span", {
+					className: "ml-0.5 text-xs font-medium text-muted-foreground",
+					children: unit
+				})]
+			}),
+			/* @__PURE__ */ jsx("span", {
+				className: "text-xs font-medium tracking-wide text-muted-foreground uppercase",
+				children: label
+			})
+		]
+	});
+}
+/** Metrics side by side, evenly spaced. */
+function MetricGroup({ className, ...props }) {
+	return /* @__PURE__ */ jsx("div", {
+		"data-slot": "metric-group",
+		className: cn("grid auto-cols-fr grid-flow-col gap-2", className),
+		...props
+	});
+}
+export { Metric, MetricGroup };

package/dist/components/layout/show-more.d.ts

@@ -0,0 +1,17 @@
+import * as React from "react";
+declare const gapClass: {
+  readonly none: "gap-0";
+  readonly xs: "gap-1";
+  readonly sm: "gap-2";
+  readonly md: "gap-3";
+  readonly lg: "gap-4";
+  readonly xl: "gap-6";
+};
+export interface ShowMoreProps extends React.ComponentProps<"div"> {
+  /** Children shown before the "Show N more" button. Default 5. */
+  initial?: number;
+  gap?: keyof typeof gapClass;
+}
+/** A list that collapses after `initial` children, with a button to show the rest. */
+declare function ShowMore({ initial, gap, className, children, ...props }: ShowMoreProps): React.JSX.Element;
+export { ShowMore };

package/dist/components/layout/show-more.js

@@ -0,0 +1,30 @@
+"use client";
+import { cn } from "../../lib/utils.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+// src/components/layout/show-more.tsx
+const gapClass = {
+	none: "gap-0",
+	xs: "gap-1",
+	sm: "gap-2",
+	md: "gap-3",
+	lg: "gap-4",
+	xl: "gap-6"
+};
+/** A list that collapses after `initial` children, with a button to show the rest. */
+function ShowMore({ initial = 5, gap = "md", className, children, ...props }) {
+	const [open, setOpen] = React.useState(false);
+	const all = React.Children.toArray(children);
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "show-more",
+		className: cn("flex min-w-0 flex-col", gapClass[gap], className),
+		...props,
+		children: [open ? all : all.slice(0, initial), all.length > initial && /* @__PURE__ */ jsx("button", {
+			type: "button",
+			onClick: () => setOpen(!open),
+			className: "self-start rounded-md text-xs font-medium text-muted-foreground outline-none hover:text-foreground focus-visible:ring-4 focus-visible:ring-ring/20",
+			children: open ? "Show less" : `Show ${all.length - initial} more`
+		})]
+	});
+}
+export { ShowMore };

package/dist/components/layout/stack.d.ts

@@ -0,0 +1,39 @@
+import * as React from "react";
+export type StackSpace = "none" | "xs" | "sm" | "md" | "lg" | "xl";
+export type StackAlign = "start" | "center" | "end" | "stretch" | "baseline";
+export type StackJustify = "start" | "center" | "end" | "between";
+export interface StackProps extends React.ComponentProps<"div"> {
+  gap?: StackSpace;
+  align?: StackAlign;
+}
+/** Vertical stack with a named gap. */
+declare function Stack({ gap, align, className, ...props }: StackProps): React.JSX.Element;
+export interface RowProps extends React.ComponentProps<"div"> {
+  gap?: StackSpace;
+  align?: StackAlign;
+  justify?: StackJustify;
+  wrap?: boolean;
+}
+/** Horizontal row with a named gap. */
+declare function Row({ gap, align, justify, wrap, className, ...props }: RowProps): React.JSX.Element;
+export type GridCols = 1 | 2 | 3 | 4 | 5 | 6;
+export type ResponsiveGridCols = GridCols | {
+  base?: GridCols;
+  sm?: GridCols;
+  md?: GridCols;
+  lg?: GridCols;
+};
+export interface GridProps extends React.ComponentProps<"div"> {
+  /** Equal columns: a number, or per breakpoint `{ base: 1, sm: 2, md: 3 }`. */
+  cols?: ResponsiveGridCols;
+  gap?: StackSpace;
+  /**
+   * What sm/md/lg measure. "viewport" (default): the screen, Tailwind's sm/md/lg.
+   * "container": the nearest `@container` ancestor (sm >= 28rem, md >= 42rem, lg >= 56rem),
+   * for blocks that sit in cards of any width.
+   */
+  query?: "viewport" | "container";
+}
+/** Grid of equal columns with named gaps and per-breakpoint column counts. */
+declare function Grid({ cols: c, gap, query, className, ...props }: GridProps): React.JSX.Element;
+export { Grid, Row, Stack };