@spunto/design-system 0.9.3 → 0.11.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,7 +89,7 @@ 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`
+## Domain components — `/workers`, `/devcontainer`, `/projects`
 
 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
@@ -82,10 +98,14 @@ of a worker. **The rule for what comes next: any new component that knows a doma
 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
+import { Button, Card } from "@spunto/design-system"                                        // primitives
+import { WorkerCard } from "@spunto/design-system/workers"                                  // domain
+import { ImageCard, FeatureCard, ExtensionCard } from "@spunto/design-system/devcontainer"  // domain
+import { ProjectForm } from "@spunto/design-system/projects"                                // domain
 ```
 
+### `@spunto/design-system/workers`
+
 - **`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:
@@ -103,6 +123,84 @@ import { WorkerCard } from "@spunto/design-system/workers"  // domain
   minimum, everything optional but `id`, and an unknown state falls back to
   `pending` instead of throwing.
 
+### `@spunto/design-system/devcontainer`
+
+The three catalogs you compose an environment from. They exist identically in the
+dashboard and in Spunto Lite, and were hand-drawn as raw `<button>`/`<li>` on both
+sides — exactly the duplication this package is for.
+
+- **`ImageCard`** — a devcontainer base image: runtime mark, label, publisher +
+  avatar, image reference in mono, description.
+- **`FeatureCard`** — a devcontainer feature: the author's avatar (the GitHub org
+  behind the `ghcr.io` ref), label, description, option chips (`version=lts`…),
+  OCI reference.
+- **`ImageTile` / `FeatureTile`** (+ the shared `CatalogTile`) — the same entries
+  at chip size: a mark, a name, one trailing detail. What a catalog needs past a
+  dozen entries, where picking is a *logo* task and full cards become a wall.
+  They flow and wrap like tags; the pickers pair them with the full card of
+  what's selected.
+- **`ExtensionCard`** (+ `ExtensionCardSkeleton`) — a VS Code extension: its real
+  Open VSX icon, display name, publisher + verified badge, version, formatted
+  install count, rating.
+
+All three share one selectable state (flame check + ring), one **compact
+read-only** variant for the project sheet, and one **`custom`** variant for a
+hand-typed reference that degrades cleanly.
+
+- **Nothing here fetches anything.** `onSelect` is a callback, the option row
+  (`optionsSlot`) and the trailing control (`action`) are slots. The author and
+  the logo are **derived from the reference** by pure functions, because the
+  catalogs carry neither: `parseRegistryRef`, `derivePublisher`
+  (`ghcr.io/<owner>/…` → that GitHub org, avatar included via
+  `github.com/<owner>.png`; `mcr.microsoft.com/devcontainers/…` → Dev Containers)
+  and `resolveStackMark`. `publisher` / `mark` / `iconUrl` are the overrides for
+  the day the API knows better — no component change needed then.
+- **Brand marks ship with the package** as single-path SVGs drawn with
+  `currentColor` (`StackMark`, `STACK_MARK_PATHS`): no third-party CDN, and each
+  logo inherits the warm accent of its card instead of dragging 20 clashing brand
+  palettes into one grid.
+- **Its bricks, exported individually**: `CatalogCard` (the selectable shell),
+  `CatalogMark` (the icon → brand → avatar → monogram cascade), `CatalogChip`,
+  `PublisherBadge`/`PublisherAvatar`, `RegistryRef` (mono + copy button), plus the
+  pure helpers `parseRegistryRef`, `derivePublisher`, `githubAvatarUrl`,
+  `resolveStackMark`, `resolveFeatureOptions`, `formatCount`, `parseExtensionId`.
+- **Types are structural** here too: `DevcontainerImageEntry`,
+  `DevcontainerFeatureEntry` and `VscodeExtensionEntry` are all-optional, and an
+  unknown registry degrades to a monogram instead of an invented author.
+
+### `@spunto/design-system/projects`
+
+- **`ProjectForm`** — the whole "compose a dev environment" screen: identity,
+  base image, repos, features, extensions, lifecycle, ports, prewarm images,
+  docker-in-docker, secrets, plus the live **build manifest** that recaps it and
+  carries the submit button.
+- **Controlled by one value.** A single `ProjectFormValue` in, one `onChange`
+  out, `onSubmit(value)` at the end. Start from `emptyProjectFormValue()`, or
+  `toProjectFormValue(partial)` to fill the gaps of an existing project. The
+  value is *always* readable — which is what makes validation, drafts and
+  previews possible at all.
+- **Which sections show is a prop** (`CREATE_SECTIONS` / `EDIT_SECTIONS` / your
+  own list, in your own order). Creation and editing are the same component with
+  a different list, not two screens that drift apart.
+- **Everything past identity / base image / repos folds under "Advanced
+  options"** (`advancedSections`, `[]` to disable). Two rules keep that honest:
+  the closed fold *writes out what it holds* ("2 features · lifecycle · 3
+  secrets") instead of showing a bare chevron, and the form opens it by itself
+  when any of those sections already has a value — so editing a project never
+  hides a setting you made earlier.
+- **Nothing fetches.** Catalogs come in as data, the marketplace search is
+  `onSearchExtensions`, the GitHub combobox is `renderRepoField` (without it: a
+  plain `<input list>` + `<datalist>`, no dependency, keyboard-friendly), and
+  `extras` slips app-specific content *inside* a section — the deploy key card,
+  a warning — without forking the component.
+- **Its bricks, exported individually**: `FormSection`, `Field`,
+  `BuildManifest`, `RepoList` (+`deriveFromGitUrl`), `SecretList`,
+  `ImagePicker`/`FeaturePicker`/`ExtensionPicker`, and the pure `manifestRows`.
+- **Responsive by container query, not viewport.** The form is a full page in
+  one app and a 700 px panel in another; it reads its own width to decide
+  whether the manifest sits beside it and whether the catalogs are one column or
+  two.
+
 ## Toasts — `SpuntoProvider` + `toast()`
 
 `SpuntoProvider` is the design system's client umbrella provider. Mount it once

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/design-system",
-  "version": "0.9.3",
+  "version": "0.11.0",
   "description": "Spunto's shared design system — warm/flame tokens, color constants, and UI primitives.",
   "type": "module",
   "license": "MIT",
@@ -37,6 +37,14 @@
       "types": "./src/components/workers/index.ts",
       "import": "./src/components/workers/index.ts"
     },
+    "./devcontainer": {
+      "types": "./src/components/devcontainer/index.ts",
+      "import": "./src/components/devcontainer/index.ts"
+    },
+    "./projects": {
+      "types": "./src/components/projects/index.ts",
+      "import": "./src/components/projects/index.ts"
+    },
     "./fonts": {
       "types": "./src/components/fonts.tsx",
       "import": "./src/components/fonts.tsx"