@jsenv/navi 0.29.11 → 0.29.14

package/README.md

@@ -12,6 +12,15 @@ Routes are flexible: you can create route groups to share logic, state, or UI ac
 
 Actions are async operations with lifecycle management — pending, success, error. You can declare actions that run when navigating to a route, and any component can subscribe to them via `useAsyncData` to reflect what is happening: loading states, results, errors. No manual wiring.
 
+## REST state
+
+`resource()` turns a REST endpoint into a reactive store: one action per verb, a
+shared signal store every component reads from, and automatic invalidation
+between related actions. Parent/child relations are first-class — `.one`,
+`.many`, `.scopedOne`, `.scopedMany` model a backend sub-resource such as
+`/games/:id/candidates` rather than leaving you to hand-roll it. See
+[docs/resource.md](./docs/resource.md).
+
 ## Layout & Typography
 
 **`Box`** is the main layout primitive. It wraps CSS Flexbox with a friendlier API: `flex` for horizontal layout, `flex="y"` for vertical (no more guessing what `flex-direction: column` does visually). Supports `grid`, `inline`, alignment via `alignX`/`alignY`, and spacing props.

package/dist/jsenv_navi.js

@@ -12042,6 +12042,13 @@ const mergeActionParams = (currentParams, newParams) => {
   if (currentParams === NO_PARAMS) {
     return newParams;
   }
+  if (newParams === undefined) {
+    // Every control binds its action to its UI state signal; a control that carries
+    // no value (a button) has an undefined one. It contributes no params, which must
+    // not be confused with "the params are undefined" — the params bound by
+    // bindParams stay in place.
+    return currentParams;
+  }
   return mergeTwoJsValues(currentParams, newParams);
 };
 
@@ -29676,6 +29683,36 @@ const debug$2 = (args) => {
   }
 };
 
+/**
+ * Creates a reactive REST resource backed by a shared signal store.
+ * Returns a `stateFacade` exposing one action per REST callback provided
+ * (`USER.GET`, `USER.GET_MANY`, `USER.POST`, …) plus `.withParams()` and the
+ * relationship methods `.one()`, `.many()`, `.scopedOne()`, `.scopedMany()`.
+ *
+ * Each REST callback receives the params passed to the action call and must return
+ * the data that will be upserted into the store:
+ * - GET / POST / PUT / PATCH → the full item object, e.g. `{ id, name }`
+ * - DELETE                   → the id or `{ id }` of the removed item
+ * - GET_MANY / POST_MANY / … → an array of item objects
+ *
+ * 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
+ * verb's callback.
+ *
+ * @param {string} name - resource name, used in action names and error messages
+ * @param {Object} restCallbacks - `{ idKey, uniqueKeys, rerunOn, dependencies, GET, GET_MANY, POST, POST_MANY, PUT, PUT_MANY, PATCH, PATCH_MANY, DELETE, DELETE_MANY }`
+ * @param {string} [restCallbacks.idKey] - primary key property, defaults to `"id"` (or the first `uniqueKeys` entry)
+ * @param {string[]} [restCallbacks.uniqueKeys] - alternate keys the store can find an item by (e.g. `"username"`); a callback may return a different `id` to rename the item's primary key
+ * @see docs/resource.md — relationships, callback return contracts, decision table
+ *
+ * @example
+ * const USER = resource("user", {
+ *   GET: ({ id }) => fetchJson(`/users/${id}`),
+ *   GET_MANY: () => fetchJson(`/users`),
+ *   POST: (user) => fetchJson(`/users`, { method: "POST", body: user }),
+ *   DELETE: ({ id }) => fetchJson(`/users/${id}`, { method: "DELETE" }),
+ * });
+ */
 const resource = (
   name,
   {
@@ -29830,7 +29867,7 @@ const createResource = (
    * @param {Object} params - Parameters to bind to all actions of this resource (required)
    * @param {Object} options - Additional options for the parameterized resource
    * @returns {Object} A new resource instance with parameter-bound actions and isolated lifecycle
-   * @see {@link ./docs/resource_with_params.md} for detailed documentation and examples
+   * @see docs/resource_with_params.md for detailed documentation and examples
    *
    * @example
    * const ROLE = resource("role", { GET: (params) => fetchRole(params) });
@@ -29877,6 +29914,31 @@ const createResource = (
   };
   stateFacade.withParams = withParams;
 
+  /**
+   * Links a property on each item to a single item in an independent child store.
+   * 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.
+   *
+   * 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.
+   *
+   * Callback return contracts:
+   * - GET / PUT → the parent object with the relationship nested inside:
+   *   `async ({ id }) => ({ id, session: { id: 10, token: "abc" } })`; `null` for no relationship
+   * - DELETE → the parent id (or `{ id }`); the property is set to `null`
+   *
+   * The backend may also embed the child inline in a parent GET/POST response — the
+   * setter on the property upserts the nested object into the child store.
+   *
+   * Returns the child relationship resource, itself chainable:
+   * `USER_SESSION.one("device", DEVICE)` adds a reactive `.device` property to each session.
+   *
+   * @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 }`
+   * @see docs/resource.md
+   */
   stateFacade.one = (
     propertyName,
     childResource,
@@ -30044,6 +30106,29 @@ ${originalActionName} source location: ${locationInfo}`,
     });
   };
 
+  /**
+   * Links a property on each item to an array of items in an independent child store.
+   * Items in the array are full entries in the shared child store — if the same item is
+   * referenced by several parents, a single update propagates to all of them.
+   *
+   * Use it when children are first-class entities shared across parents (a game's players,
+   * who are users). When the children only exist inside their owner, or when the relation
+   * itself carries fields (`seen_at`, `slot`), use `.scopedMany()` instead.
+   *
+   * Callback return contracts:
+   * - GET_MANY → the parent object with the array nested inside:
+   *   `async ({ id }) => ({ id, friends: [{ id: 2 }, { id: 3 }] })` — a full-parent
+   *   response is absorbed as-is; the array replaces the relationship
+   * - GET / POST / PUT / PATCH → the child object; it is upserted into the child store
+   *   but does NOT join the parent's array, which only a GET_MANY refresh changes
+   * - DELETE → `[parentId, childId]`
+   * - DELETE_MANY → `[parentId, [childId, childId, …]]`
+   *
+   * @param {string} propertyName - property holding the child array on each parent item
+   * @param {Object} childResource - the independent resource created by `resource()`
+   * @param {Object} [restCallbacks] - `{ rerunOn, dependencies, GET, GET_MANY, POST, POST_MANY, PUT, PUT_MANY, PATCH, PATCH_MANY, DELETE, DELETE_MANY }`
+   * @see docs/resource.md
+   */
   stateFacade.many = (
     propertyName,
     childResource,
@@ -30340,6 +30425,29 @@ ${originalActionName} source location: ${locationInfo}`,
     });
   };
 
+  /**
+   * Attaches a single private sub-object to each item. The child has no identity outside
+   * its owner and is not shared across items; each owner gets its own private signal.
+   *
+   * Use it for a sub-resource the backend exposes under the parent (`/users/:id/profile`)
+   * whose content is meaningless without that parent.
+   *
+   * All callbacks must return `[ownerId, props | null]`:
+   * - `GET:    async ({ id }) => [id, { bio: "Hello", avatar: "alice.png" }]`
+   * - `PATCH:  async ({ id, bio }) => [id, { bio, avatar: "alice.png" }]`
+   * - `DELETE: async ({ id }) => [id, null]`
+   *
+   * `ownerId` may also be `{ [uniqueKey]: value }` when the owner is known by an alternate key.
+   * The property is `null` until a callback provides data; setting it to `null` clears it.
+   * Mutations apply directly to the owner's signal, so the parent GET is never rerun.
+   *
+   * Returns the child relationship resource, itself chainable:
+   * `USER_PROFILE.one("theme", THEME)` adds a reactive `.theme` property on each profile.
+   *
+   * @param {string} propertyName - property holding the sub-object on each owner item
+   * @param {Object} [restCallbacks] - `{ idKey, rerunOn, dependencies, GET, POST, PUT, PATCH, DELETE }`
+   * @see docs/resource.md
+   */
   stateFacade.scopedOne = (
     propertyName,
     {
@@ -30461,6 +30569,36 @@ ${originalActionName} source location: ${locationInfo}`,
     return childResource;
   };
 
+  /**
+   * Attaches a private ordered collection of sub-objects to each item. The child objects
+   * have no identity outside their owner — two owners can hold items with the same id that
+   * are completely independent. Each owner gets its own private arraySignalStore.
+   *
+   * This is the shape for a backend sub-route (`/games/:id/candidates`,
+   * `…/candidates/:userId/accept`) and for a relation carrying its own fields
+   * (`candidate_since`, `seen_at`): those fields belong to the pair, not to a shared child
+   * store where they would corrupt the entity for every other reader.
+   *
+   * All callbacks must return `[ownerId, ...rest]`:
+   * - `GET_MANY: async ({ id }) => [id, [{ name: "id", type: "int" }, …]]` — replaces the collection
+   * - `POST:     async ({ id, name, type }) => [id, { name, type }]`
+   * - `PUT:      async ({ id, oldName, name, type }) => [id, oldName, { name, type }]` (id rename)
+   * - `DELETE:   async ({ id, name }) => [id, name]`
+   * - `*_MANY:   [ownerId, itemArray]` — any plural verb replaces the whole collection,
+   *   which is how a backend answering a sub-route with the refreshed parent is absorbed
+   *
+   * `ownerId` may also be `{ [uniqueKey]: value }` when the owner is known by an alternate key.
+   * A singular POST upserts the child but does not append it to the collection; ordering is
+   * the backend's, so the owner's GET is rerun instead (only when its last response embedded
+   * `propertyName`), and the child's own GET_MANY reruns per its `rerunOn`.
+   *
+   * Returns the child relationship resource, itself chainable:
+   * `TABLE_COLUMNS.one("dataType", DATA_TYPE)` adds a reactive `.dataType` property on each column.
+   *
+   * @param {string} propertyName - property holding the collection on each owner item
+   * @param {Object} [restCallbacks] - `{ idKey, rerunOn, dependencies, GET, GET_MANY, POST, POST_MANY, PUT, PUT_MANY, PATCH, PATCH_MANY, DELETE, DELETE_MANY }`
+   * @see docs/resource.md
+   */
   stateFacade.scopedMany = (
     propertyName,
     {
@@ -37600,8 +37738,8 @@ const withPixelUnit = value => {
  * because the document is the scrollport in the common case and an anchor
  * landing under a bar is never what anyone wants.
  *
- * The variables hold the bar's measured size — see the comment where FixedBar
- * sets them.
+ * The variables hold the measured size of the bars on that edge — see the
+ * comment where FixedBar sets them.
  */
 
 const FIXED_BAR_SPACE_CSS = /* css */ `
@@ -37631,18 +37769,122 @@ const FIXED_BAR_SPACE_CSS = /* css */ `
   }
 `;
 
+// Several bars can share an edge — during a page transition the outgoing and
+// the incoming one are both mounted. They are all pinned to that same edge, so
+// they overlap: the room to give back is the largest of them, not their sum,
+// and one leaving must leave the others' room in place.
+const sizeMapByArea = new Map();
+// What is currently on <html> for each area (absent = the variable is not set).
+// Writing the value that is already there would invalidate layout for nothing,
+// and several bars sharing an edge means most calls compute the same largest
+// size again — the ones for the smaller bars, and the second half of a page
+// transition.
+const writtenValueByArea = new Map();
+
+// A size that must land before the next paint: a render changed the bar, so
+// the room it takes is given back in that same commit and the content is never
+// painted under it.
 /**
  * @param {"top"|"bottom"|"left"|"right"} area
- * @param {string|null} value - `null` gives the room back to the content.
+ * @param {Element} barElement - Which bar this size belongs to.
+ * @param {number|null} size - In px; `null` gives that bar's room back to the
+ *   content.
  */
-const setFixedBarSpace = (area, value) => {
+const setFixedBarSpace = (area, barElement, size) => {
+  dropPendingSize(area, barElement);
+  storeSize(area, barElement, size);
+  writeSpace(area);
+};
+
+// A size nothing asked for, coming from a ResizeObserver. Writing the variable
+// resizes an ANCESTOR of the bars — the scroll container takes its padding
+// from it — and mutating layout from inside a resize callback is what makes
+// the browser report "ResizeObserver loop completed with undelivered
+// notifications". So the write waits for the frame that resize produced.
+// Queued here rather than deferred by each bar on its own, so the bars sharing
+// an edge resolve to a single write instead of one per bar.
+/**
+ * @param {"top"|"bottom"|"left"|"right"} area
+ * @param {Element} barElement - Which bar this size belongs to.
+ * @param {number} size - In px.
+ */
+const requestFixedBarSpace = (area, barElement, size) => {
+  let pendingSizeMap = pendingSizeMapByArea.get(area);
+  if (!pendingSizeMap) {
+    pendingSizeMap = new Map();
+    pendingSizeMapByArea.set(area, pendingSizeMap);
+  }
+  pendingSizeMap.set(barElement, size);
+  if (flushFrame !== null) {
+    return;
+  }
+  flushFrame = requestAnimationFrame(flushPendingSizes);
+};
+
+const pendingSizeMapByArea = new Map();
+let flushFrame = null;
+
+const flushPendingSizes = () => {
+  flushFrame = null;
+  for (const [area, pendingSizeMap] of pendingSizeMapByArea) {
+    for (const [barElement, size] of pendingSizeMap) {
+      storeSize(area, barElement, size);
+    }
+    writeSpace(area);
+  }
+  pendingSizeMapByArea.clear();
+};
+
+// What the bar itself just said wins over what its observer had queued about
+// it: a bar unmounting gives its room back, and a size queued for it before
+// that must not put it back.
+const dropPendingSize = (area, barElement) => {
+  const pendingSizeMap = pendingSizeMapByArea.get(area);
+  if (!pendingSizeMap) {
+    return;
+  }
+  pendingSizeMap.delete(barElement);
+  if (pendingSizeMap.size === 0) {
+    pendingSizeMapByArea.delete(area);
+  }
+};
+
+const storeSize = (area, barElement, size) => {
+  let sizeMap = sizeMapByArea.get(area);
+  if (!sizeMap) {
+    sizeMap = new Map();
+    sizeMapByArea.set(area, sizeMap);
+  }
+  if (size === null) {
+    sizeMap.delete(barElement);
+  } else {
+    sizeMap.set(barElement, size);
+  }
+};
+
+const writeSpace = (area) => {
+  const sizeMap = sizeMapByArea.get(area);
+  let largestSize = 0;
+  for (const barSize of sizeMap.values()) {
+    if (barSize > largestSize) {
+      largestSize = barSize;
+    }
+  }
   const property = `--navi-fixed-bar-space-${area}`;
   const { style } = document.documentElement;
-  if (value === null) {
-    style.removeProperty(property);
-  } else {
-    style.setProperty(property, value);
+  if (sizeMap.size === 0) {
+    if (writtenValueByArea.has(area)) {
+      writtenValueByArea.delete(area);
+      style.removeProperty(property);
+    }
+    return;
+  }
+  const value = `${largestSize}px`;
+  if (writtenValueByArea.get(area) === value) {
+    return;
   }
+  writtenValueByArea.set(area, value);
+  style.setProperty(property, value);
 };
 
 installImportMetaCssBuild(import.meta);/**
@@ -37822,20 +38064,42 @@ const FixedBar = ({
   const {
     ref
   } = props;
+  const measureSpace = barElement => {
+    const {
+      width,
+      height
+    } = barElement.getBoundingClientRect();
+    return vertical ? width : height;
+  };
+
+  // Anything a render can change — a size prop, the children, a theme variable
+  // — is measured in that same commit, before paint: no frame where the
+  // content sits under the bar, and nothing written from inside an observer.
+  useLayoutEffect(() => {
+    const barElement = ref.current;
+    if (!barElement) {
+      return;
+    }
+    setFixedBarSpace(area, barElement, measureSpace(barElement));
+  });
+
+  // What no render caused: a font loading late, content arriving from outside,
+  // a rotation moving the notch. Measuring here is safe; the write is what has
+  // to wait, and fixed_bar_space.js is the one that holds it back.
   useLayoutEffect(() => {
     const barElement = ref.current;
     if (!barElement) {
       return undefined;
     }
-    const {
-      width,
-      height
-    } = barElement.getBoundingClientRect();
-    setFixedBarSpace(area, `${vertical ? width : height}px`);
+    const resizeObserver = new ResizeObserver(() => {
+      requestFixedBarSpace(area, barElement, measureSpace(barElement));
+    });
+    resizeObserver.observe(barElement);
     return () => {
-      setFixedBarSpace(area, null);
+      resizeObserver.disconnect();
+      setFixedBarSpace(area, barElement, null);
     };
-  }, [area]);
+  }, [area, vertical]);
   return jsx(Box, {
     baseClassName: "navi_fixed_bar",
     "data-area": area,
@@ -38619,7 +38883,7 @@ const useCheckableProps = (props, options) => {
 installImportMetaCssBuild(import.meta);const css$F = /* css */`
   @layer navi {
     .navi_checkbox {
-      --border-radius: var(--navi-control-border-radius);
+      --border-radius: var(--navi-checkbox-border-radius);
       --border-width: var(--navi-control-border-width);
       /* Focus outline */
       --outline-width: var(--navi-focus-outline-width);