@barefootjs/client 0.1.0

package/src/runtime/slot-resolver.ts

@@ -0,0 +1,66 @@
+/**
+ * Shared slot-relationship resolver: identifies the SSR scope of a child
+ * component mounted at slot `<sN>` inside its parent.
+ *
+ * Both single-root (`registry.ts::upsertChild`) and multi-root loop-body
+ * (`qsa-item.ts::upsertChildItem`) paths consume this. They differ only
+ * in whether they search a single `parent` element or walk a sequence of
+ * loop-item root elements; the lookup logic is identical.
+ *
+ * See `spec/compiler.md` "Slot identity" for the marker contract.
+ */
+
+import { BF_SCOPE, BF_HOST, BF_AT } from '@barefootjs/shared'
+import { cssEscape } from './query'
+
+/** Resolve the host scope id for a slot lookup. Prefers the explicit
+ *  `anchorScope` because the immediate `parent` element may be a freshly-
+ *  created detached fragment whose `closest()` returns null. */
+export function parentScopeOf(parent: Element, anchorScope?: Element | null): string {
+  const ancestor = anchorScope ?? parent.closest(`[${BF_SCOPE}]`)
+  if (!ancestor) return ''
+  return ancestor.getAttribute(BF_SCOPE) ?? ''
+}
+
+/** Build the (host, slot) metadata for a fresh component about to be
+ *  mounted at `slotId`. `createComponent` stamps these onto the new
+ *  element so subsequent `upsertChild` lookups can find it. `parent`
+ *  defaults to the empty string when no surrounding scope is resolvable
+ *  (top-level CSR mount). */
+export function buildSlotInfo(
+  parent: Element,
+  slotId: string,
+  anchorScope?: Element | null,
+): { parent: string; mount: string } {
+  return { parent: parentScopeOf(parent, anchorScope), mount: slotId }
+}
+
+/**
+ * Find the SSR scope element for a child component at `slotId` inside
+ * `parent`. Primary lookup is `(BF_HOST, BF_AT)`; the suffix fallback
+ * covers `renderChild` paths that emit a parent-anchored `bf-s` without
+ * stamping host metadata.
+ *
+ * `selfMatch` lets the multi-root loop-body caller include the root
+ * element itself in the search (the loop-item primary may be the scope
+ * element, not just a parent of it).
+ */
+export function findSsrScopeBySlotIn(
+  parent: Element,
+  slotId: string,
+  anchorScope: Element | null | undefined,
+  selfMatch: boolean,
+): HTMLElement | null {
+  const parentBfs = parentScopeOf(parent, anchorScope)
+
+  if (parentBfs) {
+    const selector = `[${BF_HOST}="${cssEscape(parentBfs)}"][${BF_AT}="${slotId}"]`
+    if (selfMatch && parent.matches(selector)) return parent as HTMLElement
+    const direct = parent.querySelector(selector) as HTMLElement | null
+    if (direct) return direct
+  }
+
+  const suffixSelector = `[${BF_SCOPE}$="_${slotId}"]`
+  if (selfMatch && parent.matches(suffixSelector)) return parent as HTMLElement
+  return parent.querySelector(suffixSelector) as HTMLElement | null
+}

package/src/runtime/spread-attrs.ts

@@ -0,0 +1,88 @@
+/**
+ * BarefootJS - Spread Attributes Helper (Template Mode)
+ *
+ * Converts an object to an HTML attribute string for use inside template literals.
+ * Unlike applyRestAttrs (which manipulates DOM elements reactively), this produces
+ * a static string for server/template rendering of computed local spreads.
+ */
+
+import { styleToCss } from './style'
+
+/**
+ * SVG attributes that are case-sensitive and MUST stay in camelCase.
+ *
+ * The default JSX-prop → HTML-attribute rewrite lower-cases camelCase
+ * (`fooBar` → `foo-bar`), which is correct for HTML attrs and for the
+ * CSS-style SVG presentation attrs (`strokeWidth` → `stroke-width`).
+ * The XML-namespaced SVG attrs below, though, are case-sensitive in
+ * the spec: `viewBox` lower-cased to `view-box` makes the browser
+ * treat it as an unknown user attribute and the SVG no longer renders
+ * (pointer events stop hitting the inner geometry — surfaced as the
+ * Form Builder e2e regression in #1244's merge-emit follow-up).
+ *
+ * Coordinates with the compile-time `SVG_CAMEL_TO_KEBAB` table in
+ * `packages/jsx/src/ir-to-client-js/utils.ts`: presentation attrs
+ * (`clipPath`, `strokeWidth`, …) live there and must NOT appear here,
+ * or the same JSX prop would lower to `clip-path` via the explicit-
+ * attr path and stay `clipPath` via the spread path — a silent
+ * divergence. The list below is XML attribute names that have no
+ * kebab-case mirror (`viewBox`, `clipPathUnits`, …).
+ *
+ * The list mirrors React DOM's `DOMProperty` case-preserving entries
+ * (only the attributes that appear on actual SVG elements; ARIA and
+ * XLink namespaces are unrelated and handled by their `aria-*` /
+ * `xlink:*` literal prefix).
+ */
+const SVG_CAMEL_CASE_ATTRS: ReadonlySet<string> = new Set([
+  'allowReorder', 'attributeName', 'attributeType', 'autoReverse',
+  'baseFrequency', 'baseProfile', 'calcMode', 'clipPathUnits',
+  'contentScriptType', 'contentStyleType', 'diffuseConstant', 'edgeMode',
+  'externalResourcesRequired', 'filterRes', 'filterUnits', 'glyphRef',
+  'gradientTransform', 'gradientUnits', 'kernelMatrix', 'kernelUnitLength',
+  'keyPoints', 'keySplines', 'keyTimes', 'lengthAdjust', 'limitingConeAngle',
+  'markerHeight', 'markerUnits', 'markerWidth', 'maskContentUnits',
+  'maskUnits', 'numOctaves', 'pathLength', 'patternContentUnits',
+  'patternTransform', 'patternUnits', 'pointsAtX', 'pointsAtY', 'pointsAtZ',
+  'preserveAlpha', 'preserveAspectRatio', 'primitiveUnits', 'refX', 'refY',
+  'repeatCount', 'repeatDur', 'requiredExtensions', 'requiredFeatures',
+  'specularConstant', 'specularExponent', 'spreadMethod', 'startOffset',
+  'stdDeviation', 'stitchTiles', 'surfaceScale', 'systemLanguage',
+  'tableValues', 'targetX', 'targetY', 'textLength', 'viewBox', 'viewTarget',
+  'xChannelSelector', 'yChannelSelector', 'zoomAndPan',
+])
+
+/**
+ * Convert an object to an HTML attribute string.
+ * Aligned with applyRestAttrs conventions: skips null/undefined/false,
+ * event handlers, maps className→class and htmlFor→for. The `style`
+ * prop is routed through `styleToCss` so object literals serialize to
+ * a real CSS string (matching the reactive `applyRestAttrs` path).
+ *
+ * SVG attributes listed in `SVG_CAMEL_CASE_ATTRS` are preserved
+ * verbatim — the SVG XML spec is case-sensitive for those names.
+ */
+export function spreadAttrs(obj: Record<string, unknown>): string {
+  if (!obj || typeof obj !== 'object') return ''
+  const parts: string[] = []
+  for (const [key, value] of Object.entries(obj)) {
+    if (value == null || value === false) continue
+    // Skip event handlers
+    if (key.startsWith('on') && key.length > 2 && key[2] === key[2].toUpperCase()) continue
+    // Skip children prop
+    if (key === 'children') continue
+    if (key === 'style') {
+      const css = styleToCss(value)
+      if (css != null) parts.push(`style="${css}"`)
+      continue
+    }
+    // Map JSX prop names to HTML attribute names. Case-sensitive SVG
+    // attrs keep their camelCase per the spec; HTML / CSS-style SVG
+    // presentation attrs lower-case to kebab-case.
+    const attr = key === 'className' ? 'class'
+      : key === 'htmlFor' ? 'for'
+      : SVG_CAMEL_CASE_ATTRS.has(key) ? key
+      : key.replace(/([A-Z])/g, '-$1').toLowerCase()
+    parts.push(value === true ? attr : `${attr}="${value}"`)
+  }
+  return parts.join(' ')
+}

package/src/runtime/streaming.ts

@@ -0,0 +1,65 @@
+/**
+ * BarefootJS - Out-of-Order Streaming
+ *
+ * Client-side resolver for OOS (Out-of-Order Streaming) SSR.
+ * Handles swapping fallback content with resolved content that arrives
+ * via chunked HTTP responses.
+ *
+ * Protocol:
+ * 1. Server sends HTML with fallback placeholders: <div bf-async="a0">...</div>
+ * 2. As async data resolves, server appends chunks:
+ *    <template bf-async-resolve="a0">...resolved...</template>
+ *    <script>__bf_swap("a0")</script>
+ * 3. This module swaps fallback → resolved content and triggers hydration.
+ */
+
+import { BF_ASYNC, BF_ASYNC_RESOLVE } from '@barefootjs/shared'
+import { rehydrateAll } from './hydrate'
+
+/**
+ * Swap a streaming fallback placeholder with its resolved content.
+ *
+ * Finds the placeholder element (`[bf-async="<id>"]`) and the resolve
+ * template (`<template bf-async-resolve="<id>">`), replaces the placeholder's
+ * children with the resolved content, then triggers hydration.
+ *
+ * @param id - The async boundary ID (e.g., "a0")
+ */
+export function __bf_swap(id: string): void {
+  const slot = document.querySelector(`[${BF_ASYNC}="${id}"]`)
+  const tmpl = document.querySelector(`template[${BF_ASYNC_RESOLVE}="${id}"]`) as HTMLTemplateElement | null
+
+  if (!slot || !tmpl) return
+
+  // Replace fallback with resolved content
+  slot.replaceChildren(tmpl.content.cloneNode(true))
+  slot.removeAttribute(BF_ASYNC)
+
+  // Clean up the template element
+  tmpl.remove()
+
+  // Trigger hydration for newly inserted content. `rehydrateAll()`
+  // schedules its own microtask + rAF walk via `scheduleWalk()`, so the
+  // extra rAF wrapper that used to live here is redundant — calling
+  // through synchronously lets the microtask path catch the swap on
+  // the same tick.
+  rehydrateAll()
+}
+
+/**
+ * Install the global streaming resolver.
+ *
+ * Makes `__bf_swap` available as `window.__bf_swap` so that inline
+ * `<script>__bf_swap("a0")</script>` tags in streaming chunks can call it.
+ *
+ * Also exposes `window.__bf_hydrate` for manual re-hydration triggers.
+ *
+ * Call this once, early in the page (before any streaming chunks arrive).
+ */
+export function setupStreaming(): void {
+  if (typeof window === 'undefined') return
+
+  const w = window as unknown as Record<string, unknown>
+  w.__bf_swap = __bf_swap
+  w.__bf_hydrate = rehydrateAll
+}

package/src/runtime/style.ts

@@ -0,0 +1,27 @@
+/**
+ * Style attribute helpers for client-side DOM updates.
+ */
+
+/**
+ * Convert a style value (string or object) to a CSS string, or null to remove the attribute.
+ *
+ * - null/undefined → null (remove the attribute)
+ * - string → the string as-is
+ * - object → camelCase keys converted to kebab-case, joined with semicolons
+ *
+ * @example
+ * styleToCss({ backgroundColor: 'red', fontSize: '16px' }) // "background-color:red;font-size:16px"
+ * styleToCss('color:red')   // "color:red"
+ * styleToCss(null)          // null
+ */
+export function styleToCss(value: unknown): string | null {
+  if (value == null) return null
+  if (typeof value !== 'object') return String(value)
+  const parts: string[] = []
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    if (v == null) continue
+    const prop = k.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`)
+    parts.push(`${prop}:${v}`)
+  }
+  return parts.join(';') || null
+}

package/src/runtime/template.ts

@@ -0,0 +1,53 @@
+/**
+ * BarefootJS - Template Registry
+ *
+ * Stores template functions for client-side component creation.
+ * Templates generate HTML strings from props, used by createComponent().
+ */
+
+/**
+ * Template function type - generates HTML string from props
+ */
+export type TemplateFn = (props: Record<string, unknown>) => string
+
+/**
+ * Registry storing template functions by component name
+ */
+const templateRegistry = new Map<string, TemplateFn>()
+
+/**
+ * Register a template function for a component.
+ *
+ * @param name - Component name (e.g., 'TodoItem')
+ * @param templateFn - Function that generates HTML from props
+ *
+ * @example
+ * registerTemplate('TodoItem', (props) => `
+ *   <li class="${props.done ? 'done' : ''}">
+ *     <span>${props.text}</span>
+ *   </li>
+ * `)
+ */
+export function registerTemplate(name: string, templateFn: TemplateFn): void {
+  templateRegistry.set(name, templateFn)
+}
+
+/**
+ * Get a registered template function by component name.
+ *
+ * @param name - Component name
+ * @returns Template function or undefined if not registered
+ */
+export function getTemplate(name: string): TemplateFn | undefined {
+  return templateRegistry.get(name)
+}
+
+/**
+ * Check if a template is registered for a component.
+ *
+ * @param name - Component name
+ * @returns true if template is registered
+ */
+export function hasTemplate(name: string): boolean {
+  return templateRegistry.has(name)
+}

package/src/runtime/types.ts

@@ -0,0 +1,27 @@
+/**
+ * BarefootJS - Core Types
+ *
+ * Shared type definitions for component initialization and registration.
+ */
+
+/**
+ * Component init function type.
+ * Takes the scope element and props, initializes the component
+ * by setting up event handlers, effects, and reactive bindings.
+ */
+export type InitFn = (scope: Element, props: Record<string, unknown>) => void
+
+/**
+ * Component definition.
+ * Bundles the init function with optional template and scope metadata.
+ */
+export interface ComponentDef {
+  /** Component name (e.g., 'Counter'). Used for scope ID generation. */
+  name?: string
+  /** Init function that hydrates a scope element */
+  init: InitFn
+  /** Template function for client-side component creation */
+  template?: (props: Record<string, unknown>) => string
+  /** When true, use comment-based scope hydration (fragment roots) */
+  comment?: boolean
+}

package/src/shims.ts

@@ -0,0 +1,54 @@
+/**
+ * Browser-only API shims.
+ *
+ * These functions have real implementations in `./runtime/` that the
+ * compiler emits for `'use client'` components. The exports here exist
+ * for type-checking in user source files.
+ *
+ * If one of these ever runs, it means a `'use client'` component was
+ * executed without going through the compiler — or a non-client file
+ * slipped past the `MISSING_USE_CLIENT` check. Either way, it's a bug.
+ */
+
+import type { Context } from './context'
+import type { Portal, PortalChildren, PortalOptions } from './runtime/portal'
+
+export type { Portal, PortalChildren, PortalOptions, Renderable } from './runtime/portal'
+
+function browserOnly(name: string): never {
+  throw new Error(
+    `[barefootjs] ${name}() is a browser-only API and can only be called from a "use client" component. ` +
+      `If you are seeing this at runtime, the BarefootJS compiler did not rewrite the import — please report a bug.`,
+  )
+}
+
+export function useContext<T>(_context: Context<T>): T {
+  return browserOnly('useContext')
+}
+
+export function provideContext<T>(_context: Context<T>, _value: T): void {
+  return browserOnly('provideContext')
+}
+
+export function createPortal(
+  _children: PortalChildren,
+  _container?: Element,
+  _options?: PortalOptions,
+): Portal {
+  return browserOnly('createPortal')
+}
+
+export function isSSRPortal(_element: HTMLElement): boolean {
+  return browserOnly('isSSRPortal')
+}
+
+export function findSiblingSlot(
+  _el: HTMLElement,
+  _slotSelector: string,
+): HTMLElement | null {
+  return browserOnly('findSiblingSlot')
+}
+
+export function cleanupPortalPlaceholder(_portalId: string): void {
+  return browserOnly('cleanupPortalPlaceholder')
+}

package/src/slot.ts

@@ -0,0 +1,23 @@
+/**
+ * Slot marker for JSX props that contain components.
+ *
+ * When a caller passes `<Button />` inside a JSX prop, the compiler wraps
+ * the value with `__slot()`. The callee's text effect checks `__isSlot`
+ * and skips the destructive `nodeValue = String(...)` update, preserving
+ * the server-rendered DOM for hydration.
+ */
+
+export interface SlotMarker {
+  __isSlot: true
+  toString(): string
+}
+
+export function __slot(thunk: () => unknown): SlotMarker {
+  return {
+    __isSlot: true,
+    toString() {
+      const result = thunk()
+      return result == null ? '' : String(result)
+    },
+  }
+}

package/src/split-props.ts

@@ -0,0 +1,86 @@
+/**
+ * BarefootJS - splitProps
+ *
+ * SolidJS-compatible utility for splitting a props object into local and rest.
+ * Uses Proxy to preserve getter-based reactivity.
+ *
+ * @example
+ * ```tsx
+ * import { splitProps } from '@barefootjs/client'
+ *
+ * function Checkbox(props: CheckboxProps) {
+ *   const [local, rest] = splitProps(props, ['checked', 'onCheckedChange'])
+ *   return <button {...rest} aria-checked={local.checked} />
+ * }
+ * ```
+ */
+
+/**
+ * Split a props object into two: one with the specified keys, one with the rest.
+ * Both returned objects use Proxy to defer reads, preserving reactive tracking.
+ *
+ * @param props - The source props object
+ * @param keys - Keys to extract into the first (local) object
+ * @returns A tuple [local, rest] where local has the specified keys and rest has everything else
+ */
+export function splitProps<
+  T extends Record<string, unknown>,
+  K extends (keyof T)[]
+>(
+  props: T,
+  keys: K
+): [Pick<T, K[number]>, Omit<T, K[number]>] {
+  const keySet = new Set<string | symbol>(keys as (string | symbol)[])
+
+  const local = new Proxy({} as Pick<T, K[number]>, {
+    get(_, key) {
+      if (keySet.has(key)) {
+        return (props as Record<string | symbol, unknown>)[key]
+      }
+      return undefined
+    },
+    has(_, key) {
+      return keySet.has(key)
+    },
+    ownKeys() {
+      return [...keySet] as string[]
+    },
+    getOwnPropertyDescriptor(_, key) {
+      if (keySet.has(key)) {
+        return {
+          configurable: true,
+          enumerable: true,
+          get: () => (props as Record<string | symbol, unknown>)[key],
+        }
+      }
+      return undefined
+    },
+  })
+
+  const rest = new Proxy({} as Omit<T, K[number]>, {
+    get(_, key) {
+      if (!keySet.has(key)) {
+        return (props as Record<string | symbol, unknown>)[key]
+      }
+      return undefined
+    },
+    has(_, key) {
+      return key in props && !keySet.has(key)
+    },
+    ownKeys() {
+      return Object.keys(props).filter(k => !keySet.has(k))
+    },
+    getOwnPropertyDescriptor(_, key) {
+      if (key in props && !keySet.has(key)) {
+        return {
+          configurable: true,
+          enumerable: true,
+          get: () => (props as Record<string | symbol, unknown>)[key],
+        }
+      }
+      return undefined
+    },
+  })
+
+  return [local, rest]
+}

package/src/unwrap.ts

@@ -0,0 +1,18 @@
+/**
+ * BarefootJS - Unwrap Utility
+ *
+ * Unwrap a prop value that may be a getter function.
+ * When props are passed from parent to child components, reactive values
+ * are wrapped as getter functions to maintain reactivity.
+ * This helper unwraps them transparently.
+ */
+
+/**
+ * Unwrap a prop value that may be a getter function.
+ *
+ * @param prop - The prop value (may be a value or a getter function)
+ * @returns The unwrapped value
+ */
+export function unwrap<T>(prop: T | (() => T)): T {
+  return typeof prop === 'function' ? (prop as () => T)() : prop
+}