@lotics/ui 7.5.0 → 7.7.0

package/AGENTS.md

@@ -108,16 +108,19 @@ 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`
   (bulk-select bar).
 - **Filters & view controls** — `SearchInput`, `ChipGroup`, `FilterChip` (+ `RangeSlider`,
   `Counter`), `Chip`.
-- **Overlays** — `Dialog`, `Drawer` (+ `DrawerFooter`), `Popover`, `Tooltip`, `OptionList`
-  (the searchable list body — host it in a `Popover`/`Dialog` for a command palette),
-  `Alert` (the blocking confirm).
+- **Overlays** — `Dialog` (centered card over a scrim), `Modal` (+ `ModalHeader`/`ModalBody`/
+  `ModalFooter` — a full-bleed, edge-to-edge takeover with NO scrim), `Drawer` (+ `DrawerFooter`),
+  `Popover`, `Tooltip`, `OptionList` (the searchable list body — host it in a `Popover`/`Dialog` for
+  a command palette), `Alert` (the blocking confirm).
 - **Status / feedback** — `Badge` / `StatusBadge`, `Callout` (inline status), `EmptyState`,
   `CompletionState`, `ActivityIndicator` / `Loading`, `Skeleton`.
 - **Files** — `FilesEditor` (THE all-in-one attachment field: an upload-aware grid + a toolbar below
@@ -285,8 +288,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"
@@ -298,8 +305,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
@@ -618,7 +630,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
@@ -679,7 +695,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.
@@ -788,11 +804,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 ·
@@ -804,13 +820,13 @@ check_circle (CheckCircle — the completion ring: an empty ring that springs to
 floating_action_bar · filter_chip · column_filter (ColumnFilter — the typed per-column filter pill +
 columnFilterToConditions; for a register filtering on several columns) · chip_group · search_input ·
 sort_header · table · data_grid (DataGrid — the inline-managed grouped table: a grouped, sortable grid of LIVE inline-editor cells (`columns[].cell` → ANY field) + optional per-row `leading` (a CheckCircle) + `renderGroupFooter` (per-group add, align with the exported `gridRowStyle`) + `labels` (localize the sort-header a11y via `SortHeaderLabels`). Owns header/sections/rows; consumer owns data + sort/group/filter/collapse state + toolbar. Renders ALL rows — MODERATE data; 10k+ → the paginated `Table` register. Examples: `tpl_task_board`, `tpl_pipeline`) · pagination · accordion · stepper (Stepper + Step — done/current/upcoming/warning/complete progress on a track (horizontal) or spine (vertical); compound `<Step status>children` OR data `steps[]`+`current`; **navigable** via `Step.onPress` (both orientations — the whole step is the tap target) + `active` to wash the selected one, so it doubles as a section/phase switcher; the guided-run / agent-feed primitive — subsumes the old StepList) ·
-step_progress · timeline (heterogeneous event LOG — per-row icon + expandable details, models the past; NOT progress) · drawer (+ DrawerFooter) · dialog · popover · tooltip ·
+step_progress · timeline (heterogeneous event LOG — per-row icon + expandable details, models the past; NOT progress) · drawer (+ DrawerFooter) · dialog · modal (Modal + ModalHeader + ModalBody + ModalFooter — the full-bleed, edge-to-edge takeover: an OPAQUE surface that COVERS THE WHOLE SCREEN, so unlike Dialog (centered card WITH scrim) and Drawer (docked panel WITH scrim) there is nothing behind it to dim — NO scrim, NO backdrop. Lays children as a flex column: a pinned ModalHeader (eyebrow/title + an actions slot + close), a flex:1 scrolling ModalBody, a pinned ModalFooter (the commit bar, same chrome as DialogFooter/DrawerFooter). Reach for it for a focused capture / multi-step wizard / a console the user steps INTO, where surrounding chrome is a distraction; pick Dialog when the surface is a card the user can see context around) · popover · tooltip ·
 alert · peek · empty_state · completion_state · callout (Callout · CalloutTitle ·
 CalloutText · CalloutActions) · kpi_card · kpi_strip · metric · trend_chip · sparkline ·
 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.5.0",
+  "version": "7.7.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
@@ -193,6 +193,7 @@
     "./date_calendar": "./src/date_calendar.tsx",
     "./dialog": "./src/dialog.tsx",
     "./drawer": "./src/drawer.tsx",
+    "./modal": "./src/modal.tsx",
     "./screen_router": "./src/screen_router.tsx",
     "./route_matching": "./src/route_matching.ts",
     "./menu_title": "./src/menu_title.tsx",

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/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/modal.tsx

@@ -0,0 +1,163 @@
+import { ReactNode } from "react";
+import { Modal as RNModal, StyleSheet, View, ScrollView, ViewStyle } from "react-native";
+import { colors } from "@lotics/ui/colors";
+import { IconButton } from "@lotics/ui/icon_button";
+import { Text } from "@lotics/ui/text";
+import { PortalHost } from "@lotics/ui/portal";
+import { useOverlayScope } from "@lotics/ui/overlay_scope";
+
+export interface ModalProps {
+  open: boolean;
+  onClose: () => void;
+  /**
+   * The modal body. Lay it out as a flex column — a fixed `ModalHeader` and
+   * `ModalFooter` pin while a `ModalBody` scrolls between them.
+   */
+  children: ReactNode;
+  testID?: string;
+}
+
+/**
+ * A full-bleed, edge-to-edge takeover: an OPAQUE surface that covers the entire
+ * screen. Unlike `Dialog` (a centered card over a scrim) or `Drawer` (a docked
+ * panel over a scrim), a `Modal` has nothing behind it to dim — it owns the whole
+ * viewport. Reach for it for a focused capture, a multi-step wizard, or a console
+ * the user steps INTO and out of, where the surrounding chrome is a distraction.
+ *
+ * Lays children as a flex column so a fixed `ModalHeader` + `ModalFooter` pin
+ * while a `ModalBody` scrolls between them. Controlled via `open`/`onClose`; the
+ * header close control dismisses it (Escape on web, the back gesture on Android).
+ */
+export function Modal(props: ModalProps) {
+  const { open, onClose, children, testID } = props;
+  useOverlayScope(open);
+
+  return (
+    <RNModal visible={open} onRequestClose={onClose} animationType="fade">
+      <View testID={testID} style={styles.surface}>
+        <PortalHost>{children}</PortalHost>
+      </View>
+    </RNModal>
+  );
+}
+
+export interface ModalHeaderProps {
+  /** Header title. A string renders as the standard title; a node renders as-is. */
+  title?: ReactNode;
+  /** A short caption above the title (a context label / category). */
+  eyebrow?: ReactNode;
+  /** Right-aligned controls placed before the close button (e.g. a save action). */
+  actions?: ReactNode;
+  onClose: () => void;
+  style?: ViewStyle;
+}
+
+/**
+ * The fixed top bar of a `Modal`: an optional eyebrow + title on the left, an
+ * optional `actions` slot, and a close control wired to `onClose` on the right.
+ * Render it as the FIRST child of the `Modal`; it never scrolls.
+ */
+export function ModalHeader(props: ModalHeaderProps) {
+  const { title, eyebrow, actions, onClose, style } = props;
+
+  return (
+    <View style={[styles.header, style]}>
+      <View style={styles.headerText}>
+        {eyebrow !== undefined ? (
+          typeof eyebrow === "string" ? (
+            <Text size="xs" weight="medium" color="muted">
+              {eyebrow}
+            </Text>
+          ) : (
+            eyebrow
+          )
+        ) : null}
+        {title !== undefined ? (
+          typeof title === "string" ? (
+            <Text size="lg" weight="semibold">
+              {title}
+            </Text>
+          ) : (
+            title
+          )
+        ) : null}
+      </View>
+      {actions !== undefined ? <View style={styles.headerActions}>{actions}</View> : null}
+      <IconButton icon="x" size="lg" accessibilityLabel="Close" onPress={onClose} />
+    </View>
+  );
+}
+
+export interface ModalBodyProps {
+  children: ReactNode;
+}
+
+/**
+ * The flex:1 scrolling content region between a `Modal`'s pinned header and
+ * footer. Fills the remaining height; its content scrolls.
+ */
+export function ModalBody(props: ModalBodyProps) {
+  const { children } = props;
+  return <ScrollView contentContainerStyle={styles.bodyContent}>{children}</ScrollView>;
+}
+
+export interface ModalFooterProps {
+  /** The action(s) — typically right-aligned `Button`s. Prepend a
+   *  `<Text style={{ flex: 1 }}>` hint to push them right with a summary on the left. */
+  children: ReactNode;
+  align?: "start" | "end" | "space-between";
+}
+
+/**
+ * The pinned bottom action bar of a `Modal` — a hairline-topped band (the same
+ * chrome as `DialogFooter` / `DrawerFooter`) that commits the modal's work.
+ * Render it as the LAST child of the `Modal`, after the `ModalBody`; the body's
+ * `flex:1` pins it to the surface bottom.
+ */
+export function ModalFooter(props: ModalFooterProps) {
+  const { children, align = "end" } = props;
+  const justifyContent =
+    align === "end" ? "flex-end" : align === "space-between" ? "space-between" : "flex-start";
+
+  return <View style={[styles.footer, { justifyContent }]}>{children}</View>;
+}
+
+const styles = StyleSheet.create({
+  surface: {
+    flex: 1,
+    backgroundColor: colors.white,
+    flexDirection: "column",
+  },
+  header: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 12,
+    paddingLeft: 24,
+    paddingRight: 16,
+    paddingVertical: 16,
+    minHeight: 64,
+    borderBottomWidth: 1,
+    borderBottomColor: colors.border,
+  },
+  headerText: {
+    flex: 1,
+    gap: 2,
+  },
+  headerActions: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 8,
+  },
+  bodyContent: {
+    padding: 24,
+  },
+  footer: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 12,
+    paddingHorizontal: 24,
+    paddingVertical: 16,
+    borderTopWidth: 1,
+    borderTopColor: colors.border,
+  },
+});

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 (