@spunto/design-system 0.4.0 → 0.6.0

package/README.md

@@ -51,6 +51,10 @@ 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.
+  - _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`
+    ref handle. Opt-in addons through `options` (currently `webLinks`, clickable URLs).
 - **`SpuntoProvider` + `toast()`** — the imperative toast system (see below). The
   provider is also the umbrella that mounts the tooltip delay group and the overlay
   portal container the dialogs/selects render into.
@@ -104,6 +108,26 @@ toast.dismiss(id)
 `toastPosition` (default `"top-right"`), `toastDuration` (default `5000`, `0` =
 persistent) and `toastLimit` (default `3`).
 
+## LLM / agent docs (`llms.txt`)
+
+The [showcase](showcase/) also exposes its documentation as **plain markdown**,
+so coding agents can consume the component APIs directly. Everything is generated
+from the same content that drives the visual pages
+(`showcase/src/content/components.ts`) — there is no second source to keep in sync.
+
+Served both in dev (Vite middleware) and in the built site (static files) at
+`https://design.spunto.net`:
+
+- **`/llms.txt`** — index (llmstxt.org convention) linking every page.
+- **`/<component>.md`** — one page per component with import, example and the full
+  props API (e.g. `/button.md`, `/select.md`).
+- **`/colors.md`**, `/typography.md`, `/radius.md` — the foundations/tokens.
+- **`/llms-full.txt`** — every page concatenated into a single file.
+
+Adding a component = add its entry to `content/components.ts` + a demo file in
+`showcase/src/demos/`; the visual page and its `.md` are then produced
+automatically (see `showcase/vite-plugin-llms.ts`).
+
 ## Peer requirements
 
 - React 19+, and a **Tailwind CSS v4** pipeline in the consuming app.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/design-system",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Spunto's shared design system — warm/flame tokens, color constants, and UI primitives.",
   "type": "module",
   "license": "MIT",
@@ -44,6 +44,9 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/addon-web-links": "^0.12.0",
+    "@xterm/xterm": "^6.0.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "tailwind-merge": "^3.6.0"

package/src/components/terminal.tsx

@@ -0,0 +1,188 @@
+"use client"
+
+import { forwardRef, useEffect, useImperativeHandle, useRef } from "react"
+import type { Terminal as XTerm } from "@xterm/xterm"
+// xterm.js's own stylesheet — hides its input-capture textarea and glyph
+// measurement helpers. A JS-side import (not a CSS `@import`) so it loads
+// regardless of the consuming app's stylesheet pipeline/ordering.
+import "@xterm/xterm/css/xterm.css"
+
+import { cn } from "../utils"
+
+// Shared dark ANSI palette — the one look every log/terminal surface in the
+// product already uses (job runs, builds, service logs, worker shells).
+const terminalTheme = {
+  background: "#09090b",
+  foreground: "#e4e4e7",
+  cursor: "#a1a1aa",
+  selectionBackground: "#3f3f46",
+  black: "#18181b",
+  red: "#f87171",
+  green: "#4ade80",
+  yellow: "#facc15",
+  blue: "#60a5fa",
+  magenta: "#c084fc",
+  cyan: "#22d3ee",
+  white: "#e4e4e7",
+  brightBlack: "#52525b",
+  brightRed: "#fca5a5",
+  brightGreen: "#86efac",
+  brightYellow: "#fde047",
+  brightBlue: "#93c5fd",
+  brightMagenta: "#d8b4fe",
+  brightCyan: "#67e8f9",
+  brightWhite: "#f4f4f5",
+}
+
+export interface TerminalHandle {
+  /** Writes raw bytes/text (ANSI sequences included) to the terminal. */
+  write: (data: string | Uint8Array) => void
+  writeln: (data: string) => void
+  clear: () => void
+  focus: () => void
+}
+
+export interface TerminalOptions {
+  /** Turns URLs in terminal output into clickable links (`@xterm/addon-web-links`). */
+  webLinks?: boolean
+}
+
+export interface TerminalProps {
+  className?: string
+  fontSize?: number
+  scrollback?: number
+  /**
+   * Wires keystrokes back out and switches the terminal into interactive mode
+   * (blinking cursor, stdin enabled). Omit for read-only log output — the
+   * common case this primitive was built for.
+   */
+  onData?: (data: string) => void
+  /**
+   * Opt-in xterm addons — kept out of the base bundle since most consumers
+   * (plain log output) don't need them. Read once at mount, like the other
+   * props here.
+   */
+  options?: TerminalOptions
+}
+
+/**
+ * Bare xterm.js surface: mount, theme, and fit-on-resize — nothing else. It
+ * has no opinion on where bytes come from (WebSocket, SSE, a static string);
+ * feed it via the `write`/`writeln` ref handle from whatever transport you
+ * plug in on top.
+ */
+const Terminal = forwardRef<TerminalHandle, TerminalProps>(function Terminal(
+  { className, fontSize = 13, scrollback = 5000, onData, options },
+  ref
+) {
+  const outerRef = useRef<HTMLDivElement>(null)
+  const mountRef = useRef<HTMLDivElement>(null)
+  const termRef = useRef<XTerm | null>(null)
+  // xterm mounts asynchronously (dynamic import); a consumer wiring up a
+  // transport (WebSocket, SSE...) in its own effect can easily win that race
+  // and call write() before termRef exists. Queue those calls instead of
+  // dropping them, and flush in order once xterm is ready.
+  const pendingRef = useRef<Array<{ method: "write" | "writeln"; data: string | Uint8Array }>>([])
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      write: (data) => {
+        if (termRef.current) termRef.current.write(data)
+        else pendingRef.current.push({ method: "write", data })
+      },
+      writeln: (data) => {
+        if (termRef.current) termRef.current.writeln(data)
+        else pendingRef.current.push({ method: "writeln", data })
+      },
+      clear: () => termRef.current?.clear(),
+      focus: () => termRef.current?.focus(),
+    }),
+    []
+  )
+
+  useEffect(() => {
+    if (!mountRef.current) return
+
+    let disposed = false
+    let resizeObserver: ResizeObserver | undefined
+
+    async function init() {
+      const { Terminal: XTermCtor } = await import("@xterm/xterm")
+      const { FitAddon } = await import("@xterm/addon-fit")
+      if (disposed || !mountRef.current) return
+
+      const term = new XTermCtor({
+        cursorBlink: !!onData,
+        disableStdin: !onData,
+        cursorStyle: "block",
+        fontFamily: '"JetBrains Mono", "Fira Code", "Cascadia Code", monospace',
+        fontSize,
+        lineHeight: 1.4,
+        scrollback,
+        theme: terminalTheme,
+      })
+
+      const fitAddon = new FitAddon()
+      term.loadAddon(fitAddon)
+      if (options?.webLinks) {
+        const { WebLinksAddon } = await import("@xterm/addon-web-links")
+        term.loadAddon(new WebLinksAddon())
+      }
+      // FitAddon computes available space from *this* element's parent minus
+      // this element's own padding — it has no idea about an outer wrapper's
+      // padding/border. Mounting on a padding-less, border-less inner div (see
+      // render below) means that math actually lines up with what's visually
+      // available; mounting directly on the styled/padded outer div is what
+      // let `.xterm-screen` spill a few px past the rounded border.
+      term.open(mountRef.current)
+      fitAddon.fit()
+      termRef.current = term
+
+      for (const { method, data } of pendingRef.current) {
+        if (method === "writeln") term.writeln(data as string)
+        else term.write(data)
+      }
+      pendingRef.current = []
+
+      if (onData) term.onData(onData)
+
+      resizeObserver = new ResizeObserver(() => fitAddon.fit())
+      resizeObserver.observe(mountRef.current)
+    }
+
+    init()
+
+    return () => {
+      disposed = true
+      resizeObserver?.disconnect()
+      termRef.current?.dispose()
+      termRef.current = null
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  return (
+    <div
+      ref={outerRef}
+      data-slot="terminal"
+      className={cn(
+        // `[contain:inline-size]` stops this box's (fit-driven, ever-changing)
+        // content width from feeding back into an ancestor's shrink-to-fit
+        // sizing — without it, a parent with `flex-basis: auto` re-measures
+        // this element's content each time fit() grows it, which re-fires the
+        // ResizeObserver below and runs away (confirmed: unbounded growth).
+        "h-full w-full min-h-0 min-w-0 overflow-hidden rounded-lg border border-border p-2 [contain:inline-size]",
+        className
+      )}
+      style={{ backgroundColor: terminalTheme.background }}
+    >
+      {/* Padding/border live on the outer div only — FitAddon can't see them
+          (see comment above `term.open`), so xterm always mounts on a bare,
+          unstyled div that exactly matches the visually available space. */}
+      <div ref={mountRef} className="h-full w-full" />
+    </div>
+  )
+})
+
+export { Terminal }

package/src/index.ts

@@ -21,6 +21,11 @@ export { Skeleton } from "./components/skeleton"
 export { Spinner, spinnerVariants } from "./components/spinner"
 export { Avatar, AvatarImage, AvatarFallback } from "./components/avatar"
 
+// xterm.js surface — theme + fit-on-resize, transport-agnostic (feed it via
+// the write/writeln ref handle).
+export { Terminal } from "./components/terminal"
+export type { TerminalHandle, TerminalProps, TerminalOptions } from "./components/terminal"
+
 // Inline, declarative status banner (persistent) — the counterpart to `toast()`.
 // `alertVariants` ships from this directive-free module so it stays RSC-callable.
 export { Alert, AlertTitle, AlertDescription, alertVariants } from "./components/alert"

package/styles.css

@@ -186,6 +186,25 @@
   ::-webkit-scrollbar-thumb:hover { background: color-mix(in oklch, var(--muted-foreground) 30%, transparent); }
 }
 
+/* ─── Terminal — xterm.js scrollbar ──────────────────────────────────────────
+ * Restyle xterm's own custom scrollbar (14px, square corners) to match the
+ * thin/rounded one above. Its width/position are set inline by xterm's JS on
+ * every resize, hence `!important`; color is left to xterm's own theme
+ * (`scrollbarSliderBackground` etc. in `terminalTheme`, terminal.tsx) since
+ * that already defaults to a sensible foreground/20% and is the supported
+ * knob for it. */
+[data-slot="terminal"] .scrollbar.vertical,
+[data-slot="terminal"] .scrollbar.vertical > .slider {
+  width: 6px !important;
+}
+[data-slot="terminal"] .scrollbar.horizontal,
+[data-slot="terminal"] .scrollbar.horizontal > .slider {
+  height: 6px !important;
+}
+[data-slot="terminal"] .slider {
+  border-radius: 9999px;
+}
+
 /* ─── Warm background utilities ──────────────────────────────────────────── */
 .dot-grid {
   background-image: radial-gradient(circle, oklch(0.45 0.05 50 / 0.08) 1px, transparent 1px);