@lotics/ui 47.4.0 → 47.5.0

package/AGENTS.md

@@ -14,10 +14,10 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 
 | Doc | Read it for |
 |---|---|
-| [docs/catalog.md](./docs/catalog.md) | **The complete inventory** — 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/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), and where a commit sits. |
+| [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/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

@@ -298,6 +298,15 @@ by size.)
   ordinary case, not an exotic one; compose a hand-designed
   card pile (`PressableRow` + your own hierarchy) over `useScreenSize` only when a screen
   deserves a better mobile shape than the automatic stack.
+  **A row that LANDS while someone is looking takes `justArrived`**, paired with
+  `useJustArrived(ids, scope)` from `@lotics/ui/just_arrived` — the push that delivers it is
+  otherwise invisible, because the list is one row longer and nothing says which one. Pass the
+  hook's set, never a hand-rolled diff: it owns the two rules that make the naive version
+  unusable — a FIRST render is not an arrival (or a register opening on two hundred rows flashes
+  all of them), and a `scope` change reseeds silently (or picking a status flashes every row the
+  filter swapped in). WRONG PLACE: it is not a way to mark a row you want the reader to notice —
+  that is `marked`, or a badge in a cell. The question that decides it is *did this row exist a
+  moment ago*; if the answer does not change on its own, this is not the prop.
 - **Inline-managed grouped table** (MODERATE — hundreds, low-thousands — you MANAGE in view)
   — the `DataGrid` primitive: a grouped, sortable grid whose cells are LIVE inline editors
   (ANY field — a column is `{ key, label, width?, sortable?, cell: (item) => ReactNode }`,

package/docs/composition.md

@@ -1623,6 +1623,15 @@ Deciding from the CONTENT instead — prose gets `sm`, reference data gets `xs`
 that holds both. An account name beside a contract number is one line, and it takes ONE rung: the
 pair's, not each half's.
 
+**That line takes a REFERENCE, never a sentence.** It is what tells two rows with the same subject
+apart — a code, a counterparty, a date — so it is short by nature and survives every width. A
+sentence put there truncates to its opening clause in any column narrow enough to be a column, and
+the opening clause of an explanation is the half the reader already knew: *"Reordered after the
+downtown branch's…"*. It measures as an ordinary truncation and reads as a row that says nothing.
+The sentence is not homeless — a reason, a note, a hand-typed instruction belongs in what the row
+OPENS, beside the values it explains, where a full line is available. Where a row has no detail to
+open, the sentence is telling you the register wanted one.
+
 **A STACKED PAIR takes `leading="tight"` — it is not prose.** The ramp's body rungs carry prose
 leading (14/24, ratio 1.71), which is right for a paragraph and wrong for two lines that are one
 object: it leaves ~10px of empty box between them, so the pair reads as two separate lines. Beside

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "47.4.0",
+  "version": "47.5.0",
   "type": "module",
   "exports": {
     "./accordion": "./src/accordion.tsx",
@@ -159,6 +159,7 @@
     "./inset": "./src/inset.tsx",
     "./interaction_modality": "./src/interaction_modality.ts",
     "./json_panel": "./src/json_panel.tsx",
+    "./just_arrived": "./src/just_arrived.ts",
     "./keyboard": "./src/keyboard.ts",
     "./kpi_card": "./src/kpi_card.tsx",
     "./kpi_strip": "./src/kpi_strip.tsx",

package/src/just_arrived.ts

@@ -0,0 +1,70 @@
+import { useEffect, useRef, useState } from "react";
+
+/** Shared so an unchanged result keeps its identity and re-renders nothing. */
+const EMPTY: ReadonlySet<string> = new Set<string>();
+
+/**
+ * Which ids are new, given what was on screen before — the rule, without React.
+ *
+ * `before` is `null` when nothing has been seen yet, and that case is the whole
+ * reason this is a named function: **a first render is never an arrival.** A
+ * register opening on two hundred rows has two hundred ids it has not seen, and
+ * the naive diff flashes all of them — both wrong (nothing arrived, the page
+ * loaded) and the moment a highlight is least wanted.
+ *
+ * A removal reports nothing. A row leaving is not a row arriving, and the two
+ * share a diff only if you write it carelessly.
+ */
+export function arrivalsSince(
+  before: ReadonlySet<string> | null,
+  ids: readonly string[],
+): string[] {
+  if (before === null) return [];
+  return ids.filter((id) => !before.has(id));
+}
+
+/**
+ * Which of these ids are NEW since the last render — the set a register passes
+ * to `TableRow`'s `justArrived`.
+ *
+ * A row landing while someone is looking at the screen is the case the realtime
+ * push exists for, and until something marks it the push is invisible: the list
+ * is one row longer and nothing says which one. Every register wants the same
+ * diff, so it lives here rather than in each app.
+ *
+ * **`scope` is what the ids are a list OF** — the filter, the search, the page.
+ * Without it a register cannot tell twelve rows ARRIVING from a filter change
+ * that replaced the list, because both are a large diff, and it would flash the
+ * whole page every time someone picked a status. Change the scope and the
+ * baseline reseeds silently: nothing arrived, the reader asked a different
+ * question. Pass a string that changes exactly when the QUESTION does.
+ *
+ * An EMPTY render never seeds the baseline either: a list rendering `[]` while
+ * its query is in flight would otherwise make its real first page look like an
+ * arrival.
+ *
+ * Ids leave the set on the next render that carries them, so the highlight is a
+ * one-shot — re-rendering never restarts an animation that already played.
+ */
+export function useJustArrived(ids: readonly string[], scope = ""): ReadonlySet<string> {
+  const seen = useRef<Set<string> | null>(null);
+  const seenScope = useRef(scope);
+  const [fresh, setFresh] = useState<ReadonlySet<string>>(EMPTY);
+
+  // Keyed on the ids' CONTENT: an array literal is a new reference every render,
+  // so depending on the array itself would re-run this forever.
+  const key = ids.join(",");
+
+  useEffect(() => {
+    if (ids.length === 0) return;
+    const sameQuestion = seenScope.current === scope;
+    seenScope.current = scope;
+    const added = arrivalsSince(sameQuestion ? seen.current : null, ids);
+    seen.current = new Set(ids);
+    setFresh(added.length > 0 ? new Set(added) : EMPTY);
+    // `ids` is covered by `key`, which is its content rather than its identity.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key, scope]);
+
+  return fresh;
+}

package/src/table.tsx

@@ -1,6 +1,8 @@
 import {
   createContext,
   useContext,
+  useEffect,
+  useRef,
   useState,
   Children,
   cloneElement,
@@ -8,7 +10,7 @@ import {
   type ReactNode,
   type ReactElement,
 } from "react";
-import { StyleSheet, View, type ViewStyle } from "react-native";
+import { Animated, StyleSheet, View, type ViewStyle } from "react-native";
 import { Text } from "./text";
 import { colors, solid, type ColorName } from "./colors";
 import { PressableRow } from "./pressable_row";
@@ -16,6 +18,13 @@ import { PressDoor } from "./press_door";
 import { DetailRow } from "./detail_row";
 import { SortHeader, type SortState, type SortHeaderLabels } from "./sort_header";
 import { COLUMN_GAP, ROW_GUTTER, ROW_HEIGHT, computeTableFit, type TableFit, type TableFitColumn } from "./table_fit";
+
+/** How long an arrival wash sits at full strength before fading, and how long
+ *  the fade takes. Together they are the window a reader has to notice the row —
+ *  short enough that a busy register does not shimmer, long enough to survive a
+ *  glance away. */
+const ARRIVAL_HOLD_MS = 900;
+const ARRIVAL_FADE_MS = 700;
 import { ROW_WASH_BLEED } from "./control_surface";
 
 /**
@@ -359,6 +368,21 @@ export type TableRowProps = {
   selected?: boolean;
   /** Part of a multi-select set — a resting blue tint (the open/hover wash overrides it). */
   marked?: boolean;
+  /**
+   * This row LANDED — it was not here a moment ago. Plays a wash that fades out
+   * once, so a reader looking at the register when the push arrives can see
+   * which row is the new one.
+   *
+   * Pair it with `useJustArrived`, which owns the diff and the rule that a first
+   * render is never an arrival. Passing it per-row from a hand-rolled diff is
+   * how a register ends up flashing all two hundred rows on load.
+   *
+   * It is an OVERLAY, not a fifth interaction state: `backgroundColor` on this
+   * row already has one owner (hover / selected / marked / pressed), and a
+   * second writer would make the two agree only by luck. So an arrival composes
+   * with all of them — a new row you are hovering shows both.
+   */
+  justArrived?: boolean;
   /** Outside the door, BEFORE the cells (a selection checkbox) — width = Table `leading`. */
   leading?: ReactNode;
   /**
@@ -452,8 +476,46 @@ export type TableRowProps = {
  * the remaining cells as label-over-value blocks — same door, same wash, same
  * slots, different geometry.
  */
+/**
+ * The one-shot wash a row wears when it has just landed.
+ *
+ * OPACITY, never `backgroundColor` — that property belongs to the row's four
+ * interaction states, and a second writer would make them agree only by accident
+ * (see `pressable_row`). Fading an overlay composes with all four instead, and
+ * opacity is what `useNativeDriver` can animate off the JS thread, which matters
+ * on the surface most likely to be rendering two hundred rows.
+ *
+ * `accent_wash` is the token the kit reserves for ATTENTION — a drop target
+ * lighting up — as distinct from the neutral grounds that say which record is
+ * open. A row that arrived while you were looking at it is exactly that.
+ *
+ * It renders nothing until it has something to say, so an ordinary register pays
+ * no extra view per row, and it never takes a press.
+ */
+function ArrivalWash({ on }: { on: boolean }) {
+  const fade = useRef(new Animated.Value(0)).current;
+  const [live, setLive] = useState(false);
+
+  useEffect(() => {
+    if (!on) return;
+    setLive(true);
+    fade.setValue(1);
+    // Held, THEN faded: a wash that begins mid-fade reads as a rendering
+    // artefact rather than as something arriving.
+    Animated.sequence([
+      Animated.delay(ARRIVAL_HOLD_MS),
+      Animated.timing(fade, { toValue: 0, duration: ARRIVAL_FADE_MS, useNativeDriver: true }),
+    ]).start(({ finished }) => {
+      if (finished) setLive(false);
+    });
+  }, [on, fade]);
+
+  if (!live) return null;
+  return <Animated.View pointerEvents="none" style={[styles.arrival, { opacity: fade }]} />;
+}
+
 export function TableRow(props: TableRowProps) {
-  const { onPress, selected, marked, accessibilityLabel, leading, ordinal, trailing, action, minHeight, detail, expanded, children } = props;
+  const { onPress, selected, marked, justArrived, accessibilityLabel, leading, ordinal, trailing, action, minHeight, detail, expanded, children } = props;
   const ctx = useContext(TableContext);
   if (!ctx) throw new Error("TableRow must be used within a Table");
   // Read AFTER the context check so an airy register does not need every row to
@@ -522,6 +584,7 @@ export function TableRow(props: TableRowProps) {
 
   const rowSurface = (
     <PressableRow onPress={onPress} selected={selected || showDetail} marked={marked} style={styles.row}>
+      <ArrivalWash on={justArrived === true} />
       {!ctx.stacked ? <LeadGutter ordinal={ordinal}>{leading}</LeadGutter> : null}
       {/* The door hit-tests above in-flow content; the cells/slots lift back above it
           via zIndex 1 (see `PressDoor`), so the door gets only the keyboard. Radius
@@ -597,6 +660,15 @@ export function TableCell(props: TableCellProps) {
 }
 
 const styles = StyleSheet.create({
+  arrival: {
+    position: "absolute",
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    borderRadius: 12,
+    backgroundColor: colors.accent_wash,
+  },
   // The expanded detail. Indented to the identity column's text edge so it reads
   // as belonging to the row above rather than as a new row, and given the row's
   // own gutter so its content lines up with the cells it explains.