pdf-tsx 0.17.9 → 1.0.0

package/README.md

@@ -1,512 +1,632 @@
-# pdf-tsx
-
-A fully-featured, composable PDF viewer component for React.
-
-## 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
-
-MIT © Riccardo Grossano — see [LICENSE](./LICENSE) for full terms.
+# pdf-tsx
+
+A fully-featured, composable PDF viewer component for React.
+
+## 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_.