@hussmartinez/pdf-sdk 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -22,10 +22,43 @@ const editor = useRef<PdfEditorHandle>(null);
22
22
  const bytes = await editor.current?.export();
23
23
  ```
24
24
 
25
- `PdfEditor` fills the height of its container, and its viewer and thumbnails scroll within it, so give it a bounded height: a fixed height, or a grid row such as `minmax(0, 1fr)`. The same goes for `PdfViewer` and `PdfThumbnails` used on their own. **Styles:** import `@hussmartinez/ui/styles.css` before `@hussmartinez/pdf-sdk/styles.css`, once, in your application. ui's stylesheet defines the design tokens that give the editor its designed look, light and dark themes and theming; the SDK's stylesheet doesn't bundle it. Without it the editor keeps its layout and stays usable, but loses its colours, spacing and shadows. Every value is also a `--hm-pdf-*` property you can set on any ancestor.
25
+ **Styles: ui's stylesheet is required.** Import `@hussmartinez/ui/styles.css` once in your application, before `@hussmartinez/pdf-sdk/styles.css`, as above. The editor's toolbar is built from [`@hussmartinez/ui`](https://www.npmjs.com/package/@hussmartinez/ui)'s components, and their focus rings and minimum target sizes are in ui's stylesheet, along with the design tokens, themes and density ([sdk-core ADR 0036](https://github.com/ie-huss-martinez/sdk-core/blob/main/docs/adr/0036-ui-as-a-dependency-of-the-sdks.md)). The SDK's stylesheet never includes it, so a page with several SDKs loads it once. Every value is also a `--hm-pdf-*` property you can set on any ancestor.
26
+
27
+ **One copy of ui and sdk-core.** The SDK depends on `@hussmartinez/ui` `^0.7.0` and `@hussmartinez/sdk-core` `^0.4.4`. If your application uses either itself, depend on the same minor versions, and check that `npm ls @hussmartinez/ui @hussmartinez/sdk-core` lists one version of each: a second copy doesn't share providers with the first, so text falls back to English and announcements are lost.
28
+
29
+ **A bounded height.** `PdfEditor` fills the height of its container, and its viewer and thumbnails scroll within it, so give it a bounded height: a fixed height, or a grid row such as `minmax(0, 1fr)`. The same goes for `PdfViewer` and `PdfThumbnails` used on their own.
30
+
31
+ **Text.** `messages` overrides any text the editor shows, by key, including ui's, such as `"spinner.label"`. The editor builds one set of text from them and your `locale`, for its own components and for ui's ([sdk-core ADR 0046](https://github.com/ie-huss-martinez/sdk-core/blob/main/docs/adr/0046-ui-text-through-the-sdk.md)). `pdfEditorMessages` is the English catalogue, and `MessageOverrides<PdfEditorMessageCatalogue>` types your overrides.
26
32
 
27
33
  `file` opens a document, and a different one replaces it; `null` closes it. Users can also open one with the editor's button or by dropping it on the editor. `onChange` reports each `open`, `edit` and `close`, and the ref's `PdfEditorHandle` exports, undoes, redoes and closes.
28
34
 
35
+ ### Tools, the toolbar and shortcuts
36
+
37
+ The editor's tools are in `pdfTools`:
38
+
39
+ | Tool | Shortcut | What it does |
40
+ |---|---|---|
41
+ | `pdf.open` | none: `Ctrl+O` is the browser's own | Opens a PDF, replacing the current one |
42
+ | `pdf.undo` | `Ctrl+Z`, or `⌘Z` on Apple platforms | Undoes the last edit |
43
+ | `pdf.redo` | `Ctrl+Shift+Z` or `Ctrl+Y`, or `⇧⌘Z` | Redoes the last undone edit |
44
+ | `pdf.rotate-left` | `[` | Turns the selected pages, or the current one, a quarter turn anticlockwise |
45
+ | `pdf.rotate-right` | `]` | Turns them a quarter turn clockwise |
46
+
47
+ Choose which tools are present with `tools`, and arrange the toolbar with `toolbar`, as groups of tool ids; `toolbar={[]}` hides it and keeps the shortcuts. An unknown id throws when the editor renders, so a typo never leaves a tool silently missing. `icons` replaces any icon by name with your own component.
48
+
49
+ ```tsx
50
+ <PdfEditor
51
+ tools={["pdf.undo", "pdf.redo", "pdf.rotate-left", "pdf.rotate-right"]}
52
+ toolbar={[["pdf.undo", "pdf.redo"], ["pdf.rotate-left", "pdf.rotate-right"]]}
53
+ />
54
+ ```
55
+
56
+ Shortcuts work only while focus is inside the editor, never on the rest of your page, and never while typing in a field. The toolbar is one tab stop, with arrow keys between its buttons; each button names its shortcut in `aria-keyshortcuts`. Undoing, redoing and rotating are announced to screen readers.
57
+
58
+ ## Saving a project
59
+
60
+ `toPdfPlanDocument(plan, sources)` writes the session's plan as portable JSON, `hm-pdf-plan` version 1: the pages in order, their rotations and annotations, and form values, with each source's page count. It holds no PDF bytes and no file names, so store the source files alongside it. `readPdfPlanDocument(json)` reads one back, refusing another format or a later version with `UNSUPPORTED_FORMAT`, and anything invalid with `INVALID_DOCUMENT`, each with a stable `details.reason`. The JSON Schemas ship with the package, under `@hussmartinez/pdf-sdk/formats/`, for validating documents elsewhere, such as on a server. [The format record](docs/formats/hm-pdf-plan.md) describes the format, how to load its schemas, and its conformance vectors ([sdk-core ADR 0045](https://github.com/ie-huss-martinez/sdk-core/blob/main/docs/adr/0045-portable-formats-and-conformance-vectors.md)).
61
+
29
62
  ## Assets and Content Security Policy
30
63
 
31
64
  The SDK runs two workers: pdf.js's, which renders, and one with qpdf and pdf-lib, which builds documents. Some documents also need extra data: CMaps for CJK text whose fonts aren't embedded, standard fonts, and decoders for JBIG2 and JPX images, which are common in scanned documents. The SDK never fetches any of them from another origin. Choose one of two modes ([ADR 0002](docs/adr/0002-workers-and-assets.md), [ADR 0006](docs/adr/0006-icc-colour-and-self-hosted-assets.md), [ADR 0007](docs/adr/0007-one-assets-directory.md)):
@@ -41,11 +74,13 @@ The SDK runs two workers: pdf.js's, which renders, and one with qpdf and pdf-lib
41
74
  - **Inline** for the simplest setup. Most documents use RGB or grey and look the same in both modes.
42
75
  - **Self-hosted** if your Content Security Policy doesn't allow `blob:` workers, or if print colour must be accurate, for example for proofs and CMYK artwork.
43
76
 
44
- **In self-hosted mode, copy the whole directory again whenever you upgrade the package.** pdf.js requires its worker to be the same version as the code that uses it, and the processing worker refuses a `qpdf.wasm` from another version, with `WORKER_START_FAILED`.
77
+ **In self-hosted mode, copy the whole directory again whenever you upgrade the package.** A worker left over from another version is refused with `WORKER_START_FAILED`, whose `details` name the file and both versions, `{ asset, expected, actual }`: the processing worker checks the package's version, pdf.js checks its own, and the processing worker also refuses a `qpdf.wasm` from another version.
78
+
79
+ `assetsUrl` can be absolute or relative to the page, such as `/pdf-sdk/`. A relative one is resolved when a worker first starts, in the browser, so `PdfEditor`, `PdfSessionProvider`, `createPdfJsEngine` and `createPdfProcessor` all accept it on a server. A URL with a query or a fragment is refused, because the files resolved from it would lose them: the components throw `TypeError` as they render, and `createPdfJsEngine` and `createPdfProcessor` throw it when you call them.
45
80
 
46
81
  ## Development
47
82
 
48
- The repository root is the published package, laid out as in the family's [standard layout](https://github.com/ie-huss-martinez/sdk-core/blob/main/STANDARDS.md#repository-layout): the source is in [`src`](src), and the examples and end-to-end tests will join the pnpm workspace as `examples/` and `e2e/`.
83
+ The repository root is the published package, laid out as in the family's [standard layout](https://github.com/ie-huss-martinez/sdk-core/blob/main/STANDARDS.md#repository-layout): the source is in [`src`](src), and the pnpm workspace adds the examples in [`examples`](examples) and the end-to-end tests in [`e2e`](e2e) ([sdk-core ADR 0039](https://github.com/ie-huss-martinez/sdk-core/blob/main/docs/adr/0039-test-applications-in-each-repository.md)).
49
84
 
50
85
  You need Node 24 (see [`.node-version`](.node-version)) and pnpm. The exact pnpm version is pinned in `package.json`, and pnpm switches to it automatically.
51
86
 
@@ -55,7 +90,9 @@ pnpm verify # everything CI runs
55
90
  pnpm verify:fast # the subset the pre-push hook runs
56
91
  ```
57
92
 
58
- Browser tests need Playwright's browsers once: `pnpm exec playwright install chromium`, plus `firefox webkit` to run all three engines with `CI=1` or `pnpm test:browser:all`.
93
+ The examples use the built package as an application would: [`examples/next`](examples/next) renders the editor in a Next.js App Router Server Component, and [`examples/vite`](examples/vite) has one page per asset mode, each under the Content Security Policy this README gives for it. The plain HTML example joins them with the standalone script.
94
+
95
+ The browser and end-to-end tests also need Docker. They run in the pinned browser test image from [`ci/Dockerfile`](ci/Dockerfile), as in CI, through `hm-in-image` from `@hussmartinez/sdk-config` ([sdk-core ADR 0049](https://github.com/ie-huss-martinez/sdk-core/blob/main/docs/adr/0049-local-browser-tests-in-the-pinned-image.md)). The first run builds the image and installs the dependencies into its volumes. `pnpm test:browser:all` runs all three engines, as CI does.
59
96
 
60
97
  `pnpm verify` runs, in order:
61
98
 
@@ -67,14 +104,16 @@ Browser tests need Playwright's browsers once: `pnpm exec playwright install chr
67
104
  | Dependency rules | `lint:deps` | dependency-cruiser, through `hm-lint-deps` |
68
105
  | Build | `build` | Vite, then api-extractor for the type declarations |
69
106
  | Unit tests | `test` | Vitest |
70
- | Browser tests | `test:browser` | Vitest in Chromium, and in Firefox and WebKit too in CI |
107
+ | Browser tests | `test:browser` | Vitest in Chromium in the browser test image, and in Firefox and WebKit too in CI |
108
+ | Examples | `build:examples` | Production builds of the Next.js and Vite examples, against the built package |
109
+ | End-to-end tests | `test:e2e` | Playwright in the browser test image, against the examples: server rendering and hydration, axe, no foreign requests, and both asset modes under the Content Security Policies above |
71
110
  | Size budgets | `check:size` | size-limit, brotli size of each entry point |
72
- | API reports | `check:api` | api-extractor, one report per entry point in [`api`](api) |
111
+ | API reports | `check:api` | api-extractor, one report per entry point in [`api`](api), and `hm-check-api-reports` across them |
73
112
  | Package checks | `check:package` | publint and Are the Types Wrong? |
74
113
 
75
114
  The configuration extends the shared presets in [`@hussmartinez/sdk-config`](https://www.npmjs.com/package/@hussmartinez/sdk-config). The git hooks ([ADR 0016](https://github.com/ie-huss-martinez/sdk-core/blob/main/docs/adr/0016-git-hooks-and-merge-guards.md)) run automatically: a secret scan and lint of staged files on commit, a Conventional Commits check of the message, and `pnpm verify:fast` on push.
76
115
 
77
- When a change alters the public API on purpose, update the reports with `pnpm api:update` and commit them. api-extractor rolls up one entry point per run, so the React and element entries' declarations carry copies of the core types their APIs use, such as `PdfSession`. Their reports don't flag those as forgotten exports (`ae-forgotten-export` is off in `api-extractor.react.json` and `api-extractor.element.json`), because the core entry exports every one of them.
116
+ When a change alters the public API on purpose, update the reports with `pnpm api:update` and commit them. api-extractor rolls up one entry point per run, so the React and element entries' declarations carry copies of the core types their APIs use, such as `PdfSession`. Their reports list those copies, and `hm-check-api-reports` from [`@hussmartinez/sdk-config`](https://www.npmjs.com/package/@hussmartinez/sdk-config) then checks that the core entry exports every one of them, and that none is a class with private members, whose copy TypeScript would treat as a different type. All three configurations extend sdk-config's api-extractor preset.
78
117
 
79
118
  ## Contributing
80
119