@lotics/ui 47.6.1 → 47.7.1

package/AGENTS.md

@@ -18,7 +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, 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 (`Finding` is filed here because AI produces most of them, NOT because it is AI-only — a rules-derived contradiction is as in scope as an extraction's); **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), **an identity mark's GLYPH is derived from the name's distinguishing part** (an organization's first word is its legal form, so untreated every row marks one letter), **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) the first-line drift a column shows when its cell is sometimes one line and sometimes two, 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/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) the first-line drift a column shows when its cell is sometimes one line and sometimes two, the cross-FRAME check (what the screen destroys when a row arrives — the one defect that exists in no single frame), and the semantic-section check (a danger or empty section drawn as an ordinary one, and the primitive nobody reached for). 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

@@ -1045,8 +1045,11 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`card_select_item`** — `CardSelectItem`: a bordered, card-shaped button; `selected` =
   persistent ring (reads as `aria-pressed`) — the org-picker / entity-switcher item.
 - **`switcher`** — `Switcher`: current-item trigger opening a popover of `MenuButton` items
-  (`SwitcherItem { id, label }`, `currentId`, `onSelect`) — the compact entity/workspace
-  switcher.
+  (`SwitcherItem { id, label, imageUri? }`, `currentId`, `onSelect`) — the compact
+  entity/workspace switcher. A square `Avatar` appears on the trigger and every row as soon as
+  ONE item carries `imageUri`, the rest falling back to initials, so an unpictured entry still
+  lines up. `minItemsToRender` defaults to 2 (a single choice is clutter); lower it to 1 where
+  the switcher states a scope the reader has no other way to see.
 - **`count`** — `Count`: a 20px count disc that grows into a pill past one digit (`color` highlight|muted|red).
 - **`shortcut_badge`** — `ShortcutBadge`: the keycap hint pill — a zinc-50 badge rendering a
   shortcut from a raw string or `ShortcutDescriptor` (⌘B on Mac, Ctrl+B elsewhere); null on
@@ -1672,7 +1675,8 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   **The row OWNS its `title`/`description` pair, so do not hand-roll one beside it.** Both
   lines are `sm`, `leading="tight"`, no gap between them — the stacked-pair law in
   [composition.md](./composition.md), applied by the component rather than restated at each
-  call site. The row is 56.
+  call site. The row's floor is 64 — 12 a side around a tight pair and an `md` leading mark —
+  and it grows for a `description` node taller than a line.
   A `description` passed as a NODE keeps its own leading — the component only sets it on the
   string branch, because forcing a line box on somebody else's subtree re-spaces content that
   may not be a line of text at all.
@@ -1772,7 +1776,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   opened the screen for. Pass `activeCount` so the collapsed button still says the list is
   filtered, and `onClearAll` to put one clear in the sheet. Compose the band with this rather
   than a hand-rolled `<View flexDirection="row">`: a hand-rolled band is the one that does not
-  collapse.
+  collapse. **A facet with nothing to offer should render `null`, and the band then draws no
+  trigger at all** — narrow as well as wide. Gate each chip on its own options (a status filter
+  whose values are all already in view, a round picker before any round is recorded) rather than
+  shipping an empty one; search and the action stay on the band either way.
 - **`filter_chip`** — `FilterChip` + `selectSummary`: the toolbar filter pill hosting a
   facet (options, a `Slider range`, a `Counter`). It draws NO bottom band of its own — the ×
   on the pill is the clear, and the editor inside brings whatever actions it has, so a

package/docs/composition.md

@@ -1751,6 +1751,22 @@ The hit area is unchanged — it paints outside the box rather than growing it
 where it would if the control were not there. The same applies to any verb riding a value: a
 `CopyButton`, an `InlineButton`, a count chip.
 
+## "Who can reach this" is drawn as MARKS, on every surface that asks it
+
+Access is a set of people, so it renders as `AvatarGroup` — a register cell, a settings row, a
+detail header. A word in place of the marks (`Shared`, `2 people`) answers a smaller question than
+the faces do: it says THAT the thing is shared without saying WITH WHOM, which is the half the
+reader opened the screen for, and it puts one datum in two treatments the moment any other surface
+draws the marks.
+
+The one case marks cannot carry is the whole organization: "everyone" is not a set you can show
+three of, and the three that happen to sort first would say something false about who else is in
+there. That gets an icon and a word.
+
+Whether the OWNER is among the marks is the caller's decision, not a flag on the component — a
+register with its own owner column passes the shares alone, a list without one leads with the
+owner. Compose it; a boolean would make one component answer two questions.
+
 ## Identity marks — a mark that is the same on every row carries nothing
 
 `Avatar` derives its ground from the NAME (`avatar_tone`), and takes `shape="circle" | "square"`

package/docs/reviewing.md

@@ -232,6 +232,13 @@ reads as one cluster. One `gap` on a container makes every child a peer; wrap th
 space the groups. Worst where both items are small grey glyphs on one line, because nothing but
 spacing distinguishes them.
 
+**The inverted case is easiest to measure and easiest to miss: a control sitting directly on a
+list.** An action above a `List` with nothing between them measures 0, against the 1px divider
+INSIDE the list — so the boundary between two different things is smaller than the boundary
+between two rows of one thing, and the button reads as the list's first row. Measure the CTA's
+bottom against the first row's top on any panel built as *action, then list*; it is a per-screen
+defect, so finding it on one panel is a reason to sweep the siblings.
+
 → [composition.md](./composition.md) §"Touch & whitespace".
 
 ### 5. State diff
@@ -675,6 +682,27 @@ its whole subtree on each background refresh.
 
 → [composition.md](./composition.md) §"A list stays fast by keeping IDENTITY, not by memoizing".
 
+### 9d. A SEMANTIC section drawn as an ordinary one — and the primitive nobody reached for
+Probes 1 and 2 group by shape and find each group internally consistent. The defect neither sees
+is a section whose MEANING is special — destructive, warning, empty, generated — rendered in the
+same heading treatment, on the same ground, as the ordinary sections beside it. Every measurement
+passes, and the meaning is carried by the heading's WORDS alone: delete the word "Danger" and
+nothing on screen still says it.
+
+**Collect**, per section on the surface: heading `rung / weight / ink`, the section's own
+background and border, and the treatment of the action inside it. **The signature** is a
+semantically-marked section byte-identical to its neighbours — and, downstream of that, its
+action reading as the FAINTEST control on a screen whose ordinary Save is solid (probe 2's
+singleton ground, arrived at from the other end).
+
+**The cheaper detection is structural: grep the kit for a component named after the meaning
+before composing one.** A section the kit already ships — `DangerZone`, `EmptyState` — hand-rolled
+out of a divider, a heading and a button loses more than its treatment: it loses the SLOTS the
+primitive requires, which is why hand-rolled destructive sections routinely carry no consequence
+line at all. If a screen's section has a name, that name is the thing to search for. And a
+component that exists and is used NOWHERE is the same finding seen from the kit's side — worth a
+sweep, not a second copy.
+
 ### 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/package.json

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

package/src/filter_band.tsx

@@ -1,4 +1,4 @@
-import { createContext, useContext, useState, type ReactNode } from "react";
+import { Children, createContext, useContext, useState, type ReactNode } from "react";
 import { View } from "react-native";
 import { Button } from "./button";
 import { Dialog, DialogFooter, DialogHeader, DialogHeaderTitle, DialogScrollArea } from "./dialog";
@@ -58,6 +58,14 @@ export function FilterBand(props: FilterBandProps) {
   const t = useLoticsLocale().filterBand;
   const { small } = useScreenSize();
   const [open, setOpen] = useState(false);
+  // WHETHER THERE IS ANYTHING TO COLLAPSE. `Children.toArray` drops the nulls a
+  // caller renders for a facet that has nothing to offer — a status filter whose
+  // options are all in view, a round picker before any round is recorded — so a
+  // band that draws no chips wide must not draw a button narrow. It did: the wide
+  // branch renders `children` and gets nothing, the narrow one rendered the
+  // trigger unconditionally, and the two presentations stopped agreeing at exactly
+  // the width where a control that opens an empty sheet costs the most.
+  const hasFilters = Children.toArray(children).length > 0;
 
   if (!small) {
     return (
@@ -77,14 +85,16 @@ export function FilterBand(props: FilterBandProps) {
   return (
     <View testID={testID} style={{ flexDirection: "row", alignItems: "center", gap: SPACE.sm }}>
       {search != null && <View style={{ flexGrow: 1, flexShrink: 1, minWidth: 0 }}>{search}</View>}
-      <Button
-        color="secondary"
-        title={activeCount > 0 ? `${t.filters} (${activeCount})` : t.filters}
-        onPress={() => setOpen(true)}
-        testID={testID ? `${testID}-filters` : undefined}
-      />
+      {hasFilters && (
+        <Button
+          color="secondary"
+          title={activeCount > 0 ? `${t.filters} (${activeCount})` : t.filters}
+          onPress={() => setOpen(true)}
+          testID={testID ? `${testID}-filters` : undefined}
+        />
+      )}
       {action}
-      <Dialog open={open} onOpenChange={setOpen} width="92%" maxWidth={520}>
+      <Dialog open={open && hasFilters} onOpenChange={setOpen} width="92%" maxWidth={520}>
         <DialogHeader>
           <DialogHeaderTitle>{t.filters}</DialogHeaderTitle>
         </DialogHeader>

package/src/list_item.tsx

@@ -171,18 +171,17 @@ function PressRow(props: {
 }
 
 const styles = StyleSheet.create({
-  // 56, not 64. The height was sized around a pair rendered as prose — two 24px
-  // boxes plus a 2px gap is 50, and 64 left 14px of slack the row did not ask
-  // for, which is what made a correctly-sized `md` mark (28px, the documented
-  // rung for a person in a list) look adrift in it. A tight pair is 40, so 56
-  // gives it the same 8-a-side the rest of the kit's rows carry. A title-only
-  // row keeps one 20px line centred in the same box, so the two shapes still
-  // share a beat.
+  // 64 around a tight pair of 40 and an `md` (28px) leading mark — 12 a side,
+  // which is what lets a settings list of identity rows read as a list rather
+  // than a table. A title-only row keeps one 20px line centred in the same box,
+  // so the two shapes share a beat. `minHeight`, not `height`: a `description`
+  // node the caller supplies (a chip row, two stacked facts) is taller than a
+  // line of text, and a fixed height clips it.
   container: {
     flexDirection: "row",
     alignItems: "center",
     gap: 8,
-    height: 56,
+    minHeight: 64,
     paddingHorizontal: 8,
     marginHorizontal: -8,
     borderRadius: 12,

package/src/switcher.tsx

@@ -1,5 +1,6 @@
 import React, { useCallback, useState } from "react";
 import { StyleSheet } from "react-native";
+import { Avatar } from "./avatar";
 import { Icon } from "./icon";
 import { MenuButton } from "./menu_button";
 import { PressableHighlight } from "./pressable_highlight";
@@ -12,6 +13,15 @@ import { CONTROL_HEIGHT, CONTROL_RADIUS } from "./control_surface";
 export interface SwitcherItem {
   id: string;
   label: string;
+  /**
+   * An identity image for this item. Optional, and optional PER ITEM rather than
+   * per switcher: the marks appear as soon as ONE item carries an image, and an
+   * item without one falls back to `Avatar`'s initials. Letting the mark appear
+   * only on the items that have a picture is the alternative, and it shifts every
+   * unmarked label sideways — so the one entry nobody has photographed is also the
+   * one that stops lining up with the rest of the list.
+   */
+  imageUri?: string;
 }
 
 interface SwitcherProps {
@@ -61,17 +71,29 @@ export function Switcher(props: SwitcherProps) {
     [currentId, onSelect],
   );
 
-  if (items.length < minItemsToRender) return null;
+  // `minItemsToRender` can be lowered to 1 — a switcher that always shows is how a
+  // hard scope tells the reader which one they are in — so the empty set is the
+  // only one left to answer for, and there is nothing to render for it.
+  if (items.length === 0 || items.length < minItemsToRender) return null;
 
-  const current = items.find((item) => item.id === currentId);
-  const label = current?.label ?? items[0].label;
+  const current = items.find((item) => item.id === currentId) ?? items[0];
+  const withMarks = items.some((item) => item.imageUri);
+  // The `md` rung is `CONTROL_CONTENT_HEIGHT` — what a 40px band seats, which
+  // both the trigger and a `MenuButton` row are. `square`, because the things a
+  // switcher switches BETWEEN are organizations, workspaces and projects; a disc
+  // would file them as people.
+  const mark = (item: SwitcherItem) =>
+    withMarks ? (
+      <Avatar shape="square" size="md" name={item.label} source={item.imageUri ? { uri: item.imageUri } : undefined} />
+    ) : undefined;
 
   return (
     <Popover open={open} onOpenChange={setOpen} side={side} align={align}>
       <PopoverTrigger>
         <PressableHighlight focusRing style={[styles.trigger, { maxWidth: maxTriggerWidth }]}>
+          {mark(current)}
           <Text size="sm" weight="medium" color="muted" numberOfLines={1}>
-            {label}
+            {current.label}
           </Text>
           <Icon name="chevrons-up-down" size={14} color={colors.zinc["500"]} />
         </PressableHighlight>
@@ -81,6 +103,7 @@ export function Switcher(props: SwitcherProps) {
           {items.map((item) => (
             <MenuButton
               key={item.id}
+              icon={mark(item)}
               title={item.label}
               onPress={() => handleSelect(item.id)}
               right={