@barefootjs/client 0.26.3 → 0.27.0

package/src/runtime/index.ts

@@ -77,11 +77,17 @@ export {
   type PortalChildren,
 } from './portal.ts'
 
-// List reconciliation
-export { reconcileList, type RenderItemFn } from './list.ts'
-export { reconcileElements, getLoopChildren, getLoopNodes } from './reconcile-elements.ts'
+// Loop boundary marker lookup (used by mapArray/mapArrayAnchored consumers
+// and compiler-generated clearing code — see ./loop-markers.ts docstring)
+export { getLoopChildren, getLoopNodes } from './loop-markers.ts'
 export { qsaItem, upsertChildItem } from './qsa-item.ts'
 export { mapArray, mapArrayAnchored } from './map-array.ts'
+export { patchLeaf } from './patch-leaf.ts'
+
+// Claim-plan interpreter (slot unification A2/A3, spec/slot-unification.md)
+// — the ONE content-slot update mechanism, wired up by the compiler in A3.
+// Supersedes (deleted) `patchSlotRange` and `updateClientMarker`.
+export { claimSlots, lazySlots, type SlotSpec, type ClaimPlan, type ClaimedSlots, type SlotWriter } from './claim-slots.ts'
 
 // Template registry
 export { registerTemplate, getTemplate, hasTemplate, type TemplateFn } from './template.ts'
@@ -90,11 +96,10 @@ export { registerTemplate, getTemplate, hasTemplate, type TemplateFn } from './t
 export {
   createComponent,
   renderChild,
-  getPropsUpdateFn,
-  getComponentProps,
   parseHTML,
   escapeAttr,
   escapeText,
+  escapeTextOrNode,
 } from './component.ts'
 
 // Spread props helpers
@@ -109,8 +114,14 @@ export { hydrate, rehydrateAll, rehydrateScope, disposeScope, flushHydration, ge
 export { registerComponent, getComponentInit, initChild, upsertChild } from './registry.ts'
 export { insert, type BranchConfig, type BranchTemplateResult } from './insert.ts'
 export { __bfSlot } from './branch-slot.ts'
+// `__bfText` (dynamic-text.ts) and `$t` (query.ts) are kept: one narrow
+// emission site — a `@client`-nested-inside-a-top-level-conditional dynamic
+// text/JSX expression (`emitDynamicTextUpdates`'s `conditionalElems` path in
+// `ir-to-client-js/emit-reactive.ts`) still uses them, deferred from slot
+// unification A3 (see that function's docstring for why the claim-plan
+// model doesn't fit that one case cleanly). `updateClientMarker` had no
+// such holdout and is fully deleted.
 export { __bfText } from './dynamic-text.ts'
-export { updateClientMarker } from './client-marker.ts'
 
 // Hydration state
 export { hydratedScopes } from './hydration-state.ts'

package/src/runtime/insert.ts

@@ -338,7 +338,7 @@ export function insert(
 function autoFocusConditionalElement(region: CondRegion, id: string): void {
   // Use requestAnimationFrame to defer focus until after DOM updates.
   // This is necessary because createComponent() may call insert() before
-  // the element is added to the document by reconcileList().
+  // the element is added to the document by mapArray()/mapArrayAnchored().
   requestAnimationFrame(() => {
     const condEl = region.anchor
       ? findCondElInRange(region.anchor, id)

package/src/runtime/loop-markers.ts

@@ -0,0 +1,100 @@
+/**
+ * BarefootJS - Loop Boundary Marker Lookup
+ *
+ * `<!--bf-loop:<id>-->` / `<!--bf-/loop:<id>-->` comment markers delimit a
+ * loop's rendered range inside its container so `mapArray`/`mapArrayAnchored`
+ * (`./map-array.ts`) can reconcile only that range without disturbing
+ * non-loop siblings. These lookups used to also back the now-removed
+ * `reconcileElements`/`reconcileList` element-reconciler (slot unification
+ * A4); they remain as the compiler-facing marker API.
+ */
+
+import { BF_LOOP_START, BF_LOOP_END, loopStartMarker, loopEndMarker } from '@barefootjs/shared'
+
+/**
+ * Find loop boundary comment markers in a container.
+ *
+ * `markerId` scopes the lookup to `<!--bf-loop:<id>-->` / `<!--bf-/loop:<id>-->`
+ * so sibling loops under the same parent disambiguate (#1087). Without an id,
+ * accepts the legacy unscoped form too — used by tests that build containers
+ * without compiler-emitted markers.
+ */
+function findLoopMarkers(
+  container: HTMLElement,
+  markerId?: string,
+): { startMarker: Comment | null; endMarker: Comment | null } {
+  let startMarker: Comment | null = null
+  let endMarker: Comment | null = null
+  if (markerId) {
+    const startVal = loopStartMarker(markerId)
+    const endVal = loopEndMarker(markerId)
+    for (const node of Array.from(container.childNodes)) {
+      if (node.nodeType !== Node.COMMENT_NODE) continue
+      const value = (node as Comment).nodeValue
+      if (value === startVal) startMarker = node as Comment
+      else if (value === endVal) endMarker = node as Comment
+    }
+  } else {
+    const startPrefix = `${BF_LOOP_START}:`
+    const endPrefix = `${BF_LOOP_END}:`
+    for (const node of Array.from(container.childNodes)) {
+      if (node.nodeType !== Node.COMMENT_NODE) continue
+      const value = (node as Comment).nodeValue ?? ''
+      if (!startMarker && (value === BF_LOOP_START || value.startsWith(startPrefix))) {
+        startMarker = node as Comment
+      } else if (!endMarker && (value === BF_LOOP_END || value.startsWith(endPrefix))) {
+        endMarker = node as Comment
+      }
+    }
+  }
+  if (startMarker && endMarker) return { startMarker, endMarker }
+  return { startMarker: null, endMarker: null }
+}
+
+/** Get all Element nodes between start and end comment markers. */
+function getElementsBetweenMarkers(start: Comment, end: Comment): Element[] {
+  const elements: Element[] = []
+  let node: Node | null = start.nextSibling
+  while (node && node !== end) {
+    if (node.nodeType === Node.ELEMENT_NODE) {
+      elements.push(node as Element)
+    }
+    node = node.nextSibling
+  }
+  return elements
+}
+
+/**
+ * Get loop children from a container, respecting bf-loop boundary markers.
+ * When markers are present, returns only elements between them.
+ * When absent, returns all children (backward compatible).
+ * Exported for use by compiler-generated hydration code.
+ */
+export function getLoopChildren(container: HTMLElement, markerId?: string): HTMLElement[] {
+  const { startMarker, endMarker } = findLoopMarkers(container, markerId)
+  if (startMarker && endMarker) {
+    return getElementsBetweenMarkers(startMarker, endMarker) as HTMLElement[]
+  }
+  return Array.from(container.children) as HTMLElement[]
+}
+
+/**
+ * Like {@link getLoopChildren}, but returns every node between the loop
+ * boundary markers — Comments (per-item `<!--bf-loop-i-->` markers) and
+ * text included. The branch-clearing path needs to remove the per-item
+ * marker comments alongside elements; otherwise stale markers would
+ * accumulate when a branch swap forces mapArray to start over (#1212).
+ */
+export function getLoopNodes(container: HTMLElement, markerId?: string): Node[] {
+  const { startMarker, endMarker } = findLoopMarkers(container, markerId)
+  const nodes: Node[] = []
+  if (startMarker && endMarker) {
+    let node: Node | null = startMarker.nextSibling
+    while (node && node !== endMarker) {
+      nodes.push(node)
+      node = node.nextSibling
+    }
+    return nodes
+  }
+  return Array.from(container.childNodes)
+}

package/src/runtime/patch-leaf.ts

@@ -0,0 +1,41 @@
+/**
+ * In-place patch for flatMap leaf elements (the descriptor-based
+ * `mapArray` path — see `stringifyPlainLoop`'s flatMap branch in
+ * `@barefootjs/jsx`).
+ *
+ * flatMap leaves carry no per-slot reactive wiring (the compiler refuses
+ * leaves that would need it), so a leaf whose rendered HTML changed under a
+ * stable key is updated wholesale: attributes are synced and children are
+ * replaced from the freshly rendered string. The element's identity is
+ * preserved — `mapArray` holds the node in its keyed scope map, so the
+ * patch must never swap the node itself.
+ *
+ * `data-key` is excluded from attribute sync: reconciliation identity is
+ * owned by `mapArray` (stamped via `setAttribute`), never by leaf content.
+ */
+export function patchLeaf(el: Element, html: string): void {
+  const tpl = document.createElement('template')
+  tpl.innerHTML = html
+  const next = tpl.content.firstElementChild
+  if (!next) return
+  if (next.tagName !== el.tagName) {
+    // A root-tag change under a stable key cannot swap the node without
+    // desyncing mapArray's keyed scope. Attributes/children still patch
+    // onto the existing tag; the honest fix is a distinct key per branch.
+    console.warn(
+      '[barefootjs] flatMap leaf root tag changed under a stable key ' +
+        `(<${el.tagName.toLowerCase()}> -> <${next.tagName.toLowerCase()}>); ` +
+        'give each branch its own key so the node is replaced instead of patched.',
+    )
+  }
+  for (const name of el.getAttributeNames()) {
+    if (name === 'data-key') continue
+    if (!next.hasAttribute(name)) el.removeAttribute(name)
+  }
+  for (const name of next.getAttributeNames()) {
+    if (name === 'data-key') continue
+    const value = next.getAttribute(name)
+    if (value !== null && el.getAttribute(name) !== value) el.setAttribute(name, value)
+  }
+  el.replaceChildren(...Array.from(next.childNodes))
+}

package/dist/runtime/client-marker.d.ts

@@ -1,21 +0,0 @@
-/**
- * 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 declare function updateClientMarker(scope: Element | null, id: string, value: unknown): void;
-//# sourceMappingURL=client-marker.d.ts.map

package/dist/runtime/client-marker.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"client-marker.d.ts","sourceRoot":"","sources":["../../src/runtime/client-marker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAyB1F"}

package/dist/runtime/list.d.ts

@@ -1,21 +0,0 @@
-/**
- * BarefootJS - List Reconciliation
- *
- * Key-based DOM reconciliation for efficient list updates.
- * Delegates to reconcileElements for element-based rendering.
- */
-/**
- * Render function type for list items.
- * Returns an HTMLElement for each item.
- */
-export type RenderItemFn<T> = (item: T, index: number) => HTMLElement;
-/**
- * Reconcile a list container with new items using key-based matching.
- *
- * @param container - The parent element containing list items
- * @param items - Array of items to render
- * @param getKey - Function to extract a unique key from each item (or null to use index)
- * @param renderItem - Function to render an item as HTMLElement
- */
-export declare function reconcileList<T>(container: HTMLElement | null, items: T[], getKey: ((item: T, index: number) => string) | null, renderItem: RenderItemFn<T>): void;
-//# sourceMappingURL=list.d.ts.map

package/dist/runtime/list.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../src/runtime/list.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;GAGG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,WAAW,CAAA;AAErE;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,SAAS,EAAE,WAAW,GAAG,IAAI,EAC7B,KAAK,EAAE,CAAC,EAAE,EACV,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,IAAI,EACnD,UAAU,EAAE,YAAY,CAAC,CAAC,CAAC,GAC1B,IAAI,CAkBN"}

package/dist/runtime/reconcile-elements.d.ts

@@ -1,44 +0,0 @@
-/**
- * BarefootJS - Element-based List Reconciliation
- *
- * Key-based DOM reconciliation for component-based list rendering.
- * Used when renderItem returns HTMLElement (via createComponent).
- */
-/**
- * Get loop children from a container, respecting bf-loop boundary markers.
- * When markers are present, returns only elements between them.
- * When absent, returns all children (backward compatible).
- * Exported for use by compiler-generated hydration code.
- */
-export declare function getLoopChildren(container: HTMLElement, markerId?: string): HTMLElement[];
-/**
- * Like {@link getLoopChildren}, but returns every node between the loop
- * boundary markers — Comments (per-item `<!--bf-loop-i-->` markers) and
- * text included. The branch-clearing path needs to remove the per-item
- * marker comments alongside elements; otherwise stale markers would
- * accumulate when a branch swap forces mapArray to start over (#1212).
- */
-export declare function getLoopNodes(container: HTMLElement, markerId?: string): Node[];
-/**
- * Ensure loop boundary markers exist in a container for SSR-rendered content.
- * SSR HTML doesn't include markers, so we insert them during hydration.
- * Uses itemCount to identify the last N children as loop items (rest are siblings).
- */
-export declare function ensureLoopMarkers(container: HTMLElement, itemCount: number, markerId?: string): void;
-/**
- * Reconcile a list container using HTMLElement mode (for createComponent).
- * Reuses existing elements by key, creates new elements as needed.
- *
- * @param container - The parent element containing list items
- * @param items - Array of items to render
- * @param getKey - Function to extract a unique key from each item (or null to use index)
- * @param renderItem - Function that returns an HTMLElement for each item
- * @param firstElement - Pre-created element for first item (avoids duplicate creation when caller already rendered item 0)
- */
-export declare function reconcileElements<T>(container: HTMLElement | null, items: T[], getKey: ((item: T, index: number) => string) | null, renderItem: (item: T, index: number) => HTMLElement, firstElement?: HTMLElement, markerId?: string): void;
-/**
- * Sync reactive DOM state from a source element to a target element.
- * Copies class names, replaces conditional elements, and syncs text content.
- */
-export declare function syncElementState(target: HTMLElement, source: HTMLElement): void;
-//# sourceMappingURL=reconcile-elements.d.ts.map

package/dist/runtime/reconcile-elements.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"reconcile-elements.d.ts","sourceRoot":"","sources":["../../src/runtime/reconcile-elements.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAoEH;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,WAAW,EAAE,CAMxF;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,EAAE,CAY9E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAgBpG;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,SAAS,EAAE,WAAW,GAAG,IAAI,EAC7B,KAAK,EAAE,CAAC,EAAE,EACV,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,IAAI,EACnD,UAAU,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,WAAW,EACnD,YAAY,CAAC,EAAE,WAAW,EAC1B,QAAQ,CAAC,EAAE,MAAM,GAChB,IAAI,CA2JN;AAkCD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI,CAiD/E"}

package/src/runtime/client-marker.ts

@@ -1,46 +0,0 @@
-/**
- * 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
-    }
-  }
-}

package/src/runtime/list.ts

@@ -1,47 +0,0 @@
-/**
- * BarefootJS - List Reconciliation
- *
- * Key-based DOM reconciliation for efficient list updates.
- * Delegates to reconcileElements for element-based rendering.
- */
-
-import { reconcileElements } from './reconcile-elements.ts'
-
-/**
- * Render function type for list items.
- * Returns an HTMLElement for each item.
- */
-export type RenderItemFn<T> = (item: T, index: number) => HTMLElement
-
-/**
- * Reconcile a list container with new items using key-based matching.
- *
- * @param container - The parent element containing list items
- * @param items - Array of items to render
- * @param getKey - Function to extract a unique key from each item (or null to use index)
- * @param renderItem - Function to render an item as HTMLElement
- */
-export function reconcileList<T>(
-  container: HTMLElement | null,
-  items: T[],
-  getKey: ((item: T, index: number) => string) | null,
-  renderItem: RenderItemFn<T>
-): void {
-  if (!container || !items) return
-
-  if (items.length === 0) {
-    container.innerHTML = ''
-    return
-  }
-
-  // Pre-create first element to avoid duplicate creation inside reconcileElements
-  const firstElement = renderItem(items[0], 0)
-
-  reconcileElements(
-    container,
-    items,
-    getKey,
-    renderItem,
-    firstElement
-  )
-}