@jsenv/navi 0.29.442 → 0.29.444

package/dist/dev/jsenv_navi.js

@@ -6502,6 +6502,10 @@ const CONTROL_PROP_SET = new Set([
   "charGuard",
   "maxLengthGuard",
 
+  // A checkbox that is a yes/no: `true` checked, `false` unchecked, instead of
+  // HTML's value-or-nothing (see resolveEmptyUIState).
+  "boolean",
+
   // This control answers for itself: it registers into no group, no form and no
   // picker around it (see useUIStateController). It belongs here rather than
   // being deleted off `props` where it is read: props is the vnode's own object
@@ -43198,6 +43202,14 @@ const useUIStateController = (
             return ownUIState || parentUIState;
           })
         : ownUIStateSignal;
+      // What the control is worth, which its action is bound to: what it
+      // holds, or its own empty when it holds nothing. Apart from
+      // uiStateSignal because unchecked is `undefined` there (the DOM reads any
+      // other value as checked), while a yes/no unchecked is worth `false`.
+      const emptyUIStateSignal = signal(emptyUIState);
+      const valueSignal = computed(() =>
+        uiStateOrEmpty(uiStateSignal.value, emptyUIStateSignal.value),
+      );
 
       // The two-way half of a bound `signal` prop: setting it re-renders and
       // re-syncs via state_prop_change, but with the same value → guarded as a
@@ -43246,6 +43258,7 @@ const useUIStateController = (
         // travel command ended up carrying a picker's selection: see
         // resolveCommandValue in commands.js.
         ownUIStateSignal,
+        valueSignal,
         value: controlInfo.value,
         // The suggestion this control started on — what tells a field showing
         // its default from one carrying an answer (see isUIStateHeld).
@@ -43309,8 +43322,12 @@ const useUIStateController = (
           }
           s.uiActionInternal?.(currentUIState, e);
           if (s.uiAction) {
-            debugUIState(`calling uiAction for ${controlType}`, currentUIState);
-            s.uiAction(currentUIState, e);
+            const value = uiStateOrEmpty(
+              currentUIState,
+              controller.emptyUIState,
+            );
+            debugUIState(`calling uiAction for ${controlType}`, value);
+            s.uiAction(value, e);
           }
           if (skipCommand) ; else {
             const command = controller.controlHostProps.command;
@@ -43814,6 +43831,7 @@ const useUIStateController = (
       return {
         controller,
         parentUiStateSignalHolder,
+        emptyUIStateSignal,
         ...liveValues(),
       };
     },
@@ -43935,6 +43953,7 @@ const useUIStateController = (
   );
   scope.parentUiStateSignalHolder.value =
     parentUIStateController?.uiStateSignal ?? null;
+  scope.emptyUIStateSignal.value = emptyUIState;
 
   const { controller } = scope;
   const controllerRef = controller.ref;
@@ -44145,14 +44164,11 @@ const keptAndNamedChildUIStates = (children, fallbackState, kept) => {
 const readNamedChildUIStates = (children, { warnNameless }) => {
   const values = {};
   for (const child of children) {
-    const { name, emptyUIState } = child;
+    const { name } = child;
     // A control holding nothing writes its own empty, not a hole: the key is in
     // the object either way, and what is read from it keeps the shape the
     // reader was promised (see resolveEmptyUIState).
-    const uiState =
-      child.uiState === undefined && emptyUIState !== undefined
-        ? emptyUIState
-        : child.uiState;
+    const uiState = uiStateOrEmpty(child.uiState, child.emptyUIState);
     if (!name) {
       if (isNamelessGrouping(child, uiState)) {
         Object.assign(
@@ -45499,11 +45515,10 @@ const useUIFacadeStateController = (props, realUIStateController) => {
           // whose last item was unselected holds [], the same thing clearing it
           // leaves — not a value that changes type on its owner the moment it
           // empties.
-          const { emptyUIState } = s.realUIStateController;
-          const uiStateToAdopt =
-            child.uiState === undefined && emptyUIState !== undefined
-              ? emptyUIState
-              : child.uiState;
+          const uiStateToAdopt = uiStateOrEmpty(
+            child.uiState,
+            s.realUIStateController.emptyUIState,
+          );
           s.realUIStateController.setUIState(uiStateToAdopt, propagateUpEvent);
           updatingRef.current = false;
         },
@@ -45821,8 +45836,9 @@ const resolveEmptyUIState = (props, controlType) => {
   if (controlType === "input" && props.type === "checkbox") {
     // A checkbox is a member of a set, the way HTML has it: checked it sends
     // its value ("on" by default), unchecked it sends nothing at all. Only one
-    // holding `true` is a yes/no, and a yes/no nobody said yes to is `false`.
-    return props.value === true ? false : undefined;
+    // declared `boolean` is a yes/no, and a yes/no nobody said yes to is
+    // `false`.
+    return props.boolean ? false : undefined;
   }
   const stateShape = props["navi-state-shape"];
   if (stateShape === "array") {
@@ -45834,6 +45850,15 @@ const resolveEmptyUIState = (props, controlType) => {
   return undefined;
 };
 
+// What a control holding `uiState` is worth: its own empty when it holds
+// nothing, so the reader gets the shape it was promised.
+const uiStateOrEmpty = (uiState, emptyUIState) => {
+  if (uiState === undefined && emptyUIState !== undefined) {
+    return emptyUIState;
+  }
+  return uiState;
+};
+
 // What a cleared control shows: its own empty, kept in the shape it was holding.
 const resolveClearedUIState = (controller) => {
   const { controlType, props } = controller;
@@ -46069,7 +46094,7 @@ const useControlProps = (props, {
   // of a form would re-render at each change of any of its fields.
   // eslint-disable-next-line no-unused-expressions
   uiStateController.ownUIStateSignal.value;
-  const boundAction = useAction(props.action, uiStateController.uiStateSignal);
+  const boundAction = useAction(props.action, uiStateController.valueSignal);
   const [controlRootProps, controlHostProps] = useInteractiveProps(props, {
     uiStateController,
     boundAction,
@@ -58190,7 +58215,23 @@ const css$M = /* css */`@layer navi {
 const InputCheckbox = props => {
   const defaultRef = useRef();
   props.ref = props.ref || defaultRef;
-  props.value = props.value === undefined ? "on" : props.value;
+  const valueWarnedRef = useRef(false);
+  if (!valueWarnedRef.current) {
+    // `true` is what `boolean` writes into `value` below, and Preact hands the
+    // same props object back on a re-render the component triggers itself.
+    if (props.boolean && props.value !== undefined && props.value !== true) {
+      valueWarnedRef.current = true;
+      console.warn(`[checkbox] "boolean" is true or false, its "value" is ignored: remove value={${JSON.stringify(props.value)}}.`);
+    } else if (!props.boolean && props.value === true) {
+      valueWarnedRef.current = true;
+      console.warn(`[checkbox] value={true} is a value like any other: unchecked is undefined. For a yes/no (true or false), use the "boolean" prop.`);
+    }
+  }
+  if (props.boolean) {
+    props.value = true;
+  } else if (props.value === undefined) {
+    props.value = "on";
+  }
   if (props.headless) {
     return jsx(InputCheckboxHeadless, {
       ...props,
@@ -72814,15 +72855,16 @@ document.addEventListener(
 );
 
 /*
- * Whether writing a scroll position now would cost the user the scroll in
- * progress. A write is an instant scroll, and the browser abandons for it any
- * scroll it is playing on its own, short of where that one was going: a key
- * (Home, PageDown, Space), a smooth `scrollTo` or `scrollIntoView`, the status
- * bar tap on iOS. A scroll following a hand is not abandoned: the wheel's next
- * turn carries on, and on most engines a finger keeps dragging from wherever
- * the write left it, and the fling it leaves behind once it lifts carries on
- * from there too (Chrome under DevTools' touch emulation: flings written to at
- * every move of a list's window went as far as flings never written to).
+ * Moves a scroll by what the content moved under the user, unless the write
+ * would cost them the scroll in progress. A write is an instant scroll, and
+ * the browser abandons for it any scroll it is playing on its own, short of
+ * where that one was going: a key (Home, PageDown, Space), a smooth `scrollTo`
+ * or `scrollIntoView`, the status bar tap on iOS. A scroll following a hand is
+ * not abandoned: the wheel's next turn carries on, and on most engines a
+ * finger keeps dragging from wherever the write left it, and the fling it
+ * leaves behind once it lifts carries on from there too (Chrome under
+ * DevTools' touch emulation: flings written to at every move of a list's
+ * window went as far as flings never written to).
  *
  * A fling must not be taken for a scroll the browser plays on its own. A list
  * then leaves uncorrected, for the whole fling, the room its fillers lose above
@@ -72849,6 +72891,18 @@ document.addEventListener(
  * while the finger is still on one of them, and the touchend of a removed
  * element never reaches the document.
  *
+ * Chrome ends a scroll at every write, a finger's fling included: "scrollend"
+ * a frame after the write, and the fling goes on a frame later as a scroll of
+ * its own, as far as it was going (a bare page written to every 120ms of a
+ * fling: 9 "scrollend" for 8 writes, the fling as long). Taken for a new
+ * scroll, it is nobody's once it starts far enough from the finger's last
+ * move, and the list's corrections are refused for the rest of the fling: in
+ * wematch, cards drawn above the screen pushing it down at every window slide.
+ * So a scroll starting right after the "scrollend" of a scroll written to here
+ * goes on as that scroll: same start, same hand. Only a written one: a scroll
+ * starting right after one that ended on its own is a new one, a key or a
+ * smooth `scrollTo` must not pass for the fling before it.
+ *
  * In a browser without "scrollend", no write is said to interrupt anything: a
  * scroll would never be seen ending.
  */
@@ -72858,8 +72912,8 @@ document.addEventListener(
 // hand on a scroll that came from elsewhere.
 const WHEEL_REACH = 100;
 // The fling Chrome plays as a scroll of its own starts a frame or two after the
-// drag's last move (DevTools' touch emulation, 4× CPU: 12ms after the drag's
-// "scrollend").
+// "scrollend" of the drag, or of a write (DevTools' touch emulation, 4× CPU:
+// 12ms after the drag's, 24 to 40ms after a write's in wematch).
 const FLING_REACH = 150;
 // iOS's touch handling, the one engine whose finger drops writes (see above).
 const FINGER_KEEPS_WRITES = !window.CSS.supports(
@@ -72868,14 +72922,41 @@ const FINGER_KEEPS_WRITES = !window.CSS.supports(
 );
 
 const flightMap = new WeakMap();
+// Scrollers written to since their last "scrollend": that "scrollend" may be
+// the write's.
+const writtenScrollerSet = new WeakSet();
+// The flight of a written scroller, from its "scrollend" until a scroll goes on
+// with it.
+const writtenFlightEndMap = new WeakMap();
 let fingersDown = 0;
 let wheelTimeStamp = -Infinity;
 let fingerScrollTimeStamp = -Infinity;
 
 /**
+ * Answers whether it wrote.
+ *
  * @param {Element} scrollerEl
+ * @param {number} delta
+ * @param {{ horizontal?: boolean }} [options]
  * @returns {boolean}
  */
+const scrollByUnlessInterrupting = (
+  scrollerEl,
+  delta,
+  { horizontal } = {},
+) => {
+  if (wouldInterruptScroll(scrollerEl)) {
+    return false;
+  }
+  writtenScrollerSet.add(scrollerEl);
+  if (horizontal) {
+    scrollerEl.scrollLeft += delta;
+  } else {
+    scrollerEl.scrollTop += delta;
+  }
+  return true;
+};
+
 const wouldInterruptScroll = (scrollerEl) => {
   const flight = flightMap.get(scrollerEl);
   if (!flight) {
@@ -72918,6 +72999,15 @@ if ("onscrollend" in window) {
       if (flightMap.has(scroller)) {
         return;
       }
+      const writtenFlightEnd = writtenFlightEndMap.get(scroller);
+      writtenFlightEndMap.delete(scroller);
+      if (
+        writtenFlightEnd &&
+        e.timeStamp - writtenFlightEnd.timeStamp < FLING_REACH
+      ) {
+        flightMap.set(scroller, writtenFlightEnd.flight);
+        return;
+      }
       flightMap.set(scroller, { timeStamp: e.timeStamp });
     },
     { capture: true, passive: true },
@@ -72925,7 +73015,13 @@ if ("onscrollend" in window) {
   document.addEventListener(
     "scrollend",
     (e) => {
-      flightMap.delete(asScroller(e.target));
+      const scroller = asScroller(e.target);
+      const flight = flightMap.get(scroller);
+      flightMap.delete(scroller);
+      if (flight && writtenScrollerSet.has(scroller)) {
+        writtenFlightEndMap.set(scroller, { flight, timeStamp: e.timeStamp });
+      }
+      writtenScrollerSet.delete(scroller);
     },
     { capture: true, passive: true },
   );
@@ -73647,13 +73743,24 @@ const createListItems = () => {
       }
       return null;
     },
-    // The room the item at that index took when it was last drawn, or
-    // undefined: never drawn, not held, or not an item of a run.
+    // The room the item at that index takes: the room it took when it was
+    // last drawn, else the room its run is given for it (see List.Items'
+    // itemSize), else undefined.
     roomAt: (index) => {
       for (const locator of locatorByOwner.values()) {
-        const id = locator.idAt(index);
-        if (id !== undefined) {
-          return roomById.get(id);
+        const room = locator.roomAt(index);
+        if (room !== undefined) {
+          return room;
+        }
+      }
+      return undefined;
+    },
+    // The room the run of that index is given for it, whatever was measured.
+    givenRoomAt: (index) => {
+      for (const locator of locatorByOwner.values()) {
+        const room = locator.givenRoomAt(index);
+        if (room !== undefined) {
+          return room;
         }
       }
       return undefined;
@@ -75142,6 +75249,23 @@ const css$x = /* css */`@property --list-group-label-height {
   &[data-hidden-while-empty]:not(:has([navi-list-item-real])) {
     display: none;
   }
+
+  &[data-continued] {
+    margin-top: calc(-1 * var(--x-list-gap, 0px));
+    display: grid;
+
+    & > .navi_list_item_group_label, & > .navi_list_item_group_list {
+      grid-area: 1 / 1;
+    }
+
+    & > .navi_list_item_group_label {
+      align-self: start;
+    }
+  }
+
+  &[data-continued="hole"] > .navi_list_item_group_label {
+    visibility: hidden;
+  }
 }
 
 .navi_list_container[data-horizontal] > .navi_list_scroll_container > .navi_list > .navi_list_item_group {
@@ -75962,6 +76086,7 @@ const useListScrollSync = ({
   // that changed since is measured again when drawn again, and the anchoring
   // holds the view across the difference. Items laid side by side in a grid
   // share a line, which the fillers hold at the one size.
+  const givenRoomWarnedRef = useRef(false);
   const rememberItemRooms = () => {
     if (!ref.current || itemsPerLineRef.current !== 1) {
       return;
@@ -75970,7 +76095,22 @@ const useListScrollSync = ({
     if (!listEl) {
       return;
     }
-    readItemRooms(listEl, horizontal, listItems.roomById);
+    readItemRooms(listEl, horizontal, (item, room, complete) => {
+      listItems.roomById.set(item.id, room);
+      if (!complete || givenRoomWarnedRef.current) {
+        return;
+      }
+      const givenRoom = listItems.givenRoomAt(item.index);
+      if (givenRoom === undefined) {
+        return;
+      }
+      const difference = room - givenRoom;
+      if (difference > -0.5 && difference < 0.5) {
+        return;
+      }
+      givenRoomWarnedRef.current = true;
+      console.warn(`List.Items itemSize gives ${givenRoom}px to the item at index ${item.index}, which took ${Math.round(room * 10) / 10}px from the end of the item before it to its own end. The items not drawn are held at the room itemSize gives, so the screen moves by the difference when they are drawn above it — and nothing corrects it during a fling on iOS.`);
+    });
   };
   const updateRenderWindow = (newStart, newEnd, reason) => {
     const {
@@ -76732,18 +76872,14 @@ const useListScrollSync = ({
       if (delta > -0.5 && delta < 0.5) {
         return;
       }
-      if (wouldInterruptScroll(scrollerEl)) {
-        // As the anchoring's write would (see holdAnchorStill). The document's
-        // box is the scroller of a list scrolling the page, and it resizes with
-        // every item drawn taller than its filler: while the page scrolls, that
-        // is at every window move.
-        return;
-      }
-      anchorRef.current = null;
-      if (horizontal) {
-        scrollerEl.scrollLeft += delta;
-      } else {
-        scrollerEl.scrollTop += delta;
+      // Not into a scroll it would cut short, as the anchoring's write (see
+      // holdAnchorStill). The document's box is the scroller of a list
+      // scrolling the page, and it resizes with every item drawn taller than
+      // its filler: while the page scrolls, that is at every window move.
+      if (scrollByUnlessInterrupting(scrollerEl, delta, {
+        horizontal
+      })) {
+        anchorRef.current = null;
       }
     };
     const observer = new ResizeObserver(entries => {
@@ -76836,19 +76972,15 @@ const useListScrollSync = ({
       return;
     }
     anchorRef.current = null;
-    if (wouldInterruptScroll(scrollerEl)) {
-      // Nobody is looking at items standing still: they are passing by, on
-      // their way somewhere the browser takes them (a key, a smooth scrollTo,
-      // the status bar, a fling on iOS). The write would stop that scroll short
-      // of where it was going. Left alone, the items drawn above push the rest
-      // by `drift` while all of it moves, and the scroll lands.
-      return;
-    }
-    scrolledByListRef.current = true;
-    if (horizontal) {
-      scrollerEl.scrollLeft += drift;
-    } else {
-      scrollerEl.scrollTop += drift;
+    // Not written into a scroll nobody is looking at: its items are passing
+    // by, on their way somewhere the browser takes them (a key, a smooth
+    // scrollTo, the status bar, a fling on iOS). The write would stop that
+    // scroll short of where it was going. Left alone, the items drawn above
+    // push the rest by `drift` while all of it moves, and the scroll lands.
+    if (scrollByUnlessInterrupting(scrollerEl, drift, {
+      horizontal
+    })) {
+      scrolledByListRef.current = true;
     }
   };
   useLayoutEffect(holdAnchorStill);
@@ -77983,18 +78115,17 @@ const readWindowGeometry = (scrollerEl, listEl, horizontal) => {
   };
 };
 // The room each item drawn takes along the scroll axis (see
-// rememberItemRooms): up to the next item when that one is drawn too, so that
-// what stands between them — a separator, the label of a group the next one
-// opens — is counted; its own box otherwise. A stand-in is not measured: it
-// takes the room it is given, not the room of its item.
-const readItemRooms = (listEl, horizontal, roomById) => {
+// rememberItemRooms): from where the item before it ends to where it ends, so
+// that what stands between the two — a separator, the label of the group it
+// opens — is counted with the item it comes with. A group the window cuts
+// draws its label without room (see the data-continued rule above): that
+// label's room is held by the item that opens the group, in the filler. The
+// first item drawn is measured from the end of what stands before it in the
+// list (a filler, a header); a stand-in is not measured, it takes the room it
+// is given and not the room of its item, but an item after it ends where it
+// ends. `complete` says whether the room was read up to an end before it.
+const readItemRooms = (listEl, horizontal, onRoom) => {
   let previous = null;
-  const keepRoom = (item, next) => {
-    if (item.id === null) {
-      return;
-    }
-    roomById.set(item.id, next && next.index === item.index + 1 ? next.from - item.from : item.to - item.from);
-  };
   for (const itemEl of listEl.querySelectorAll(`[${LIST_ITEM_INDEX_ATTRIBUTE}]`)) {
     if (!isOwnItem(itemEl, listEl)) {
       continue;
@@ -78009,14 +78140,41 @@ const readItemRooms = (listEl, horizontal, roomById) => {
       from: horizontal ? rect.left : rect.top,
       to: horizontal ? rect.right : rect.bottom
     };
-    if (previous) {
-      keepRoom(previous, item);
+    if (item.id !== null) {
+      const endBefore = previous && previous.index === item.index - 1 ? previous.to : readEndBefore(itemEl, listEl, horizontal);
+      if (endBefore === null) {
+        onRoom(item, item.to - item.from, false);
+      } else {
+        onRoom(item, item.to - endBefore, true);
+      }
     }
     previous = item;
   }
-  if (previous) {
-    keepRoom(previous, null);
+};
+// 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.
+const readEndBefore = (itemEl, listEl, horizontal) => {
+  let slotEl = itemEl;
+  const groupListEl = itemEl.parentElement;
+  if (groupListEl && groupListEl.classList.contains("navi_list_item_group_list") && groupListEl.firstElementChild === itemEl) {
+    slotEl = groupListEl.closest(".navi_list_item_group") || itemEl;
+  }
+  const beforeEl = slotEl.previousElementSibling;
+  if (beforeEl) {
+    const rect = beforeEl.getBoundingClientRect();
+    if (rect.width === 0 && rect.height === 0) {
+      return null;
+    }
+    return horizontal ? rect.right : rect.bottom;
+  }
+  if (slotEl.parentElement !== listEl) {
+    return null;
   }
+  const listRect = listEl.getBoundingClientRect();
+  const listStyle = window.getComputedStyle(listEl);
+  return horizontal ? listRect.left + parseFloat(listStyle.borderLeftWidth) + parseFloat(listStyle.paddingLeft) : listRect.top + parseFloat(listStyle.borderTopWidth) + parseFloat(listStyle.paddingTop);
 };
 // The first item the screen shows from `position` on, and the item after the
 // last one it shows up to `position` (exclusive, like the window's end). An
@@ -78566,6 +78724,8 @@ const UnorderedList = ({
     grid: trackColumns ? true : undefined,
     gridTemplateColumns: trackColumns,
     ...rest,
+    // The gap a group the window cuts takes back (see data-continued).
+    style: withListGap(rest.style, spacing),
     spacing: spacing,
     baseClassName: "navi_list",
     children: [!suppressFallback && searchFallbackShown && jsx(SearchFallback, {
@@ -78598,6 +78758,21 @@ const UnorderedList = ({
     })]
   });
 };
+// The list's spacing as a variable, next to the style it is given (an object
+// or a css string, as Box takes either).
+const withListGap = (style, spacing) => {
+  if (spacing === undefined) {
+    return style;
+  }
+  const gap = stringifySpacingStyle(spacing, "gap");
+  if (typeof style === "string") {
+    return `${style};--x-list-gap:${gap}`;
+  }
+  return {
+    ...style,
+    "--x-list-gap": gap
+  };
+};
 
 // The "no match" message. Whether it shows is decided by ListUI (see its
 // searchFallbackShown): a search left nothing to display, and the caller did
@@ -78635,19 +78810,20 @@ const Fallback = ({
 // every item it draws must not be redrawn — every item of it — because the size
 // settled after the first commit.
 // It holds lines: the items side by side on one take its room together, and a
-// last line left short takes it all the same. An item the list drew before
-// takes the room it took then instead (see rememberItemRooms).
+// last line left short takes it all the same. An item whose room is known takes
+// that room instead: the one it took when the list drew it before (see
+// rememberItemRooms), or the one its run is given (see List.Items' itemSize).
 const VirtualFiller = ({
   edge,
   itemCount,
   itemsPerLine,
-  itemsRemembered,
-  roomRemembered,
+  itemsKnown,
+  roomKnown,
   findChunks
 }) => {
   const listItems = useContext(ListItemsContext);
   const lineSize = listItems.virtualItemSizeSignal.value;
-  const sizeToFill = Math.ceil(itemCount / itemsPerLine) * lineSize - itemsRemembered * lineSize / itemsPerLine + roomRemembered;
+  const sizeToFill = Math.ceil(itemCount / itemsPerLine) * lineSize - itemsKnown * lineSize / itemsPerLine + roomKnown;
   // A filler resizing moves what stands below it — the items on screen, when it
   // holds the room of items above them — and it resizes in a commit of its own
   // when the item size settles after the list has rendered: the list puts its
@@ -79364,6 +79540,7 @@ const VISIBILITY_HIDDEN_STYLE = {
  *   pageSize?: number,
  *   memoryBudget?: number,
  *   renderSkeleton?: false | ((index: number) => import("ignore:preact").ComponentChildren),
+ *   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,
  * }>}
@@ -79396,6 +79573,10 @@ const VISIBILITY_HIDDEN_STYLE = {
  *   `<List.Group>` whose label (`renderGroupLabel`) stays on screen for as long
  *   as one of them is. The groups are found in the data as it arrives, which is
  *   the only way a list that discovers its items page by page can have any.
+ *   Style the label, not the group element: a group the render window cuts is
+ *   laid out by the list, its label over its first items, so that the label
+ *   and the gap before it — held in the room of the item opening the group —
+ *   take no room twice.
  * @param {(item: any, index: number) => any} [props.renderGroupLabel]
  *   The label of the group an item opens, given that item.
  * @param {(item: any, index: number) => object} [props.groupLabelProps]
@@ -79414,9 +79595,26 @@ const VISIBILITY_HIDDEN_STYLE = {
  *   further out. `Infinity` keeps every item the run ever received; `0` keeps
  *   only the ones around the window.
  * @param {false|(index: number) => any} [props.renderSkeleton]
- *   What to draw for an item the run does not hold. Defaults to List's own
+ *   What to draw for an item the run does not hold, at the room that item will
+ *   take: a screen of skeletons alone has no item for the list to hold still,
+ *   and when the page lands, what is below a skeleton of the wrong size moves
+ *   by the difference (see docs/scroll.md). Defaults to List's own
  *   `renderSkeleton`, then to a bare `<List.Item skeleton>`; `false` leaves the
  *   item empty (its room is still held, or the list would jump as it loads).
+ * @param {(index: number) => number} [props.itemSize]
+ *   The room the item at an index takes along the scroll axis, in px, known
+ *   before the item arrives: from where the item before it ends to where it
+ *   ends — what stands between the two is its own (the gap, a separator, the
+ *   label of the group it opens; the first item of the list has no gap before
+ *   it). The fillers then hold every item the list has not drawn at its own
+ *   room instead of List's `virtualItemSize`, and an item drawn above the
+ *   screen takes exactly the room held for it: nothing on screen moves. It is
+ *   the only way the screen holds still during a fling on iOS, where writing
+ *   the scroll to correct it would stop the fling. The same index
+ *   `renderSkeleton` is given — the two draw on the same knowledge. A room
+ *   measured on an item drawn wins over it, and in development one that
+ *   differs from it is reported. Items side by side in a grid (`columns`)
+ *   share a line, which keeps `virtualItemSize`.
  * @param {(failure: {error: any, retry: () => void, start: number, end: number}) => any} [props.renderError]
  *   What to draw where items were asked for and never came: given the `error`,
  *   a `retry` to call, and the `start`/`end` of the range that failed — the
@@ -79489,6 +79687,7 @@ const useRunItems = (store, {
   renderItem,
   findText,
   pageSize,
+  itemSize,
   groupBy,
   renderGroupLabel,
   groupLabelProps,
@@ -79572,6 +79771,22 @@ const useRunItems = (store, {
     const item = getItemAt(itemIndex);
     return item === undefined ? undefined : idOf(item, itemIndex);
   };
+  // The room the caller says an item takes (`itemSize`), drawn or not.
+  const givenRoomOf = itemIndex => {
+    if (!itemSize || itemsPerLine !== 1 || itemIndex < runStart || itemIndex >= runEnd) {
+      return undefined;
+    }
+    const room = itemSize(itemIndex);
+    return room > 0 ? room : undefined;
+  };
+  // The room an item took when the list last drew it (see rememberItemRooms),
+  // else the room the caller gives it, else undefined: a filler holds an item
+  // it knows nothing about at the item size.
+  const roomOf = itemIndex => {
+    const id = idAt(itemIndex);
+    const remembered = id === undefined ? undefined : listItems.roomById.get(id);
+    return remembered === undefined ? givenRoomOf(itemIndex) : remembered;
+  };
   listItems.setItemLocator(ownerId, {
     indexOf: id => {
       let found = null;
@@ -79583,32 +79798,27 @@ const useRunItems = (store, {
       });
       return found;
     },
-    idAt
+    roomAt: roomOf,
+    givenRoomAt: givenRoomOf
   });
-  // The room an item took when the list last drew it (see rememberItemRooms),
-  // or undefined: a filler holds an item it never drew at the item size.
-  const roomOf = itemIndex => {
-    const id = idAt(itemIndex);
-    return id === undefined ? undefined : listItems.roomById.get(id);
-  };
-  const readRemembered = (from, to) => {
-    const remembered = {
+  const readKnownRooms = (from, to) => {
+    const known = {
       room: 0,
       count: 0
     };
-    if (listItems.roomById.size === 0) {
-      return remembered;
+    if (listItems.roomById.size === 0 && !itemSize) {
+      return known;
     }
     let itemIndex = from;
     while (itemIndex < to) {
       const room = roomOf(itemIndex);
       if (room !== undefined) {
-        remembered.room += room;
-        remembered.count++;
+        known.room += room;
+        known.count++;
       }
       itemIndex++;
     }
-    return remembered;
+    return known;
   };
   useLayoutEffect(() => {
     return () => {
@@ -79729,6 +79939,7 @@ const useRunItems = (store, {
     nodes.push(jsx(ListItemGroup, {
       label: group.label,
       labelProps: group.labelProps,
+      continued: group.continued,
       children: group.children
     }, groupCount === 1 ? `${ownerId}_group_${group.key}` : `${ownerId}_group_${group.key}_${groupCount}`));
     group = null;
@@ -79766,10 +79977,38 @@ const useRunItems = (store, {
     }
     return groupBy(item, itemIndex);
   };
+  // Where a group opened at that item began, when not there (see
+  // data-continued): "above" the window, or in the "hole" of items not held
+  // drawn right before it. Items not held belong to the group they lead to as
+  // often as not — a page lands every hundred items, a group starts a few
+  // times in a thread — so a group the window starts in is taken to go on
+  // above it unless the item before, held, says otherwise.
+  // Along y only, never built along x: there a group stands its label over
+  // its items, so the label takes no room on the axis (unless it is wider than
+  // the items drawn) and only the gap would be taken back — `margin-left`,
+  // without the overlay of the data-continued rule. Nothing measured it yet.
+  let afterHole = false;
+  const whereGroupContinues = (groupKey, itemIndex) => {
+    if (listItems.horizontal) {
+      return undefined;
+    }
+    if (afterHole) {
+      return "hole";
+    }
+    if (itemIndex !== windowFrom || windowFrom <= runStart) {
+      return undefined;
+    }
+    const itemBefore = getItemAt(windowFrom - 1);
+    if (itemBefore === undefined || groupBy(itemBefore, windowFrom - 1) === groupKey) {
+      return "above";
+    }
+    return undefined;
+  };
   const pushItem = (itemNode, item, itemIndex, groupKey) => {
     if (groupKey === undefined) {
       closeGroup();
       nodes.push(itemNode);
+      afterHole = item === undefined;
       return;
     }
     if (!group || group.key !== groupKey) {
@@ -79778,9 +80017,11 @@ const useRunItems = (store, {
         key: groupKey,
         label: renderGroupLabel ? renderGroupLabel(item, itemIndex) : groupKey,
         labelProps: groupLabelProps ? groupLabelProps(item, itemIndex) : undefined,
+        continued: whereGroupContinues(groupKey, itemIndex),
         children: []
       };
     }
+    afterHole = false;
     group.children.push(itemNode);
   };
   // The text of the items a filler stands for, cut in chunks aligned on the
@@ -79823,13 +80064,13 @@ const useRunItems = (store, {
   // one run, and what sits before or after it (a header, items given one by
   // one) is not virtualized at all.
   if (windowFrom > runStart) {
-    const remembered = readRemembered(runStart, windowFrom);
+    const known = readKnownRooms(runStart, windowFrom);
     nodes.push(jsx(VirtualFiller, {
       edge: "before",
       itemCount: windowFrom - runStart,
       itemsPerLine: itemsPerLine,
-      itemsRemembered: remembered.count,
-      roomRemembered: remembered.room,
+      itemsKnown: known.count,
+      roomKnown: known.room,
       findChunks: getFindChunks(runStart, windowFrom)
     }, "navi-list-filler-before"));
   }
@@ -79856,6 +80097,7 @@ const useRunItems = (store, {
           retry: store.retry
         })
       }, `${ownerId}_failure_${failureFrom}`));
+      afterHole = false;
       itemIndex = failureTo + 1;
       continue;
     }
@@ -79931,13 +80173,13 @@ const useRunItems = (store, {
   }
   closeGroup();
   if (runEnd > windowTo) {
-    const remembered = readRemembered(windowTo, runEnd);
+    const known = readKnownRooms(windowTo, runEnd);
     nodes.push(jsx(VirtualFiller, {
       edge: "after",
       itemCount: runEnd - windowTo,
       itemsPerLine: itemsPerLine,
-      itemsRemembered: remembered.count,
-      roomRemembered: remembered.room,
+      itemsKnown: known.count,
+      roomKnown: known.room,
       findChunks: getFindChunks(windowTo, runEnd)
     }, "navi-list-filler-after"));
   }
@@ -80591,12 +80833,17 @@ const useItemStore = ({
  *   hiddenWhileEmpty — the group leaves the flow (`display: none`) while it
  *                      holds no real item — a search that emptied it, items not
  *                      arrived yet
+ *   continued        — set by a run of items, not by callers: the group began
+ *                      before the first item drawn ("above" the render window,
+ *                      or in a "hole" of items not held), and what stands
+ *                      before that item takes no room (see data-continued)
  *   ...rest          — forwarded to the outer <li role="presentation">
  */
 const ListItemGroup = ({
   label,
   labelProps,
   hiddenWhileEmpty,
+  continued,
   children,
   ...rest
 }) => {
@@ -80639,6 +80886,7 @@ const ListItemGroup = ({
     baseClassName: "navi_list_item_group",
     role: "presentation",
     "data-hidden-while-empty": hiddenWhileEmpty ? "" : undefined,
+    "data-continued": continued,
     children: [jsx("span", {
       ...labelRest,
       ref: labelRef,
@@ -80885,7 +81133,8 @@ const ListResolved = /*#__PURE__*/createComponentResolver([ListFirstResolver, Li
  *   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
- *   then. Left out, it is the average of the items measured so far — once when
+ *   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
  *   while items are held off screen. Given, it is the worst case: the size
  *   every item has, or, in a list whose items differ, the smallest an item can