@jsenv/navi 0.29.11 → 0.29.12

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

@@ -29676,6 +29676,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 +29860,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 +29907,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 +30099,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 +30418,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 +30562,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 +37731,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,17 +37762,42 @@ 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();
+
 /**
  * @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) => {
+  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);
+  }
+
+  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) {
+  if (sizeMap.size === 0) {
     style.removeProperty(property);
   } else {
-    style.setProperty(property, value);
+    style.setProperty(property, `${largestSize}px`);
   }
 };
 
@@ -37818,6 +37974,9 @@ const FixedBar = ({
   // rebuilt as a calc() expression, so a size coming from anywhere — a prop, a
   // theme variable, the content itself — is reserved just the same, and each
   // `env()` inset stays the browser's business alone.
+  // And measured again whenever it changes: a ResizeObserver on the bar covers
+  // in one go a size prop that changes, content arriving or leaving, a font
+  // loading late, a rotation moving the notch.
   const vertical = area === "left" || area === "right";
   const {
     ref
@@ -37827,15 +37986,21 @@ const FixedBar = ({
     if (!barElement) {
       return undefined;
     }
-    const {
-      width,
-      height
-    } = barElement.getBoundingClientRect();
-    setFixedBarSpace(area, `${vertical ? width : height}px`);
+    const publishSize = () => {
+      const {
+        width,
+        height
+      } = barElement.getBoundingClientRect();
+      setFixedBarSpace(area, barElement, vertical ? width : height);
+    };
+    publishSize();
+    const resizeObserver = new ResizeObserver(publishSize);
+    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 +38784,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);