@rlabs-inc/tui 0.3.2 → 0.6.0

package/src/state/context.ts

@@ -0,0 +1,212 @@
+/**
+ * TUI Framework - Reactive Context System
+ *
+ * Provides React-like context for passing data deep without prop drilling.
+ * Uses ReactiveMap for automatic reactive subscriptions - no explicit
+ * subscribe/unsubscribe needed!
+ *
+ * How it works:
+ * - ReactiveMap has per-key fine-grained reactivity
+ * - Reading from the map inside a derived/effect auto-subscribes
+ * - Writing to the map auto-notifies all readers of that key
+ *
+ * Usage:
+ * ```ts
+ * // Create a context
+ * const ThemeContext = createContext<Theme>(defaultTheme)
+ *
+ * // Provider sets it
+ * provide(ThemeContext, darkTheme)
+ *
+ * // Consumer reads it - automatically reactive!
+ * function ThemedBox() {
+ *   const theme = useContext(ThemeContext)
+ *   return box({ bg: theme.background })
+ * }
+ *
+ * // Update context - all consumers re-render
+ * provide(ThemeContext, lightTheme)
+ * ```
+ */
+
+import { ReactiveMap, signal, type WritableSignal } from '@rlabs-inc/signals'
+
+// =============================================================================
+// Context Types
+// =============================================================================
+
+/**
+ * A context identifier with type information.
+ * The symbol ensures uniqueness, the type parameter ensures type safety.
+ */
+export interface Context<T> {
+  /** Unique identifier for this context */
+  readonly id: symbol
+  /** Default value if no provider exists */
+  readonly defaultValue: T
+  /** Display name for debugging */
+  readonly displayName?: string
+}
+
+// =============================================================================
+// Context Storage
+// =============================================================================
+
+/**
+ * Global reactive storage for all context values.
+ *
+ * Using ReactiveMap means:
+ * - get(key) inside derived/effect = auto-subscribe to that key
+ * - set(key, value) = auto-notify all subscribers of that key
+ *
+ * This is the magic that makes context automatically reactive!
+ */
+const contextValues = new ReactiveMap<symbol, unknown>()
+
+/**
+ * Signal wrappers for contexts that need .value access pattern.
+ * When a user provides a signal, we store it directly.
+ * When they provide a static value, we wrap it in a signal.
+ */
+const contextSignals = new ReactiveMap<symbol, WritableSignal<unknown>>()
+
+// =============================================================================
+// Context API
+// =============================================================================
+
+/**
+ * Create a new context with a default value.
+ *
+ * @param defaultValue - Value used when no provider exists
+ * @param displayName - Optional name for debugging
+ * @returns A Context object to use with provide() and useContext()
+ *
+ * @example
+ * ```ts
+ * const UserContext = createContext<User | null>(null)
+ * const ThemeContext = createContext(defaultTheme, 'Theme')
+ * ```
+ */
+export function createContext<T>(defaultValue: T, displayName?: string): Context<T> {
+  return {
+    id: Symbol(displayName ?? 'Context'),
+    defaultValue,
+    displayName,
+  }
+}
+
+/**
+ * Provide a value for a context.
+ *
+ * Can be called multiple times to update the context value.
+ * All consumers using useContext() will automatically update.
+ *
+ * @param context - The context to provide
+ * @param value - The value to provide (static or signal)
+ *
+ * @example
+ * ```ts
+ * // Static value
+ * provide(ThemeContext, darkTheme)
+ *
+ * // Signal - consumers react to signal changes too!
+ * const theme = signal(darkTheme)
+ * provide(ThemeContext, theme)
+ * theme.value = lightTheme  // All consumers update!
+ * ```
+ */
+export function provide<T>(context: Context<T>, value: T | WritableSignal<T>): void {
+  // Check if value is a signal from @rlabs-inc/signals
+  // Signals have a Symbol('signal.source') property that plain objects don't have
+  // This is more reliable than just checking for 'value' since regular objects
+  // might have a 'value' property but won't have the internal signal symbol
+  if (
+    value !== null &&
+    typeof value === 'object' &&
+    'value' in value &&
+    Object.getOwnPropertySymbols(value).some((sym) => sym.description === 'signal.source')
+  ) {
+    // It's a signal - store it directly for reactive access
+    contextSignals.set(context.id, value as WritableSignal<unknown>)
+    contextValues.set(context.id, value)
+  } else {
+    // Static value - wrap in a signal for consistent access
+    const existing = contextSignals.get(context.id)
+    if (existing) {
+      // Update existing signal
+      existing.value = value
+    } else {
+      // Create new signal
+      const sig = signal(value)
+      contextSignals.set(context.id, sig as WritableSignal<unknown>)
+    }
+    contextValues.set(context.id, value)
+  }
+}
+
+/**
+ * Get the current value of a context.
+ *
+ * This is automatically reactive when used inside:
+ * - derived(() => ...)
+ * - effect(() => ...)
+ * - Component prop getters: () => useContext(...)
+ *
+ * @param context - The context to read
+ * @returns The current context value, or defaultValue if no provider
+ *
+ * @example
+ * ```ts
+ * function MyComponent() {
+ *   const theme = useContext(ThemeContext)
+ *   return box({ bg: theme.background })
+ * }
+ * ```
+ */
+export function useContext<T>(context: Context<T>): T {
+  // Check for signal wrapper first (for .value reactivity)
+  const sig = contextSignals.get(context.id)
+  if (sig !== undefined) {
+    return sig.value as T
+  }
+
+  // Fall back to direct value lookup (still reactive via ReactiveMap!)
+  const value = contextValues.get(context.id)
+  if (value !== undefined) {
+    return value as T
+  }
+
+  return context.defaultValue
+}
+
+/**
+ * Check if a context has been provided.
+ *
+ * @param context - The context to check
+ * @returns true if provide() has been called for this context
+ */
+export function hasContext<T>(context: Context<T>): boolean {
+  return contextValues.has(context.id)
+}
+
+/**
+ * Clear a context, returning to default value.
+ *
+ * @param context - The context to clear
+ */
+export function clearContext<T>(context: Context<T>): void {
+  contextValues.delete(context.id)
+  contextSignals.delete(context.id)
+}
+
+// =============================================================================
+// Reset (for testing)
+// =============================================================================
+
+/**
+ * Reset all context state (for testing)
+ */
+export function resetContexts(): void {
+  contextValues.clear()
+  contextSignals.clear()
+}

package/src/state/drawnCursor.ts

@@ -0,0 +1,326 @@
+/**
+ * TUI Framework - Drawn Cursor State
+ *
+ * Manages cursor state for input components (input, textarea, custom editors).
+ * Unlike the terminal native cursor (cursor.ts), this cursor is drawn into
+ * the frameBuffer and supports full customization.
+ *
+ * Features:
+ * - Style presets (block, bar, underline) or custom characters
+ * - Blink animation with configurable FPS (default: 2 FPS)
+ * - Custom colors (fg/bg) or inherit from component
+ * - Alt character for blink "off" phase
+ * - Integrates with animation module for efficient shared clocks
+ *
+ * Usage:
+ * ```ts
+ * import { createCursor, disposeCursor } from '../state/drawnCursor'
+ *
+ * // In input component:
+ * const cursor = createCursor(index, {
+ *   style: 'bar',
+ *   blink: true,
+ *   fps: 2,
+ * })
+ *
+ * // Update position
+ * cursor.setPosition(5)
+ *
+ * // Cleanup on unmount
+ * disposeCursor(index)
+ * ```
+ */
+
+import { signal } from '@rlabs-inc/signals'
+import * as interaction from '../engine/arrays/interaction'
+import { registerFocusCallbacks } from './focus'
+import { onDestroy } from '../engine/lifecycle'
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export type DrawnCursorStyle = 'block' | 'bar' | 'underline'
+
+export interface DrawnCursorConfig {
+  /** Cursor style preset */
+  style?: DrawnCursorStyle
+  /** Custom cursor character (overrides style) */
+  char?: string
+  /** Enable blink animation (default: true) */
+  blink?: boolean
+  /** Blink FPS (default: 2, which gives 500ms on/off cycle) */
+  fps?: number
+  /** Alt character for blink "off" phase (default: invisible/space) */
+  altChar?: string
+  /** Initial cursor position */
+  position?: number
+}
+
+export interface DrawnCursor {
+  /** Set cursor position in text */
+  setPosition: (pos: number) => void
+  /** Get current position */
+  getPosition: () => number
+  /** Manually show cursor (override blink) */
+  show: () => void
+  /** Manually hide cursor (override blink) */
+  hide: () => void
+  /** Check if cursor is currently visible */
+  isVisible: () => boolean
+  /** Cleanup - stops animation, clears arrays */
+  dispose: () => void
+}
+
+// =============================================================================
+// CURSOR CHARACTER CODEPOINTS
+// =============================================================================
+
+const CURSOR_CHARS: Record<DrawnCursorStyle, number> = {
+  block: 0,        // 0 = special case: inverse block (swap fg/bg)
+  bar: 0x2502,     // │ vertical line
+  underline: 0x5F, // _ underscore
+}
+
+// =============================================================================
+// BLINK ANIMATION REGISTRY
+// Shared clocks per FPS - same pattern as animation.ts
+// =============================================================================
+
+interface BlinkRegistry {
+  phase: ReturnType<typeof signal<boolean>>
+  interval: ReturnType<typeof setInterval> | null
+  subscribers: number
+}
+
+const blinkRegistry = new Map<number, BlinkRegistry>()
+
+function getBlinkClock(fps: number): BlinkRegistry {
+  let registry = blinkRegistry.get(fps)
+
+  if (!registry) {
+    registry = {
+      phase: signal(true), // true = visible
+      interval: null,
+      subscribers: 0,
+    }
+    blinkRegistry.set(fps, registry)
+  }
+
+  return registry
+}
+
+function subscribeToBlink(fps: number): () => void {
+  // Guard against invalid fps (0 or negative would cause Infinity interval)
+  if (fps <= 0) {
+    return () => {} // No-op unsubscribe
+  }
+
+  const registry = getBlinkClock(fps)
+  registry.subscribers++
+
+  // Start interval if first subscriber
+  if (registry.subscribers === 1 && !registry.interval) {
+    const ms = Math.floor(1000 / fps / 2) // Divide by 2 for on/off cycle
+    registry.interval = setInterval(() => {
+      registry.phase.value = !registry.phase.value
+    }, ms)
+  }
+
+  return () => {
+    registry.subscribers = Math.max(0, registry.subscribers - 1)
+
+    // Stop interval if no more subscribers
+    if (registry.subscribers === 0 && registry.interval) {
+      clearInterval(registry.interval)
+      registry.interval = null
+      registry.phase.value = true // Reset to visible
+    }
+  }
+}
+
+// =============================================================================
+// ACTIVE CURSORS REGISTRY
+// =============================================================================
+
+const activeCursors = new Map<number, {
+  unsubscribeBlink: (() => void) | null
+  unsubscribeFocus: () => void
+  manualVisible: ReturnType<typeof signal<boolean | null>>
+}>()
+
+// =============================================================================
+// CREATE CURSOR
+// =============================================================================
+
+/**
+ * Create a drawn cursor for a component.
+ *
+ * @param index Component index
+ * @param config Cursor configuration
+ * @returns Cursor control object
+ *
+ * @example
+ * ```ts
+ * const cursor = createCursor(index, {
+ *   style: 'bar',      // 'block' | 'bar' | 'underline'
+ *   blink: true,       // default: true
+ *   fps: 2,            // default: 2 (500ms cycle)
+ * })
+ *
+ * cursor.setPosition(5)
+ * ```
+ */
+export function createCursor(index: number, config: DrawnCursorConfig = {}): DrawnCursor {
+  const {
+    style = 'block',
+    char,
+    blink = true,
+    fps = 2,
+    altChar,
+    position = 0,
+  } = config
+
+  // Determine cursor character codepoint
+  let charCode: number
+  if (char) {
+    charCode = char.codePointAt(0) ?? 0
+  } else {
+    charCode = CURSOR_CHARS[style]
+  }
+
+  // Determine alt character for blink "off" phase
+  const altCharCode = altChar ? (altChar.codePointAt(0) ?? 0) : 0
+
+  // Set cursor arrays
+  interaction.cursorChar.setSource(index, charCode)
+  interaction.cursorAltChar.setSource(index, altCharCode)
+  interaction.cursorBlinkFps.setSource(index, blink ? fps : 0)
+  interaction.cursorPosition.setSource(index, position)
+
+  // Manual visibility override (null = use blink, true/false = override)
+  const manualVisible = signal<boolean | null>(null)
+
+  // Blink subscription (managed by focus callbacks, not effect)
+  let unsubscribeBlink: (() => void) | null = null
+  const shouldBlink = blink && fps > 0
+
+  // Register focus callbacks to start/stop blink (imperative, at the source)
+  const unsubscribeFocus = registerFocusCallbacks(index, {
+    onFocus: () => {
+      if (shouldBlink && !unsubscribeBlink) {
+        unsubscribeBlink = subscribeToBlink(fps)
+      }
+    },
+    onBlur: () => {
+      if (unsubscribeBlink) {
+        unsubscribeBlink()
+        unsubscribeBlink = null
+      }
+    },
+  })
+
+  // Cursor visibility as derived getter (reactive, no effect)
+  interaction.cursorVisible.setSource(index, () => {
+    // Manual override takes precedence
+    if (manualVisible.value !== null) {
+      return manualVisible.value ? 1 : 0
+    }
+    // Not focused = always visible (cursor shows but doesn't blink)
+    if (interaction.focusedIndex.value !== index) {
+      return 1
+    }
+    // Focused + blink disabled = always visible
+    if (!shouldBlink) {
+      return 1
+    }
+    // Focused + blink enabled = follow blink clock
+    return getBlinkClock(fps).phase.value ? 1 : 0
+  })
+
+  // Store in registry for cleanup
+  activeCursors.set(index, {
+    unsubscribeBlink,
+    unsubscribeFocus,
+    manualVisible,
+  })
+
+  // Register safety-net cleanup with lifecycle system.
+  // This ensures cursor is disposed even if component forgets to call dispose()
+  // or an error path skips cleanup. disposeCursor() is idempotent (safe to call twice).
+  onDestroy(() => {
+    disposeCursor(index)
+  })
+
+  // Return control object
+  return {
+    setPosition(pos: number) {
+      interaction.cursorPosition.setSource(index, pos)
+    },
+
+    getPosition() {
+      return interaction.cursorPosition[index] || 0
+    },
+
+    show() {
+      manualVisible.value = true
+    },
+
+    hide() {
+      manualVisible.value = false
+    },
+
+    isVisible() {
+      return (interaction.cursorVisible[index] ?? 1) === 1
+    },
+
+    dispose() {
+      disposeCursor(index)
+    },
+  }
+}
+
+// =============================================================================
+// DISPOSE CURSOR
+// =============================================================================
+
+/**
+ * Dispose a cursor and clean up its resources.
+ *
+ * @param index Component index
+ */
+export function disposeCursor(index: number): void {
+  const cursor = activeCursors.get(index)
+
+  if (cursor) {
+    // Unsubscribe from focus callbacks
+    cursor.unsubscribeFocus()
+
+    // Unsubscribe from blink (if active)
+    cursor.unsubscribeBlink?.()
+
+    // Remove from registry
+    activeCursors.delete(index)
+  }
+
+  // Clear cursor arrays
+  interaction.cursorChar.clear(index)
+  interaction.cursorAltChar.clear(index)
+  interaction.cursorBlinkFps.clear(index)
+  interaction.cursorVisible.clear(index)
+  // Note: cursorPosition is managed by component, don't clear here
+}
+
+// =============================================================================
+// UTILITY EXPORTS
+// =============================================================================
+
+/** Get cursor style codepoint */
+export function getCursorCharCode(style: DrawnCursorStyle): number {
+  return CURSOR_CHARS[style]
+}
+
+/** Check if a component has an active cursor */
+export function hasCursor(index: number): boolean {
+  return activeCursors.has(index)
+}

package/src/state/focus.ts

@@ -11,11 +11,70 @@
 import { signal, derived, unwrap } from '@rlabs-inc/signals'
 import { focusable, tabIndex, focusedIndex as _focusedIndex } from '../engine/arrays/interaction'
 import { visible } from '../engine/arrays/core'
-import { getAllocatedIndices } from '../engine/registry'
+import { getAllocatedIndices, getId } from '../engine/registry'
 
 // Re-export the focusedIndex from interaction arrays
 export const focusedIndex = _focusedIndex
 
+// =============================================================================
+// FOCUS CALLBACKS (event integration at the source)
+// Supports MULTIPLE callback registrations per index (e.g., cursor blink + user callback)
+// =============================================================================
+
+interface FocusCallbacks {
+  onFocus?: () => void
+  onBlur?: () => void
+}
+
+// Store arrays of callbacks - multiple registrations allowed per index
+const focusCallbackRegistry = new Map<number, FocusCallbacks[]>()
+
+/** Register focus callbacks for a component - returns unsubscribe function */
+export function registerFocusCallbacks(index: number, callbacks: FocusCallbacks): () => void {
+  let list = focusCallbackRegistry.get(index)
+  if (!list) {
+    list = []
+    focusCallbackRegistry.set(index, list)
+  }
+  list.push(callbacks)
+
+  return () => {
+    const arr = focusCallbackRegistry.get(index)
+    if (arr) {
+      const idx = arr.indexOf(callbacks)
+      if (idx >= 0) arr.splice(idx, 1)
+      if (arr.length === 0) focusCallbackRegistry.delete(index)
+    }
+  }
+}
+
+/** Internal: Set focus and fire callbacks at the source */
+function setFocusWithCallbacks(newIndex: number): void {
+  const oldIndex = focusedIndex.value
+
+  // No change, no callbacks
+  if (oldIndex === newIndex) return
+
+  // Fire onBlur for all callbacks on old focus
+  if (oldIndex >= 0) {
+    const callbacks = focusCallbackRegistry.get(oldIndex)
+    if (callbacks) {
+      for (const cb of callbacks) cb.onBlur?.()
+    }
+  }
+
+  // Update reactive state
+  focusedIndex.value = newIndex
+
+  // Fire onFocus for all callbacks on new focus
+  if (newIndex >= 0) {
+    const callbacks = focusCallbackRegistry.get(newIndex)
+    if (callbacks) {
+      for (const cb of callbacks) cb.onFocus?.()
+    }
+  }
+}
+
 // =============================================================================
 // FOCUS TRAP (for modals/dialogs)
 // =============================================================================
@@ -46,14 +105,20 @@ export function getFocusTrapContainer(): number | undefined {
 // FOCUS HISTORY (for restoration)
 // =============================================================================
 
-const focusHistory: number[] = []
+interface FocusHistoryEntry {
+  index: number
+  id: string | undefined
+}
+
+const focusHistory: FocusHistoryEntry[] = []
 const MAX_HISTORY = 10
 
 /** Save current focus to history */
 export function saveFocusToHistory(): void {
   const current = focusedIndex.value
   if (current >= 0) {
-    focusHistory.push(current)
+    const id = getId(current)
+    focusHistory.push({ index: current, id })
     if (focusHistory.length > MAX_HISTORY) {
       focusHistory.shift()
     }
@@ -63,13 +128,15 @@ export function saveFocusToHistory(): void {
 /** Restore focus from history */
 export function restoreFocusFromHistory(): boolean {
   while (focusHistory.length > 0) {
-    const index = focusHistory.pop()!
+    const entry = focusHistory.pop()!
+    // Verify the index hasn't been recycled for a different component
+    if (getId(entry.index) !== entry.id) continue
     // Check if component is still valid and focusable
     // Match TITAN's logic: undefined means visible, only 0/false means hidden
-    const isVisible = unwrap(visible[index])
+    const isVisible = unwrap(visible[entry.index])
     const isActuallyVisible = isVisible !== 0 && isVisible !== false
-    if (unwrap(focusable[index]) && isActuallyVisible) {
-      focusedIndex.value = index
+    if (unwrap(focusable[entry.index]) && isActuallyVisible) {
+      setFocusWithCallbacks(entry.index)
       return true
     }
   }
@@ -99,7 +166,7 @@ export function getFocusableIndices(): number[] {
   result.sort((a, b) => {
     const tabA = unwrap(tabIndex[a]) ?? 0
     const tabB = unwrap(tabIndex[b]) ?? 0
-    if (tabA !== tabB) return tabA - tabB
+    if (tabA !== tabB) return tabA < tabB ? -1 : 1
     return a - b // Stable sort by index
   })
 
@@ -152,7 +219,7 @@ export function focusNext(): boolean {
   const next = findNextFocusable(current, 1)
   if (next !== -1 && next !== current) {
     saveFocusToHistory()
-    focusedIndex.value = next
+    setFocusWithCallbacks(next)
     return true
   }
   return false
@@ -163,7 +230,7 @@ export function focusPrevious(): boolean {
   const prev = findNextFocusable(focusedIndex.value, -1)
   if (prev !== -1 && prev !== focusedIndex.value) {
     saveFocusToHistory()
-    focusedIndex.value = prev
+    setFocusWithCallbacks(prev)
     return true
   }
   return false
@@ -177,7 +244,7 @@ export function focus(index: number): boolean {
   if (unwrap(focusable[index]) && isActuallyVisible) {
     if (focusedIndex.value !== index) {
       saveFocusToHistory()
-      focusedIndex.value = index
+      setFocusWithCallbacks(index)
     }
     return true
   }
@@ -188,7 +255,7 @@ export function focus(index: number): boolean {
 export function blur(): void {
   if (focusedIndex.value >= 0) {
     saveFocusToHistory()
-    focusedIndex.value = -1
+    setFocusWithCallbacks(-1)
   }
 }
 
@@ -216,9 +283,10 @@ export function focusLast(): boolean {
 
 /** Reset all focus state (for testing) */
 export function resetFocusState(): void {
-  focusedIndex.value = -1
+  setFocusWithCallbacks(-1)
   focusTrapStack.length = 0
   focusHistory.length = 0
+  focusCallbackRegistry.clear()
 }
 
 // =============================================================================
@@ -249,4 +317,7 @@ export const focusManager = {
   // History
   saveFocusToHistory,
   restoreFocusFromHistory,
+
+  // Callbacks (event integration at source)
+  registerFocusCallbacks,
 }