teamsync-pdf-viewer 1.7.1 → 1.8.0

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to `teamsync-pdf-viewer` are documented here.
 
+## [1.8.0] — 2026-09-17
+
+### Added
+- **Native Microsoft Office Document Viewing**:
+  - View Microsoft Word (`.docx`, `.doc`), Excel (`.xlsx`, `.xls`), and PowerPoint (`.pptx`, `.ppt`) documents natively inside `<TeamSyncViewer>`.
+  - Transparent document type detection via magic byte signatures and file extension inspection (`officeDetector.ts`).
+  - Animated conversion loading overlay (`OfficeLoadingOverlay.tsx`) with real-time status indication.
+  - Local drag-and-drop and toolbar file picker conversion fallback.
+- **Enterprise Hybrid Office Architecture**:
+  - **Edge CDN Pre-Conversion & Caching**: Fast 200–400ms cached vector PDF delivery via `/api/convert?file=...` with zero server CPU load on repeat views.
+  - **Client-Side On-The-Fly Fallback**: Multipart form upload proxy for local user file drops and selection via `POST /api/convert`.
+  - **Zero Leaked Secrets**: Gotenberg credentials injected server-side; client bundles never expose backend credentials.
+- **Host SDK Office Module**:
+  - Exported `useOfficeDocument` React hook for host applications to manage loading, pre-conversion, and error states before mounting the viewer.
+  - Exported `preloadOfficeDocument(fileOrUrl, config, fileName)` async helper for routers, loaders, and prefetching.
+  - Exported `officeConverter` client service supporting remote URL conversion (`convertOfficeUrl`) and multipart file uploads (`convertOfficeFile`).
+  - Added dedicated `./office` subpath export in `package.json` alongside root exports.
+  - Exported office detection utilities: `isOfficeDocumentUrl`, `isOfficeFile`, `detectOfficeType`, `isOfficeExtension`, `SUPPORTED_OFFICE_EXTENSIONS`.
+  - Exported TypeScript types: `OfficeConversionConfig`, `OfficeConversionState`, `OfficeFileType`, `OfficeDocumentOptions`, `UseOfficeDocumentResult`.
+- **Top-Level SDK Version Export & About Modal Synchronization**:
+  - Exported `VERSION` constant from `teamsync-pdf-viewer` public API.
+  - Automated build-time version synchronization script (`scripts/sync-version.mjs`) ensuring parity across package and git tags.
+  - Dynamic About modal reflecting the active release tag with a direct link to GitHub release notes.
+  - Edge release endpoint (`/api/version`) caching GitHub release metadata at the CDN edge.
+
 ## [1.7.1] — 2026-09-15
 
 ### Fixed

package/README.md

@@ -71,6 +71,7 @@ Explore detailed SDK guides, parameter options, code snippets, and architecture
 - 🎨 **[Annotations & Markup Guide](docs/wiki/Annotations-&-Markup-Guide.md)**: Freehand drawing, vector shapes, callouts & links.
 - 🛡️ **[Redactions & PII Sanitization Guide](docs/wiki/Redactions-&-PII-Sanitization.md)**: Binary redactions, regex PII scanning & discard options.
 - 💧 **[Forensic Watermarking Guide](docs/wiki/Forensic-Watermarking.md)**: Dynamic single and tiled watermark setup.
+- 📄 **[Viewing Office Documents Guide](docs/wiki/Viewing-Office-Documents.md)**: Word (.docx), PowerPoint (.pptx), Excel (.xlsx) high-fidelity viewing & conversion.
 - 🔌 **[Plugin Architecture Guide](docs/wiki/Plugin-Architecture.md)**: Writing custom extension plugins.
 
 ---

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

@@ -3,6 +3,7 @@ import { DocumentLoadErrorInfo } from './DocumentViewer';
 import { WebViewerInstance } from '../core/ViewerInstance';
 import { WebViewerOptions, Redaction, TransientHighlight, LinkClickEvent } from '../core/types';
 import { Annotation } from '../annotations/types';
+import { OfficeConverterConfig, OfficeFileType } from '../office';
 export interface TeamSyncViewerProps extends Omit<WebViewerOptions, 'path'> {
     /** URL of the PDF to display. Alias of `initialDoc`; `fileUrl` wins when both are set. */
     fileUrl?: string;
@@ -74,6 +75,28 @@ export interface TeamSyncViewerProps extends Omit<WebViewerOptions, 'path'> {
      * Call `event.preventDefault()` to suppress default behavior.
      */
     onLinkClick?: (event: LinkClickEvent) => boolean | void | Promise<void>;
+    /**
+     * Configuration for viewing Microsoft Office documents (.docx, .doc, .pptx, .ppt, .xlsx, .xls).
+     */
+    officeConverter?: OfficeConverterConfig;
+    /** Fires when an Office document starts converting to PDF. */
+    onOfficeConverting?: (info: {
+        fileType: OfficeFileType;
+        url?: string;
+        fileName?: string;
+    }) => void;
+    /** Fires when an Office document has successfully converted to PDF. */
+    onOfficeConverted?: (info: {
+        fileType: OfficeFileType;
+        url?: string;
+        fromCache: boolean;
+    }) => void;
+    /** Fires when an Office document conversion encounters an error. */
+    onOfficeConversionError?: (info: {
+        fileType: OfficeFileType;
+        error: Error;
+        url?: string;
+    }) => void;
     className?: string;
     style?: React.CSSProperties;
 }

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

@@ -4,7 +4,8 @@ import { Annotation } from '../annotations/types';
 import { AnnotationChangedEvent } from '../annotations/AnnotationManager';
 import { PdfAssetPaths } from './pdfAssets';
 import { WebViewerInstance } from './ViewerInstance';
-export type { PdfAssetPaths, WebViewerInstance };
+import { OfficeConverterConfig, OfficeFileType } from '../office/types';
+export type { PdfAssetPaths, WebViewerInstance, OfficeConverterConfig, OfficeFileType };
 export interface SearchBounds {
     x: number;
     y: number;
@@ -134,7 +135,14 @@ 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. */
+    /**
+     * Configuration for viewing Microsoft Office documents (.docx, .doc, .pptx, .ppt, .xlsx, .xls).
+     * Supports headless backend conversion (Gotenberg / LibreOffice daemon) or custom conversion hooks.
+     */
+    officeConverter?: OfficeConverterConfig;
+    /**
+     * 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.
@@ -228,6 +236,24 @@ export interface ViewerEventMap {
         text: string;
     };
     linkClicked: LinkClickEvent;
+    /** Fires when an Office document begins conversion. */
+    officeConverting: {
+        fileType: OfficeFileType;
+        url?: string;
+        fileName?: string;
+    };
+    /** Fires when an Office document finishes conversion successfully. */
+    officeConverted: {
+        fileType: OfficeFileType;
+        url?: string;
+        fromCache: boolean;
+    };
+    /** Fires when an Office document conversion fails. */
+    officeConversionError: {
+        fileType: OfficeFileType;
+        error: Error;
+        url?: string;
+    };
     destroy: Record<string, never>;
 }
 export type ViewerEventType = keyof ViewerEventMap;

package/dist/src/index.d.ts

@@ -40,3 +40,11 @@ export type { ScrollCompensationParams, ScrollPosition } from './utils/zoomUtils
 export { estimatePageDimensions, computeRowLayout, DEFAULT_FALLBACK_DIMS, hasDimensionMismatch } from './utils/layoutUtils';
 export type { PageDimension, RowLayout } from './utils/layoutUtils';
 export * from './plugins/types';
+export * from './office';
+export { officeConverter, convertOfficeDocument, convertOfficeFile, convertOfficeUrl, } from './office/officeConverter';
+export { useOfficeDocument, preloadOfficeDocument, } from './office/useOfficeDocument';
+export type { UseOfficeDocumentOptions, UseOfficeDocumentResult, } from './office/useOfficeDocument';
+export { isOfficeDocumentUrl, isOfficeFile, detectOfficeType, isOfficeExtension, SUPPORTED_OFFICE_EXTENSIONS, } from './office/officeDetector';
+export { OfficeLoadingOverlay } from './office/OfficeLoadingOverlay';
+export type { OfficeConverterConfig, OfficeConversionConfig, OfficeConversionState, OfficeFileType, OfficeDocumentOptions, OfficeDocumentInfo, } from './office/types';
+export { VERSION } from './version';

package/dist/src/office/OfficeLoadingOverlay.d.ts

@@ -0,0 +1,9 @@
+import { default as React } from 'react';
+import { OfficeFileType } from './types';
+export interface OfficeLoadingOverlayProps {
+    fileType: OfficeFileType;
+    fileName?: string;
+    error?: Error | null;
+    onRetry?: () => void;
+}
+export declare const OfficeLoadingOverlay: React.FC<OfficeLoadingOverlayProps>;

package/dist/src/office/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './officeDetector';
+export * from './officeConverter';
+export * from './OfficeLoadingOverlay';
+export * from './useOfficeDocument';

package/dist/src/office/officeConverter.d.ts

@@ -0,0 +1,46 @@
+import { OfficeConverterConfig, OfficeFileType } from './types';
+/**
+ * Retrieves a cached converted PDF from memory or sessionStorage.
+ */
+export declare function getCachedOfficePdf(fileOrUrl: string | File | Blob | ArrayBuffer, fileType: OfficeFileType, cacheMode?: OfficeConverterConfig['cache']): Promise<ArrayBuffer | null>;
+/**
+ * Stores a converted PDF in memory and optionally sessionStorage.
+ */
+export declare function setCachedOfficePdf(fileOrUrl: string | File | Blob | ArrayBuffer, fileType: OfficeFileType, pdfBuffer: ArrayBuffer, cacheMode?: OfficeConverterConfig['cache']): Promise<void>;
+/**
+ * Clears the converted document cache.
+ */
+export declare function clearOfficeCache(): void;
+export interface ConvertOfficeDocumentResult {
+    /** Raw PDF ArrayBuffer ready for PDF.js or downstream processing */
+    pdfBuffer: ArrayBuffer;
+    /** Browser Blob Object URL (e.g. blob:http...) ready for rendering or iframe preview */
+    objectUrl: string;
+    /** Whether the document was served from cache */
+    fromCache: boolean;
+}
+/**
+ * Converts an Office document (Word, PowerPoint, Excel) into a standardized PDF ArrayBuffer
+ * and Blob URL using either a custom converter or the configured backend microservice.
+ */
+export declare function convertOfficeDocument(fileOrUrl: string | File | Blob | ArrayBuffer, config: OfficeConverterConfig, fileName?: string): Promise<ConvertOfficeDocumentResult>;
+/**
+ * Convenience helper to convert a remote Office document URL.
+ */
+export declare function convertOfficeUrl(url: string, config: OfficeConverterConfig, fileName?: string): Promise<ConvertOfficeDocumentResult>;
+/**
+ * Convenience helper to convert a local Office File or Blob.
+ */
+export declare function convertOfficeFile(file: File | Blob, config: OfficeConverterConfig, fileName?: string): Promise<ConvertOfficeDocumentResult>;
+/**
+ * Unified Office converter service object.
+ */
+export declare const officeConverter: {
+    convert: typeof convertOfficeDocument;
+    convertDocument: typeof convertOfficeDocument;
+    convertUrl: typeof convertOfficeUrl;
+    convertFile: typeof convertOfficeFile;
+    getCached: typeof getCachedOfficePdf;
+    setCached: typeof setCachedOfficePdf;
+    clearCache: typeof clearOfficeCache;
+};

package/dist/src/office/officeDetector.d.ts

@@ -0,0 +1,30 @@
+import { OfficeFileType, OfficeDocumentCategory, OfficeBadgeMeta, OfficeDocumentInfo } from './types';
+/**
+ * Detects whether a string URL, File, or Blob represents a supported Microsoft Office document.
+ */
+export declare function getOfficeFileType(target: unknown): OfficeFileType | null;
+/**
+ * Returns true if the given input is a supported Microsoft Office document.
+ */
+export declare function isOfficeDocument(target: unknown): boolean;
+/**
+ * Returns the broad document category ('word' | 'powerpoint' | 'excel') for an Office file type.
+ */
+export declare function getOfficeDocumentCategory(fileType: OfficeFileType): OfficeDocumentCategory;
+/**
+ * Returns standard MIME type for an Office file type.
+ */
+export declare function getOfficeMimeType(fileType: OfficeFileType): string;
+/**
+ * Metadata used to display themed UI badges, spinners, and icons for Office document types.
+ */
+export declare function getOfficeBadgeMeta(fileType: OfficeFileType): OfficeBadgeMeta;
+/**
+ * Inspects a target and returns rich Office metadata if it is an Office document.
+ */
+export declare function getOfficeDocumentInfo(target: unknown): OfficeDocumentInfo | null;
+export declare const isOfficeDocumentUrl: typeof isOfficeDocument;
+export declare const isOfficeFile: typeof isOfficeDocument;
+export declare const detectOfficeType: typeof getOfficeFileType;
+export declare function isOfficeExtension(ext: string): boolean;
+export declare const SUPPORTED_OFFICE_EXTENSIONS: readonly ["docx", "doc", "pptx", "ppt", "xlsx", "xls"];

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

@@ -0,0 +1,67 @@
+export type OfficeFileType = 'docx' | 'doc' | 'pptx' | 'ppt' | 'xlsx' | 'xls';
+export type OfficeDocumentCategory = 'word' | 'powerpoint' | 'excel';
+export interface OfficeBadgeMeta {
+    category: OfficeDocumentCategory;
+    name: string;
+    extension: string;
+    brandColor: string;
+    darkBrandColor: string;
+    iconName: string;
+}
+export type OfficeConversionState = 'idle' | 'converting' | 'converted' | 'error';
+export interface OfficeConverterConfig {
+    /**
+     * Backend conversion endpoint URL (e.g. Gotenberg, custom API proxy, or serverless function).
+     * Example: 'http://localhost:3000/api/convert-office' or 'http://localhost:3001/forms/libreoffice/convert'
+     */
+    endpoint?: string;
+    /**
+     * Custom HTTP headers to include with the conversion request.
+     */
+    headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+    /**
+     * Authorization token (Bearer token, API key, or JWT) sent with conversion requests.
+     * Can be a static string or a function/promise returning the current token.
+     * Automatically injected as 'Authorization: Bearer <token>' header.
+     */
+    authToken?: string | (() => string | Promise<string>);
+    /**
+     * Caching strategy:
+     * - 'memory': Cache converted PDF ArrayBuffers in browser memory for the current session (default).
+     * - 'session': Cache in sessionStorage.
+     * - 'none': Do not cache.
+     */
+    cache?: 'memory' | 'session' | 'none' | boolean;
+    /**
+     * Custom conversion hook allowing host application to supply its own conversion logic.
+     * If provided, this hook is called instead of the built-in Gotenberg/HTTP dispatcher.
+     */
+    convert?: (fileOrUrl: string | File | Blob | ArrayBuffer, fileType: OfficeFileType, options?: {
+        fileName?: string;
+        excelOptions?: OfficeConverterConfig['excelOptions'];
+    }) => Promise<ArrayBuffer | Uint8Array | Blob | string>;
+    /**
+     * Options for Excel worksheet conversion.
+     */
+    excelOptions?: {
+        fitToPageWidth?: boolean;
+        includeGridlines?: boolean;
+        paperSize?: 'A4' | 'Letter' | 'Legal';
+        orientation?: 'landscape' | 'portrait';
+    };
+}
+export interface OfficeDocumentInfo {
+    fileType: OfficeFileType;
+    category: OfficeDocumentCategory;
+    fileName?: string;
+    originalUrl?: string;
+    mimeType: string;
+}
+/**
+ * Alias for OfficeConverterConfig for ergonomic naming.
+ */
+export type OfficeConversionConfig = OfficeConverterConfig;
+/**
+ * Alias for OfficeDocumentInfo / options.
+ */
+export type OfficeDocumentOptions = OfficeDocumentInfo;

package/dist/src/office/useOfficeDocument.d.ts

@@ -0,0 +1,44 @@
+import { OfficeConverterConfig, OfficeFileType, OfficeDocumentInfo } from './types';
+export interface UseOfficeDocumentOptions {
+    /** Converter configuration (endpoint, authToken, cache mode, etc.) */
+    converterConfig?: OfficeConverterConfig;
+    /** Optional file name override */
+    fileName?: string;
+    /** Whether to automatically convert when the document changes (defaults to true) */
+    autoConvert?: boolean;
+}
+export interface UseOfficeDocumentResult {
+    /** Whether the input source was identified as a Microsoft Office document */
+    isOffice: boolean;
+    /** Detected office file type ('docx', 'pptx', 'xlsx', etc.) or null if PDF */
+    fileType: OfficeFileType | null;
+    /** Detailed metadata about the office document */
+    documentInfo: OfficeDocumentInfo | null;
+    /** Whether conversion is actively in progress */
+    isConverting: boolean;
+    /** The final PDF URL ready for the viewer (<TeamSyncViewer fileUrl={pdfUrl} />) */
+    pdfUrl: string | null;
+    /** Raw PDF ArrayBuffer */
+    pdfBuffer: ArrayBuffer | null;
+    /** Whether the document was served from memory/session cache */
+    fromCache: boolean;
+    /** Any error encountered during conversion */
+    error: Error | null;
+    /** Manually trigger conversion or retry */
+    convert: () => Promise<string | null>;
+}
+/**
+ * React hook that pre-converts Office documents into viewable PDF URLs before viewer mounting.
+ * If the input is already a PDF, it passes through immediately with `isConverting: false`.
+ */
+export declare function useOfficeDocument(fileOrUrl: string | File | Blob | ArrayBuffer | null | undefined, options?: UseOfficeDocumentOptions): UseOfficeDocumentResult;
+/**
+ * Standalone asynchronous preloader for Office documents.
+ * Can be called anywhere (e.g. in loaders, event handlers, or background tasks).
+ */
+export declare function preloadOfficeDocument(fileOrUrl: string | File | Blob | ArrayBuffer, config: OfficeConverterConfig, fileName?: string): Promise<{
+    pdfUrl: string;
+    pdfBuffer: ArrayBuffer;
+    fromCache: boolean;
+    fileType: OfficeFileType | 'pdf';
+}>;

package/dist/src/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION: string;