@lotics/ui 41.3.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/MIGRATION.md

@@ -4,6 +4,23 @@ Breaking changes, newest first — normally per major, plus the rare minor that
 anyway (recorded under its exact version). The current contract lives in `AGENTS.md` + `docs/`;
 this file exists only to move an app from one release to the next.
 
+## 41.4.0 — embedded markdown is demoted in the OUTLINE, not only on the type ladder
+
+`<Markdown variant="embedded">` sized its headings down and left them as the tags the author
+wrote, so an `h2` inside a record value still landed in heading navigation as a PEER of the
+page's own sections. Measured on a record surface, the outline read:
+
+> Activity · "Tóm tắt cuộc họp (AI) — …" · "Bài học …" · Details · Next action
+
+— a model's call-summary title between two real sections, contributed from inside ONE row of a
+feed that can hold twenty more. Nothing visual finds this, and fixing the size is what makes it
+invisible: the defect stops looking wrong at the moment it stops being measurable.
+
+Embedded headings now render `h4`/`h5`/`h6` (h1→h4, h2→h5, h3 and deeper→h6). They stay
+headings, so a reader can still navigate inside a long summary; they simply can no longer reach
+a section's level. **Nothing to migrate** — document-scale markdown is untouched, and the
+embedded type scale is unchanged.
+
 ## 41.3.0 — `Timeline` rows, embedded markdown, and a disclosure that is not a link
 
 Nothing here removes an API or breaks a type. Two of the changes alter what your rows render on

package/docs/catalog.md

@@ -413,7 +413,9 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   field on a record, a summary in a feed row. Reach for `"embedded"` whenever the
   text was not written by whoever built the screen, which is now the common case
   because the writer is routinely a model; at document scale an `h1` it emits is
-  the same rung as your `SectionHeadingTitle`.
+  the same rung as your `SectionHeadingTitle`. Embedded demotes the heading LEVEL as well as
+  the scale (h1→h4, h2→h5, h3+→h6): sizing alone leaves a model's `##` announcing as a PEER of
+  your own sections in heading navigation, which no visual check can see.
 - **`markdown_types`** — `MarkdownProps`; types only.
 - **`markdown.css`** — import once for the web markdown styling.
 - **`format_date`** — `formatDate` / `parseDate` / `toISODate` + `DateFormatStyle`.

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.3.0",
+  "version": "41.4.1",
   "type": "module",
   "exports": {
     "./vite": {

package/src/markdown.web.tsx

@@ -8,10 +8,14 @@ import { colors } from "./colors";
 import type { MarkdownProps } from "./markdown_types";
 
 export function Markdown({ children, variant = "document" }: MarkdownProps) {
+  const embedded = variant === "embedded";
   return (
     <View>
-      <div className={variant === "embedded" ? "ui-markdown ui-markdown-embedded" : "ui-markdown"}>
-        <ReactMarkdown remarkPlugins={[remarkGfmSafe]} components={markdownComponents}>
+      <div className={embedded ? "ui-markdown ui-markdown-embedded" : "ui-markdown"}>
+        <ReactMarkdown
+          remarkPlugins={[remarkGfmSafe]}
+          components={embedded ? embeddedComponents : markdownComponents}
+        >
           {children}
         </ReactMarkdown>
       </div>
@@ -24,6 +28,56 @@ const markdownComponents = {
   table: CopyableTable,
 };
 
+/**
+ * EMBEDDED MARKDOWN IS DEMOTED IN THE OUTLINE, not only on the type ladder.
+ *
+ * Sizing the headings down fixes what a screen SHOWS and nothing about what it
+ * ANNOUNCES: an `h2` the author of the text happened to write is still an `h2`,
+ * so it lands in heading navigation as a PEER of the page's own sections.
+ * Measured on a record surface, the outline read
+ *
+ *   Activity · "Tóm tắt cuộc họp (AI) — …" · "Bài học …" · Details · Next action
+ *
+ * — a model's call-summary title sitting between two real sections, from inside
+ * one row of a feed that can hold twenty more. No visual probe finds this, and
+ * fixing the size is what makes it invisible: the defect stops looking wrong at
+ * the exact moment it stops being measurable.
+ *
+ * The page's sections are `h2` (`SectionHeading`), and embedded markdown is a
+ * VALUE inside one — inside a row, usually — so it starts at `h4`: deep enough
+ * that it can never be a section's peer, shallow enough to keep its own
+ * hierarchy. It stays a heading rather than becoming a `<div>`, because a long
+ * summary genuinely has parts and a reader navigating INSIDE it should still
+ * find them.
+ */
+const EMBEDDED_HEADING_LEVEL: Record<string, "h4" | "h5" | "h6"> = {
+  h1: "h4",
+  h2: "h5",
+  h3: "h6",
+  h4: "h6",
+  h5: "h6",
+  h6: "h6",
+};
+
+type HeadingProps = React.ComponentPropsWithoutRef<"h4"> & { node?: unknown };
+
+function embeddedHeading(from: keyof typeof EMBEDDED_HEADING_LEVEL) {
+  const Tag = EMBEDDED_HEADING_LEVEL[from];
+  return function EmbeddedHeading({ node: _node, children, ...rest }: HeadingProps) {
+    return <Tag {...rest}>{children}</Tag>;
+  };
+}
+
+const embeddedComponents = {
+  ...markdownComponents,
+  h1: embeddedHeading("h1"),
+  h2: embeddedHeading("h2"),
+  h3: embeddedHeading("h3"),
+  h4: embeddedHeading("h4"),
+  h5: embeddedHeading("h5"),
+  h6: embeddedHeading("h6"),
+};
+
 function CopyableTable(props: React.ComponentPropsWithoutRef<"table"> & { node?: unknown }) {
   const { node: _node, children, ...rest } = props;
   const tableRef = useRef<HTMLTableElement>(null);