@gridkitjs/dom 0.0.0-dev-20261108230616 → 0.0.0-dev-20261108231045

package/dist/index.d.ts

@@ -87,7 +87,8 @@ interface AttachedChecklist {
      * How many items the whole list holds, mounted or not. Starts at 0, so a
      * renderer calls this straight after attaching, and again whenever the
      * list changes — a search narrowing it, say. A focused place past the new
-     * end moves back to the last item.
+     * end moves back to the last item, and so does a move still waiting for
+     * an item past it.
      */
     readonly setCount: (count: number) => void;
     /**
@@ -445,8 +446,13 @@ interface GridFocusController {
     /**
      * Connects the tab stop to the rendered rows, which the browser's focus
      * then follows it among. Returns the function that disconnects them.
+     *
+     * `root`, the element holding every row, lets the user take over from a
+     * move still waiting for its row to be drawn: focus leaving `root`, or a
+     * wheel or a press inside it, drops the move, so a row mounting later
+     * neither scrolls back to itself nor pulls focus back into the grid.
      */
-    readonly attach: (rows: GridFocusRows) => () => void;
+    readonly attach: (rows: GridFocusRows, root?: HTMLElement | null) => () => void;
     /**
      * Called by the renderer once it has drawn `drawn` — a value `getFocus`
      * returned — so the browser's focus follows a move to the cell now in the
@@ -498,8 +504,9 @@ interface InfiniteScrollOptions {
     readonly hasMore: boolean;
     /**
      * Called at most once per approach: when the sentinel comes within
-     * `rootMargin` of the root's visible area, and not again until
-     * `isLoadingMore` has gone from `true` back to `false`.
+     * `rootMargin` of the root's visible area. Not again until that load has
+     * finished (`isLoadingMore` back to `false`), `hasMore` has changed, or
+     * the sentinel has left `rootMargin` and come back.
      */
     readonly onLoadMore?: (() => void) | undefined;
     /** Whether a load `onLoadMore` started is still in flight. */
@@ -511,24 +518,24 @@ interface InfiniteScroll {
     /**
      * Takes the current options. Cheap when nothing changed, so a renderer may
      * call it after every render; a new sentinel or `rootMargin` restarts the
-     * observer, and `isLoadingMore` going back to `false` re-checks at once.
+     * observer, and a load finishing or `hasMore` changing re-checks at once.
      */
     readonly update: (options: InfiniteScrollOptions) => void;
-    /** Stops watching for good. */
+    /** Stops watching for good: a later `update` does nothing. */
     readonly detach: () => void;
 }
 /**
  * Turns a sentinel's approach to the bottom of the scrolling `root` into
- * `onLoadMore` calls, no more than one per "the sentinel is near and no load
- * is in flight since the last one finished".
+ * `onLoadMore` calls, no more than one per approach while no load is in
+ * flight.
  *
- * Three facts drive it: whether the sentinel is intersecting (as of the
- * observer's last report), whether `onLoadMore` has fired since the last
- * load finished, and whether a load was in flight at the last update. They
- * outlive the sentinel itself, which a renderer mounts and unmounts as
- * `hasMore` changes, so they live here rather than on any one observer.
+ * Two facts drive it: whether the sentinel is intersecting (as of the
+ * observer's last report), and the `LoadState`. Both outlive the sentinel
+ * itself, which a renderer mounts and unmounts as `hasMore` changes, so they
+ * live here rather than on any one observer.
  *
- * Off means off: with `hasMore` false, or no sentinel, no observer exists.
+ * Off means off: with `hasMore` false, no sentinel, or once detached, no
+ * observer exists.
  */
 declare function attachInfiniteScroll(root: Element, options: InfiniteScrollOptions): InfiniteScroll;
 
@@ -693,9 +700,19 @@ interface OverlayOptions extends OverlayPlacementOptions {
     readonly initialFocus?: OverlayInitialFocus | undefined;
     /**
      * Where focus goes when the overlay detaches. Defaults to the element that
-     * had focus when it attached; `null` leaves focus alone.
+     * had focus when it attached; `null` leaves focus alone, unless
+     * `returnFocusFallback` names somewhere.
      */
     readonly returnFocusTo?: HTMLElement | null | undefined;
+    /**
+     * Where focus goes when there is nothing to return it to as the overlay
+     * detaches: `returnFocusTo` is `null`, or has left the page — the button a
+     * menu opened from, taken away by what the menu ran. Called then, so it
+     * can name what is on the page by that time; returning `null` leaves focus
+     * alone. Like the return itself, it applies only while focus is still in
+     * the panel, in an overlay above it, or nowhere.
+     */
+    readonly returnFocusFallback?: (() => HTMLElement | null) | undefined;
     /**
      * Whether a scroll outside the panel just after input inside it — an
      * `input` or `change` event, in the two animation frames that follow it —
@@ -745,6 +762,8 @@ interface OverlayOptions extends OverlayPlacementOptions {
  * Detaching removes every listener and returns focus, but only when focus is
  * still in the panel, in an overlay above it, or nowhere — a click that
  * dismissed it by landing on another control leaves focus on that control.
+ * Focus goes to `returnFocusFallback` instead when the element it would
+ * return to has left the page.
  * Any overlay still above it is dismissed with `"parent"` and detached first.
  */
 declare function attachOverlay(anchor: OverlayAnchor, panel: HTMLElement, options: OverlayOptions): () => void;
@@ -776,10 +795,15 @@ interface RowVirtualizer {
     /**
      * Scrolls so row `index` is in view. A mounted row is scrolled to directly;
      * one outside the window is jumped to at its estimated offset, then
-     * scrolled to properly once it mounts and can be measured.
+     * scrolled to properly once it mounts and can be measured. A later call
+     * replaces one still waiting for its row, and so does a row count that no
+     * longer holds that row.
      */
     readonly scrollToIndex: (index: number, options?: ScrollIntoViewOptions) => void;
-    /** Stops listening and measuring, for good. */
+    /**
+     * Stops listening, measuring and scrolling, for good: every method does
+     * nothing after it.
+     */
     readonly destroy: () => void;
 }
 /**
@@ -894,7 +918,8 @@ interface PrintDocumentOptions {
  * which a popup blocker would stop.
  *
  * One print at a time: a call while a print is open resolves at once
- * without printing.
+ * without printing. Rejects, with the frame removed, if the frame is taken
+ * out of the page before it loads or the dialog fails to open.
  */
 declare function printDocument(options: PrintDocumentOptions): Promise<void>;
 

package/dist/index.js

@@ -175,8 +175,7 @@ function attachChecklist(list, options) {
       item.focus({ preventScroll: true });
     }
   }
-  const observer = new MutationObserver(() => {
-    setTabStop();
+  function focusPendingIfMounted() {
     const item = pending === null ? null : itemAt(pending);
     if (item === null) {
       return;
@@ -186,6 +185,10 @@ function attachChecklist(list, options) {
     if (focused === null || focused === document.body || list.contains(focused)) {
       item.focus({ preventScroll: true });
     }
+  }
+  const observer = new MutationObserver(() => {
+    setTabStop();
+    focusPendingIfMounted();
   });
   observer.observe(list, {
     childList: true,
@@ -200,7 +203,11 @@ function attachChecklist(list, options) {
     setCount(next) {
       count = next;
       active = Math.max(0, Math.min(active, count - 1));
+      if (pending !== null) {
+        pending = count === 0 ? null : Math.min(pending, count - 1);
+      }
       setTabStop();
+      focusPendingIfMounted();
     },
     focusItem: moveTo,
     detach() {
@@ -658,6 +665,25 @@ function createGridFocus(initialOptions) {
     }
     return snapshot.focus;
   }
+  function dropPendingMove() {
+    pendingMove = null;
+  }
+  function listenForTakeover(root) {
+    function onFocusOut(event) {
+      const to = event.relatedTarget;
+      if (to instanceof Node && !root.contains(to)) {
+        dropPendingMove();
+      }
+    }
+    root.addEventListener("focusout", onFocusOut);
+    root.addEventListener("wheel", dropPendingMove, { passive: true });
+    root.addEventListener("pointerdown", dropPendingMove);
+    return () => {
+      root.removeEventListener("focusout", onFocusOut);
+      root.removeEventListener("wheel", dropPendingMove);
+      root.removeEventListener("pointerdown", dropPendingMove);
+    };
+  }
   function focusCell(rowIndex, columnIndex) {
     const next = clampFocus(
       { rowIndex, columnIndex },
@@ -702,9 +728,11 @@ function createGridFocus(initialOptions) {
       focusCell(next.rowIndex, next.columnIndex);
       return true;
     },
-    attach(next) {
+    attach(next, root) {
       rows = next;
+      const stopListening = root == null ? void 0 : listenForTakeover(root);
       return () => {
+        stopListening?.();
         if (rows === next) {
           rows = null;
         }
@@ -734,20 +762,36 @@ function createGridFocus(initialOptions) {
 }
 
 // src/infiniteScroll.ts
+var IDLE = { kind: "idle" };
+var REQUESTED = { kind: "requested" };
+var LOADING = { kind: "loading" };
+var DETACHED = { kind: "detached" };
+function afterUpdate(state, loading, hasMoreChanged) {
+  if (loading) {
+    return LOADING;
+  }
+  return state.kind === "loading" || hasMoreChanged ? IDLE : state;
+}
 function attachInfiniteScroll(root, options) {
   let latest = options;
   let intersecting = false;
-  let fired = false;
-  let wasLoading = options.isLoadingMore ?? false;
+  let state = options.isLoadingMore ?? false ? LOADING : IDLE;
   let observer = null;
   let observed = null;
   function maybeLoadMore() {
-    if (!intersecting || !latest.hasMore || (latest.isLoadingMore ?? false) || fired) {
+    if (state.kind !== "idle" || !intersecting || !latest.hasMore) {
       return;
     }
-    fired = true;
+    state = REQUESTED;
     latest.onLoadMore?.();
   }
+  function report(isIntersecting) {
+    intersecting = isIntersecting;
+    if (!intersecting && state.kind === "requested") {
+      state = IDLE;
+    }
+    maybeLoadMore();
+  }
   function disconnect() {
     observer?.disconnect();
     observer = null;
@@ -767,11 +811,9 @@ function attachInfiniteScroll(root, options) {
     observer = new IntersectionObserver(
       (entries) => {
         const entry = entries[entries.length - 1];
-        if (entry === void 0) {
-          return;
+        if (entry !== void 0) {
+          report(entry.isIntersecting);
         }
-        intersecting = entry.isIntersecting;
-        maybeLoadMore();
       },
       { root, rootMargin }
     );
@@ -781,16 +823,19 @@ function attachInfiniteScroll(root, options) {
   observe();
   return {
     update(next) {
-      latest = next;
-      const loading = next.isLoadingMore ?? false;
-      if (wasLoading && !loading) {
-        fired = false;
-        maybeLoadMore();
+      if (state.kind === "detached") {
+        return;
       }
-      wasLoading = loading;
+      const hasMoreChanged = next.hasMore !== latest.hasMore;
+      latest = next;
+      state = afterUpdate(state, next.isLoadingMore ?? false, hasMoreChanged);
       observe();
+      maybeLoadMore();
     },
-    detach: disconnect
+    detach() {
+      disconnect();
+      state = DETACHED;
+    }
   };
 }
 
@@ -810,6 +855,8 @@ var MOVES = {
   Home: "first",
   End: "last"
 };
+var IDLE2 = { kind: "idle" };
+var AWAY = { kind: "away" };
 function idOf(item) {
   return item.getAttribute("data-gridkit-menu-item") ?? "";
 }
@@ -827,10 +874,8 @@ function isTypeahead(event) {
   return /^\S$/u.test(event.key) && !event.ctrlKey && !event.metaKey && !event.altKey;
 }
 function attachMenu(panel, options) {
-  let typed = "";
-  let typeaheadTimer;
-  let hovered = null;
-  let hoverTimer;
+  let typeahead = IDLE2;
+  let hover = AWAY;
   function items() {
     return Array.from(panel.querySelectorAll(ITEM2));
   }
@@ -859,21 +904,58 @@ function attachMenu(panel, options) {
       options.onActivate(idOf(item));
     }
   }
-  function typeahead(key, all, from) {
-    typed += key;
-    window.clearTimeout(typeaheadTimer);
-    typeaheadTimer = window.setTimeout(() => {
-      typed = "";
-    }, TYPEAHEAD_TIMEOUT);
+  function endTyping() {
+    if (typeahead.kind === "typing") {
+      window.clearTimeout(typeahead.timer);
+    }
+    typeahead = IDLE2;
+  }
+  function endHover() {
+    if (hover.kind === "resting") {
+      window.clearTimeout(hover.timer);
+    }
+    hover = AWAY;
+  }
+  function type(key, all, from) {
+    const typed = (typeahead.kind === "typing" ? typeahead.typed : "") + key;
+    endTyping();
+    typeahead = {
+      kind: "typing",
+      typed,
+      timer: window.setTimeout(() => {
+        typeahead = IDLE2;
+      }, TYPEAHEAD_TIMEOUT)
+    };
     const match = all[typeaheadIndex(all.map(labelOf), from, typed)];
     if (match !== void 0) {
       focus(match);
     }
   }
+  function rest(item) {
+    hover = {
+      kind: "resting",
+      item,
+      timer: window.setTimeout(() => {
+        hover = { kind: "rested", item };
+        if (opensSubmenu(item) && !isDisabled(item)) {
+          openSubmenu(item, "none");
+        } else {
+          options.onCollapseSubmenu?.();
+        }
+      }, HOVER_DELAY)
+    };
+  }
   function onKeyDown2(event) {
-    if (event.isComposing) {
+    if (event.isComposing || !actOnKey(event)) {
       return;
     }
+    event.preventDefault();
+    endHover();
+    if (!isTypeahead(event)) {
+      endTyping();
+    }
+  }
+  function actOnKey(event) {
     const all = items();
     const item = itemOf(event.target);
     const from = item === null ? -1 : all.indexOf(item);
@@ -900,11 +982,11 @@ function attachMenu(panel, options) {
     } else if (event.key === "Tab") {
       options.onClose("tab");
     } else if (isTypeahead(event)) {
-      typeahead(event.key, all, from);
+      type(event.key, all, from);
     } else {
-      return;
+      return false;
     }
-    event.preventDefault();
+    return true;
   }
   function onFocusIn(event) {
     const item = itemOf(event.target);
@@ -926,24 +1008,16 @@ function attachMenu(panel, options) {
     if (item !== null && document.activeElement !== item) {
       focus(item);
     }
-    if (item === hovered) {
+    if (hover.kind !== "away" && hover.item === item) {
       return;
     }
-    hovered = item;
-    window.clearTimeout(hoverTimer);
+    endHover();
     if (item !== null) {
-      hoverTimer = window.setTimeout(() => {
-        if (opensSubmenu(item) && !isDisabled(item)) {
-          openSubmenu(item, "none");
-        } else {
-          options.onCollapseSubmenu?.();
-        }
-      }, HOVER_DELAY);
+      rest(item);
     }
   }
   function onPointerLeave() {
-    hovered = null;
-    window.clearTimeout(hoverTimer);
+    endHover();
   }
   const focused = itemOf(document.activeElement);
   setTabStop(focused ?? items()[0]);
@@ -961,8 +1035,8 @@ function attachMenu(panel, options) {
       }
     },
     detach() {
-      window.clearTimeout(typeaheadTimer);
-      window.clearTimeout(hoverTimer);
+      endTyping();
+      endHover();
       panel.removeEventListener("keydown", onKeyDown2);
       panel.removeEventListener("focusin", onFocusIn);
       panel.removeEventListener("click", onClick);
@@ -1256,15 +1330,18 @@ function attachOverlay(anchor, panel, options) {
     if (settlingFrame !== null) {
       cancelAnimationFrame(settlingFrame);
     }
-    if (returnFocusTo !== null && focusInside) {
-      returnFocusTo.focus({ preventScroll: true });
+    if (!focusInside) {
+      return;
     }
+    const target = returnFocusTo?.isConnected === true ? returnFocusTo : options.returnFocusFallback?.();
+    target?.focus({ preventScroll: true });
   }
   return detach;
 }
 
 // src/rowVirtualizer.ts
 import { visibleRange } from "@gridkitjs/core";
+var READY = { kind: "ready" };
 function sameRange(a, b) {
   return a.startIndex === b.startIndex && a.endIndex === b.endIndex && a.offsetBefore === b.offsetBefore && a.offsetAfter === b.offsetAfter;
 }
@@ -1274,13 +1351,12 @@ function createRowVirtualizer(scrollElement, options) {
   let scrollTop = scrollElement.scrollTop;
   let viewportHeight = scrollElement.clientHeight;
   let range = null;
-  let destroyed = false;
-  let pendingScroll;
+  let phase = READY;
   const elements = /* @__PURE__ */ new Map();
   const indexByElement = /* @__PURE__ */ new Map();
   const refCallbacks = /* @__PURE__ */ new Map();
   function recompute() {
-    if (destroyed) {
+    if (phase.kind === "destroyed") {
       return;
     }
     const next = visibleRange(
@@ -1331,6 +1407,9 @@ function createRowVirtualizer(scrollElement, options) {
   recompute();
   return {
     setRowCount(count) {
+      if (phase.kind === "awaiting-row" && phase.index >= count) {
+        phase = READY;
+      }
       heights = Array.from({ length: count }, (_, index) => heights[index]);
       recompute();
     },
@@ -1348,15 +1427,15 @@ function createRowVirtualizer(scrollElement, options) {
             indexByElement.delete(previous);
             elements.delete(index);
           }
-          if (element === null || destroyed) {
+          if (element === null || phase.kind === "destroyed") {
             return;
           }
           elements.set(index, element);
           indexByElement.set(element, index);
           rowObserver.observe(element);
-          if (pendingScroll?.index === index) {
-            element.scrollIntoView(pendingScroll.options);
-            pendingScroll = void 0;
+          if (phase.kind === "awaiting-row" && phase.index === index) {
+            element.scrollIntoView(phase.options);
+            phase = READY;
           }
         };
         refCallbacks.set(index, callback);
@@ -1364,21 +1443,21 @@ function createRowVirtualizer(scrollElement, options) {
       return callback;
     },
     scrollToIndex(index, scrollOptions) {
-      if (heights.length === 0) {
+      if (phase.kind === "destroyed" || heights.length === 0) {
         return;
       }
       const clamped = Math.max(0, Math.min(index, heights.length - 1));
       const mounted = elements.get(clamped);
       if (mounted !== void 0) {
+        phase = READY;
         mounted.scrollIntoView(scrollOptions);
         return;
       }
-      pendingScroll = { index: clamped, options: scrollOptions };
+      phase = { kind: "awaiting-row", index: clamped, options: scrollOptions };
       scrollElement.scrollTop = estimateOffsetBefore(clamped);
     },
     destroy() {
-      destroyed = true;
-      pendingScroll = void 0;
+      phase = { kind: "destroyed" };
       scrollElement.removeEventListener("scroll", handleScroll);
       viewportObserver.disconnect();
       rowObserver.disconnect();
@@ -1607,17 +1686,26 @@ function createFrame(bodyHtml) {
 }
 function load(frame) {
   return new Promise((resolve, reject) => {
-    frame.addEventListener(
-      "load",
-      () => {
-        if (frame.contentWindow === null) {
-          reject(new Error("The print frame has no window."));
-        } else {
-          resolve(frame.contentWindow);
-        }
-      },
-      { once: true }
-    );
+    const removal = new MutationObserver(() => {
+      if (!frame.isConnected) {
+        settle();
+        reject(new Error("The print frame was removed before it loaded."));
+      }
+    });
+    function loaded() {
+      settle();
+      if (frame.contentWindow === null) {
+        reject(new Error("The print frame has no window."));
+      } else {
+        resolve(frame.contentWindow);
+      }
+    }
+    function settle() {
+      removal.disconnect();
+      frame.removeEventListener("load", loaded);
+    }
+    frame.addEventListener("load", loaded);
+    removal.observe(document.body, { childList: true });
     document.body.append(frame);
   });
 }
@@ -1628,7 +1716,7 @@ function fill(view, { title, styles }) {
   style.textContent = styles;
   frameDocument.head.append(style);
 }
-function print(view) {
+async function print(view) {
   const listeners = [
     [view, "afterprint"],
     ...RETURN_EVENTS.flatMap((type) => [
@@ -1636,19 +1724,22 @@ function print(view) {
       [window, type]
     ])
   ];
-  return new Promise((resolve) => {
-    function done() {
-      for (const [target, type] of listeners) {
-        target.removeEventListener(type, done, { capture: true });
-      }
-      resolve();
-    }
-    for (const [target, type] of listeners) {
-      target.addEventListener(type, done, { capture: true });
-    }
+  let done = () => void 0;
+  const closed = new Promise((resolve) => {
+    done = resolve;
+  });
+  for (const [target, type] of listeners) {
+    target.addEventListener(type, done, { capture: true });
+  }
+  try {
     view.focus();
     view.print();
-  });
+    await closed;
+  } finally {
+    for (const [target, type] of listeners) {
+      target.removeEventListener(type, done, { capture: true });
+    }
+  }
 }
 async function printDocument(options) {
   if (printing) {