@lotics/ui 5.8.0 → 5.9.0

package/AGENTS.md

@@ -24,8 +24,9 @@ Pick by capability, not by name. (→ the source file for the API.)
 
 - **Actions** — `Button` (labelled; `title` is MANDATORY; `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, the SAME `color` palette as Button, plus `loading`;
-  needs `accessibilityLabel`/`tooltip`), `LinkButton` (quiet ghost
+  here. `size` `lg` 40px / `md` 28px / `sm` 24px, the SAME `color` palette as Button, 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`), `LinkButton` (quiet ghost
   action — Clear / Select all), `Chip` (dismissible facet chip). A button is never a raw
   `Pressable`. For a link OUT (a URL / record / document) use `Link` — underline+blue, the
   destination signal; the opposite of `LinkButton` (a quiet in-app action, never underlined).
@@ -74,7 +75,15 @@ Pick by capability, not by name. (→ the source file for the API.)
   `Alert` (the blocking confirm).
 - **Status / feedback** — `Badge` / `StatusBadge`, `Callout` (inline status), `EmptyState`,
   `CompletionState`, `ActivityIndicator` / `Loading`, `Skeleton`.
-- **Files** — `FileDropzone`, `FileThumbnail` / `FileThumbnailGrid`, `FilePreview` /
+- **Files** — `FileDropzone`, `FileRows` (batteries-included file LIST: tap a row → built-in
+  full-screen gallery, ⋯ 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 — use this for any add-files screen), `FileThumbnail` / `FileThumbnailGrid`
+  (square tiles, display-only), `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 / action
+  / remove; `onPress` makes the whole row a pressable door, `trailing` stays an independently-pressable
+  sibling; for checklists & readable lists), `FileBadge` (the two-tone type mark), `FilePreview` /
   `FileGalleryModal`, `ImageGallery`; for gated CRUD compose locally with `useSelectionMode` +
   `shareOrDownloadFiles` + `rotateImageToBlob` (see §Data entry → Attachments).
 - **Specialized work surfaces** — `ScanField` (scan/verify), `Stepper` (a guided run / progress
@@ -199,23 +208,49 @@ marked + disabled), not a generic text menu. A composition (Badge + Button + Pop
 
 ### Attachments — a full add / preview / DELETE field
 Capture with `<FileDropzone onFiles accept label hint dropLabel height>` (drag-over lights the
-accent; click falls back to a picker); display what landed with `<FileThumbnailGrid files>` ABOVE
+accent; click falls back to a picker); display what landed with **`<FileGrid files uploads>`** ABOVE
 the dropzone (existing files are the content; the dropzone sinks to the bottom as the "add more"
-affordance — only the empty state leads with it). Make it CRUDable by wiring the grid's two
-callbacks: `onFilePress` → set a `number|null` index that drives `<FileGalleryModal files
-activeIndex onIndexChange>` (built-in prev/next/ESC/rotate); `onRemove` → drop the file from state
-(the grid renders a ✕ on each thumbnail automatically). Keep label+grid+dropzone on a `gap` (a bare
-`CardBody` has none). `FileThumbnail` shows the right surface per MIME (image thumbnail · doc card ·
-media card), and takes `uploading` to dim it with a spinner while the bytes are still going up.
-Never hand-build a drop well, a file row grid, or a preview modal. In a custom-code APP, don't
-hand-roll the upload+preview state either — `@lotics/app-sdk` `useAttachments()` gives the chat's
-instant-preview lifecycle (local object-URL now, `file_id` on complete); map each `AttachedFile` to a
-`DisplayFile` (snake → camel: `preview_url`→`url`, `mime_type`→`mimeType`) for
-`<FileThumbnail file={…} uploading={f.status === "uploading"} />`.
+affordance — only the empty state leads with it). `FileGrid` is the upload-aware grid: `files` are
+the saved/completed `DisplayFile`s, `uploads` is 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`; the Lotics `@lotics/ui-internal` adapter already injects vi/en). 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 (filename · counter · ⋯actions (download, optional
+`onOpenExternal`/`onRemove`) · close-✕), prev/next, ESC, and rotate; `onDisplayRemove`/`onUploadRemove`
+→ drop the file / cancel the upload (the grid renders a ✕ on each tile automatically); `onRetry` /
+`onRetryAll` for failed uploads. In a sandboxed custom-code app the toolbar's "open in new tab" can't
+pop a window — pass `onOpenExternal` wired to the SDK's `openExternal` (omit it elsewhere and the
+action hides). PDF/Word/Excel/CSV all render INLINE here (pdf.js / `@lotics/docx` / `@lotics/xlsx`,
+lazy) — no native `<iframe>` viewer, so they work inside the cross-origin app iframe. Keep
+label+grid+dropzone on a `gap` (a bare `CardBody` has none). By default `FileGrid` tiles FILL the
+container width — a uniform size (≥ `minItemWidth`, default 96) so full rows span the width and reflow
+as it changes; a short last row keeps that size and left-aligns (no stretched tiles, no empty cells).
+Pass `columns` for a fixed column count, or `itemSize` for exact fixed-size tiles. For a dense strip
+in a FIXED-width container that must NOT wrap, pass `singleRow` — it fits as many tiles as the width
+allows and collapses the rest into a clickable "+N" overflow tile (`onOverflowPress(hiddenCount)`,
+which the host wires — e.g. open the gallery at the first hidden file). This is the responsive overflow
+pattern (avatar stack / Finder); prefer it over a hardcoded `maxVisible`, which can't adapt to width.
+Under the hood it composes `FileThumbnail` (the completed tile — right surface per
+MIME: image thumbnail · a doc tile with the `FileBadge` centered + a single-line filename · media
+card; also takes `isTemplate` to overlay a TMPL marker) and `UploadingThumbnail` (the in-flight tile);
+reach for either directly only when hand-rolling a NON-grid layout. **When the filename must be
+readable, use `FileRow`** — a horizontal LINE (`FileBadge` or a `placeholder` + the FULL name + a meta
+line + a composable `trailing` slot). `onPress` makes the whole row a pressable door (open the file);
+`trailing` (a status `Badge`, an action, a remove ✕) stays an independently-pressable sibling. For
+attachment lists / message files / document checklists where a square tile truncates the name. Never hand-build a drop well, a file grid, the upload tiles, or a preview
+modal. In a custom-code APP, don't hand-roll the upload+preview state either — `@lotics/app-sdk`
+`useAttachments()` gives the chat's instant-preview lifecycle (local object-URL now, `file_id` on
+complete); map each `AttachedFile` to a `FileUpload` (ready → `{ status: "complete", id, file: {…} }`,
+else `{ status, id, filename, mimeType: mime_type, previewUrl: preview_url }`) and feed `FileGrid`'s
+`uploads` — `onUploadRemove={remove}`.
 
 **Gated file CRUD is a PATTERN, composed locally — not a sealed kit component.** When a file field must
-GUARD deletion (operator-facing, accidental delete is a real risk), compose it in the app from the kit
-pieces; don't reach for a one-size widget (the action set + layout vary per app — the host frontend's
+GUARD deletion (operator-facing, accidental delete is a real risk), DON'T use `FileGrid` (its per-tile
+✕ is exactly the stray-tap risk you're guarding against) — compose it in the app from the kit pieces;
+don't reach for a one-size widget (the action set + layout vary per app — the host frontend's
 `files_editor` and each app compose their own). The recipe: `FileDropzone` (add) + `FileThumbnailGrid
 files selectedIds onFilePress` (pass `selectedIds` ONLY in select mode) + `FileGalleryModal` (view +
 rotate + persist) + a `Dialog` confirm, all driven by **`useSelectionMode()`** — the reusable LOGIC. The
@@ -479,6 +514,16 @@ was only ever about the review surfaces' sparkles/severity glyphs, not functiona
     padded container, NO `Divider`s (the gap + rounded hover separate them).
   Right-hand columns align only if every trailing element is FIXED-width (give each trailing action
   a fixed `width`, so amount/status columns don't jitter).
+- **Row actions are ALWAYS-VISIBLE siblings, never hover-revealed, never nested.** A pressable row =
+  a role-less surface (the hover/press wash, via DOM `mouseenter` so it covers the whole row) + an
+  accessible "Open …" door (the body, a button) + trailing actions (⋯, remove ✕, edit) as SIBLINGS of
+  the door — a button must not contain another button, so the action is independently pressable and
+  the ✕ isn't swallowed by the row press (`FileRow` and `PressableRow` are the references). Actions
+  stay **visible** — a hover-only action is invisible to keyboard and touch users. The ONLY exception
+  is a DENSE tree/register where a persistent per-row action would clutter (e.g. the DB sidebar):
+  reveal on hover **OR focus-within**, keeping the action in the DOM + tab order and gating only its
+  opacity, so it's still keyboard-reachable. Do that locally — there is no shared hover-reveal
+  primitive (the old `HoverAction` made the keyboard-inaccessible anti-pattern easy and was removed).
 - **Master-detail = list + workspace `Drawer` with sequencing.** Pressing a PRIMARY entity row
   opens the record workspace in a `Drawer` with `onPrev`/`onNext`/`position` ("3/24") over the
   visible ordering (←/→ built in). Key the drawer body by record id so per-record state resets on
@@ -619,7 +664,7 @@ command_menu · alert · peek · empty_state · completion_state · callout (Cal
 CalloutText · CalloutActions) · kpi_card · kpi_strip · metric · trend_chip · sparkline ·
 bar_chart · line_chart · pie_chart · ring_gauge · progress_bar · stacked_progress_bar · breakdown ·
 status_grid (StatusGrid + StatusLegend) · heatmap · legend_item · remainder_meter · allocation_row ·
-scan_field · file_dropzone · file_thumbnail · file_thumbnail_grid · file_preview ·
+scan_field · file_dropzone · file_grid (FileGrid — the upload-aware grid: completed files + a live upload queue in one surface; FileUpload/PendingUpload types; the add-files default) · uploading_thumbnail (UploadingThumbnail — the single in-flight upload tile FileGrid renders; reach for it only when hand-rolling a non-grid upload layout) · file_thumbnail · file_thumbnail_grid · file_row · file_rows (FileRows — batteries-included file list: row press → built-in gallery + a ⋯ Download/Open-external/Remove menu; composes FileRow + ActionMenu + FileGalleryModal) · file_preview ·
 file_gallery_modal · image_gallery · use_selection_mode · share_or_download · rotate_image · avatar · skeleton · activity_indicator · loading · divider ·
 spacer · stack · section_card · page_header · page_content · calendar (calendar/index.ts) · gantt ·
 comments_thread · agent_run (live streaming work feed) · agent_progress (its compact floating

package/examples/tpl_convert.tsx

@@ -8,7 +8,7 @@ import { Card } from "@lotics/ui/card";
 import { DetailRow } from "@lotics/ui/detail_row";
 import { Divider } from "@lotics/ui/divider";
 import { Drawer, DrawerFooter } from "@lotics/ui/drawer";
-import { FileBadge } from "@lotics/ui/file_badge";
+import { FileRow } from "@lotics/ui/file_row";
 import { FileDropzone } from "@lotics/ui/file_dropzone";
 import { FileThumbnailGrid } from "@lotics/ui/file_thumbnail_grid";
 import { FileGalleryModal } from "@lotics/ui/file_gallery_modal";
@@ -37,8 +37,8 @@ import { Timeline, type TimelineItem } from "@lotics/ui/timeline";
 // required-document checklist with a free FILE DUMP for anything extra. The
 // drawer's ◀▶ keys walk the manager down the queue without closing it.
 //
-// Reference composition — Drawer (list nav) + Stepper + FileBadge (+ placeholder)
-// + Pagination + DetailRow.
+// Reference composition — Drawer (list nav) + Stepper + FileRow (badge + name +
+// meta + a trailing status/action slot) + Pagination + DetailRow.
 // ─────────────────────────────────────────────────────────────────────────────
 
 const CODES: Record<string, string> = {
@@ -141,21 +141,9 @@ function QueueRow({ app, active, onPress }: { app: Applicant; active: boolean; o
   );
 }
 
-// A document line — a FileBadge (or a same-footprint placeholder) + name + meta.
-function FileRow({ name, meta, mimeType, placeholder, tone, action }: {
-  name: string; meta?: string; mimeType?: string; placeholder?: boolean; tone?: "received" | "ready"; action?: ReactNode;
-}) {
-  return (
-    <View style={{ flexDirection: "row", alignItems: "center", gap: 12 }}>
-      <FileBadge size={30} mimeType={mimeType} placeholder={placeholder} />
-      <View style={{ flex: 1 }}>
-        <Text size="sm" weight="medium">{name}</Text>
-        {meta ? <Text size="xs" color="muted">{meta}</Text> : null}
-      </View>
-      {action ?? (tone === "received" ? <Badge variant="dot" label="Received" color="emerald" /> : tone === "ready" ? <Badge variant="dot" label="Generated" color="blue" /> : null)}
-    </View>
-  );
-}
+// Document status chips — the `trailing` slot content for the kit's `FileRow`.
+const receivedBadge = <Badge variant="dot" label="Received" color="emerald" />;
+const generatedBadge = <Badge variant="dot" label="Generated" color="blue" />;
 
 // The extra-documents zone — the data-capture attachment field: a thumbnail grid
 // (click to preview in the gallery, ✕ to delete) above a dropzone. Read-only once
@@ -189,7 +177,7 @@ function UploadsField({ uploads, editable, onAdd, onRemove }: {
       ) : uploads.length === 0 ? (
         <Text size="sm" color="muted">No extra files.</Text>
       ) : null}
-      <FileGalleryModal files={uploads} activeIndex={active} onIndexChange={setActive} captionHint="ESC to close · ←/→ to move" />
+      <FileGalleryModal files={uploads} activeIndex={active} onIndexChange={setActive} />
     </View>
   );
 }
@@ -217,7 +205,7 @@ function StageSection({ app, index, onMarkDoc, onAddUploads, onRemoveUpload }: {
   if (status === "pending") {
     body = <Text size="sm" color="muted">{`Unlocks after ${STAGES[index - 1].label.toLowerCase()}.`}</Text>;
   } else if (index === 0) {
-    body = <FileRow name="Application fee receipt" meta={status === "done" ? `${formatMoney(app.fee)} · issued` : formatMoney(app.fee)} mimeType="application/pdf" tone={status === "done" ? "ready" : undefined} />;
+    body = <FileRow name="Application fee receipt" meta={status === "done" ? `${formatMoney(app.fee)} · issued` : formatMoney(app.fee)} mimeType="application/pdf" trailing={status === "done" ? generatedBadge : undefined} />;
   } else if (index === 1) {
     body = (
       <View style={{ flexDirection: "row", alignItems: "center", gap: 10 }}>
@@ -229,7 +217,7 @@ function StageSection({ app, index, onMarkDoc, onAddUploads, onRemoveUpload }: {
     body = (
       <View style={{ gap: 10 }}>
         {GENERATED_DOCS.map((d) => (
-          <FileRow key={d} name={d} mimeType="application/pdf" meta={status === "done" ? "generated" : "template"} tone={status === "done" ? "ready" : undefined} />
+          <FileRow key={d} name={d} mimeType="application/pdf" meta={status === "done" ? "generated" : "template"} trailing={status === "done" ? generatedBadge : undefined} />
         ))}
       </View>
     );
@@ -245,9 +233,9 @@ function StageSection({ app, index, onMarkDoc, onAddUploads, onRemoveUpload }: {
               meta={d.received ? `${d.file} · received` : "Awaiting upload"}
               mimeType={d.received ? "application/pdf" : undefined}
               placeholder={!d.received}
-              action={status === "current"
+              trailing={status === "current"
                 ? (d.received ? <Button title="Remove" color="muted" onPress={() => onMarkDoc(d.name, false)} /> : <Button title="Upload" color="secondary" onPress={() => onMarkDoc(d.name, true)} />)
-                : (d.received ? <Badge variant="dot" label="Received" color="emerald" /> : undefined)}
+                : (d.received ? receivedBadge : undefined)}
             />
           ))}
         </View>

package/examples/tpl_order.tsx

@@ -477,7 +477,7 @@ export function TplOrder() {
         </Screen>
       </Dialog>
 
-      <FileGalleryModal files={files} activeIndex={activeFile} onIndexChange={setActiveFile} captionHint="ESC to close · ←/→ to move" />
+      <FileGalleryModal files={files} activeIndex={activeFile} onIndexChange={setActiveFile} />
     </ScrollView>
   );
 }

package/examples/tpl_ratedesk.tsx

@@ -292,7 +292,7 @@ export function TplRatedesk() {
       ) : null}
     </Dialog>
 
-    <FileGalleryModal files={files} activeIndex={activeFile} onIndexChange={setActiveFile} captionHint="ESC to close · ←/→ to move" />
+    <FileGalleryModal files={files} activeIndex={activeFile} onIndexChange={setActiveFile} />
     </>
   );
 }

package/examples/tpl_record.tsx

@@ -295,7 +295,7 @@ export function TplRecord() {
         </Card>
       </View>
 
-      <FileGalleryModal files={docs} activeIndex={activeDoc} onIndexChange={setActiveDoc} captionHint="ESC to close · ←/→ to move" />
+      <FileGalleryModal files={docs} activeIndex={activeDoc} onIndexChange={setActiveDoc} />
     </ScrollView>
   );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "5.8.0",
+  "version": "5.9.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
@@ -18,6 +18,8 @@
     "./file_badge": "./src/file_badge.tsx",
     "./file_dropzone": "./src/file_dropzone.tsx",
     "./file_thumbnail": "./src/file_thumbnail.tsx",
+    "./file_row": "./src/file_row.tsx",
+    "./file_rows": "./src/file_rows.tsx",
     "./file_preview": {
       "react-native": "./src/file_preview.tsx",
       "default": "./src/file_preview.web.tsx"
@@ -29,6 +31,8 @@
     "./use_image_rotation": "./src/use_image_rotation.ts",
     "./use_selection_mode": "./src/use_selection_mode.ts",
     "./file_thumbnail_grid": "./src/file_thumbnail_grid.tsx",
+    "./uploading_thumbnail": "./src/uploading_thumbnail.tsx",
+    "./file_grid": "./src/file_grid.tsx",
     "./pagination": "./src/pagination.tsx",
     "./bar_chart": "./src/bar_chart.tsx",
     "./line_chart": "./src/line_chart.tsx",
@@ -192,7 +196,6 @@
     },
     "./use_async_fn": "./src/use_async_fn.ts",
     "./use_form": "./src/use_form.ts",
-    "./hover_action": "./src/hover_action.tsx",
     "./scroll_to_bottom": "./src/scroll_to_bottom.tsx",
     "./animation_fade_in": "./src/animation_fade_in.tsx",
     "./json_panel": "./src/json_panel.tsx",
@@ -233,6 +236,7 @@
     "expo-image": ">=3.0.0",
     "lucide-react": ">=0.460.0",
     "lucide-react-native": ">=0.460.0",
+    "pdfjs-dist": ">=6.0.0",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "react-native": ">=0.85.0",
@@ -246,6 +250,9 @@
     "@lotics/xlsx": {
       "optional": true
     },
+    "pdfjs-dist": {
+      "optional": true
+    },
     "expo-image": {
       "optional": true
     },
@@ -271,6 +278,7 @@
     "@types/react-dom": "~19.2.2",
     "@vitejs/plugin-react": "^4.3.4",
     "lucide-react": "^0.562.0",
+    "pdfjs-dist": "^6.0.227",
     "react-dom": "^19.2.0",
     "react-native-web": "^0.21.0",
     "vite": "^7.2.4"