@silvery/tea 0.3.0

package/src/tea/index.ts

@@ -0,0 +1,174 @@
+/**
+ * silvery/tea — Zustand middleware for TEA (The Elm Architecture) effects.
+ *
+ * A ~30-line middleware that extends Zustand reducers to optionally return
+ * [state, effects]. Gradual adoption: return plain state (Level 3) or
+ * [state, effects] (Level 4) on a per-case basis.
+ *
+ * @example
+ * ```ts
+ * import { createStore } from "zustand"
+ * import { tea, collect } from "@silvery/tea/tea"
+ *
+ * // Define effects as plain data
+ * const log = (msg: string) => ({ type: "log" as const, msg })
+ * const httpPost = (url: string, body: unknown) => ({ type: "http" as const, url, body })
+ *
+ * type MyEffect = ReturnType<typeof log> | ReturnType<typeof httpPost>
+ *
+ * interface State {
+ *   count: number
+ * }
+ *
+ * type Op = { type: "increment" } | { type: "save" }
+ *
+ * // Reducer: return state (no effects) or [state, effects]
+ * function reducer(state: State, op: Op): TeaResult<State, MyEffect> {
+ *   switch (op.type) {
+ *     case "increment":
+ *       return { ...state, count: state.count + 1 }              // Level 3: plain state
+ *     case "save":
+ *       return [{ ...state }, [httpPost("/api", state), log("saved")]]  // Level 4: [state, effects]
+ *   }
+ * }
+ *
+ * // Effect runners (swappable: production, test, replay)
+ * const runners: EffectRunners<MyEffect, Op> = {
+ *   log: (e) => console.log(e.msg),
+ *   http: async (e, dispatch) => {
+ *     const res = await fetch(e.url, { method: "POST", body: JSON.stringify(e.body) })
+ *     dispatch({ type: "loaded", data: await res.json() })
+ *   },
+ * }
+ *
+ * // Wire up
+ * const store = createStore(tea({ count: 0 }, reducer, { runners }))
+ * store.getState().dispatch({ type: "increment" })
+ *
+ * // Test: collect() normalizes output for assertions
+ * const [state, effects] = collect(reducer(initial, { type: "save" }))
+ * expect(effects).toContainEqual(httpPost("/api", initial))
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import type { StateCreator } from "zustand"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/** An effect is a plain object with a `type` discriminant. */
+export type EffectLike = { type: string }
+
+/** Reducer result: plain state (no effects) or [state, effects]. */
+export type TeaResult<S, E extends EffectLike = EffectLike> = S | readonly [S, E[]]
+
+/** A reducer that takes state + operation and returns TeaResult. */
+export type TeaReducer<S, Op, E extends EffectLike = EffectLike> = (state: S, op: Op) => TeaResult<S, E>
+
+/**
+ * Effect runners keyed by effect `type`.
+ *
+ * Each runner receives the effect and a dispatch function for round-trip
+ * communication (Elm's Cmd Msg pattern).
+ */
+export type EffectRunners<E extends EffectLike, Op = unknown> = {
+  [K in E["type"]]?: (effect: Extract<E, { type: K }>, dispatch: (op: Op) => void) => void | Promise<void>
+}
+
+/** Options for the tea() middleware. */
+export interface TeaOptions<E extends EffectLike, Op> {
+  /** Effect runners. Keyed by effect type. Unmatched effects are silently dropped. */
+  runners?: EffectRunners<E, Op>
+}
+
+/**
+ * The store shape produced by the tea() middleware.
+ *
+ * `dispatch(op)` runs the reducer, updates state, and executes effects.
+ * All domain state fields from S are spread at the top level alongside dispatch.
+ */
+export type TeaSlice<S, Op> = S & {
+  /** Dispatch an operation through the reducer. */
+  dispatch: (op: Op) => void
+}
+
+// =============================================================================
+// Core: tea() middleware
+// =============================================================================
+
+/**
+ * Zustand state creator that adds TEA-style dispatch + effects.
+ *
+ * The reducer can return plain state (Level 3) or `[state, effects]` (Level 4).
+ * Array.isArray detects which — safe because Zustand state is always an object.
+ *
+ * Effects are executed after state update. Each effect is routed to a runner
+ * by its `type` field. Runners receive a `dispatch` callback for round-trip
+ * communication (Elm's Cmd Msg pattern).
+ */
+export function tea<S extends object, Op, E extends EffectLike = EffectLike>(
+  initialState: S,
+  reducer: TeaReducer<S, Op, E>,
+  options?: TeaOptions<E, Op>,
+): StateCreator<TeaSlice<S, Op>> {
+  return (set, get) => {
+    const dispatch = (op: Op): void => {
+      // Extract domain state (everything except dispatch)
+      const { dispatch: _, ...currentState } = get()
+      const result = reducer(currentState as unknown as S, op)
+
+      // Detect: plain state vs [state, effects]
+      const [newState, effects] = Array.isArray(result) ? (result as [S, E[]]) : [result as S, [] as E[]]
+
+      // Update Zustand store (spread domain state, keep dispatch)
+      set(newState as Partial<TeaSlice<S, Op>>)
+
+      // Execute effects
+      if (effects.length > 0 && options?.runners) {
+        for (const effect of effects) {
+          const runner = options.runners[effect.type as E["type"]]
+          if (runner) {
+            ;(runner as (e: E, d: (op: Op) => void) => void)(effect, dispatch)
+          }
+        }
+      }
+    }
+
+    return {
+      ...initialState,
+      dispatch,
+    } as TeaSlice<S, Op>
+  }
+}
+
+// =============================================================================
+// Test helper: collect()
+// =============================================================================
+
+/**
+ * Normalize a reducer result to `[state, effects]` tuple.
+ *
+ * Use in tests to uniformly assert on both state and effects regardless of
+ * whether the reducer returned plain state or a tuple.
+ *
+ * @example
+ * ```ts
+ * const [state, effects] = collect(reducer(initial, { type: "save" }))
+ * expect(state.saving).toBe(true)
+ * expect(effects).toContainEqual(httpPost("/api", initial))
+ *
+ * // Also works for Level 3 (no effects):
+ * const [state2, effects2] = collect(reducer(initial, { type: "increment" }))
+ * expect(state2.count).toBe(1)
+ * expect(effects2).toEqual([])
+ * ```
+ */
+export function collect<S, E extends EffectLike = EffectLike>(result: TeaResult<S, E>): [S, E[]] {
+  if (Array.isArray(result)) {
+    return result as [S, E[]]
+  }
+  return [result as S, []]
+}

package/src/text-cursor.ts

@@ -0,0 +1,206 @@
+/**
+ * Text Cursor Utilities
+ *
+ * Pure functions for mapping between flat character offsets and visual
+ * (row, col) positions in word-wrapped text. Uses the same wrapText()
+ * function as the rendering pipeline, guaranteeing cursor positions
+ * match what's displayed on screen.
+ *
+ * Architecture layer 0 — no state, no hooks, no components.
+ * Used by: TextArea (layer 3), useTextEdit (layer 1), and apps
+ * that need cursor math without the full component stack.
+ *
+ * @example
+ * ```ts
+ * import { cursorToRowCol, cursorMoveDown } from '@silvery/react'
+ *
+ * const { row, col } = cursorToRowCol("hello world", 5, 8)
+ * // row=0, col=5 (fits in 8-wide line)
+ *
+ * const next = cursorMoveDown("hello world\nfoo", 3, 8)
+ * // next = 12 (moved to row 1, col 3 → "foo"[3] = end)
+ * ```
+ */
+import { type Measurer, wrapText } from "@silvery/term/unicode"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface WrappedLine {
+  /** The text content of this visual line */
+  line: string
+  /** Character offset in the original text where this line starts */
+  startOffset: number
+}
+
+// =============================================================================
+// Core Functions
+// =============================================================================
+
+/**
+ * Convert a flat cursor offset to visual (row, col) in word-wrapped text.
+ *
+ * Uses wrapText() from unicode.ts — the same function the render pipeline
+ * uses — so cursor positions always match what's displayed on screen.
+ */
+export function cursorToRowCol(
+  text: string,
+  cursor: number,
+  wrapWidth: number,
+  measurer?: Measurer,
+): { row: number; col: number } {
+  if (wrapWidth <= 0) return { row: 0, col: 0 }
+  return cursorToRowColFromLines(getWrappedLines(text, wrapWidth, measurer), cursor)
+}
+
+/** Internal: compute row/col from pre-computed wrapped lines. */
+function cursorToRowColFromLines(lines: WrappedLine[], cursor: number): { row: number; col: number } {
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!
+    const lineEnd = line.startOffset + line.line.length
+    const isLast = i === lines.length - 1
+
+    if (cursor <= lineEnd || isLast) {
+      const col = Math.max(0, Math.min(cursor - line.startOffset, line.line.length))
+      return { row: i, col }
+    }
+  }
+
+  return { row: Math.max(0, lines.length - 1), col: 0 }
+}
+
+/**
+ * Get all wrapped display lines with their starting character offsets.
+ *
+ * Each entry represents one visual line on screen. The startOffset can be
+ * used to convert a (row, col) back to a flat cursor position:
+ * `flatOffset = lines[row].startOffset + col`
+ */
+export function getWrappedLines(text: string, wrapWidth: number, measurer?: Measurer): WrappedLine[] {
+  if (wrapWidth <= 0) return [{ line: "", startOffset: 0 }]
+
+  const logicalLines = text.split("\n")
+  const result: WrappedLine[] = []
+  let offset = 0
+  // Use explicit measurer when available, fall back to module-level convenience function
+  const wt = measurer ? measurer.wrapText.bind(measurer) : wrapText
+
+  for (let li = 0; li < logicalLines.length; li++) {
+    const line = logicalLines[li]!
+    // Use trim=true to match the renderer's wrapping behavior.
+    // The renderer uses wrapText(text, width, true, true), so cursor math
+    // must produce the same visual lines to keep positions synchronized.
+    const wrapped = wt(line, wrapWidth, false, true)
+    const lines = wrapped.length === 0 ? [""] : wrapped
+
+    for (const wLine of lines) {
+      // Skip whitespace in the original text that was trimmed:
+      // - Leading spaces on continuation lines (trimmed by renderer)
+      // - Trailing space at break point (consumed as separator by renderer)
+      while (offset < text.length && text[offset] === " " && wLine.length > 0 && text[offset] !== wLine[0]) {
+        offset++
+      }
+      result.push({ line: wLine, startOffset: offset })
+      offset += wLine.length
+    }
+    // Skip any remaining trailing spaces before the newline
+    while (offset < text.length && text[offset] === " ") {
+      offset++
+    }
+    offset++ // for \n
+  }
+
+  return result
+}
+
+/**
+ * Convert visual (row, col) to a flat cursor offset.
+ *
+ * Clamps col to the line length if the target column exceeds it
+ * (important for stickyX behavior on short lines).
+ */
+export function rowColToCursor(text: string, row: number, col: number, wrapWidth: number, measurer?: Measurer): number {
+  const lines = getWrappedLines(text, wrapWidth, measurer)
+  if (row < 0) return 0
+  if (row >= lines.length) return text.length
+  const line = lines[row]!
+  return line.startOffset + Math.min(col, line.line.length)
+}
+
+/**
+ * Move cursor up one visual line.
+ *
+ * Returns the new cursor offset, or null if already on the first visual line
+ * (indicating a boundary — the caller should handle cross-block navigation).
+ *
+ * @param stickyX - Preferred column position for vertical movement.
+ *   When moving through lines of different lengths, the cursor tries to
+ *   stay at this column. Pass the col from the original position before
+ *   the first vertical move in a sequence.
+ */
+export function cursorMoveUp(
+  text: string,
+  cursor: number,
+  wrapWidth: number,
+  stickyX?: number,
+  measurer?: Measurer,
+): number | null {
+  if (wrapWidth <= 0) return cursor > 0 ? 0 : null
+
+  const lines = getWrappedLines(text, wrapWidth, measurer)
+  const { row, col } = cursorToRowColFromLines(lines, cursor)
+
+  if (row === 0) return null // at first visual line — boundary
+
+  const targetX = stickyX ?? col
+  // Try successive lines upward: if the target position equals the current cursor
+  // (happens at wrap boundaries), keep going up to make real progress.
+  for (let prevRow = row - 1; prevRow >= 0; prevRow--) {
+    const targetLine = lines[prevRow]!
+    const next = targetLine.startOffset + Math.min(targetX, targetLine.line.length)
+    if (next !== cursor) return next
+  }
+  return null // all preceding lines map to same position — boundary
+}
+
+/**
+ * Move cursor down one visual line.
+ *
+ * Returns the new cursor offset, or null if already on the last visual line
+ * (indicating a boundary — the caller should handle cross-block navigation).
+ *
+ * @param stickyX - Preferred column position for vertical movement.
+ */
+export function cursorMoveDown(
+  text: string,
+  cursor: number,
+  wrapWidth: number,
+  stickyX?: number,
+  measurer?: Measurer,
+): number | null {
+  if (wrapWidth <= 0) return cursor < text.length ? text.length : null
+
+  const lines = getWrappedLines(text, wrapWidth, measurer)
+  const { row, col } = cursorToRowColFromLines(lines, cursor)
+
+  if (row >= lines.length - 1) return null // at last visual line — boundary
+
+  const targetX = stickyX ?? col
+  // Try successive lines: if the target position equals the current cursor
+  // (happens at wrap boundaries where end-of-line-N == start-of-line-N+1),
+  // advance to the next line to make real progress.
+  for (let nextRow = row + 1; nextRow < lines.length; nextRow++) {
+    const targetLine = lines[nextRow]!
+    const next = targetLine.startOffset + Math.min(targetX, targetLine.line.length)
+    if (next !== cursor) return next
+  }
+  return null // all remaining lines map to same position — boundary
+}
+
+/**
+ * Count total visual lines after word wrapping.
+ */
+export function countVisualLines(text: string, wrapWidth: number, measurer?: Measurer): number {
+  return getWrappedLines(text, wrapWidth, measurer).length
+}

package/src/text-decorations.ts

@@ -0,0 +1,253 @@
+/**
+ * Text Decorations — SlateJS-style overlay ranges for styled text.
+ *
+ * Decorations overlay visual styles on text without modifying the underlying
+ * content. Use cases: search highlighting, syntax coloring, spell-check
+ * underlines, diff markers, collaborative cursors.
+ *
+ * Architecture layer 0 — no state, no hooks, no components. Pure functions.
+ *
+ * @example
+ * ```ts
+ * import { splitIntoSegments, type Decoration } from '@silvery/tea/text-decorations'
+ *
+ * const decorations: Decoration[] = [
+ *   { from: 0, to: 5, style: { backgroundColor: "yellow" } },
+ *   { from: 10, to: 15, style: { bold: true } },
+ * ]
+ *
+ * // Split a line range into styled segments
+ * const segments = splitIntoSegments(0, 20, decorations, null)
+ * // => [
+ * //   { from: 0, to: 5, style: { backgroundColor: "yellow" } },
+ * //   { from: 5, to: 10, style: {} },
+ * //   { from: 10, to: 15, style: { bold: true } },
+ * //   { from: 15, to: 20, style: {} },
+ * // ]
+ * ```
+ */
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Style properties for a decoration. Matches silvery Text component props.
+ * All properties are optional — only specified properties are applied.
+ */
+export interface DecorationStyle {
+  /** Foreground color (hex, named, or $token) */
+  color?: string
+  /** Background color (hex, named, or $token) */
+  backgroundColor?: string
+  /** Bold text */
+  bold?: boolean
+  /** Italic text */
+  italic?: boolean
+  /** Underline text */
+  underline?: boolean
+  /** Strikethrough text */
+  strikethrough?: boolean
+  /** Dim (reduced intensity) */
+  dimColor?: boolean
+  /** Inverse (swap fg/bg) */
+  inverse?: boolean
+}
+
+/**
+ * A decoration range that overlays styles on text.
+ *
+ * Ranges are half-open: [from, to) — `from` is inclusive, `to` is exclusive.
+ * Ranges refer to character offsets in the full text value.
+ */
+export interface Decoration {
+  /** Start offset in the text (inclusive) */
+  from: number
+  /** End offset in the text (exclusive) */
+  to: number
+  /** Style properties to apply to this range */
+  style: DecorationStyle
+}
+
+/**
+ * A resolved segment with merged styles. Produced by splitIntoSegments().
+ * Segments are non-overlapping and sorted by position.
+ */
+export interface StyledSegment {
+  /** Start offset (inclusive) */
+  from: number
+  /** End offset (exclusive) */
+  to: number
+  /** Merged style from all overlapping decorations */
+  style: DecorationStyle
+  /** Whether this segment is within the selection */
+  selected?: boolean
+}
+
+/** Selection range as [start, end) character offsets */
+export interface SelectionRange {
+  start: number
+  end: number
+}
+
+// =============================================================================
+// Segment Splitting
+// =============================================================================
+
+/**
+ * Split a line range into non-overlapping styled segments.
+ *
+ * Takes a range [lineStart, lineEnd), an array of decorations, and an optional
+ * selection range. Returns sorted, non-overlapping segments that cover the
+ * entire line range.
+ *
+ * Rules:
+ * - Selection takes precedence over decorations (selected text ignores decoration styles)
+ * - Later decorations override earlier ones for overlapping style properties
+ * - Empty segments (from === to) are omitted
+ * - Decorations outside [lineStart, lineEnd) are clipped
+ *
+ * @param lineStart - Start of the line range (inclusive, character offset in full text)
+ * @param lineEnd - End of the line range (exclusive)
+ * @param decorations - Array of decoration ranges (may be empty)
+ * @param selection - Optional selection range, or null
+ * @returns Array of non-overlapping StyledSegment objects covering [lineStart, lineEnd)
+ */
+export function splitIntoSegments(
+  lineStart: number,
+  lineEnd: number,
+  decorations: readonly Decoration[],
+  selection: SelectionRange | null,
+): StyledSegment[] {
+  if (lineStart >= lineEnd) return []
+
+  // Collect all boundary points within the line range
+  const boundaries = new Set<number>()
+  boundaries.add(lineStart)
+  boundaries.add(lineEnd)
+
+  // Add decoration boundaries (clipped to line range)
+  for (const dec of decorations) {
+    if (dec.to <= lineStart || dec.from >= lineEnd) continue
+    boundaries.add(Math.max(dec.from, lineStart))
+    boundaries.add(Math.min(dec.to, lineEnd))
+  }
+
+  // Add selection boundaries (clipped to line range)
+  if (selection && selection.start < lineEnd && selection.end > lineStart) {
+    boundaries.add(Math.max(selection.start, lineStart))
+    boundaries.add(Math.min(selection.end, lineEnd))
+  }
+
+  // Sort boundaries
+  const sorted = Array.from(boundaries).sort((a, b) => a - b)
+
+  // Build segments
+  const segments: StyledSegment[] = []
+  for (let i = 0; i < sorted.length - 1; i++) {
+    const from = sorted[i]!
+    const to = sorted[i + 1]!
+    if (from >= to) continue
+
+    // Check if this segment is within the selection
+    const isSelected = selection !== null && from >= selection.start && to <= selection.end
+
+    // Merge styles from all overlapping decorations (later wins for conflicts)
+    const mergedStyle: DecorationStyle = {}
+    for (const dec of decorations) {
+      if (dec.from >= to || dec.to <= from) continue
+      // Merge: later decoration properties override earlier ones
+      Object.assign(mergedStyle, dec.style)
+    }
+
+    segments.push({
+      from,
+      to,
+      style: mergedStyle,
+      ...(isSelected ? { selected: true } : {}),
+    })
+  }
+
+  return segments
+}
+
+// =============================================================================
+// Decoration Utilities
+// =============================================================================
+
+/**
+ * Create decorations for all occurrences of a search string in text.
+ *
+ * @param text - The full text to search in
+ * @param query - The search string (case-insensitive)
+ * @param style - Style to apply to matches
+ * @returns Array of Decoration objects for all matches
+ */
+export function createSearchDecorations(
+  text: string,
+  query: string,
+  style: DecorationStyle = { backgroundColor: "yellow", color: "black" },
+): Decoration[] {
+  if (!query || !text) return []
+
+  const decorations: Decoration[] = []
+  const lowerText = text.toLowerCase()
+  const lowerQuery = query.toLowerCase()
+  let pos = 0
+
+  while (pos < lowerText.length) {
+    const idx = lowerText.indexOf(lowerQuery, pos)
+    if (idx === -1) break
+    decorations.push({
+      from: idx,
+      to: idx + query.length,
+      style,
+    })
+    pos = idx + 1 // Allow overlapping matches
+  }
+
+  return decorations
+}
+
+/**
+ * Adjust decoration positions after a text edit operation.
+ *
+ * When text is inserted or deleted, decoration ranges need to shift
+ * to maintain their association with the correct text content.
+ *
+ * @param decorations - Existing decorations
+ * @param editStart - Position where the edit occurred
+ * @param deletedLength - Number of characters deleted (0 for pure insert)
+ * @param insertedLength - Number of characters inserted (0 for pure delete)
+ * @returns New array of adjusted decorations (removed decorations are filtered out)
+ */
+export function adjustDecorations(
+  decorations: readonly Decoration[],
+  editStart: number,
+  deletedLength: number,
+  insertedLength: number,
+): Decoration[] {
+  const delta = insertedLength - deletedLength
+  const editEnd = editStart + deletedLength
+
+  return decorations
+    .map((dec) => {
+      // Decoration is entirely before the edit — no change
+      if (dec.to <= editStart) return dec
+
+      // Decoration is entirely after the edit — shift by delta
+      if (dec.from >= editEnd) {
+        return { ...dec, from: dec.from + delta, to: dec.to + delta }
+      }
+
+      // Decoration overlaps the edit region — adjust boundaries
+      const newFrom = dec.from < editStart ? dec.from : editStart + insertedLength
+      const newTo = dec.to <= editEnd ? editStart + insertedLength : dec.to + delta
+
+      // If the decoration collapses to zero width, remove it
+      if (newFrom >= newTo) return null
+
+      return { ...dec, from: newFrom, to: newTo }
+    })
+    .filter((dec): dec is Decoration => dec !== null)
+}