@silvery/tea 0.3.0

package/src/pipe.ts

@@ -0,0 +1,110 @@
+/**
+ * pipe() — Compose app plugins left-to-right.
+ *
+ * The foundational composition function for silvery's plugin system.
+ * Each plugin is a function `(app) => enhancedApp` that takes an app object
+ * and returns an enhanced version with additional capabilities.
+ *
+ * Plugins compose left-to-right: `pipe(base, p1, p2)` = `p2(p1(base))`
+ *
+ * @example
+ * ```tsx
+ * import { pipe, createApp, withReact, withTerminal, withFocus, withDomEvents } from '@silvery/tea'
+ *
+ * const app = pipe(
+ *   createApp(store),
+ *   withReact(<Board />),
+ *   withTerminal(process),
+ *   withFocus(),
+ *   withDomEvents(),
+ * )
+ * await app.run()
+ * ```
+ *
+ * @example Typed plugin
+ * ```tsx
+ * type MyPlugin = (app: App) => App & { custom: () => void }
+ *
+ * const withCustom: MyPlugin = (app) => ({
+ *   ...app,
+ *   custom: () => console.log('hello'),
+ * })
+ *
+ * const enhanced = pipe(baseApp, withCustom)
+ * enhanced.custom() // typed!
+ * ```
+ */
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * A plugin function that enhances an app.
+ *
+ * Takes an app of type A and returns an enhanced app of type B.
+ * The plugin can add new methods, override existing ones, or
+ * wrap behavior via closures.
+ */
+export type AppPlugin<A, B> = (app: A) => B
+
+// =============================================================================
+// Implementation
+// =============================================================================
+
+/**
+ * Compose app plugins left-to-right.
+ *
+ * `pipe(base, p1, p2, p3)` is equivalent to `p3(p2(p1(base)))`.
+ *
+ * Each plugin receives the result of the previous plugin, allowing
+ * progressive enhancement of the app object.
+ *
+ * Type inference works through the chain: if p1 adds `.cmd` and p2
+ * requires it, TypeScript catches the error at the call site.
+ */
+export function pipe<A>(base: A): A
+export function pipe<A, B>(base: A, p1: AppPlugin<A, B>): B
+export function pipe<A, B, C>(base: A, p1: AppPlugin<A, B>, p2: AppPlugin<B, C>): C
+export function pipe<A, B, C, D>(base: A, p1: AppPlugin<A, B>, p2: AppPlugin<B, C>, p3: AppPlugin<C, D>): D
+export function pipe<A, B, C, D, E>(
+  base: A,
+  p1: AppPlugin<A, B>,
+  p2: AppPlugin<B, C>,
+  p3: AppPlugin<C, D>,
+  p4: AppPlugin<D, E>,
+): E
+export function pipe<A, B, C, D, E, F>(
+  base: A,
+  p1: AppPlugin<A, B>,
+  p2: AppPlugin<B, C>,
+  p3: AppPlugin<C, D>,
+  p4: AppPlugin<D, E>,
+  p5: AppPlugin<E, F>,
+): F
+export function pipe<A, B, C, D, E, F, G>(
+  base: A,
+  p1: AppPlugin<A, B>,
+  p2: AppPlugin<B, C>,
+  p3: AppPlugin<C, D>,
+  p4: AppPlugin<D, E>,
+  p5: AppPlugin<E, F>,
+  p6: AppPlugin<F, G>,
+): G
+export function pipe<A, B, C, D, E, F, G, H>(
+  base: A,
+  p1: AppPlugin<A, B>,
+  p2: AppPlugin<B, C>,
+  p3: AppPlugin<C, D>,
+  p4: AppPlugin<D, E>,
+  p5: AppPlugin<E, F>,
+  p6: AppPlugin<F, G>,
+  p7: AppPlugin<G, H>,
+): H
+export function pipe(base: unknown, ...plugins: AppPlugin<unknown, unknown>[]): unknown {
+  let result = base
+  for (const plugin of plugins) {
+    result = plugin(result)
+  }
+  return result
+}

package/src/plugins.ts

@@ -0,0 +1,119 @@
+/**
+ * silvery/plugins -- Composable plugin system for silvery apps.
+ *
+ * Plugins are functions `(app) => enhancedApp` that compose via `pipe()`:
+ *
+ * ```tsx
+ * import { pipe, withCommands, withKeybindings, withFocus, withDomEvents } from '@silvery/tea/plugins'
+ *
+ * const app = pipe(
+ *   baseApp,
+ *   withFocus(),
+ *   withDomEvents(),
+ *   withCommands(cmdOpts),
+ *   withKeybindings(kbOpts),
+ * )
+ *
+ * await app.cmd.down()       // Direct command invocation
+ * await app.press('j')       // Key -> command -> action
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// =============================================================================
+// pipe — Plugin composition
+// =============================================================================
+
+export { pipe } from "./pipe"
+export type { AppPlugin } from "./pipe"
+
+// =============================================================================
+// withReact — React reconciler mounting
+// =============================================================================
+
+export { withReact } from "./with-react"
+export type { AppWithReact } from "./with-react"
+
+// =============================================================================
+// withTerminal — Terminal I/O
+// =============================================================================
+
+export { withTerminal } from "./with-terminal"
+export type { WithTerminalOptions, AppWithTerminal, ProcessLike } from "./with-terminal"
+
+// =============================================================================
+// withFocus — Focus management
+// =============================================================================
+
+export { withFocus } from "./with-focus"
+export type { WithFocusOptions, AppWithFocus } from "./with-focus"
+
+// =============================================================================
+// withDomEvents — DOM-style event dispatch
+// =============================================================================
+
+export { withDomEvents } from "./with-dom-events"
+export type { WithDomEventsOptions } from "./with-dom-events"
+
+// =============================================================================
+// createCommandRegistry — Command registry builder
+// =============================================================================
+
+export { createCommandRegistry } from "./create-command-registry"
+export type { CommandDefInput, CommandDefs } from "./create-command-registry"
+
+// =============================================================================
+// withCommands — Command system
+// =============================================================================
+
+export { withCommands } from "./with-commands"
+export type {
+  WithCommandsOptions,
+  CommandDef,
+  CommandRegistryLike,
+  CommandInfo,
+  Command,
+  Cmd,
+  AppWithCommands,
+  AppState,
+  KeybindingDef,
+} from "./with-commands"
+
+// =============================================================================
+// withKeybindings — Keybinding resolution
+// =============================================================================
+
+export { withKeybindings } from "./with-keybindings"
+export type { WithKeybindingsOptions, KeybindingContext, ExtendedKeybindingDef } from "./with-keybindings"
+
+// =============================================================================
+// withDiagnostics — Testing invariants
+// =============================================================================
+
+export { withDiagnostics, VirtualTerminal } from "./with-diagnostics"
+export type { DiagnosticOptions } from "./with-diagnostics"
+
+// =============================================================================
+// withInk — Ink compatibility layer (from @silvery/compat)
+// =============================================================================
+
+export { withInk } from "@silvery/compat/with-ink"
+export type { WithInkOptions, AppWithInk } from "@silvery/compat/with-ink"
+
+// =============================================================================
+// withInkCursor — Ink cursor compatibility adapter (from @silvery/compat)
+// =============================================================================
+
+export { withInkCursor } from "@silvery/compat/with-ink-cursor"
+export type { WithInkCursorOptions, AppWithInkCursor } from "@silvery/compat/with-ink-cursor"
+
+// =============================================================================
+// withInkFocus — Ink focus compatibility adapter (from @silvery/compat)
+// =============================================================================
+
+export { withInkFocus } from "@silvery/compat/with-ink-focus"
+export type { WithInkFocusOptions, AppWithInkFocus } from "@silvery/compat/with-ink-focus"
+
+// Scheduler errors (for catching incremental render mismatches)
+export { IncrementalRenderMismatchError } from "@silvery/term/scheduler"

package/src/store/index.ts

@@ -0,0 +1,306 @@
+/**
+ * silvery/store — TEA-style state container with effects.
+ *
+ * Wraps FocusManager into a dispatch/subscribe loop following
+ * The Elm Architecture (TEA): Model + Msg -> [Model, Effect[]].
+ *
+ * The store provides:
+ * - `dispatch(msg)` — send a message, run update, execute effects
+ * - `getModel()` — current model snapshot
+ * - `subscribe(listener)` — for useSyncExternalStore integration
+ * - `getSnapshot(selector)` — selector-based access
+ *
+ * Effects are executed after each update cycle. `dispatch` effects
+ * are queued (not re-entrant) to prevent stack overflow.
+ *
+ * @packageDocumentation
+ */
+
+import type { Effect, SilveryModel, SilveryMsg, Plugin } from "../core"
+import { none } from "../core"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Configuration for creating a store.
+ */
+export interface StoreConfig<Model extends SilveryModel, Msg extends SilveryMsg> {
+  /** Initialize model and effects. Called once on store creation. */
+  init: () => [Model, Effect[]]
+  /** Pure update function: (msg, model) -> [newModel, effects] */
+  update: (msg: Msg, model: Model) => [Model, Effect[]]
+}
+
+/**
+ * The store API returned by createStore.
+ */
+export interface StoreApi<Model extends SilveryModel, Msg extends SilveryMsg> {
+  /** Send a message through the update function. */
+  dispatch(msg: Msg): void
+  /** Get the current model. */
+  getModel(): Model
+  /** Subscribe to model changes. Returns unsubscribe function. */
+  subscribe(listener: () => void): () => void
+  /** Get a derived value from the model via selector. */
+  getSnapshot<T>(selector: (model: Model) => T): T
+}
+
+// =============================================================================
+// Built-in Plugins
+// =============================================================================
+
+/**
+ * Plugin that handles focus-related messages by updating the focus slice.
+ *
+ * Handles: focus, blur, scope-enter, scope-exit.
+ * Passes focus-next, focus-prev, focus-direction through (they need
+ * the node tree, which the store doesn't have — those are handled
+ * at the React integration layer).
+ */
+export function withFocusManagement<Model extends SilveryModel, Msg extends SilveryMsg>(): Plugin<Model, Msg> {
+  return (innerUpdate) => (msg, model) => {
+    switch (msg.type) {
+      case "focus": {
+        const focusMsg = msg as Extract<SilveryMsg, { type: "focus" }>
+        const newModel = {
+          ...model,
+          focus: {
+            ...model.focus,
+            previousId: model.focus.activeId,
+            activeId: focusMsg.nodeId,
+            origin: focusMsg.origin ?? "programmatic",
+            // Remember in current scope
+            scopeMemory:
+              model.focus.scopeStack.length > 0
+                ? {
+                    ...model.focus.scopeMemory,
+                    [model.focus.scopeStack[model.focus.scopeStack.length - 1]!]: focusMsg.nodeId,
+                  }
+                : model.focus.scopeMemory,
+          },
+        }
+        return [newModel as Model, [none]]
+      }
+
+      case "blur": {
+        const newModel = {
+          ...model,
+          focus: {
+            ...model.focus,
+            previousId: model.focus.activeId,
+            activeId: null,
+            origin: null,
+          },
+        }
+        return [newModel as Model, [none]]
+      }
+
+      case "scope-enter": {
+        const scopeMsg = msg as Extract<SilveryMsg, { type: "scope-enter" }>
+        const newModel = {
+          ...model,
+          focus: {
+            ...model.focus,
+            scopeStack: [...model.focus.scopeStack, scopeMsg.scopeId],
+          },
+        }
+        return [newModel as Model, [none]]
+      }
+
+      case "scope-exit": {
+        const newModel = {
+          ...model,
+          focus: {
+            ...model.focus,
+            scopeStack: model.focus.scopeStack.slice(0, -1),
+          },
+        }
+        return [newModel as Model, [none]]
+      }
+
+      default:
+        return innerUpdate(msg, model)
+    }
+  }
+}
+
+// =============================================================================
+// Default Update
+// =============================================================================
+
+/**
+ * The default silvery update function.
+ *
+ * Returns the model unchanged with no effects for any unhandled message.
+ * Compose with plugins to add behavior.
+ */
+export function silveryUpdate<Model extends SilveryModel, Msg extends SilveryMsg>(
+  _msg: Msg,
+  model: Model,
+): [Model, Effect[]] {
+  return [model, [none]]
+}
+
+// =============================================================================
+// Default Init
+// =============================================================================
+
+/**
+ * Create a default initial SilveryModel.
+ */
+export function defaultInit(): [SilveryModel, Effect[]] {
+  return [
+    {
+      focus: {
+        activeId: null,
+        previousId: null,
+        origin: null,
+        scopeStack: [],
+        scopeMemory: {},
+      },
+    },
+    [none],
+  ]
+}
+
+// =============================================================================
+// Store Factory
+// =============================================================================
+
+/**
+ * Create a TEA-style store.
+ *
+ * The store manages model state and effect execution. Messages are
+ * dispatched through the update function, which returns a new model
+ * and a list of effects. Effects are executed after each update cycle.
+ *
+ * Dispatch effects are queued to prevent re-entrant dispatch:
+ * if dispatching msg A triggers effect dispatch(B), B is queued and
+ * processed after A's full update cycle completes.
+ *
+ * @example
+ * ```ts
+ * import { createStore, withFocusManagement, silveryUpdate } from '@silvery/tea/store'
+ * import { compose } from '@silvery/tea/core'
+ *
+ * const store = createStore({
+ *   init: () => [{ focus: { activeId: null, ... }, count: 0 }, []],
+ *   update: compose(withFocusManagement())(silveryUpdate),
+ * })
+ *
+ * store.dispatch({ type: 'focus', nodeId: 'btn1' })
+ * console.log(store.getModel().focus.activeId) // 'btn1'
+ * ```
+ */
+export function createStore<Model extends SilveryModel, Msg extends SilveryMsg>(
+  config: StoreConfig<Model, Msg>,
+): StoreApi<Model, Msg> {
+  // Initialize
+  const [initialModel, initialEffects] = config.init()
+  let model = initialModel
+
+  // Subscriber management
+  const listeners = new Set<() => void>()
+
+  function notify(): void {
+    for (const listener of listeners) {
+      listener()
+    }
+  }
+
+  // Effect execution with queue for dispatch effects
+  let isDispatching = false
+  const dispatchQueue: Msg[] = []
+
+  function executeEffects(effects: Effect[]): void {
+    for (const effect of effects) {
+      executeEffect(effect)
+    }
+  }
+
+  function executeEffect(effect: Effect): void {
+    switch (effect.type) {
+      case "none":
+        break
+      case "batch":
+        executeEffects(effect.effects)
+        break
+      case "dispatch":
+        // Queue dispatch effects to prevent re-entrant dispatch
+        dispatchQueue.push(effect.msg as Msg)
+        break
+    }
+  }
+
+  function dispatch(msg: Msg): void {
+    if (isDispatching) {
+      // Queue if we're already in a dispatch cycle
+      dispatchQueue.push(msg)
+      return
+    }
+
+    isDispatching = true
+    try {
+      // Run update
+      const [newModel, effects] = config.update(msg, model)
+      const changed = newModel !== model
+      model = newModel
+
+      // Execute effects (may queue more dispatches)
+      executeEffects(effects)
+
+      // Notify subscribers if model changed
+      if (changed) {
+        notify()
+      }
+
+      // Process queued dispatches
+      while (dispatchQueue.length > 0) {
+        const queued = dispatchQueue.shift()!
+        const [nextModel, nextEffects] = config.update(queued, model)
+        const nextChanged = nextModel !== model
+        model = nextModel
+        executeEffects(nextEffects)
+        if (nextChanged) {
+          notify()
+        }
+      }
+    } finally {
+      isDispatching = false
+    }
+  }
+
+  function getModel(): Model {
+    return model
+  }
+
+  function subscribe(listener: () => void): () => void {
+    listeners.add(listener)
+    return () => {
+      listeners.delete(listener)
+    }
+  }
+
+  function getSnapshot<T>(selector: (model: Model) => T): T {
+    return selector(model)
+  }
+
+  // Execute initial effects and drain any queued dispatches
+  executeEffects(initialEffects)
+  while (dispatchQueue.length > 0) {
+    const queued = dispatchQueue.shift()!
+    const [nextModel, nextEffects] = config.update(queued, model)
+    model = nextModel
+    executeEffects(nextEffects)
+    // No notify during init — no subscribers yet
+  }
+
+  return {
+    dispatch,
+    getModel,
+    subscribe,
+    getSnapshot,
+  }
+}