@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.
- package/dist/docs/examples/attach-and-scan.md +202 -0
- package/dist/docs/examples/custom-toolbar.md +196 -2
- package/dist/docs/examples/dialog.md +191 -0
- package/dist/docs/examples/fixed-proportions.md +1 -0
- package/dist/docs/examples/form.md +156 -0
- package/dist/docs/examples/upload.md +1 -1
- package/dist/docs/guide/accessibility.md +5 -5
- package/dist/docs/guide/editing.md +9 -18
- package/dist/docs/guide/getting-started.md +84 -11
- package/dist/docs/guide/introduction.md +1 -1
- package/dist/docs/guide/labels.md +2 -4
- package/dist/docs/guide/loading.md +130 -0
- package/dist/docs/guide/performance.md +17 -3
- package/dist/docs/guide/saving.md +17 -9
- package/dist/docs/guide/styling.md +2 -0
- package/dist/docs/guide/tools/adjust.md +4 -2
- package/dist/docs/guide/tools/clean-up.md +1 -1
- package/dist/docs/guide/tools/crop.md +3 -1
- package/dist/docs/guide/tools/rotate-and-flip.md +3 -1
- package/dist/docs/guide/tools/straighten.md +1 -1
- package/dist/docs/guide/troubleshooting.md +45 -0
- package/dist/docs/guide/viewer.md +12 -10
- package/dist/docs/reference/events.md +20 -7
- package/dist/docs/reference/labels.md +2 -2
- package/dist/docs/reference/methods.md +71 -15
- package/dist/docs/reference/options.md +9 -9
- package/dist/docs/reference/react.md +8 -4
- package/dist/docs/reference/state.md +113 -19
- package/dist/docs/reference/types.md +2 -2
- package/dist/docs/reference/vue.md +8 -6
- package/dist/index.d.ts +75 -50
- package/dist/index.js +1469 -1350
- package/dist/{pipeline-MP1RPlXT.js → steps-DuGiMvk0.js} +236 -75
- package/dist/types-C3ZHKId1.d.ts +31 -0
- package/dist/worker.d.ts +13 -61
- package/dist/worker.js +3 -10
- 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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
-
*
|
|
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/
|
|
31
|
+
* @see https://paperpic.dev/reference/options#src
|
|
37
32
|
*/
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
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
|
|
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
|
|
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
|
-
/**
|
|
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
|
|
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
|
-
/**
|
|
285
|
+
/** Apply finished, from the button, `Enter` or `apply()`. The result is already on display. */
|
|
278
286
|
apply: ExportedImage;
|
|
279
|
-
/**
|
|
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
|
-
/**
|
|
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
|
|
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.
|
|
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
|
-
/**
|
|
515
|
-
private
|
|
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 };
|