@spunto/design-system 0.15.1 → 0.17.0

package/src/components/command-palette.tsx

@@ -15,6 +15,7 @@ import { Dialog } from "@base-ui/react/dialog"
 import { SearchIcon } from "lucide-react"
 
 import { cn } from "../utils"
+import { highlightMatch, type CommandFilter, type CommandFilterItem } from "./command-shared"
 import { Kbd } from "./kbd"
 import { Skeleton } from "./skeleton"
 import { Spinner } from "./spinner"
@@ -41,17 +42,13 @@ import { useOverlayContainer } from "./spunto-provider"
 // already-filtered items in.
 // ---------------------------------------------------------------------------
 
-/** What the filter gets to look at for one item. */
-export interface CommandPaletteFilterItem {
-  /** `label` prop, or the item's children when they're a plain string. */
-  label: string
-  /** Extra terms that match but are never displayed. */
-  keywords: string[]
-  /** The item's `value`, when it has one. */
-  value?: string
-}
+/**
+ * What the filter gets to look at for one item. Shared with `CommandMenu` — the
+ * two components filter identically, only their shell differs.
+ */
+export type CommandPaletteFilterItem = CommandFilterItem
 
-export type CommandPaletteFilter = (item: CommandPaletteFilterItem, query: string) => boolean
+export type CommandPaletteFilter = CommandFilter
 
 interface PaletteContextValue {
   query: string
@@ -107,46 +104,6 @@ function comboMatches(event: KeyboardEvent, combo: Combo): boolean {
   return true
 }
 
-// --- match highlighting -----------------------------------------------------
-
-/**
- * Folds a string to a comparable form (lowercase, no diacritics) while keeping,
- * for every folded character, the index it came from — so a match found on the
- * folded text can be highlighted on the original one ("déploiement" matched by
- * "deploi" highlights the right six characters, accent included).
- */
-function fold(text: string): { folded: string; map: number[] } {
-  let folded = ""
-  const map: number[] = []
-  for (let i = 0; i < text.length; i++) {
-    const chunk = text[i].normalize("NFD").replace(/\p{Diacritic}/gu, "").toLowerCase()
-    for (const char of chunk) {
-      folded += char
-      map.push(i)
-    }
-  }
-  return { folded, map }
-}
-
-/** Wraps the matched slice of `text` in a `<mark>`. Returns the plain text when there's no match. */
-function highlightMatch(text: string, query: string): ReactNode {
-  if (!query.trim()) return text
-  const haystack = fold(text)
-  const needle = fold(query.trim()).folded
-  if (!needle) return text
-  const at = haystack.folded.indexOf(needle)
-  if (at === -1) return text
-  const start = haystack.map[at]
-  const end = haystack.map[at + needle.length - 1] + 1
-  return (
-    <>
-      {text.slice(0, start)}
-      <mark className="rounded-xs bg-primary/15 text-inherit">{text.slice(start, end)}</mark>
-      {text.slice(end)}
-    </>
-  )
-}
-
 // --- root -------------------------------------------------------------------
 
 export interface CommandPaletteProps {

package/src/components/command-shared.tsx

@@ -0,0 +1,59 @@
+import type { ReactNode } from "react"
+
+// ---------------------------------------------------------------------------
+// What `CommandPalette` (modal, ⌘K) and `CommandMenu` (inline, anchored) share:
+// how an item describes itself to the filter, and how a match is highlighted.
+// The two components differ in their shell — a focus-trapping Dialog vs. a
+// Popover that never takes focus — not in what "matching" means, so a filter
+// written for one works verbatim on the other.
+// ---------------------------------------------------------------------------
+
+/** What the filter gets to look at for one item. */
+export interface CommandFilterItem {
+  /** `label` prop, or the item's children when they're a plain string. */
+  label: string
+  /** Extra terms that match but are never displayed. */
+  keywords: string[]
+  /** The item's `value`, when it has one. */
+  value?: string
+}
+
+export type CommandFilter = (item: CommandFilterItem, query: string) => boolean
+
+/**
+ * Folds a string to a comparable form (lowercase, no diacritics) while keeping,
+ * for every folded character, the index it came from — so a match found on the
+ * folded text can be highlighted on the original one ("déploiement" matched by
+ * "deploi" highlights the right six characters, accent included).
+ */
+export function fold(text: string): { folded: string; map: number[] } {
+  let folded = ""
+  const map: number[] = []
+  for (let i = 0; i < text.length; i++) {
+    const chunk = text[i].normalize("NFD").replace(/\p{Diacritic}/gu, "").toLowerCase()
+    for (const char of chunk) {
+      folded += char
+      map.push(i)
+    }
+  }
+  return { folded, map }
+}
+
+/** Wraps the matched slice of `text` in a `<mark>`. Returns the plain text when there's no match. */
+export function highlightMatch(text: string, query: string): ReactNode {
+  if (!query.trim()) return text
+  const haystack = fold(text)
+  const needle = fold(query.trim()).folded
+  if (!needle) return text
+  const at = haystack.folded.indexOf(needle)
+  if (at === -1) return text
+  const start = haystack.map[at]
+  const end = haystack.map[at + needle.length - 1] + 1
+  return (
+    <>
+      {text.slice(0, start)}
+      <mark className="rounded-xs bg-primary/15 text-inherit">{text.slice(start, end)}</mark>
+      {text.slice(end)}
+    </>
+  )
+}

package/src/components/marketing/code-block.tsx

@@ -0,0 +1,89 @@
+// Snippets and screenshots — the two ways a marketing page shows the product
+// rather than describing it. Both static, both server-renderable.
+
+import type { ReactElement, ReactNode } from "react"
+
+import { cn } from "../../utils"
+
+/* ─── CodeBlock ────────────────────────────────────────────────────────────
+   A real snippet (a compose file, a script, an import), on the same warm dark
+   surface as every other terminal-ish panel — the `--code-surface` token
+   (`bg-code-surface`), so the value lives in `styles.css` and not as a magic
+   `oklch(…)` string recopied into each component.
+
+   Deliberately unhighlighted: a syntax highlighter is another dependency and
+   another 30 kB on a marketing page, and these snippets are six lines long. A
+   consumer that wants highlighting renders its own `<pre>` inside the frame. */
+
+export interface CodeBlockProps {
+  code: string
+  /** Optional filename bar above the snippet. */
+  filename?: ReactNode
+  className?: string
+}
+
+export function CodeBlock({ code, filename, className }: CodeBlockProps) {
+  return (
+    <div translate="no" className={cn("overflow-hidden rounded-lg border border-border", className)}>
+      {filename && (
+        <div className="border-b border-border bg-card px-4 py-2 font-mono text-[10.5px] uppercase tracking-[0.14em] text-muted-foreground">
+          {filename}
+        </div>
+      )}
+      <pre className="night-scroll overflow-x-auto bg-code-surface px-4 py-4 font-mono text-[11.5px] leading-[1.8] text-stone-200 md:text-[12.5px]">
+        <code>{code}</code>
+      </pre>
+    </div>
+  )
+}
+
+/* ─── Figure — a real screenshot, framed and captioned ─────────────────────
+   Marketing illustrations are product screenshots rather than drawings, so they
+   get a browser-ish frame and a caption saying what you're looking at.
+
+   The image element is a **slot**, for the same reason links are: the package
+   never imports `next/image` (or any framework primitive). Default is a plain
+   `<img>`; a Next app passes `render={{ image: (p) => <Image {...p} /> }}` and
+   gets its optimizer back. */
+
+export interface FigureImageProps {
+  src: string
+  alt: string
+  width: number
+  height: number
+  className?: string
+}
+
+export type FigureImageRender = (props: FigureImageProps) => ReactElement
+
+export interface FigureProps {
+  src: string
+  alt: string
+  caption?: ReactNode
+  width: number
+  height: number
+  render?: { image?: FigureImageRender }
+  className?: string
+}
+
+export function Figure({ src, alt, caption, width, height, render, className }: FigureProps) {
+  const image = render?.image ?? ((props: FigureImageProps) => <img {...props} alt={props.alt} />)
+
+  return (
+    <figure className={className}>
+      <div className="overflow-hidden rounded-lg border border-border bg-card">
+        <div className="flex items-center gap-1.5 border-b border-border px-3 py-2" aria-hidden>
+          <span className="h-2.5 w-2.5 rounded-full bg-border" />
+          <span className="h-2.5 w-2.5 rounded-full bg-border" />
+          <span className="h-2.5 w-2.5 rounded-full bg-border" />
+        </div>
+        {image({ src, alt, width, height, className: "w-full" })}
+      </div>
+      {caption && (
+        <figcaption className="mt-2.5 font-mono text-[10px] uppercase tracking-[0.14em] text-muted-foreground/60">
+          {caption}
+        </figcaption>
+      )}
+    </figure>
+  )
+}

package/src/components/marketing/copy-command.tsx

@@ -0,0 +1,139 @@
+"use client"
+
+import { useEffect, useRef, useState, type ReactNode } from "react"
+import { CheckIcon, CopyIcon } from "lucide-react"
+
+import { cn } from "../../utils"
+
+/* ─── CopyCommand — the call to action, when it's a command ────────────────
+   The primary action on an infrastructure landing is usually a command rather
+   than a signup form, so it gets the care a button would: the copy affordance
+   is always visible (there is no hover on a phone), and what lands in the
+   clipboard is the joined-up one-liner, not the pretty wrapped version.
+
+   **One component, two registers.** The site had this twice — `CopyCommand` on
+   the light document and `NightCommand` on the dark band, same behaviour, two
+   files, two places to fix a bug. Here it's one component and a `tone`:
+
+     - `"day"`   — bordered card on the light document, dark `<pre>` inside.
+     - `"night"` — translucent black on a `NightBand`, no opaque surface of its
+                   own so the band's glow shows through.
+
+   `accent` colours the `$` prompt (and, in the night register, is the only warm
+   thing in the block) — a page passes its own product accent. */
+
+export type CommandTone = "day" | "night"
+
+export interface CopyCommandProps {
+  command: string
+  /** Mono label in the bar — "your machine", "on each node you connect"… */
+  caption?: ReactNode
+  /** Small print under the block. */
+  note?: ReactNode
+  tone?: CommandTone
+  /** Any CSS colour, used for the `$` prompt. */
+  accent?: string
+  className?: string
+  /** Label of the copy button, for screen readers. */
+  copyLabel?: string
+}
+
+export function CopyCommand({
+  command,
+  caption,
+  note,
+  tone = "day",
+  accent,
+  className,
+  copyLabel = "Copy the command",
+}: CopyCommandProps) {
+  const [copied, setCopied] = useState(false)
+  // A visitor who copies then navigates away would otherwise leave a 2s timer
+  // behind, firing setState on an unmounted component.
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null)
+  useEffect(() => () => void (timer.current && clearTimeout(timer.current)), [])
+
+  function copy() {
+    // The multi-line form is for reading; what gets pasted is the one-liner.
+    const text = command.replace(/\\\n\s*/g, "")
+    navigator.clipboard
+      ?.writeText(text)
+      .then(() => {
+        setCopied(true)
+        if (timer.current) clearTimeout(timer.current)
+        timer.current = setTimeout(() => setCopied(false), 2000)
+      })
+      .catch(() => {
+        /* Denied permission / insecure context: the command is still selectable. */
+      })
+  }
+
+  const night = tone === "night"
+
+  return (
+    <div className={className}>
+      <div
+        translate="no"
+        className={cn(
+          "overflow-hidden rounded-lg border",
+          night ? "border-white/15 bg-black/30 backdrop-blur-sm" : "border-border"
+        )}
+      >
+        <div
+          className={cn(
+            "flex items-center justify-between gap-3 border-b px-3 py-2 font-mono text-[10.5px] uppercase tracking-[0.14em] md:px-4",
+            night ? "border-white/10 text-stone-400" : "border-border bg-card text-muted-foreground"
+          )}
+        >
+          <span className="truncate">{caption ?? "your machine"}</span>
+          <button
+            type="button"
+            onClick={copy}
+            aria-label={copyLabel}
+            className={cn(
+              "inline-flex shrink-0 items-center gap-1.5 rounded-md border px-2 py-1 text-[10px] uppercase tracking-[0.14em] transition-colors",
+              night
+                ? "border-white/15 hover:border-white/35 hover:text-white"
+                : "border-border hover:border-primary/40 hover:text-foreground"
+            )}
+          >
+            {copied ? (
+              <>
+                <CheckIcon className={cn("h-3 w-3", night ? "text-emerald-400" : "text-emerald-500")} />
+                copied
+              </>
+            ) : (
+              <>
+                <CopyIcon className="h-3 w-3" />
+                copy
+              </>
+            )}
+          </button>
+        </div>
+        <pre
+          className={cn(
+            "night-scroll overflow-x-auto px-3 py-3.5 font-mono text-[11px] leading-[1.75] text-stone-200 md:px-4 md:text-[12px]",
+            // On the band the block stays translucent; on the document it needs
+            // its own dark surface, the same one CodeBlock uses.
+            !night && "bg-code-surface"
+          )}
+        >
+          <code>
+            <span
+              className={cn("select-none", !accent && !night && "text-primary", !accent && night && "text-flame")}
+              style={accent ? { color: accent } : undefined}
+            >
+              ${" "}
+            </span>
+            {command}
+          </code>
+        </pre>
+      </div>
+      {note && (
+        <p className={cn("mt-2.5 text-[12.5px] leading-relaxed", night ? "text-stone-400" : "text-muted-foreground")}>
+          {note}
+        </p>
+      )}
+    </div>
+  )
+}

package/src/components/marketing/index.ts

@@ -0,0 +1,55 @@
+// @spunto/design-system/marketing — the vocabulary of a marketing page.
+//
+// Fourth sub-export, after `/workers`, `/devcontainer` and `/projects`, and the
+// first one that isn't a Spunto domain: these are layout and typography
+// primitives — a numbered chapter, a display headline, a mono kicker, key/value
+// rows, a disclosure row, a copyable command, a night band. They live behind
+// their own entry rather than in the root because an app that draws a dashboard
+// has no use for them, and because they carry their own opinions (a display
+// face, a fixed dark surface) that the root primitives deliberately don't.
+//
+// **The rule for what belongs here**, applied on the way in and worth keeping:
+// if a component needs to know a product, a URL or a session, it stays in the
+// site. If it only lays out or types, it comes here. That is why the site's
+// product registry, its navs and footers, its product logos and its OG cards
+// did *not* travel — they are the site, not the system.
+//
+// Two constraints the package enforces that the site's own kits didn't have to:
+//
+//   - **No framework imports.** No `next/link`, no `next/image`. Navigation is
+//     the caller's (`actions` slots, plain children) and `Figure` takes an image
+//     `render` slot — the same motif as `CommandPaletteLinkRender` and
+//     `WorkerCard`'s `render.link`.
+//   - **No motion library.** `Reveal` is an IntersectionObserver and a CSS
+//     transition; `useLoopClock` is one rAF. A design system doesn't put
+//     `framer-motion` in the bundle of consumers who never draw a landing page.
+//
+// Server components: everything static (`Section`, `H2`, `Kicker`, `SpecList`,
+// `Disclosure`, `CodeBlock`, `Figure`, `NightBand`, `NightChip`,
+// `ProductHeader`) is free of `"use client"` and renders on the server. Only
+// `CopyCommand`, `Reveal` and the hooks are client files.
+
+export { Section, H2, Kicker, SpecList, Disclosure } from "./section"
+export type { SectionProps, H2Props, KickerProps, SpecListProps, DisclosureProps } from "./section"
+
+export { CodeBlock, Figure } from "./code-block"
+export type { CodeBlockProps, FigureProps, FigureImageProps, FigureImageRender } from "./code-block"
+
+export { CopyCommand } from "./copy-command"
+export type { CopyCommandProps, CommandTone } from "./copy-command"
+
+export { NightBand, NightChip } from "./night-band"
+export type { NightBandProps, NightChipProps } from "./night-band"
+
+export { ProductHeader } from "./product-header"
+export type { ProductHeaderProps } from "./product-header"
+
+export { Reveal } from "./reveal"
+export type { RevealProps } from "./reveal"
+
+export { usePrefersReducedMotion, useLoopClock } from "./motion"
+export type { LoopClock } from "./motion"
+
+// Re-exported here so a consumer of the marketing surface doesn't have to import
+// the root entry just to compose class names.
+export { cn } from "../../utils"

package/src/components/marketing/motion.ts

@@ -0,0 +1,92 @@
+"use client"
+
+import { useEffect, useRef, useState, useSyncExternalStore } from "react"
+
+/* ─── prefers-reduced-motion, as a value ───────────────────────────────────
+   `useSyncExternalStore` rather than an effect + state: the subscription *is*
+   the media query, so there is no first-render frame with the wrong answer and
+   nothing to keep in sync by hand. The server snapshot is `false` (assume
+   motion, then correct on hydration) — the alternative renders the still frame
+   to everyone. */
+
+const REDUCED_MOTION_QUERY = "(prefers-reduced-motion: reduce)"
+
+function subscribeReducedMotion(onChange: () => void) {
+  const mq = window.matchMedia(REDUCED_MOTION_QUERY)
+  mq.addEventListener("change", onChange)
+  return () => mq.removeEventListener("change", onChange)
+}
+
+export function usePrefersReducedMotion(): boolean {
+  return useSyncExternalStore(
+    subscribeReducedMotion,
+    () => window.matchMedia(REDUCED_MOTION_QUERY).matches,
+    () => false
+  )
+}
+
+/* ─── useLoopClock — "how far into the loop are we" ────────────────────────
+   The animated artifacts of a landing page (a terminal typing itself out, a
+   build filling up) are usually pure functions of one number. Modelling them
+   that way keeps each to a single rAF, makes the reduced-motion path a matter
+   of picking a frame, and makes them trivially testable.
+
+   Two things this does that a naive rAF loop doesn't:
+
+     - it **stops when the element is off screen** (IntersectionObserver on the
+       returned ref), so a page with three animated panels runs one loop, not
+       three;
+     - it **commits at ~14 Hz, not 60** (`resolutionMs`) — a marketing page has
+       no business re-rendering a React tree on every frame.
+
+   Attach `ref` to the element that has to be visible for the clock to run, and
+   drive everything else from `t` (milliseconds into the loop). */
+
+export interface LoopClock<T extends HTMLElement> {
+  /** Milliseconds elapsed in the current loop, in `[0, loop)`. */
+  t: number
+  /** Attach to the animated element — the clock pauses while it's off screen. */
+  ref: React.RefObject<T | null>
+}
+
+export function useLoopClock<T extends HTMLElement = HTMLDivElement>(
+  /** Loop length, in milliseconds. */
+  loop: number,
+  /** `false` freezes the clock at 0 — pass `!prefersReducedMotion`. */
+  enabled: boolean,
+  /** Minimum gap between two committed values. */
+  resolutionMs = 70,
+  /** Changing it restarts the loop from zero. */
+  resetKey: unknown = null
+): LoopClock<T> {
+  const [t, setT] = useState(0)
+  const ref = useRef<T>(null)
+  const [visible, setVisible] = useState(true)
+
+  useEffect(() => {
+    const el = ref.current
+    if (!el) return
+    const io = new IntersectionObserver(([entry]) => setVisible(entry.isIntersecting), { rootMargin: "120px" })
+    io.observe(el)
+    return () => io.disconnect()
+  }, [])
+
+  useEffect(() => {
+    if (!enabled || !visible) return
+    let raf = 0
+    let committed = -1
+    const start = performance.now()
+    const tick = (now: number) => {
+      const v = (now - start) % loop
+      if (v < committed || v - committed >= resolutionMs) {
+        committed = v
+        setT(v)
+      }
+      raf = requestAnimationFrame(tick)
+    }
+    raf = requestAnimationFrame(tick)
+    return () => cancelAnimationFrame(raf)
+  }, [enabled, visible, loop, resolutionMs, resetKey])
+
+  return { t, ref }
+}

package/src/components/marketing/night-band.tsx

@@ -0,0 +1,75 @@
+// The night register — a fixed dark band inside an otherwise light document.
+//
+// Static markup only (no state, no effect), so it stays server-renderable: the
+// drifting light source is a CSS animation carried by `styles.css`, not a rAF
+// loop, because this is usually the most-viewed element of a site and it has no
+// business holding one open.
+
+import type { ReactNode } from "react"
+
+import { cn } from "../../utils"
+
+/* ─── NightBand ────────────────────────────────────────────────────────────
+   A page that is cream on cream from top to bottom is calm at a glance and
+   flat over its full height. The band is the contrast: near-black, with the
+   accent as a light source behind it, dropping back into the document
+   underneath on a hairline.
+
+   The surface is the `--night` token (`bg-night`), deliberately deeper than the
+   dark theme's own background so the band still reads as a band when the whole
+   site is already dark — and identical in both themes, since it *is* the dark
+   moment of the page rather than a themed surface. */
+
+export interface NightBandProps {
+  children: ReactNode
+  /** The light source. A page passes its own accent — any CSS colour. */
+  glow?: string
+  className?: string
+}
+
+export function NightBand({ children, glow = "var(--flame)", className }: NightBandProps) {
+  return (
+    <div className={cn("relative isolate overflow-hidden bg-night text-stone-100", className)}>
+      <div aria-hidden className="night-grid pointer-events-none absolute inset-0" />
+      {/* `glow` transitions, so a page that lets the visitor pick a product in
+          the hero changes temperature with the selection. */}
+      <div
+        aria-hidden
+        className="night-glow-a pointer-events-none absolute -left-[10%] -top-[45%] h-[85%] w-[70%] opacity-[0.5] transition-[background] duration-700"
+        style={{ background: `radial-gradient(closest-side, ${glow}, transparent)` }}
+      />
+      <div
+        aria-hidden
+        className="night-glow-b pointer-events-none absolute -bottom-[55%] right-[-15%] h-[90%] w-[60%] opacity-[0.22] transition-[background] duration-700"
+        style={{ background: `radial-gradient(closest-side, ${glow}, transparent)` }}
+      />
+      {/* Hairline at the seam, so the band ends on a line like everything else. */}
+      <div aria-hidden className="pointer-events-none absolute inset-x-0 bottom-0 h-px bg-white/10" />
+      <div className="relative">{children}</div>
+    </div>
+  )
+}
+
+/* ─── NightChip — a small fact on a night surface ─────────────────────────── */
+
+export interface NightChipProps {
+  children: ReactNode
+  /** Any CSS colour: tints the border and lights the leading dot. */
+  accent?: string
+  className?: string
+}
+
+export function NightChip({ children, accent, className }: NightChipProps) {
+  return (
+    <span
+      className={cn(
+        "inline-flex items-center gap-1.5 rounded-full border border-white/15 px-2 py-1 font-mono text-[9px] uppercase tracking-[0.1em] text-stone-300 sm:px-2.5 sm:text-[10px] sm:tracking-[0.14em]",
+        className
+      )}
+      style={accent ? { borderColor: `color-mix(in oklch, ${accent} 45%, transparent)` } : undefined}
+    >
+      {accent && <span className="h-1.5 w-1.5 rounded-full" style={{ backgroundColor: accent }} />}
+      {children}
+    </span>
+  )
+}