@spunto/design-system 0.15.1 → 0.17.0

package/README.md

@@ -46,6 +46,9 @@ const nextConfig = { transpilePackages: ["@spunto/design-system"] }
   → Tailwind color/radius mapping, a minimal base layer, and the `dot-grid` /
   `grid-lines` background utilities. Brand color is **flame** (`--primary` ≈ `#ea5400`);
   radius base is `0.25rem`; `Build`/`Ship`/`Run` are semantic (`bg-build`, `text-run`…).
+  Plus the two **unthemed** marketing surfaces — `--night` (`bg-night`) and
+  `--code-surface` (`bg-code-surface`) — and the `night-grid` / `night-glow-a`
+  / `night-glow-b` / `night-scroll` utilities they come with.
 - **`cn`** — `clsx` + `tailwind-merge`.
 - **`./colors`** — `cssVar`, `chartColors`, `chartRamp`, `segColors` for JS/chart contexts.
 - **Primitives** — form + layout building blocks styled on `@base-ui/react`:
@@ -60,9 +63,20 @@ const nextConfig = { transpilePackages: ["@spunto/design-system"] }
     `Alert` (+`AlertTitle`/`AlertDescription`, +`alertVariants`) — an **inline, persistent,
     declarative** status banner, the counterpart to the ephemeral imperative `toast()`.
   - _Overlays_ (plug into the `SpuntoProvider` umbrella) — `Dialog`, `AlertDialog`
-    (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.
+    (a confirmation variant, non-dismissible), `Sheet`, `Tooltip`. Their portals render
+    into the provider's overlay container; `Tooltip`'s shared delay group is mounted by
+    the provider too.
+  - _Sheet_ — `Sheet` (+`SheetTrigger`/`SheetClose`/`SheetContent`/`SheetHeader`/
+    `SheetFooter`/`SheetTitle`/`SheetDescription`), the same Base UI dialog entering from
+    an edge. `side` (4) decides the edge, `size` (`sm`…`full`) how far it comes in — two
+    props rather than one bundle of `data-[side=right]:`-prefixed classes, precisely so
+    `className` stays the layout escape hatch (an app widens a panel or lays it out in two
+    columns without `!important`).
+  - _Table_ — `Table` (+`TableHeader`/`TableBody`/`TableFooter`/`TableRow`/`TableHead`/
+    `TableCell`/`TableCaption`). **Presentational only**: no sorting, no pagination, no
+    column model — apps already own that logic and disagree on it; what they were
+    duplicating is the markup and the token choices. `containerClassName` reaches the
+    scroll container (max-height, border, sticky-header context).
   - _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
@@ -77,6 +91,17 @@ const nextConfig = { transpilePackages: ["@spunto/design-system"] }
     `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.
+  - _CommandMenu_ — `CommandMenu` (+`CommandMenuInput`/`List`/`Group`/`Item`/`Empty`/
+    `Loading`/`Separator`), the palette's vocabulary **inline**: a Base UI `Popover`
+    anchored to an element or a **virtual element** (a caret rect), which never moves
+    focus (`initialFocus`/`finalFocus` off, no backdrop, non-modal) and claims ↑ ↓ ↵ Esc
+    on `document` in the **capture** phase, before the field underneath. That's what a
+    "/" menu inside a block editor needs and what the dialog-based palette can't do
+    without losing the caret — hence a separate component rather than a `modal={false}`
+    flag: the contract is the opposite one. Enter is only claimed when an item is
+    highlighted, so a query with no result still inserts a line break. The query either
+    comes from the caller (`query`, the "/" case) or from a `CommandMenuInput` rendered
+    inside the popup (a filter dropdown on a button; `autoFocus` is opt-in).
   - _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`
@@ -112,11 +137,16 @@ import { Button, Card } from "@spunto/design-system"
 import { WorkerCard } from "@spunto/design-system/workers"                                  // domain
 import { ImageCard, FeatureCard, ExtensionCard } from "@spunto/design-system/devcontainer"  // domain
 import { ProjectForm, ProjectPanel } from "@spunto/design-system/projects"                   // domain
+import { Section, ProductHeader } from "@spunto/design-system/marketing"                     // not a domain — see below
 ```
 
 One entry **per domain**, not per component: a project's form and a project's
 panel are the same concept seen twice, so they share `/projects`.
 
+`/marketing` is the exception that proves the rule: it knows no Spunto concept
+(that's exactly why the product registry stayed in the site), but it carries
+opinions a dashboard doesn't want, so it gets an entry too.
+
 ### `@spunto/design-system/workers`
 
 - **`WorkerCard`** — a Spunto worker as a card: state, author, node, setup
@@ -264,6 +294,72 @@ And the read-only twin of that form:
 - **Container queries** here too: the panel is 288 px in a sidebar on a 27" screen
   and full width on a phone — and the desktop case is the narrow one.
 
+## Marketing — `/marketing`
+
+```tsx
+import { Section, H2, Kicker, SpecList, Disclosure, CodeBlock, Figure,
+         CopyCommand, NightBand, NightChip, ProductHeader, Reveal,
+         usePrefersReducedMotion, useLoopClock } from "@spunto/design-system/marketing"
+```
+
+The vocabulary of a **marketing page** — a numbered chapter, a display headline,
+a mono kicker, key/value rows, a disclosure row, a copyable command, a night
+band. Its own entry rather than the root, for two reasons: an app that draws a
+dashboard has no use for it, and these primitives carry opinions the root
+deliberately doesn't (a display face, a fixed dark surface).
+
+- **`Section`** — the chapter: hairline, number in the accent, mono title,
+  margin `note`, then the content. Repeating one opening down a page is what
+  makes it read as a document rather than a stack of blocks.
+- **`H2`** / **`Kicker`** — the display headline (Syne, capped at 24ch) and the
+  mono line above it. **One `Kicker`, not two**: the site had `Kicker` and
+  `Eyebrow` doing the same job under two names and two letter-spacings; the wider
+  one is now a `className`.
+- **`SpecList`** — key/value rows, the default way to list facts without bullets.
+- **`Disclosure`** — the row you open. `<details name>` gives the exclusive
+  accordion natively: no state, no hydration surface, and it works before the JS
+  lands.
+- **`CodeBlock`** / **`Figure`** — a snippet on the `--code-surface` token
+  (deliberately unhighlighted: a highlighter is a dependency and ~30 kB for a
+  six-line snippet), and a framed, captioned screenshot whose **image element is
+  a slot** (`render.image`) — same rule as links, the package never imports
+  `next/image`.
+- **`CopyCommand`** — the call to action when it's a command. **One component,
+  two registers** (`tone="day" | "night"`), where the site had `CopyCommand` and
+  `NightCommand`: same behaviour, two files, two places to fix a bug. What lands
+  in the clipboard is the joined-up one-liner, not the wrapped version.
+- **`NightBand`** / **`NightChip`** — the dark band a page opens on, lit by its
+  `glow` accent. `--night` is *not themed*: it's the dark moment of the page, so
+  it stays deeper than the dark theme's own background and identical in both.
+  The drifting light sources are CSS animations (stopped by
+  `prefers-reduced-motion`), never a rAF loop.
+- **`ProductHeader`** — mark, name, kind, headline, promise, the one command, the
+  chips. **Generalised on the way in**: the site's version took a `Product` out
+  of its own registry, this one knows about no product at all — everything
+  product-specific goes through `actions`.
+- **`Reveal`** + **`usePrefersReducedMotion`** / **`useLoopClock`** — scroll
+  reveal as an `IntersectionObserver` and a CSS transition, and the "how far into
+  the loop are we" clock that pauses off screen and commits at ~14 Hz.
+
+Two rules the package enforces here:
+
+- **No framework imports.** No `next/link`, no `next/image`. Navigation is the
+  caller's (`actions` slots), and `Figure` takes an image `render` slot — the
+  same motif as `CommandPaletteLinkRender` and `WorkerCard`'s `render.link`.
+- **No motion library.** `framer-motion` as a hard dependency would weigh on
+  every consumer, including the ones that never draw a landing page. `Reveal` is
+  ~20 lines of observer + transition instead.
+
+`Section`, `H2`, `Kicker`, `SpecList`, `Disclosure`, `CodeBlock`, `Figure`,
+`NightBand`, `NightChip` and `ProductHeader` carry **no `"use client"`** — they
+render from a React Server Component. Only `CopyCommand`, `Reveal` and the hooks
+are client files. (Same split, same care, as `buttonVariants`/`alertVariants`.)
+
+**What stays in the site, on purpose:** the product registry and anything reading
+it, the navs and footers (they hard-code URLs and a session), the product logos
+and OG cards. The rule: *if it needs to know a product, a URL or a session, it's
+the site; if it only lays out or types, it's the system.*
+
 ## 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.15.1",
+  "version": "0.17.0",
   "description": "Spunto's shared design system — warm/flame tokens, color constants, and UI primitives.",
   "type": "module",
   "license": "MIT",
@@ -45,6 +45,10 @@
       "types": "./src/components/projects/index.ts",
       "import": "./src/components/projects/index.ts"
     },
+    "./marketing": {
+      "types": "./src/components/marketing/index.ts",
+      "import": "./src/components/marketing/index.ts"
+    },
     "./fonts": {
       "types": "./src/components/fonts.tsx",
       "import": "./src/components/fonts.tsx"