@lotics/ui 47.3.0 → 47.4.1

package/AGENTS.md

@@ -17,7 +17,7 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 | [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/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

@@ -1125,8 +1125,14 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   choice. → `data_entry.md` §"Choosing a CHOICE control" — and check the states really ARE
   exclusive: independent capabilities that happen to be exclusive today bake today's
   combinations into the type.
-- **`chip_group`** — `ChipGroup`: pill single-select over a small visible set. → `data_entry.md`
-  §"Choosing a CHOICE control" for which control the count and the job call for.
+- **`chip_group`** — `ChipGroup`: pill single-select over a small visible set. The row wraps by
+  default; `overflow="scroll"` keeps it to ONE row for a register FILTER, where six options
+  carrying counts wrap to three rows — 136px on a phone, more than the search band and the view
+  switcher combined. Deliberately NOT a screen-width branch: width is not the question, the job
+  is, and both jobs occur at every width. Never `scroll` on a form field or a view control —
+  chips are worth more than a `Picker` there only because every option is visible, and a swipe
+  is exactly what takes that away. → `data_entry.md` §"Choosing a CHOICE control" for which
+  control the count and the job call for.
 - **`checkbox`** — `Checkbox`: the bare square check control. Bare means UNLABELLED — reach for
   `CheckboxInput` unless something else already names it (a table's select-all, a row's
   leading slot). A square means CHOSEN; a ring means DONE, and spending the wrong one teaches a

package/docs/composition.md

@@ -1015,7 +1015,9 @@ by what KIND of thing they are.
   stays one consistent band. Never a bare `TextInputField` + search icon.
 - **`ChipGroup`** is THE one-of-N lens (≤ ~10 options the user flips between; include "All";
   counts in the label). Filters ONE list to a SUBSET — including by process stage / lifecycle
-  state.
+  state. As a FILTER above a register it takes `overflow="scroll"` and costs one row on a phone
+  instead of three; a VIEW CONTROL ("how are they arranged") and a form field keep the default
+  wrap. The line is the toolbar's own — which rows vs how they are arranged — not a width.
 - **`FilterChip`** is THE secondary-dimension filter — a compact chip that opens a composed
   popover editor (`OptionList` multi / `Slider range` / `Counter` / date range). Single-select
   closes on pick via the `{({ close }) => …}` render prop.
@@ -1621,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.3.0",
+  "version": "47.4.1",
   "type": "module",
   "exports": {
     "./accordion": "./src/accordion.tsx",

package/src/chip_group.tsx

@@ -1,4 +1,4 @@
-import { StyleSheet, View, type ViewStyle } from "react-native";
+import { ScrollView, StyleSheet, View, type ViewStyle } from "react-native";
 import { colors } from "./colors";
 import { Icon, type IconName } from "./icon";
 import { solid, type ColorName } from "./colors";
@@ -6,8 +6,9 @@ import { Text } from "./text";
 import { PressableHighlight } from "./pressable_highlight";
 import { chipSurfaceStyle } from "./control_surface";
 
-// One-of-N chips: every option visible, one tap to switch, the row wraps on
-// narrow widths. Quiet zinc styling — bordered white at rest, and the active one
+// One-of-N chips: every option visible, one tap to switch. The row WRAPS by
+// default; a hot filter with many options passes `overflow="scroll"` to keep
+// itself to one row. Quiet zinc styling — bordered white at rest, and the active one
 // keeps that same ground and takes a doubled zinc-900 EDGE instead, so a
 // selection never spends the brand and never speaks the row's language (the
 // reasoning is on `chipSurfaceStyle`). Colour stays reserved for status +
@@ -76,12 +77,34 @@ export interface ChipGroupProps<T extends string = string> {
    *  yet) is valid. */
   value: T;
   onValueChange: (value: T) => void;
+  /**
+   * What the row does when it runs out of width.
+   *
+   * `"wrap"` (the default) keeps EVERY option on screen, which is the whole
+   * reason a form field or a composer reaches for chips instead of a `Picker` —
+   * a required single-select that hides half its values behind a swipe is a
+   * worse `Picker`, not a better one. Those sets are 2-3 short options and fit
+   * a phone anyway.
+   *
+   * `"scroll"` is for the other job: a HOT FILTER above a register, where the
+   * set is long enough and the labels carry counts. Six status options wrap to
+   * THREE ROWS at 390px — 136px, more than the search band and the view
+   * switcher combined, and the largest single block above the first record.
+   * One row costs 40px; the leading options stay a tap away and the tail is a
+   * swipe.
+   *
+   * Not derived from screen width, because width is not the question — the JOB
+   * is, and both jobs occur at every width. A `ScrollView` whose content fits
+   * does not scroll, so this is a no-op on a desktop either way.
+   */
+  overflow?: "wrap" | "scroll";
 }
 
 export function ChipGroup<T extends string = string>(props: ChipGroupProps<T>) {
-  const { accessibilityLabel, options, value, onValueChange } = props;
-  return (
-    <View style={{ flexDirection: "row", alignItems: "center", flexWrap: "wrap", gap: 8 }}>
+  const { accessibilityLabel, options, value, onValueChange, overflow = "wrap" } = props;
+
+  const inner = (
+    <>
       {options.map((option) => {
         const active = option.value === value;
         return (
@@ -140,11 +163,22 @@ export function ChipGroup<T extends string = string>(props: ChipGroupProps<T>) {
           </PressableHighlight>
         );
       })}
-    </View>
+    </>
+  );
+
+  return overflow === "scroll" ? (
+    <ScrollView horizontal showsHorizontalScrollIndicator={false} contentContainerStyle={styles.scrollRow}>
+      {inner}
+    </ScrollView>
+  ) : (
+    <View style={styles.wrapRow}>{inner}</View>
   );
 }
 
 const styles = StyleSheet.create({
+  wrapRow: { flexDirection: "row", alignItems: "center", flexWrap: "wrap", gap: 8 },
+  // paddingRight so the last chip does not sit flush against the edge mid-scroll
+  scrollRow: { flexDirection: "row", alignItems: "center", gap: 8, paddingRight: 8 },
   dot: { width: 6, height: 6, borderRadius: 3 },
   chip: {
     flexDirection: "row",