@lotics/ui 5.8.0 → 5.10.0

package/src/file_gallery_modal.tsx

@@ -1,39 +1,53 @@
-// FileGalleryModal — fullscreen file preview with prev/next nav + ESC close.
-// Pure primitive: takes DisplayFile[] only, no Lotics domain coupling. Renders
-// every previewable type (image/PDF/video/audio/Word/Excel/CSV) via FilePreview,
-// whose document engines (@lotics/docx, @lotics/xlsx) are optional peer deps
-// loaded lazily — so a consumer that only shows images pays nothing extra.
+// FileGalleryModal — full-screen file preview with a toolbar (filename · counter
+// · actions · close), prev/next nav, and ESC close. Pure primitive: takes
+// DisplayFile[] only, no Lotics domain coupling. Renders every previewable type
+// (image/PDF/video/audio/Word/Excel/CSV) via FilePreview, whose document engines
+// (pdfjs-dist, @lotics/docx, @lotics/xlsx) are optional peer deps loaded lazily —
+// so a consumer that only shows images pays nothing extra.
 
-import { useCallback, useEffect, useRef } from "react";
-import {
-  Modal,
-  Pressable,
-  StyleSheet,
-  View,
-} from "react-native";
+import { useCallback, useEffect, type ReactNode } from "react";
+import { Linking, Modal, Platform, StyleSheet, View } from "react-native";
 import { Text } from "./text";
 import { Icon } from "./icon";
+import { IconButton } from "./icon_button";
+import { Button } from "./button";
+import { FocusRingPressable } from "./focus_ring_pressable";
+import { Alert } from "./alert";
 import { colors } from "./colors";
 import type { DisplayFile } from "./file_thumbnail";
 import { FilePreview } from "./file_preview";
 import { isImageMimeType } from "./mime";
 import { useImageRotation, type ImageRotation } from "./use_image_rotation";
-import type { PreviewLabels } from "./file_preview_types";
+import { resolveGalleryLabels, type GalleryLabels } from "./file_preview_types";
+import { downloadFileFromUrl } from "./download";
 
 export interface FileGalleryModalProps {
   files: DisplayFile[];
   /** Index of the file currently shown. When null, the modal is closed. */
   activeIndex: number | null;
   onIndexChange: (next: number | null) => void;
-  /**
-   * Optional caption suffix shown under the file. Useful for hint text like
-   * "ESC để đóng · ←/→ để chuyển". When omitted, just shows filename + count.
-   */
-  captionHint?: string;
-  /** Translated preview strings; English fallback when omitted. */
-  labels?: Partial<PreviewLabels>;
+  /** Translated chrome + preview strings; English fallback when omitted. */
+  labels?: Partial<GalleryLabels>;
   /** Reported when a file fails to render (host wires to its logger). */
   onError?: (error: unknown, meta: { fileId: string; mimeType: string }) => void;
+  /**
+   * Override the toolbar's Download action. Omit ⇒ a built-in default (web:
+   * fetch+save the presigned URL; native: open it externally) — correct for a
+   * custom-code app's same-origin presigned R2 URLs. The host frontend passes
+   * its own, which sends `credentials: "include"` for auth-gated proxy URLs.
+   */
+  onDownload?: (file: DisplayFile) => void;
+  /**
+   * Open the active file outside the modal (a new browser tab on the frontend, the
+   * SDK's `openExternal` inside a custom-code app — the sandbox can't pop tabs).
+   * When omitted, the action is hidden.
+   */
+  onOpenExternal?: (file: DisplayFile) => void;
+  /**
+   * Remove the active file. When provided, a Remove action (with a confirm) shows
+   * in the actions menu; the host drops the file from its own state.
+   */
+  onRemove?: (fileId: string) => void;
   /**
    * Optional shared rotation state (from `useImageRotation`) — pass it to keep an
    * inline gallery and this modal in sync. Omitted ⇒ the modal keeps its own
@@ -42,6 +56,21 @@ export interface FileGalleryModalProps {
   rotation?: ImageRotation;
   /** Show 90° rotate controls for image files. Default true. */
   rotatable?: boolean;
+  /**
+   * Override how the active file's CONTENT is rendered (the toolbar/nav chrome is
+   * unchanged). Omit ⇒ the built-in `FilePreview`. The host frontend passes this
+   * to route Excel to its live editable workbook while delegating every other
+   * type to `FilePreview`; custom-code apps never set it. `rotation` (degrees) is
+   * forwarded so the override can honor the rotate controls for images.
+   */
+  renderPreview?: (file: DisplayFile, opts: { rotation: number }) => ReactNode;
+  /**
+   * Credentials mode for the built-in `FilePreview`'s byte fetches. The host
+   * frontend passes `"include"` so the session cookie rides the cross-origin
+   * fetch to its auth-gated proxy; custom-code apps omit it (presigned URLs).
+   * Ignored when `renderPreview` is set (the override owns its own fetching).
+   */
+  credentials?: RequestCredentials;
   /**
    * Persist the active image's current view-rotation as a new stored file. When
    * provided and the active image is rotated, a confirm (✓) control appears next
@@ -54,13 +83,27 @@ export interface FileGalleryModalProps {
 }
 
 /**
- * Fullscreen file preview gallery. Renders any previewable MIME type inline
- * via FilePreview; unknown types show a download placeholder.
+ * Full-screen file preview gallery. Renders any previewable MIME type inline via
+ * FilePreview; unknown types show a download placeholder.
  */
 export function FileGalleryModal(props: FileGalleryModalProps) {
-  const { files, activeIndex, onIndexChange, captionHint, labels, onError, rotation, rotatable = true, onPersistRotation, persisting } = props;
+  const {
+    files,
+    activeIndex,
+    onIndexChange,
+    labels,
+    onError,
+    onDownload,
+    onOpenExternal,
+    onRemove,
+    rotation,
+    rotatable = true,
+    renderPreview,
+    credentials,
+    onPersistRotation,
+    persisting,
+  } = props;
   const visible = activeIndex !== null;
-  const overlayRef = useRef<View | null>(null);
   // Own the rotation when the host doesn't share one (standalone consumers).
   const internalRotation = useImageRotation();
   const rot = rotation ?? internalRotation;
@@ -103,84 +146,152 @@ export function FileGalleryModal(props: FileGalleryModalProps) {
   const file = files[activeIndex];
   if (!file) return null;
 
+  const l = resolveGalleryLabels(labels);
   const isImage = isImageMimeType(file.mimeType);
   const total = files.length;
-  const caption = captionHint
-    ? `${file.filename} · ${activeIndex + 1} / ${total} · ${captionHint}`
-    : `${file.filename} · ${activeIndex + 1} / ${total}`;
+  const rotated = rot.rotationFor(file.id) !== 0;
+
+  const handleDownload = () => {
+    if (onDownload) {
+      onDownload(file);
+      return;
+    }
+    // Default: the web fetch+save path. `credentials` rides the host's auth-gated
+    // proxy URLs (presigned app URLs are same-origin and omit it). On native the
+    // web primitive can't run, so open the URL externally.
+    if (Platform.OS === "web") {
+      void downloadFileFromUrl(file.url, file.filename, { credentials });
+    } else {
+      void Linking.openURL(file.url);
+    }
+  };
+  const handleOpenExternal = () => {
+    onOpenExternal?.(file);
+  };
+  const handleRemove = () => {
+    if (!onRemove) return;
+    Alert.alert(l.removeConfirmTitle, l.removeConfirmMessage(file.filename), [
+      { text: l.cancel, style: "cancel" },
+      {
+        text: l.remove,
+        style: "destructive",
+        onPress: () => {
+          if (total === 1) {
+            onRemove(file.id);
+            close();
+            return;
+          }
+          // Pre-move before the list shrinks, clamping off the end.
+          onIndexChange(activeIndex >= total - 1 ? activeIndex - 1 : activeIndex);
+          onRemove(file.id);
+        },
+      },
+    ]);
+  };
 
   return (
     <Modal visible transparent onRequestClose={close} animationType="fade">
-      <View style={styles.overlay} ref={overlayRef}>
-        <Pressable
-          accessibilityRole="button"
-          accessibilityLabel="Close"
-          onPress={close}
-          style={StyleSheet.absoluteFill}
-        />
+      <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}`}
+            </Text>
+          ) : null}
+          <View style={styles.spacer} />
 
-        <View style={styles.previewPanel}>
-          <FilePreview file={file} labels={labels} onError={onError} rotation={rot.rotationFor(file.id)} />
-        </View>
+          {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));
+                  }}
+                />
+              ) : null}
+            </>
+          ) : null}
 
-        {isImage && rotatable ? (
-          <View style={styles.controls}>
-            <Pressable
-              onPress={() => rot.rotate(file.id, -1)}
-              accessibilityRole="button"
-              accessibilityLabel="Rotate left"
-              style={styles.controlButton}
-            >
-              <Icon name="rotate-ccw" size={20} color={colors.white} />
-            </Pressable>
-            <Pressable
-              onPress={() => rot.rotate(file.id, 1)}
-              accessibilityRole="button"
-              accessibilityLabel="Rotate right"
-              style={styles.controlButton}
-            >
-              <Icon name="rotate-cw" size={20} color={colors.white} />
-            </Pressable>
-            {onPersistRotation && rot.rotationFor(file.id) !== 0 ? (
-              <Pressable
-                onPress={() => { if (!persisting) onPersistRotation(file, rot.rotationFor(file.id)); }}
-                accessibilityRole="button"
-                accessibilityLabel="Save rotation"
-                disabled={persisting}
-                style={[styles.controlButton, styles.controlButtonPrimary, persisting && styles.controlButtonBusy]}
-              >
-                <Icon name="check" size={20} color={colors.white} />
-              </Pressable>
-            ) : null}
-          </View>
-        ) : 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}
 
-        {activeIndex > 0 ? (
-          <Pressable
-            onPress={prev}
-            accessibilityRole="button"
-            accessibilityLabel="Previous"
-            style={[styles.navButton, styles.navLeft]}
-          >
-            <Icon name="chevron-left" size={28} color={colors.white} />
-          </Pressable>
-        ) : null}
+          <IconButton size="lg" icon="x" tooltip={l.close} color="secondary" onPress={close} />
+        </View>
 
-        {activeIndex < total - 1 ? (
-          <Pressable
-            onPress={next}
-            accessibilityRole="button"
-            accessibilityLabel="Next"
-            style={[styles.navButton, styles.navRight]}
-          >
-            <Icon name="chevron-right" size={28} color={colors.white} />
-          </Pressable>
-        ) : null}
+        <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}
+            />
+          )}
 
-        <View style={styles.captionWrap} pointerEvents="none">
-          <View style={styles.captionPill}>
-            <Text size="sm" style={styles.captionText}>{caption}</Text>
-          </View>
+          {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}
         </View>
       </View>
     </Modal>
@@ -188,20 +299,34 @@ export function FileGalleryModal(props: FileGalleryModalProps) {
 }
 
 const styles = StyleSheet.create({
-  overlay: {
+  surface: {
     flex: 1,
-    backgroundColor: "rgba(0, 0, 0, 0.88)",
-    justifyContent: "center",
+    backgroundColor: colors.background,
+  },
+  toolbar: {
+    flexDirection: "row",
     alignItems: "center",
+    gap: 8,
+    paddingHorizontal: 12,
+    paddingVertical: 8,
+    borderBottomWidth: 1,
+    borderBottomColor: colors.border,
+    zIndex: 1,
   },
-  previewPanel: {
-    width: "92%",
-    height: "86%",
-    backgroundColor: colors.background,
-    borderRadius: 8,
-    overflow: "hidden",
+  filename: {
+    flexShrink: 1,
+  },
+  counter: {
+    flexShrink: 0,
   },
-  navButton: {
+  spacer: {
+    flex: 1,
+  },
+  previewArea: {
+    flex: 1,
+    justifyContent: "center",
+  },
+  nav: {
     position: "absolute",
     top: "50%",
     transform: [{ translateY: -28 }],
@@ -218,41 +343,4 @@ const styles = StyleSheet.create({
   navRight: {
     right: 16,
   },
-  controls: {
-    position: "absolute",
-    top: 16,
-    right: 16,
-    flexDirection: "row",
-    gap: 8,
-  },
-  controlButton: {
-    width: 44,
-    height: 44,
-    borderRadius: 22,
-    backgroundColor: "rgba(0, 0, 0, 0.4)",
-    justifyContent: "center",
-    alignItems: "center",
-  },
-  controlButtonPrimary: {
-    backgroundColor: colors.blue["600"],
-  },
-  controlButtonBusy: {
-    opacity: 0.6,
-  },
-  captionWrap: {
-    position: "absolute",
-    bottom: 24,
-    left: 0,
-    right: 0,
-    alignItems: "center",
-  },
-  captionPill: {
-    backgroundColor: "rgba(0, 0, 0, 0.7)",
-    paddingHorizontal: 12,
-    paddingVertical: 6,
-    borderRadius: 6,
-  },
-  captionText: {
-    color: colors.white,
-  },
 });

package/src/file_grid.tsx

@@ -0,0 +1,184 @@
+// FileGrid — the upload-aware file grid: a ThumbnailGrid that interleaves
+// completed files (FileThumbnail) with in-flight uploads (UploadingThumbnail).
+// Pure: the host supplies completed files + a normalized upload queue + callbacks;
+// no domain/upload-transport coupling. Each host wires its own upload mechanism
+// (a custom-code app: app-sdk useAttachments; the frontend: its upload queue) and
+// feeds the result here.
+//
+// Layout: by default tiles FILL the container width (uniform size derived from
+// `minItemWidth`, reflowing as the width changes); a short last row keeps that
+// size and is left-aligned — no stretched tiles, no empty spacer cells. Pass
+// `columns` for a fixed column count, or `itemSize` for exact fixed-size tiles.
+
+import { useCallback } from "react";
+import type { ViewStyle } from "react-native";
+import { FileThumbnail, type DisplayFile } from "./file_thumbnail";
+import { ThumbnailGrid } from "./file_thumbnail_grid";
+import { UploadingThumbnail, type UploadStatus, type UploadStatusLabels } from "./uploading_thumbnail";
+import { Button } from "./button";
+
+/** An in-flight upload item (everything except a completed file). */
+export interface PendingUpload {
+  id: string;
+  filename: string;
+  mimeType: string;
+  previewUrl?: string;
+  status: UploadStatus;
+  staleFile?: boolean;
+}
+
+/** A live upload-queue entry: a just-completed file (in place) or an in-flight
+ *  upload. The host maps its own upload state to this. */
+export type FileUpload = { status: "complete"; id: string; file: DisplayFile } | PendingUpload;
+
+export interface FileGridLabels {
+  /** "Retry all" footer button (shown when any upload errored). */
+  retryAll?: string;
+  /** Status text for in-flight upload tiles (failed / paused / retrying / …). */
+  upload?: UploadStatusLabels;
+}
+
+export interface FileGridProps {
+  /** Pre-existing completed files (e.g. a record's saved attachments). */
+  files?: DisplayFile[];
+  /** The live add-queue: completed-in-place or in-flight uploads. */
+  uploads?: FileUpload[];
+  /** EXACT fixed tile size (px) — opts out of fill, for small fixed tiles. */
+  itemSize?: number;
+  /** FILL with a fixed column count (tiles take an equal 1/N of the width). */
+  columns?: number;
+  /** FILL target width (default 96): the default mode derives the column count so
+   *  each tile is ≥ this and rows span the container. */
+  minItemWidth?: number;
+  gap?: number;
+  maxVisible?: number;
+  /** SINGLE non-wrapping row, fit-to-width: shows as many tiles as fit, reserving
+   *  a "+N" overflow tile. For a dense strip in a fixed-width container. */
+  singleRow?: boolean;
+  /** Press handler for the "+N" overflow tile (the hidden count). Host wires it —
+   *  e.g. open the gallery at the first hidden file. */
+  onOverflowPress?: (hiddenCount: number) => void;
+  style?: ViewStyle;
+  disablePress?: boolean;
+  partialRowAlign?: "start" | "end";
+  selectedIds?: ReadonlySet<string>;
+  /** When provided, tapping toggles selection instead of `onFilePress`. */
+  onToggleSelect?: (id: string) => void;
+  /** A completed file was pressed (open it / a gallery). */
+  onFilePress?: (file: DisplayFile) => void;
+  /** Remove a completed file (its id). */
+  onDisplayRemove?: (id: string) => void;
+  /** Remove an in-flight upload (its id) — cancels it. */
+  onUploadRemove?: (id: string) => void;
+  /** Retry one failed upload. */
+  onRetry?: (id: string) => void;
+  /** Retry all failed uploads. */
+  onRetryAll?: () => void;
+  labels?: FileGridLabels;
+}
+
+type RenderItem =
+  | { kind: "display"; file: DisplayFile; removeId: string }
+  | { kind: "upload"; removeId: string; upload: PendingUpload };
+
+function buildRenderItems(files?: DisplayFile[], uploads?: FileUpload[]): RenderItem[] {
+  const items: RenderItem[] = [];
+  if (files) {
+    for (const file of files) items.push({ kind: "display", file, removeId: file.id });
+  }
+  if (uploads) {
+    for (const upload of uploads) {
+      if (upload.status === "complete") {
+        items.push({ kind: "display", file: upload.file, removeId: upload.id });
+      } else {
+        items.push({ kind: "upload", removeId: upload.id, upload });
+      }
+    }
+  }
+  return items;
+}
+
+export function FileGrid(props: FileGridProps) {
+  const {
+    files,
+    uploads,
+    itemSize,
+    columns,
+    minItemWidth,
+    gap = 8,
+    maxVisible,
+    singleRow,
+    onOverflowPress,
+    style,
+    disablePress,
+    partialRowAlign,
+    selectedIds,
+    onToggleSelect,
+    onFilePress,
+    onDisplayRemove,
+    onUploadRemove,
+    onRetry,
+    onRetryAll,
+    labels,
+  } = props;
+
+  const renderItems = buildRenderItems(files, uploads);
+
+  const handleFilePress = useCallback(
+    (file: DisplayFile) => {
+      if (disablePress) return;
+      if (onToggleSelect) {
+        onToggleSelect(file.id);
+        return;
+      }
+      onFilePress?.(file);
+    },
+    [disablePress, onToggleSelect, onFilePress],
+  );
+
+  const retryAll =
+    onRetryAll && renderItems.some((item) => item.kind === "upload" && item.upload.status === "error") ? (
+      <Button onPress={onRetryAll} color="danger" title={labels?.retryAll ?? "Retry all"} />
+    ) : null;
+
+  return (
+    <ThumbnailGrid
+      items={renderItems}
+      keyExtractor={(item) => item.removeId}
+      itemSize={itemSize}
+      columns={columns}
+      minItemWidth={minItemWidth}
+      gap={gap}
+      maxVisible={maxVisible}
+      singleRow={singleRow}
+      onOverflowPress={onOverflowPress}
+      partialRowAlign={partialRowAlign}
+      style={style}
+      disablePress={disablePress}
+      footer={retryAll}
+      renderItem={(item, size) =>
+        item.kind === "display" ? (
+          <FileThumbnail
+            file={item.file}
+            size={size}
+            onPress={disablePress ? undefined : () => handleFilePress(item.file)}
+            onRemove={onDisplayRemove ? () => onDisplayRemove(item.removeId) : undefined}
+            selected={selectedIds?.has(item.file.id)}
+          />
+        ) : (
+          <UploadingThumbnail
+            filename={item.upload.filename}
+            mimeType={item.upload.mimeType}
+            previewUrl={item.upload.previewUrl}
+            status={item.upload.status}
+            staleFile={item.upload.status === "error" ? item.upload.staleFile : undefined}
+            size={size}
+            onRemove={onUploadRemove ? () => onUploadRemove(item.removeId) : undefined}
+            onRetry={onRetry ? () => onRetry(item.removeId) : undefined}
+            labels={labels?.upload}
+          />
+        )
+      }
+    />
+  );
+}