@spunto/design-system 0.9.0 → 0.9.2

package/src/components/terminal.tsx

@@ -2,6 +2,7 @@
 
 import { forwardRef, useEffect, useImperativeHandle, useRef } from "react"
 import type { Terminal as XTerm } from "@xterm/xterm"
+import type { SearchAddon } from "@xterm/addon-search"
 // 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.
@@ -34,17 +35,55 @@ const terminalTheme = {
   brightWhite: "#f4f4f5",
 }
 
+export interface TerminalSearchOptions {
+  caseSensitive?: boolean
+  wholeWord?: boolean
+  regex?: boolean
+  /** Re-runs from the current match rather than the next one — for search-as-you-type. */
+  incremental?: boolean
+}
+
+/** What `onViewportChange` reports. See that prop for why both fields are needed. */
+export interface TerminalViewportState {
+  /** Rows between the bottom of the viewport and the end of the buffer. 0 = stuck to the tail. */
+  rowsBelow: number
+  /** `"output"` = a new line was printed · `"scroll"` = the viewport itself moved. */
+  reason: "output" | "scroll"
+}
+
 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
+  /**
+   * The whole scrollback as plain text — ANSI stripped, rows that xterm split at
+   * the viewport width rejoined into the single line they were written as. This
+   * is what "copy everything" / "download the log" need, and neither can be done
+   * from outside: only xterm holds the buffer.
+   */
+  getContent: () => string
+  /** Jumps the viewport back to the tail of the buffer (the "follow" button). */
+  scrollToBottom: () => void
+  /** Same number as `TerminalViewportState.rowsBelow`, polled instead of pushed. */
+  rowsBelow: () => number
+  /**
+   * Search, delegated to `@xterm/addon-search`. No-ops (returns false) unless
+   * `options.search` was set at mount — the addon isn't loaded otherwise.
+   * Match highlighting/colors are handled inside; callers only pass the query.
+   */
+  findNext: (query: string, options?: TerminalSearchOptions) => boolean
+  findPrevious: (query: string, options?: TerminalSearchOptions) => boolean
+  /** Drops the highlights — call it when the search UI closes. */
+  clearSearch: () => void
 }
 
 export interface TerminalOptions {
   /** Turns URLs in terminal output into clickable links (`@xterm/addon-web-links`). */
   webLinks?: boolean
+  /** Loads `@xterm/addon-search`, which powers the `findNext`/`findPrevious` handle. */
+  search?: boolean
 }
 
 export interface TerminalProps {
@@ -63,6 +102,27 @@ export interface TerminalProps {
    * props here.
    */
   options?: TerminalOptions
+  /**
+   * Fires whenever the buffer grows or the viewport moves. Exists for one job:
+   * letting a wrapper (`TerminalPanel`) answer "is the user still watching the
+   * tail, and how much have they missed?" — xterm never scrolls the user down by
+   * force, but it also never tells them lines are piling up below.
+   *
+   * `reason` is what makes the count possible: an `"output"` event means one more
+   * missed line, a `"scroll"` event means the user moved on purpose and the count
+   * should re-baseline. It fires per line feed on a busy stream, so coalesce
+   * (rAF/ref) rather than calling `setState` straight from it.
+   */
+  onViewportChange?: (state: TerminalViewportState) => void
+  /**
+   * New grid size after a fit — i.e. after the container resized. An interactive
+   * consumer has to forward this to whatever is on the other end (a PTY sizes its
+   * output to the client's grid), and `fit()` happens in here, so nowhere else can
+   * observe it. Also fires once at mount with the initial size.
+   */
+  onResize?: (size: { cols: number; rows: number }) => void
+  /** Match count/position of the running search — only fires when `options.search` is on. */
+  onSearchResults?: (results: { resultIndex: number; resultCount: number }) => void
 }
 
 /**
@@ -72,12 +132,22 @@ export interface TerminalProps {
  * plug in on top.
  */
 const Terminal = forwardRef<TerminalHandle, TerminalProps>(function Terminal(
-  { className, fontSize = 13, scrollback = 5000, onData, options },
+  { className, fontSize = 13, scrollback = 5000, onData, options, onViewportChange, onResize, onSearchResults },
   ref
 ) {
   const outerRef = useRef<HTMLDivElement>(null)
   const mountRef = useRef<HTMLDivElement>(null)
   const termRef = useRef<XTerm | null>(null)
+  const searchRef = useRef<SearchAddon | null>(null)
+  // xterm's event handlers are wired once at mount, but these two callbacks come
+  // from a consumer that re-renders — read them through refs so a new closure
+  // doesn't require tearing the terminal down.
+  const viewportCbRef = useRef(onViewportChange)
+  const resizeCbRef = useRef(onResize)
+  const searchCbRef = useRef(onSearchResults)
+  viewportCbRef.current = onViewportChange
+  resizeCbRef.current = onResize
+  searchCbRef.current = onSearchResults
   // 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
@@ -97,6 +167,12 @@ const Terminal = forwardRef<TerminalHandle, TerminalProps>(function Terminal(
       },
       clear: () => termRef.current?.clear(),
       focus: () => termRef.current?.focus(),
+      getContent: () => (termRef.current ? bufferToText(termRef.current) : ""),
+      scrollToBottom: () => termRef.current?.scrollToBottom(),
+      rowsBelow: () => (termRef.current ? rowsBelowViewport(termRef.current) : 0),
+      findNext: (query, opts) => searchRef.current?.findNext(query, searchOptions(opts)) ?? false,
+      findPrevious: (query, opts) => searchRef.current?.findPrevious(query, searchOptions(opts)) ?? false,
+      clearSearch: () => searchRef.current?.clearDecorations(),
     }),
     []
   )
@@ -133,6 +209,9 @@ const Terminal = forwardRef<TerminalHandle, TerminalProps>(function Terminal(
         lineHeight: 1.2,
         scrollback,
         theme: terminalTheme,
+        // Only the search addon needs it (its match highlighting goes through
+        // the decoration API), so it stays off for everyone else.
+        allowProposedApi: !!options?.search,
       })
 
       const fitAddon = new FitAddon()
@@ -141,6 +220,13 @@ const Terminal = forwardRef<TerminalHandle, TerminalProps>(function Terminal(
         const { WebLinksAddon } = await import("@xterm/addon-web-links")
         term.loadAddon(new WebLinksAddon())
       }
+      if (options?.search) {
+        const { SearchAddon } = await import("@xterm/addon-search")
+        const searchAddon = new SearchAddon()
+        term.loadAddon(searchAddon)
+        searchAddon.onDidChangeResults((results) => searchCbRef.current?.(results))
+        searchRef.current = searchAddon
+      }
       // 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
@@ -159,6 +245,16 @@ const Terminal = forwardRef<TerminalHandle, TerminalProps>(function Terminal(
 
       if (onData) term.onData(onData)
 
+      // Two events rather than one because they mean opposite things to a tail
+      // follower: a line feed is output the user may be missing, a scroll is the
+      // user deciding where to look.
+      term.onLineFeed(() => viewportCbRef.current?.({ rowsBelow: rowsBelowViewport(term), reason: "output" }))
+      term.onScroll(() => viewportCbRef.current?.({ rowsBelow: rowsBelowViewport(term), reason: "scroll" }))
+      term.onResize((size) => resizeCbRef.current?.(size))
+      // xterm only emits onResize on *changes*, and the first fit() above already
+      // happened — so announce the initial grid explicitly.
+      resizeCbRef.current?.({ cols: term.cols, rows: term.rows })
+
       resizeObserver = new ResizeObserver(() => fitAddon.fit())
       resizeObserver.observe(mountRef.current)
     }
@@ -170,6 +266,7 @@ const Terminal = forwardRef<TerminalHandle, TerminalProps>(function Terminal(
       resizeObserver?.disconnect()
       termRef.current?.dispose()
       termRef.current = null
+      searchRef.current = null
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [])
@@ -201,4 +298,58 @@ const Terminal = forwardRef<TerminalHandle, TerminalProps>(function Terminal(
   )
 })
 
+/**
+ * Rows between the bottom of the viewport and the end of the buffer. `baseY` is
+ * where the tail starts, `viewportY` where the user is looking — equal means
+ * "stuck to the bottom", which is the state a follow-tail affordance cares about.
+ */
+function rowsBelowViewport(term: XTerm): number {
+  const buffer = term.buffer.active
+  return Math.max(0, buffer.baseY - buffer.viewportY)
+}
+
+/**
+ * The buffer as plain text. Two things xterm won't do for you:
+ *
+ *  - **Rejoin wrapped rows.** A 300-char line is stored as three rows once the
+ *    viewport is 100 columns wide; copying it as three lines would make the
+ *    exported log depend on the window width it was read at.
+ *  - **Drop the empty tail.** The scrollback is pre-allocated, so the last rows
+ *    are blank filler, not log content.
+ */
+function bufferToText(term: XTerm): string {
+  const buffer = term.buffer.active
+  const lines: string[] = []
+
+  for (let i = 0; i < buffer.length; i++) {
+    const line = buffer.getLine(i)
+    if (!line) continue
+    const text = line.translateToString(true)
+    if (line.isWrapped && lines.length > 0) lines[lines.length - 1] += text
+    else lines.push(text)
+  }
+
+  while (lines.length > 0 && lines[lines.length - 1] === "") lines.pop()
+  return lines.join("\n")
+}
+
+/**
+ * Match colors live here, not at the call site: search is a design-system
+ * affordance and every terminal in the product should highlight the same way —
+ * zinc for the other matches, flame for the one you're on.
+ */
+function searchOptions(options?: TerminalSearchOptions) {
+  return {
+    ...options,
+    decorations: {
+      matchBackground: "#3f3f46",
+      matchBorder: "#71717a",
+      matchOverviewRuler: "#a1a1aa",
+      activeMatchBackground: "#ea5400",
+      activeMatchBorder: "#fb923c",
+      activeMatchColorOverviewRuler: "#ea5400",
+    },
+  }
+}
+
 export { Terminal }

package/src/index.ts

@@ -1,13 +1,9 @@
 // @spunto/design-system — shared UI primitives, helpers, and color constants.
 // Tokens ship as a CSS file: `import "@spunto/design-system/styles.css"`.
 
-export { cn, formatDuration, formatRelativeTime } from "./utils"
+export { cn } from "./utils"
 export * from "./colors"
 
-// Domain (Spunto-specific) components live behind their own entry point —
-// `@spunto/design-system/workers` — so this root stays domain-free primitives.
-// See README § "Domain components".
-
 export { Button } from "./components/button"
 // `buttonVariants` is exported from its own directive-free module (not through the
 // "use client" button.tsx) so it stays callable from React Server Components.
@@ -28,7 +24,18 @@ 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"
+export type {
+  TerminalHandle,
+  TerminalProps,
+  TerminalOptions,
+  TerminalSearchOptions,
+  TerminalViewportState,
+} from "./components/terminal"
+
+// The frame around a Terminal — bar (title/status/actions) + surface + the
+// connection/empty/loading/error states. Its ref *is* a TerminalHandle.
+export { TerminalPanel } from "./components/terminal-panel"
+export type { TerminalPanelProps, TerminalPanelStatus } from "./components/terminal-panel"
 
 // Docker image pull as a real UI (one segmented bar, one block per layer) —
 // presentational only: give it a snapshot, it draws it.

package/src/utils.ts

@@ -5,26 +5,3 @@ import { twMerge } from "tailwind-merge"
 export function cn(...inputs: ClassValue[]) {
   return twMerge(clsx(inputs))
 }
-
-/**
- * Coarse "3h ago" stamp — minutes, then hours, then days. Deliberately not a
- * live-ticking relative time: every surface using it (worker cards, tables)
- * already re-renders on its own polling cadence, and a second timer per row
- * would cost more than the precision is worth.
- */
-export function formatRelativeTime(date: string | number | Date): string {
-  const ms = date instanceof Date ? date.getTime() : new Date(date).getTime()
-  if (!Number.isFinite(ms)) return ""
-  const minutes = Math.floor((Date.now() - ms) / 60_000)
-  if (minutes < 1) return "just now"
-  if (minutes < 60) return `${minutes}m ago`
-  const hours = Math.floor(minutes / 60)
-  if (hours < 24) return `${hours}h ago`
-  return `${Math.floor(hours / 24)}d ago`
-}
-
-/** Short duration, one significant decimal under 10 s ("840ms", "4.2s", "38s"). */
-export function formatDuration(ms: number): string {
-  if (ms >= 1000) return `${(ms / 1000).toFixed(ms >= 10_000 ? 0 : 1)}s`
-  return `${Math.max(0, Math.round(ms))}ms`
-}

package/src/components/workers/creator-avatar.tsx

@@ -1,38 +0,0 @@
-// Who spawned the worker, in 20 px.
-//
-// A plain <img>, deliberately: the design system is consumed by two Next apps
-// *and* by a Vite showcase, so it can't reach for `next/image`. Avatars come
-// from GitHub/Google CDNs already sized for this.
-
-import { cn } from "../../utils"
-import type { WorkerCreator } from "./types"
-
-export function CreatorAvatar({ creator, className }: { creator: WorkerCreator; className?: string }) {
-  if (creator.avatarUrl) {
-    return (
-      <img
-        src={creator.avatarUrl}
-        alt={creator.name}
-        className={cn("h-5 w-5 shrink-0 rounded-full object-cover ring-1 ring-border", className)}
-      />
-    )
-  }
-
-  const initials = creator.name
-    .split(" ")
-    .map((n) => n[0])
-    .join("")
-    .toUpperCase()
-    .slice(0, 2)
-
-  return (
-    <span
-      className={cn(
-        "flex h-5 w-5 shrink-0 items-center justify-center rounded-full bg-muted text-[9px] font-semibold text-muted-foreground ring-1 ring-border",
-        className
-      )}
-    >
-      {initials}
-    </span>
-  )
-}

package/src/components/workers/git-branch-chips.tsx

@@ -1,120 +0,0 @@
-// "repo · branch +3" chips — what a worker is actually working on.
-//
-// The dashboard's version shows the modified count; Lite's also shows ahead /
-// behind. This is the union: every counter is rendered only when the caller
-// supplies it, so neither app has to send a field it doesn't have.
-
-import { ArrowDownIcon, ArrowUpIcon, ExternalLinkIcon, GitBranchIcon } from "lucide-react"
-
-import { cn } from "../../utils"
-
-export interface GitRepoStatus {
-  /** Absolute path of the checkout inside the worker — also the React key. */
-  path: string
-  branch?: string | null
-  /** Display name; defaults to the last segment of `path`. */
-  name?: string
-  /** Uncommitted files. */
-  modified?: number
-  /** Commits ahead of / behind the upstream branch. */
-  ahead?: number
-  behind?: number
-}
-
-export interface GitBranchChipsProps {
-  repos: GitRepoStatus[]
-  /**
-   * Chip → URL. A slot, not a link component: the design system knows nothing
-   * about code-server URLs, and returning `undefined` renders a plain span.
-   */
-  repoHref?: (repo: GitRepoStatus) => string | undefined
-  className?: string
-}
-
-export function repoName(repo: GitRepoStatus): string {
-  return repo.name ?? repo.path.split("/").filter(Boolean).pop() ?? repo.path
-}
-
-/** One chip per checked-out repository, wrapping onto as many lines as needed. */
-export function GitBranchChips({ repos, repoHref, className }: GitBranchChipsProps) {
-  if (!repos.length) return null
-
-  return (
-    <div data-slot="git-branch-chips" className={cn("flex flex-wrap gap-1.5", className)}>
-      {repos.map((repo) => {
-        const href = repoHref?.(repo)
-        const Tag = href ? "a" : "span"
-        return (
-          <Tag
-            key={repo.path}
-            {...(href ? { href, target: "_blank", rel: "noopener noreferrer" } : {})}
-            title={repo.path}
-            className={cn(
-              "inline-flex items-center gap-1 rounded-md border border-border bg-muted/40 px-2 py-0.5 font-mono text-[11px] text-muted-foreground",
-              href && "transition-colors hover:border-border/80 hover:bg-muted/70"
-            )}
-          >
-            <span className="font-medium text-foreground/70">{repoName(repo)}</span>
-            <span className="mx-0.5 text-muted-foreground/40">·</span>
-            <GitBranchIcon className="h-2.5 w-2.5 shrink-0" />
-            <span className="max-w-[120px] truncate">{repo.branch || "—"}</span>
-            <RepoCounters repo={repo} />
-            {href && <ExternalLinkIcon className="ml-0.5 h-2.5 w-2.5 opacity-40" />}
-          </Tag>
-        )
-      })}
-    </div>
-  )
-}
-
-/** Amber for local work not yet committed/pushed, muted for what's merely behind. */
-function RepoCounters({ repo }: { repo: GitRepoStatus }) {
-  return (
-    <>
-      {!!repo.modified && <span className="ml-0.5 text-amber-500 dark:text-amber-400">+{repo.modified}</span>}
-      {!!repo.ahead && (
-        <span className="ml-0.5 inline-flex items-center text-amber-500 dark:text-amber-400">
-          <ArrowUpIcon className="h-2.5 w-2.5" />
-          {repo.ahead}
-        </span>
-      )}
-      {!!repo.behind && (
-        <span className="ml-0.5 inline-flex items-center text-muted-foreground/70">
-          <ArrowDownIcon className="h-2.5 w-2.5" />
-          {repo.behind}
-        </span>
-      )}
-    </>
-  )
-}
-
-export interface GitStatusSummaryProps {
-  repos: GitRepoStatus[]
-  /** Heading above the list — e.g. "Open in VS Code" inside a tooltip. */
-  title?: string
-  className?: string
-}
-
-/**
- * The same information as the chips, stacked one repo per line. Meant for the
- * inside of a tooltip or a popover, where chips would wrap badly — the tooltip
- * itself stays the app's business (the design system doesn't decide what opens
- * it).
- */
-export function GitStatusSummary({ repos, title, className }: GitStatusSummaryProps) {
-  if (!repos.length) return null
-
-  return (
-    <span data-slot="git-status-summary" className={cn("flex flex-col gap-1", className)}>
-      {title && <span className="text-[10px] uppercase tracking-wide opacity-60">{title}</span>}
-      {repos.map((repo) => (
-        <span key={repo.path} className="flex items-center gap-1.5">
-          <span className="font-medium">{repoName(repo)}</span>
-          <GitBranchIcon className="h-3 w-3 opacity-60" />
-          <span className="font-mono">{repo.branch || "—"}</span>
-          <RepoCounters repo={repo} />
-        </span>
-      ))}
-    </span>
-  )
-}

package/src/components/workers/index.ts

@@ -1,35 +0,0 @@
-// @spunto/design-system/workers — Spunto's *domain* components.
-//
-// Deliberately a sub-export rather than part of the main entry: the root of the
-// package stays "primitives with no domain" (a Button knows nothing about a
-// worker), and a third party consuming the design system never has to carry the
-// notion of a worker. New business components go here — see the README's
-// "Domain components" section for the rule.
-
-export { WorkerCard } from "./worker-card"
-export type { WorkerCardProps, LinkRender } from "./worker-card"
-
-export { WorkerStatusDot, WorkerStatusPill, resolveWorkerStatus, workerStatusConfig } from "./worker-status"
-export type { WorkerStatus, WorkerStatusConfig, WorkerStatusKey } from "./worker-status"
-
-export { SetupProgress, StepIndicator, phaseLabel, setupProgress, setupTotalMs } from "./setup-progress"
-export type { SetupProgressProps, StepState } from "./setup-progress"
-
-export { ResourceBars } from "./resource-bars"
-export type { ResourceBarsProps, WorkerStats } from "./resource-bars"
-
-export { GitBranchChips, GitStatusSummary, repoName } from "./git-branch-chips"
-export type { GitBranchChipsProps, GitRepoStatus, GitStatusSummaryProps } from "./git-branch-chips"
-
-export { TagChips } from "./tag-chips"
-export type { TagChipsProps } from "./tag-chips"
-export { tagColor } from "./tag-color"
-export type { TagPalette } from "./tag-color"
-
-export { CreatorAvatar } from "./creator-avatar"
-
-export type { WorkerCardWorker, WorkerCreator, WorkerSetupStatus } from "./types"
-
-// Re-exported here too so a consumer of the worker surface doesn't have to
-// import the root entry just to format the timestamps it feeds these components.
-export { cn, formatDuration, formatRelativeTime } from "../../utils"

package/src/components/workers/resource-bars.tsx

@@ -1,100 +0,0 @@
-// CPU + memory of a running container, as two thin bars.
-//
-// Written identically in the dashboard's card and its table row — the `compact`
-// flag is the only thing that ever differed between the two copies.
-
-import type { ReactNode } from "react"
-import { CpuIcon, MemoryStickIcon } from "lucide-react"
-
-import { cn } from "../../utils"
-
-export interface WorkerStats {
-  cpuPercent: number
-  memUsageMb: number
-  memLimitMb?: number
-  memPercent?: number
-}
-
-export interface ResourceBarsProps {
-  stats: WorkerStats
-  /** Drops the framed panel — just the two bars, for a table cell or a tooltip. */
-  compact?: boolean
-  className?: string
-}
-
-/** Past this, the bar turns red: the container is about to be the problem. */
-const DANGER = 80
-
-export function ResourceBars({ stats, compact = false, className }: ResourceBarsProps) {
-  const cpu = stats.cpuPercent ?? 0
-  const mem = stats.memPercent ?? 0
-
-  return (
-    <div
-      data-slot="resource-bars"
-      className={cn(
-        "grid grid-cols-2 gap-3",
-        !compact && "rounded-lg border border-border/40 bg-muted/20 px-3 py-2.5",
-        className
-      )}
-    >
-      <Metric
-        icon={<CpuIcon className="h-3 w-3" />}
-        label="CPU"
-        value={`${cpu.toFixed(1)}%`}
-        valueClass={cpu > DANGER ? "text-orange-500 dark:text-orange-400" : "text-foreground/70"}
-        percent={cpu}
-        // Flame for CPU, Build amber for memory: two bars side by side need to be
-        // told apart at a glance, and both hues already mean "compute" here.
-        barClass={cpu > DANGER ? "bg-destructive" : "bg-primary"}
-      />
-      <Metric
-        icon={<MemoryStickIcon className="h-3 w-3" />}
-        label="Memory"
-        value={
-          <>
-            {(stats.memUsageMb ?? 0).toFixed(0)}
-            <span className="text-muted-foreground/50"> MB</span>
-          </>
-        }
-        valueClass="text-foreground/70"
-        percent={mem}
-        barClass={mem > DANGER ? "bg-destructive" : "bg-build"}
-      />
-    </div>
-  )
-}
-
-function Metric({
-  icon,
-  label,
-  value,
-  valueClass,
-  percent,
-  barClass,
-}: {
-  icon: ReactNode
-  label: string
-  value: ReactNode
-  valueClass: string
-  percent: number
-  barClass: string
-}) {
-  return (
-    <div>
-      <div className="mb-1.5 flex items-center justify-between">
-        <span className="flex items-center gap-1 text-[11px] text-muted-foreground">
-          {icon}
-          {label}
-        </span>
-        <span className={cn("font-mono text-[11px] tabular-nums", valueClass)}>{value}</span>
-      </div>
-      <div className="h-1 overflow-hidden rounded-full bg-muted">
-        <div
-          className={cn("h-full rounded-full transition-all duration-500 motion-reduce:transition-none", barClass)}
-          style={{ width: `${Math.min(Math.max(percent, 0), 100)}%` }}
-        />
-      </div>
-    </div>
-  )
-}