@lotics/ui 1.14.0 → 1.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "1.14.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/menu_list_item.tsx

@@ -1,6 +1,7 @@
 import { Ref } from "react";
 import { StyleProp, StyleSheet, View, ViewStyle } from "react-native";
 import { Text } from "./text";
+import { colors } from "./colors";
 import { Icon, IconName } from "./icon";
 import { PressableHighlight } from "./pressable_highlight";
 
@@ -11,13 +12,38 @@ export interface MenuListItemProps {
   description?: string;
   right?: React.ReactNode;
   onPress?: () => void;
+  onHoverIn?: () => void;
+  /** Persistent selection highlight (e.g. the current value in a listbox). */
+  selected?: boolean;
+  /** Roving keyboard highlight, driven by the controlling input via
+   *  `aria-activedescendant`. Distinct from `selected`. */
+  focused?: boolean;
   disabled?: boolean;
   style?: StyleProp<ViewStyle>;
   testID?: string;
+  /** DOM id, referenced by a combobox input's `aria-activedescendant`. */
+  nativeID?: string;
+  /** ARIA role. Defaults to `button`; pass `option` for a listbox row. */
+  role?: "menuitem" | "button" | "option";
 }
 
 export function MenuListItem(props: MenuListItemProps) {
-  const { ref, icon, title, description, right, onPress, disabled, style, testID } = props;
+  const {
+    ref,
+    icon,
+    title,
+    description,
+    right,
+    onPress,
+    onHoverIn,
+    selected,
+    focused,
+    disabled,
+    style,
+    testID,
+    nativeID,
+    role = "button",
+  } = props;
 
   const resolvedIcon =
     typeof icon === "string" ? <Icon size={20} name={icon as IconName} /> : icon;
@@ -39,18 +65,26 @@ export function MenuListItem(props: MenuListItemProps) {
     </>
   );
 
-  const containerStyle = [styles.container, style];
+  const containerStyle = [
+    styles.container,
+    selected && styles.selected,
+    focused && !selected && styles.focused,
+    style,
+  ];
 
   if (onPress) {
     return (
       <PressableHighlight
         ref={ref}
         testID={testID}
+        nativeID={nativeID}
         onPress={onPress}
+        onHoverIn={onHoverIn}
         disabled={disabled}
         style={containerStyle}
-        accessibilityRole="button"
+        role={role}
         accessibilityLabel={description ? `${title}, ${description}` : title}
+        aria-selected={selected || undefined}
         aria-disabled={disabled || undefined}
       >
         {inner}
@@ -79,4 +113,10 @@ const styles = StyleSheet.create({
     gap: 2,
     alignItems: "flex-start",
   },
+  selected: {
+    backgroundColor: colors.zinc["100"],
+  },
+  focused: {
+    backgroundColor: colors.zinc["50"],
+  },
 });