@lotics/ui 7.6.0 → 7.8.0

package/AGENTS.md

@@ -108,7 +108,9 @@ Pick by capability, not by name. (→ the source file for the API.)
   `Matrix` (the PIVOT cross-tab: the NUMBER in each cell — optionally a heat wash behind it — plus
   row/column/grand totals; press a cell to drill).
 - **Surfaces & layout** — `Card` (+ `CardHeader`/`CardHeaderTitle`/`CardHeaderMeta`/`CardBody`/
-  `CardFooter`), `SectionCard`, `SectionHeading` (+ `SectionHeadingTitle`), `PageHeader` /
+  `CardFooter`), `Section` (the card-less twin of `Card`: bare gap-spaced region + `SectionHeading`/
+  `SectionHeadingTitle`/`SectionHeadingMeta`; no body component — children are the body), `SectionCard`,
+  `PageHeader` /
   `PageContent`, `Stack`, `Spacer`, `Divider`, `Accordion`, `Tabs`, `SegmentedControl`, `Stepper`.
 - **Rows & registers** — `PressableRow` (THE register row), `ListItem`, `MenuButton`,
   `MenuListItem`, `DetailRow` (label+value for drawers/peeks), `ActionMenu` (⋯), `FloatingActionBar`
@@ -225,7 +227,10 @@ parts render the CHROME, composed as children — never a render-prop pile:
 
 It's a SELECT by default (`ComboboxInput` with NO `icon` → a trailing chevron); opt INTO the
 search-box look with `ComboboxInput icon="search"` only when typing-to-search is primary (a
-large/remote set). `allowCustom` appends a "Create …" row (`customOptionLabel`) when the query
+large/remote set). For a select that the user can RESET, pass `clearable` + `onClear` (deselect):
+the chevron shows while the field is empty and a clear ✕ replaces it once there's a value/query;
+pressing ✕ clears the text and reopens the full-browse list, so `onClear` lands back on the whole
+set (on focus an empty field already browses everything — `recentOptions ?? all`). `allowCustom` appends a "Create …" row (`customOptionLabel`) when the query
 matches no option, emitting the typed text as the value — so a value not in the known set means
 CREATE. Wire that branch to a create overlay (a modal `Dialog` for 4+ fields, an anchored popover
 for 1–3) that builds the new record and attaches it; existing matches attach directly. The create
@@ -286,8 +291,12 @@ marked + disabled), not a generic text menu. A composition (Badge + Button + Pop
 ### Attachments — a full add / preview / DELETE field
 **Default: `<FilesEditor files onAdd onRemove>`** — it bundles the grid + a toolbar (Upload · Select ·
 Download all) + a batch SELECT mode + the gallery + confirmed-remove; the host only owns `files` and
-wires `onAdd` (picked → its upload) / `onRemove`. Reach for the lower-level pieces below only when you
-need custom chrome:
+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); 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. Reach for the
+lower-level pieces below only when you need custom chrome:
 Capture with `<FileDropzone onFiles accept label hint dropLabel height>` (drag-over lights the
 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"
@@ -299,8 +308,13 @@ hand-map an upload to a `FileThumbnail`. Localize the labels with `labels.upload
 `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 · inline action buttons — download, optional
-`onOpenExternal`/`onRemove` · close-✕), prev/next, ESC, and rotate; `onDisplayRemove`/`onUploadRemove`
+FULL-SCREEN viewer with a toolbar (filename · counter · actions — download, optional
+`onOpenExternal`/`onRemove` · close-✕), prev/next, ESC, and rotate. The toolbar is RESPONSIVE: on a
+phone (`useScreenSize().small`) the actions collapse into a `⋯` `ActionMenu` so the close-✕ never
+overflows off-screen (its popover portals inside the modal's own `PortalHost` — a raw `<Modal>` lacks
+one, which is why an earlier inline-less popover rendered behind the overlay). The 90° rotate controls
+for images are NOT in the toolbar — they FLOAT as a pill overlaid on the image (every screen size).
+`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
@@ -619,7 +633,11 @@ was only ever about the review surfaces' sparkles/severity glyphs, not functiona
   the records behind it when pressed — switch to the filtered list, expand in place, or navigate.
   Expansion happens IMMEDIATELY below the pressed element — the composable `Accordion` family
   (`AccordionHeader`/`AccordionTitle`/`AccordionMeta`/`AccordionContent`); header-only = a plain row
-  of identical rhythm, so lists mix expandable + static rows.
+  of identical rhythm, so lists mix expandable + static rows. The body is **flush** with the
+  header's left edge (aligns with the title — like a `Section` body, no indent). `AccordionHeader`
+  is a layout slot: `AccordionTitle`/`AccordionMeta` is the compact list-row heading, but for a
+  **collapsible Section** (configurable font/level/description + count) compose the SAME
+  `SectionHeadingTitle`/`SectionHeadingMeta` inside it — one heading family across static + collapsible.
 - **No dead rows.** Every listed record is actionable. PRIMARY entity rows press-open the workspace
   `Drawer` (sequenced); read-only drill-downs expand via `Accordion` or glance via `Peek`; every
   other row gets an `ActionMenu` (⋯ → MenuButton items: destructive last + **confirmed** via
@@ -680,7 +698,7 @@ was only ever about the review surfaces' sparkles/severity glyphs, not functiona
     port, a customer) rather than a short fixed list. Pass `recentOptions` (the same option list) so
     a click opens the full list, then typing filters. The **From → To route picker** is two of them
     (`icon="map-pin"`, `clearable`) with an `arrow-right` between — flight-search style.
-  · `Tabs` switch between VIEWS/sections (different content/layout) — never a subset of one list.
+  · `Tabs` switch between VIEWS/sections (different content/layout) — never a subset of one list. A tab earns a `status` dot (optional `TabOption.status`) only when its area needs attention (a blocker / missing item) — the resting state has none.
     `SegmentedControl` chooses a MODE/PARAMETER of the SAME view (2–4 peers, no panel swap).
 - **Footer actions align RIGHT.** `PopoverFooter`/`DialogFooter`/`DrawerFooter` default
   `align="end"` — commit at the right edge, secondary to its left. Never left-flow a Save/Submit.
@@ -789,11 +807,11 @@ recipe for a screen JOB; copy and adapt). Pick by the job:
 text ·
 markdown (Markdown — the single canonical markdown renderer for chat, apps, and `AgentRun`; rich on web via react-markdown/remark-gfm with copyable tables, plain-text on native; takes a markdown `children` string; import `@lotics/ui/markdown.css` once for styling) ·
 card (Card · CardHeader · CardHeaderTitle · CardHeaderMeta · CardBody · CardFooter) ·
-section_heading (SectionHeading · SectionHeadingTitle — compound, owns no margin) · badge ·
+section_heading (Section · SectionHeading · SectionHeadingTitle · SectionHeadingMeta — the card-less twin of the Card family, compound, owns no margin; spacing via the Section gap, no body component. `SectionHeadingTitle` takes `weight` medium|semibold — default medium, `semibold` for dense surfaces (a side panel, a stacked group list) where medium blends into the body, matching `CardHeaderTitle`; + `info` for an ⓘ provenance popover after the title, same as `CardHeaderTitle.info`) · badge ·
 option_badge (OptionBadge — a select value as its configured colored badge) ·
 member_chip (MemberChip — avatar + name; the universal person render) ·
 member_select (MemberSelect — a Picker of MemberChip options; the member picker) ·
-status_badge · button · icon_button · link · text_link (TextLink — underlined text that's optionally an `onPress` action or an `href` link, or plain underlined text to wrap in your own pressable; the neutral counterpart to the fixed-blue `Link`) · chip · tabs · segmented_control ·
+status_badge · button · icon_button · link · text_link (TextLink — underlined text that's optionally an `onPress` action or an `href` link, or plain underlined text to wrap in your own pressable; the neutral counterpart to the fixed-blue `Link`) · chip · tabs (Tabs — switch between content sections; WAI-ARIA tablist + roving tabindex; each TabOption takes an optional `status` ColorName → a small attention dot before its label, for a tab whose area needs work) · segmented_control ·
 picker (native `<select>`, plain label-only single) · select (Select — rich/custom-rendered, single/multi, select-all, chips via `renderSelected` + `searchable` + `allowCustom` — the tag field is just a multi Select; opens `OptionList`) · option_list (OptionList — the ONE shared searchable listbox body every selector opens: single/multi, optional internal search, create row, keyboard + native-`<select>` typeahead; host it directly in a `Popover`/`Dialog` for a command palette) · combobox (COMPOUND single-select editable search: `Combobox` root + `ComboboxInput` + `ComboboxContent`, optional `ComboboxEmpty`/`ComboboxFooter`, `useCombobox()`; over the shared `useOptionList` engine; browses on focus; no `multi` — multi-value chips → `Select multi`) ·
 text_input_field · number_input · search_input · form_field · checkbox · checkbox_input · switch ·
 radio_picker · counter · range_slider · date_picker · date_range_filter_field · time_picker ·
@@ -811,7 +829,7 @@ CalloutText · CalloutActions) · kpi_card · kpi_strip · metric · trend_chip
 bar_chart · line_chart · pie_chart · ring_gauge · progress_bar · stacked_progress_bar · breakdown ·
 funnel (Funnel — conversion funnel: narrowing bars + the step rate as a bold aligned headline row, count below; `orientation` vertical|horizontal, `onSelect`/`selectedKey` press-to-drill; the subset/drop-off sibling of stacked_progress_bar's whole-split) ·
 status_grid (StatusGrid + StatusLegend) · heatmap (density cross-tab — colour-only, no numbers) · matrix (Matrix — the PIVOT cross-tab: band-compound `Matrix` root + `Matrix.Header` (corner + axis labels) + `Matrix.Grid` (`display` number|heat|both — the cells, pressable, the value IN the cell) + `Matrix.Totals` (row + column + grand) + `Matrix.Legend`; the data layer `matrixTotals`/`MatrixAxisItem`/`MatrixCellRef` import from `@lotics/ui/matrix_totals`. Pick over `Heatmap` when the NUMBER and totals matter, not just where it clusters) · legend_item · remainder_meter · allocation_row ·
-scan_field · file_dropzone · 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) + built-in gallery + Alert-confirmed remove; host wires `files` + `onAdd`/`onRemove` (+ optional `uploads`, `onShareSelected`, `readOnly`, `labels`, `galleryLabels`); mirrors the frontend cell_files_editor. Use FileGrid/FileRows bare only when you own the chrome) · 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 ·
+scan_field · file_dropzone · 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) + built-in gallery (Download + inline preview; no "open in new tab") + Alert-confirmed remove; host wires `files` + `onAdd`/`onRemove` (+ optional `uploads`, `onShareSelected`, `readOnly`, `labels`, `galleryLabels`, `gridMaxHeight` — cap the grid height so it scrolls and the toolbar pins, for a popover/drawer); mirrors the frontend cell_files_editor. Use FileGrid/FileRows bare only when you own the chrome) · 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 (FilePreview — the universal inline preview: image/PDF/video/audio + Word via `@lotics/docx` + Excel/CSV via `@lotics/xlsx`; the heavy engines are LAZY (dynamic-imported, ~free until a doc of that type is opened) so custom-code APPS can use it too — they just add `@lotics/docx` + `@lotics/xlsx` to their deps. Renders to canvas/DOM, never a nested iframe — works in the sandboxed app iframe) ·
 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "7.6.0",
+  "version": "7.8.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",

package/src/accordion.tsx

@@ -77,8 +77,10 @@ export function Accordion(props: AccordionProps) {
 }
 
 export interface AccordionHeaderProps {
-  /** Usually `AccordionTitle` (+ optionally `AccordionMeta`, a Badge, or any
-   * right-side node). The band is a layout slot. */
+  /** A layout slot. `AccordionTitle` (+ `AccordionMeta`) is the compact
+   * list-row heading; for a configurable section-style header, compose the
+   * SAME `SectionHeadingTitle`/`SectionHeadingMeta` you'd use in a `Section`
+   * (full font/level/description config). Plus a `Badge` or any right-side node. */
   children: ReactNode;
   accessibilityLabel?: string;
   style?: StyleProp<ViewStyle>;
@@ -153,9 +155,9 @@ export interface AccordionContentProps {
 }
 
 /** The collapsible body, revealed in place under the header. Plain by
- * design — content indents to align under the title, no tinted well; the
- * chevron + position already say "inside". Compose rows/dividers/actions
- * directly. */
+ * design — flush with the header's left edge (aligns with the title), no
+ * tinted well; the chevron + position already say "inside". Compose
+ * rows/dividers/actions directly. */
 export function AccordionContent(props: AccordionContentProps) {
   const { expanded } = useAccordionContext();
   if (!expanded) return null;
@@ -185,9 +187,9 @@ const styles = StyleSheet.create({
   titleText: {
     flex: 1,
   },
-  // Aligns under the title text (16px icon + 12px gap = 28).
+  // Flush with the header's left edge — aligns with the title, like a Section
+  // body. The chevron + position already say "inside"; no indent needed.
   content: {
-    paddingLeft: 28,
     paddingBottom: 10,
   },
 });

package/src/combobox.tsx

@@ -182,7 +182,13 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
   const single = value ?? null;
   const reflectedText = single ? (single.label ?? single.value) : "";
 
-  const [query, setQuery] = useState(reflectSelection && single ? reflectedText : "");
+  // The live edit buffer. `null` = the user isn't editing: the input reflects the
+  // committed selection's label and the list browses the FULL set. A string (incl.
+  // "") = the user is searching: the input shows it and the list filters by it.
+  // This one nullable carries the bit that (value, inputText) alone can't — after
+  // selecting FPP, the input reads "FPP" whether the user just reopened (browse)
+  // or retyped it (filter); `draft` is null in the first case, "FPP" in the second.
+  const [draft, setDraft] = useState<string | null>(null);
   const [open, setOpen] = useState(autoFocus);
   const triggerRef = useRef<View>(null);
   const inputRef = useRef<RNTextInput>(null);
@@ -197,9 +203,11 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
   const isServer = onSearchChange !== undefined;
   const debouncedSearch = useDebouncedCallback(onSearchChange ?? (() => {}), searchDebounceMs);
 
-  // The displayed text equals the reflected selection until the user types — show
-  // ALL options then (browse), not the list filtered to the selected label.
-  const filterQuery = reflectSelection && single && query === reflectedText ? "" : query;
+  // What the input shows: the live draft while editing, else the reflected label.
+  const inputText = draft ?? (reflectSelection && single ? reflectedText : "");
+  // What the list filters by: nothing while reflecting a selection (browse), the
+  // draft while editing — so retyping the selected label still filters to it.
+  const filterQuery = draft ?? "";
 
   const findOption = useCallback(
     (val: T): PickerOption<T, D> =>
@@ -215,7 +223,9 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
         debouncedSearch.cancel();
         onSearchChange?.("");
       }
-      setQuery(reflectSelection ? (opt.label ?? opt.value) : "");
+      // Stop editing — the input reflects the new label (or clears, when
+      // reflectSelection is off) and the next open browses the full set.
+      setDraft(null);
       setOpen(false);
       // The refocus below must not reopen the just-closed menu.
       suppressFocusOpenRef.current = true;
@@ -247,7 +257,7 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
 
   const handleChangeText = useCallback(
     (text: string) => {
-      setQuery(text);
+      setDraft(text);
       if (!disabled) setOpen(true);
       if (isServer) debouncedSearch(text);
     },
@@ -285,7 +295,7 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
     // Boundary cast: the engine is generic per-instance, the context type is not.
     // `ComboboxContent` casts back to its own `<T, D>` before touching rows.
     list: list as unknown as UseOptionList<string, unknown>,
-    query,
+    query: inputText,
     open,
     showList,
     loading,
@@ -349,9 +359,14 @@ export interface ComboboxInputProps {
 export function ComboboxInput(props: ComboboxInputProps) {
   const { icon, placeholder, clearable = false, onClear, clearLabel, accessibilityLabel, testID } = props;
   const ctx = useComboboxContext("ComboboxInput");
-  // Select mode (no leading icon): a trailing chevron so the field reads as a
-  // picker, not a free-text search. The clear ✕ owns the right slot when present.
-  const showChevron = !icon && !clearable;
+  // Select mode (no leading icon): the right slot holds the clear ✕ when the field
+  // carries text (a reflected selection or a live query) AND it's clearable;
+  // otherwise the trailing chevron, so an EMPTY picker still reads as a picker.
+  // The two never show together — ✕ replaces the chevron once there's something to
+  // clear, and pressing it resets the query + reopens the browse list (via
+  // `handleChangeText("")`) so the consumer's `onClear` lands back on the full set.
+  const showClear = clearable && ctx.query.length > 0;
+  const showChevron = !icon && !showClear;
 
   return (
     <View ref={ctx.triggerRef}>
@@ -375,7 +390,9 @@ export function ComboboxInput(props: ComboboxInputProps) {
         autoCorrect={false}
         accessibilityLabel={accessibilityLabel}
         style={[
-          showChevron ? styles.selectInput : undefined,
+          // Select mode reserves the right gutter for whichever trailing affordance
+          // is up (chevron when empty, ✕ when there's text) so neither overlaps it.
+          !icon ? styles.selectInput : undefined,
           // Gate on `showList`, not `open`: an empty query with no options has
           // `open=true` but renders NO dropdown, so a ring tied to `open` would
           // show with nothing below it AND linger after blur (no popover fires a

package/src/file_gallery_modal.tsx

@@ -20,6 +20,9 @@ import { isImageMimeType } from "./mime";
 import { useImageRotation, type ImageRotation } from "./use_image_rotation";
 import { resolveGalleryLabels, type GalleryLabels } from "./file_preview_types";
 import { downloadFileFromUrl } from "./download";
+import { ActionMenu, type ActionMenuItem } from "./action_menu";
+import { useScreenSize } from "./use_screen_size";
+import { PortalHost } from "./portal";
 
 export interface FileGalleryModalProps {
   files: DisplayFile[];
@@ -107,6 +110,10 @@ export function FileGalleryModal(props: FileGalleryModalProps) {
   // Own the rotation when the host doesn't share one (standalone consumers).
   const internalRotation = useImageRotation();
   const rot = rotation ?? internalRotation;
+  // Rotate controls float over the image on every screen. On phones the toolbar
+  // additionally can't hold filename + every action inline (the close button gets
+  // pushed off-screen), so the remaining actions collapse into a ⋯ menu.
+  const { small } = useScreenSize();
 
   const close = useCallback(() => onIndexChange(null), [onIndexChange]);
   const next = useCallback(() => {
@@ -189,111 +196,139 @@ export function FileGalleryModal(props: FileGalleryModalProps) {
     ]);
   };
 
+  // Same actions the desktop toolbar shows inline, collapsed into the ⋯ menu on
+  // phones. Download is always present; open-external / remove follow their props.
+  const actionItems: ActionMenuItem[] = [
+    { key: "download", label: l.download, icon: "download", onPress: handleDownload },
+    ...(onOpenExternal
+      ? [{ key: "open", label: l.openExternal, icon: "external-link", onPress: handleOpenExternal } as const]
+      : []),
+    ...(onRemove
+      ? [{ key: "remove", label: l.remove, icon: "trash", danger: true, onPress: handleRemove } as const]
+      : []),
+  ];
+
   return (
     <Modal visible transparent onRequestClose={close} animationType="fade">
-      <View style={styles.surface}>
-        <View style={styles.toolbar}>
-          <Text size="sm" weight="medium" numberOfLines={1} style={styles.filename}>
-            {file.filename}
-          </Text>
-          {total > 1 ? (
-            <Text size="xs" color="muted" style={styles.counter}>
-              {`${activeIndex + 1} / ${total}`}
+      {/* PortalHost so the ⋯ menu's popover portals INSIDE the modal's stacking
+          context (on top) instead of to the app-root host behind the overlay —
+          the dead-menu bug that drove #1850's inline buttons. */}
+      <PortalHost>
+        <View style={styles.surface}>
+          <View style={styles.toolbar}>
+            <Text size="sm" weight="medium" numberOfLines={1} style={styles.filename}>
+              {file.filename}
             </Text>
-          ) : null}
-          <View style={styles.spacer} />
-
-          {isImage && rotatable ? (
-            <>
-              <IconButton
-                size="lg"
-                icon="rotate-ccw"
-                tooltip={l.rotateLeft}
-                color="secondary"
-                onPress={() => rot.rotate(file.id, -1)}
-              />
-              <IconButton
-                size="lg"
-                icon="rotate-cw"
-                tooltip={l.rotateRight}
-                color="secondary"
-                onPress={() => rot.rotate(file.id, 1)}
-              />
-              {onPersistRotation && rotated ? (
-                <IconButton
-                  size="lg"
-                  icon="check"
-                  tooltip={l.saveRotation}
-                  color="primary"
-                  disabled={persisting}
-                  onPress={() => {
-                    if (!persisting) onPersistRotation(file, rot.rotationFor(file.id));
-                  }}
+            {total > 1 ? (
+              <Text size="xs" color="muted" style={styles.counter}>
+                {`${activeIndex + 1} / ${total}`}
+              </Text>
+            ) : null}
+            <View style={styles.spacer} />
+  
+            {small ? (
+              // Phone: actions collapse to a ⋯ menu.
+              <ActionMenu items={actionItems} accessibilityLabel={l.actions} />
+            ) : (
+              // Wider screens: every action inline (download · open · remove).
+              // Rotate lives on the image overlay, not the toolbar.
+              <>
+                <Button
+                  icon="download"
+                  title={l.download}
+                  color="secondary"
+                  onPress={handleDownload}
                 />
-              ) : null}
-            </>
-          ) : null}
-
-          <Button
-            icon="download"
-            title={l.download}
-            color="secondary"
-            onPress={handleDownload}
-          />
-          {onOpenExternal ? (
-            <Button
-              icon="external-link"
-              title={l.openExternal}
-              color="secondary"
-              onPress={handleOpenExternal}
-            />
-          ) : null}
-          {onRemove ? (
-            <Button
-              icon="trash"
-              title={l.remove}
-              color="danger-secondary"
-              onPress={handleRemove}
-            />
-          ) : null}
-
-          <IconButton size="lg" icon="x" tooltip={l.close} color="secondary" onPress={close} />
-        </View>
-
-        <View style={styles.previewArea}>
-          {renderPreview ? (
-            renderPreview(file, { rotation: rot.rotationFor(file.id) })
-          ) : (
-            <FilePreview
-              file={file}
-              labels={labels}
-              onError={onError}
-              rotation={rot.rotationFor(file.id)}
-              credentials={credentials}
-            />
-          )}
-
-          {activeIndex > 0 ? (
-            <FocusRingPressable accessibilityRole="button"
-              onPress={prev}
-              accessibilityLabel={l.previous}
-              style={[styles.nav, styles.navLeft]}
-            >
-              <Icon name="chevron-left" size={28} color={colors.white} />
-            </FocusRingPressable>
-          ) : null}
-
-          {activeIndex < total - 1 ? (
-            <FocusRingPressable accessibilityRole="button"
-              onPress={next}
-              accessibilityLabel={l.next}
-              style={[styles.nav, styles.navRight]}
-            >
-              <Icon name="chevron-right" size={28} color={colors.white} />
-            </FocusRingPressable>
-          ) : null}
+                {onOpenExternal ? (
+                  <Button
+                    icon="external-link"
+                    title={l.openExternal}
+                    color="secondary"
+                    onPress={handleOpenExternal}
+                  />
+                ) : null}
+                {onRemove ? (
+                  <Button
+                    icon="trash"
+                    title={l.remove}
+                    color="danger-secondary"
+                    onPress={handleRemove}
+                  />
+                ) : null}
+              </>
+            )}
+  
+            <IconButton size="lg" icon="x" tooltip={l.close} color="secondary" onPress={close} />
+          </View>
+  
+          <View style={styles.previewArea}>
+            {renderPreview ? (
+              renderPreview(file, { rotation: rot.rotationFor(file.id) })
+            ) : (
+              <FilePreview
+                file={file}
+                labels={labels}
+                onError={onError}
+                rotation={rot.rotationFor(file.id)}
+                credentials={credentials}
+              />
+            )}
+  
+            {activeIndex > 0 ? (
+              <FocusRingPressable accessibilityRole="button"
+                onPress={prev}
+                accessibilityLabel={l.previous}
+                style={[styles.nav, styles.navLeft]}
+              >
+                <Icon name="chevron-left" size={28} color={colors.white} />
+              </FocusRingPressable>
+            ) : null}
+  
+            {activeIndex < total - 1 ? (
+              <FocusRingPressable accessibilityRole="button"
+                onPress={next}
+                accessibilityLabel={l.next}
+                style={[styles.nav, styles.navRight]}
+              >
+                <Icon name="chevron-right" size={28} color={colors.white} />
+              </FocusRingPressable>
+            ) : null}
+  
+            {isImage && rotatable ? (
+              <View style={styles.rotateOverlay} pointerEvents="box-none">
+                <View style={styles.rotateCluster}>
+                  <IconButton
+                    size="lg"
+                    icon="rotate-ccw"
+                    tooltip={l.rotateLeft}
+                    color="white"
+                    onPress={() => rot.rotate(file.id, -1)}
+                  />
+                  <IconButton
+                    size="lg"
+                    icon="rotate-cw"
+                    tooltip={l.rotateRight}
+                    color="white"
+                    onPress={() => rot.rotate(file.id, 1)}
+                  />
+                  {onPersistRotation && rotated ? (
+                    <IconButton
+                      size="lg"
+                      icon="check"
+                      tooltip={l.saveRotation}
+                      color="white"
+                      disabled={persisting}
+                      onPress={() => {
+                        if (!persisting) onPersistRotation(file, rot.rotationFor(file.id));
+                      }}
+                    />
+                  ) : null}
+                </View>
+              </View>
+            ) : null}
+          </View>
         </View>
-      </View>
+      </PortalHost>
     </Modal>
   );
 }
@@ -343,4 +378,21 @@ const styles = StyleSheet.create({
   navRight: {
     right: 16,
   },
+  rotateOverlay: {
+    position: "absolute",
+    bottom: 24,
+    left: 0,
+    right: 0,
+    flexDirection: "row",
+    justifyContent: "center",
+  },
+  rotateCluster: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 4,
+    paddingHorizontal: 8,
+    paddingVertical: 6,
+    borderRadius: 28,
+    backgroundColor: "rgba(0, 0, 0, 0.55)",
+  },
 });

package/src/file_preview.web.tsx

@@ -1,3 +1,5 @@
+// eslint-disable-next-line typescript/triple-slash-reference -- the ambient pdfjs_worker.d.ts must be referenced so its `declare module` reaches a consuming app's tsc; an ESM import can't pull in an ambient declaration, and inlining it errors (TS2665 — can't augment an untyped resolved module)
+/// <reference path="./pdfjs_worker.d.ts" />
 import { useEffect, useRef, useState } from "react";
 import { View, StyleSheet } from "react-native";
 import { Text } from "./text";

package/src/files_editor.tsx

@@ -1,5 +1,5 @@
 import { useState } from "react";
-import { View, StyleSheet } from "react-native";
+import { View, ScrollView, StyleSheet } from "react-native";
 import { Button } from "./button";
 import { Popover, PopoverTrigger, PopoverContent } from "./popover";
 import { MenuButton } from "./menu_button";
@@ -80,6 +80,10 @@ export interface FilesEditorProps {
   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 —
+   *  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. */
   labels?: Partial<FilesEditorLabels>;
   /** Credentials mode for the built-in gallery's preview fetches — `"include"`
@@ -118,6 +122,7 @@ export function FilesEditor(props: FilesEditorProps) {
     itemSize,
     minItemWidth,
     columns,
+    gridMaxHeight,
     labels,
     credentials,
     galleryLabels,
@@ -148,22 +153,32 @@ export function FilesEditor(props: FilesEditorProps) {
     void pickFiles({ multiple: true, accept }).then((picked) => { if (picked.length > 0) onAdd(picked); });
   };
 
+  const grid = (
+    <FileGrid
+      files={files}
+      uploads={uploads}
+      itemSize={itemSize}
+      minItemWidth={minItemWidth}
+      columns={columns}
+      selectedIds={selectMode ? selected : 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 — the default view stays a clean
+      // preview surface so a stray tap can't drop a file.
+      onDisplayRemove={!readOnly && selectMode && onRemove ? (id) => confirmRemove(() => onRemove(id)) : undefined}
+      onUploadRemove={onUploadRemove}
+      onRetry={onRetry}
+      onRetryAll={onRetryAll}
+    />
+  );
+
   return (
     <View style={styles.root}>
-      <FileGrid
-        files={files}
-        uploads={uploads}
-        itemSize={itemSize}
-        minItemWidth={minItemWidth}
-        columns={columns}
-        selectedIds={selectMode ? selected : undefined}
-        onToggleSelect={selectMode ? toggle : undefined}
-        onFilePress={selectMode ? undefined : (f) => setGalleryIndex(files.findIndex((x) => x.id === f.id))}
-        onDisplayRemove={!readOnly && !selectMode && onRemove ? (id) => confirmRemove(() => onRemove(id)) : undefined}
-        onUploadRemove={onUploadRemove}
-        onRetry={onRetry}
-        onRetryAll={onRetryAll}
-      />
+      {gridMaxHeight !== undefined ? (
+        <ScrollView style={{ maxHeight: gridMaxHeight }}>{grid}</ScrollView>
+      ) : (
+        grid
+      )}
 
       {readOnly ? (
         hasFiles ? (
@@ -216,7 +231,6 @@ export function FilesEditor(props: FilesEditorProps) {
         onIndexChange={setGalleryIndex}
         onRemove={!readOnly && onRemove ? onRemove : undefined}
         onDownload={onDownload}
-        onOpenExternal={(f) => { if (typeof window !== "undefined") window.open(f.url, "_blank"); }}
         credentials={credentials}
         labels={galleryLabels}
       />

package/src/section_heading.tsx

@@ -1,6 +1,7 @@
 import { View, type StyleProp, type ViewStyle } from "react-native";
 import { Text, type HeadingLevel } from "./text";
 import { Icon, type IconName } from "./icon";
+import { InfoPopover } from "./info_popover";
 
 // The card-less section header — the bare-canvas sibling of `CardHeader`, built
 // the same compound way. A title (+ optional leading icon / description) on one
@@ -13,6 +14,31 @@ import { Icon, type IconName } from "./icon";
 //     <Button title="Add line" … />            {/* pushed right by the grow */}
 //   </SectionHeading>
 
+export interface SectionProps {
+  children: React.ReactNode;
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * The card-less twin of `Card`: a bare, gap-spaced region with no surface
+ * chrome. Compose a `SectionHeading` then the body content — the gap spaces the
+ * heading from the body (and body rows from each other), so there is no
+ * `SectionBody` (a card-less body has no padding to own). Reach for `Card` when
+ * the group needs a contained surface; reach for `Section` on the bare canvas.
+ *
+ *   <Section>
+ *     <SectionHeading>
+ *       <SectionHeadingTitle>Containers</SectionHeadingTitle>
+ *       <SectionHeadingMeta>3 cont</SectionHeadingMeta>
+ *       <Button … />
+ *     </SectionHeading>
+ *     {body}
+ *   </Section>
+ */
+export function Section(props: SectionProps) {
+  return <View style={[{ gap: 10 }, props.style]}>{props.children}</View>;
+}
+
 export interface SectionHeadingProps {
   children: React.ReactNode;
   style?: StyleProp<ViewStyle>;
@@ -32,18 +58,26 @@ export interface SectionHeadingTitleProps {
   icon?: IconName;
   /** Heading rank. Defaults to 2 — typical for page-level section titles. */
   level?: HeadingLevel;
+  /** Title weight. Defaults to `medium`; `semibold` (matching `CardHeaderTitle`)
+   * for denser surfaces — a side panel, a stacked group list — where `medium`
+   * blends into the body rows. */
+  weight?: "medium" | "semibold";
+  /** An ⓘ popover after the title — a short "what this is / where it came from"
+   * gloss, mirroring `CardHeaderTitle`'s `info`. */
+  info?: string;
 }
 
 /** The title block — grows to push any sibling actions to the right edge. */
 export function SectionHeadingTitle(props: SectionHeadingTitleProps) {
-  const { children, description, icon, level = 2 } = props;
+  const { children, description, icon, level = 2, weight = "medium", info } = props;
   return (
     <View style={{ flex: 1, gap: 2 }}>
       <View style={{ flexDirection: "row", alignItems: "center", gap: 6 }}>
         {icon ? <Icon name={icon} size={18} /> : null}
-        <Text level={level} weight="medium" size="md">
+        <Text level={level} weight={weight} size="md">
           {children}
         </Text>
+        {info ? <InfoPopover text={info} accessibilityLabel="Giải thích dữ liệu" /> : null}
       </View>
       {description ? (
         <Text color="zinc-500" size="sm">
@@ -53,3 +87,18 @@ export function SectionHeadingTitle(props: SectionHeadingTitleProps) {
     </View>
   );
 }
+
+export interface SectionHeadingMetaProps {
+  children: React.ReactNode;
+}
+
+/** Right-side context for `SectionHeading` — a count ("3 cont"), unit, or
+ * period. xs muted, tabular for numerals. The card-less twin of `CardHeaderMeta`;
+ * the title's `flex: 1` pushes it (and any actions) to the right edge. */
+export function SectionHeadingMeta(props: SectionHeadingMetaProps) {
+  return (
+    <Text size="xs" color="muted" tabular>
+      {props.children}
+    </Text>
+  );
+}

package/src/tabs.tsx

@@ -2,13 +2,16 @@ import { useCallback, useRef } from "react";
 import { View } from "react-native";
 import { PressableHighlight } from "./pressable_highlight";
 import { Text } from "./text";
-import { colors } from "./colors";
+import { colors, solid, type ColorName } from "./colors";
 import { CONTROL_RADIUS } from "./control_surface";
 
 export interface TabOption<T extends string> {
   label: string;
   value: T;
   testID?: string;
+  /** A small status dot before the label — set only when the tab's area needs
+   *  attention (a blocker / missing item). Omit for the resting state. */
+  status?: ColorName;
 }
 
 interface TabsProps<T extends string> {
@@ -99,13 +102,18 @@ function TabButton<T extends string>(props: TabButtonProps<T>) {
   }, [option.value, option.label, option.testID, onSelectTab]);
 
   const inner = (
-    <Text
-      weight={selected ? "medium" : "regular"}
-      color={selected ? "zinc-900" : "zinc-700"}
-      userSelect="none"
-    >
-      {option.label}
-    </Text>
+    <View style={{ flexDirection: "row", alignItems: "center", gap: 6 }}>
+      {option.status ? (
+        <View style={{ width: 6, height: 6, borderRadius: 999, backgroundColor: solid(option.status) }} />
+      ) : null}
+      <Text
+        weight={selected ? "medium" : "regular"}
+        color={selected ? "zinc-900" : "zinc-700"}
+        userSelect="none"
+      >
+        {option.label}
+      </Text>
+    </View>
   );
 
   return (