@jsenv/navi 0.29.63 → 0.29.65

package/docs/AI_INSTRUCTIONS.md

@@ -138,6 +138,12 @@ consistency across the app, not from any single call site.
   `<Interpolate>` for one sentence, `createI18n` for the app's registry,
   `naviI18n` for navi's own texts. Read it before writing a user-visible
   sentence, and before overriding a navi message.
+- `docs/testid.md` — how a test names an element: why role + accessible name
+  comes first, when `data-testid` takes over, and where navi puts it — on the
+  control's host (the real `<input>`/`<button>`), not on the box around it.
+  Read it before writing a selector in a Playwright/Cypress test against a navi
+  app, and before targeting a `.navi_*` class or a `navi-*`/`data-*` attribute
+  of navi's own.
 - `docs/interactions.md` — the `interactions` prop: making a component answer a
   swipe, a held press, a shortcut, and registering a gesture navi does not have.
   Read it before reading the pointer by hand — who owns a press between nested

package/docs/popup_open.md

@@ -121,9 +121,9 @@ positioned relative to its anchor, say what the anchor is:
 ```
 
 The `anchor` prop always wins over whatever the command carried.
-`anchorCustomEventDetail="ignore"` (Popover only) goes further and drops the
-event's anchor entirely, for a popover that must never be anchored to whatever
-opened it.
+`anchorCustomEventDetail="ignore"` goes further and drops the event's anchor
+entirely — for a popover that must never be anchored to whatever opened it, and
+for a dialog that must never be sized from it (`SidePanel` needs both).
 
 ## Opening it ON something
 
@@ -214,48 +214,39 @@ refuses the one close that matters, the one over a control mid-action.
 
 ### Closing when a button also runs an action
 
-Closing from inside the `action` does not close. While the action runs, the
-button that started it is busy, and a busy control is exactly what a popup
-refuses to close over (see the top of this page). The refusal is not silent —
-the busy control raises a callout saying so — but the popup stays open, and the
-first Escape afterwards dismisses that callout rather than the popup, which
-reads as a popup that no longer closes at all.
-
-There are two shapes, and they say different things:
+A button that carries both runs them in that order: the action first, the
+command once it succeeded.
 
 ```jsx
-// Closes on the press. The popup does NOT wait for save(): it is already
-// closed when the action starts, and the action finishes behind it.
+// Stays open while save() runs, closes when it resolves, stays open if it
+// throws — with what was typed still there and the error on the button.
 <Button command="--navi-close" commandfor="note-dialog" action={save}>
   Save
 </Button>
 ```
 
-`command` next to `action` is the one to reach for when the answer is taken as
-soon as it is given — the popup gets out of the way, the save runs on its own.
-Know what it costs: **a save that fails does so behind a closed popup**, and the
-error callout it raises lands on a button nobody can see any more. Use it where
-the failure is reported somewhere else, or where losing it is acceptable.
-
-```jsx
-// Closes only once save() has resolved, and stays open if it throws.
-<Button
-  action={save}
-  onActionEnd={() => {
-    // NOT synchronously: the button still counts as busy while its own
-    // action-end handlers run, and the popup would refuse the close.
-    queueMicrotask(() => {
-      triggerNaviCommand(dialogRef.current, "--navi-close");
-    });
-  }}
->
-  Save
-</Button>
-```
-
-`onActionEnd` only fires when the action succeeded, so the popup stays open on
-failure — the answer is then neither committed nor given up, and it is still
-there to be corrected, with the error shown on the button that raised it.
+The command is what the press means AFTER the work, so it waits for the work:
+closing first would take the form off the screen over a request that can still
+fail, and the error callout it raises would land on a button nobody can see any
+more. An action that ends in an error or an abort — a `confirm` answered "no" is
+an abort — leaves the popup where it is. Same rule a form already follows for
+what comes after its send (`data-after-send`, see `resolveAfterSend` in
+commands.js).
+
+The wait is why closing **from inside** the action still does not close: while
+the action runs, the button that started it is busy, and a busy control is
+exactly what a popup refuses to close over (see the top of this page). The
+refusal is not silent — the busy control raises a callout saying so — but the
+popup stays open, and the first Escape afterwards dismisses that callout rather
+than the popup, which reads as a popup that no longer closes at all. Nothing has
+to be hand-written to work around it: `command` next to `action` is that
+workaround, done at the one moment where the action has settled and the button
+is no longer busy.
+
+To close on the press instead — the answer taken as soon as it is given, the
+save running on its own behind a closed popup — close from somewhere the action
+does not hold up, e.g. an `onClick` of your own. Know what it costs: **a save
+that fails does so behind a closed popup**.
 
 ## Escape cancels, the other gestures keep
 

package/docs/testid.md

@@ -0,0 +1,103 @@
+# Naming an element for a test (`data-testid`)
+
+What we want: **a test names what it targets, not how it is drawn.** A test
+that finds a button through `.navi_button_content > span:nth-child(2)`, or
+through the sentence written in it, breaks the day the component is restyled,
+the wording changes, or the app is translated — and it breaks with a failure
+that says nothing about the application. `data-testid` is the name the test
+uses: an attribute that exists for no other reason, so nothing but the test can
+break it.
+
+```jsx
+<Button data-testid="save-game" action={save}>
+  Save
+</Button>
+```
+
+```js
+// playwright
+await page.getByTestId("save-game").click();
+// cypress
+cy.get('[data-testid="save-game"]').click();
+```
+
+`data-testid` is that exact spelling on purpose: it is Playwright's default
+`testIdAttribute` and Testing Library's default, and it is the one navi knows
+about (see below). Cypress has no built-in attribute — it reads it as a plain
+selector — so the same name works there too. Don't invent `data-test`,
+`data-cy` or `data-qa` variants per project.
+
+## Prefer the contract the user already sees
+
+`data-testid` is not the first tool. When an element has a role and a stable
+accessible name, target THAT:
+
+```js
+await page.getByRole("button", { name: "Save" }).click();
+await page.getByLabel("Email").fill("a@b.c");
+```
+
+It asserts something the application actually owes the user — a button that is
+a button, a field that is labelled — so the test fails when accessibility
+regresses, which a `data-testid` never notices. Reach for `data-testid` when
+that contract is absent or not usable:
+
+- there is no accessible name, or it is an icon, or it is dynamic;
+- the app is translated, and the test must pass in every language;
+- several elements legitimately share role and name (rows of a list, cells of a
+  table) and only their position tells them apart — a per-item
+  `data-testid={`row-${id}`}` names them by identity instead of by index.
+
+## Where it lands in navi
+
+Navi renders more than one element per component: a control is a little tree —
+a wrapper box, sometimes a label, slots, and inside it the real
+`<input>`/`<button>`/`<select>` that holds the value and receives the clicks
+(the **host**, marked `navi-control-host` in the DOM; the root of the tree
+carries `navi-control`).
+
+**`data-testid` lands on the host**, not on the wrapper. That is deliberate and
+it is the whole point: `getByTestId("email")` gives back the element you can
+`fill()`, `check()`, `press()`, and assert `toBeDisabled()` / `toHaveValue()`
+on. A testid on the wrapper would answer a click with a hit on the padding.
+
+```jsx
+<Input name="email" data-testid="email" />
+```
+
+```html
+<span class="navi_input" navi-control="input">
+  <input navi-control-host="input" data-testid="email" />
+</span>
+```
+
+This routing is what `CONTROL_ATTRIBUTE_SET` in
+`src/control/control_context.js` lists: the props navi hands to the host rather
+than to the box around it (`id`, `name`, `type`, `value`, `tabIndex`,
+`data-testid`, …). Any prop navi does not know lands on the root box instead —
+so a `data-test-id` or a `data-qa` of your own would name the wrapper, which is
+the second reason to keep the standard spelling.
+
+When the wrapper IS what the test wants — a whole field with its label and its
+error message, a section, a row — put the testid on the surrounding component
+(`<Field data-testid="email-field">`, `<Box data-testid="cart-row">`); anything
+built on `Box` forwards it to its own element.
+
+## What not to target
+
+Navi's own attributes are implementation, not a contract: `data-header`,
+`data-body`, `data-scrollable`, `data-variant`, `data-callout-*`,
+`navi-control*`, `.navi_*` class names, and the ids navi generates when none is
+given (`useId`). They change without notice and without a migration note.
+Likewise a `view-transition-name` or a CSS variable: those exist to draw, not
+to be found.
+
+## Naming
+
+The name says what the thing is in the application, never how it looks or where
+it sits: `save-game`, `player-row`, `cart-total` — not `blue-button`,
+`second-input`, `header-btn`. It is a public name of the app for its tests: when
+it has to change, it is because the feature changed.
+
+`data-testid` stays in the production DOM — navi strips nothing. That is
+accepted: a few bytes per element, against tests that survive a redesign.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.63",
+  "version": "0.29.65",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {
@@ -29,7 +29,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@jsenv/dom": "0.17.21",
+    "@jsenv/dom": "0.17.22",
     "@jsenv/humanize": "1.7.8",
     "@jsenv/validity": "0.4.2"
   },