@jsenv/navi 0.29.43 → 0.29.44

package/dist/jsenv_navi.js

@@ -23758,9 +23758,9 @@ const useUIGroupStateController = (
   const delegatedChildrenRef = useRef(new Map());
 
   const groupIsRenderingRef = useRef(false);
-  const pendingChangeRef = useRef(false);
+  const pendingChangeRef = useRef(null);
   groupIsRenderingRef.current = true;
-  pendingChangeRef.current = false;
+  pendingChangeRef.current = null;
 
   const isMonitoringChild = (childUIStateController) => {
     if (childUIStateController.isProxy) return false;
@@ -23792,7 +23792,18 @@ const useUIGroupStateController = (
       // signals/pubsub without needing external refs.
       const onChange = (e, { notifyExternal }) => {
         if (groupIsRenderingRef.current) {
-          pendingChangeRef.current = true;
+          // Held until the layout effect below, WITH what it asked for: a child
+          // whose bound signal was written from the outside changes during the
+          // render that follows, and replaying that as a mount sync is what
+          // makes a group silently drift — its own state comes up to date while
+          // the form around it is never told anything moved. A real change
+          // deferred alongside a mount sync stays a real change.
+          const pendingChange = pendingChangeRef.current;
+          pendingChangeRef.current = {
+            e,
+            notifyExternal:
+              pendingChange?.notifyExternal === true ? true : notifyExternal,
+          };
           return;
         }
         const aggChildState = resolvedAggregateChildStates(
@@ -24256,12 +24267,16 @@ const useUIGroupStateController = (
 
   useLayoutEffect(() => {
     groupIsRenderingRef.current = false;
-    if (pendingChangeRef.current) {
-      pendingChangeRef.current = false;
-      scope._onChange(
-        new CustomEvent(`${controlType}_batched_ui_state_update`),
-        { notifyExternal: "silent" },
+    const pendingChange = pendingChangeRef.current;
+    if (pendingChange) {
+      pendingChangeRef.current = null;
+      const batchedEvent = new CustomEvent(
+        `${controlType}_batched_ui_state_update`,
       );
+      chainEvent(batchedEvent, pendingChange.e);
+      scope._onChange(batchedEvent, {
+        notifyExternal: pendingChange.notifyExternal,
+      });
     }
   });
 
@@ -24322,20 +24337,6 @@ const useUIFacadeStateController = (props, realUIStateController) => {
           // not be treated as the picker's synced child.
           return false;
         }
-        if (props.type === "form" && childController.controlType !== "form") {
-          // Only a form: what a type="form" picker syncs with is the form in
-          // its popup, not any control that happens to be in there (an input
-          // sitting outside the form, a ControlGroup — which is a way of
-          // grouping controls INSIDE a form, not a thing a picker talks to).
-          return false;
-        }
-        if (
-          props.type === "array" &&
-          childController.controlType !== "checkbox_group"
-        ) {
-          // only selectable list expose array, ignore others
-          return false;
-        }
         return true;
       };
 
@@ -24355,7 +24356,7 @@ const useUIFacadeStateController = (props, realUIStateController) => {
               `[navi] a second control ("${childType}"${child.name ? ` name="${child.name}"` : ""}) registered in the ${describePicker(props)} popup. ` +
                 `A picker talks to ONE control: the first one receives the picker's whole value and is the only one read back, ` +
                 `so this one is neither filled nor collected. ` +
-                `A popup holding several values needs one group around them — wrap them in a <ControlGroup>, name each control inside it, and give the picker type="form".`,
+                `A popup holding several values needs one group around them — wrap them in a <ControlGroup>, name each control inside it, and give the picker type="object".`,
               child,
             );
           } else {
@@ -32346,6 +32347,12 @@ const defaultRerunOn = {
   GET: false,
   GET_MANY: ["POST"],
 };
+// What makes a range reader stale (rerunOn.GET_RANGE overrides it). DELETE is
+// in there, unlike for GET_MANY: an action holds ids and the store drops the
+// deleted one out of every list holding it, while a list reading by slices
+// holds places — the row that left takes the ones after it one rank up, and
+// only the collection knows who fills the last one.
+const defaultInvalidateRangeOn = ["POST", "DELETE"];
 
 // This handles ALL resource lifecycle logic (rerun/reset) across all resources
 const createResourceLifecycleManager = () => {
@@ -32366,6 +32373,7 @@ const createResourceLifecycleManager = () => {
       paramScope,
       uniqueKeys,
       restActionSet: new Set(),
+      rangeReaderSet: new Set(),
     });
 
     // Register dependencies
@@ -32378,6 +32386,14 @@ const createResourceLifecycleManager = () => {
       }
     }
   };
+  // Only the reader the resource exposes is registered; the ones `bindParams`
+  // makes share its signal (see resource_range_reader.js).
+  const registerRangeReader = (resourceScope, rangeReader) => {
+    const config = registeredResources.get(resourceScope);
+    if (config) {
+      config.rangeReaderSet.add(rangeReader);
+    }
+  };
   const registerAction = (resourceScope, restAction) => {
     const config = registeredResources.get(resourceScope);
     if (config) {
@@ -32608,7 +32624,39 @@ const createResourceLifecycleManager = () => {
     };
   };
 
+  // Which readers hold slices of a collection the mutation just changed: the
+  // one of the resource itself, and the ones of the resources that said they
+  // depend on it.
+  const invalidateRangeReaders = (
+    triggeringAction,
+    triggeringActionContext,
+  ) => {
+    const triggerVerb = triggeringAction.meta.verb;
+    const triggerResourceScope = triggeringActionContext.resourceScope;
+    for (const [resourceScope, config] of registeredResources) {
+      if (config.rangeReaderSet.size === 0) {
+        continue;
+      }
+      const isSameResource = resourceScope === triggerResourceScope;
+      const isDependent = Boolean(
+        triggerResourceScope &&
+        resourceDependencies.get(triggerResourceScope)?.has(resourceScope),
+      );
+      if (!isSameResource && !isDependent) {
+        continue;
+      }
+      const invalidateOn = config.rerunOn.GET_RANGE ?? defaultInvalidateRangeOn;
+      if (!shouldRerunAfter(invalidateOn, triggerVerb)) {
+        continue;
+      }
+      for (const rangeReader of config.rangeReaderSet) {
+        rangeReader.invalidate();
+      }
+    }
+  };
+
   const onActionComplete = (restActionWhoJustCompleted, restActionContext) => {
+    invalidateRangeReaders(restActionWhoJustCompleted, restActionContext);
     const { actionsToRerun, actionsToReset, reasons } = findEffectOnActions(
       restActionWhoJustCompleted,
       restActionContext,
@@ -32627,6 +32675,7 @@ const createResourceLifecycleManager = () => {
   return {
     registerResource,
     registerAction,
+    registerRangeReader,
     onActionComplete,
     // Registers: when `triggerResource` fires, rerun `dependentResource`'s actions.
     // Used by scopedMany to make the parent GET rerun when a child mutation completes.
@@ -32704,13 +32753,20 @@ const getParamScope = (params) => {
  *
  * The reader is a function, so a list feeds on it the way it feeds on any other
  * source: `itemsAction={GAME.GET_RANGE.bindParams({ radar })}`.
+ *
+ * Keeping nothing does not mean hearing nothing: a mutation that decides who
+ * belongs to the collection (a POST, a DELETE, whatever `rerunOn.GET_RANGE`
+ * says) bumps `invalidationSignal`, and whoever reads slices through it goes
+ * and asks again — the counterpart, for a reader, of what a rerun is for an
+ * action. Every reader made by `bindParams` shares the signal of the one it
+ * comes from: the params say which slices are read, not which collection.
  */
 
 
 const createRangeReader = (
   actionName,
   callback,
-  { store, params: boundParams },
+  { store, params: boundParams, invalidationSignal = signal(0) },
 ) => {
   const readRange = async (range = {}) => {
     const { signal, ...rangeParams } = range;
@@ -32739,10 +32795,17 @@ const createRangeReader = (
   };
   Object.defineProperty(readRange, "name", { value: actionName });
   readRange.isRangeReader = true;
+  // Bumped when the collection this reads has moved: the slices anyone holds
+  // stand for a composition that is gone.
+  readRange.invalidationSignal = invalidationSignal;
+  readRange.invalidate = () => {
+    invalidationSignal.value = invalidationSignal.peek() + 1;
+  };
   readRange.bindParams = (paramsToBind) => {
     return createRangeReader(actionName, callback, {
       store,
       params: boundParams ? { ...boundParams, ...paramsToBind } : paramsToBind,
+      invalidationSignal,
     });
   };
   return readRange;
@@ -32809,9 +32872,11 @@ const debug$2 = (args) => {
  * - GET_MANY / POST_MANY / … → an array of item objects
  * - GET_RANGE                 → `{ items, start, count }`, one slice of the collection
  *
- * `GET_RANGE` is a reader rather than an action: it keeps no value and takes no place in
- * the rerun graph, so a `<List.Items>` can feed on it slice by slice
- * (`itemsAction={USER.GET_RANGE.bindParams({ team })}`).
+ * `GET_RANGE` is a reader rather than an action: it keeps no value and has nothing to
+ * rerun, so a `<List.Items>` can feed on it slice by slice
+ * (`itemsAction={USER.GET_RANGE.bindParams({ team })}`). A mutation listed in
+ * `rerunOn.GET_RANGE` (`["POST", "DELETE"]` by default) tells it the collection moved,
+ * and whoever holds slices reads them again.
  *
  * A sub-resource of the backend (`/games/:id/candidates`) must be modelled with a
  * relationship method, never as an `op`/`type` discriminator dispatched inside one
@@ -33991,13 +34056,18 @@ ${originalActionName} source location: ${locationInfo}`,
       continue;
     }
     if (restCallbackKey === "GET_RANGE") {
-      // A range is read, never kept: no action, no place in the rerun graph
+      // A range is read, never kept: no action, nothing to rerun — only a
+      // signal saying the slices anyone holds are out of date
       // (see resource_range_reader.js).
       stateFacade.GET_RANGE = createRangeReader(
         `${name}.GET_RANGE`,
         restCallback,
         { store, params },
       );
+      resourceLifecycleManager.registerRangeReader(
+        stateFacade,
+        stateFacade.GET_RANGE,
+      );
       continue;
     }
     const isMany = restCallbackKey.endsWith("_MANY");
@@ -54720,6 +54790,7 @@ const ListUI = props => {
     expand: expand,
     "navi-nothing-to-display": nothingToDisplay ? "" : undefined,
     "navi-loading": loading ? "" : undefined,
+    "navi-refreshing": virtual.refreshingSignal.value ? "" : undefined,
     "navi-error": error ? "" : undefined,
     styleCSSVars: LIST_STYLE_CSS_VARS,
     pseudoClasses: LIST_PSEUDO_CLASSES,
@@ -57044,6 +57115,10 @@ const createListVirtual = () => {
   // registers, nothing is drawn), and yet they are what it may have been
   // waiting for — the row it was told to open on, for one.
   const pagesSignal = signal(0);
+  // How many runs are re-reading rows they already show. The list wears it as
+  // an attribute: what is drawn is from before, and the app may want to say so
+  // without taking anything away.
+  const refreshingSignal = signal(0);
   const placeByOwner = new Map();
   const locatorByOwner = new Map();
   let passId = 0;
@@ -57051,6 +57126,7 @@ const createListVirtual = () => {
   const virtual = {
     totalSignal,
     pagesSignal,
+    refreshingSignal,
     // What a run needs to know about the list it lives in: how many rows the
     // list is willing to draw at once, which end it opens on, and how much
     // room one row is given — a row whose content has not arrived must take
@@ -57153,7 +57229,7 @@ const VISIBILITY_HIDDEN_STYLE = {
  * inside `<List.Group>`s; each takes its place in declaration order.
  *
  * @type {import("ignore:preact").FunctionComponent<{
- *   renderItem: (item: any, index: number) => import("ignore:preact").ComponentChildren,
+ *   renderItem: (item: any, index: number, state: {refreshing: boolean}) => import("ignore:preact").ComponentChildren,
  *   itemsAction: (range: {start: number, end: number, limit: number, before?: string, after?: string, around?: string, count?: number, signal: AbortSignal}) => any,
  *   count?: number,
  *   groupBy?: (item: any, index: number) => any,
@@ -57163,6 +57239,10 @@ const VISIBILITY_HIDDEN_STYLE = {
  *   renderSkeleton?: false | ((index: number) => import("ignore:preact").ComponentChildren),
  *   renderError?: (failure: {error: any, retry: () => void, start: number, end: number}) => import("ignore:preact").ComponentChildren,
  * }>}
+ * @param {(item: any, index: number, state: {refreshing: boolean}) => any} props.renderItem
+ *   What one row is, given the item and where it sits. `state.refreshing` says
+ *   the rows drawn are the ones from before while the run reads the collection
+ *   again — the list carries `navi-refreshing` for the same reason.
  * @param {(item: any, index: number) => any} [props.groupBy]
  *   What tells rows that belong together apart from the others — the day of a
  *   message, the month of a game. Consecutive rows sharing it are wrapped in a
@@ -57369,6 +57449,9 @@ const ListItems = ({
       virtualItemSize: virtualItemSize
     }, "navi-list-filler-before"));
   }
+  const renderItemState = {
+    refreshing: store.refreshing
+  };
   let rowIndex = windowFrom;
   while (rowIndex < windowTo) {
     if (rowIndex >= failureFrom && rowIndex <= failureTo) {
@@ -57396,7 +57479,7 @@ const ListItems = ({
     const key = item === undefined ? `${ownerId}_skeleton_${rowIndex}` : idOf(item, rowIndex);
     let rowVnode;
     if (item !== undefined) {
-      rowVnode = renderItem(item, rowIndex);
+      rowVnode = renderItem(item, rowIndex, renderItemState);
     } else if (renderRowSkeleton === false) {
       // The row must still take its room: without it the rows below would
       // climb up and slide back down as the answer arrives.
@@ -57497,6 +57580,22 @@ const useItemStore = ({
   }
   const pages = pagesRef.current;
   const [, setPageVersion] = useState(0);
+  // The rows held are out of date and the run has not asked for the new ones
+  // yet. They stay on screen until the answer comes: what is drawn is from
+  // before, which is not the same thing as nothing to draw.
+  const staleRef = useRef(false);
+  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
+  // to the collection is exactly what a run cannot deduce from the rows it
+  // holds. A source that says nothing is read once and stays as it is.
+  const invalidationSignal = typeof itemsAction === "function" ? itemsAction.invalidationSignal : null;
+  const invalidation = invalidationSignal ? invalidationSignal.value : 0;
+  const invalidationRef = useRef(invalidation);
+  if (invalidationRef.current !== invalidation) {
+    invalidationRef.current = invalidation;
+    staleRef.current = true;
+  }
   // The one request in flight, with the means to call it off: a page asked for
   // a window the list has left is work the server and the browser are doing for
   // nothing.
@@ -57506,7 +57605,8 @@ const useItemStore = ({
     end: -1,
     held: -1,
     controller: null,
-    generation: 0
+    generation: 0,
+    revalidating: false
   });
   // The rows asked for that never came. Kept as a range so the list can say
   // where the hole is, and cleared by a retry — which is what makes the same
@@ -57517,9 +57617,24 @@ const useItemStore = ({
   // It stands for a windowful of them: a list that is about to be filled looks
   // like rows on their way, not like an empty list.
   const rowCount = pages.count ?? count ?? virtual.renderBudget;
+  // A run that never received anything has nothing to keep on screen: asking
+  // again is its first ask, not a refresh.
+  if (staleRef.current && pages.count === undefined) {
+    staleRef.current = false;
+  }
+  useLayoutEffect(() => {
+    if (!refreshing) {
+      return null;
+    }
+    virtual.refreshingSignal.value = virtual.refreshingSignal.peek() + 1;
+    return () => {
+      virtual.refreshingSignal.value = virtual.refreshingSignal.peek() - 1;
+    };
+  }, [refreshing]);
   const store = {
     rowCount,
     failure,
+    refreshing,
     // JS memory is cheap next to the DOM, but a long enough scroll accumulates
     // everything it ever went through. Rows far from what is on screen are
     // dropped and simply asked for again if the user goes back — the same
@@ -57560,7 +57675,25 @@ const useItemStore = ({
       let start = missingStart;
       let end = missingEnd;
       let around;
-      if (pages.count === undefined) {
+      // Rows that are all there but out of date: the ask is the window itself,
+      // anchored on the row at its top — a source paginating by cursor gets a
+      // row to count from, and the reading position is what must survive.
+      const revalidating = staleRef.current;
+      if (revalidating) {
+        start = windowFrom;
+        end = windowTo - 1;
+        if (end < start) {
+          // Nothing of this run is on screen (the window frames another one, or
+          // the list is scrolled past it): its own first rows are what it will
+          // draw next.
+          start = 0;
+          end = budget - 1;
+        }
+        const firstHeld = pages.byIndex.get(windowFrom);
+        if (firstHeld && firstHeld.id !== undefined) {
+          around = firstHeld.id;
+        }
+      } else if (pages.count === undefined) {
         const scrolled = virtual.scrolled;
         if (scrolled === "end") {
           // Counting back from the end, the way an HTTP range does: a list
@@ -57591,6 +57724,14 @@ const useItemStore = ({
           return;
         }
         const request = requestRef.current;
+        if (revalidating && request.busy) {
+          if (request.revalidating) {
+            return;
+          }
+          // A page for a window that is about to be replaced wholesale.
+          request.controller?.abort();
+          request.busy = false;
+        }
         if (request.busy) {
           // Still worth waiting for as long as what it went to fetch is still
           // what the list would draw. Once it is not, it is called off — and
@@ -57609,8 +57750,9 @@ const useItemStore = ({
         }
         const held = pages.byIndex.size;
         // Asking again for a range that was already asked for, having received
-        // nothing since, can only produce the same answer.
-        if (request.start === start && request.end === end && request.held === held) {
+        // nothing since, can only produce the same answer. A revalidation is
+        // exactly the case where it produces another one.
+        if (!revalidating && request.start === start && request.end === end && request.held === held) {
           return;
         }
         request.start = start;
@@ -57625,17 +57767,33 @@ const useItemStore = ({
           end,
           around,
           limit: end - start + 1,
-          before: cursor.before,
-          after: cursor.after,
+          // A cursor names a row of the collection as it was; a revalidation
+          // is asked precisely because that is what changed.
+          before: revalidating ? undefined : cursor.before,
+          after: revalidating ? undefined : cursor.after,
           count: pages.count,
           signal: controller.signal
         };
         request.busy = true;
+        request.revalidating = revalidating;
+        if (revalidating) {
+          setRefreshing(true);
+        }
         const done = page => {
           const current = generation === request.generation;
           if (current) {
             request.busy = false;
+            request.revalidating = false;
             setFailure(null);
+            if (revalidating) {
+              staleRef.current = false;
+              setRefreshing(false);
+            }
+          }
+          if (revalidating && !current) {
+            // Rows of a composition already superseded by a newer ask: keeping
+            // them would mix two states of the collection.
+            return;
           }
           if (!page) {
             return;
@@ -57646,6 +57804,12 @@ const useItemStore = ({
           // Before the rows land: what is on screen has to stay where it is,
           // and the DOM still shows the state to hold onto.
           virtual.captureAnchor();
+          if (revalidating) {
+            // The rows held stood for a composition that has moved on; the
+            // ones outside the window are forgotten and asked for again if the
+            // user goes back to them.
+            pages.byIndex = new Map();
+          }
           let i = 0;
           while (i < pageItems.length) {
             pages.byIndex.set(pageStart + i, pageItems[i]);
@@ -57661,6 +57825,14 @@ const useItemStore = ({
             return;
           }
           request.busy = false;
+          request.revalidating = false;
+          if (revalidating) {
+            // The rows from before stay: a revalidation that failed has
+            // nothing better to put in their place.
+            staleRef.current = false;
+            setRefreshing(false);
+            return;
+          }
           setFailure({
             start,
             end,
@@ -58265,8 +58437,8 @@ const PickerTypeResolver = props => {
       ...props
     });
   }
-  if (props.type === "form") {
-    return jsx(PickerForm, {
+  if (props.type === "object") {
+    return jsx(PickerObject, {
       ...props
     });
   }
@@ -58282,19 +58454,19 @@ const PickerText = props => {
   });
 };
 
-// The popup holds a group of named controls — a `<Form>`, or a `<ControlGroup>`
-// when the group is only a shape and has no submit — and this picker's value is
-// whatever that group aggregates. The popup itself holds nothing: it is a
-// surface (see dialog.jsx), so there is nothing to tell it about the shape.
-const PickerForm = props => {
+// The popup holds a group of named controls — a `<ControlGroup>`, or a `<Form>`
+// when that group is a question with a send of its own — and this picker's
+// value is the object that group aggregates. The popup itself holds nothing: it
+// is a surface (see dialog.jsx), so there is nothing to tell it about the shape.
+const PickerObject = props => {
   const Next = useNextResolver();
   return jsx(Next, {
-    ui: jsx(PickerFormUI, {}),
+    ui: jsx(PickerObjectUI, {}),
     ...props,
     type: "navi_js"
   });
 };
-const PickerFormUI = () => {
+const PickerObjectUI = () => {
   const {
     value,
     placeholder
@@ -59304,7 +59476,7 @@ Picker.UI.Week = PickerWeekUI;
 Picker.UI.Datetime = PickerDatetimeUI;
 Picker.UI.File = PickerFileUI;
 Picker.UI.Color = PickerColorUI;
-Picker.UI.Form = PickerFormUI;
+Picker.UI.Object = PickerObjectUI;
 Picker.UI.Multiple = PickerArrayUI;
 Picker.UI.PencilSvg = PencilSvg;
 Picker.UI.ChevronDownSvg = ChevronDownSvg$1;