@paperpic/vue 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 +3 -1
- package/package.json +3 -3
|
@@ -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
|
@@ -48,7 +48,7 @@ interface PaperPicProps {
|
|
|
48
48
|
src?: PaperPicSource$1;
|
|
49
49
|
/** Whether to show the built-in toolbar and edit bar. Without them, build your own with the methods of `instance`. */
|
|
50
50
|
toolbar?: boolean;
|
|
51
|
-
/** Which tools the edit bar offers. By default, all of them. */
|
|
51
|
+
/** Which tools the edit bar offers. By default, all of them. It only chooses the buttons: the methods work with every tool. */
|
|
52
52
|
tools?: readonly ToolId$1[];
|
|
53
53
|
/** Whether the wheel zooms. Turn it off when the viewer sits in a long page. */
|
|
54
54
|
wheelZoom?: boolean;
|
|
@@ -61,6 +61,7 @@ declare const __VLS_export: import("vue").DefineComponent<PaperPicProps, {
|
|
|
61
61
|
change: (payload: import("@paperpic/core").PaperPicState) => any;
|
|
62
62
|
error: (payload: {
|
|
63
63
|
error: Error;
|
|
64
|
+
phase: "load" | "preview" | "apply";
|
|
64
65
|
}) => any;
|
|
65
66
|
load: (payload: import("@paperpic/core").Size) => any;
|
|
66
67
|
}, string, import("vue").PublicProps, Readonly<PaperPicProps> & Readonly<{
|
|
@@ -69,6 +70,7 @@ declare const __VLS_export: import("vue").DefineComponent<PaperPicProps, {
|
|
|
69
70
|
onChange?: ((payload: import("@paperpic/core").PaperPicState) => any) | undefined;
|
|
70
71
|
onError?: ((payload: {
|
|
71
72
|
error: Error;
|
|
73
|
+
phase: "load" | "preview" | "apply";
|
|
72
74
|
}) => any) | undefined;
|
|
73
75
|
onLoad?: ((payload: import("@paperpic/core").Size) => any) | undefined;
|
|
74
76
|
}>, {
|
package/package.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@paperpic/vue",
|
|
3
3
|
"type": "module",
|
|
4
|
-
"version": "0.
|
|
5
|
-
"description": "Vue 3
|
|
4
|
+
"version": "0.3.1",
|
|
5
|
+
"description": "Vue 3 component to view and edit document images with PaperPic: straighten, crop and clean up phone photos, scans and any image with text.",
|
|
6
6
|
"author": "Marco Caparrós <hello@paperpic.dev>",
|
|
7
7
|
"license": "MIT",
|
|
8
8
|
"homepage": "https://paperpic.dev",
|
|
@@ -42,7 +42,7 @@
|
|
|
42
42
|
"vue": "^3.5.0"
|
|
43
43
|
},
|
|
44
44
|
"dependencies": {
|
|
45
|
-
"@paperpic/core": "0.
|
|
45
|
+
"@paperpic/core": "0.3.1"
|
|
46
46
|
},
|
|
47
47
|
"devDependencies": {
|
|
48
48
|
"@arethetypeswrong/core": "0.18.5",
|