@jsenv/navi 0.29.311 → 0.29.314

package/docs/actions.md

@@ -325,10 +325,17 @@ Which instance that is depends on whether the control carries a value:
   what it runs **is** the instance it was handed. `useActionStatus` on that
   instance sees the click, the run, the data.
 - a control that **carries a value** — an input, a form — runs the child
-  instance bound to that value. Those params are not the caller's, so neither
-  is the status: the instance the caller holds stays idle while the control's
-  run moves. Read the effect where it lands (the store, for a resource verb),
-  or listen to the run itself, below.
+  instance bound to that value: the value merged over the params the caller
+  bound, and a value that is not an object **replaces them outright**. A
+  checkbox handed `ACTION.bindParams({ id })` runs `ACTION(true)`, and `id`
+  is gone — the call fails wherever it needed it, far from the binding that
+  lost it. Bind params to a control that holds a value only when the value
+  completes them (a form's object over a bound `{ id }`); when it would
+  replace them, pass a function and keep the params in its closure:
+  `action={() => ACTION({ id, sure: true })}`. Those params are not the
+  caller's, so neither is the status: the instance the caller holds stays idle
+  while the control's run moves. Read the effect where it lands (the store,
+  for a resource verb), or listen to the run itself, below.
 
 Every control with an `action` reports the run it performs, whichever instance
 that is:

package/docs/control_object.md

@@ -54,14 +54,21 @@ So the choice is not about the value, it is about whether this cluster is a
 - something the user sends → `Form`.
 
 A `<Form>` inside a `<Form>` is legal — the inner one becomes a group without
-the `<form>` element — but it carries all of the above with it: its own
-reference, its own "nothing changed", its own submit story. Grouping three
-fields into a sub-object should cost none of that.
+the `<form>` element — and it is a **second question**, not a sub-object of the
+first: what it holds is its own, and the form around it never sees it. Not in
+the value it sends, not in its "nothing changed", and not in the constraints it
+checks before sending — a required field in a popup nobody opened cannot refuse
+the outer submit and point at something the screen is not showing.
+
+So the inner form carries all of the above with it: its own reference, its own
+"nothing changed", its own submit story. Grouping three fields into a sub-object
+should cost none of that — that is a `ControlGroup`.
 
 ## Naming, and what a nameless group does
 
-A group's `name` is the key its value lands under, in the group above it. This
-is true of a `ControlGroup` and of a nested `Form` alike.
+A group's `name` is the key its value lands under, in the group above it — a
+`ControlGroup`, or a `Form` inside something that is not a form (a picker, say).
+A form inside a form lands nowhere: it answers for itself, named or not.
 
 Left nameless, a group is a **grouping**: it exists to hold its children
 together (shared navigation, a visual cluster) without claiming a key, and what
@@ -109,7 +116,9 @@ Two things to get right:
   only one read back. Two controls side by side in a popup is the shape to
   avoid — the second is neither filled nor collected, and navi says so in dev.
   Wrap them in one `ControlGroup` (or one `Form`, when the popup has a send of
-  its own).
+  its own — but only while the picker itself is not inside a form, since a form
+  inside a form answers for itself and the picker would be left with nothing to
+  fill).
 - **The value travels by name.** What the picker was given goes down into the
   group, which hands each named child its own key; a nameless grouping inside
   receives the whole object and picks out what it names. Give a picker of this

package/docs/data_states.md

@@ -57,7 +57,11 @@ consequence: the component stays, so it is still there to offer the way out.
 
 A component that delegates nothing needs no `<Loading>` above it. One that
 delegates its wait does, since that is where the suspension lands, and navi says
-so rather than leaving the subtree blank.
+so rather than leaving the subtree blank. Inside a popup that boundary is the
+popup's own — `{ loading: true }`, or a `<Loading>` inside the popup — never
+the one above the page: a suspension landing there takes the popup away with
+the page it copies, and the popup does not open at all (see
+[popup_open.md](./popup_open.md#a-popup-that-loads-data)).
 
 ## `data` and `loading` are independent
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.311",
+  "version": "0.29.314",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {