@multiplatform.one/frappe-ui 7.4.1 → 7.5.0

package/src/FileBrowser/FileBrowser.spec.tsx

@@ -0,0 +1,268 @@
+import { fireEvent, screen } from "@testing-library/react";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { describe, expect, it, vi } from "vitest";
+import { getFieldComponent } from "../fieldRegistry";
+import { FileBrowser } from "./index";
+import type { FileBrowserFile } from "./types";
+import { readPersistedView } from "./viewPersistence";
+
+const FIXTURE: FileBrowserFile[] = [
+  { name: "Home", file_name: "Home", folder: "", is_folder: 1 },
+  { name: "Home/Invoices", file_name: "Invoices", folder: "Home", is_folder: 1 },
+  {
+    name: "inv-1",
+    file_name: "invoice.pdf",
+    folder: "Home/Invoices",
+    file_size: 72400,
+    file_type: "pdf",
+    file_url: "/files/invoice.pdf",
+    modified: "2026-08-12",
+  },
+  {
+    name: "img-1",
+    file_name: "topology.png",
+    folder: "Home/Invoices",
+    file_size: 612000,
+    file_type: "png",
+    file_url: "/files/topology.png",
+    modified: "2026-08-09",
+  },
+];
+
+function folderState(container: HTMLElement) {
+  return container
+    .querySelector("[data-filebrowser-folders-state]")
+    ?.getAttribute("data-filebrowser-folders-state");
+}
+
+function filesState(container: HTMLElement) {
+  return container
+    .querySelector("[data-filebrowser-files-state]")
+    ?.getAttribute("data-filebrowser-files-state");
+}
+
+describe("FileBrowser panes — four states (DG-TBL-06)", () => {
+  it("folders pane: ready, loading, empty, error", () => {
+    const { container, rerender } = renderWithProviders(
+      <FileBrowser files={FIXTURE} layout="split" currentFolder="Home/Invoices" />,
+    );
+    expect(folderState(container)).toBe("ready");
+
+    rerender(
+      <FileBrowser
+        files={FIXTURE}
+        layout="split"
+        currentFolder="Home/Invoices"
+        foldersStatus="loading"
+      />,
+    );
+    expect(folderState(container)).toBe("loading");
+
+    rerender(
+      <FileBrowser
+        files={FIXTURE}
+        layout="split"
+        currentFolder="Home/Invoices"
+        foldersStatus="empty"
+      />,
+    );
+    expect(folderState(container)).toBe("empty");
+    expect(screen.getByText("No folders")).toBeTruthy();
+
+    rerender(
+      <FileBrowser
+        files={FIXTURE}
+        layout="split"
+        currentFolder="Home/Invoices"
+        foldersStatus="error"
+        foldersError="timed out"
+      />,
+    );
+    expect(folderState(container)).toBe("error");
+    expect(screen.getByText("Couldn't load folders")).toBeTruthy();
+  });
+
+  it("files pane: ready, loading, empty, error", () => {
+    const { container, rerender } = renderWithProviders(
+      <FileBrowser files={FIXTURE} layout="split" currentFolder="Home/Invoices" />,
+    );
+    expect(filesState(container)).toBe("ready");
+
+    rerender(
+      <FileBrowser
+        files={FIXTURE}
+        layout="split"
+        currentFolder="Home/Invoices"
+        filesStatus="loading"
+      />,
+    );
+    expect(filesState(container)).toBe("loading");
+
+    rerender(
+      <FileBrowser
+        files={FIXTURE}
+        layout="split"
+        currentFolder="Home/Invoices"
+        filesStatus="empty"
+      />,
+    );
+    expect(filesState(container)).toBe("empty");
+    expect(screen.getByText("No files")).toBeTruthy();
+
+    rerender(
+      <FileBrowser
+        files={FIXTURE}
+        layout="split"
+        currentFolder="Home/Invoices"
+        filesStatus="error"
+        filesError="timed out"
+      />,
+    );
+    expect(filesState(container)).toBe("error");
+    expect(screen.getByText("Couldn't load files")).toBeTruthy();
+  });
+
+  it("empty and error are visually distinct (DG-ST-01)", () => {
+    const { container, rerender } = renderWithProviders(
+      <FileBrowser
+        files={FIXTURE}
+        layout="split"
+        currentFolder="Home/Invoices"
+        foldersStatus="empty"
+        filesStatus="empty"
+      />,
+    );
+    expect(container.querySelectorAll('[data-async-state="empty"]').length).toBeGreaterThan(0);
+    expect(container.querySelector('[data-async-state="error"]')).toBeNull();
+    expect(screen.queryByText("Couldn't load folders")).toBeNull();
+    expect(screen.queryByText("Couldn't load files")).toBeNull();
+
+    rerender(
+      <FileBrowser
+        files={FIXTURE}
+        layout="split"
+        currentFolder="Home/Invoices"
+        foldersStatus="error"
+        filesStatus="error"
+        foldersError
+        filesError
+      />,
+    );
+    expect(container.querySelectorAll('[data-async-state="error"]').length).toBeGreaterThan(0);
+    expect(screen.getByText("Couldn't load folders")).toBeTruthy();
+    expect(screen.getByText("Couldn't load files")).toBeTruthy();
+    expect(screen.queryByText("No folders")).toBeNull();
+    expect(screen.queryByText("No files")).toBeNull();
+  });
+});
+
+describe("FileBrowser grid skeleton (LC-20)", () => {
+  it("renders the skeleton at the grid's mediaAspect", () => {
+    const { container } = renderWithProviders(
+      <FileBrowser
+        files={FIXTURE}
+        layout="split"
+        currentFolder="Home/Invoices"
+        view="grid"
+        filesStatus="loading"
+        mediaAspect="photo"
+        tileSize="md"
+      />,
+    );
+    const skeleton = container.querySelector("[data-async-skeleton='image-grid']");
+    expect(skeleton).toBeTruthy();
+    expect(skeleton?.getAttribute("data-media-aspect")).not.toBeNull();
+    expect(Number(skeleton?.getAttribute("data-media-aspect"))).not.toBe(1);
+    expect(container.querySelector("[data-filebrowser-tile-size='md']")).toBeTruthy();
+  });
+});
+
+describe("FileBrowser composition", () => {
+  it("keeps folders in the tree and files out of it", () => {
+    const { container } = renderWithProviders(
+      <FileBrowser files={FIXTURE} layout="split" currentFolder="Home/Invoices" />,
+    );
+    const tree = container.querySelector("[data-filebrowser-folders]");
+    expect(tree?.textContent).toContain("Invoices");
+    expect(tree?.textContent).not.toContain("invoice.pdf");
+    expect(container.querySelector("[data-filebrowser-files]")?.textContent).toContain(
+      "invoice.pdf",
+    );
+  });
+
+  it("collapses to drill-in without shipping the pointer tree", () => {
+    const { container } = renderWithProviders(
+      <FileBrowser files={FIXTURE} layout="drill" currentFolder="Home/Invoices" />,
+    );
+    expect(container.querySelector("[data-filebrowser-layout='drill']")).toBeTruthy();
+    expect(container.querySelector("[data-filebrowser-folders] [role='tree']")).toBeNull();
+    expect(container.querySelector("[data-filebrowser-back]")).toBeTruthy();
+  });
+
+  it("multi-select shows checkboxes; Attach pick mode does not", () => {
+    const { container, rerender } = renderWithProviders(
+      <FileBrowser
+        files={FIXTURE}
+        layout="split"
+        currentFolder="Home/Invoices"
+        selectionMode="multi"
+      />,
+    );
+    expect(container.querySelector("[data-filebrowser-selection='multi']")).toBeTruthy();
+    expect(container.querySelectorAll('[role="checkbox"]').length).toBeGreaterThan(0);
+
+    rerender(
+      <FileBrowser
+        files={FIXTURE}
+        layout="split"
+        currentFolder="Home/Invoices"
+        selectionMode="single"
+        currentValue="/files/invoice.pdf"
+      />,
+    );
+    expect(container.querySelector("[data-filebrowser-selection='single']")).toBeTruthy();
+    expect(container.querySelectorAll('[role="checkbox"]').length).toBe(0);
+  });
+
+  it("persists view per surface and uses the tileSize rung, never a column literal", () => {
+    const onViewChange = vi.fn();
+    const { container } = renderWithProviders(
+      <FileBrowser
+        files={FIXTURE}
+        layout="split"
+        currentFolder="Home/Invoices"
+        surfaceId="desk-files"
+        defaultView="list"
+        onViewChange={onViewChange}
+        tileSize="lg"
+      />,
+    );
+    expect(container.querySelector("[data-filebrowser-view='list']")).toBeTruthy();
+    fireEvent.click(screen.getByRole("button", { name: "Grid" }));
+    expect(onViewChange).toHaveBeenCalledWith("grid");
+    expect(readPersistedView("desk-files")).toBe("grid");
+    expect(container.querySelector("[data-filebrowser-tile-size='lg']")).toBeTruthy();
+    expect(container.querySelector("[data-filebrowser-tile-size='280']")).toBeNull();
+  });
+});
+
+describe("Attach choose-from-library tab", () => {
+  it("serves FileBrowser as Attach's library tab", async () => {
+    const AttachField = getFieldComponent("Attach")!;
+    const onChange = vi.fn();
+    renderWithProviders(
+      <AttachField
+        label="Attachment"
+        value={null}
+        onChange={onChange}
+        libraryFiles={FIXTURE}
+        libraryFolder="Home/Invoices"
+      />,
+    );
+    expect(screen.getByText(/Choose File/i)).toBeTruthy();
+    fireEvent.click(screen.getByRole("button", { name: /From Library/i }));
+    expect(screen.getByRole("tab", { name: /From library/i })).toBeTruthy();
+    expect(document.querySelector("[data-filebrowser-selection='single']")).toBeTruthy();
+    expect(document.querySelectorAll("[data-filebrowser] [role='checkbox']").length).toBe(0);
+  });
+});

package/src/FileBrowser/FileBrowser.stories.tsx

@@ -0,0 +1,93 @@
+import { YStack } from "tamagui";
+import { FileBrowser } from ".";
+import type { FileBrowserFile } from "./types";
+
+const files: FileBrowserFile[] = [
+  { name: "Home", file_name: "Home", folder: "", is_folder: 1 },
+  { name: "Home/Invoices", file_name: "Invoices", folder: "Home", is_folder: 1 },
+  { name: "Home/Library", file_name: "Library", folder: "Home", is_folder: 1 },
+  {
+    name: "inv-1",
+    file_name: "hetzner-hel1-invoice-aug.pdf",
+    folder: "Home/Invoices",
+    file_size: 72400,
+    file_type: "pdf",
+    file_url: "/files/invoice.pdf",
+    modified: "2026-08-12",
+  },
+  {
+    name: "img-1",
+    file_name: "swarm01-topology.png",
+    folder: "Home/Invoices",
+    file_size: 612000,
+    file_type: "png",
+    file_url: "/files/topology.png",
+    modified: "2026-08-09",
+  },
+];
+
+export default {
+  title: "FrappeUI/FileBrowser",
+  component: FileBrowser,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "File doctype browser: TreeView folders rail + DataTable/ImageGrid files pane. Doubles as Attach's choose-from-library tab.",
+      },
+    },
+  },
+};
+
+export const SplitList = () => (
+  <FileBrowser files={files} layout="split" currentFolder="Home/Invoices" surfaceId="story-split" />
+);
+
+export const SplitGrid = () => (
+  <FileBrowser
+    files={files}
+    layout="split"
+    view="grid"
+    tileSize="md"
+    mediaAspect="square"
+    currentFolder="Home/Invoices"
+    surfaceId="story-grid"
+  />
+);
+
+export const DrillIn = () => (
+  <YStack width={390}>
+    <FileBrowser files={files} layout="drill" currentFolder="Home" surfaceId="story-drill" />
+  </YStack>
+);
+
+export const AttachPick = () => (
+  <FileBrowser
+    files={files}
+    layout="split"
+    selectionMode="single"
+    currentValue="/files/invoice.pdf"
+    currentFolder="Home/Invoices"
+    surfaceId="story-attach"
+  />
+);
+
+export const FourStates = () => (
+  <YStack gap="$4">
+    <FileBrowser
+      files={files}
+      layout="split"
+      currentFolder="Home/Invoices"
+      foldersStatus="loading"
+    />
+    <FileBrowser files={files} layout="split" currentFolder="Home/Invoices" filesStatus="empty" />
+    <FileBrowser
+      files={files}
+      layout="split"
+      currentFolder="Home/Invoices"
+      filesStatus="error"
+      filesError="timed out"
+    />
+  </YStack>
+);

package/src/FileBrowser/folderTree.ts

@@ -0,0 +1,62 @@
+import type { TreeNode } from "@multiplatform.one/components";
+import { buildTreeNodes } from "../FrappeTreeView";
+import type { FileBrowserFile } from "./types";
+
+export function isFolder(file: FileBrowserFile): boolean {
+  return file.is_folder === 1 || file.is_folder === true;
+}
+
+export function folderParent(folder?: string): string {
+  return folder && folder.length > 0 ? folder : "Home";
+}
+
+export function childrenOf(files: FileBrowserFile[], folderName: string): FileBrowserFile[] {
+  return files.filter(
+    (file) => folderParent(file.folder) === folderName && file.name !== folderName,
+  );
+}
+
+export function buildFolderTree(files: FileBrowserFile[]): TreeNode<FileBrowserFile>[] {
+  const folders = files.filter(isFolder).map((file) => ({
+    ...file,
+    name: file.name,
+  }));
+  return buildTreeNodes(folders, "folder", "file_name") as TreeNode<FileBrowserFile>[];
+}
+
+export function breadcrumbItems(folderName: string): { label: string; href: string }[] {
+  const parts = folderName.split("/").filter(Boolean);
+  if (parts.length === 0) return [{ label: "Home", href: "Home" }];
+  return parts.map((label, index) => ({
+    label,
+    href: parts.slice(0, index + 1).join("/"),
+  }));
+}
+
+export function parentFolder(folderName: string): string | undefined {
+  const parts = folderName.split("/").filter(Boolean);
+  if (parts.length <= 1) return undefined;
+  return parts.slice(0, -1).join("/");
+}
+
+/** Ancestor folder ids so TreeView reveals the open folder (not just the root). */
+export function ancestorFolderIds(folderName: string): string[] {
+  const parts = folderName.split("/").filter(Boolean);
+  const ids: string[] = [];
+  for (let i = 1; i < parts.length; i++) {
+    ids.push(parts.slice(0, i).join("/"));
+  }
+  return ids;
+}
+
+export function fileKind(
+  file: FileBrowserFile,
+): "folder" | "image" | "video" | "text" | "zip" | "file" {
+  if (isFolder(file)) return "folder";
+  const type = `${file.file_type ?? ""} ${file.file_name}`.toLowerCase();
+  if (/\.(png|jpe?g|gif|webp|svg|avif)(\b|$)/.test(type) || type.includes("image")) return "image";
+  if (/\.(mp4|mov|webm|mkv)(\b|$)/.test(type) || type.includes("video")) return "video";
+  if (/\.(zip|tar|gz|tgz|rar|7z)(\b|$)/.test(type) || type.includes("zip")) return "zip";
+  if (/\.(pdf|txt|md|csv|json|xml|doc)(\b|$)/.test(type) || type.includes("text")) return "text";
+  return "file";
+}