@tangle-network/ui 11.24.0 → 11.26.0

package/src/files/file-card.tsx

@@ -0,0 +1,210 @@
+/**
+ * FileCard — one file, described: its kind, name, size, date and uploader,
+ * with Download and any actions the host adds. FilePreview shows it for a file
+ * it cannot render inline; a host can show it anywhere a file stands on its own.
+ */
+
+import * as React from "react";
+import {
+  Download,
+  File,
+  FileAudio,
+  FileCode,
+  FileImage,
+  FileJson,
+  FileSpreadsheet,
+  FileText,
+  FileVideo,
+  type LucideIcon,
+} from "lucide-react";
+import { cn } from "../lib/utils";
+import { Button } from "../primitives/button";
+import { IconTile, type IconTileProps } from "../primitives/icon-tile";
+import type { CategoryTone } from "../primitives/tone";
+import { formatBytes } from "../utils/format";
+import { getFormatLabel, resolveFilePreviewKind, type FilePreviewKind } from "./file-format";
+
+/** Who added a file, as a reader of the list should see them. */
+export interface FileUploader {
+  name: string;
+  /** Their relationship to the work, e.g. "Client" or "Attorney". */
+  role?: string;
+}
+
+/** What FileCard and FileList show about one file. */
+export interface FileDetails {
+  filename: string;
+  /** Wins over the extension when choosing the kind, as in FilePreview. */
+  mimeType?: string;
+  /** Size in bytes. */
+  size?: number;
+  /** When the file was added or last changed. */
+  date?: Date | string | number;
+  uploader?: FileUploader;
+}
+
+// File kinds are categories, so each takes a categorical tone and never a
+// status colour: a PDF is not an error. See "Color Roles" in the brand guide.
+const KIND_ICON: Record<FilePreviewKind, { icon: LucideIcon; tone: CategoryTone }> = {
+  pdf: { icon: FileText, tone: "orange" },
+  image: { icon: FileImage, tone: "pink" },
+  video: { icon: FileVideo, tone: "violet" },
+  audio: { icon: FileAudio, tone: "cyan" },
+  csv: { icon: FileSpreadsheet, tone: "lime" },
+  spreadsheet: { icon: FileSpreadsheet, tone: "lime" },
+  code: { icon: FileCode, tone: "blue" },
+  json: { icon: FileJson, tone: "blue" },
+  yaml: { icon: FileCode, tone: "blue" },
+  markdown: { icon: FileText, tone: "teal" },
+  text: { icon: FileText, tone: "teal" },
+  binary: { icon: File, tone: "brown" },
+};
+
+/** The kind's icon on its category tone. Decorative: the filename names the file. */
+export function FileKindTile({
+  filename,
+  mimeType,
+  size = "md",
+  className,
+}: {
+  filename: string;
+  mimeType?: string;
+  size?: IconTileProps["size"];
+  className?: string;
+}) {
+  const { icon: Icon, tone } = KIND_ICON[resolveFilePreviewKind(filename, mimeType)];
+  return <IconTile tone={tone} size={size} icon={<Icon />} className={className} />;
+}
+
+function toDate(value: FileDetails["date"]): Date | undefined {
+  if (value === undefined) return undefined;
+  const date = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(date.getTime()) ? undefined : date;
+}
+
+const DATE_FORMAT = new Intl.DateTimeFormat(undefined, { dateStyle: "medium" });
+
+/**
+ * A dot between facts for the eye, a comma for a screen reader, which would
+ * otherwise read the facts as one run-on word or announce "middle dot".
+ */
+export function FactSeparator() {
+  return (
+    <>
+      <span aria-hidden="true"> · </span>
+      <span className="sr-only">, </span>
+    </>
+  );
+}
+
+/**
+ * The kind, size and date as one muted line, each part only when known.
+ * The date follows the reader's locale, which a server render may not share,
+ * so the element tolerates a hydration difference.
+ */
+export function FileFacts({
+  filename,
+  mimeType,
+  size,
+  date,
+  showKind = false,
+  className,
+}: Pick<FileDetails, "filename" | "mimeType" | "size" | "date"> & {
+  showKind?: boolean;
+  className?: string;
+}) {
+  const parsed = toDate(date);
+  const parts: React.ReactNode[] = [];
+  if (showKind) parts.push(getFormatLabel(resolveFilePreviewKind(filename, mimeType)));
+  if (size !== undefined) parts.push(formatBytes(size));
+  if (parsed) {
+    parts.push(
+      <time key="date" dateTime={parsed.toISOString()} suppressHydrationWarning>
+        {DATE_FORMAT.format(parsed)}
+      </time>,
+    );
+  }
+  if (parts.length === 0) return null;
+  return (
+    <span className={cn("text-xs text-muted-foreground", className)}>
+      {parts.map((part, index) => (
+        <React.Fragment key={index}>
+          {index > 0 && <FactSeparator />}
+          {part}
+        </React.Fragment>
+      ))}
+    </span>
+  );
+}
+
+/** "Dana Ruiz (Client)", or the name alone. */
+export function uploaderLabel(uploader: FileUploader): string {
+  return uploader.role ? `${uploader.name} (${uploader.role})` : uploader.name;
+}
+
+export interface FileCardProps
+  extends FileDetails,
+    Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
+  /** One sentence under the details, such as why there is no preview. */
+  description?: React.ReactNode;
+  /** Adds a Download button. */
+  onDownload?: () => void;
+  /** Further buttons after Download, such as Open or Delete. */
+  actions?: React.ReactNode;
+}
+
+export const FileCard = React.forwardRef<HTMLDivElement, FileCardProps>(
+  (
+    {
+      filename,
+      mimeType,
+      size,
+      date,
+      uploader,
+      description,
+      onDownload,
+      actions,
+      className,
+      ...props
+    },
+    ref,
+  ) => (
+    <div
+      ref={ref}
+      className={cn(
+        "flex min-w-0 flex-col items-center justify-center rounded-[var(--radius-md)] border border-border bg-card px-6 py-12 text-center",
+        className,
+      )}
+      {...props}
+    >
+      <FileKindTile filename={filename} mimeType={mimeType} size="lg" />
+      <p
+        className="mt-3 line-clamp-2 max-w-full text-sm font-medium text-foreground [overflow-wrap:anywhere]"
+        title={filename}
+      >
+        {filename}
+      </p>
+      <FileFacts filename={filename} size={size} date={date} className="mt-1" />
+      {uploader && (
+        <p className="mt-0.5 max-w-full truncate text-xs text-muted-foreground">
+          Uploaded by {uploaderLabel(uploader)}
+        </p>
+      )}
+      {description && (
+        <div className="mt-3 max-w-md text-sm text-muted-foreground">{description}</div>
+      )}
+      {(onDownload || actions) && (
+        <div className="mt-5 flex flex-wrap items-center justify-center gap-2">
+          {onDownload && (
+            <Button type="button" variant="outline" size="sm" onClick={onDownload}>
+              <Download />
+              Download
+            </Button>
+          )}
+          {actions}
+        </div>
+      )}
+    </div>
+  ),
+);
+FileCard.displayName = "FileCard";

package/src/files/file-list.stories.tsx

@@ -0,0 +1,121 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { useState } from "react";
+import { Button } from "../primitives/button";
+import { FileCard } from "./file-card";
+import { FileList, type FileListItem } from "./file-list";
+
+const CASE_FILES: FileListItem[] = [
+  {
+    id: "lease",
+    filename: "Commercial lease — 418 Harbor Street.pdf",
+    size: 2_516_582,
+    date: "2026-09-28T16:20:00Z",
+    uploader: { name: "Dana Ruiz", role: "Client" },
+  },
+  {
+    id: "notice",
+    filename: "Notice of lease termination.pdf",
+    size: 75_955,
+    date: "2026-10-06T09:05:00Z",
+    uploader: { name: "Priya Adeyemi", role: "Attorney" },
+  },
+  {
+    id: "photos",
+    filename: "Rear storage room, water damage.jpg",
+    mimeType: "image/jpeg",
+    size: 3_145_728,
+    date: "2026-08-12T18:42:00Z",
+    uploader: { name: "Dana Ruiz", role: "Client" },
+  },
+  {
+    id: "ledger",
+    filename: "Rent ledger 2023–2026.xlsx",
+    size: 48_640,
+    date: "2026-09-30T11:00:00Z",
+    uploader: { name: "Coastal Property Holdings" },
+  },
+  {
+    id: "estimate",
+    filename: "Contractor estimate.docx",
+    size: 182_000,
+    date: "2026-08-20T14:10:00Z",
+  },
+];
+
+function CaseDocuments() {
+  const [files, setFiles] = useState(CASE_FILES);
+  const [openId, setOpenId] = useState("notice");
+  return (
+    <FileList
+      aria-label="Case documents"
+      files={files}
+      activeId={openId}
+      onOpen={(file) => setOpenId(file.id)}
+      onDownload={() => {}}
+      onDelete={(file) => setFiles((current) => current.filter((item) => item.id !== file.id))}
+      empty="No documents yet. Upload the lease to get started."
+    />
+  );
+}
+
+const meta: Meta<typeof FileList> = {
+  title: "Files/FileList",
+  component: FileList,
+  parameters: { layout: "fullscreen" },
+  decorators: [
+    (Story) => (
+      <div className="min-h-[100dvh] bg-background p-4 text-foreground">
+        <div className="mx-auto max-w-2xl">
+          <Story />
+        </div>
+      </div>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof FileList>;
+
+export const Documents: Story = {
+  name: "Case documents",
+  render: () => <CaseDocuments />,
+};
+
+export const DocumentsLight: Story = {
+  name: "Case documents (light)",
+  globals: { theme: "light" },
+  render: () => <CaseDocuments />,
+};
+
+export const ReadOnly: Story = {
+  name: "Read-only list",
+  render: () => <FileList aria-label="Shared with you" files={CASE_FILES.slice(0, 3)} />,
+};
+
+export const Empty: Story = {
+  render: () => <FileList files={[]} empty="No documents yet. Upload the lease to get started." />,
+};
+
+export const Card: Story = {
+  name: "FileCard",
+  render: () => (
+    <FileCard
+      filename="Commercial lease — 418 Harbor Street.pdf"
+      size={2_516_582}
+      date="2026-09-28T16:20:00Z"
+      uploader={{ name: "Dana Ruiz", role: "Client" }}
+      onDownload={() => {}}
+      actions={
+        <Button type="button" size="sm">
+          Open
+        </Button>
+      }
+    />
+  ),
+};
+
+export const CardLight: Story = {
+  name: "FileCard (light)",
+  globals: { theme: "light" },
+  render: Card.render,
+};

package/src/files/file-list.test.tsx

@@ -0,0 +1,81 @@
+import { fireEvent, render, screen, within } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { FileList, type FileListItem } from "./file-list";
+
+interface CaseDocument extends FileListItem {
+  matterId: string;
+}
+
+const FILES: CaseDocument[] = [
+  {
+    id: "lease",
+    matterId: "m-1",
+    filename: "Commercial lease.pdf",
+    size: 482_000,
+    date: "2026-10-01T12:00:00Z",
+    uploader: { name: "Dana Ruiz", role: "Client" },
+  },
+  {
+    id: "photos",
+    matterId: "m-1",
+    filename: "Water damage.jpg",
+    mimeType: "image/jpeg",
+    size: 3_100_000,
+  },
+];
+
+describe("FileList", () => {
+  it("shows each file's kind, size and uploader", () => {
+    render(<FileList files={FILES} aria-label="Case documents" />);
+    const rows = within(screen.getByRole("list", { name: "Case documents" })).getAllByRole(
+      "listitem",
+    );
+    expect(rows).toHaveLength(2);
+    expect(rows[0]).toHaveTextContent("Commercial lease.pdf");
+    // A dot between facts on screen, a comma for a screen reader.
+    expect(rows[0]).toHaveTextContent(/PDF · , 471 KB · , .+ · , Dana Ruiz \(Client\)/);
+    expect(rows[1]).toHaveTextContent("Image · , 3.0 MB");
+  });
+
+  it("opens a file from its row and hands back the host's own record", () => {
+    const onOpen = vi.fn();
+    render(<FileList files={FILES} onOpen={onOpen} activeId="photos" />);
+
+    fireEvent.click(screen.getByRole("button", { name: /Commercial lease\.pdf/ }));
+    expect(onOpen).toHaveBeenCalledWith(FILES[0]);
+    expect(onOpen.mock.calls[0][0].matterId).toBe("m-1");
+
+    expect(screen.getByRole("button", { name: /Water damage\.jpg/ })).toHaveAttribute(
+      "aria-current",
+      "true",
+    );
+    expect(screen.getByRole("button", { name: /Commercial lease\.pdf/ })).not.toHaveAttribute(
+      "aria-current",
+    );
+  });
+
+  it("downloads and deletes through per-file buttons", () => {
+    const onDownload = vi.fn();
+    const onDelete = vi.fn();
+    render(<FileList files={FILES} onDownload={onDownload} onDelete={onDelete} />);
+
+    fireEvent.click(screen.getByRole("button", { name: "Download Water damage.jpg" }));
+    expect(onDownload).toHaveBeenCalledWith(FILES[1]);
+    fireEvent.click(screen.getByRole("button", { name: "Delete Commercial lease.pdf" }));
+    expect(onDelete).toHaveBeenCalledWith(FILES[0]);
+  });
+
+  it("renders no controls the host did not ask for", () => {
+    render(<FileList files={FILES} />);
+    expect(screen.queryByRole("button")).toBeNull();
+  });
+
+  it("shows the empty message in place of the list", () => {
+    const { rerender } = render(<FileList files={[]} />);
+    expect(screen.queryByRole("list")).toBeNull();
+    expect(screen.getByText("No files yet.")).toBeInTheDocument();
+
+    rerender(<FileList files={[]} empty="Upload the lease to start." />);
+    expect(screen.getByText("Upload the lease to start.")).toBeInTheDocument();
+  });
+});

package/src/files/file-list.tsx

@@ -0,0 +1,167 @@
+/**
+ * FileList — a flat list of documents: each row names the file and its kind,
+ * size, date and uploader; selecting the row opens it, and the row's own
+ * buttons download or delete it.
+ */
+
+import * as React from "react";
+import { Download, Trash2 } from "lucide-react";
+import { focusRingInset } from "../lib/focus";
+import { cn } from "../lib/utils";
+import { Button } from "../primitives/button";
+import {
+  FactSeparator,
+  FileFacts,
+  FileKindTile,
+  uploaderLabel,
+  type FileDetails,
+} from "./file-card";
+
+export interface FileListItem extends FileDetails {
+  /** Stable key, and what `activeId` matches. */
+  id: string;
+}
+
+export interface FileListProps<T extends FileListItem = FileListItem>
+  extends Omit<React.HTMLAttributes<HTMLElement>, "children"> {
+  files: readonly T[];
+  /** Opens a file, usually in a preview. Makes each row a button. */
+  onOpen?: (file: T) => void;
+  /** Adds a Download button to each row. */
+  onDownload?: (file: T) => void;
+  /**
+   * Adds a Delete button to each row. It calls this at once, so a host that
+   * wants a confirmation asks for it here.
+   */
+  onDelete?: (file: T) => void;
+  /** The open file. Its row is marked as the current one. */
+  activeId?: string;
+  /** Shown in place of the list when `files` is empty. */
+  empty?: React.ReactNode;
+}
+
+export function FileList<T extends FileListItem>({
+  files,
+  onOpen,
+  onDownload,
+  onDelete,
+  activeId,
+  empty = "No files yet.",
+  className,
+  ...props
+}: FileListProps<T>) {
+  if (files.length === 0) {
+    return (
+      <div
+        className={cn(
+          "rounded-[var(--radius-md)] border border-border bg-card px-4 py-10 text-center text-sm text-muted-foreground",
+          className,
+        )}
+        {...props}
+      >
+        {empty}
+      </div>
+    );
+  }
+
+  return (
+    <ul
+      className={cn(
+        "divide-y divide-border overflow-hidden rounded-[var(--radius-md)] border border-border bg-card",
+        className,
+      )}
+      {...props}
+    >
+      {files.map((file) => {
+        const active = file.id === activeId;
+        const body = (
+          <>
+            <FileKindTile filename={file.filename} mimeType={file.mimeType} />
+            {/* On a phone the name may take two lines and the uploader takes
+                its own, since one line of facts cannot hold who sent the file. */}
+            <span className="grid min-w-0 flex-1">
+              <span className="line-clamp-2 text-sm font-medium text-foreground [overflow-wrap:anywhere] sm:line-clamp-1">
+                {file.filename}
+              </span>
+              <span className="truncate text-xs text-muted-foreground">
+                <FileFacts
+                  filename={file.filename}
+                  mimeType={file.mimeType}
+                  size={file.size}
+                  date={file.date}
+                  showKind
+                />
+                {file.uploader && (
+                  <span className="hidden sm:inline">
+                    <FactSeparator />
+                    {uploaderLabel(file.uploader)}
+                  </span>
+                )}
+              </span>
+              {file.uploader && (
+                <span className="truncate text-xs text-muted-foreground sm:hidden">
+                  {uploaderLabel(file.uploader)}
+                </span>
+              )}
+            </span>
+          </>
+        );
+        return (
+          <li
+            key={file.id}
+            className={cn(
+              "flex items-center gap-1 pr-2",
+              active ? "bg-primary/10" : onOpen && "hover:bg-[var(--bg-hover)]",
+            )}
+          >
+            {onOpen ? (
+              <button
+                type="button"
+                onClick={() => onOpen(file)}
+                aria-current={active ? "true" : undefined}
+                className={cn(
+                  "flex min-w-0 flex-1 items-center gap-3 py-2.5 pl-3 text-left",
+                  focusRingInset,
+                )}
+              >
+                {body}
+              </button>
+            ) : (
+              <div
+                aria-current={active ? "true" : undefined}
+                className="flex min-w-0 flex-1 items-center gap-3 py-2.5 pl-3"
+              >
+                {body}
+              </div>
+            )}
+            {onDownload && (
+              <Button
+                type="button"
+                variant="ghost"
+                size="icon"
+                aria-label={`Download ${file.filename}`}
+                title="Download"
+                onClick={() => onDownload(file)}
+              >
+                <Download />
+              </Button>
+            )}
+            {onDelete && (
+              <Button
+                type="button"
+                variant="ghost"
+                size="icon"
+                aria-label={`Delete ${file.filename}`}
+                title="Delete"
+                className="hover:text-[var(--surface-danger-text)]"
+                onClick={() => onDelete(file)}
+              >
+                <Trash2 />
+              </Button>
+            )}
+          </li>
+        );
+      })}
+    </ul>
+  );
+}