@rlabs-inc/tui 0.1.0 → 0.2.0

package/src/primitives/animation.ts

@@ -0,0 +1,194 @@
+/**
+ * TUI Framework - Animation Primitives
+ *
+ * Reusable animation utilities for spinners, progress indicators, etc.
+ * Handles frame cycling with proper lifecycle management.
+ *
+ * Usage:
+ * ```ts
+ * const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
+ *
+ * function LoadingSpinner(props): Cleanup {
+ *   return scoped(() => {
+ *     const frame = useAnimation(SPINNER, {
+ *       fps: 12,
+ *       active: () => props.loading.value,
+ *     })
+ *
+ *     text({ content: frame, fg: t.warning })
+ *   })
+ * }
+ * ```
+ */
+
+import { signal, derived, effect } from '@rlabs-inc/signals'
+import type { DerivedSignal } from '@rlabs-inc/signals'
+import { onCleanup, getActiveScope } from './scope'
+
+export interface AnimationOptions {
+  /** Frames per second (default: 12) */
+  fps?: number
+  /** Whether animation is active - can be reactive */
+  active?: boolean | (() => boolean) | { readonly value: boolean }
+  /** Start at a specific frame index (default: 0) */
+  startFrame?: number
+}
+
+// Global animation registry - shared intervals for same FPS
+interface AnimationRegistry {
+  frameIndex: ReturnType<typeof signal<number>>
+  interval: ReturnType<typeof setInterval> | null
+  subscribers: number
+}
+
+const animationRegistry = new Map<number, AnimationRegistry>()
+
+/**
+ * Get or create a shared animation clock for the given FPS.
+ */
+function getAnimationClock(fps: number): AnimationRegistry {
+  let registry = animationRegistry.get(fps)
+
+  if (!registry) {
+    registry = {
+      frameIndex: signal(0),
+      interval: null,
+      subscribers: 0,
+    }
+    animationRegistry.set(fps, registry)
+  }
+
+  return registry
+}
+
+/**
+ * Subscribe to an animation clock.
+ */
+function subscribeToAnimation(fps: number): () => void {
+  const registry = getAnimationClock(fps)
+  registry.subscribers++
+
+  // Start interval if this is the first subscriber
+  if (registry.subscribers === 1 && !registry.interval) {
+    const ms = Math.floor(1000 / fps)
+    registry.interval = setInterval(() => {
+      registry.frameIndex.value++
+    }, ms)
+  }
+
+  // Return unsubscribe function
+  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
+    }
+  }
+}
+
+/**
+ * Create an animated signal that cycles through frames.
+ *
+ * @example Basic spinner
+ * ```ts
+ * const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
+ * const frame = useAnimation(SPINNER)
+ * text({ content: frame }) // Animates automatically
+ * ```
+ *
+ * @example Conditional animation
+ * ```ts
+ * const frame = useAnimation(SPINNER, {
+ *   fps: 12,
+ *   active: () => isLoading.value,
+ * })
+ * // Animation only runs when isLoading is true
+ * ```
+ *
+ * @example With scope (auto-cleanup)
+ * ```ts
+ * function Spinner(): Cleanup {
+ *   return scoped(() => {
+ *     const frame = useAnimation(SPINNER, { active: () => loading.value })
+ *     text({ content: frame, fg: t.warning })
+ *   })
+ * }
+ * ```
+ */
+export function useAnimation<T>(
+  frames: readonly T[],
+  options: AnimationOptions = {}
+): DerivedSignal<T> {
+  const { fps = 12, active = true, startFrame = 0 } = options
+
+  // Get shared animation clock
+  const clock = getAnimationClock(fps)
+
+  // Track whether we're subscribed
+  let unsubscribe: (() => void) | null = null
+
+  // Unwrap active prop
+  const isActive = (): boolean => {
+    if (typeof active === 'function') return active()
+    if (typeof active === 'object' && 'value' in active) return active.value
+    return active
+  }
+
+  // Effect to manage subscription based on active state
+  const stopEffect = effect(() => {
+    const shouldBeActive = isActive()
+
+    if (shouldBeActive && !unsubscribe) {
+      unsubscribe = subscribeToAnimation(fps)
+    } else if (!shouldBeActive && unsubscribe) {
+      unsubscribe()
+      unsubscribe = null
+    }
+  })
+
+  // Auto-register cleanup with active scope
+  const scope = getActiveScope()
+  if (scope) {
+    scope.cleanups.push(() => {
+      stopEffect()
+      if (unsubscribe) {
+        unsubscribe()
+        unsubscribe = null
+      }
+    })
+  }
+
+  // Return derived that computes current frame
+  return derived(() => {
+    const index = (clock.frameIndex.value + startFrame) % frames.length
+    return frames[index]!
+  })
+}
+
+/**
+ * Common animation frame sets.
+ */
+export const AnimationFrames = {
+  /** Braille spinner (smooth) */
+  spinner: ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'] as const,
+
+  /** Braille dots (vertical) */
+  dots: ['⣾', '⣽', '⣻', '⢿', '⡿', '⣟', '⣯', '⣷'] as const,
+
+  /** Simple line spinner */
+  line: ['|', '/', '-', '\\'] as const,
+
+  /** Growing bar */
+  bar: ['▏', '▎', '▍', '▌', '▋', '▊', '▉', '█'] as const,
+
+  /** Bouncing ball */
+  bounce: ['⠁', '⠂', '⠄', '⡀', '⢀', '⠠', '⠐', '⠈'] as const,
+
+  /** Clock */
+  clock: ['🕐', '🕑', '🕒', '🕓', '🕔', '🕕', '🕖', '🕗', '🕘', '🕙', '🕚', '🕛'] as const,
+
+  /** Pulse */
+  pulse: ['◯', '◔', '◑', '◕', '●', '◕', '◑', '◔'] as const,
+} as const

package/src/primitives/box.ts

@@ -21,7 +21,7 @@
  * ```
  */
 
-import { bind, BINDING_SYMBOL } from '@rlabs-inc/signals'
+// No direct imports from signals - using slotArray APIs
 import { ComponentType } from '../types'
 import {
   allocateIndex,
@@ -32,6 +32,7 @@ import {
 } from '../engine/registry'
 import { cleanupIndex as cleanupKeyboardListeners } from '../state/keyboard'
 import { getVariantStyle } from '../state/theme'
+import { getActiveScope } from './scope'
 
 // Import arrays
 import * as core from '../engine/arrays/core'
@@ -113,29 +114,18 @@ function alignSelfToNum(align: string | undefined): number {
 }
 
 /**
- * Create a binding for enum props that converts at read time.
- * No derived needed - reads signal directly and converts inline.
- * This creates dependency directly on user's signal, no intermediate objects.
+ * Create a slot source for enum props - returns getter for reactive, value for static.
+ * For use with slotArray.setSource()
  */
-function bindEnumProp<T extends string>(
+function enumSource<T extends string>(
   prop: T | { value: T } | undefined,
   converter: (val: T | undefined) => number
-): ReturnType<typeof bind<number>> {
-  // If it's reactive (has .value), create binding that converts at read time
+): number | (() => number) {
   if (prop !== undefined && typeof prop === 'object' && prop !== null && 'value' in prop) {
     const reactiveSource = prop as { value: T }
-    return {
-      [BINDING_SYMBOL]: true,
-      get value(): number {
-        return converter(reactiveSource.value)
-      },
-      set value(_: number) {
-        // Enum props are read-only from number side
-      },
-    } as unknown as ReturnType<typeof bind<number>>
+    return () => converter(reactiveSource.value)
   }
-  // Static value - just convert and bind
-  return bind(converter(prop as T | undefined))
+  return converter(prop as T | undefined)
 }
 
 /** Get static boolean for visible prop */
@@ -170,38 +160,38 @@ export function box(props: BoxProps = {}): Cleanup {
   // CORE - Always needed
   // ==========================================================================
   core.componentType[index] = ComponentType.BOX
-  core.parentIndex[index] = bind(getCurrentParentIndex())
+  core.parentIndex.setSource(index, getCurrentParentIndex())
 
   // Visible - only bind if passed (default is visible, handled by TITAN)
   if (props.visible !== undefined) {
-    core.visible[index] = bind(props.visible)
+    core.visible.setSource(index, props.visible)
   }
 
   // ==========================================================================
   // DIMENSIONS - Only bind what's passed (TITAN uses ?? 0 for undefined)
   // ==========================================================================
-  if (props.width !== undefined) dimensions.width[index] = bind(props.width)
-  if (props.height !== undefined) dimensions.height[index] = bind(props.height)
-  if (props.minWidth !== undefined) dimensions.minWidth[index] = bind(props.minWidth)
-  if (props.maxWidth !== undefined) dimensions.maxWidth[index] = bind(props.maxWidth)
-  if (props.minHeight !== undefined) dimensions.minHeight[index] = bind(props.minHeight)
-  if (props.maxHeight !== undefined) dimensions.maxHeight[index] = bind(props.maxHeight)
+  if (props.width !== undefined) dimensions.width.setSource(index, props.width)
+  if (props.height !== undefined) dimensions.height.setSource(index, props.height)
+  if (props.minWidth !== undefined) dimensions.minWidth.setSource(index, props.minWidth)
+  if (props.maxWidth !== undefined) dimensions.maxWidth.setSource(index, props.maxWidth)
+  if (props.minHeight !== undefined) dimensions.minHeight.setSource(index, props.minHeight)
+  if (props.maxHeight !== undefined) dimensions.maxHeight.setSource(index, props.maxHeight)
 
   // ==========================================================================
   // PADDING - Shorthand support: padding sets all 4, individual overrides
   // ==========================================================================
   if (props.padding !== undefined) {
     // Shorthand - set all 4 sides
-    spacing.paddingTop[index] = bind(props.paddingTop ?? props.padding)
-    spacing.paddingRight[index] = bind(props.paddingRight ?? props.padding)
-    spacing.paddingBottom[index] = bind(props.paddingBottom ?? props.padding)
-    spacing.paddingLeft[index] = bind(props.paddingLeft ?? props.padding)
+    spacing.paddingTop.setSource(index, props.paddingTop ?? props.padding)
+    spacing.paddingRight.setSource(index, props.paddingRight ?? props.padding)
+    spacing.paddingBottom.setSource(index, props.paddingBottom ?? props.padding)
+    spacing.paddingLeft.setSource(index, props.paddingLeft ?? props.padding)
   } else {
     // Individual only - bind only what's passed
-    if (props.paddingTop !== undefined) spacing.paddingTop[index] = bind(props.paddingTop)
-    if (props.paddingRight !== undefined) spacing.paddingRight[index] = bind(props.paddingRight)
-    if (props.paddingBottom !== undefined) spacing.paddingBottom[index] = bind(props.paddingBottom)
-    if (props.paddingLeft !== undefined) spacing.paddingLeft[index] = bind(props.paddingLeft)
+    if (props.paddingTop !== undefined) spacing.paddingTop.setSource(index, props.paddingTop)
+    if (props.paddingRight !== undefined) spacing.paddingRight.setSource(index, props.paddingRight)
+    if (props.paddingBottom !== undefined) spacing.paddingBottom.setSource(index, props.paddingBottom)
+    if (props.paddingLeft !== undefined) spacing.paddingLeft.setSource(index, props.paddingLeft)
   }
 
   // ==========================================================================
@@ -209,90 +199,80 @@ export function box(props: BoxProps = {}): Cleanup {
   // ==========================================================================
   if (props.margin !== undefined) {
     // Shorthand - set all 4 sides
-    spacing.marginTop[index] = bind(props.marginTop ?? props.margin)
-    spacing.marginRight[index] = bind(props.marginRight ?? props.margin)
-    spacing.marginBottom[index] = bind(props.marginBottom ?? props.margin)
-    spacing.marginLeft[index] = bind(props.marginLeft ?? props.margin)
+    spacing.marginTop.setSource(index, props.marginTop ?? props.margin)
+    spacing.marginRight.setSource(index, props.marginRight ?? props.margin)
+    spacing.marginBottom.setSource(index, props.marginBottom ?? props.margin)
+    spacing.marginLeft.setSource(index, props.marginLeft ?? props.margin)
   } else {
     // Individual only - bind only what's passed
-    if (props.marginTop !== undefined) spacing.marginTop[index] = bind(props.marginTop)
-    if (props.marginRight !== undefined) spacing.marginRight[index] = bind(props.marginRight)
-    if (props.marginBottom !== undefined) spacing.marginBottom[index] = bind(props.marginBottom)
-    if (props.marginLeft !== undefined) spacing.marginLeft[index] = bind(props.marginLeft)
+    if (props.marginTop !== undefined) spacing.marginTop.setSource(index, props.marginTop)
+    if (props.marginRight !== undefined) spacing.marginRight.setSource(index, props.marginRight)
+    if (props.marginBottom !== undefined) spacing.marginBottom.setSource(index, props.marginBottom)
+    if (props.marginLeft !== undefined) spacing.marginLeft.setSource(index, props.marginLeft)
   }
 
   // Gap - only bind if passed
-  if (props.gap !== undefined) spacing.gap[index] = bind(props.gap)
+  if (props.gap !== undefined) spacing.gap.setSource(index, props.gap)
 
   // ==========================================================================
   // LAYOUT - Only bind what's passed (TITAN uses sensible defaults)
   // ==========================================================================
-  if (props.flexDirection !== undefined) layout.flexDirection[index] = bindEnumProp(props.flexDirection, flexDirectionToNum)
-  if (props.flexWrap !== undefined) layout.flexWrap[index] = bindEnumProp(props.flexWrap, flexWrapToNum)
-  if (props.justifyContent !== undefined) layout.justifyContent[index] = bindEnumProp(props.justifyContent, justifyToNum)
-  if (props.alignItems !== undefined) layout.alignItems[index] = bindEnumProp(props.alignItems, alignToNum)
-  if (props.overflow !== undefined) layout.overflow[index] = bindEnumProp(props.overflow, overflowToNum)
-  if (props.grow !== undefined) layout.flexGrow[index] = bind(props.grow)
-  if (props.shrink !== undefined) layout.flexShrink[index] = bind(props.shrink)
-  if (props.flexBasis !== undefined) layout.flexBasis[index] = bind(props.flexBasis)
-  if (props.zIndex !== undefined) layout.zIndex[index] = bind(props.zIndex)
-  if (props.alignSelf !== undefined) layout.alignSelf[index] = bindEnumProp(props.alignSelf, alignSelfToNum)
+  if (props.flexDirection !== undefined) layout.flexDirection.setSource(index, enumSource(props.flexDirection, flexDirectionToNum))
+  if (props.flexWrap !== undefined) layout.flexWrap.setSource(index, enumSource(props.flexWrap, flexWrapToNum))
+  if (props.justifyContent !== undefined) layout.justifyContent.setSource(index, enumSource(props.justifyContent, justifyToNum))
+  if (props.alignItems !== undefined) layout.alignItems.setSource(index, enumSource(props.alignItems, alignToNum))
+  if (props.overflow !== undefined) layout.overflow.setSource(index, enumSource(props.overflow, overflowToNum))
+  if (props.grow !== undefined) layout.flexGrow.setSource(index, props.grow)
+  if (props.shrink !== undefined) layout.flexShrink.setSource(index, props.shrink)
+  if (props.flexBasis !== undefined) layout.flexBasis.setSource(index, props.flexBasis)
+  if (props.zIndex !== undefined) layout.zIndex.setSource(index, props.zIndex)
+  if (props.alignSelf !== undefined) layout.alignSelf.setSource(index, enumSource(props.alignSelf, alignSelfToNum))
 
   // ==========================================================================
-  // INTERACTION - Only bind if focusable
+  // INTERACTION - Focusable handling
+  // Auto-focusable for overflow:'scroll' (unless explicitly disabled)
   // ==========================================================================
-  if (props.focusable) {
-    interaction.focusable[index] = bind(1)
-    if (props.tabIndex !== undefined) interaction.tabIndex[index] = bind(props.tabIndex)
+  const shouldBeFocusable = props.focusable || (props.overflow === 'scroll' && props.focusable !== false)
+  if (shouldBeFocusable) {
+    interaction.focusable.setSource(index, 1)
+    if (props.tabIndex !== undefined) interaction.tabIndex.setSource(index, props.tabIndex)
   }
 
   // ==========================================================================
   // VISUAL - Colors and borders (only bind what's passed)
   // ==========================================================================
   if (props.variant && props.variant !== 'default') {
-    // Variant colors - inline bindings that read theme at read time (no deriveds!)
+    // Variant colors - use getters that read theme at read time
     const variant = props.variant
     if (props.fg !== undefined) {
-      visual.fgColor[index] = bind(props.fg)
+      visual.fgColor.setSource(index, props.fg)
     } else {
-      visual.fgColor[index] = {
-        [BINDING_SYMBOL]: true,
-        get value() { return getVariantStyle(variant).fg },
-        set value(_) {},
-      } as any
+      visual.fgColor.setSource(index, () => getVariantStyle(variant).fg)
     }
     if (props.bg !== undefined) {
-      visual.bgColor[index] = bind(props.bg)
+      visual.bgColor.setSource(index, props.bg)
     } else {
-      visual.bgColor[index] = {
-        [BINDING_SYMBOL]: true,
-        get value() { return getVariantStyle(variant).bg },
-        set value(_) {},
-      } as any
+      visual.bgColor.setSource(index, () => getVariantStyle(variant).bg)
     }
     if (props.borderColor !== undefined) {
-      visual.borderColor[index] = bind(props.borderColor)
+      visual.borderColor.setSource(index, props.borderColor)
     } else {
-      visual.borderColor[index] = {
-        [BINDING_SYMBOL]: true,
-        get value() { return getVariantStyle(variant).border },
-        set value(_) {},
-      } as any
+      visual.borderColor.setSource(index, () => getVariantStyle(variant).border)
     }
   } else {
     // Direct colors - only bind if passed
-    if (props.fg !== undefined) visual.fgColor[index] = bind(props.fg)
-    if (props.bg !== undefined) visual.bgColor[index] = bind(props.bg)
-    if (props.borderColor !== undefined) visual.borderColor[index] = bind(props.borderColor)
+    if (props.fg !== undefined) visual.fgColor.setSource(index, props.fg)
+    if (props.bg !== undefined) visual.bgColor.setSource(index, props.bg)
+    if (props.borderColor !== undefined) visual.borderColor.setSource(index, props.borderColor)
   }
-  if (props.opacity !== undefined) visual.opacity[index] = bind(props.opacity)
+  if (props.opacity !== undefined) visual.opacity.setSource(index, props.opacity)
 
   // Border style - shorthand and individual
-  if (props.border !== undefined) visual.borderStyle[index] = bind(props.border)
-  if (props.borderTop !== undefined) visual.borderTop[index] = bind(props.borderTop)
-  if (props.borderRight !== undefined) visual.borderRight[index] = bind(props.borderRight)
-  if (props.borderBottom !== undefined) visual.borderBottom[index] = bind(props.borderBottom)
-  if (props.borderLeft !== undefined) visual.borderLeft[index] = bind(props.borderLeft)
+  if (props.border !== undefined) visual.borderStyle.setSource(index, props.border)
+  if (props.borderTop !== undefined) visual.borderTop.setSource(index, props.borderTop)
+  if (props.borderRight !== undefined) visual.borderRight.setSource(index, props.borderRight)
+  if (props.borderBottom !== undefined) visual.borderBottom.setSource(index, props.borderBottom)
+  if (props.borderLeft !== undefined) visual.borderLeft.setSource(index, props.borderLeft)
 
   // Render children with this box as parent context
   if (props.children) {
@@ -305,8 +285,16 @@ export function box(props: BoxProps = {}): Cleanup {
   }
 
   // Cleanup function
-  return () => {
+  const cleanup = () => {
     cleanupKeyboardListeners(index)  // Remove any focused key handlers
     releaseIndex(index)
   }
+
+  // Auto-register with active scope if one exists
+  const scope = getActiveScope()
+  if (scope) {
+    scope.cleanups.push(cleanup)
+  }
+
+  return cleanup
 }

package/src/primitives/each.ts

@@ -0,0 +1,87 @@
+/**
+ * TUI Framework - Each Primitive
+ *
+ * Reactive list rendering. Creates components for each item in an array.
+ * When the array changes, components are automatically added/removed.
+ * Props inside components remain reactive through normal slot binding.
+ *
+ * Usage:
+ * ```ts
+ * each(() => items.value, (getItem, key) => {
+ *   // key is STABLE (use for selection!)
+ *   // getItem() returns current item value (reactive!)
+ *   text({ content: () => getItem().name, id: `item-${key}` })
+ * }, { key: item => item.id })
+ * ```
+ */
+
+import { signal, effect, effectScope, onScopeDispose, type WritableSignal } from '@rlabs-inc/signals'
+import { getCurrentParentIndex, pushParentContext, popParentContext } from '../engine/registry'
+import type { Cleanup } from './types'
+
+/**
+ * Render a list of components reactively.
+ *
+ * Uses fine-grained reactivity: each item is stored in a signal.
+ * When items change, signals are updated (not recreated).
+ * Components read from signals via getter - truly reactive!
+ *
+ * @param itemsGetter - Getter that returns the items array
+ * @param renderFn - Receives: getItem() for reactive item access, key (stable ID)
+ * @param options.key - Function to get unique key for each item
+ */
+export function each<T>(
+  itemsGetter: () => T[],
+  renderFn: (getItem: () => T, key: string) => Cleanup,
+  options: { key: (item: T) => string }
+): Cleanup {
+  const cleanups = new Map<string, Cleanup>()
+  const itemSignals = new Map<string, WritableSignal<T>>()
+  const parentIndex = getCurrentParentIndex()
+  const scope = effectScope()
+
+  scope.run(() => {
+    effect(() => {
+      const items = itemsGetter()
+      const currentKeys = new Set<string>()
+
+      pushParentContext(parentIndex)
+      try {
+        for (let i = 0; i < items.length; i++) {
+          const item = items[i]!
+          const key = options.key(item)
+          currentKeys.add(key)
+
+          if (!itemSignals.has(key)) {
+            // NEW item - create signal and component
+            const itemSignal = signal(item)
+            itemSignals.set(key, itemSignal)
+            cleanups.set(key, renderFn(() => itemSignal.value, key))
+          } else {
+            // EXISTING item - just update the signal (fine-grained!)
+            itemSignals.get(key)!.value = item
+          }
+        }
+      } finally {
+        popParentContext()
+      }
+
+      // Cleanup removed items
+      for (const [key, cleanup] of cleanups) {
+        if (!currentKeys.has(key)) {
+          cleanup()
+          cleanups.delete(key)
+          itemSignals.delete(key)
+        }
+      }
+    })
+
+    onScopeDispose(() => {
+      for (const cleanup of cleanups.values()) cleanup()
+      cleanups.clear()
+      itemSignals.clear()
+    })
+  })
+
+  return () => scope.stop()
+}

package/src/primitives/index.ts

@@ -7,6 +7,13 @@
 
 export { box } from './box'
 export { text } from './text'
+export { each } from './each'
+export { show } from './show'
+export { when } from './when'
+export { scoped, onCleanup, componentScope, cleanupCollector } from './scope'
+export { useAnimation, AnimationFrames } from './animation'
 
 // Types
 export type { BoxProps, TextProps, Cleanup } from './types'
+export type { ComponentScopeResult } from './scope'
+export type { AnimationOptions } from './animation'