@paperpic/core 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/docs/reference/events.md +3 -3
- package/dist/docs/reference/methods.md +5 -5
- package/dist/docs/reference/options.md +5 -5
- package/dist/docs/reference/react.md +10 -10
- package/dist/docs/reference/state.md +4 -4
- package/dist/docs/reference/types.md +301 -0
- package/dist/docs/reference/vue.md +9 -9
- package/dist/index.d.ts +89 -32
- package/dist/index.js +1 -1
- package/package.json +1 -1
|
@@ -30,7 +30,7 @@ pic.on('apply', ({ blob }) => upload(blob))
|
|
|
30
30
|
|
|
31
31
|
## `load`
|
|
32
32
|
|
|
33
|
-
- **Payload:** `
|
|
33
|
+
- **Payload:** [`Size`](./types#size)
|
|
34
34
|
|
|
35
35
|
The image is loaded and on display. `width` and `height` are its size in pixels.
|
|
36
36
|
|
|
@@ -48,13 +48,13 @@ The user changed the view or the edit, such as by zooming, opening a tool or und
|
|
|
48
48
|
|
|
49
49
|
## `apply`
|
|
50
50
|
|
|
51
|
-
- **Payload:** `
|
|
51
|
+
- **Payload:** [`ExportedImage`](./types#exportedimage)
|
|
52
52
|
|
|
53
53
|
The user applied the edits, and the result is already on display. `blob` holds the image in the format `type`, which [`output`](./options#output) chooses.
|
|
54
54
|
|
|
55
55
|
## `download`
|
|
56
56
|
|
|
57
|
-
- **Payload:** `
|
|
57
|
+
- **Payload:** [`PaperPicDownload`](./types#paperpicdownload)
|
|
58
58
|
|
|
59
59
|
The image is about to be saved, from the download button or from [`download()`](./methods#download). `source` is the image on display: the result of the last Apply, or else the `src`. `filename` is the name of the file.
|
|
60
60
|
|
|
@@ -58,7 +58,7 @@ Returns what the viewer is showing, such as the zoom, the mode and whether there
|
|
|
58
58
|
### `on()`
|
|
59
59
|
|
|
60
60
|
```ts
|
|
61
|
-
function on(name:
|
|
61
|
+
function on<Name extends keyof PaperPicEvents>(name: Name, listener: (payload: PaperPicEvents[Name]) => void): () => void
|
|
62
62
|
```
|
|
63
63
|
|
|
64
64
|
Listens to an event, and returns a function that stops listening. [Events](./events) describes each event.
|
|
@@ -90,20 +90,20 @@ Zooms out one step, around the center of the viewer.
|
|
|
90
90
|
### `zoomTo()`
|
|
91
91
|
|
|
92
92
|
```ts
|
|
93
|
-
function zoomTo(zoom: number, point?:
|
|
93
|
+
function zoomTo(zoom: number, point?: ViewPoint): void
|
|
94
94
|
```
|
|
95
95
|
|
|
96
|
-
Sets the zoom, where `1` shows one pixel of the image per screen pixel. `point` stays in place: it is in CSS pixels from the top left corner of the viewer, and its center by default.
|
|
96
|
+
Sets the zoom, where `1` shows one pixel of the image per screen pixel. [`point`](./types#viewpoint) stays in place: it is in CSS pixels from the top left corner of the viewer, and its center by default.
|
|
97
97
|
|
|
98
98
|
The zoom goes from the fit of the whole image, or `1` if that is smaller, up to `8`. A value out of range is clamped.
|
|
99
99
|
|
|
100
100
|
### `fit()`
|
|
101
101
|
|
|
102
102
|
```ts
|
|
103
|
-
function fit(fit:
|
|
103
|
+
function fit(fit: Fit): void
|
|
104
104
|
```
|
|
105
105
|
|
|
106
|
-
Fits the whole image, its width or its height to the viewer.
|
|
106
|
+
Fits the whole image, its width or its height to the viewer. `fit` is a [`Fit`](./types#fit): `'image'`, `'width'` or `'height'`.
|
|
107
107
|
|
|
108
108
|
## Editing
|
|
109
109
|
|
|
@@ -19,7 +19,7 @@ pic.setOptions({ editable: false })
|
|
|
19
19
|
|
|
20
20
|
### `src`
|
|
21
21
|
|
|
22
|
-
- **Type:** `
|
|
22
|
+
- **Type:** [`PaperPicSource`](./types#paperpicsource)
|
|
23
23
|
- **Default:** none
|
|
24
24
|
|
|
25
25
|
The image to show: a URL from the same origin, or a `File` or `Blob` attached on the client.
|
|
@@ -51,7 +51,7 @@ Whether to show the built-in toolbar and edit bar. Without them, build your own
|
|
|
51
51
|
|
|
52
52
|
### `tools`
|
|
53
53
|
|
|
54
|
-
- **Type:** `readonly ToolId[]`
|
|
54
|
+
- **Type:** [`readonly ToolId[]`](./types#toolid)
|
|
55
55
|
- **Default:** every tool
|
|
56
56
|
|
|
57
57
|
The tools the edit bar offers. They keep the order of this table, whatever the order of the array.
|
|
@@ -81,14 +81,14 @@ Whether the toolbar has a button that saves the image on display: the result of
|
|
|
81
81
|
|
|
82
82
|
### `labels`
|
|
83
83
|
|
|
84
|
-
- **Type:** `Partial<PaperPicLabels>`
|
|
84
|
+
- **Type:** [`Partial<PaperPicLabels>`](./types#paperpiclabels)
|
|
85
85
|
- **Default:** the English texts
|
|
86
86
|
|
|
87
87
|
Replaces any of the texts that the component shows or announces. [Labels](./labels) lists every key.
|
|
88
88
|
|
|
89
89
|
### `icons`
|
|
90
90
|
|
|
91
|
-
- **Type:** `Partial<PaperPicIcons>`
|
|
91
|
+
- **Type:** [`Partial<PaperPicIcons>`](./types#paperpicicons)
|
|
92
92
|
- **Default:** the built-in icons
|
|
93
93
|
|
|
94
94
|
Replaces any of the icons with your own markup of one element, such as an `<svg>`. The markup goes into the page as HTML, so pass only markup you trust. An empty string leaves the buttons of that icon without one. [Styling](../guide/styling#icons) shows an example.
|
|
@@ -122,7 +122,7 @@ Each key names an icon, and some icons appear on two buttons:
|
|
|
122
122
|
|
|
123
123
|
### `output`
|
|
124
124
|
|
|
125
|
-
- **Type:** `
|
|
125
|
+
- **Type:** [`PaperPicOutput`](./types#paperpicoutput)
|
|
126
126
|
- **Default:** the format of the source
|
|
127
127
|
|
|
128
128
|
The format of the edited image. `type` is `'image/jpeg'`, `'image/png'` or `'image/webp'`, and `quality` goes from 0 to 1 for JPEG and WebP, with `0.92` by default.
|
|
@@ -40,19 +40,19 @@ Objects and arrays, such as `labels` or `tools`, reach the viewer again whenever
|
|
|
40
40
|
|
|
41
41
|
## Events
|
|
42
42
|
|
|
43
|
-
| Prop | Payload
|
|
44
|
-
| ------------ |
|
|
45
|
-
| `onApply` | `
|
|
46
|
-
| `onChange` | [`PaperPicState`](./state)
|
|
47
|
-
| `onDownload` | `
|
|
48
|
-
| `onError` | `{ error }`
|
|
49
|
-
| `onLoad` | `
|
|
43
|
+
| Prop | Payload |
|
|
44
|
+
| ------------ | ---------------------------------------------- |
|
|
45
|
+
| `onApply` | [`ExportedImage`](./types#exportedimage) |
|
|
46
|
+
| `onChange` | [`PaperPicState`](./state) |
|
|
47
|
+
| `onDownload` | [`PaperPicDownload`](./types#paperpicdownload) |
|
|
48
|
+
| `onError` | `{ error }` |
|
|
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
|
## Methods
|
|
54
54
|
|
|
55
|
-
`ref` receives the viewer, of type `PaperPicInstance
|
|
55
|
+
`ref` receives the viewer, of type [`PaperPicInstance`](./types#paperpicinstance), with every [method](./methods). It is `null` until the component mounts:
|
|
56
56
|
|
|
57
57
|
```tsx
|
|
58
58
|
import type { PaperPicInstance } from '@paperpic/react'
|
|
@@ -75,9 +75,9 @@ export function Viewer({ src }: { src: string }) {
|
|
|
75
75
|
|
|
76
76
|
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
77
|
|
|
78
|
-
## Types
|
|
78
|
+
## Types {#types}
|
|
79
79
|
|
|
80
|
-
`@paperpic/react` exports
|
|
80
|
+
`@paperpic/react` 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 that `ref` receives.
|
|
81
81
|
|
|
82
82
|
## Server-side rendering
|
|
83
83
|
|
|
@@ -15,16 +15,16 @@ pic.on('change', ({ canApply, busy }) => {
|
|
|
15
15
|
|
|
16
16
|
| Field | Type | Description |
|
|
17
17
|
| ------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
|
18
|
-
| `activeTool` | `ToolId \| null`
|
|
18
|
+
| `activeTool` | [`ToolId \| null`](./types#toolid) | The open tool, such as `'crop'` or `'adjust'`, or `null` |
|
|
19
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
20
|
| `busy` | `boolean` | Whether Apply is running |
|
|
21
21
|
| `canApply` | `boolean` | Whether there are changes to apply. Rotations and flips that cancel out are no change |
|
|
22
22
|
| `canRedo` | `boolean` | Whether there is an edit to bring back |
|
|
23
23
|
| `canUndo` | `boolean` | Whether there is an edit to undo |
|
|
24
|
-
| `fit` | `
|
|
25
|
-
| `image` | `
|
|
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
26
|
| `mode` | `'view' \| 'edit'` | Whether the user is viewing or editing the image |
|
|
27
|
-
| `rotation` | `
|
|
27
|
+
| `rotation` | [`Rotation`](./types#rotation) | How far the image on display is turned, in degrees clockwise |
|
|
28
28
|
| `status` | `'empty' \| 'loading' \| 'ready' \| 'error'` | Whether there is an image, and whether it loaded |
|
|
29
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
30
|
| `zoom` | `number` | Screen pixels per pixel of the image |
|
|
@@ -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 }
|
|
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.
|
|
@@ -35,13 +35,13 @@ Objects and arrays that the template builds, such as `:labels="{ apply: t('apply
|
|
|
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 }` |
|
|
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,47 +1,64 @@
|
|
|
1
|
-
/** What the `download` event carries. */
|
|
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;
|
|
11
1
|
/**
|
|
12
|
-
*
|
|
2
|
+
* How far the image is turned, in degrees clockwise.
|
|
13
3
|
*
|
|
14
|
-
* @
|
|
4
|
+
* @see https://paperpic.dev/reference/state
|
|
5
|
+
*/
|
|
6
|
+
type Rotation = 0 | 90 | 180 | 270;
|
|
7
|
+
/**
|
|
8
|
+
* The format of the image that editing produces.
|
|
9
|
+
*
|
|
10
|
+
* @see https://paperpic.dev/reference/options#output
|
|
15
11
|
*/
|
|
16
|
-
export declare function normalizeRotation(degrees: number): Rotation;
|
|
17
|
-
/** The format of the image that editing produces. */
|
|
18
12
|
interface PaperPicOutput {
|
|
19
13
|
/** From 0 to 1, for JPEG and WebP. */
|
|
20
14
|
quality?: number;
|
|
21
15
|
/** `image/jpeg`, `image/png` or `image/webp`. By default, the format of the source. */
|
|
22
16
|
type?: string;
|
|
23
17
|
}
|
|
24
|
-
/**
|
|
18
|
+
/**
|
|
19
|
+
* The image that editing produces, which the `apply` event carries.
|
|
20
|
+
*
|
|
21
|
+
* @see https://paperpic.dev/reference/events#apply
|
|
22
|
+
*/
|
|
25
23
|
interface ExportedImage {
|
|
24
|
+
/** The edited image, ready to upload. */
|
|
26
25
|
blob: Blob;
|
|
26
|
+
/** In pixels. */
|
|
27
27
|
height: number;
|
|
28
28
|
/** The format of `blob`. A browser that cannot encode the requested one gives PNG. */
|
|
29
29
|
type: string;
|
|
30
|
+
/** In pixels. */
|
|
30
31
|
width: number;
|
|
31
32
|
}
|
|
32
|
-
/**
|
|
33
|
+
/**
|
|
34
|
+
* A width and a height in pixels.
|
|
35
|
+
*
|
|
36
|
+
* @see https://paperpic.dev/reference/types#size
|
|
37
|
+
*/
|
|
33
38
|
interface Size {
|
|
34
39
|
height: number;
|
|
35
40
|
width: number;
|
|
36
41
|
}
|
|
37
|
-
/**
|
|
42
|
+
/**
|
|
43
|
+
* A position in CSS pixels, relative to the top left corner of the viewer.
|
|
44
|
+
*
|
|
45
|
+
* @see https://paperpic.dev/reference/methods#zoomto
|
|
46
|
+
*/
|
|
38
47
|
interface ViewPoint {
|
|
39
48
|
x: number;
|
|
40
49
|
y: number;
|
|
41
50
|
}
|
|
42
|
-
/**
|
|
51
|
+
/**
|
|
52
|
+
* How the image adapts to the viewer: the whole image, its width or its height.
|
|
53
|
+
*
|
|
54
|
+
* @see https://paperpic.dev/reference/methods#fit
|
|
55
|
+
*/
|
|
43
56
|
type Fit = 'image' | 'width' | 'height';
|
|
44
|
-
/**
|
|
57
|
+
/**
|
|
58
|
+
* Every text the component shows or announces. The texts with values are functions.
|
|
59
|
+
*
|
|
60
|
+
* @see https://paperpic.dev/reference/labels
|
|
61
|
+
*/
|
|
45
62
|
interface PaperPicLabels {
|
|
46
63
|
/** Opens the ruler of brightness and contrast. */
|
|
47
64
|
adjust: string;
|
|
@@ -115,9 +132,17 @@ interface PaperPicLabels {
|
|
|
115
132
|
zoomLevel: (percent: number) => string;
|
|
116
133
|
zoomOut: string;
|
|
117
134
|
}
|
|
118
|
-
/**
|
|
135
|
+
/**
|
|
136
|
+
* The tools the edit bar can offer. `perspective` is Straighten, and `threshold` is Clean up.
|
|
137
|
+
*
|
|
138
|
+
* @see https://paperpic.dev/reference/options#tools
|
|
139
|
+
*/
|
|
119
140
|
type ToolId = 'adjust' | 'crop' | 'flip' | 'perspective' | 'rotate' | 'threshold';
|
|
120
|
-
/**
|
|
141
|
+
/**
|
|
142
|
+
* Every icon of the interface, as the markup of one element, such as an `<svg>`. One icon can appear on several buttons.
|
|
143
|
+
*
|
|
144
|
+
* @see https://paperpic.dev/reference/options#icons
|
|
145
|
+
*/
|
|
121
146
|
interface PaperPicIcons {
|
|
122
147
|
/** Adjust, which opens the ruler of brightness and contrast. */
|
|
123
148
|
adjust: string;
|
|
@@ -151,9 +176,18 @@ interface PaperPicIcons {
|
|
|
151
176
|
zoomIn: string;
|
|
152
177
|
zoomOut: string;
|
|
153
178
|
}
|
|
154
|
-
/**
|
|
155
|
-
|
|
156
|
-
|
|
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
|
+
/**
|
|
186
|
+
* What the constructor and `setOptions()` take.
|
|
187
|
+
*
|
|
188
|
+
* @see https://paperpic.dev/reference/options
|
|
189
|
+
*/
|
|
190
|
+
interface PaperPicOptions {
|
|
157
191
|
/** Describes the image for screen readers. Without it, they skip the image, as they skip an `<img>` with an empty `alt`. */
|
|
158
192
|
alt?: string;
|
|
159
193
|
/** The real proportions of the document, as width divided by height, such as `210 / 297` for A4. Without it, straightening estimates them. */
|
|
@@ -192,8 +226,12 @@ export interface PaperPicOptions {
|
|
|
192
226
|
/** Whether the wheel zooms. Turn it off when the viewer sits in a long page. */
|
|
193
227
|
wheelZoom?: boolean;
|
|
194
228
|
}
|
|
195
|
-
/**
|
|
196
|
-
|
|
229
|
+
/**
|
|
230
|
+
* What the viewer is showing, which `getState()` returns and the `change` event carries.
|
|
231
|
+
*
|
|
232
|
+
* @see https://paperpic.dev/reference/state
|
|
233
|
+
*/
|
|
234
|
+
interface PaperPicState {
|
|
197
235
|
/** The open tool, such as Crop or Adjust, or `null`. Done or Cancel closes it. */
|
|
198
236
|
activeTool: ToolId | null;
|
|
199
237
|
/**
|
|
@@ -208,7 +246,9 @@ export interface PaperPicState {
|
|
|
208
246
|
busy: boolean;
|
|
209
247
|
/** Whether there are changes to apply. Rotations that cancel out are no change. */
|
|
210
248
|
canApply: boolean;
|
|
249
|
+
/** Whether there is an edit to bring back. */
|
|
211
250
|
canRedo: boolean;
|
|
251
|
+
/** Whether there is an edit to undo. */
|
|
212
252
|
canUndo: boolean;
|
|
213
253
|
/** The fit in effect, or `null` once the user has zoomed by hand. */
|
|
214
254
|
fit: Fit | null;
|
|
@@ -216,7 +256,9 @@ export interface PaperPicState {
|
|
|
216
256
|
image: Size | null;
|
|
217
257
|
/** Whether the user is viewing or editing the image. */
|
|
218
258
|
mode: 'view' | 'edit';
|
|
259
|
+
/** How far the image on display is turned, in degrees clockwise. */
|
|
219
260
|
rotation: Rotation;
|
|
261
|
+
/** Whether there is an image, and whether it loaded. */
|
|
220
262
|
status: 'empty' | 'loading' | 'ready' | 'error';
|
|
221
263
|
/** Whether the document gets cleaned up, and how much. While Clean up is open, what it shows, which Done would keep. */
|
|
222
264
|
threshold: {
|
|
@@ -226,7 +268,12 @@ export interface PaperPicState {
|
|
|
226
268
|
/** Screen pixels per image pixel. */
|
|
227
269
|
zoom: number;
|
|
228
270
|
}
|
|
229
|
-
|
|
271
|
+
/**
|
|
272
|
+
* Each event of `on()`, with what it carries.
|
|
273
|
+
*
|
|
274
|
+
* @see https://paperpic.dev/reference/events
|
|
275
|
+
*/
|
|
276
|
+
interface PaperPicEvents {
|
|
230
277
|
/** The user applied the changes. The result is already on display. */
|
|
231
278
|
apply: ExportedImage;
|
|
232
279
|
/** The user changed the view or the edit. `setOptions()` never triggers it. */
|
|
@@ -238,10 +285,7 @@ export interface PaperPicEvents {
|
|
|
238
285
|
error: Error;
|
|
239
286
|
};
|
|
240
287
|
/** The image is ready. */
|
|
241
|
-
load:
|
|
242
|
-
height: number;
|
|
243
|
-
width: number;
|
|
244
|
-
};
|
|
288
|
+
load: Size;
|
|
245
289
|
}
|
|
246
290
|
type Listener<Name extends keyof PaperPicEvents> = (payload: PaperPicEvents[Name]) => void;
|
|
247
291
|
/**
|
|
@@ -495,4 +539,17 @@ export declare class PaperPic {
|
|
|
495
539
|
/** Runs a key's command. Returns whether it did something, so other keys keep their usual effect. */
|
|
496
540
|
private runKey;
|
|
497
541
|
}
|
|
498
|
-
|
|
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
|
+
export type { ExportedImage, Fit, PaperPicDownload, PaperPicEvents, PaperPicIcons, PaperPicLabels, PaperPicOptions, PaperPicOutput, PaperPicSource, PaperPicState, Rotation, Size, ToolId, ViewPoint };
|
package/dist/index.js
CHANGED
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@paperpic/core",
|
|
3
3
|
"type": "module",
|
|
4
|
-
"version": "0.
|
|
4
|
+
"version": "0.2.0",
|
|
5
5
|
"description": "Framework-agnostic document image viewer and editor, for use with plain JavaScript or through a PaperPic wrapper.",
|
|
6
6
|
"author": "Marco Caparrós <hello@paperpic.dev>",
|
|
7
7
|
"license": "MIT",
|