@hussmartinez/pdf-sdk 0.1.0 → 0.2.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 +40 -5
- package/dist/assets/processing/processing.worker.js +21 -21
- package/dist/index.d.ts +18 -0
- package/dist/index.js +1 -1
- package/dist/lazy/processing-worker-DU8GEYFs.js +30 -0
- package/dist/lazy/{processing-worker-CxoVSxEZ.js.map → processing-worker-DU8GEYFs.js.map} +1 -1
- package/dist/react.d.ts +256 -1
- package/dist/react.js +287 -29
- package/dist/react.js.map +1 -1
- package/dist/shared/{en-B0u26URn.js → en-BYB_GHqG.js} +53 -32
- package/dist/shared/en-BYB_GHqG.js.map +1 -0
- package/dist/styles.css +10 -8
- package/package.json +11 -7
- package/dist/lazy/processing-worker-CxoVSxEZ.js +0 -30
- package/dist/shared/en-B0u26URn.js.map +0 -1
package/README.md
CHANGED
|
@@ -22,10 +22,39 @@ const editor = useRef<PdfEditorHandle>(null);
|
|
|
22
22
|
const bytes = await editor.current?.export();
|
|
23
23
|
```
|
|
24
24
|
|
|
25
|
-
|
|
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
|
+
|
|
29
58
|
## Assets and Content Security Policy
|
|
30
59
|
|
|
31
60
|
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 +70,13 @@ The SDK runs two workers: pdf.js's, which renders, and one with qpdf and pdf-lib
|
|
|
41
70
|
- **Inline** for the simplest setup. Most documents use RGB or grey and look the same in both modes.
|
|
42
71
|
- **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
72
|
|
|
44
|
-
**In self-hosted mode, copy the whole directory again whenever you upgrade the package.**
|
|
73
|
+
**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.
|
|
74
|
+
|
|
75
|
+
`assetsUrl` can be absolute or relative to the page, such as `/pdf-sdk/`. `PdfEditor` and `PdfSessionProvider` render on a server with a relative one: they create their engine and processor only when they're first used, in the browser. 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`, called directly, throw it when you call them, as they do for a relative URL where there's no page to resolve it against.
|
|
45
76
|
|
|
46
77
|
## Development
|
|
47
78
|
|
|
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
|
|
79
|
+
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
80
|
|
|
50
81
|
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
82
|
|
|
@@ -55,6 +86,8 @@ pnpm verify # everything CI runs
|
|
|
55
86
|
pnpm verify:fast # the subset the pre-push hook runs
|
|
56
87
|
```
|
|
57
88
|
|
|
89
|
+
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.
|
|
90
|
+
|
|
58
91
|
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`.
|
|
59
92
|
|
|
60
93
|
`pnpm verify` runs, in order:
|
|
@@ -68,13 +101,15 @@ Browser tests need Playwright's browsers once: `pnpm exec playwright install chr
|
|
|
68
101
|
| Build | `build` | Vite, then api-extractor for the type declarations |
|
|
69
102
|
| Unit tests | `test` | Vitest |
|
|
70
103
|
| Browser tests | `test:browser` | Vitest in Chromium, and in Firefox and WebKit too in CI |
|
|
104
|
+
| Examples | `build:examples` | Production builds of the Next.js and Vite examples, against the built package |
|
|
105
|
+
| End-to-end tests | `test:e2e` | Playwright against the examples: server rendering and hydration, axe, no foreign requests, and both asset modes under the Content Security Policies above |
|
|
71
106
|
| 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) |
|
|
107
|
+
| API reports | `check:api` | api-extractor, one report per entry point in [`api`](api), and `hm-check-api-reports` across them |
|
|
73
108
|
| Package checks | `check:package` | publint and Are the Types Wrong? |
|
|
74
109
|
|
|
75
110
|
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
111
|
|
|
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
|
|
112
|
+
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
113
|
|
|
79
114
|
## Contributing
|
|
80
115
|
|