@lotics/ui 22.1.0 → 22.3.0

package/AGENTS.md

@@ -15,9 +15,9 @@ 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` for a custom-code app's `vite.config.ts`). 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, find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (the `FilesEditor` COMPOUND — 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, the commit-on-blur vs action-press ordering law (the kit gates the press — `pending_commits`). |
+| [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 (the `FilesEditor` COMPOUND — 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, 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 (modify → review-before-apply; create → save-direct + the `ResultHeader` receipt), findings, provenance, confidence; 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) |
-| [docs/composition.md](./docs/composition.md) | The design-language contract — canvas + content column, heading altitude, banded cards, register vs inset rows, master-detail `Drawer`, view controls, color discipline, typography, whitespace. |
+| [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, master-detail `Drawer`, view controls, color discipline, typography, whitespace, and how to TEST an overlay component (a `Popover`-backed surface never mounts under jsdom). |
 | [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). |
 
 ## Iron rules

package/docs/ai_patterns.md

@@ -174,9 +174,11 @@ that tool's `output-error` part and flows like a normal call — the amber dot m
 group's header goes amber too), the reason waits in the expanded Error panel; real runs retry and
 move on, so the feed doesn't dramatize it. A BREAKING error that terminates the whole run lives
 OUTSIDE `parts` (chat persists it in the message's `errors`; `useAgentRun().error` carries it) —
-pass it as the `error` prop and it renders as a terminal danger row under the transcript. Pass
-**`onRetry`** alongside it and a Retry action (a secondary `Button`) rides under that row so the
-operator can re-fire the run; omit it and the error row renders exactly as before.
+pass it as the `error` prop and it terminates the feed with an error `Callout` — a contained,
+tinted panel rather than another step row, because the run did not advance, it stopped, and it
+carries `role="alert"` so a screen reader announces it. Pass **`onRetry`** alongside it and a Retry
+action (a secondary `Button`) sits INSIDE that panel so the operator can re-fire the run; omit it
+and the panel carries the message alone.
 
 **In a bounded container, wrap it in `FollowScroll`.** An `AgentRun` streaming inside a dialog,
 drawer, or fixed-height panel grows BELOW the fold — a plain scroll container doesn't follow. Wrap

package/docs/composition.md

@@ -74,8 +74,23 @@ restyle a heading level per-page.
   section's lead group. Group leads INSIDE a subsection's rows are `md` medium at most. Do NOT
   hand-roll `Text weight="semibold"` group leads inside a section, and never promote a subsection
   to its own section-level heading just to separate it.
-- **Eyebrow / label** — `<Text size="xs" color="muted" weight="medium">`, **sentence case, NEVER
-  `transform="uppercase"`**: a small quiet label above or beside content — an artifact tag
+- **Eyebrow vs group lead — a label is one or the other, and the difference is what it
+  LABELS.** Both are hand-written `Text`; picking by feel is how a title ends up whispering.
+
+  | | Eyebrow | Group lead |
+  |---|---|---|
+  | Labels | a VALUE — beside or above it | a BLOCK — a titled sub-part of a section |
+  | Treatment | `xs` muted medium | `sm`–`md` medium (never semibold — that rung is a heading) |
+  | Examples | a metric's caption, a field name in a cell, an artifact tag ("Proposed") | "Deciding factor" over the fact it names, "Delivery" over an address stack |
+
+  The eyebrow is calibrated for DENSE surfaces — a register row, a drawer's detail stack, a
+  table cell — where a 12px label sits beside dozens of siblings and quiet is the point. On a
+  low-density surface (a single-answer page, a public result screen) the same treatment reads as
+  an afterthought: there are no siblings for it to be quiet among. A label that titles a block
+  someone must ACT on is a group lead, and `sm medium` is its floor.
+
+- **Eyebrow** — `<Text size="xs" color="muted" weight="medium">`, **sentence case, NEVER
+  `transform="uppercase"`**: a small quiet label above or beside a VALUE — an artifact tag
   ("Proposed", "Question", "Suggested edit"), a field name, a metric caption, a minor one-line
   label. **All-caps is banned** — it reads as shouting, and reflexively uppercasing every little
   label is the #1 thing that makes a surface feel templated. Sentence case + medium weight, full
@@ -566,6 +581,30 @@ Anything pressable is ≥ 40px tall (8px minimum gap between pressables). 16px b
 canvas padding, 16–20 inside bands, 10–12 between content lines. Density comes from alignment +
 hierarchy, not cramming.
 
+## 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` +
+rAF against `getBoundingClientRect`, which jsdom answers with zeroes, so the content never renders
+no matter how long you `waitFor`. That covers everything built on it: the `Combobox` listbox,
+`Select`, `Menu`, `Tooltip`, `InfoPopover`, `Peek`. The kit's own suite is pure-logic for exactly
+this reason — there is no render test for any of them.
+
+The trap is that the CONTROL works fine, so the failure looks like a wiring bug: the input takes
+its value, `aria-expanded` flips to `true`, and `role="option"` is nowhere. Time goes into
+debugging the component instead of the harness.
+
+So split the assertion:
+
+- **the decision** — whatever the selection drives (which rate is reachable, which rows survive a
+  filter) belongs in a pure module with its own test. That is where the consequential logic lives,
+  and it tests far better there: every branch, no DOM.
+- **the wiring** — that picking an option calls the handler and the screen re-renders — is a
+  browser check (`lotics app dev` + Playwright), which the quality bar requires anyway.
+
+A component test can still assert everything BEFORE the overlay opens: the empty default, the
+placeholder, the disabled state, and — often the point — what the screen refuses to claim while
+nothing is selected.
+
 ## Microcopy — content, not mechanics
 
 UI copy states WHAT something is — domain content or one real rule — never how the widget
@@ -592,6 +631,18 @@ that praises it is marketing.
   cut-off, the box misses the sailing").
 - **The deletion test**: if removing the line changes nothing for the reader, remove the line —
   `description` is optional for a reason; when no invisible truth is worth stating, omit it.
+- **NEVER join text with a middot — ` · ` is banned.** It is punctuation doing a word's job: it
+  asserts that two things are related while refusing to say how, leaving the reader to guess
+  between "and", "of", "for", "then", and "here is another fact". It is also the single loudest
+  templated-metadata tell (`5 min read · Jan 3 · Design`), and screen readers drop it, so the
+  only thing carrying the relationship vanishes. Use the mark that MEANS what you intend:
+  **`:`** for a run-in label naming its value (`Hàng hoá: <goods>`), **`( )`** for a
+  supplementary count or qualifier (`Đã đọc biểu thuế (2 bước)`), **`;`** between two related
+  clauses, **`,`** in a genuine list of like items, a real preposition when the relation is
+  semantic (`Tính thuế cho 8415.10.20`) — or a **line break plus ink contrast**, which is what
+  a middot is usually a substitute for. Facts of two different KINDS want two lines, not one
+  line with a glyph between them. (Verbatim quoted DATA keeps its own delimiters — this governs
+  copy we write, not text we reproduce.)
 - **Plain language over jargon; effect over mechanism** ("Record visibility", not "Row-Level
   Privacy") — if a term needs explaining, replace it. **One concept = one word everywhere** —
   pick the term once and reuse it on every surface.

package/docs/data_entry.md

@@ -198,6 +198,23 @@ Past two columns the label→field link breaks — MANY inputs means GROUPING in
 wrap their OWN `FormField` (and don't put a `style` on it) — for a grid cell use a bare
 `FormField style={half}` wrapping `DatePicker`/`Picker`.
 
+## Browser autofill — suppressed on search, kept on forms
+
+**A control that owns a suggestion list must suppress the browser's.** Chrome offers saved form
+values on any text input it does not recognize as opted out, and on a `Combobox` the two dropdowns
+STACK — the component's own options render behind the browser's autofill panel, which reads as a
+rendering bug in the app.
+
+The kit sets `autoComplete="off"` for you on every control whose content is a query rather than a
+personal detail: `ComboboxInput`, `SearchInput`, `ScanField`, `ColumnFilter`, and the shared
+`OptionList` search. Nothing to pass.
+
+It deliberately does NOT do this on `FormTextInput`, the inline editors, or the comment composer.
+A contact form SHOULD autofill a name, an email and a phone number — suppressing it there is a real
+usability loss, and which fields those are is the app author's call, not the kit's. Pass
+`autoComplete` yourself on a form field (`"name"`, `"tel"`, `"email"`, `"off"`); it forwards to the
+DOM input.
+
 ## Find-or-create — the `Combobox` family IS the control
 
 `Combobox` is COMPOUND: a root holds the DATA + behaviour (its internal option-list engine —

package/package.json

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

package/src/accordion.tsx

@@ -130,7 +130,12 @@ export function AccordionTitle(props: AccordionTitleProps) {
   return (
     <View style={styles.title}>
       {props.icon ? <Icon name={props.icon} size={16} color={props.iconColor ?? colors.zinc[500]} /> : null}
-      <Text size="sm" numberOfLines={1} style={styles.titleText}>
+      {/* MEDIUM, like every other row identity in the kit (`ListItem`,
+          `MenuButton`, `MenuListItem`, `DetailRow` label). This was the one
+          pressable-row title at regular weight, so in a long register — 200
+          instruments, say — the thing you scan and press carried no more weight
+          than the prose above the list. */}
+      <Text size="sm" weight="medium" numberOfLines={1} style={styles.titleText}>
         {props.children}
       </Text>
     </View>

package/src/agent_run.tsx

@@ -4,6 +4,7 @@ import { colors } from "./colors";
 import { Text } from "./text";
 import { Button } from "./button";
 import { Icon, type IconName } from "./icon";
+import { Callout, CalloutActions, CalloutText } from "./callout";
 import { Markdown } from "./markdown";
 import { JsonPanel, stringifyData } from "./json_panel";
 import { PressableHighlight } from "./pressable_highlight";
@@ -187,27 +188,44 @@ export function AgentRun(props: AgentRunProps) {
           />
         );
       })}
-      {/* A run-level BREAKING error terminates the feed with a danger row. It lives
-          outside `parts` (the stream failed), so the caller passes it explicitly.
-          A retry action rides UNDER it when the caller can restart the run. */}
+      {/* A run-level BREAKING error terminates the feed. It lives outside `parts`
+          (the stream failed), so the caller passes it explicitly.
+          A CONTAINED surface, not another step row: the run didn't advance, it
+          stopped, and a tinted panel says that at a glance where a bare red line
+          in the step gutter reads as one more step that happened to fail. It also
+          gives the retry a container — free-floating, a full-weight button in a
+          column of text reads as a stray control — and `Callout` carries
+          `role="alert"`, which the plain row did not.
+          FULL WIDTH, unlike `reasoning` / `rowDetail`: those indent to a step's
+          text column because they are that step's sub-content. This hangs under
+          no step — it is the whole run ending — so indenting it would make a
+          run-level failure read as the last step's detail. */}
       {props.error ? (
-        <View style={{ gap: 8 }}>
-          <View style={styles.row}>
-            <View style={styles.dotCol}>
-              <Icon name="circle-alert" size={17} color={colors.red[500]} />
-            </View>
-            <View style={styles.rowBody}>
-              <Text size="sm" color="danger">
-                {props.error}
-              </Text>
-            </View>
-          </View>
+        <Callout tone="error">
+          <CalloutText>{props.error}</CalloutText>
           {onRetry ? (
-            <View style={styles.retry}>
-              <Button title={locale.agentRun.retry} color="secondary" icon="rotate-ccw" alignSelf="flex-start" onPress={onRetry} />
-            </View>
+            <CalloutActions>
+              {/* PRIMARY, deliberately. `Callout` is a calm panel by design (a
+                  50 tint behind a soft 100 border), so a filled button inside it
+                  is not emphasis twice — it is the one action on a quiet
+                  surface. Every unfilled variant loses here: default and muted
+                  hover to zinc-100, a grey wash over the red tint, and
+                  danger-secondary puts red ink on a red-50 ground, the weakest
+                  contrast of the options. The run just died; the only way out
+                  should be the most legible thing in the panel.
+                  Still a Button, never a link: a link navigates, this re-fires a
+                  run, and that distinction is what a screen reader and the
+                  keyboard both rely on. */}
+              <Button
+                title={locale.agentRun.retry}
+                color="primary"
+                icon="rotate-ccw"
+                alignSelf="flex-start"
+                onPress={onRetry}
+              />
+            </CalloutActions>
           ) : null}
-        </View>
+        </Callout>
       ) : null}
     </View>
   );
@@ -365,10 +383,14 @@ function ReasoningDisclosure(props: { text: string; streaming?: boolean; expande
 
 function SummaryLabel({ label, count, stepsLabel }: { label: string; count: number; stepsLabel: (n: number) => string }) {
   return (
+    // PARENTHESES, not a middot. The count is supplementary to the action, and
+    // parentheses say so in a mark that survives text extraction and screen
+    // readers; a middot asserts a relationship without naming it, and the ink
+    // contrast here was already doing the separating anyway.
     <Text size="sm" weight="medium" numberOfLines={1}>
       {label}
       <Text size="sm" color="muted">
-        {"  ·  " + stepsLabel(count)}
+        {" (" + stepsLabel(count) + ")"}
       </Text>
     </Text>
   );
@@ -482,7 +504,4 @@ const styles = StyleSheet.create({
   reasoning: { paddingLeft: 28, paddingBottom: 4 },
   // A step's expanded I/O panels — same left edge as the reasoning body.
   rowDetail: { paddingLeft: 28, paddingBottom: 6, paddingTop: 2 },
-  // The retry action under the terminal error — aligned to the message body
-  // (past the dot column + its gap), so it reads as a response to that row.
-  retry: { paddingLeft: 28 },
 });

package/src/column_filter.tsx

@@ -118,6 +118,9 @@ export function ColumnFilter(props: ColumnFilterProps) {
     >
       {column.type === "text" ? (
           <TextInputField
+            // A filter value is never a saved personal detail, so the browser
+            // has nothing useful to offer and a dropdown to obscure the rows with.
+            autoComplete="off"
             autoFocus
             value={value?.kind === "text" ? value.query : ""}
             onChangeText={(query) => onChange({ kind: "text", query })}

package/src/combobox.tsx

@@ -389,6 +389,11 @@ export function ComboboxInput(props: ComboboxInputProps) {
         editable={!ctx.disabled}
         autoFocus={ctx.autoFocus}
         autoCapitalize="none"
+        // The browser must not open its OWN suggestion list over this one.
+        // Chrome offers saved form values on any unmarked text input, and on a
+        // control that already owns a listbox the two dropdowns stack — the
+        // component's options end up behind the browser's autofill panel.
+        autoComplete="off"
         autoCorrect={false}
         accessibilityLabel={accessibilityLabel}
         style={[

package/src/comments_thread.tsx

@@ -213,7 +213,7 @@ function CommentRow(props: CommentRowProps) {
           <Text weight="medium">{displayName}</Text>
           <Text size="sm" color="zinc-500">
             {formatTimestamp(comment.created_at)}
-            {comment.updated_at !== comment.created_at ? ` · ${labels.edited}` : ""}
+            {comment.updated_at !== comment.created_at ? ` (${labels.edited})` : ""}
           </Text>
           <Spacer size={8} />
           {isEditing ? (

package/src/option_list.tsx

@@ -68,6 +68,11 @@ export function OptionList<T extends string, MULTI extends boolean = false, D =
     <View testID={testID} style={[styles.container, small ? { flex: 1 } : { maxHeight: 480 }]}>
       {search.mode === "internal" ? (
         <TextInputField
+          // The browser must not open its OWN suggestion list over this one.
+          // Chrome offers saved form values on any unmarked text input, and on a
+          // control that already owns a listbox the two dropdowns stack — the
+          // component's options end up behind the browser's autofill panel.
+          autoComplete="off"
           icon="search"
           value={list.query}
           onChangeText={list.setQuery}

package/src/scan_field.tsx

@@ -37,6 +37,11 @@ export function ScanField(props: ScanFieldProps) {
   return (
     <View style={{ gap: 6 }}>
       <TextInputField
+        // The browser must not open its OWN suggestion list over a scan target.
+        // Chrome offers saved form values on any unmarked text input, and on a
+        // control that already owns a listbox the two dropdowns stack — the
+        // component's options end up behind the browser's autofill panel.
+        autoComplete="off"
         value={value}
         onChangeText={onChangeText}
         onSubmitEditing={onScan}

package/src/search_input.tsx

@@ -46,6 +46,11 @@ export function SearchInput(props: SearchInputProps) {
     <View style={style as ViewStyle}>
       <TextInputField
         {...rest}
+        // The browser must not open its OWN suggestion list over this one.
+        // Chrome offers saved form values on any unmarked text input, and on a
+        // control that already owns a listbox the two dropdowns stack — the
+        // component's options end up behind the browser's autofill panel.
+        autoComplete="off"
         ref={mergedRef}
         onKeyPress={handleKeyPress}
         icon="search"