@rlabs-inc/tui 0.6.0 → 0.8.1

package/README.md

@@ -16,26 +16,24 @@ A blazing-fast, fine-grained reactive terminal UI framework with complete flexbo
 ## Quick Start
 
 ```bash
-bun add tui @rlabs-inc/signals
+bun add @rlabs-inc/tui
 ```
 
 ```typescript
-import { mount, box, text, derived } from 'tui'
-import { signal } from '@rlabs-inc/signals'
+import { mount, box, text, signal, derived } from '@rlabs-inc/tui'
 
 // Create reactive state
 const count = signal(0)
 const doubled = derived(() => count.value * 2)
 
-// Build your UI
-box({ width: 40, height: 10, children: () => {
-  text({ content: count })                         // signal directly
-  text({ content: doubled })                       // derived directly
-  text({ content: () => `Count: ${count.value}` }) // () => for formatting
-}})
-
-// Mount to terminal
-mount()
+// Mount to terminal - build UI inside mount()
+mount(() => {
+  box({ width: 40, height: 10, children: () => {
+    text({ content: count })                         // signal directly
+    text({ content: doubled })                       // derived directly
+    text({ content: () => `Count: ${count.value}` }) // () => for formatting
+  }})
+})
 
 // Update anywhere - UI reacts automatically
 setInterval(() => count.value++, 1000)
@@ -85,12 +83,13 @@ User Signals → bind() → Parallel Arrays → layoutDerived → frameBufferDer
 
 ```bash
 # Run examples
-bun run examples/hello.ts
-bun run examples/showcase.ts
+bun run examples/showcase/01-hello-counter.ts
+bun run examples/showcase/08-todo-app.ts
+bun run examples/showcase/04-dashboard.ts
 
-# Run tests
-bun run examples/tests/01-box-basics.ts
+# Run visual tests
 bun run examples/tests/03-layout-flex.ts
+bun run examples/tests/05-flex-complete.ts
 ```
 
 ## Documentation
@@ -102,7 +101,7 @@ bun run examples/tests/03-layout-flex.ts
 - [First App Tutorial](./docs/getting-started/first-app.md) - Build a complete app
 
 ### User Guides
-- [Primitives](./docs/guides/primitives/) - box, text, each, show, when
+- [Primitives](./docs/guides/primitives/box.md) - box, text, each, show, when
 - [Layout](./docs/guides/layout/flexbox.md) - Flexbox layout system
 - [Styling](./docs/guides/styling/colors.md) - Colors, themes, borders
 - [Reactivity](./docs/guides/reactivity/signals.md) - Signals and reactivity
@@ -125,7 +124,7 @@ bun run examples/tests/03-layout-flex.ts
 |-----------|--------|-------------|
 | `box` | Complete | Container with flexbox layout |
 | `text` | Complete | Text display with styling |
-| `input` | Planned | Text input field |
+| `input` | Complete | Text input field |
 | `select` | Planned | Dropdown selection |
 | `progress` | Planned | Progress bar |
 
@@ -144,26 +143,28 @@ Reactive control flow for dynamic UIs - no manual effects needed!
 Renders a list of components that automatically updates when the array changes.
 
 ```typescript
-import { each, box, text, signal } from '@rlabs-inc/tui'
+import { mount, signal, each, box, text } from '@rlabs-inc/tui'
 
 const todos = signal([
   { id: '1', text: 'Learn TUI', done: false },
   { id: '2', text: 'Build app', done: false },
 ])
 
-box({
-  children: () => {
-    each(
-      () => todos.value,                    // Reactive array getter
-      (todo) => box({                       // Render function per item
-        id: `todo-${todo.id}`,              // Stable ID for reconciliation
-        children: () => {
-          text({ content: todo.text })      // Static value from item
-        }
-      }),
-      { key: (todo) => todo.id }            // Key function for efficient updates
-    )
-  }
+mount(() => {
+  box({
+    children: () => {
+      each(
+        () => todos.value,                      // Reactive array getter
+        (getItem, key) => box({                 // Render function: getItem() + stable key
+          id: `todo-${key}`,                    // Use key for stable ID
+          children: () => {
+            text({ content: () => getItem().text })  // Call getItem() to access value
+          }
+        }),
+        { key: (todo) => todo.id }              // Key function for efficient updates
+      )
+    }
+  })
 })
 
 // Add item - UI updates automatically
@@ -178,22 +179,24 @@ todos.value = todos.value.filter(t => t.id !== '1')
 Shows or hides components based on a reactive condition.
 
 ```typescript
-import { show, box, text, signal } from '@rlabs-inc/tui'
+import { mount, show, box, text, signal } from '@rlabs-inc/tui'
 
 const isLoggedIn = signal(false)
 
-box({
-  children: () => {
-    show(
-      () => isLoggedIn.value,               // Condition getter
-      () => box({                           // Render when true
-        children: () => {
-          text({ content: 'Welcome back!' })
-        }
-      }),
-      () => text({ content: 'Please log in' })  // Optional: render when false
-    )
-  }
+mount(() => {
+  box({
+    children: () => {
+      show(
+        () => isLoggedIn.value,               // Condition getter
+        () => box({                           // Render when true
+          children: () => {
+            text({ content: 'Welcome back!' })
+          }
+        }),
+        () => text({ content: 'Please log in' })  // Optional: render when false
+      )
+    }
+  })
 })
 
 // Toggle - UI switches automatically
@@ -205,7 +208,7 @@ isLoggedIn.value = true
 Handles async operations with loading, success, and error states.
 
 ```typescript
-import { when, box, text, signal } from '@rlabs-inc/tui'
+import { mount, when, box, text, signal } from '@rlabs-inc/tui'
 
 const userId = signal('123')
 
@@ -213,25 +216,27 @@ const userId = signal('123')
 const fetchUser = (id: string) =>
   fetch(`/api/users/${id}`).then(r => r.json())
 
-box({
-  children: () => {
-    when(
-      () => fetchUser(userId.value),        // Promise getter (re-runs on userId change)
-      {
-        pending: () => text({ content: 'Loading...' }),
-        then: (user) => box({
-          children: () => {
-            text({ content: `Name: ${user.name}` })
-            text({ content: `Email: ${user.email}` })
-          }
-        }),
-        catch: (error) => text({
-          content: `Error: ${error.message}`,
-          fg: 'red'
-        })
-      }
-    )
-  }
+mount(() => {
+  box({
+    children: () => {
+      when(
+        () => fetchUser(userId.value),        // Promise getter (re-runs on userId change)
+        {
+          pending: () => text({ content: 'Loading...' }),
+          then: (user) => box({
+            children: () => {
+              text({ content: `Name: ${user.name}` })
+              text({ content: `Email: ${user.email}` })
+            }
+          }),
+          catch: (error) => text({
+            content: `Error: ${error.message}`,
+            fg: 'red'
+          })
+        }
+      )
+    }
+  })
 })
 
 // Change userId - triggers new fetch, shows loading, then result

package/index.ts

@@ -10,7 +10,7 @@ export { mount } from './src/api'
 
 // Primitives - UI building blocks
 export { box, text, input, each, show, when, scoped, onCleanup, useAnimation, AnimationFrames } from './src/primitives'
-export type { BoxProps, TextProps, InputProps, CursorConfig, CursorStyle, Cleanup, AnimationOptions } from './src/primitives'
+export type { BoxProps, TextProps, InputProps, CursorConfig, CursorStyle, Cleanup, AnimationOptions, MouseProps } from './src/primitives'
 
 // Lifecycle hooks - Component mount/destroy callbacks
 export { onMount, onDestroy } from './src/engine/lifecycle'
@@ -21,6 +21,7 @@ export type { Context } from './src/state/context'
 
 // State modules - Input handling
 export { keyboard, lastKey, lastEvent } from './src/state/keyboard'
+export type { KeyHandler, KeyboardEvent as TuiKeyboardEvent, Modifiers } from './src/state/keyboard'
 export {
   mouse,
   hitGrid,
@@ -34,6 +35,7 @@ export {
   onScroll,
   onComponent,
 } from './src/state/mouse'
+export type { MouseEvent as TuiMouseEvent, MouseHandler, MouseHandlers } from './src/state/mouse'
 export { focusManager, focusedIndex, pushFocusTrap, popFocusTrap, isFocusTrapped, getFocusTrapContainer } from './src/state/focus'
 export { scroll } from './src/state/scroll'
 export { globalKeys } from './src/state/global-keys'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rlabs-inc/tui",
-  "version": "0.6.0",
+  "version": "0.8.1",
   "description": "The Terminal UI Framework for TypeScript/Bun - Blazing-fast, fine-grained reactive terminal UI with complete flexbox layout",
   "module": "index.ts",
   "main": "index.ts",

package/src/primitives/box.ts

@@ -35,7 +35,9 @@ import {
   popCurrentComponent,
   runMountCallbacks,
 } from '../engine/lifecycle'
-import { cleanupIndex as cleanupKeyboardListeners } from '../state/keyboard'
+import { cleanupIndex as cleanupKeyboardListeners, onFocused } from '../state/keyboard'
+import { registerFocusCallbacks, focus as focusComponent } from '../state/focus'
+import { onComponent as onMouseComponent } from '../state/mouse'
 import { getVariantStyle } from '../state/theme'
 import { getActiveScope } from './scope'
 import { enumSource } from './utils'
@@ -232,6 +234,53 @@ export function box(props: BoxProps = {}): Cleanup {
     if (props.tabIndex !== undefined) interaction.tabIndex.setSource(index, props.tabIndex)
   }
 
+  // ==========================================================================
+  // FOCUS CALLBACKS & KEYBOARD HANDLER
+  // Only registered when focusable AND callbacks provided
+  // ==========================================================================
+  let unsubKeyboard: (() => void) | undefined
+  let unsubFocusCallbacks: (() => void) | undefined
+
+  if (shouldBeFocusable) {
+    // Register keyboard handler (fires only when this box has focus)
+    if (props.onKey) {
+      unsubKeyboard = onFocused(index, props.onKey)
+    }
+
+    // Register focus/blur callbacks (fires at the source - focus manager)
+    if (props.onFocus || props.onBlur) {
+      unsubFocusCallbacks = registerFocusCallbacks(index, {
+        onFocus: props.onFocus,
+        onBlur: props.onBlur,
+      })
+    }
+  }
+
+  // ==========================================================================
+  // MOUSE HANDLERS
+  // Registered when focusable (for click-to-focus) OR any mouse callback provided
+  // ==========================================================================
+  let unsubMouse: (() => void) | undefined
+
+  const hasMouseHandlers = props.onMouseDown || props.onMouseUp || props.onClick || props.onMouseEnter || props.onMouseLeave || props.onScroll
+
+  if (shouldBeFocusable || hasMouseHandlers) {
+    unsubMouse = onMouseComponent(index, {
+      onMouseDown: props.onMouseDown,
+      onMouseUp: props.onMouseUp,
+      // Click-to-focus: focus this component on click (if focusable), then call user's handler
+      onClick: (event) => {
+        if (shouldBeFocusable) {
+          focusComponent(index)
+        }
+        return props.onClick?.(event)
+      },
+      onMouseEnter: props.onMouseEnter,
+      onMouseLeave: props.onMouseLeave,
+      onScroll: props.onScroll,
+    })
+  }
+
   // ==========================================================================
   // VISUAL - Colors and borders (only bind what's passed)
   // ==========================================================================
@@ -284,6 +333,9 @@ export function box(props: BoxProps = {}): Cleanup {
 
   // Cleanup function
   const cleanup = () => {
+    unsubFocusCallbacks?.()
+    unsubMouse?.()
+    unsubKeyboard?.()
     cleanupKeyboardListeners(index)  // Remove any focused key handlers
     releaseIndex(index)
   }

package/src/primitives/index.ts

@@ -15,6 +15,6 @@ export { scoped, onCleanup, componentScope, cleanupCollector } from './scope'
 export { useAnimation, AnimationFrames } from './animation'
 
 // Types
-export type { BoxProps, TextProps, InputProps, CursorConfig, CursorStyle, BlinkConfig, Cleanup } from './types'
+export type { BoxProps, TextProps, InputProps, CursorConfig, CursorStyle, BlinkConfig, Cleanup, MouseProps } from './types'
 export type { ComponentScopeResult } from './scope'
 export type { AnimationOptions } from './animation'

package/src/primitives/input.ts

@@ -32,6 +32,7 @@ import {
   runMountCallbacks,
 } from '../engine/lifecycle'
 import { cleanupIndex as cleanupKeyboardListeners, onFocused } from '../state/keyboard'
+import { onComponent as onMouseComponent } from '../state/mouse'
 import { getVariantStyle, t } from '../state/theme'
 import { focus as focusComponent, registerFocusCallbacks } from '../state/focus'
 import { createCursor, disposeCursor } from '../state/drawnCursor'
@@ -322,6 +323,23 @@ export function input(props: InputProps): Cleanup {
     onBlur: props.onBlur,
   })
 
+  // ==========================================================================
+  // MOUSE HANDLERS
+  // Always registered for inputs (click-to-focus) + any user callbacks
+  // ==========================================================================
+  const unsubMouse = onMouseComponent(index, {
+    onMouseDown: props.onMouseDown,
+    onMouseUp: props.onMouseUp,
+    // Click-to-focus: inputs are always focusable, so click always focuses
+    onClick: (event) => {
+      focusComponent(index)
+      return props.onClick?.(event)
+    },
+    onMouseEnter: props.onMouseEnter,
+    onMouseLeave: props.onMouseLeave,
+    onScroll: props.onScroll,
+  })
+
   // ==========================================================================
   // AUTO FOCUS
   // ==========================================================================
@@ -343,6 +361,7 @@ export function input(props: InputProps): Cleanup {
 
   const cleanup = () => {
     unsubFocusCallbacks()
+    unsubMouse()
     cursor.dispose()
     unsubKeyboard()
     cleanupKeyboardListeners(index)

package/src/primitives/text.ts

@@ -32,6 +32,7 @@ import {
   runMountCallbacks,
 } from '../engine/lifecycle'
 import { cleanupIndex as cleanupKeyboardListeners } from '../state/keyboard'
+import { onComponent as onMouseComponent } from '../state/mouse'
 import { getVariantStyle } from '../state/theme'
 import { getActiveScope } from './scope'
 import { enumSource } from './utils'
@@ -200,12 +201,30 @@ export function text(props: TextProps): Cleanup {
   }
   if (props.opacity !== undefined) visual.opacity.setSource(index, props.opacity)
 
+  // ==========================================================================
+  // MOUSE HANDLERS
+  // Registered when any mouse callback provided
+  // ==========================================================================
+  let unsubMouse: (() => void) | undefined
+
+  if (props.onMouseDown || props.onMouseUp || props.onClick || props.onMouseEnter || props.onMouseLeave || props.onScroll) {
+    unsubMouse = onMouseComponent(index, {
+      onMouseDown: props.onMouseDown,
+      onMouseUp: props.onMouseUp,
+      onClick: props.onClick,
+      onMouseEnter: props.onMouseEnter,
+      onMouseLeave: props.onMouseLeave,
+      onScroll: props.onScroll,
+    })
+  }
+
   // Component setup complete - run lifecycle callbacks
   popCurrentComponent()
   runMountCallbacks(index)
 
   // Cleanup function
   const cleanup = () => {
+    unsubMouse?.()
     cleanupKeyboardListeners(index)
     releaseIndex(index)
   }

package/src/primitives/types.ts

@@ -8,6 +8,8 @@
 import type { RGBA, CellAttrs, Dimension } from '../types'
 import type { WritableSignal, Binding, ReadonlyBinding } from '@rlabs-inc/signals'
 import type { Variant } from '../state/theme'
+import type { KeyHandler } from '../state/keyboard'
+import type { MouseEvent, MouseHandler } from '../state/mouse'
 
 // =============================================================================
 // REACTIVE PROP TYPES
@@ -122,11 +124,26 @@ export interface InteractionProps {
   tabIndex?: Reactive<number>
 }
 
+export interface MouseProps {
+  /** Called on mouse down over this component. Return true to consume event. */
+  onMouseDown?: (event: MouseEvent) => void | boolean
+  /** Called on mouse up over this component. Return true to consume event. */
+  onMouseUp?: (event: MouseEvent) => void | boolean
+  /** Called on click (down + up on same component). Return true to consume event. */
+  onClick?: (event: MouseEvent) => void | boolean
+  /** Called when mouse enters this component */
+  onMouseEnter?: (event: MouseEvent) => void
+  /** Called when mouse leaves this component */
+  onMouseLeave?: (event: MouseEvent) => void
+  /** Called on scroll over this component. Return true to consume event. */
+  onScroll?: (event: MouseEvent) => void | boolean
+}
+
 // =============================================================================
 // BOX PROPS
 // =============================================================================
 
-export interface BoxProps extends StyleProps, BorderProps, DimensionProps, SpacingProps, LayoutProps, InteractionProps {
+export interface BoxProps extends StyleProps, BorderProps, DimensionProps, SpacingProps, LayoutProps, InteractionProps, MouseProps {
   /** Component ID (optional, auto-generated if not provided) */
   id?: string
   /** Is visible */
@@ -138,13 +155,23 @@ export interface BoxProps extends StyleProps, BorderProps, DimensionProps, Spaci
    * Variants: 'default' | 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'info' | 'ghost' | 'outline'
    */
   variant?: Variant
+  /**
+   * Keyboard handler - fires only when this box has focus.
+   * Return true to consume the event (prevent propagation).
+   * Requires focusable: true or overflow: 'scroll'.
+   */
+  onKey?: KeyHandler
+  /** Called when this box receives focus */
+  onFocus?: () => void
+  /** Called when this box loses focus */
+  onBlur?: () => void
 }
 
 // =============================================================================
 // TEXT PROPS
 // =============================================================================
 
-export interface TextProps extends StyleProps, DimensionProps, SpacingProps, LayoutProps {
+export interface TextProps extends StyleProps, DimensionProps, SpacingProps, LayoutProps, MouseProps {
   /** Component ID (optional, auto-generated if not provided) */
   id?: string
   /** Text content (strings and numbers auto-converted) */
@@ -192,7 +219,7 @@ export interface CursorConfig {
   bg?: Reactive<RGBA>
 }
 
-export interface InputProps extends StyleProps, BorderProps, DimensionProps, SpacingProps, InteractionProps {
+export interface InputProps extends StyleProps, BorderProps, DimensionProps, SpacingProps, InteractionProps, MouseProps {
   /** Component ID (optional, auto-generated if not provided) */
   id?: string
   /** Current value (two-way bound) */