@lotics/ui 1.15.0 → 1.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
@@ -9,6 +9,11 @@
     "./download": "./src/download.ts",
     "./file_badge": "./src/file_badge.tsx",
     "./file_thumbnail": "./src/file_thumbnail.tsx",
+    "./file_preview": {
+      "react-native": "./src/file_preview.tsx",
+      "default": "./src/file_preview.web.tsx"
+    },
+    "./file_preview_types": "./src/file_preview_types.ts",
     "./file_gallery_modal": "./src/file_gallery_modal.tsx",
     "./pagination": "./src/pagination.tsx",
     "./bar_chart": "./src/bar_chart.tsx",
@@ -153,6 +158,8 @@
   },
   "license": "MIT",
   "peerDependencies": {
+    "@lotics/docx": "^0.1.0",
+    "@lotics/xlsx": "^0.1.0",
     "@react-native-picker/picker": ">=2.0.0",
     "expo-image": ">=3.0.0",
     "lucide-react": ">=0.460.0",
@@ -165,6 +172,12 @@
     "recharts": ">=3.0.0"
   },
   "peerDependenciesMeta": {
+    "@lotics/docx": {
+      "optional": true
+    },
+    "@lotics/xlsx": {
+      "optional": true
+    },
     "expo-image": {
       "optional": true
     },
@@ -187,6 +200,8 @@
     "test": "vitest run"
   },
   "devDependencies": {
+    "@lotics/docx": "^0.1.0",
+    "@lotics/xlsx": "^0.1.0",
     "recharts": "^3.8.1"
   }
 }

package/src/combobox.tsx

@@ -29,6 +29,13 @@ export interface ComboboxProps<T extends string = string> {
   searchPlaceholder?: string;
   /** Shown when there are no results and not loading. Default: "No results". */
   emptyText?: string;
+  /** Accept free entry: when the typed query matches no option, offer it as a
+   *  custom value. `onValueChange` then receives `{ value: query, label: query }`.
+   *  The consumer decides what an unknown value means (e.g. a manually-typed id). */
+  allowCustom?: boolean;
+  /** Label for the free-entry row (default: the raw query). Return `null` to
+   *  suppress it for a given query (e.g. still incomplete/invalid). */
+  customOptionLabel?: (query: string) => string | null;
   disabled?: boolean;
   autoFocus?: boolean;
   testID?: string;
@@ -56,6 +63,8 @@ export function Combobox<T extends string>(props: ComboboxProps<T>) {
     placeholder,
     searchPlaceholder,
     emptyText,
+    allowCustom,
+    customOptionLabel,
     disabled = false,
     autoFocus = false,
     testID,
@@ -73,9 +82,10 @@ export function Combobox<T extends string>(props: ComboboxProps<T>) {
     (v: T) => {
       const opt = options.find((o) => o.value === v);
       if (opt) onValueChange(opt);
+      else if (allowCustom && v) onValueChange({ value: v, label: v });
       setOpen(false);
     },
-    [options, onValueChange],
+    [options, onValueChange, allowCustom],
   );
 
   return (
@@ -117,6 +127,8 @@ export function Combobox<T extends string>(props: ComboboxProps<T>) {
           onValueChange={handleSelect}
           onRequestClose={() => setOpen(false)}
           enableSearch
+          allowCustom={allowCustom}
+          customOptionLabel={customOptionLabel}
           onSearchChange={debouncedSearch}
           // Local filtering is wrong when the consumer drives search server-side.
           serverFiltered={onSearchChange !== undefined}

package/src/custom_option.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect } from "vitest";
+import { customOptionFor } from "./custom_option";
+
+const opts = [
+  { value: "BX1N", label: "BX1N" },
+  { value: "UX1N", label: "UX1N" },
+];
+
+describe("customOptionFor", () => {
+  it("offers the trimmed query when nothing matches", () => {
+    expect(customOptionFor({ allowCustom: true, multi: false, query: "  ABCD ", options: opts }))
+      .toEqual({ value: "ABCD", label: "ABCD" });
+  });
+
+  it("suppressed when free entry is off", () => {
+    expect(customOptionFor({ allowCustom: false, multi: false, query: "ABCD", options: opts })).toBeNull();
+    expect(customOptionFor({ allowCustom: undefined, multi: false, query: "ABCD", options: opts })).toBeNull();
+  });
+
+  it("suppressed for multi-select", () => {
+    expect(customOptionFor({ allowCustom: true, multi: true, query: "ABCD", options: opts })).toBeNull();
+  });
+
+  it("suppressed for an empty / whitespace query", () => {
+    expect(customOptionFor({ allowCustom: true, multi: false, query: "   ", options: opts })).toBeNull();
+  });
+
+  it("suppressed when the query matches an option value (case-insensitive)", () => {
+    expect(customOptionFor({ allowCustom: true, multi: false, query: "bx1n", options: opts })).toBeNull();
+  });
+
+  it("uses customOptionLabel for the row label but keeps the raw value", () => {
+    expect(customOptionFor({
+      allowCustom: true, multi: false, query: "ABCD", options: opts,
+      customOptionLabel: (q) => `Add "${q}"`,
+    })).toEqual({ value: "ABCD", label: 'Add "ABCD"' });
+  });
+
+  it("suppressed when customOptionLabel returns null", () => {
+    expect(customOptionFor({
+      allowCustom: true, multi: false, query: "AB", options: opts,
+      customOptionLabel: () => null,
+    })).toBeNull();
+  });
+
+  it("ignores undefined / false holes in the options list", () => {
+    expect(customOptionFor({ allowCustom: true, multi: false, query: "ABCD", options: [undefined, false, ...opts] }))
+      .toEqual({ value: "ABCD", label: "ABCD" });
+  });
+});

package/src/custom_option.ts

@@ -0,0 +1,30 @@
+import type { PickerOption } from "./picker";
+
+/**
+ * Resolve the free-entry ("custom") option a search picker should offer for the
+ * current query — or `null` when it should not be offered. The option's `value`
+ * stays the raw trimmed query; consumers decide what an unknown value means.
+ *
+ * Suppressed when: free entry is disabled, the picker is multi-select, the query
+ * is empty, the query already matches an existing option's value
+ * (case-insensitive), or `customOptionLabel` returns `null` for it.
+ *
+ * Pure and RN-free so it is unit-testable in isolation from `PickerMenu`.
+ */
+export function customOptionFor<T extends string>(args: {
+  allowCustom: boolean | undefined;
+  multi: boolean;
+  query: string;
+  options: (PickerOption<T> | undefined | false)[];
+  customOptionLabel?: (query: string) => string | null;
+}): PickerOption<T> | null {
+  const { allowCustom, multi, query, options, customOptionLabel } = args;
+  if (!allowCustom || multi) return null;
+  const q = query.trim();
+  if (!q || options.some((o) => o && String(o.value).toLowerCase() === q.toLowerCase())) {
+    return null;
+  }
+  const label = customOptionLabel ? customOptionLabel(q) : q;
+  if (label == null) return null;
+  return { value: q as T, label };
+}

package/src/file_gallery_modal.tsx

@@ -1,12 +1,11 @@
-// FileGalleryModal — pure fullscreen image preview with prev/next nav + ESC close.
-// Pure primitive: takes DisplayFile[] only, no Lotics domain coupling. Frontend
-// has a richer modal in `frontend/components/file_gallery.tsx` that handles
-// xlsx/docx/pdf inline rendering — leave that one for Lotics-specific previews
-// and use this primitive when only images need previewing.
+// 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.
 
 import { useCallback, useEffect, useRef } from "react";
 import {
-  Image,
   Modal,
   Pressable,
   StyleSheet,
@@ -15,8 +14,9 @@ import {
 import { Text } from "./text";
 import { Icon } from "./icon";
 import { colors } from "./colors";
-import { isImageMimeType } from "./mime";
 import type { DisplayFile } from "./file_thumbnail";
+import { FilePreview } from "./file_preview";
+import type { PreviewLabels } from "./file_preview_types";
 
 export interface FileGalleryModalProps {
   files: DisplayFile[];
@@ -24,19 +24,22 @@ export interface FileGalleryModalProps {
   activeIndex: number | null;
   onIndexChange: (next: number | null) => void;
   /**
-   * Optional caption suffix shown under the image. Useful for hint text like
+   * 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>;
+  /** Reported when a file fails to render (host wires to its logger). */
+  onError?: (error: unknown, meta: { fileId: string; mimeType: string }) => void;
 }
 
 /**
- * Image-focused fullscreen preview. Non-image MIME types render as a simple
- * "{filename} · cannot preview" card — callers needing rich preview should use
- * a Lotics-specific gallery instead.
+ * Fullscreen 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 } = props;
+  const { files, activeIndex, onIndexChange, captionHint, labels, onError } = props;
   const visible = activeIndex !== null;
   const overlayRef = useRef<View | null>(null);
 
@@ -81,22 +84,9 @@ export function FileGalleryModal(props: FileGalleryModalProps) {
           style={StyleSheet.absoluteFill}
         />
 
-        {isImageMimeType(file.mimeType) ? (
-          <Image
-            source={{ uri: file.url }}
-            style={styles.image}
-            resizeMode="contain"
-          />
-        ) : (
-          <View style={styles.unsupportedCard}>
-            <Text size="md" style={styles.unsupportedText}>
-              {file.filename}
-            </Text>
-            <Text size="sm" color="muted">
-              Cannot preview this file type in the gallery.
-            </Text>
-          </View>
-        )}
+        <View style={styles.previewPanel}>
+          <FilePreview file={file} labels={labels} onError={onError} />
+        </View>
 
         {activeIndex > 0 ? (
           <Pressable
@@ -137,20 +127,12 @@ const styles = StyleSheet.create({
     justifyContent: "center",
     alignItems: "center",
   },
-  image: {
+  previewPanel: {
     width: "92%",
-    height: "85%",
-  },
-  unsupportedCard: {
-    backgroundColor: colors.white,
+    height: "86%",
+    backgroundColor: colors.background,
     borderRadius: 8,
-    padding: 24,
-    maxWidth: 480,
-    gap: 8,
-    alignItems: "center",
-  },
-  unsupportedText: {
-    fontWeight: "600",
+    overflow: "hidden",
   },
   navButton: {
     position: "absolute",

package/src/file_preview.tsx

@@ -0,0 +1,38 @@
+import { View, Image, StyleSheet } from "react-native";
+import { Text } from "./text";
+import { DocumentCard } from "./file_thumbnail";
+import { isImageMimeType } from "./mime";
+import { type FilePreviewProps, resolveLabels } from "./file_preview_types";
+
+/**
+ * Native (mobile) fallback: images render full-bleed; everything else shows a
+ * document placeholder. Rich document rendering (docx/xlsx/pdf) is web-only —
+ * the `.web.tsx` variant carries it; native consumers download instead.
+ */
+export function FilePreview({ file, labels }: FilePreviewProps) {
+  const l = resolveLabels(labels);
+  if (isImageMimeType(file.mimeType)) {
+    return (
+      <Image
+        source={{ uri: file.url }}
+        resizeMode="contain"
+        style={styles.image}
+        accessibilityIgnoresInvertColors
+      />
+    );
+  }
+  return (
+    <View style={styles.placeholder}>
+      <DocumentCard mimeType={file.mimeType} filename={file.filename} size={120} />
+      <Text size="sm" color="muted" style={styles.placeholderText}>
+        {l.notAvailable}
+      </Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  image: { flex: 1, width: "100%" },
+  placeholder: { flex: 1, justifyContent: "center", alignItems: "center", gap: 16 },
+  placeholderText: { marginTop: 8 },
+});

package/src/file_preview.web.tsx

@@ -0,0 +1,198 @@
+import { useEffect, useRef, useState } from "react";
+import { View, StyleSheet } from "react-native";
+import { Text } from "./text";
+import { Button } from "./button";
+import { DocumentCard, MediaCard } from "./file_thumbnail";
+import {
+  isImageMimeType,
+  isPdfMimeType,
+  isDocxMimeType,
+  isVideoMimeType,
+  isAudioMimeType,
+  isPreviewableMimeType,
+} from "./mime";
+import { type FilePreviewProps, resolveLabels, type PreviewLabels } from "./file_preview_types";
+import { SpreadsheetView } from "./spreadsheet_view";
+import { downloadFileFromUrl } from "./download";
+
+/**
+ * Universal inline file preview (web). Renders by MIME type: images, PDF, video
+ * and audio use browser-native elements; Word via the lazy-loaded `@lotics/docx`
+ * renderer; Excel/CSV via the read-only `@lotics/xlsx` canvas. Heavy engines are
+ * dynamic-imported so non-document files never pay their bundle cost.
+ *
+ * Pure: i18n via `labels` props, errors via `onError` — no lingui/analytics
+ * (purity test). Lifted from the frontend gallery so both share one renderer.
+ */
+export function FilePreview({ file, labels, onError }: FilePreviewProps) {
+  const l = resolveLabels(labels);
+
+  if (isImageMimeType(file.mimeType)) {
+    return <img alt={file.filename} src={file.url} style={imageStyle} />;
+  }
+  if (isPdfMimeType(file.mimeType)) {
+    return <iframe src={file.url} title={file.filename} style={fullFrameStyle} />;
+  }
+  if (isDocxMimeType(file.mimeType)) {
+    return <WordPreview file={file} labels={l} onError={onError} />;
+  }
+  if (isVideoMimeType(file.mimeType)) {
+    return <video controls preload="metadata" src={file.url} style={mediaElementStyle} />;
+  }
+  if (isAudioMimeType(file.mimeType)) {
+    return (
+      <div style={audioContainerStyle}>
+        <MediaCard mimeType={file.mimeType} filename={file.filename} icon="music" size={160} />
+        <audio controls preload="metadata" src={file.url} style={audioElementStyle} />
+      </div>
+    );
+  }
+  if (isPreviewableMimeType(file.mimeType)) {
+    return <SpreadsheetView file={file} labels={l} onError={onError} />;
+  }
+
+  return (
+    <View style={styles.placeholder}>
+      <DocumentCard mimeType={file.mimeType} filename={file.filename} size={120} />
+      <Text size="sm" color="muted" style={styles.placeholderText}>
+        {l.notAvailable}
+      </Text>
+    </View>
+  );
+}
+
+/** Lazy bridge — pulls jszip + prosemirror only when a .docx is actually opened. */
+async function lazyLoadDocx(
+  ...args: Parameters<typeof import("@lotics/docx/load").loadDocxIntoElement>
+): ReturnType<typeof import("@lotics/docx/load").loadDocxIntoElement> {
+  const mod = await import("@lotics/docx/load");
+  return mod.loadDocxIntoElement(...args);
+}
+
+function WordPreview({
+  file,
+  labels,
+  onError,
+}: {
+  file: FilePreviewProps["file"];
+  labels: PreviewLabels;
+  onError: FilePreviewProps["onError"];
+}) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [state, setState] = useState<{ loading: boolean; error: string | undefined }>({
+    loading: true,
+    error: undefined,
+  });
+
+  useEffect(() => {
+    const controller = new AbortController();
+    let loadedView: { destroy: () => void } | null = null;
+    setState({ loading: true, error: undefined });
+
+    const run = async () => {
+      const response = await fetch(file.url, { signal: controller.signal });
+      if (!response.ok) throw new Error(`Document fetch failed (${response.status})`);
+      const arrayBuffer = await response.arrayBuffer();
+      const bytes = new Uint8Array(arrayBuffer);
+      if (controller.signal.aborted || !containerRef.current) return;
+      containerRef.current.innerHTML = "";
+      const loaded = await lazyLoadDocx(containerRef.current, bytes);
+      if (controller.signal.aborted) {
+        loaded.view.destroy();
+        return;
+      }
+      loadedView = loaded.view;
+    };
+
+    run().then(
+      () => {
+        if (!controller.signal.aborted) setState({ loading: false, error: undefined });
+      },
+      (err: unknown) => {
+        if (controller.signal.aborted) return;
+        if (err instanceof DOMException && err.name === "AbortError") return;
+        onError?.(err, { fileId: file.id, mimeType: file.mimeType });
+        setState({ loading: false, error: labels.loadFailed });
+      },
+    );
+
+    return () => {
+      controller.abort();
+      loadedView?.destroy();
+    };
+  }, [file.url, file.id, file.mimeType, labels.loadFailed, onError]);
+
+  return (
+    <div style={wordContainerStyle}>
+      {state.loading && (
+        <div style={centerStyle}>
+          <Text size="sm" color="muted">
+            …
+          </Text>
+        </div>
+      )}
+      {state.error !== undefined && (
+        <div style={centerStyle}>
+          <Text size="sm" color="muted">
+            {state.error}
+          </Text>
+          <View style={{ marginTop: 12 }}>
+            <Button
+              icon="download"
+              title={labels.download}
+              color="secondary"
+              onPress={() => void downloadFileFromUrl(file.url, file.filename)}
+            />
+          </View>
+        </div>
+      )}
+      <div ref={containerRef} style={state.loading ? hiddenStyle : wordContentStyle} />
+    </div>
+  );
+}
+
+const styles = StyleSheet.create({
+  placeholder: { flex: 1, justifyContent: "center", alignItems: "center", gap: 16 },
+  placeholderText: { marginTop: 8 },
+});
+
+const imageStyle: React.CSSProperties = {
+  width: "100%",
+  height: "100%",
+  objectFit: "contain",
+  backgroundColor: "rgba(10, 10, 10, 0.8)",
+};
+const fullFrameStyle: React.CSSProperties = { width: "100%", height: "100%", border: "none" };
+const mediaElementStyle: React.CSSProperties = {
+  width: "100%",
+  height: "100%",
+  backgroundColor: "rgba(10, 10, 10, 0.8)",
+  objectFit: "contain",
+};
+const audioContainerStyle: React.CSSProperties = {
+  display: "flex",
+  flexDirection: "column",
+  alignItems: "center",
+  justifyContent: "center",
+  flex: 1,
+  gap: 24,
+  padding: 48,
+};
+const audioElementStyle: React.CSSProperties = { width: "min(480px, 100%)" };
+const wordContainerStyle: React.CSSProperties = {
+  display: "flex",
+  flexDirection: "column",
+  flex: 1,
+  overflow: "auto",
+  backgroundColor: "#f4f4f5",
+};
+const wordContentStyle: React.CSSProperties = { display: "block", minHeight: "100%" };
+const hiddenStyle: React.CSSProperties = { display: "none" };
+const centerStyle: React.CSSProperties = {
+  display: "flex",
+  flexDirection: "column",
+  alignItems: "center",
+  justifyContent: "center",
+  flex: 1,
+  padding: 48,
+};

package/src/file_preview_types.ts

@@ -0,0 +1,35 @@
+import type { DisplayFile } from "./file_thumbnail";
+
+/**
+ * Caption/error strings shown inside the preview. `@lotics/ui` is i18n-free
+ * (purity test forbids lingui), so the host passes translated strings; English
+ * is the fallback.
+ */
+export interface PreviewLabels {
+  notAvailable: string;
+  loadFailed: string;
+  download: string;
+  passwordProtected: string;
+}
+
+export const defaultPreviewLabels: PreviewLabels = {
+  notAvailable: "Preview not available",
+  loadFailed: "Failed to load preview",
+  download: "Download file",
+  passwordProtected: "This file is password-protected and cannot be previewed",
+};
+
+export interface FilePreviewProps {
+  file: DisplayFile;
+  /** Override any subset of the English default labels. */
+  labels?: Partial<PreviewLabels>;
+  /**
+   * Reported on a render/parse failure. Logging/analytics live in the host (the
+   * package stays analytics-free), so the host wires this to its logger.
+   */
+  onError?: (error: unknown, meta: { fileId: string; mimeType: string }) => void;
+}
+
+export function resolveLabels(labels: Partial<PreviewLabels> | undefined): PreviewLabels {
+  return labels ? { ...defaultPreviewLabels, ...labels } : defaultPreviewLabels;
+}

package/src/mime.ts

@@ -13,3 +13,49 @@ export function isVideoMimeType(mimeType: string): boolean {
 export function isAudioMimeType(mimeType: string): boolean {
   return mimeType.toLowerCase().startsWith("audio/");
 }
+
+const EXCEL_MIME_TYPES = [
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  "application/wps-office.xlsx",
+  "application/wps-office.xls",
+  "application/vnd.ms-excel",
+];
+
+const LEGACY_EXCEL_MIME_TYPES = ["application/vnd.ms-excel", "application/wps-office.xls"];
+
+const DOCX_MIME_TYPES = [
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  "application/wps-office.docx",
+];
+
+export function isPdfMimeType(mimeType: string): boolean {
+  return mimeType.toLowerCase() === "application/pdf";
+}
+
+export function isExcelMimeType(mimeType: string): boolean {
+  return EXCEL_MIME_TYPES.includes(mimeType.toLowerCase());
+}
+
+/** Legacy .xls (BIFF) — not parseable in-app; excluded from previewable. */
+export function isLegacyExcelMimeType(mimeType: string): boolean {
+  return LEGACY_EXCEL_MIME_TYPES.includes(mimeType.toLowerCase());
+}
+
+export function isCsvMimeType(mimeType: string): boolean {
+  const mt = mimeType.toLowerCase();
+  return mt === "text/csv" || mt === "text/tab-separated-values";
+}
+
+export function isDocxMimeType(mimeType: string): boolean {
+  return DOCX_MIME_TYPES.includes(mimeType.toLowerCase());
+}
+
+/** PDF, modern Excel (.xlsx), Word (.docx), or CSV — types FilePreview renders inline. */
+export function isPreviewableMimeType(mimeType: string): boolean {
+  return (
+    (isExcelMimeType(mimeType) && !isLegacyExcelMimeType(mimeType)) ||
+    isCsvMimeType(mimeType) ||
+    isPdfMimeType(mimeType) ||
+    isDocxMimeType(mimeType)
+  );
+}

package/src/picker_menu.tsx

@@ -10,6 +10,7 @@ import { MenuButton } from "./menu_button";
 import { ActivityIndicator } from "./activity_indicator";
 import { PickerOption, PickerValue, PickerOnValueChange, PickerOnClose } from "./picker";
 import { useScreenSize } from "./use_screen_size";
+import { customOptionFor } from "./custom_option";
 
 export interface PickerMenuProps<T extends string = string, MULTI extends boolean = false> {
   testID?: string;
@@ -22,6 +23,14 @@ export interface PickerMenuProps<T extends string = string, MULTI extends boolea
   renderOptionContent?: (option: PickerOption<T>) => React.ReactNode;
   /** Enable search input to filter options */
   enableSearch?: boolean;
+  /** Single-select + search only: when the typed query matches no option, append
+   *  a trailing row that selects the raw query as a custom value (free entry).
+   *  `onValueChange` then receives the typed string. */
+  allowCustom?: boolean;
+  /** Label for the free-entry row (default: the raw query). Return `null` to
+   *  suppress the row for a given query — e.g. while it is still incomplete or
+   *  invalid — so "add" only appears when it is a meaningful thing to add. */
+  customOptionLabel?: (query: string) => string | null;
   enableSelectAll?: boolean;
   includeEmptyOption?: boolean;
   /** Called whenever the search text changes. Provide it to drive server-side
@@ -61,6 +70,8 @@ export function PickerMenu<T extends string, MULTI extends boolean = false>(
     onRequestClose,
     enableSelectAll,
     enableSearch,
+    allowCustom,
+    customOptionLabel,
     includeEmptyOption,
     onSearchChange,
     serverFiltered,
@@ -92,6 +103,13 @@ export function PickerMenu<T extends string, MULTI extends boolean = false>(
 
   const [searchQuery, setSearchQuery] = useState("");
 
+  // Free entry: a trailing selectable row carrying the raw query as its value
+  // (recognised below for distinct styling). See `customOptionFor` for the rules.
+  const customOpt = useMemo(
+    () => customOptionFor({ allowCustom, multi, query: searchQuery, options, customOptionLabel }),
+    [allowCustom, multi, searchQuery, options, customOptionLabel],
+  );
+
   const filteredOptions = useMemo(() => {
     let result = options;
     // Skip the local filter in server-driven mode — `options` already reflect
@@ -107,8 +125,11 @@ export function PickerMenu<T extends string, MULTI extends boolean = false>(
       };
       result = [emptyOption, ...result];
     }
+    if (customOpt) {
+      result = [...result, customOpt];
+    }
     return result;
-  }, [options, enableSearch, searchQuery, includeEmptyOption, serverFiltered]);
+  }, [options, enableSearch, searchQuery, includeEmptyOption, serverFiltered, customOpt]);
 
   const [focusedIndex, setFocusedIndex] = useState<number>(() => {
     const selectedIndex = filteredOptions.findIndex((opt) => {
@@ -297,23 +318,26 @@ export function PickerMenu<T extends string, MULTI extends boolean = false>(
             ? Array.isArray(multiValue) && multiValue.includes(item.value)
             : item.value === singleValue;
           const isFocused = index === focusedIndex;
+          const isCustom = !!customOpt && item.value === customOpt.value;
 
           return (
             <MenuButton
               key={item.value}
-              testID={item.testID || `picker-option-${item.value}`}
+              testID={isCustom ? "picker-custom-option" : item.testID || `picker-option-${item.value}`}
               icon={multi ? <Checkbox checked={isSelected} /> : undefined}
               title={
-                renderOptionContent ? (
+                renderOptionContent && !isCustom ? (
                   renderOptionContent(item)
                 ) : (
-                  <Text userSelect="none" numberOfLines={1}>
+                  <Text userSelect="none" numberOfLines={1} color={isCustom ? "zinc-500" : undefined}>
                     {item.label}
                   </Text>
                 )
               }
               right={
-                !multi && isSelected ? (
+                isCustom ? (
+                  <Icon name="plus" size={16} color={colors.zinc["400"]} />
+                ) : !multi && isSelected ? (
                   <Icon name="check" size={18} color={colors.zinc["950"]} />
                 ) : undefined
               }

package/src/spreadsheet_view.tsx

@@ -0,0 +1,304 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { View, StyleSheet, Pressable } from "react-native";
+import { Text } from "./text";
+import { Button } from "./button";
+import { colors } from "./colors";
+import { isExcelMimeType } from "./mime";
+import { downloadFileFromUrl } from "./download";
+import { type PreviewLabels } from "./file_preview_types";
+import type { DisplayFile } from "./file_thumbnail";
+import type { WorkbookModel } from "@lotics/xlsx/workbook_model";
+import type { RenderConfig } from "@lotics/xlsx/canvas_renderer";
+import type { MergedCellRange } from "@lotics/xlsx/types";
+import type { LayoutConfig } from "@lotics/xlsx/canvas_layout";
+
+// All of @lotics/xlsx (parser, formula engine, canvas renderer) is dynamic-
+// imported so a consumer that never opens a spreadsheet doesn't bundle the
+// engine. Only `import type` is static here. Functions are captured on mount.
+interface XlsxApi {
+  loadWorkbookFromSnapshot: typeof import("@lotics/xlsx/workbook_model").loadWorkbookFromSnapshot;
+  recomputeIfStale: typeof import("@lotics/xlsx/formula_engine").recomputeIfStale;
+  drawSpreadsheet: typeof import("@lotics/xlsx/canvas_renderer").drawSpreadsheet;
+  LayoutEngine: typeof import("@lotics/xlsx/canvas_layout").LayoutEngine;
+  rowColToRef: typeof import("@lotics/xlsx/excel_utils").rowColToRef;
+  refToRowCol: typeof import("@lotics/xlsx/excel_utils").refToRowCol;
+  parseExcelBuffer: typeof import("@lotics/xlsx/excel_parser").parseExcelBuffer;
+  parseCsvFile: typeof import("@lotics/xlsx/csv_parser").parseCsvFile;
+}
+
+async function loadXlsx(): Promise<XlsxApi> {
+  const [model, formula, renderer, layout, utils, excel, csv] = await Promise.all([
+    import("@lotics/xlsx/workbook_model"),
+    import("@lotics/xlsx/formula_engine"),
+    import("@lotics/xlsx/canvas_renderer"),
+    import("@lotics/xlsx/canvas_layout"),
+    import("@lotics/xlsx/excel_utils"),
+    import("@lotics/xlsx/excel_parser"),
+    import("@lotics/xlsx/csv_parser"),
+  ]);
+  return {
+    loadWorkbookFromSnapshot: model.loadWorkbookFromSnapshot,
+    recomputeIfStale: formula.recomputeIfStale,
+    drawSpreadsheet: renderer.drawSpreadsheet,
+    LayoutEngine: layout.LayoutEngine,
+    rowColToRef: utils.rowColToRef,
+    refToRowCol: utils.refToRowCol,
+    parseExcelBuffer: excel.parseExcelBuffer,
+    parseCsvFile: csv.parseCsvFile,
+  };
+}
+
+async function fetchArrayBuffer(url: string, signal: AbortSignal): Promise<ArrayBuffer> {
+  const response = await fetch(url, { signal });
+  if (!response.ok) throw new Error(`Spreadsheet fetch failed (${response.status})`);
+  return response.arrayBuffer();
+}
+
+interface SpreadsheetViewProps {
+  file: DisplayFile;
+  labels: PreviewLabels;
+  onError?: (error: unknown, meta: { fileId: string; mimeType: string }) => void;
+}
+
+interface ParseState {
+  loading: boolean;
+  workbook: WorkbookModel | undefined;
+  error: string | undefined;
+}
+
+/**
+ * Read-only spreadsheet preview: parses Excel/CSV into a `WorkbookModel` and
+ * paints it with the `@lotics/xlsx` canvas renderer. Virtual-scroll — a
+ * transparent scroll layer (sized to the sheet) sits over a viewport-sized
+ * canvas that redraws on scroll. No editing, ribbon, or selection.
+ */
+export function SpreadsheetView({ file, labels, onError }: SpreadsheetViewProps) {
+  const apiRef = useRef<XlsxApi | null>(null);
+  const [state, setState] = useState<ParseState>({ loading: true, workbook: undefined, error: undefined });
+  const [sheetIndex, setSheetIndex] = useState(0);
+
+  const viewportRef = useRef<HTMLDivElement>(null);
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+  const rafRef = useRef<number | null>(null);
+  const [viewport, setViewport] = useState({ w: 0, h: 0 });
+  const [scroll, setScroll] = useState({ x: 0, y: 0 });
+
+  // Parse the file into a workbook (loads the engine on first spreadsheet open).
+  useEffect(() => {
+    const controller = new AbortController();
+    setState({ loading: true, workbook: undefined, error: undefined });
+    const run = async () => {
+      const api = apiRef.current ?? (apiRef.current = await loadXlsx());
+      const parsed = isExcelMimeType(file.mimeType)
+        ? api.parseExcelBuffer(await fetchArrayBuffer(file.url, controller.signal))
+        : await api.parseCsvFile(file.url, controller.signal);
+      if (controller.signal.aborted) return;
+      const wb = api.loadWorkbookFromSnapshot(parsed);
+      api.recomputeIfStale(wb);
+      if (controller.signal.aborted) return;
+      setSheetIndex(wb.activeSheetIndex);
+      setState({ loading: false, workbook: wb, error: undefined });
+    };
+    run().catch((err: unknown) => {
+      if (controller.signal.aborted) return;
+      if (err instanceof DOMException && err.name === "AbortError") return;
+      const passwordProtected = err instanceof Error && err.name === "PasswordProtectedError";
+      onError?.(err, { fileId: file.id, mimeType: file.mimeType });
+      setState({
+        loading: false,
+        workbook: undefined,
+        error: passwordProtected ? labels.passwordProtected : labels.loadFailed,
+      });
+    });
+    return () => controller.abort();
+  }, [file.url, file.id, file.mimeType, labels.loadFailed, labels.passwordProtected, onError]);
+
+  // Track the viewport size.
+  useEffect(() => {
+    const el = viewportRef.current;
+    if (!el || typeof ResizeObserver === "undefined") return;
+    const update = () => setViewport({ w: el.clientWidth, h: el.clientHeight });
+    update();
+    const ro = new ResizeObserver(update);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [state.workbook]);
+
+  // Coalesce native scroll (which fires faster than frames) into one redraw per frame.
+  const onScroll = useCallback(() => {
+    if (rafRef.current != null) return;
+    rafRef.current = requestAnimationFrame(() => {
+      rafRef.current = null;
+      const el = scrollRef.current;
+      if (el) setScroll({ x: el.scrollLeft, y: el.scrollTop });
+    });
+  }, []);
+  useEffect(
+    () => () => {
+      if (rafRef.current != null) cancelAnimationFrame(rafRef.current);
+    },
+    [],
+  );
+
+  const layout = useMemo(() => {
+    const api = apiRef.current;
+    const wb = state.workbook;
+    if (!api || !wb) return null;
+    const s = wb.sheets[sheetIndex];
+    if (!s) return null;
+    const used = s.getUsedRange();
+    const config: LayoutConfig = {
+      colCount: Math.max(used.maxCol + 2, 26),
+      rowCount: Math.max(used.maxRow + 5, 50),
+      colWidths: s.colWidths,
+      rowHeights: s.rowHeights,
+      defaultColWidth: s.defaultColWidth,
+      defaultRowHeight: s.defaultRowHeight,
+      hiddenCols: s.hiddenCols,
+      hiddenRows: s.hiddenRows,
+      freeze: s.freeze,
+    };
+    return new api.LayoutEngine(config);
+  }, [state.workbook, sheetIndex]);
+
+  // Redraw the visible range whenever scroll / size / sheet changes.
+  useEffect(() => {
+    const api = apiRef.current;
+    const wb = state.workbook;
+    const canvas = canvasRef.current;
+    if (!api || !wb || !layout || !canvas || viewport.w === 0 || viewport.h === 0) return;
+    const s = wb.sheets[sheetIndex];
+    if (!s) return;
+    const dpr = window.devicePixelRatio || 1;
+    // Resize only when the viewport actually changes — assigning width/height
+    // reallocates (and clears) the backing store, so doing it per scroll frame
+    // is wasteful. On scroll the size is unchanged; drawSpreadsheet clears via
+    // its own full-viewport fillRect, so a plain redraw suffices.
+    const wPx = Math.round(viewport.w * dpr);
+    const hPx = Math.round(viewport.h * dpr);
+    if (canvas.width !== wPx) canvas.width = wPx;
+    if (canvas.height !== hPx) canvas.height = hPx;
+    const ctx = canvas.getContext("2d");
+    if (!ctx) return;
+
+    const mergedCells: MergedCellRange[] = s.mergedCells.map((ref) => {
+      const [a, b] = ref.split(":");
+      const start = api.refToRowCol(a ?? "");
+      const end = api.refToRowCol(b ?? a ?? "");
+      return {
+        startRow: start?.row ?? 1,
+        startCol: start?.col ?? 1,
+        endRow: end?.row ?? start?.row ?? 1,
+        endCol: end?.col ?? start?.col ?? 1,
+      };
+    });
+
+    const config: RenderConfig = {
+      layout,
+      scrollX: scroll.x,
+      scrollY: scroll.y,
+      viewWidth: viewport.w,
+      viewHeight: viewport.h,
+      devicePixelRatio: dpr,
+      getCell: (row, col) => {
+        const cell = s.getCell(api.rowColToRef(row, col));
+        if (!cell) return undefined;
+        return {
+          displayValue: cell.displayValue,
+          style: wb.styles.get(cell.styleIndex),
+          richText: cell.richText,
+          isHyperlink: s.hyperlinks.has(api.rowColToRef(row, col)) || undefined,
+        };
+      },
+      mergedCells,
+      freeze: s.freeze,
+      showGridLines: s.view.showGridLines,
+      images: s.images,
+      charts: s.charts,
+      drawings: s.drawings,
+      richText: (row, col) => s.getCell(api.rowColToRef(row, col))?.richText,
+    };
+    api.drawSpreadsheet(ctx, config);
+  }, [state.workbook, sheetIndex, layout, viewport, scroll]);
+
+  if (state.loading) {
+    return (
+      <View style={styles.center}>
+        <Text size="sm" color="muted">
+          …
+        </Text>
+      </View>
+    );
+  }
+  if (state.error !== undefined || !state.workbook) {
+    return (
+      <View style={styles.center}>
+        <Text size="sm" color="muted">
+          {state.error ?? labels.loadFailed}
+        </Text>
+        <View style={{ marginTop: 12 }}>
+          <Button
+            icon="download"
+            title={labels.download}
+            color="secondary"
+            onPress={() => void downloadFileFromUrl(file.url, file.filename)}
+          />
+        </View>
+      </View>
+    );
+  }
+
+  const sheets = state.workbook.sheets;
+  const totalWidth = layout?.totalWidth ?? 0;
+  const totalHeight = layout?.totalHeight ?? 0;
+
+  return (
+    <View style={styles.container}>
+      <div style={viewportStyle} ref={viewportRef}>
+        <canvas ref={canvasRef} style={{ ...canvasStyle, width: viewport.w, height: viewport.h }} />
+        <div ref={scrollRef} onScroll={onScroll} style={scrollLayerStyle}>
+          <div style={{ width: totalWidth, height: totalHeight }} />
+        </div>
+      </div>
+      {sheets.length > 1 ? (
+        <View style={styles.tabs}>
+          {sheets.map((s, i) => (
+            <Pressable
+              key={i}
+              accessibilityRole="tab"
+              accessibilityState={{ selected: i === sheetIndex }}
+              onPress={() => {
+                setSheetIndex(i);
+                setScroll({ x: 0, y: 0 });
+                if (scrollRef.current) scrollRef.current.scrollTo({ left: 0, top: 0 });
+              }}
+              style={[styles.tab, i === sheetIndex ? styles.tabActive : null]}
+            >
+              <Text size="xs" color={i === sheetIndex ? "default" : "muted"} numberOfLines={1}>
+                {s.name}
+              </Text>
+            </Pressable>
+          ))}
+        </View>
+      ) : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: { flex: 1 },
+  center: { flex: 1, justifyContent: "center", alignItems: "center", padding: 48 },
+  tabs: {
+    flexDirection: "row",
+    borderTopWidth: 1,
+    borderTopColor: colors.border,
+    backgroundColor: colors.zinc[50],
+  },
+  tab: { paddingHorizontal: 14, paddingVertical: 8, borderRightWidth: 1, borderRightColor: colors.border },
+  tabActive: { backgroundColor: colors.background },
+});
+
+const viewportStyle: React.CSSProperties = { position: "relative", flex: 1, overflow: "hidden" };
+const canvasStyle: React.CSSProperties = { position: "absolute", top: 0, left: 0 };
+const scrollLayerStyle: React.CSSProperties = { position: "absolute", inset: 0, overflow: "auto" };

package/src/table.tsx

@@ -1,19 +1,40 @@
-import { ScrollView, View, ViewStyle, StyleSheet } from "react-native";
+import { Pressable, ScrollView, View, ViewStyle, StyleSheet } from "react-native";
 import { Text } from "@lotics/ui/text";
 import { ReactNode } from "react";
 import { colors } from "@lotics/ui/colors";
 
+export type SortDir = "asc" | "desc";
+export interface TableSort<TRow extends Record<string, unknown>> {
+  key: keyof TRow;
+  dir: SortDir;
+}
+
 interface TableProps<TRow extends Record<string, unknown>> {
   columns: Column<TRow>[];
   rows: (TRow | null | false)[];
   rowKey?: keyof TRow;
   rowStyle?: (row: TRow) => ViewStyle | undefined;
+  /** Current sort. Pair with `onSortChange` to render sortable headers. The
+   *  parent owns the actual sorting of `rows` — this only drives the indicator. */
+  sort?: TableSort<TRow> | null;
+  /** Pressing a `sortable` header calls this with the column key (the parent
+   *  toggles asc/desc and re-sorts `rows`). */
+  onSortChange?: (key: keyof TRow) => void;
+  /** Pressing a row calls this — e.g. to open a detail drilldown. The row
+   *  becomes a Pressable with a hover/press surface. Interactive cells nested
+   *  inside (Pressables/buttons) capture their own press and don't bubble. */
+  onRowPress?: (row: TRow) => void;
 }
 
 interface Column<TRow extends Record<string, unknown>> {
   key: keyof TRow;
   label: string;
   width?: number;
+  /** Horizontal alignment of header + cell content. Default "left". */
+  align?: "left" | "right";
+  /** When true (and `onSortChange` is set), the header is pressable + shows a
+   *  sort arrow when this column is the active `sort`. */
+  sortable?: boolean;
   renderCell?: RenderCell<TRow>;
 }
 
@@ -25,48 +46,80 @@ type RenderCell<TRow extends Record<string, unknown>> = (params: {
 const stickyHeader = [0];
 
 export function Table<TRow extends Record<string, unknown>>(props: TableProps<TRow>) {
-  const { columns, rows, rowKey, rowStyle } = props;
+  const { columns, rows, rowKey, rowStyle, sort, onSortChange, onRowPress } = props;
 
   return (
     <ScrollView style={styles.container} stickyHeaderIndices={stickyHeader}>
       <View style={styles.headerRow}>
-        {columns.map((column) => (
+        {columns.map((column) => {
+          const sortable = column.sortable && !!onSortChange;
+          const active = sort?.key === column.key;
+          const cellStyle = [
+            column.width ? { width: column.width } : styles.flexColumn,
+            styles.headerCell,
+            column.align === "right" ? styles.alignEnd : null,
+          ];
+          const inner = (
+            <View style={styles.headerInner}>
+              <Text weight="medium" numberOfLines={1} userSelect="none">
+                {column.label}
+              </Text>
+              {sortable ? (
+                <Text size="xs" color="muted" userSelect="none">
+                  {active ? (sort?.dir === "asc" ? "↑" : "↓") : "↕"}
+                </Text>
+              ) : null}
+            </View>
+          );
+          return sortable ? (
+            <Pressable
+              key={column.key as string}
+              accessibilityRole="button"
+              accessibilityLabel={`Sắp xếp theo ${column.label}`}
+              onPress={() => onSortChange?.(column.key)}
+              style={cellStyle}
+            >
+              {inner}
+            </Pressable>
+          ) : (
+            <View key={column.key as string} style={cellStyle}>
+              {inner}
+            </View>
+          );
+        })}
+      </View>
+      {rows.filter(Boolean).map((r, i) => {
+        const row = r as TRow;
+        const extraStyle = rowStyle?.(row);
+        const cells = columns.map((column) => (
           <View
+            key={column.key as string}
             style={[
               column.width ? { width: column.width } : styles.flexColumn,
-              styles.headerCell,
+              styles.bodyCell,
+              column.align === "right" ? styles.alignEnd : null,
             ]}
-            key={column.key as string}
           >
-            <Text weight="medium" numberOfLines={1} userSelect="none">
-              {column.label}
-            </Text>
+            {column.renderCell ? (
+              column.renderCell({ row, column })
+            ) : (
+              <Text numberOfLines={1}>{row[column.key]?.toString()}</Text>
+            )}
           </View>
-        ))}
-      </View>
-      {rows.filter(Boolean).map((r, i) => {
-        const row = r as TRow;
-        const extraStyle = rowStyle?.(row);
-        return (
-          <View
-            key={rowKey ? String(row[rowKey]) : i}
-            style={[styles.bodyRow, extraStyle]}
+        ));
+        const key = rowKey ? String(row[rowKey]) : i;
+        return onRowPress ? (
+          <Pressable
+            key={key}
+            accessibilityRole="button"
+            onPress={() => onRowPress(row)}
+            style={({ pressed }) => [styles.bodyRow, pressed ? styles.rowPressed : null, extraStyle]}
           >
-            {columns.map((column) => (
-              <View
-                key={column.key as string}
-                style={[
-                  column.width ? { width: column.width } : styles.flexColumn,
-                  styles.bodyCell,
-                ]}
-              >
-                {column.renderCell ? (
-                  column.renderCell({ row, column })
-                ) : (
-                  <Text numberOfLines={1}>{row[column.key]?.toString()}</Text>
-                )}
-              </View>
-            ))}
+            {cells}
+          </Pressable>
+        ) : (
+          <View key={key} style={[styles.bodyRow, extraStyle]}>
+            {cells}
           </View>
         );
       })}
@@ -86,19 +139,35 @@ const styles = StyleSheet.create({
     backgroundColor: colors.zinc[50],
   },
   headerCell: {
-    height: 44,
+    minHeight: 40,
     justifyContent: "center",
-    paddingHorizontal: 8,
+    paddingHorizontal: 12,
+    paddingVertical: 10,
   },
-bodyRow: {
+  headerInner: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 4,
+  },
+  bodyRow: {
     flexDirection: "row",
     borderBottomWidth: 1,
     borderBottomColor: colors.border,
+    alignItems: "stretch",
+  },
+  rowPressed: {
+    backgroundColor: colors.zinc[50],
   },
+  // No fixed height — the row sizes to its content + vertical padding, so rich
+  // cells (avatar chips, buttons, stacked badges) get room instead of squeezing.
   bodyCell: {
     minHeight: 44,
     justifyContent: "center",
-    paddingHorizontal: 8,
+    paddingHorizontal: 12,
+    paddingVertical: 12,
+  },
+  alignEnd: {
+    alignItems: "flex-end",
   },
   flexColumn: {
     flex: 1,