@jsenv/navi 0.30.24 → 0.30.26

package/dist/jsenv_navi.js

@@ -3535,6 +3535,7 @@ const updateActions = ({
 
       const actionToRunPrivateProperties =
         getActionPrivateProperties(actionToPrerunOrRun);
+      actionToRunPrivateProperties.answeredAsync = false;
       let performRunResult;
       try {
         performRunResult = actionToRunPrivateProperties.performRun({
@@ -3559,6 +3560,7 @@ const updateActions = ({
       activationWeakSet.add(actionToPrerunOrRun);
 
       if (performRunResult && typeof performRunResult.then === "function") {
+        actionToRunPrivateProperties.answeredAsync = true;
         actionPromiseMap.set(actionToPrerunOrRun, performRunResult);
         allThenableArray.push(performRunResult);
         hasAsync = true;
@@ -3588,7 +3590,9 @@ const updateActions = ({
 
     // Execute promotions (prerun -> run requested)
     for (const actionToPromote of willPromoteSet) {
-      actionToPromote.isPrerunSignal.value = false;
+      writeActionState(() => {
+        actionToPromote.isPrerunSignal.value = false;
+      });
     }
   }
 
@@ -3597,13 +3601,21 @@ const updateActions = ({
   // that IS carrying it. `await action.run()` then means the same thing to
   // every caller: the second one waits for the first one's request and reads
   // the same data, instead of being handed `undefined` before the network has
-  // said anything. See the run() JSDoc.
+  // said anything. It answers in the tense of that run: the answer of a run
+  // that answered with a promise comes back as one, so `run().catch()` holds
+  // whatever state the instance is in. See the run() JSDoc.
   {
     for (const actionToJoin of willJoinSet) {
       const runningPromise = actionPromiseMap.get(actionToJoin);
       if (runningPromise) {
         hasAsync = true;
         resultArray.push({ type: "async", promise: runningPromise });
+      } else if (getActionPrivateProperties(actionToJoin).answeredAsync) {
+        hasAsync = true;
+        resultArray.push({
+          type: "async",
+          promise: Promise.resolve(actionToJoin.dataSignal.peek()),
+        });
       } else {
         resultArray.push({
           type: "sync",
@@ -3809,6 +3821,10 @@ const createAction = (callback, rootOptions = {}) => {
      * the one that asked first or the one that arrived while the request was
      * out. Use `rerun()` to force a fresh run ("refresh", "check now", any
      * explicit user intent to go back to the network).
+     *
+     * An asynchronous callback answers with a promise, joined or not:
+     * `ACTION.run().catch(…)` holds in every state. A synchronous one answers
+     * synchronously, and throws its failure.
      */
     const run = (options) => {
       action.debug(`${action}.run(${stringifyForDisplay(options)})`);
@@ -4267,7 +4283,9 @@ const createAction = (callback, rootOptions = {}) => {
             // another run's, or idle.
             return;
           }
-          runningStateSignal.value = ABORTED;
+          writeActionState(() => {
+            runningStateSignal.value = ABORTED;
+          });
           internalAbortController.abort(abortReason);
           actionAbortMap.delete(action);
           if (isPrerun && (globalAbortSignal.aborted || abortSignal.aborted)) {
@@ -4291,7 +4309,7 @@ const createAction = (callback, rootOptions = {}) => {
 
         actionAbortMap.set(action, abort);
 
-        batch(() => {
+        writeActionState(() => {
           if (valueSignal.peek() === undefined) {
             // An action saying nothing of its own may still have a value the
             // page kept from the previous document (see kept_values.js).
@@ -4370,7 +4388,7 @@ const createAction = (callback, rootOptions = {}) => {
            * before the UI attempts to render the now-missing resource.
            */
 
-          batch(() => {
+          writeActionState(() => {
             const value = resultToValue
               ? resultToValue(runResult, action)
               : runResult;
@@ -4399,7 +4417,9 @@ const createAction = (callback, rootOptions = {}) => {
               error === internalAbortSignal.reason) ||
             error.name === "AbortError";
           if (isAbort) {
-            runningStateSignal.value = ABORTED;
+            writeActionState(() => {
+              runningStateSignal.value = ABORTED;
+            });
             if (isPrerun && abortSignal.aborted) {
               prerunProtectionRegistry.unprotect(action);
             }
@@ -4410,7 +4430,7 @@ const createAction = (callback, rootOptions = {}) => {
           if (isPrerun) {
             markErrorAsPrerunFailure(error);
           }
-          batch(() => {
+          writeActionState(() => {
             errorSignal.value = error;
             runningStateSignal.value = FAILED;
             onError?.(error, { event, action, args });
@@ -4502,7 +4522,7 @@ const createAction = (callback, rootOptions = {}) => {
         }
 
         actionPromiseMap.delete(action);
-        batch(() => {
+        writeActionState(() => {
           if (!willRunOrPrerun) {
             errorSignal.value = undefined;
             valueSignal.value = valueInitial;
@@ -4520,6 +4540,9 @@ const createAction = (callback, rootOptions = {}) => {
         provisionalValue,
         inheritData,
         keepsAnswers: keptAnswerRegistry !== null,
+        // Whether the last run answered with a promise, written by
+        // updateActions: the tense a run joining this instance answers in.
+        answeredAsync: false,
 
         performRun,
         performReset,
@@ -5003,6 +5026,35 @@ const isPlainObject$2 = (obj) => {
   );
 };
 
+// Every state write of a run (start, end, failure, abort, reset), batched. At
+// the end of the batch preact runs the effects those writes woke up, anywhere
+// in the app, and rethrows the first one that threw: from there it would fail
+// this run, or leave it RUNNING, or stop the update half way. That throw is
+// the effect's, so it is reported on its own, as action_error_report.js
+// reports an error (thrown from a timer), and the action carries on. What
+// `write` throws (resultToValue, onComplete…) is the run's, and goes on.
+const writeActionState = (write) => {
+  let writeThrew = false;
+  let writeError;
+  try {
+    batch(() => {
+      try {
+        write();
+      } catch (e) {
+        writeThrew = true;
+        writeError = e;
+      }
+    });
+  } catch (effectError) {
+    setTimeout(() => {
+      throw effectError;
+    });
+  }
+  if (writeThrew) {
+    throw writeError;
+  }
+};
+
 /**
  * Reactively runs an action whenever the params derived from signals change.
  *
@@ -27535,7 +27587,11 @@ ${[idKey, ...uniqueKeys].join(", ")}`,
    * (docs/resource.md).
    */
   const upsertAnswer = (...args) => upsertWith(args, true);
-  const drop = (...args) => {
+  // Batched like upsertWith: a removal observer may drop rows of another
+  // store (a `.one()` declared with `onDelete: "cascade"`), and an effect
+  // reading both runs once, never between the child leaving and its parents.
+  const drop = (...args) => batch(() => dropNow(...args));
+  const dropNow = (...args) => {
     const removedItemArray = [];
     const triggerRemovedMutations = () => {
       if (removedItemArray.length === 0) {
@@ -27570,6 +27626,7 @@ ${[idKey, ...uniqueKeys].join(", ")}`,
           hasFound = true;
           idToRemoveSet.delete(existingItemId);
           idRemovedArray.push(existingItemId);
+          removedItemArray.push(existingItem);
         } else {
           arrayWithoutDroppedItems.push(existingItem);
         }
@@ -29629,6 +29686,15 @@ const createResource = (
    * The property is reactive: updating the child item anywhere propagates immediately.
    * The child resource exists independently — it is not owned by, nor deleted with, the parent.
    *
+   * The other way round is declared with `onDelete`. Left out, a parent outlives its
+   * child: once the child leaves its store, the property reads an empty object (truthy,
+   * `valueOf()` is `null`, no fields) until the parent is read again — a game whose
+   * organizer is deleted is still a game. `onDelete: "cascade"` is for a parent that is
+   * nothing without its child (an address-book row, the person in it): when the child
+   * leaves its store, the parents pointing at it leave theirs in the same write, and
+   * with them every list holding them. Which one a relation needs is decided in
+   * docs/resource.md, "When the child is deleted".
+   *
    * Use it when the child is a first-class entity with its own store, shared across
    * parents (a user referenced by many games). When the child only exists inside its
    * owner, use `.scopedOne()` instead.
@@ -29648,7 +29714,12 @@ const createResource = (
    *
    * @param {string} propertyName - property holding the child on each parent item
    * @param {Object} childResource - the independent resource created by `resource()`
-   * @param {Object} [restCallbacks] - `{ rerunOn, dependencies, GET, PUT, DELETE }`
+   * @param {Object} [restCallbacks] - `{ rerunOn, dependencies, onDelete, GET, PUT, DELETE }`
+   * @param {"cascade"} [restCallbacks.onDelete] - `"cascade"`: a parent leaves its store
+   *   when its child leaves the child's (the child's `DELETE`, `DELETE_MANY`, a write
+   *   named with verb `DELETE`, a cascade of its own). Not the relation's own `DELETE`,
+   *   which unlinks: the property becomes `null` and the parent stays. Throws on a
+   *   relation declared on a scoped child.
    * @see docs/resource.md
    */
   stateFacade.one = (
@@ -29657,6 +29728,7 @@ const createResource = (
     {
       rerunOn: oneRerunOn,
       dependencies: oneDependencies,
+      onDelete,
 
       GET,
       PUT,
@@ -29664,16 +29736,54 @@ const createResource = (
     } = {},
   ) => {
     const declarationSite = getDeclarationSite();
+    const relationLabel = `${name}.one("${propertyName}")`;
     if (ownerName) {
       refuseCallbacksNamingScopedItem(
-        `${name}.one("${propertyName}")`,
+        relationLabel,
         { GET, PUT, DELETE },
         { name, ownerName, propertyName, declarationSite },
       );
     }
+    if (onDelete !== undefined && onDelete !== "cascade") {
+      throw new TypeError(
+        `${relationLabel}: onDelete must be "cascade" or left out, got ${onDelete}.
+${relationLabel} source location: ${declarationSite}`,
+      );
+    }
+    const cascade = onDelete === "cascade";
+    if (cascade && ownerName) {
+      // A scoped item lives in its owner's collection, not in a store this
+      // relation could drop it from.
+      throw new Error(
+        `${relationLabel} cannot declare onDelete: "cascade": a "${name}" item exists only inside its "${ownerName}", and leaves through the "${ownerName}" callbacks.
+Read the "${ownerName}" again after the "${childResource.name}" is deleted (dependencies).
+${relationLabel} source location: ${declarationSite}`,
+      );
+    }
     const childName = `${name}.${propertyName}`;
     const childIdKey = childResource.idKey;
     const childStore = childResource.store;
+    // The id each parent points at, carried by the parent row (copies of a row
+    // keep it, a spread does not): a removal is matched against the parents
+    // the store holds at that moment, under the ids they have then.
+    const childIdSymbol = cascade ? Symbol(`${childName} id`) : undefined;
+    if (cascade) {
+      childStore.observeRemovals((removedChildArray) => {
+        const removedChildIdSet = new Set();
+        for (const removedChild of removedChildArray) {
+          removedChildIdSet.add(removedChild[childIdKey]);
+        }
+        const orphanIdArray = [];
+        for (const parentItem of store.arraySignal.peek()) {
+          if (removedChildIdSet.has(parentItem[childIdSymbol])) {
+            orphanIdArray.push(parentItem[idKey]);
+          }
+        }
+        if (orphanIdArray.length > 0) {
+          store.drop(orphanIdArray);
+        }
+      });
+    }
     addItemSetup((item, answer) => {
       const childItemIdSignal = signal();
       const updateChildItemId = (value, answer) => {
@@ -29728,6 +29838,11 @@ const createResource = (
         get: () => childItemFacadeSignal.value,
         set: updateChildItemId,
       });
+      if (cascade) {
+        Object.defineProperty(item, childIdSymbol, {
+          get: () => childItemIdSignal.peek(),
+        });
+      }
       debug$2(
         `setup ${item}.${propertyName} is one "${childResource.name}" (current value: ${childItemSignal.peek()})`,
       );
@@ -38153,10 +38268,12 @@ const barsOutside = (areaElement) => {
 };
 
 // Room around what a bar's picture holds for what paints past every box — a
-// shadow, the blur of a wall — which no API measures: a filter cuts whatever
+// shadow, the bar's own filter — which no API measures: a filter cuts whatever
 // falls outside its region.
 const WALL_FILTER_INK_ROOM = 100;
 const SVG_NS = "http://www.w3.org/2000/svg";
+// A blur() in a computed filter, its radius in px.
+const BLUR_FUNCTION_REGEXP = /blur\(([^)]*)\)/g;
 
 // The bar's picture dimmed, not a rectangle over it: each wall's colour is
 // flooded atop the bar's own pixels (Porter-Duff source-atop, which no blend
@@ -38184,11 +38301,17 @@ const dimBarPicture = (bar, sources) => {
   const ownFilter = getComputedStyle(bar).filter;
   const chain = ownFilter === "none" ? [] : [ownFilter];
   for (const source of sources) {
-    const backdropFilter = getComputedStyle(source)
-      .getPropertyValue("--backdrop-filter")
-      .trim();
-    if (backdropFilter && backdropFilter !== "none") {
-      chain.push(backdropFilter);
+    const backdropFilter = readBackdropFilter(source);
+    if (backdropFilter !== "none") {
+      // Blurred alone, the bar would fade to transparent over its edges and
+      // show the live document through them: its blur stays inside its shape.
+      chain.push(
+        backdropFilter.replace(
+          BLUR_FUNCTION_REGEXP,
+          (_, radius) =>
+            `url(#${createShapeBlurFilter(parseFloat(radius), region).id})`,
+        ),
+      );
     }
     chain.push(`url(#${createWallFilter(source, region).id})`);
   }
@@ -38197,7 +38320,59 @@ const dimBarPicture = (bar, sources) => {
   dimmedBars.push(bar);
 };
 
+// The wall's backdrop-filter as computed, so a blur radius written in em or
+// rem reads in px, as the wall resolves it where it paints.
+const readBackdropFilter = (source) => {
+  const sourceStyle = getComputedStyle(source);
+  const backdropFilter = sourceStyle
+    .getPropertyValue("--backdrop-filter")
+    .trim();
+  if (!backdropFilter || backdropFilter === "none") {
+    return "none";
+  }
+  const probe = document.createElement("div");
+  probe.style.fontSize = sourceStyle.fontSize;
+  probe.style.filter = backdropFilter;
+  document.body.append(probe);
+  const filter = getComputedStyle(probe).filter;
+  probe.remove();
+  return filter;
+};
+
 const createWallFilter = (source, region) => {
+  const filter = createFilter(region);
+  const flood = document.createElementNS(SVG_NS, "feFlood");
+  flood.setAttribute("flood-color", readBackdropColor(source));
+  const composite = document.createElementNS(SVG_NS, "feComposite");
+  composite.setAttribute("in2", "SourceGraphic");
+  composite.setAttribute("operator", "atop");
+  filter.append(flood, composite);
+  return filter;
+};
+
+// Colour kept, alpha set to 1.
+const OPAQUE_MATRIX = "1 0 0 0 0  0 1 0 0 0  0 0 1 0 0  0 0 0 0 1";
+
+// The wall's blur kept inside the bar. At rest the window is blurred as one
+// image; a CSS blur() on the bar sees only the bar, so its edges go half
+// transparent and its colour spreads past its box. Made opaque, each pixel is
+// the mean of the bar's own pixels around it (feColorMatrix works on
+// unpremultiplied colours), then cut back to the bar's own alpha.
+const createShapeBlurFilter = (stdDeviation, region) => {
+  const filter = createFilter(region);
+  const blur = document.createElementNS(SVG_NS, "feGaussianBlur");
+  blur.setAttribute("stdDeviation", stdDeviation);
+  const opaque = document.createElementNS(SVG_NS, "feColorMatrix");
+  opaque.setAttribute("type", "matrix");
+  opaque.setAttribute("values", OPAQUE_MATRIX);
+  const clip = document.createElementNS(SVG_NS, "feComposite");
+  clip.setAttribute("in2", "SourceAlpha");
+  clip.setAttribute("operator", "in");
+  filter.append(blur, opaque, clip);
+  return filter;
+};
+
+const createFilter = (region) => {
   if (!wallFilterSvg) {
     wallFilterSvg = document.createElementNS(SVG_NS, "svg");
     wallFilterSvg.setAttribute(WALL_FILTERS_ATTRIBUTE, "");
@@ -38207,18 +38382,13 @@ const createWallFilter = (source, region) => {
   wallFilterCount++;
   const filter = document.createElementNS(SVG_NS, "filter");
   filter.id = `navi-transition-wall-${wallFilterCount}`;
-  // linearRGB, the default, floods another colour than the wall's.
+  // linearRGB, the default, floods another colour than the wall's and blurs
+  // in another space than its backdrop-filter.
   filter.setAttribute("color-interpolation-filters", "sRGB");
   filter.setAttribute("x", region.x);
   filter.setAttribute("y", region.y);
   filter.setAttribute("width", region.width);
   filter.setAttribute("height", region.height);
-  const flood = document.createElementNS(SVG_NS, "feFlood");
-  flood.setAttribute("flood-color", readBackdropColor(source));
-  const composite = document.createElementNS(SVG_NS, "feComposite");
-  composite.setAttribute("in2", "SourceGraphic");
-  composite.setAttribute("operator", "atop");
-  filter.append(flood, composite);
   wallFilterSvg.appendChild(filter);
   return filter;
 };