@paperpic/core 0.1.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/docs/examples/attach-and-scan.md +196 -0
- package/dist/docs/examples/custom-toolbar.md +183 -0
- package/dist/docs/guide/accessibility.md +1 -1
- package/dist/docs/guide/editing.md +6 -15
- package/dist/docs/guide/getting-started.md +83 -10
- package/dist/docs/guide/loading.md +128 -0
- package/dist/docs/guide/performance.md +17 -3
- package/dist/docs/guide/saving.md +6 -0
- package/dist/docs/guide/styling.md +2 -0
- package/dist/docs/guide/tools/adjust.md +2 -0
- package/dist/docs/guide/tools/crop.md +2 -0
- package/dist/docs/guide/tools/rotate-and-flip.md +3 -1
- package/dist/docs/guide/troubleshooting.md +45 -0
- package/dist/docs/guide/viewer.md +1 -1
- package/dist/docs/reference/events.md +11 -7
- package/dist/docs/reference/methods.md +8 -8
- package/dist/docs/reference/options.md +7 -7
- package/dist/docs/reference/react.md +11 -11
- package/dist/docs/reference/state.md +4 -4
- package/dist/docs/reference/types.md +301 -0
- package/dist/docs/reference/vue.md +10 -10
- package/dist/index.d.ts +125 -49
- 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
|
@@ -0,0 +1,301 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Types
|
|
3
|
+
description: Every TypeScript type that PaperPic exports, with its definition, the page that explains it and how to import it from the package you installed.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Types
|
|
7
|
+
|
|
8
|
+
The reference and the examples name types such as `ExportedImage` or `ToolId`. This page shows what each one holds, so you can type your own code. Each type links to the page that explains it.
|
|
9
|
+
|
|
10
|
+
Import the types from the package you installed. `@paperpic/vue` and `@paperpic/react` export every type of `@paperpic/core`, so you do not need to install it:
|
|
11
|
+
|
|
12
|
+
:::tabs key:framework
|
|
13
|
+
== JavaScript
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
import type { ExportedImage, PaperPicState, ToolId } from '@paperpic/core'
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
== Vue
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
import type { ExportedImage, PaperPicState, ToolId } from '@paperpic/vue'
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
== React
|
|
26
|
+
|
|
27
|
+
```ts
|
|
28
|
+
import type { ExportedImage, PaperPicState, ToolId } from '@paperpic/react'
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
:::
|
|
32
|
+
|
|
33
|
+
## Options
|
|
34
|
+
|
|
35
|
+
### `PaperPicOptions`
|
|
36
|
+
|
|
37
|
+
```ts
|
|
38
|
+
interface PaperPicOptions {
|
|
39
|
+
alt?: string
|
|
40
|
+
aspectRatio?: number
|
|
41
|
+
download?: boolean
|
|
42
|
+
editable?: boolean
|
|
43
|
+
filename?: string
|
|
44
|
+
icons?: Partial<PaperPicIcons>
|
|
45
|
+
labels?: Partial<PaperPicLabels>
|
|
46
|
+
maxOutputSize?: number
|
|
47
|
+
output?: PaperPicOutput
|
|
48
|
+
softness?: number
|
|
49
|
+
src?: PaperPicSource
|
|
50
|
+
toolbar?: boolean
|
|
51
|
+
tools?: readonly ToolId[]
|
|
52
|
+
wheelZoom?: boolean
|
|
53
|
+
}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
What the constructor and [`setOptions()`](./methods#setoptions) take. In Vue and React, these are the props of the component. [Options](./options) explains each one.
|
|
57
|
+
|
|
58
|
+
### `PaperPicSource`
|
|
59
|
+
|
|
60
|
+
```ts
|
|
61
|
+
type PaperPicSource = string | Blob
|
|
62
|
+
```
|
|
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.
|
|
65
|
+
|
|
66
|
+
### `PaperPicOutput`
|
|
67
|
+
|
|
68
|
+
```ts
|
|
69
|
+
interface PaperPicOutput {
|
|
70
|
+
quality?: number
|
|
71
|
+
type?: string
|
|
72
|
+
}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
The format of the edited image, in [`output`](./options#output).
|
|
76
|
+
|
|
77
|
+
### `ToolId`
|
|
78
|
+
|
|
79
|
+
```ts
|
|
80
|
+
type ToolId = 'adjust' | 'crop' | 'flip' | 'perspective' | 'rotate' | 'threshold'
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
A tool of the edit bar, in [`tools`](./options#tools), [`openTool()`](./methods#opentool) and the `activeTool` of the [state](./state). [`tools`](./options#tools) gives the button of each one.
|
|
84
|
+
|
|
85
|
+
### `PaperPicLabels`
|
|
86
|
+
|
|
87
|
+
```ts
|
|
88
|
+
interface PaperPicLabels {
|
|
89
|
+
adjust: string
|
|
90
|
+
adjustmentLevel: (name: string, value: number) => string
|
|
91
|
+
applied: string
|
|
92
|
+
apply: string
|
|
93
|
+
applyError: string
|
|
94
|
+
brightness: string
|
|
95
|
+
cancel: string
|
|
96
|
+
cancelTool: string
|
|
97
|
+
confirm: string
|
|
98
|
+
contrast: string
|
|
99
|
+
cornerBottomLeft: string
|
|
100
|
+
cornerBottomRight: string
|
|
101
|
+
cornerMoved: (corner: string, x: number, y: number) => string
|
|
102
|
+
cornerSelected: (corner: string) => string
|
|
103
|
+
cornerTopLeft: string
|
|
104
|
+
cornerTopRight: string
|
|
105
|
+
crop: string
|
|
106
|
+
cropHint: string
|
|
107
|
+
discard: string
|
|
108
|
+
discardQuestion: string
|
|
109
|
+
download: string
|
|
110
|
+
edit: string
|
|
111
|
+
editBar: string
|
|
112
|
+
editing: string
|
|
113
|
+
fitHeight: string
|
|
114
|
+
fitWidth: string
|
|
115
|
+
flip: string
|
|
116
|
+
inUse: string
|
|
117
|
+
keepEditing: string
|
|
118
|
+
loadError: string
|
|
119
|
+
loading: string
|
|
120
|
+
perspective: string
|
|
121
|
+
perspectiveHint: string
|
|
122
|
+
processing: string
|
|
123
|
+
redo: string
|
|
124
|
+
rotateLeft: string
|
|
125
|
+
rotateRight: string
|
|
126
|
+
threshold: string
|
|
127
|
+
thresholdLevel: (percent: number) => string
|
|
128
|
+
thresholdSensitivity: string
|
|
129
|
+
toolbar: string
|
|
130
|
+
undo: string
|
|
131
|
+
viewer: string
|
|
132
|
+
zoomIn: string
|
|
133
|
+
zoomLevel: (percent: number) => string
|
|
134
|
+
zoomOut: string
|
|
135
|
+
}
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Every text of the interface, in [`labels`](./options#labels). The texts that include a value, such as the zoom level, are functions. [Labels](./labels) gives the English text of each one.
|
|
139
|
+
|
|
140
|
+
### `PaperPicIcons`
|
|
141
|
+
|
|
142
|
+
```ts
|
|
143
|
+
interface PaperPicIcons {
|
|
144
|
+
adjust: string
|
|
145
|
+
apply: string
|
|
146
|
+
brightness: string
|
|
147
|
+
cancel: string
|
|
148
|
+
contrast: string
|
|
149
|
+
crop: string
|
|
150
|
+
download: string
|
|
151
|
+
edit: string
|
|
152
|
+
fitHeight: string
|
|
153
|
+
fitWidth: string
|
|
154
|
+
flip: string
|
|
155
|
+
perspective: string
|
|
156
|
+
redo: string
|
|
157
|
+
rotateDocument: string
|
|
158
|
+
rotateLeft: string
|
|
159
|
+
rotateRight: string
|
|
160
|
+
threshold: string
|
|
161
|
+
undo: string
|
|
162
|
+
zoomIn: string
|
|
163
|
+
zoomOut: string
|
|
164
|
+
}
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
Every icon of the interface, as the markup of one element, in [`icons`](./options#icons), which gives the buttons of each one.
|
|
168
|
+
|
|
169
|
+
## State
|
|
170
|
+
|
|
171
|
+
### `PaperPicState`
|
|
172
|
+
|
|
173
|
+
```ts
|
|
174
|
+
interface PaperPicState {
|
|
175
|
+
activeTool: ToolId | null
|
|
176
|
+
adjustments: { brightness: number, contrast: number }
|
|
177
|
+
busy: boolean
|
|
178
|
+
canApply: boolean
|
|
179
|
+
canRedo: boolean
|
|
180
|
+
canUndo: boolean
|
|
181
|
+
fit: Fit | null
|
|
182
|
+
image: Size | null
|
|
183
|
+
mode: 'view' | 'edit'
|
|
184
|
+
rotation: Rotation
|
|
185
|
+
status: 'empty' | 'loading' | 'ready' | 'error'
|
|
186
|
+
threshold: { enabled: boolean, sensitivity: number }
|
|
187
|
+
zoom: number
|
|
188
|
+
}
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
What [`getState()`](./methods#getstate) returns and the [`change`](./events#change) event carries. [State](./state) explains each field.
|
|
192
|
+
|
|
193
|
+
### `Fit`
|
|
194
|
+
|
|
195
|
+
```ts
|
|
196
|
+
type Fit = 'image' | 'width' | 'height'
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
How the image fits the viewer: whole, by its width or by its height. [`fit()`](./methods#fit) takes it, and the `fit` of the [state](./state) holds it.
|
|
200
|
+
|
|
201
|
+
### `Rotation`
|
|
202
|
+
|
|
203
|
+
```ts
|
|
204
|
+
type Rotation = 0 | 90 | 180 | 270
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
How far the image on display is turned, in degrees clockwise, in the `rotation` of the [state](./state).
|
|
208
|
+
|
|
209
|
+
### `Size`
|
|
210
|
+
|
|
211
|
+
```ts
|
|
212
|
+
interface Size {
|
|
213
|
+
height: number
|
|
214
|
+
width: number
|
|
215
|
+
}
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
A width and a height in pixels, such as the `image` of the [state](./state) or what the [`load`](./events#load) event carries.
|
|
219
|
+
|
|
220
|
+
## Events
|
|
221
|
+
|
|
222
|
+
### `PaperPicEvents`
|
|
223
|
+
|
|
224
|
+
```ts
|
|
225
|
+
interface PaperPicEvents {
|
|
226
|
+
apply: ExportedImage
|
|
227
|
+
change: PaperPicState
|
|
228
|
+
download: PaperPicDownload
|
|
229
|
+
error: { error: Error, phase: 'load' | 'preview' | 'apply' }
|
|
230
|
+
load: Size
|
|
231
|
+
}
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
Each event with what it carries, for [`on()`](./methods#on). [Events](./events) explains each one.
|
|
235
|
+
|
|
236
|
+
### `ExportedImage`
|
|
237
|
+
|
|
238
|
+
```ts
|
|
239
|
+
interface ExportedImage {
|
|
240
|
+
blob: Blob
|
|
241
|
+
height: number
|
|
242
|
+
type: string
|
|
243
|
+
width: number
|
|
244
|
+
}
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
The edited image, which the [`apply`](./events#apply) event carries. `type` is the format of `blob`, which [`output`](./options#output) chooses.
|
|
248
|
+
|
|
249
|
+
### `PaperPicDownload`
|
|
250
|
+
|
|
251
|
+
```ts
|
|
252
|
+
interface PaperPicDownload {
|
|
253
|
+
filename: string
|
|
254
|
+
preventDefault: () => void
|
|
255
|
+
source: PaperPicSource
|
|
256
|
+
}
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
What the [`download`](./events#download) event carries. Call `preventDefault()` to save the file another way.
|
|
260
|
+
|
|
261
|
+
## Methods
|
|
262
|
+
|
|
263
|
+
### `ViewPoint`
|
|
264
|
+
|
|
265
|
+
```ts
|
|
266
|
+
interface ViewPoint {
|
|
267
|
+
x: number
|
|
268
|
+
y: number
|
|
269
|
+
}
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
A point in CSS pixels from the top left corner of the viewer, for [`zoomTo()`](./methods#zoomto).
|
|
273
|
+
|
|
274
|
+
## Vue and React
|
|
275
|
+
|
|
276
|
+
`@paperpic/vue` and `@paperpic/react` also export the types of their component. [Vue](./vue) and [React](./react) show how to use it.
|
|
277
|
+
|
|
278
|
+
### `PaperPicInstance`
|
|
279
|
+
|
|
280
|
+
```ts
|
|
281
|
+
type PaperPicInstance = PaperPic
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
The viewer that the component gives you: `instance` in Vue, and what `ref` receives in React. It is the class `PaperPic` of `@paperpic/core`, with every [method](./methods).
|
|
285
|
+
|
|
286
|
+
### `PaperPicProps`
|
|
287
|
+
|
|
288
|
+
```ts
|
|
289
|
+
interface PaperPicProps extends PaperPicOptions {
|
|
290
|
+
className?: string
|
|
291
|
+
onApply?: (result: PaperPicEvents['apply']) => void
|
|
292
|
+
onChange?: (state: PaperPicEvents['change']) => void
|
|
293
|
+
onDownload?: (download: PaperPicEvents['download']) => void
|
|
294
|
+
onError?: (failure: PaperPicEvents['error']) => void
|
|
295
|
+
onLoad?: (size: PaperPicEvents['load']) => void
|
|
296
|
+
ref?: Ref<PaperPicInstance>
|
|
297
|
+
style?: CSSProperties
|
|
298
|
+
}
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
The props of the component in React: the options, plus the classes and styles of its element, a callback for each event, and `ref`. In Vue, the props have the same fields as [`PaperPicOptions`](#paperpicoptions), and the events are component events.
|
|
@@ -31,17 +31,17 @@ The component fills its parent element, so give the parent a height.
|
|
|
31
31
|
|
|
32
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()`.
|
|
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
|
|
|
38
|
-
| Event | Payload
|
|
39
|
-
| ---------- |
|
|
40
|
-
| `apply` | `
|
|
41
|
-
| `change` | [`PaperPicState`](./state)
|
|
42
|
-
| `download` | `
|
|
43
|
-
| `error` | `{ error }`
|
|
44
|
-
| `load` | `
|
|
38
|
+
| Event | Payload |
|
|
39
|
+
| ---------- | ---------------------------------------------- |
|
|
40
|
+
| `apply` | [`ExportedImage`](./types#exportedimage) |
|
|
41
|
+
| `change` | [`PaperPicState`](./state) |
|
|
42
|
+
| `download` | [`PaperPicDownload`](./types#paperpicdownload) |
|
|
43
|
+
| `error` | `{ error, phase }` |
|
|
44
|
+
| `load` | [`Size`](./types#size) |
|
|
45
45
|
|
|
46
46
|
[Events](./events) describes each one. A change of a prop never emits `change`.
|
|
47
47
|
|
|
@@ -69,9 +69,9 @@ const pic = useTemplateRef('pic')
|
|
|
69
69
|
|
|
70
70
|
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
71
|
|
|
72
|
-
## Types
|
|
72
|
+
## Types {#types}
|
|
73
73
|
|
|
74
|
-
`@paperpic/vue` exports
|
|
74
|
+
`@paperpic/vue` exports every type of `@paperpic/core`, so you do not need to install it: [Types](./types) shows each one. It also exports the types of the component: [`PaperPicProps`](./types#paperpicprops), with its props, and [`PaperPicInstance`](./types#paperpicinstance), the viewer in `instance`.
|
|
75
75
|
|
|
76
76
|
## Server-side rendering
|
|
77
77
|
|
package/dist/index.d.ts
CHANGED
|
@@ -1,51 +1,66 @@
|
|
|
1
|
-
|
|
2
|
-
interface PaperPicDownload {
|
|
3
|
-
/** The name of the file, with the extension of its format. */
|
|
4
|
-
filename: string;
|
|
5
|
-
/** Stops the browser from saving the file, so you can save it another way. */
|
|
6
|
-
preventDefault: () => void;
|
|
7
|
-
/** The image to save: the result of the last Apply, or else the `src`. */
|
|
8
|
-
source: string | Blob;
|
|
9
|
-
}
|
|
10
|
-
export type Rotation = 0 | 90 | 180 | 270;
|
|
1
|
+
import { i as Size } from "./types-C3ZHKId1.js";
|
|
11
2
|
/**
|
|
12
|
-
*
|
|
3
|
+
* The format of the image that editing produces.
|
|
13
4
|
*
|
|
14
|
-
* @
|
|
5
|
+
* @see https://paperpic.dev/reference/options#output
|
|
15
6
|
*/
|
|
16
|
-
export declare function normalizeRotation(degrees: number): Rotation;
|
|
17
|
-
/** The format of the image that editing produces. */
|
|
18
7
|
interface PaperPicOutput {
|
|
19
8
|
/** From 0 to 1, for JPEG and WebP. */
|
|
20
9
|
quality?: number;
|
|
21
10
|
/** `image/jpeg`, `image/png` or `image/webp`. By default, the format of the source. */
|
|
22
11
|
type?: string;
|
|
23
12
|
}
|
|
24
|
-
/**
|
|
13
|
+
/**
|
|
14
|
+
* The image that editing produces, which the `apply` event carries.
|
|
15
|
+
*
|
|
16
|
+
* @see https://paperpic.dev/reference/events#apply
|
|
17
|
+
*/
|
|
25
18
|
interface ExportedImage {
|
|
19
|
+
/** The edited image, ready to upload. */
|
|
26
20
|
blob: Blob;
|
|
21
|
+
/** In pixels. */
|
|
27
22
|
height: number;
|
|
28
23
|
/** The format of `blob`. A browser that cannot encode the requested one gives PNG. */
|
|
29
24
|
type: string;
|
|
25
|
+
/** In pixels. */
|
|
30
26
|
width: number;
|
|
31
27
|
}
|
|
32
|
-
/**
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
28
|
+
/**
|
|
29
|
+
* The image to show: a URL from the same origin, or a file attached on the client.
|
|
30
|
+
*
|
|
31
|
+
* @see https://paperpic.dev/reference/options#src
|
|
32
|
+
*/
|
|
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;
|
|
40
|
+
/**
|
|
41
|
+
* A position in CSS pixels, relative to the top left corner of the viewer.
|
|
42
|
+
*
|
|
43
|
+
* @see https://paperpic.dev/reference/methods#zoomto
|
|
44
|
+
*/
|
|
38
45
|
interface ViewPoint {
|
|
39
46
|
x: number;
|
|
40
47
|
y: number;
|
|
41
48
|
}
|
|
42
|
-
/**
|
|
49
|
+
/**
|
|
50
|
+
* How the image adapts to the viewer: the whole image, its width or its height.
|
|
51
|
+
*
|
|
52
|
+
* @see https://paperpic.dev/reference/methods#fit
|
|
53
|
+
*/
|
|
43
54
|
type Fit = 'image' | 'width' | 'height';
|
|
44
|
-
/**
|
|
55
|
+
/**
|
|
56
|
+
* Every text the component shows or announces. The texts with values are functions.
|
|
57
|
+
*
|
|
58
|
+
* @see https://paperpic.dev/reference/labels
|
|
59
|
+
*/
|
|
45
60
|
interface PaperPicLabels {
|
|
46
61
|
/** Opens the ruler of brightness and contrast. */
|
|
47
62
|
adjust: string;
|
|
48
|
-
/** Announced after
|
|
63
|
+
/** Announced after moving the ruler of Adjust, with the name of the tone and its value from -100 to 100. */
|
|
49
64
|
adjustmentLevel: (name: string, value: number) => string;
|
|
50
65
|
/** Announced when the changes are applied. */
|
|
51
66
|
applied: string;
|
|
@@ -101,7 +116,7 @@ interface PaperPicLabels {
|
|
|
101
116
|
rotateRight: string;
|
|
102
117
|
/** Opens Clean up, and names its switch. */
|
|
103
118
|
threshold: string;
|
|
104
|
-
/** Announced after
|
|
119
|
+
/** Announced after moving the ruler of Clean up, with its value in percent. */
|
|
105
120
|
thresholdLevel: (percent: number) => string;
|
|
106
121
|
/** Name of the ruler of Clean up. */
|
|
107
122
|
thresholdSensitivity: string;
|
|
@@ -115,9 +130,17 @@ interface PaperPicLabels {
|
|
|
115
130
|
zoomLevel: (percent: number) => string;
|
|
116
131
|
zoomOut: string;
|
|
117
132
|
}
|
|
118
|
-
/**
|
|
133
|
+
/**
|
|
134
|
+
* The tools the edit bar can offer. `perspective` is Straighten, and `threshold` is Clean up.
|
|
135
|
+
*
|
|
136
|
+
* @see https://paperpic.dev/reference/options#tools
|
|
137
|
+
*/
|
|
119
138
|
type ToolId = 'adjust' | 'crop' | 'flip' | 'perspective' | 'rotate' | 'threshold';
|
|
120
|
-
/**
|
|
139
|
+
/**
|
|
140
|
+
* Every icon of the interface, as the markup of one element, such as an `<svg>`. One icon can appear on several buttons.
|
|
141
|
+
*
|
|
142
|
+
* @see https://paperpic.dev/reference/options#icons
|
|
143
|
+
*/
|
|
121
144
|
interface PaperPicIcons {
|
|
122
145
|
/** Adjust, which opens the ruler of brightness and contrast. */
|
|
123
146
|
adjust: string;
|
|
@@ -151,9 +174,12 @@ interface PaperPicIcons {
|
|
|
151
174
|
zoomIn: string;
|
|
152
175
|
zoomOut: string;
|
|
153
176
|
}
|
|
154
|
-
/**
|
|
155
|
-
|
|
156
|
-
|
|
177
|
+
/**
|
|
178
|
+
* What the constructor and `setOptions()` take.
|
|
179
|
+
*
|
|
180
|
+
* @see https://paperpic.dev/reference/options
|
|
181
|
+
*/
|
|
182
|
+
interface PaperPicOptions {
|
|
157
183
|
/** Describes the image for screen readers. Without it, they skip the image, as they skip an `<img>` with an empty `alt`. */
|
|
158
184
|
alt?: string;
|
|
159
185
|
/** The real proportions of the document, as width divided by height, such as `210 / 297` for A4. Without it, straightening estimates them. */
|
|
@@ -187,13 +213,30 @@ export interface PaperPicOptions {
|
|
|
187
213
|
src?: PaperPicSource;
|
|
188
214
|
/** Whether to show the built-in toolbar and edit bar. Without them, build your own with the public methods. */
|
|
189
215
|
toolbar?: boolean;
|
|
190
|
-
/** 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. */
|
|
191
217
|
tools?: readonly ToolId[];
|
|
192
218
|
/** Whether the wheel zooms. Turn it off when the viewer sits in a long page. */
|
|
193
219
|
wheelZoom?: boolean;
|
|
194
220
|
}
|
|
195
|
-
/**
|
|
196
|
-
|
|
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
|
+
}
|
|
234
|
+
/**
|
|
235
|
+
* What the viewer is showing, which `getState()` returns and the `change` event carries.
|
|
236
|
+
*
|
|
237
|
+
* @see https://paperpic.dev/reference/state
|
|
238
|
+
*/
|
|
239
|
+
interface PaperPicState {
|
|
197
240
|
/** The open tool, such as Crop or Adjust, or `null`. Done or Cancel closes it. */
|
|
198
241
|
activeTool: ToolId | null;
|
|
199
242
|
/**
|
|
@@ -208,7 +251,9 @@ export interface PaperPicState {
|
|
|
208
251
|
busy: boolean;
|
|
209
252
|
/** Whether there are changes to apply. Rotations that cancel out are no change. */
|
|
210
253
|
canApply: boolean;
|
|
254
|
+
/** Whether there is an edit to bring back. */
|
|
211
255
|
canRedo: boolean;
|
|
256
|
+
/** Whether there is an edit to undo. */
|
|
212
257
|
canUndo: boolean;
|
|
213
258
|
/** The fit in effect, or `null` once the user has zoomed by hand. */
|
|
214
259
|
fit: Fit | null;
|
|
@@ -216,7 +261,9 @@ export interface PaperPicState {
|
|
|
216
261
|
image: Size | null;
|
|
217
262
|
/** Whether the user is viewing or editing the image. */
|
|
218
263
|
mode: 'view' | 'edit';
|
|
264
|
+
/** How far the image on display is turned, in degrees clockwise. */
|
|
219
265
|
rotation: Rotation;
|
|
266
|
+
/** Whether there is an image, and whether it loaded. */
|
|
220
267
|
status: 'empty' | 'loading' | 'ready' | 'error';
|
|
221
268
|
/** Whether the document gets cleaned up, and how much. While Clean up is open, what it shows, which Done would keep. */
|
|
222
269
|
threshold: {
|
|
@@ -226,22 +273,28 @@ export interface PaperPicState {
|
|
|
226
273
|
/** Screen pixels per image pixel. */
|
|
227
274
|
zoom: number;
|
|
228
275
|
}
|
|
229
|
-
|
|
276
|
+
/**
|
|
277
|
+
* Each event of `on()`, with what it carries.
|
|
278
|
+
*
|
|
279
|
+
* @see https://paperpic.dev/reference/events
|
|
280
|
+
*/
|
|
281
|
+
interface PaperPicEvents {
|
|
230
282
|
/** The user applied the changes. The result is already on display. */
|
|
231
283
|
apply: ExportedImage;
|
|
232
|
-
/** The user changed the
|
|
284
|
+
/** The user changed something in the state, such as the zoom or the edit. A pan and `setOptions()` never trigger it. */
|
|
233
285
|
change: PaperPicState;
|
|
234
286
|
/** The image is about to be saved. Call `preventDefault()` to save it another way. */
|
|
235
287
|
download: PaperPicDownload;
|
|
236
|
-
/**
|
|
288
|
+
/**
|
|
289
|
+
* Something failed. `phase` says what: `'load'` for the image, `'preview'` for the pixels of an edit on display,
|
|
290
|
+
* which leaves the edit open, and `'apply'` for the changes.
|
|
291
|
+
*/
|
|
237
292
|
error: {
|
|
238
293
|
error: Error;
|
|
294
|
+
phase: 'load' | 'preview' | 'apply';
|
|
239
295
|
};
|
|
240
296
|
/** The image is ready. */
|
|
241
|
-
load:
|
|
242
|
-
height: number;
|
|
243
|
-
width: number;
|
|
244
|
-
};
|
|
297
|
+
load: Size;
|
|
245
298
|
}
|
|
246
299
|
type Listener<Name extends keyof PaperPicEvents> = (payload: PaperPicEvents[Name]) => void;
|
|
247
300
|
/**
|
|
@@ -264,6 +317,7 @@ export declare class PaperPic {
|
|
|
264
317
|
private readonly toolbar;
|
|
265
318
|
private readonly editBar;
|
|
266
319
|
private readonly renderer;
|
|
320
|
+
private readonly gestures;
|
|
267
321
|
private readonly runner;
|
|
268
322
|
private readonly listeners;
|
|
269
323
|
private readonly cleanups;
|
|
@@ -276,14 +330,15 @@ export declare class PaperPic {
|
|
|
276
330
|
/** What the edits look like, while they need other pixels than the image. */
|
|
277
331
|
private preview;
|
|
278
332
|
private previewKey;
|
|
279
|
-
private
|
|
280
|
-
private previewing;
|
|
333
|
+
private readonly previewQueue;
|
|
281
334
|
/** The open tool with a selection of its own, such as Crop. */
|
|
282
335
|
private session;
|
|
283
336
|
/** The open Adjust or Clean up. */
|
|
284
337
|
private draft;
|
|
285
338
|
private loadStatus;
|
|
286
339
|
private loadId;
|
|
340
|
+
/** Changes when an edit ends without a trace, so an Apply that finishes afterwards knows that its edit is gone. */
|
|
341
|
+
private editId;
|
|
287
342
|
private view;
|
|
288
343
|
private viewport;
|
|
289
344
|
private mode;
|
|
@@ -294,6 +349,7 @@ export declare class PaperPic {
|
|
|
294
349
|
/**
|
|
295
350
|
* @param container The element to fill. It needs a height, or the viewer stays at its minimum height.
|
|
296
351
|
* @throws {TypeError} If `container` is not an element. Create the instance once the element exists, such as on mount.
|
|
352
|
+
* @throws {RangeError} If an option is out of its range, such as a `softness` of 2.
|
|
297
353
|
*
|
|
298
354
|
* @example
|
|
299
355
|
* const pic = new PaperPic(container, {
|
|
@@ -308,10 +364,17 @@ export declare class PaperPic {
|
|
|
308
364
|
* Changes only the options you pass, and `undefined` brings one back to its default. It does not emit `change`, so
|
|
309
365
|
* two-way bindings do not loop.
|
|
310
366
|
*
|
|
367
|
+
* @throws {RangeError} If an option is out of its range, such as a `softness` of 2. No option changes then.
|
|
368
|
+
*
|
|
311
369
|
* @example
|
|
312
370
|
* pic.setOptions({ editable: false })
|
|
313
371
|
*/
|
|
314
372
|
setOptions(options: PaperPicOptions): void;
|
|
373
|
+
/**
|
|
374
|
+
* Applies the options that changed. Options with the same values change nothing, so a wrapper can pass them all on
|
|
375
|
+
* every render, and a message on screen stays. The constructor passes `initial` to set everything up.
|
|
376
|
+
*/
|
|
377
|
+
private changeOptions;
|
|
315
378
|
/** Returns what the viewer is showing. */
|
|
316
379
|
getState(): PaperPicState;
|
|
317
380
|
/**
|
|
@@ -435,9 +498,6 @@ export declare class PaperPic {
|
|
|
435
498
|
private describeImage;
|
|
436
499
|
private scene;
|
|
437
500
|
private toolHost;
|
|
438
|
-
/** Paints the image larger around a point, inside a circle. */
|
|
439
|
-
private paintLens;
|
|
440
|
-
private canAdjust;
|
|
441
501
|
/** The open tool, with a selection or a panel of settings of its own. */
|
|
442
502
|
private openToolId;
|
|
443
503
|
/** Shows other settings in the open Adjust or Clean up, without any edit. */
|
|
@@ -445,6 +505,10 @@ export declare class PaperPic {
|
|
|
445
505
|
/** The edit that the open Adjust or Clean up would leave, or `null` if it changes nothing. */
|
|
446
506
|
private draftEdit;
|
|
447
507
|
private closeTool;
|
|
508
|
+
/**
|
|
509
|
+
* Tells the listeners of an event. A listener that throws is the app failing, not the viewer, so the page gets its
|
|
510
|
+
* error as any uncaught one, the other listeners still run, and it never looks like a failed load or Apply.
|
|
511
|
+
*/
|
|
448
512
|
private emit;
|
|
449
513
|
private hasFocus;
|
|
450
514
|
/** Puts the keyboard focus back on the toolbar, because the button that had it may be gone. */
|
|
@@ -453,7 +517,7 @@ export declare class PaperPic {
|
|
|
453
517
|
/** Changes what a download saves, and frees the address of the file it saved before. */
|
|
454
518
|
private setSaved;
|
|
455
519
|
private setImage;
|
|
456
|
-
/** Ends the edit without a trace.
|
|
520
|
+
/** Ends the edit without a trace. An Apply in progress is ignored when it finishes, because `editId` changes. */
|
|
457
521
|
private leaveEdit;
|
|
458
522
|
private addOperation;
|
|
459
523
|
private setHistory;
|
|
@@ -467,8 +531,10 @@ export declare class PaperPic {
|
|
|
467
531
|
private previewTone;
|
|
468
532
|
/** Makes the pixels on display match the edits. A change of tones of the same kind only repaints the preview. */
|
|
469
533
|
private updatePreview;
|
|
470
|
-
/**
|
|
471
|
-
private
|
|
534
|
+
/** Shows a preview that arrived, with the tones of the ruler, which may have moved while it was on its way. */
|
|
535
|
+
private showPreview;
|
|
536
|
+
/** Keeps the edit open, and reports that its pixels could not be shown. */
|
|
537
|
+
private previewFailed;
|
|
472
538
|
/**
|
|
473
539
|
* 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.
|
|
474
540
|
* With `null` it goes back to the image, and any preview in progress is forgotten.
|
|
@@ -481,9 +547,19 @@ export declare class PaperPic {
|
|
|
481
547
|
/** The image on display, once the viewer has a size to show it in. A hidden container has none. */
|
|
482
548
|
private measuredImage;
|
|
483
549
|
private applyViewport;
|
|
550
|
+
/** Whether the zoom can go further in each direction, from the view on display. */
|
|
551
|
+
private canZoom;
|
|
552
|
+
/** Makes the whole interface match the state: the bars, the mode and the view. */
|
|
484
553
|
private refresh;
|
|
554
|
+
/**
|
|
555
|
+
* Makes what follows the view match it: the zoom and fit buttons, the handles of an open tool, the cursor and the
|
|
556
|
+
* image. A pan or a zoom needs nothing else, and it can come on every move of the pointer.
|
|
557
|
+
*/
|
|
558
|
+
private refreshView;
|
|
559
|
+
/** Shows another view. Returns whether it differs from the one on display. */
|
|
485
560
|
private commit;
|
|
486
561
|
private resetRotation;
|
|
562
|
+
/** Moves the image. Returns whether it moved, which an image that fits, or one at its edge, does not. */
|
|
487
563
|
private pan;
|
|
488
564
|
private zoomAround;
|
|
489
565
|
/**
|
|
@@ -495,4 +571,4 @@ export declare class PaperPic {
|
|
|
495
571
|
/** Runs a key's command. Returns whether it did something, so other keys keep their usual effect. */
|
|
496
572
|
private runKey;
|
|
497
573
|
}
|
|
498
|
-
export type { ExportedImage, Fit, PaperPicDownload, PaperPicIcons, PaperPicLabels, PaperPicOutput, Size, ToolId, ViewPoint };
|
|
574
|
+
export type { ExportedImage, Fit, PaperPicDownload, PaperPicEvents, PaperPicIcons, PaperPicLabels, PaperPicOptions, PaperPicOutput, PaperPicSource, PaperPicState, Rotation, Size, ToolId, ViewPoint };
|