@spunto/design-system 0.5.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.5.0",
+  "version": "0.6.0",
   "description": "Spunto's shared design system — warm/flame tokens, color constants, and UI primitives.",
   "type": "module",
   "license": "MIT",
@@ -45,6 +45,7 @@
   },
   "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",

package/src/components/terminal.tsx

@@ -42,6 +42,11 @@ export interface TerminalHandle {
   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
@@ -52,6 +57,12 @@ export interface TerminalProps {
    * 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
 }
 
 /**
@@ -61,18 +72,29 @@ export interface TerminalProps {
  * plug in on top.
  */
 const Terminal = forwardRef<TerminalHandle, TerminalProps>(function Terminal(
-  { className, fontSize = 13, scrollback = 5000, onData },
+  { 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) => termRef.current?.write(data),
-      writeln: (data) => termRef.current?.writeln(data),
+      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(),
     }),
@@ -103,6 +125,10 @@ const Terminal = forwardRef<TerminalHandle, TerminalProps>(function Terminal(
 
       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
@@ -113,6 +139,12 @@ const Terminal = forwardRef<TerminalHandle, TerminalProps>(function Terminal(
       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())

package/src/index.ts

@@ -24,7 +24,7 @@ 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"
+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.