@rlabs-inc/tui 0.3.1 → 0.3.2

package/README.md

@@ -12,7 +12,6 @@ A blazing-fast, fine-grained reactive terminal UI framework with complete flexbo
 | Updates per second | 41,000+ |
 | Layout (10K components) | 0.66ms |
 | Memory per component | ~500 bytes |
-| Maximum components tested | 1,000,000 |
 
 ## Quick Start
 
@@ -21,15 +20,18 @@ bun add tui @rlabs-inc/signals
 ```
 
 ```typescript
-import { mount, box, text } from 'tui'
+import { mount, box, text, derived } from 'tui'
 import { signal } from '@rlabs-inc/signals'
 
 // 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: ${count.value}` })
+  text({ content: count })                         // signal directly
+  text({ content: doubled })                       // derived directly
+  text({ content: () => `Count: ${count.value}` }) // () => for formatting
 }})
 
 // Mount to terminal
@@ -56,6 +58,7 @@ setInterval(() => count.value++, 1000)
 - Effects for side effects
 - Bindings for prop connections
 - Zero reconciliation - reactivity IS the update mechanism
+- **Clean syntax**: Pass signals/deriveds directly, use `() =>` only for inline computations
 
 ### State Modules
 - **keyboard** - Key events, shortcuts, input buffering
@@ -155,7 +158,7 @@ box({
       (todo) => box({                       // Render function per item
         id: `todo-${todo.id}`,              // Stable ID for reconciliation
         children: () => {
-          text({ content: () => todo.text })  // Props can be reactive too!
+          text({ content: todo.text })      // Static value from item
         }
       }),
       { key: (todo) => todo.id }            // Key function for efficient updates

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rlabs-inc/tui",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "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",
@@ -15,7 +15,7 @@
     "src"
   ],
   "scripts": {
-    "dev": "bun run examples/hello.ts",
+    "dev": "bun run examples/showcase/01-hello-counter.ts",
     "test": "bun test",
     "typecheck": "tsc --noEmit"
   },

package/src/api/mount.ts

@@ -46,8 +46,22 @@ import { globalKeys } from '../state/global-keys'
  *
  * @param root - Function that creates the component tree
  * @param options - Mount options (mode, mouse, keyboard)
- * @returns Cleanup function to unmount
+ * @returns Cleanup function to unmount (or AppendMountResult for append mode)
  */
+// Overloads for proper return type inference
+export async function mount(
+  root: () => void,
+  options: MountOptions & { mode: 'append' }
+): Promise<AppendMountResult>
+export async function mount(
+  root: () => void,
+  options?: MountOptions & { mode?: 'fullscreen' | 'inline' }
+): Promise<() => Promise<void>>
+export async function mount(
+  root: () => void,
+  options?: MountOptions
+): Promise<(() => Promise<void>) | AppendMountResult>
+// Implementation
 export async function mount(
   root: () => void,
   options: MountOptions = {}

package/src/primitives/box.ts

@@ -116,15 +116,22 @@ function alignSelfToNum(align: string | undefined): number {
 /**
  * Create a slot source for enum props - returns getter for reactive, value for static.
  * For use with slotArray.setSource()
+ * Handles: static values, signals/bindings ({ value: T }), and getter functions (() => T)
  */
 function enumSource<T extends string>(
-  prop: T | { value: T } | undefined,
+  prop: T | { value: T } | (() => T) | undefined,
   converter: (val: T | undefined) => number
 ): number | (() => number) {
+  // Handle getter function (inline derived)
+  if (typeof prop === 'function') {
+    return () => converter(prop())
+  }
+  // Handle object with .value (signal/binding/derived)
   if (prop !== undefined && typeof prop === 'object' && prop !== null && 'value' in prop) {
     const reactiveSource = prop as { value: T }
     return () => converter(reactiveSource.value)
   }
+  // Static value
   return converter(prop as T | undefined)
 }
 

package/src/primitives/text.ts

@@ -76,18 +76,45 @@ function alignSelfToNum(alignSelf: string | undefined): number {
 
 // bindEnumProp removed - using enumSource instead
 
+/**
+ * Convert content prop (string | number) to string source for setSource.
+ * Handles: static values, signals, and getters.
+ */
+function contentToStringSource(
+  content: TextProps['content']
+): string | (() => string) {
+  // Getter function - wrap to convert
+  if (typeof content === 'function') {
+    return () => String(content())
+  }
+  // Signal/binding/derived with .value
+  if (content !== null && typeof content === 'object' && 'value' in content) {
+    const reactive = content as { value: string | number }
+    return () => String(reactive.value)
+  }
+  // Static value
+  return String(content)
+}
+
 /**
  * Create a slot source for enum props - returns getter for reactive, value for static.
  * For use with slotArray.setSource()
+ * Handles: static values, signals/bindings ({ value: T }), and getter functions (() => T)
  */
 function enumSource<T extends string>(
-  prop: T | { value: T } | undefined,
+  prop: T | { value: T } | (() => T) | undefined,
   converter: (val: T | undefined) => number
 ): number | (() => number) {
+  // Handle getter function (inline derived)
+  if (typeof prop === 'function') {
+    return () => converter(prop())
+  }
+  // Handle object with .value (signal/binding/derived)
   if (prop !== undefined && typeof prop === 'object' && prop !== null && 'value' in prop) {
     const reactiveSource = prop as { value: T }
     return () => converter(reactiveSource.value)
   }
+  // Static value
   return converter(prop as T | undefined)
 }
 
@@ -123,8 +150,9 @@ export function text(props: TextProps): Cleanup {
   // ==========================================================================
   // TEXT CONTENT - Always needed (this is a text component!)
   // Uses setSource() for stable slot tracking (fixes bind() replacement bug)
+  // Converts numbers to strings automatically
   // ==========================================================================
-  textArrays.textContent.setSource(index, props.content)
+  textArrays.textContent.setSource(index, contentToStringSource(props.content))
 
   // Text styling - only set if passed
   if (props.attrs !== undefined) textArrays.textAttrs.setSource(index, props.attrs)

package/src/primitives/types.ts

@@ -16,8 +16,15 @@ import type { Variant } from '../state/theme'
 /**
  * A prop value that can be static or reactive.
  * Components will sync reactive values automatically.
+ *
+ * Accepts:
+ * - Static value: `42`, `'hello'`
+ * - Signal: `mySignal`
+ * - Derived: `myDerived`
+ * - Binding: `bind(source)`
+ * - Getter (inline derived): `() => count.value * 2`
  */
-export type Reactive<T> = T | WritableSignal<T> | Binding<T> | ReadonlyBinding<T>
+export type Reactive<T> = T | WritableSignal<T> | Binding<T> | ReadonlyBinding<T> | (() => T)
 
 /**
  * Make specific props reactive while keeping others static.
@@ -138,8 +145,8 @@ export interface BoxProps extends StyleProps, BorderProps, DimensionProps, Spaci
 // =============================================================================
 
 export interface TextProps extends StyleProps, DimensionProps, SpacingProps, LayoutProps {
-  /** Text content */
-  content: Reactive<string>
+  /** Text content (strings and numbers auto-converted) */
+  content: Reactive<string | number>
   /** Text alignment: 'left' | 'center' | 'right' */
   align?: Reactive<'left' | 'center' | 'right'>
   /** Text attributes (bold, italic, etc.) */

package/src/state/keyboard.ts

@@ -52,7 +52,7 @@ export const lastKey = derived(() => lastEvent.value?.key ?? '')
 // =============================================================================
 
 const globalHandlers = new Set<KeyHandler>()
-const keyHandlers = new Map<string, Set<() => void | boolean>>()
+const keyHandlers = new Map<string, Set<() => void | boolean | Promise<void>>>()
 const focusedHandlers = new Map<number, Set<KeyHandler>>()
 
 // =============================================================================
@@ -118,8 +118,9 @@ export function on(handler: KeyHandler): () => void {
  * Subscribe to specific key(s).
  * Handler receives no arguments - check lastEvent if needed.
  * Return true to consume the event.
+ * Async handlers are supported (e.g., for cleanup functions).
  */
-export function onKey(key: string | string[], handler: () => void | boolean): () => void {
+export function onKey(key: string | string[], handler: () => void | boolean | Promise<void>): () => void {
   const keys = Array.isArray(key) ? key : [key]
   const unsubscribers: (() => void)[] = []