@silvery/tea 0.3.0

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@silvery/tea",
+  "version": "0.3.0",
+  "description": "TEA (The Elm Architecture) state machine store for silvery",
+  "license": "MIT",
+  "author": "Bjørn Stabell <bjorn@stabell.org>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/beorn/silvery.git",
+    "directory": "packages/tea"
+  },
+  "files": [
+    "src"
+  ],
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./core": {
+      "types": "./src/core/index.ts",
+      "import": "./src/core/index.ts"
+    },
+    "./store": {
+      "types": "./src/store/index.ts",
+      "import": "./src/store/index.ts"
+    },
+    "./tea": {
+      "types": "./src/tea/index.ts",
+      "import": "./src/tea/index.ts"
+    },
+    "./streams": {
+      "types": "./src/streams/index.ts",
+      "import": "./src/streams/index.ts"
+    },
+    "./plugins": {
+      "types": "./src/plugins.ts",
+      "import": "./src/plugins.ts"
+    },
+    "./*": "./src/*.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@silvery/compat": "workspace:*",
+    "@silvery/react": "workspace:*",
+    "@silvery/term": "workspace:*",
+    "@silvery/test": "workspace:*"
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,225 @@
+/**
+ * @silvery/core — TEA runtime, React reconciler, store, and effect system.
+ *
+ * Portable core that doesn't depend on terminal specifics. Can target
+ * terminal, canvas, DOM, or any custom render backend.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * silvery/core — Pure functions and types, NO React dependency.
+ *
+ * This sub-path export provides:
+ * - TEA (The Elm Architecture) types: SilveryModel, SilveryMsg, Effect, Sub, Plugin
+ * - Focus manager: createFocusManager + types
+ * - Focus events: event factories + dispatch functions
+ * - Focus queries: tree query functions
+ * - Plugin composition: compose() for middleware-style plugin chaining
+ *
+ * Everything here is pure TypeScript — no React import anywhere in the
+ * dependency graph. Safe for use in non-React contexts (CLI tools, tests,
+ * server-side logic).
+ *
+ * @packageDocumentation
+ */
+
+// =============================================================================
+// TEA Types (The Elm Architecture)
+// =============================================================================
+
+import type { FocusOrigin } from "../focus-manager.js"
+export type { FocusOrigin } from "../focus-manager.js"
+
+/**
+ * The model type that silvery manages for focus state.
+ *
+ * Applications extend this with their own model fields.
+ * The store's update function receives the full model and returns
+ * a new model + effects tuple.
+ */
+export interface SilveryModel {
+  focus: {
+    activeId: string | null
+    previousId: string | null
+    origin: FocusOrigin | null
+    scopeStack: string[]
+    scopeMemory: Record<string, string>
+  }
+}
+
+/**
+ * Direction type used in spatial navigation messages.
+ */
+export type Direction = "up" | "down" | "left" | "right"
+
+/**
+ * Message types that silvery understands.
+ *
+ * Applications can extend this union with their own message types.
+ * The store's update function pattern-matches on `type` to decide
+ * how to update the model.
+ */
+export type SilveryMsg =
+  | { type: "focus"; nodeId: string; origin?: FocusOrigin }
+  | { type: "blur" }
+  | { type: "focus-next" }
+  | { type: "focus-prev" }
+  | { type: "focus-direction"; direction: Direction }
+  | { type: "scope-enter"; scopeId: string }
+  | { type: "scope-exit" }
+  | {
+      type: "term:key"
+      key: string
+      input: string
+      ctrl: boolean
+      meta: boolean
+      shift: boolean
+    }
+  | {
+      type: "term:mouse"
+      action: "down" | "up" | "move" | "scroll"
+      x: number
+      y: number
+      button: number
+    }
+  | { type: "term:resize"; cols: number; rows: number }
+
+/**
+ * Effect commands returned by update functions.
+ *
+ * Effects are declarative descriptions of side effects. The store
+ * executes them after the model update, keeping the update function pure.
+ *
+ * - `none`: No effect (useful as a default)
+ * - `batch`: Multiple effects to execute
+ * - `dispatch`: Queue another message (no re-entrant dispatch)
+ */
+export type Effect = { type: "none" } | { type: "batch"; effects: Effect[] } | { type: "dispatch"; msg: SilveryMsg }
+
+/**
+ * Subscription descriptor (for future use).
+ *
+ * Subscriptions represent long-running side effects (timers, event listeners)
+ * that produce messages over time. The store manages their lifecycle.
+ */
+export type Sub = {
+  type: "none"
+}
+
+// =============================================================================
+// Effect Constructors
+// =============================================================================
+
+/** No-op effect. */
+export const none: Effect = { type: "none" }
+
+/** Batch multiple effects. */
+export function batch(...effects: Effect[]): Effect {
+  // Flatten nested batches and filter out none effects
+  const flat: Effect[] = []
+  for (const e of effects) {
+    if (e.type === "none") continue
+    if (e.type === "batch") {
+      flat.push(...e.effects)
+    } else {
+      flat.push(e)
+    }
+  }
+  if (flat.length === 0) return none
+  if (flat.length === 1) return flat[0]!
+  return { type: "batch", effects: flat }
+}
+
+/** Queue a message dispatch as an effect. */
+export function dispatch(msg: SilveryMsg): Effect {
+  return { type: "dispatch", msg }
+}
+
+// =============================================================================
+// Plugin Type (Middleware Composition)
+// =============================================================================
+
+/**
+ * A plugin wraps an update function, adding behavior before/after/around it.
+ *
+ * Plugins compose via `compose()` — the outermost plugin runs first on
+ * message receive, but the innermost (original) update runs first for
+ * model updates. This is the standard middleware pattern.
+ *
+ * @example
+ * ```ts
+ * const logging: Plugin<MyModel, MyMsg> = (inner) => (msg, model) => {
+ *   console.log('msg:', msg.type)
+ *   const result = inner(msg, model)
+ *   console.log('new model:', result[0])
+ *   return result
+ * }
+ * ```
+ */
+export type Plugin<Model, Msg> = (
+  innerUpdate: (msg: Msg, model: Model) => [Model, Effect[]],
+) => (msg: Msg, model: Model) => [Model, Effect[]]
+
+/**
+ * Compose multiple plugins into a single update function wrapper.
+ *
+ * Plugins are applied right-to-left (innermost first), so the first
+ * plugin in the array is the outermost wrapper — it sees messages first
+ * and model changes last.
+ *
+ * @example
+ * ```ts
+ * const update = compose(logging, focusNav, spatialNav)(baseUpdate)
+ * // Equivalent to: logging(focusNav(spatialNav(baseUpdate)))
+ * ```
+ */
+export function compose<Model, Msg>(...plugins: Plugin<Model, Msg>[]): Plugin<Model, Msg> {
+  return (innerUpdate) => {
+    let update = innerUpdate
+    // Apply right-to-left so first plugin is outermost
+    for (let i = plugins.length - 1; i >= 0; i--) {
+      update = plugins[i]!(update)
+    }
+    return update
+  }
+}
+
+// =============================================================================
+// Focus Manager (pure, no React)
+// =============================================================================
+
+export { createFocusManager } from "../focus-manager.js"
+export type { FocusManager, FocusManagerOptions, FocusChangeCallback, FocusSnapshot } from "../focus-manager.js"
+
+// =============================================================================
+// Focus Events (pure, no React)
+// =============================================================================
+
+export { createKeyEvent, createFocusEvent, dispatchKeyEvent, dispatchFocusEvent } from "../focus-events.js"
+export type { SilveryKeyEvent, SilveryFocusEvent, FocusEventProps } from "../focus-events.js"
+
+// =============================================================================
+// Focus Queries (pure, no React)
+// =============================================================================
+
+export {
+  findFocusableAncestor,
+  getTabOrder,
+  findByTestID,
+  findSpatialTarget,
+  getExplicitFocusLink,
+} from "../focus-queries.js"
+
+// =============================================================================
+// Slices (ops-as-data helper)
+// =============================================================================
+
+export { createSlice } from "./slice.js"
+export type { Slice, SliceWithInit, InferOp } from "./slice.js"
+
+// =============================================================================
+// Shared Types (pure)
+// =============================================================================
+
+export type { TeaNode, Rect } from "../types.js"

package/src/core/slice.ts

@@ -0,0 +1,69 @@
+// --- Types ---
+
+/** True if F accepts at least 2 args */
+type HasParams<F> = F extends (a: any, b: any, ...rest: any[]) => any ? true : false
+
+/** Extract 2nd arg type, or never for 1-arg handlers */
+type HandlerParams<F> = HasParams<F> extends true ? (F extends (s: any, params: infer P) => any ? P : never) : never
+
+/** One variant of the op union */
+type OpVariant<Name extends string, F> = [HandlerParams<F>] extends [never]
+  ? { op: Name }
+  : { op: Name } & HandlerParams<F>
+
+/** Full op union inferred from handler map */
+export type InferOp<H> = {
+  [K in keyof H & string]: OpVariant<K, H[K]>
+}[keyof H & string]
+
+/** Union of all handler return types */
+type ApplyReturn<H> = {
+  [K in keyof H]: H[K] extends (...args: any[]) => infer R ? R : never
+}[keyof H]
+
+/** Handlers-only slice (no state factory) */
+export type Slice<S, H extends Record<string, (s: S, ...args: any[]) => any>> = H & {
+  apply(s: S, op: InferOp<H>): ApplyReturn<H>
+  readonly Op: InferOp<H>
+}
+
+/** Slice with bundled state factory */
+export type SliceWithInit<S, H extends Record<string, (s: S, ...args: any[]) => any>> = Slice<S, H> & {
+  create(): { state: S; apply: (op: InferOp<H>) => ApplyReturn<H> }
+}
+
+// --- Implementation ---
+
+// Shared: build the slice object from handlers
+function makeSlice<S, H extends Record<string, (s: S, ...args: any[]) => any>>(handlers: H): Slice<S, H> {
+  const apply = (s: S, op: { op: string }) => {
+    const handler = handlers[op.op]
+    if (!handler) throw new Error(`Unknown op: ${op.op}`)
+    return handler(s, op)
+  }
+  return Object.assign({ apply }, handlers) as any
+}
+
+// Overload 1: state factory + handlers (primary)
+export function createSlice<S, H extends Record<string, (s: S, ...args: any[]) => any>>(
+  init: () => S,
+  handlers: H,
+): SliceWithInit<S, H>
+
+// Overload 2: curried, no state (fallback)
+export function createSlice<S>(): <H extends Record<string, (s: S, ...args: any[]) => any>>(handlers: H) => Slice<S, H>
+
+export function createSlice(...args: any[]): any {
+  if (args.length === 0) {
+    // Curried form
+    return <H extends Record<string, (s: any, ...args: any[]) => any>>(handlers: H) => makeSlice(handlers)
+  }
+  // State factory form
+  const [init, handlers] = args
+  const slice = makeSlice(handlers)
+  ;(slice as any).create = () => {
+    const state = init()
+    return { state, apply: (op: any) => slice.apply(state, op) }
+  }
+  return slice
+}

package/src/create-command-registry.ts

@@ -0,0 +1,106 @@
+/**
+ * createCommandRegistry() — Build a typed command registry from a definition object.
+ *
+ * Silvery's own command registry builder. Creates a `CommandRegistryLike`
+ * from a plain object of command definitions, suitable for use with
+ * `withCommands()`.
+ *
+ * @example
+ * ```tsx
+ * const registry = createCommandRegistry({
+ *   cursor_down: {
+ *     name: 'Move Down',
+ *     description: 'Move cursor down one row',
+ *     shortcuts: ['j', 'ArrowDown'],
+ *     execute: (ctx) => ({ type: 'moveCursor', delta: 1 }),
+ *   },
+ *   cursor_up: {
+ *     name: 'Move Up',
+ *     description: 'Move cursor up one row',
+ *     shortcuts: ['k', 'ArrowUp'],
+ *     execute: (ctx) => ({ type: 'moveCursor', delta: -1 }),
+ *   },
+ *   toggle_done: {
+ *     name: 'Toggle Done',
+ *     description: 'Toggle the done state of the current item',
+ *     execute: (ctx) => ({ type: 'toggleDone', index: ctx.cursor }),
+ *   },
+ * })
+ *
+ * // Use with withCommands
+ * const app = withCommands(baseApp, {
+ *   registry,
+ *   getContext: () => buildContext(state),
+ *   handleAction: (action) => dispatch(action),
+ * })
+ * ```
+ */
+
+import type { CommandDef, CommandRegistryLike } from "./with-commands"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Definition for a single command in the registry builder.
+ *
+ * Unlike the full `CommandDef`, the `id` is inferred from the object key.
+ */
+export interface CommandDefInput<TContext = unknown, TAction = unknown> {
+  /** Human-readable name */
+  name: string
+  /** Description of what the command does */
+  description?: string
+  /** Default keyboard shortcuts */
+  shortcuts?: string[]
+  /** Execute the command, returning action(s) or null */
+  execute: (ctx: TContext) => TAction | TAction[] | null
+}
+
+/**
+ * A record mapping command IDs to their definitions.
+ */
+export type CommandDefs<TContext = unknown, TAction = unknown> = Record<string, CommandDefInput<TContext, TAction>>
+
+// =============================================================================
+// Implementation
+// =============================================================================
+
+/**
+ * Create a command registry from a definition object.
+ *
+ * Each key in the object becomes the command ID. The returned registry
+ * implements `CommandRegistryLike` for use with `withCommands()`.
+ *
+ * @param defs - Object mapping command IDs to their definitions
+ * @returns A command registry with `get()` and `getAll()`
+ */
+export function createCommandRegistry<TContext, TAction>(
+  defs: CommandDefs<TContext, TAction>,
+): CommandRegistryLike<TContext, TAction> {
+  // Build the full CommandDef array with IDs
+  const commands: CommandDef<TContext, TAction>[] = []
+  const byId = new Map<string, CommandDef<TContext, TAction>>()
+
+  for (const [id, def] of Object.entries(defs)) {
+    const command: CommandDef<TContext, TAction> = {
+      id,
+      name: def.name,
+      description: def.description ?? def.name,
+      shortcuts: def.shortcuts,
+      execute: def.execute,
+    }
+    commands.push(command)
+    byId.set(id, command)
+  }
+
+  return {
+    get(id: string): CommandDef<TContext, TAction> | undefined {
+      return byId.get(id)
+    },
+    getAll(): CommandDef<TContext, TAction>[] {
+      return commands
+    },
+  }
+}

package/src/effects.ts

@@ -0,0 +1,145 @@
+/**
+ * Built-in TEA effects for timers and dispatch.
+ *
+ * Effect constructors create plain data objects. Effect runners execute them.
+ * The update function returns effects as data — the runtime executes them.
+ *
+ * @example
+ * ```ts
+ * function update(state, msg) {
+ *   switch (msg.type) {
+ *     case "start":
+ *       return [{ ...state, phase: "thinking" }, [fx.delay(1200, { type: "done" })]]
+ *     case "tick":
+ *       return { ...state, count: state.count + 1 }  // no effects
+ *     case "done":
+ *       return [{ ...state, phase: "idle" }, [fx.cancel("ticker")]]
+ *   }
+ * }
+ * ```
+ */
+
+import type { EffectLike, EffectRunners } from "./tea"
+
+// =============================================================================
+// Effect Types
+// =============================================================================
+
+/** Fire a message after a delay. */
+export interface DelayEffect<Msg = unknown> extends EffectLike {
+  type: "delay"
+  ms: number
+  msg: Msg
+  id?: string
+}
+
+/** Fire a message repeatedly on an interval. */
+export interface IntervalEffect<Msg = unknown> extends EffectLike {
+  type: "interval"
+  ms: number
+  msg: Msg
+  id: string
+}
+
+/** Cancel a named timer (delay or interval). */
+export interface CancelEffect extends EffectLike {
+  type: "cancel"
+  id: string
+}
+
+/** All built-in effect types. */
+export type TimerEffect<Msg = unknown> = DelayEffect<Msg> | IntervalEffect<Msg> | CancelEffect
+
+// =============================================================================
+// Effect Constructors (the fx namespace)
+// =============================================================================
+
+/** Fire `msg` after `ms` milliseconds. Optionally named for cancellation. */
+function delay<Msg>(ms: number, msg: Msg, id?: string): DelayEffect<Msg> {
+  return { type: "delay", ms, msg, id }
+}
+
+/** Fire `msg` every `ms` milliseconds. Must be named (for cancellation). */
+function interval<Msg>(ms: number, msg: Msg, id: string): IntervalEffect<Msg> {
+  return { type: "interval", ms, msg, id }
+}
+
+/** Cancel a named delay or interval. */
+function cancel(id: string): CancelEffect {
+  return { type: "cancel", id }
+}
+
+/**
+ * Built-in effect constructors.
+ *
+ * ```ts
+ * return [newState, [fx.delay(1000, { type: "tick" }), fx.cancel("old")]]
+ * ```
+ */
+export const fx = { delay, interval, cancel } as const
+
+// =============================================================================
+// Effect Runners
+// =============================================================================
+
+/**
+ * Create timer effect runners that manage named timers.
+ *
+ * Returns runners + a cleanup function. Call cleanup on unmount to
+ * cancel all active timers.
+ *
+ * @example
+ * ```ts
+ * const { runners, cleanup } = createTimerRunners<MyMsg>()
+ * const [state, send] = useTea(init, update, runners)
+ * useEffect(() => cleanup, [])
+ * ```
+ */
+export function createTimerRunners<Msg>(): {
+  runners: EffectRunners<TimerEffect<Msg>, Msg>
+  cleanup: () => void
+} {
+  const timers = new Map<string, ReturnType<typeof setTimeout> | ReturnType<typeof setInterval>>()
+  let nextAnon = 0
+
+  function clearTimer(id: string): void {
+    const existing = timers.get(id)
+    if (existing !== undefined) {
+      clearTimeout(existing as ReturnType<typeof setTimeout>)
+      clearInterval(existing as ReturnType<typeof setInterval>)
+      timers.delete(id)
+    }
+  }
+
+  const runners: EffectRunners<TimerEffect<Msg>, Msg> = {
+    delay(effect, dispatch) {
+      const id = effect.id ?? `__anon_${nextAnon++}`
+      clearTimer(id)
+      const timer = setTimeout(() => {
+        timers.delete(id)
+        dispatch(effect.msg as Msg)
+      }, effect.ms)
+      timers.set(id, timer)
+    },
+
+    interval(effect, dispatch) {
+      clearTimer(effect.id)
+      const timer = setInterval(() => {
+        dispatch(effect.msg as Msg)
+      }, effect.ms)
+      timers.set(effect.id, timer)
+    },
+
+    cancel(effect) {
+      clearTimer(effect.id)
+    },
+  }
+
+  function cleanup(): void {
+    for (const [id] of timers) {
+      clearTimer(id)
+    }
+  }
+
+  return { runners, cleanup }
+}