@jsenv/navi 0.29.447 → 0.29.448

package/dist/dev/jsenv_navi.js

@@ -75001,6 +75001,7 @@ const css$x = /* css */`@property --list-group-label-height {
 }
 
 .navi_list {
+  --x-list-item-between: 0px;
   box-sizing: border-box;
   outline: none;
   margin: 0;
@@ -75937,7 +75938,7 @@ const useListScrollSync = ({
     setScrollerElResolved(current => current === scrollerElNow ? current : scrollerElNow);
   };
   useLayoutEffect(resolveScroller);
-  useStickyScrollportWarning(ref, scroller);
+  useStickyScrollportWarning(ref, scroller, getScroller, horizontal);
   useDuplicateHeaderWarning(ref);
   useStuckWindowWarning({
     ref,
@@ -76013,6 +76014,32 @@ const useListScrollSync = ({
     }
   });
 
+  // What stands between two items along the axis — the gap, a separator and
+  // the gaps around it — which an item on its way takes out of the room it is
+  // given (see getSkeletonItem): virtualItemSize is an item's room, from the
+  // end of the item before to its own end, and a skeleton whose box took all
+  // of it would be taller than the item replacing it, moving everything below
+  // by the difference. Read before the anchoring of this commit runs, and
+  // written to the list's own box so the skeletons follow without rendering.
+  // Items side by side in a grid share a line: none stands between them.
+  useLayoutEffect(() => {
+    if (columns || !ref.current || !listItems.hasRuns()) {
+      return;
+    }
+    const listEl = getListEl();
+    if (!listEl) {
+      return;
+    }
+    const spaceBetween = readSpaceBetweenItems(listEl, horizontal);
+    if (spaceBetween === null) {
+      return;
+    }
+    const value = `${spaceBetween}px`;
+    if (listEl.style.getPropertyValue("--x-list-item-between") !== value) {
+      listEl.style.setProperty("--x-list-item-between", value);
+    }
+  });
+
   // What the window holds goes through three stages (see settleWindow):
   // - "first": the first commit, a count of items since nothing is laid out
   //   yet to measure a size with — `initial` or the budget when they are one,
@@ -77502,25 +77529,41 @@ const canScrollerScroll = (scrollerEl, axis) => {
   return scrollSize - clientSize > 1;
 };
 // What a sticky part of the list sticks to is the nearest scroll container in
-// the DOM; `scroller` has no say in it. A list told the page scrolls it can
-// therefore have its group labels and its header stuck to a wrapper that never
-// scrolls — and pushed down by that wrapper's scroll-padding on top of it. The
-// usual culprit is an app wrapper carrying `overflow-x: auto` to keep the
-// document from overflowing horizontally on mobile; `overflow-x: clip` keeps
-// that guarantee without making a scroll container.
+// the DOM; `scroller` has no say in it. A list scrolled by a box around it can
+// therefore have its group labels and its header stuck to a wrapper between
+// the two that never scrolls along that axis — and pushed down by that
+// wrapper's scroll-padding on top of it. The usual culprit is a wrapper
+// carrying `overflow-x: auto`: to keep the document from overflowing
+// horizontally on mobile, where `overflow-x: clip` keeps that guarantee without
+// making a scroll container, or to let a wide table scroll sideways, where the
+// header cannot stick to both boxes.
 const STICKY_LIST_PART_SELECTOR = `.navi_list_item_header, .navi_list_item_footer, .navi_list_item_group_label`;
-const useStickyScrollportWarning = (ref, scroller) => {
+const useStickyScrollportWarning = (ref, scroller, getScroller, horizontal) => {
   const doneRef = useRef(false);
   useLayoutEffect(() => {
-    if (doneRef.current || scroller !== "document") {
+    if (doneRef.current) {
+      return;
+    }
+    const scrollerNamed = scroller && typeof scroller === "object";
+    if (scroller !== "document" && scroller !== "parent" && !scrollerNamed) {
+      // The list scrolls itself: its sticky parts stick to its own box.
+      return;
+    }
+    if (scrollerNamed && !(scroller.nodeType === 1 || scroller.current)) {
+      // The ref is not set yet: the box that scrolls is not known.
       return;
     }
     const listContainerEl = ref.current;
     if (!listContainerEl) {
       return;
     }
+    const scrollerEl = getScroller();
+    if (scroller === "parent" && scrollerEl !== document.scrollingElement && !canScroll(scrollerEl, horizontal ? "x" : "y")) {
+      // Measured: until the box around scrolls, which one it is is not known.
+      return;
+    }
     const scrollportEl = findScrollportEl(listContainerEl);
-    if (!scrollportEl) {
+    if ((scrollportEl || document.scrollingElement) === scrollerEl) {
       doneRef.current = true;
       return;
     }
@@ -77530,8 +77573,10 @@ const useStickyScrollportWarning = (ref, scroller) => {
       return;
     }
     doneRef.current = true;
-    console.warn(`<List scroller="document"> is inside ${getElementSignature(scrollportEl)}, a scroll container: its sticky group labels and header stick to that box instead of to the page. Give that box "overflow: clip" (it clips without creating a scroll container), or tell the list about it with scroller={element}.`, {
+    const scrolledBy = scrollerEl === document.scrollingElement ? "the page" : getElementSignature(scrollerEl);
+    console.warn(`<List> is scrolled by ${scrolledBy}, but it is inside ${getElementSignature(scrollportEl)}, a scroll container closer to it: its sticky header and group labels stick to that box instead. A box there to clip: give it "overflow: clip", which clips without creating a scroll container. A box that scrolls the list: name it, scroller={element}. A box there to scroll a wide list sideways: the sticky parts cannot stick to both boxes — let ${scrolledBy} scroll sideways too, or keep the header at the top of the list.`, {
       list: listContainerEl,
+      scroller: scrollerEl,
       scrollport: scrollportEl,
       sticky: stickyEl
     });
@@ -78045,6 +78090,32 @@ const findItemsFrom = (listEl, from, horizontal) => {
 // items (a card holding a list of its own): both carry the same attributes.
 // Groups nest the items in a list of their own class, not in another list.
 const isOwnItem = (itemEl, listEl) => itemEl.closest(".navi_list") === listEl;
+// From where an item ends to where the item after it starts, read on the first
+// two that follow each other in the same container (a group's label stands
+// between two items of different groups). Null when no two items do.
+const readSpaceBetweenItems = (listEl, horizontal) => {
+  let previous = null;
+  for (const itemEl of listEl.querySelectorAll(`[${LIST_ITEM_INDEX_ATTRIBUTE}]`)) {
+    if (!isOwnItem(itemEl, listEl)) {
+      continue;
+    }
+    const rect = itemEl.getBoundingClientRect();
+    if (rect.width === 0 && rect.height === 0) {
+      previous = null;
+      continue;
+    }
+    const index = Number(itemEl.getAttribute(LIST_ITEM_INDEX_ATTRIBUTE));
+    if (previous && previous.index === index - 1 && previous.containerEl === itemEl.parentElement) {
+      return (horizontal ? rect.left : rect.top) - previous.to;
+    }
+    previous = {
+      index,
+      containerEl: itemEl.parentElement,
+      to: horizontal ? rect.right : rect.bottom
+    };
+  }
+  return null;
+};
 // The item drawn at an index of the list, a stand-in or a real one.
 const findItemElementAt = (listEl, index) => {
   for (const itemEl of listEl.querySelectorAll(`[${LIST_ITEM_INDEX_ATTRIBUTE}="${index}"]`)) {
@@ -78160,7 +78231,10 @@ const readItemRooms = (listEl, horizontal, onRoom) => {
 // Where what stands before an item in the list ends: the element before the
 // item, or before its group when it is the first of it — or the start of the
 // list's content when nothing does. Null when the element before is not laid
-// out.
+// out. It is where that element ends in the flow: where the item (or its
+// group) starts, less the gap and the margins between the two. Its own box is
+// where it is painted, which a sticky header stuck to the top of the screen
+// puts thousands of pixels away from its place in the list.
 const readEndBefore = (itemEl, listEl, horizontal) => {
   let slotEl = itemEl;
   const groupListEl = itemEl.parentElement;
@@ -78169,11 +78243,20 @@ const readEndBefore = (itemEl, listEl, horizontal) => {
   }
   const beforeEl = slotEl.previousElementSibling;
   if (beforeEl) {
-    const rect = beforeEl.getBoundingClientRect();
-    if (rect.width === 0 && rect.height === 0) {
+    const beforeRect = beforeEl.getBoundingClientRect();
+    if (beforeRect.width === 0 && beforeRect.height === 0) {
       return null;
     }
-    return horizontal ? rect.right : rect.bottom;
+    const slotRect = slotEl.getBoundingClientRect();
+    const containerStyle = window.getComputedStyle(slotEl.parentElement);
+    const slotStyle = window.getComputedStyle(slotEl);
+    const beforeStyle = window.getComputedStyle(beforeEl);
+    // A gap the browser computes as "normal" is none in a flex or grid list.
+    const lengthOf = value => parseFloat(value) || 0;
+    if (horizontal) {
+      return slotRect.left - lengthOf(containerStyle.columnGap) - lengthOf(slotStyle.marginLeft) - lengthOf(beforeStyle.marginRight);
+    }
+    return slotRect.top - lengthOf(containerStyle.rowGap) - lengthOf(slotStyle.marginTop) - lengthOf(beforeStyle.marginBottom);
   }
   if (slotEl.parentElement !== listEl) {
     return null;
@@ -79503,10 +79586,12 @@ const VISIBILITY_HIDDEN_STYLE = {
  * A collection read a slice at a time comes from `itemsAction(range)`: the run
  * asks for what it is about to draw and keeps what it gets. The range says the
  * same thing three ways, so a source can read it however it paginates —
- * `{ start, end }` (places in the collection, a negative `start` counting back
- * from the end like `Range: items=-25`, which is what a list opening on its
- * last items asks for before it knows how many there are), `limit` (how many
- * items), and
+ * `{ start, end }` (places in the collection, `end` included as in
+ * `Range: items=0-99`; a negative `start` counting back from the end like
+ * `Range: items=-25`, which is what a list opening on its last items asks for
+ * before it knows how many there are), `limit` (how many items:
+ * `end - start + 1` — an API whose end is excluded is called with
+ * `start + limit`), and
  * `before`/`after`/`around` (the id of an item to count from, for a source
  * paginating by cursor). Answer with the items (an array — that is all of
  * them), or with a range the way a Content-Range does: `{ items, start, count }`
@@ -79521,10 +79606,11 @@ const VISIBILITY_HIDDEN_STYLE = {
  * (see docs/resource.md).
  *
  * A collection that changes as a whole (a search reordering it) is a different
- * collection: with `items`, another array is another collection and the run
- * draws it from its first item; with `itemsAction`, give the run a `key` that
- * changes with it, the way one does for anything else that is not the same
- * thing anymore.
+ * collection, and the run draws it from its first item: with `items`, another
+ * array is another collection; with `itemsAction`, another reader is — a
+ * reader bound to other params (`bindParams({ q })` with another `q`). A param
+ * held in a signal changes what the reader reads without changing the reader:
+ * give the run a `key` that follows it.
  *
  * An item says what it is where it is drawn: `renderItem` returns a
  * `<List.Item>` carrying its own props (`selectable`, `value`, `selected`…),
@@ -79539,6 +79625,7 @@ const VISIBILITY_HIDDEN_STYLE = {
  *   findText?: (item: any, index: number) => string,
  *   items?: any[],
  *   itemsAction?: (range: {start: number, end: number, limit: number, before?: string, after?: string, around?: string, count?: number, signal: AbortSignal}) => any,
+ *   debounce?: number,
  *   count?: number,
  *   groupBy?: (item: any, index: number) => any,
  *   renderGroupLabel?: (item: any, index: number) => import("ignore:preact").ComponentChildren,
@@ -79549,6 +79636,7 @@ const VISIBILITY_HIDDEN_STYLE = {
  *   itemSize?: (index: number) => number,
  *   renderError?: (failure: {error: any, retry: () => void, start: number, end: number}) => import("ignore:preact").ComponentChildren,
  *   onRequestStateChange?: (state: {busy: boolean, refreshing: boolean, range: {start: number, end: number}|null}) => void,
+ *   onCountChange?: (count: number|undefined) => void,
  * }>}
  * @param {(item: any, index: number, state: {refreshing: boolean}) => any} props.renderItem
  *   What is drawn for one item, given its data and where it sits — its place in the list,
@@ -79573,6 +79661,12 @@ const VISIBILITY_HIDDEN_STYLE = {
  * @param {(range: object) => any} [props.itemsAction]
  *   Where the items come from when the collection is read a slice at a time:
  *   a resource's range reader (`RESOURCE.GET_RANGE.bindParams(...)`).
+ * @param {number} [props.debounce]
+ *   Milliseconds the reader must hold still before the run draws the
+ *   collection it reads: params following a field as the user types
+ *   (`bindParams({ q })`) ask once typing stops, not once per key. Meanwhile
+ *   the run keeps drawing the collection from before, `refreshing`. The
+ *   first collection is drawn at once.
  * @param {(item: any, index: number) => any} [props.groupBy]
  *   What tells items that belong together apart from the others — the day of a
  *   message, the month of a game. Consecutive items sharing it are wrapped in a
@@ -79636,24 +79730,101 @@ const VISIBILITY_HIDDEN_STYLE = {
  *   collection's own ranks as `itemsAction` sees them, `null` once nothing is.
  *   A range called off and asked again right away stays one `busy`, and a list
  *   unmounted while asking says `busy: false` on its way out.
+ * @param {(count: number|undefined) => void} [props.onCountChange]
+ *   Called with how many items the collection holds when that changes — for
+ *   the screen around the list to say it ("5 of 83 books"): the `count` the
+ *   source answers with each slice, or the one given to the run.
+ *   `undefined` until it is known; a run drawing another collection says it
+ *   again, so the number always belongs to the collection on screen.
  */
 const ListItems = ({
+  itemsAction,
+  debounce,
+  ...props
+}) => {
+  // Read so that this component renders in the pass of the List moving its
+  // window, and the run with it: the List frames its window on the items its
+  // runs drew in that same commit (see settleWindow). Skipped as an unchanged
+  // child, it would leave the run to a render of its own, after that commit.
+  useContext(RenderWindowContext);
+  const {
+    reader,
+    settling
+  } = useSettledReader(itemsAction, debounce);
+  return jsx(ListItemsRun
+  // Another reader is another collection — bindParams gives back the
+  // reader it made for equal params — and the run holds the ranks, the
+  // count and the asks of the one it draws.
+  , {
+    itemsAction: reader,
+    settling: settling,
+    ...props
+  }, reader && reader.isRangeReader ? readerKeyOf(reader) : undefined);
+};
+const ListItemsRun = ({
   items,
   itemsAction,
+  settling,
   count,
   memoryBudget,
   onRequestStateChange,
+  onCountChange,
   ...runProps
 }) => {
   const store = useItemStore({
     items,
     count,
     itemsAction,
+    settling,
     memoryBudget,
-    onRequestStateChange
+    onRequestStateChange,
+    onCountChange
   });
   return useRunItems(store, runProps);
 };
+const readerKeyByReader = new WeakMap();
+let readerKeyPrevious = 0;
+const readerKeyOf = reader => {
+  let key = readerKeyByReader.get(reader);
+  if (key === undefined) {
+    readerKeyPrevious++;
+    key = readerKeyPrevious;
+    readerKeyByReader.set(reader, key);
+  }
+  return key;
+};
+// The reader the run draws: the one it is given, or under `debounce` the one
+// it was drawing until the one given has held still that long. Only between
+// two range readers — the first collection is drawn at once, and a collection
+// held in memory costs no request to follow.
+const useSettledReader = (itemsAction, debounce) => {
+  const settledRef = useRef(itemsAction);
+  const [, setSettleCount] = useState(0);
+  const settled = settledRef.current;
+  const waits = Boolean(debounce) && itemsAction !== settled && Boolean(itemsAction && itemsAction.isRangeReader) && Boolean(settled && settled.isRangeReader);
+  if (!waits) {
+    settledRef.current = itemsAction;
+  }
+  useLayoutEffect(() => {
+    if (!waits) {
+      return undefined;
+    }
+    const timeout = setTimeout(() => {
+      settledRef.current = itemsAction;
+      setSettleCount(settleCount => settleCount + 1);
+    }, debounce);
+    return () => {
+      clearTimeout(timeout);
+    };
+  }, [waits, itemsAction, debounce]);
+  return waits ? {
+    reader: settled,
+    settling: true
+  } : {
+    reader: itemsAction,
+    settling: false
+  };
+};
 
 // The items a `loading` list is told to expect (loadingSkeletonCount): a run
 // holding none of them, and asking for none — they arrive through the app.
@@ -79734,10 +79905,13 @@ const useRunItems = (store, {
     skeletonItem = {};
     const virtualItemSize = listItems.virtualItemSizeSignal.value;
     if (virtualItemSize) {
+      // The room is the item's and what stands before it (see
+      // readSpaceBetweenItems): the box takes what is left of it.
+      const minSize = `calc(${virtualItemSize}px - var(--x-list-item-between, 0px))`;
       if (listItems.horizontal) {
-        skeletonItem.itemMinWidth = `${virtualItemSize}px`;
+        skeletonItem.itemMinWidth = minSize;
       } else {
-        skeletonItem.itemMinHeight = `${virtualItemSize}px`;
+        skeletonItem.itemMinHeight = minSize;
       }
     }
     return skeletonItem;
@@ -80271,6 +80445,7 @@ const ListItemsFailure = ({
 // hits the network again.
 const ITEM_STORE_MAX_DEFAULT = 1000;
 const ITEM_STORE_KEEP_AROUND = 250;
+const COUNT_NOT_SAID = {};
 const rangeIsSame = (a, b) => {
   if (!a || !b) {
     return a === b;
@@ -80287,8 +80462,10 @@ const useItemStore = ({
   items,
   count,
   itemsAction,
+  settling,
   memoryBudget,
-  onRequestStateChange
+  onRequestStateChange,
+  onCountChange
 }) => {
   // A collection given whole (`items`) is held from the first render: nothing
   // to ask for, nothing to keep across mounts, nothing to invalidate. The rest
@@ -80423,15 +80600,37 @@ const useItemStore = ({
   // It stands for a page of them: a list that is about to be filled looks
   // like items on their way, not like an empty list.
   const itemCount = pages.count ?? count ?? listItems.pageSize;
+  // The items drawn are from before while they are read again, and while the
+  // collection that replaces them waits for its params to hold still (see
+  // useSettledReader).
+  const refreshingShown = refreshing || Boolean(settling);
   useLayoutEffect(() => {
-    if (!refreshing) {
+    if (!refreshingShown) {
       return null;
     }
     listItems.refreshingSignal.value = listItems.refreshingSignal.peek() + 1;
     return () => {
       listItems.refreshingSignal.value = listItems.refreshingSignal.peek() - 1;
     };
-  }, [refreshing]);
+  }, [refreshingShown]);
+
+  // How many items the collection holds, for the screen around the list to
+  // say: the count the source answered or the caller gave, never the page the
+  // run stands for before it knows. Said by each run on its first commit, so a
+  // run drawing another collection takes back what the one before said.
+  const countKnown = pages.count ?? count;
+  const onCountChangeRef = useRef(onCountChange);
+  onCountChangeRef.current = onCountChange;
+  const countSaidRef = useRef(COUNT_NOT_SAID);
+  useLayoutEffect(() => {
+    if (countSaidRef.current === countKnown) {
+      return;
+    }
+    countSaidRef.current = countKnown;
+    if (onCountChangeRef.current) {
+      onCountChangeRef.current(countKnown);
+    }
+  });
 
   // What the run is doing, for the screen around the list to draw: the list has
   // its own skeletons, what is around it has to be told. Read from the request
@@ -80480,7 +80679,7 @@ const useItemStore = ({
   const store = {
     itemCount,
     failure,
-    refreshing,
+    refreshing: refreshingShown,
     // JS memory is cheap next to the DOM, but a long enough scroll accumulates
     // everything it ever went through. Items far from what is on screen are
     // dropped and simply asked for again if the user goes back — the same
@@ -81137,8 +81336,9 @@ const ListResolved = /*#__PURE__*/createComponentResolver([ListFirstResolver, Li
  * @param {number} [props.virtualItemSize]
  *   The room an item never drawn is held at, in px along the scroll axis: what
  *   the fillers hold for it outside the render window, what a scroll position
- *   inside them is read with, and the least an item on its way takes (see
- *   `renderSkeleton`). An item the list has drawn is held at the room it took
+ *   inside them is read with, and the least room an item on its way takes
+ *   (see `renderSkeleton`) — a room counts what stands before the item, a
+ *   gap or a separator, so the item's own box takes the rest of it. An item the list has drawn is held at the room it took
  *   then, and an item whose run says its room (`<List.Items itemSize>`) at
  *   that room. Left out, it is the average of the items measured so far — once when
  *   the list mounts, again when a popup around it opens, and after each commit