@jsenv/navi 0.29.324 → 0.29.325

package/docs/AI_INSTRUCTIONS.md

@@ -159,8 +159,9 @@ to start when unsure which export solves a problem.
   `triggerNaviCommand` as the last resort, with the event forwarded and never
   invented; opening ON something; a press that opens and acts is a `Picker`,
   and its trigger wears the wait and the error (a card that lifts, `openOn`);
-  Escape cancels; the close cross; one panel fed by a slot (`createSlot`,
-  `open={isFilled}`); a popup that loads data. Read before passing `open`,
+  Escape cancels; the close cross; one panel fed by a slot (`createSlot`: one
+  `SlotFill` where the choice is made, `open` bound to the screen's signal, never
+  to `isFilled`); a popup that loads data. Read before passing `open`,
   calling `triggerNaviCommand`, or writing a close button.
 - `popup_backdrop.md` — three independent questions: a wall or not
   (`backdrop={false}`), what an outside press does, how far the page withdraws;

package/docs/dialog_shape.md

@@ -57,8 +57,28 @@ Two consequences worth knowing before writing CSS of your own:
 ## One dialog, two shapes
 
 `dockedOnSmallTouchScreen` is the whole small-screen story in one prop: on a
-small touch screen the dialog stops being a centered box and becomes a bottom
-sheet; everywhere else nothing changes.
+small touch screen the dialog stops being a centered box and becomes a sheet
+flush against one edge of the screen; everywhere else nothing changes.
+
+The value says which edge. `true` rests the sheet on the **top** edge, out of
+the virtual keyboard's way: a field tapped in the sheet raises the keyboard
+below it, and the question and the field stay where the finger found them.
+`"bottom"` rests it on the bottom edge, where the thumbs are — for a sheet one
+reads and taps (a list, a couple of buttons, a confirmation) and that holds
+nothing raising a keyboard. A bottom sheet one types into is reflowed into the
+strip left above the keyboard at every keystroke, and the mistake is silent on
+the desktop the author tests on — which is why the safe edge is the default
+and the thumb-first one is the opt-in, and why a `"bottom"` sheet found holding
+a field is warned about in dev, on any screen.
+
+```jsx
+<Dialog dockedOnSmallTouchScreen />          // top: the keyboard cannot reach it
+<Dialog dockedOnSmallTouchScreen="bottom" /> // no field in here, thumbs first
+```
+
+The edge is the prop's own value rather than `positionArea` because
+`positionArea` places _both_ shapes: `positionArea="bottom"` also pins the
+centered box to the bottom of a desktop window.
 
 Both halves of the name matter. Touch alone would dock a tablet or a kiosk
 panel — a whole screen away from where the finger just tapped. Size alone would
@@ -70,38 +90,38 @@ re-resolves the dialog.
 What docking supplies — defaults only, so any single axis of the sheet can be
 adjusted without giving up the rest:
 
-| supplied              | value      | why                                                   |
-| --------------------- | ---------- | ----------------------------------------------------- |
-| `positionArea`        | `"bottom"` | where the thumbs rest and where the keyboard comes up |
-| `marginWithContainer` | `0`        | a sheet is flush, or it is not a sheet                |
-| `expandX`             | `true`     | container-wide, same reason                           |
-| `scrollCapture`       | `true`     | a drag past the sheet's edge must not reach the page  |
+| supplied              | value    | why                                                  |
+| --------------------- | -------- | ---------------------------------------------------- |
+| `positionArea`        | the edge | `"top"` unless the prop says `"bottom"`, see above   |
+| `marginWithContainer` | `0`      | a sheet is flush, or it is not a sheet               |
+| `expandX`             | `true`   | container-wide, same reason                          |
+| `scrollCapture`       | `true`   | a drag past the sheet's edge must not reach the page |
 
-A `layer="top"` dialog flush with an edge of the screen — a docked sheet on the
-bottom, anything with `marginWithContainer={0}` — keeps the band the device
+A `layer="top"` dialog flush with an edge of the screen — a docked sheet,
+anything with `marginWithContainer={0}` — keeps the band the device
 reserves there (`env(safe-area-inset-*)`: the notch, the home indicator,
 Safari's floating bar). The surface still reaches the edge; what it holds stops
 at the band. Only the device's own inset: the dialog is in front of the app's
 fixed bars, so `--navi-safe-area-inset-*`, which counts them too (see
 [`safe_area.md`](./safe_area.md)), is not what it reads.
 
-Plus a swipe-down-to-close, held by the sheet's `header` (a `Box` with the
+Plus a swipe-to-close through the edge the sheet rests on (down for a bottom
+sheet, up for a top one), held by the sheet's `header` (a `Box` with the
 `header` prop) and by anything carrying `data-swipe-grip` — never by the whole
 sheet, so a board something is dragged across keeps its own gestures. See
 [`drag_to_travel.md`](./drag_to_travel.md).
 
 **`expandY` (or `expand`) cancels docking outright.** A dialog already filling
-the height is on the bottom edge docking would bring it to; all docking could
-still do is take away the shape the caller asked for, and arm a swipe-down on
-something that never rose.
+the height touches both edges; all docking could still do is take away the
+shape the caller asked for, and arm a swipe on something that never rose.
 
 ## Saying the two shapes at once
 
 The sentence an app almost always wants is two sentences:
 
 > Keep this dialog between 12 and 16rem so it does not sprawl on a wide window
-> and does not collapse to its shortest line. **And when it is a bottom sheet,
-> forget all that: a sheet is flush and full width.**
+> and does not collapse to its shortest line. **And when it is a sheet, forget
+> all that: a sheet is flush and full width.**
 
 Both halves are written together, and each applies where it means something:
 
@@ -134,7 +154,7 @@ than capping the sheet with it. The container ceiling still holds, as always.
 > dialog that also sets `expandY` never docks, so the cap must never be
 > withdrawn there, and the line above withdraws it anyway. Beyond being wrong,
 > it duplicates a condition navi owns at every call site (it drifts the day
-> "docked" gains a rule), and it reads as a bug: it says nothing about bottom
+> "docked" gains a rule), and it reads as a bug: it says nothing about docked
 > sheets to the next person. State both bounds plainly and let the dialog
 > resolve its own shape.
 
@@ -148,7 +168,7 @@ Since docking _supplies_ `expandX`, passing it explicitly takes the caller out
 of that default:
 
 ```jsx
-// The sheet stops being flush: a floating box at the bottom of the screen.
+// The sheet stops being flush: a floating box against its edge of the screen.
 <Dialog dockedOnSmallTouchScreen expandX={false} />
 ```
 

package/docs/drag_to_travel.md

@@ -272,15 +272,15 @@ so it takes the press outright.
 
 ### A popup pushed back the way it came
 
-A `Dialog` docked to the bottom edge (`dockedOnSmallTouchScreen`) and a
-`SidePanel` close by being pushed back the way they came in — a third consumer
+A `Dialog` docked to an edge (`dockedOnSmallTouchScreen`) and a `SidePanel`
+close by being pushed back the way they came in — a third consumer
 of this same travel, `swipe_to_close.js`. A popup that names a **grip** reads the
 press only there: for a `Dialog` that is its header, plus anything carrying
 `data-swipe-grip`. Everything else it holds is content the finger came to operate
 — a board a piece is dragged across, a map, a list — and a press there never
 reaches the travel at all, whatever it is made of.
 
-So a sheet with no header and nothing marked is not pushed down; it closes by
+So a sheet with no header and nothing marked is not pushed back; it closes by
 its own controls, the backdrop and Escape. A `SidePanel` names no grip and is
 pushed from its whole surface, which suits a panel made of nothing else.
 

package/docs/popup_backdrop.md

@@ -70,14 +70,16 @@ that stays live. `Popup` forwards `backdrop` in both modes, so which of popover
 or dialog the small-screen resolution picks says nothing about whether one
 press or two are needed.
 
-That is what a bottom sheet on a phone is made of. `dockedOnSmallTouchScreen`
-docks the dialog against its container, and `layer` is what that container is —
-`"top"` for the screen, `"local"` for the box the popup was declared in. A
-sheet flush with the bottom of the screen over a map still being read object by
-object is `layer="top"` for the shape and `backdrop={false}` for the map:
+That is what a sheet on a phone is made of. `dockedOnSmallTouchScreen` docks
+the dialog against an edge of its container (the top one, or `"bottom"` for a
+sheet one only reads and taps — see [`dialog_shape.md`](./dialog_shape.md)),
+and `layer` is what that container is — `"top"` for the screen, `"local"` for
+the box the popup was declared in. A sheet flush with the bottom of the screen
+over a map still being read object by object is `layer="top"` for the shape and
+`backdrop={false}` for the map:
 
 ```jsx
-<Popup dockedOnSmallTouchScreen layer="top" backdrop={false}>
+<Popup dockedOnSmallTouchScreen="bottom" layer="top" backdrop={false}>
 ```
 
 Going `layer="local"` to keep the map live instead confines the sheet to the
@@ -177,7 +179,7 @@ panel that closes on that press then reopens on the click that follows is a
 panel meant to stay open, blinking.
 
 ```jsx
-<SidePanel id="error_panel" closeOnClickOutside backdrop={false} open={isFilled}>
+<SidePanel id="error_panel" signal={openCardIdSignal} closeOnClickOutside>
   …
 </SidePanel>
 

package/docs/popup_open.md

@@ -916,30 +916,65 @@ the page appeared (no entrance).
 
 A board with a detail pane wants one panel that stays open as long as something
 asks to be shown in it, and whose content changes from one card to the next
-without the panel closing and reopening. That is `open` driven by a slot:
-`createSlot(Renderer)` keeps the renderer mounted whether or not anything fills
-it, and hands it `isFilled`.
+without the panel closing and reopening. That is a slot: `createSlot(Renderer)`
+keeps the renderer mounted whether or not anything fills it, and the panel is
+the renderer.
 
 ```jsx
-const Panel = ({ isFilled, children }) => (
-  <SidePanel
-    open={isFilled}
-    onClose={() => {
-      openCardIdSignal.value = null;
-    }}
-  >
+const Panel = ({ children }) => (
+  <SidePanel id="error_panel" signal={openCardIdSignal} closeOnClickOutside>
     {children}
   </SidePanel>
 );
 const [PanelSlot, PanelSlotFill] = createSlot(Panel);
 ```
 
-`<PanelSlot />` sits once at the board level; the open card renders a
-`<PanelSlotFill>` holding what the panel shows. The slot holds one filler, the
-last to render: switching cards mounts the next fill in the render that unmounts
-the previous one, and the leaver, unmounting after, leaves the slot to the
-newcomer. `onClose` is the panel's own way out — the close cross, Escape, an
-outside press — and clears the state that renders the fill; the panel follows.
+`<PanelSlot />` sits once at the board level, and so does the one
+`<PanelSlotFill>`, rendered by the board with the named card's content as its
+children:
+
+```jsx
+const openCardId = openCardIdSignal.value;
+return (
+  <Box>
+    {cards.map((card) => (
+      <Card key={card.id} card={card} />
+    ))}
+    {openCardId && (
+      <PanelSlotFill>
+        <CardDetail key={openCardId} id={openCardId} />
+      </PanelSlotFill>
+    )}
+    <PanelSlot />
+  </Box>
+);
+```
+
+Two rules hold this shape together, and each guards against a trap the other
+shape falls into.
+
+**One `SlotFill`, rendered where the choice is made.** The tempting shape is a
+`SlotFill` inside each card, rendered by the card that is open. It works until
+two cards cross: each card reads the signal on its own, so switching from A to
+B is two separate renders, A's fill unmounting in one and B's mounting in the
+other. Between the two the slot is empty, and its renderer is rendered on that
+empty frame — whichever of A or B the tree walks first, the gap exists in one
+of the two directions. The slot cannot tell that gap from a real emptying, and
+does not try to: a fix there would have to guess the scheduler. Rendered once,
+by the component that holds the choice, the fill never leaves; only its
+children change, and there is no gap to fall into.
+
+**The panel is bound to the screen's state, not to `isFilled`.** `isFilled` is
+a fact about the render — whether a fill is mounted right now — and the signal
+is a fact about the screen — which card the address names. `open={isFilled}`
+turns any empty frame into a close, and its `onClose` then clears the very
+state the next fill was waiting for. Bound to the signal, the panel is open
+exactly while a card is named, its own ways out (the close cross, Escape, an
+outside press) clear the signal themselves, and the fill only has to say what
+the panel shows. `isFilled` stays the right `open` for a renderer that has no
+such state — a toolbar or a status shown while anything fills it — fed by the
+one fill above.
+
 A press on another card is not an outside press once the card names the panel
 with `data-navi-popup-inside` (see [popup_backdrop.md](./popup_backdrop.md)).
 The full example is `src/layout/demos/7_slot_demo.html`, "two side panels".

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.324",
+  "version": "0.29.325",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {
@@ -34,7 +34,7 @@
     "preact": "^11.0.0-rc.2"
   },
   "dependencies": {
-    "@jsenv/dom": "0.17.65",
+    "@jsenv/dom": "0.17.66",
     "@jsenv/humanize": "1.8.3",
     "@jsenv/validity": "0.4.4"
   },