silvery 0.0.1 → 0.3.0

package/examples/runtime/pipe-composition.tsx

@@ -0,0 +1,184 @@
+/**
+ * Pipe Composition - Plugin System Example
+ *
+ * Demonstrates the full pipe() composition pattern — silvery's
+ * plugin system for building apps from composable pieces.
+ *
+ * Each plugin is a function (app) => enhancedApp that adds one
+ * capability. pipe() chains them left-to-right:
+ *
+ *   pipe(base, p1, p2, p3)  =  p3(p2(p1(base)))
+ *
+ * This example builds a selectable list using:
+ *   - createApp()      — Zustand store for list state
+ *   - withReact()      — binds the React element
+ *   - withTerminal()   — binds stdin/stdout for terminal I/O
+ *
+ * Usage: bun examples/runtime/pipe-composition.tsx
+ *
+ * Controls:
+ *   j/k       - Move selection down/up
+ *   Space/x   - Toggle item
+ *   a         - Add new item
+ *   Esc/q     - Quit
+ */
+
+import React from "react"
+import { Box, Text, H3, Muted, Small } from "../../src/index.js"
+import { createApp, useApp } from "@silvery/term/runtime"
+import { pipe, withReact, withTerminal } from "@silvery/tea/plugins"
+import { ExampleBanner, type ExampleMeta } from "../_banner.js"
+
+export const meta: ExampleMeta = {
+  name: "Pipe Composition",
+  description: "Plugin system: pipe() composes createApp + withReact + withTerminal",
+  features: ["pipe()", "withReact()", "withTerminal()", "createApp()"],
+}
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface ListItem {
+  id: number
+  label: string
+  selected: boolean
+}
+
+interface State {
+  items: ListItem[]
+  cursor: number
+  nextId: number
+}
+
+// ============================================================================
+// Components
+// ============================================================================
+
+function Item({ item, isCursor }: { item: ListItem; isCursor: boolean }) {
+  const check = item.selected ? "◉" : "○"
+  return (
+    <Box>
+      <Text color={isCursor ? "$primary" : "$muted"}>{isCursor ? "❯ " : "  "}</Text>
+      <Text color={item.selected ? "$success" : undefined}>
+        {check} {item.label}
+      </Text>
+    </Box>
+  )
+}
+
+function SelectableList() {
+  const items = useApp((s: State) => s.items)
+  const cursor = useApp((s: State) => s.cursor)
+
+  const selectedCount = items.filter((i) => i.selected).length
+
+  return (
+    <Box flexDirection="column" padding={1}>
+      <H3>Select items:</H3>
+      <Text> </Text>
+      {items.map((item, i) => (
+        <Item key={item.id} item={item} isCursor={i === cursor} />
+      ))}
+      {items.length === 0 && <Muted>No items. Press 'a' to add one.</Muted>}
+      <Text> </Text>
+      <Muted>
+        {selectedCount}/{items.length} selected
+      </Muted>
+      <Text> </Text>
+      <Small>j/k: move • space/x: toggle • a: add • Esc/q: quit</Small>
+    </Box>
+  )
+}
+
+// ============================================================================
+// App — the pipe() composition pattern
+// ============================================================================
+
+// Step 1: Define the app with createApp()
+//
+// createApp() takes a store factory and event handlers.
+// It returns an AppDefinition with a run(element, options) method.
+const baseApp = createApp<Record<string, unknown>, State>(
+  // Store factory: (providers) => zustand StateCreator
+  () => (set) => ({
+    items: [
+      { id: 1, label: "Read the docs", selected: false },
+      { id: 2, label: "Try pipe() composition", selected: true },
+      { id: 3, label: "Build something", selected: false },
+      { id: 4, label: "Ship it", selected: false },
+    ],
+    cursor: 0,
+    nextId: 5,
+  }),
+
+  // Event handlers: 'provider:event' → handler
+  {
+    "term:key": (
+      data: unknown,
+      { get, set }: { get: () => State; set: (fn: (s: State) => Partial<State>) => void },
+    ) => {
+      const { input: k, key } = data as { input: string; key: { escape: boolean } }
+      const { items, cursor, nextId } = get()
+
+      if (key.escape || k === "q") return "exit"
+
+      switch (k) {
+        case "j":
+          set(() => ({ cursor: Math.min(cursor + 1, items.length - 1) }))
+          break
+        case "k":
+          set(() => ({ cursor: Math.max(cursor - 1, 0) }))
+          break
+        case " ":
+        case "x":
+          set(() => ({
+            items: items.map((item, i) => (i === cursor ? { ...item, selected: !item.selected } : item)),
+          }))
+          break
+        case "a":
+          set(() => ({
+            items: [...items, { id: nextId, label: `Item ${nextId}`, selected: false }],
+            nextId: nextId + 1,
+          }))
+          break
+      }
+    },
+  },
+)
+
+// Step 2: Compose with pipe()
+//
+// pipe() chains plugins left-to-right. Each plugin wraps run():
+//   - withReact(<App />)    → binds the element, so run() needs no JSX
+//   - withTerminal(process) → binds stdin/stdout, so run() needs no options
+//
+// The result is an app where run() takes no arguments.
+const app = pipe(
+  baseApp,
+  withReact(
+    <ExampleBanner meta={meta} controls="j/k move  space/x toggle  a add  Esc/q quit">
+      <SelectableList />
+    </ExampleBanner>,
+  ),
+  withTerminal(process),
+)
+
+// ============================================================================
+// Main
+// ============================================================================
+
+async function main() {
+  // Step 3: Run — no arguments needed, everything is composed
+  const handle = await app.run()
+
+  await handle.waitUntilExit()
+
+  const { items } = handle.store.getState()
+  const selected = items.filter((i) => i.selected)
+  console.log(`\nSelected ${selected.length} items:`, selected.map((i) => i.label).join(", "))
+}
+
+if (import.meta.main) {
+  main().catch(console.error)
+}

package/examples/runtime/run-counter.tsx

@@ -0,0 +1,78 @@
+/**
+ * Run Counter - Layer 2 Example
+ *
+ * Demonstrates run() with React hooks (useState, useEffect)
+ * and useInput for keyboard handling.
+ *
+ * This is the simplest way to build an interactive TUI app.
+ * Under the hood, run() creates a createApp() with an empty store
+ * and renders the element — it's sugar over the Layer 3 pipe() pattern:
+ *
+ *   run(<App />)
+ *   // is equivalent to:
+ *   pipe(createApp(() => () => ({})), withReact(<App />), withTerminal(process)).run()
+ *
+ * Use run() when component-local state (useState) is sufficient.
+ * Use pipe() + createApp() when you need shared state (Zustand store).
+ *
+ * Usage: bun examples/runtime/run-counter.tsx
+ *
+ * Controls:
+ *   j/k - Increment/decrement counter
+ *   r   - Reset to 0
+ *   Esc/q - Quit
+ */
+
+import React, { useState, useCallback } from "react"
+import { Box, Text, Small } from "../../src/index.js"
+import { run, useInput, type Key } from "@silvery/term/runtime"
+import { ExampleBanner, type ExampleMeta } from "../_banner.js"
+
+export const meta: ExampleMeta = {
+  name: "Run Counter",
+  description: "Layer 2: run() with React hooks and useRuntimeInput",
+  features: ["run()", "useState", "useInput"],
+}
+
+function Counter() {
+  const [count, setCount] = useState(0)
+
+  useInput(
+    useCallback((input: string, key: Key) => {
+      if (input === "j") setCount((c) => c + 1)
+      if (input === "k") setCount((c) => c - 1)
+      if (input === "r") setCount(0)
+      if (input === "q" || key.escape) return "exit"
+    }, []),
+  )
+
+  return (
+    <Box flexDirection="column" padding={1}>
+      <Box>
+        <Text>Count: </Text>
+        <Text bold color={count >= 0 ? "green" : "red"}>
+          {count}
+        </Text>
+      </Box>
+      <Text> </Text>
+      <Small>j/k: increment/decrement • r: reset • Esc/q: quit</Small>
+    </Box>
+  )
+}
+
+async function main() {
+  const handle = await run(
+    <ExampleBanner meta={meta} controls="j/k inc/dec  r reset  Esc/q quit">
+      <Counter />
+    </ExampleBanner>,
+  )
+
+  // Wait until user presses q
+  await handle.waitUntilExit()
+
+  console.log("\nGoodbye!")
+}
+
+if (import.meta.main) {
+  main().catch(console.error)
+}

package/examples/runtime/runtime-counter.tsx

@@ -0,0 +1,197 @@
+/**
+ * Runtime Counter Example
+ *
+ * Demonstrates the createRuntime() API (Layer 1):
+ * - Runtime handles diffing internally
+ * - events() provides AsyncIterable event stream
+ * - schedule() for async effects
+ * - Clean disposal with Symbol.dispose
+ *
+ * This is the recommended way to build custom event loops.
+ *
+ * Usage: bun examples/runtime-counter.tsx
+ */
+
+import React from "react"
+import { Box, Text, H3, Small } from "../../src/index.js"
+import {
+  createRuntime,
+  ensureLayoutEngine,
+  layout,
+  type Dims,
+  type Event,
+  type RenderTarget,
+} from "@silvery/term/runtime"
+import type { ExampleMeta } from "../_banner.js"
+
+export const meta: ExampleMeta = {
+  name: "Runtime Counter",
+  description: "Layer 1 event loop: events() AsyncIterable + schedule()",
+  features: ["createRuntime()", "event loop", "dispatch()"],
+}
+
+// ============================================================================
+// State & Types
+// ============================================================================
+
+interface State {
+  count: number
+}
+
+// ============================================================================
+// Reducer (pure function)
+// ============================================================================
+
+function reducer(state: State, event: Event): State {
+  switch (event.type) {
+    case "resize":
+      // Just trigger re-render, state unchanged
+      return state
+    case "effect":
+      // Effect completed - increment count
+      // Note: event.id is auto-generated ("effect-0", "effect-1", ...),
+      // event.result is whatever schedule() callback returned
+      if (event.result === "increment") {
+        return { ...state, count: state.count + 1 }
+      }
+      return state
+    default:
+      return state
+  }
+}
+
+// ============================================================================
+// View (pure function)
+// ============================================================================
+
+function view(state: State, dims: Dims): React.ReactElement {
+  return (
+    <Box flexDirection="column" padding={1}>
+      <H3>Runtime Counter Example</H3>
+      <Text> </Text>
+      <Text>
+        Count: <Text color="green">{state.count}</Text>
+      </Text>
+      <Text> </Text>
+      <Small>
+        Terminal: {dims.cols}x{dims.rows}
+      </Small>
+      <Small>Press Ctrl+C to quit</Small>
+    </Box>
+  )
+}
+
+// ============================================================================
+// Terminal Target
+// ============================================================================
+
+function createTerminalTarget(): RenderTarget & { cleanup: () => void } {
+  const resizeHandlers = new Set<(dims: Dims) => void>()
+
+  const onResizeHandler = () => {
+    const dims = {
+      cols: process.stdout.columns || 80,
+      rows: process.stdout.rows || 24,
+    }
+    for (const handler of resizeHandlers) {
+      handler(dims)
+    }
+  }
+
+  process.stdout.on("resize", onResizeHandler)
+
+  return {
+    write(frame: string): void {
+      process.stdout.write(frame)
+    },
+
+    getDims(): Dims {
+      return {
+        cols: process.stdout.columns || 80,
+        rows: process.stdout.rows || 24,
+      }
+    },
+
+    onResize(handler: (dims: Dims) => void): () => void {
+      resizeHandlers.add(handler)
+      return () => resizeHandlers.delete(handler)
+    },
+
+    cleanup(): void {
+      process.stdout.off("resize", onResizeHandler)
+    },
+  }
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+async function main() {
+  // Initialize layout engine
+  await ensureLayoutEngine()
+
+  // Create terminal target
+  const target = createTerminalTarget()
+
+  // Create runtime with abort signal for cleanup
+  const controller = new AbortController()
+  const runtime = createRuntime({ target, signal: controller.signal })
+
+  // Handle Ctrl+C
+  process.on("SIGINT", () => {
+    controller.abort()
+  })
+
+  // Initial state
+  let state: State = { count: 0 }
+
+  // Clear screen and hide cursor
+  process.stdout.write("\x1b[2J\x1b[H\x1b[?25l")
+
+  try {
+    // Initial render
+    runtime.render(layout(view(state, runtime.getDims()), runtime.getDims()))
+
+    // Schedule periodic increments using effects
+    const scheduleIncrement = () => {
+      runtime.schedule(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 1000))
+        return "increment"
+      })
+    }
+
+    // Start first increment
+    scheduleIncrement()
+
+    // Event loop
+    for await (const event of runtime.events()) {
+      // Update state
+      const newState = reducer(state, event)
+
+      // Re-render if state changed or resize occurred
+      if (newState !== state || event.type === "resize") {
+        state = newState
+        runtime.render(layout(view(state, runtime.getDims()), runtime.getDims()))
+      }
+
+      // Schedule next increment after effect completes
+      if (event.type === "effect" && event.id.startsWith("effect-")) {
+        scheduleIncrement()
+      }
+    }
+  } finally {
+    // Cleanup
+    runtime[Symbol.dispose]()
+    target.cleanup()
+
+    // Show cursor and reset
+    process.stdout.write("\x1b[?25h\x1b[0m\n")
+    console.log("Final count:", state.count)
+  }
+}
+
+// Run
+if (import.meta.main) {
+  main().catch(console.error)
+}