kerfjs 4.2.0 → 4.3.0-beta.1

package/CHANGELOG.md

@@ -6,6 +6,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+- **`kerfjs/overlay` gains opt-in native top-layer backing (`native: true`).** Every overlay surface (`overlay`, `confirm`, `prompt`, `form`, `choice`, `popover`, `tooltip`) now takes `native?: boolean` (default `false`). When `true` and the engine supports it, a **modal** surface (`trap: true`) is hosted in a `<dialog>` opened with `.showModal()` — real document inerting (pointer + focus + AT) and guaranteed stacking above any `z-index` — and a **non-modal** surface (`trap: false`) uses the **Popover API** (`[popover]` + `showPopover()`). Feature-detected (`HTMLDialogElement.prototype.showModal`, `HTMLElement.prototype.showPopover`), falling back to today's plain `<div>` where unsupported, so `native: true` is always safe to pass. The `render` slot + promise API are unchanged — kerf just hosts your markup in a `<dialog>` / `[popover]`. **Opt-in on purpose:** the native elements carry UA default styles (a `::backdrop`, centering, border, padding) that kerf does **not** reset (a reset would violate the zero-CSS contract) — style the element and its `::backdrop` via `className` (`.kerf-overlay::backdrop { … }`, the stable contract); and `container` becomes a visual no-op in native mode (the top layer ignores DOM position). See [`docs/19-native-overlay-backing.md`](docs/19-native-overlay-backing.md).
+- **`bindList` virtualization gains a `content-visibility` mode.** `virtualize: { rowHeight, mode: 'content-visibility' }` is a second virtualization strategy alongside the default `mode: 'window'` (today's JS windowing). It keeps **every** row in the DOM and sets `content-visibility: auto` + `contain-intrinsic-size: 0 <rowHeight>px` on each row, so a supporting engine (Chromium, Safari 18) skips the *layout/paint* of off-screen rows while **all rows stay findable** — find-in-page (Cmd/Ctrl+F), the accessibility tree, and anchor links / `scrollIntoView` all work on any row (the exact guarantee `mode: 'window'` can't give, since it removes off-window rows from the DOM). The `mode` choice is the app's and it's about list size: pick `'content-visibility'` for medium lists where findability beats the node ceiling, keep `'window'` for very large (100k-row) lists. In this mode `rowHeight` is only the `contain-intrinsic-size` placeholder (no windowing math), `setHeight` / `observeRowHeights` are no-ops (the browser owns measurement), `minRows` is ignored (all rows already render), and no scroll listener / `ResizeObserver` is installed — while `handle.container` / `containerClass` / `containerId` still work. There is deliberately **no feature detection**: on an engine without `content-visibility` the CSS is inert, so all rows still render (correct, still findable) — only the off-screen-skip optimization is absent. See [`docs/17-list-virtualization.md`](docs/17-list-virtualization.md) §17.11.
+- **Docs: `bindList` virtualization findability/a11y tradeoff is now a first-class caveat.** Off-window rows are removed from the DOM (not just hidden), so with `virtualize` set, find-in-page (Cmd/Ctrl+F), screen readers / the accessibility tree, and anchor links / `scrollIntoView` reach only the visible window. New `docs/17-list-virtualization.md` §17.10 spells out the consequences and the guidance (don't virtualize, or use `minRows` above the list length, when full findability matters more than the DOM node ceiling), and the `bindList` JSDoc + `docs/8-api-reference.md` §8.11 carry the same note. Behavior unchanged — documentation only.
+- **State-preserving row moves via `moveBefore()` (transparent optimization).** When a keyed list reorders — `each()` (snapshot and granular paths), `bindList`, and `morph()`'s keyed / positional / list-marker moves — kerf now relocates an already-connected row with `Node.prototype.moveBefore()` where the engine supports it (Chromium 133+, spreading to other engines), falling back to `insertBefore()` everywhere else. `moveBefore()` is an atomic move: the node is never disconnected, so a moved row keeps its focus, text selection, `<iframe>` document state, playing media, running CSS transitions/animations, and open `popover`/`dialog` state across the reorder — richer state than the existing focus snapshot in the reconciler could ever restore, and it needs no snapshot at all where it runs. No API change and no behavior change on engines without `moveBefore()`; the focus-preservation snapshot stays in place for them. Fresh (not-yet-connected) rows still use `insertBefore()` — only genuine moves of connected rows take the new path. See [`docs/18-state-preserving-moves.md`](docs/18-state-preserving-moves.md).
+
 ## [4.2.0] - 2026-08-20
 
 

package/dist/{chunk-LKWAKC2X.js → chunk-SRWQKB33.js}

@@ -240,6 +240,16 @@ function eachSnapshotById(items, render, cacheKey, id, source) {
   return listSafeHtml(id, segItems, source);
 }
 
+// src/utils/moveNode.ts
+function moveNode(parent, node, ref) {
+  const move = parent.moveBefore;
+  if (move !== void 0 && node.isConnected) {
+    move.call(parent, node, ref);
+  } else {
+    parent.insertBefore(node, ref);
+  }
+}
+
 // src/list-reconcile-focus.ts
 function captureFocus(liveParent) {
   const active = document.activeElement;
@@ -355,7 +365,7 @@ function morphChildren(fromParent, toParent, ownedItems) {
       matched = keyed.get(toKey);
       keyed.delete(toKey);
       if (matched !== fromChild) {
-        fromParent.insertBefore(matched, fromChild);
+        moveNode(fromParent, matched, fromChild);
       } else {
         fromChild = skipOwned(fromChild.nextSibling, ownedItems);
       }
@@ -382,7 +392,7 @@ function morphChildren(fromParent, toParent, ownedItems) {
         if (el.tagName !== toTag || getNodeKey(el) !== void 0) continue;
         if (protectionTag(el) !== protectionTag(toChild)) continue;
         matched = el;
-        fromParent.insertBefore(el, fromChild);
+        moveNode(fromParent, el, fromChild);
         break;
       }
     }
@@ -396,7 +406,7 @@ function morphChildren(fromParent, toParent, ownedItems) {
           run.push(r);
         }
         const focusSnap = captureFocus(fromParent);
-        for (const node of run) fromParent.insertBefore(node, fromChild);
+        for (const node of run) moveNode(fromParent, node, fromChild);
         if (focusSnap !== null) restoreFocus(focusSnap);
         matched = scan;
         break;
@@ -755,7 +765,7 @@ function reconcileGranular(binding, patches) {
       let anchorIdx = patch.to;
       if (patch.from < patch.to) anchorIdx += 1;
       const anchor = anchorIdx < items.length ? items[anchorIdx].node : endAnchor(binding);
-      liveParent.insertBefore(moved.node, anchor);
+      moveNode(liveParent, moved.node, anchor);
       items.splice(patch.from, 1);
       items.splice(patch.to, 0, moved);
       i += 1;
@@ -1053,7 +1063,7 @@ function applyMoves(liveParent, newRecord, prevIdx, stable, tailAnchor) {
   for (let i = newRecord.length - 1; i >= 0; i--) {
     const node = newRecord[i].node;
     if (prevIdx[i] === -1 || !stable.has(i)) {
-      liveParent.insertBefore(node, nextSibling);
+      moveNode(liveParent, node, nextSibling);
     }
     nextSibling = node;
   }
@@ -1390,6 +1400,6 @@ function collectComments(node, out) {
   }
 }
 
-export { each, morph, mount };
-//# sourceMappingURL=chunk-LKWAKC2X.js.map
-//# sourceMappingURL=chunk-LKWAKC2X.js.map
+export { each, morph, mount, moveNode };
+//# sourceMappingURL=chunk-SRWQKB33.js.map
+//# sourceMappingURL=chunk-SRWQKB33.js.map