@files-preview-app/preview-file 1.3.0 → 1.3.2

package/dist/index.d-B79v0jxi.d.cts

@@ -0,0 +1,570 @@
+/**
+ * Supported file input sources.
+ * Accepts URL strings, File objects, Blobs, ArrayBuffers, or Uint8Arrays.
+ */
+type FileSource = string | File | Blob | ArrayBuffer | Uint8Array;
+/** Metadata extracted from a file source */
+interface FileMetadata {
+    /** Original filename (if available) */
+    name?: string;
+    /** File size in bytes */
+    size?: number;
+    /** Detected MIME type */
+    mimeType?: string;
+    /** File extension (lowercase, with dot, e.g. '.pdf') */
+    extension?: string;
+}
+/** Information about a resolved file, ready for plugin matching */
+interface FileInfo {
+    metadata: FileMetadata;
+    buffer: ArrayBuffer;
+}
+/** Toolbar action types */
+type ToolbarActionType = 'button' | 'toggle' | 'range' | 'input' | 'separator' | 'page-nav';
+/** Toolbar action group names for visual grouping */
+type ToolbarGroup = 'navigation' | 'zoom' | 'view' | 'actions';
+/** Represents a single toolbar action/control */
+interface ToolbarAction {
+    /** Unique action identifier */
+    id: string;
+    /** SVG icon markup string */
+    icon: string;
+    /** Accessible label */
+    label: string;
+    /** Type of control to render */
+    type: ToolbarActionType;
+    /** Visual group placement */
+    group: ToolbarGroup;
+    /** Whether the action is currently enabled */
+    enabled?: boolean;
+    /** Whether a toggle is currently active */
+    active?: boolean;
+    /** Execute the action */
+    execute: (...args: unknown[]) => void;
+    /** For 'range' type: min/max/step/value */
+    min?: number;
+    max?: number;
+    step?: number;
+    value?: number;
+}
+/** Represents a thumbnail in the sidebar */
+interface Thumbnail {
+    /** Page/sheet/frame index */
+    index: number;
+    /** Display label (e.g., "Page 1", "Sheet: Revenue") */
+    label: string;
+    /** Renders the thumbnail into a canvas element */
+    render: (canvas: HTMLCanvasElement) => Promise<void>;
+}
+/** Instance returned after a file is rendered — exposes controls */
+interface PreviewInstance {
+    /** Clean up all resources */
+    destroy(): void;
+    zoomIn?(): void;
+    zoomOut?(): void;
+    getZoom?(): number;
+    setZoom?(level: number): void;
+    fitToPage?(): void;
+    fitToWidth?(): void;
+    goToPage?(page: number): void;
+    getPageCount?(): number;
+    getCurrentPage?(): number;
+    rotateCW?(): void;
+    rotateCCW?(): void;
+    getRotation?(): number;
+    play?(): void;
+    pause?(): void;
+    isPlaying?(): boolean;
+    fastForward?(seconds?: number): void;
+    rewind?(seconds?: number): void;
+    setPlaybackRate?(rate: number): void;
+    getPlaybackRate?(): number;
+    getThumbnails?(): Thumbnail[] | Promise<Thumbnail[]>;
+    toggleThumbnails?(): void;
+    download?(): void;
+    print?(): void;
+    [key: string]: unknown;
+}
+/** Context passed to a plugin's render function */
+interface RenderContext {
+    /** The container DOM element to render into */
+    container: HTMLElement;
+    /** Original file source */
+    source: FileSource;
+    /** Resolved file metadata */
+    metadata: FileMetadata;
+    /** File content as ArrayBuffer */
+    buffer: ArrayBuffer;
+    /** Viewer options */
+    options: PreviewViewerOptions;
+    /** AbortSignal for cancellation */
+    signal: AbortSignal;
+    /** Emit an event to the viewer */
+    emit: (event: string, payload?: unknown) => void;
+}
+/** Plugin interface — each file format renderer implements this */
+interface PreviewPlugin {
+    /** Unique plugin identifier */
+    id: string;
+    /** Human-readable plugin name */
+    name: string;
+    /** File extensions this plugin handles (e.g., ['.pdf']) */
+    extensions: string[];
+    /** MIME types this plugin handles */
+    mimeTypes: string[];
+    /** Priority when multiple plugins match (higher = preferred) */
+    weight?: number;
+    /** Check if this plugin can handle the given file */
+    supports(file: FileInfo): boolean | Promise<boolean>;
+    /** Return toolbar actions for the rendered instance */
+    getToolbarActions(instance: PreviewInstance): ToolbarAction[];
+    /** Render the file into the container */
+    render(ctx: RenderContext): Promise<PreviewInstance>;
+}
+/** Configuration to selectively enable or disable individual toolbar functions/buttons */
+interface ToolbarConfig {
+    /** Page navigation (< [1] / N >) */
+    pageNav?: boolean;
+    pagination?: boolean;
+    prevPage?: boolean;
+    nextPage?: boolean;
+    /** Zoom controls */
+    zoomIn?: boolean;
+    zoomOut?: boolean;
+    fitPage?: boolean;
+    fitToPage?: boolean;
+    fitWidth?: boolean;
+    zoomReset?: boolean;
+    /** View controls */
+    rotate?: boolean;
+    rotateCW?: boolean;
+    rotateCCW?: boolean;
+    fullscreen?: boolean;
+    thumbnails?: boolean;
+    /** Action controls */
+    download?: boolean;
+    print?: boolean;
+    openWindow?: boolean;
+    openSeparateWindow?: boolean;
+    copy?: boolean;
+    /** Media controls */
+    play?: boolean;
+    pause?: boolean;
+    fastForward?: boolean;
+    rewind?: boolean;
+    speed?: boolean;
+}
+/** Viewer configuration options */
+interface PreviewViewerOptions extends ToolbarConfig {
+    /** Color theme */
+    theme?: 'light' | 'dark' | 'auto';
+    /** Locale for UI labels */
+    locale?: string;
+    /** Initial zoom level (1.0 = 100%) */
+    zoom?: number;
+    /** Initial page number (1-based) */
+    page?: number;
+    /** Show the toolbar */
+    showToolbar?: boolean;
+    /** Detailed toolbar configuration (or boolean to show/hide entire toolbar) */
+    toolbar?: boolean | (ToolbarConfig & Record<string, boolean | undefined>);
+    /** Toolbar position */
+    toolbarPosition?: 'top' | 'bottom';
+    /** Fit mode: 'page' (fill frame width with minimal margins) or 'width' */
+    fitMode?: 'page' | 'width';
+    /** Show thumbnail sidebar initially */
+    showThumbnails?: boolean;
+    /** Whether to display the file name / title bar above the toolbar in the preview panel (defaults to true) */
+    showFileName?: boolean;
+    /** Custom file name / title override to display */
+    fileName?: string;
+    /** Custom CSS class for the container */
+    className?: string;
+    /** Plugin-specific options */
+    pluginOptions?: Record<string, unknown>;
+    /** Optional file metadata overrides (name, extension, mimeType, etc.) */
+    metadata?: FileMetadata;
+    /** Custom URL to navigate when "Open in Separate Full Window" is clicked */
+    standaloneViewerUrl?: string;
+    /** Custom handler for opening preview in a separate window */
+    onOpenSeparateWindow?: (payload: {
+        buffer: ArrayBuffer;
+        metadata: FileMetadata;
+        options: PreviewViewerOptions;
+    }) => Window | null;
+    /** Internal flag: true when viewer is rendered inside separate full window */
+    _isSeparateWindow?: boolean;
+    /** Allow custom/plugin-specific options */
+    [key: string]: unknown;
+}
+/** Events emitted by the viewer */
+type PreviewEvent = 'loading' | 'loaded' | 'error' | 'page-change' | 'zoom-change' | 'rotate' | 'destroy';
+/** Event handler function */
+type EventHandler<T = unknown> = (data: T) => void;
+/** Unsubscribe function returned by on() */
+type Unsubscribe = () => void;
+
+/**
+ * Main file preview viewer engine.
+ * Manages plugins, rendering lifecycle, toolbar, and thumbnails.
+ */
+declare class FilePreviewViewer {
+    private plugins;
+    private activeInstance;
+    private abortController;
+    private eventEmitter;
+    private toolbar;
+    private thumbnailPanel;
+    private wrapperEl;
+    private contentEl;
+    private currentBuffer;
+    private currentMetadata;
+    private keyHandler;
+    private currentContainer;
+    private currentOptions;
+    private resizeObserver;
+    private fullscreenHandler;
+    private titleBarEl;
+    /**
+     * Register a preview plugin.
+     */
+    registerPlugin(plugin: PreviewPlugin): this;
+    /**
+     * Register multiple plugins at once.
+     */
+    registerPlugins(plugins: PreviewPlugin[]): this;
+    /**
+     * Preview a file in the given container element.
+     */
+    preview(container: HTMLElement, source: FileSource, options?: PreviewViewerOptions): Promise<PreviewInstance>;
+    /**
+     * Opens the current file preview in a separate full browser window.
+     */
+    openInSeparateWindow(): Window | null;
+    /**
+     * Subscribe to viewer events.
+     */
+    on(event: string, handler: EventHandler): Unsubscribe;
+    /**
+     * Destroy the viewer and clean up all resources.
+     */
+    destroy(): void;
+    /**
+     * Get the currently active preview instance.
+     */
+    getInstance(): PreviewInstance | null;
+    /**
+     * Configure toolbar features dynamically through options or methods.
+     * e.g. viewer.setToolbarConfig({ zoomIn: false, print: false })
+     */
+    setToolbarConfig(config: ToolbarConfig): void;
+    /**
+     * Get current toolbar configuration.
+     */
+    getToolbarConfig(): ToolbarConfig;
+    /**
+     * Hide a specific toolbar action by ID or alias (e.g. 'zoom-in', 'print', 'download').
+     */
+    hideToolbarAction(actionId: string): void;
+    /**
+     * Show a specific toolbar action by ID or alias.
+     */
+    showToolbarAction(actionId: string): void;
+    /**
+     * Enable a specific toolbar action button.
+     */
+    enableToolbarAction(actionId: string): void;
+    /**
+     * Disable a specific toolbar action button.
+     */
+    disableToolbarAction(actionId: string): void;
+    /**
+     * Fit document to page so it fills the frame width with minimal margins.
+     */
+    fitToPage(): void;
+    /**
+     * Zoom in.
+     */
+    zoomIn(): void;
+    /**
+     * Zoom out.
+     */
+    zoomOut(): void;
+    /**
+     * Set specific zoom level.
+     */
+    setZoom(level: number): void;
+    /**
+     * Get current zoom level.
+     */
+    getZoom(): number;
+    /**
+     * Rotate 90 degrees clockwise.
+     */
+    rotateCW(): void;
+    /**
+     * Rotate 90 degrees counter-clockwise.
+     */
+    rotateCCW(): void;
+    /**
+     * Navigate to a specific page number.
+     */
+    goToPage(page: number): void;
+    /**
+     * Navigate to next page.
+     */
+    nextPage(): void;
+    /**
+     * Navigate to previous page.
+     */
+    prevPage(): void;
+    /**
+     * Get total page count.
+     */
+    getPageCount(): number;
+    /**
+     * Get current page number.
+     */
+    getCurrentPage(): number;
+    /**
+     * Download the current document.
+     */
+    download(): void;
+    /**
+     * Print the current document.
+     */
+    print(): void;
+    /**
+     * Toggle fullscreen mode.
+     */
+    toggleFullscreen(): void;
+    /**
+     * Toggle thumbnails sidebar panel.
+     */
+    toggleThumbnails(): void;
+    /**
+     * Set whether to display the file name / title bar above the toolbar.
+     */
+    setShowFileName(show: boolean): void;
+    /**
+     * Set or override the displayed file name in the preview panel.
+     */
+    setFileName(name: string): void;
+    private updateTitleBar;
+    private extractToolbarConfig;
+    private abort;
+    private destroyInstance;
+    private findPlugin;
+    private setupDOM;
+    private setupResizeAndFullscreenListeners;
+    private setupKeyboardShortcuts;
+    private setupDragAndDrop;
+    private showLoading;
+    private hideLoading;
+    private showError;
+}
+
+/**
+ * Lightweight typed event emitter for the file preview system.
+ * Supports on/off/emit with automatic cleanup.
+ */
+declare class EventEmitter {
+    private listeners;
+    /**
+     * Subscribe to an event.
+     * @returns An unsubscribe function.
+     */
+    on(event: string, handler: EventHandler): Unsubscribe;
+    /**
+     * Unsubscribe from an event.
+     */
+    off(event: string, handler: EventHandler): void;
+    /**
+     * Emit an event with optional payload.
+     */
+    emit(event: string, data?: unknown): void;
+    /**
+     * Remove all listeners, optionally for a specific event.
+     */
+    removeAll(event?: string): void;
+    /**
+     * Get the count of listeners for a specific event.
+     */
+    listenerCount(event: string): number;
+}
+
+/**
+ * Detect MIME type from file buffer magic bytes.
+ */
+declare function detectMagicBytes(buffer: ArrayBuffer): string | null;
+/**
+ * Detect ZIP sub-type (OOXML or OpenDocument) by checking ZIP entry names.
+ * All OOXML formats use ZIP container with PK header.
+ * OpenDocument formats also use ZIP with a 'mimetype' entry at offset 0.
+ */
+declare function detectOoxmlType(buffer: ArrayBuffer): string | null;
+/**
+ * Extract file extension from a filename or URL.
+ */
+declare function extractExtension(nameOrUrl: string): string | undefined;
+/**
+ * Get MIME type from file extension.
+ */
+declare function mimeFromExtension(extension: string): string | undefined;
+/**
+ * Convert any FileSource to ArrayBuffer.
+ */
+declare function sourceToArrayBuffer(source: FileSource, signal?: AbortSignal): Promise<{
+    buffer: ArrayBuffer;
+    metadata: FileMetadata;
+}>;
+
+/**
+ * Sanitize HTML string using DOMPurify to prevent XSS.
+ */
+declare function sanitizeHTML(html: string): string;
+/**
+ * Sanitize SVG string using DOMPurify.
+ */
+declare function sanitizeSVG(svg: string): string;
+/**
+ * Download a file from an ArrayBuffer.
+ */
+declare function downloadFile(buffer: ArrayBuffer, filename: string, mimeType?: string): void;
+/**
+ * Print an HTML element by opening a print window.
+ */
+declare function printElement(element: HTMLElement, title?: string): void;
+/**
+ * Format file size in human-readable format.
+ */
+declare function formatFileSize(bytes: number): string;
+/**
+ * Debounce a function call.
+ */
+declare function debounce<T extends (...args: unknown[]) => void>(fn: T, delay: number): (...args: Parameters<T>) => void;
+/**
+ * Clamp a number between min and max.
+ */
+declare function clamp(value: number, min: number, max: number): number;
+/**
+ * Create a DOM element with optional attributes and children.
+ */
+declare function createElement<K extends keyof HTMLElementTagNameMap>(tag: K, attrs?: Record<string, string>, ...children: (string | Node)[]): HTMLElementTagNameMap[K];
+
+declare class ToolbarController {
+    private el;
+    private toolbarEl;
+    private actions;
+    private config;
+    private pageInputEl;
+    private pageLabelEl;
+    private prevPageBtn;
+    private nextPageBtn;
+    constructor(container: HTMLElement, config?: ToolbarConfig);
+    setConfig(config: ToolbarConfig): void;
+    getConfig(): ToolbarConfig;
+    hideAction(actionId: string): void;
+    showAction(actionId: string): void;
+    private normalizeActionId;
+    enableAction(actionId: string): void;
+    disableAction(actionId: string): void;
+    setActionActive(actionId: string, active: boolean): void;
+    isActionEnabled(action: ToolbarAction): boolean;
+    setPage(page: number, max?: number): void;
+    update(actions: ToolbarAction[]): void;
+    show(): void;
+    hide(): void;
+    destroy(): void;
+    private render;
+    private createButton;
+}
+
+declare class ThumbnailPanel {
+    private el;
+    private panelEl;
+    private listEl;
+    private headerEl;
+    private thumbnails;
+    private onSelect?;
+    private onToggleCallback?;
+    private activeIndex;
+    private observer?;
+    private renderedIndices;
+    constructor(container: HTMLElement, onToggle?: (isOpen: boolean) => void);
+    isOpen(): boolean;
+    update(thumbnails: Thumbnail[], onSelect: (index: number) => void): void;
+    setActive(index: number): void;
+    show(): void;
+    hide(): void;
+    toggle(): void;
+    destroy(): void;
+    renderAllVisible(): void;
+    private renderThumbnailItem;
+    private render;
+}
+
+/**
+ * IndexedDB and in-memory document transfer utility for cross-window preview opening.
+ */
+interface TransferPayload {
+    buffer: ArrayBuffer;
+    metadata?: {
+        name?: string;
+        extension?: string;
+        mimeType?: string;
+        size?: number;
+    };
+    options?: Record<string, any>;
+}
+/**
+ * Save file payload to IndexedDB and window storage for cross-window retrieval.
+ */
+declare function saveTransferPayload(id: string, payload: TransferPayload): Promise<void>;
+/**
+ * Retrieve transferred file payload from opener window or IndexedDB.
+ */
+declare function getTransferPayload(id: string): Promise<TransferPayload | null>;
+
+/**
+ * Compound File Binary Format (CFBF / OLE2) parser.
+ * Implements Microsoft [MS-CFB] specification for legacy Office formats (.doc, .ppt, .xls).
+ * Zero external dependencies, client-side browser and Node.js compatible.
+ */
+interface CfbfEntry {
+    name: string;
+    type: number;
+    size: number;
+    startSector: number;
+}
+declare class CfbfReader {
+    private view;
+    private u8;
+    private sectorSize;
+    private miniSectorSize;
+    private miniStreamCutoff;
+    private fat;
+    private miniFat;
+    private entries;
+    private miniStream;
+    constructor(buffer: ArrayBuffer);
+    /** Check if the magic 8-byte signature matches [MS-CFB] */
+    isValid(): boolean;
+    /** Return all directory stream/storage entries found in the file */
+    listEntries(): CfbfEntry[];
+    /** Check if a stream exists */
+    hasStream(name: string): boolean;
+    /**
+     * Read raw bytes of a named stream (e.g. "WordDocument", "PowerPoint Document", "Workbook")
+     */
+    readStream(name: string): Uint8Array | null;
+    private findEntryCaseInsensitive;
+    private getSectorOffset;
+    private parseFat;
+    private parseDirectory;
+    private parseMiniFat;
+    private readRegularStream;
+    private readMiniStream;
+}
+
+export { sanitizeHTML as A, sanitizeSVG as B, type CfbfEntry as C, saveTransferPayload as D, EventEmitter as E, type FileSource as F, sourceToArrayBuffer as G, type PreviewPlugin as P, type RenderContext as R, type Thumbnail as T, type Unsubscribe as U, type PreviewViewerOptions as a, type PreviewInstance as b, FilePreviewViewer as c, CfbfReader as d, type EventHandler as e, type FileInfo as f, type FileMetadata as g, type PreviewEvent as h, ThumbnailPanel as i, type ToolbarAction as j, type ToolbarActionType as k, type ToolbarConfig as l, ToolbarController as m, type ToolbarGroup as n, type TransferPayload as o, clamp as p, createElement as q, debounce as r, detectMagicBytes as s, detectOoxmlType as t, downloadFile as u, extractExtension as v, formatFileSize as w, getTransferPayload as x, mimeFromExtension as y, printElement as z };