@jsenv/navi 0.29.447 → 0.29.449

package/dist/jsenv_navi.js

@@ -4827,9 +4827,11 @@ const actionRunEffect = (
     return params;
   });
   // Whether the getter asks for a run is read off what it returned, never off
-  // the params of the instance it leads to: an action handed here holding
-  // params of its own (an instance, a binding) keeps them when the getter
-  // returns nothing — and nothing must still run nothing.
+  // the instances it moves between: an action handed here holding params of
+  // its own (an instance, a binding) keeps them when the getter returns
+  // nothing — and nothing must still run nothing; an instance reset under the
+  // effect (a same-resource DELETE) reads as never run — and the next params
+  // the getter asks for must still run.
   let asking = Boolean(actionParamsSignal.peek());
   const actionRunnedByThisEffect = action.bindParams(actionParamsSignal, {
     debounce,
@@ -4856,11 +4858,7 @@ const actionRunEffect = (
         return;
       }
 
-      if (
-        actionTargetPrevious &&
-        !actionTargetPrevious.isPrerun &&
-        actionTarget
-      ) {
+      if (actionTargetPrevious && actionTarget) {
         // params changed
         if (!asking) {
           // falsy params, don't run
@@ -73595,6 +73593,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;
@@ -74568,6 +74567,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,
@@ -76011,14 +76036,16 @@ 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) => {
   useRef(false);
   useLayoutEffect(() => {
     {
@@ -76492,6 +76519,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}"]`)) {
@@ -76607,7 +76660,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;
@@ -76616,11 +76672,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;
@@ -77947,10 +78012,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 }`
@@ -77965,10 +78032,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`…),
@@ -77983,6 +78051,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,
@@ -77993,6 +78062,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,
@@ -78017,6 +78087,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
@@ -78080,24 +78156,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.
@@ -78178,10 +78331,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;
@@ -78715,6 +78871,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;
@@ -78731,8 +78888,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
@@ -78815,6 +78974,68 @@ const useItemStore = ({
   if (staleRanksRef.current === null) {
     staleRanksRef.current = restored ? new Set(pages.byIndex.keys()) : new Set();
   }
+  const takeInPage = ({
+    pageItems,
+    pageStart,
+    pageCount
+  }) => {
+    // An item from before is gone from where it stood when the page puts
+    // it at another rank (it would be drawn twice), or when its rank is
+    // past the end of the collection.
+    const staleRanks = staleRanksRef.current;
+    const pageEnd = pageStart + pageItems.length;
+    let dropped = false;
+    if (staleRanks.size > 0) {
+      const pageIds = new Set();
+      for (const pageItem of pageItems) {
+        if (pageItem && pageItem.id !== undefined) {
+          pageIds.add(pageItem.id);
+        }
+      }
+      for (const rank of staleRanks) {
+        if (rank >= pageStart && rank < pageEnd) {
+          continue;
+        }
+        const staleItem = pages.byIndex.get(rank);
+        if (rank >= pageCount || staleItem && pageIds.has(staleItem.id)) {
+          staleRanks.delete(rank);
+          pages.byIndex.delete(rank);
+          dropped = true;
+        }
+      }
+    }
+    let i = 0;
+    while (i < pageItems.length) {
+      pages.byIndex.set(pageStart + i, pageItems[i]);
+      staleRanks.delete(pageStart + i);
+      i++;
+    }
+    pages.count = pageCount;
+    // Which rank holds which id, kept by the source so a list drawing
+    // this collection again finds it drawn (see readComposition above).
+    if (itemsAction.writeComposition) {
+      itemsAction.writeComposition({
+        byIndex: pages.byIndex,
+        count: pageCount,
+        replace: dropped
+      });
+    }
+  };
+  // The pages answered since the last render, taken in by the render and not
+  // as they land: what the list reads of the run — how many items it stands for
+  // (see listItems.take), where an item sits (its locator) — then moves in one
+  // step. Taken in on landing, an item could be located past the count the list
+  // still holds, and a list held on it would aim its window there at every
+  // render, framed back each time.
+  const pagesLandedRef = useRef([]);
+  const pagesLanded = pagesLandedRef.current;
+  const pagesTakenIn = pagesLanded.length > 0;
+  if (pagesTakenIn) {
+    pagesLandedRef.current = [];
+    for (const page of pagesLanded) {
+      takeInPage(page);
+    }
+  }
   const [refreshing, setRefreshing] = useState(false);
   // A source that says when what it reads has moved (a resource range reader
   // does: see rerunOn.GET_RANGE) is heard here — a write deciding who belongs
@@ -78845,28 +79066,55 @@ const useItemStore = ({
   const [failure, setFailure] = useState(null);
   const listItems = useContext(ListItemsContext);
   // The items are there, which is what the list waits for to place itself on the
-  // item it is held at (see placeWhereHeld). Said from an effect: a signal read
-  // during this very render must not be written during it.
+  // item it is held at (see placeWhereHeld). Said from an effect, once the run
+  // has drawn them: a signal read during this very render must not be written
+  // during it.
   useLayoutEffect(() => {
-    if (!inMemory || itemsHeldRef.current) {
+    if (inMemory) {
+      if (itemsHeldRef.current) {
+        return;
+      }
+      itemsHeldRef.current = true;
+    } else if (!pagesTakenIn) {
       return;
     }
-    itemsHeldRef.current = true;
     listItems.pagesSignal.value = listItems.pagesSignal.peek() + 1;
   });
   // Before the first answer a run does not know how many items it stands for.
   // 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
@@ -78901,8 +79149,11 @@ const useItemStore = ({
   };
   // A list taken off the screen while it was asking leaves nothing ringing
   // behind it: whoever is drawing "looking for items" has to stop.
+  const mountedRef = useRef(false);
   useLayoutEffect(() => {
+    mountedRef.current = true;
     return () => {
+      mountedRef.current = false;
       if (requestStateRef.current.busy && onRequestStateChangeRef.current) {
         onRequestStateChangeRef.current({
           busy: false,
@@ -78915,7 +79166,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
@@ -79164,51 +79415,21 @@ const useItemStore = ({
           const pageItems = Array.isArray(page) ? page : page.items;
           const pageStart = Array.isArray(page) ? 0 : page.start ?? 0;
           const pageCount = Array.isArray(page) ? pageItems.length : page.count ?? pageStart + pageItems.length;
+          const pageLanded = {
+            pageItems,
+            pageStart,
+            pageCount
+          };
+          if (!mountedRef.current) {
+            // No render is coming to take it in, and the source still keeps
+            // what came back for the next list drawing this collection.
+            takeInPage(pageLanded);
+            return;
+          }
           // Before the items land: what is on screen has to stay where it is,
           // and the DOM still shows the state to hold onto.
           listItems.captureAnchor();
-          // An item from before is gone from where it stood when the page puts
-          // it at another rank (it would be drawn twice), or when its rank is
-          // past the end of the collection.
-          const staleRanksNow = staleRanksRef.current;
-          const pageEnd = pageStart + pageItems.length;
-          let dropped = false;
-          if (staleRanksNow.size > 0) {
-            const pageIds = new Set();
-            for (const pageItem of pageItems) {
-              if (pageItem && pageItem.id !== undefined) {
-                pageIds.add(pageItem.id);
-              }
-            }
-            for (const rank of staleRanksNow) {
-              if (rank >= pageStart && rank < pageEnd) {
-                continue;
-              }
-              const staleItem = pages.byIndex.get(rank);
-              if (rank >= pageCount || staleItem && pageIds.has(staleItem.id)) {
-                staleRanksNow.delete(rank);
-                pages.byIndex.delete(rank);
-                dropped = true;
-              }
-            }
-          }
-          let i = 0;
-          while (i < pageItems.length) {
-            pages.byIndex.set(pageStart + i, pageItems[i]);
-            staleRanksNow.delete(pageStart + i);
-            i++;
-          }
-          pages.count = pageCount;
-          // Which rank holds which id, kept by the source so a list drawing
-          // this collection again finds it drawn (see readComposition above).
-          if (itemsAction.writeComposition) {
-            itemsAction.writeComposition({
-              byIndex: pages.byIndex,
-              count: pageCount,
-              replace: dropped
-            });
-          }
-          listItems.pagesSignal.value = listItems.pagesSignal.peek() + 1;
+          pagesLandedRef.current.push(pageLanded);
           setPageVersion(version => version + 1);
         };
         const failed = error => {
@@ -79572,8 +79793,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