@epam/ai-dial-chat-hooks 1.2.0-dev.3 → 1.2.0-dev.38

package/file-manager-canvas.d.ts

@@ -0,0 +1,398 @@
+import { Annotation } from '@epam/ai-dial-chat-shared';
+import { AnnotationGroup } from '@epam/ai-dial-quotations';
+import { ApplicationVisualizer } from '@epam/ai-dial-chat-shared';
+import { AttachmentResource } from '@epam/ai-dial-chat-shared';
+import { CustomVisualizer } from '@epam/ai-dial-chat-shared';
+import type { CustomVisualizerDataLayout } from '@epam/ai-dial-chat-shared';
+import { DisplayAttachment } from '@epam/ai-dial-chat-shared';
+import type { GroupedAttachmentItem } from '@epam/ai-dial-chat-shared';
+import type { InputHighlightData } from '@epam/pdf-highlighter-kit';
+
+/**
+ * Builds an `OoxmlCanvasContent` for a DOCX/PPTX/XLSX citation annotation,
+ * including highlights for every annotation sharing the clicked one's source
+ * document. Returns `null` when the annotation has no source attachment,
+ * the source is not a format `@silurus/ooxml` renders as DOCX/XLSX/PPTX (a
+ * CSV source returns `null` — citation highlighting targets Office documents
+ * only), or no URL resolves.
+ */
+export declare const annotationToOoxmlCanvasContent: (annotation: Annotation, annotations: Annotation[], resolvers: AttachmentCanvasUrlResolvers) => OoxmlCanvasContent | null;
+
+/**
+ * Builds a `PdfCanvasContent` for a PDF citation annotation, including highlights
+ * for the clicked annotation's document within its citation group.
+ * 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;
+    /** Resolves a DIAL Core file id to a fetchable metadata URL (used for cache-freshness validation). */
+    resolveDialFileMetadataUrl: (fileId: string) => string | undefined;
+}
+
+/** The type of content the canvas can display. */
+declare enum AttachmentContentType {
+    PlainText = 'plain_text',
+    Image = 'image',
+    Audio = 'audio',
+    Markdown = 'markdown',
+    MarkdownTable = 'markdown_table',
+    Json = 'json',
+    Pdf = 'pdf',
+    Ooxml = 'ooxml',
+    Code = 'code',
+    Html = 'html',
+    Visualizer = 'visualizer',
+    GroupedVisualizer = 'grouped_visualizer',
+    McpApp = 'mcp_app',
+    Unsupported = 'unsupported',
+    Error = 'error',
+}
+
+/** 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',
+}
+
+/** 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;
+}
+
+/** 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;
+}
+
+/** Content payload for an application-scoped grouped visualizer: every attachment a message's visualizer claims, rendered together inside one sandboxed iframe. */
+declare interface GroupedVisualizerCanvasContent {
+    /** Discriminates the content type to select the correct renderer. */
+    type: AttachmentContentType.GroupedVisualizer;
+    /** Iframe `src`, resolved from the matching registry entry's `url`. */
+    url: string;
+    /** One item per claimed attachment, in the message's attachment order. Each `url` is absolute, resolved by the host. */
+    attachments: GroupedAttachmentItem[];
+    /** Presentation layout hints (`themeId`, `width`, `height`, `mobileHeight`) shared by every item. */
+    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;
+}
+
+/** Outcome of building a grouped visualizer payload. */
+export declare interface GroupedVisualizerResolution {
+    /** The grouped payload, or `null` when no claimed attachment resolved to a URL. */
+    content: GroupedVisualizerCanvasContent | null;
+    /** The claimed attachments that reached `content.attachments`, in the input's order. The caller returns the rest to the ordinary attachment tray. */
+    resolved: DisplayAttachment[];
+}
+
+/**
+ * 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;
+
+/** 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;
+}
+
+/** 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;
+}
+
+/** 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;
+}
+
+/** Content payload for OOXML document and CSV spreadsheet attachments. */
+declare interface OoxmlCanvasContent {
+    /** Discriminates the content type to select the correct renderer. */
+    type: AttachmentContentType.Ooxml;
+    /** Resolved download URL or object URL for the source file. */
+    url: string;
+    /** The document format used to select and configure the format-specific renderer. */
+    format: OoxmlFileType;
+    /** Cited locations to draw over the document. Omitted, never `[]`, when there is nothing to highlight. */
+    highlights?: OoxmlHighlight[];
+    /** Id of the highlight to navigate to and emphasise. Omitted when the clicked citation resolved to no location. */
+    selectedHighlightId?: string;
+}
+
+/** A 1-based cell address, matching `@silurus/ooxml`'s own `CellAddress`. */
+declare interface OoxmlCellAddress {
+    /** 1-based row number. */
+    row: number;
+    /** 1-based column number. */
+    col: number;
+}
+
+/** A cited character range inside a DOCX story, addressed by story name and source-tree path. */
+declare interface OoxmlDocxHighlightLocation {
+    /** Discriminates this location within `OoxmlHighlightLocation`. */
+    kind: OoxmlHighlightKind.DocxTextRange;
+    /** Name of the DOCX story the range lives in, as an opaque string (only `'body'` is confirmed upstream). */
+    story: string;
+    /** Source-tree element indices identifying the paragraph, matched element-wise. */
+    path: number[];
+    /** Inclusive start character offset within the story's matched text. */
+    start: number;
+    /** Exclusive end character offset, already converted from the wire's inclusive `end`. */
+    endExclusive: number;
+    /** The cited text, compared against the text resolved over `[start, endExclusive)`. */
+    text: string;
+}
+
+/** A complete table row in the DOCX body, matched by cell text. */
+declare interface OoxmlDocxTableRowLocation {
+    /** Location kind. */
+    kind: OoxmlHighlightKind.DocxTableRow;
+    /** Plain text of each cell, in column order. */
+    cells: string[];
+    /** 1-based matching row in document order. */
+    occurrence: number;
+}
+
+/** Supported document formats rendered by the installed `@silurus/ooxml` runtime. */
+declare enum OoxmlFileType {
+    Docx = 'docx',
+    Xlsx = 'xlsx',
+    Pptx = 'pptx',
+    Csv = 'csv',
+}
+
+/** One citation's highlight: the locations it resolved to, under a stable id. */
+declare interface OoxmlHighlight {
+    /** Stable id, used to mark exactly one highlight selected. */
+    id: string;
+    /** One or more locations — a single citation may carry several selectors. */
+    locations: OoxmlHighlightLocation[];
+}
+
+/** Discriminates the Office highlight location descriptors an `OoxmlCanvasContent` can carry. */
+declare enum OoxmlHighlightKind {
+    /** A character range inside a DOCX story, addressed by story name and source-tree path. */
+    DocxTextRange = 'docxTextRange',
+    /** A character range inside a single PPTX shape on one slide. */
+    PptxTextRange = 'pptxTextRange',
+    /** A complete DOCX table row identified by its cell text. */
+    DocxTableRow = 'docxTableRow',
+    /** A complete PPTX table row identified by its cell text on one slide. */
+    PptxTableRow = 'pptxTableRow',
+    /** One cell, or a contiguous same-row cell range, on a named XLSX sheet. */
+    XlsxCellRange = 'xlsxCellRange',
+}
+
+/** A cited location inside an Office document, in document coordinates. */
+declare type OoxmlHighlightLocation =
+| OoxmlDocxHighlightLocation
+| OoxmlPptxHighlightLocation
+| OoxmlDocxTableRowLocation
+| OoxmlPptxTableRowLocation
+| OoxmlXlsxHighlightLocation;
+
+/** A cited character range inside a single shape on one PPTX slide. */
+declare interface OoxmlPptxHighlightLocation {
+    /** Discriminates this location within `OoxmlHighlightLocation`. */
+    kind: OoxmlHighlightKind.PptxTextRange;
+    /** 1-based slide number. */
+    slide: number;
+    /** Shape identifier, compared as a string against the run's own `shapeId`. */
+    shapeId: string;
+    /** Inclusive start character offset within the shape's matched text. */
+    start: number;
+    /** Exclusive end character offset, already converted from the wire's inclusive `end`. */
+    endExclusive: number;
+    /** The cited text, compared against the text resolved over `[start, endExclusive)`. */
+    text: string;
+}
+
+/** A complete table row on one PPTX slide, matched by cell text. */
+declare interface OoxmlPptxTableRowLocation {
+    /** Location kind. */
+    kind: OoxmlHighlightKind.PptxTableRow;
+    /** Plain text of each cell, in column order. */
+    cells: string[];
+    /** 1-based matching row on the specified slide. */
+    occurrence: number;
+    /** 1-based slide number. */
+    slide: number;
+}
+
+/** A cited cell, or contiguous same-row cell range, on a named XLSX sheet. */
+declare interface OoxmlXlsxHighlightLocation {
+    /** Discriminates this location within `OoxmlHighlightLocation`. */
+    kind: OoxmlHighlightKind.XlsxCellRange;
+    /** Sheet name, matched exactly against the workbook's own sheet names. */
+    sheet: string;
+    /** First cell of the range. 1-based, passed to the viewer unconverted. */
+    start: OoxmlCellAddress;
+    /** Last cell of the range, on the same row as `start`. Omitted for a single cell. */
+    end?: OoxmlCellAddress;
+}
+
+/** 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;
+    /** 1-based page to navigate to on initial load, independent of highlight geometry. */
+    page?: number;
+}
+
+/** 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 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;
+
+/** 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>;
+
+/**
+ * Builds the grouped payload for an application-scoped visualizer from the
+ * attachments its entry claims, reporting which of them `resolveAbsoluteUrl`
+ * could produce a URL for. Unlike the single-attachment resolver this fetches
+ * nothing: the grouped protocol hands the visualizer URLs and lets it read
+ * them itself, so the URLs must be absolute — a host-relative path would
+ * resolve against the iframe's own origin. Producing one is host knowledge,
+ * which is why it arrives as a callback rather than being built here.
+ */
+export declare const resolveGroupedVisualizerCanvasContent: (attachments: DisplayAttachment[], resolveAbsoluteUrl: (attachment: DisplayAttachment) => string | undefined, entry: ApplicationVisualizer, themeId: string) => GroupedVisualizerResolution;
+
+/**
+ * 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 a local blob URL or the BFF download URL directly so the
+ * browser cache can be shared with the conversation view's `<img>` element.
+ * A local `File` with bytes takes precedence over the DIAL download URL; a
+ * 0-byte `File` (the file-manager placeholder) does not. 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 or CSV renderer payload from a DisplayAttachment, or `null` if unavailable. */
+export declare const resolveOoxmlCanvasContent: (attachment: DisplayAttachment, resolvers: AttachmentCanvasUrlResolvers, format: OoxmlFileType) => Promise<OoxmlCanvasContent | ErrorCanvasContent | null>;
+
+/** 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>;
+
+/** 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>;
+
+/** 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 { }

package/file-manager-canvas.js

@@ -0,0 +1,2 @@
+import { annotationToOoxmlCanvasContent as e, annotationToPdfCanvasContent as t, clearAttachmentCache as n, hasAttachmentTextSource as r, referenceAttachmentToPdfCanvasContent as i, resolveCodeCanvasContent as a, resolveGroupedVisualizerCanvasContent as o, resolveHtmlCanvasContent as s, resolveImageCanvasContent as c, resolveJsonCanvasContent as l, resolveMarkdownCanvasContent as u, resolveOoxmlCanvasContent as d, resolvePdfCanvasContent as f, resolveTextCanvasContent as p, resolveVisualizerCanvasContent as m } from "./files/attachment-canvas.js";
+export { e as annotationToOoxmlCanvasContent, t as annotationToPdfCanvasContent, n as clearAttachmentCache, r as hasAttachmentTextSource, i as referenceAttachmentToPdfCanvasContent, a as resolveCodeCanvasContent, o as resolveGroupedVisualizerCanvasContent, s as resolveHtmlCanvasContent, c as resolveImageCanvasContent, l as resolveJsonCanvasContent, u as resolveMarkdownCanvasContent, d as resolveOoxmlCanvasContent, f as resolvePdfCanvasContent, p as resolveTextCanvasContent, m as resolveVisualizerCanvasContent };