@epam/ai-dial-chat-hooks 1.1.0-dev.383 → 1.1.0-dev.390

package/file-manager.d.ts

@@ -0,0 +1,1344 @@
+import { Annotation } from '@epam/ai-dial-chat-shared';
+import { AnnotationGroup } from '@epam/ai-dial-quotations';
+import { ArchiveItemDto } from '@epam/ai-dial-chat-api-client';
+import { Attachment } from '@epam/ai-dial-chat-shared';
+import { AttachmentDisplayResolvers } from '@epam/ai-dial-chat-shared';
+import { AttachmentResource } from '@epam/ai-dial-chat-shared';
+import { CopyFilesResponseDto } from '@epam/ai-dial-chat-api-client';
+import { CopyItemDto } from '@epam/ai-dial-chat-api-client';
+import { CreateFolderDto } from '@epam/ai-dial-chat-api-client';
+import { CreateFolderResponseDto } from '@epam/ai-dial-chat-api-client';
+import { CustomVisualizer } from '@epam/ai-dial-chat-shared';
+import type { CustomVisualizerDataLayout } from '@epam/ai-dial-chat-shared';
+import { DeleteFilesResponseDto } from '@epam/ai-dial-chat-api-client';
+import { DeleteItemDto } from '@epam/ai-dial-chat-api-client';
+import { DialCopiedItem } from '@epam/ai-dial-react-file-manager';
+import { DialDeletedItem } from '@epam/ai-dial-react-file-manager';
+import { DialFile } from '@epam/ai-dial-react-file-manager';
+import { DialFile as DialFile_2 } from '@epam/ai-dial-ui-kit';
+import { DialFileAcceptType } from '@epam/ai-dial-react-file-manager';
+import { DialFileManagerActionProfile } from '@epam/ai-dial-chat-shared';
+import { DialFileManagerActions } from '@epam/ai-dial-react-file-manager';
+import { DialFileManagerTabs } from '@epam/ai-dial-react-file-manager';
+import { DialFileManagerVariant } from '@epam/ai-dial-chat-shared';
+import { DialFilePermission } from '@epam/ai-dial-react-file-manager';
+import { DialUploadFileItem } from '@epam/ai-dial-react-file-manager';
+import { DiscardSharedItemDto } from '@epam/ai-dial-chat-api-client';
+import { DiscardSharedResponseDto } from '@epam/ai-dial-chat-api-client';
+import { DisplayAttachment } from '@epam/ai-dial-chat-shared';
+import { FileManagerColumnKey } from '@epam/ai-dial-react-file-manager';
+import { FileMetadataResponseDto } from '@epam/ai-dial-chat-api-client';
+import { FilesApi } from '@epam/ai-dial-chat-api-client';
+import { FileUploadBatchState } from '@epam/ai-dial-chat-shared';
+import { FileUploadEntry } from '@epam/ai-dial-chat-shared';
+import { FileUploadResponseDto } from '@epam/ai-dial-chat-api-client';
+import { FileUploadStatus } from '@epam/ai-dial-chat-shared';
+import { FileUploadValidationResult } from '@epam/ai-dial-chat-shared';
+import { getParentFolderPath } from '@epam/ai-dial-chat-shared';
+import type { InputHighlightData } from '@epam/pdf-highlighter-kit';
+import { ListFilesItemDto } from '@epam/ai-dial-chat-api-client';
+import { ListFilesResponseDto } from '@epam/ai-dial-chat-api-client';
+import { ListPublicFilesRequest } from '@epam/ai-dial-chat-api-client';
+import { ListSharedFilesRequest } from '@epam/ai-dial-chat-api-client';
+import { MessageAttachment } from '@epam/ai-dial-chat-shared';
+import { MoveFilesResponseDto } from '@epam/ai-dial-chat-api-client';
+import { MoveItemDto } from '@epam/ai-dial-chat-api-client';
+import { NotificationVariant } from '@epam/ai-dial-ui-kit';
+import { RenameFilesResponseDto } from '@epam/ai-dial-chat-api-client';
+import { RenameItemDto } from '@epam/ai-dial-chat-api-client';
+import { RevokeAccessItemDto } from '@epam/ai-dial-chat-api-client';
+import { RevokeAccessResponseDto } from '@epam/ai-dial-chat-api-client';
+import { TabModel } from '@epam/ai-dial-ui-kit';
+import { ToolbarOptions } from '@epam/ai-dial-react-file-manager';
+import { UploadArchiveResponseDto } from '@epam/ai-dial-chat-api-client';
+import { useGridEditingScroll } from '@epam/ai-dial-chat-shared';
+import { UseGridEditingScrollOptions } from '@epam/ai-dial-chat-shared';
+import { UseGridEditingScrollResult } from '@epam/ai-dial-chat-shared';
+
+/** Maps an annotation's source attachment to the display-only attachment model. */
+export declare const annotationToDisplayAttachment: (annotation: Annotation) => DisplayAttachment | null;
+
+/**
+ * Builds a `PdfCanvasContent` for a PDF citation annotation, including highlights
+ * for all annotations in the same source group and scroll target for the clicked one.
+ * Returns `null` if the annotation has no PDF source attachment.
+ */
+export declare const annotationToPdfCanvasContent: (annotation: Annotation, groups: AnnotationGroup[], resolvers: AttachmentCanvasUrlResolvers) => PdfCanvasContent | null;
+
+/**
+ * DIAL-file URL resolution injected by the host into every attachment-canvas
+ * content resolver below. Host-owned — encodes the app's own
+ * file-download endpoint.
+ */
+export declare interface AttachmentCanvasUrlResolvers {
+    /** Resolves a DIAL Core file id to a downloadable URL. */
+    resolveDialFileDownloadUrl: (fileId: string) => string | undefined;
+    /** Resolves the best downloadable DIAL-file URL from an attachment's `url` or `referenceUrl`. */
+    resolveDialUrl: (attachment: DisplayAttachment) => string | undefined;
+}
+
+/** The type of content the canvas can display. */
+declare enum AttachmentContentType {
+    PlainText = 'plain_text',
+    Image = 'image',
+    Audio = 'audio',
+    Markdown = 'markdown',
+    Json = 'json',
+    Pdf = 'pdf',
+    Ooxml = 'ooxml',
+    Code = 'code',
+    Html = 'html',
+    Visualizer = 'visualizer',
+    McpApp = 'mcp_app',
+    Unsupported = 'unsupported',
+    Error = 'error',
+}
+
+/** Maps Chat API attachment DTOs to display-only attachment models. */
+export declare const attachmentDtosToDisplayAttachments: (dtos: MessageAttachment[] | undefined, resolvers: AttachmentDisplayResolvers) => DisplayAttachment[];
+
+/**
+ * Maps a message attachment payload to the display-only attachment model used by UI components.
+ */
+export declare const attachmentDtoToDisplayAttachment: (dto: MessageAttachment, resolvers: AttachmentDisplayResolvers) => DisplayAttachment;
+
+/** The kind of failure that produced an `ErrorCanvasContent`. */
+declare enum AttachmentErrorType {
+    /** The file failed to load (network error or a non-`403` non-OK response). */
+    LoadFailed = 'load_failed',
+    /** The file request failed with HTTP `403` — the user lacks permission to access it. */
+    Forbidden = 'forbidden',
+}
+
+export declare const buildFromCache: (cache: Map<string, ListFilesItemDto[]>, listingPermissionsCache: Map<string, string[] | undefined>, apiPath: string, virtualBasePath: string, folderId: string) => DialFile[];
+
+/**
+ * Converts a bucket-relative path (e.g. "reports/q1.pdf") to the virtual
+ * DialFile.path format ("/My files/reports/q1.pdf") that ui-kit compares
+ * row items against for `sharedByMePaths`/`sharedWithMeIds` gating — the
+ * DIAL Core resource path ("files/{bucket}/...") is a different identifier
+ * space and never matches. Decodes each path segment independently, matching
+ * how buildFromCache derives virtual paths.
+ */
+export declare const buildSharedItemVirtualPath: (relativePath: string, rootLabel: string, isFolder: boolean) => string;
+
+/** Clears all cached fetch results. Call this when leaving a conversation. */
+export declare const clearAttachmentCache: () => void;
+
+/** Content payload for syntax-highlighted source-code or text file attachments. */
+declare interface CodeCanvasContent {
+    /** Discriminates the content type to select the correct renderer. */
+    type: AttachmentContentType.Code;
+    /** The raw source text to display. */
+    text: string;
+    /** `react-syntax-highlighter` language identifier (e.g. `'typescript'`). `undefined` renders plain monospace. */
+    language?: string;
+}
+
+export declare const COLUMNS_WITH_AUTHOR: FileManagerColumnKey[];
+
+export declare const COLUMNS_WITHOUT_AUTHOR: FileManagerColumnKey[];
+
+export declare interface CopyMoveResult {
+    success?: boolean;
+    sourcePath?: string;
+    destinationPath?: string;
+}
+
+export declare const CORE_PERMISSION_MAP: Record<string, DialFilePermission>;
+
+/**
+ * Builds the DIAL files API wrapper functions `apps/chat/src/server-api/files.api.ts`
+ * exposes today, delegating to an already-configured `FilesApi` instance and
+ * an injected progress-reporting upload function.
+ */
+export declare const createFilesApiClient: (filesApi: FilesApi, uploadFileWithProgress: UploadFileWithProgressFn) => FilesApiClient;
+
+/**
+ * Builds a progress-reporting file-upload function backed by
+ * `XMLHttpRequest` (needed because the `fetch`-based generated client has no
+ * upload-progress event), reporting progress, honoring an `AbortSignal`,
+ * attaching/rotating a CSRF token, and reporting an unauthorized response.
+ */
+export declare const createUploadFileWithProgress: (deps: CreateUploadFileWithProgressDeps) => UploadFileWithProgressFn;
+
+/** Host capabilities {@link createUploadFileWithProgress} needs to perform an XHR upload. */
+export declare interface CreateUploadFileWithProgressDeps {
+    /** Returns the currently held CSRF token, or `null` when none is set. */
+    getCsrfToken: () => string | null;
+    /** Stores a CSRF token captured from the upload response header. */
+    setCsrfToken: (token: string | null) => void;
+    /** Notifies the host that the upload request was unauthorized. */
+    notifyUnauthorized: (url: string) => void;
+    /** Constructs the error thrown to signal an unauthorized upload. */
+    createUnauthorizedError: (url: string) => Error;
+    /** The upload endpoint's URL. */
+    uploadUrl: string;
+    /** Builds the `XMLHttpRequest` instance to upload through. Defaults to `() => new XMLHttpRequest()`. */
+    xhrFactory?: () => XMLHttpRequest;
+}
+
+export declare const DATE_OPTIONS: Intl.DateTimeFormatOptions;
+
+export declare const deriveActionProfile: (variant: DialFileManagerVariant) => DialFileManagerActionProfile;
+
+/** Strip the "files/{bucket}/" prefix from a DIAL Core URL to get the path within the bucket. */
+export declare const dialCorePathToRelative: (dialCorePath: string, bucket: string) => string;
+
+export { DialFileManagerActionProfile }
+
+export { DialFileManagerVariant }
+
+/**
+ * Operation port every file-manager hook that performs network I/O accepts as
+ * a parameter, replacing direct `server-api/files.api` access. Mirrors
+ * `apps/chat/src/server-api/files.api.ts`'s exact function signatures — not
+ * the generated client's own method shapes — since that file wraps
+ * `uploadFile`/`uploadArchive` with custom XHR-based progress/cancellation
+ * that has no equivalent in the generated client.
+ */
+export declare interface DialFilesApi {
+    /** Lists files/folders directly under `params.path` within `params.bucket`. */
+    listFiles(params: {
+        bucket: string;
+        path?: string;
+        token?: string;
+        limit?: number;
+        recursive?: boolean;
+        permissions?: boolean;
+    }, signal?: AbortSignal): Promise<ListFilesResponseDto>;
+    /** Lists files/folders under the organization's public root. */
+    listPublicFiles(params: ListPublicFilesRequest): Promise<ListFilesResponseDto>;
+    /** Lists files/folders shared with the current user. */
+    listSharedFiles(params: ListSharedFilesRequest): Promise<ListFilesResponseDto>;
+    /** Lists items the current user has shared with others, from their own bucket. */
+    listSharedByMe(bucket: string): Promise<ListFilesResponseDto>;
+    /** Fetches metadata for a single file or folder. */
+    getFileMetadata(params: {
+        bucket: string;
+        path: string;
+    }): Promise<FileMetadataResponseDto>;
+    /**
+     * Uploads a file, reporting progress via `options.onProgress` when supplied
+     * and honoring cancellation via `options.signal` or a bare `AbortSignal`.
+     */
+    uploadFile(bucket: string, path: string, file: File, options?: AbortSignal | DialFilesApiUploadOptions): Promise<FileUploadResponseDto>;
+    /** Uploads a ZIP archive and extracts its entries under `destinationPath`. */
+    uploadArchive(file: File, bucket: string, destinationPath: string): Promise<UploadArchiveResponseDto>;
+    /** Creates a new folder. */
+    createFolder(params: CreateFolderDto): Promise<CreateFolderResponseDto>;
+    /** Deletes one or more files/folders. */
+    deleteFiles(items: DeleteItemDto[]): Promise<DeleteFilesResponseDto>;
+    /** Renames one or more files/folders in place (same parent folder). */
+    renameFiles(items: RenameItemDto[]): Promise<RenameFilesResponseDto>;
+    /** Copies one or more files/folders to a destination path. */
+    copyFiles(items: CopyItemDto[], signal?: AbortSignal): Promise<CopyFilesResponseDto>;
+    /** Moves one or more files/folders to a destination path (different parent folder). */
+    moveFiles(items: MoveItemDto[], signal?: AbortSignal): Promise<MoveFilesResponseDto>;
+    /** Downloads a single file, returning the raw fetch `Response`. */
+    downloadFile(bucket: string, path: string, signal?: AbortSignal): Promise<Response>;
+    /** Downloads a ZIP archive of the given items, returning the raw fetch `Response`. */
+    downloadArchive(items: ArchiveItemDto[]): Promise<Response>;
+    /** Revokes access previously granted on the given owned items. */
+    revokeAccess(items: RevokeAccessItemDto[]): Promise<RevokeAccessResponseDto>;
+    /** Discards items shared with the current user. */
+    discardShared(items: DiscardSharedItemDto[]): Promise<DiscardSharedResponseDto>;
+}
+
+/** Upload mode passed through to `DialFilesApi.uploadFile` — mirrors the BFF's `uploadMode` form field. */
+export declare enum DialFilesApiUploadMode {
+    Overwrite = "overwrite",
+    CreateOnly = "create-only"
+}
+
+/** Options accepted by `DialFilesApi.uploadFile` beyond an already-created `AbortSignal`. */
+export declare interface DialFilesApiUploadOptions {
+    /** Aborts the in-flight upload when triggered. */
+    signal?: AbortSignal;
+    /** Called with the 0–100 upload progress percentage when the transport reports byte progress. */
+    onProgress?: (percent: number) => void;
+    /** Controls create-only vs. overwrite semantics for the destination path. */
+    uploadMode?: DialFilesApiUploadMode;
+}
+
+/** Maps a batch of selected DIAL files to attachments, dropping folders and unresolvable entries. */
+export declare const dialFilesToAttachments: (files: DialFile_2[], bucket: string, options?: DialFileToAttachmentOptions) => Attachment[];
+
+/**
+ * Converts a selected ui-kit file into the generic attachment contract.
+ * DIAL storage identifiers are resolved at the app edge so the input library
+ * remains unaware of buckets, server routes, and external file systems.
+ */
+export declare const dialFileToAttachment: (file: DialFile_2, bucket: string, options?: DialFileToAttachmentOptions) => Attachment | null;
+
+/** Options for {@link dialFileToAttachment} and {@link dialFilesToAttachments}. */
+export declare interface DialFileToAttachmentOptions {
+    /**
+     * Resolves an image attachment's `previewUrl` from its DIAL resource URL.
+     * Left unset, image attachments get no `previewUrl`. The host owns bucket/
+     * icon-path REST construction — this hook never builds those URLs itself.
+     */
+    resolvePreviewUrl?: (url: string) => string | undefined;
+}
+
+/**
+ * Converts a DIAL Core folder path (e.g. `files/{bucket}/{path}/`) into an
+ * attachment. DIAL Core resolves folder contents server-side when the path is
+ * sent as an attachment URL.
+ */
+export declare const dialFolderPathToAttachment: (folderPath: string) => Attachment;
+
+/** Discriminated destination a host resolves for a download, passed back into `triggerDownload`. */
+export declare type DownloadDestination = {
+    type: DownloadDestinationType.Blob;
+} | {
+    type: DownloadDestinationType.Stream;
+    writable: WritableStream<Uint8Array>;
+} | {
+    type: DownloadDestinationType.Cancelled;
+};
+
+/**
+ * Host-injected seam for `useDialFileMutations.onDownloadFiles`, replacing a
+ * direct import of the app's browser "Save As" / auto-download utilities —
+ * that behavior is desktop/web-shell-specific, not file-manager domain logic.
+ */
+export declare interface DownloadDestinationHandlers {
+    /** Resolves where a download with the given file name/MIME type should be written. */
+    resolveDestination(filename: string, mimeType: string): Promise<DownloadDestination>;
+    /** Writes `response` to `destination` and returns the name it was saved under. */
+    triggerDownload(response: Response, fallbackName: string, destination: DownloadDestination): Promise<string>;
+}
+
+/**
+ * Where a downloaded file's bytes should be written. Mirrors the host's own
+ * "Save As" vs. blob-download vs. cancelled-picker outcomes without the lib
+ * depending on the host's browser-API implementation.
+ */
+export declare enum DownloadDestinationType {
+    Blob = "blob",
+    Stream = "stream",
+    Cancelled = "cancelled"
+}
+
+/** Content payload for attachments whose file failed to load or that the user cannot access. */
+declare interface ErrorCanvasContent {
+    /** Discriminates the content type to select the correct renderer. */
+    type: AttachmentContentType.Error;
+    /** The kind of failure that occurred. */
+    errorType: AttachmentErrorType;
+    /** Remote URL of the file, if known. Ignored for download purposes when `errorType` is `Forbidden`. */
+    url?: string;
+    /** Overrides the default `loadErrorLabel`/`forbiddenErrorLabel` message, for callers whose failed content isn't a generic "file" (e.g. an MCP App). */
+    label?: string;
+}
+
+export declare const fetchByTab: (filesApi: DialFilesApi, tab: DialFileManagerTabs, bucket: string, folderPath: string, sharedRootMeta: Map<string, SharedRootMeta>) => Promise<{
+    items: ListFilesItemDto[];
+    permissions?: string[];
+}>;
+
+export declare const fetchForSearch: (filesApi: DialFilesApi, tab: DialFileManagerTabs, bucket: string, folderPath: string, sharedRootMeta: Map<string, SharedRootMeta>) => Promise<{
+    items: ListFilesItemDto[];
+}>;
+
+/**
+ * Structured toast event emitted by file-manager hooks. `reason` carries a
+ * library-owned identifier the host translates; `message` is an optional
+ * pre-rendered fallback for notifications a hook composes without a `reason`
+ * (e.g. hosts still authoring their own text for hooks not yet covered by a
+ * `FileManagerNotificationReason` member). The remaining fields carry the
+ * data a host needs to interpolate its translated string for reasons whose
+ * wording depends on more than the reason itself.
+ */
+export declare interface FileManagerNotification {
+    variant: NotificationVariant;
+    title?: string;
+    message?: string;
+    reason?: FileManagerNotificationReason;
+    /** Number of items the notification covers (e.g. a partial-failure count). */
+    count?: number;
+    /** Name of the affected entity or first successfully affected item. */
+    name?: string;
+    /** Source or destination folder name the notification refers to. */
+    folder?: string;
+    /** Up to the first 5 names affected by a partial/full failure list (e.g. archive extraction, delete). */
+    names?: string[];
+    /** Count of additional affected items beyond `names`' limit. */
+    restCount?: number;
+}
+
+/**
+ * Library-owned identifier for why a file-manager hook is surfacing an
+ * `onNotification` event, replacing a pre-translated toast message. The host
+ * maps each reason to its own translated string.
+ */
+export declare enum FileManagerNotificationReason {
+    /** A folder listing fetch (initial load, expand, invalidate-refetch, or popup preload) failed. */
+    FolderLoadFailed = "folderLoadFailed",
+    /** A single-file/folder metadata fetch (`onGetInfo`) failed. */
+    MetadataLoadFailed = "metadataLoadFailed",
+    /** `onCreateFolder`'s `createFolder` call failed. */
+    FolderCreateFailed = "folderCreateFailed",
+    /** `onDownloadFiles` failed for a single file/folder selection. */
+    DownloadFileFailed = "downloadFileFailed",
+    /** `onDownloadFiles` failed for a multi-item selection. */
+    DownloadFilesFailed = "downloadFilesFailed",
+    /** `onDeleteFiles` deleted at least one item successfully; `count`/`name`/`folder` describe the result. */
+    FilesDeleted = "filesDeleted",
+    /** `onDeleteFiles` completed with at least one failure alongside a success; `names`/`restCount` list the failures. */
+    FilesDeletePartiallyFailed = "filesDeletePartiallyFailed",
+    /** `onDeleteFiles`'s `deleteFiles` request itself rejected. */
+    DeleteFailed = "deleteFailed",
+    /** `onMoveToFiles`'s rename branch failed for every item in the batch. */
+    RenameFailed = "renameFailed",
+    /** `onMoveToFiles`'s rename branch failed for some items; `count` is the failed count. */
+    RenamePartiallyFailed = "renamePartiallyFailed",
+    /** `onMoveToFiles`'s move branch failed for every item in the batch. */
+    MoveFailed = "moveFailed",
+    /** `onMoveToFiles`'s move branch failed for some items; `count` is the failed count. */
+    MovePartiallyFailed = "movePartiallyFailed",
+    /** `onCopyFiles` failed for every item in the batch. */
+    CopyFailed = "copyFailed",
+    /** `onCopyFiles` failed for some items; `count` is the failed count. */
+    CopyPartiallyFailed = "copyPartiallyFailed",
+    /** `useDialFileSharing`'s `onUnshareFiles` request failed. */
+    UnshareFailed = "unshareFailed",
+    /** `useDialFileSharing`'s `onRemoveFilesAccess` request failed. */
+    RemoveAccessFailed = "removeAccessFailed",
+    /** `useDialFileUploadBatch`'s plain-file batch had zero successful uploads. */
+    UploadFailed = "uploadFailed",
+    /** `useDialFileUploadBatch`'s plain-file batch completed (fully or partially successful). */
+    UploadCompleted = "uploadCompleted",
+    /** `onUploadArchive` extracted zero entries successfully; `names`/`restCount` list the failures. */
+    UploadArchiveFailed = "uploadArchiveFailed",
+    /** `onUploadArchive` extracted some entries successfully and some failed; `count`/`names`/`restCount` describe the failures. */
+    UploadArchivePartiallyFailed = "uploadArchivePartiallyFailed",
+    /** `onUploadArchive`'s `uploadArchive` request itself rejected. */
+    UploadArchiveRequestFailed = "uploadArchiveRequestFailed"
+}
+
+/**
+ * Discriminated validation failure returned by `onCreateFolderValidate`/
+ * `onRenameValidate` instead of a pre-translated message; `null` means the
+ * name is valid. The host maps each `reason` to its own translated string.
+ */
+export declare type FileNameValidationError = {
+    reason: FileNameValidationErrorReason.Empty;
+} | {
+    reason: FileNameValidationErrorReason.ForbiddenSymbols;
+    symbols: string;
+} | {
+    reason: FileNameValidationErrorReason.ReservedName;
+} | {
+    reason: FileNameValidationErrorReason.TooLong;
+    maxLength: number;
+} | {
+    reason: FileNameValidationErrorReason.DuplicateName;
+    existingName: string;
+} | {
+    reason: FileNameValidationErrorReason.LeadingDot;
+};
+
+/**
+ * Reason a file/folder name failed `onCreateFolderValidate`/
+ * `onRenameValidate`'s validation, used as the discriminant of
+ * `FileNameValidationError`.
+ */
+export declare enum FileNameValidationErrorReason {
+    Empty = "empty",
+    ForbiddenSymbols = "forbiddenSymbols",
+    ReservedName = "reservedName",
+    TooLong = "tooLong",
+    DuplicateName = "duplicateName",
+    LeadingDot = "leadingDot"
+}
+
+/**
+ * Kind of mutation `useDialFileMutations` just completed successfully, for
+ * `onOperationSuccess`. Delete has no member here — its success feedback
+ * stays a structured `onNotification` event since it needs a count/folder,
+ * not a single named entity.
+ */
+export declare enum FileOperationKind {
+    FolderCreated = "folderCreated",
+    FileRenamed = "fileRenamed",
+    FileDownloaded = "fileDownloaded",
+    FilesDownloaded = "filesDownloaded",
+    FileCopied = "fileCopied",
+    FilesCopied = "filesCopied",
+    FileMoved = "fileMoved",
+    FilesMoved = "filesMoved"
+}
+
+/**
+ * Structured success event `useDialFileMutations` emits through
+ * `onOperationSuccess` instead of calling an application notification
+ * service directly.
+ */
+export declare interface FileOperationSuccessEvent {
+    /** Which mutation just succeeded. */
+    kind: FileOperationKind;
+    /** Name of the affected entity or first successfully affected item, when applicable. */
+    name?: string;
+    /** Number of items the operation covered, when applicable. */
+    count?: number;
+    /** Destination folder name, for copy/move operations. */
+    destinationFolderName?: string;
+    /**
+     * Whether the affected item is a folder rather than a file. Only set for
+     * `fileRenamed`, since it is the only kind whose current wording depends
+     * on the item's node type (a rename toast reads "Folder renamed" vs.
+     * "File renamed").
+     */
+    isFolder?: boolean;
+}
+
+/** The DIAL files API surface produced by {@link createFilesApiClient}. */
+export declare interface FilesApiClient {
+    listPublicFiles: (params: ListPublicFilesRequest) => Promise<ListFilesResponseDto>;
+    listSharedFiles: (params: ListSharedFilesRequest) => Promise<ListFilesResponseDto>;
+    listFiles: (params: {
+        bucket: string;
+        path?: string;
+        token?: string;
+        limit?: number;
+        recursive?: boolean;
+        permissions?: boolean;
+    }, signal?: AbortSignal) => Promise<ListFilesResponseDto>;
+    uploadFile: (bucket: string, path: string, file: File, options?: AbortSignal | UploadFileOptions) => Promise<FileUploadResponseDto>;
+    uploadArchive: (file: File, bucket: string, destinationPath: string) => Promise<UploadArchiveResponseDto>;
+    getFileMetadata: (params: {
+        bucket: string;
+        path: string;
+    }) => Promise<FileMetadataResponseDto>;
+    downloadFile: (bucket: string, path: string, signal?: AbortSignal) => Promise<Response>;
+    createFolder: (params: CreateFolderDto) => Promise<CreateFolderResponseDto>;
+    deleteFiles: (items: DeleteItemDto[]) => Promise<DeleteFilesResponseDto>;
+    renameFiles: (items: RenameItemDto[]) => Promise<RenameFilesResponseDto>;
+    copyFiles: (items: CopyItemDto[], signal?: AbortSignal) => Promise<CopyFilesResponseDto>;
+    moveFiles: (items: MoveItemDto[], signal?: AbortSignal) => Promise<MoveFilesResponseDto>;
+    downloadArchive: (items: ArchiveItemDto[]) => Promise<Response>;
+    revokeAccess: (items: RevokeAccessItemDto[]) => Promise<RevokeAccessResponseDto>;
+    discardShared: (items: DiscardSharedItemDto[]) => Promise<DiscardSharedResponseDto>;
+    listSharedByMe: (bucket: string) => Promise<ListFilesResponseDto>;
+}
+
+export { FileUploadValidationResult }
+
+export declare const findDialFileByPath: (nodes: DialFile[], targetPath: string) => DialFile | undefined;
+
+export declare const findFirstSuccessfulCopyMoveItem: <TDto extends {
+    success?: boolean;
+    sourcePath?: string;
+    destinationPath?: string;
+}>(items: PreparedCopyMoveItem<TDto>[], results: {
+    success?: boolean;
+    sourcePath?: string;
+    destinationPath?: string;
+}[]) => PreparedCopyMoveItem<TDto> | undefined;
+
+export declare const findFolderByVirtualPath: (nodes: DialFile[], virtualPath: string) => DialFile | undefined;
+
+export declare const formatOperationFolderName: (destinationFolder: string, rootLabel: string) => string;
+
+export { getParentFolderPath }
+
+/**
+ * Returns the last path segment of `url` — its file name — for both absolute
+ * URLs and DIAL-relative resource paths such as
+ * `files/<bucket>/qa-routed-source.html`. Any query string or hash is dropped
+ * and percent escapes are decoded. Returns an empty string when no segment can
+ * be extracted. Used to classify a resource by extension when its display name
+ * is a citation title rather than a file name.
+ */
+export declare const getUrlFileName: (url: string) => string;
+
+export declare const getVirtualPathName: (virtualPath: string, fallback: string) => string;
+
+/**
+ * Whether the attachment carries text `resolveAttachmentText` can resolve —
+ * inline data, a DIAL download URL, or a locally-picked file. Mirrors that
+ * function's source list, so a `null` resolver result can be read as "the text
+ * was fetched and rejected" rather than "there was no text to fetch".
+ */
+export declare const hasAttachmentTextSource: (attachment: DisplayAttachment, resolvers: AttachmentCanvasUrlResolvers) => boolean;
+
+export declare const hasDialFileWritePermission: (folder?: DialFile) => boolean;
+
+export declare const hasForbiddenNameSymbols: (name: string, forbiddenSymbolsRegExp?: RegExp) => boolean;
+
+/** Content payload for HTML file attachments or external HTML URL sources. */
+declare interface HtmlCanvasContent {
+    /** Discriminates the content type to select the correct renderer. */
+    type: AttachmentContentType.Html;
+    /** Full HTML text rendered via `srcdoc` in a sandboxed iframe. Used for file attachments. */
+    srcdoc?: string;
+    /** External URL rendered via `src` in a sandboxed iframe. Used for external link sources. */
+    url?: string;
+}
+
+/** Content payload for image attachments. */
+declare interface ImageCanvasContent {
+    /** Discriminates the content type to select the correct renderer. */
+    type: AttachmentContentType.Image;
+    /** URL of the image to display (object URL or resolved download URL). */
+    url: string;
+}
+
+/** Copy/Move/Duplicate are Browse/Full-only — the attach picker excludes them. */
+export declare const isCopyMoveDuplicateAllowed: (actionProfile: DialFileManagerActionProfile) => boolean;
+
+/** Narrows a string to a `DialFileAcceptType` — a dotted extension or a MIME type/wildcard. */
+export declare const isDialFileAcceptType: (type: string) => type is DialFileAcceptType;
+
+/** True when `url` looks like a DIAL Core file id (`files/{bucket}/{path}`). */
+export declare const isDialFileId: (url: string) => boolean;
+
+/** Returns true when an external (non-DIAL) source URL should be opened in the canvas rather than a new browser tab. */
+export declare const isExternalSourcePreviewable: (contentType: string, url: string) => boolean;
+
+/** Share/Unshare/Remove access are Full-only — Browse and Attach never expose them. */
+export declare const isShareActionsAllowed: (actionProfile: DialFileManagerActionProfile) => boolean;
+
+/** Content payload for JSON file attachments. */
+declare interface JsonCanvasContent {
+    /** Discriminates the content type to select the correct renderer. */
+    type: AttachmentContentType.Json;
+    /** Already-parsed JSON value. The lib never calls JSON.parse. */
+    value: unknown;
+}
+
+export declare const mapCorePermissions: (permissions?: string[]) => DialFile["permissions"] | undefined;
+
+/**
+ * Overlays a `FileMetadataResponseDto` response onto the clicked grid row so
+ * `fileMetadataPopupOptions.fileMetadata` receives a value structurally
+ * consistent with any other `DialFile` — the row already carries the correct
+ * virtual `path`/`id`/`name`/`nodeType`/`folderId`, while size/date/author/
+ * permissions are refreshed from the just-fetched server response.
+ */
+export declare const mapFileMetadataToDialFile: (metadata: FileMetadataResponseDto, original: DialFile) => DialFile;
+
+export declare const mapSearchItem: (item: ListFilesItemDto, fallbackBucket: string, rootLabel: string) => DialFile;
+
+/** Content payload for Markdown file attachments. */
+declare interface MarkdownCanvasContent {
+    /** Discriminates the content type to select the correct renderer. */
+    type: AttachmentContentType.Markdown;
+    /** Raw Markdown string to render. */
+    text: string;
+}
+
+export declare const mergeCreatedFolderIntoCache: (cache: Map<string, ListFilesItemDto[]>, parentApiPath: string, created: CreateFolderResponseDto, inheritedPermissions?: string[]) => Map<string, ListFilesItemDto[]>;
+
+/** Formats MIME types as a human-readable, comma-separated list of dotted extensions (or the MIME type itself for wildcards). */
+export declare const mimeTypesToAttachmentExtensionLabels: (types: string[]) => string;
+
+/** Normalizes `*` to the all-files wildcard and drops any value that is not a valid `DialFileAcceptType`. */
+export declare const mimeTypesToDialFileAcceptTypes: (types?: string[]) => DialFileAcceptType[] | undefined;
+
+/**
+ * Builds an `<input accept>` string from resolved MIME types, filtering out
+ * any value `isDialFileAcceptType` rejects, or `undefined` when no types are
+ * given or any type accepts everything.
+ */
+export declare const mimeTypesToFileAccept: (types?: string[]) => string | undefined;
+
+export declare const normalizeVirtualPath: (value: string) => string;
+
+/** Content payload for Office Open XML document attachments. */
+declare interface OoxmlCanvasContent {
+    /** Discriminates the content type to select the correct renderer. */
+    type: AttachmentContentType.Ooxml;
+    /** Resolved download URL or object URL for the OOXML file. */
+    url: string;
+    /** The document format used to select the format-specific renderer. */
+    format: OoxmlFileType;
+}
+
+/** Supported Office Open XML document formats. */
+declare enum OoxmlFileType {
+    Docx = 'docx',
+    Xlsx = 'xlsx',
+    Pptx = 'pptx',
+}
+
+/**
+ * Opens a cited/referenced attachment: triggers a browser download for
+ * DIAL-hosted files (`files/...` ids) via the injected `resolveDownloadUrl`,
+ * otherwise opens the URL in a new tab. No-ops when the attachment has no
+ * URL or the download URL cannot be resolved.
+ */
+export declare const openAnnotationAttachment: (attachment: AttachmentResource, resolveDownloadUrl: ResolveDownloadUrl) => void;
+
+export declare const parseNewFolderVirtualPath: (newFolderVirtualPath: string, rootLabel: string) => {
+    parentVirtualPath: string;
+    name: string;
+};
+
+export declare const PATH_SEPARATOR_REGEXP: RegExp;
+
+/** Content payload for PDF file attachments. */
+declare interface PdfCanvasContent {
+    /** Discriminates the content type to select the correct renderer. */
+    type: AttachmentContentType.Pdf;
+    /** Resolved download URL or object URL for the PDF file. */
+    url: string;
+    /** Highlight regions to render over the PDF pages. */
+    highlights?: InputHighlightData[];
+    /** ID of the highlight to scroll to and select on initial load. */
+    selectedHighlightId?: string;
+}
+
+/** Content payload for plain-text attachments. */
+declare interface PlainTextCanvasContent {
+    /** Discriminates the content type to select the correct renderer. */
+    type: AttachmentContentType.PlainText;
+    /** The raw text to display. */
+    text: string;
+}
+
+/** Builds the `copyFiles` DTOs (with their destination display name) for `onCopyFiles`. */
+export declare const prepareCopyItems: (copiedItems: DialCopiedItem[], bucket: string, rootLabel: string) => PreparedCopyMoveItem<CopyItemDto>[];
+
+export declare interface PreparedCopyMoveItem<TDto> {
+    dto: TDto;
+    destinationName: string;
+}
+
+/**
+ * Resolves where a download should be written: the browser's native "Save
+ * As" picker when available (`window.showSaveFilePicker`), otherwise a
+ * plain blob download. Returns `Cancelled` if the user dismisses the picker.
+ */
+export declare const prepareDownloadDestination: (filename: string, mimeType?: string) => Promise<DownloadDestination>;
+
+/**
+ * Rename-vs-move disambiguation (design.md D3): entries whose parent folder
+ * is unchanged become `renameDtos`; entries whose parent folder changed
+ * become `preparedMoveItems`.
+ */
+export declare const prepareMoveRenameItems: (copiedItems: DialCopiedItem[], bucket: string, rootLabel: string) => {
+    renameDtos: RenameItemDto[];
+    preparedMoveItems: PreparedCopyMoveItem<MoveItemDto>[];
+};
+
+/**
+ * Builds a `PdfCanvasContent` for a reference-only attachment whose
+ * `reference_url` points at a PDF file (optionally with a `#page=N`
+ * fragment), so it can be opened in the canvas and scrolled to the
+ * referenced page the same way a regular PDF citation is. Returns `null`
+ * when the attachment's `url` does not target a PDF.
+ */
+export declare const referenceAttachmentToPdfCanvasContent: (attachment: AttachmentResource, resolvers: AttachmentCanvasUrlResolvers) => PdfCanvasContent | null;
+
+/** Name reserved for the hidden marker file used to create empty folders. */
+export declare const RESERVED_MARKER_NAME = ".dial_folder";
+
+/** Resolves a syntax-highlighted code canvas content payload from a DisplayAttachment, or `null` if unavailable. */
+export declare const resolveCodeCanvasContent: (attachment: DisplayAttachment, resolvers: AttachmentCanvasUrlResolvers, language?: string) => Promise<CodeCanvasContent | ErrorCanvasContent | null>;
+
+/**
+ * Resolves a DialFile to the bucket-relative API path used by files BFF endpoints.
+ * Prefers DIAL resource ids when present; otherwise converts DialFile.path virtual paths.
+ */
+export declare const resolveDialFileApiPath: (file: DialFile, bucket: string, rootLabel: string) => string;
+
+/**
+ * Extracts the bucket and decoded relative path from a DIAL file ID
+ * (`files/{bucket}/{path}`). Returns `undefined` if the input does not start
+ * with `files/` or has no path segment after the bucket.
+ */
+export declare const resolveDialFileBucketAndPath: (fileId: string) => {
+    bucket: string;
+    path: string;
+} | undefined;
+
+/** Resolves a DIAL Core file id to a downloadable URL. Host-owned — encodes the app's own file-download endpoint. */
+declare type ResolveDownloadUrl = (fileId: string) => string | undefined;
+
+/**
+ * Returns the content type to trust for an external citation source: `contentType`
+ * unchanged when it is already an image/audio/PDF/OOXML marker, otherwise the
+ * type implied by `url`'s path extension (`MIMEType.PDF` for `.pdf`, the
+ * canonical OOXML MIME for `.docx`/`.xlsx`/`.pptx`) when that extension is
+ * recognized, otherwise `contentType` unchanged.
+ *
+ * Web-search grounding APIs label every reference — PDFs and Office documents
+ * included — as `text/markdown`, so a mislabeled `contentType` must not win
+ * over a recognized URL extension: doing so previously sent a PDF's raw bytes
+ * into the markdown/text canvas viewer, rendering garbled text instead of
+ * opening the PDF/OOXML viewer.
+ */
+export declare const resolveExternalSourceContentType: (contentType: string, url: string) => string;
+
+/**
+ * Resolves an HTML canvas content payload from a DisplayAttachment.
+ * Fetches and inlines the HTML as `srcdoc` when the attachment has a download URL or inline data.
+ * Returns `null` if no source is available, or an `ErrorCanvasContent` on fetch failure.
+ * Rejects `srcdoc` payloads larger than 1 MiB to prevent browser truncation.
+ */
+export declare const resolveHtmlCanvasContent: (attachment: DisplayAttachment, resolvers: AttachmentCanvasUrlResolvers) => Promise<HtmlCanvasContent | ErrorCanvasContent | null>;
+
+/**
+ * Resolves an image canvas content payload from a DisplayAttachment without
+ * fetching — returns the BFF download URL (or a local/inline blob URL)
+ * directly so the browser cache can be shared with the conversation view's
+ * `<img>` element. Error detection is delegated to `<img onError>` in the
+ * canvas renderer. Returns `null` if no URL source is available.
+ */
+export declare const resolveImageCanvasContent: (attachment: DisplayAttachment, resolvers: AttachmentCanvasUrlResolvers) => ImageCanvasContent | null;
+
+/**
+ * Resolves a JSON canvas content payload from a DisplayAttachment, or `null` if unavailable.
+ * Falls back to `PlainTextCanvasContent` when the fetched text is not valid JSON.
+ */
+export declare const resolveJsonCanvasContent: (attachment: DisplayAttachment, resolvers: AttachmentCanvasUrlResolvers) => Promise<JsonCanvasContent | PlainTextCanvasContent | ErrorCanvasContent | null>;
+
+/** Resolves a Markdown canvas content payload from a DisplayAttachment, or `null` if unavailable. */
+export declare const resolveMarkdownCanvasContent: (attachment: DisplayAttachment, resolvers: AttachmentCanvasUrlResolvers) => Promise<MarkdownCanvasContent | ErrorCanvasContent | null>;
+
+/** Resolves an OOXML canvas content payload from a DisplayAttachment, or `null` if unavailable. */
+export declare const resolveOoxmlCanvasContent: (attachment: DisplayAttachment, resolvers: AttachmentCanvasUrlResolvers, format: OoxmlFileType) => Promise<OoxmlCanvasContent | ErrorCanvasContent | null>;
+
+/**
+ * Resolves the effective bucket and path for a write operation on the Shared tab.
+ * For Shared tab items, the first segment of apiPath is the shared root folder name
+ * whose owner bucket is stored in sharedRootMeta.
+ */
+export declare const resolveOwnerCoords: (apiPath: string, sharedRootMeta: Map<string, SharedRootMeta>, fallbackBucket: string) => {
+    bucket: string;
+    path: string;
+};
+
+/** Resolves a PDF canvas content payload from a DisplayAttachment, or `null` if unavailable. */
+export declare const resolvePdfCanvasContent: (attachment: DisplayAttachment, resolvers: AttachmentCanvasUrlResolvers) => Promise<PdfCanvasContent | ErrorCanvasContent | null>;
+
+/**
+ * Converts a DIAL file ID or full resource path to the relative bucket path
+ * expected by the files download API.
+ */
+export declare const resolveRelativeDialFilePath: (pathOrFileId: string, bucket: string) => string;
+
+/** Resolves a plain-text canvas content payload from a DisplayAttachment, or `null` if unavailable. */
+export declare const resolveTextCanvasContent: (attachment: DisplayAttachment, resolvers: AttachmentCanvasUrlResolvers) => Promise<PlainTextCanvasContent | ErrorCanvasContent | null>;
+
+/**
+ * Fetches the attachment payload and builds a `VisualizerCanvasContent` for the
+ * given registry entry and theme. Returns `null` when the payload cannot be
+ * fetched (caller should fall through to default content-type handling).
+ *
+ * Only JSON payloads are parsed into `data`. Non-JSON payloads (plain text,
+ * CSV, binary, …) resolve with `data: {}` — the visualizer still receives
+ * `mimeType` and `layout`, just no payload body. This is intentional: only
+ * JSON attachment content is forwarded to visualizers in this version.
+ */
+export declare const resolveVisualizerCanvasContent: (attachment: DisplayAttachment, resolvers: AttachmentCanvasUrlResolvers, entry: CustomVisualizer, themeId: string) => Promise<VisualizerCanvasContent | null>;
+
+/**
+ * Sanitizes a filename for upload by replacing forbidden characters with `_`,
+ * trimming trailing dots/whitespace from the base name, and capping the result
+ * to 255 UTF-8 bytes.
+ *
+ * Mutates nothing — returns a new string. The caller (onValidateUpload) is
+ * responsible for writing the result back to DialUploadFileItem.name so the
+ * ui-kit's subsequent conflict detection sees the sanitized name.
+ *
+ * If the base name is empty after sanitization, returns the original name unchanged.
+ */
+export declare const sanitizeFileName: (name: string) => string;
+
+/** Owner-bucket resolution metadata for a Shared-tab root folder, keyed by its display name. */
+export declare interface SharedRootMeta {
+    bucket: string;
+    /** DIAL Core URL of the shared root item, e.g. "files/owner-bucket/some-folder/" */
+    dialCorePath: string;
+}
+
+/** Splits a file name into its base and extension, using only the last dot. */
+export declare const splitFileNameExtension: (fileName: string) => {
+    base: string;
+    extension: string;
+};
+
+export declare const trimFileNameToByteLimit: (name: string, limit?: number) => string;
+
+export declare const updateEntry: (prev: FileUploadBatchState | null, index: number, patch: FileUploadStatus | Partial<Pick<FileUploadEntry, "status" | "percent">>) => FileUploadBatchState | null;
+
+/** Max number of files uploaded concurrently within a single upload batch. */
+export declare const UPLOAD_CONCURRENCY = 3;
+
+/** Options accepted by the returned `uploadFile`. */
+export declare type UploadFileOptions = UploadFileWithProgressOptions;
+
+/** Shape of a progress-reporting file upload function, e.g. the return value of `createUploadFileWithProgress`. */
+export declare type UploadFileWithProgressFn = (bucket: string, path: string, file: File, options?: UploadFileWithProgressOptions) => Promise<FileUploadResponseDto>;
+
+/** Options accepted by an {@link UploadFileWithProgressFn}. */
+export declare interface UploadFileWithProgressOptions {
+    /** Aborts the upload in flight. */
+    signal?: AbortSignal;
+    /** Called with the upload's progress percentage (0–100). */
+    onProgress?: (percent: number) => void;
+    /** Defaults to the generated client's own default when omitted. */
+    uploadMode?: UploadMode;
+}
+
+/** Upload mode passed to `FilesApi.uploadFile`: overwrite an existing file or fail if it already exists. */
+export declare type UploadMode = 'overwrite' | 'create-only';
+
+/**
+ * Manages DIAL file-storage browsing state: folder listing/navigation, the
+ * tree's expand/collapse state, search, and the shared per-folder cache that
+ * `useDialFileUploadBatch`/`useDialFileMutations`/`useDialFileSharing` invalidate
+ * through `invalidateFolders`/`bumpRetry` after their own mutations settle
+ * (design.md D1) — this hook is the sole owner/writer of that cache.
+ *
+ * Supports three listing sources via `activeTab`:
+ * - my_files: user's own bucket via `DialFilesApi.listFiles`
+ * - shared: files shared with the user via `DialFilesApi.listSharedFiles`
+ * - organization: public bucket via `DialFilesApi.listPublicFiles`
+ */
+export declare const useDialFileListing: ({ filesApi, bucket, rootLabel, activeTab, onNotification, }: UseDialFileListingOptions) => UseDialFileListingResult;
+
+/** Options accepted by `useDialFileListing`. */
+export declare interface UseDialFileListingOptions {
+    /** Injected operation port used for every listing/search network call. */
+    filesApi: DialFilesApi;
+    /** DIAL Core bucket to browse (used only for the my_files tab). */
+    bucket: string;
+    /** Display name for the root folder node (e.g. `'My files'`). */
+    rootLabel: string;
+    /** Active tab — drives listing source and per-tab options. */
+    activeTab: DialFileManagerTabs;
+    /** Called with a structured event when a folder-load operation fails. */
+    onNotification?: (notification: FileManagerNotification) => void;
+}
+
+/** Values returned by `useDialFileListing`. */
+export declare interface UseDialFileListingResult {
+    items: DialFile[];
+    isLoading: boolean;
+    error: string | null;
+    path: string;
+    /** Bucket-relative path of the currently browsed folder (e.g. `"reports/"`, `""` for root). */
+    folderPath: string;
+    onPathChange: (nextPath?: string) => void;
+    retry: () => void;
+    onSearchFiles: (folder: string, query: string) => void;
+    isSearching: boolean;
+    searchResults: DialFile[] | null;
+    clearSearchResults: () => void;
+    expandedPaths: Set<string>;
+    loadedPaths: Set<string>;
+    onExpandedPathsChange: (paths: Set<string>) => void;
+    onFolderPopupPathChange: (nextPath?: string) => void;
+    folderPopupLoadingPaths: Set<string>;
+    sharedWithMeIds: string[] | undefined;
+    sharedByMePaths: Set<string>;
+    currentFolder: DialFile | undefined;
+    /** Read-only snapshot of the per-folder listing cache, for `useDialFileUploadBatch`'s overwrite-mode check. */
+    cache: Map<string, ListFilesItemDto[]>;
+    /** Read-only snapshot of per-folder permissions, for `useDialFileMutations`'s create-folder inherited permissions. */
+    listingPermissionsCache: Map<string, string[] | undefined>;
+    /** Owner-bucket resolution metadata for the Shared tab, populated by the root listing fetch. */
+    sharedRootMetaRef: React.RefObject<Map<string, SharedRootMeta>>;
+    /** Imperatively navigates the current folder — used by mutations after a rename/delete of the browsed folder. */
+    setFolderPath: React.Dispatch<React.SetStateAction<string>>;
+    /**
+     * Deletes the given API-path cache keys so the next listing fetch/expand for
+     * that folder re-fetches from the server. The only way sibling sub-hooks may
+     * invalidate the shared cache (design.md D1).
+     */
+    invalidateFolders: (apiPaths: string[]) => void;
+    /** Merges a just-created folder into its parent's cache entry (optimistic display for create-folder). */
+    mergeCreatedFolder: (parentApiPath: string, created: CreateFolderResponseDto, inheritedPermissions?: string[]) => void;
+    /** Forces the listing effect to re-fetch the currently browsed folder. */
+    bumpRetry: () => void;
+}
+
+/**
+ * Composes the five file-manager sub-hooks — listing/navigation, upload
+ * batches, CRUD mutations, sharing, and metadata — into the single flat
+ * result `DialFileManagerShell`/`DialFileManagerModal`/`DialFileManagerPage`
+ * consume. Cache ownership and cross-hook invalidation stay inside
+ * `useDialFileListing`; this composer only wires that hook's
+ * `invalidateFolders`/`bumpRetry` into its siblings and derives the handful
+ * of tab/actionProfile UI fields that read outputs from more than one
+ * sub-hook. Imports neither `react-i18next` nor any application context —
+ * every translated string reaches it through `labels`,
+ * `disabledNewButtonTooltip`, and `buildValidationErrorMessage`.
+ */
+export declare const useDialFileManager: ({ filesApi, bucket, rootLabel, activeTab, onNotification, onOperationSuccess, forbiddenSymbolsRegExp, variant, actionProfile, labels, locale, disabledNewButtonTooltip, downloadDestination, buildValidationErrorMessage, }: UseDialFileManagerOptions) => UseDialFileManagerResult;
+
+export declare interface UseDialFileManagerOptions {
+    /** Injected operation port used for every file-manager network call. */
+    filesApi: DialFilesApi;
+    /** DIAL Core bucket to browse (used only for my_files tab). */
+    bucket: string;
+    /** Display name for the root folder node. Defaults to `'My files'`. */
+    rootLabel?: string;
+    /** Active tab — drives listing source and per-tab options. Defaults to MyFiles. */
+    activeTab?: DialFileManagerTabs;
+    /** Called when a file-manager action should surface a toast notification. */
+    onNotification?: (notification: FileManagerNotification) => void;
+    /** Called when a mutation succeeds, instead of invoking an application notification service directly. */
+    onOperationSuccess?: (event: FileOperationSuccessEvent) => void;
+    /** Regexp of characters forbidden in file/folder names (e.g. NOT_ALLOWED_SYMBOLS_REGEXP). */
+    forbiddenSymbolsRegExp?: RegExp;
+    /** Which host is driving this hook instance. Defaults to `Attach`. */
+    variant?: DialFileManagerVariant;
+    /** Gates which actions are exposed. Defaults to the value derived from `variant`. */
+    actionProfile?: DialFileManagerActionProfile;
+    /**
+     * Host-supplied action label text, keyed by `DialFileManagerActions`. The
+     * hook computes which actions are visible/enabled per tab/variant/
+     * actionProfile and intersects that gating with this map — an action the
+     * gating allows but this map omits is left out of `actionLabels`.
+     */
+    labels: Partial<Record<DialFileManagerActions, string>>;
+    /** BCP-47 locale string for date formatting, replacing `i18n.language`. */
+    locale: string;
+    /** Translated tooltip shown on the disabled New/Upload button. */
+    disabledNewButtonTooltip: string;
+    /** Host-injected browser "Save As"/auto-download seam for `onDownloadFiles`. */
+    downloadDestination: DownloadDestinationHandlers;
+    /**
+     * Builds a translated message from a structured validation-error reason,
+     * for `onCreateFolderValidate`/`onRenameValidate`. `item` is passed for a
+     * rename (so the host can distinguish file vs. folder wording) and
+     * omitted for folder creation.
+     */
+    buildValidationErrorMessage: (error: FileNameValidationError, item?: DialFile) => string;
+}
+
+export declare interface UseDialFileManagerResult {
+    /** Hierarchical items for DialFileManager's `items` prop. */
+    items: DialFile[];
+    /** True while the current folder is loading. */
+    isLoading: boolean;
+    /** Non-null when the last fetch failed. */
+    error: string | null;
+    /** Current path in DialFileManager format (e.g. `"/My files"`, `"/My files/reports/"`). */
+    path: string;
+    /** Pass directly to DialFileManager's `onPathChange`. */
+    onPathChange: (nextPath?: string) => void;
+    /** Re-runs the fetch for the current `folderPath`. */
+    retry: () => void;
+    /**
+     * Search: called by DialFileManager when the user types in the search box.
+     * `folder` is accepted for API parity with DialFileManager but is intentionally
+     * unused — this hook always searches from the active-tab root stored in
+     * `folderPath`, not from the passed-in `folder` (see design decision D3).
+     */
+    onSearchFiles: (folder: string, query: string) => void;
+    /** Search: true while a search request is in flight. */
+    isSearching: boolean;
+    /** Search: flat list of matching files, or null when search is not active. */
+    searchResults: DialFile[] | null;
+    /** Search: clears results and exits search mode. */
+    clearSearchResults: () => void;
+    /** Tree: controlled set of expanded folder virtual paths. */
+    expandedPaths: Set<string>;
+    /** Tree: expanded or destination-popup virtual paths whose children are already cached. */
+    loadedPaths: Set<string>;
+    /** Tree: called by DialFileManager when a folder is expanded/collapsed. */
+    onExpandedPathsChange: (paths: Set<string>) => void;
+    /** Destination folder popup: preloads the browsed folder without changing the outer grid path. */
+    onFolderPopupPathChange: (nextPath?: string) => void;
+    /** Destination folder popup: normalized virtual paths currently being preloaded. */
+    folderPopupLoadingPaths: Set<string>;
+    /** Upload: start a new batch. */
+    onUploadFiles: (files: DialUploadFileItem[], destinationFolder: string) => void;
+    /** Upload: extracts and uploads a ZIP archive's entries to the destination folder. */
+    onUploadArchive: (file: File, name: string, destinationFolder: string) => void;
+    /** Upload: validate file names before upload (called by DialFileManager). */
+    onValidateUpload: (files: DialUploadFileItem[], existingFiles: DialFile[], destinationFolder: string) => Promise<FileUploadValidationResult>;
+    /** Upload: current batch state (null when idle). */
+    uploadBatchState: FileUploadBatchState | null;
+    /** Upload: abort all in-flight and queued uploads. */
+    cancelUpload: () => void;
+    /** Upload: dismiss the progress modal after the batch has settled. */
+    clearUploadBatch: () => void;
+    /** Folder creation: called when user confirms a new folder name. */
+    onCreateFolder: (file: DialUploadFileItem, folderPath: string, fileId: string) => Promise<void>;
+    /** Folder creation: inline synchronous validation (returns error message or null). */
+    onCreateFolderValidate: (name: string, parentFolder: DialFile) => string | null;
+    /** True while a folder creation request is in flight. */
+    isCreatingFolder: boolean;
+    /** Download: called when user triggers download on one or more items. */
+    onDownloadFiles: (dialFiles: DialFile[]) => void;
+    /** True while a download is in progress. */
+    isDownloading: boolean;
+    /** Delete: called when user confirms deletion of one or more items. */
+    onDeleteFiles: (items: DialDeletedItem[], sourceFolder: string) => void;
+    /** True while a delete request is in flight. */
+    isDeleting: boolean;
+    /** Rename: inline validation — returns error string or null. */
+    onRenameValidate: (value: string, item: DialFile) => string | null;
+    /** Rename: called when user confirms an inline rename. Also dispatches cross-folder move (see D3). */
+    onMoveToFiles: (items: DialCopiedItem[], sourceFolder: string, destinationFolder: string) => void;
+    /** True while a rename request is in flight. */
+    isRenaming: boolean;
+    /** Copy: called when user confirms a copy-paste. */
+    onCopyFiles: (items: DialCopiedItem[], destinationFolder: string) => void;
+    /** True while a copy request is in flight. */
+    isCopying: boolean;
+    /** True while the cross-folder-move branch of onMoveToFiles is in flight. */
+    isMoving: boolean;
+    /** Aborts whichever of copy/move is currently in flight. */
+    cancelCopyMove: () => void;
+    /** True when the current folder grants WRITE (upload + new folder). */
+    uploadEnabled: boolean;
+    /** True when Upload/New must be disabled. */
+    isNewButtonDisabled: boolean;
+    /** Tooltip for disabled New/Upload when `isNewButtonDisabled` is true. */
+    disabledNewButtonTooltip: string;
+    /** Columns to show in the grid — tab-dependent. */
+    visibleColumns: FileManagerColumnKey[];
+    /** BCP-47 locale string for date formatting, sourced from i18n.language. */
+    dateLocale: string;
+    /** Fixed date format options for the UpdatedAt column. */
+    dateOptions: Intl.DateTimeFormatOptions;
+    /** Action labels for grid/tree/bulk — Delete present only on my_files tab. */
+    actionLabels: Partial<Record<DialFileManagerActions, string>>;
+    /** Root-level shared item paths, populated only on the Shared tab. */
+    sharedWithMeIds: string[] | undefined;
+    /** Share: paths the user has shared with others, populated only on my_files tab. */
+    sharedByMePaths: Set<string>;
+    /** Unshare: called when user removes a shared-with-me item (Shared tab only). */
+    onUnshareFiles: (files: DialFile[]) => void;
+    /** True while an unshare request is in flight. */
+    isUnsharing: boolean;
+    /** Remove access: called when user revokes access to an owned shared item (my_files tab only). */
+    onRemoveFilesAccess: (files: DialFile[]) => void;
+    /** True while a remove-access request is in flight. */
+    isRemovingAccess: boolean;
+    /** Metadata: populated once onGetInfo resolves; passed to fileMetadataPopupOptions.fileMetadata. */
+    fileMetadata: DialFile | undefined;
+    /** True while a metadata request is in flight. */
+    isFileMetadataLoading: boolean;
+    /** Metadata: called by DialFileManager.onGetInfo to fetch and display a file's details. */
+    onGetInfo: (file: DialFile) => void;
+    /** Metadata: resets fileMetadata/isFileMetadataLoading; passed to fileMetadataPopupOptions.clearMetadata. */
+    clearMetadata: () => void;
+    /**
+     * True while any mutating file-manager operation is in flight: the OR of
+     * `isCreatingFolder`, `isDownloading`, `isDeleting`, `isRenaming`, `isCopying`,
+     * `isMoving`, `isUnsharing`, `isRemovingAccess`, and `uploadBatchState != null`.
+     *
+     * Deliberately excludes three flags, each already fully contained by its own
+     * scoped loading UI:
+     * - `isLoading` — a read (listing fetch), not a mutation.
+     * - `isSearching` — scoped to ui-kit's own search-progress UI.
+     * - `isFileMetadataLoading` — has its own `loading` state in `fileMetadataPopupOptions`.
+     */
+    isAnyOperationInProgress: boolean;
+}
+
+/**
+ * Filters the file-manager's tab list down to the host's configured set and
+ * resets `activeTab` to the highest-priority still-enabled tab when the
+ * current one becomes excluded. A `fileManagerTabs` of `undefined` means no
+ * restriction — every tab in `allTabs` stays enabled and no reset ever fires.
+ */
+export declare const useDialFileManagerTabConfig: (activeTab: DialFileManagerTabs, onTabChange: (tab: DialFileManagerTabs) => void, allTabs: TabModel[] | undefined, fileManagerTabs: string[] | undefined) => UseDialFileManagerTabConfigResult;
+
+/** Values returned by `useDialFileManagerTabConfig`. */
+export declare interface UseDialFileManagerTabConfigResult {
+    tabs: ToolbarOptions['tabs'];
+}
+
+/**
+ * Fetches and holds single-file metadata for `fileMetadataPopupOptions` —
+ * the only sub-hook with no interaction with the shared listing cache, since
+ * viewing metadata never mutates listing state.
+ */
+export declare const useDialFileMetadata: ({ filesApi, bucket, rootLabel, onNotification, }: UseDialFileMetadataOptions) => UseDialFileMetadataResult;
+
+/** Options accepted by `useDialFileMetadata`. */
+export declare interface UseDialFileMetadataOptions {
+    /** Injected operation port used for the metadata network call. */
+    filesApi: DialFilesApi;
+    /** DIAL Core bucket the current user browses (used only for my_files items). */
+    bucket: string;
+    /** Display name of the root folder node, used to resolve virtual paths back to API paths. */
+    rootLabel: string;
+    /** Called with a structured event when the metadata fetch fails. */
+    onNotification?: (notification: FileManagerNotification) => void;
+}
+
+/** Values returned by `useDialFileMetadata`. */
+export declare interface UseDialFileMetadataResult {
+    fileMetadata: DialFile | undefined;
+    isFileMetadataLoading: boolean;
+    onGetInfo: (file: DialFile) => void;
+    clearMetadata: () => void;
+}
+
+/**
+ * Manages create-folder, download, delete, rename, copy, and move mutations.
+ * Every mutation invalidates the shared listing cache for its affected
+ * folders through `invalidateFolders`/`bumpRetry` rather than holding its own
+ * cache copy; create-folder additionally uses `mergeCreatedFolder` so a newly
+ * created folder appears immediately even when created from a
+ * destination-folder popup browsing a different folder than the outer grid.
+ */
+export declare const useDialFileMutations: ({ filesApi, bucket, rootLabel, activeTab, folderPath, currentFolder, sharedRootMetaRef, listingPermissionsCache, invalidateFolders, bumpRetry, mergeCreatedFolder, setFolderPath, onNotification, onOperationSuccess, downloadDestination, forbiddenSymbolsRegExp, }: UseDialFileMutationsOptions) => UseDialFileMutationsResult;
+
+/** Options accepted by `useDialFileMutations`. */
+export declare interface UseDialFileMutationsOptions {
+    /** Injected operation port used for every mutation network call. */
+    filesApi: DialFilesApi;
+    /** DIAL Core bucket to browse (used only for the my_files tab). */
+    bucket: string;
+    /** Display name for the root folder node. */
+    rootLabel: string;
+    /** Active tab — drives owner-bucket resolution for the Shared tab. */
+    activeTab: DialFileManagerTabs;
+    /** Bucket-relative path of the currently browsed folder, owned by `useDialFileListing`. */
+    folderPath: string;
+    /** Currently browsed folder node, owned by `useDialFileListing`. */
+    currentFolder: DialFile | undefined;
+    /** Owner-bucket resolution metadata for the Shared tab, owned by `useDialFileListing`. */
+    sharedRootMetaRef: React.RefObject<Map<string, SharedRootMeta>>;
+    /** Read-only snapshot of `useDialFileListing`'s per-folder permissions cache. */
+    listingPermissionsCache: Map<string, string[] | undefined>;
+    /** Deletes the given API-path cache keys so the next fetch re-fetches them. */
+    invalidateFolders: (apiPaths: string[]) => void;
+    /** Forces `useDialFileListing`'s fetch effect to re-run. */
+    bumpRetry: () => void;
+    /** Merges a newly created folder into its parent's cache entry, owned by `useDialFileListing`. */
+    mergeCreatedFolder: (parentApiPath: string, created: CreateFolderResponseDto, inheritedPermissions?: string[]) => void;
+    /** Imperatively navigates the current folder after a rename/delete of the browsed folder. */
+    setFolderPath: React.Dispatch<React.SetStateAction<string>>;
+    /** Called when a mutation should surface a toast notification. */
+    onNotification?: (notification: FileManagerNotification) => void;
+    /** Called when a mutation succeeds, instead of invoking an application notification service directly. */
+    onOperationSuccess?: (event: FileOperationSuccessEvent) => void;
+    /** Host-injected browser "Save As"/auto-download seam for `onDownloadFiles`. */
+    downloadDestination: DownloadDestinationHandlers;
+    /** Regexp of characters forbidden in file/folder names beyond the path separator. */
+    forbiddenSymbolsRegExp?: RegExp;
+}
+
+/** Values returned by `useDialFileMutations`. */
+export declare interface UseDialFileMutationsResult {
+    isCreatingFolder: boolean;
+    isDownloading: boolean;
+    isDeleting: boolean;
+    isRenaming: boolean;
+    isCopying: boolean;
+    isMoving: boolean;
+    onCreateFolder: (file: DialUploadFileItem, folderPath: string, fileId: string) => Promise<void>;
+    onCreateFolderValidate: (name: string, parentFolder: DialFile) => FileNameValidationError | null;
+    onDownloadFiles: (dialFiles: DialFile[]) => void;
+    onDeleteFiles: (items: DialDeletedItem[], sourceFolder: string) => void;
+    onRenameValidate: (value: string, item: DialFile) => FileNameValidationError | null;
+    onMoveToFiles: (items: DialCopiedItem[], sourceFolder: string, destinationFolder: string) => void;
+    onCopyFiles: (items: DialCopiedItem[], destinationFolder: string) => void;
+    cancelCopyMove: () => void;
+}
+
+/**
+ * Manages the unshare/remove-access mutations. Bumps `useDialFileListing`'s
+ * shared retry counter after each mutation settles rather than holding its
+ * own cache copy.
+ */
+export declare const useDialFileSharing: ({ filesApi, bucket, rootLabel, bumpRetry, onNotification, }: UseDialFileSharingOptions) => UseDialFileSharingResult;
+
+/** Options accepted by `useDialFileSharing`. */
+export declare interface UseDialFileSharingOptions {
+    /** Injected operation port used for every sharing network call. */
+    filesApi: DialFilesApi;
+    /** DIAL Core bucket to browse (used only for the my_files tab). */
+    bucket: string;
+    /** Display name for the root folder node. */
+    rootLabel: string;
+    /** Forces `useDialFileListing`'s fetch effect to re-run after a mutation settles. */
+    bumpRetry: () => void;
+    /** Called when a sharing mutation fails and should surface a toast notification. */
+    onNotification?: (notification: FileManagerNotification) => void;
+}
+
+/** Values returned by `useDialFileSharing`. */
+export declare interface UseDialFileSharingResult {
+    isUnsharing: boolean;
+    isRemovingAccess: boolean;
+    onUnshareFiles: (files: DialFile[]) => void;
+    onRemoveFilesAccess: (files: DialFile[]) => void;
+}
+
+/**
+ * Manages upload batches (single-file and ZIP-archive extraction), including
+ * concurrency-limited progress tracking and abort. Invalidates the shared
+ * listing cache for the destination folder through `invalidateFolders`/
+ * `bumpRetry` after a batch settles — it never holds its own copy of the
+ * cache.
+ */
+export declare const useDialFileUploadBatch: ({ filesApi, bucket, rootLabel, activeTab, cache, sharedRootMetaRef, invalidateFolders, bumpRetry, onNotification, }: UseDialFileUploadBatchOptions) => UseDialFileUploadBatchResult;
+
+/** Options accepted by `useDialFileUploadBatch`. */
+export declare interface UseDialFileUploadBatchOptions {
+    /** Injected operation port used for every upload network call. */
+    filesApi: DialFilesApi;
+    /** DIAL Core bucket to browse (used only for the my_files tab). */
+    bucket: string;
+    /** Display name for the root folder node. */
+    rootLabel: string;
+    /** Active tab — drives owner-bucket resolution for the Shared tab. */
+    activeTab: DialFileManagerTabs;
+    /** Read-only snapshot of `useDialFileListing`'s cache, used to decide overwrite vs. create-only upload mode. */
+    cache: Map<string, ListFilesItemDto[]>;
+    /** Owner-bucket resolution metadata for the Shared tab, owned by `useDialFileListing`. */
+    sharedRootMetaRef: React.RefObject<Map<string, SharedRootMeta>>;
+    /** Deletes the given API-path cache keys so the next fetch re-fetches them. */
+    invalidateFolders: (apiPaths: string[]) => void;
+    /** Forces `useDialFileListing`'s fetch effect to re-run. */
+    bumpRetry: () => void;
+    /** Called when an upload batch fails or completes and should surface a toast notification. */
+    onNotification?: (notification: FileManagerNotification) => void;
+}
+
+/** Values returned by `useDialFileUploadBatch`. */
+export declare interface UseDialFileUploadBatchResult {
+    onUploadFiles: (files: DialUploadFileItem[], destinationFolder: string) => void;
+    onUploadArchive: (file: File, name: string, destinationFolder: string) => void;
+    onValidateUpload: (files: DialUploadFileItem[], existingFiles: DialFile[], destinationFolder: string) => Promise<FileUploadValidationResult>;
+    uploadBatchState: FileUploadBatchState | null;
+    cancelUpload: () => void;
+    clearUploadBatch: () => void;
+}
+
+export { useGridEditingScroll }
+
+export { UseGridEditingScrollOptions }
+
+export { UseGridEditingScrollResult }
+
+/**
+ * Converts a DialFileManager virtual path to an API folder path.
+ * e.g. "/My files" → "", "/My files/reports/" → "reports/"
+ */
+export declare const virtualPathToApiPath: (virtualPath: string, rootLabel: string) => string;
+
+/** Content payload for a custom-visualizer attachment rendered inside a sandboxed iframe. */
+declare interface VisualizerCanvasContent {
+    /** Discriminates the content type to select the correct renderer. */
+    type: AttachmentContentType.Visualizer;
+    /** Iframe `src`, resolved from the matching registry entry's `url`. */
+    url: string;
+    /** The attachment's own MIME type (not the registry entry's raw, possibly comma-separated, `contentType`). */
+    mimeType: string;
+    /** Opaque attachment payload consumed by the visualizer. */
+    data: unknown;
+    /** Presentation layout hints (`themeId`, `width`, `height`, `mobileHeight`). */
+    layout: CustomVisualizerDataLayout;
+    /** postMessage protocol namespace — MUST equal the registry entry's `title`, or the iframe never receives data. */
+    visualizerName: string;
+    /** Milliseconds to wait for a `send()` request's response before rejecting. From the registry entry; does NOT bound the handshake. */
+    requestTimeout?: number;
+}
+
+export { }