@barefootjs/client 0.1.0

package/src/reactive.ts

@@ -0,0 +1,411 @@
+/**
+ * BarefootJS - Reactive Primitives
+ *
+ * Minimal reactive system for DOM manipulation.
+ * Inspired by SolidJS signals.
+ */
+
+/**
+ * Phantom brand for compile-time reactivity detection.
+ * The compiler checks for the '__reactive' property via TypeChecker
+ * to identify reactive expressions.
+ */
+export type Reactive<T> = T & { readonly __reactive: true }
+
+export type Signal<T> = [
+  /** Get current value (registers dependency when called inside effect) */
+  Reactive<() => T>,
+  /** Update value (accepts value or updater function) */
+  (valueOrFn: T | ((prev: T) => T)) => void
+]
+
+export type CleanupFn = () => void
+export type EffectFn = () => void | CleanupFn
+export type Memo<T> = Reactive<() => T>
+
+type EffectContext = {
+  fn: EffectFn
+  cleanup: CleanupFn | null
+  dependencies: Set<Set<EffectContext>>
+  owner: EffectContext | null   // Parent scope for hierarchical disposal
+  children: EffectContext[]     // Owned child effects/roots
+  disposed: boolean
+  runCount: number              // Per-effect re-entry counter for circular dependency detection
+}
+
+let Owner: EffectContext | null = null
+let Listener: EffectContext | null = null
+const MAX_EFFECT_RUNS = 100
+
+let BatchDepth = 0
+const PendingEffects = new Set<EffectContext>()
+
+/**
+ * Create a reactive value
+ *
+ * @param initialValue - Initial value
+ * @returns [getter, setter] tuple
+ *
+ * @example
+ * const [count, setCount] = createSignal(0)
+ * count()              // 0
+ * setCount(5)          // Update to 5
+ * setCount(n => n + 1) // Update with function (becomes 6)
+ */
+export function createSignal<T>(initialValue: T): Signal<T> {
+  let value = initialValue
+  const subscribers = new Set<EffectContext>()
+
+  const get = () => {
+    if (Listener) {
+      subscribers.add(Listener)
+      Listener.dependencies.add(subscribers)
+    }
+    return value
+  }
+
+  const set = (valueOrFn: T | ((prev: T) => T)) => {
+    const newValue = typeof valueOrFn === 'function'
+      ? (valueOrFn as (prev: T) => T)(value)
+      : valueOrFn
+
+    if (Object.is(value, newValue)) {
+      return
+    }
+
+    value = newValue
+
+    if (BatchDepth > 0) {
+      for (const effect of subscribers) {
+        PendingEffects.add(effect)
+      }
+    } else {
+      const effectsToRun = [...subscribers]
+      for (const effect of effectsToRun) {
+        runEffect(effect)
+      }
+    }
+  }
+
+  return [get, set] as Signal<T>
+}
+
+/**
+ * Side effect that runs automatically when signals change
+ *
+ * @param fn - Effect function (can return a cleanup function)
+ *
+ * @example
+ * const [count, setCount] = createSignal(0)
+ * createEffect(() => {
+ *   console.log("count changed:", count())
+ * })
+ * setCount(1)  // Logs "count changed: 1"
+ */
+export function createEffect(fn: EffectFn): void {
+  // Note: Nested effects are now allowed. runEffect() properly saves/restores
+  // prevEffect, so nested effects correctly track their own dependencies.
+  // This enables synchronous component initialization in reconcileList.
+
+  const effect: EffectContext = {
+    fn,
+    cleanup: null,
+    dependencies: new Set(),
+    owner: Owner,
+    children: [],
+    disposed: false,
+    runCount: 0,
+  }
+
+  // Register with parent owner for hierarchical disposal
+  if (Owner) Owner.children.push(effect)
+
+  runEffect(effect)
+}
+
+function runEffect(effect: EffectContext): void {
+  if (effect.disposed) return
+
+  effect.runCount++
+  if (effect.runCount > MAX_EFFECT_RUNS) {
+    effect.runCount = 0
+    throw new Error(`Circular dependency detected: effect re-entered itself ${MAX_EFFECT_RUNS} times.`)
+  }
+
+  if (effect.cleanup) {
+    effect.cleanup()
+    effect.cleanup = null
+  }
+
+  for (const dep of effect.dependencies) {
+    dep.delete(effect)
+  }
+  effect.dependencies.clear()
+
+  const prevOwner = Owner
+  const prevListener = Listener
+  Owner = effect
+  Listener = effect
+
+  try {
+    const result = effect.fn()
+    if (typeof result === 'function') {
+      effect.cleanup = result
+    }
+  } finally {
+    Owner = prevOwner
+    Listener = prevListener
+    effect.runCount--
+  }
+}
+
+/**
+ * Dispose an effect and its entire owned subtree, without touching the
+ * parent's `children` list. Internal to `disposeEffect` — every recursive
+ * step uses this path so cascade disposal can never mutate a list it's
+ * currently iterating over.
+ */
+function disposeSubtree(effect: EffectContext): void {
+  if (effect.disposed) return
+  effect.disposed = true
+
+  for (const child of effect.children) {
+    disposeSubtree(child)
+  }
+  effect.children.length = 0
+
+  if (effect.cleanup) {
+    effect.cleanup()
+    effect.cleanup = null
+  }
+
+  for (const dep of effect.dependencies) {
+    dep.delete(effect)
+  }
+  effect.dependencies.clear()
+
+  effect.owner = null
+}
+
+/**
+ * Public dispose entry point: detach `effect` from its parent's `children`
+ * list, then dispose the subtree rooted at `effect`. The detach step lives
+ * only here so the recursion (which doesn't need it — the parent clears
+ * `children.length = 0` itself) cannot splice entries out of the array
+ * it is iterating. The splice-during-iter shape was the root cause of
+ * #1366; separating the two responsibilities makes it structurally
+ * unreachable.
+ */
+function disposeEffect(effect: EffectContext): void {
+  if (effect.disposed) return
+
+  if (effect.owner) {
+    const idx = effect.owner.children.indexOf(effect)
+    if (idx >= 0) effect.owner.children.splice(idx, 1)
+  }
+
+  disposeSubtree(effect)
+}
+
+/**
+ * Create an isolated reactive scope with explicit disposal.
+ * All effects/memos created inside run within this root and are
+ * disposed together when the returned dispose function is called.
+ *
+ * Used internally by mapArray for per-item reactive scopes.
+ *
+ * @param fn - Function to run in the new scope. Receives a dispose function.
+ * @returns The return value of fn
+ */
+export function createRoot<T>(fn: (dispose: () => void) => T): T {
+  const root: EffectContext = {
+    fn: () => {},
+    cleanup: null,
+    dependencies: new Set(),
+    owner: Owner,
+    children: [],
+    disposed: false,
+    runCount: 0,
+  }
+
+  if (Owner) Owner.children.push(root)
+
+  const prevOwner = Owner
+  const prevListener = Listener
+  Owner = root
+  Listener = null  // Isolate: signal reads inside root don't track in parent effect
+
+  try {
+    return fn(() => disposeEffect(root))
+  } finally {
+    Owner = prevOwner
+    Listener = prevListener
+  }
+}
+
+/**
+ * Create an effect that can be explicitly disposed (unsubscribed from all signals).
+ * Used for effects inside conditional branches that need cleanup on branch switch.
+ *
+ * @returns A dispose function that stops the effect and removes it from all signal dependencies.
+ */
+export function createDisposableEffect(fn: EffectFn): () => void {
+  let disposed = false
+
+  const effect: EffectContext = {
+    fn: () => {
+      if (disposed) return  // Prevent re-activation after disposal
+      return fn()
+    },
+    cleanup: null,
+    dependencies: new Set(),
+    owner: Owner,
+    children: [],
+    disposed: false,
+    runCount: 0,
+  }
+
+  if (Owner) Owner.children.push(effect)
+
+  runEffect(effect)
+
+  return () => {
+    disposeEffect(effect)
+  }
+}
+
+/**
+ * Register cleanup function for effects
+ *
+ * @param fn - Cleanup function
+ *
+ * @example
+ * createEffect(() => {
+ *   const timer = setInterval(() => console.log('tick'), 1000)
+ *   onCleanup(() => clearInterval(timer))
+ * })
+ */
+export function onCleanup(fn: CleanupFn): void {
+  if (Owner) {
+    const effect = Owner
+    const prevCleanup = effect.cleanup
+    effect.cleanup = () => {
+      if (prevCleanup) prevCleanup()
+      fn()
+    }
+  }
+}
+
+/**
+ * Run a function without tracking signal dependencies
+ *
+ * @param fn - Function to run without tracking
+ * @returns The return value of fn
+ *
+ * @example
+ * createEffect(() => {
+ *   const value = untrack(() => someSignal()) // won't re-run when someSignal changes
+ *   console.log(value)
+ * })
+ */
+export function untrack<T>(fn: () => T): T {
+  const prevListener = Listener
+  Listener = null
+  try {
+    return fn()
+  } finally {
+    Listener = prevListener
+  }
+}
+
+/**
+ * Batch multiple signal updates and propagate once
+ *
+ * Collects all signal writes inside `fn`, then flushes
+ * dependent effects after `fn` returns. Duplicate effects
+ * are deduplicated, so a deep memo chain only propagates once
+ * regardless of how many times the source signal was written.
+ *
+ * Batches can be nested — effects flush when the outermost batch ends.
+ *
+ * @param fn - Function containing signal writes to batch
+ * @returns The return value of fn
+ *
+ * @example
+ * const [a, setA] = createSignal(0)
+ * const [b, setB] = createSignal(0)
+ * batch(() => {
+ *   setA(1)  // queued
+ *   setB(2)  // queued
+ * })
+ * // effects run once here, not twice
+ */
+export function batch<T>(fn: () => T): T {
+  BatchDepth++
+  try {
+    return fn()
+  } finally {
+    BatchDepth--
+    if (BatchDepth === 0) {
+      flushEffects()
+    }
+  }
+}
+
+function flushEffects(): void {
+  while (PendingEffects.size > 0) {
+    const effects = [...PendingEffects]
+    PendingEffects.clear()
+    for (const effect of effects) {
+      runEffect(effect)
+    }
+  }
+}
+
+/**
+ * Run a function once when the component mounts
+ *
+ * Thin wrapper around createEffect for one-time mount code.
+ * The function runs immediately and does not track any dependencies.
+ *
+ * @param fn - Function to run on mount
+ *
+ * @example
+ * onMount(() => {
+ *   console.log('Component mounted!')
+ *   onCleanup(() => console.log('Component unmounted!'))
+ * })
+ */
+export function onMount(fn: () => void): void {
+  createEffect(() => untrack(fn))
+}
+
+/**
+ * Create a memoized computed value
+ *
+ * A derived signal that:
+ * - Tracks dependencies automatically (like createEffect)
+ * - Caches the computed result
+ * - Acts as a read-only signal (can be used as dependency by other effects/memos)
+ *
+ * @param fn - Computation function that returns a value
+ * @returns Getter function for the memoized value
+ *
+ * @example
+ * const [count, setCount] = createSignal(2)
+ * const doubled = createMemo(() => count() * 2)
+ * doubled()    // 4
+ * setCount(5)
+ * doubled()    // 10
+ */
+export function createMemo<T>(fn: () => T): Memo<T> {
+  const [value, setValue] = createSignal<T>(undefined as T)
+
+  createEffect(() => {
+    const result = fn()
+    setValue(() => result)
+  })
+
+  return value
+}
+

package/src/runtime/apply-rest-attrs.ts

@@ -0,0 +1,109 @@
+/**
+ * BarefootJS - Apply Rest Attributes Helper
+ *
+ * Applies spread attributes to HTML elements at hydration time.
+ * Used when spread props cannot be statically expanded (open types).
+ */
+
+import { createEffect } from '@barefootjs/client/reactive'
+import { styleToCss } from './style'
+
+/** Map of JSX prop names to HTML attribute names */
+function toAttrName(key: string): string {
+  if (key === 'className') return 'class'
+  if (key === 'htmlFor') return 'for'
+  // Convert camelCase to kebab-case for data-* and aria-* style attributes
+  return key.replace(/([A-Z])/g, '-$1').toLowerCase()
+}
+
+/**
+ * Convert a JSX event prop name to a DOM event name for addEventListener.
+ * Handles: camelCase → lowercase, plus special mappings (doubleclick → dblclick).
+ * Mirrors the compiler's toDomEventName in packages/jsx/src/ir-to-client-js/utils.ts.
+ */
+const jsxToDomEventMap: Record<string, string> = { doubleclick: 'dblclick' }
+function toEventName(jsxPropName: string): string {
+  // onKeyDown → 'k' + 'eyDown' → 'keydown'
+  const raw = (jsxPropName[2].toLowerCase() + jsxPropName.slice(3)).toLowerCase()
+  return jsxToDomEventMap[raw] ?? raw
+}
+
+/**
+ * Reactively apply rest attributes from a props source onto an HTML element.
+ * Runs inside a createEffect so attribute values update when props change.
+ *
+ * @param el - The target DOM element
+ * @param source - The props/rest object to read attributes from
+ * @param excludeKeys - Keys already handled statically (don't apply twice)
+ */
+export function applyRestAttrs(
+  el: Element,
+  source: Record<string, unknown>,
+  excludeKeys: string[]
+): void {
+  const exclude = new Set(excludeKeys)
+
+  // Wire up event handlers and ref callbacks once (not reactively)
+  for (const key of Object.keys(source)) {
+    if (exclude.has(key)) continue
+    if (key === 'ref') {
+      const ref = source[key]
+      if (typeof ref === 'function') (ref as (el: Element) => void)(el)
+      continue
+    }
+    if (key.startsWith('on') && key.length > 2 && key[2] === key[2].toUpperCase()) {
+      const handler = source[key]
+      if (typeof handler === 'function') {
+        el.addEventListener(toEventName(key), handler as EventListener)
+      }
+    }
+  }
+
+  createEffect(() => {
+    for (const key of Object.keys(source)) {
+      if (exclude.has(key)) continue
+
+      // Event handlers and ref are wired up above, not as attributes
+      if (key === 'ref') continue
+      // `children` is a JSX construct rendered inside the element, never
+      // a DOM attribute. Without this exclusion, parent components that
+      // pass `children` through `{...props}` end up with
+      // `children="<p ...>...</p>"` written as a literal attribute on
+      // the wrapper div. The matching `spreadAttrs` (SSR-string) path
+      // already skips `children` for the same reason.
+      if (key === 'children') continue
+      if (key.startsWith('on') && key.length > 2 && key[2] === key[2].toUpperCase()) continue
+
+      const value = source[key]
+      const attr = toAttrName(key)
+
+      if (value != null && value !== false) {
+        // Use DOM property for value/checked (setAttribute sets the default, not current)
+        if (attr === 'value' && 'value' in el) {
+          const strVal = String(value)
+          if ((el as HTMLInputElement).value !== strVal) (el as HTMLInputElement).value = strVal
+        } else if (attr === 'checked' && 'checked' in el) {
+          (el as HTMLInputElement).checked = !!value
+        } else if (attr === 'style') {
+          // Route the `style` prop through `styleToCss` so object literals
+          // (`{'--err': errorHue()}`) and inline strings (`'color:red'`)
+          // both reach the DOM as a real CSS string instead of
+          // `[object Object]`. Mirrors the compiler's
+          // `setAttribute('style', styleToCss(...))` path used when the
+          // attribute is bound directly on a JSX element.
+          const css = styleToCss(value)
+          if (css == null) el.removeAttribute('style')
+          else el.setAttribute('style', css)
+        } else {
+          el.setAttribute(attr, String(value))
+        }
+      } else {
+        if (attr === 'checked' && 'checked' in el) {
+          (el as HTMLInputElement).checked = false
+        } else {
+          el.removeAttribute(attr)
+        }
+      }
+    }
+  })
+}

package/src/runtime/branch-slot.ts

@@ -0,0 +1,32 @@
+/**
+ * Branch-template slot helper (#1213).
+ *
+ * Conditional `template()` arrows interpolate Child-position expressions
+ * via `${expr}`. When `expr` evaluates to a live `Node` (e.g. the result
+ * of `_p.renderNode(node())` returning an `HTMLElement` from
+ * `createComponent`), the surrounding template literal coerces it via
+ * `Object.prototype.toString`, producing `"[object HTMLDivElement]"` and
+ * destroying the live node identity on hydration.
+ *
+ * `__bfSlot` intercepts the value before stringification: if it's a
+ * `Node`, it stashes the node into the closure-scoped `slots` array and
+ * returns a unique marker comment. The `insert()` runtime then walks the
+ * parsed fragment for those markers and splices the original node back
+ * in by identity (no `cloneNode`), preserving event listeners and signal
+ * bindings.
+ *
+ * Non-node values fall through to `String(value)` for the existing
+ * inline-string path.
+ */
+export function __bfSlot(value: unknown, slots: Node[]): string {
+  if (value == null || value === false || value === true) return ''
+  if (typeof Node !== 'undefined' && value instanceof Node) {
+    const idx = slots.length
+    slots.push(value)
+    return `<!--bf-slot:${idx}-->`
+  }
+  if (Array.isArray(value)) {
+    return value.map((v) => __bfSlot(v, slots)).join('')
+  }
+  return String(value)
+}

package/src/runtime/client-marker.ts

@@ -0,0 +1,46 @@
+/**
+ * BarefootJS - Client Marker
+ *
+ * Update text content for @client directive expressions
+ * that are evaluated only on the client side.
+ */
+
+/**
+ * Update text content for a client marker.
+ *
+ * Expects comment marker format: <!--bf-client:sX-->
+ * Both GoTemplateAdapter and HonoAdapter output this format for @client directives.
+ *
+ * A zero-width space (\u200B) is used as a prefix to mark text nodes managed by @client.
+ * This allows distinguishing managed text nodes from other content.
+ *
+ * @param scope - The component scope element to search within
+ * @param id - The slot ID (e.g., 's5')
+ * @param value - The value to display (will be converted to string)
+ */
+export function updateClientMarker(scope: Element | null, id: string, value: unknown): void {
+  if (!scope) return
+
+  const marker = `bf-client:${id}`
+  const walker = document.createTreeWalker(scope, NodeFilter.SHOW_COMMENT)
+
+  while (walker.nextNode()) {
+    if (walker.currentNode.nodeValue === marker) {
+      const comment = walker.currentNode
+      let textNode = comment.nextSibling
+
+      // Check if next sibling is our managed text node (prefixed with zero-width space)
+      if (textNode?.nodeType !== Node.TEXT_NODE ||
+          !textNode.nodeValue?.startsWith('\u200B')) {
+        // Create new text node with zero-width space marker
+        textNode = document.createTextNode('\u200B' + String(value ?? ''))
+        // Insert after the comment node
+        comment.parentNode?.insertBefore(textNode, comment.nextSibling)
+      } else {
+        // Update existing managed text node
+        textNode.nodeValue = '\u200B' + String(value ?? '')
+      }
+      return
+    }
+  }
+}