@barefootjs/client 0.34.0 → 0.35.0

package/src/runtime/map-array.ts

@@ -18,7 +18,7 @@
  * Single-root loops continue to flow through the legacy path verbatim.
  */
 
-import { createSignal, createEffect, createRoot } from '@barefootjs/client/reactive'
+import { createSignal, createEffect, createRoot, batch } from '@barefootjs/client/reactive'
 import { hydratedScopes } from './hydration-state.ts'
 import { setRowMountPoint, type RowMountPoint } from './component.ts'
 import {
@@ -80,8 +80,30 @@ type ItemScope<T> = {
   scopeComments: ScopeCommentPair | null
   dispose: () => void
   setItem: (v: T) => void
+  /**
+   * Push this row's CURRENT position (#2859). A same-key reorder never
+   * re-invokes `renderItem` — only `setItem`/`setIndex` run — so anything
+   * the row body derives from the raw `.map()` index parameter (rather
+   * than from the item itself) stays live only because the compiler
+   * rewrites references to that parameter into a call through the
+   * accessor `renderItem` received (`wrapLoopParamAsAccessor`,
+   * ir-to-client-js/utils.ts) instead of using the plain number this
+   * signal was seeded from.
+   */
+  setIndex: (i: number) => void
 }
 
+/**
+ * Shape `renderItem` callbacks are compiled to. `index` mirrors `item`:
+ * an accessor, not a plain number, so a row body's reference to the raw
+ * `.map()` index parameter — rewritten to a call by
+ * `wrapLoopParamAsAccessor` — reads the row's CURRENT position instead of
+ * the value captured when the row was first created (#2859). `existing`
+ * stays optional/untyped-per-call-site since `mapArray` and
+ * `mapArrayAnchored` return different element shapes.
+ */
+export type RenderItem<T, E, R> = (item: () => T, index: () => number, existing?: E) => R
+
 /**
  * Find loop boundary comment markers in a container.
  *
@@ -327,7 +349,7 @@ function removeScope<T>(scope: ItemScope<T>): void {
 function createItemScope<T>(
   item: T,
   index: number,
-  renderItem: (item: () => T, index: number, existing?: HTMLElement) => HTMLElement,
+  renderItem: RenderItem<T, HTMLElement, HTMLElement>,
   existingPrimary?: HTMLElement,
   existingExtras?: HTMLElement[],
   existingStart?: Comment | null,
@@ -337,6 +359,7 @@ function createItemScope<T>(
   let primaryEl!: HTMLElement
   let dispose!: () => void
   let setItem!: (v: T) => void
+  let setIndex!: (i: number) => void
   let extras: HTMLElement[] = []
   let startMarker: Comment | null = null
   let scopeComments: ScopeCommentPair | null = null
@@ -344,7 +367,9 @@ function createItemScope<T>(
   createRoot((d) => {
     dispose = d
     const [itemAccessor, itemSetter] = createSignal(item)
+    const [indexAccessor, indexSetter] = createSignal(index)
     setItem = itemSetter
+    setIndex = indexSetter
     // Fresh row: hand the mount point down so the row's own root — whether a
     // `createComponent` call or a `mountRowRoot(clone)` — observes a connected
     // element when the body's tail initialises its children. A body that does
@@ -358,7 +383,7 @@ function createItemScope<T>(
     const ownsRowMount = !existingPrimary && !!rowMount
     const prevRowMount = ownsRowMount ? setRowMountPoint(rowMount) : null
     try {
-      primaryEl = renderItem(itemAccessor, index, existingPrimary)
+      primaryEl = renderItem(itemAccessor, indexAccessor, existingPrimary)
     } catch (err) {
       // A row that connected itself and then failed to finish would stay
       // visible as a half-built row. Detached rows never could, so undo the
@@ -399,7 +424,7 @@ function createItemScope<T>(
     primaryEl.remove()
   }
 
-  return { startMarker, primaryEl, extras, scopeComments, dispose, setItem }
+  return { startMarker, primaryEl, extras, scopeComments, dispose, setItem, setIndex }
 }
 
 /**
@@ -427,7 +452,7 @@ export function mapArray<T>(
   accessor: () => T[],
   container: HTMLElement | null,
   getKey: ((item: T, index: number) => string) | null,
-  renderItem: (item: () => T, index: number, existing?: HTMLElement) => HTMLElement,
+  renderItem: RenderItem<T, HTMLElement, HTMLElement>,
   markerId?: string,
   bfId?: string,
   keyAttrName: string = BF_KEY,
@@ -573,6 +598,7 @@ export function mapArray<T>(
             scopeComments: range.scopeComments,
             dispose: () => {},
             setItem: () => {},
+            setIndex: () => {},
           })
         }
       }
@@ -645,8 +671,13 @@ export function mapArray<T>(
       const existing = scopes.get(key)
       if (existing) {
         // Same key: update per-item signal — fine-grained effects handle DOM updates.
-        // Element is preserved (no dispose, no re-render).
-        existing.setItem(item)
+        // Element is preserved (no dispose, no re-render). `setIndex` pushes this
+        // row's CURRENT position (#2859) — batched with `setItem` so a row whose
+        // effect reads both doesn't run twice for one reconcile pass.
+        batch(() => {
+          existing.setItem(item)
+          existing.setIndex(i)
+        })
         desiredOrder.push(existing)
       } else {
         // New item: create in isolated scope. The row is mounted at the end of
@@ -779,6 +810,8 @@ type AnchorScope<T> = {
   pending: DocumentFragment | null
   dispose: () => void
   setItem: (v: T) => void
+  /** See `ItemScope.setIndex` (#2859) — same per-row "current position" push. */
+  setIndex: (i: number) => void
 }
 
 const ITEM_PREFIX = `${BF_LOOP_ITEM}:`
@@ -845,23 +878,26 @@ function createAnchorScope<T>(
   item: T,
   index: number,
   key: string,
-  renderItem: (item: () => T, index: number, existing?: Comment) => DocumentFragment | Comment,
+  renderItem: RenderItem<T, Comment, DocumentFragment | Comment>,
   existingAnchor?: Comment,
 ): AnchorScope<T> {
   let dispose!: () => void
   let setItem!: (v: T) => void
+  let setIndex!: (i: number) => void
   let returned!: DocumentFragment | Comment
 
   createRoot((d) => {
     dispose = d
     const [itemAccessor, itemSetter] = createSignal(item)
+    const [indexAccessor, indexSetter] = createSignal(index)
     setItem = itemSetter
-    returned = renderItem(itemAccessor, index, existingAnchor)
+    setIndex = indexSetter
+    returned = renderItem(itemAccessor, indexAccessor, existingAnchor)
     return undefined
   })
 
   if (existingAnchor) {
-    return { anchor: existingAnchor, pending: null, dispose, setItem }
+    return { anchor: existingAnchor, pending: null, dispose, setItem, setIndex }
   }
   // CSR: renderItem returns a fragment whose first child is the anchor.
   const frag = returned as DocumentFragment
@@ -871,7 +907,7 @@ function createAnchorScope<T>(
   if (anchor && !anchor.nodeValue?.startsWith(ITEM_PREFIX)) {
     anchor.nodeValue = loopItemMarker(key)
   }
-  return { anchor, pending: frag, dispose, setItem }
+  return { anchor, pending: frag, dispose, setItem, setIndex }
 }
 
 /**
@@ -886,7 +922,7 @@ export function mapArrayAnchored<T>(
   accessor: () => T[],
   container: HTMLElement | null,
   getKey: ((item: T, index: number) => string) | null,
-  renderItem: (item: () => T, index: number, existing?: Comment) => DocumentFragment | Comment,
+  renderItem: RenderItem<T, Comment, DocumentFragment | Comment>,
   markerId?: string,
   bfId?: string,
 ): void {
@@ -949,7 +985,12 @@ export function mapArrayAnchored<T>(
 
       const existing = scopes.get(key)
       if (existing) {
-        existing.setItem(item)
+        // See the identical `mapArray` branch above (#2859): batched so a row
+        // whose effect reads both item and index doesn't run twice.
+        batch(() => {
+          existing.setItem(item)
+          existing.setIndex(i)
+        })
         desiredOrder.push(existing)
       } else {
         const scope = createAnchorScope(item, i, key, renderItem)

package/src/runtime/portal.ts

@@ -126,6 +126,143 @@ export function cleanupPortalPlaceholder(portalId: string): void {
   placeholder?.remove()
 }
 
+/**
+ * A portal whose deferral subject (see `createPortal`'s insertion rule) was
+ * not yet in the document when `createPortal` ran (#2717). Its element is
+ * ALREADY a child of `container`; once the subject connects it is
+ * re-appended, which moves it to the container's end.
+ */
+interface PendingPortal {
+  element: HTMLElement
+  container: HTMLElement
+  /** The node whose connection is awaited: the owner, or the element's former parent. */
+  subject: Node
+}
+
+/** Creation-ordered queue of portals waiting for their subject to connect. */
+const pendingPortals: PendingPortal[] = []
+/** Alive only while `pendingPortals` is non-empty. */
+let pendingObserver: MutationObserver | null = null
+
+/**
+ * `Element.moveBefore()` — not yet in TS's bundled `lib.dom.d.ts` — moves an
+ * already-connected node without the side effects `appendChild`/
+ * `insertBefore` are specified to have on one: it resets `<iframe>` load
+ * state, `<video>`/`<audio>` playback position, CSS animation/transition
+ * state, `:focus`/`:active`, and native `popover`/fullscreen state. The
+ * reorder below is a genuine move of an already-connected node (the
+ * element is already `container`'s child from `createPortal`'s initial
+ * append), so it must prefer `moveBefore` and fall back to `appendChild`
+ * only where the API isn't supported yet — same fallback shape as the
+ * `MutationObserver` feature-detection above.
+ */
+interface MoveBeforeCapable {
+  moveBefore(node: Node, child: Node | null): void
+}
+
+/** Move `element` to `container`'s end, preserving any live state a plain re-`appendChild` would reset (see `MoveBeforeCapable`). */
+function moveToContainerEnd(container: HTMLElement, element: HTMLElement): void {
+  const moveBefore = (container as Partial<MoveBeforeCapable>).moveBefore
+  if (typeof moveBefore === 'function') {
+    moveBefore.call(container, element, null)
+  } else {
+    container.appendChild(element)
+  }
+}
+
+/**
+ * Re-append every pending portal whose subject has connected since the
+ * last check, in creation order — the same order the hydration path
+ * produces when the owner is already connected and each `createPortal`
+ * appends synchronously. The element is already in `container`, so this
+ * moves the connected node to the container's end (see `moveToContainerEnd`),
+ * after the root that connected it, rather than inserting a new one.
+ * Pending entries whose subject is still detached are kept; an entry
+ * whose element has left the container in the meantime (removed or moved
+ * by the caller without `unmount`) is dropped rather than re-inserted.
+ */
+function flushPendingPortals(): void {
+  for (const pending of pendingPortals.slice()) {
+    if (!pending.subject.isConnected) continue
+    pendingPortals.splice(pendingPortals.indexOf(pending), 1)
+    if (pending.element.parentNode === pending.container) {
+      moveToContainerEnd(pending.container, pending.element)
+    }
+  }
+  if (pendingPortals.length === 0 && pendingObserver) {
+    pendingObserver.disconnect()
+    pendingObserver = null
+  }
+}
+
+function enqueuePendingPortal(pending: PendingPortal): void {
+  pendingPortals.push(pending)
+  if (!pendingObserver) {
+    // Observe the whole document: the subject is connected by whoever holds
+    // the component root (`document.body.appendChild(root)` in a CSR boot,
+    // a placeholder `replaceWith` higher up the tree, …) — the runtime has
+    // no hook of its own at that moment, so the DOM's own insertion
+    // notification is the one signal that covers every caller. Callbacks
+    // run as a microtask, before the next paint, so the element is never
+    // rendered at its pre-reorder position.
+    pendingObserver = new MutationObserver(flushPendingPortals)
+    pendingObserver.observe(document, { childList: true, subtree: true })
+  }
+}
+
+function cancelPendingPortal(element: HTMLElement): void {
+  const idx = pendingPortals.findIndex(p => p.element === element)
+  if (idx >= 0) pendingPortals.splice(idx, 1)
+  if (pendingPortals.length === 0 && pendingObserver) {
+    pendingObserver.disconnect()
+    pendingObserver = null
+  }
+}
+
+/**
+ * Insertion rule (#2717): the portal's content is appended to `container`
+ * synchronously, at call time, and — when the component it belongs to is
+ * not yet in the document — re-appended once that component connects,
+ * which moves it to the container's end.
+ *
+ * - Owner already connected (hydration: SSR markup is in the document
+ *   before `init` runs), or nothing to wait for: a single append, at the
+ *   container's end — unchanged behaviour.
+ * - Owner not yet connected (a client-side mount: `materializeComponent`
+ *   runs `init` — and so the `ref` callbacks that call this — BEFORE the
+ *   bare-`createComponent` caller connects the root): the element is
+ *   appended now all the same, and a reorder is queued; once the owner
+ *   connects, pending portals are re-appended in creation order.
+ *
+ * Without the reorder the two construction paths disagree on
+ * `document.body`'s child order: hydration yields `[root, …portals]`
+ * while a CSR mount yields `[…portals, root]`, because the root is
+ * appended AFTER its portals were. Child order is user-visible (paint
+ * order between equal-`z-index` overlays, focus traversal, `querySelector`
+ * results), so both paths converge on the hydration answer.
+ *
+ * The append itself is never deferred: the element is connected to the
+ * document at every point in time, only its position among the
+ * container's children settles asynchronously (as a microtask, before the
+ * next paint). Portal consumers measure layout synchronously in the same
+ * tick as their `ref` callback — `createEffect`'s first run is synchronous,
+ * and the floating-position components (popover, dropdown-menu, context-
+ * menu, …) read `offsetWidth`/`offsetHeight` of the portaled element there,
+ * gated only on their open signal — so a portal that was briefly absent
+ * from the document would hand them zero-sized boxes with nothing to
+ * re-trigger the measurement once it landed.
+ *
+ * The subject whose connection is awaited is the `ownerScope` when given
+ * and it lies outside the element; otherwise the element's former parent.
+ * The self-owner shape (`ownerScope === element`: a child component whose
+ * own root carries `bf-s`, e.g. DialogOverlay/DialogContent) needs that
+ * fallback, since the immediate append connects the element — and so the
+ * owner — right away, while the component under construction is the tree
+ * it was taken from. An element in a detached tree with no owner (a
+ * fragment-root component, whose scope lives on a comment) is the same
+ * case. A bare element with neither has nothing that will ever connect
+ * it, so there is nothing to wait for.
+ */
 export function createPortal(
   children: PortalChildren,
   container: HTMLElement = document.body,
@@ -161,11 +298,28 @@ export function createPortal(
     }
   }
 
+  // The reorder subject, resolved BEFORE the append moves the element:
+  // the declared owner when it lies outside the element, else the
+  // element's former parent (see the insertion rule above). Only a parent
+  // the caller handed us counts — the string path parses into a fragment,
+  // which never connects; the same goes for a caller-built fragment.
+  const owner = options?.ownerScope
+  const formerParent = children instanceof HTMLElement ? children.parentNode : null
+  const subject: Node | null =
+    owner && !element.contains(owner) ? owner : formerParent instanceof Element ? formerParent : null
+
   container.appendChild(element)
 
+  // `MutationObserver` is the reorder primitive; an environment without it
+  // keeps the plain synchronous append (the pre-#2717 behaviour).
+  if (subject && !subject.isConnected && typeof MutationObserver !== 'undefined') {
+    enqueuePendingPortal({ element, container, subject })
+  }
+
   return {
     element,
     unmount(): void {
+      cancelPendingPortal(element)
       if (element.parentNode) {
         element.parentNode.removeChild(element)
       }

package/src/runtime/track-position.ts

@@ -0,0 +1,47 @@
+/**
+ * BarefootJS - Floating-element position tracking
+ *
+ * Keeps a `position: fixed` overlay (menu, popover, listbox, hover card)
+ * anchored to its trigger for as long as it is open. Shared by every
+ * site/ui overlay that positions itself from `getBoundingClientRect()`
+ * so the decision below is made in one place (#2848).
+ */
+
+/**
+ * Run `update` now, re-run it on every scroll (capture phase, so a
+ * nested scroll container counts too) and on resize, and return the
+ * dispose that detaches both listeners.
+ *
+ * The dispose re-runs `update` ONCE, synchronously, before detaching —
+ * that final sample is the whole point of this helper. `scroll` events
+ * are coalesced per rendering frame and report the scroll position at
+ * dispatch time, not at scroll time. A programmatic scroll that landed
+ * in the current frame (a `focus()` on an offscreen item, a
+ * `scrollIntoView()`) has therefore not dispatched yet when a close
+ * runs in the same frame; the listener is gone by the time the event
+ * fires, and whatever position the listener would have written is lost.
+ * Without the final sample the closed element's inline position depends
+ * on whether a frame boundary happened to fall between that scroll and
+ * the close — measured as the `dropdown-menu` idempotence oracle
+ * landing on `top: -580px` / `-606px` / `33px` for the same action
+ * sequence. Sampling once at dispose makes the closed position a
+ * function of the geometry at close time only.
+ *
+ * (An `overflow: hidden` scroll lock does not narrow this window: it
+ * blocks user gestures, never programmatic scrolling, on `html` and
+ * `body` alike — verified in Chromium against the fixture-hydrate host.)
+ *
+ * @param update - Positions the element from current geometry.
+ * @returns Dispose: re-runs `update` once, then detaches the listeners.
+ */
+export function trackPosition(update: () => void): () => void {
+  update()
+  const onChange = () => update()
+  window.addEventListener('scroll', onChange, true)
+  window.addEventListener('resize', onChange)
+  return () => {
+    window.removeEventListener('scroll', onChange, true)
+    window.removeEventListener('resize', onChange)
+    update()
+  }
+}

package/src/shims.ts

@@ -52,3 +52,7 @@ export function findSiblingSlot(
 export function cleanupPortalPlaceholder(_portalId: string): void {
   return browserOnly('cleanupPortalPlaceholder')
 }
+
+export function trackPosition(_update: () => void): () => void {
+  return browserOnly('trackPosition')
+}