@matangot/react-pdf-viewer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matan Got
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,152 @@
+# @matangot/react-pdf-viewer
+
+A fast, customizable React PDF viewer component powered by pdf.js. Works with Next.js, Vite, CRA, and any React environment.
+
+## Features
+
+- Navigation (prev/next, page jump, keyboard shortcuts)
+- Zoom (in/out, fit-width, fit-page)
+- Search with match highlighting
+- Download with custom filename
+- Print
+- Full screen
+- Rotation
+- Thumbnail sidebar
+- Light/dark/system theme
+- Compound components for full layout control
+- CSS custom properties for easy theming
+
+## Installation
+
+```bash
+npm install @matangot/react-pdf-viewer react react-dom pdfjs-dist
+```
+
+### Setup pdf.js worker
+
+```ts
+import { GlobalWorkerOptions } from 'pdfjs-dist';
+
+GlobalWorkerOptions.workerSrc = new URL(
+  'pdfjs-dist/build/pdf.worker.min.mjs',
+  import.meta.url
+).toString();
+```
+
+## Quick Start
+
+```tsx
+import { PdfViewer } from '@matangot/react-pdf-viewer';
+import '@matangot/react-pdf-viewer/styles.css';
+
+function App() {
+  return (
+    <PdfViewer
+      src="https://example.com/document.pdf"
+      defaultPage={1}
+      defaultZoom="fit-width"
+      theme="system"
+    />
+  );
+}
+```
+
+## Compound Components
+
+For full control over layout and which actions to show:
+
+```tsx
+import { PdfViewer } from '@matangot/react-pdf-viewer';
+import '@matangot/react-pdf-viewer/styles.css';
+
+function CustomViewer() {
+  return (
+    <PdfViewer.Root src={pdfUrl} theme="dark">
+      <PdfViewer.Toolbar>
+        <PdfViewer.Navigation />
+        <PdfViewer.Separator />
+        <PdfViewer.Zoom />
+        <PdfViewer.Separator />
+        <PdfViewer.Download fileName="report.pdf" />
+        <PdfViewer.Print />
+        <PdfViewer.FullScreen />
+      </PdfViewer.Toolbar>
+      <PdfViewer.Pages />
+    </PdfViewer.Root>
+  );
+}
+```
+
+## Programmatic Access
+
+```tsx
+import { usePdfViewer } from '@matangot/react-pdf-viewer';
+
+function CustomControls() {
+  const { currentPage, totalPages, zoomIn, goToPage } = usePdfViewer();
+
+  return (
+    <div>
+      <span>Page {currentPage} of {totalPages}</span>
+      <button onClick={zoomIn}>Zoom In</button>
+      <button onClick={() => goToPage(1)}>Go to First Page</button>
+    </div>
+  );
+}
+```
+
+## Props
+
+### `<PdfViewer>` / `<PdfViewer.Root>`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src` | `string \| File \| ArrayBuffer \| Uint8Array` | — | PDF source (required) |
+| `defaultPage` | `number` | `1` | Initial page |
+| `defaultZoom` | `number \| 'fit-width' \| 'fit-page'` | `1` | Initial zoom |
+| `theme` | `'light' \| 'dark' \| 'system'` | `'system'` | Color theme |
+| `onPageChange` | `(page: number) => void` | — | Page change callback |
+| `onDocumentLoad` | `(info: DocumentInfo) => void` | — | Document load callback |
+| `className` | `string` | — | Additional CSS class |
+
+### `<PdfViewer.Download>`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `fileName` | `string` | Override downloaded file name |
+
+## Theming
+
+Override CSS custom properties to customize the look:
+
+```css
+.pdf-viewer {
+  --pdf-toolbar-bg: #1a1a2e;
+  --pdf-toolbar-color: #ffffff;
+  --pdf-toolbar-height: 48px;
+  --pdf-sidebar-width: 200px;
+  --pdf-page-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
+  --pdf-page-gap: 16px;
+  --pdf-search-highlight: rgba(255, 230, 0, 0.4);
+  --pdf-font-family: system-ui, sans-serif;
+}
+```
+
+For a completely custom look, skip importing `styles.css` and style from scratch using the BEM class names.
+
+## Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Arrow Left` / `Page Up` | Previous page |
+| `Arrow Right` / `Page Down` | Next page |
+| `Ctrl/Cmd + =` | Zoom in |
+| `Ctrl/Cmd + -` | Zoom out |
+| `Ctrl/Cmd + 0` | Reset zoom |
+| `Ctrl/Cmd + F` | Focus search |
+| `Enter` | Next search match |
+| `Shift + Enter` | Previous search match |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,234 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React, { ReactNode } from 'react';
+import * as pdfjs_dist from 'pdfjs-dist';
+
+declare function DocumentPropertiesModal(): react_jsx_runtime.JSX.Element | null;
+
+interface DropdownMenuProps {
+    trigger: ReactNode;
+    children: ReactNode;
+    className?: string;
+    align?: 'left' | 'right' | 'center';
+    title?: string;
+    triggerClassName?: string;
+}
+declare function DropdownMenu({ trigger, children, className, align, title, triggerClassName }: DropdownMenuProps): react_jsx_runtime.JSX.Element;
+interface DropdownMenuItemProps {
+    icon?: ReactNode;
+    label: string;
+    onClick: () => void;
+    disabled?: boolean;
+    active?: boolean;
+}
+declare function DropdownMenuItem({ icon, label, onClick, disabled, active }: DropdownMenuItemProps): react_jsx_runtime.JSX.Element;
+declare function DropdownMenuSeparator(): react_jsx_runtime.JSX.Element;
+
+interface MoreMenuProps {
+    className?: string;
+}
+declare function MoreMenu({ className }: MoreMenuProps): react_jsx_runtime.JSX.Element;
+
+interface CursorModeToggleProps {
+    className?: string;
+}
+declare function CursorModeToggle({ className }: CursorModeToggleProps): react_jsx_runtime.JSX.Element;
+
+interface PageProps {
+    pageNumber: number;
+    className?: string;
+}
+declare function Page({ pageNumber, className }: PageProps): react_jsx_runtime.JSX.Element;
+
+interface PagesProps {
+    className?: string;
+}
+declare function Pages({ className }: PagesProps): react_jsx_runtime.JSX.Element;
+
+interface ThumbnailSidebarProps {
+    className?: string;
+}
+declare function ThumbnailSidebar({ className }: ThumbnailSidebarProps): react_jsx_runtime.JSX.Element | null;
+
+interface ThumbnailToggleProps {
+    className?: string;
+}
+declare function ThumbnailToggle({ className }: ThumbnailToggleProps): react_jsx_runtime.JSX.Element;
+
+interface FullScreenProps {
+    className?: string;
+}
+declare function FullScreen({ className }: FullScreenProps): react_jsx_runtime.JSX.Element;
+
+interface PrintProps {
+    className?: string;
+}
+declare function Print({ className }: PrintProps): react_jsx_runtime.JSX.Element;
+
+interface DownloadProps {
+    fileName?: string;
+    className?: string;
+}
+declare function Download({ fileName, className }: DownloadProps): react_jsx_runtime.JSX.Element;
+
+interface RotateProps {
+    className?: string;
+}
+declare function Rotate({ className }: RotateProps): react_jsx_runtime.JSX.Element;
+
+interface SeparatorProps {
+    className?: string;
+}
+declare function Separator({ className }: SeparatorProps): react_jsx_runtime.JSX.Element;
+
+interface SearchProps {
+    className?: string;
+}
+declare function Search({ className }: SearchProps): react_jsx_runtime.JSX.Element;
+
+interface ZoomProps {
+    className?: string;
+}
+declare function Zoom({ className }: ZoomProps): react_jsx_runtime.JSX.Element;
+
+interface NavigationProps {
+    className?: string;
+}
+declare function Navigation({ className }: NavigationProps): react_jsx_runtime.JSX.Element;
+
+interface ToolbarProps {
+    className?: string;
+    children: ReactNode;
+}
+declare function Toolbar({ className, children }: ToolbarProps): react_jsx_runtime.JSX.Element;
+
+type PdfSource = string | File | ArrayBuffer | Uint8Array;
+type ZoomMode = 'fit-width' | 'fit-page';
+type ZoomValue = number | ZoomMode;
+type Theme = 'light' | 'dark' | 'system';
+type CursorMode = 'select' | 'hand';
+type ViewMode = 'single' | 'dual';
+type ScrollMode = 'page' | 'vertical' | 'horizontal';
+/** @deprecated Use ViewMode and ScrollMode instead */
+type LayoutMode = 'single' | 'dual' | 'horizontal';
+interface DocumentInfo {
+    numPages: number;
+    title?: string;
+    author?: string;
+}
+interface DocumentProperties {
+    fileName: string;
+    fileSize: string;
+    title: string;
+    author: string;
+    subject: string;
+    creator: string;
+    producer: string;
+    creationDate: string;
+    modificationDate: string;
+    pageCount: number;
+    pageSize: string;
+}
+interface SearchMatch {
+    pageIndex: number;
+    matchIndex: number;
+}
+interface PdfViewerState {
+    document: pdfjs_dist.PDFDocumentProxy | null;
+    isLoading: boolean;
+    error: Error | null;
+    currentPage: number;
+    totalPages: number;
+    zoomLevel: number;
+    zoomMode: ZoomMode | null;
+    rotation: number;
+    isThumbnailsOpen: boolean;
+    searchQuery: string;
+    searchMatches: SearchMatch[];
+    currentMatchIndex: number;
+    cursorMode: CursorMode;
+    viewMode: ViewMode;
+    scrollMode: ScrollMode;
+    layoutMode: LayoutMode;
+    isDocPropertiesOpen: boolean;
+    docProperties: DocumentProperties | null;
+    isPrinting: boolean;
+}
+interface PdfViewerActions {
+    goToPage: (page: number) => void;
+    nextPage: () => void;
+    prevPage: () => void;
+    zoomIn: () => void;
+    zoomOut: () => void;
+    zoomTo: (value: ZoomValue) => void;
+    /** @internal Set zoom level without clearing zoomMode (used by fit-zoom computation) */
+    _setZoomLevel: (level: number) => void;
+    /** @internal Set current page without scrolling (used by scroll tracking) */
+    _setCurrentPage: (page: number) => void;
+    rotate: (degrees?: number) => void;
+    toggleThumbnails: () => void;
+    search: (query: string) => void;
+    nextMatch: () => void;
+    prevMatch: () => void;
+    clearSearch: () => void;
+    download: (fileName?: string) => void;
+    print: () => void;
+    toggleFullScreen: () => void;
+    setCursorMode: (mode: CursorMode) => void;
+    toggleCursorMode: () => void;
+    setViewMode: (mode: ViewMode) => void;
+    setScrollMode: (mode: ScrollMode) => void;
+    setLayoutMode: (mode: LayoutMode) => void;
+    goToFirstPage: () => void;
+    goToLastPage: () => void;
+    openDocProperties: () => void;
+    closeDocProperties: () => void;
+    /** @internal Ref to the pages container element for fit-zoom calculations */
+    containerRef: React.MutableRefObject<HTMLElement | null>;
+    /** @internal Ref to scroll-to-page function set by Pages component */
+    scrollToPageRef: React.MutableRefObject<((page: number) => void) | null>;
+}
+type PdfViewerContextValue = PdfViewerState & PdfViewerActions;
+interface PdfViewerRootProps {
+    src: PdfSource;
+    defaultPage?: number;
+    defaultZoom?: ZoomValue;
+    defaultCursorMode?: CursorMode;
+    defaultSidebarOpen?: boolean;
+    theme?: Theme;
+    onPageChange?: (page: number) => void;
+    onDocumentLoad?: (info: DocumentInfo) => void;
+    className?: string;
+    children: React.ReactNode;
+}
+interface PdfViewerProps extends Omit<PdfViewerRootProps, 'children'> {
+}
+
+declare function Root({ src, defaultPage, defaultZoom, defaultCursorMode, defaultSidebarOpen, theme, onPageChange, onDocumentLoad, className, children, }: PdfViewerRootProps): react_jsx_runtime.JSX.Element;
+
+declare function PdfViewer(props: PdfViewerProps): react_jsx_runtime.JSX.Element;
+declare namespace PdfViewer {
+    var Root: typeof Root;
+    var Toolbar: typeof Toolbar;
+    var Navigation: typeof Navigation;
+    var Zoom: typeof Zoom;
+    var Search: typeof Search;
+    var Separator: typeof Separator;
+    var Rotate: typeof Rotate;
+    var Download: typeof Download;
+    var Print: typeof Print;
+    var FullScreen: typeof FullScreen;
+    var ThumbnailToggle: typeof ThumbnailToggle;
+    var ThumbnailSidebar: typeof ThumbnailSidebar;
+    var Pages: typeof Pages;
+    var Page: typeof Page;
+    var CursorModeToggle: typeof CursorModeToggle;
+    var MoreMenu: typeof MoreMenu;
+    var DropdownMenu: typeof DropdownMenu;
+    var DropdownMenuItem: typeof DropdownMenuItem;
+    var DropdownMenuSeparator: typeof DropdownMenuSeparator;
+    var DocumentPropertiesModal: typeof DocumentPropertiesModal;
+}
+
+declare function usePdfViewer(): PdfViewerContextValue;
+
+export { type CursorMode, CursorModeToggle, type DocumentInfo, type DocumentProperties, DocumentPropertiesModal, Download, DropdownMenu, DropdownMenuItem, DropdownMenuSeparator, FullScreen, type LayoutMode, MoreMenu, Navigation, Page, Pages, type PdfSource, PdfViewer, type PdfViewerContextValue, type PdfViewerProps, type PdfViewerRootProps, Print, Root, Rotate, type ScrollMode, Search, Separator, type Theme, ThumbnailSidebar, ThumbnailToggle, Toolbar, type ViewMode, Zoom, type ZoomMode, type ZoomValue, usePdfViewer };