@silvery/tea 0.3.0

package/src/with-dom-events.ts

@@ -0,0 +1,168 @@
+/**
+ * withDomEvents() — Plugin for DOM-style event dispatch
+ *
+ * Wires mouse event dispatch through the render tree:
+ * - Hit testing via screenRect (tree-based, not manual registry)
+ * - Bubbling from target → root with stopPropagation() support
+ * - mouseenter/mouseleave tracking (no bubble, per DOM spec)
+ * - Double-click detection (300ms / 2-cell threshold)
+ * - Click-to-focus (focuses nearest focusable ancestor on mousedown)
+ *
+ * Mouse event handler props (onClick, onMouseDown, etc.) are already
+ * defined on BoxProps/TextProps via MouseEventProps. This plugin wires
+ * the dispatch that invokes them.
+ *
+ * @example
+ * ```tsx
+ * import { pipe, withDomEvents } from '@silvery/tea'
+ *
+ * const app = pipe(
+ *   baseApp,
+ *   withFocus(),
+ *   withDomEvents(),
+ * )
+ *
+ * // Components can now use mouse event handlers
+ * function Button() {
+ *   return (
+ *     <Box onClick={(e) => {
+ *       console.log('clicked at', e.clientX, e.clientY)
+ *       e.stopPropagation()
+ *     }}>
+ *       <Text>Click me</Text>
+ *     </Box>
+ *   )
+ * }
+ *
+ * // Programmatic mouse events also dispatch through the tree
+ * await app.click(10, 5)
+ * await app.wheel(10, 5, 1)
+ * ```
+ */
+
+import type { App } from "@silvery/term/app"
+import type { FocusManager } from "./focus-manager"
+import {
+  createMouseEventProcessor,
+  processMouseEvent,
+  type MouseEventProcessorOptions,
+  type MouseEventProcessorState,
+} from "@silvery/term/mouse-events"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Options for withDomEvents.
+ */
+export interface WithDomEventsOptions {
+  /** Focus manager for click-to-focus behavior.
+   *  If the app has a focusManager property, it's used automatically. */
+  focusManager?: FocusManager
+}
+
+// =============================================================================
+// Implementation
+// =============================================================================
+
+/**
+ * Add DOM-style mouse event dispatch to an App.
+ *
+ * This plugin creates a mouse event processor and ensures that
+ * click(), doubleClick(), and wheel() methods on the app dispatch
+ * events through the render tree with proper bubbling.
+ *
+ * The App's buildApp() already sets up mouse event processing.
+ * This plugin is provided for explicit composition via pipe()
+ * and ensures the focus manager is connected for click-to-focus.
+ *
+ * @param options - Configuration (focusManager for click-to-focus)
+ * @returns Plugin function that enhances an App with DOM event dispatch
+ */
+export function withDomEvents(options: WithDomEventsOptions = {}): <T extends App>(app: T) => T {
+  return <T extends App>(app: T): T => {
+    // Get focus manager from options or from the app itself
+    const fm = options.focusManager ?? (app as App & { focusManager?: FocusManager }).focusManager
+
+    // Create a mouse event processor with the focus manager
+    const processorOptions: MouseEventProcessorOptions = {}
+    if (fm) {
+      processorOptions.focusManager = fm
+    }
+    const mouseState = createMouseEventProcessor(processorOptions)
+
+    // Override click, doubleClick, and wheel to use our processor
+    // which is connected to the focus manager
+    return new Proxy(app, {
+      get(target, prop, receiver) {
+        if (prop === "click") {
+          return async function enhancedClick(x: number, y: number, clickOptions?: { button?: number }): Promise<T> {
+            const button = clickOptions?.button ?? 0
+            const root = target.getContainer()
+            processMouseEvent(
+              mouseState,
+              { button, x, y, action: "down", shift: false, meta: false, ctrl: false },
+              root,
+            )
+            processMouseEvent(mouseState, { button, x, y, action: "up", shift: false, meta: false, ctrl: false }, root)
+            await Promise.resolve()
+            return receiver as T
+          }
+        }
+
+        if (prop === "doubleClick") {
+          return async function enhancedDoubleClick(
+            x: number,
+            y: number,
+            clickOptions?: { button?: number },
+          ): Promise<T> {
+            const button = clickOptions?.button ?? 0
+            const root = target.getContainer()
+            const parsed = {
+              button,
+              x,
+              y,
+              action: "down" as const,
+              shift: false,
+              meta: false,
+              ctrl: false,
+            }
+            // First click
+            processMouseEvent(mouseState, parsed, root)
+            processMouseEvent(mouseState, { ...parsed, action: "up" }, root)
+            // Second click (triggers double-click detection)
+            processMouseEvent(mouseState, parsed, root)
+            processMouseEvent(mouseState, { ...parsed, action: "up" }, root)
+            await Promise.resolve()
+            return receiver as T
+          }
+        }
+
+        if (prop === "wheel") {
+          return async function enhancedWheel(x: number, y: number, delta: number): Promise<T> {
+            const root = target.getContainer()
+            processMouseEvent(
+              mouseState,
+              {
+                button: 0,
+                x,
+                y,
+                action: "wheel",
+                delta,
+                shift: false,
+                meta: false,
+                ctrl: false,
+              },
+              root,
+            )
+            await Promise.resolve()
+            return receiver as T
+          }
+        }
+
+        return Reflect.get(target, prop, receiver)
+      },
+    }) as T
+  }
+}

package/src/with-focus.ts

@@ -0,0 +1,162 @@
+/**
+ * withFocus() — Plugin for Tab/Shift+Tab focus navigation
+ *
+ * Intercepts `press()` calls to handle focus navigation keys:
+ * - Tab → focus next
+ * - Shift+Tab → focus previous
+ * - Escape → blur (when something is focused)
+ *
+ * Also provides focus scope management and dispatches focus/blur
+ * events through the render tree.
+ *
+ * @example
+ * ```tsx
+ * import { pipe, withFocus } from '@silvery/tea'
+ *
+ * const app = pipe(
+ *   baseApp,
+ *   withFocus(),
+ * )
+ *
+ * // Tab/Shift+Tab now cycle focus through focusable nodes
+ * await app.press('Tab')
+ * await app.press('Shift+Tab')
+ *
+ * // Focus manager is accessible
+ * app.focusManager.activeId  // currently focused testID
+ * ```
+ */
+
+import type { App } from "@silvery/term/app"
+import { createFocusManager, type FocusManager, type FocusManagerOptions } from "./focus-manager"
+import { createFocusEvent, createKeyEvent, dispatchFocusEvent, dispatchKeyEvent } from "./focus-events"
+import { parseHotkey, parseKey } from "./keys"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Options for withFocus.
+ */
+export interface WithFocusOptions {
+  /** Custom focus manager (creates a new one if not provided) */
+  focusManager?: FocusManager
+  /** Focus manager options (ignored if focusManager is provided) */
+  focusManagerOptions?: FocusManagerOptions
+  /** Handle Tab key for focus cycling (default: true) */
+  handleTab?: boolean
+  /** Handle Escape key to blur (default: true) */
+  handleEscape?: boolean
+  /** Dispatch keyboard events through focus tree (default: true) */
+  dispatchKeyEvents?: boolean
+}
+
+/**
+ * App enhanced with focus management.
+ */
+export type AppWithFocus = App & {
+  /** The focus manager instance */
+  readonly focusManager: FocusManager
+}
+
+// =============================================================================
+// Implementation
+// =============================================================================
+
+/**
+ * Add focus management to an App.
+ *
+ * Intercepts key presses for focus navigation (Tab/Shift+Tab/Escape)
+ * and optionally dispatches keyboard events through the focus tree
+ * with capture/target/bubble phases.
+ *
+ * @param options - Focus configuration (all defaults are sensible)
+ * @returns Plugin function that enhances an App with focus management
+ */
+export function withFocus(options: WithFocusOptions = {}): (app: App) => AppWithFocus {
+  return (app: App): AppWithFocus => {
+    const { handleTab = true, handleEscape = true, dispatchKeyEvents = true } = options
+
+    // Create or reuse focus manager
+    const fm =
+      options.focusManager ??
+      createFocusManager({
+        ...options.focusManagerOptions,
+        // Wire up focus change events to dispatch through the tree
+        onFocusChange: (oldNode, newNode, origin) => {
+          // Call user's callback too if provided
+          options.focusManagerOptions?.onFocusChange?.(oldNode, newNode, origin)
+
+          // Dispatch blur event on old node
+          if (oldNode) {
+            const blurEvent = createFocusEvent("blur", oldNode, newNode)
+            dispatchFocusEvent(blurEvent)
+          }
+
+          // Dispatch focus event on new node
+          if (newNode) {
+            const focusEvent = createFocusEvent("focus", newNode, oldNode)
+            dispatchFocusEvent(focusEvent)
+          }
+        },
+      })
+
+    // Wrap press() to intercept focus navigation keys
+    const originalPress = app.press.bind(app)
+
+    const enhancedApp = new Proxy(app, {
+      get(target, prop, receiver) {
+        if (prop === "focusManager") {
+          return fm
+        }
+
+        if (prop === "press") {
+          return async function focusPress(keyStr: string): Promise<typeof enhancedApp> {
+            const { key, shift } = parseHotkey(keyStr)
+
+            const root = target.getContainer()
+
+            // Tab → focus next
+            if (handleTab && key === "Tab" && !shift) {
+              fm.focusNext(root)
+              return enhancedApp
+            }
+
+            // Shift+Tab → focus previous
+            if (handleTab && key === "Tab" && shift) {
+              fm.focusPrev(root)
+              return enhancedApp
+            }
+
+            // Escape → blur (only when something is focused)
+            if (handleEscape && key === "Escape" && fm.activeElement) {
+              fm.blur()
+              return enhancedApp
+            }
+
+            // Dispatch keyboard event through focus tree before passing through
+            if (dispatchKeyEvents && fm.activeElement) {
+              const [input, parsedKey] = parseKey(keyStr)
+              const keyEvent = createKeyEvent(input, parsedKey, fm.activeElement)
+              dispatchKeyEvent(keyEvent)
+
+              // If the event was handled (stopPropagation), don't pass through
+              if (keyEvent.propagationStopped || keyEvent.defaultPrevented) {
+                return enhancedApp
+              }
+            }
+
+            // Pass through to original press handler
+            await originalPress(keyStr)
+            return enhancedApp
+          }
+        }
+
+        return Reflect.get(target, prop, receiver)
+      },
+    }) as AppWithFocus
+
+    return enhancedApp
+  }
+}

package/src/with-keybindings.ts

@@ -0,0 +1,180 @@
+/**
+ * withKeybindings - SlateJS-style plugin for keybinding wiring
+ *
+ * Intercepts `press()` calls and routes them to commands via keybinding resolution.
+ * Commands not in the registry fall through to component useInput handlers.
+ *
+ * @example
+ * ```tsx
+ * const app = withKeybindings(withCommands(render(<Board />), cmdOpts), {
+ *   bindings: defaultKeybindings,
+ *   getKeyContext: () => ({ mode: 'normal', hasSelection: false, ... }),
+ * })
+ *
+ * // Press 'j' → resolves to cursor_down → calls app.cmd.down()
+ * await app.press('j')
+ *
+ * // Press 'x' (no binding) → passes through to useInput handlers
+ * await app.press('x')
+ * ```
+ *
+ * See docs/future/silvery-command-api-research.md for design rationale.
+ */
+
+import type { AppWithCommands, KeybindingDef } from "./with-commands"
+import { parseHotkey } from "./keys"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Context for keybinding resolution.
+ * Used to match mode-specific bindings and conditional bindings.
+ */
+export interface KeybindingContext {
+  mode: string
+  hasSelection: boolean
+  [key: string]: unknown
+}
+
+/**
+ * Options for withKeybindings.
+ */
+export interface WithKeybindingsOptions {
+  /** Keybindings to resolve */
+  bindings: KeybindingDef[]
+  /** Build context for keybinding resolution */
+  getKeyContext: () => KeybindingContext
+}
+
+/**
+ * Extended keybinding with mode support.
+ */
+export interface ExtendedKeybindingDef extends KeybindingDef {
+  modes?: string[]
+  when?: (ctx: KeybindingContext) => boolean
+}
+
+// =============================================================================
+// Implementation
+// =============================================================================
+
+// parseKey replaced by parseHotkey from ./keys.js
+
+/**
+ * Resolve a key press to a command ID using keybinding lookup.
+ */
+function resolveKeybinding(
+  key: string,
+  modifiers: { ctrl: boolean; meta: boolean; shift: boolean; super: boolean },
+  bindings: ExtendedKeybindingDef[],
+  ctx: KeybindingContext,
+): string | null {
+  for (const binding of bindings) {
+    // Check key match
+    if (binding.key !== key) continue
+
+    // Check modifiers
+    if (!!binding.ctrl !== !!modifiers.ctrl) continue
+    if (!!binding.opt !== !!modifiers.meta) continue
+    if (!!binding.cmd !== !!modifiers.super) continue
+
+    // For single uppercase letters (A-Z), the shift key is implicit
+    const isUppercaseLetter = key.length === 1 && key >= "A" && key <= "Z" && !binding.shift
+    if (!isUppercaseLetter && !!binding.shift !== !!modifiers.shift) continue
+
+    // alt removed — macOS uses opt (⌥), matched against modifiers.meta above
+
+    // Check mode
+    if (binding.modes && binding.modes.length > 0) {
+      if (!binding.modes.includes(ctx.mode)) continue
+    }
+
+    // Check conditional
+    if (binding.when && !binding.when(ctx)) continue
+
+    return binding.commandId
+  }
+  return null
+}
+
+/**
+ * Wire keybindings to command invocation.
+ *
+ * Intercepts `press()` and routes matching keys to commands.
+ * Non-matching keys pass through to the original press handler.
+ *
+ * Supports two calling styles:
+ * - Direct: `withKeybindings(app, options)` — returns enhanced app immediately
+ * - Curried: `withKeybindings(options)` — returns a plugin for pipe() composition
+ *
+ * @example Direct
+ * ```tsx
+ * const app = withKeybindings(appWithCmd, {
+ *   bindings: defaultKeybindings,
+ *   getKeyContext: () => buildKeybindingContext(state),
+ * })
+ * ```
+ *
+ * @example Curried (pipe)
+ * ```tsx
+ * const app = pipe(
+ *   baseApp,
+ *   withCommands(cmdOpts),
+ *   withKeybindings({
+ *     bindings: defaultKeybindings,
+ *     getKeyContext: () => buildKeybindingContext(state),
+ *   }),
+ * )
+ * ```
+ */
+// Curried form: withKeybindings(options) => plugin
+export function withKeybindings(options: WithKeybindingsOptions): <T extends AppWithCommands>(app: T) => T
+// Direct form: withKeybindings(app, options) => enhancedApp
+export function withKeybindings<T extends AppWithCommands>(app: T, options: WithKeybindingsOptions): T
+export function withKeybindings<T extends AppWithCommands>(
+  appOrOptions: T | WithKeybindingsOptions,
+  maybeOptions?: WithKeybindingsOptions,
+): T | (<U extends AppWithCommands>(app: U) => U) {
+  // Curried form: first arg is options (no press/text/ansi = not an App)
+  if (maybeOptions === undefined) {
+    const options = appOrOptions as WithKeybindingsOptions
+    return <U extends AppWithCommands>(app: U) => applyKeybindings(app, options)
+  }
+  // Direct form: first arg is app
+  return applyKeybindings(appOrOptions as T, maybeOptions)
+}
+
+function applyKeybindings<T extends AppWithCommands>(app: T, options: WithKeybindingsOptions): T {
+  const { bindings, getKeyContext } = options
+  const originalPress = app.press.bind(app)
+
+  // Create a proxy to intercept press() while preserving all other properties
+  return new Proxy(app, {
+    get(target, prop, receiver) {
+      if (prop === "press") {
+        return async function interceptedPress(keyStr: string): Promise<T> {
+          const { key, ...modifiers } = parseHotkey(keyStr)
+          const ctx = getKeyContext()
+
+          // Try to resolve to a command
+          const commandId = resolveKeybinding(key, modifiers, bindings as ExtendedKeybindingDef[], ctx)
+
+          if (commandId) {
+            const cmd = target.cmd[commandId]
+            if (cmd) {
+              await cmd()
+              return receiver as T
+            }
+          }
+
+          // Pass through to original press handler (for useInput)
+          await originalPress(keyStr)
+          return receiver as T
+        }
+      }
+      return Reflect.get(target, prop, receiver)
+    },
+  })
+}

package/src/with-react.ts

@@ -0,0 +1,92 @@
+/**
+ * withReact(element) — Plugin: mount React reconciler + virtual buffer
+ *
+ * This plugin represents the React rendering layer in silvery's plugin
+ * composition model. It mounts a React element through the reconciler,
+ * manages the virtual buffer, and re-renders reactively on store changes.
+ *
+ * In the current architecture, React mounting is handled by createApp()
+ * and render(). This plugin provides the declarative interface for
+ * pipe() composition:
+ *
+ * ```tsx
+ * const app = pipe(
+ *   createApp(store),
+ *   withReact(<Board />),
+ *   withTerminal(process),
+ * )
+ * ```
+ *
+ * Currently, withReact stores the element for use by the runtime
+ * that calls run(). Future iterations will extract the full React
+ * reconciler lifecycle into this plugin.
+ *
+ * @example
+ * ```tsx
+ * import { pipe, withReact } from '@silvery/tea'
+ *
+ * // The element is associated with the app for later mounting
+ * const app = pipe(baseApp, withReact(<MyComponent />))
+ * ```
+ */
+
+import type { ReactElement } from "react"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * App enhanced with a React element for rendering.
+ */
+export interface AppWithReact {
+  /** The React element to render */
+  readonly element: ReactElement
+  /** Run the app (renders the element and starts the event loop) */
+  run(): Promise<void>
+}
+
+/**
+ * Minimal app shape that withReact can enhance.
+ * Requires a run() method that accepts an element.
+ */
+interface RunnableApp {
+  run(element: ReactElement, ...args: unknown[]): unknown
+  [key: string]: unknown
+}
+
+// =============================================================================
+// Implementation
+// =============================================================================
+
+/**
+ * Associate a React element with an app for rendering.
+ *
+ * In pipe() composition, this captures the element so that subsequent
+ * plugins and the final run() know what to render.
+ *
+ * The plugin wraps `run()` to automatically pass the element:
+ * - Before: `app.run(<Board />, options)`
+ * - After: `app.run()` (element already bound)
+ *
+ * @param element - The React element to render
+ * @returns Plugin function that binds the element to the app
+ */
+export function withReact<T extends RunnableApp>(element: ReactElement): (app: T) => T & AppWithReact {
+  return (app: T): T & AppWithReact => {
+    const originalRun = app.run
+
+    return Object.assign(Object.create(app), {
+      element,
+      run(...args: unknown[]) {
+        // If run() is called without an element, inject our bound element
+        if (args.length === 0 || typeof args[0] !== "object" || args[0] === null || !("type" in (args[0] as object))) {
+          // args[0] is likely options, not an element
+          return originalRun.call(app, element, ...args)
+        }
+        // Otherwise pass through as-is
+        return originalRun.apply(app, args as [ReactElement, ...unknown[]])
+      },
+    }) as T & AppWithReact
+  }
+}

package/src/with-render.ts

@@ -0,0 +1,92 @@
+/**
+ * withRender(term) -- extends a Term with render pipeline capabilities.
+ *
+ * Creates term-scoped pipeline config (width measurer + output phase) from caps,
+ * then returns an extended term with render() and renderStatic() methods.
+ *
+ * Usage:
+ *   const term = withRender(createTerm())
+ *   const { output, buffer } = term.render(root, 80, 24, null, { mode: "fullscreen" })
+ *   const html = await term.renderStatic(<Report />)
+ */
+
+import type { Term } from "@silvery/term/ansi"
+import type { ReactElement } from "react"
+import type { TerminalBuffer } from "@silvery/term/buffer"
+import { createPipeline, type MeasuredTerm } from "@silvery/term/measurer"
+import { executeRender, type ExecuteRenderOptions, type PipelineConfig } from "@silvery/term/pipeline"
+import type { TeaNode } from "./types"
+
+/**
+ * Extended Term with render pipeline capabilities.
+ *
+ * Extends MeasuredTerm (Term + Measurer methods) with render/renderStatic.
+ */
+export interface RenderTerm extends MeasuredTerm {
+  /** Pipeline configuration (measurer + output phase) */
+  readonly pipelineConfig: PipelineConfig
+  /**
+   * Run the full render pipeline.
+   */
+  render(
+    root: TeaNode,
+    width: number,
+    height: number,
+    prevBuffer: TerminalBuffer | null,
+    options?: ExecuteRenderOptions | "fullscreen" | "inline",
+  ): { output: string; buffer: TerminalBuffer }
+  /**
+   * Render a React element to a string using this terminal's caps.
+   * Uses the term's width measurer for correct text measurement.
+   */
+  renderStatic(element: ReactElement, options?: { width?: number; height?: number; plain?: boolean }): Promise<string>
+}
+
+/**
+ * Extend a Term with render pipeline capabilities.
+ *
+ * Creates a pipeline config (width measurer + output phase) from the term's caps,
+ * and adds render() and renderStatic() methods plus measurer methods.
+ *
+ * @param term - A Term instance (from createTerm)
+ * @returns Extended term with render and measurement capabilities
+ */
+export function withRender(term: Term): RenderTerm {
+  const pipelineConfig = createPipeline({ caps: term.caps })
+  const { measurer } = pipelineConfig
+
+  function renderPipeline(
+    root: TeaNode,
+    width: number,
+    height: number,
+    prevBuffer: TerminalBuffer | null,
+    options?: ExecuteRenderOptions | "fullscreen" | "inline",
+  ): { output: string; buffer: TerminalBuffer } {
+    return executeRender(root, width, height, prevBuffer, options, pipelineConfig)
+  }
+
+  async function renderStaticFn(
+    element: ReactElement,
+    options?: { width?: number; height?: number; plain?: boolean },
+  ): Promise<string> {
+    const { renderString } = await import("@silvery/react/render-string")
+    return renderString(element, { ...options, pipelineConfig })
+  }
+
+  // Return a proxy that extends the original term with measurer methods and render capabilities
+  return Object.create(term, {
+    // Measurer methods (from pipeline config)
+    textEmojiWide: { get: () => measurer.textEmojiWide, enumerable: true },
+    textSizingEnabled: { get: () => measurer.textSizingEnabled, enumerable: true },
+    displayWidth: { value: measurer.displayWidth.bind(measurer), enumerable: true },
+    displayWidthAnsi: { value: measurer.displayWidthAnsi.bind(measurer), enumerable: true },
+    graphemeWidth: { value: measurer.graphemeWidth.bind(measurer), enumerable: true },
+    wrapText: { value: measurer.wrapText.bind(measurer), enumerable: true },
+    sliceByWidth: { value: measurer.sliceByWidth.bind(measurer), enumerable: true },
+    sliceByWidthFromEnd: { value: measurer.sliceByWidthFromEnd.bind(measurer), enumerable: true },
+    // Pipeline config and render methods
+    pipelineConfig: { value: pipelineConfig, enumerable: true },
+    render: { value: renderPipeline, enumerable: true },
+    renderStatic: { value: renderStaticFn, enumerable: true },
+  }) as RenderTerm
+}