@lotics/ui 15.0.0 → 15.1.1

package/src/file_intake.ts

@@ -0,0 +1,148 @@
+// File INTAKE — the shared core behind every "a file arrived" path in the kit:
+// what counts as an acceptable file, and how to read files off a drag-drop or a
+// clipboard paste. Both payloads are a `DataTransfer`, so ONE extractor serves
+// the `drop` and the `paste` event; `FileDropzone`, `FileDropTarget` and
+// `usePasteFiles` all route through it and can never drift apart.
+//
+// Also the shared CONTRACT module for the two platform-split primitives
+// (`use_paste_files` / `file_drop_target`): their option and prop shapes live
+// here so the `.web` implementation and its native sibling declare them once.
+//
+// No react-native import — the components render this module's result, so the
+// logic stays unit-testable (Vitest cannot parse `react-native`).
+
+import type { ReactNode } from "react";
+import type { StyleProp, ViewStyle } from "react-native";
+
+/** The filter every intake path applies to what arrived. */
+export interface FileIntakeFilter {
+  /** Native `accept` filter (e.g. `"application/pdf,image/*"`) — matched against
+   *  the file's MIME type, or its extension for a `.ext` pattern. */
+  accept?: string;
+  /** Keep more than one file. Default true. */
+  multiple?: boolean;
+}
+
+/**
+ * The structural shape a `DataTransfer` satisfies — `DragEvent.dataTransfer`
+ * (a drop) and `ClipboardEvent.clipboardData` (a paste) are the same object.
+ * Declared structurally so the extractor is testable without a DOM.
+ */
+export interface FileTransferLike {
+  readonly files?: ArrayLike<File> | null;
+  readonly items?: ArrayLike<{ readonly kind: string; getAsFile: () => File | null }> | null;
+}
+
+/** The minimal ref shape `usePasteFiles`/`FileDropTarget` need to locate a
+ *  region — an RN `View` ref satisfies it (`useRef<View>(null)`); on web its
+ *  `.current` IS the region's DOM node. Declared structurally (readonly, so an
+ *  `RefObject<View | null>` assigns cleanly) to keep this module RN-free. */
+export interface RegionRef {
+  readonly current: unknown;
+}
+
+/** Options for `usePasteFiles` (`@lotics/ui/use_paste_files`). */
+export interface UsePasteFilesOptions extends FileIntakeFilter {
+  /** Receives the pasted files. Bytes/upload belong to the host. */
+  onFiles: (files: File[]) => void;
+  /** Subscribe only while true (default true) — scope the sink to "while this
+   *  surface is open" so a background screen never swallows a paste. */
+  enabled?: boolean;
+  /** The region this sink belongs to. When the paste happens while focus is
+   *  INSIDE this region, this sink wins over a later-mounted one (see
+   *  `selectPasteSink`). Omit for a region-less surface (a modal dialog) — the
+   *  sink then participates by stack order alone. */
+  region?: RegionRef;
+}
+
+/** Props for `FileDropTarget` (`@lotics/ui/file_drop_target`). */
+export interface FileDropTargetProps extends FileIntakeFilter {
+  /** Receives the dropped files. */
+  onFiles: (files: File[]) => void;
+  /** Also accept a clipboard PASTE, scoped to this region's focus: while focus
+   *  is inside the wrapped region, Ctrl/Cmd+V lands here. Wires `usePasteFiles`
+   *  with this region — so two peer file sections each win when focus is in
+   *  them, instead of the last-mounted one silently grabbing every paste. */
+  paste?: boolean;
+  /** Stop accepting drops/pastes (and drop the affordance). */
+  disabled?: boolean;
+  /**
+   * The region. A plain node lets the target paint the drag affordance itself;
+   * a FUNCTION receives the drag state and OWNS the visual (the target paints
+   * nothing) — how `FileDropzone` keeps its own well styling.
+   */
+  children: ReactNode | ((dragging: boolean) => ReactNode);
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * Does a file pass a native `accept` list? Each comma-separated pattern is an
+ * extension (`.pdf`), a wildcard type (`image/*`) or an exact MIME
+ * (`application/pdf`); an empty/absent list accepts everything.
+ */
+export function matchesAccept(file: File, accept: string | undefined): boolean {
+  if (!accept) return true;
+  const patterns = accept.split(",").map((p) => p.trim().toLowerCase()).filter(Boolean);
+  if (patterns.length === 0) return true;
+  const mime = file.type.toLowerCase();
+  const name = file.name.toLowerCase();
+  return patterns.some((p) => {
+    if (p.startsWith(".")) return name.endsWith(p);
+    if (p.endsWith("/*")) return mime.startsWith(p.slice(0, -1));
+    return mime === p;
+  });
+}
+
+/**
+ * The files a drop or a paste carries, filtered by `accept` and capped by
+ * `multiple`. Returns a new array; never throws on a missing/empty transfer.
+ */
+export function filesFromTransfer(
+  transfer: FileTransferLike | null | undefined,
+  filter: FileIntakeFilter = {},
+): File[] {
+  if (!transfer) return [];
+  // `files` carries a drop and most pastes. A pasted SCREENSHOT reaches some
+  // engines only through `items` (a `kind: "file"` entry), so fall back to it —
+  // never union the two, or an engine that populates both doubles every file.
+  const direct = transfer.files ? Array.from(transfer.files) : [];
+  const candidates =
+    direct.length > 0
+      ? direct
+      : Array.from(transfer.items ?? [])
+          .filter((item) => item.kind === "file")
+          .map((item) => item.getAsFile())
+          .filter((file): file is File => file !== null);
+
+  const accepted = candidates.filter((file) => matchesAccept(file, filter.accept));
+  return filter.multiple === false ? accepted.slice(0, 1) : accepted;
+}
+
+/** One registered paste sink for the routing decision: the payload to hand the
+ *  paste to, and whether its region currently contains focus. */
+export interface PasteSinkEntry<T> {
+  sink: T;
+  /** True when `document.activeElement` is inside this sink's region. A
+   *  region-less sink (a modal dialog) is always false — it routes by stack
+   *  order alone. */
+  focused: boolean;
+}
+
+/**
+ * Which sink gets the paste, given the active sinks in MOUNT order (oldest
+ * first, top of the stack last). The rule: the TOP-MOST focused region wins —
+ * so when two file targets are enabled on the same layer, the one the user is
+ * actually working in takes the file. With NO region focused it falls back to
+ * the top of the stack (the last-mounted surface), which is the right default
+ * for modal stacking (a dialog over a screen). Returns `undefined` for an empty
+ * stack.
+ *
+ * Pure so the DOM-free routing rule is unit-tested here; the `focused` flags are
+ * computed against live focus in the `.web` sink at dispatch time.
+ */
+export function selectPasteSink<T>(entries: readonly PasteSinkEntry<T>[]): T | undefined {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    if (entries[i].focused) return entries[i].sink;
+  }
+  return entries.length > 0 ? entries[entries.length - 1].sink : undefined;
+}

package/src/locale.tsx

@@ -230,7 +230,7 @@ export const en: LoticsLocale = {
   chart: { noData: "No data", total: "Total" },
   composer: { send: "Send", stop: "Stop" },
   overlay: { close: "Close" },
-  fileDropzone: { label: "Drag files here", hint: "or click to browse", drop: "Drop to upload" },
+  fileDropzone: { label: "Drag files here", hint: "or click, or paste (⌘V)", drop: "Drop to upload" },
   fileThumbnail: { remove: "Remove" },
   imageGallery: { empty: "No images.", rotateLeft: "Rotate left", rotateRight: "Rotate right", zoom: "Zoom image" },
   infoPopover: { more: "More information" },
@@ -328,7 +328,7 @@ export const vi: LoticsLocale = {
   chart: { noData: "Không có dữ liệu", total: "Tổng" },
   composer: { send: "Gửi", stop: "Dừng" },
   overlay: { close: "Đóng" },
-  fileDropzone: { label: "Kéo tệp vào đây", hint: "hoặc bấm để chọn", drop: "Thả để tải lên" },
+  fileDropzone: { label: "Kéo tệp vào đây", hint: "hoặc bấm chọn, hoặc dán (Ctrl+V)", drop: "Thả để tải lên" },
   fileThumbnail: { remove: "Xóa" },
   imageGallery: { empty: "Chưa có ảnh.", rotateLeft: "Xoay trái", rotateRight: "Xoay phải", zoom: "Phóng to ảnh" },
   infoPopover: { more: "Thông tin thêm" },

package/src/use_paste_files.ts

@@ -0,0 +1,14 @@
+import type { UsePasteFilesOptions } from "./file_intake";
+
+/**
+ * Native stand-in for the web clipboard sink.
+ *
+ * There is no document-level `paste` event on React Native — the OS clipboard is
+ * read imperatively — so the hook is a no-op and the surface's own Add-file CTA
+ * stays the intake path. The file exists so a shared screen can call
+ * `usePasteFiles` unconditionally without the DOM code ever reaching Metro.
+ *
+ * Web targets resolve `use_paste_files.web.ts` instead (Metro's `.web` extension
+ * resolution; the package's `react-native` export condition).
+ */
+export function usePasteFiles(_options: UsePasteFilesOptions): void {}

package/src/use_paste_files.web.ts

@@ -0,0 +1,101 @@
+import { useEffect, useRef } from "react";
+import { filesFromTransfer, selectPasteSink, type UsePasteFilesOptions } from "./file_intake";
+import { resolveRegionNode } from "./dom_region";
+
+/**
+ * Web variant: the document-level clipboard sink. Isolated into its own module
+ * so the native bundle (which resolves `use_paste_files.ts`) never references
+ * the DOM.
+ */
+
+type PasteSink = (event: ClipboardEvent) => void;
+
+interface RegisteredSink {
+  sink: PasteSink;
+  /** Evaluated at dispatch time: does this sink's region contain focus? A
+   *  region-less sink is always false — it routes by stack order alone. */
+  hasFocusWithin: () => boolean;
+}
+
+/**
+ * The active sinks, most recently subscribed LAST, behind ONE document listener.
+ * A paste is routed by `selectPasteSink`: the TOP-MOST sink whose region holds
+ * focus wins (so two file targets on one layer each take the paste when the user
+ * is working in them), else the top of the stack (right for modal stacking — a
+ * dialog over a screen).
+ */
+const sinks: RegisteredSink[] = [];
+let listening = false;
+
+function dispatch(event: ClipboardEvent) {
+  // An inner handler (a composer with its own attach path) already claimed it.
+  if (event.defaultPrevented) return;
+  const chosen = selectPasteSink(
+    sinks.map((registered) => ({ sink: registered.sink, focused: registered.hasFocusWithin() })),
+  );
+  chosen?.(event);
+}
+
+function pushSink(registered: RegisteredSink): () => void {
+  sinks.push(registered);
+  if (!listening) {
+    document.addEventListener("paste", dispatch);
+    listening = true;
+  }
+  return () => {
+    const index = sinks.lastIndexOf(registered);
+    if (index >= 0) sinks.splice(index, 1);
+    if (sinks.length === 0 && listening) {
+      document.removeEventListener("paste", dispatch);
+      listening = false;
+    }
+  };
+}
+
+/**
+ * Ctrl/Cmd+V adds files — the paste half of file intake, alongside the drop
+ * (`FileDropTarget` / `FileDropzone`) and the pick (`pickFiles`). Reads whatever
+ * the clipboard carries (a copied file, or a screenshot, which some engines
+ * surface only through `clipboardData.items`), filters it by `accept`, and hands
+ * it to `onFiles`.
+ *
+ * Scope it with `enabled` so only the open surface listens. Pass `region` (the
+ * ref of the surface's DOM region) to route by FOCUS: when the paste fires while
+ * focus is inside this region, this sink wins over a later-mounted one — so two
+ * peer file sections each take the paste when the user is in them. Without a
+ * region it routes by stack order (the modal-stacking default). A paste carrying
+ * NO acceptable file is left entirely alone — typing Ctrl+V in a text field
+ * still pastes text.
+ */
+export function usePasteFiles(options: UsePasteFilesOptions): void {
+  const { onFiles, accept, multiple = true, enabled = true, region } = options;
+
+  // Read through a ref so the sink subscribes ONCE per enabled window. Keying
+  // the effect on `onFiles` instead would re-push on every parent render —
+  // routine with an inline callback — and a background surface re-rendering
+  // would jump the stack and steal the next paste.
+  const latest = useRef({ onFiles, accept, multiple, region });
+  useEffect(() => {
+    latest.current = { onFiles, accept, multiple, region };
+  });
+
+  useEffect(() => {
+    if (!enabled) return;
+    if (typeof document === "undefined") return;
+    return pushSink({
+      hasFocusWithin: () => {
+        const node = resolveRegionNode(latest.current.region);
+        return node !== null && node.contains(document.activeElement);
+      },
+      sink: (event) => {
+        const settings = latest.current;
+        const files = filesFromTransfer(event.clipboardData, settings);
+        if (files.length === 0) return;
+        // Claim ONLY the paste actually consumed, so a text paste stays the
+        // browser's (and the focused input's) to handle.
+        event.preventDefault();
+        settings.onFiles(files);
+      },
+    });
+  }, [enabled]);
+}