@lotics/ui 47.5.0 → 47.5.2

package/AGENTS.md

@@ -17,8 +17,8 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 | [docs/catalog.md](./docs/catalog.md) | **The complete inventory** — incl. `just_arrived` (`useJustArrived` + `TableRow`'s `justArrived`: the one-shot wash a row wears when it LANDS, so a realtime push is visible rather than one row of two hundred silently changing) — Reach-by-role (each data role → the ONE canonical component) + every `@lotics/ui/<module>` entry point (incl. `@lotics/ui/vite`'s `loticsOptimizeDeps` + `loticsResolve()` — the pre-bundle list and the whole `resolve` block a custom-code app's `vite.config.ts` imports rather than hand-carries, dev-link included). Read before building any screen; reuse first. |
 | [docs/data_entry.md](./docs/data_entry.md) | Which editing pattern for which job — inline edit, fieldset forms, choosing a CHOICE control by option count, find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (`InlineFiles` for a record ROW, the `FilesEditor` COMPOUND for a whole section, plus the three-way file INTAKE), stage gates, and the commit-on-blur vs action-press ordering law. |
 | [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; findings, provenance, confidence; **after the run** — a stored record that fills up from several writers; the whole run in a dialog, **stopping**; **review surfaces compose from atoms** — `DiffValue`, `DiffMark`, `useChangeSet`. |
-| [docs/composition.md](./docs/composition.md) | The design-language contract — **the form comes before the treatment** (name what the subject IS before reaching for parts), canvas + content column, heading altitude, register vs inset rows, the button ladder, master-detail `Drawer`, the register's rhythm, craft and TRIAGE bands, where the accent goes, theming as an app-level ESCAPE HATCH, color discipline, typography, **one fact one surface** (a chooser over the thing it chooses is a SELECTOR, not a second card grid; a control that only swaps one number for another is replaced by showing both), **a width floor answers can this be READ and never can this be operated** (the operating question passes a row whose every string is already cut), **a status column earns its slot by carrying a REASON rather than a state** (the floor asks for the fact to be visible, not for a badge), **a row subject's supporting line takes a REFERENCE and never a sentence** (an explanation truncates to the clause the reader already knew), and where a commit sits. |
-| [docs/reviewing.md](./docs/reviewing.md) | **Reviewing a screen you built — and the answer when one "looks bad"** — the other docs say what good looks like; this one says how to find out whether you achieved it. Run it BEFORE the deploy: a typecheck, a lint, a test and `app check` are all blind to how a screen reads. GATES that outrank every treatment question, then the probes, each naming what to COLLECT and the SIGNATURE in the numbers — including the truncation sweep (a row whose halves both measure fine and whose text is cut) the summary-vs-facet check (a strip that keeps describing the unfiltered set) and the derivable-column test (a status badge its neighbour already answers). Plus the extraction snippets, what measurement cannot see, and how to act on a finding. |
+| [docs/composition.md](./docs/composition.md) | The design-language contract — **the form comes before the treatment** (name what the subject IS before reaching for parts), canvas + content column, heading altitude, register vs inset rows, the button ladder, master-detail `Drawer`, the register's rhythm, craft and TRIAGE bands, where the accent goes, theming as an app-level ESCAPE HATCH, color discipline, typography, **one fact one surface** (a chooser over the thing it chooses is a SELECTOR, not a second card grid; a control that only swaps one number for another is replaced by showing both), **a width floor answers can this be READ and never can this be operated** (the operating question passes a row whose every string is already cut), **a status column earns its slot by carrying a REASON rather than a state** (the floor asks for the fact to be visible, not for a badge), **a row subject's supporting line takes a REFERENCE and never a sentence** (an explanation truncates to the clause the reader already knew), **a list stays fast by keeping IDENTITY rather than memoizing** (key by the record not the index; `memo` is the last resort and does nothing against a freshly-built prop), and where a commit sits. |
+| [docs/reviewing.md](./docs/reviewing.md) | **Reviewing a screen you built — and the answer when one "looks bad"** — the other docs say what good looks like; this one says how to find out whether you achieved it. Run it BEFORE the deploy: a typecheck, a lint, a test and `app check` are all blind to how a screen reads. GATES that outrank every treatment question, then the probes, each naming what to COLLECT and the SIGNATURE in the numbers — including the truncation sweep (a row whose halves both measure fine and whose text is cut) the summary-vs-facet check (a strip that keeps describing the unfiltered set) and the derivable-column test (a status badge its neighbour already answers) and the cross-FRAME check (what the screen destroys when a row arrives — the one defect that exists in no single frame). Plus the extraction snippets, what measurement cannot see, and how to act on a finding. |
 | [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. |
 

package/docs/catalog.md

@@ -2303,7 +2303,13 @@ component rather than showing it at zero.
   filename; pass `accessibilityLabel` to say what pressing it DOES instead. The per-surface
   pieces are exported for a hand-rolled layout: `DocumentBadge` (a bare pressable badge —
   its `size` is the square SLOT side, like every other tile here, and the badge is fitted to
-  it), `DocumentCard`, `MediaCard`, `RemoveButton`.
+  it), `DocumentCard`, `MediaCard`, `RemoveButton`. **`toDisplayFile(cell)` is how a file
+  reaches any of them** — it takes a `FileCell` (a record read's `files` entry: `id`,
+  `filename`, `mime_type`, `url`, optional `thumbnail_url`) and returns the `DisplayFile`
+  every component here expects. Reach for it rather than writing the five-line mapping: the
+  hand-written one is where a `mime_type`/`mimeType` slip becomes a tile that silently
+  renders as a generic document. It returns a fresh object per call by design — see
+  composition.md §"A list stays fast" for why an identity cache is the wrong answer.
 - **`file_thumbnail_grid`** — **`diffs`** (a `ReadonlyMap<string, DiffKind>`, keyed like
   `selectedIds`) marks each tile, so a grid under review is the SAME grid with one more map
   passed in rather than a different component the operator has never seen.

package/docs/composition.md

@@ -136,6 +136,19 @@ the subject into rows.
 | Register / work list / calendar | 1040 |
 | Wide wallboard / report | 1100 |
 
+**A row that navigates PAINTS.** A link is not a row: it paints nothing, so a row tall enough to
+hold an identity mark becomes a large silent target — the pointer crosses it and the only thing
+saying it is pressable is the cursor. Reach for the row surface (`PressableRow`), never a
+hand-rolled hover on the anchor: the wash has to span the WHOLE row *including its trailing
+controls*, and a parent's Pressability hover is released to the innermost nested pressable, which
+stops the wash short of the `⋯` and leaves a gap exactly where the eye is going. Keep the anchor
+INSIDE as the accessible door — a row of places to go owes middle-click, cmd-click and copy-link,
+which only a real anchor gives.
+
+Without that wash the trailing controls are what look wrong: nothing ties a `⋯` to its row, so the
+right edge reads as a floating column competing with the names, and the instinct is to hide the
+control. Paint the row first — the clutter usually WAS the missing wash.
+
 **ONE LEFT EDGE — the whole page, and then the whole APP.** Headings, detail labels, prose, a
 table's first column, a footer's totals, a dialog's title. Then check the screen this one OPENS: a
 list and the record it opens are one reading column seen twice, and both must derive from ONE
@@ -2083,6 +2096,35 @@ 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.
 
+## A list stays fast by keeping IDENTITY, not by memoizing
+
+The expensive thing a screen can do is not re-render — it is REPLACE. Re-running a
+component produces no DOM work at all when the output matches; React's diff absorbs it. A
+15-row register with 58 pictures, re-rendered against equal data, writes **nothing**. The
+same register with one row inserted, when identity is lost, writes **271 mutations and
+rebuilds 89 nodes** — and every rebuilt `Image` starts empty and paints blank until a
+frame later, which is the flicker people describe as "the images reload".
+
+So the rule is about identity:
+
+- **Key a row by the record, never by its position.** `key={i}` is correct only for a list
+  that cannot reorder or grow. The moment something can be inserted, an index key hands
+  every row a different slot and React rebuilds all of them. This applies to any wrapper
+  you put around a mapped child too — a container keyed by index destroys the identity its
+  child was carrying.
+- **Don't define a component inside another component's render.** Its type changes every
+  render, so its whole subtree remounts.
+- **Don't swap a list for a placeholder on refetch.** `loading ? <Skeleton/> : <Rows/>`
+  belongs to the FIRST load only — gate it on having no rows yet, never on a request being
+  in flight, or every background refresh unmounts the content and remounts it.
+
+**Reach for `memo` last, and only with a measurement.** It prevents a re-render, which is
+the cheap half, and it silently does nothing when a prop is a fresh object each render —
+which is the normal case, since rows come from a `useMemo` over query results. Where a list
+is genuinely large enough to hurt, window the rows; that removes the work rather than
+comparing it. `toDisplayFile` returns a new object per call for exactly this reason: an
+identity cache would exist to enable a memo that measurement does not justify.
+
 ## `accessibilityState` never reaches the DOM — write `aria-*` yourself
 
 React Native Web maps a subset of RN's accessibility props and **silently drops

package/docs/reviewing.md

@@ -595,6 +595,34 @@ a second copy free to disagree — check it against the FIELD, not against itsel
 
 → [data_entry.md](./data_entry.md) §"A picker over a select FIELD keeps the field's colours".
 
+### 9c. What the screen does when the data MOVES — the cross-frame check
+Every probe above reads ONE rendered frame. This defect does not exist in a frame: the screen is
+correct before, correct after, and destroys itself in between. A register whose rows are correct
+either side of an insert can still have rebuilt every row to get there, and each rebuilt picture
+paints EMPTY for a frame before it repaints — which is what people report as "the images reload".
+
+**Collect:** stamp the nodes, move the data, count the survivors.
+
+```js
+document.querySelectorAll("img").forEach((el, i) => { el.__s = i; });
+// …now insert a row / reorder / let a refetch land…
+const imgs = [...document.querySelectorAll("img")];
+({ total: imgs.length, survived: imgs.filter((e) => e.__s !== undefined).length })
+```
+
+**The signature** is survivors far below the rows that were already there — a row that only MOVED
+should keep its node. Only genuinely new rows may be fresh. A `MutationObserver` gives the same
+answer as a magnitude: a re-render against equal data should write NOTHING, and one insert should
+write about one row's worth.
+
+Two causes, both invisible to every other probe. A container keying its wrapped children by
+POSITION overrides the caller's correct keys, so an insert shifts every child into a different slot
+and React rebuilds all of them — the caller cannot see it or fix it from outside. And a region
+gated on a REQUEST (`loading ? <Spinner/> : <Rows/>`) rather than on having nothing yet unmounts
+its whole subtree on each background refresh.
+
+→ [composition.md](./composition.md) §"A list stays fast by keeping IDENTITY, not by memoizing".
+
 ### 10. Microcopy
 - **No punctuation doing a word's job.** ` · ` is banned outright — it claims a relationship while
   refusing to name it, and it is the loudest templated-metadata tell there is. If a mark cannot be

package/docs/testing.md

@@ -70,3 +70,26 @@ and the window are the right ones. From the dragged element,
 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.
+
+## Assert what an update KEEPS, not only what it renders
+
+A test that reads the output passes either way when a list rebuilds itself: the same rows are on
+screen, so nothing about the text is wrong. What changed is that every node was replaced — and a
+replaced `Image` paints empty before it repaints.
+
+Hold the node and compare it after the update:
+
+```tsx
+const { rerender, getByTestId } = render(board(["a", "b"]));
+const before = getByTestId("b");
+rerender(board(["new", "a", "b"]));
+expect(getByTestId("b")).toBe(before); // MOVED, not rebuilt
+```
+
+State the budget as DOM WRITES, never as a render count. Re-running a component is close to free —
+React's diff absorbs it — so counting renders fails a healthy tree and pushes the next author into
+memoising leaves that cost nothing. A `MutationObserver` around a `rerender` with equal data should
+see zero. And assert the opposite too: an insert MUST write, or a green suite only proves the
+observer was blind.
+
+→ [composition.md](./composition.md) §"A list stays fast by keeping IDENTITY, not by memoizing".

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "47.5.0",
+  "version": "47.5.2",
   "type": "module",
   "exports": {
     "./accordion": "./src/accordion.tsx",

package/src/file_thumbnail.tsx

@@ -72,6 +72,47 @@ export interface DisplayFile {
   previewUrl?: string;
 }
 
+/**
+ * The wire shape of a file cell — what a record read hands back, before it is
+ * anything a component can render.
+ *
+ * Structural, not imported: the kit stays free of platform packages, and this
+ * names only the five fields the conversion reads.
+ */
+export interface FileCell {
+  id: string;
+  filename: string;
+  mime_type: string;
+  url: string;
+  thumbnail_url?: string;
+}
+
+/**
+ * A file cell → the shape every display component here takes.
+ *
+ * It lives in the kit because it was living in every app instead: each one
+ * re-declared the same five-line mapping, so a field added here reached none of
+ * them and a `mime_type`/`mimeType` slip was a per-app bug. One definition, on
+ * the side that owns the type.
+ *
+ * It returns a NEW object per call, deliberately. An identity cache here would
+ * let callers memoize on reference, but a re-render that changes nothing
+ * already writes nothing to the DOM (`table_render_budget.test.tsx` pins it),
+ * so the cache would buy a fraction of a cheap operation and cost a map that
+ * grows for the life of the tab — presigned urls rotate, so its keys never stop
+ * accumulating. If a list ever outgrows that, the answer is windowing the rows,
+ * not remembering the objects.
+ */
+export function toDisplayFile(f: FileCell): DisplayFile {
+  return {
+    id: f.id,
+    filename: f.filename,
+    mimeType: f.mime_type,
+    url: f.url,
+    thumbnailUrl: f.thumbnail_url,
+  };
+}
+
 // =============================================================================
 // FileThumbnail - Main display component
 // =============================================================================
@@ -485,6 +526,11 @@ function ImageThumbnail(props: ImageThumbnailProps) {
   const a11yLabel = props.accessibilityLabel ?? file.filename;
   const [useFallback, setUseFallback] = useState(false);
   const { focusVisible, focusProps } = useFocusRing();
+  // STABLE, not an inline arrow. `onError` sits in react-native-web's image
+  // load effect's dependency array, so a fresh callback each render tears the
+  // pending request down and issues a new `Image()` — re-fetching a picture
+  // that never changed, on every render of the row it sits in.
+  const handleError = useCallback(() => setUseFallback(true), []);
 
   // Use thumbnail if available, fallback to full URL
   const url = !useFallback && file.thumbnailUrl ? file.thumbnailUrl : file.url;
@@ -502,7 +548,7 @@ function ImageThumbnail(props: ImageThumbnailProps) {
             source={{ uri: url }}
             style={styles.image}
             resizeMode="cover"
-            onError={() => setUseFallback(true)}
+            onError={handleError}
           />
           <TileScrim hovered={(state as { hovered?: boolean }).hovered} pressed={state.pressed} />
         </>

package/src/image_gallery.tsx

@@ -68,7 +68,12 @@ export function ImageGallery({
   // Per-image rotation, shared with the zoom modal so a turn survives opening it.
   const rotation = useImageRotation();
 
-  if (loading) return <ActivityIndicator />;
+  // FIRST load only. Gating the spinner on the request rather than on having
+  // nothing to show swaps the whole gallery for it on every revalidation —
+  // unmounting each <Image>, which then remounts empty and repaints. A caller
+  // passing `loading={isValidating}` is doing the ordinary thing; the component
+  // has to survive it.
+  if (loading && images.length === 0) return <ActivityIndicator />;
   if (images.length === 0) return <Text size="sm" color="muted">{emptyText ?? locale.imageGallery.empty}</Text>;
 
   const idx = Math.min(selected, images.length - 1);

package/src/list.tsx

@@ -15,7 +15,10 @@ export function List(props: ListProps) {
   return (
     <View style={style}>
       {childArray.map((child, index) => (
-        <React.Fragment key={index}>
+        // The child's own key, never its position: a filtered list changes
+        // membership on every keystroke, and an index key rebuilds every
+        // surviving row (see composition.md §"A list stays fast").
+        <React.Fragment key={React.isValidElement(child) ? child.key : index}>
           {child}
           {index < childArray.length - 1 && <Divider />}
         </React.Fragment>

package/src/popover.tsx

@@ -433,6 +433,34 @@ export function PopoverContent(props: PopoverContentProps) {
     return () => document.removeEventListener("click", onOutsideClick, true);
   }, [open, small, onOpenChange, triggerRef]);
 
+  // The one press the click listener above CANNOT see: one that lands inside a
+  // cross-origin iframe. Those events are dispatched in the frame's own document
+  // and never cross into this one, so a popover anchored over an embedded app —
+  // the app page's own chrome is exactly this shape — stayed open while the user
+  // clicked around underneath it, with no way to dismiss but pressing the trigger
+  // again or hitting Escape.
+  //
+  // Focus is the signal that survives the boundary: clicking into a frame moves
+  // this document's `activeElement` to the IFRAME element and blurs the window.
+  //
+  // Checking `activeElement` is what keeps this from over-firing. A window blur
+  // alone also means "switched tab" or "moved to another app", and dismissing
+  // then is a menu that quietly disappears while the user was reading something
+  // else. Only a blur that HANDED FOCUS TO A FRAME is a press we missed.
+  useEffect(() => {
+    if (!open || small) return;
+    const onWindowBlur = () => {
+      // Deferred: at blur time the browser has not always moved `activeElement`
+      // to the frame yet, so reading it synchronously can still report the
+      // trigger and miss the dismissal entirely.
+      setTimeout(() => {
+        if (document.activeElement instanceof HTMLIFrameElement) onOpenChange(false);
+      }, 0);
+    };
+    window.addEventListener("blur", onWindowBlur);
+    return () => window.removeEventListener("blur", onWindowBlur);
+  }, [open, small, onOpenChange]);
+
   const calculatePosition = useCallback(() => {
     if (!popoverRef.current) return;
     if (small) return;

package/src/section_stack.tsx

@@ -1,4 +1,4 @@
-import { Children, Fragment } from "react";
+import { Children, Fragment, isValidElement } from "react";
 import { View, type StyleProp, type ViewStyle } from "react-native";
 import { Divider } from "./divider";
 
@@ -17,9 +17,11 @@ function DividedStack({ children, divided = true, gap, style }: StackProps & { g
   return (
     <View style={[{ gap }, style]}>
       {blocks.map((block, i) => (
-        // Children.toArray keys are stable for conditional lists; the fragment
-        // pairs each block with the hairline that separates it from the last.
-        <Fragment key={`sec_${i}`}>
+        // Children.toArray keys are stable for conditional lists — so USE
+        // them. `toArray` drops nulls, so a conditional section appearing
+        // shifts every later index and an index key would remount all of
+        // them, including any field mid-edit.
+        <Fragment key={isValidElement(block) ? block.key : `sec_${i}`}>
           {divided && i > 0 ? <Divider /> : null}
           {block}
         </Fragment>

package/src/sequence.tsx

@@ -62,7 +62,11 @@ export function Sequence({ children }: SequenceProps) {
     // which the rail runs through.
     <View>
       {items.map((child, index) => (
-        <SequenceItemContext.Provider key={index} value={{ index, count: items.length }}>
+        // The child's own key, never its position. This list REORDERS by
+        // design, and a Provider keyed by index makes "move up" tear both
+        // items down — losing the text a person was part-way through typing
+        // in them (see composition.md §"A list stays fast").
+        <SequenceItemContext.Provider key={child.key ?? index} value={{ index, count: items.length }}>
           {child}
         </SequenceItemContext.Provider>
       ))}

package/src/stack.tsx

@@ -28,7 +28,10 @@ export function Stack(props: StackProps) {
         children,
         (child, index) =>
           child && (
-            <View key={index}>
+            // NO key: `Children.map` already composes the child's own key
+            // onto what it returns. Adding one here overrides that with the
+            // position and remounts the list whenever it changes.
+            <View>
               {child}
               {useSeparator && index < React.Children.count(children) - 1 && (
                 <Separator padding={separatorPadding} />

package/src/table.tsx

@@ -281,11 +281,15 @@ export function Table(props: TableProps) {
           </View>
         )}
         <View style={styles.body}>
-          {rows.map((row, i) => {
-            return (
-              <View key={i}>{row}</View>
-            );
-          })}
+          {/* Keyed by the ROW's own key, never its index. `Children.toArray`
+              derives these from the caller's `key`, so they track the record
+              rather than the position. Keyed by index, inserting a row at the
+              top shifts every row into a different wrapper: React then sees a
+              new child key inside each one and remounts the whole list, which
+              destroys every `<Image>` and repaints the register blank. */}
+          {rows.map((row, i) => (
+            <View key={row.key ?? i}>{row}</View>
+          ))}
         </View>
       </View>
     </TableContext.Provider>
@@ -356,8 +360,9 @@ export function TableGroup(props: TableGroupProps) {
         ) : null}
       </View>
       <View style={styles.body}>
+        {/* The row's own key, for the reason given in the wide variant above. */}
         {rows.map((row, i) => (
-          <View key={i}>{row}</View>
+          <View key={row.key ?? i}>{row}</View>
         ))}
       </View>
     </View>