@paperpic/react 0.2.0 → 0.3.1

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.
@@ -0,0 +1,156 @@
1
+ ---
2
+ title: Send with a form
3
+ description: A complete example where the photo of a receipt goes in a form field, the user edits it in PaperPic, and the form sends the edited image without any code of its own, in plain JavaScript, Vue and React.
4
+ ---
5
+
6
+ # Send with a form
7
+
8
+ Some apps send documents with a plain form, such as an expense with its receipt, and have no code of their own to upload a file. This example keeps the photo in the file field of the form, and puts the edited image back in that field when the user applies the changes, so the form sends it as it would any file.
9
+
10
+ :::tabs key:framework
11
+ == JavaScript
12
+
13
+ ```html
14
+ <form action="/api/expenses" method="post" enctype="multipart/form-data">
15
+ <label>
16
+ Amount
17
+ <input name="amount" type="number" step="0.01" required />
18
+ </label>
19
+ <label>
20
+ Receipt
21
+ <input id="receipt" name="receipt" type="file" accept="image/*" required />
22
+ </label>
23
+ <div id="viewer" style="height: 480px"></div>
24
+ <button type="submit">Send</button>
25
+ </form>
26
+ ```
27
+
28
+ ```ts
29
+ import { PaperPic } from '@paperpic/core'
30
+ import '@paperpic/core/style.css'
31
+
32
+ const input = document.querySelector<HTMLInputElement>('#receipt')!
33
+ const pic = new PaperPic(document.querySelector<HTMLElement>('#viewer')!, {
34
+ alt: 'The receipt you attached',
35
+ maxOutputSize: 3000,
36
+ })
37
+
38
+ input.addEventListener('change', () => {
39
+ const file = input.files?.[0]
40
+ if (file) {
41
+ pic.setOptions({ src: file })
42
+ }
43
+ })
44
+
45
+ // The form sends the edited image in place of the photo
46
+ pic.on('apply', ({ blob, type }) => {
47
+ const name = input.files?.[0]?.name.replace(/\.\w+$/, '') ?? 'receipt'
48
+ const files = new DataTransfer()
49
+ files.items.add(new File([blob], `${name}.${type.split('/')[1]}`, { type }))
50
+ input.files = files.files
51
+ })
52
+ ```
53
+
54
+ == Vue
55
+
56
+ ```vue
57
+ <script setup lang="ts">
58
+ import type { ExportedImage } from '@paperpic/vue'
59
+ import { PaperPic } from '@paperpic/vue'
60
+ import { shallowRef, useTemplateRef } from 'vue'
61
+ import '@paperpic/vue/style.css'
62
+
63
+ const input = useTemplateRef('input')
64
+ const photo = shallowRef<File>()
65
+
66
+ function choose() {
67
+ photo.value = input.value?.files?.[0]
68
+ }
69
+
70
+ // The form sends the edited image in place of the photo
71
+ function applied({ blob, type }: ExportedImage) {
72
+ const field = input.value
73
+ if (!field) {
74
+ return
75
+ }
76
+ const name = field.files?.[0]?.name.replace(/\.\w+$/, '') ?? 'receipt'
77
+ const files = new DataTransfer()
78
+ files.items.add(new File([blob], `${name}.${type.split('/')[1]}`, { type }))
79
+ field.files = files.files
80
+ }
81
+ </script>
82
+
83
+ <template>
84
+ <form action="/api/expenses" method="post" enctype="multipart/form-data">
85
+ <label>
86
+ Amount
87
+ <input name="amount" type="number" step="0.01" required>
88
+ </label>
89
+ <label>
90
+ Receipt
91
+ <input ref="input" name="receipt" type="file" accept="image/*" required @change="choose">
92
+ </label>
93
+ <div v-if="photo" style="height: 480px">
94
+ <PaperPic :src="photo" alt="The receipt you attached" :max-output-size="3000" @apply="applied" />
95
+ </div>
96
+ <button type="submit">
97
+ Send
98
+ </button>
99
+ </form>
100
+ </template>
101
+ ```
102
+
103
+ == React
104
+
105
+ ```tsx
106
+ import type { ExportedImage } from '@paperpic/react'
107
+ import { PaperPic } from '@paperpic/react'
108
+ import { useRef, useState } from 'react'
109
+ import '@paperpic/react/style.css'
110
+
111
+ export function ExpenseForm() {
112
+ const inputRef = useRef<HTMLInputElement>(null)
113
+ const [photo, setPhoto] = useState<File>()
114
+
115
+ // The form sends the edited image in place of the photo
116
+ function applied({ blob, type }: ExportedImage) {
117
+ const input = inputRef.current
118
+ if (!input) {
119
+ return
120
+ }
121
+ const name = input.files?.[0]?.name.replace(/\.\w+$/, '') ?? 'receipt'
122
+ const files = new DataTransfer()
123
+ files.items.add(new File([blob], `${name}.${type.split('/')[1]}`, { type }))
124
+ input.files = files.files
125
+ }
126
+
127
+ return (
128
+ <form action="/api/expenses" method="post" encType="multipart/form-data">
129
+ <label>
130
+ Amount
131
+ <input name="amount" type="number" step="0.01" required />
132
+ </label>
133
+ <label>
134
+ Receipt
135
+ <input ref={inputRef} name="receipt" type="file" accept="image/*" required onChange={event => setPhoto(event.target.files?.[0])} />
136
+ </label>
137
+ {photo && (
138
+ <div style={{ height: 480 }}>
139
+ <PaperPic src={photo} alt="The receipt you attached" maxOutputSize={3000} onApply={applied} />
140
+ </div>
141
+ )}
142
+ <button type="submit">Send</button>
143
+ </form>
144
+ )
145
+ }
146
+ ```
147
+
148
+ :::
149
+
150
+ ## Notes
151
+
152
+ - Apply puts the edited image in the file field with a [`DataTransfer`](https://developer.mozilla.org/docs/Web/API/DataTransfer), so the form sends it under the same name. Before any Apply, the form sends the photo as the user picked it.
153
+ - Changing the files of the field from code does not fire its `change` event, so the viewer keeps the result on display.
154
+ - The file keeps the name of the photo, with the extension of the result, such as `receipt.png` after Clean up.
155
+ - The buttons of the viewer never submit the form.
156
+ - [`maxOutputSize`](../reference/options#maxoutputsize) keeps the form light. Phone photos have 12 megapixels or more, and documents stay readable at 3000 pixels on the longest side.
@@ -127,4 +127,4 @@ export function Invoice() {
127
127
  - `role="status"` makes screen readers announce the result of the upload.
128
128
  - [`maxOutputSize`](../reference/options#maxoutputsize) keeps the file small. Documents stay readable at 3000 pixels on the longest side.
129
129
  - After Apply, the history is empty, so the user cannot undo into the old image. To offer a retry button, keep the last `blob` and `type` and call `upload` again.
130
- - The server receives PNG for a cleaned up document, and the format of the source otherwise. Read [Saving the result](../guide/saving) to choose another one.
130
+ - The server receives PNG for a cleaned up document, and otherwise the format of the source when it is JPEG, PNG or WebP. Read [Saving the result](../guide/saving#format) to learn how PaperPic tells the format, and to choose another one.
@@ -7,16 +7,16 @@ description: How PaperPic works with the keyboard, screen readers and touch scre
7
7
 
8
8
  People read and fix documents with a mouse, a finger, the keyboard or a screen reader. PaperPic aims at WCAG 2.2 AA, and most of the work is built in. This page lists what it does and what your app needs to add.
9
9
 
10
- ## What your app provides
10
+ ## What your app needs to do
11
11
 
12
12
  - **A description.** Pass [`alt`](../reference/options#alt), such as "Receipt from 5 November". Screen readers read it as the name of the image.
13
13
  - **Texts in the user's language.** Screen readers announce the buttons and the changes, so translate them with [`labels`](./labels).
14
14
  - **Your own controls, if any.** With `toolbar: false`, the buttons you build replace the built-in ones, and they need their own names and keyboard support.
15
15
  - **A visible focus.** Keep your CSS from hiding the focus outline of the viewer.
16
16
 
17
- ## Keyboard
17
+ ## Keyboard {#keyboard}
18
18
 
19
- With the focus on the viewer:
19
+ With the focus inside the viewer:
20
20
 
21
21
  | Key | Action |
22
22
  | -------------------------- | ---------------------------------------------------------------------------- |
@@ -28,7 +28,7 @@ With the focus on the viewer:
28
28
  | `Enter` | Confirm the open tool, or else apply the changes |
29
29
  | `Esc` | Let go of a selected corner, close the open tool, or else cancel the changes |
30
30
 
31
- On macOS, `Cmd` works like `Ctrl`. Before cancelling changes, `Esc` asks for confirmation. With `toolbar: false`, it leaves them to your interface.
31
+ On macOS, `Cmd` works like `Ctrl`. With the focus on a button, `Enter` presses that button instead. Before cancelling changes, `Esc` asks for confirmation. With `toolbar: false`, `Esc` still closes a tool, but it does not cancel the edit: your interface decides.
32
32
 
33
33
  - **Toolbar and edit bar.** Tab reaches each bar, and inside it the arrow keys move between the buttons, with `Home` and `End` for the first and the last.
34
34
  - **Corner handles.** With Crop or Straighten open, Tab moves between the handles, and the arrow keys move the focused one 1 screen pixel, or 10 with Shift.
@@ -38,7 +38,7 @@ On macOS, `Cmd` works like `Ctrl`. Before cancelling changes, `Esc` asks for con
38
38
 
39
39
  - The image has the role of an image, named by `alt`. Without `alt`, screen readers skip it.
40
40
  - The toolbar and the edit bar have their own names, such as "Image controls" and "Editing controls".
41
- - An announcement reports each change that the user cannot see by the focus alone: the zoom level, the start of the edit mode, the position of a moved corner, the value of a ruler, and the result of Apply.
41
+ - An announcement reports what the user cannot see by the focus alone: the loading of the image, the zoom level, the start of the edit mode, a selected corner and the position of a moved corner, the value of a ruler, the result of Apply, and any failure.
42
42
  - The switch of Clean up has the role of a switch. A tool in use, which a dot marks on screen, is described as "In use".
43
43
 
44
44
  ## Touch screens
@@ -15,7 +15,7 @@ A photo of a document usually needs a few fixes before it is worth keeping. The
15
15
 
16
16
  Nothing changes the image until Apply. Before that, the edits are a list that the viewer previews.
17
17
 
18
- The edit bar has two rows of the same height in every state: the tools, or the panel of the open tool, above, and below, Cancel at the left and Apply, or Done, at the right. So the image keeps its place when a tool opens. In a viewer at least 28rem wide, the bar fits on one row. A dot marks Adjust and Clean up while their setting is in effect.
18
+ In a narrow viewer, the edit bar has two rows: the tools, or the panel of the open tool, above, and below, Cancel at the left and Apply, or Done, at the right. From 28rem wide, everything fits on one row. Either way, the bar keeps its height when a tool opens, so the image keeps its place. A dot marks Adjust and Clean up while their setting is in effect.
19
19
 
20
20
  ## Tools
21
21
 
@@ -70,7 +70,7 @@ export function Receipt() {
70
70
 
71
71
  :::
72
72
 
73
- Crop, Straighten, Adjust and Clean up open a panel in place of the tools, so the rest of the edit bar waits while one of them is open. Done, or `Enter`, adds what the tool chose to the edits, and Cancel this tool, or `Esc`, discards it.
73
+ Crop, Straighten, Adjust and Clean up open a panel in place of the tools. While one of them is open, the other tools, Undo, Redo and Apply wait. Done, or `Enter`, adds what the tool chose to the edits, and Cancel this tool, or `Esc`, discards it.
74
74
 
75
75
  Inside a panel, the image looks as the result will, Clean up included. Straighten is the exception: it shows the photo without Clean up, so the edges of the paper stay visible.
76
76
 
@@ -82,11 +82,11 @@ Apply cannot be interrupted. It blocks the controls and shows a message while it
82
82
 
83
83
  ## What your code receives
84
84
 
85
- | Event | When |
86
- | -------- | ------------------------------------------------------------------- |
87
- | `apply` | When the result is ready, with `{ blob, width, height, type }` |
88
- | `change` | After each action of the user, with the [state](../reference/state) |
89
- | `error` | When Apply fails, or when the image cannot be loaded |
85
+ | Event | When |
86
+ | -------- | ---------------------------------------------------------------------- |
87
+ | `apply` | When the result is ready, with `{ blob, width, height, type }` |
88
+ | `change` | Each time the user or a method changes the [state](../reference/state) |
89
+ | `error` | When the image cannot be loaded, or an edit cannot be shown or applied |
90
90
 
91
91
  :::tabs key:framework
92
92
  == JavaScript
@@ -121,20 +121,11 @@ pic.on('error', ({ error }) => console.error(error))
121
121
  ## What discards the edits
122
122
 
123
123
  - Cancel, after the user confirms, or [`cancel()`](../reference/methods#cancel), which does not ask.
124
- - A new `src` while editing.
124
+ - A new `src`, or [`reload()`](../reference/methods#reload), while editing.
125
125
  - A change of `editable` while editing.
126
126
 
127
127
  After Apply, passing the same `src` again does nothing, so the result stays on display. [`reload()`](../reference/methods#reload) brings back the original.
128
128
 
129
129
  ## Keyboard
130
130
 
131
- With the focus on the viewer:
132
-
133
- | Key | Action |
134
- | -------------------------- | ------------------------------------------------ |
135
- | `Ctrl+Z` | Undo |
136
- | `Ctrl+Shift+Z` or `Ctrl+Y` | Redo |
137
- | `Enter` | Confirm the open tool, or else apply the changes |
138
- | `Esc` | Close the open tool, or else cancel the changes |
139
-
140
- On macOS, `Cmd` works like `Ctrl`.
131
+ With the focus on the viewer, keys undo, redo, confirm and cancel. [Accessibility](./accessibility#keyboard) lists every key.
@@ -9,31 +9,95 @@ This page takes you from installing PaperPic to showing an image and getting the
9
9
 
10
10
  ## Installation
11
11
 
12
- :::tabs key:framework
12
+ ::::tabs key:framework
13
13
  == JavaScript
14
14
 
15
- ```sh
15
+ ::: code-group
16
+
17
+ ```sh [npm]
18
+ npm install @paperpic/core
19
+ ```
20
+
21
+ ```sh [pnpm]
16
22
  pnpm add @paperpic/core
17
23
  ```
18
24
 
25
+ ```sh [yarn]
26
+ yarn add @paperpic/core
27
+ ```
28
+
29
+ ```sh [bun]
30
+ bun add @paperpic/core
31
+ ```
32
+
33
+ :::
34
+
19
35
  == Vue
20
36
 
21
- ```sh
37
+ ::: code-group
38
+
39
+ ```sh [npm]
40
+ npm install @paperpic/vue
41
+ ```
42
+
43
+ ```sh [pnpm]
22
44
  pnpm add @paperpic/vue
23
45
  ```
24
46
 
47
+ ```sh [yarn]
48
+ yarn add @paperpic/vue
49
+ ```
50
+
51
+ ```sh [bun]
52
+ bun add @paperpic/vue
53
+ ```
54
+
55
+ :::
56
+
25
57
  `@paperpic/vue` requires Vue 3.5 or newer.
26
58
 
27
59
  == React
28
60
 
29
- ```sh
61
+ ::: code-group
62
+
63
+ ```sh [npm]
64
+ npm install @paperpic/react
65
+ ```
66
+
67
+ ```sh [pnpm]
30
68
  pnpm add @paperpic/react
31
69
  ```
32
70
 
33
- `@paperpic/react` requires React 19 or newer.
71
+ ```sh [yarn]
72
+ yarn add @paperpic/react
73
+ ```
74
+
75
+ ```sh [bun]
76
+ bun add @paperpic/react
77
+ ```
34
78
 
35
79
  :::
36
80
 
81
+ `@paperpic/react` requires React 19 or newer.
82
+
83
+ ::::
84
+
85
+ ### Without a bundler {#cdn}
86
+
87
+ The core also loads from a CDN that serves the files of the package as they are, such as jsDelivr. Import `dist/index.js` from a module script, and link `dist/style.css`:
88
+
89
+ ```html
90
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@paperpic/core@0.3/dist/style.css" />
91
+ <div id="viewer" style="height: 480px"></div>
92
+ <script type="module">
93
+ import { PaperPic } from 'https://cdn.jsdelivr.net/npm/@paperpic/core@0.3/dist/index.js'
94
+
95
+ const pic = new PaperPic(document.querySelector('#viewer'), { src: '/receipt.jpg', alt: 'A receipt' })
96
+ </script>
97
+ ```
98
+
99
+ Browsers only start a worker from the origin of the page, so with the package on a CDN the editing runs on the main thread: it works, but large photos freeze the page for a moment on Apply. Serve the files from your own origin, or use a bundler, to keep the worker. The Vue and React components need a bundler.
100
+
37
101
  ## Show an image
38
102
 
39
103
  The viewer fills its container, so give the container a height. Import the stylesheet once in your app.
@@ -87,7 +151,7 @@ export function Receipt() {
87
151
 
88
152
  :::
89
153
 
90
- `src` takes a URL from the same origin as your page, or a `File` that the user picks, such as from an `<input type="file">`. `alt` describes the image for screen readers.
154
+ `src` takes a URL from the same origin as your page, a `File` that the user picks, such as from an `<input type="file">`, or a `Blob`. `alt` describes the image for screen readers. [Loading images](./loading) covers images from other origins, formats and load errors.
91
155
 
92
156
  ## Get the edited image
93
157
 
@@ -124,7 +188,17 @@ async function upload(blob: Blob) {
124
188
  }
125
189
  ```
126
190
 
127
- The `blob` keeps the format of the source, or is PNG when the user cleaned up the document. The [`output`](../reference/options#output) option changes it.
191
+ The `blob` keeps the format of the source when it is JPEG, PNG or WebP, and is PNG when the user cleaned up the document. [Format and quality](./saving#format) explains how PaperPic tells the format, and the [`output`](../reference/options#output) option changes it.
192
+
193
+ ## Remove the viewer {#destroy}
194
+
195
+ The Vue and React components create the viewer when they mount and destroy it when they unmount. With the core, call [`destroy()`](../reference/methods#destroy) when you take the viewer out of the page, such as when the route changes:
196
+
197
+ ```ts
198
+ pic.destroy()
199
+ ```
200
+
201
+ It removes the viewer from its container, stops its listeners and its worker, and frees the memory of the image. To show it again, create a new one.
128
202
 
129
203
  ## Only show the image
130
204
 
@@ -132,13 +206,12 @@ To show a document that people should not change, turn editing off with `editabl
132
206
 
133
207
  ## Requirements
134
208
 
135
- - PaperPic works in the browsers of [Baseline Widely Available](https://web.dev/baseline).
136
- - The editing runs in a Web Worker, which bundlers such as Vite and webpack pick up on their own. If the worker cannot start, the editing runs on the main thread: it still works, but the page can freeze for a moment with large images.
137
- - With a Content Security Policy, allow the worker with `worker-src 'self'`, and allow `img-src blob:`, because the viewer shows attached files and results through `blob:` URLs.
138
- - With server-side rendering, such as in Nuxt or Next.js, the Vue and React components render an empty element on the server and create the viewer in the browser. With the core, create the viewer in the browser yourself.
209
+ PaperPic works in the browsers of [Baseline Widely Available](https://web.dev/baseline). [Performance and support](./performance) covers the worker, Content Security Policy, server-side rendering and large photos.
139
210
 
140
211
  ## Next steps
141
212
 
213
+ - [Loading images](./loading): where the image comes from, and which formats open.
142
214
  - [Viewer](./viewer): zoom, fit and read-only use.
143
215
  - [Editing](./editing): the edit mode, the tools, Undo and Apply.
144
216
  - [Options](../reference/options): everything you can configure.
217
+ - [Troubleshooting](./troubleshooting): when the viewer does not look or work as it should.
@@ -9,7 +9,7 @@ Photos of documents arrive skewed, shadowed and full of background. PaperPic sho
9
9
 
10
10
  ## What it does
11
11
 
12
- - **View.** Zoom with the buttons, the wheel or a pinch, pan, and fit the whole image, its width or its height. A read-only viewer can also rotate the image.
12
+ - **View.** Zoom with the buttons, the wheel, a pinch, a double click or the keyboard, pan, and fit the whole image, its width or its height. A read-only viewer can also rotate the image.
13
13
  - **Edit.** In the edit mode, the user can crop, straighten a photo taken at an angle, rotate, flip, adjust the brightness and the contrast, and clean up the document into black and white. Every edit can be undone until the user applies the changes.
14
14
  - **Deliver.** Apply computes the result at full resolution and hands it to your code as a `Blob`. A download button can also save it.
15
15
 
@@ -71,7 +71,7 @@ const labels: Partial<PaperPicLabels> = {
71
71
 
72
72
  ## Follow the language of your app
73
73
 
74
- When your app changes language, pass new labels, and the viewer updates its texts at once. Build the object only when the language changes, so the viewer does not receive a new one on every render:
74
+ When your app changes language, pass the labels of the new language, and the viewer updates its texts at once. Keep one object of labels for each language, created once, so that each render passes the same object:
75
75
 
76
76
  :::tabs key:framework
77
77
  == JavaScript
@@ -103,11 +103,9 @@ const labels = computed(() => translations[locale.value])
103
103
 
104
104
  ```tsx
105
105
  import { PaperPic } from '@paperpic/react'
106
- import { useMemo } from 'react'
107
106
 
108
107
  export function Receipt({ language }: { language: string }) {
109
- const labels = useMemo(() => translations[language], [language])
110
- return <PaperPic src="/receipt.jpg" labels={labels} />
108
+ return <PaperPic src="/receipt.jpg" labels={translations[language]} />
111
109
  }
112
110
  ```
113
111
 
@@ -0,0 +1,130 @@
1
+ ---
2
+ title: Loading images
3
+ description: How to give PaperPic an image, from a URL, a file the user picks or a Blob you fetch, which formats it opens, and how your code learns that the image loaded or failed.
4
+ ---
5
+
6
+ # Loading images
7
+
8
+ PaperPic shows the image that you pass in `src`. This page covers where that image can come from, which formats open, and how your code learns that the image is ready or that it failed.
9
+
10
+ ## Where the image comes from
11
+
12
+ `src` takes one of three things:
13
+
14
+ - **A URL from the same origin as your page**, such as `/documents/42.jpg`.
15
+ - **A `File`** that the user picks with `<input type="file">`. [Attach and scan](../examples/attach-and-scan) shows the whole flow, from the camera to the upload.
16
+ - **A `Blob`** that your code holds, such as the body of a response.
17
+
18
+ For a `File` or a `Blob`, PaperPic creates the `blob:` URL it needs, and frees it when the image changes or the viewer is destroyed.
19
+
20
+ ## Images from another origin, or behind a login {#fetch}
21
+
22
+ PaperPic reads the pixels of the image to edit it. Browsers only allow that for an image from another origin when it arrives with CORS, which PaperPic does not request. Such an image shows, but editing it fails: an [`error`](../reference/events#error) says so as soon as an edit needs its pixels, or on Apply.
23
+
24
+ Fetch the image yourself, and pass the `Blob` as `src`. This also covers images behind a login, because your request carries the cookies of the user:
25
+
26
+ ```ts
27
+ async function fetchImage(url: string): Promise<Blob> {
28
+ const response = await fetch(url, { credentials: 'include' })
29
+ if (!response.ok) {
30
+ throw new Error(`The image could not be fetched: status ${response.status}`)
31
+ }
32
+ return response.blob()
33
+ }
34
+ ```
35
+
36
+ The other server must allow your origin with CORS, as for any `fetch` from the page.
37
+
38
+ ## Formats {#formats}
39
+
40
+ PaperPic opens every format that the browser shows in an `<img>`:
41
+
42
+ - **JPEG, PNG, WebP and AVIF** open in every [supported browser](./performance#browser-support).
43
+ - **SVG** opens when the file has `width` and `height` attributes. Without them, it has no size, and the load fails.
44
+ - **HEIC**, the format of iPhone photos, only opens in Safari. When an iPhone user picks a photo with `<input type="file" accept="image/*">`, iOS usually hands the page a JPEG copy. A HEIC file that reaches another browser in another way fails to load.
45
+
46
+ Phones often save a photo sideways, with an EXIF tag that says how to turn it. PaperPic shows the photo the way the tag says, as an `<img>` does, and the result of Apply comes out upright.
47
+
48
+ ## Know when it loads or fails
49
+
50
+ The [`load`](../reference/events#load) event reports that the image is on display, with its size. If the image cannot load, because it is missing, it is not an image or the browser cannot decode it, the viewer shows a message, and the [`error`](../reference/events#error) event carries `phase: 'load'`:
51
+
52
+ :::tabs key:framework
53
+ == JavaScript
54
+
55
+ ```ts
56
+ import { PaperPic } from '@paperpic/core'
57
+
58
+ const pic = new PaperPic(container, { src: '/documents/42.jpg', alt: 'Invoice 42' })
59
+
60
+ pic.on('load', ({ width, height }) => {
61
+ console.log(`The image is ${width}×${height} pixels`)
62
+ })
63
+ pic.on('error', ({ error, phase }) => {
64
+ if (phase === 'load') {
65
+ console.error(error.message)
66
+ }
67
+ })
68
+ ```
69
+
70
+ == Vue
71
+
72
+ ```vue
73
+ <script setup lang="ts">
74
+ import type { PaperPicEvents } from '@paperpic/vue'
75
+ import { PaperPic } from '@paperpic/vue'
76
+
77
+ function loaded({ width, height }: PaperPicEvents['load']) {
78
+ console.log(`The image is ${width}×${height} pixels`)
79
+ }
80
+
81
+ function failed({ error, phase }: PaperPicEvents['error']) {
82
+ if (phase === 'load') {
83
+ console.error(error.message)
84
+ }
85
+ }
86
+ </script>
87
+
88
+ <template>
89
+ <div style="height: 480px">
90
+ <PaperPic src="/documents/42.jpg" alt="Invoice 42" @load="loaded" @error="failed" />
91
+ </div>
92
+ </template>
93
+ ```
94
+
95
+ == React
96
+
97
+ ```tsx
98
+ import type { PaperPicEvents } from '@paperpic/react'
99
+ import { PaperPic } from '@paperpic/react'
100
+
101
+ function loaded({ width, height }: PaperPicEvents['load']) {
102
+ console.log(`The image is ${width}×${height} pixels`)
103
+ }
104
+
105
+ function failed({ error, phase }: PaperPicEvents['error']) {
106
+ if (phase === 'load') {
107
+ console.error(error.message)
108
+ }
109
+ }
110
+
111
+ export function Invoice() {
112
+ return (
113
+ <div style={{ height: 480 }}>
114
+ <PaperPic src="/documents/42.jpg" alt="Invoice 42" onLoad={loaded} onError={failed} />
115
+ </div>
116
+ )
117
+ }
118
+ ```
119
+
120
+ :::
121
+
122
+ `load` fires each time a `src` loads, also with [`reload()`](../reference/methods#reload), but not after Apply: the result arrives with the [`apply`](../reference/events#apply) event.
123
+
124
+ The `status` of [`getState()`](../reference/state) gives the same answer at any time: `'empty'`, `'loading'`, `'ready'` or `'error'`.
125
+
126
+ ## Change or reload the image
127
+
128
+ - **A new `src`** loads the new image. While the user is editing, it discards the edits.
129
+ - **The same `src`** does nothing, so the result of Apply stays on display.
130
+ - **[`reload()`](../reference/methods#reload)** loads the current `src` again, which brings back the original after an Apply. While the user is editing, it discards the edits too.
@@ -9,7 +9,7 @@ Phone photos have 12 megapixels or more, and editing them takes real work. This
9
9
 
10
10
  ## A Web Worker does the work
11
11
 
12
- Clean up and Straighten take more than a second on a 12-megapixel photo on a phone. On the main thread, the page would freeze for that long. PaperPic runs them in a Web Worker instead, so the page keeps responding while Apply runs.
12
+ Clean up and Straighten take about a second and a half on a 12-megapixel photo on a recent phone, as the [measured times](#measurements) show. On the main thread, the page would freeze for that long. PaperPic runs them in a Web Worker instead, so the page keeps responding while Apply runs.
13
13
 
14
14
  The worker ships inside the package and starts with the standard `new Worker(new URL(…, import.meta.url))`, which bundlers such as Vite and webpack 5 pick up on their own, with no configuration. If the worker cannot start, the editing runs on the main thread: it still works, but the page can freeze for a moment with large images.
15
15
 
@@ -19,6 +19,8 @@ With a Content Security Policy, allow:
19
19
 
20
20
  - `worker-src 'self'`, for the worker.
21
21
  - `img-src blob:`, because the viewer shows attached files and the results of Apply through `blob:` URLs.
22
+ - `paperpic` in `trusted-types`, if your policy restricts Trusted Types policies, because the icons of the buttons go through that policy.
23
+ - A `default` Trusted Types policy whose `createScriptURL` accepts the URL of the worker, if your policy requires Trusted Types. Bundlers only pick up a worker created from a plain URL, which Trusted Types block, so without that policy the editing runs on the main thread.
22
24
 
23
25
  ## Large photos
24
26
 
@@ -26,9 +28,21 @@ With a Content Security Policy, allow:
26
28
  - **On Apply**, every edit runs at full resolution. Large photos take a few seconds, so the viewer shows a message and blocks the controls meanwhile.
27
29
  - **To save time and memory**, set [`maxOutputSize`](../reference/options#maxoutputsize). A limit such as 2000 or 3000 pixels keeps documents readable, and makes Apply faster and the files smaller.
28
30
 
29
- ## Images it accepts
31
+ ## Measured times {#measurements}
30
32
 
31
- `src` takes a URL from the same origin as your page, or a `File` or `Blob` attached on the client. PaperPic reads the pixels of the image, and browsers only allow that for images from other origins under CORS, which PaperPic does not request. Serve the images from your own domain, or fetch them yourself and pass the `Blob`.
33
+ Each step of Apply, in the worker, on a Pixel 10 Pro with Chrome 156:
34
+
35
+ | Step | 2 MP | 12 MP | 37.5 MP |
36
+ | --------------------------- | ------ | ------ | ------- |
37
+ | Clean up | 256 ms | 1.5 s | 4.8 s |
38
+ | Straighten | 251 ms | 1.6 s | 5.0 s |
39
+ | Export to PNG | 92 ms | 378 ms | 979 ms |
40
+ | Export to JPEG, quality 0.9 | 33 ms | 142 ms | 525 ms |
41
+
42
+ - A move of the ruler of Clean up takes about 40 ms on the same phone, because it works on the preview of about 2 MP.
43
+ - A desktop computer with 8 cores does each step about six times faster.
44
+ - At 37.5 MP, Clean up needs about 340 MB of memory at its peak.
45
+ - Mid-range Android phones and iPhones are not measured yet.
32
46
 
33
47
  ## Server-side rendering
34
48