teamsync-pdf-viewer 1.5.1 → 1.6.1

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to `teamsync-pdf-viewer` are documented here.
 
+## [1.6.1] — 2026-09-15
+
+### Added
+- **`initialWidthRatio` Option**: Added `initialWidthRatio?: number` (with `widthRatio?: number` as an alias) to `<TeamSyncViewer>` and `WebViewerOptions`, allowing clients to target an exact fraction of the available viewing width on initial load (e.g. `0.7` for 70% width).
+- **Responsive PDF Container Resizing**: Added automatic `ResizeObserver` tracking on the document container to refit the open PDF responsively at 60fps via `requestAnimationFrame` when the viewer page, container, or sidebars resize while in a width-ratio, fit-width, or fit-page mode.
+- **`responsive` Prop**: Added `responsive?: boolean` (defaults to `true`) to `<TeamSyncViewer>` and `WebViewerOptions` for explicit control over auto-refitting on container resize.
+- **Public `calculateFitWidthScale` Utility**: Exported `calculateFitWidthScale(availableWidth, pageWidth, ratio?, minScale?, maxScale?)` from the public package root.
+- **Ratio Support in `fitWidth` & `fitToWidth`**: Updated `instance.UI.fitWidth(ratio?)`, `instance.UI.fitToWidth(ratio?)`, and added direct instance methods `instance.fitWidth(ratio?)`, `instance.fitToWidth(ratio?)`, `instance.fitPage()`, and `instance.fitToPage()`.
+
+## [1.6.0] — 2026-09-06
+
+### Added
+- **Whitespace-Tolerant Text Search**: Search queries now match across line breaks, multiple whitespace runs, tabs, NBSP (`\u00A0`), and other unicode whitespace variants seamlessly. Matches in normalized space while accurately reporting raw source coordinates and bounds.
+- **Shared `pageText` Builder & Bounding Box Interpolator**: Unified raw text extraction and character coordinate mapping between PDF search and regex redactions via internal `buildPageText` and `boundsForRawRange` helpers.
+- **Page-Scoped Search & Highlighting**:
+  - Added additive 5th parameter `pages?: number[]` to `searchPdfText(doc, query, redactions, onProgress, pages)`.
+  - Added `options.pages?: number[]` to `instance.searchText(query, options)`.
+  - Added `scope?: 'document' | 'page'` to `instance.highlightSnippet(query, options)` allowing strict page restriction when navigating to snippet citations.
+- **Sidebar Highlighting Precision**: Result `matchLength` now reflects the exact consumed raw glyph span, ensuring sidebar bold highlights match rendered page text identically.
+- **Stable Search Results Sorting**: Corrected search result sorting to maintain page index ascending order while preserving intra-page ascending match order.
+
 ## [1.5.1] — 2026-09-06
 
 ### Added

package/README.md

@@ -25,7 +25,7 @@ Try the **[Interactive Live Demo](https://pdfviewer.teamsync.com/)** or integrat
 Traditional commercial PDF viewers force developers into expensive per-domain licenses, opaque sales calls, and heavy server-side processing dependencies. **TeamSync PDF Viewer** is built from the ground up to solve these pain points.
 
 - 💰 **Zero-Cost, Transparent Licensing**: Uncapped usage, no per-server fees, and no commercial paywalls. 100% free and open-source under CPAL 1.0.
-- ⚡ **100% Client-Side WebAssembly**: Documents never leave the browser sandbox. Process, redact, and render PDFs entirely on the client. 
+- ⚡ **100% Client-Side PDF Processing**: Documents never leave the browser sandbox. Process, redact, and render PDFs entirely on the client. 
 - 🔌 **Universal WebViewer API**: Clean, intuitive `WebViewer({...})` API interface that makes integrating into your web applications effortless.
 - 🎨 **Headless & Customizable**: Built for modern React 19 SPA lifecycles. No bloated iFrames to fight—customize toolbars, sidebars, context menus, and controls natively.
 

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 } from '../core/types';
+import { Redaction, WatermarkOptions, SDKPermissions, PdfAssetPaths, TransientHighlight, InitialScale } from '../core/types';
 import * as pdfjsLib from 'pdfjs-dist';
 export interface DocumentLoadErrorInfo {
     url: string;
@@ -56,6 +56,9 @@ interface DocumentViewerProps {
     enableTextSelection?: boolean;
     defaultTool?: 'select' | 'pan';
     showSelectionTooltip?: boolean;
+    initialScale?: InitialScale;
+    initialWidthRatio?: number;
+    responsive?: boolean;
 }
-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 }: 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, }: DocumentViewerProps): React.JSX.Element;
 export {};

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

@@ -68,10 +68,29 @@ export declare class WebViewerInstance {
     }): void;
     /** Set the current page number (1-based). Alias of goToPage. */
     setCurrentPage(pageNumber: number): void;
+    /**
+     * Scale the document to fit the container width.
+     *
+     * @param ratio - Optional width ratio fraction (e.g. `0.7` for 70% of available width).
+     *   Defaults to `1.0` (100% full-width fit).
+     */
+    fitWidth(ratio?: number): void;
+    /** Alias of `fitWidth`. */
+    fitToWidth(ratio?: number): void;
+    /** Scale the document to fit the entire page within the container viewport. */
+    fitPage(): void;
+    /** Alias of `fitPage`. */
+    fitToPage(): void;
     /**
      * Search the document for text matches, returning snippets and page bounding boxes.
+     *
+     * @param query - Search term.
+     * @param options - Search options:
+     *   - `pages`: Specific 1-based page numbers to search. Defaults to all pages.
      */
-    searchText(query: string): Promise<SearchResult[]>;
+    searchText(query: string, options?: {
+        pages?: number[];
+    }): Promise<SearchResult[]>;
     /** Get the current list of transient highlights. */
     getTransientHighlights(): TransientHighlight[];
     /**
@@ -87,9 +106,21 @@ export declare class WebViewerInstance {
     /**
      * Search for a snippet or citation query, scroll to its page, and highlight it temporarily.
      * Returns the matched SearchResult or null if not found.
+     *
+     * @param query - The text snippet to locate and highlight.
+     * @param options - Navigation and display options:
+     *   - `pageIndex`: Preferred page (1-based). When `scope: 'page'`, restricts search to this page.
+     *   - `scope`: Search scope. `'document'` (default) searches all pages, keeping `pageIndex` as a preference.
+     *     `'page'` restricts the search strictly to `pageIndex` (avoids full-document walk).
+     *     If `scope: 'page'` is provided without `pageIndex`, it gracefully degrades to `'document'`.
+     *   - `pulse`: Animate focus ring (default true).
+     *   - `scrollTo`: Scroll page into view (default true).
+     *   - `color`: Background highlight color.
+     *   - `tooltip`: Tooltip text above the highlight (defaults to matched snippet).
      */
     highlightSnippet(query: string, options?: {
         pageIndex?: number;
+        scope?: 'document' | 'page';
         pulse?: boolean;
         scrollTo?: boolean;
         color?: string;
@@ -127,9 +158,9 @@ export declare class WebViewerInstance {
         setToolMode: (tool: string | null) => void;
         getSelectedText: () => string;
         copySelectedText: () => Promise<boolean>;
-        fitWidth: () => void;
+        fitWidth: (ratio?: number) => void;
         fitPage: () => void;
-        fitToWidth: () => void;
+        fitToWidth: (ratio?: number) => void;
         fitToPage: () => void;
         startCompare: (docA: any, docB: any, options?: any) => void;
         stopCompare: () => void;

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

@@ -53,7 +53,10 @@ export interface ViewerUser {
     id: string;
     name: string;
 }
-export type InitialScale = number | 'fit-width' | 'fit-page';
+export type InitialScale = number | 'fit-width' | 'fit-page' | {
+    type: 'fit-width';
+    ratio?: number;
+};
 export type ToolMode = 'select' | 'pan' | 'rectangle' | 'ellipse' | 'line' | 'arrow' | 'freehand' | 'highlight' | 'underline' | 'strikeout' | 'squiggly' | 'text' | 'eraser' | 'note' | 'callout' | 'signature' | 'digital_signature' | 'link' | 'redaction' | null;
 /**
  * Options accepted by `createWebViewer()` (and the deprecated `WebViewer()` alias).
@@ -67,6 +70,18 @@ export interface WebViewerOptions {
     /** Display name used for downloads. */
     fileName?: string;
     initialScale?: InitialScale;
+    /**
+     * Initial page width target as a ratio of the available viewing container width (e.g. `0.7` for 70%).
+     * When provided, the viewer scales the document to occupy this fraction of available width on initial render.
+     */
+    initialWidthRatio?: number;
+    /** Alias of `initialWidthRatio`. */
+    widthRatio?: number;
+    /**
+     * Automatically re-calculate scale when the viewer container or window resizes while in a fit or width-ratio mode.
+     * Default: true.
+     */
+    responsive?: boolean;
     /** 1-based page to scroll to after load. */
     initialPage?: number;
     /** Current 1-based page to display. Changes navigate to the given page. */

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

@@ -10,10 +10,10 @@ export interface SearchResult {
     bounds: SearchBounds[];
 }
 /**
- * Standalone asynchronous text search across all pages of a PDFDocumentProxy.
+ * Standalone asynchronous text search across all pages (or specified pages) of a PDFDocumentProxy.
  * Sanitizes redacted regions and returns matching snippets and bounding boxes.
  */
-export declare function searchPdfText(pdfDoc: pdfjsLib.PDFDocumentProxy, query: string, redactions?: Redaction[], onProgress?: (progress: number) => void): Promise<SearchResult[]>;
+export declare function searchPdfText(pdfDoc: pdfjsLib.PDFDocumentProxy, query: string, redactions?: Redaction[], onProgress?: (progress: number) => void, pages?: number[]): Promise<SearchResult[]>;
 export declare function usePdfSearch(pdfDoc: pdfjsLib.PDFDocumentProxy | null, redactions?: Redaction[]): {
     search: (query: string) => Promise<void>;
     searchResults: SearchResult[];

package/dist/src/index.d.ts

@@ -33,7 +33,7 @@ export type { PrintOptions } from './core/print';
 export { usePdfSearch, searchPdfText } from './hooks/usePdfSearch';
 export type { SearchResult, SearchBounds } from './hooks/usePdfSearch';
 export type { TransientHighlight } from './core/types';
-export { MIN_SCALE, MAX_SCALE, clampScale, calculateNextZoomIn, calculateNextZoomOut, calculateScrollCompensation } from './utils/zoomUtils';
+export { MIN_SCALE, MAX_SCALE, clampScale, calculateNextZoomIn, calculateNextZoomOut, calculateFitWidthScale, calculateScrollCompensation } from './utils/zoomUtils';
 export type { ScrollCompensationParams, ScrollPosition } from './utils/zoomUtils';
 export { estimatePageDimensions, computeRowLayout, DEFAULT_FALLBACK_DIMS, hasDimensionMismatch } from './utils/layoutUtils';
 export type { PageDimension, RowLayout } from './utils/layoutUtils';

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

@@ -0,0 +1,23 @@
+import { SearchBounds } from '../core/types';
+export interface PageText {
+    fullText: string;
+    itemIndices: number[];
+    charIndices: number[];
+    normText: string;
+    normToRaw: number[];
+}
+/**
+ * Collapses any consecutive whitespace runs to a single space and trims edges.
+ */
+export declare function collapseWhitespace(s: string): string;
+/**
+ * Builds raw page text with item/char index source-mapping, followed by a second pass
+ * creating normalized text (collapsing any maximal whitespace run to a single space)
+ * and a 1-to-1 index map back to raw string indices.
+ */
+export declare function buildPageText(items: any[]): PageText;
+/**
+ * Computes bounding boxes in PDF coordinate points for a matched range [rawStart, rawEndExcl) in fullText.
+ * Separator sentinels (-1) are skipped, and character positions are interpolated across each TextItem.
+ */
+export declare function boundsForRawRange(items: any[], pageText: Pick<PageText, 'itemIndices' | 'charIndices'>, rawStart: number, rawEndExcl: number): SearchBounds[];

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

@@ -27,6 +27,11 @@ export declare function calculateNextZoomOut(currentScale: number, minScale?: nu
  * Clamps and rounds a requested zoom level within [minScale, maxScale].
  */
 export declare function clampScale(scale: number, minScale?: number, maxScale?: number): number;
+/**
+ * Calculates the target scale to fit a given page width to an available container width,
+ * optionally scaled by a width ratio (e.g. 0.7 for 70% of available width).
+ */
+export declare function calculateFitWidthScale(availableWidth: number, pageWidth: number, ratio?: number, minScale?: number, maxScale?: number): number;
 /**
  * Calculates the safe rasterization scale for PDF.js viewport rendering so that
  * canvas dimensions and texture memory stay strictly within hardware limits.