teamsync-pdf-viewer 1.6.1 → 1.7.1

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to `teamsync-pdf-viewer` are documented here.
 
+## [1.7.1] — 2026-09-15
+
+### Fixed
+- **Default Responsive Fit-Width**: Resolved an issue where omitting `initialScale` prevented `ResizeObserver` from auto-refitting the document when the browser window or viewer container resized. Now defaults to `'fit-width'` and `{ type: 'fit-width', ratio: 1.0 }` when no explicit numeric zoom is provided.
+- **Dynamic Horizontal Page Centering**: Added live `containerDimensions` state tracking so that pages automatically re-center horizontally in real-time during window resize and sidebar toggles, eliminating stale pixel offsets and right-edge clipping.
+- **Programmatic Zoom Tracking**: Fixed dangling programmatic scale flag when `newScale === scale` during minor resize steps so manual zoom interactions properly clear auto-fit mode.
+- **Window Resize Event Listener**: Added window `resize` event listener alongside `ResizeObserver` for comprehensive container refitting across all viewport changes.
+
+## [1.7.0] — 2026-09-15
+
+### Added
+- **Cross-Instance Document Linking**: Links referring to other documents or specific pages can now automatically load and navigate the destination document in a designated target `TeamSyncViewer` instance.
+- **`targetViewer` Prop & Option**: Added `targetViewer` to `<TeamSyncViewer>` and `WebViewerOptions`, accepting another `WebViewerInstance`, a React ref (`useRef<WebViewerInstance>`), a getter function `() => WebViewerInstance | null`, or an instance ID string.
+- **Static Viewer Instance Registry**: Added `WebViewerInstance.getInstance(id)`, `WebViewerInstance.registerInstance(id, inst)`, `WebViewerInstance.unregisterInstance(id)`, and automatic unregistration when the viewer is unmounted/destroyed.
+- **`loadOrNavigate` & `openLink` APIs**: Added `instance.loadOrNavigate(documentUrl, page?)` (smoothly navigates to the page if the document is already loaded, or reloads at that page if not) and `instance.openLink(url, options?)`.
+- **Dual Link Support (TeamSync Annotations & Embedded PDF Links)**:
+  - Native embedded PDF `/Link` annotations are now extracted from PDF.js (`page.getAnnotations({ intent: 'display' })`) and rendered with interactive SVG hitboxes and tooltip preview.
+  - Link annotations and sidebar comment links seamlessly route through the link handler.
+- **"Other Doc" Tab in Insert Link Modal**: Added a dedicated 3rd tab to `InsertLinkModal` for configuring cross-document links with document URL and target page number.
+- **`linkClicked` Event & Custom Handlers**: Added `linkClicked` event to `ViewerEventMap` with a cancellable `LinkClickEvent` supporting `event.preventDefault()`, plus `onLinkClick` and `resolveLinkUrl` props for URL mapping and event interception.
+- **Public Utilities Export**: Exported `parseLinkTarget`, `isDocumentUrl`, `ParsedLinkTarget`, and `LinkClickEvent` from the library root.
+
 ## [1.6.1] — 2026-09-15
 
 ### Added

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

@@ -1,7 +1,7 @@
 import { default as React } from 'react';
 import { Annotation } from '../annotations/types';
 import { AnnotationManager } from '../annotations/AnnotationManager';
-import { Redaction, WatermarkOptions, SDKPermissions, PdfAssetPaths, TransientHighlight, InitialScale } from '../core/types';
+import { Redaction, WatermarkOptions, SDKPermissions, PdfAssetPaths, TransientHighlight, InitialScale, LinkClickEvent, WebViewerInstance } from '../core/types';
 import * as pdfjsLib from 'pdfjs-dist';
 export interface DocumentLoadErrorInfo {
     url: string;
@@ -59,6 +59,19 @@ interface DocumentViewerProps {
     initialScale?: InitialScale;
     initialWidthRatio?: number;
     responsive?: boolean;
+    instance?: WebViewerInstance;
+    targetViewer?: WebViewerInstance | React.RefObject<WebViewerInstance | null> | (() => WebViewerInstance | null) | string;
+    resolveLinkUrl?: (linkUrl: string, context: {
+        sourceViewer: WebViewerInstance;
+        annotation?: Annotation;
+    }) => string | {
+        url: string;
+        page?: number;
+    } | Promise<string | {
+        url: string;
+        page?: number;
+    } | null> | null;
+    onLinkClick?: (event: LinkClickEvent) => boolean | void | Promise<void>;
 }
-export default function DocumentViewer({ leftSidebarOpen, rightSidebarOpen, activeTab, annotationManager, initialDoc, loadNonce, withCredentials, assets, sidebars, redactions, regexRedactions, scale, setScale, sidebarTab, setSidebarTab, onAnnotationsChange, onRedactionsChange, onRedactionsApplied, onDocumentLoaded, onLoadError, onFirstPageRendered, onPageRendered, onPageChange, pageTransition, pageLayout, rotation, setRotation, watermark, watermarkText, enableAnnotations: _enableAnnotations, initialPage, page, transientHighlights, permissions, hideAnnotationsUntilPageRendered, enableTextSelection, defaultTool, showSelectionTooltip, initialScale, initialWidthRatio, responsive, }: DocumentViewerProps): React.JSX.Element;
+export default function DocumentViewer({ leftSidebarOpen, rightSidebarOpen, activeTab, annotationManager, initialDoc, loadNonce, withCredentials, assets, sidebars, redactions, regexRedactions, scale, setScale, sidebarTab, setSidebarTab, onAnnotationsChange, onRedactionsChange, onRedactionsApplied, onDocumentLoaded, onLoadError, onFirstPageRendered, onPageRendered, onPageChange, pageTransition, pageLayout, rotation, setRotation, watermark, watermarkText, enableAnnotations: _enableAnnotations, initialPage, page, transientHighlights, permissions, hideAnnotationsUntilPageRendered, enableTextSelection, defaultTool, showSelectionTooltip, initialScale, initialWidthRatio, responsive, instance, targetViewer, resolveLinkUrl, onLinkClick, }: DocumentViewerProps): React.JSX.Element;
 export {};

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

@@ -40,7 +40,8 @@ interface PageRendererProps {
     onRendered?: (pageNum: number) => void;
     /** Whether to hide annotations and transient highlights until the page canvas has finished rendering. Default: true. */
     hideAnnotationsUntilPageRendered?: boolean;
+    onLinkClick?: (url: string, annotation?: Annotation, e?: React.MouseEvent) => void;
 }
-declare function PageRendererComponent({ pageNum, pdfDoc, scale, rotation, containerWidth: _containerWidth, containerHeight: _containerHeight, scrollTop: _scrollTop, scrollLeft: _scrollLeft, pageTop, pageLeft, basePageWidth, basePageHeight, activeTab, activeTool, annotations, selectedAnnotationId, activeSearchResult, transientHighlights, onMouseDown, onMouseMove, onMouseUp, onAnnotationClick, onAnnotationDoubleClick, onStartResize, onStartMove, onAnnotationMouseEnter, onClearSelection, watermark, watermarkText, redactions, onDiscardRedaction, onRendered, hideAnnotationsUntilPageRendered }: PageRendererProps): React.JSX.Element;
+declare function PageRendererComponent({ pageNum, pdfDoc, scale, rotation, containerWidth: _containerWidth, containerHeight: _containerHeight, scrollTop: _scrollTop, scrollLeft: _scrollLeft, pageTop, pageLeft, basePageWidth, basePageHeight, activeTab, activeTool, annotations, selectedAnnotationId, activeSearchResult, transientHighlights, onMouseDown, onMouseMove, onMouseUp, onAnnotationClick, onAnnotationDoubleClick, onStartResize, onStartMove, onAnnotationMouseEnter, onClearSelection, watermark, watermarkText, redactions, onDiscardRedaction, onRendered, hideAnnotationsUntilPageRendered, onLinkClick }: PageRendererProps): React.JSX.Element;
 declare const PageRenderer: React.MemoExoticComponent<typeof PageRendererComponent>;
 export default PageRenderer;

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

@@ -13,6 +13,7 @@ interface SidebarProps {
     onResultClick: (result: SearchResult) => void;
     activeTab: 'Comments' | 'Search';
     setActiveTab: (tab: 'Comments' | 'Search') => void;
+    onLinkClick?: (url: string, annotation?: any, e?: React.MouseEvent) => void;
 }
-export default function Sidebar({ isOpen, annotations, setAnnotations, selectedAnnotationId, setSelectedAnnotationId, onSearch, searchResults, isSearching, searchProgress, onResultClick, activeTab, setActiveTab }: SidebarProps): React.JSX.Element;
+export default function Sidebar({ isOpen, annotations, setAnnotations, selectedAnnotationId, setSelectedAnnotationId, onSearch, searchResults, isSearching, searchProgress, onResultClick, activeTab, setActiveTab, onLinkClick }: SidebarProps): React.JSX.Element;
 export {};

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

@@ -1,7 +1,7 @@
 import { default as React } from 'react';
 import { DocumentLoadErrorInfo } from './DocumentViewer';
 import { WebViewerInstance } from '../core/ViewerInstance';
-import { WebViewerOptions, Redaction, TransientHighlight } from '../core/types';
+import { WebViewerOptions, Redaction, TransientHighlight, LinkClickEvent } from '../core/types';
 import { Annotation } from '../annotations/types';
 export interface TeamSyncViewerProps extends Omit<WebViewerOptions, 'path'> {
     /** URL of the PDF to display. Alias of `initialDoc`; `fileUrl` wins when both are set. */
@@ -47,6 +47,33 @@ export interface TeamSyncViewerProps extends Omit<WebViewerOptions, 'path'> {
     onTextCopied?: (info: {
         text: string;
     }) => void;
+    /** Unique ID for this viewer instance, enabling other viewers to target it by name. */
+    id?: string;
+    /**
+     * Target viewer instance, ref, getter, or instance ID to open cross-document links in.
+     * When a link annotation pointing to another PDF is clicked, the document will automatically
+     * be loaded and navigated in this target viewer instance.
+     */
+    targetViewer?: WebViewerInstance | React.RefObject<WebViewerInstance | null> | (() => WebViewerInstance | null) | string;
+    /**
+     * Optional custom resolver for cross-document links.
+     * Allows transforming relative filenames, document IDs, or URNs into full fetchable document URLs or target pages.
+     */
+    resolveLinkUrl?: (linkUrl: string, context: {
+        sourceViewer: WebViewerInstance;
+        annotation?: Annotation;
+    }) => string | {
+        url: string;
+        page?: number;
+    } | Promise<string | {
+        url: string;
+        page?: number;
+    } | null> | null;
+    /**
+     * Fires when a link annotation or embedded PDF link is clicked.
+     * Call `event.preventDefault()` to suppress default behavior.
+     */
+    onLinkClick?: (event: LinkClickEvent) => boolean | void | Promise<void>;
     className?: string;
     style?: React.CSSProperties;
 }

package/dist/src/core/ViewerInstance.d.ts

@@ -1,14 +1,10 @@
+import { default as React } from 'react';
 import { ViewerBus } from './eventBus';
 import { ExportOptions } from './export';
 import { Annotation } from '../annotations/types';
 import { AnnotationManager } from '../annotations/AnnotationManager';
 import { Redaction, WatermarkOptions, ViewerEventMap, ViewerEventType, TransientHighlight } from './types';
 import { SearchResult } from '../hooks/usePdfSearch';
-/**
- * © 2026 AngelBot Ai Pvt Ltd. All rights reserved.
- * WebViewerInstance — the imperative handle returned by `createWebViewer()` and exposed through
- * `<TeamSyncViewer ref>`. Keeps the legacy `UI` / `Core` facade for drop-in compatibility.
- */
 import type * as pdfjsLib from 'pdfjs-dist';
 /** Callbacks the React component installs so the instance can reach live state. */
 export interface ViewerBinding {
@@ -29,15 +25,31 @@ export interface ViewerBinding {
     setTransientHighlights(highlights: TransientHighlight[]): void;
 }
 export declare class WebViewerInstance {
+    private static instances;
+    /** Retrieve a registered WebViewerInstance by its ID. */
+    static getInstance(id: string): WebViewerInstance | undefined;
+    /** Register a WebViewerInstance with an ID. */
+    static registerInstance(id: string, instance: WebViewerInstance): void;
+    /** Unregister an instance by its ID. */
+    static unregisterInstance(id: string): void;
+    /** Clear all registered instances (primarily for testing). */
+    static clearInstances(): void;
     readonly bus: ViewerBus;
     /** Annotation list, history, permissions and XFDF import/export. */
     readonly annotationManager: AnnotationManager;
     /** Root element of the viewer once mounted. */
     element: HTMLElement | null;
+    /** Unique identifier for this instance. */
+    id?: string;
     private binding;
     private unmountRoot;
     private destroyed;
-    constructor(bus: ViewerBus, annotationManager?: AnnotationManager);
+    private targetViewerTarget;
+    constructor(bus: ViewerBus, annotationManager?: AnnotationManager, id?: string);
+    /** Sets the target viewer instance, ref, getter, or ID to receive cross-document links. */
+    setTargetViewer(target: WebViewerInstance | React.RefObject<WebViewerInstance | null> | (() => WebViewerInstance | null) | string | null): void;
+    /** Resolves the target viewer instance if configured. */
+    getTargetViewer(): WebViewerInstance | null;
     /** @internal */
     _bind(binding: ViewerBinding, element: HTMLElement | null): void;
     /** @internal */
@@ -54,10 +66,29 @@ export declare class WebViewerInstance {
     on<K extends ViewerEventType>(type: K, listener: (detail: ViewerEventMap[K]) => void): () => void;
     off<K extends ViewerEventType>(type: K, listener: (detail: ViewerEventMap[K]) => void): void;
     /** Load (or reload) a document by URL. Resolves when loaded, rejects on load error. */
-    loadDocument(url: string): Promise<{
+    loadDocument(url: string, options?: {
+        page?: number;
+        initialPage?: number;
+    }): Promise<{
         url: string;
         numPages: number;
     }>;
+    /**
+     * Loads a document or navigates to a page within it. If the document is already loaded,
+     * directly navigates to the requested page without reloading.
+     */
+    loadOrNavigate(url: string, options?: {
+        page?: number;
+        initialPage?: number;
+    }): Promise<{
+        url: string;
+        numPages: number;
+    } | void>;
+    /**
+     * Programmatically trigger link following for a given link URL or target,
+     * routing through targetViewer or opening appropriately.
+     */
+    openLink(linkUrl: string): void;
     getDocumentUrl(): string | undefined;
     getPdfDocument(): pdfjsLib.PDFDocumentProxy | null;
     getCurrentPage(): number;

package/dist/src/core/types.d.ts

@@ -1,8 +1,10 @@
+import { default as React } from 'react';
 import { ViewerPlugin } from '../plugins/types';
 import { Annotation } from '../annotations/types';
 import { AnnotationChangedEvent } from '../annotations/AnnotationManager';
 import { PdfAssetPaths } from './pdfAssets';
-export type { PdfAssetPaths };
+import { WebViewerInstance } from './ViewerInstance';
+export type { PdfAssetPaths, WebViewerInstance };
 export interface SearchBounds {
     x: number;
     y: number;
@@ -132,6 +134,52 @@ export interface WebViewerOptions {
     onRedactionsChange?: (redactions: Redaction[]) => void;
     /** Fires once per user click of Apply in the confirmation modal with all applied redactions. */
     onRedactionsApplied?: (redactions: Redaction[]) => void;
+    /** Unique identifier for this viewer instance, allowing other viewers to target it by name. */
+    id?: string;
+    /**
+     * Target viewer instance, ref, getter, or instance ID to open cross-document links in.
+     * When a link annotation pointing to another PDF is clicked, the document will automatically
+     * be loaded and navigated in this target viewer instance.
+     */
+    targetViewer?: WebViewerInstance | React.RefObject<WebViewerInstance | null> | (() => WebViewerInstance | null) | string;
+    /**
+     * Optional custom resolver for cross-document links.
+     * Allows transforming relative filenames, document IDs, or URNs into full fetchable document URLs or target pages.
+     */
+    resolveLinkUrl?: (linkUrl: string, context: {
+        sourceViewer: WebViewerInstance;
+        annotation?: Annotation;
+    }) => string | {
+        url: string;
+        page?: number;
+    } | Promise<string | {
+        url: string;
+        page?: number;
+    } | null> | null;
+    /**
+     * Fires when a link annotation or embedded PDF link is clicked.
+     * Call `event.preventDefault()` to suppress default behavior.
+     */
+    onLinkClick?: (event: LinkClickEvent) => boolean | void | Promise<void>;
+}
+/** Details provided when a link annotation or embedded PDF link is clicked. */
+export interface LinkClickEvent {
+    /** The raw link URL or target string. */
+    url: string;
+    /** Target document URL if the link points to a document (clean without page hash). */
+    docUrl?: string;
+    /** Target page number (1-based), if specified in the link. */
+    pageNumber?: number;
+    /** True if the link points to an internal page in the current document. */
+    isInternalPage: boolean;
+    /** The annotation object if clicked from a link annotation. */
+    annotation?: Annotation;
+    /** Original mouse event if triggered by user interaction. */
+    originalEvent?: React.MouseEvent;
+    /** Calling this prevents default behavior (e.g. scrolling current document, auto-forwarding to targetViewer, or opening window.open). */
+    preventDefault: () => void;
+    /** Whether preventDefault() was called. */
+    readonly defaultPrevented: boolean;
 }
 /** Events available through `instance.on(type, listener)`. */
 export interface ViewerEventMap {
@@ -179,6 +227,7 @@ export interface ViewerEventMap {
     textCopied: {
         text: string;
     };
+    linkClicked: LinkClickEvent;
     destroy: Record<string, never>;
 }
 export type ViewerEventType = keyof ViewerEventMap;

package/dist/src/index.d.ts

@@ -17,7 +17,9 @@ export { ViewerBus } from './core/eventBus';
 export type { BusListener } from './core/eventBus';
 export { buildPdfBytes, MAX_EXPORT_BYTES } from './core/export';
 export type { ExportInput, ExportOptions } from './core/export';
-export type { WebViewerOptions, Redaction, WatermarkOptions, SDKPermissions, ViewerUser, InitialScale, ViewerEventMap, ViewerEventType, ToolMode, } from './core/types';
+export type { WebViewerOptions, Redaction, WatermarkOptions, SDKPermissions, ViewerUser, InitialScale, ViewerEventMap, ViewerEventType, ToolMode, LinkClickEvent, } from './core/types';
+export { parseLinkTarget, isDocumentUrl } from './utils/linkUtils';
+export type { ParsedLinkTarget } from './utils/linkUtils';
 export { copyTextToClipboard } from './utils/clipboardUtils';
 export { TextSelectionTooltip } from './components/TextSelectionTooltip';
 export type { Annotation, AnnotationType, AnnotationPoint, AnnotationInput } from './annotations/types';

package/dist/src/utils/linkUtils.d.ts

@@ -0,0 +1,23 @@
+/**
+ * © 2026 AngelBot Ai Pvt Ltd. All rights reserved.
+ */
+export interface ParsedLinkTarget {
+    /** Raw input URL or link target string. */
+    rawUrl: string;
+    /** True if the link refers only to an internal page jump within the current document (e.g. '#page=5' or '#5'). */
+    isInternalPage: boolean;
+    /** Clean document URL without page hash if referencing another document (e.g. 'supporting.pdf' or 'https://.../doc.pdf'). */
+    docUrl?: string;
+    /** Target page number (1-based) if specified (e.g. 5 from '#page=5' or 'doc.pdf#page=5'). */
+    pageNumber?: number;
+    /** True if this is an external web URL (e.g. 'https://google.com') that is not a PDF/document. */
+    isExternalWeb: boolean;
+}
+/**
+ * Checks whether a given URL or filename refers to a PDF / document rather than a general web page.
+ */
+export declare function isDocumentUrl(url: string): boolean;
+/**
+ * Parses any link URL into structured destination information, extracting target documents and page numbers.
+ */
+export declare function parseLinkTarget(linkUrl: string): ParsedLinkTarget;