@bendyline/docblocks-react 1.1.2 → 2.1.0

package/dist/index.d.ts

@@ -1,20 +1,348 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { FileSystemProvider, FileSystemEntry } from '@bendyline/docblocks/filesystem';
+import { WorkspaceDescriptor } from '@bendyline/docblocks/workspace';
+import { EditorColorScheme } from '@bendyline/squisq-editor-react';
+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';
+import { SharedDocumentMode } from '@bendyline/docblocks/share';
+import { ContentContainer } from '@bendyline/squisq/storage';
+import { VideoExportModalProps } from '@bendyline/squisq-video-react';
+import { ExportBlobSaver } from './export/index.js';
+export { DEFAULT_OPTIONS, ExportDestinationControl, ExportDialog, ExportDialogProps, ExportFormat, ExportOptions, HtmlBundle, HtmlStyle, buildExportFilename, loadLastExportOptions, runExport } from './export/index.js';
+import { DocumentSession, DocumentSessionSnapshot } from '@bendyline/docblocks/document';
+import 'react';
+
+type FileTreeChange = {
+    type: 'create';
+    path: string;
+    kind?: 'file' | 'directory';
+} | {
+    type: 'delete';
+    path: string;
+    kind: 'file' | 'directory';
+} | {
+    type: 'move';
+    oldPath: string;
+    newPath: string;
+    kind: 'file' | 'directory';
+};
+type FileTreeMutationHandler = (change: FileTreeChange, mutate: () => Promise<void>) => Promise<void>;
+interface WorkspaceMoveDestination {
+    id: string;
+    name: string;
+}
+interface FileExplorerProps {
+    /** The filesystem to display. */
+    provider: FileSystemProvider | null;
+    /** Active document to select and reveal by expanding all ancestor folders. */
+    activeFilePath?: string | null;
+    /** Called when any entry is selected (file or directory). */
+    onSelect?: (path: string, kind: 'file' | 'directory') => void;
+    /**
+     * Wraps destructive tree mutations so the active document session can
+     * flush, cancel, or retarget itself before storage changes.
+     */
+    onTreeMutation?: FileTreeMutationHandler;
+    /** Called after any mutation, with move details when paths change. */
+    onTreeChange?: (change?: FileTreeChange) => void;
+    /** Called when supported files are dropped onto the explorer. */
+    onImportFiles?: (files: File[]) => void;
+    /**
+     * Ask the user to confirm an irreversible delete. Resolve `false` to abort.
+     * Hosts with their own dialog pass it here; otherwise the tree falls back to
+     * a native prompt rather than deleting unasked.
+     */
+    confirmDelete?: (message: string) => boolean | Promise<boolean>;
+    /** Persisted workspaces that can receive the current transient workspace. */
+    moveDestinations?: readonly WorkspaceMoveDestination[];
+    /** When provided, shows the transient-workspace move action above the tree. */
+    onMoveToWorkspace?: (workspaceId: string) => Promise<void>;
+    /** 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;
+
+/** Git decoration for a row — precomputed by FileExplorer so this node stays context-free. */
+interface FileTreeNodeBadge {
+    kind: string;
+    glyph: string;
+    label: string;
+}
+/** Git context-menu actions, prebound to this entry's path. */
+interface FileTreeNodeGitActions {
+    viewChanges?: () => void;
+    fileHistory?: () => void;
+    openOnRemote?: () => void;
+}
+interface FileTreeNodeProps {
+    entry: FileSystemEntry;
+    depth: number;
+    expanded: boolean;
+    selected: boolean;
+    badge?: FileTreeNodeBadge;
+    gitActions?: FileTreeNodeGitActions;
+    children?: FileSystemEntry[];
+    /**
+     * Roving tabindex: true only for the tree's single tab stop. Defaults to
+     * true so a node rendered on its own is still reachable.
+     */
+    focusable?: boolean;
+    /** 1-based position among siblings, for aria-posinset. */
+    posInSet?: number;
+    /** Number of siblings, for aria-setsize. */
+    setSize?: number;
+    /** The row took focus (click or arrow key) — move the roving tab stop. */
+    onRowFocus?: (path: string) => void;
+    onToggle: (path: string) => void;
+    onSelect: (path: string) => void;
+    /**
+     * Ask the user to confirm an irreversible delete. Resolve `false` to abort.
+     *
+     * Optional so a standalone `<FileTreeNode>` still asks before destroying
+     * something; hosts that have their own dialog (as `<DocBlocksShell>` does)
+     * pass it here so the prompt matches the product instead of being a native
+     * browser/Electron dialog.
+     */
+    confirmDelete?: (message: string) => boolean | Promise<boolean>;
+    onDelete: (path: string, kind: 'file' | 'directory') => Promise<void>;
+    onRename: (oldPath: string, newPath: string, kind: 'file' | 'directory') => Promise<void>;
+    draggable?: boolean;
+    dragging?: boolean;
+    dropTarget?: boolean;
+    onDragStart?: (event: React.DragEvent, entry: FileSystemEntry) => void;
+    onDragEnd?: () => void;
+    onDragOverEntry?: (event: React.DragEvent, entry: FileSystemEntry) => void;
+    onDropEntry?: (event: React.DragEvent, entry: FileSystemEntry) => void;
+    renderChildren?: (dirPath: string) => 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;
+
 /**
- * @bendyline/docblocks-react — React components for DocBlocks
+ * useFileTree — hook that reads from a FileSystemProvider,
+ * maintains expanded/collapsed state, and provides CRUD operations.
  */
-export { FileExplorer } from './FileExplorer/index.js';
-export type { FileExplorerProps } from './FileExplorer/index.js';
-export { FileTreeNode } from './FileExplorer/index.js';
-export type { FileTreeNodeProps } from './FileExplorer/index.js';
-export { useFileTree } from './FileExplorer/index.js';
-export { WorkspacePicker } from './WorkspacePicker/index.js';
-export type { WorkspacePickerProps } from './WorkspacePicker/index.js';
-export { DocBlocksShell } from './DocBlocksShell/index.js';
-export type { DocBlocksShellProps } from './DocBlocksShell/index.js';
-export { AppMenu } from './AppMenu/index.js';
-export type { AppMenuProps, ThemePreference } from './AppMenu/index.js';
-export { ExportToolbarControls } from './Export/index.js';
-export type { ExportToolbarControlsProps, ExportFormat, ExportOptions } from './Export/index.js';
-export { ExportDialog } from './Export/index.js';
-export type { ExportDialogProps } from './Export/index.js';
-export { useAutoSave } from './hooks/index.js';
-//# sourceMappingURL=index.d.ts.map
+
+interface FileTreeState {
+    /** Flat list of entries for the current directory view. */
+    entries: FileSystemEntry[];
+    /** Set of expanded directory paths. */
+    expanded: Set<string>;
+    /** Currently selected path — file or directory (null if none). */
+    selectedPath: string | null;
+    /** Kind of the selected entry. */
+    selectedKind: 'file' | 'directory' | null;
+    /** Whether the tree is loading. */
+    loading: boolean;
+    /** Latest provider/read/watch failure, cleared by a successful refresh. */
+    error: string | null;
+}
+interface FileTreeActions {
+    /** Toggle a directory's expanded state. */
+    toggleExpand: (path: string) => void;
+    /** Select a file or directory. */
+    select: (path: string, kind: 'file' | 'directory') => void;
+    /** Select an entry and expand each directory needed to reveal it. */
+    reveal: (path: string, kind: 'file' | 'directory') => void;
+    /** Create a new file with optional initial content. */
+    createFile: (path: string, content?: string) => Promise<void>;
+    /** Create a new directory. */
+    createDirectory: (path: string) => Promise<void>;
+    /** Delete a file or directory. */
+    deleteEntry: (path: string) => Promise<void>;
+    /** Rename or move a file or directory, including a markdown companion folder. */
+    renameEntry: (oldPath: string, newPath: string, kind?: 'file' | 'directory') => Promise<void>;
+    /** Force refresh the tree. */
+    refresh: () => Promise<void>;
+}
+declare function useFileTree(provider: FileSystemProvider | null): FileTreeState & FileTreeActions;
+
+interface WorkspacePickerProps {
+    /** Currently active workspace id. */
+    activeWorkspaceId: string | null;
+    /** Called when the user picks a different workspace. */
+    onSelect: (descriptor: WorkspaceDescriptor) => void;
+    /** Called when the user chooses "Open Folder" (native FS). */
+    onOpenFolder: () => void;
+    /**
+     * Called when the user chooses "Clone Git repository". Only provided on
+     * the desktop when git is available — omitted, the item is hidden.
+     */
+    onCloneRepository?: () => void;
+    /** Forces a list refresh after an external workspace-registry mutation. */
+    refreshKey?: number;
+    /** Optional className. */
+    className?: string;
+}
+declare function WorkspacePicker({ activeWorkspaceId, onSelect, onOpenFolder, onCloneRepository, refreshKey, className, }: WorkspacePickerProps): react_jsx_runtime.JSX.Element;
+
+interface DocBlocksShellProps {
+    /**
+     * The theme to use before the user has an opinion. Omit or pass `'auto'` to
+     * follow the OS. An explicit `'light'`/`'dark'` choice the user makes in
+     * Settings outranks this — it is their app, not the host's.
+     */
+    theme?: EditorColorScheme | 'auto';
+    /** Optional logo image URL for the app menu. */
+    logoUrl?: string;
+    /** Version and surface label included in prefilled issue reports, e.g. `1.1.2 web`. */
+    issueReportVersion?: string;
+    /** Stable host title used before a document opens and for the optional home document. */
+    homeDocumentTitle?: string;
+    /** Document path that represents the host's indexable home experience. */
+    homeDocumentPath?: string;
+    /**
+     * Enable document version history. Snapshots are written under
+     * `<basename>_files/.versions/` next to each markdown file (i.e., the
+     * per-document container). Defaults to `true`.
+     */
+    allowVersioning?: boolean;
+    /**
+     * Override the document basename used in version filenames. Defaults
+     * to the basename of the currently selected file.
+     */
+    versionBasename?: string;
+    /** Prune policy applied after each successful save. Default: keep last 50. */
+    versioningPrunePolicy?: PrunePolicy;
+    /** Idle delay (ms) before the editor auto-saves a version. `0` disables. Default 5000. */
+    versioningAutoSaveIdleMs?: number;
+    /** Notified after each `saveVersion` attempt (saved=true and saved=false). */
+    onSaveVersion?: (result: SaveVersionResult) => void;
+    /** Optional escape hatch for hosts that want imperative access to the version manager. */
+    versioningRef?: React.Ref<DocumentVersionManager | null>;
+    /**
+     * True when a new deploy is waiting (browser PWA hosts: a fresh service
+     * worker finished installing). The shell shows an "Update available"
+     * status-bar notice that opens a Reload/Later prompt.
+     */
+    updateAvailable?: boolean;
+    /** Activates the waiting update and reloads onto the new version. */
+    onApplyUpdate?: () => void;
+    /**
+     * 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, homeDocumentTitle, homeDocumentPath, allowVersioning, versionBasename, versioningPrunePolicy, versioningAutoSaveIdleMs, onSaveVersion, versioningRef, updateAvailable, onApplyUpdate, offlineReady, }: DocBlocksShellProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Versioning preferences — global default + per-workspace resolution.
+ *
+ * The global preference controls whether DocBlocks writes version
+ * snapshots (under `<basename>_files/.versions/`) when editing. The
+ * default is `'browser-only'` so local-folder workspaces stay clean by
+ * default and only IndexedDB workspaces accumulate version history.
+ *
+ * Each workspace can override the global default with its own setting
+ * stored on the WorkspaceDescriptor. `'inherit'` (or absent) defers to
+ * the global preference; `'on'` / `'off'` force the behavior regardless.
+ */
+
+type VersioningPreference = 'on' | 'browser-only' | 'off';
+
+interface AppMenuProps {
+    /** Optional logo image URL to display instead of the text label. */
+    logoUrl?: string;
+    /** Current theme preference. */
+    themePreference?: ThemePreference;
+    /** Called when the user changes the theme preference. */
+    onThemeChange?: (theme: ThemePreference) => void;
+    /** Current accent color. */
+    accentColor?: AccentColor;
+    /** Called when the user changes the accent color. */
+    onAccentColorChange?: (color: AccentColor) => void;
+    /** Current typography preferences for the editor's Write canvas. */
+    writeCanvasSettings?: WriteCanvasPreferences;
+    /** Called when the user changes the Write canvas typography. */
+    onWriteCanvasSettingsChange?: (settings: WriteCanvasPreferences) => void;
+    /** Current global versioning preference. */
+    versioningPreference?: VersioningPreference;
+    /** Called when the user changes the global versioning preference. */
+    onVersioningPreferenceChange?: (pref: VersioningPreference) => void;
+    /**
+     * Called when the user clicks "Download all workspaces". When omitted,
+     * the menu item is hidden.
+     */
+    onDownloadAllWorkspaces?: () => void | Promise<void>;
+    /**
+     * Called when the user asks the browser to keep origin storage persistent.
+     * When omitted, the menu item is hidden.
+     */
+    onKeepBrowserData?: () => void | Promise<void>;
+    /**
+     * Called when the user clicks "Install DocBlocks…" (browser PWA install).
+     * When omitted — Electron, unsupported browsers, or already installed —
+     * the menu item is hidden.
+     */
+    onInstallApp?: () => void | Promise<void>;
+    /**
+     * Async origin storage usage/quota for the Settings "Storage" section
+     * (fetched when the dialog opens). When omitted — Electron, or browsers
+     * without `navigator.storage.estimate` — the section is hidden.
+     */
+    getStorageEstimate?: () => Promise<{
+        usage: number;
+        quota: number;
+    } | null>;
+    /** Whether the browser has marked origin storage persistent (Settings display). */
+    storagePersistent?: boolean;
+}
+declare function AppMenu({ logoUrl, themePreference, onThemeChange, accentColor, onAccentColorChange, writeCanvasSettings, onWriteCanvasSettingsChange, versioningPreference, onVersioningPreferenceChange, onDownloadAllWorkspaces, onKeepBrowserData, onInstallApp, getStorageEstimate, storagePersistent, }: AppMenuProps): react_jsx_runtime.JSX.Element;
+
+interface ExportToolbarControlsProps {
+    /** Currently selected file path — used to derive the download filename. */
+    selectedFile: string | null;
+    /** Media container for resolving images during export. */
+    mediaContainer?: ContentContainer | 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. */
+    destinationAdapter?: ExportDestinationAdapter;
+    /** Render the trigger as a direct Export button instead of the overflow menu. */
+    trigger?: 'menu' | 'button';
+    /** Whether to show video export in the overflow menu. */
+    showVideoExport?: boolean;
+    /** Resolved host color scheme for the video export dialog. */
+    colorScheme?: 'light' | 'dark';
+    /** Host palette overrides for the video export dialog and progress UI. */
+    videoExportPalette?: VideoExportModalProps['uiPalette'];
+    /** HTTP(S) DocBlocks page used as the base of generated shared links. */
+    shareBaseUrl?: string;
+    /** One-time Use mode supplied by an opened shared document link. */
+    initialSharedMode?: SharedDocumentMode | null;
+}
+/** Host-specific operations behind the shared export destination control. */
+interface ExportDestinationTarget {
+    grantId: string | null;
+    displayPath: string;
+}
+interface ExportDestinationAdapter {
+    resolveTarget: (filename: string) => Promise<ExportDestinationTarget>;
+    pickTarget: (filename: string, currentTarget?: ExportDestinationTarget | null) => Promise<ExportDestinationTarget | null>;
+    saveBlob: (blob: Blob, filename: string, target?: ExportDestinationTarget | null) => Promise<ExportDestinationTarget | null>;
+    hint?: string;
+}
+
+/** Public toolbar control with its editor-coupled implementation deferred. */
+declare function ExportToolbarControls(props: ExportToolbarControlsProps): react_jsx_runtime.JSX.Element;
+
+/** Keep a user-edited target name while switching the selected export format. */
+declare function updateExportTargetExtension(targetPath: string, suggestedFilename: string): string;
+
+interface UseDocumentSessionResult {
+    /** Stable controller for the lifetime of the mounted shell/panel. */
+    session: DocumentSession;
+    /** React snapshot of dirty/saving/saved/error/conflict state. */
+    snapshot: DocumentSessionSnapshot;
+}
+/**
+ * React binding for the framework-neutral DocumentSession engine.
+ *
+ * The hook deliberately does not infer target transitions from props.
+ * Callers must use transitionTo(), retarget(), or delete() before changing
+ * their view state so persistence ordering remains explicit.
+ */
+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, updateExportTargetExtension, useDocumentSession, useFileTree };