@lotics/ui 41.4.0 → 41.4.1

package/AGENTS.md

@@ -18,6 +18,7 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 | [docs/data_entry.md](./docs/data_entry.md) | Which editing pattern for which job — inline edit, fieldset forms, browser-autofill suppression (search controls only), find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (`InlineFiles` for a record ROW — list + one CTA, `multiple` decides add-vs-replace; the `FilesEditor` COMPOUND for a whole section — root owns selection/gallery/confirm, you compose the bar, a HOST verb reads `useFilesEditorSelection` — plus the three-way file INTAKE: CTA + `FileDropTarget` + `usePasteFiles`), stage gates, whether a multiline value keeps its fixed reserve or `autoGrow`s (who decides the length — the field, or whoever is typing), the commit-on-blur vs action-press ordering law (the kit gates the press — `pending_commits`). |
 | [docs/ai_patterns.md](./docs/ai_patterns.md) | AI acts, the human stays in charge — composer, live run feed (`AgentRun`), the one law's split — it turns on WHO supplied the values (machine → a gate: a diff when something is being replaced, a full editable preview when records are being created from a document; human-typed → save-direct + the `ResultHeader` receipt), findings, provenance, confidence; **after the run** — a stored record that fills up from several writers (a person, a chat agent, an extraction, an automation) and remembers none of them: an unwritten value must not render like a written one, a machine's prose and a person's must not share a treatment, model markdown goes in `variant="embedded"`, and the read path must project every field the write paths set; the UI half of the SDK's [ai doc](../app-sdk/docs/ai.md)., the whole run in a dialog (`AgentRunScope`/`AgentRunPane`/`AgentRunActions` — a parked question REPLACES the feed, actions in the footer, **Stop** while streaming), **stopping** (`cancel` stops the run, `abort` only stops listening — so closing a dialog must `cancel` or it keeps billing); **review surfaces compose from atoms** — `DiffValue` (a changed value, droppable in any cell/row/total), `DiffMark` (what happened to the row — ONE circular disc, every surface), `useChangeSet` (accept/reject/undo bookkeeping, no layout) — see [MIGRATION.md](./MIGRATION.md) for the `ChangeReview` family they replace |
 | [docs/composition.md](./docs/composition.md) | The design-language contract — canvas + content column, heading altitude (incl. eyebrow vs group lead — a label is one or the other), banded cards, register vs inset rows (incl. the register laws a row centres its cells by: every cell a FIXED height, a pressable cell on the shared hover token, a column sized by what it carries), the button ladder and **what underlined text may mean** (it GOES somewhere or REVEALS something — never mutates; blue leaves the surface, muted stays on it, and the one in-prose disclosure exception is scoped there), master-detail `Drawer` on a LIST screen vs a child collection's row EXPANDING inside a record, view controls, RECORD EXTENT (one page, sections scrolled to and never routed to), color discipline, typography, whitespace, and how to TEST an overlay component (a `Popover`-backed surface never mounts under jsdom). |
+| [docs/testing.md](./docs/testing.md) | Driving the kit in a browser — the three anatomies where the a11y tree says one thing and a driver must do another: a `PressDoor` row whose named button always intercepts pointer events (by design), portalled overlays that render at the top of the DOM, and custom pointer drag that `dragTo` cannot move. |
 | [docs/templates.md](./docs/templates.md) | The map of `examples/tpl_*.tsx` — what shape each template solves and which to start from (copy + adapt, never import) — plus the record-surface composition rules (pipeline order, static shape, decision budget) and the ACTIVITY shape — a communications feed where the row's label is the GIST and the body varies by medium, one anatomy rather than a row type per kind. |
 
 ## Iron rules

package/docs/composition.md

@@ -1047,6 +1047,29 @@ most common, because it survives every other check: each piece is defensible alo
 question "what does this tell me that the screen does not already say" catches decoration wearing
 an information costume.
 
+## `accessibilityState` never reaches the DOM — write `aria-*` yourself
+
+React Native Web maps a subset of RN's accessibility props and **silently drops
+`accessibilityState`**. So a control written the RN way announces nothing:
+
+```tsx
+// renders, typechecks, and the DOM carries no state at all
+<Pressable accessibilityRole="tab" accessibilityState={{ selected: isActive }} />
+
+// what actually reaches the DOM
+<Pressable accessibilityRole="tab" aria-selected={isActive} />
+```
+
+The trap is the failure's shape rather than its cause. There is no type error —
+the prop is declared — no runtime warning, and the control looks and behaves
+correctly; only a screen reader and the DOM inspector disagree with the source.
+Nothing in a normal loop surfaces it, so it survives review, tests and QA.
+
+Write the raw `aria-*` attribute for any STATE (`aria-selected`, `aria-checked`,
+`aria-expanded`, `aria-disabled`, `aria-current`). `accessibilityRole` and
+`accessibilityLabel` do map and are fine as-is. **Verify in the DOM, never in the
+source** — the source is what lies here.
+
 ## Testing an overlay component — assert through the logic, prove in a browser
 
 **A `Popover`-backed surface does not mount under jsdom.** It positions in a `useLayoutEffect` +

package/docs/testing.md

@@ -0,0 +1,70 @@
+# Driving the kit in a browser
+
+Three kit anatomies where the accessibility tree says one thing and an automated
+driver has to do another. Each is **by design** — the shape that makes the
+component correct for a keyboard and a screen reader is the shape that defeats a
+naive `click()` — so each will read as a bug the first time, and the wrong
+reaction (`force: true`, or "the component is broken") costs a debugging session.
+
+Everything here is true wherever the kit renders. The iframe that a Lotics app
+runs inside adds one more rule on top — `lotics docs building_an_app` § 8.
+
+---
+
+## A pressable row: click the surface, not the named button
+
+A row that presses open **and** carries its own controls is a role-less
+`PressableRow` with a `PressDoor` sibling (`@lotics/ui` AGENTS.md — *a button
+never contains a control*). The door is what a keyboard and a screen reader
+use: it holds the tab stop, the accessible name and the focus ring, and it is an
+**empty absolutely-positioned element**. The cells render above it.
+
+So the a11y tree shows `button "Open ACME-1042"`, and clicking it fails:
+
+```
+subtree intercepts pointer events
+```
+
+That is the design working, not a defect — the visible row is above the door
+precisely so a pointer lands on the row rather than the door. Drive it the way a
+mouse user does:
+
+- **click the row container** — the `generic [cursor=pointer]` wrapping the door;
+  the click bubbles to `PressableRow`
+- or `dispatchEvent('click')` on the door directly
+- or exercise the keyboard path, which is the one the door exists for: focus the
+  door and press `Enter`
+
+**Never reach for `force: true`.** It suppresses the actionability check that is
+telling you the truth, and the click then lands somewhere you did not choose.
+
+## Overlays render at the top of the DOM, not inside their trigger
+
+Popovers, tooltips and dialogs go through a portal (`dom_portal`), so their
+content is a sibling near the end of the document rather than a descendant of
+the control that opened it. Looking for it under the trigger finds nothing.
+
+Assert two things, not one: that the content appeared, and that it **dismisses**
+— outside-click and `Escape` both. An open overlay usually has a click-catching
+backdrop, so clicking the trigger a second time is often intercepted; click the
+backdrop or press `Escape`.
+
+## Custom pointer drag is not `dragTo`
+
+The calendar and gantt drags are built on `use_pointer_drag`, which listens for
+real `pointerdown` / `pointermove` / `pointerup`. Playwright's `dragTo` and mouse
+emulation do not drive them — the sequence simply does nothing, with no error.
+
+Dispatch the events yourself, **in the frame's own context** so the coordinates
+and the window are the right ones. From the dragged element,
+`el.ownerDocument.defaultView` is that window:
+
+1. `pointerdown` on the element
+2. `pointermove` on the window, past the drag threshold (a few pixels — a smaller
+   move is treated as a click, deliberately)
+3. `pointerup` on the window, with `clientX`/`clientY` at the drop target
+
+Then check **both** halves: re-snapshot for the optimistic move, and re-read the
+record to confirm the mutation actually persisted. An optimistic move that never
+reached the server looks identical on screen, which is the whole reason to check
+the second one.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "41.4.0",
+  "version": "41.4.1",
   "type": "module",
   "exports": {
     "./vite": {