@bendyline/docblocks-react 2.2.1 → 2.3.0

package/dist/index.d.ts

@@ -1,12 +1,13 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { FileSystemProvider, FileSystemEntry } from '@bendyline/docblocks/filesystem';
+import { FileSystemProvider, FileSystemEntry, FsErrorCode } from '@bendyline/docblocks/filesystem';
 import { WorkspaceDescriptor } from '@bendyline/docblocks/workspace';
 import { EditorColorScheme } from '@bendyline/squisq-editor-react';
 import { FfmpegWasmLoadConfig } from '@bendyline/squisq-video';
 import { PrunePolicy, SaveVersionResult, DocumentVersionManager } from '@bendyline/squisq/versions';
 import { ThemePreference, AccentColor, WriteCanvasPreferences } from './settings/index.js';
-export { AccentColorSettings, AccentColorSettingsProps, SettingsDialog, SettingsDialogProps, ThemeSettings, ThemeSettingsProps, WriteCanvasSettingsControls, WriteCanvasSettingsControlsProps } from './settings/index.js';
+export { AccentColorSettings, AccentColorSettingsProps, DEFAULT_WRITE_CANVAS_FONT_SCHEME, SettingsDialog, SettingsDialogProps, ThemeSettings, ThemeSettingsProps, WRITE_CANVAS_FONT_SCHEMES, WriteCanvasFontScheme, WriteCanvasFontSchemeGroup, WriteCanvasFontSchemeOption, WriteCanvasSettingsControls, WriteCanvasSettingsControlsProps, resolveWriteCanvasFonts } from './settings/index.js';
 import { SharedDocumentMode } from '@bendyline/docblocks/share';
+import { MediaProvider } from '@bendyline/squisq/schemas';
 import { ContentContainer } from '@bendyline/squisq/storage';
 import { VideoExportModalProps } from '@bendyline/squisq-video-react';
 import { ExportBlobSaver } from './export/index.js';
@@ -15,6 +16,19 @@ import { DocumentSession, DocumentSessionSnapshot } from '@bendyline/docblocks/d
 import 'react';
 import '@bendyline/squisq-formats/pptx';
 
+interface PinnedDocument {
+    readonly workspaceId: string;
+    readonly workspaceName: string;
+    /** Canonical, root-relative workspace path. */
+    readonly path: string;
+}
+type PinnedDocumentAvailability = 'unknown' | 'available' | 'missing';
+interface PinnedDocumentListItem extends PinnedDocument {
+    readonly availability: PinnedDocumentAvailability;
+}
+
+type FileExplorerSortMode = 'name' | 'last-modified';
+
 type FileTreeChange = {
     type: 'create';
     path: string;
@@ -37,8 +51,30 @@ interface WorkspaceMoveDestination {
 interface FileExplorerProps {
     /** The filesystem to display. */
     provider: FileSystemProvider | null;
+    /** Changes after a non-watch provider has durably updated file metadata. */
+    metadataRefreshKey?: string | number | null;
     /** Active document to select and reveal by expanding all ancestor folders. */
     activeFilePath?: string | null;
+    /** Presentation order for files within each directory. */
+    sortMode?: FileExplorerSortMode;
+    /** Called when a file ordering toolbar button is selected. */
+    onSortModeChange?: (mode: FileExplorerSortMode) => void;
+    /** Active workspace identity, used to decorate a selected cross-workspace pin. */
+    activeWorkspaceId?: string | null;
+    /** Documents pinned across every workspace, shown above the active file tree. */
+    pinnedDocuments?: readonly PinnedDocumentListItem[];
+    /** Canonical paths pinned inside the active workspace. */
+    pinnedPaths?: readonly string[];
+    /** Opens a pinned document, switching workspace when necessary. */
+    onPinnedDocumentSelect?: (document: PinnedDocumentListItem) => void;
+    /** Removes a document from the global pinned list. */
+    onPinnedDocumentUnpin?: (document: PinnedDocumentListItem) => void | Promise<void>;
+    /** Renames a pinned document without requiring its workspace to be active. */
+    onPinnedDocumentRename?: (document: PinnedDocumentListItem) => void | Promise<void>;
+    /** Deletes a pinned document without requiring its workspace to be active. */
+    onPinnedDocumentDelete?: (document: PinnedDocumentListItem) => void | Promise<void>;
+    /** Pins or unpins a file in the active workspace. */
+    onTogglePin?: (path: string) => void | Promise<void>;
     /** Called when any entry is selected (file or directory). */
     onSelect?: (path: string, kind: 'file' | 'directory') => void;
     /**
@@ -63,7 +99,7 @@ interface FileExplorerProps {
     /** Optional className for the root element. */
     className?: string;
 }
-declare function FileExplorer({ provider, activeFilePath, onSelect, onTreeMutation, onTreeChange, onImportFiles, confirmDelete, moveDestinations, onMoveToWorkspace, className, }: FileExplorerProps): react_jsx_runtime.JSX.Element;
+declare function FileExplorer({ provider, metadataRefreshKey, activeFilePath, sortMode, onSortModeChange, activeWorkspaceId, pinnedDocuments, pinnedPaths, onPinnedDocumentSelect, onPinnedDocumentUnpin, onPinnedDocumentRename, onPinnedDocumentDelete, onTogglePin, onSelect, onTreeMutation, onTreeChange, onImportFiles, confirmDelete, moveDestinations, onMoveToWorkspace, className, }: FileExplorerProps): react_jsx_runtime.JSX.Element;
 
 /** Git decoration for a row — precomputed by FileExplorer so this node stays context-free. */
 interface FileTreeNodeBadge {
@@ -109,6 +145,10 @@ interface FileTreeNodeProps {
     confirmDelete?: (message: string) => boolean | Promise<boolean>;
     onDelete: (path: string, kind: 'file' | 'directory') => Promise<void>;
     onRename: (oldPath: string, newPath: string, kind: 'file' | 'directory') => Promise<void>;
+    /** Whether this document is present in the shell's cross-workspace pin list. */
+    pinned?: boolean;
+    /** Pin or unpin this file. Omitted for directories and standalone trees. */
+    onTogglePin?: (path: string) => void | Promise<void>;
     draggable?: boolean;
     dragging?: boolean;
     dropTarget?: boolean;
@@ -117,14 +157,26 @@ interface FileTreeNodeProps {
     onDragOverEntry?: (event: React.DragEvent, entry: FileSystemEntry) => void;
     onDropEntry?: (event: React.DragEvent, entry: FileSystemEntry) => void;
     renderChildren?: (dirPath: string) => React.ReactNode;
+    /** Path-scoped directory loading failure, rendered outside the ARIA tree group. */
+    childError?: React.ReactNode;
 }
-declare function FileTreeNode({ entry, depth, expanded, selected, badge, gitActions, focusable, posInSet, setSize, onRowFocus, onToggle, onSelect, confirmDelete, onDelete, onRename, draggable, dragging, dropTarget, onDragStart, onDragEnd, onDragOverEntry, onDropEntry, renderChildren, }: FileTreeNodeProps): react_jsx_runtime.JSX.Element;
+declare function FileTreeNode({ entry, depth, expanded, selected, badge, gitActions, focusable, posInSet, setSize, onRowFocus, onToggle, onSelect, confirmDelete, onDelete, onRename, pinned, onTogglePin, draggable, dragging, dropTarget, onDragStart, onDragEnd, onDragOverEntry, onDropEntry, renderChildren, childError, }: FileTreeNodeProps): react_jsx_runtime.JSX.Element;
 
 /**
  * useFileTree — hook that reads from a FileSystemProvider,
  * maintains expanded/collapsed state, and provides CRUD operations.
  */
 
+interface FileTreeReadIssue {
+    /** Directory whose listing was requested, in canonical workspace-relative form. */
+    readonly directoryPath: string;
+    /** Exact failing path supplied by the filesystem error. */
+    readonly path: string;
+    readonly code: FsErrorCode;
+    readonly message: string;
+    /** Whether another user-initiated attempt can reasonably succeed. */
+    readonly retryable: boolean;
+}
 interface FileTreeState {
     /** Flat list of entries for the current directory view. */
     entries: FileSystemEntry[];
@@ -136,8 +188,14 @@ interface FileTreeState {
     selectedKind: 'file' | 'directory' | null;
     /** Whether the tree is loading. */
     loading: boolean;
-    /** Latest provider/read/watch failure, cleared by a successful refresh. */
+    /** Root provider/read/watch failure, retained for backwards compatibility. */
     error: string | null;
+    /** Structured root failure, including its exact filesystem path. */
+    rootIssue: FileTreeReadIssue | null;
+    /** Failures scoped to expanded child directories. */
+    childIssues: ReadonlyMap<string, FileTreeReadIssue>;
+    /** Cached listings for expanded child directories. */
+    childEntries: ReadonlyMap<string, FileSystemEntry[]>;
 }
 interface FileTreeActions {
     /** Toggle a directory's expanded state. */
@@ -156,8 +214,10 @@ interface FileTreeActions {
     renameEntry: (oldPath: string, newPath: string, kind?: 'file' | 'directory') => Promise<void>;
     /** Force refresh the tree. */
     refresh: () => Promise<void>;
+    /** Retry one failed directory without treating it as a workspace-root failure. */
+    retryDirectory: (path: string) => Promise<void>;
 }
-declare function useFileTree(provider: FileSystemProvider | null): FileTreeState & FileTreeActions;
+declare function useFileTree(provider: FileSystemProvider | null, metadataRefreshKey?: string | number | null, metadataRefreshPath?: string | null): FileTreeState & FileTreeActions;
 
 interface WorkspacePickerProps {
     /** Currently active workspace id. */
@@ -224,13 +284,15 @@ interface DocBlocksShellProps {
     updateAvailable?: boolean;
     /** Activates the waiting update and reloads onto the new version. */
     onApplyUpdate?: () => void;
+    /** Host-supplied content rendered at the right edge of the editor status bar. */
+    statusBarSlotRight?: React.ReactNode;
     /**
      * True once the app has been fully cached for offline use (browser PWA
      * hosts). Shown to the user once as a passive notice.
      */
     offlineReady?: boolean;
 }
-declare function DocBlocksShell({ theme: hostTheme, logoUrl, issueReportVersion, appBuildDate, ffmpegWasm, homeDocumentTitle, homeDocumentPath, allowVersioning, versionBasename, versioningPrunePolicy, versioningAutoSaveIdleMs, onSaveVersion, versioningRef, updateAvailable, onApplyUpdate, offlineReady, }: DocBlocksShellProps): react_jsx_runtime.JSX.Element;
+declare function DocBlocksShell({ theme: hostTheme, logoUrl, issueReportVersion, appBuildDate, ffmpegWasm, homeDocumentTitle, homeDocumentPath, allowVersioning, versionBasename, versioningPrunePolicy, versioningAutoSaveIdleMs, onSaveVersion, versioningRef, updateAvailable, onApplyUpdate, statusBarSlotRight, offlineReady, }: DocBlocksShellProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Versioning preferences — global default + per-workspace resolution.
@@ -305,6 +367,8 @@ interface ExportToolbarControlsProps {
     selectedFile: string | null;
     /** Media container for resolving images during export. */
     mediaContainer?: ContentContainer | null;
+    /** Active document media provider used to preload audio and video export assets. */
+    mediaProvider?: MediaProvider | null;
     /** Override the default browser download behavior for host-provided save flows. */
     saveBlob?: ExportBlobSaver;
     /** Optional host adapter for displaying, picking, and saving to a native target path. */
@@ -354,4 +418,4 @@ interface UseDocumentSessionResult {
  */
 declare function useDocumentSession(autoSaveDelayMs?: number): UseDocumentSessionResult;
 
-export { AccentColor, AppMenu, type AppMenuProps, DocBlocksShell, type DocBlocksShellProps, ExportBlobSaver, type ExportDestinationAdapter, type ExportDestinationTarget, ExportToolbarControls, type ExportToolbarControlsProps, FileExplorer, type FileExplorerProps, type FileTreeChange, type FileTreeMutationHandler, FileTreeNode, type FileTreeNodeProps, ThemePreference, type UseDocumentSessionResult, WorkspacePicker, type WorkspacePickerProps, WriteCanvasPreferences, useDocumentSession, useFileTree };
+export { AccentColor, AppMenu, type AppMenuProps, DocBlocksShell, type DocBlocksShellProps, ExportBlobSaver, type ExportDestinationAdapter, type ExportDestinationTarget, ExportToolbarControls, type ExportToolbarControlsProps, FileExplorer, type FileExplorerProps, type FileExplorerSortMode, type FileTreeActions, type FileTreeChange, type FileTreeMutationHandler, FileTreeNode, type FileTreeNodeProps, type FileTreeReadIssue, type FileTreeState, ThemePreference, type UseDocumentSessionResult, WorkspacePicker, type WorkspacePickerProps, WriteCanvasPreferences, useDocumentSession, useFileTree };