@spunto/design-system 0.9.2 → 0.10.0

package/README.md

@@ -40,7 +40,9 @@ const nextConfig = { transpilePackages: ["@spunto/design-system"] }
 - **`./colors`** — `cssVar`, `chartColors`, `chartRamp`, `segColors` for JS/chart contexts.
 - **Primitives** — form + layout building blocks styled on `@base-ui/react`:
   - _Basics_ — `Button` (+`buttonVariants`), `Card` (+parts), `Badge` (+`badgeVariants`),
-    `Separator`, `Spinner`, `Skeleton`, `Avatar` (+`AvatarImage`/`AvatarFallback`).
+    `Separator`, `Spinner`, `Skeleton`, `Avatar` (+`AvatarImage`/`AvatarFallback`),
+    `Kbd` — one keyboard cap, or a whole shortcut (`keys="mod+k"` → ⌘ K, Ctrl K off Apple),
+    spelled out for screen readers.
   - _Forms_ — `Input`, `Textarea`, `Label`, `Switch`, `Checkbox`,
     `RadioGroup` (+`RadioGroupItem`), `Select` (+`SelectTrigger`/`SelectValue`/
     `SelectContent`/`SelectItem`/`SelectGroup`/`SelectGroupLabel`/`SelectSeparator`).
@@ -51,6 +53,20 @@ const nextConfig = { transpilePackages: ["@spunto/design-system"] }
     (a confirmation variant, non-dismissible), `Tooltip`. Their portals render into
     the provider's overlay container; `Tooltip`'s shared delay group is mounted by the
     provider too.
+  - _CommandPalette_ — `CommandPalette` (+`CommandPaletteInput`/`List`/`Group`/`Item`/
+    `Empty`/`Loading`/`Separator`/`Footer`/`Trigger`), the ⌘K palette: an input, groups,
+    items, and a jump. **Domain-free**, hence its place in the root entry — it knows
+    nothing of projects, workers or deployments; those are items the app hands it. Base UI
+    `Autocomplete` (combobox/listbox roles, `aria-activedescendant`, ↑↓ + scroll-into-view,
+    ↵ activates the highlighted item) rendered *inline* inside a Base UI `Dialog` (focus
+    trap, focus restore, Escape, backdrop), portalled into the provider's overlay container
+    like the other overlays. Compositional like `Dialog`/`Select`, not a config array —
+    which is why the root runs Base UI in `mode="none"` and each item decides for itself
+    whether it matches, with the same `Autocomplete.useFilter()` collator. Presentational
+    only: `loading` is a prop, results are children, and a server-side search is
+    `value`/`onValueChange` + `filter={null}`. Navigation is `href` + `render.link`, never
+    `next/link` — same rule as `WorkerCard`. Not virtualized: a few hundred items stay
+    fluid (a non-matching item renders nothing), beyond that filter server-side.
   - _Terminal_ — `Terminal` (+`TerminalHandle`, `TerminalOptions`), a transport-agnostic
     xterm.js surface: mount, shared dark ANSI theme, fit-on-resize. No opinion on where
     bytes come from (WebSocket, SSE, a static string) — feed it via the `write`/`writeln`
@@ -73,6 +89,36 @@ const nextConfig = { transpilePackages: ["@spunto/design-system"] }
   provider is also the umbrella that mounts the tooltip delay group and the overlay
   portal container the dialogs/selects render into.
 
+## Domain components — `@spunto/design-system/workers`
+
+Everything above is domain-free: a `Button` knows nothing about Spunto. Components
+that **do** know a Spunto concept live behind their own entry point, so the root
+export stays primitives-only and a third-party consumer never carries the notion
+of a worker. **The rule for what comes next: any new component that knows a domain
+concept goes behind a domain sub-export, never in the root entry.**
+
+```tsx
+import { Button, Card } from "@spunto/design-system"        // primitives
+import { WorkerCard } from "@spunto/design-system/workers"  // domain
+```
+
+- **`WorkerCard`** — a Spunto worker as a card: state, author, node, setup
+  progress, git branches, resources, banners, actions. **Purely presentational** —
+  hand it a snapshot plus slots and it draws. The rule that keeps it that way:
+  *everything that CALLS the API is a slot or a callback; everything that DRAWS is
+  in the component.* So the `⋯` menu (`actions`), the footer (`footer`), the link
+  (`href` + `render.link`, never `next/link`), the rebuild (`onRebuild`) and the
+  tag persistence (`onAddTag`/`onRemoveTag`) all stay in the app.
+- **Its bricks, exported individually** because the table view assembles them
+  differently: `WorkerStatusDot`/`WorkerStatusPill` (+`resolveWorkerStatus`,
+  `workerStatusConfig`), `SetupProgress` (+`setupProgress`, `phaseLabel`,
+  `setupTotalMs`), `StepIndicator`, `ResourceBars`, `GitBranchChips`/
+  `GitStatusSummary`, `TagChips` (+`tagColor`), `CreatorAvatar`.
+- **Types are structural**, never the apps' OpenAPI types: the dashboard and
+  Spunto Lite model a worker differently, so `WorkerCardWorker` asks for the
+  minimum, everything optional but `id`, and an unknown state falls back to
+  `pending` instead of throwing.
+
 ## Toasts — `SpuntoProvider` + `toast()`
 
 `SpuntoProvider` is the design system's client umbrella provider. Mount it once
@@ -145,3 +191,7 @@ automatically (see `showcase/vite-plugin-llms.ts`).
 ## Peer requirements
 
 - React 19+, and a **Tailwind CSS v4** pipeline in the consuming app.
+- `lucide-react` is a **regular dependency** (since `0.9.3`): the worker
+  components use ~15 icons, and inlining them as SVG or passing them all as props
+  would have been worse than the dependency. It's tree-shakable and both apps
+  already ship it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/design-system",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "description": "Spunto's shared design system — warm/flame tokens, color constants, and UI primitives.",
   "type": "module",
   "license": "MIT",
@@ -33,6 +33,10 @@
       "types": "./src/colors.ts",
       "import": "./src/colors.ts"
     },
+    "./workers": {
+      "types": "./src/components/workers/index.ts",
+      "import": "./src/components/workers/index.ts"
+    },
     "./fonts": {
       "types": "./src/components/fonts.tsx",
       "import": "./src/components/fonts.tsx"
@@ -54,6 +58,7 @@
     "@xterm/xterm": "^6.0.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
+    "lucide-react": "^1.7.0",
     "tailwind-merge": "^3.6.0"
   },
   "peerDependencies": {