@epam/ai-dial-react-pdf-highlighter 0.1.0-rc.0

package/dist/src/components/PdfViewer/PdfViewer.d.ts

@@ -0,0 +1,35 @@
+import { PDFSource, InputHighlightData } from '@epam/pdf-highlighter-kit';
+import { FC } from 'react';
+import { PdfViewerApi } from '../../models/pdf-viewer.models';
+/**
+ * Props for the low-level PDF rendering component.
+ */
+export interface PdfViewerProps {
+    /** PDF source: a URL string, `Blob`, or `ArrayBuffer`. */
+    pdf: PDFSource;
+    /** Highlight data rendered by pdf-highlighter-kit. */
+    highlights: InputHighlightData[];
+    /** Zoom mode: `auto`, `page-fit`, or stringified numeric value such as `1.25`. */
+    zoom?: string;
+    /** Highlight id to navigate to after highlights are loaded. */
+    selectedHighlightId?: string;
+    /** Auto-focus the first highlight when highlights are loaded. */
+    autoFocusFirstHighlight?: boolean;
+    /** Navigates to this page after viewer initialization. */
+    selectedPageNumber?: number;
+    /** Additional class name for the root viewer container. */
+    containerClassName?: string;
+    /** Callback invoked when total pages become available. */
+    onTotalPagesChange?: (totalPages: number) => void;
+    /** Callback invoked with an imperative API when viewer setup completes. */
+    onViewerReady?: (api: PdfViewerApi) => void;
+    /** Optional list of pages to load instead of the full document. */
+    selectedPages?: number[];
+}
+/**
+ * Low-level PDF viewer wrapper around `PDFHighlightViewer`.
+ *
+ * This component is intended for scenarios where only rendering/navigation logic is needed
+ * without the higher-level toolbar and overlays from `DocumentPreview`.
+ */
+export declare const PDFViewer: FC<PdfViewerProps>;

package/dist/src/constants/pdf-viewer.constants.d.ts

@@ -0,0 +1,12 @@
+import { ZoomOption } from '../models/pdf-viewer.models';
+export declare const AUTO_ZOOM_ID = "auto";
+export declare const FIT_ZOOM_ID = "page-fit";
+export declare const ZOOM_OPTIONS: ZoomOption[];
+export declare const THUMBNAIL_IMAGE_OPTIONS: {
+    maxWidth: number;
+    format: "image/jpeg";
+    quality: number;
+};
+export declare const THUMBNAIL_BATCH_SIZE = 15;
+export declare const CONTENT_TYPE_PDF = "application/pdf";
+export declare const FILE_EXTENSION_PDF = ".pdf";

package/dist/src/constants/storybook.d.ts

@@ -0,0 +1,2 @@
+import { InputHighlightData } from '@epam/pdf-highlighter-kit';
+export declare const sampleHighlights: InputHighlightData[];

package/dist/src/context/documentCacheContext.d.ts

@@ -0,0 +1,2 @@
+import { DocumentCacheContextValue } from '../models/document-cache.models';
+export declare const DocumentPreviewCacheContext: import('react').Context<DocumentCacheContextValue | null>;

package/dist/src/context/documentCacheProvider.d.ts

@@ -0,0 +1,15 @@
+import { FC, PropsWithChildren } from 'react';
+interface DocumentCacheProviderProps extends PropsWithChildren {
+    /** TTL in milliseconds. Default: 1 200 000 ms (20 min) */
+    ttlMs?: number;
+    /** Maximum number of cached entries (LRU). Default: 20 */
+    maxEntries?: number;
+}
+/**
+ * Provides blob caching for document fetches with TTL expiration and LRU eviction.
+ *
+ * Wrap the subtree that renders `DocumentPreview` to avoid repeated network requests
+ * for frequently opened files.
+ */
+export declare const DocumentCacheProvider: FC<DocumentCacheProviderProps>;
+export {};

package/dist/src/hooks/useDocumentPreview.d.ts

@@ -0,0 +1,7 @@
+import { UseDocumentPreviewOptions, UseDocumentPreviewResult } from '../models/document-preview.models';
+/**
+ * Encapsulates all logic for the document preview: file loading (with optional
+ * cache integration), highlight index navigation, zoom state, and thumbnail
+ * generation. Pair with a UI layer to build a custom document preview.
+ */
+export declare const useDocumentPreview: ({ fileUrl, fileName, loadFileCb, highlights, selectedPageNumber: _selectedPageNumber, onTotalPagesChange: _onTotalPagesChange, thumbnailPageNumbers, onThumbnailsLoaded, onViewerReady, showLoaderOverlay, selectedPages: _selectedPages, }: UseDocumentPreviewOptions) => UseDocumentPreviewResult;

package/dist/src/hooks/useDocumentPreviewCache.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns the current document preview cache context.
+ *
+ * When used outside `DocumentPreviewCacheProvider`, returns `null`.
+ */
+export declare const useDocumentPreviewCache: () => import('../models/document-cache.models').DocumentCacheContextValue | null;

package/dist/src/index.d.ts

@@ -0,0 +1,16 @@
+export { PDFViewer } from './components/PdfViewer/PdfViewer';
+export type { PdfViewerProps } from './components/PdfViewer/PdfViewer';
+export { DocumentPreview } from './components/DocumentPreview/DocumentPreview';
+export type { DocumentPreviewProps } from './components/DocumentPreview/DocumentPreview';
+export { DocumentCacheProvider as DocumentPreviewCacheProvider } from './context/documentCacheProvider';
+export { useDocumentPreviewCache } from './hooks/useDocumentPreviewCache';
+export { useDocumentPreview } from './hooks/useDocumentPreview';
+export type { UseDocumentPreviewResult } from './models/document-preview.models';
+export { PdfPreviewLoader } from './components/PdfPreviewLoader/PdfPreviewLoader';
+export type { PdfPreviewLoaderProps } from './components/PdfPreviewLoader/PdfPreviewLoader';
+export { PageThumbnail } from './components/PageThumbnail/PageThumbnail';
+export type { PageThumbnailProps } from './components/PageThumbnail/PageThumbnail';
+export type { PdfViewerApi } from './models/pdf-viewer.models';
+export type { ZoomOption } from './models/pdf-viewer.models';
+export { AUTO_ZOOM_ID, FIT_ZOOM_ID, THUMBNAIL_BATCH_SIZE, THUMBNAIL_IMAGE_OPTIONS, ZOOM_OPTIONS, } from './constants/pdf-viewer.constants';
+export { getStepZoomOptionValue, isPdfFile } from './utils/pdf-viewer.utils';

package/dist/src/models/document-cache.models.d.ts

@@ -0,0 +1,17 @@
+export interface DocumentCacheContextValue {
+    /**
+     * Returns a cached file when available, or invokes `loader` and caches the result.
+     */
+    getFile: (url: string, loader: () => Promise<Blob>) => Promise<Blob>;
+    /** Clears all cached entries immediately. */
+    clearCache: () => void;
+}
+/** Internal cache record for a loaded or in-flight document blob. */
+export interface CacheEntry {
+    /** In-flight loader promise used for request coalescing. */
+    promise?: Promise<Blob>;
+    /** Resolved blob value when loading succeeded. */
+    file?: Blob;
+    /** Last touch timestamp used for TTL checks and LRU ordering. */
+    timestamp: number;
+}

package/dist/src/models/document-preview.models.d.ts

@@ -0,0 +1,33 @@
+import { InputHighlightData } from '@epam/pdf-highlighter-kit';
+import { PdfViewerApi } from './pdf-viewer.models';
+export interface UseDocumentPreviewOptions {
+    fileUrl: string;
+    fileName?: string;
+    loadFileCb: (url: string) => Promise<Blob>;
+    highlights: InputHighlightData[];
+    selectedPageNumber?: number;
+    onTotalPagesChange?: (totalPages: number) => void;
+    thumbnailPageNumbers?: number[];
+    onThumbnailsLoaded?: (map: Map<number, string>) => void;
+    onViewerReady?: (api: PdfViewerApi) => void;
+    showLoaderOverlay?: boolean;
+    selectedPages?: number[];
+}
+export interface UseDocumentPreviewResult {
+    file: Blob | null;
+    isLoading: boolean | null;
+    isError: boolean;
+    isSupportedFile: boolean;
+    activeHighlightIndex: number;
+    zoom: string;
+    setZoom: (value: string) => void;
+    zoomSelectOptions: {
+        value: string;
+        label: string;
+    }[];
+    viewerApiRef: React.RefObject<PdfViewerApi | null>;
+    showLoader: boolean;
+    changeIndex: (dir: 1 | -1) => void;
+    handleZoomChange: (dir?: 1 | -1) => void;
+    handleViewerReady: (api: PdfViewerApi) => void;
+}

package/dist/src/models/pdf-viewer.models.d.ts

@@ -0,0 +1,25 @@
+import { ThumbnailOptions } from '@epam/pdf-highlighter-kit';
+/**
+ * Imperative API exposed by {@link PDFViewer} through the `onViewerReady` callback.
+ */
+export interface PdfViewerApi {
+    /**
+     * Generates data URLs for requested pages.
+     *
+     * @param pageNumbers 1-based page numbers to render thumbnails for.
+     * @param options Rendering options forwarded to pdf-highlighter-kit.
+     */
+    getThumbnailsDataUrl: (pageNumbers: number[], options?: ThumbnailOptions) => Promise<Map<number, string>>;
+    /** Increases current zoom level by one viewer step. */
+    zoomIn: () => void;
+    /** Decreases current zoom level by one viewer step. */
+    zoomOut: () => void;
+    /** Returns the current numeric zoom value. */
+    getZoom: () => number;
+    /** Navigates to a specific 1-based page number. */
+    navigateToPage: (page: number) => void;
+}
+export interface ZoomOption {
+    value: string;
+    label: string;
+}

package/dist/src/utils/pdf-viewer.utils.d.ts

@@ -0,0 +1,2 @@
+export declare const getStepZoomOptionValue: (currentZoom: string, direction: 1 | -1, actualZoom?: number) => string;
+export declare function isPdfFile(name?: string | null | undefined, contentType?: string | null | undefined): boolean;

package/package.json

@@ -0,0 +1,111 @@
+{
+  "name": "@epam/ai-dial-react-pdf-highlighter",
+  "version": "0.1.0-rc.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "description": "React components for PDF viewing and highlighting, built on @epam/pdf-highlighter-kit",
+  "types": "dist/src/index.d.ts",
+  "engines": {
+    "node": ">=22.2.0",
+    "npm": ">=10.7.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/ai-dial-react-pdf-highlighter.es.js",
+      "require": "./dist/ai-dial-react-pdf-highlighter.cjs.js"
+    },
+    "./styles.css": {
+      "require": "./dist/index.css",
+      "default": "./dist/index.css"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": [
+    "*.css",
+    "*.scss"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build && npm run build:css",
+    "build:css": "tailwindcss -m -i ./src/styles/tailwind-entry.scss -o ./dist/index.css",
+    "lint": "eslint . --ext ts,tsx --fix --report-unused-disable-directives --max-warnings 0",
+    "lint:check": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
+    "typecheck": "tsc --noEmit",
+    "test:run": "vitest run",
+    "verify:agent-hook": "npm run typecheck && npm run lint:check && npm run test:run",
+    "format": "prettier --check .",
+    "format-fix": "prettier --write .",
+    "preview": "vite preview",
+    "storybook": "concurrently \"npm run storybook:css\" \"storybook dev -p 6007\"",
+    "storybook:css": "tailwindcss -w -i ./src/styles/tailwind-entry.scss -o ./src/index.css",
+    "build-storybook": "concurrently \"npm run build-storybook:css\" \"storybook build\"",
+    "build-storybook:css": "tailwindcss -m -i ./src/styles/tailwind-entry.scss -o ./src/index.css",
+    "prepare": "husky",
+    "publish": "node tools/publish-lib.mjs",
+    "publish:dry": "node tools/publish-lib.mjs --dry",
+    "test": "vitest --coverage"
+  },
+  "lint-staged": {
+    "*.{ts,tsx}": [
+      "npm run lint"
+    ]
+  },
+  "peerDependencies": {
+    "@epam/ai-dial-ui-kit": ">=0.8.0",
+    "@epam/pdf-highlighter-kit": ">=0.0.13",
+    "@tabler/icons-react": "^3.0.0",
+    "pdfjs-dist": ">=4.0.0",
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "devDependencies": {
+    "@chromatic-com/storybook": "^4.1.3",
+    "@epam/ai-dial-ui-kit": "0.9.0-rc.20",
+    "@epam/pdf-highlighter-kit": "^0.0.13",
+    "@eslint/compat": "^1.3.1",
+    "@eslint/eslintrc": "^3.3.1",
+    "@eslint/js": "^9.31.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@storybook/addon-a11y": "^10.2.17",
+    "@storybook/addon-docs": "^10.2.17",
+    "@storybook/addon-vitest": "^10.2.17",
+    "@storybook/react-vite": "^10.2.17",
+    "@tabler/icons-react": "^3.36.1",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.3.0",
+    "@types/node": "^22.15.30",
+    "@types/react": "^19.1.8",
+    "@types/react-dom": "^19.1.6",
+    "@vitejs/plugin-react": "^4.6.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "autoprefixer": "^10.4.21",
+    "concurrently": "^9.2.0",
+    "esbuild": "^0.25.9",
+    "eslint": "^9.30.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.3",
+    "eslint-plugin-react": "7.37.5",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "eslint-plugin-react-refresh": "^0.4.20",
+    "eslint-plugin-storybook": "^10.2.17",
+    "globals": "^16.3.0",
+    "husky": "^9.1.7",
+    "jsdom": "^26.1.0",
+    "lint-staged": "^16.1.2",
+    "pdfjs-dist": "5.4.149",
+    "postcss": "^8.5.6",
+    "postcss-import": "^16.1.1",
+    "prettier": "3.6.2",
+    "sass": "^1.89.2",
+    "storybook": "^10.2.17",
+    "tailwindcss": "^3.4.17",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.48.0",
+    "vite": "^7.1.5",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^3.2.4"
+  }
+}