silvery 0.3.0 → 0.4.0

package/examples/runtime/pipe-composition.tsx

@@ -1,184 +0,0 @@
-/**
- * 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

@@ -1,78 +0,0 @@
-/**
- * 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

@@ -1,197 +0,0 @@
-/**
- * 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)
-}