@lotics/ui 11.8.3 → 11.8.8

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 /
@@ -390,9 +392,12 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   name), `color` = emphasis/risk.
 - **`icon_button`** — `IconButton`: the icon-only circular action (see
   [Actions](#actions)).
-- **`back_button`** — `BackButton`: the chevron-left `IconButton` (lg, secondary) heading a
-  screen/panel: `onPress` + `accessibilityLabel` (defaults to the locale's `nav.back` —
-  "Back" / "Quay lại"); the one go-back glyph — don't hand-roll it.
+- **`back_button`** — `BackButton`: the one go-back control — don't hand-roll it (an
+  `arrow-left` `MenuButton` reads as another nav ITEM, not an exit). `onPress` +
+  `accessibilityLabel` (defaults to `label`, else the locale's `nav.back` — "Back" /
+  "Quay lại"). Bare, it's the chevron-left `IconButton` (lg, secondary) heading a
+  screen/panel; pass **`label`** to name where back GOES ("Danh sách") and it becomes ONE
+  pressable over glyph + words — never an icon button beside unclickable prose.
 - **`link`** — `Link`: the EXTERNAL hyperlink — fixed underline+blue + `role="link"`;
   `onPress` only (the consumer wires the opener).
 - **`text_link`** — `TextLink`: underlined text that's optionally an `onPress` action or an
@@ -578,7 +583,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/docs/templates.md

@@ -244,6 +244,26 @@ Top → bottom:
 - A LEFT OUTLINE RAIL (`MenuButton` + `useSectionNav`) jumps between the sections and
   scroll-spies the active one; on narrow containers it becomes the pinned current-section
   bar opening a section-picker `Modal`.
+- **The page layout is the DOCS layout — the reading column is CENTRED IN THE VIEWPORT, and
+  the rail sits in its left gutter.** The `ScrollView` is FULL-WIDTH — **never cap it at
+  `CONTENT_MAX`, or the scroll container becomes the column and the gutters go wheel-dead**
+  (measured: a 720px scroller in a 1440px window leaves half the page ignoring the wheel).
+  Inside it sits one centred row (`width: "100%"`,
+  `maxWidth: GUTTER * 2 + CONTENT_MAX`, `alignSelf: "center"`, `flexDirection: "row"`) of
+  three parts: a gutter RESERVED for the rail (`width: GUTTER` — the rail's own `RAIL_W`
+  PLUS `RAIL_GAP`, the docs' 3rem of breathing room, so the rail never butts against the
+  column), the reading column (`flex: 1, minWidth: 0`), and an EMPTY right gutter of the
+  same `GUTTER` that BALANCES the rail — without it the column sits half a rail right of centre. (The public docs pages get
+  this balance for free: their right-hand TOC is the counterweight. A record surface has no
+  TOC, so the gutter is simply reserved.) The rail is NOT window chrome: no full-height
+  border, not glued to the window edge — it FLOATS over its reserved gutter
+  (`position: "absolute"`, `left` mirroring the row's centring maths), so it stays put while
+  the record scrolls **without** web-only `position: sticky` (which RN does not type —
+  `position` is `"absolute" | "relative" | "static"`) and without stealing the page's
+  scrollable width. The rail earns its place only while the centred column still has room
+  beside it (`pageWidth >= GUTTER * 2 + 560`); below that it collapses to the pinned bar.
+  Sizing the column is the SHELL's job — inner blocks are plain `width: "100%"`, never a
+  second `maxWidth` + `alignSelf: "center"`.
 
 ### `tpl_tasks` — the quick list
 

package/examples/tpl_record.tsx

@@ -367,6 +367,17 @@ function InvoiceBand({
   );
 }
 
+/** The section rail's width — and, mirrored as an empty right gutter, what
+ *  keeps the reading column centred in the viewport. */
+const RAIL_W = 208;
+/** Breathing room between the rail and the reading column (the docs' 3rem). */
+const RAIL_GAP = 48;
+/** The reserved gutter: the rail plus its gap. Mirrored empty on the right, this
+ *  is what centres the column. */
+const GUTTER = RAIL_W + RAIL_GAP;
+/** The reading column's ceiling. */
+const CONTENT_MAX = 720;
+
 export function TplRecord() {
   const id = useRef(1);
   const nextId = (prefix: string) => `${prefix}_${(id.current += 1)}`;
@@ -626,21 +637,25 @@ export function TplRecord() {
   // it opens a full-page section picker (Escape / the close control dismiss).
   const [sectionsOpen, setSectionsOpen] = useState(false);
   const [pageWidth, setPageWidth] = useState<number | null>(null);
-  const wide = pageWidth != null && pageWidth >= 760;
+  // The rail lives in the page's LEFT GUTTER and an equal spacer balances it on
+  // the right, so the reading column lands dead-centre in the viewport (the docs
+  // layout, where the right-hand TOC is the balancer). The rail only earns its
+  // place once the centred column still has room beside it: 2 × rail + a
+  // readable column — below that it collapses to the pinned bar.
+  const wide = pageWidth != null && pageWidth >= GUTTER * 2 + 560;
+  // The rail floats over its RESERVED gutter rather than sitting in the scroll
+  // row, so the ScrollView keeps the FULL page width — wheel anywhere and the
+  // record scrolls. (Capping the ScrollView at the column's width instead makes
+  // the gutters dead zones.) Mirrors the flex maths the row does below: the
+  // group is centred inside the 28px content padding.
+  const groupW = pageWidth == null ? 0 : Math.min(pageWidth - 28 * 2, GUTTER * 2 + CONTENT_MAX);
+  const railLeft = pageWidth == null ? 0 : 28 + Math.max(0, (pageWidth - 28 * 2 - groupW) / 2);
 
   return (
     // Measure-then-reveal: hidden until the width is known, so the rail/bar
     // choice never visibly reshuffles the page on first paint.
-    <View style={{ flex: 1, flexDirection: wide ? "row" : "column", backgroundColor: colors.white, opacity: pageWidth == null ? 0 : 1 }} onLayout={(e) => setPageWidth(e.nativeEvent.layout.width)}>
-      {pageWidth == null ? null : wide ? (
-        <View style={{ width: 208, borderRightWidth: 1, borderRightColor: colors.zinc[200], padding: 8 }}>
-          <View style={{ gap: 2 }}>
-            {SECTIONS.map((sec) => (
-              <MenuButton key={sec.key} icon={sec.icon} title={sec.label} selected={nav.activeKey === sec.key} onPress={() => nav.jumpTo(sec.key)} />
-            ))}
-          </View>
-        </View>
-      ) : (
+    <View style={{ flex: 1, backgroundColor: colors.white, opacity: pageWidth == null ? 0 : 1 }} onLayout={(e) => setPageWidth(e.nativeEvent.layout.width)}>
+      {pageWidth == null || wide ? null : (
         // Narrow: a pinned bar names the CURRENT section (the spy keeps it
         // honest while scrolling); tapping opens the full-page section picker —
         // no tab strip the thumb has to scroll.
@@ -653,11 +668,19 @@ export function TplRecord() {
           />
         </View>
       )}
+    <View style={{ flex: 1 }}>
+    {/* FULL-WIDTH scroller: the whole page scrolls, wherever the pointer is. */}
     <ScrollView ref={nav.scrollRef} onScroll={nav.onScroll} scrollEventThrottle={16} style={{ flex: 1 }} contentContainerStyle={{ padding: 28, paddingBottom: 96 }}>
+      {/* The centred group: a gutter RESERVED for the rail, the reading column,
+          and an equal empty gutter that balances it — so the column's centre is
+          the window's centre. Both gutters live INSIDE the scroller, so they
+          scroll like everything else. */}
+      <View style={{ width: "100%", maxWidth: wide ? GUTTER * 2 + CONTENT_MAX : CONTENT_MAX, alignSelf: "center", flexDirection: "row" }}>
+      {wide ? <View style={{ width: GUTTER, flexShrink: 0 }} /> : null}
       {/* the page column is a SectionStack — it owns the 56px beat + the
           hairline BETWEEN top-level blocks (a conditional block that renders
           null never leaves a stray divider) */}
-      <SectionStack style={{ width: "100%", maxWidth: 720, alignSelf: "center" }}>
+      <SectionStack style={{ flex: 1, minWidth: 0 }}>
         {/* header band — app bar + summary + key facts read as ONE block */}
         <View style={{ gap: 32 }}>
         {/* app bar — CREATE is one click; the surface is where everything is refined */}
@@ -1342,7 +1365,25 @@ export function TplRecord() {
           <Button title="Issue" color="primary" onPress={() => confirmIssue && issue(confirmIssue)} />
         </DialogFooter>
       </Dialog>
+      {/* Balances the rail so the reading column lands dead-centre. In the docs
+          layout the right-hand TOC does this job; a record surface has no TOC,
+          so the gutter is simply reserved. */}
+      {wide ? <View style={{ width: GUTTER, flexShrink: 0 }} /> : null}
+      </View>
     </ScrollView>
+    {/* The rail floats over its reserved gutter — pinned while the record
+        scrolls, and out of the scroll row so the page stays wheel-scrollable
+        edge to edge. */}
+    {pageWidth == null || !wide ? null : (
+      <View style={{ position: "absolute", top: 28, left: railLeft, width: RAIL_W }}>
+        <View style={{ gap: 2 }}>
+          {SECTIONS.map((sec) => (
+            <MenuButton key={sec.key} icon={sec.icon} title={sec.label} selected={nav.activeKey === sec.key} onPress={() => nav.jumpTo(sec.key)} />
+          ))}
+        </View>
+      </View>
+    )}
+    </View>
     </View>
   );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "11.8.3",
+  "version": "11.8.8",
   "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/back_button.tsx

@@ -1,26 +1,64 @@
 import { IconButton } from "./icon_button";
-import { View } from "react-native";
+import { Pressable, View } from "react-native";
+import { Icon } from "./icon";
+import { Text } from "./text";
+import { colors } from "./colors";
 import { useLoticsLocale } from "./locale";
 
 interface BackButtonProps {
   onPress: () => void;
-  /** Accessible name. Defaults to the locale's `nav.back` ("Back" / "Quay lại"). */
+  /** Names where back GOES ("Orders", "Danh sách"). Renders beside the glyph as
+   *  part of the SAME control — a label you can't press is a lie. Omit for the
+   *  bare glyph. */
+  label?: string;
+  /** Accessible name. Defaults to `label`, else the locale's `nav.back`
+   *  ("Back" / "Quay lại"). */
   accessibilityLabel?: string;
 }
 
 export function BackButton(props: BackButtonProps) {
   const locale = useLoticsLocale();
-  const { onPress, accessibilityLabel = locale.nav.back } = props;
+  const { onPress, label, accessibilityLabel = label ?? locale.nav.back } = props;
+  // Bare glyph — the circular icon IS the control.
+  if (label === undefined) {
+    return (
+      <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+        <IconButton
+          icon="chevron-left"
+          size="lg"
+          color="secondary"
+          accessibilityLabel={accessibilityLabel}
+          onPress={onPress}
+          style={{ alignSelf: "flex-start" }}
+        />
+      </View>
+    );
+  }
+  // Labelled — ONE pressable over glyph + label, so the words are a target too
+  // (an IconButton beside a Text would be a control next to unclickable prose).
   return (
-    <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
-      <IconButton
-        icon="chevron-left"
-        size="lg"
-        color="secondary"
-        accessibilityLabel={accessibilityLabel}
-        onPress={onPress}
-        style={{ alignSelf: "flex-start" }}
-      />
-    </View>
+    <Pressable
+      accessibilityRole="button"
+      accessibilityLabel={accessibilityLabel}
+      onPress={onPress}
+      style={({ pressed, hovered }) => [
+        {
+          flexDirection: "row",
+          alignItems: "center",
+          gap: 6,
+          alignSelf: "flex-start",
+          paddingVertical: 6,
+          paddingLeft: 6,
+          paddingRight: 10,
+          borderRadius: 8,
+        },
+        (hovered || pressed) && { backgroundColor: colors.zinc[100] },
+      ]}
+    >
+      <Icon name="chevron-left" size={16} color={colors.zinc[500]} />
+      <Text size="sm" weight="medium" color="muted" numberOfLines={1}>
+        {label}
+      </Text>
+    </Pressable>
   );
 }

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