@jsenv/navi 0.29.425 → 0.29.426

package/docs/AI_INSTRUCTIONS.md

@@ -116,8 +116,11 @@ start when unsure which export solves a problem.
   keeps the shape of the question. Before wiring a value with `value` +
   `uiAction`.
 - `control_object.md` — one value made of several controls: `ControlGroup` versus
-  `Form`, naming, `<Picker type="object">`, a settings sheet. Before putting
-  anything in a picker popup.
+  `Form`, naming, `<Picker type="object">`, a settings sheet, controls that are
+  not there (lazy slides, popups, deferred boxes, items outside the render
+  window: the group keeps their keys, shared state is written through it).
+  Before putting anything in a picker popup, and before lazy-mounting anything
+  that holds named controls.
 - `group.md` — `<Group>`: several controls reading as one framed object. Before
   negative margins or `border-radius: 0` by hand.
 - `form_changed.md` — a form sends nothing when nothing changed; what "changed"
@@ -179,9 +182,10 @@ start when unsure which export solves a problem.
 - `scroll.md` — where scrolling happens: `header`/`body`/`footer`, a `List`'s
   `scroller`, where a list opens (a position handed back whole, `visibleCount`
   included), a popup that scrolls, many rows (`<List.Items>`, the render window
-  and its first picture, `findText`), hover while scrolling. Before writing CSS
-  to make something scroll, and before rendering a collection as `<List.Item>`
-  children.
+  and its first picture, `findText`), many sections (`<Box mount="after-paint">`
+  and what it leaves out of reach), hover while scrolling. Before writing CSS to
+  make something scroll, before rendering a collection as `<List.Item>`
+  children, and before deferring part of a page.
 - `z_index.md` — DOM order first; a `z-index` without `isolation: isolate`
   competes with the page; navi's bands. Before writing a `z-index`.
 - `typography.md` — text is a component; `maxLines` is the one truncation; one

package/docs/control_object.md

@@ -12,6 +12,7 @@ whose value is an object needs in its popup.
 - [Naming, and what a nameless group does](#naming-and-what-a-nameless-group-does)
 - [A picker whose value is an object](#a-picker-whose-value-is-an-object)
 - [A group holds what it was given](#a-group-holds-what-it-was-given)
+- [A control that is not there](#a-control-that-is-not-there)
 - [One line, one key](#one-line-one-key)
 - [A settings sheet](#a-settings-sheet)
 - [`Group` is not `ControlGroup`](#group-is-not-controlgroup)
@@ -142,7 +143,9 @@ not while the children are not all there yet:
 
 - a group **told** a value holds it whole, before any child has registered to
   show it: items still loading, a popup built at open, a row scrolled out of a
-  virtualized list do not make the value smaller;
+  virtualized list do not make the value smaller, nor does a child acting while
+  others are away (see
+  [A control that is not there](#a-control-that-is-not-there));
 - **a child mounting or unmounting is not somebody answering.** While children
   arrive, their aggregate is a partial reading; the group takes it for its value
   only once it derived that value itself (nobody handed it one), or once a child
@@ -209,6 +212,76 @@ const moveTo = (from, to) => {
 };
 ```
 
+## A control that is not there
+
+The answer lives in the group — and in the signal bound to it, or to the
+picker around it — and the controls are views of it. A view can be missing
+while the answer still matters: a slide not built yet
+(`SlideContainer mount="near"`), a popup or an `Expandable` not opened yet, a
+`<Box mount="after-paint">` before its first frame, an item outside a list's
+render window, a page parked while a route action reruns. None of that makes
+the answer smaller:
+
+- **a key stays until a control of that name, there, says otherwise.** The
+  group keeps what it holds for a control that is not there, the way a
+  selectable list keeps the selection of items it does not draw. A control that
+  arrives is placed from it; one that leaves takes nothing with it;
+- **a value put ON the group reaches every key**, whether its control is there
+  or not: the group's `signal` or `value`, a picker filling its popup, a cancel
+  putting back what the picker held at open, a `--navi-update` aimed at the
+  group. It replaces the whole object, which is also how a key is dropped on
+  purpose;
+- **a control's own `signal` reaches that control only.** Written while the
+  control is not there, nobody is listening: the group never hears of it, and a
+  cancel has nothing to take back. The answer is ONE signal, on the group or on
+  the picker holding it — never one per control, assembled by hand;
+- **only a control that is there checks itself.** `required`, a pattern, a range
+  are verified by the control, so a field not built yet is not validated;
+- **a field hidden on purpose keeps its key too**: the group cannot tell
+  "removed" from "not built yet". Empty it before hiding it, or put the value
+  without it on the group.
+
+So something shared by controls that are not all there — seven days of which
+one is on screen, a copy of one day onto the others — is written as one value,
+through the group:
+
+```jsx
+// the week, keyed by day: what the tabs, the summary and the save read
+const weekSignal = useSignal({ 1: [], 2: [18, 19], 3: [], … });
+
+<Picker type="object" signal={weekSignal} action={saveWeek} ui={<WeekSummary />}>
+  <ControlGroup id="week">
+    <SlideContainer mount="near" signal={daySignal}>
+      {DAYS.map((day) => (
+        <Slide key={day} area={day}>
+          <List selectable multiple name={day}>…</List>
+        </Slide>
+      ))}
+    </SlideContainer>
+    {/* every day, the ones not built included — and a cancel takes it back */}
+    <Button
+      command="--navi-update"
+      commandFor="week"
+      value={sameEveryDay(weekSignal.value[daySignal.value])}
+    >
+      Same hours every day
+    </Button>
+  </ControlGroup>
+</Picker>
+```
+
+```jsx
+// ✗ one signal per day, written by hand: the days not built never hear it,
+//   and Escape leaves them changed
+for (const day of DAYS) {
+  daySignals[day].value = [...shownHours];
+}
+```
+
+The picker's signal follows the popup gesture by gesture, so the button reads
+the day shown from it; the dots on the tabs read it too, for days whose slide
+was never built.
+
 ## One line, one key
 
 A row that opens a popup is one control, so what it answers arrives under its
@@ -274,7 +347,8 @@ one being tried.
 
 **Every field answers**, including those on another tab: they stay mounted and
 come back in the object, and whoever receives it reads `origin` to know which
-count. Aggregating the sheet to a single value of its own
+count. Under `mount="near"` a tab not built yet answers with what the group
+holds for it ([A control that is not there](#a-control-that-is-not-there)). Aggregating the sheet to a single value of its own
 (`aggregateChildStates`) throws away what makes the answer readable, starting
 with the tab. **A button inside is not a field**: the one asking for a position
 acts on the press, and what it answers goes into a control that IS one (a

package/docs/navigation.md

@@ -565,7 +565,10 @@ of the document's scrollport — it holds an offset even without a scrollbar, wh
 `overflow: clip` holds none — so it is the first thing to look for when a row
 does not give positions back. And a page whose height depends on something still
 loading is not tall enough when its position is put back: only the page knows
-when it is whole.
+when it is whole. What navi itself builds after the first frame
+(`<Box mount="after-paint">`, see
+[scroll.md](./scroll.md#many-sections-box-mountafter-paint)) is not such a
+page: the part the position shows is built before it is written.
 
 ## Creating something, then editing it
 

package/docs/popup_open.md

@@ -895,9 +895,12 @@ opening — so the `mount` prop answers both at once:
 | `"while-opened"`              | not mounted                 | not mounted   |
 
 `"always"` is for content something depends on before any opening: a value read
-off it (the default of a picker told no value whose value is read), fields a surrounding form
-submits, a size measured from outside. `"idle"` is `"always"` minus the cost on
-the render that draws the page.
+off it (the default of a picker told no value whose value is read), fields a
+surrounding form must validate or read their own `defaultValue` from, a size
+measured from outside. What such a form was handed it keeps for fields not built
+yet, and hands them once they are
+([control_object.md](./control_object.md#a-control-that-is-not-there)).
+`"idle"` is `"always"` minus the cost on the render that draws the page.
 
 Whatever the value but `"while-opened"`, intent on what opens the popup builds
 the content ahead of the click, `onOpen` or not: a pointer over its anchor, or

package/docs/scroll.md

@@ -307,6 +307,11 @@ A run whose rows all fit the window is just rows: nothing is virtualized, and
 it costs what the same rows would as children. There is no reason to hold back
 from it for a list that might grow.
 
+What an item outside the window holds is not lost with its row: a selection
+keeps the items it does not draw (`--navi-select` reaches them by id), and a
+group keeps the keys of named controls that are not there
+([control_object.md](./control_object.md#a-control-that-is-not-there)).
+
 ### What the list knows, and what it guesses
 
 A virtualized list has one aim: draw as few items as it can, and never show a
@@ -433,6 +438,54 @@ on the run when the collection changes as a whole (never to refresh it, see
 searched), `src/control/demos/integration/1_list_loaded_by_scroll_demo.html` (a
 run reading a slice at a time).
 
+## Many sections: `<Box mount="after-paint">`
+
+The render window's twin for a page that is not a list — a profile, a settings
+screen, sections stacked in a column. The browser paints nothing until the
+render that builds the page has ended, and the sections below the first screen
+weigh in it as much as those on it.
+
+```jsx
+<Box flex="y" spacing="l">
+  <ProfileHeader user={user} />
+  <UpcomingGames user={user} />
+  <Box flex="y" spacing="l" mount="after-paint">
+    <Searches user={user} />
+    <Badges user={user} />
+    <LinkedAccounts />
+  </Box>
+</Box>
+```
+
+The box is empty in the render that mounts it, and built right after the first
+frame that shows the page (the first frame of its route transition, when there
+is one), then kept: a later render of the page renders it as usual.
+
+Which sections lie below the screen is not left to the app's guess, which a
+taller phone or an empty first section breaks. navi looks at each box before
+that frame is painted, and one the frame would show — on the screen, or above
+it — is built before the paint all the same: marking too much costs a second
+render in that frame, never a section popping in. A page put back where it was
+left (see
+[navigation.md](./navigation.md#where-a-navigation-lands-the-scroll)) has the
+boxes that offset shows built before the offset is written, so the offset is not
+clamped by a document still missing its bottom.
+
+What navi cannot do is make the content exist before it is built. So the box is
+only for content nothing reaches during that first frame:
+
+- **Named controls** inside are not there until built: what a group holds for
+  them waits, a value written into their own `signal` reaches nothing, and
+  nothing inside checks itself (see
+  [control_object.md](./control_object.md#a-control-that-is-not-there)).
+- **Ids**: a `commandFor`, a popup `anchor` or a `triggerNaviCommand` aimed
+  inside finds nothing, and neither does a focus put back there. A `#fragment`
+  aimed inside lands a frame late, once the element is there; a popup opened
+  from the address opens once built, since it reads its signal then.
+- **Size**: the box has no height until it is built (a `minHeight` reserves
+  one). Anything measuring it in that frame — a sticky offset, a size read from
+  outside — sees it empty.
+
 ## Hover while scrolling
 
 A scroll moves the content under a pointer that does not move, and the browser

package/package.json

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