@arbidocs/blocks 0.4.154 → 0.4.155

package/dist/connection/files/DocumentSyncGlyph.d.ts

@@ -0,0 +1,28 @@
+/**
+ * DocumentSyncGlyph
+ *
+ * Marks a document that's saved on THIS device for offline use — the
+ * OneDrive/Drive "available offline" convention: a small badge on the file icon.
+ * A down-arrow-to-line (the universal "downloaded / saved locally" glyph) so it
+ * reads instantly as "kept on my device" — clearer than a hard-drive icon and
+ * never confused with the "ready" checkmark. A neutral grey badge: ambient
+ * metadata, not a status to draw the eye (the document "ready" status owns the
+ * coloured cyan/navy treatment).
+ *
+ * Pending offline edits are shown separately, as a "changes pending" document
+ * status in the Status column — not here — so the file icon stays quiet and only
+ * the genuinely-useful "you can open this offline" signal lives on it.
+ *
+ * Self-subscribing to the offline set so it updates even inside a memoized grid
+ * cell. Renders nothing for cloud-only docs (the common case).
+ */
+interface DocumentSyncGlyphProps {
+    docExtId: string;
+    size?: number;
+    className?: string;
+    /** Badge fill — neutral grey by default; pass e.g. `bg-green-600` for a
+     *  prominent "downloaded" badge. */
+    bgClassName?: string;
+}
+export declare function DocumentSyncGlyph({ docExtId, size, className, bgClassName, }: DocumentSyncGlyphProps): import("react").JSX.Element | null;
+export {};

package/dist/connection/files/explorer/ConnectedFilesExplorer.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The workspace's files as a file explorer (OneDrive / Drive style), bound to the session: folders
+ * come from each document's `folder` path; renames, moves and deletes are written through
+ * `@arbidocs/react`.
+ *
+ *  - Breadcrumb navigation is the host's (`folderPath` / `onFolderPathChange`): it may keep the
+ *    folder in a filter, the URL or state.
+ *  - A virtualised tile grid that scales to thousands of documents, sized by `tileSize`.
+ *  - OS-style selection: click, ⌘/Ctrl-click, shift-range, the hover checkbox and a marquee.
+ *  - Drag files onto a folder tile to move them; drop OS files on the view to upload.
+ *
+ * Selection is the host's (`selectedIds` / `onSelectionChange`), so its bulk actions act on it.
+ */
+import { type ReactNode } from 'react';
+import { type ExplorerFolder, type ExplorerSort } from '../../../files/folders';
+import { type FileTileDocument } from './FileTiles';
+/** The zoom slider's bounds: the target tile width in px (smaller: more tiles per row). */
+export declare const TILE_MIN = 88;
+export declare const TILE_MAX = 232;
+export declare const TILE_DEFAULT = 200;
+export interface ConnectedFilesExplorerHandle {
+    /** Add a placeholder folder here and start naming it. */
+    triggerNewFolder: () => void;
+    /** Scroll the tile of `docId` into view, when it is displayed. */
+    scrollToDocument: (docId: string) => void;
+}
+export interface ConnectedFilesExplorerProps {
+    documents: FileTileDocument[];
+    isLoading: boolean;
+    /** The viewer may add, rename and move files here. */
+    canUpload: boolean;
+    selectedIds: string[];
+    onSelectionChange: (ids: string[]) => void;
+    onOpenDocument: (docId: string) => void;
+    onUploadFiles: (files: File[], folder?: string | null) => void;
+    /** The open folder (empty: the workspace root). */
+    folderPath: readonly string[];
+    onFolderPathChange: (path: string[]) => void;
+    /** A search across every folder (absent or empty: the open folder is listed). */
+    search?: string;
+    sort: ExplorerSort;
+    sortReversed: boolean;
+    /** The target tile width in px (`TILE_MIN`..`TILE_MAX`). */
+    tileSize: number;
+    /** The ids of the files displayed, in display order (a navigator steps the same list). */
+    onOrderedFilesChange?: (docIds: string[]) => void;
+    /** Move the selected files: the host opens its folder picker. Absent: not offered. */
+    onMoveSelected?: () => void;
+    /** Move a folder with its structure: the host opens its folder picker. */
+    onFolderMove?: (folder: ExplorerFolder) => void;
+    /** Open a document in the host's review view. Absent: not offered. */
+    onOpenInReview?: (docId: string) => void;
+    /** Shown instead of the explorer while the workspace has no documents and the viewer may add. */
+    emptyWorkspace?: ReactNode;
+}
+export declare const ConnectedFilesExplorer: import("react").ForwardRefExoticComponent<ConnectedFilesExplorerProps & import("react").RefAttributes<ConnectedFilesExplorerHandle>>;

package/dist/connection/files/explorer/FileTiles.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The explorer's one tile binding. The presentation (`ExplorerFileTile`, `ExplorerFolderTile`,
+ * `ExplorerFileTooltip`) is in `files/`; this binds it to the session: @dnd-kit draggable and
+ * droppable, the document's live processing status, the copies kept offline, the open viewer, the
+ * document pill, the mail handoff and the member / label lookups. `FileTile` is a draggable
+ * document, `FolderTile` a droppable folder (separate components so the dnd hooks always run).
+ */
+import { type WorkspaceDocument } from '@arbidocs/react';
+import { type ExplorerDensity, type ExplorerMenuItem } from '../../../files/ExplorerTile';
+import { type ExplorerFolder } from '../../../files/folders';
+import { type FilesStartItem } from '../support';
+export type { ExplorerDensity };
+/** A workspace member as a tile shows them (avatar and name). */
+export interface FileTileUser {
+    external_id: string;
+    given_name: string;
+    family_name?: string | null;
+    email: string;
+    picture?: string | null;
+}
+/** A document row as the tiles read it (the session's rows carry these). */
+export type FileTileDocument = WorkspaceDocument & {
+    failed_stage?: string | null;
+};
+/** Whether a status is still being worked on. */
+export declare function isActiveDocumentStatus(status: string): boolean;
+/** The hover card of a document: the same in the explorer tiles and the table's name cell. */
+export declare function FileTooltipContent({ doc, modifiedBy, tagNameById, }: {
+    doc: FileTileDocument;
+    modifiedBy?: FileTileUser;
+    tagNameById: ReadonlyMap<string, string>;
+}): import("react").JSX.Element;
+/** The "Start…" submenu: one entry per thing the host can start on the file or folder. */
+export declare function startMenuItem(items: readonly FilesStartItem[]): ExplorerMenuItem[];
+interface FileTileProps {
+    doc: FileTileDocument;
+    density: ExplorerDensity;
+    selected: boolean;
+    /** Part of an in-flight drag (dimmed). */
+    dragging: boolean;
+    /** Any tile is being dragged: no hover card, so it cannot swallow the moves dnd-kit tracks. */
+    dndActive: boolean;
+    /** Being renamed inline. */
+    renaming: boolean;
+    /** The viewer may delete this document. */
+    canDelete: boolean;
+    /** The first-page thumbnail (absent: the file-type icon). */
+    thumbnailUrl?: string;
+    /** Who last changed the document (the hover card's avatar line). */
+    modifiedBy?: FileTileUser;
+    /** Label id → name, for the document's labels on the hover card. */
+    tagNameById: ReadonlyMap<string, string>;
+    onSelect: (doc: FileTileDocument, e: React.MouseEvent) => void;
+    onToggle: (doc: FileTileDocument, e: React.MouseEvent) => void;
+    onOpen: (doc: FileTileDocument) => void;
+    /** Open the document in the review view. Absent: not offered. */
+    onReview?: (doc: FileTileDocument) => void;
+    onStartRename: (doc: FileTileDocument) => void;
+    onCommitRename: (doc: FileTileDocument, name: string) => void;
+    onCancelRename: () => void;
+    onDownload: (doc: FileTileDocument) => void;
+    onMove?: (doc: FileTileDocument) => void;
+    onDelete: (doc: FileTileDocument) => void;
+}
+export declare const FileTile: import("react").NamedExoticComponent<FileTileProps>;
+interface FolderTileProps {
+    folder: ExplorerFolder;
+    density: ExplorerDensity;
+    /** Being renamed inline. */
+    editing?: boolean;
+    /** Every document beneath the folder is selected. */
+    selected?: boolean;
+    /** Some (not all) documents beneath the folder are selected. */
+    partiallySelected?: boolean;
+    /** Every document beneath the folder (its count of files still processing). */
+    documents: readonly FileTileDocument[];
+    onOpen: (folder: ExplorerFolder) => void;
+    /** Toggle the whole folder (all its documents). */
+    onToggleSelect?: (folder: ExplorerFolder, e: React.MouseEvent) => void;
+    onCommitName?: (folder: ExplorerFolder, name: string) => void;
+    onCancelName?: () => void;
+    onStartRename?: (folder: ExplorerFolder) => void;
+    onDownload?: (folder: ExplorerFolder) => void;
+    onMove?: (folder: ExplorerFolder) => void;
+    onDelete?: (folder: ExplorerFolder) => void;
+}
+export declare const FolderTile: import("react").NamedExoticComponent<FolderTileProps>;

package/dist/connection/files/index.d.ts

@@ -0,0 +1,5 @@
+export { ConnectedFilesExplorer, TILE_DEFAULT, TILE_MAX, TILE_MIN, type ConnectedFilesExplorerHandle, type ConnectedFilesExplorerProps, } from './explorer/ConnectedFilesExplorer';
+export { FileTooltipContent, isActiveDocumentStatus, startMenuItem, type FileTileDocument, type FileTileUser, } from './explorer/FileTiles';
+export { DocumentSyncGlyph } from './DocumentSyncGlyph';
+export { FilesSupportProvider, useFilesSupport, useOfflineDocumentIds, useViewingDocumentId, type FilesStartItem, type FilesSupport, } from './support';
+export { useFilesStore, usePendingFolders } from './store';

package/dist/connection/files/store.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The Files kits' own state: empty folders the user created (a folder exists only through its
+ * documents, so a new one is a placeholder until something is moved into it), per workspace, for
+ * the session (kept in `sessionStorage`, so a reload keeps them).
+ */
+interface FilesState {
+    /** Placeholder folder paths per workspace. */
+    pendingFolders: Readonly<Record<string, readonly string[]>>;
+    addPendingFolder: (workspaceId: string, path: string) => void;
+    removePendingFolder: (workspaceId: string, path: string) => void;
+}
+export declare const useFilesStore: import("zustand").UseBoundStore<Omit<import("zustand").StoreApi<FilesState>, "setState" | "persist"> & {
+    setState(partial: FilesState | Partial<FilesState> | ((state: FilesState) => FilesState | Partial<FilesState>), replace?: false | undefined): unknown;
+    setState(state: FilesState | ((state: FilesState) => FilesState), replace: true): unknown;
+    persist: {
+        setOptions: (options: Partial<import("zustand/middleware").PersistOptions<FilesState, unknown, unknown>>) => void;
+        clearStorage: () => void;
+        rehydrate: () => Promise<void> | void;
+        hasHydrated: () => boolean;
+        onHydrate: (fn: (state: FilesState) => void) => () => void;
+        onFinishHydration: (fn: (state: FilesState) => void) => () => void;
+        getOptions: () => Partial<import("zustand/middleware").PersistOptions<FilesState, unknown, unknown>>;
+    };
+}>;
+/** A workspace's placeholder folders. */
+export declare function usePendingFolders(workspaceId: string | null | undefined): readonly string[];
+export {};

package/dist/connection/files/support.d.ts

@@ -0,0 +1,38 @@
+/**
+ * What a host adds to the connected Files kits (explorer, table, page). The kits read and write the
+ * documents on the signed-in session by themselves (`@arbidocs/react`); these are the host's own
+ * things they cannot know: its workflows ("Start…"), its chat, its mail, the copies it keeps
+ * offline, its viewer. Every field is optional: without one a kit offers less, never something
+ * that does nothing.
+ */
+import { type ReactNode } from 'react';
+import type { WorkspaceDocument } from '@arbidocs/react';
+/** Something the host can start on documents or a folder (a workflow, a skill). */
+export interface FilesStartItem {
+    id: string;
+    title: string;
+    run: () => void;
+}
+export interface FilesSupport {
+    /** What can be started on one file. */
+    startItemsForFile?: (document: WorkspaceDocument) => FilesStartItem[];
+    /** What can be started on everything in a folder (workflows that take a set of files). */
+    startItemsForFolder?: (folderPath: string) => FilesStartItem[];
+    /** Start a chat about one document. Absent: not offered. */
+    openDocumentChat?: (docId: string) => void;
+    /** Hand a document to the host's mail composer as an attachment (offered while mail is on). */
+    emailDocument?: (document: WorkspaceDocument) => Promise<void>;
+    /** The documents kept on this device for offline use, as a hook. */
+    useOfflineDocumentIds?: () => ReadonlySet<string>;
+    /** The document open in the host's viewer, as a hook (its tile is marked); null when closed. */
+    useViewingDocumentId?: () => string | null;
+}
+export declare function FilesSupportProvider({ value, children, }: {
+    value: FilesSupport;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useFilesSupport(): FilesSupport;
+/** The documents kept offline (none without host support). */
+export declare function useOfflineDocumentIds(): ReadonlySet<string>;
+/** The document open in the host's viewer (none without host support). */
+export declare function useViewingDocumentId(): string | null;

package/dist/files/DocStatusIcon.d.ts

@@ -1,12 +1,13 @@
-import type { ReactNode } from 'react';
 export interface DocStatusIconProps {
     /** Document processing status (case-insensitive); unknown / empty renders nothing. */
     status?: string | null;
     /** Activating the glyph (click, Enter, Space) e.g. opens the status details. */
     onClick?: () => void;
-    /** The `failed` glyph is stage-aware and host-supplied. */
-    failed?: ReactNode;
+    /** Where a failed document's processing stopped (the failed glyph differs per stage). */
+    failedStage?: string | null;
+    /** Why it failed, added to the failed glyph's title. */
+    errorMessage?: string | null;
     className?: string;
 }
 /** Compact status glyph of a document row (ready, empty, low content, indexing, queued, failed). */
-export declare function DocStatusIcon({ status, onClick, failed, className }: DocStatusIconProps): import("react").JSX.Element | null;
+export declare function DocStatusIcon({ status, onClick, failedStage, errorMessage, className, }: DocStatusIconProps): import("react").JSX.Element | null;

package/dist/files/FailedStageIcon.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Stage-aware failure icon.
+ *
+ * All variants share the red color and "alert" weight so the cell still
+ * reads as "failure" at a glance, but the glyph differs per pipeline
+ * stage so users can tell *where* it died without opening details.
+ *
+ * Backend taxonomy (mirrors src/models/document.py FAILABLE_STAGES):
+ *   parsing    — parser service: extraction / OCR / marker-subchunk
+ *   indexing   — Qdrant chunk + vector writes
+ *   encrypting — SecretBox wrap of chunks/metadata
+ *   analysing  — doctagllm metadata extraction
+ *   queued     — failed before processing started
+ *   unknown    — current code couldn't classify (defensive fallback)
+ *   null       — legacy failure predating the failed_stage column;
+ *                rendered as "Failed (stage unknown)"
+ */
+export type FailedStage = 'parsing' | 'indexing' | 'encrypting' | 'analysing' | 'queued' | 'unknown';
+interface FailedStageIconProps {
+    stage: string | null | undefined;
+    errorMessage?: string | null;
+    className?: string;
+    onClick?: (e: React.MouseEvent) => void;
+}
+export declare const FailedStageIcon: import("react").NamedExoticComponent<FailedStageIconProps>;
+export {};

package/dist/files/folders/FolderProviderIcon.d.ts

@@ -0,0 +1,29 @@
+/**
+ * folderProviderIcon
+ *
+ * Maps a folder path to the brand mark of the connector that imported it, so
+ * connector-created folders (e.g. "Outlook (jane@arbi.city)") show their
+ * source at a glance. Only the ROOT segment is matched — nested subfolders
+ * keep the generic folder icon. Returns null when the root isn't a known
+ * provider (including the legacy bare "Email" root), letting call sites fall
+ * back to their existing folder glyph.
+ */
+/**
+ * Provider brand mark for a folder path's root segment, or null when the
+ * folder isn't a connector import (call sites render their usual icon).
+ */
+export declare function FolderProviderIcon({ folderPath, className, }: {
+    folderPath: string;
+    className?: string;
+}): import("react").JSX.Element | null;
+/** True when the folder path's root segment belongs to a known connector. */
+export declare function hasFolderProviderIcon(folderPath: string): boolean;
+/**
+ * Display text for a single folder path segment. Provider roots drop the
+ * provider name — the brand mark already says it — leaving just the account:
+ *   "Outlook (jane@arbi.city)" → "jane@arbi.city"
+ *   "Outlook" (legacy bare root) → "" (the logo stands alone)
+ * Non-provider segments are returned unchanged. Stored paths are untouched;
+ * this is display-only.
+ */
+export declare function formatFolderSegment(segment: string): string;

package/dist/files/folders/folderPaths.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Pure helpers that turn the flat document list into a navigable folder tree.
+ *
+ * Folders are not a backend entity — each document carries a slash-separated
+ * `folder` path string (e.g. `"Reports/Q1"`, or `null`/`""` for the root).
+ * These helpers derive, for a given path, the immediate sub-folders (with
+ * descendant counts) and the files that live directly in that folder. Kept
+ * pure and side-effect-free so the navigation logic is unit-testable.
+ */
+/** The fields of a document the folder view reads. */
+export interface FolderDocument {
+    external_id: string;
+    file_name?: string | null;
+    file_type?: string | null;
+    file_size?: number | null;
+    folder?: string | null;
+    parent_ext_id?: string | null;
+    created_at?: string | null;
+    doc_metadata?: {
+        title?: string | null;
+    } | null;
+}
+export interface ExplorerFolder {
+    kind: 'folder';
+    /** The folder's own name (last path segment). */
+    name: string;
+    /** Full path segments from the root, including this folder. */
+    path: string[];
+    /** Number of documents anywhere beneath this folder. */
+    count: number;
+}
+export interface ExplorerFile<D extends FolderDocument = FolderDocument> {
+    kind: 'file';
+    doc: D;
+}
+export type ExplorerEntry<D extends FolderDocument = FolderDocument> = ExplorerFolder | ExplorerFile<D>;
+export type ExplorerSort = 'name' | 'date' | 'size';
+/**
+ * Display name for a document in the explorer, with its real file extension —
+ * the familiar "Report.pdf" form. Many documents store an AI-generated display
+ * title that drops the extension, so we re-attach it from the stored
+ * `file_name` or, failing that, the MIME `file_type`.
+ */
+export declare function getExplorerDisplayName(doc: FolderDocument): string;
+/** Split a `Doc.folder` value into trimmed, non-empty path segments. */
+export declare function parseFolderSegments(folder?: string | null): string[];
+/** Join path segments back into a canonical `Doc.folder` string (or null at root). */
+export declare function joinFolderPath(segments: string[]): string | null;
+/**
+ * A document is shown in the explorer unless it belongs to an email family:
+ * attachments and archived messages (`parent_ext_id` set) live "inside" their
+ * email / archive and would otherwise clutter the folder view. Versions are not
+ * children — the list holds each document's current version only.
+ */
+export declare function isExplorerDocument(doc: FolderDocument): boolean;
+/**
+ * Every explorer document that lives anywhere beneath `path` (directly in the
+ * folder or in a sub-folder). Used to expand a folder into the documents a
+ * folder-level action (select / move / download / delete / rename) applies to —
+ * "act on a folder" means "act on everything in it".
+ */
+export declare function collectFolderDocs<D extends FolderDocument>(documents: D[], path: string[]): D[];
+/**
+ * Documents in the order the gallery shows them for a sort choice (and its
+ * direction toggle). Review mode steps through this same order.
+ */
+export declare function sortExplorerFiles<D extends FolderDocument>(docs: D[], sort: ExplorerSort, reversed?: boolean): D[];
+/**
+ * Build the folders and files that live directly under `currentPath`.
+ *
+ * - Files: documents whose folder path exactly equals `currentPath`.
+ * - Folders: the distinct next path segment of any document nested deeper than
+ *   `currentPath`, with `count` = number of documents beneath it.
+ *
+ * Folders are always sorted by name; files by the requested sort.
+ */
+export declare function buildExplorerEntries<D extends FolderDocument>(documents: D[], currentPath: string[], sort?: ExplorerSort, pendingFolders?: string[]): {
+    folders: ExplorerFolder[];
+    files: D[];
+};
+/**
+ * Flat, cross-folder search over every top-level document by title / file name.
+ * Used when the explorer search box is non-empty (mirrors real file explorers,
+ * which flatten results and ignore the current folder while searching).
+ */
+export declare function searchExplorerDocuments<D extends FolderDocument>(documents: D[], query: string, sort?: ExplorerSort): D[];

package/dist/files/folders/index.d.ts

@@ -0,0 +1,2 @@
+export { getExplorerDisplayName, parseFolderSegments, joinFolderPath, isExplorerDocument, collectFolderDocs, sortExplorerFiles, buildExplorerEntries, searchExplorerDocuments, type FolderDocument, type ExplorerFolder, type ExplorerFile, type ExplorerEntry, type ExplorerSort, } from './folderPaths';
+export { FolderProviderIcon, hasFolderProviderIcon, formatFolderSegment, } from './FolderProviderIcon';