@barefootjs/cli 0.34.0 → 0.35.1

package/dist/docs/core/components/portals.md

@@ -125,6 +125,13 @@ const handleMount = (el: HTMLElement) => {
 
 `bf-po` on the moved element lets scoped queries from the owner still find it.
 
+`ownerScope` also fixes *where* the element ends up among the container's children. Portal content is always appended to the container immediately — it is in the document from the moment `createPortal` returns, so a `ref` callback can measure it (`offsetWidth`, `getBoundingClientRect()`) in the same tick — and its position settles once its owner is connected:
+
+- Owner already connected (hydration — the SSR markup is in the document before `init` runs), or no `ownerScope` given: a single append, at the container's end.
+- Owner not yet connected (a client-side mount — the component's `init`, and so the `ref` callback, runs before whoever called `createComponent()` appends the root): once the owner connects, the element is re-appended, which moves it to the container's end. Pending portals move in creation order, before the next paint.
+
+Both construction paths therefore land on the same `document.body` child order — the component root first, then its portals in the order they were created — which decides paint order between overlays with equal `z-index`, focus traversal, and `querySelector` results.
+
 
 ## Dialog Example
 

package/dist/docs/core/reactivity/untrack.md

@@ -67,3 +67,43 @@ createEffect(() => {
   setResult(a + b)
 })
 ```
+
+
+## What `untrack` Does Not Do
+
+`untrack` only stops the wrapped read from **registering a dependency**. It does not stop the surrounding effect from **re-running** — and when the effect re-runs for any other reason, the code inside `untrack` runs again too.
+
+This matters because BarefootJS groups several bindings into one effect for performance: every reactive attribute on one element shares an effect, and a keyed `.map()` row's attributes and text share a single row effect. When one binding in that group changes, the whole effect re-runs, and every expression in it — untracked or not — is evaluated again.
+
+```tsx
+'use client'
+import { createSignal, untrack } from '@barefootjs/client'
+
+function renderPreview(id: number): string {
+  return `<p>Preview for item ${id}</p>`
+}
+
+export function Gallery() {
+  const [items, setItems] = createSignal([{ id: 1, label: 'First' }, { id: 2, label: 'Second' }])
+  const rename = () => setItems(items().map(item => ({ id: item.id, label: item.label + '!' })))
+  return (
+    <div>
+      <button onClick={rename}>Rename all</button>
+      <ul>
+        {items().map(item => (
+          <li key={item.id} title={item.label} data-preview={untrack(() => renderPreview(item.id))}>
+            {item.label}
+          </li>
+        ))}
+      </ul>
+    </div>
+  )
+}
+```
+
+Clicking "Rename all" changes `title` on every row, so every row effect re-runs and `renderPreview` is called again for each row even though it is wrapped in `untrack`. Two guarantees hold regardless:
+
+- The untracked read still does not subscribe: a signal read only inside `untrack` never triggers the effect on its own.
+- A DOM write is skipped when the binding's new value is the same as the last one it computed (compared with `Object.is`). `data-preview` above is recomputed on every run but not rewritten, so an attribute whose write is expensive to apply — `srcdoc` on an `<iframe>`, which reloads the frame on every assignment — stays untouched until its value actually changes.
+
+If the **computation** itself is what you need to avoid repeating, `untrack` is the wrong tool: put it in a `createMemo` so it only re-runs when its own inputs change.