silvery 0.0.1 → 0.3.0

package/examples/layout/live-resize.tsx

@@ -0,0 +1,290 @@
+/**
+ * Live Resize Demo
+ *
+ * THE showcase demo for silvery's unique capability: components that know their size.
+ *
+ * Demonstrates:
+ * - useContentRect() providing real-time width/height during render
+ * - Multi-column layout that reflows from 1 to 2 to 3 columns based on width
+ * - Responsive breakpoints with visual feedback
+ * - Content that adapts its presentation based on available space
+ * - No useEffect, no layout thrashing — dimensions are synchronous
+ *
+ * Usage: bun run examples/live-resize/index.tsx
+ *
+ * Try resizing your terminal to see the layout reflow in real-time!
+ *
+ * Controls:
+ *   Esc/q or Ctrl+C - Quit
+ */
+
+import React from "react"
+import { Box, Text, H1, H3, Kbd, Muted, Small, useContentRect } from "../../src/index.js"
+import { run, useInput, type Key } from "@silvery/term/runtime"
+import { useCallback } from "react"
+import { ExampleBanner, type ExampleMeta } from "../_banner.js"
+
+export const meta: ExampleMeta = {
+  name: "Live Resize",
+  description: "Responsive multi-column grid that reflows based on terminal width",
+  features: ["useContentRect()", "responsive breakpoints", "Box flexDirection"],
+}
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface CardData {
+  title: string
+  icon: string
+  value: string
+  detail: string
+  color: string
+  sparkline: string
+}
+
+// ============================================================================
+// Data
+// ============================================================================
+
+const CARDS: CardData[] = [
+  {
+    title: "CPU Usage",
+    icon: "\u{1f4bb}",
+    value: "42%",
+    detail: "4 cores, 2.4 GHz base",
+    color: "green",
+    sparkline: "\u2582\u2583\u2585\u2587\u2586\u2584\u2583\u2585\u2587\u2588\u2586\u2584\u2583\u2582\u2583\u2585",
+  },
+  {
+    title: "Memory",
+    icon: "\u{1f9e0}",
+    value: "8.2 GB",
+    detail: "of 16 GB (51% used)",
+    color: "cyan",
+    sparkline: "\u2584\u2584\u2585\u2585\u2585\u2586\u2586\u2586\u2585\u2585\u2586\u2586\u2587\u2587\u2586\u2586",
+  },
+  {
+    title: "Disk I/O",
+    icon: "\u{1f4be}",
+    value: "234 MB/s",
+    detail: "Read: 180 MB/s Write: 54 MB/s",
+    color: "yellow",
+    sparkline: "\u2581\u2582\u2583\u2587\u2588\u2587\u2584\u2582\u2581\u2582\u2585\u2587\u2586\u2583\u2582\u2581",
+  },
+  {
+    title: "Network",
+    icon: "\u{1f310}",
+    value: "1.2 Gb/s",
+    detail: "In: 800 Mb/s Out: 400 Mb/s",
+    color: "magenta",
+    sparkline: "\u2583\u2584\u2585\u2586\u2587\u2586\u2585\u2584\u2585\u2586\u2587\u2588\u2587\u2586\u2585\u2584",
+  },
+  {
+    title: "Processes",
+    icon: "\u{2699}\u{fe0f}",
+    value: "247",
+    detail: "12 running, 235 sleeping",
+    color: "blue",
+    sparkline: "\u2585\u2585\u2585\u2586\u2585\u2585\u2585\u2585\u2586\u2585\u2585\u2585\u2586\u2585\u2585\u2585",
+  },
+  {
+    title: "Temperature",
+    icon: "\u{1f321}\u{fe0f}",
+    value: "62 C",
+    detail: "Max: 85 C (safe range)",
+    color: "red",
+    sparkline: "\u2583\u2583\u2584\u2584\u2585\u2585\u2586\u2586\u2585\u2585\u2584\u2584\u2583\u2584\u2585\u2585",
+  },
+]
+
+// ============================================================================
+// Components
+// ============================================================================
+
+function MetricCard({ card, compact }: { card: CardData; compact: boolean }): JSX.Element {
+  if (compact) {
+    // Minimal: single-line card for narrow terminals
+    return (
+      <Box borderStyle="round" borderColor={card.color} paddingX={1} flexDirection="row" justifyContent="space-between">
+        <H1 color={card.color}>{card.title}</H1>
+        <H3>{card.value}</H3>
+      </Box>
+    )
+  }
+
+  // Full card with sparkline and details
+  return (
+    <Box borderStyle="round" borderColor={card.color} paddingX={1} flexDirection="column" flexGrow={1}>
+      <Box justifyContent="space-between">
+        <H1 color={card.color}>{card.title}</H1>
+        <H1 color={card.color}>{card.value}</H1>
+      </Box>
+      <Text color={card.color}>{card.sparkline}</Text>
+      <Small>{card.detail}</Small>
+    </Box>
+  )
+}
+
+function BreakpointIndicator({ width, columns }: { width: number; columns: number }): JSX.Element {
+  const breakpoints = [
+    { threshold: 0, cols: 1, label: "< 60" },
+    { threshold: 60, cols: 2, label: "60-99" },
+    { threshold: 100, cols: 3, label: "100+" },
+  ]
+
+  return (
+    <Box gap={2} paddingX={1}>
+      {breakpoints.map((bp) => {
+        const isActive = bp.cols === columns
+        return (
+          <Box key={bp.cols} gap={1}>
+            <Text color={isActive ? "green" : "gray"} bold={isActive}>
+              {isActive ? "\u25cf" : "\u25cb"}
+            </Text>
+            <Text color={isActive ? "white" : "gray"} bold={isActive}>
+              {bp.cols} col{bp.cols > 1 ? "s" : " "} ({bp.label})
+            </Text>
+          </Box>
+        )
+      })}
+    </Box>
+  )
+}
+
+function GridLayout({
+  cards,
+  columns,
+  compact,
+}: {
+  cards: CardData[]
+  columns: number
+  compact: boolean
+}): JSX.Element {
+  if (columns === 1) {
+    return (
+      <Box flexDirection="column" gap={compact ? 0 : 1} flexGrow={1}>
+        {cards.map((card) => (
+          <MetricCard key={card.title} card={card} compact={compact} />
+        ))}
+      </Box>
+    )
+  }
+
+  // Build rows of N columns
+  const rows: CardData[][] = []
+  for (let i = 0; i < cards.length; i += columns) {
+    rows.push(cards.slice(i, i + columns))
+  }
+
+  return (
+    <Box flexDirection="column" gap={1} flexGrow={1}>
+      {rows.map((row, rowIndex) => (
+        <Box key={rowIndex} flexDirection="row" gap={1}>
+          {row.map((card) => (
+            <Box key={card.title} flexGrow={1} flexBasis={0}>
+              <MetricCard card={card} compact={false} />
+            </Box>
+          ))}
+          {/* Fill remaining slots for even spacing */}
+          {row.length < columns &&
+            Array.from({ length: columns - row.length }, (_, i) => (
+              <Box key={`spacer-${i}`} flexGrow={1} flexBasis={0} />
+            ))}
+        </Box>
+      ))}
+    </Box>
+  )
+}
+
+function CodeSnippet({ width }: { width: number }): JSX.Element {
+  const showSnippet = width >= 60
+
+  if (!showSnippet) {
+    return (
+      <Box paddingX={1}>
+        <Text dim italic>
+          (Widen terminal to see the code that powers this)
+        </Text>
+      </Box>
+    )
+  }
+
+  return (
+    <Box flexDirection="column" borderStyle="single" borderColor="$border" paddingX={1}>
+      <H1 color="yellow">How it works:</H1>
+      <Text color="gray">
+        {"  "}
+        <Text color="magenta">const</Text> {"{"} width {"}"} = <Text color="cyan">useContentRect</Text>()
+      </Text>
+      <Text color="gray">
+        {"  "}
+        <Text color="magenta">const</Text> columns = width {">"} 100 ? <Text color="green">3</Text> : width {">"} 60 ?{" "}
+        <Text color="green">2</Text> : <Text color="green">1</Text>
+      </Text>
+      <Text dim italic>
+        {"  "}// No useEffect, no layout thrashing. Synchronous.
+      </Text>
+    </Box>
+  )
+}
+
+// ============================================================================
+// Main App
+// ============================================================================
+
+function LiveResize(): JSX.Element {
+  const { width, height } = useContentRect()
+
+  // Responsive breakpoints
+  const columns = width >= 100 ? 3 : width >= 60 ? 2 : 1
+  const compact = height < 20 || width < 40
+
+  useInput(
+    useCallback((input: string, key: Key) => {
+      if (input === "q" || key.escape || (key.ctrl && input === "c")) {
+        return "exit"
+      }
+    }, []),
+  )
+
+  return (
+    <Box flexDirection="column" width="100%" height="100%" padding={1}>
+      {/* Breakpoint indicator */}
+      <BreakpointIndicator width={width} columns={columns} />
+
+      {/* Main grid */}
+      <Box flexGrow={1} flexDirection="column" marginTop={1}>
+        <GridLayout cards={CARDS} columns={columns} compact={compact} />
+      </Box>
+
+      {/* Code snippet showing how it works */}
+      {!compact && <CodeSnippet width={width} />}
+
+      {/* Footer */}
+      <Box justifyContent="space-between" paddingX={1}>
+        <Muted>Resize your terminal to see the layout reflow</Muted>
+        <Muted>
+          <Kbd>Esc/q</Kbd> quit
+        </Muted>
+      </Box>
+    </Box>
+  )
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+async function main() {
+  const handle = await run(
+    <ExampleBanner meta={meta} controls="Resize terminal to see reflow  Esc/q quit">
+      <LiveResize />
+    </ExampleBanner>,
+  )
+  await handle.waitUntilExit()
+}
+
+if (import.meta.main) {
+  main().catch(console.error)
+}

package/examples/layout/overflow.tsx

@@ -0,0 +1,51 @@
+import React from "react"
+import { render, Box, Text, useApp, useInput, createTerm } from "../../src/index.js"
+import { ExampleBanner, type ExampleMeta } from "../_banner.js"
+
+export const meta: ExampleMeta = {
+  name: "Overflow",
+  description: 'overflow="hidden" content clipping demonstration',
+  features: ['overflow="hidden"', "Box height"],
+}
+
+export function OverflowApp() {
+  const { exit } = useApp()
+  useInput((input, key) => {
+    if (input === "q" || key.escape) exit()
+  })
+
+  return (
+    <Box flexDirection="column" padding={1}>
+      <Text color="yellow">Title</Text>
+
+      <Box borderStyle="single" borderColor="$primary" height={5} overflow="hidden">
+        <Box flexDirection="column" flexGrow={1}>
+          <Text>Line 1</Text>
+          <Text>Line 2</Text>
+          <Text>Line 3</Text>
+          <Text>Line 4</Text>
+          <Text>Line 5</Text>
+          <Text>Line 6 - should NOT appear</Text>
+          <Text>Line 7 - should NOT appear</Text>
+        </Box>
+      </Box>
+
+      <Text color="$success">This should NOT be corrupted</Text>
+    </Box>
+  )
+}
+
+async function main() {
+  using term = createTerm()
+  const { waitUntilExit } = await render(
+    <ExampleBanner meta={meta} controls="Esc/q quit">
+      <OverflowApp />
+    </ExampleBanner>,
+    term,
+  )
+  await waitUntilExit()
+}
+
+if (import.meta.main) {
+  main().catch(console.error)
+}

package/examples/playground/README.md

@@ -0,0 +1,69 @@
+# Silvery Canvas Playground
+
+Interactive browser demo of Silvery's Canvas 2D adapter. Renders React components to an HTML5 `<canvas>` element using the same layout engine and rendering pipeline as the terminal adapter.
+
+## Quick Start
+
+```bash
+# Build the playground bundle
+cd vendor/silvery
+bun run examples/playground/build.ts
+
+# Open in browser
+open examples/playground/index.html
+```
+
+No dev server required -- just open `index.html` directly in any modern browser.
+
+## What It Shows
+
+The playground includes seven preset examples accessible via buttons or number keys (1-7):
+
+| #   | Preset     | Demonstrates                                              |
+| --- | ---------- | --------------------------------------------------------- |
+| 1   | Hello      | Basic Box + Text, `useContentRect()` size display         |
+| 2   | Text       | Bold, italic, underline styles (single/double/curly/etc.) |
+| 3   | Colors     | Named ANSI colors, hex, RGB, background fills             |
+| 4   | Flexbox    | Row/column layouts, `flexGrow`, `gap`, nested panels      |
+| 5   | Borders    | single, double, round, bold border styles                 |
+| 6   | Dashboard  | Multi-panel system monitor layout                         |
+| 7   | Responsive | Layout adapts between horizontal/vertical based on width  |
+
+Resize the browser window to see layouts recompute. The canvas size is shown in the bottom-right corner.
+
+## Architecture
+
+The playground uses the same rendering pipeline as Silvery's terminal mode:
+
+```
+React JSX
+  |  React reconciler builds SilveryNode tree
+  v
+Flexily layout engine (pure JS flexbox)
+  |  Computes { x, y, width, height } for every node
+  v
+Canvas adapter (CanvasRenderBuffer)
+  |  drawText(), fillRect(), drawChar() to OffscreenCanvas
+  v
+Visible <canvas> element
+  |  ctx.drawImage(offscreenCanvas, 0, 0)
+  v
+Browser display
+```
+
+Key files:
+
+- `src/adapters/canvas-adapter.ts` -- Canvas `RenderAdapter` implementation
+- `src/canvas/index.ts` -- `renderToCanvas()` entry point and React integration
+- `src/render-adapter.ts` -- The `RenderAdapter` interface shared by all targets
+
+## Building a Full Playground (Live JSX Editing)
+
+A static HTML page cannot bundle a JSX transpiler. For a full live-editing experience with Monaco editor, see `docs/playground-design.md`. The architecture uses:
+
+- **Vite** for dev server and HMR
+- **Monaco Editor** for JSX editing with TypeScript intellisense
+- **Sucrase** (in-browser) for JSX transpilation
+- **silvery/canvas** for rendering the user's components
+
+Deployment targets: GitHub Pages (static export), StackBlitz (zero-install), or self-hosted.

package/examples/playground/build.ts

@@ -0,0 +1,61 @@
+#!/usr/bin/env bun
+/**
+ * Build the Canvas Playground
+ *
+ * Bundles the playground React app for browser usage.
+ * Run: bun run examples/playground/build.ts
+ */
+
+import { mkdir } from "node:fs/promises"
+import { join, dirname } from "node:path"
+
+const __dirname = dirname(new URL(import.meta.url).pathname)
+const distDir = join(__dirname, "dist")
+
+// Ensure dist directory exists
+await mkdir(distDir, { recursive: true })
+
+// Browser-safe defines for Node.js globals.
+// loggily and @silvery/ansi access process.env at module init,
+// which throws ReferenceError in browsers where `process` is undefined.
+const browserDefines: Record<string, string> = {
+  "process.env.NODE_ENV": '"production"',
+  "process.env.LOG_LEVEL": "undefined",
+  "process.env.TRACE": "undefined",
+  "process.env.TRACE_FORMAT": "undefined",
+  "process.env.DEBUG": "undefined",
+  "process.env.NO_COLOR": "undefined",
+  "process.env.FORCE_COLOR": "undefined",
+  "process.env.TERM": "undefined",
+  "process.env.TERM_PROGRAM": "undefined",
+  "process.env.COLORTERM": "undefined",
+  "process.env.CI": "undefined",
+  "process.env.GITHUB_ACTIONS": "undefined",
+  "process.env.KITTY_WINDOW_ID": "undefined",
+  "process.env.WT_SESSION": "undefined",
+  "process.env.LANG": "undefined",
+  "process.env.LC_ALL": "undefined",
+  "process.env.LC_CTYPE": "undefined",
+}
+
+const result = await Bun.build({
+  entrypoints: [join(__dirname, "playground-app.tsx")],
+  outdir: distDir,
+  target: "browser",
+  format: "esm",
+  minify: false,
+  sourcemap: "external",
+  define: browserDefines,
+})
+
+if (!result.success) {
+  console.error("Playground build failed:")
+  for (const log of result.logs) {
+    console.error(log)
+  }
+  process.exit(1)
+}
+
+console.log("Built examples/playground/dist/playground-app.js")
+console.log("\nOpen in browser:")
+console.log("  examples/playground/index.html")