pdf-tsx 1.0.1 → 1.1.1

package/README.md

@@ -1,634 +1,678 @@
-# pdf-tsx
-
-A fully-featured, composable PDF viewer component for React.
-
-**🔗 [Live demo & docs → pdf-tsx.netlify.app](https://pdf-tsx.netlify.app/)**
-
-## Installation
-
-```bash
-npm install pdf-tsx
-```
-
-### Peer dependencies
-
-```bash
-npm install react react-dom pdfjs-dist
-```
-
----
-
-## CSS
-
-Import the stylesheet once in your app entry point:
-
-```ts
-import "pdf-tsx/dist/es/pdf-tsx.css";
-```
-
----
-
-## Quick start
-
-`PDFViewer` requires a `workerSrc` prop — the URL of the pdfjs worker script. The easiest way is to serve it from the `pdfjs-dist` package directly:
-
-```tsx
-import { PDFViewer } from "pdf-tsx";
-import workerUrl from "pdfjs-dist/build/pdf.worker.min.mjs?url";
-
-function App() {
-  const [file, setFile] = useState<File | null>(null);
-
-  if (!file)
-    return (
-      <input
-        type="file"
-        accept=".pdf"
-        onChange={(e) => setFile(e.target.files![0])}
-      />
-    );
-
-  return <PDFViewer file={file} workerSrc={workerUrl} />;
-}
-```
-
-> The `?url` suffix is a Vite feature that returns the asset URL as a string. If you use a different bundler, import the worker URL accordingly or pass a CDN URL:
->
-> ```ts
-> workerSrc = "https://unpkg.com/pdfjs-dist@5/build/pdf.worker.min.mjs";
-> ```
-
----
-
-## Icons
-
-Feature components do not bundle any icon library. Each component that shows an icon requires you to pass it explicitly as a prop — use any icon library or custom SVG you prefer.
-
-```tsx
-import { LuZoomIn, LuZoomOut } from "react-icons/lu";
-
-<PDFZoomControls
-  zoomInIcon={<LuZoomIn size={16} />}
-  zoomOutIcon={<LuZoomOut size={16} />}
-/>;
-```
-
----
-
-## PDFViewer
-
-The main component. Must wrap all feature components.
-
-```tsx
-<PDFViewer
-  file={file}
-  workerSrc={workerUrl}
-  sidebar={<PDFSidebar panels={[...]} />}
-  toolbar={<>...</>}
-  onChangeFile={(newFile) => setFile(newFile)}
-/>
-```
-
-| Prop             | Type                                                | Required | Description                                             |
-| ---------------- | --------------------------------------------------- | -------- | ------------------------------------------------------- |
-| `file`           | `File`                                              | yes      | The PDF file object to display                          |
-| `workerSrc`      | `string`                                            | yes      | URL of the pdfjs worker script (see Quick start)        |
-| `sidebar`        | `ReactNode`                                         | no       | Content rendered on the left side                       |
-| `toolbar`        | `ReactNode`                                         | no       | Content rendered in the top toolbar                     |
-| `onChangeFile`   | `(file: File) => void`                              | no       | Called when the user opens a different file             |
-| `defaultTheme`   | `"light" \| "dark"`                                 | no       | Initial theme mode (default: `"light"`)                 |
-| `themeOverrides` | `{ light?: Partial<Theme>; dark?: Partial<Theme> }` | no       | Override individual theme tokens (see Theming)          |
-| `defaultFit`     | `"width" \| "page"`                                 | no       | Initial zoom mode when a PDF is loaded                  |
-| `language`       | `"it" \| "en"`                                      | no       | UI language (default: `"en"`)                           |
-| `className`      | `string`                                            | no       | CSS class applied to the root layout element            |
-| `style`          | `React.CSSProperties`                               | no       | Inline style applied to the root layout element         |
-| `requireRead`    | `boolean`                                           | no       | Show a mandatory-reading banner (see Mandatory reading) |
-| `onDocumentRead` | `() => void`                                        | no       | Called once when the user reaches the last page         |
-
----
-
-## Theming
-
-`PDFViewer` ships with built-in light and dark themes. The default is `"light"`. Use `defaultTheme` to set the initial mode and `themeOverrides` to override individual tokens without replacing the whole theme.
-
-```tsx
-import { PDFViewer, darkTheme } from 'pdf-tsx'
-
-<PDFViewer
-  themeOverrides={{
-    dark:  { accent: '#e11d48', accentHover: '#be123c', accentDark: '#9f1239' },
-    light: { accent: '#e11d48', accentHover: '#be123c', accentDark: '#9f1239' },
-  }}
-  ...
-/>
-```
-
-Both `darkTheme` and `lightTheme` are exported so you can spread them as a base:
-
-```tsx
-import { darkTheme } from 'pdf-tsx'
-
-themeOverrides={{ dark: { ...darkTheme, bg: '#0f0f0f' } }}
-```
-
-**Theme tokens** (`Theme` interface):
-
-| Token              | CSS variable              | Description                                                   |
-| ------------------ | ------------------------- | ------------------------------------------------------------- |
-| `bg`               | `--pdf-bg`                | Main background                                               |
-| `surface`          | `--pdf-surface`           | Card / panel surface                                          |
-| `surfaceHover`     | `--pdf-surface-hover`     | Surface hover state                                           |
-| `border`           | `--pdf-border`            | Default border color                                          |
-| `borderLight`      | `--pdf-border-light`      | Subtle border color                                           |
-| `scrollArea`       | `--pdf-scroll-area`       | Scroll container background                                   |
-| `textPrimary`      | `--pdf-text-primary`      | Primary text                                                  |
-| `textSecondary`    | `--pdf-text-secondary`    | Secondary text                                                |
-| `textMuted`        | `--pdf-text-muted`        | Muted / disabled text                                         |
-| `textPlaceholder`  | `--pdf-text-placeholder`  | Input placeholder text                                        |
-| `accent`           | `--pdf-accent`            | Accent / interactive color                                    |
-| `accentHover`      | `--pdf-accent-hover`      | Accent hover state                                            |
-| `accentDark`       | `--pdf-accent-dark`       | Accent dark variant                                           |
-| `accentLight`      | `--pdf-accent-light`      | Accent light variant                                          |
-| `accentSubtle`     | `--pdf-accent-subtle`     | Accent with low opacity (backgrounds)                         |
-| `panelBg`          | `--pdf-panel-bg`          | Sidebar panel background                                      |
-| `panelBorder`      | `--pdf-panel-border`      | Sidebar panel border                                          |
-| `panelHeaderBg`    | `--pdf-panel-header-bg`   | Sidebar panel header background                               |
-| `shadowPage`       | `--pdf-shadow-page`       | Drop shadow color for PDF pages                               |
-| `badgeBg`          | `--pdf-badge-bg`          | Count badge background (signatures, annotations, attachments) |
-| `toolbarSeparator` | `--pdf-toolbar-separator` | `PDFToolbarSeparator` line color                              |
-| `fontFamily`       | `--pdf-font-family`       | Font family for all viewer UI text                            |
-
----
-
-## PDFSidebar
-
-A collapsible icon sidebar. Each panel has an icon button — clicking it toggles the panel open/closed. When collapsed via `PDFSidebarToggle`, the entire sidebar is hidden (`null`).
-
-```tsx
-import { PDFSidebar } from "pdf-tsx";
-import { LuLayoutGrid, LuBookOpen } from "react-icons/lu";
-
-<PDFSidebar
-  panels={[
-    {
-      icon: <LuLayoutGrid size={18} />,
-      label: "Thumbnails",
-      content: <PDFThumbnails />,
-    },
-    {
-      icon: <LuBookOpen size={18} />,
-      label: "Outline",
-      content: <PDFOutline />,
-    },
-  ]}
-/>;
-```
-
-| Prop     | Type             | Description                |
-| -------- | ---------------- | -------------------------- |
-| `panels` | `SidebarPanel[]` | Array of panels to display |
-
-**SidebarPanel**
-
-| Field     | Type        | Description                            |
-| --------- | ----------- | -------------------------------------- |
-| `icon`    | `ReactNode` | Icon shown in the sidebar button bar   |
-| `label`   | `string`    | Panel title shown in the header        |
-| `content` | `ReactNode` | Content rendered inside the open panel |
-
-### Sidebar hide/show pattern
-
-Use `PDFSidebarToggle` in the toolbar alongside `PDFSidebar`. When the sidebar is open, the collapse button lives inside the sidebar. When collapsed, the expand button appears in the toolbar.
-
-```tsx
-import { PDFSidebar, PDFSidebarToggle, PDFToolbar } from 'pdf-tsx'
-import { LuPanelLeftClose, LuPanelLeftOpen, LuEllipsis } from 'react-icons/lu'
-
-<PDFViewer
-  sidebar={
-    <PDFSidebar panels={[...]} />
-  }
-  toolbar={
-    <PDFToolbar overflowIcon={<LuEllipsis size={16} />}>
-      <PDFSidebarToggle
-        collapseIcon={<LuPanelLeftClose size={16} />}
-        expandIcon={<LuPanelLeftOpen size={16} />}
-      />
-      {/* other toolbar items */}
-    </PDFToolbar>
-  }
-/>
-```
-
----
-
-## PDFToolbar (responsive toolbar)
-
-`PDFToolbar` wraps your toolbar items and automatically collapses those that don't fit the available width into an overflow `···` dropdown. It uses `ResizeObserver` to react to container size changes — no configuration required.
-
-```tsx
-import { PDFToolbar } from "pdf-tsx";
-import {
-  LuEllipsis,
-  LuPanelLeftClose,
-  LuPanelLeftOpen,
-  LuSearch,
-  LuChevronUp,
-  LuChevronDown,
-  LuX,
-  LuZoomOut,
-  LuZoomIn,
-  LuChevronLeft,
-  LuChevronRight,
-} from "react-icons/lu";
-
-<PDFViewer
-  toolbar={
-    <PDFToolbar overflowIcon={<LuEllipsis size={16} />}>
-      <PDFSidebarToggle
-        collapseIcon={<LuPanelLeftClose size={16} />}
-        expandIcon={<LuPanelLeftOpen size={16} />}
-      />
-      <PDFSearch
-        searchIcon={<LuSearch size={14} />}
-        prevIcon={<LuChevronUp size={14} />}
-        nextIcon={<LuChevronDown size={14} />}
-        clearIcon={<LuX size={14} />}
-      />
-      <PDFZoomControls
-        zoomOutIcon={<LuZoomOut size={16} />}
-        zoomInIcon={<LuZoomIn size={16} />}
-      />
-      <PDFNavigation
-        prevIcon={<LuChevronLeft size={16} />}
-        nextIcon={<LuChevronRight size={16} />}
-      />
-      {/* … more items */}
-    </PDFToolbar>
-  }
-/>;
-```
-
-| Prop           | Type        | Description                                           |
-| -------------- | ----------- | ----------------------------------------------------- |
-| `children`     | `ReactNode` | Toolbar items in priority order (left = highest)      |
-| `overflowIcon` | `ReactNode` | Icon for the `···` overflow button (default: `"···"`) |
-
-**Dropdown labels** — all built-in feature components carry a `toolbarLabelKey` static property. When an item is moved to the overflow dropdown, `PDFToolbar` resolves the label from the active language automatically. No extra configuration needed.
-
-**Custom items** — wrap any custom component in `PDFToolbarItem` to give it a dropdown label:
-
-```tsx
-import { PDFToolbarItem } from "pdf-tsx";
-
-<PDFToolbar overflowIcon={<LuEllipsis size={16} />}>
-  <PDFToolbarItem label="Custom">
-    <MyCustomButton />
-  </PDFToolbarItem>
-</PDFToolbar>;
-```
-
----
-
-## Feature components
-
-All feature components must be rendered inside `<PDFViewer>`. They read and write state via `usePDFViewer()` internally.
-
-| Component             | Icon props                                     | Description                                                                                                |
-| --------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `PDFToolbar`          | `overflowIcon`                                 | Responsive toolbar — collapses items into `···` dropdown when space runs out                               |
-| `PDFToolbarItem`      | —                                              | Wrapper for custom toolbar items to add a dropdown label                                                   |
-| `PDFToolbarSeparator` | —                                              | Vertical divider between toolbar groups — hidden automatically in the overflow dropdown                    |
-| `PDFThumbnails`       | —                                              | Page thumbnail strip for quick navigation                                                                  |
-| `PDFOutline`          | —                                              | Document outline / bookmarks tree                                                                          |
-| `PDFAnnotations`      | —                                              | Display PDF annotations                                                                                    |
-| `PDFAnnotationsIcon`  | `icon`                                         | Sidebar icon with annotation count badge                                                                   |
-| `PDFSignatures`       | —                                              | Display PDF digital signatures                                                                             |
-| `PDFSignaturesIcon`   | `icon`                                         | Sidebar icon with signature count badge                                                                    |
-| `PDFAttachments`      | —                                              | List embedded file attachments with download buttons                                                       |
-| `PDFAttachmentsIcon`  | `icon`                                         | Sidebar icon with attachment count badge                                                                   |
-| `PDFSearch`           | `searchIcon` `prevIcon` `nextIcon` `clearIcon` | Full-text search with match highlighting. Accepts optional `defaultSearch` to pre-fill and auto-navigate   |
-| `PDFZoomControls`     | `zoomInIcon` `zoomOutIcon`                     | Zoom in / zoom out buttons with percentage display                                                         |
-| `PDFPageFit`          | `fitWidthIcon` `fitPageIcon`                   | Fit-to-width and fit-to-page buttons                                                                       |
-| `PDFRotationControl`  | `icon`                                         | Rotate page clockwise                                                                                      |
-| `PDFNavigation`       | `prevIcon` `nextIcon`                          | Previous / next page buttons with current page input                                                       |
-| `PDFDownloadButton`   | `icon`                                         | Download the current PDF file                                                                              |
-| `PDFChangeFile`       | `icon`                                         | Button to open a new PDF file                                                                              |
-| `PDFThemeToggle`      | `lightIcon` `darkIcon`                         | Toggle between dark and light mode                                                                         |
-| `PDFPrintButton`      | `icon`                                         | Print the PDF using the browser's native print dialog                                                      |
-| `PDFSidebarToggle`    | `collapseIcon` `expandIcon`                    | Toolbar button to expand the sidebar — visible only when sidebar is hidden (see Sidebar hide/show pattern) |
-
-### PDFSearch
-
-| Prop            | Type        | Required | Description                                                                                                                                                       |
-| --------------- | ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `searchIcon`    | `ReactNode` | yes      | Icon shown inside the search input                                                                                                                                |
-| `prevIcon`      | `ReactNode` | yes      | Icon for the "previous match" button                                                                                                                              |
-| `nextIcon`      | `ReactNode` | yes      | Icon for the "next match" button                                                                                                                                  |
-| `clearIcon`     | `ReactNode` | yes      | Icon for the "clear search" button                                                                                                                                |
-| `initialSearch` | `string`    | no       | Pre-fills the search input and automatically navigates to the first match once the PDF is loaded. Navigation fires once — subsequent manual edits are unaffected. |
-
-```tsx
-<PDFSearch
-  initialSearch="invoice"
-  searchIcon={<LuSearch size={14} />}
-  prevIcon={<LuChevronUp size={14} />}
-  nextIcon={<LuChevronDown size={14} />}
-  clearIcon={<LuX size={14} />}
-/>
-```
-
----
-
-### Count badges
-
-`PDFSignaturesIcon`, `PDFAnnotationsIcon`, and `PDFAttachmentsIcon` are icon wrapper components intended for use as the `icon` prop in `PDFSidebar` panels. They render the provided icon with a small count badge in the top-right corner, automatically populated from the loaded PDF.
-
-```tsx
-import {
-  PDFSidebar,
-  PDFSignatures,
-  PDFSignaturesIcon,
-  PDFAnnotations,
-  PDFAnnotationsIcon,
-  PDFAttachments,
-  PDFAttachmentsIcon,
-} from "pdf-tsx";
-import { LuSignature, LuStickyNote, LuPaperclip } from "react-icons/lu";
-
-<PDFSidebar
-  panels={[
-    {
-      icon: <PDFSignaturesIcon icon={<LuSignature size={17} />} />,
-      label: "Signatures",
-      content: <PDFSignatures />,
-    },
-    {
-      icon: <PDFAnnotationsIcon icon={<LuStickyNote size={17} />} />,
-      label: "Annotations",
-      content: <PDFAnnotations />,
-    },
-    {
-      icon: <PDFAttachmentsIcon icon={<LuPaperclip size={17} />} />,
-      label: "Attachments",
-      content: <PDFAttachments />,
-    },
-  ]}
-/>;
-```
-
-The badge uses `var(--pdf-accent)` and respects `themeOverrides`.
-
----
-
-## Mandatory reading
-
-Use `requireRead` when the user must scroll through the entire document before proceeding (e.g. terms and conditions, consent forms).
-
-```tsx
-const [canProceed, setCanProceed] = useState(false)
-
-<PDFViewer
-  requireRead
-  onDocumentRead={() => setCanProceed(true)}
-  ...
-/>
-
-<button disabled={!canProceed}>Accetto</button>
-```
-
-`PDFViewer` renders a sticky banner at the bottom of the scroll area:
-
-- **Pending** — accent color, arrow-down icon, label `requireReadPending` ("Scroll to the end to continue")
-- **Confirmed** — green (`#16a34a`), checkmark icon, label `requireReadDone` ("Document read") — the banner stays visible after confirmation
-
-`onDocumentRead` fires at most once per loaded file. Both banner labels are part of the `Labels` interface and are translated automatically when `language="it"` is set.
-
----
-
-## Localisation
-
-`PDFViewer` ships with English (default) and Italian label sets. Switch via the `language` prop:
-
-```tsx
-<PDFViewer language="it" ... />
-```
-
-Both label objects are exported if you need to inspect them:
-
-```tsx
-import { italianLabels, englishLabels } from "pdf-tsx";
-```
-
-The `Labels` interface (also exported) describes every string key. The built-in toolbar overflow labels are resolved automatically from the active language — no extra configuration needed.
-
----
-
-## Full example
-
-```tsx
-import { useState, Suspense, lazy } from "react";
-import {
-  PDFSidebar,
-  PDFSidebarToggle,
-  PDFToolbar,
-  PDFToolbarItem,
-  PDFToolbarSeparator,
-  PDFThumbnails,
-  PDFOutline,
-  PDFSearch,
-  PDFZoomControls,
-  PDFPageFit,
-  PDFRotationControl,
-  PDFNavigation,
-  PDFDownloadButton,
-  PDFChangeFile,
-  PDFThemeToggle,
-  PDFPrintButton,
-  PDFSignatures,
-  PDFSignaturesIcon,
-  PDFAnnotations,
-  PDFAnnotationsIcon,
-  PDFAttachments,
-  PDFAttachmentsIcon,
-} from "pdf-tsx";
-import {
-  LuLayoutGrid,
-  LuBookOpen,
-  LuSignature,
-  LuStickyNote,
-  LuPaperclip,
-  LuSearch,
-  LuChevronUp,
-  LuChevronDown,
-  LuX,
-  LuZoomIn,
-  LuZoomOut,
-  LuArrowLeftRight,
-  LuScan,
-  LuRotateCw,
-  LuChevronLeft,
-  LuChevronRight,
-  LuDownload,
-  LuFolderPlus,
-  LuPrinter,
-  LuSun,
-  LuMoon,
-  LuPanelLeftClose,
-  LuPanelLeftOpen,
-  LuEllipsis,
-} from "react-icons/lu";
-import workerUrl from "pdfjs-dist/build/pdf.worker.min.mjs?url";
-
-const PDFViewer = lazy(() =>
-  import("pdf-tsx").then((m) => ({ default: m.PDFViewer })),
-);
-
-function App() {
-  const [file, setFile] = useState<File | null>(null);
-
-  if (!file) {
-    return (
-      <input
-        type="file"
-        accept=".pdf"
-        onChange={(e) => setFile(e.target.files![0])}
-      />
-    );
-  }
-
-  return (
-    <Suspense fallback={<div>Loading...</div>}>
-      <PDFViewer
-        file={file}
-        workerSrc={workerUrl}
-        defaultFit="width"
-        onChangeFile={setFile}
-        sidebar={
-          <PDFSidebar
-            panels={[
-              {
-                icon: <LuLayoutGrid size={18} />,
-                label: "Thumbnails",
-                content: <PDFThumbnails />,
-              },
-              {
-                icon: <LuBookOpen size={18} />,
-                label: "Outline",
-                content: <PDFOutline />,
-              },
-              {
-                icon: <PDFSignaturesIcon icon={<LuSignature size={17} />} />,
-                label: "Signatures",
-                content: <PDFSignatures />,
-              },
-              {
-                icon: <PDFAnnotationsIcon icon={<LuStickyNote size={17} />} />,
-                label: "Annotations",
-                content: <PDFAnnotations />,
-              },
-              {
-                icon: <PDFAttachmentsIcon icon={<LuPaperclip size={17} />} />,
-                label: "Attachments",
-                content: <PDFAttachments />,
-              },
-            ]}
-          />
-        }
-        toolbar={
-          <PDFToolbar overflowIcon={<LuEllipsis size={16} />}>
-            <PDFSidebarToggle
-              collapseIcon={<LuPanelLeftClose size={16} />}
-              expandIcon={<LuPanelLeftOpen size={16} />}
-            />
-            <PDFToolbarSeparator />
-            <PDFSearch
-              searchIcon={<LuSearch size={14} />}
-              prevIcon={<LuChevronUp size={14} />}
-              nextIcon={<LuChevronDown size={14} />}
-              clearIcon={<LuX size={14} />}
-            />
-            <PDFToolbarSeparator />
-            <PDFZoomControls
-              zoomOutIcon={<LuZoomOut size={16} />}
-              zoomInIcon={<LuZoomIn size={16} />}
-            />
-            <PDFRotationControl icon={<LuRotateCw size={16} />} />
-            <PDFPageFit
-              fitWidthIcon={<LuArrowLeftRight size={16} />}
-              fitPageIcon={<LuScan size={16} />}
-            />
-            <PDFToolbarSeparator />
-            <PDFNavigation
-              prevIcon={<LuChevronLeft size={16} />}
-              nextIcon={<LuChevronRight size={16} />}
-            />
-            <PDFToolbarSeparator />
-            <PDFThemeToggle
-              lightIcon={<LuSun size={16} />}
-              darkIcon={<LuMoon size={16} />}
-            />
-            <PDFPrintButton icon={<LuPrinter size={16} />} />
-            <PDFChangeFile icon={<LuFolderPlus size={16} />} />
-            <PDFDownloadButton icon={<LuDownload size={15} />} />
-            {/* custom button with overflow label */}
-            <PDFToolbarItem label="Share">
-              <button onClick={() => {}}>Share</button>
-            </PDFToolbarItem>
-          </PDFToolbar>
-        }
-      />
-    </Suspense>
-  );
-}
-```
-
----
-
-## Keyboard shortcuts
-
-When focus is not on an input or textarea, the following keys are active:
-
-| Key                        | Action        |
-| -------------------------- | ------------- |
-| `ArrowLeft` / `ArrowUp`    | Previous page |
-| `ArrowRight` / `ArrowDown` | Next page     |
-| `r` / `R`                  | Rotate +90°   |
-
-## Gesture & zoom controls
-
-Zoom can be controlled via toolbar buttons (`PDFZoomControls`), keyboard/trackpad gestures, and touch gestures — no configuration required.
-
-| Input                    | Action                                |
-| ------------------------ | ------------------------------------- |
-| `Ctrl + scroll` (mouse)  | Zoom in / out                         |
-| `Cmd + scroll` (macOS)   | Zoom in / out                         |
-| Trackpad pinch (desktop) | Zoom in / out                         |
-| Two-finger pinch (touch) | Zoom in / out                         |
-| Double tap (touch)       | Toggle between 2× zoom and 1× (reset) |
-
-Zoom is clamped to the range `[0.2, 3.0]`. Any manual gesture clears the active `fitMode` (`"width"` / `"page"`).
-
----
-
-## Performance
-
-`pdf-tsx` uses **virtual rendering**: only the pages near the current view are rendered at any one time. The default window is the current page ±2. Pages with an active highlight or search match are always included regardless of position.
-
-This means:
-
-- Initial load renders at most 5 pages, regardless of document length
-- Memory and CPU usage stay flat as the user scrolls through a large document
-- Pages that have already been rendered are kept in the DOM as the user scrolls, avoiding redundant re-renders
-
-Render cascades are minimised via manual memoization: the context value is wrapped in `useMemo` so a zoom or page change does not re-render unrelated consumers, and inner sub-components (`AnnotationCard`, `SignatureCard`, `OutlineItem`) are wrapped in `React.memo`.
-
-No configuration is needed — this is the default behaviour.
-
----
-
-## License
-
-**PolyForm Noncommercial License 1.0.0** © Riccardo Grossano — see [LICENSE](./LICENSE) for full terms.
-
-Free for noncommercial use (personal, research, education, non-profit). **Commercial use requires a separate commercial license** — _coming soon_.
+# pdf-tsx
+
+A fully-featured, composable PDF viewer component for React.
+
+**🔗 [Live demo & docs → pdf-tsx.netlify.app](https://pdf-tsx.netlify.app/)**
+
+## Installation
+
+```bash
+npm install pdf-tsx
+```
+
+### Peer dependencies
+
+```bash
+npm install react react-dom pdfjs-dist
+```
+
+---
+
+## CSS
+
+Import the stylesheet once in your app entry point:
+
+```ts
+import "pdf-tsx/dist/es/pdf-tsx.css";
+```
+
+---
+
+## Quick start
+
+`PDFViewer` requires a `workerSrc` prop — the URL of the pdfjs worker script. The easiest way is to serve it from the `pdfjs-dist` package directly:
+
+```tsx
+import { PDFViewer } from "pdf-tsx";
+import workerUrl from "pdfjs-dist/build/pdf.worker.min.mjs?url";
+
+function App() {
+  const [file, setFile] = useState<File | null>(null);
+
+  if (!file)
+    return (
+      <input
+        type="file"
+        accept=".pdf"
+        onChange={(e) => setFile(e.target.files![0])}
+      />
+    );
+
+  return <PDFViewer file={file} workerSrc={workerUrl} />;
+}
+```
+
+> The `?url` suffix is a Vite feature that returns the asset URL as a string. If you use a different bundler, import the worker URL accordingly or pass a CDN URL:
+>
+> ```ts
+> workerSrc = "https://unpkg.com/pdfjs-dist@5/build/pdf.worker.min.mjs";
+> ```
+
+PDFs containing JPEG2000 (JPX) or JBIG2-encoded images (common in scanned documents) render correctly out of the box — the required decoders are bundled with the library, no extra setup needed.
+
+---
+
+## Icons
+
+Feature components do not bundle any icon library. Each component that shows an icon requires you to pass it explicitly as a prop — use any icon library or custom SVG you prefer.
+
+```tsx
+import { LuZoomIn, LuZoomOut } from "react-icons/lu";
+
+<PDFZoomControls
+  zoomInIcon={<LuZoomIn size={16} />}
+  zoomOutIcon={<LuZoomOut size={16} />}
+/>;
+```
+
+---
+
+## PDFViewer
+
+The main component. Must wrap all feature components.
+
+```tsx
+<PDFViewer
+  file={file}
+  workerSrc={workerUrl}
+  sidebar={<PDFSidebar panels={[...]} />}
+  toolbar={<>...</>}
+  onChangeFile={(newFile) => setFile(newFile)}
+/>
+```
+
+| Prop             | Type                                                | Required | Description                                             |
+| ---------------- | --------------------------------------------------- | -------- | ------------------------------------------------------- |
+| `file`           | `File`                                              | yes      | The PDF file object to display                          |
+| `workerSrc`      | `string`                                            | yes      | URL of the pdfjs worker script (see Quick start)        |
+| `sidebar`        | `ReactNode`                                         | no       | Content rendered on the left side                       |
+| `toolbar`        | `ReactNode`                                         | no       | Content rendered in the top toolbar                     |
+| `onChangeFile`   | `(file: File) => void`                              | no       | Called when the user opens a different file             |
+| `defaultTheme`   | `"light" \| "dark"`                                 | no       | Initial theme mode (default: `"light"`)                 |
+| `themeOverrides` | `{ light?: Partial<Theme>; dark?: Partial<Theme> }` | no       | Override individual theme tokens (see Theming)          |
+| `defaultFit`     | `"width" \| "page"`                                 | no       | Initial zoom mode when a PDF is loaded                  |
+| `defaultLayout`  | `"continuous" \| "single" \| "spread"`              | no       | Initial page layout (default: `"continuous"`, see Page layouts) |
+| `language`       | `"it" \| "en"`                                      | no       | UI language (default: `"en"`)                           |
+| `className`      | `string`                                            | no       | CSS class applied to the root layout element            |
+| `style`          | `React.CSSProperties`                               | no       | Inline style applied to the root layout element         |
+| `requireRead`    | `boolean`                                           | no       | Show a mandatory-reading banner (see Mandatory reading) |
+| `onDocumentRead` | `() => void`                                        | no       | Called once when the user reaches the last page         |
+
+---
+
+## Theming
+
+`PDFViewer` ships with built-in light and dark themes. The default is `"light"`. Use `defaultTheme` to set the initial mode and `themeOverrides` to override individual tokens without replacing the whole theme.
+
+```tsx
+import { PDFViewer, darkTheme } from 'pdf-tsx'
+
+<PDFViewer
+  themeOverrides={{
+    dark:  { accent: '#e11d48', accentHover: '#be123c', accentDark: '#9f1239' },
+    light: { accent: '#e11d48', accentHover: '#be123c', accentDark: '#9f1239' },
+  }}
+  ...
+/>
+```
+
+Both `darkTheme` and `lightTheme` are exported so you can spread them as a base:
+
+```tsx
+import { darkTheme } from 'pdf-tsx'
+
+themeOverrides={{ dark: { ...darkTheme, bg: '#0f0f0f' } }}
+```
+
+**Theme tokens** (`Theme` interface):
+
+| Token              | CSS variable              | Description                                                   |
+| ------------------ | ------------------------- | ------------------------------------------------------------- |
+| `bg`               | `--pdf-bg`                | Main background                                               |
+| `surface`          | `--pdf-surface`           | Card / panel surface                                          |
+| `surfaceHover`     | `--pdf-surface-hover`     | Surface hover state                                           |
+| `border`           | `--pdf-border`            | Default border color                                          |
+| `borderLight`      | `--pdf-border-light`      | Subtle border color                                           |
+| `scrollArea`       | `--pdf-scroll-area`       | Scroll container background                                   |
+| `textPrimary`      | `--pdf-text-primary`      | Primary text                                                  |
+| `textSecondary`    | `--pdf-text-secondary`    | Secondary text                                                |
+| `textMuted`        | `--pdf-text-muted`        | Muted / disabled text                                         |
+| `textPlaceholder`  | `--pdf-text-placeholder`  | Input placeholder text                                        |
+| `accent`           | `--pdf-accent`            | Accent / interactive color                                    |
+| `accentHover`      | `--pdf-accent-hover`      | Accent hover state                                            |
+| `accentDark`       | `--pdf-accent-dark`       | Accent dark variant                                           |
+| `accentLight`      | `--pdf-accent-light`      | Accent light variant                                          |
+| `accentSubtle`     | `--pdf-accent-subtle`     | Accent with low opacity (backgrounds)                         |
+| `panelBg`          | `--pdf-panel-bg`          | Sidebar panel background                                      |
+| `panelBorder`      | `--pdf-panel-border`      | Sidebar panel border                                          |
+| `panelHeaderBg`    | `--pdf-panel-header-bg`   | Sidebar panel header background                               |
+| `shadowPage`       | `--pdf-shadow-page`       | Drop shadow color for PDF pages                               |
+| `badgeBg`          | `--pdf-badge-bg`          | Count badge background (signatures, annotations, attachments) |
+| `toolbarSeparator` | `--pdf-toolbar-separator` | `PDFToolbarSeparator` line color                              |
+| `fontFamily`       | `--pdf-font-family`       | Font family for all viewer UI text                            |
+
+---
+
+## PDFSidebar
+
+A collapsible icon sidebar. Each panel has an icon button — clicking it toggles the panel open/closed. When collapsed via `PDFSidebarToggle`, the entire sidebar is hidden (`null`).
+
+```tsx
+import { PDFSidebar } from "pdf-tsx";
+import { LuLayoutGrid, LuBookOpen } from "react-icons/lu";
+
+<PDFSidebar
+  panels={[
+    {
+      icon: <LuLayoutGrid size={18} />,
+      label: "Thumbnails",
+      content: <PDFThumbnails />,
+    },
+    {
+      icon: <LuBookOpen size={18} />,
+      label: "Outline",
+      content: <PDFOutline />,
+    },
+  ]}
+/>;
+```
+
+| Prop     | Type             | Description                |
+| -------- | ---------------- | -------------------------- |
+| `panels` | `SidebarPanel[]` | Array of panels to display |
+
+**SidebarPanel**
+
+| Field     | Type        | Description                            |
+| --------- | ----------- | -------------------------------------- |
+| `icon`    | `ReactNode` | Icon shown in the sidebar button bar   |
+| `label`   | `string`    | Panel title shown in the header        |
+| `content` | `ReactNode` | Content rendered inside the open panel |
+
+### Sidebar hide/show pattern
+
+Use `PDFSidebarToggle` in the toolbar alongside `PDFSidebar`. When the sidebar is open, the collapse button lives inside the sidebar. When collapsed, the expand button appears in the toolbar.
+
+```tsx
+import { PDFSidebar, PDFSidebarToggle, PDFToolbar } from 'pdf-tsx'
+import { LuPanelLeftClose, LuPanelLeftOpen, LuEllipsis } from 'react-icons/lu'
+
+<PDFViewer
+  sidebar={
+    <PDFSidebar panels={[...]} />
+  }
+  toolbar={
+    <PDFToolbar overflowIcon={<LuEllipsis size={16} />}>
+      <PDFSidebarToggle
+        collapseIcon={<LuPanelLeftClose size={16} />}
+        expandIcon={<LuPanelLeftOpen size={16} />}
+      />
+      {/* other toolbar items */}
+    </PDFToolbar>
+  }
+/>
+```
+
+---
+
+## PDFToolbar (responsive toolbar)
+
+`PDFToolbar` wraps your toolbar items and automatically collapses those that don't fit the available width into an overflow `···` dropdown. It uses `ResizeObserver` to react to container size changes — no configuration required.
+
+```tsx
+import { PDFToolbar } from "pdf-tsx";
+import {
+  LuEllipsis,
+  LuPanelLeftClose,
+  LuPanelLeftOpen,
+  LuSearch,
+  LuChevronUp,
+  LuChevronDown,
+  LuX,
+  LuZoomOut,
+  LuZoomIn,
+  LuChevronLeft,
+  LuChevronRight,
+} from "react-icons/lu";
+
+<PDFViewer
+  toolbar={
+    <PDFToolbar overflowIcon={<LuEllipsis size={16} />}>
+      <PDFSidebarToggle
+        collapseIcon={<LuPanelLeftClose size={16} />}
+        expandIcon={<LuPanelLeftOpen size={16} />}
+      />
+      <PDFSearch
+        searchIcon={<LuSearch size={14} />}
+        prevIcon={<LuChevronUp size={14} />}
+        nextIcon={<LuChevronDown size={14} />}
+        clearIcon={<LuX size={14} />}
+      />
+      <PDFZoomControls
+        zoomOutIcon={<LuZoomOut size={16} />}
+        zoomInIcon={<LuZoomIn size={16} />}
+      />
+      <PDFNavigation
+        prevIcon={<LuChevronLeft size={16} />}
+        nextIcon={<LuChevronRight size={16} />}
+      />
+      {/* … more items */}
+    </PDFToolbar>
+  }
+/>;
+```
+
+| Prop           | Type        | Description                                           |
+| -------------- | ----------- | ----------------------------------------------------- |
+| `children`     | `ReactNode` | Toolbar items in priority order (left = highest)      |
+| `overflowIcon` | `ReactNode` | Icon for the `···` overflow button (default: `"···"`) |
+
+**Dropdown labels** — all built-in feature components carry a `toolbarLabelKey` static property. When an item is moved to the overflow dropdown, `PDFToolbar` resolves the label from the active language automatically. No extra configuration needed.
+
+**Custom items** — wrap any custom component in `PDFToolbarItem` to give it a dropdown label:
+
+```tsx
+import { PDFToolbarItem } from "pdf-tsx";
+
+<PDFToolbar overflowIcon={<LuEllipsis size={16} />}>
+  <PDFToolbarItem label="Custom">
+    <MyCustomButton />
+  </PDFToolbarItem>
+</PDFToolbar>;
+```
+
+---
+
+## Feature components
+
+All feature components must be rendered inside `<PDFViewer>`. They read and write state via `usePDFViewer()` internally.
+
+| Component             | Icon props                                     | Description                                                                                                |
+| --------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `PDFToolbar`          | `overflowIcon`                                 | Responsive toolbar — collapses items into `···` dropdown when space runs out                               |
+| `PDFToolbarItem`      | —                                              | Wrapper for custom toolbar items to add a dropdown label                                                   |
+| `PDFToolbarSeparator` | —                                              | Vertical divider between toolbar groups — hidden automatically in the overflow dropdown                    |
+| `PDFThumbnails`       | —                                              | Page thumbnail strip for quick navigation                                                                  |
+| `PDFOutline`          | —                                              | Document outline / bookmarks tree                                                                          |
+| `PDFAnnotations`      | —                                              | Display PDF annotations                                                                                    |
+| `PDFAnnotationsIcon`  | `icon`                                         | Sidebar icon with annotation count badge                                                                   |
+| `PDFSignatures`       | —                                              | Display PDF digital signatures                                                                             |
+| `PDFSignaturesIcon`   | `icon`                                         | Sidebar icon with signature count badge                                                                    |
+| `PDFAttachments`      | —                                              | List embedded file attachments with download buttons                                                       |
+| `PDFAttachmentsIcon`  | `icon`                                         | Sidebar icon with attachment count badge                                                                   |
+| `PDFSearch`           | `searchIcon` `prevIcon` `nextIcon` `clearIcon` | Full-text search with match highlighting. Accepts optional `defaultSearch` to pre-fill and auto-navigate   |
+| `PDFZoomControls`     | `zoomInIcon` `zoomOutIcon`                     | Zoom in / zoom out buttons with percentage display                                                         |
+| `PDFPageFit`          | `fitWidthIcon` `fitPageIcon`                   | Fit-to-width and fit-to-page buttons                                                                       |
+| `PDFViewModeToggle`   | `continuousIcon` `singleIcon` `spreadIcon`     | Dropdown to switch page layout (continuous / single / spread) — see Page layouts                          |
+| `PDFRotationControl`  | `icon`                                         | Rotate page clockwise                                                                                      |
+| `PDFNavigation`       | `prevIcon` `nextIcon`                          | Previous / next page buttons with current page input                                                       |
+| `PDFDownloadButton`   | `icon`                                         | Download the current PDF file                                                                              |
+| `PDFChangeFile`       | `icon`                                         | Button to open a new PDF file                                                                              |
+| `PDFThemeToggle`      | `lightIcon` `darkIcon`                         | Toggle between dark and light mode                                                                         |
+| `PDFPrintButton`      | `icon`                                         | Print the PDF using the browser's native print dialog                                                      |
+| `PDFSidebarToggle`    | `collapseIcon` `expandIcon`                    | Toolbar button to expand the sidebar — visible only when sidebar is hidden (see Sidebar hide/show pattern) |
+
+### PDFSearch
+
+| Prop            | Type        | Required | Description                                                                                                                                                       |
+| --------------- | ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `searchIcon`    | `ReactNode` | yes      | Icon shown inside the search input                                                                                                                                |
+| `prevIcon`      | `ReactNode` | yes      | Icon for the "previous match" button                                                                                                                              |
+| `nextIcon`      | `ReactNode` | yes      | Icon for the "next match" button                                                                                                                                  |
+| `clearIcon`     | `ReactNode` | yes      | Icon for the "clear search" button                                                                                                                                |
+| `initialSearch` | `string`    | no       | Pre-fills the search input and automatically navigates to the first match once the PDF is loaded. Navigation fires once — subsequent manual edits are unaffected. |
+
+```tsx
+<PDFSearch
+  initialSearch="invoice"
+  searchIcon={<LuSearch size={14} />}
+  prevIcon={<LuChevronUp size={14} />}
+  nextIcon={<LuChevronDown size={14} />}
+  clearIcon={<LuX size={14} />}
+/>
+```
+
+---
+
+### Count badges
+
+`PDFSignaturesIcon`, `PDFAnnotationsIcon`, and `PDFAttachmentsIcon` are icon wrapper components intended for use as the `icon` prop in `PDFSidebar` panels. They render the provided icon with a small count badge in the top-right corner, automatically populated from the loaded PDF.
+
+```tsx
+import {
+  PDFSidebar,
+  PDFSignatures,
+  PDFSignaturesIcon,
+  PDFAnnotations,
+  PDFAnnotationsIcon,
+  PDFAttachments,
+  PDFAttachmentsIcon,
+} from "pdf-tsx";
+import { LuSignature, LuStickyNote, LuPaperclip } from "react-icons/lu";
+
+<PDFSidebar
+  panels={[
+    {
+      icon: <PDFSignaturesIcon icon={<LuSignature size={17} />} />,
+      label: "Signatures",
+      content: <PDFSignatures />,
+    },
+    {
+      icon: <PDFAnnotationsIcon icon={<LuStickyNote size={17} />} />,
+      label: "Annotations",
+      content: <PDFAnnotations />,
+    },
+    {
+      icon: <PDFAttachmentsIcon icon={<LuPaperclip size={17} />} />,
+      label: "Attachments",
+      content: <PDFAttachments />,
+    },
+  ]}
+/>;
+```
+
+The badge uses `var(--pdf-accent)` and respects `themeOverrides`.
+
+---
+
+## Page layouts
+
+`PDFViewer` arranges pages in one of three layouts, controlled by the `defaultLayout` prop and switchable at runtime with `PDFViewModeToggle`:
+
+| Layout       | Behaviour                                                          |
+| ------------ | ----------------------------------------------------------------- |
+| `continuous` | Vertical scroll, one page after another (default)                 |
+| `single`     | One page at a time — navigate with `PDFNavigation` / arrow keys    |
+| `spread`     | Pages flow side by side, as many per row as fit the viewport width |
+
+`PDFViewModeToggle` renders a single toolbar button (showing the active layout's icon plus a chevron) that opens a dropdown to pick the layout:
+
+```tsx
+import { PDFViewModeToggle } from "pdf-tsx";
+import { LuScrollText, LuFile, LuBookOpenText } from "react-icons/lu";
+
+<PDFViewModeToggle
+  continuousIcon={<LuScrollText size={16} />}
+  singleIcon={<LuFile size={16} />}
+  spreadIcon={<LuBookOpenText size={16} />}
+/>;
+```
+
+| Prop             | Type        | Required | Description                          |
+| ---------------- | ----------- | -------- | ------------------------------------ |
+| `continuousIcon` | `ReactNode` | yes      | Icon for the continuous layout option |
+| `singleIcon`     | `ReactNode` | yes      | Icon for the single-page layout option |
+| `spreadIcon`     | `ReactNode` | yes      | Icon for the spread layout option    |
+
+---
+
+## Mandatory reading
+
+Use `requireRead` when the user must scroll through the entire document before proceeding (e.g. terms and conditions, consent forms).
+
+```tsx
+const [canProceed, setCanProceed] = useState(false)
+
+<PDFViewer
+  requireRead
+  onDocumentRead={() => setCanProceed(true)}
+  ...
+/>
+
+<button disabled={!canProceed}>Accetto</button>
+```
+
+`PDFViewer` renders a sticky banner at the bottom of the scroll area:
+
+- **Pending** — accent color, arrow-down icon, label `requireReadPending` ("Scroll to the end to continue")
+- **Confirmed** — green (`#16a34a`), checkmark icon, label `requireReadDone` ("Document read") — the banner stays visible after confirmation
+
+`onDocumentRead` fires at most once per loaded file. Both banner labels are part of the `Labels` interface and are translated automatically when `language="it"` is set.
+
+---
+
+## Localisation
+
+`PDFViewer` ships with English (default) and Italian label sets. Switch via the `language` prop:
+
+```tsx
+<PDFViewer language="it" ... />
+```
+
+Both label objects are exported if you need to inspect them:
+
+```tsx
+import { italianLabels, englishLabels } from "pdf-tsx";
+```
+
+The `Labels` interface (also exported) describes every string key. The built-in toolbar overflow labels are resolved automatically from the active language — no extra configuration needed.
+
+---
+
+## Full example
+
+```tsx
+import { useState, Suspense, lazy } from "react";
+import {
+  PDFSidebar,
+  PDFSidebarToggle,
+  PDFToolbar,
+  PDFToolbarItem,
+  PDFToolbarSeparator,
+  PDFThumbnails,
+  PDFOutline,
+  PDFSearch,
+  PDFZoomControls,
+  PDFPageFit,
+  PDFViewModeToggle,
+  PDFRotationControl,
+  PDFNavigation,
+  PDFDownloadButton,
+  PDFChangeFile,
+  PDFThemeToggle,
+  PDFPrintButton,
+  PDFSignatures,
+  PDFSignaturesIcon,
+  PDFAnnotations,
+  PDFAnnotationsIcon,
+  PDFAttachments,
+  PDFAttachmentsIcon,
+} from "pdf-tsx";
+import {
+  LuLayoutGrid,
+  LuBookOpen,
+  LuSignature,
+  LuStickyNote,
+  LuPaperclip,
+  LuSearch,
+  LuChevronUp,
+  LuChevronDown,
+  LuX,
+  LuZoomIn,
+  LuZoomOut,
+  LuArrowLeftRight,
+  LuScan,
+  LuScrollText,
+  LuFile,
+  LuBookOpenText,
+  LuRotateCw,
+  LuChevronLeft,
+  LuChevronRight,
+  LuDownload,
+  LuFolderPlus,
+  LuPrinter,
+  LuSun,
+  LuMoon,
+  LuPanelLeftClose,
+  LuPanelLeftOpen,
+  LuEllipsis,
+} from "react-icons/lu";
+import workerUrl from "pdfjs-dist/build/pdf.worker.min.mjs?url";
+
+const PDFViewer = lazy(() =>
+  import("pdf-tsx").then((m) => ({ default: m.PDFViewer })),
+);
+
+function App() {
+  const [file, setFile] = useState<File | null>(null);
+
+  if (!file) {
+    return (
+      <input
+        type="file"
+        accept=".pdf"
+        onChange={(e) => setFile(e.target.files![0])}
+      />
+    );
+  }
+
+  return (
+    <Suspense fallback={<div>Loading...</div>}>
+      <PDFViewer
+        file={file}
+        workerSrc={workerUrl}
+        defaultFit="width"
+        onChangeFile={setFile}
+        sidebar={
+          <PDFSidebar
+            panels={[
+              {
+                icon: <LuLayoutGrid size={18} />,
+                label: "Thumbnails",
+                content: <PDFThumbnails />,
+              },
+              {
+                icon: <LuBookOpen size={18} />,
+                label: "Outline",
+                content: <PDFOutline />,
+              },
+              {
+                icon: <PDFSignaturesIcon icon={<LuSignature size={17} />} />,
+                label: "Signatures",
+                content: <PDFSignatures />,
+              },
+              {
+                icon: <PDFAnnotationsIcon icon={<LuStickyNote size={17} />} />,
+                label: "Annotations",
+                content: <PDFAnnotations />,
+              },
+              {
+                icon: <PDFAttachmentsIcon icon={<LuPaperclip size={17} />} />,
+                label: "Attachments",
+                content: <PDFAttachments />,
+              },
+            ]}
+          />
+        }
+        toolbar={
+          <PDFToolbar overflowIcon={<LuEllipsis size={16} />}>
+            <PDFSidebarToggle
+              collapseIcon={<LuPanelLeftClose size={16} />}
+              expandIcon={<LuPanelLeftOpen size={16} />}
+            />
+            <PDFToolbarSeparator />
+            <PDFSearch
+              searchIcon={<LuSearch size={14} />}
+              prevIcon={<LuChevronUp size={14} />}
+              nextIcon={<LuChevronDown size={14} />}
+              clearIcon={<LuX size={14} />}
+            />
+            <PDFToolbarSeparator />
+            <PDFZoomControls
+              zoomOutIcon={<LuZoomOut size={16} />}
+              zoomInIcon={<LuZoomIn size={16} />}
+            />
+            <PDFRotationControl icon={<LuRotateCw size={16} />} />
+            <PDFPageFit
+              fitWidthIcon={<LuArrowLeftRight size={16} />}
+              fitPageIcon={<LuScan size={16} />}
+            />
+            <PDFViewModeToggle
+              continuousIcon={<LuScrollText size={16} />}
+              singleIcon={<LuFile size={16} />}
+              spreadIcon={<LuBookOpenText size={16} />}
+            />
+            <PDFToolbarSeparator />
+            <PDFNavigation
+              prevIcon={<LuChevronLeft size={16} />}
+              nextIcon={<LuChevronRight size={16} />}
+            />
+            <PDFToolbarSeparator />
+            <PDFThemeToggle
+              lightIcon={<LuSun size={16} />}
+              darkIcon={<LuMoon size={16} />}
+            />
+            <PDFPrintButton icon={<LuPrinter size={16} />} />
+            <PDFChangeFile icon={<LuFolderPlus size={16} />} />
+            <PDFDownloadButton icon={<LuDownload size={15} />} />
+            {/* custom button with overflow label */}
+            <PDFToolbarItem label="Share">
+              <button onClick={() => {}}>Share</button>
+            </PDFToolbarItem>
+          </PDFToolbar>
+        }
+      />
+    </Suspense>
+  );
+}
+```
+
+---
+
+## Keyboard shortcuts
+
+When focus is not on an input or textarea, the following keys are active:
+
+| Key                        | Action        |
+| -------------------------- | ------------- |
+| `ArrowLeft` / `ArrowUp`    | Previous page |
+| `ArrowRight` / `ArrowDown` | Next page     |
+| `r` / `R`                  | Rotate +90°   |
+
+## Gesture & zoom controls
+
+Zoom can be controlled via toolbar buttons (`PDFZoomControls`), keyboard/trackpad gestures, and touch gestures — no configuration required.
+
+| Input                    | Action                                |
+| ------------------------ | ------------------------------------- |
+| `Ctrl + scroll` (mouse)  | Zoom in / out                         |
+| `Cmd + scroll` (macOS)   | Zoom in / out                         |
+| Trackpad pinch (desktop) | Zoom in / out                         |
+| Two-finger pinch (touch) | Zoom in / out                         |
+| Double tap (touch)       | Toggle between 2× zoom and 1× (reset) |
+
+Zoom is clamped to the range `[0.2, 3.0]`. Any manual gesture clears the active `fitMode` (`"width"` / `"page"`).
+
+---
+
+## Performance
+
+`pdf-tsx` uses **virtual rendering**: only the pages that are actually in (or near) the viewport are rendered at any one time. A page is rendered when it intersects the scroll container (via `IntersectionObserver`), plus the current page ±2 as a buffer. Pages with an active highlight or search match are always included regardless of position. This holds across all layouts — including `spread` and when zoomed far out, where many pages are on screen at once.
+
+This means:
+
+- A long document only renders the handful of pages on screen, regardless of total length
+- Memory and CPU usage stay flat as the user scrolls through a large document
+- Pages that have already been rendered are kept in the DOM as the user scrolls, avoiding redundant re-renders
+
+Render cascades are minimised via manual memoization: the context value is wrapped in `useMemo` so a zoom or page change does not re-render unrelated consumers, and inner sub-components (`AnnotationCard`, `SignatureCard`, `OutlineItem`) are wrapped in `React.memo`.
+
+No configuration is needed — this is the default behaviour.
+
+---
+
+## License
+
+**PolyForm Noncommercial License 1.0.0** © Riccardo Grossano — see [LICENSE](./LICENSE) for full terms.
+
+Free for noncommercial use (personal, research, education, non-profit). **Commercial use requires a separate commercial license** — _coming soon_.