@parallelworks/ui 0.2.0 → 0.3.1

package/dist/file-explorer/FilePreview/parse.d.ts

@@ -0,0 +1,24 @@
+/** Parse CSV/TSV, honoring quoted fields (embedded delimiter/newline/escaped quote);
+ * `maxRows` stops early so a big file isn't walked in full for a preview. */
+export declare function parseDelimited(text: string, delimiter: string, maxRows?: number): string[][];
+export interface NotebookOutput {
+    output_type: string;
+    text?: string | string[];
+    data?: Record<string, unknown>;
+    ename?: string;
+    evalue?: string;
+    traceback?: string[];
+}
+export interface NotebookCell {
+    cell_type: string;
+    source: string | string[];
+    outputs?: NotebookOutput[];
+    execution_count?: number | null;
+}
+export interface ParsedNotebook {
+    cells: NotebookCell[];
+}
+export declare function parseNotebook(text: string): ParsedNotebook | null;
+/** nbformat `source`/`text` is a string or an array of lines; normalize to one string. */
+export declare function joinSource(source: unknown): string;
+export declare function stripAnsi(text: string): string;

package/dist/file-explorer/FilePreview/previewCache.d.ts

@@ -0,0 +1,26 @@
+type UrlResult = [string | null, Error | null];
+interface UrlRecord {
+    promise: Promise<UrlResult>;
+    value?: UrlResult;
+}
+interface ContentRecord<T> {
+    promise: Promise<T>;
+    value?: T;
+    controller: AbortController;
+    dispose?: ((value: T) => void) | undefined;
+}
+/** Request a presigned URL for `path` once and remember the result; a failed or
+ * empty result is not cached so a later mount retries. */
+export declare function loadPreviewUrl(path: string, loader: () => Promise<UrlResult>): UrlRecord;
+/** Fetch the object for `path` once and remember it; `dispose` frees the value
+ * (e.g. revokes a blob URL) when the entry is evicted. A rejected fetch is not
+ * cached so a later mount retries. */
+export declare function loadPreviewContent<T>(path: string, loader: (signal: AbortSignal) => Promise<T>, dispose?: (value: T) => void): ContentRecord<T>;
+/** Fetch a preview object over its signed URL; a 401/403 means the URL is stale
+ * or unauthorized, so drop it from the cache and let the next mount fetch a fresh
+ * one instead of replaying the dead one. */
+export declare function fetchPreviewObject(path: string, url: string, signal: AbortSignal, headers?: HeadersInit): Promise<Response>;
+export declare function peekPreviewUrl(path: string): UrlResult | undefined;
+export declare function peekPreviewContent<T>(path: string): T | undefined;
+export declare function clearPreviewCache(): void;
+export {};

package/dist/file-explorer/FilePreview/previewType.d.ts

@@ -0,0 +1,21 @@
+import { getFileExtension } from '../lib/utils.js';
+import type { TreeNode } from '../lib/types.js';
+export { getFileExtension };
+export type PreviewKind = 'image' | 'video' | 'audio' | 'pdf' | 'code' | 'csv' | 'notebook' | 'archive' | 'unsupported';
+/** Short-lived so the link doesn't linger; an hour covers a viewing session. */
+export declare const PREVIEW_URL_EXPIRES_IN: number;
+/** Cap text pulled into the tab; media streams through native elements uncapped. */
+export declare const CODE_PREVIEW_MAX_BYTES: number;
+export declare const TABULAR_PREVIEW_MAX_BYTES: number;
+export declare const CSV_PREVIEW_MAX_ROWS = 500;
+/** A line cap bounds what a text preview holds and renders; the byte cap above cuts
+ * short whatever the line cap hasn't, and refuses outright only content with no line
+ * break to cut on. Well under Monaco's 20MB and 300K-line thresholds, past which it
+ * stops tokenizing and highlighting dies. */
+export declare const CODE_PREVIEW_MAX_LINES = 5000;
+/** Fetched into a blob URL to render inline regardless of served content type; falls back to download above this. */
+export declare const PDF_PREVIEW_MAX_BYTES: number;
+export declare function getMonacoLanguage(node: TreeNode): string;
+/** Content type wins when present; extension is the fallback. */
+export declare function getPreviewKind(node: TreeNode): PreviewKind;
+export declare function canPreview(node: TreeNode): boolean;

package/dist/file-explorer/FilePreview/readCappedBytes.d.ts

@@ -0,0 +1,37 @@
+/** Read a Response body but stop once it passes `maxBytes` (returning `tooLarge`), so an object whose listed size is missing or under-reported can't be pulled fully into the tab. */
+export declare function readCappedBytes(response: Response, maxBytes: number): Promise<{
+    bytes: Uint8Array<ArrayBuffer>;
+    tooLarge: boolean;
+}>;
+/** Lines a preview will render; a trailing newline doesn't open another line. */
+export declare function countLines(text: string): number;
+interface CappedText {
+    text: string;
+    tooLarge: boolean;
+    truncated: boolean;
+}
+/** Read a Response as text capped at `maxBytes`; when `maxLines` is given, cancel the stream
+ * once that many `\n` arrive. Cutting on `\n` keeps the returned prefix on a clean UTF-8 boundary. */
+export declare function readCappedText(response: Response, maxBytes: number, maxLines?: number): Promise<CappedText>;
+/** Keep the last `maxLines` lines, ignoring a single trailing newline so a file
+ * ending in one doesn't spend a line on the empty remainder. */
+export declare function lastLines(text: string, maxLines: number): {
+    text: string;
+    truncated: boolean;
+};
+/** Range header for reading the last `maxBytes` of an object. A closed range is a
+ * CORS-safelisted header value, so it travels without a preflight that a bucket's
+ * CORS rules may not answer; the suffix form is not safelisted, and is only reached
+ * for workspace files, which are same-origin and list no size. Closing the range at
+ * the listed size also bounds the window: left open, an object that grew since the
+ * listing would serve more than `maxBytes` and the read would refuse it. */
+export declare function tailRangeFor(knownSize: number | undefined, maxBytes: number): string | null;
+/** What a ranged response actually delivered: whether its first line arrives cut in
+ * half, or `null` when the body can't be the object's end at all. */
+export declare function tailWindow(response: Response, maxBytes: number): {
+    startsMidObject: boolean;
+} | null;
+/** Read a range covering the end of an object as text. `startsMidObject` says the
+ * range began at an arbitrary byte, so the first line arrives cut in half. */
+export declare function readTailText(response: Response, maxBytes: number, maxLines: number | undefined, startsMidObject: boolean): Promise<CappedText>;
+export {};

package/dist/file-explorer/FilePreview/useObjectBlobUrl.d.ts

@@ -0,0 +1,16 @@
+interface ObjectBlobState {
+    blobUrl: string | null;
+    loading: boolean;
+    error: string | null;
+    tooLarge: boolean;
+    corsError: boolean;
+}
+/** Fetch an object into a blob URL with a forced MIME type so e.g. PDFs render inline even when served as octet-stream; cached per `cacheKey` so repeated mounts share one download and one blob URL, revoked when the cache drops it. */
+export declare function useObjectBlobUrl(url: string | null, { enabled, maxBytes, knownSize, mimeType, cacheKey, }: {
+    enabled: boolean;
+    maxBytes: number;
+    knownSize?: number | undefined;
+    mimeType: string;
+    cacheKey: string;
+}): ObjectBlobState;
+export {};

package/dist/file-explorer/FilePreview/useObjectText.d.ts

@@ -0,0 +1,23 @@
+interface TextResult {
+    text: string | null;
+    tooLarge: boolean;
+    truncated: boolean;
+}
+interface ObjectTextState extends TextResult {
+    loading: boolean;
+    error: string | null;
+    corsError: boolean;
+}
+/** Fetch a text object from a presigned URL, cached per `cacheKey` so repeated mounts
+ * download it once. `maxLines` stops the read early and `maxBytes` cuts short what it
+ * hasn't. `tail` reads the end of the object instead of the start, and caches
+ * separately because the same object yields different text. */
+export declare function useObjectText(url: string | null, { enabled, maxBytes, maxLines, knownSize, cacheKey, tail, }: {
+    enabled: boolean;
+    maxBytes: number;
+    maxLines?: number | undefined;
+    knownSize?: number | undefined;
+    cacheKey: string;
+    tail?: boolean | undefined;
+}): ObjectTextState;
+export {};

package/dist/file-explorer/FilePreview/usePresignedUrl.d.ts

@@ -0,0 +1,12 @@
+import type { TreeNode } from '../lib/types.js';
+interface PresignedUrlState {
+    url: string | null;
+    loading: boolean;
+    error: string | null;
+}
+/** Fetch a presigned URL per file, cached so repeated mounts share one request; callbacks come from refs so the effect keys only on file identity. */
+export declare function usePresignedUrl(node: TreeNode | null, getPresignedUrl: (node: TreeNode) => Promise<[string | null, Error | null]>, { enabled, linkErrorMessage }: {
+    enabled: boolean;
+    linkErrorMessage: string;
+}): PresignedUrlState;
+export {};

package/dist/file-explorer/FileRow.d.ts

@@ -0,0 +1,35 @@
+import { type OpenMenu, type RowMenuItem } from '../list/index.js';
+import type { ReactNode } from 'react';
+import type { TreeNode } from './lib/types.js';
+export declare const ROW_HEIGHT_SHORT = 45;
+export declare const ROW_HEIGHT_TALL = 52.25;
+export declare function isTwoLineRow(node: TreeNode): boolean;
+/** Pure function of the node, so the virtualizer sizes rows without measuring. */
+export declare function fileRowHeight(node: TreeNode): number;
+interface FileRowProps {
+    node: TreeNode;
+    icon: ReactNode;
+    /** Target for the table's aria-activedescendant. */
+    rowId: string;
+    /** True position in the folder, which a windowed table cannot convey from DOM order. */
+    rowIndex: number;
+    /** The keyboard cursor row. Focus stays on the container, so nothing else marks it. */
+    active: boolean;
+    checked: boolean;
+    canPreview: boolean;
+    getItems: () => RowMenuItem[];
+    openMenu: OpenMenu;
+    onOpen: (node: TreeNode) => void;
+    onToggleCheck: (node: TreeNode, checked: boolean) => void;
+    onPreview: (node: TreeNode) => void;
+}
+export declare function UserRow({ node, icon, storageCount, getItems, openMenu, onOpen, }: {
+    node: TreeNode;
+    icon: ReactNode;
+    storageCount: number;
+    getItems: () => RowMenuItem[];
+    openMenu: OpenMenu;
+    onOpen: (node: TreeNode) => void;
+}): import("react").JSX.Element;
+export declare function FileRow({ node, icon, rowId, rowIndex, active, checked, canPreview, getItems, openMenu, onOpen, onToggleCheck, onPreview, }: FileRowProps): import("react").JSX.Element;
+export {};

package/dist/file-explorer/FileRowsWindow.d.ts

@@ -0,0 +1,43 @@
+import type { OpenMenu, RowMenuItem } from '../list/index.js';
+import type { TreeNode } from './lib/types.js';
+interface Span {
+    start: number;
+    end: number;
+}
+/** `start`/`end` include scrollMargin but getTotalSize() does not, so the margin
+ *  has to come back out of both. */
+export declare function spacerHeights(items: readonly Span[], totalSize: number, scrollMargin: number): {
+    top: number;
+    bottom: number;
+};
+interface VirtualRow {
+    index: number;
+    start: number;
+    size: number;
+}
+interface FileRowsWindowProps {
+    items: readonly VirtualRow[];
+    padTop: number;
+    padBottom: number;
+    nodes: TreeNode[];
+    checkedItems: Set<string>;
+    /** Keyboard cursor owned by FileTable; -1 when there is none. */
+    activeIndex: number;
+    rowIdPrefix: string;
+    scrollEl: HTMLElement | null;
+    loadMore?: {
+        loading: boolean;
+        error: string | undefined;
+        auto: boolean;
+        onLoadMore: () => void;
+    } | undefined;
+    getItems: (node: TreeNode) => RowMenuItem[];
+    openMenu: OpenMenu;
+    onOpen: (node: TreeNode) => void;
+    onToggleCheck: (node: TreeNode, checked: boolean) => void;
+    onPreview: (node: TreeNode) => void;
+}
+/** Must stay a single child of `<Table>`: Table re-keys children by traversal
+ *  index, so a count that varied with scroll position would remount every row. */
+export declare function FileRowsWindow({ items, padTop, padBottom, nodes, checkedItems, activeIndex, rowIdPrefix, scrollEl, loadMore, getItems, openMenu, onOpen, onToggleCheck, onPreview, }: FileRowsWindowProps): import("react").JSX.Element;
+export {};

package/dist/file-explorer/FileTable.d.ts

@@ -0,0 +1,26 @@
+import { type OpenMenu, type RowMenuItem } from '../list/index.js';
+import type { TreeNode } from './lib/types.js';
+interface FileTableProps {
+    nodes: TreeNode[];
+    checkedItems: Set<string>;
+    allSelected: boolean;
+    someSelected: boolean;
+    onSelectAll: () => void;
+    getItems: (node: TreeNode) => RowMenuItem[];
+    openMenu: OpenMenu;
+    onOpen: (node: TreeNode) => void;
+    onToggleCheck: (node: TreeNode, checked: boolean) => void;
+    onPreview: (node: TreeNode) => void;
+    /** Set when the folder has pages left to fetch. */
+    loadMore?: {
+        loading: boolean;
+        error: string | undefined;
+        auto: boolean;
+        onLoadMore: () => void;
+    } | undefined;
+}
+/** The file table. Give it a `key` of the folder path: a folder change must reset
+ *  the cursor, the scroll offset and the virtualizer's measurements, and a remount
+ *  does all three without a synchronising effect. */
+export declare function FileTable({ nodes, checkedItems, allSelected, someSelected, onSelectAll, getItems, openMenu, onOpen, onToggleCheck, onPreview, loadMore, }: FileTableProps): import("react").JSX.Element;
+export {};

package/dist/file-explorer/FileTableHeaders.d.ts

@@ -0,0 +1,13 @@
+interface FileTableHeadersProps {
+    allSelected: boolean;
+    someSelected: boolean;
+    /** Takes no event: the box is indeterminate-but-unchecked while pages remain. */
+    onSelectAll: () => void;
+}
+/** Carries `isTableHeader` so `Table` hoists these into `<thead>`; a bare fragment
+ *  would land in `<tbody>`, since Children.toArray only flattens arrays. */
+export declare function FileTableHeaders({ allSelected, someSelected, onSelectAll, }: FileTableHeadersProps): import("react").JSX.Element;
+export declare namespace FileTableHeaders {
+    var isTableHeader: boolean;
+}
+export {};

package/dist/file-explorer/LoadMoreRow.d.ts

@@ -0,0 +1,15 @@
+/** The virtualizer sizes this row from the constant, never by measuring it. */
+export declare const LOAD_MORE_ROW_HEIGHT = 45;
+interface LoadMoreRowProps {
+    rowId: string;
+    rowIndex: number;
+    loading: boolean;
+    error: string | undefined;
+    /** False past the auto-load cap, where the user asks for each page. */
+    auto: boolean;
+    /** The table's scroll container, so proximity is not measured against the page. */
+    root: HTMLElement | null;
+    onLoadMore: () => void;
+}
+export declare function LoadMoreRow({ rowId, rowIndex, loading, error, auto, root, onLoadMore, }: LoadMoreRowProps): import("react").JSX.Element;
+export {};

package/dist/file-explorer/TreeView.d.ts

@@ -0,0 +1,28 @@
+import type { TreeNode } from './lib/types.js';
+/** Row pitch, with `space-y-0.5` folded in: absolutely positioned rows cannot use
+ *  sibling margins. useTreePitchAudit warns if this drifts from the DOM. */
+export declare const TREE_ROW_HEIGHT = 30;
+export declare const TREE_SKELETON_HEIGHT = 64;
+interface TreeViewProps {
+    rootNodes: TreeNode[];
+    parentToChildrenMap: Record<string, TreeNode[]>;
+    expandedPaths: ReadonlySet<string>;
+    selectedPath: string;
+    loadingPaths: ReadonlySet<string>;
+    onToggleExpand: (path: string) => void;
+    onSelect: (path: string, node: TreeNode) => void;
+    onDropToFolder: (folderPath: string, files: FileList | DataTransferItemList) => void;
+    onContextMenu: (e: React.MouseEvent, node: TreeNode) => void;
+    onPreviewFile: (node: TreeNode) => void;
+    /** Directories with pages left to fetch, and how to fetch them. */
+    paging?: {
+        incompletePaths: ReadonlySet<string>;
+        isLoading: (path: string) => boolean;
+        hasFailed: (path: string) => boolean;
+        onLoadMore: (node: TreeNode) => void;
+    } | undefined;
+}
+/** The sidebar tree, flattened and windowed. The flat array is the single source
+ *  of truth for rendering, arrow keys and ARIA. */
+export declare function TreeView({ rootNodes, parentToChildrenMap, expandedPaths, selectedPath, loadingPaths, onToggleExpand, onSelect, onDropToFolder, onContextMenu, onPreviewFile, paging, }: TreeViewProps): import("react").JSX.Element;
+export {};

package/dist/file-explorer/helpers.d.ts

@@ -0,0 +1,47 @@
+import type { TreeNode, TStorage, UploadNode } from './lib/types.js';
+import { type JSX } from 'react';
+declare const SIDEBAR_WIDTH_STORAGE_KEY = "fileExplorerSidebarWidth";
+declare const SIDEBAR_WIDTH_DEFAULT = 300;
+type StorageIconUrlResolver = (args: {
+    type: string;
+}) => string | undefined;
+declare function getNodeIcon(node: TreeNode, storageIconUrl?: StorageIconUrlResolver, storageIconAlt?: string): JSX.Element | null;
+declare function renderUploadNodes(uploadNodes: UploadNode[]): JSX.Element[];
+declare function NoFileSelectedPreview(): JSX.Element;
+/** Shown instead of a skeleton that has nothing left to wait for. */
+declare function NotFoundPreview({ path, onRetry, }: {
+    path: string;
+    onRetry: () => void;
+}): JSX.Element;
+export type CorsAwareRefresh = (opts?: {
+    silent?: boolean;
+}) => Promise<{
+    corsError: boolean;
+} | void>;
+declare function CorsIssuePreview({ selectedStorage, onRefresh, }: {
+    selectedStorage: TStorage | null;
+    onRefresh?: CorsAwareRefresh;
+}): JSX.Element;
+declare function NoDataAvailablePreview({ selectedStorage, error, onRefresh, connectionIssueMessage, className, canWrite, }: {
+    selectedStorage: TStorage | null;
+    error?: Error | null;
+    onRefresh?: CorsAwareRefresh;
+    connectionIssueMessage?: string | null;
+    className?: string;
+    canWrite?: boolean;
+}): JSX.Element;
+declare function SkeletonPreview({ variant, }?: {
+    variant?: 'classic' | 'modern';
+}): JSX.Element;
+interface IDragDropZoneProps {
+    onDropFiles?: ((files: FileList | DataTransferItemList) => void) | undefined;
+    children: React.ReactNode;
+    className?: string;
+}
+declare function DragDropZone({ onDropFiles, children, className, }: IDragDropZoneProps): JSX.Element;
+interface IShareFileButtonProps {
+    node: TreeNode;
+    onShare: (node: TreeNode) => Promise<void>;
+}
+declare function ShareFileButton({ node, onShare }: IShareFileButtonProps): JSX.Element;
+export { CorsIssuePreview, DragDropZone, getNodeIcon, NoFileSelectedPreview, NoDataAvailablePreview, NotFoundPreview, renderUploadNodes, ShareFileButton, SIDEBAR_WIDTH_DEFAULT, SIDEBAR_WIDTH_STORAGE_KEY, SkeletonPreview, };

package/dist/file-explorer/index.d.ts

@@ -0,0 +1,10 @@
+export { default as FileExplorer } from './FileExplorer.js';
+export { FileExplorerProvider, useFileExplorer, } from './FileExplorerContext.js';
+export { NoDataAvailablePreview, SkeletonPreview } from './helpers.js';
+export type { FileExplorerDeleteFilesResult, FileExplorerGetFileResult, IFileExplorerClient, IFileExplorerProvider, } from './lib/fileExplorer.js';
+export type { TListPageRequest } from './lib/paging.js';
+export { LIST_PAGE_SIZE } from './lib/paging.js';
+export type { TreeNode, TStorage, TStorageObject } from './lib/types.js';
+export { CorsError } from './lib/errors.js';
+export { chunk, mapWithConcurrency, paginate } from './lib/batch.js';
+export { collectObjectKeysToDelete, getObjectKeyFromNode, isClientValid, removeLeadingAndTrailingSlashes, } from './lib/utils.js';