@lotics/ui 11.8.3 → 11.8.4

package/AGENTS.md

@@ -6,7 +6,7 @@
 > app with two renames IN THIS ORDER: first `size="xxl"` → `size="xxxl"`, then `size="xl"` →
 > `size="xxl"` — every existing usage keeps its exact look. Also: `SectionHeadingTitle` is now
 > ALWAYS `##` (22/24), and disabled `Button`s fade their label to the zinc-400 disabled ink on
-> every variant.
+> every variant EXCEPT `primary`, which keeps inverted ink over its washed surface.
 
 The component kit for Lotics custom-code apps and the product frontend: React-Native-Web
 primitives (renders on web **and** native), data-entry patterns, AI surfaces, a composition

package/docs/catalog.md

@@ -36,7 +36,7 @@ Pick by capability, not by name. (→ the source file for the API.)
 `Button` (labelled; `title` is MANDATORY — the type blocks a title-less Button; `color` =
 emphasis/risk), `IconButton` (icon-ONLY — the circular affordance; an icon-only Button is a
 type error, so reach here. `size` `lg` 40px / `md` 28px / `sm` 24px — md/sm keep a 40px touch
-target via hitSlop — the SAME `color` palette as Button, plus `loading` and `elevated` (white
+target via hitSlop — the SAME `color` palette as Button plus `none`/`white`, plus `loading` and `elevated` (white
 fill + border + shadow, for a button sitting ON imagery — a tile's remove ✕, an overlay's
 retry); needs `accessibilityLabel`/`tooltip`), `TextLink` (underlined text that's OPTIONALLY
 an action (`onPress`) or a link (`href` — a real web anchor) — or, with neither, plain
@@ -212,7 +212,9 @@ this first for "manage a record's attachments"), `FileDropzone`, `FileRows`
 trailing ⋯ menu = Download · Open-external · Remove; the default "here are some files"
 surface), `FileGrid` (the upload-aware grid: completed files + a live upload queue in one
 surface — `FilesEditor` is this + the toolbar; reach for `FileGrid` bare when you own the
-chrome), `FileThumbnail` / `FileThumbnailGrid` (square tiles, display-only),
+chrome), `FileThumbnail` / `FileThumbnailGrid` (square tiles; `onPress`/`onFilePress` makes each
+tile a pressable door — e.g. tap-to-preview — carrying an accessible button role + filename
+label; `selectedIds` for a selection overlay),
 `UploadingThumbnail` (the single in-flight tile FileGrid renders — reach for it only when
 hand-rolling a non-grid upload layout), `FileRow` (a horizontal file/document LINE —
 badge-or-placeholder + name + meta + a composable `trailing` slot for a status badge /
@@ -578,7 +580,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   repeating the same labelWidth/trailingWidth. Worked example:
   [`tpl_record`](../examples/tpl_record.tsx).
 - **`record_summary`** — `RecordSummary`: the identity band of a record detail/drawer — ONE
-  row: `title` xl semibold tabular · `subtitle` sm muted · `status` Badge slot · optional
+  row: `title` xxl semibold tabular · `subtitle` sm muted · `status` Badge slot · optional
   `metric` {label,value,tone,note} pinned right, the band's ONE accent. The record's FIELDS
   never live in the header: compose them as `DetailTable`s in the sections below. Replaces
   hand-rolled record headers (mixed scales, several competing figures, color noise).

package/docs/data_entry.md

@@ -46,7 +46,8 @@ click away onto non-focusable space) does NOT restore — a mouse user has no ne
 preserve, and a bare `.focus()` would scroll the target into view, jerking the page (the
 restore is gated on modality via `shouldRestoreFocusOnClose`).
 
-**Typed dates.** `InlineDatePicker`'s keyboard mode is the kit's segmented `DateField`: type
+**Typed dates.** `InlineDatePicker`'s keyboard mode is an internal segmented date field
+(`DateField` — not exported; reached only through `InlineDatePicker`): type
 the date in the locale's own field order (dd/MM/yyyy where the locale says so — pass
 `locale`), digits auto-advance, and a typed separator (`/` `.` `-`) advances a single-digit
 day/month; Enter or blur commits, Escape reverts, Alt+ArrowDown floats the calendar. The
@@ -82,9 +83,15 @@ One per type:
   CLOSING commits the new set in one `onSave` — never a borderless `Select` posing as an inline
   field.
 
-All are built on **`useInlineEdit`** + **`InlineEditView`** (custom inputs join the family via
-those). `onSave` is async: the saving spinner sits INSIDE the control at its right edge (never a
-sibling — that reflows); an error shows inline without losing the edit.
+They split across two shared shells. The same-height **input-swap** editors (`InlineTextInput`,
+`InlineNumberInput`, `InlineTimePicker`) render **`InlineEditFrame`** driven by the
+**`useInlineEdit`** hook (the view⇄edit toggle, draft buffer, and async save) — swap a custom
+input into that pair to join the family. The **popover** editors (`InlineSelect`,
+`InlineMemberSelect`, `InlineDatePicker`, `InlineTagSelect`) instead compose **`InlineEditView`**
+(the resting box, wired as the popover trigger) with their OWN `useState` for open/draft/saving/
+error — a pick, not a keystroke, is the edit, so `useInlineEdit` doesn't fit. `onSave` is async
+either way: the saving spinner sits INSIDE the control at its right edge (never a sibling — that
+reflows); an error shows inline without losing the edit.
 
 To let a value be UNSET (a diff-write CLEAR — unassign, remove a due date, drop a select), pass
 **`onClear`** to `InlineSelect` / `InlineMemberSelect` / `InlineDatePicker`. It surfaces through
@@ -139,7 +146,8 @@ wrap their OWN `FormField` (and don't put a `style` on it) — for a grid cell u
 
 ## Find-or-create — the `Combobox` family IS the control
 
-`Combobox` is COMPOUND: a root holds the DATA + behaviour (the shared `useOptionList` engine —
+`Combobox` is COMPOUND: a root holds the DATA + behaviour (its internal option-list engine —
+`useOptionList`, not exported —
 `options`, `value`, `onValueChange`, `onSearchChange`, `allowCustom`, the per-row
 `getOptionDescription`/`renderOptionContent` so they're typed against the option `data`), and the
 parts render the CHROME, composed as children — never a render-prop pile:
@@ -198,17 +206,22 @@ When work crosses departments (sales → operations → accounting), the HANDOFF
 changing desks — never an inbox, a notification, or a copied task. Two types:
 
 **(A) Same entity** → a STAGE field on the shared record: sections carry OWNER dot tags, and the
-handoff is MANAGED AS TASKS — each desk's checklist on the record (the task-row vocabulary:
-sibling `CheckCircle` + struck transparent `InlineTextInput` + per-task `InlineMemberSelect`
-assignees + the `CaptureRow` add-affordance — never a decorative progress strip). A NEW record
-starts with an EMPTY checklist — tasks truly vary. The commons split in two: MANDATORY tasks are
-seeded by the app (a workflow on create, per record type) — no human types them; common-but-
-OPTIONAL tasks appear as `SuggestionChip`s under the list — a PILL, never a row, so a suggestion
-can't be mistaken for a task (tap = materialize, ✕ = dismiss for this record; already-present
-labels filter out; suggestions never count in done/total and pause while a filter narrows the
-view) — the same suggestion grammar as the billing Standard pill. Real rows carry a ⋯ `menu` (an
-`ActionMenu`; Delete lives BEHIND it, danger-styled and last — never a bare ✕ a stray tap can
-hit), completing the checklist's CRUD.
+handoff is MANAGED AS TASKS — each desk's checklist on the record. The **`Checklist`** compound
+OWNS the list geometry (row height, ring/title alignment, and the one trailing column, set once
+via `trailingWidth`) — compose it, never hand-roll the row. Each **`ChecklistRow`** takes a
+`control` (a `CheckCircle` — a read-only ring when it has no `onChange`), its title as children (a
+struck transparent `InlineTextInput`, or plain `Text`), then EITHER a `trailing` cell on wide
+surfaces (the per-task assignee `InlineMemberSelect`, sized by the list's `trailingWidth`) OR a
+`meta` line under the title on NARROW surfaces (a drawer/popover checklist — the two are mutually
+exclusive), plus a `menu` for the row's ⋯ options — never a decorative progress strip. `CaptureRow`
+closes the list as its add-affordance. A NEW record starts with an EMPTY checklist — tasks truly
+vary. The commons split in two: MANDATORY tasks are seeded by the app (a workflow on create, per
+record type) — no human types them; common-but-OPTIONAL tasks appear as `SuggestionChip`s under
+the list — a PILL, never a row, so a suggestion can't be mistaken for a task (tap = materialize,
+✕ = dismiss for this record; already-present labels filter out; suggestions never count in
+done/total and pause while a filter narrows the view) — the same suggestion grammar as the billing
+Standard pill. The row's `menu` (an `ActionMenu`; Delete lives BEHIND it, danger-styled and last —
+never a bare ✕ a stray tap can hit) completes the checklist's CRUD.
 
 Open tasks INFORM the handoff, they NEVER block it: the CTA stays enabled, the count warns, and
 open tasks carry over. The handoff CTA opens a DIALOG for the receiving desk (assignee
@@ -216,8 +229,9 @@ open tasks carry over. The handoff CTA opens a DIALOG for the receiving desk (as
 the record left this register.
 
 Tasks PEEK from the register: the done/total column is a pressable compact-`ProgressBar` trigger
-whose popover holds the checklist on FIXED columns — every row ring · struck `InlineTextInput`
-title (flex) · quick-reassign `InlineMemberSelect` (140) — no expandable rows (tags/files depth is
+whose popover holds the same `Checklist` on FIXED columns (`trailingWidth={140}`) — every
+`ChecklistRow`'s ring `control` · struck `InlineTextInput` title (flex) · quick-reassign
+`InlineMemberSelect` `trailing` — no expandable rows (tags/files depth is
 the Task list template's lesson, not the peek's); the popover body is `PopoverContent`'s own
 ScrollView (`disableBodyScroll` is ONLY for children that manage their own scroll, like
 `OptionList`). The DRAWER carries a real Tasks SECTION in the Record template's shape (heading +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "11.8.3",
+  "version": "11.8.4",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
@@ -131,6 +131,8 @@
     "./use_screen_size": "./src/use_screen_size.ts",
     "./use_auto_grow_height": "./src/use_auto_grow_height.ts",
     "./use_focus_ring": "./src/use_focus_ring.ts",
+    "./interaction_modality": "./src/interaction_modality.ts",
+    "./inline_focus": "./src/inline_focus.ts",
     "./use_hover": "./src/use_hover.ts",
     "./focus_ring_pressable": "./src/focus_ring_pressable.tsx",
     "./control_surface": "./src/control_surface.ts",

package/src/file_thumbnail.tsx

@@ -108,6 +108,7 @@ export function FileThumbnail(props: FileThumbnailProps) {
           mimeType={file.mimeType}
           size={size}
           isTemplate={isTemplate}
+          accessibilityLabel={file.filename}
           onPress={onPress ?? (() => Linking.openURL(file.url))}
           onLongPress={onLongPress}
         />
@@ -179,17 +180,27 @@ interface DocumentBadgeProps {
   isTemplate?: boolean;
   onPress?: () => void;
   onLongPress?: () => void;
+  /** Accessible name for the pressable badge — the filename it stands for.
+   *  Falls back to the file-type label (e.g. "PDF") when omitted. */
+  accessibilityLabel?: string;
 }
 
 /**
  * Compact two-tone file badge with document lines and colored label.
  */
 export function DocumentBadge(props: DocumentBadgeProps) {
-  const { mimeType, isTemplate, onPress, onLongPress } = props;
+  const { mimeType, isTemplate, onPress, onLongPress, accessibilityLabel } = props;
   const { focusVisible, focusProps } = useFocusRing();
 
   return (
-    <Pressable onPress={onPress} onLongPress={onLongPress} {...focusProps} style={focusVisible ? { boxShadow: FOCUS_RING, borderRadius: 6 } : undefined}>
+    <Pressable
+      onPress={onPress}
+      onLongPress={onLongPress}
+      accessibilityRole="button"
+      accessibilityLabel={accessibilityLabel ?? resolveMime(mimeType).label}
+      {...focusProps}
+      style={focusVisible ? { boxShadow: FOCUS_RING, borderRadius: 6 } : undefined}
+    >
       <FileBadge mimeType={mimeType} isTemplate={isTemplate} />
     </Pressable>
   );
@@ -234,6 +245,8 @@ export function DocumentCard(props: DocumentCardProps) {
       ]}
       onPress={onPress}
       onLongPress={onLongPress}
+      accessibilityRole="button"
+      accessibilityLabel={filename}
       {...focusProps}
     >
       <FileBadge mimeType={mimeType} size={badgeSize} isTemplate={isTemplate} />
@@ -280,6 +293,8 @@ export function MediaCard(props: MediaCardProps) {
         style={({ pressed }) => [styles.mediaCardCompact, sizeStyle, { backgroundColor: color }, pressed && styles.pressedDim, focusVisible && { boxShadow: FOCUS_RING }]}
         onPress={onPress}
         onLongPress={onLongPress}
+        accessibilityRole="button"
+        accessibilityLabel={filename}
         {...focusProps}
       >
         <Icon name={icon} size={iconSize} color={colors.white} />
@@ -292,7 +307,7 @@ export function MediaCard(props: MediaCardProps) {
   const backdrop = iconSize + 20;
 
   return (
-    <Pressable style={[styles.documentCard, sizeStyle, focusVisible && { boxShadow: FOCUS_RING }]} onPress={onPress} onLongPress={onLongPress} {...focusProps}>
+    <Pressable style={[styles.documentCard, sizeStyle, focusVisible && { boxShadow: FOCUS_RING }]} onPress={onPress} onLongPress={onLongPress} accessibilityRole="button" accessibilityLabel={filename} {...focusProps}>
       {(state) => (
         <>
           <View style={[styles.mediaCardBody, { backgroundColor: color }]}>
@@ -343,7 +358,7 @@ function ImageThumbnail(props: ImageThumbnailProps) {
       : { width: "100%" as const, height: "100%" as const };
 
   return (
-    <Pressable onPress={onPress} onLongPress={onLongPress} {...focusProps} style={[styles.imageThumbnail, sizeStyle, focusVisible && { boxShadow: FOCUS_RING }]}>
+    <Pressable onPress={onPress} onLongPress={onLongPress} accessibilityRole={onPress ? "button" : "image"} accessibilityLabel={file.filename} {...focusProps} style={[styles.imageThumbnail, sizeStyle, focusVisible && { boxShadow: FOCUS_RING }]}>
       {(state) => (
         <>
           <Image