@spunto/design-system 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/design-system",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Spunto's shared design system — warm/flame tokens, color constants, and UI primitives.",
   "type": "module",
   "license": "MIT",
@@ -44,6 +44,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@xterm/addon-fit": "^0.11.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,156 @@
+"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 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
+}
+
+/**
+ * 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 },
+  ref
+) {
+  const outerRef = useRef<HTMLDivElement>(null)
+  const mountRef = useRef<HTMLDivElement>(null)
+  const termRef = useRef<XTerm | null>(null)
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      write: (data) => termRef.current?.write(data),
+      writeln: (data) => termRef.current?.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)
+      // 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
+
+      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 } 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);