@calliopelabs/ui 0.13.0 → 0.16.0

package/dist/workbench/FileBrowser.d.ts

@@ -0,0 +1,62 @@
+import * as React from "react";
+import { type MoveHandler } from "./dnd.js";
+import { type FileTreeProps } from "./FileTree.js";
+import { type FileItem, type FileSort, type FileView } from "./model.js";
+export interface FileBrowserProps {
+    /** The directory on screen; "" is the root. */
+    path: string;
+    /** Its entries, in any order (the browser sorts them). Undefined while loading. */
+    items?: readonly FileItem[];
+    /** The listing failed: shown in place of the entries, with `onRetry`. */
+    error?: string | {
+        message: string;
+    } | null;
+    onRetry?: () => void;
+    /** Go to a directory: a breadcrumb, a tree node, or opening a folder. */
+    onNavigate: (path: string) => void;
+    /** Open a file (double-click or Enter). Folders navigate instead. */
+    onOpen?: (item: FileItem) => void;
+    /** Names the browser. Defaults to "Files". */
+    label?: string;
+    /** The root's name in the breadcrumb. Defaults to "Home". */
+    rootLabel?: string;
+    view?: FileView;
+    defaultView?: FileView;
+    onViewChange?: (view: FileView) => void;
+    sort?: FileSort;
+    defaultSort?: FileSort;
+    onSortChange?: (sort: FileSort) => void;
+    /** The selected paths. Controlled when given. */
+    selection?: ReadonlySet<string>;
+    onSelectionChange?: (selection: Set<string>) => void;
+    onMove?: MoveHandler;
+    onDelete?: (items: FileItem[]) => void;
+    onRename?: (item: FileItem) => void;
+    /**
+     * Context-menu items (`ContextMenuItem`s) for the items right-clicked (the
+     * selection), or for the folder itself when `targets` is empty.
+     */
+    contextMenu?: (targets: FileItem[]) => React.ReactNode;
+    /** A folder tree beside the listing; the browser wires its selection, moves and navigation. */
+    tree?: Omit<FileTreeProps, "selectedPath" | "onSelect" | "onMove" | "contextMenu">;
+    /** Controls beside the view switch: new folder, upload, search. */
+    toolbar?: React.ReactNode;
+    /** A thumbnail for grid tiles. */
+    renderThumbnail?: (item: FileItem) => React.ReactNode;
+    formatDate?: (value: string | Date) => string;
+    /** Copy for an empty folder. */
+    empty?: {
+        title: string;
+        description?: string;
+    };
+    className?: string;
+}
+/**
+ * The file browser: breadcrumb, view switch, an optional folder tree, and
+ * the listing as a table (FileList) or tiles (FileGrid), with sorting,
+ * selection, keyboard navigation, a context menu and drag-and-drop moves.
+ * It is driven by the host: data comes in as props and every change goes
+ * out through a callback, so it fetches nothing and runs over any store.
+ * Uncontrolled view, sort and selection work out of the box.
+ */
+export declare function FileBrowser({ path, items, error, onRetry, onNavigate, onOpen, label, rootLabel, view: viewProp, defaultView, onViewChange, sort: sortProp, defaultSort, onSortChange, selection: selectionProp, onSelectionChange, onMove, onDelete, onRename, contextMenu, tree, toolbar, renderThumbnail, formatDate, empty, className, }: FileBrowserProps): React.JSX.Element;

package/dist/workbench/FileBrowser.js

@@ -0,0 +1,117 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ChevronRightIcon, FolderOpenIcon, LayoutGridIcon, ListIcon } from "lucide-react";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+import { ContextMenu, ContextMenuContent, ContextMenuTrigger } from "../primitives/ContextMenu.js";
+import { Segmented } from "../primitives/Segmented.js";
+import { useUI } from "../provider/UIProvider.js";
+import { EmptyState } from "../states/EmptyState.js";
+import { ErrorState } from "../states/ErrorState.js";
+import { LoadingState } from "../states/LoadingState.js";
+import { useFileDrop } from "./dnd.js";
+import { FileGrid } from "./FileGrid.js";
+import { FileList } from "./FileList.js";
+import { FileTree } from "./FileTree.js";
+import { pathSegments, sortFiles } from "./model.js";
+/**
+ * The file browser: breadcrumb, view switch, an optional folder tree, and
+ * the listing as a table (FileList) or tiles (FileGrid), with sorting,
+ * selection, keyboard navigation, a context menu and drag-and-drop moves.
+ * It is driven by the host: data comes in as props and every change goes
+ * out through a callback, so it fetches nothing and runs over any store.
+ * Uncontrolled view, sort and selection work out of the box.
+ */
+export function FileBrowser({ path, items, error, onRetry, onNavigate, onOpen, label, rootLabel, view: viewProp, defaultView = "list", onViewChange, sort: sortProp, defaultSort = { key: "name", dir: "asc" }, onSortChange, selection: selectionProp, onSelectionChange, onMove, onDelete, onRename, contextMenu, tree, toolbar, renderThumbnail, formatDate, empty, className, }) {
+    const { messages } = useUI();
+    const t = messages.workbench;
+    const [ownView, setOwnView] = React.useState(defaultView);
+    const [ownSort, setOwnSort] = React.useState(defaultSort);
+    const [ownSelection, setOwnSelection] = React.useState(() => new Set());
+    const [menuTargets, setMenuTargets] = React.useState([]);
+    const view = viewProp ?? ownView;
+    const sort = sortProp ?? ownSort;
+    const selection = selectionProp ?? ownSelection;
+    const name = label ?? t.files;
+    const setView = (next) => {
+        setOwnView(next);
+        onViewChange?.(next);
+    };
+    const setSort = (next) => {
+        setOwnSort(next);
+        onSortChange?.(next);
+    };
+    const setSelection = React.useCallback((next) => {
+        setOwnSelection(next);
+        onSelectionChange?.(next);
+    }, [onSelectionChange]);
+    // A new folder starts with nothing selected (a controlled selection is the host's to clear).
+    const [shownPath, setShownPath] = React.useState(path);
+    if (shownPath !== path) {
+        setShownPath(path);
+        setOwnSelection(new Set());
+    }
+    const sorted = React.useMemo(() => (items ? sortFiles(items, sort) : []), [items, sort]);
+    const open = (item) => item.kind === "directory" ? onNavigate(item.path) : onOpen?.(item);
+    const segments = pathSegments(path);
+    const here = segments[segments.length - 1]?.name ?? rootLabel ?? t.root;
+    const viewProps = {
+        label: t.filesIn(here),
+        items: sorted,
+        selection,
+        onSelectionChange: setSelection,
+        onOpen: open,
+        onDelete,
+        onRename,
+        onMove,
+    };
+    const errorMessage = typeof error === "string" ? error : error?.message;
+    let body;
+    if (error) {
+        body = (_jsx(ErrorState, { title: t.loadFailed, error: errorMessage || t.loadFailed, onRetry: onRetry, retryLabel: t.retry }));
+    }
+    else if (!items) {
+        body = _jsx(LoadingState, { label: t.loading, rows: 6 });
+    }
+    else if (sorted.length === 0) {
+        body = (_jsx(EmptyState, { icon: _jsx(FolderOpenIcon, { "aria-hidden": true, className: "size-6" }), title: empty?.title ?? t.empty, description: empty?.description ?? (onMove ? t.emptyDescription : undefined) }));
+    }
+    else if (view === "grid") {
+        body = _jsx(FileGrid, { ...viewProps, renderThumbnail: renderThumbnail });
+    }
+    else {
+        body = _jsx(FileList, { ...viewProps, sort: sort, onSortChange: setSort, formatDate: formatDate });
+    }
+    const folderDrop = useFileDrop(items ? path : null, onMove);
+    const pane = (_jsx("div", { ...folderDrop.props, onContextMenu: (event) => {
+            if (!contextMenu)
+                return;
+            // The menu is for the item under the pointer (with the rest of the
+            // selection when it is part of it), or the folder on empty space.
+            const path = event.target.closest("[data-path]")?.dataset.path;
+            const item = sorted.find((i) => i.path === path);
+            const targets = !item
+                ? []
+                : selection.has(item.path)
+                    ? sorted.filter((i) => selection.has(i.path))
+                    : [item];
+            if (!items || error || contextMenu(targets) == null) {
+                event.preventDefault();
+                return;
+            }
+            setMenuTargets(targets);
+        }, className: cn("min-h-0 min-w-0 flex-1 overflow-auto", folderDrop.over && "bg-primary/5 ring-2 ring-primary ring-inset"), children: body }));
+    return (_jsxs("section", { "aria-label": name, "data-slot": "file-browser", className: cn("@container flex min-h-0 flex-col bg-background text-sm", className), children: [_jsxs("div", { className: "flex min-h-11 flex-wrap items-center gap-2 border-b px-3 py-1.5", children: [_jsx(PathBar, { path: path, rootLabel: rootLabel ?? t.root, onNavigate: onNavigate, onMove: onMove }), _jsxs("div", { className: "ml-auto flex items-center gap-1.5", children: [toolbar, _jsx(Segmented, { label: t.view, size: "sm", iconOnly: true, value: view, onValueChange: setView, options: [
+                                    { value: "list", label: t.listView, icon: ListIcon },
+                                    { value: "grid", label: t.gridView, icon: LayoutGridIcon },
+                                ] })] })] }), _jsxs("div", { className: "flex min-h-0 flex-1", children: [tree && (_jsx("div", { className: "hidden w-56 shrink-0 overflow-auto border-r @2xl:block", children: _jsx(FileTree, { ...tree, selectedPath: path, onSelect: (item) => item.kind === "directory" ? onNavigate(item.path) : onOpen?.(item), onMove: onMove }) })), contextMenu ? (_jsxs(ContextMenu, { children: [_jsx(ContextMenuTrigger, { asChild: true, children: pane }), _jsx(ContextMenuContent, { children: contextMenu(menuTargets) })] })) : (pane)] }), _jsxs("div", { role: "status", className: "flex h-7 items-center gap-3 border-t px-3 text-xs text-muted-foreground", children: [items && !error && _jsx("span", { children: t.itemCount(sorted.length) }), selection.size > 0 && _jsx("span", { children: t.selected(selection.size) })] })] }));
+}
+function PathBar({ path, rootLabel, onNavigate, onMove, }) {
+    const { messages } = useUI();
+    const crumbs = [{ name: rootLabel, path: "" }, ...pathSegments(path)];
+    return (_jsx("nav", { "aria-label": messages.workbench.location, className: "min-w-0 flex-1", children: _jsx("ol", { className: "flex min-w-0 items-center gap-0.5", children: crumbs.map((crumb, i) => (_jsx(Crumb, { name: crumb.name, path: crumb.path, first: i === 0, current: i === crumbs.length - 1, onNavigate: onNavigate, onMove: onMove }, crumb.path || "/"))) }) }));
+}
+function Crumb({ name, path, first, current, onNavigate, onMove, }) {
+    const drop = useFileDrop(current ? null : path, onMove);
+    return (_jsxs("li", { className: cn("flex min-w-0 items-center gap-0.5", current ? "shrink" : "shrink-[2]"), children: [!first && _jsx(ChevronRightIcon, { "aria-hidden": true, className: "size-3 shrink-0 text-muted-foreground" }), _jsx("button", { type: "button", "aria-current": current ? "location" : undefined, onClick: () => onNavigate(path), ...drop.props, className: cn("min-w-0 truncate rounded-lg px-1.5 py-0.5 outline-none hover:bg-accent hover:text-accent-foreground focus-visible:ring-2 focus-visible:ring-ring/50", current ? "font-medium text-foreground" : "text-muted-foreground", drop.over && "bg-primary/10 ring-2 ring-primary"), children: name })] }));
+}

package/dist/workbench/FileGrid.d.ts

@@ -0,0 +1,13 @@
+import * as React from "react";
+import type { FileItem } from "./model.js";
+import type { FileViewProps } from "./FileList.js";
+export interface FileGridProps extends FileViewProps {
+    /** A thumbnail in place of the type icon (an image's own preview). */
+    renderThumbnail?: (item: FileItem) => React.ReactNode;
+}
+/**
+ * A directory as tiles: a multi-select listbox laid out in rows, so the
+ * arrows move in two dimensions (up and down by a row of tiles). The same
+ * selection, opening, typeahead and drag rules as FileList.
+ */
+export declare function FileGrid({ label, items, selection, onSelectionChange, onOpen, onDelete, onRename, onMove, renderThumbnail, className, }: FileGridProps): React.JSX.Element;

package/dist/workbench/FileGrid.js

@@ -0,0 +1,114 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+import { useUI } from "../provider/UIProvider.js";
+import { startFileDrag, useFileDrop } from "./dnd.js";
+import { FileIcon } from "./FileIcon.js";
+import { modeOf, useSelectionModel } from "./selection.js";
+import { typeahead } from "./typeahead.js";
+/**
+ * A directory as tiles: a multi-select listbox laid out in rows, so the
+ * arrows move in two dimensions (up and down by a row of tiles). The same
+ * selection, opening, typeahead and drag rules as FileList.
+ */
+export function FileGrid({ label, items, selection, onSelectionChange, onOpen, onDelete, onRename, onMove, renderThumbnail, className, }) {
+    const { messages } = useUI();
+    const t = messages.workbench;
+    const order = React.useMemo(() => items.map((i) => i.path), [items]);
+    const model = useSelectionModel(order, selection, onSelectionChange);
+    const [focusIndex, setFocusIndex] = React.useState(0);
+    const index = Math.min(focusIndex, items.length - 1);
+    const list = React.useRef(null);
+    const tiles = React.useRef(new Map());
+    const pending = React.useRef(false);
+    const search = React.useRef({ text: "", at: 0 });
+    React.useLayoutEffect(() => {
+        if (!pending.current)
+            return;
+        pending.current = false;
+        tiles.current.get(index)?.focus();
+    });
+    const columns = () => {
+        const template = list.current ? getComputedStyle(list.current).gridTemplateColumns : "";
+        return Math.max(1, template.split(" ").filter(Boolean).length);
+    };
+    const onKeyDown = (event) => {
+        const meta = event.metaKey || event.ctrlKey;
+        const go = (target) => {
+            event.preventDefault();
+            const next = Math.min(Math.max(target, 0), items.length - 1);
+            pending.current = true;
+            setFocusIndex(next);
+            const item = items[next];
+            if (item && !meta)
+                model.select(item.path, event.shiftKey ? "range" : "replace");
+        };
+        switch (event.key) {
+            case "ArrowRight":
+                return go(index + 1);
+            case "ArrowLeft":
+                return go(index - 1);
+            case "ArrowDown":
+                return go(index + columns());
+            case "ArrowUp":
+                return go(index - columns());
+            case "Home":
+                return go(0);
+            case "End":
+                return go(items.length - 1);
+        }
+        const item = items[index];
+        if (!item)
+            return;
+        if (event.key === "Enter") {
+            event.preventDefault();
+            onOpen(item);
+        }
+        else if (event.key === " ") {
+            event.preventDefault();
+            model.select(item.path, meta ? "toggle" : event.shiftKey ? "range" : "replace");
+        }
+        else if (meta && event.key.toLowerCase() === "a") {
+            event.preventDefault();
+            model.selectAll();
+        }
+        else if (event.key === "Escape" && selection.size > 0) {
+            event.preventDefault();
+            model.clear();
+        }
+        else if (onDelete && (event.key === "Delete" || (meta && event.key === "Backspace"))) {
+            const targets = items.filter((i) => selection.has(i.path));
+            if (targets.length) {
+                event.preventDefault();
+                onDelete(targets);
+            }
+        }
+        else if (onRename && event.key === "F2") {
+            event.preventDefault();
+            onRename(item);
+        }
+        else {
+            const next = typeahead(search.current, event, items.map((i) => i.name), index);
+            if (next !== null)
+                go(next);
+        }
+    };
+    return (_jsx("div", { ref: list, role: "listbox", "aria-label": label, "aria-multiselectable": true, onKeyDown: onKeyDown, className: cn("grid grid-cols-[repeat(auto-fill,minmax(6.5rem,1fr))] content-start gap-1 p-2", className), children: items.map((item, i) => (_jsx(Tile, { item: item, selected: selection.has(item.path), tabbable: i === index, tileRef: (el) => {
+                if (el)
+                    tiles.current.set(i, el);
+                else
+                    tiles.current.delete(i);
+            }, onFocus: () => setFocusIndex(i), onMove: onMove, dragPaths: selection.has(item.path) ? order.filter((p) => selection.has(p)) : [item.path], dragLabel: (n) => (n === 1 ? item.name : t.itemCount(n)), thumbnail: renderThumbnail?.(item), onClick: (event) => {
+                setFocusIndex(i);
+                model.select(item.path, modeOf(event));
+            }, onDoubleClick: () => onOpen(item), onContextMenu: () => {
+                // Right-clicking outside the selection selects the item, as file managers do.
+                if (!selection.has(item.path))
+                    model.select(item.path, "replace");
+            } }, item.path))) }));
+}
+function Tile({ item, selected, tabbable, tileRef, onFocus, onMove, dragPaths, dragLabel, thumbnail, onClick, onDoubleClick, onContextMenu, }) {
+    const drop = useFileDrop(item.kind === "directory" ? item.path : null, onMove);
+    return (_jsxs("div", { ref: tileRef, role: "option", "data-path": item.path, "aria-selected": selected, tabIndex: tabbable ? 0 : -1, title: item.name, draggable: Boolean(onMove), onDragStart: onMove ? (event) => startFileDrag(event, dragPaths, dragLabel(dragPaths.length)) : undefined, ...drop.props, onFocus: onFocus, onClick: onClick, onDoubleClick: onDoubleClick, onContextMenu: onContextMenu, className: cn("flex cursor-default flex-col items-center gap-1.5 rounded-lg p-2 text-center outline-none select-none hover:bg-accent/60 focus-visible:ring-2 focus-visible:ring-ring/50", selected && "bg-accent text-accent-foreground hover:bg-accent", drop.over && "bg-primary/10 ring-2 ring-primary"), children: [_jsx("span", { className: "flex size-12 items-center justify-center overflow-hidden rounded-lg", children: thumbnail ?? _jsx(FileIcon, { name: item.name, kind: item.kind, className: "size-8" }) }), _jsx("span", { className: "line-clamp-2 w-full text-xs [overflow-wrap:anywhere]", children: item.name })] }));
+}

package/dist/workbench/FileIcon.d.ts

@@ -0,0 +1,10 @@
+import { type FileKind } from "./model.js";
+export interface FileIconProps {
+    name: string;
+    kind: FileKind;
+    /** An open directory (an expanded tree node). */
+    open?: boolean;
+    className?: string;
+}
+/** A file-type glyph from the name's extension; directories in the accent. Decorative. */
+export declare function FileIcon({ name, kind, open, className }: FileIconProps): import("react").JSX.Element;

package/dist/workbench/FileIcon.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { FileArchiveIcon, FileCodeIcon, FileIcon as LucideFileIcon, FileImageIcon, FileJsonIcon, FileSpreadsheetIcon, FileTextIcon, FolderIcon, FolderOpenIcon, } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { fileExtension } from "./model.js";
+const BY_EXTENSION = {};
+const group = (icon, extensions) => {
+    for (const ext of extensions.split(" "))
+        BY_EXTENSION[ext] = icon;
+};
+group(FileCodeIcon, "py js jsx ts tsx mjs cjs rs go java kt rb sh bash zsh sql html css scss c h cpp hpp cs php swift lua r tf");
+group(FileJsonIcon, "json jsonl ipynb");
+group(FileSpreadsheetIcon, "csv tsv parquet xlsx xls ods");
+group(FileImageIcon, "png jpg jpeg gif svg webp avif bmp ico");
+group(FileTextIcon, "md markdown txt log yaml yml toml ini cfg conf rst pdf doc docx");
+group(FileArchiveIcon, "zip tar gz tgz bz2 xz 7z rar");
+/** A file-type glyph from the name's extension; directories in the accent. Decorative. */
+export function FileIcon({ name, kind, open = false, className }) {
+    if (kind === "directory") {
+        const Folder = open ? FolderOpenIcon : FolderIcon;
+        return _jsx(Folder, { "aria-hidden": true, className: cn("size-4 shrink-0 text-primary", className) });
+    }
+    const Glyph = BY_EXTENSION[fileExtension(name)] ?? LucideFileIcon;
+    return _jsx(Glyph, { "aria-hidden": true, className: cn("size-4 shrink-0 text-muted-foreground", className) });
+}

package/dist/workbench/FileList.d.ts

@@ -0,0 +1,35 @@
+import * as React from "react";
+import { type MoveHandler } from "./dnd.js";
+import { type FileItem, type FileSort } from "./model.js";
+export interface FileViewProps {
+    /** Names the view for screen readers ("Files in reports"). */
+    label: string;
+    /** In display order (`sortFiles`). */
+    items: readonly FileItem[];
+    selection: ReadonlySet<string>;
+    onSelectionChange: (next: Set<string>) => void;
+    /** Double-click or Enter. */
+    onOpen: (item: FileItem) => void;
+    /** Delete, or Cmd/Ctrl+Backspace, on the selection. */
+    onDelete?: (items: FileItem[]) => void;
+    /** F2 on one item. */
+    onRename?: (item: FileItem) => void;
+    /** Drag items onto directories. */
+    onMove?: MoveHandler;
+    className?: string;
+}
+export interface FileListProps extends FileViewProps {
+    sort?: FileSort;
+    /** Present, the headers are sort buttons. */
+    onSortChange?: (sort: FileSort) => void;
+    /** How a modified time reads. Defaults to the locale's medium date and short time. */
+    formatDate?: (value: string | Date) => string;
+}
+/**
+ * A directory as a sortable table, on the WAI-ARIA grid pattern: one tab
+ * stop, arrows move between cells, selection follows the focus (Ctrl or Cmd
+ * with an arrow moves without selecting, Shift extends), Home and End, Page
+ * Up and Down, Enter opens, Cmd/Ctrl+A selects all, Escape clears, and
+ * typing finds a name. Rows drag onto folders.
+ */
+export declare function FileList({ label, items, selection, onSelectionChange, onOpen, onDelete, onRename, onMove, sort, onSortChange, formatDate, className, }: FileListProps): React.JSX.Element;

package/dist/workbench/FileList.js

@@ -0,0 +1,160 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { ArrowDownIcon, ArrowUpIcon } from "lucide-react";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+import { useUI } from "../provider/UIProvider.js";
+import { startFileDrag, useFileDrop } from "./dnd.js";
+import { FileIcon } from "./FileIcon.js";
+import { formatBytes } from "./model.js";
+import { modeOf, useSelectionModel } from "./selection.js";
+import { typeahead } from "./typeahead.js";
+const COLUMNS = ["name", "size", "modified"];
+const WIDTH = {
+    name: "min-w-0 flex-1",
+    size: "w-20 shrink-0 justify-end text-right",
+    modified: "hidden w-44 shrink-0 @lg:flex",
+};
+const defaultFormat = (value) => {
+    const date = value instanceof Date ? value : new Date(value);
+    return Number.isNaN(date.getTime())
+        ? ""
+        : date.toLocaleString(undefined, { dateStyle: "medium", timeStyle: "short" });
+};
+/**
+ * A directory as a sortable table, on the WAI-ARIA grid pattern: one tab
+ * stop, arrows move between cells, selection follows the focus (Ctrl or Cmd
+ * with an arrow moves without selecting, Shift extends), Home and End, Page
+ * Up and Down, Enter opens, Cmd/Ctrl+A selects all, Escape clears, and
+ * typing finds a name. Rows drag onto folders.
+ */
+export function FileList({ label, items, selection, onSelectionChange, onOpen, onDelete, onRename, onMove, sort, onSortChange, formatDate = defaultFormat, className, }) {
+    const { messages } = useUI();
+    const t = messages.workbench;
+    const order = React.useMemo(() => items.map((i) => i.path), [items]);
+    const model = useSelectionModel(order, selection, onSelectionChange);
+    // Focus: row -1 is the header; columns index COLUMNS.
+    const [focus, setFocus] = React.useState({ row: 0, col: 0 });
+    const cells = React.useRef(new Map());
+    const pending = React.useRef(false);
+    const search = React.useRef({ text: "", at: 0 });
+    const headerRow = onSortChange ? -1 : 0;
+    const row = Math.min(Math.max(focus.row, headerRow), items.length - 1);
+    const col = focus.col;
+    React.useLayoutEffect(() => {
+        if (!pending.current)
+            return;
+        pending.current = false;
+        cells.current.get(`${row}:${col}`)?.focus();
+    });
+    const move = (next) => {
+        pending.current = true;
+        setFocus({
+            row: Math.min(Math.max(next.row, headerRow), items.length - 1),
+            col: Math.min(Math.max(next.col, 0), COLUMNS.length - 1),
+        });
+    };
+    const selected = () => items.filter((i) => selection.has(i.path));
+    const onKeyDown = (event) => {
+        const meta = event.metaKey || event.ctrlKey;
+        const go = (target) => {
+            event.preventDefault();
+            const clamped = Math.min(Math.max(target, headerRow), items.length - 1);
+            move({ row: clamped, col });
+            const item = items[clamped];
+            if (item && !meta)
+                model.select(item.path, event.shiftKey ? "range" : "replace");
+        };
+        switch (event.key) {
+            case "ArrowDown":
+                return go(row + 1);
+            case "ArrowUp":
+                return go(row - 1);
+            case "PageDown":
+                return go(row + 10);
+            case "PageUp":
+                return go(row - 10);
+            case "ArrowRight":
+                event.preventDefault();
+                return move({ row, col: col + 1 });
+            case "ArrowLeft":
+                event.preventDefault();
+                return move({ row, col: col - 1 });
+            case "Home":
+                if (meta)
+                    return go(0);
+                event.preventDefault();
+                return move({ row, col: 0 });
+            case "End":
+                if (meta)
+                    return go(items.length - 1);
+                event.preventDefault();
+                return move({ row, col: COLUMNS.length - 1 });
+        }
+        if (row < 0)
+            return;
+        const item = items[row];
+        if (!item)
+            return;
+        if (event.key === "Enter") {
+            event.preventDefault();
+            onOpen(item);
+        }
+        else if (event.key === " ") {
+            event.preventDefault();
+            model.select(item.path, meta ? "toggle" : event.shiftKey ? "range" : "replace");
+        }
+        else if (meta && event.key.toLowerCase() === "a") {
+            event.preventDefault();
+            model.selectAll();
+        }
+        else if (event.key === "Escape" && selection.size > 0) {
+            event.preventDefault();
+            model.clear();
+        }
+        else if (onDelete && (event.key === "Delete" || (meta && event.key === "Backspace"))) {
+            const targets = selected();
+            if (targets.length) {
+                event.preventDefault();
+                onDelete(targets);
+            }
+        }
+        else if (onRename && event.key === "F2") {
+            event.preventDefault();
+            onRename(item);
+        }
+        else {
+            const next = typeahead(search.current, event, items.map((i) => i.name), row);
+            if (next !== null)
+                go(next);
+        }
+    };
+    const cellRef = (r, c) => (el) => {
+        if (el)
+            cells.current.set(`${r}:${c}`, el);
+        else
+            cells.current.delete(`${r}:${c}`);
+    };
+    const tabIndex = (r, c) => (r === row && c === col ? 0 : -1);
+    const header = { name: t.name, size: t.size, modified: t.modified };
+    return (_jsxs("div", { role: "grid", "aria-label": label, "aria-multiselectable": true, "aria-rowcount": items.length + 1, onKeyDown: onKeyDown, className: cn("@container flex min-w-0 flex-col text-sm", className), children: [_jsx("div", { role: "row", "aria-rowindex": 1, className: "sticky top-0 z-10 flex items-center gap-2 border-b bg-muted/60 px-3 text-xs font-medium text-muted-foreground backdrop-blur-sm", children: COLUMNS.map((key, c) => {
+                    const active = sort?.key === key;
+                    const ariaSort = active ? (sort.dir === "asc" ? "ascending" : "descending") : undefined;
+                    return (_jsx("div", { role: "columnheader", "aria-sort": ariaSort, className: cn("flex h-8 items-center", WIDTH[key]), children: onSortChange ? (_jsxs("button", { type: "button", ref: cellRef(-1, c), tabIndex: tabIndex(-1, c), onFocus: () => setFocus({ row: -1, col: c }), onClick: () => onSortChange({
+                                key,
+                                dir: active && sort.dir === "asc" ? "desc" : "asc",
+                            }), className: "inline-flex items-center gap-1 rounded-lg outline-none hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring/50", children: [header[key], active &&
+                                    (sort.dir === "asc" ? (_jsx(ArrowUpIcon, { "aria-hidden": true, className: "size-3" })) : (_jsx(ArrowDownIcon, { "aria-hidden": true, className: "size-3" })))] })) : (header[key]) }, key));
+                }) }), items.map((item, r) => (_jsx(FileRow, { item: item, index: r, selected: selection.has(item.path), onMove: onMove, dragPaths: selection.has(item.path) ? order.filter((p) => selection.has(p)) : [item.path], dragLabel: (n) => (n === 1 ? item.name : t.itemCount(n)), onClick: (event) => {
+                    setFocus({ row: r, col });
+                    model.select(item.path, modeOf(event));
+                }, onDoubleClick: () => onOpen(item), onContextMenu: () => {
+                    // Right-clicking outside the selection selects the item, as file managers do.
+                    if (!selection.has(item.path))
+                        model.select(item.path, "replace");
+                }, children: COLUMNS.map((key, c) => (_jsx("div", { role: "gridcell", ref: cellRef(r, c), tabIndex: tabIndex(r, c), onFocus: () => setFocus({ row: r, col: c }), className: cn("flex h-8 items-center gap-2 rounded-lg outline-none focus-visible:ring-2 focus-visible:ring-ring/50", WIDTH[key], key !== "name" && "text-xs text-muted-foreground"), children: key === "name" ? (_jsxs(_Fragment, { children: [_jsx(FileIcon, { name: item.name, kind: item.kind }), _jsx("span", { className: "truncate", children: item.name })] })) : key === "size" ? (item.kind === "file" && item.size != null ? (formatBytes(item.size)) : (_jsx("span", { "aria-label": t.noSize, children: "\u2013" }))) : item.modified ? (_jsx("span", { className: "truncate", children: formatDate(item.modified) })) : null }, key))) }, item.path)))] }));
+}
+function FileRow({ item, index, selected, onMove, dragPaths, dragLabel, onClick, onDoubleClick, onContextMenu, children, }) {
+    const drop = useFileDrop(item.kind === "directory" ? item.path : null, onMove);
+    return (_jsx("div", { role: "row", "data-path": item.path, "aria-rowindex": index + 2, "aria-selected": selected, draggable: Boolean(onMove), onDragStart: onMove ? (event) => startFileDrag(event, dragPaths, dragLabel(dragPaths.length)) : undefined, ...drop.props, onClick: onClick, onDoubleClick: onDoubleClick, onContextMenu: onContextMenu, className: cn("flex cursor-default items-center gap-2 px-3 select-none hover:bg-accent/60", selected && "bg-accent text-accent-foreground hover:bg-accent", drop.over && "bg-primary/10 ring-2 ring-primary ring-inset"), children: children }));
+}

package/dist/workbench/FilePreview.d.ts

@@ -0,0 +1,66 @@
+import * as React from "react";
+/** What the host read from the file. `previewKindFor(name, mime)` picks the kind. */
+export type FilePreviewContent = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "markdown";
+    text: string;
+}
+/** Pretty-printed when it parses; shown as written otherwise (JSON Lines). */
+ | {
+    kind: "json";
+    text: string;
+}
+/** Parsed here; the first row is the header unless `header` is false. `delimiter` "\t" for TSV. */
+ | {
+    kind: "csv";
+    text: string;
+    delimiter?: string;
+    header?: boolean;
+}
+/** Rows the server already parsed (a Parquet or Excel sample). */
+ | {
+    kind: "table";
+    columns: readonly string[];
+    rows: readonly Record<string, unknown>[];
+} | {
+    kind: "image";
+    src: string;
+    alt?: string;
+}
+/** Nothing to show: the type and size only. */
+ | {
+    kind: "binary";
+};
+export interface FilePreviewProps {
+    /** The file's name, the panel's title. */
+    name: string;
+    size?: number | null;
+    mimeType?: string | null;
+    /** Undefined while loading. */
+    content?: FilePreviewContent;
+    error?: string | {
+        message: string;
+    } | null;
+    onRetry?: () => void;
+    /** Part of the file only: the rows or bytes shown, and the whole when known. */
+    truncated?: boolean | {
+        shown: number;
+        total?: number | null;
+    };
+    /** Draws markdown. The package ships no markdown parser; without one the source shows as text. */
+    renderMarkdown?: (text: string) => React.ReactNode;
+    /** Shows a close button. */
+    onClose?: () => void;
+    /** Buttons in the header: download, open. */
+    actions?: React.ReactNode;
+    className?: string;
+}
+/**
+ * A file's contents in a side panel: CSV and tables in the library's
+ * DataTable (search, sort, paging), JSON pretty-printed, images, markdown
+ * through the host's renderer, and text. It reads nothing itself: the host
+ * fetches the bytes and hands over the content.
+ */
+export declare function FilePreview({ name, size, mimeType, content, error, onRetry, truncated, renderMarkdown, onClose, actions, className, }: FilePreviewProps): React.JSX.Element;