@paperpic/core 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.
Files changed (37) hide show
  1. package/dist/docs/examples/attach-and-scan.md +202 -0
  2. package/dist/docs/examples/custom-toolbar.md +196 -2
  3. package/dist/docs/examples/dialog.md +191 -0
  4. package/dist/docs/examples/fixed-proportions.md +1 -0
  5. package/dist/docs/examples/form.md +156 -0
  6. package/dist/docs/examples/upload.md +1 -1
  7. package/dist/docs/guide/accessibility.md +5 -5
  8. package/dist/docs/guide/editing.md +9 -18
  9. package/dist/docs/guide/getting-started.md +84 -11
  10. package/dist/docs/guide/introduction.md +1 -1
  11. package/dist/docs/guide/labels.md +2 -4
  12. package/dist/docs/guide/loading.md +130 -0
  13. package/dist/docs/guide/performance.md +17 -3
  14. package/dist/docs/guide/saving.md +17 -9
  15. package/dist/docs/guide/styling.md +2 -0
  16. package/dist/docs/guide/tools/adjust.md +4 -2
  17. package/dist/docs/guide/tools/clean-up.md +1 -1
  18. package/dist/docs/guide/tools/crop.md +3 -1
  19. package/dist/docs/guide/tools/rotate-and-flip.md +3 -1
  20. package/dist/docs/guide/tools/straighten.md +1 -1
  21. package/dist/docs/guide/troubleshooting.md +45 -0
  22. package/dist/docs/guide/viewer.md +12 -10
  23. package/dist/docs/reference/events.md +20 -7
  24. package/dist/docs/reference/labels.md +2 -2
  25. package/dist/docs/reference/methods.md +71 -15
  26. package/dist/docs/reference/options.md +9 -9
  27. package/dist/docs/reference/react.md +8 -4
  28. package/dist/docs/reference/state.md +113 -19
  29. package/dist/docs/reference/types.md +2 -2
  30. package/dist/docs/reference/vue.md +8 -6
  31. package/dist/index.d.ts +75 -50
  32. package/dist/index.js +1469 -1350
  33. package/dist/{pipeline-MP1RPlXT.js → steps-DuGiMvk0.js} +236 -75
  34. package/dist/types-C3ZHKId1.d.ts +31 -0
  35. package/dist/worker.d.ts +13 -61
  36. package/dist/worker.js +3 -10
  37. package/package.json +2 -2
@@ -36,7 +36,7 @@ Every [option](./options) is a prop with the same name, such as `editable={false
36
36
  | `className` | `string` | Classes on top of `paperpic-host` |
37
37
  | `style` | `CSSProperties` | Inline styles |
38
38
 
39
- Objects and arrays, such as `labels` or `tools`, reach the viewer again whenever they are new. Define them outside the component, or with `useMemo`.
39
+ An object or array with the same contents as before, such as `tools={['crop', 'rotate']}`, changes nothing, so inline values are fine. A function is new on every render, so define the functions of `labels`, such as `zoomLevel`, outside the component, or build those labels with `useMemo`.
40
40
 
41
41
  ## Events
42
42
 
@@ -45,14 +45,16 @@ Objects and arrays, such as `labels` or `tools`, reach the viewer again whenever
45
45
  | `onApply` | [`ExportedImage`](./types#exportedimage) |
46
46
  | `onChange` | [`PaperPicState`](./state) |
47
47
  | `onDownload` | [`PaperPicDownload`](./types#paperpicdownload) |
48
- | `onError` | `{ error }` |
48
+ | `onError` | `{ error, phase }` |
49
49
  | `onLoad` | [`Size`](./types#size) |
50
50
 
51
51
  [Events](./events) describes each one. A new function does not recreate the viewer, so inline functions are fine. A change of props never calls `onChange`.
52
52
 
53
- ## Methods
53
+ `onChange` receives the [state](./state) of the viewer, not a DOM event. [State](./state#in-step) shows how to keep it with `useState`, `onChange`, `onLoad` and `onError`.
54
54
 
55
- `ref` receives the viewer, of type [`PaperPicInstance`](./types#paperpicinstance), with every [method](./methods). It is `null` until the component mounts:
55
+ ## Methods {#methods}
56
+
57
+ `ref` receives the viewer, of type [`PaperPicInstance`](./types#paperpicinstance), with the [methods](./methods), such as `zoomIn()` or `apply()`. It is `null` until the component mounts:
56
58
 
57
59
  ```tsx
58
60
  import type { PaperPicInstance } from '@paperpic/react'
@@ -73,6 +75,8 @@ export function Viewer({ src }: { src: string }) {
73
75
  }
74
76
  ```
75
77
 
78
+ The component creates the viewer when it mounts and destroys it when it unmounts, so do not call `destroy()`. Change the props instead of calling `setOptions()`, which the next change of a prop would undo, and use the callback props instead of `on()`.
79
+
76
80
  Passing the same `src` again does not reload the image, so it keeps the result of an edit. To bring back the original, call `picRef.current.reload()`.
77
81
 
78
82
  ## Types {#types}
@@ -1,30 +1,124 @@
1
1
  ---
2
2
  title: State
3
- description: What getState() returns and the change event carries, such as the status of the image, the mode, the zoom, the edits and whether there is something to apply.
3
+ description: What getState() returns and the change event carries, such as the status of the image, the mode, the zoom, the edits and whether there is something to apply, and how to keep controls of your own in step with it.
4
4
  ---
5
5
 
6
6
  # State
7
7
 
8
- The state describes what the viewer shows at a given moment. [`getState()`](./methods#getstate) returns it, and the [`change`](./events#change) event carries it. Use it to keep controls of your own in step, such as an Apply button:
8
+ The state is a snapshot of the viewer: whether there is an image, the mode, the zoom, the open tool and whether there are changes to apply. You get it in two ways, and both give the same [`PaperPicState`](./types#paperpicstate) object:
9
+
10
+ - [`getState()`](./methods#getstate) returns it whenever you ask.
11
+ - The [`change`](./events#change) event sends it each time the user or a method changes it.
12
+
13
+ ## Keeping controls in step {#in-step}
14
+
15
+ `change` does not report the image. A loaded image comes with [`load`](./events#load), and a load or an Apply that fails comes with [`error`](./events#error). To keep controls of your own in step, such as an Apply button, read the state at the start, take it from each `change`, and read it again on `load` and `error`:
16
+
17
+ :::tabs key:framework
18
+ == JavaScript
9
19
 
10
20
  ```ts
11
- pic.on('change', ({ canApply, busy }) => {
21
+ import type { PaperPicState } from '@paperpic/core'
22
+ import { PaperPic } from '@paperpic/core'
23
+ import '@paperpic/core/style.css'
24
+
25
+ const applyButton = document.querySelector<HTMLButtonElement>('#apply')!
26
+ const pic = new PaperPic(container, { src: '/receipt.jpg', toolbar: false })
27
+
28
+ function update({ canApply, busy }: PaperPicState) {
12
29
  applyButton.disabled = !canApply || busy
13
- })
30
+ }
31
+
32
+ update(pic.getState())
33
+ pic.on('change', update)
34
+ pic.on('load', () => update(pic.getState()))
35
+ pic.on('error', () => update(pic.getState()))
36
+ applyButton.addEventListener('click', () => pic.apply())
14
37
  ```
15
38
 
16
- | Field | Type | Description |
17
- | ------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
18
- | `activeTool` | [`ToolId \| null`](./types#toolid) | The open tool, such as `'crop'` or `'adjust'`, or `null` |
19
- | `adjustments` | `{ brightness, contrast }` | The brightness and the contrast, each from -1 to 1. Clean up leaves them out. While Adjust is open, the values it shows |
20
- | `busy` | `boolean` | Whether Apply is running |
21
- | `canApply` | `boolean` | Whether there are changes to apply. Rotations and flips that cancel out are no change |
22
- | `canRedo` | `boolean` | Whether there is an edit to bring back |
23
- | `canUndo` | `boolean` | Whether there is an edit to undo |
24
- | `fit` | [`Fit \| null`](./types#fit) | The fit in effect, or `null` once the user has zoomed by hand |
25
- | `image` | [`Size \| null`](./types#size) | The size of the image on display in pixels, with the edits so far, or `null` without an image |
26
- | `mode` | `'view' \| 'edit'` | Whether the user is viewing or editing the image |
27
- | `rotation` | [`Rotation`](./types#rotation) | How far the image on display is turned, in degrees clockwise |
28
- | `status` | `'empty' \| 'loading' \| 'ready' \| 'error'` | Whether there is an image, and whether it loaded |
29
- | `threshold` | `{ enabled, sensitivity }` | Whether Clean up is on, and its sensitivity from 0 to 1. While Clean up is open, what it shows |
30
- | `zoom` | `number` | Screen pixels per pixel of the image |
39
+ == Vue
40
+
41
+ ```vue
42
+ <script setup lang="ts">
43
+ import type { PaperPicState } from '@paperpic/vue'
44
+ import { PaperPic } from '@paperpic/vue'
45
+ import { shallowRef, useTemplateRef } from 'vue'
46
+ import '@paperpic/vue/style.css'
47
+
48
+ const pic = useTemplateRef('pic')
49
+ const state = shallowRef<PaperPicState>()
50
+
51
+ function refresh() {
52
+ state.value = pic.value?.instance?.getState()
53
+ }
54
+ </script>
55
+
56
+ <template>
57
+ <button type="button" :disabled="!state || !state.canApply || state.busy" @click="pic?.instance?.apply()">
58
+ Apply
59
+ </button>
60
+ <div style="height: 480px">
61
+ <PaperPic
62
+ ref="pic"
63
+ src="/receipt.jpg"
64
+ :toolbar="false"
65
+ @change="next => (state = next)"
66
+ @load="refresh"
67
+ @error="refresh"
68
+ />
69
+ </div>
70
+ </template>
71
+ ```
72
+
73
+ == React
74
+
75
+ ```tsx
76
+ import type { PaperPicInstance, PaperPicState } from '@paperpic/react'
77
+ import { PaperPic } from '@paperpic/react'
78
+ import { useRef, useState } from 'react'
79
+ import '@paperpic/react/style.css'
80
+
81
+ export function Receipt() {
82
+ const picRef = useRef<PaperPicInstance>(null)
83
+ const [state, setState] = useState<PaperPicState>()
84
+
85
+ function refresh() {
86
+ setState(picRef.current?.getState())
87
+ }
88
+
89
+ return (
90
+ <>
91
+ <button type="button" disabled={!state || !state.canApply || state.busy} onClick={() => picRef.current?.apply()}>
92
+ Apply
93
+ </button>
94
+ <div style={{ height: 480 }}>
95
+ <PaperPic ref={picRef} src="/receipt.jpg" toolbar={false} onChange={setState} onLoad={refresh} onError={refresh} />
96
+ </div>
97
+ </>
98
+ )
99
+ }
100
+ ```
101
+
102
+ :::
103
+
104
+ In Vue and React the viewer exists only once the component mounts, so the state starts as `undefined` and arrives with the first `load` or `error`. Until then, there is nothing to apply.
105
+
106
+ ## Fields
107
+
108
+ | Field | Type | Description |
109
+ | ------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
110
+ | `activeTool` | [`ToolId \| null`](./types#toolid) | The open tool, such as `'crop'` or `'adjust'`, or `null` |
111
+ | `adjustments` | `{ brightness, contrast }` | The brightness and the contrast, each from -1 to 1. They do not apply while Clean up is on. While Adjust is open, they are the values on its panel |
112
+ | `busy` | `boolean` | Whether Apply is running |
113
+ | `canApply` | `boolean` | Whether there are changes to apply. Rotations and flips that cancel out are no change |
114
+ | `canRedo` | `boolean` | Whether there is an edit to bring back |
115
+ | `canUndo` | `boolean` | Whether there is an edit to undo |
116
+ | `fit` | [`Fit \| null`](./types#fit) | The fit in effect, or `null` once the user has zoomed by hand |
117
+ | `image` | [`Size \| null`](./types#size) | The size of the image in pixels, at full resolution and with the edits so far, but without the turn of `rotation`, or `null` without an image |
118
+ | `mode` | `'view' \| 'edit'` | Whether the user is viewing or editing the image |
119
+ | `rotation` | [`Rotation`](./types#rotation) | How far the image on display is turned from `image`, in degrees clockwise |
120
+ | `status` | `'empty' \| 'loading' \| 'ready' \| 'error'` | `'empty'` without `src`, `'loading'` while it loads, `'ready'` once it is on display, and `'error'` if it could not be loaded |
121
+ | `threshold` | `{ enabled, sensitivity }` | Whether Clean up is on, and its sensitivity from 0 to 1. While Clean up is open, they are the values on its panel |
122
+ | `zoom` | `number` | Screen pixels per pixel of the image |
123
+
124
+ With a `rotation` of 90 or 270, the image on screen, and the result of Apply, have the width and the height of `image` swapped. [`maxOutputSize`](./options#maxoutputsize) can make the result smaller.
@@ -61,7 +61,7 @@ What the constructor and [`setOptions()`](./methods#setoptions) take. In Vue and
61
61
  type PaperPicSource = string | Blob
62
62
  ```
63
63
 
64
- The image in [`src`](./options#src): a URL from the same origin, or a `File` or `Blob` attached on the client. The `source` of [`PaperPicDownload`](#paperpicdownload) has the same type.
64
+ The image in [`src`](./options#src): a URL, or a `File` or a `Blob`. The `source` of [`PaperPicDownload`](#paperpicdownload) has the same type.
65
65
 
66
66
  ### `PaperPicOutput`
67
67
 
@@ -226,7 +226,7 @@ interface PaperPicEvents {
226
226
  apply: ExportedImage
227
227
  change: PaperPicState
228
228
  download: PaperPicDownload
229
- error: { error: Error }
229
+ error: { error: Error, phase: 'load' | 'preview' | 'apply' }
230
230
  load: Size
231
231
  }
232
232
  ```
@@ -29,9 +29,9 @@ The component fills its parent element, so give the parent a height.
29
29
 
30
30
  ## Props
31
31
 
32
- Every [option](./options) is a prop with the same name, such as `:editable="false"` or `:aspect-ratio="210 / 297"`. A change of a prop reaches the viewer through `setOptions()`.
32
+ Every [option](./options) is a prop with the same name, such as `:editable="false"` or `:aspect-ratio="210 / 297"`. A change of a prop reaches the viewer through `setOptions()`. `class` and `style` go to the element that holds the viewer, which also has the class `paperpic-host`.
33
33
 
34
- Objects and arrays that the template builds, such as `:labels="{ apply: t('apply') }"`, are new on every render of the parent, and the viewer receives them again each time. Build them with `computed` instead.
34
+ An object or array with the same contents as before, such as `:tools="['crop', 'rotate']"`, changes nothing, so the template can build them. A function is new on every render of the parent, so build `labels` that hold functions, such as `zoomLevel`, with `computed`.
35
35
 
36
36
  ## Events
37
37
 
@@ -40,14 +40,14 @@ Objects and arrays that the template builds, such as `:labels="{ apply: t('apply
40
40
  | `apply` | [`ExportedImage`](./types#exportedimage) |
41
41
  | `change` | [`PaperPicState`](./state) |
42
42
  | `download` | [`PaperPicDownload`](./types#paperpicdownload) |
43
- | `error` | `{ error }` |
43
+ | `error` | `{ error, phase }` |
44
44
  | `load` | [`Size`](./types#size) |
45
45
 
46
- [Events](./events) describes each one. A change of a prop never emits `change`.
46
+ [Events](./events) describes each one. A change of a prop never emits `change`. [State](./state#in-step) shows how to keep the state in a `shallowRef` with `@change`, `@load` and `@error`.
47
47
 
48
- ## Methods
48
+ ## Methods {#methods}
49
49
 
50
- The component exposes the viewer as `instance`, with every [method](./methods). It is `null` until the component mounts:
50
+ The component exposes the viewer as `instance`, with the [methods](./methods), such as `zoomIn()` or `apply()`. It is `null` until the component mounts:
51
51
 
52
52
  ```vue
53
53
  <script setup lang="ts">
@@ -67,6 +67,8 @@ const pic = useTemplateRef('pic')
67
67
  </template>
68
68
  ```
69
69
 
70
+ The component creates the viewer when it mounts and destroys it when it unmounts, so do not call `destroy()`. Change the props instead of calling `setOptions()`, which the next change of a prop would undo, and use the component events instead of `on()`.
71
+
70
72
  Passing the same `src` again does not reload the image, so it keeps the result of an edit. To bring back the original, call `instance.reload()`.
71
73
 
72
74
  ## Types {#types}
package/dist/index.d.ts CHANGED
@@ -1,9 +1,4 @@
1
- /**
2
- * How far the image is turned, in degrees clockwise.
3
- *
4
- * @see https://paperpic.dev/reference/state
5
- */
6
- type Rotation = 0 | 90 | 180 | 270;
1
+ import { i as Size } from "./types-C3ZHKId1.js";
7
2
  /**
8
3
  * The format of the image that editing produces.
9
4
  *
@@ -31,14 +26,17 @@ interface ExportedImage {
31
26
  width: number;
32
27
  }
33
28
  /**
34
- * A width and a height in pixels.
29
+ * The image to show: a URL from the same origin, or a file attached on the client.
35
30
  *
36
- * @see https://paperpic.dev/reference/types#size
31
+ * @see https://paperpic.dev/reference/options#src
37
32
  */
38
- interface Size {
39
- height: number;
40
- width: number;
41
- }
33
+ type PaperPicSource = string | Blob;
34
+ /**
35
+ * How far the image is turned, in degrees clockwise.
36
+ *
37
+ * @see https://paperpic.dev/reference/state
38
+ */
39
+ type Rotation = 0 | 90 | 180 | 270;
42
40
  /**
43
41
  * A position in CSS pixels, relative to the top left corner of the viewer.
44
42
  *
@@ -62,7 +60,7 @@ type Fit = 'image' | 'width' | 'height';
62
60
  interface PaperPicLabels {
63
61
  /** Opens the ruler of brightness and contrast. */
64
62
  adjust: string;
65
- /** Announced after changing a slider of brightness or contrast, with its name and its value from -100 to 100. */
63
+ /** Announced after moving the ruler of Adjust, with the name of the tone and its value from -100 to 100. */
66
64
  adjustmentLevel: (name: string, value: number) => string;
67
65
  /** Announced when the changes are applied. */
68
66
  applied: string;
@@ -118,7 +116,7 @@ interface PaperPicLabels {
118
116
  rotateRight: string;
119
117
  /** Opens Clean up, and names its switch. */
120
118
  threshold: string;
121
- /** Announced after changing the ruler of Clean up. */
119
+ /** Announced after moving the ruler of Clean up, with its value in percent. */
122
120
  thresholdLevel: (percent: number) => string;
123
121
  /** Name of the ruler of Clean up. */
124
122
  thresholdSensitivity: string;
@@ -176,12 +174,6 @@ interface PaperPicIcons {
176
174
  zoomIn: string;
177
175
  zoomOut: string;
178
176
  }
179
- /**
180
- * The image to show: a URL from the same origin, or a file attached on the client.
181
- *
182
- * @see https://paperpic.dev/reference/options#src
183
- */
184
- type PaperPicSource = string | Blob;
185
177
  /**
186
178
  * What the constructor and `setOptions()` take.
187
179
  *
@@ -221,11 +213,24 @@ interface PaperPicOptions {
221
213
  src?: PaperPicSource;
222
214
  /** Whether to show the built-in toolbar and edit bar. Without them, build your own with the public methods. */
223
215
  toolbar?: boolean;
224
- /** Which tools the edit bar offers. By default, all of them. */
216
+ /** Which tools the edit bar offers. By default, all of them. It only chooses the buttons: the methods work with every tool. */
225
217
  tools?: readonly ToolId[];
226
218
  /** Whether the wheel zooms. Turn it off when the viewer sits in a long page. */
227
219
  wheelZoom?: boolean;
228
220
  }
221
+ /**
222
+ * What the `download` event carries.
223
+ *
224
+ * @see https://paperpic.dev/reference/events#download
225
+ */
226
+ interface PaperPicDownload {
227
+ /** The name of the file, with the extension of its format. */
228
+ filename: string;
229
+ /** Stops the browser from saving the file, so you can save it another way. */
230
+ preventDefault: () => void;
231
+ /** The image to save: the result of the last Apply, or else the `src`. */
232
+ source: PaperPicSource;
233
+ }
229
234
  /**
230
235
  * What the viewer is showing, which `getState()` returns and the `change` event carries.
231
236
  *
@@ -244,7 +249,7 @@ interface PaperPicState {
244
249
  };
245
250
  /** Whether the changes are being applied. */
246
251
  busy: boolean;
247
- /** Whether there are changes to apply. Rotations that cancel out are no change. */
252
+ /** Whether there are changes to apply. Rotations and flips that cancel out are no change. */
248
253
  canApply: boolean;
249
254
  /** Whether there is an edit to bring back. */
250
255
  canRedo: boolean;
@@ -252,11 +257,14 @@ interface PaperPicState {
252
257
  canUndo: boolean;
253
258
  /** The fit in effect, or `null` once the user has zoomed by hand. */
254
259
  fit: Fit | null;
255
- /** The size of the image on display in pixels, with the edits so far, or `null` if there is none. */
260
+ /**
261
+ * The size of the image in pixels, at full resolution and with the edits so far, but without the turn of `rotation`,
262
+ * or `null` if there is none.
263
+ */
256
264
  image: Size | null;
257
265
  /** Whether the user is viewing or editing the image. */
258
266
  mode: 'view' | 'edit';
259
- /** How far the image on display is turned, in degrees clockwise. */
267
+ /** How far the image on display is turned from `image`, in degrees clockwise. */
260
268
  rotation: Rotation;
261
269
  /** Whether there is an image, and whether it loaded. */
262
270
  status: 'empty' | 'loading' | 'ready' | 'error';
@@ -274,17 +282,24 @@ interface PaperPicState {
274
282
  * @see https://paperpic.dev/reference/events
275
283
  */
276
284
  interface PaperPicEvents {
277
- /** The user applied the changes. The result is already on display. */
285
+ /** Apply finished, from the button, `Enter` or `apply()`. The result is already on display. */
278
286
  apply: ExportedImage;
279
- /** The user changed the view or the edit. `setOptions()` never triggers it. */
287
+ /**
288
+ * The user or a method changed the state, such as the zoom or the edit. A loaded image comes with `load`, and a failed
289
+ * Apply with `error`, instead. A pan, `setOptions()` and the props of the components never trigger it.
290
+ */
280
291
  change: PaperPicState;
281
292
  /** The image is about to be saved. Call `preventDefault()` to save it another way. */
282
293
  download: PaperPicDownload;
283
- /** The image could not be loaded, or the changes could not be applied. */
294
+ /**
295
+ * Something failed. `phase` says what: `'load'` for the image, `'preview'` for the pixels of an edit on display,
296
+ * which leaves the edit open, and `'apply'` for the changes.
297
+ */
284
298
  error: {
285
299
  error: Error;
300
+ phase: 'load' | 'preview' | 'apply';
286
301
  };
287
- /** The image is ready. */
302
+ /** The image of `src` is ready, also after `reload()`. Apply does not trigger it. */
288
303
  load: Size;
289
304
  }
290
305
  type Listener<Name extends keyof PaperPicEvents> = (payload: PaperPicEvents[Name]) => void;
@@ -308,6 +323,7 @@ export declare class PaperPic {
308
323
  private readonly toolbar;
309
324
  private readonly editBar;
310
325
  private readonly renderer;
326
+ private readonly gestures;
311
327
  private readonly runner;
312
328
  private readonly listeners;
313
329
  private readonly cleanups;
@@ -320,14 +336,15 @@ export declare class PaperPic {
320
336
  /** What the edits look like, while they need other pixels than the image. */
321
337
  private preview;
322
338
  private previewKey;
323
- private previewId;
324
- private previewing;
339
+ private readonly previewQueue;
325
340
  /** The open tool with a selection of its own, such as Crop. */
326
341
  private session;
327
342
  /** The open Adjust or Clean up. */
328
343
  private draft;
329
344
  private loadStatus;
330
345
  private loadId;
346
+ /** Changes when an edit ends without a trace, so an Apply that finishes afterwards knows that its edit is gone. */
347
+ private editId;
331
348
  private view;
332
349
  private viewport;
333
350
  private mode;
@@ -338,6 +355,7 @@ export declare class PaperPic {
338
355
  /**
339
356
  * @param container The element to fill. It needs a height, or the viewer stays at its minimum height.
340
357
  * @throws {TypeError} If `container` is not an element. Create the instance once the element exists, such as on mount.
358
+ * @throws {RangeError} If an option is out of its range, such as a `softness` of 2.
341
359
  *
342
360
  * @example
343
361
  * const pic = new PaperPic(container, {
@@ -352,10 +370,17 @@ export declare class PaperPic {
352
370
  * Changes only the options you pass, and `undefined` brings one back to its default. It does not emit `change`, so
353
371
  * two-way bindings do not loop.
354
372
  *
373
+ * @throws {RangeError} If an option is out of its range, such as a `softness` of 2. No option changes then.
374
+ *
355
375
  * @example
356
376
  * pic.setOptions({ editable: false })
357
377
  */
358
378
  setOptions(options: PaperPicOptions): void;
379
+ /**
380
+ * Applies the options that changed. Options with the same values change nothing, so a wrapper can pass them all on
381
+ * every render, and a message on screen stays. The constructor passes `initial` to set everything up.
382
+ */
383
+ private changeOptions;
359
384
  /** Returns what the viewer is showing. */
360
385
  getState(): PaperPicState;
361
386
  /**
@@ -443,7 +468,7 @@ export declare class PaperPic {
443
468
  cancel(): void;
444
469
  /**
445
470
  * Applies the edits. The result becomes the image on display, and the `apply` event carries it.
446
- * If it fails, the `error` event reports it and the edit stays open.
471
+ * If it fails, the `error` event reports it and the edit stays open. The promise resolves either way.
447
472
  *
448
473
  * @example
449
474
  * pic.on('apply', ({ blob, type }) => upload(blob, type))
@@ -479,9 +504,6 @@ export declare class PaperPic {
479
504
  private describeImage;
480
505
  private scene;
481
506
  private toolHost;
482
- /** Paints the image larger around a point, inside a circle. */
483
- private paintLens;
484
- private canAdjust;
485
507
  /** The open tool, with a selection or a panel of settings of its own. */
486
508
  private openToolId;
487
509
  /** Shows other settings in the open Adjust or Clean up, without any edit. */
@@ -489,6 +511,10 @@ export declare class PaperPic {
489
511
  /** The edit that the open Adjust or Clean up would leave, or `null` if it changes nothing. */
490
512
  private draftEdit;
491
513
  private closeTool;
514
+ /**
515
+ * Tells the listeners of an event. A listener that throws is the app failing, not the viewer, so the page gets its
516
+ * error as any uncaught one, the other listeners still run, and it never looks like a failed load or Apply.
517
+ */
492
518
  private emit;
493
519
  private hasFocus;
494
520
  /** Puts the keyboard focus back on the toolbar, because the button that had it may be gone. */
@@ -497,7 +523,7 @@ export declare class PaperPic {
497
523
  /** Changes what a download saves, and frees the address of the file it saved before. */
498
524
  private setSaved;
499
525
  private setImage;
500
- /** Ends the edit without a trace. In-progress work is ignored when it finishes, because a load changes `loadId`. */
526
+ /** Ends the edit without a trace. An Apply in progress is ignored when it finishes, because `editId` changes. */
501
527
  private leaveEdit;
502
528
  private addOperation;
503
529
  private setHistory;
@@ -511,8 +537,10 @@ export declare class PaperPic {
511
537
  private previewTone;
512
538
  /** Makes the pixels on display match the edits. A change of tones of the same kind only repaints the preview. */
513
539
  private updatePreview;
514
- /** Computes the pixels of the edits. A result that arrives after newer edits is ignored. */
515
- private startPreview;
540
+ /** Shows a preview that arrived, with the tones of the ruler, which may have moved while it was on its way. */
541
+ private showPreview;
542
+ /** Keeps the edit open, and reports that its pixels could not be shown. */
543
+ private previewFailed;
516
544
  /**
517
545
  * Changes the pixels on display. A new shape starts from a fitted view, and the same shape keeps the zoom, as when the threshold changes.
518
546
  * With `null` it goes back to the image, and any preview in progress is forgotten.
@@ -525,9 +553,19 @@ export declare class PaperPic {
525
553
  /** The image on display, once the viewer has a size to show it in. A hidden container has none. */
526
554
  private measuredImage;
527
555
  private applyViewport;
556
+ /** Whether the zoom can go further in each direction, from the view on display. */
557
+ private canZoom;
558
+ /** Makes the whole interface match the state: the bars, the mode and the view. */
528
559
  private refresh;
560
+ /**
561
+ * Makes what follows the view match it: the zoom and fit buttons, the handles of an open tool, the cursor and the
562
+ * image. A pan or a zoom needs nothing else, and it can come on every move of the pointer.
563
+ */
564
+ private refreshView;
565
+ /** Shows another view. Returns whether it differs from the one on display. */
529
566
  private commit;
530
567
  private resetRotation;
568
+ /** Moves the image. Returns whether it moved, which an image that fits, or one at its edge, does not. */
531
569
  private pan;
532
570
  private zoomAround;
533
571
  /**
@@ -539,17 +577,4 @@ export declare class PaperPic {
539
577
  /** Runs a key's command. Returns whether it did something, so other keys keep their usual effect. */
540
578
  private runKey;
541
579
  }
542
- /**
543
- * What the `download` event carries.
544
- *
545
- * @see https://paperpic.dev/reference/events#download
546
- */
547
- interface PaperPicDownload {
548
- /** The name of the file, with the extension of its format. */
549
- filename: string;
550
- /** Stops the browser from saving the file, so you can save it another way. */
551
- preventDefault: () => void;
552
- /** The image to save: the result of the last Apply, or else the `src`. */
553
- source: PaperPicSource;
554
- }
555
580
  export type { ExportedImage, Fit, PaperPicDownload, PaperPicEvents, PaperPicIcons, PaperPicLabels, PaperPicOptions, PaperPicOutput, PaperPicSource, PaperPicState, Rotation, Size, ToolId, ViewPoint };