@lotics/ui 20.2.0 → 21.0.0

package/AGENTS.md

@@ -15,7 +15,7 @@ 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 (incl. 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, 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/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). |

package/MIGRATION.md

@@ -4,6 +4,63 @@ Breaking changes, newest first — normally per major, plus the rare minor that
 anyway (recorded under its exact version). The current contract lives in `AGENTS.md` + `docs/`;
 this file exists only to move an app from one release to the next.
 
+## v21 from 20.x
+
+**`FilesEditor` is a COMPOUND.** It rendered a fixed toolbar — Upload · Select · Download all,
+swapping into a select-mode row whose actions hid behind a generic "Menu" — and that shape cost
+two things in real screens. A HOST verb had nowhere to go, so a surface that needed one (an AI
+read over the picked papers, "send these to the broker") hand-rolled the whole grid and lost the
+gallery, the upload queue and the confirm with it. And the actions that DID exist sat behind a
+label naming a widget rather than an act, five interactions deep for "delete this scan".
+
+The root still owns what a host cannot reasonably re-implement — the batch selection, the
+full-screen gallery, the Alert-confirmed remove — and still renders the grid. What you can DO to
+the files is now composed below it.
+
+```tsx
+// BEFORE
+<FilesEditor
+  files={files} uploads={uploads} onAdd={add} onRemove={remove}
+  onShareSelected={share} onDownloadZipSelected={zip} readOnly={readOnly}
+/>
+
+// AFTER
+<FilesEditor files={files} uploads={uploads} onAdd={readOnly ? undefined : add} onRemove={readOnly ? undefined : remove}>
+  <FilesEditorBar>
+    <FilesEditorUpload />
+    <FilesEditorSelect />
+    <FilesEditorSelectAll />
+    <FilesEditorBarSpacer />
+    <FilesEditorDownload />
+    <FilesEditorRemove />
+  </FilesEditorBar>
+</FilesEditor>
+```
+
+| Gone | Now |
+|---|---|
+| `onShareSelected` | a `Button` in the bar reading `useFilesEditorSelection()` — sharing is a HOST act |
+| `onDownloadZipSelected` | the same |
+| `readOnly` | withhold `onAdd`/`onRemove`; the pieces render nothing without a handler, so the composition IS the read-only shape and there is no second mode to keep in sync |
+| the "Menu" popover | the bar. Actions are visible controls, in the order the surface wants them |
+| `labels.menu` · `labels.share` · `labels.downloadZip` | deleted with the acts they named |
+
+**No children means no bar** — a grid that previews and nothing else. That is the one rendering
+path; there is no default toolbar to fall back to.
+
+**The remaining labels resolve prop → `LoticsLocale.filesEditor` → nothing**, so an app that
+supplies its pack at the root gets them translated with no per-instance wiring.
+
+A host verb reads the selection:
+
+```tsx
+function ReadWithAi() {
+  const { selected, exit } = useFilesEditorSelection();
+  return <Button title="Đọc bằng AI" disabled={selected.length === 0}
+                 onPress={() => { run(selected); exit(); }} />;
+}
+```
+
 ## v20 from 19.x
 
 **`@lotics/ui/section` is DELETED.** Two modules exported a `Section` — the layout grammar's

package/docs/catalog.md

@@ -221,15 +221,12 @@ reference), `InfoPopover` (the ⓘ explainer).
 
 ### Files
 
-`FilesEditor` (THE all-in-one attachment field: an upload-aware grid + a toolbar below it
-that swaps into a batch SELECT mode, full-screen preview, download/share, and
-Alert-confirmed remove — the host only owns `files` + wires `onAdd`/`onRemove`. Reach for
-this first for "manage a record's attachments"), `FileDropzone`, `FileRows`
-(batteries-included file LIST: tap a row → built-in full-screen gallery, with a per-row
-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; `onPress`/`onFilePress` makes each
+`FilesEditor` (THE attachment surface: an upload-aware grid whose bar you COMPOSE — the root
+owns selection + gallery + confirmed remove, the bar pieces and any HOST verb go below it via
+`useFilesEditorSelection`),
+`FileGrid` (the upload-aware grid: completed files + a live upload queue in one
+surface — `FilesEditor` is this + selection + the composed bar; reach for `FileGrid` bare when
+you own all three), `FileThumbnail` / `FileThumbnailGrid` (square tiles; `onPress`/`onFilePress` makes each
 tile a pressable door — e.g. tap-to-preview — carrying an accessible button role + the
 filename as its name, overridable per tile with `accessibilityLabel` when what the press
 DOES reads better than a raw filename; `selectedIds` for a selection overlay),
@@ -1065,26 +1062,38 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   screenshot needs), `selectPasteSink(entries)` (the pure focus-then-stack routing rule the
   `.web` sink applies), and the types `FileIntakeFilter` / `FileTransferLike` / `RegionRef` /
   `PasteSinkEntry` / `UsePasteFilesOptions` / `FileDropTargetProps`.
-- **`files_editor`** — `FilesEditor` — THE all-in-one attachment field: `FileGrid` + a
-  toolbar (Upload primary · Select · Download all) that swaps into a batch SELECT mode
-  (Select all · a Menu of Download/Share/Delete · Done; the per-tile ✕ is select-mode-only,
-  never in the default view; `selectTileRemove={false}` drops even that so delete is
-  menu-only) + built-in gallery (Download + inline preview; no "open in new tab") +
-  Alert-confirmed remove; host wires `files` + `onAdd`/`onRemove` (+ optional `uploads`,
-  `onShareSelected`, `readOnly`, `selectTileRemove`, `labels`, `galleryLabels`,
-  `gridMaxHeight` — cap the grid height so it scrolls and the toolbar pins, for a
-  popover/drawer). Use `FileGrid`/`FileRows` bare only when you own the chrome.
+- **`files_editor`** — THE attachment surface, as a **compound**. `FilesEditor` (root) owns
+  what a host cannot reasonably re-implement — the batch selection, the built-in gallery
+  (Download + inline preview; no "open in new tab"), the Alert-confirmed remove — and renders
+  `FileGrid`; the host wires `files` + `onAdd`/`onRemove` (+ optional `uploads`,
+  `selectTileRemove`, `labels`, `galleryLabels`, `gridMaxHeight` — cap the grid height so it
+  scrolls and the bar pins, for a popover/drawer). **What you can DO to the files is composed
+  below it**, from `FilesEditorBar` + `FilesEditorUpload` · `FilesEditorSelect` ·
+  `FilesEditorSelectAll` · `FilesEditorDownload` · `FilesEditorRemove` (+
+  `FilesEditorBarSpacer` to push the rest right). Each renders nothing without the handler it
+  needs, so withholding `onAdd`/`onRemove` IS the read-only shape — there is no `readOnly`
+  mode. **A HOST verb is a plain `Button`** reading **`useFilesEditorSelection()`**
+  (`{selected, selectedIds, files, selectMode, clear, exit}`) — an AI read over the picked
+  papers, "send to the broker", a ZIP: acts the kit has never heard of, which is why there is
+  no props-per-act toolbar and no generic Menu. **No children means no bar** (a grid that only
+  previews). Bar words resolve prop → `LoticsLocale.filesEditor`; in-flight tile words →
+  `LoticsLocale.fileUpload`. **No empty state:** with zero files it is a bare bar, so pair it
+  with a `FileDropzone` for the well a records screen opens on. Use `FileGrid`/`FileRows` bare
+  only when you own the selection and the gallery too.
 - **`file_grid`** — `FileGrid` + the `FileUpload`/`PendingUpload` types: the upload-aware
   grid — `files` are the saved/completed `DisplayFile`s, `uploads` is the LIVE add-queue; it
   interleaves both and renders each in-flight tile itself with a labeled status overlay.
   Tiles FILL the container width at a uniform size (≥ `minItemWidth`, default 96); pass
   `columns` for a fixed count, `itemSize` for exact tiles, or `singleRow` to fit one row and
   collapse the rest into a clickable "+N" overflow tile (`onOverflowPress(hiddenCount)`).
-  CRUD via `onFilePress` / `onDisplayRemove` / `onUploadRemove` / `onRetry` / `onRetryAll`;
-  localize with `labels.upload` (an `UploadStatusLabels`).
+  CRUD via `onFilePress` / `onDisplayRemove` / `onUploadRemove` / `onRetry` / `onRetryAll`.
+  The status words resolve **prop → `LoticsLocale.fileUpload` → nothing**, so they follow the
+  root pack with no per-call-site wiring (that is also how the grid inside `FilesEditor`, which
+  cannot pass `labels`, gets localized); `labels.upload`/`labels.retryAll` override one grid.
 - **`uploading_thumbnail`** — `UploadingThumbnail` + `UploadStatus`/`UploadStatusLabels`:
   the single in-flight upload tile `FileGrid` renders; reach for it only when hand-rolling a
-  non-grid upload layout.
+  non-grid upload layout — it is i18n-free by design, so a bare call site owes it `labels`
+  (`FileGrid` resolves them from `LoticsLocale.fileUpload` on your behalf).
 - **`file_thumbnail`** — `FileThumbnail` + `DisplayFile` + `THUMBNAIL_SIZE` /
   `COMPACT_THUMBNAIL_SIZE` + `getMediaIcon`: the completed tile — the right surface per
   MIME: image thumbnail · a doc tile with the `FileBadge` centered + a single-line filename

package/docs/data_entry.md

@@ -514,28 +514,59 @@ affordance line under its heading — **`<SectionHeadingTitle description="Drag,
 to add files">`** (both templates do this). A `FileDropzone`'s own hint already names the paste
 (its default `fileDropzone.hint` is "or click, or paste (⌘V)").
 
-### Default: `FilesEditor`
-
-**`<FilesEditor files onAdd onRemove>`** bundles the upload-aware grid + a toolbar below it
-(Upload · Select · Download all) + a batch SELECT mode + the full-screen gallery +
-Alert-confirmed remove; the host only owns `files` and wires `onAdd` (picked → its upload) /
-`onRemove`. The destructive per-tile ✕ shows only in SELECT mode (the default view is a clean
-preview — no stray-tap deletes); pass `selectTileRemove={false}` to drop that ✕ entirely so
-select mode deletes ONLY via Select → Menu → Delete (the batch gating flow — right for a
-height-bounded cell editor). The built-in gallery is Download + inline preview (no "open in new
-tab" — it's redundant once everything previews inline). In a height-bounded container (a
-popover/drawer) pass `gridMaxHeight` so the grid SCROLLS and the toolbar pins below it; omit it
-in free-flow layouts (a form field) where the grid grows.
+### Default: the `FilesEditor` compound
+
+**The root owns what a host cannot reasonably re-implement** — the batch selection, the
+full-screen gallery, the Alert-confirmed remove — and renders the upload-aware grid. **What you
+can DO to the files is composed below it**, so a surface offers exactly its own verbs, in its
+own order, under their own names.
+
+```tsx
+<FilesEditor files={files} uploads={queue} onAdd={add} onRemove={remove}>
+  <FilesEditorBar>
+    <FilesEditorUpload />
+    <FilesEditorSelect />       {/* "Select" ⇄ "Done" — one toggle, not two buttons */}
+    <FilesEditorSelectAll />    {/* renders only while selecting */}
+    <FilesEditorBarSpacer />
+    <FilesEditorDownload />     {/* the selection while selecting, everything at rest */}
+    <FilesEditorRemove />
+  </FilesEditorBar>
+</FilesEditor>
+```
+
+**A HOST verb is a plain `Button`** that reads `useFilesEditorSelection()` →
+`{selected, selectedIds, files, selectMode, clear, exit}`. This is the whole reason the bar is
+composed: an act the kit has never heard of — read these with AI, send them to the broker, ZIP
+them — has a home, instead of forcing the screen to hand-roll the grid and lose the gallery and
+the upload queue with it.
+
+```tsx
+function ReadWithAi() {
+  const { selected, exit } = useFilesEditorSelection();
+  return <Button title="Read with AI" disabled={selected.length === 0}
+                 onPress={() => { run(selected); exit(); }} />;
+}
+```
+
+**Each piece renders nothing without the handler it needs**, so composition expresses the
+variants that used to be flags: withhold `onAdd` and there is no Upload; withhold `onRemove` and
+there is no Remove and no per-tile ✕ — that IS read-only, with no second mode to keep in sync.
+**No children means no bar**: a grid that previews and nothing else.
+
+The destructive per-tile ✕ shows only in SELECT mode (the default view is a clean preview — no
+stray-tap deletes); `selectTileRemove={false}` drops it there too, so the bar's Remove is the
+only delete path (right for a height-bounded cell editor). The built-in gallery is Download +
+inline preview (no "open in new tab" — redundant once everything previews inline). In a
+height-bounded container (a popover/drawer) pass `gridMaxHeight` so the grid SCROLLS and the bar
+pins below it; omit it in free-flow layouts where the grid grows.
 
 The rest of the surface: `uploads` passes the live add-queue through to the grid (with
-`onUploadRemove`/`onRetry`/`onRetryAll`); `onUpload` overrides the Upload action's built-in web
-picker (e.g. a native document picker); `readOnly` (or omitting `onRemove`) makes it a view-only
-download+preview surface; omitting `onAdd` hides Upload. Select mode gains a Share action via
-`onShareSelected(files)` and a "Download as ZIP" item via `onDownloadZipSelected(files)` (shown at
-2+ selected) — both host-provided, hidden when omitted. `onDownload` overrides the default
-per-file `downloadFileFromUrl`; `accept` filters the picker; `itemSize`/`minItemWidth`/`columns`
-pass through to the grid; `credentials` covers auth-gated preview URLs; `labels` /
-`galleryLabels` localize the toolbar and the gallery chrome.
+`onUploadRemove`/`onRetry`/`onRetryAll`); `onUpload` overrides the Upload picker (e.g. a native
+document picker); `onDownload` overrides the default per-file `downloadFileFromUrl`; `accept`
+filters the picker; `itemSize`/`minItemWidth`/`columns` pass through to the grid; `credentials`
+covers auth-gated preview URLs. Bar words resolve **prop → `LoticsLocale.filesEditor`**, gallery
+chrome via `galleryLabels`, in-flight tile words via `LoticsLocale.fileUpload` — so an app that
+supplies its pack at the root needs no per-instance labels at all.
 
 Reach for the lower-level pieces below only when you need custom chrome.
 
@@ -551,9 +582,10 @@ more" affordance — only the empty state leads with it).
 the LIVE add-queue (`FileUpload[]`) — it interleaves both and renders each in-flight tile itself —
 a LABELED status overlay (uploading spinner · "Retrying" · "Paused" · "Upload failed" + a retry
 button · "Can't upload" for a dead/empty file) — so you never hand-map an upload to a
-`FileThumbnail`. Localize the labels with `labels.upload` (an `UploadStatusLabels`) and
-`labels.retryAll`. **Limitation:** the upload-status labels are NOT wired to
-`LoticsLocaleProvider` — they default to English; pass `labels` per instance to localize.
+`FileThumbnail`. Those words resolve **prop → `LoticsLocale.fileUpload` → nothing** — set the
+pack once at the root and a stalled or dead upload speaks the app's language everywhere,
+including inside `FilesEditor`, which has no per-instance way to reach them. `labels.upload` /
+`labels.retryAll` override one grid.
 
 Make it CRUDable by wiring its callbacks: `onFilePress` → set a `number|null` index that drives
 `<FileGalleryModal files activeIndex onIndexChange>` — a FULL-SCREEN viewer with a toolbar

package/examples/tpl_task_board.tsx

@@ -21,7 +21,7 @@ import { ActionMenu } from "@lotics/ui/action_menu";
 import { Alert } from "@lotics/ui/alert";
 import { pickFiles } from "@lotics/ui/file_picker";
 import { Popover, PopoverTrigger, PopoverContent } from "@lotics/ui/popover";
-import { FilesEditor } from "@lotics/ui/files_editor";
+import { FilesEditor, FilesEditorBar, FilesEditorBarSpacer, FilesEditorRemove, FilesEditorSelect, FilesEditorUpload } from "@lotics/ui/files_editor";
 import { FileThumbnail, type DisplayFile } from "@lotics/ui/file_thumbnail";
 import { DataGrid, gridRowStyle, type DataGridColumn, type DataGridGroup } from "@lotics/ui/data_grid";
 import { CONTROL_RADIUS } from "@lotics/ui/control_surface";
@@ -483,7 +483,16 @@ function FilesCell({ files, onAdd, onRemove }: { files: DisplayFile[]; onAdd: (p
       </PopoverTrigger>
       <PopoverContent>
         <View style={{ width: 340, padding: 8 }}>
-          <FilesEditor files={files} itemSize={76} onAdd={onAdd} onRemove={onRemove} />
+          {/* The bar is composed, so this popover offers exactly the three acts
+              a task attachment needs and nothing else. */}
+          <FilesEditor files={files} itemSize={76} onAdd={onAdd} onRemove={onRemove}>
+            <FilesEditorBar>
+              <FilesEditorUpload />
+              <FilesEditorSelect />
+              <FilesEditorBarSpacer />
+              <FilesEditorRemove />
+            </FilesEditorBar>
+          </FilesEditor>
         </View>
       </PopoverContent>
     </Popover>

package/package.json

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

package/src/file_grid.tsx

@@ -16,6 +16,7 @@ import { FileThumbnail, type DisplayFile } from "./file_thumbnail";
 import { ThumbnailGrid } from "./file_thumbnail_grid";
 import { UploadingThumbnail, type UploadStatus, type UploadStatusLabels } from "./uploading_thumbnail";
 import { Button } from "./button";
+import { useLoticsLocale } from "./locale";
 
 /** An in-flight upload item (everything except a completed file). */
 export interface PendingUpload {
@@ -31,6 +32,9 @@ export interface PendingUpload {
  *  upload. The host maps its own upload state to this. */
 export type FileUpload = { status: "complete"; id: string; file: DisplayFile } | PendingUpload;
 
+/** Per-instance overrides. Both fall back to the active `LoticsLocale`
+ *  (`fileUpload`), so an app localizes this grid — including the one inside
+ *  `FilesEditor` — by supplying its pack once at the root, not per call site. */
 export interface FileGridLabels {
   /** "Retry all" footer button (shown when any upload errored). */
   retryAll?: string;
@@ -126,6 +130,14 @@ export function FileGrid(props: FileGridProps) {
     labels,
   } = props;
 
+  // prop → locale → (nothing) — the locale pack is always complete, so an app
+  // that never passes `labels` still reads its own language on an upload that
+  // stalls or dies. Hardcoded English here is what made "Upload failed" surface
+  // inside a fully-Vietnamese app, since `FilesEditor` — the way most apps reach
+  // this grid — has no way to pass `labels` down.
+  const loc = useLoticsLocale().fileUpload;
+  const upload = { ...loc, ...labels?.upload };
+
   const renderItems = buildRenderItems(files, uploads);
 
   const handleFilePress = useCallback(
@@ -142,7 +154,7 @@ export function FileGrid(props: FileGridProps) {
 
   const retryAll =
     onRetryAll && renderItems.some((item) => item.kind === "upload" && item.upload.status === "error") ? (
-      <Button onPress={onRetryAll} color="danger" title={labels?.retryAll ?? "Retry all"} />
+      <Button onPress={onRetryAll} color="danger" title={labels?.retryAll ?? loc.retryAll} />
     ) : null;
 
   return (
@@ -180,7 +192,7 @@ export function FileGrid(props: FileGridProps) {
             size={size}
             onRemove={onUploadRemove ? () => onUploadRemove(item.removeId) : undefined}
             onRetry={onRetry ? () => onRetry(item.removeId) : undefined}
-            labels={labels?.upload}
+            labels={upload}
           />
         )
       }

package/src/files_editor.tsx

@@ -1,8 +1,6 @@
-import { useState } from "react";
+import { createContext, useCallback, useContext, useMemo, useState, type ReactNode } from "react";
 import { View, ScrollView, StyleSheet } from "react-native";
 import { Button } from "./button";
-import { Popover, PopoverTrigger, PopoverContent } from "./popover";
-import { MenuButton } from "./menu_button";
 import { Alert } from "./alert";
 import { FileGrid, type FileUpload } from "./file_grid";
 import { FileGalleryModal } from "./file_gallery_modal";
@@ -10,21 +8,22 @@ import type { GalleryLabels } from "./file_preview_types";
 import { type DisplayFile } from "./file_thumbnail";
 import { pickFiles } from "./file_picker";
 import { downloadFileFromUrl } from "./download";
+import { useLoticsLocale } from "./locale";
 
+/**
+ * The words the shipped bar pieces say. Each resolves **prop → `LoticsLocale`
+ * (`filesEditor`) → nothing**, so an app localizes by supplying its pack once at
+ * the root. A HOST verb is a plain `Button` and names itself.
+ */
 export interface FilesEditorLabels {
   upload: string;
   select: string;
   selectAll: string;
   deselectAll: string;
   done: string;
-  /** The select-mode actions menu trigger. */
-  menu: string;
   downloadAll: string;
-  /** Download-selected menu item, given the count. */
+  /** Download-selected, given the count. */
   downloadSelected: (n: number) => string;
-  /** Download-as-ZIP menu item (shown when `onDownloadZipSelected` + 2+ selected). */
-  downloadZip: string;
-  share: string;
   delete: string;
   removeTitle: string;
   removeMessage: string;
@@ -32,83 +31,151 @@ export interface FilesEditorLabels {
   removeConfirm: string;
 }
 
-const DEFAULT_LABELS: FilesEditorLabels = {
-  upload: "Upload",
-  select: "Select",
-  selectAll: "Select all",
-  deselectAll: "Deselect all",
-  done: "Done",
-  menu: "Menu",
-  downloadAll: "Download all",
-  downloadSelected: (n) => `Download (${n})`,
-  downloadZip: "Download as ZIP",
-  share: "Share",
-  delete: "Delete",
-  removeTitle: "Remove attachment?",
-  removeMessage: "This removes the file.",
-  removeCancel: "Cancel",
-  removeConfirm: "Remove",
-};
+interface FilesEditorCtx {
+  files: DisplayFile[];
+  selectMode: boolean;
+  setSelectMode: (on: boolean) => void;
+  selectedIds: Set<string>;
+  selected: DisplayFile[];
+  toggle: (id: string) => void;
+  setAll: (on: boolean) => void;
+  clear: () => void;
+  exit: () => void;
+  onAdd?: (files: File[]) => void;
+  onUpload?: () => void;
+  onRemove?: (id: string) => void;
+  accept?: string;
+  labels: FilesEditorLabels;
+  download: (files: DisplayFile[]) => void;
+  confirmRemove: (files: DisplayFile[], onConfirm: () => void) => void;
+}
+
+const Ctx = createContext<FilesEditorCtx | null>(null);
+
+function useCtx(who: string): FilesEditorCtx {
+  const ctx = useContext(Ctx);
+  if (!ctx) throw new Error(`<${who}> must be rendered inside <FilesEditor>`);
+  return ctx;
+}
+
+/**
+ * What a HOST verb reads: the files the user picked, and how to stand down
+ * afterwards. This is the whole point of the compound — an action the kit has
+ * never heard of ("read these with AI", "attach to the shipment", "send to the
+ * broker") is a plain `Button` in the bar that calls this.
+ *
+ * ```tsx
+ * function ReadWithAi() {
+ *   const { selected, exit } = useFilesEditorSelection();
+ *   return <Button title="Đọc bằng AI" disabled={selected.length === 0}
+ *                  onPress={() => { run(selected); exit(); }} />;
+ * }
+ * ```
+ */
+export function useFilesEditorSelection(): {
+  /** The picked files, in the grid's order. Empty outside select mode. */
+  selected: DisplayFile[];
+  /** Their ids. */
+  selectedIds: string[];
+  /** Every file on the surface, picked or not. */
+  files: DisplayFile[];
+  /** Is the surface in batch-select mode? */
+  selectMode: boolean;
+  /** Drop the selection, stay in select mode. */
+  clear: () => void;
+  /** Drop the selection AND leave select mode — what a verb does when it is done. */
+  exit: () => void;
+} {
+  const ctx = useCtx("useFilesEditorSelection");
+  return {
+    selected: ctx.selected,
+    selectedIds: ctx.selected.map((f) => f.id),
+    files: ctx.files,
+    selectMode: ctx.selectMode,
+    clear: ctx.clear,
+    exit: ctx.exit,
+  };
+}
 
 export interface FilesEditorProps {
   /** Completed/saved files. */
   files: DisplayFile[];
   /** The live add-queue (in-flight uploads) — pass through from your upload mechanism. */
   uploads?: FileUpload[];
-  /** Picked files → the host uploads + appends to `files`. Omit to hide Upload. */
+  /** Picked files → the host uploads + appends to `files`. Omit to hide `FilesEditorUpload`. */
   onAdd?: (files: File[]) => void;
   /** Override the Upload action's picker (e.g. a native document picker). When
-   *  set, the Upload button calls this instead of the built-in web `pickFiles`. */
+   *  set, `FilesEditorUpload` calls this instead of the built-in web `pickFiles`. */
   onUpload?: () => void;
-  /** Show a "Download as ZIP" action in select mode (2+ selected), given the files. */
-  onDownloadZipSelected?: (files: DisplayFile[]) => void;
-  /** Remove a completed file. Omit (or `readOnly`) for a view-only surface. */
+  /** Remove a completed file. Omit to hide `FilesEditorRemove` and the per-tile ✕. */
   onRemove?: (id: string) => void;
   /** Show the per-tile ✕ during SELECT mode (default `true`). The default
    *  (non-select) view NEVER shows a ✕ regardless — this governs select mode
-   *  only. Set `false` when batch Select → Menu → Delete is the sole delete
-   *  path (e.g. a cell popover), so a tile in select mode toggles selection and
-   *  nothing else. */
+   *  only. Set `false` when a bar action is the sole delete path, so a tile in
+   *  select mode toggles selection and nothing else. */
   selectTileRemove?: boolean;
   /** Cancel an in-flight upload / retry a failed one (when using `uploads`). */
   onUploadRemove?: (id: string) => void;
   onRetry?: (id: string) => void;
   onRetryAll?: () => void;
-  /** Show a Share action in select mode, given the selected files. Omit to hide it. */
-  onShareSelected?: (files: DisplayFile[]) => void;
   /** Override the default download (`downloadFileFromUrl`). */
   onDownload?: (file: DisplayFile) => void;
-  /** Download + preview only (no Upload / Select / remove). */
-  readOnly?: boolean;
   /** Native `accept` filter for the file picker. */
   accept?: string;
   itemSize?: number;
   minItemWidth?: number;
   /** Fixed column count for the grid (passed through to `FileGrid`). */
   columns?: number;
-  /** Cap the grid's height (px) so it SCROLLS and the toolbar pins below it —
+  /** Cap the grid's height (px) so it SCROLLS and the bar pins below it —
    *  for a height-bounded container (a popover, a drawer). Omit in free-flow
    *  layouts (a form field) where the grid should grow and the page scrolls. */
   gridMaxHeight?: number;
-  /** Translated labels. Defaults to English. */
+  /** Per-instance overrides for the shipped bar pieces. Falls back to the
+   *  active `LoticsLocale`. */
   labels?: Partial<FilesEditorLabels>;
   /** Credentials mode for the built-in gallery's preview fetches — `"include"`
    *  for the host's auth-gated proxy URLs, omitted for an app's presigned URLs.
    *  See `FilePreviewProps`. */
   credentials?: RequestCredentials;
   /** Translated labels for the built-in full-screen gallery (its toolbar action
-   *  buttons + confirm dialog). Defaults to English. */
+   *  buttons + confirm dialog). Defaults to the active locale. */
   galleryLabels?: Partial<GalleryLabels>;
+  /**
+   * The bar (and anything else) BELOW the grid. Compose it from the shipped
+   * pieces plus your own verbs; omit it entirely for a grid that only previews.
+   */
+  children?: ReactNode;
 }
 
 /**
- * The all-in-one attachment surface: an upload-aware thumbnail grid (`FileGrid`)
- * with a toolbar BELOW it, a batch SELECT mode, full-screen preview
- * (`FileGalleryModal`), and download / share / Alert-confirmed remove. Agnostic —
- * the host wires `onAdd` (picked files → its upload) and `onRemove`; select mode,
- * the gallery, download and the remove confirm are all internal. Mirrors the
- * frontend `files_editor`. For a plain row list use `FileRows`; for the bare
- * upload grid use `FileGrid`.
+ * The attachment surface, as a COMPOUND: this root owns the parts a host cannot
+ * reasonably re-implement — the batch selection, the full-screen gallery, and the
+ * Alert-confirmed remove — and renders the upload-aware grid (`FileGrid`). What
+ * you can DO to the files is composed below it, so a surface offers exactly its
+ * own verbs in its own order.
+ *
+ * It was a monolith with a fixed toolbar and a generic "Menu" holding whatever
+ * the kit happened to support (download, share, delete). That shape had two
+ * costs, and both showed up in real apps: a HOST verb had nowhere to go, so a
+ * screen that needed one (an AI read over the picked papers) hand-rolled the
+ * whole grid and lost the gallery and the upload queue with it; and the actions
+ * that DID exist hid behind a label that names a widget rather than an act, five
+ * interactions deep for "delete this scan".
+ *
+ * ```tsx
+ * <FilesEditor files={docs} uploads={queue} onAdd={add} onRemove={remove}>
+ *   <FilesEditorBar>
+ *     <FilesEditorUpload />
+ *     <FilesEditorSelect />
+ *     <FilesEditorBarSpacer />
+ *     <FilesEditorDownload />
+ *     <FilesEditorRemove />
+ *   </FilesEditorBar>
+ * </FilesEditor>
+ * ```
+ *
+ * For a plain row list use `FileRows`; for the bare grid with no selection or
+ * gallery, `FileGrid`.
  */
 export function FilesEditor(props: FilesEditorProps) {
   const {
@@ -116,15 +183,12 @@ export function FilesEditor(props: FilesEditorProps) {
     uploads,
     onAdd,
     onUpload,
-    onDownloadZipSelected,
     onRemove,
     selectTileRemove = true,
     onUploadRemove,
     onRetry,
     onRetryAll,
-    onShareSelected,
     onDownload,
-    readOnly = false,
     accept,
     itemSize,
     minItemWidth,
@@ -133,31 +197,44 @@ export function FilesEditor(props: FilesEditorProps) {
     labels,
     credentials,
     galleryLabels,
+    children,
   } = props;
-  const l = { ...DEFAULT_LABELS, ...labels };
+  const loc = useLoticsLocale().filesEditor;
+  const l = useMemo(() => ({ ...loc, ...labels }), [loc, labels]);
 
-  const [selectMode, setSelectMode] = useState(false);
-  const [selected, setSelected] = useState<Set<string>>(() => new Set());
-  const [menuOpen, setMenuOpen] = useState(false);
+  const [selectMode, setSelectModeState] = useState(false);
+  const [selectedIds, setSelectedIds] = useState<Set<string>>(() => new Set());
   const [galleryIndex, setGalleryIndex] = useState<number | null>(null);
 
-  const hasFiles = files.length > 0;
-  const allSelected = hasFiles && selected.size === files.length;
-  const selectedFiles = files.filter((f) => selected.has(f.id));
+  const selected = useMemo(() => files.filter((f) => selectedIds.has(f.id)), [files, selectedIds]);
+
+  const clear = useCallback(() => setSelectedIds(new Set()), []);
+  const exit = useCallback(() => { setSelectModeState(false); setSelectedIds(new Set()); }, []);
+  const setSelectMode = useCallback((on: boolean) => { if (on) setSelectModeState(true); else exit(); }, [exit]);
+  const toggle = useCallback((id: string) => {
+    setSelectedIds((s) => { const n = new Set(s); if (n.has(id)) n.delete(id); else n.add(id); return n; });
+  }, []);
+  const setAll = useCallback((on: boolean) => {
+    setSelectedIds(on ? new Set(files.map((f) => f.id)) : new Set());
+  }, [files]);
+
+  const download = useCallback((fs: DisplayFile[]) => {
+    for (const f of fs) {
+      if (onDownload) onDownload(f);
+      else void downloadFileFromUrl(f.url, f.filename, { credentials });
+    }
+  }, [onDownload, credentials]);
 
-  const toggle = (id: string) =>
-    setSelected((s) => { const n = new Set(s); if (n.has(id)) n.delete(id); else n.add(id); return n; });
-  const exitSelect = () => { setSelectMode(false); setSelected(new Set()); };
-  const download = (fs: DisplayFile[]) =>
-    fs.forEach((f) => (onDownload ? onDownload(f) : void downloadFileFromUrl(f.url, f.filename, { credentials })));
-  const confirmRemove = (onConfirm: () => void) =>
+  const confirmRemove = useCallback((fs: DisplayFile[], onConfirm: () => void) => {
     Alert.alert(l.removeTitle, l.removeMessage, [
       { text: l.removeCancel, style: "cancel" },
       { text: l.removeConfirm, style: "destructive", onPress: onConfirm },
     ]);
-  const upload = () => {
-    if (!onAdd) return;
-    void pickFiles({ multiple: true, accept }).then((picked) => { if (picked.length > 0) onAdd(picked); });
+  }, [l.removeTitle, l.removeMessage, l.removeCancel, l.removeConfirm]);
+
+  const ctx: FilesEditorCtx = {
+    files, selectMode, setSelectMode, selectedIds, selected, toggle, setAll, clear, exit,
+    onAdd, onUpload, onRemove, accept, labels: l, download, confirmRemove,
   };
 
   const grid = (
@@ -167,14 +244,16 @@ export function FilesEditor(props: FilesEditorProps) {
       itemSize={itemSize}
       minItemWidth={minItemWidth}
       columns={columns}
-      selectedIds={selectMode ? selected : undefined}
+      selectedIds={selectMode ? selectedIds : undefined}
       onToggleSelect={selectMode ? toggle : undefined}
       onFilePress={selectMode ? undefined : (f) => setGalleryIndex(files.findIndex((x) => x.id === f.id))}
       // The per-tile ✕ is a SELECT-mode affordance (opt-out via `selectTileRemove`)
       // — the default view stays a clean preview surface so a stray tap can't drop a
-      // file, and a `selectTileRemove={false}` surface deletes only via the menu.
+      // file, and a `selectTileRemove={false}` surface deletes only via the bar.
       onDisplayRemove={
-        !readOnly && selectMode && selectTileRemove && onRemove ? (id) => confirmRemove(() => onRemove(id)) : undefined
+        selectMode && selectTileRemove && onRemove
+          ? (id) => confirmRemove(files.filter((f) => f.id === id), () => onRemove(id))
+          : undefined
       }
       onUploadRemove={onUploadRemove}
       onRetry={onRetry}
@@ -183,74 +262,104 @@ export function FilesEditor(props: FilesEditorProps) {
   );
 
   return (
-    <View style={styles.root}>
-      {gridMaxHeight !== undefined ? (
-        <ScrollView style={{ maxHeight: gridMaxHeight }}>{grid}</ScrollView>
-      ) : (
-        grid
-      )}
+    <Ctx.Provider value={ctx}>
+      <View style={styles.root}>
+        {gridMaxHeight !== undefined ? <ScrollView style={{ maxHeight: gridMaxHeight }}>{grid}</ScrollView> : grid}
+        {children}
+        <FileGalleryModal
+          files={files}
+          activeIndex={galleryIndex}
+          onIndexChange={setGalleryIndex}
+          onRemove={onRemove}
+          onDownload={onDownload}
+          credentials={credentials}
+          labels={galleryLabels}
+        />
+      </View>
+    </Ctx.Provider>
+  );
+}
+
+/** The action row under the grid. Lay it out left-to-right; a
+ *  `FilesEditorBarSpacer` pushes what follows to the right edge. */
+export function FilesEditorBar({ children }: { children: ReactNode }) {
+  return <View style={styles.bar}>{children}</View>;
+}
 
-      {readOnly ? (
-        hasFiles ? (
-          <View style={styles.bar}>
-            <View style={styles.spacer} />
-            <Button title={l.downloadAll} color="secondary" onPress={() => download(files)} />
-          </View>
-        ) : null
-      ) : selectMode ? (
-        <View style={styles.bar}>
-          <Button
-            title={allSelected ? l.deselectAll : l.selectAll}
-            color="muted"
-            onPress={() => setSelected(allSelected ? new Set() : new Set(files.map((f) => f.id)))}
-          />
-          <Popover open={menuOpen} onOpenChange={setMenuOpen} align="start">
-            <PopoverTrigger>
-              <Button title={l.menu} color="secondary" disabled={selected.size === 0} onPress={() => setMenuOpen(true)} />
-            </PopoverTrigger>
-            <PopoverContent>
-              <View style={styles.menu}>
-                <MenuButton icon="download" title={l.downloadSelected(selected.size)} onPress={() => { setMenuOpen(false); download(selectedFiles); }} />
-                {onDownloadZipSelected && selected.size > 1 ? (
-                  <MenuButton icon="file-down" title={l.downloadZip} onPress={() => { setMenuOpen(false); onDownloadZipSelected(selectedFiles); }} />
-                ) : null}
-                {onShareSelected ? (
-                  <MenuButton icon="share" title={l.share} onPress={() => { setMenuOpen(false); onShareSelected(selectedFiles); }} />
-                ) : null}
-                {onRemove ? (
-                  <MenuButton icon="trash" title={l.delete} danger onPress={() => { setMenuOpen(false); confirmRemove(() => { selectedFiles.forEach((f) => onRemove(f.id)); exitSelect(); }); }} />
-                ) : null}
-              </View>
-            </PopoverContent>
-          </Popover>
-          <View style={styles.spacer} />
-          <Button title={l.done} color="secondary" onPress={exitSelect} />
-        </View>
-      ) : (
-        <View style={styles.bar}>
-          {onAdd || onUpload ? <Button title={l.upload} color="primary" onPress={onUpload ?? upload} /> : null}
-          {hasFiles ? <Button title={l.select} color="secondary" onPress={() => setSelectMode(true)} /> : null}
-          <View style={styles.spacer} />
-          {hasFiles ? <Button title={l.downloadAll} color="secondary" onPress={() => download(files)} /> : null}
-        </View>
-      )}
+/** Pushes the rest of the bar to the right edge. */
+export function FilesEditorBarSpacer() {
+  return <View style={styles.spacer} />;
+}
 
-      <FileGalleryModal
-        files={files}
-        activeIndex={galleryIndex}
-        onIndexChange={setGalleryIndex}
-        onRemove={!readOnly && onRemove ? onRemove : undefined}
-        onDownload={onDownload}
-        credentials={credentials}
-        labels={galleryLabels}
-      />
-    </View>
+/** Add files. Renders nothing when the root was given neither `onAdd` nor
+ *  `onUpload` — a surface cannot offer an upload it has no handler for. */
+export function FilesEditorUpload({ title }: { title?: string } = {}) {
+  const { onAdd, onUpload, accept, labels } = useCtx("FilesEditorUpload");
+  if (!onAdd && !onUpload) return null;
+  const pick = () => {
+    if (onUpload) { onUpload(); return; }
+    void pickFiles({ multiple: true, accept }).then((picked) => { if (picked.length > 0) onAdd?.(picked); });
+  };
+  return <Button title={title ?? labels.upload} color="primary" onPress={pick} />;
+}
+
+/** Enter batch-select mode, and leave it. One control, because it is one
+ *  toggle — it reads "Chọn" at rest and "Xong" while selecting. */
+export function FilesEditorSelect() {
+  const { files, selectMode, setSelectMode, labels } = useCtx("FilesEditorSelect");
+  if (files.length === 0) return null;
+  return selectMode ? (
+    <Button title={labels.done} color="secondary" onPress={() => setSelectMode(false)} />
+  ) : (
+    <Button title={labels.select} color="secondary" onPress={() => setSelectMode(true)} />
+  );
+}
+
+/** Select-all / deselect-all. Only meaningful while selecting, so it renders
+ *  nothing at rest. */
+export function FilesEditorSelectAll() {
+  const { files, selectMode, selectedIds, setAll, labels } = useCtx("FilesEditorSelectAll");
+  if (!selectMode || files.length === 0) return null;
+  const allSelected = selectedIds.size === files.length;
+  return <Button title={allSelected ? labels.deselectAll : labels.selectAll} color="muted" onPress={() => setAll(!allSelected)} />;
+}
+
+/**
+ * Download. Acts on the SELECTION while selecting and on everything at rest, so
+ * it is one control rather than two that mean the same thing in different modes.
+ */
+export function FilesEditorDownload() {
+  const { files, selectMode, selected, download, labels } = useCtx("FilesEditorDownload");
+  if (files.length === 0) return null;
+  if (!selectMode) return <Button title={labels.downloadAll} color="secondary" onPress={() => download(files)} />;
+  return (
+    <Button
+      title={labels.downloadSelected(selected.length)}
+      color="secondary"
+      disabled={selected.length === 0}
+      onPress={() => download(selected)}
+    />
+  );
+}
+
+/** Remove the picked files, behind the root's Alert confirm. Renders nothing
+ *  when the root was given no `onRemove`, and nothing at rest — removing is an
+ *  act on a chosen set, never on "everything". */
+export function FilesEditorRemove() {
+  const { selectMode, selected, onRemove, confirmRemove, exit, labels } = useCtx("FilesEditorRemove");
+  if (!onRemove || !selectMode) return null;
+  return (
+    <Button
+      title={labels.delete}
+      color="danger-secondary"
+      disabled={selected.length === 0}
+      onPress={() => confirmRemove(selected, () => { for (const f of selected) onRemove(f.id); exit(); })}
+    />
   );
 }
 
 const styles = StyleSheet.create({
   root: { gap: 10 },
-  bar: { flexDirection: "row", alignItems: "center", gap: 8 },
+  bar: { flexDirection: "row", alignItems: "center", gap: 8, flexWrap: "wrap" },
   spacer: { flex: 1 },
-  menu: { minWidth: 200, gap: 2, padding: 4 },
 });

package/src/locale.tsx

@@ -118,6 +118,36 @@ export interface LoticsLocale {
   fileDropzone: { label: string; hint: string; drop: string };
   /** `FileThumbnail`'s `RemoveButton`: the ✕ a11y name. */
   fileThumbnail: { remove: string };
+  /** `FilesEditor`'s shipped bar pieces (upload · select · select-all · download
+   *  · remove) and the remove confirm. A HOST verb is a plain `Button` and names
+   *  itself, so nothing here is about what an app happens to do with a file. */
+  filesEditor: {
+    upload: string;
+    select: string;
+    selectAll: string;
+    deselectAll: string;
+    done: string;
+    downloadAll: string;
+    downloadSelected: (n: number) => string;
+    delete: string;
+    removeTitle: string;
+    removeMessage: string;
+    removeCancel: string;
+    removeConfirm: string;
+  };
+  /** `FileGrid`'s in-flight tiles (`UploadingThumbnail`) + its retry-all footer:
+   *  the states an upload can be caught in, and what to press about them. The
+   *  plain `uploading` state has no entry on purpose — a spinner needs no word in
+   *  any language, and only a state that wants ATTENTION earns one. */
+  fileUpload: {
+    paused: string;
+    retrying: string;
+    failed: string;
+    /** Retry is futile on the same input — a dead picker ref, or zero bytes. */
+    unavailable: string;
+    retry: string;
+    retryAll: string;
+  };
   /** `ImageGallery`: the empty state, the inline rotate controls, and the
    *  press-to-zoom a11y name. */
   imageGallery: { empty: string; rotateLeft: string; rotateRight: string; zoom: string };
@@ -250,6 +280,28 @@ export const en: LoticsLocale = {
   overlay: { close: "Close" },
   fileDropzone: { label: "Drag files here", hint: "or click, or paste (⌘V)", drop: "Drop to upload" },
   fileThumbnail: { remove: "Remove" },
+  filesEditor: {
+    upload: "Upload",
+    select: "Select",
+    selectAll: "Select all",
+    deselectAll: "Deselect all",
+    done: "Done",
+    downloadAll: "Download all",
+    downloadSelected: (n: number) => `Download (${n})`,
+    delete: "Delete",
+    removeTitle: "Remove attachment?",
+    removeMessage: "This removes the file.",
+    removeCancel: "Cancel",
+    removeConfirm: "Remove",
+  },
+  fileUpload: {
+    paused: "Paused",
+    retrying: "Retrying",
+    failed: "Upload failed",
+    unavailable: "Can't upload",
+    retry: "Retry upload",
+    retryAll: "Retry all",
+  },
   imageGallery: { empty: "No images.", rotateLeft: "Rotate left", rotateRight: "Rotate right", zoom: "Zoom image" },
   infoPopover: { more: "More information" },
   matrix: { total: "Total", less: "Less", more: "More" },
@@ -376,6 +428,28 @@ export const vi: LoticsLocale = {
   overlay: { close: "Đóng" },
   fileDropzone: { label: "Kéo tệp vào đây", hint: "hoặc bấm chọn, hoặc dán (Ctrl+V)", drop: "Thả để tải lên" },
   fileThumbnail: { remove: "Xóa" },
+  filesEditor: {
+    upload: "Tải lên",
+    select: "Chọn",
+    selectAll: "Chọn tất cả",
+    deselectAll: "Bỏ chọn",
+    done: "Xong",
+    downloadAll: "Tải tất cả",
+    downloadSelected: (n: number) => `Tải ${n} tệp`,
+    delete: "Xóa",
+    removeTitle: "Xóa tệp?",
+    removeMessage: "Tệp sẽ bị gỡ khỏi bản ghi.",
+    removeCancel: "Hủy",
+    removeConfirm: "Xóa",
+  },
+  fileUpload: {
+    paused: "Tạm dừng",
+    retrying: "Đang thử lại",
+    failed: "Không tải lên được",
+    unavailable: "Tệp không đọc được",
+    retry: "Thử lại",
+    retryAll: "Thử lại tất cả",
+  },
   imageGallery: { empty: "Chưa có ảnh.", rotateLeft: "Xoay trái", rotateRight: "Xoay phải", zoom: "Phóng to ảnh" },
   infoPopover: { more: "Thông tin thêm" },
   matrix: { total: "Tổng", less: "Ít", more: "Nhiều" },

package/src/uploading_thumbnail.tsx

@@ -14,9 +14,11 @@ import { isImageMimeType } from "./mime";
 /** In-flight upload states (everything except a completed file). */
 export type UploadStatus = "preparing" | "queued" | "uploading" | "paused_offline" | "retrying" | "error";
 
-/** Status text for the non-happy-path states. i18n-free defaults (English); the
- *  Lotics host injects translations. The common `uploading` state stays text-free
- *  (a spinner is self-evident) — only states that need attention get a word. */
+/** Status text for the non-happy-path states. This component stays i18n-free —
+ *  `FileGrid` resolves the words (per-instance labels over the active
+ *  `LoticsLocale`) and hands them in, so nothing below it reads context. The
+ *  common `uploading` state stays text-free (a spinner is self-evident) — only
+ *  states that need attention get a word. */
 export interface UploadStatusLabels {
   /** Upload paused because the device is offline. Default "Paused". */
   paused?: string;