@paperpic/vue 0.3.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 +9 -3
- package/dist/docs/examples/custom-toolbar.md +13 -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 +4 -4
- package/dist/docs/guide/editing.md +8 -8
- package/dist/docs/guide/getting-started.md +3 -3
- package/dist/docs/guide/introduction.md +1 -1
- package/dist/docs/guide/labels.md +2 -4
- package/dist/docs/guide/loading.md +4 -2
- package/dist/docs/guide/saving.md +11 -9
- package/dist/docs/guide/tools/adjust.md +2 -2
- package/dist/docs/guide/tools/clean-up.md +1 -1
- package/dist/docs/guide/tools/crop.md +1 -1
- package/dist/docs/guide/tools/straighten.md +1 -1
- package/dist/docs/guide/troubleshooting.md +2 -2
- package/dist/docs/guide/viewer.md +12 -10
- package/dist/docs/reference/events.md +13 -4
- package/dist/docs/reference/labels.md +2 -2
- package/dist/docs/reference/methods.md +68 -12
- package/dist/docs/reference/options.md +7 -7
- package/dist/docs/reference/react.md +6 -2
- package/dist/docs/reference/state.md +113 -19
- package/dist/docs/reference/types.md +1 -1
- package/dist/docs/reference/vue.md +6 -4
- package/package.json +2 -2
|
@@ -35,6 +35,7 @@ const pic = new PaperPic(document.querySelector<HTMLElement>('#viewer')!, {
|
|
|
35
35
|
|
|
36
36
|
input.addEventListener('change', () => {
|
|
37
37
|
const file = input.files?.[0]
|
|
38
|
+
input.value = ''
|
|
38
39
|
if (file) {
|
|
39
40
|
status.textContent = ''
|
|
40
41
|
pic.setOptions({ src: file })
|
|
@@ -76,7 +77,9 @@ const photo = shallowRef<File>()
|
|
|
76
77
|
const status = shallowRef('')
|
|
77
78
|
|
|
78
79
|
function choose(event: Event) {
|
|
79
|
-
const
|
|
80
|
+
const input = event.target as HTMLInputElement
|
|
81
|
+
const file = input.files?.[0]
|
|
82
|
+
input.value = ''
|
|
80
83
|
if (file) {
|
|
81
84
|
status.value = ''
|
|
82
85
|
photo.value = file
|
|
@@ -136,7 +139,9 @@ export function AttachDocument() {
|
|
|
136
139
|
const [photo, setPhoto] = useState<File>()
|
|
137
140
|
const [status, setStatus] = useState('')
|
|
138
141
|
|
|
139
|
-
function choose(
|
|
142
|
+
function choose(input: HTMLInputElement) {
|
|
143
|
+
const file = input.files?.[0]
|
|
144
|
+
input.value = ''
|
|
140
145
|
if (file) {
|
|
141
146
|
setStatus('')
|
|
142
147
|
setPhoto(file)
|
|
@@ -164,7 +169,7 @@ export function AttachDocument() {
|
|
|
164
169
|
<>
|
|
165
170
|
<label>
|
|
166
171
|
Photo of the document
|
|
167
|
-
<input type="file" accept="image/*" capture="environment" onChange={event => choose(event.target
|
|
172
|
+
<input type="file" accept="image/*" capture="environment" onChange={event => choose(event.target)} />
|
|
168
173
|
</label>
|
|
169
174
|
{photo && (
|
|
170
175
|
<div style={{ height: 480 }}>
|
|
@@ -190,6 +195,7 @@ export function AttachDocument() {
|
|
|
190
195
|
## Notes
|
|
191
196
|
|
|
192
197
|
- `capture="environment"` opens the back camera on phones, and computers ignore it. Without it, phones offer the camera and the photo library, which suits documents the user already has.
|
|
198
|
+
- Emptying the input after each choice lets the user pick the same photo again, such as to start over after Apply.
|
|
193
199
|
- The viewer opens in the edit mode once the photo loads, so the user goes straight to Straighten or Clean up. Leave out the `load` listener to show the photo first.
|
|
194
200
|
- `phase: 'load'` tells a file the browser cannot open, such as a HEIC photo outside Safari, from a failed edit. [Loading images](../guide/loading#formats) lists the formats.
|
|
195
201
|
- The photo stays in the browser until Apply calls `upload`. PaperPic sends nothing on its own.
|
|
@@ -19,6 +19,7 @@ The [`change`](../reference/events#change) event carries the [state](../referenc
|
|
|
19
19
|
<button type="button" data-action="edit">Edit</button>
|
|
20
20
|
<button type="button" data-action="straighten">Straighten</button>
|
|
21
21
|
<button type="button" data-action="confirmTool">Done</button>
|
|
22
|
+
<button type="button" data-action="cancelTool">Cancel this tool</button>
|
|
22
23
|
<button type="button" data-action="undo">Undo</button>
|
|
23
24
|
<button type="button" data-action="cancel">Cancel</button>
|
|
24
25
|
<button type="button" data-action="apply">Apply</button>
|
|
@@ -43,6 +44,7 @@ const actions: Record<string, () => void> = {
|
|
|
43
44
|
edit: () => pic.edit(),
|
|
44
45
|
straighten: () => pic.openTool('perspective'),
|
|
45
46
|
confirmTool: () => pic.confirmTool(),
|
|
47
|
+
cancelTool: () => pic.cancelTool(),
|
|
46
48
|
undo: () => pic.undo(),
|
|
47
49
|
cancel: () => pic.cancel(),
|
|
48
50
|
apply: () => pic.apply(),
|
|
@@ -61,6 +63,7 @@ function update({ status, mode, activeTool, canUndo, canApply, busy }: PaperPicS
|
|
|
61
63
|
edit: !editing,
|
|
62
64
|
straighten: editing && !activeTool,
|
|
63
65
|
confirmTool: Boolean(activeTool),
|
|
66
|
+
cancelTool: Boolean(activeTool),
|
|
64
67
|
undo: editing && !activeTool,
|
|
65
68
|
cancel: editing && !activeTool,
|
|
66
69
|
apply: editing && !activeTool,
|
|
@@ -115,6 +118,9 @@ function refresh() {
|
|
|
115
118
|
<button type="button" @click="viewer?.confirmTool()">
|
|
116
119
|
Done
|
|
117
120
|
</button>
|
|
121
|
+
<button type="button" @click="viewer?.cancelTool()">
|
|
122
|
+
Cancel this tool
|
|
123
|
+
</button>
|
|
118
124
|
</template>
|
|
119
125
|
<template v-else>
|
|
120
126
|
<button type="button" @click="viewer?.openTool('perspective')">
|
|
@@ -173,7 +179,10 @@ export function Receipt() {
|
|
|
173
179
|
<button type="button" disabled={state.status !== 'ready'} onClick={() => viewer().edit()}>Edit</button>
|
|
174
180
|
)}
|
|
175
181
|
{state.mode === 'edit' && state.activeTool && (
|
|
176
|
-
|
|
182
|
+
<>
|
|
183
|
+
<button type="button" onClick={() => viewer().confirmTool()}>Done</button>
|
|
184
|
+
<button type="button" onClick={() => viewer().cancelTool()}>Cancel this tool</button>
|
|
185
|
+
</>
|
|
177
186
|
)}
|
|
178
187
|
{state.mode === 'edit' && !state.activeTool && (
|
|
179
188
|
<>
|
|
@@ -313,6 +322,7 @@ function cancel() {
|
|
|
313
322
|
:toolbar="false"
|
|
314
323
|
@change="next => (state = next)"
|
|
315
324
|
@load="state = viewer?.getState()"
|
|
325
|
+
@error="state = viewer?.getState()"
|
|
316
326
|
/>
|
|
317
327
|
</div>
|
|
318
328
|
</template>
|
|
@@ -377,6 +387,7 @@ export function CleanUpRuler() {
|
|
|
377
387
|
toolbar={false}
|
|
378
388
|
onChange={setState}
|
|
379
389
|
onLoad={() => setState(viewer().getState())}
|
|
390
|
+
onError={() => setState(viewer().getState())}
|
|
380
391
|
/>
|
|
381
392
|
</div>
|
|
382
393
|
</>
|
|
@@ -388,7 +399,7 @@ export function CleanUpRuler() {
|
|
|
388
399
|
|
|
389
400
|
## Notes
|
|
390
401
|
|
|
391
|
-
- With `toolbar: false`, the built-in edit bar is hidden too, so Crop and Straighten show their handles but no Done button. Your interface confirms them with [`confirmTool()`](../reference/methods#confirmtool), as `Enter` does.
|
|
402
|
+
- With `toolbar: false`, the built-in edit bar is hidden too, so Crop and Straighten show their handles but no Done button. Your interface confirms them with [`confirmTool()`](../reference/methods#confirmtool), as `Enter` does. To close them without their changes, call [`cancelTool()`](../reference/methods#canceltool), as `Esc` does.
|
|
392
403
|
- Sliders of your own can call [`setThreshold()`](../reference/methods#setthreshold) and [`setAdjustments()`](../reference/methods#setadjustments) directly, which adds one edit for each call. To leave one edit for a whole drag, open the tool with [`openTool()`](../reference/methods#opentool) first: the same methods then change what it shows, and `confirmTool()` keeps it.
|
|
393
404
|
- [`cancel()`](../reference/methods#cancel) does not ask before discarding the edits. Ask the user first if there are some, such as when `canApply` is true.
|
|
394
405
|
- The keyboard shortcuts keep working with the focus on the viewer. See [Accessibility](../guide/accessibility).
|
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Edit in a dialog
|
|
3
|
+
description: A complete example that opens PaperPic in a dialog to edit a photo, and closes the dialog when the user applies or cancels the changes, in plain JavaScript, Vue and React.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Edit in a dialog
|
|
7
|
+
|
|
8
|
+
Many apps edit a document in a dialog over the page, such as from a list of attachments. This example opens the viewer in a `<dialog>`, starts the edit mode, and closes the dialog when the user applies the changes or cancels them.
|
|
9
|
+
|
|
10
|
+
`upload` is the function from [Upload to a server](./upload).
|
|
11
|
+
|
|
12
|
+
:::tabs key:framework
|
|
13
|
+
== JavaScript
|
|
14
|
+
|
|
15
|
+
```html
|
|
16
|
+
<button id="open" type="button">Edit the photo</button>
|
|
17
|
+
<dialog id="editor">
|
|
18
|
+
<div id="viewer" style="width: min(90vw, 720px); height: 70vh"></div>
|
|
19
|
+
</dialog>
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
```ts
|
|
23
|
+
import { PaperPic } from '@paperpic/core'
|
|
24
|
+
import '@paperpic/core/style.css'
|
|
25
|
+
|
|
26
|
+
const dialog = document.querySelector<HTMLDialogElement>('#editor')!
|
|
27
|
+
const pic = new PaperPic(document.querySelector<HTMLElement>('#viewer')!, {
|
|
28
|
+
src: '/receipt.jpg',
|
|
29
|
+
alt: 'A receipt',
|
|
30
|
+
})
|
|
31
|
+
let editing = false
|
|
32
|
+
|
|
33
|
+
document.querySelector('#open')!.addEventListener('click', () => {
|
|
34
|
+
dialog.showModal()
|
|
35
|
+
pic.edit()
|
|
36
|
+
})
|
|
37
|
+
|
|
38
|
+
// A photo still loading starts the edit once it is on display
|
|
39
|
+
pic.on('load', () => {
|
|
40
|
+
if (dialog.open) {
|
|
41
|
+
pic.edit()
|
|
42
|
+
}
|
|
43
|
+
})
|
|
44
|
+
|
|
45
|
+
// Apply or Cancel ends the edit, and the dialog closes with it
|
|
46
|
+
pic.on('change', ({ mode }) => {
|
|
47
|
+
if (editing && mode === 'view') {
|
|
48
|
+
dialog.close()
|
|
49
|
+
}
|
|
50
|
+
editing = mode === 'edit'
|
|
51
|
+
})
|
|
52
|
+
|
|
53
|
+
// While editing, Esc goes to the viewer, which asks before discarding the changes
|
|
54
|
+
dialog.addEventListener('cancel', (event) => {
|
|
55
|
+
if (editing) {
|
|
56
|
+
event.preventDefault()
|
|
57
|
+
}
|
|
58
|
+
})
|
|
59
|
+
|
|
60
|
+
pic.on('apply', ({ blob, type }) => upload(blob, type))
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
== Vue
|
|
64
|
+
|
|
65
|
+
```vue
|
|
66
|
+
<script setup lang="ts">
|
|
67
|
+
import type { PaperPicState } from '@paperpic/vue'
|
|
68
|
+
import { PaperPic } from '@paperpic/vue'
|
|
69
|
+
import { useTemplateRef } from 'vue'
|
|
70
|
+
import '@paperpic/vue/style.css'
|
|
71
|
+
|
|
72
|
+
const dialog = useTemplateRef('dialog')
|
|
73
|
+
const pic = useTemplateRef('pic')
|
|
74
|
+
let editing = false
|
|
75
|
+
|
|
76
|
+
function open() {
|
|
77
|
+
dialog.value?.showModal()
|
|
78
|
+
pic.value?.instance?.edit()
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
// A photo still loading starts the edit once it is on display
|
|
82
|
+
function loaded() {
|
|
83
|
+
if (dialog.value?.open) {
|
|
84
|
+
pic.value?.instance?.edit()
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
// Apply or Cancel ends the edit, and the dialog closes with it
|
|
89
|
+
function changed({ mode }: PaperPicState) {
|
|
90
|
+
if (editing && mode === 'view') {
|
|
91
|
+
dialog.value?.close()
|
|
92
|
+
}
|
|
93
|
+
editing = mode === 'edit'
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
// While editing, Esc goes to the viewer, which asks before discarding the changes
|
|
97
|
+
function keepEditing(event: Event) {
|
|
98
|
+
if (editing) {
|
|
99
|
+
event.preventDefault()
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
</script>
|
|
103
|
+
|
|
104
|
+
<template>
|
|
105
|
+
<button type="button" @click="open">
|
|
106
|
+
Edit the photo
|
|
107
|
+
</button>
|
|
108
|
+
<dialog ref="dialog" @cancel="keepEditing">
|
|
109
|
+
<div style="width: min(90vw, 720px); height: 70vh">
|
|
110
|
+
<PaperPic
|
|
111
|
+
ref="pic"
|
|
112
|
+
src="/receipt.jpg"
|
|
113
|
+
alt="A receipt"
|
|
114
|
+
@load="loaded"
|
|
115
|
+
@change="changed"
|
|
116
|
+
@apply="({ blob, type }) => upload(blob, type)"
|
|
117
|
+
/>
|
|
118
|
+
</div>
|
|
119
|
+
</dialog>
|
|
120
|
+
</template>
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
== React
|
|
124
|
+
|
|
125
|
+
```tsx
|
|
126
|
+
import type { PaperPicInstance, PaperPicState } from '@paperpic/react'
|
|
127
|
+
import type { SyntheticEvent } from 'react'
|
|
128
|
+
import { PaperPic } from '@paperpic/react'
|
|
129
|
+
import { useRef } from 'react'
|
|
130
|
+
import '@paperpic/react/style.css'
|
|
131
|
+
|
|
132
|
+
export function PhotoEditor() {
|
|
133
|
+
const dialogRef = useRef<HTMLDialogElement>(null)
|
|
134
|
+
const picRef = useRef<PaperPicInstance>(null)
|
|
135
|
+
const editing = useRef(false)
|
|
136
|
+
|
|
137
|
+
function open() {
|
|
138
|
+
dialogRef.current?.showModal()
|
|
139
|
+
picRef.current?.edit()
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
// A photo still loading starts the edit once it is on display
|
|
143
|
+
function loaded() {
|
|
144
|
+
if (dialogRef.current?.open) {
|
|
145
|
+
picRef.current?.edit()
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
// Apply or Cancel ends the edit, and the dialog closes with it
|
|
150
|
+
function changed({ mode }: PaperPicState) {
|
|
151
|
+
if (editing.current && mode === 'view') {
|
|
152
|
+
dialogRef.current?.close()
|
|
153
|
+
}
|
|
154
|
+
editing.current = mode === 'edit'
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
// While editing, Esc goes to the viewer, which asks before discarding the changes
|
|
158
|
+
function keepEditing(event: SyntheticEvent<HTMLDialogElement>) {
|
|
159
|
+
if (editing.current) {
|
|
160
|
+
event.preventDefault()
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
return (
|
|
165
|
+
<>
|
|
166
|
+
<button type="button" onClick={open}>Edit the photo</button>
|
|
167
|
+
<dialog ref={dialogRef} onCancel={keepEditing}>
|
|
168
|
+
<div style={{ width: 'min(90vw, 720px)', height: '70vh' }}>
|
|
169
|
+
<PaperPic
|
|
170
|
+
ref={picRef}
|
|
171
|
+
src="/receipt.jpg"
|
|
172
|
+
alt="A receipt"
|
|
173
|
+
onLoad={loaded}
|
|
174
|
+
onChange={changed}
|
|
175
|
+
onApply={({ blob, type }) => upload(blob, type)}
|
|
176
|
+
/>
|
|
177
|
+
</div>
|
|
178
|
+
</dialog>
|
|
179
|
+
</>
|
|
180
|
+
)
|
|
181
|
+
}
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
:::
|
|
185
|
+
|
|
186
|
+
## Notes
|
|
187
|
+
|
|
188
|
+
- The viewer can live in the dialog while it is closed. It has no size then, and it fits the image as soon as the dialog opens.
|
|
189
|
+
- Opening the dialog starts the edit mode. If the photo is still loading, the `load` event starts it instead.
|
|
190
|
+
- Apply and Cancel end the edit, and the [`change`](../reference/events#change) that follows closes the dialog. If Apply fails, the edit stays open, and so does the dialog.
|
|
191
|
+
- Each opening edits the image on display, which after an Apply is the result. To start from the original every time, call [`reload()`](../reference/methods#reload) before `edit()`.
|
|
@@ -116,5 +116,6 @@ export function Form() {
|
|
|
116
116
|
|
|
117
117
|
- Straighten stores the proportions when the user presses Done, so choose the type before straightening. Changing it later affects only the next straightening.
|
|
118
118
|
- For a document in landscape, swap the numbers, such as `297 / 210`.
|
|
119
|
+
- The proportions apply to the page as it shows on screen. If the photo is sideways, turn it with Rotate left before you use Straighten, or a sheet in portrait comes out squashed.
|
|
119
120
|
- Leave `aspectRatio` out for documents without a fixed size, such as receipts, and Straighten estimates them.
|
|
120
121
|
- [Straighten](../guide/tools/straighten) explains the estimate and how to handle corners that fall outside the photo.
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Send with a form
|
|
3
|
+
description: A complete example where the photo of a receipt goes in a form field, the user edits it in PaperPic, and the form sends the edited image without any code of its own, in plain JavaScript, Vue and React.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Send with a form
|
|
7
|
+
|
|
8
|
+
Some apps send documents with a plain form, such as an expense with its receipt, and have no code of their own to upload a file. This example keeps the photo in the file field of the form, and puts the edited image back in that field when the user applies the changes, so the form sends it as it would any file.
|
|
9
|
+
|
|
10
|
+
:::tabs key:framework
|
|
11
|
+
== JavaScript
|
|
12
|
+
|
|
13
|
+
```html
|
|
14
|
+
<form action="/api/expenses" method="post" enctype="multipart/form-data">
|
|
15
|
+
<label>
|
|
16
|
+
Amount
|
|
17
|
+
<input name="amount" type="number" step="0.01" required />
|
|
18
|
+
</label>
|
|
19
|
+
<label>
|
|
20
|
+
Receipt
|
|
21
|
+
<input id="receipt" name="receipt" type="file" accept="image/*" required />
|
|
22
|
+
</label>
|
|
23
|
+
<div id="viewer" style="height: 480px"></div>
|
|
24
|
+
<button type="submit">Send</button>
|
|
25
|
+
</form>
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
```ts
|
|
29
|
+
import { PaperPic } from '@paperpic/core'
|
|
30
|
+
import '@paperpic/core/style.css'
|
|
31
|
+
|
|
32
|
+
const input = document.querySelector<HTMLInputElement>('#receipt')!
|
|
33
|
+
const pic = new PaperPic(document.querySelector<HTMLElement>('#viewer')!, {
|
|
34
|
+
alt: 'The receipt you attached',
|
|
35
|
+
maxOutputSize: 3000,
|
|
36
|
+
})
|
|
37
|
+
|
|
38
|
+
input.addEventListener('change', () => {
|
|
39
|
+
const file = input.files?.[0]
|
|
40
|
+
if (file) {
|
|
41
|
+
pic.setOptions({ src: file })
|
|
42
|
+
}
|
|
43
|
+
})
|
|
44
|
+
|
|
45
|
+
// The form sends the edited image in place of the photo
|
|
46
|
+
pic.on('apply', ({ blob, type }) => {
|
|
47
|
+
const name = input.files?.[0]?.name.replace(/\.\w+$/, '') ?? 'receipt'
|
|
48
|
+
const files = new DataTransfer()
|
|
49
|
+
files.items.add(new File([blob], `${name}.${type.split('/')[1]}`, { type }))
|
|
50
|
+
input.files = files.files
|
|
51
|
+
})
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
== Vue
|
|
55
|
+
|
|
56
|
+
```vue
|
|
57
|
+
<script setup lang="ts">
|
|
58
|
+
import type { ExportedImage } from '@paperpic/vue'
|
|
59
|
+
import { PaperPic } from '@paperpic/vue'
|
|
60
|
+
import { shallowRef, useTemplateRef } from 'vue'
|
|
61
|
+
import '@paperpic/vue/style.css'
|
|
62
|
+
|
|
63
|
+
const input = useTemplateRef('input')
|
|
64
|
+
const photo = shallowRef<File>()
|
|
65
|
+
|
|
66
|
+
function choose() {
|
|
67
|
+
photo.value = input.value?.files?.[0]
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
// The form sends the edited image in place of the photo
|
|
71
|
+
function applied({ blob, type }: ExportedImage) {
|
|
72
|
+
const field = input.value
|
|
73
|
+
if (!field) {
|
|
74
|
+
return
|
|
75
|
+
}
|
|
76
|
+
const name = field.files?.[0]?.name.replace(/\.\w+$/, '') ?? 'receipt'
|
|
77
|
+
const files = new DataTransfer()
|
|
78
|
+
files.items.add(new File([blob], `${name}.${type.split('/')[1]}`, { type }))
|
|
79
|
+
field.files = files.files
|
|
80
|
+
}
|
|
81
|
+
</script>
|
|
82
|
+
|
|
83
|
+
<template>
|
|
84
|
+
<form action="/api/expenses" method="post" enctype="multipart/form-data">
|
|
85
|
+
<label>
|
|
86
|
+
Amount
|
|
87
|
+
<input name="amount" type="number" step="0.01" required>
|
|
88
|
+
</label>
|
|
89
|
+
<label>
|
|
90
|
+
Receipt
|
|
91
|
+
<input ref="input" name="receipt" type="file" accept="image/*" required @change="choose">
|
|
92
|
+
</label>
|
|
93
|
+
<div v-if="photo" style="height: 480px">
|
|
94
|
+
<PaperPic :src="photo" alt="The receipt you attached" :max-output-size="3000" @apply="applied" />
|
|
95
|
+
</div>
|
|
96
|
+
<button type="submit">
|
|
97
|
+
Send
|
|
98
|
+
</button>
|
|
99
|
+
</form>
|
|
100
|
+
</template>
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
== React
|
|
104
|
+
|
|
105
|
+
```tsx
|
|
106
|
+
import type { ExportedImage } from '@paperpic/react'
|
|
107
|
+
import { PaperPic } from '@paperpic/react'
|
|
108
|
+
import { useRef, useState } from 'react'
|
|
109
|
+
import '@paperpic/react/style.css'
|
|
110
|
+
|
|
111
|
+
export function ExpenseForm() {
|
|
112
|
+
const inputRef = useRef<HTMLInputElement>(null)
|
|
113
|
+
const [photo, setPhoto] = useState<File>()
|
|
114
|
+
|
|
115
|
+
// The form sends the edited image in place of the photo
|
|
116
|
+
function applied({ blob, type }: ExportedImage) {
|
|
117
|
+
const input = inputRef.current
|
|
118
|
+
if (!input) {
|
|
119
|
+
return
|
|
120
|
+
}
|
|
121
|
+
const name = input.files?.[0]?.name.replace(/\.\w+$/, '') ?? 'receipt'
|
|
122
|
+
const files = new DataTransfer()
|
|
123
|
+
files.items.add(new File([blob], `${name}.${type.split('/')[1]}`, { type }))
|
|
124
|
+
input.files = files.files
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
return (
|
|
128
|
+
<form action="/api/expenses" method="post" encType="multipart/form-data">
|
|
129
|
+
<label>
|
|
130
|
+
Amount
|
|
131
|
+
<input name="amount" type="number" step="0.01" required />
|
|
132
|
+
</label>
|
|
133
|
+
<label>
|
|
134
|
+
Receipt
|
|
135
|
+
<input ref={inputRef} name="receipt" type="file" accept="image/*" required onChange={event => setPhoto(event.target.files?.[0])} />
|
|
136
|
+
</label>
|
|
137
|
+
{photo && (
|
|
138
|
+
<div style={{ height: 480 }}>
|
|
139
|
+
<PaperPic src={photo} alt="The receipt you attached" maxOutputSize={3000} onApply={applied} />
|
|
140
|
+
</div>
|
|
141
|
+
)}
|
|
142
|
+
<button type="submit">Send</button>
|
|
143
|
+
</form>
|
|
144
|
+
)
|
|
145
|
+
}
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
:::
|
|
149
|
+
|
|
150
|
+
## Notes
|
|
151
|
+
|
|
152
|
+
- Apply puts the edited image in the file field with a [`DataTransfer`](https://developer.mozilla.org/docs/Web/API/DataTransfer), so the form sends it under the same name. Before any Apply, the form sends the photo as the user picked it.
|
|
153
|
+
- Changing the files of the field from code does not fire its `change` event, so the viewer keeps the result on display.
|
|
154
|
+
- The file keeps the name of the photo, with the extension of the result, such as `receipt.png` after Clean up.
|
|
155
|
+
- The buttons of the viewer never submit the form.
|
|
156
|
+
- [`maxOutputSize`](../reference/options#maxoutputsize) keeps the form light. Phone photos have 12 megapixels or more, and documents stay readable at 3000 pixels on the longest side.
|
|
@@ -127,4 +127,4 @@ export function Invoice() {
|
|
|
127
127
|
- `role="status"` makes screen readers announce the result of the upload.
|
|
128
128
|
- [`maxOutputSize`](../reference/options#maxoutputsize) keeps the file small. Documents stay readable at 3000 pixels on the longest side.
|
|
129
129
|
- After Apply, the history is empty, so the user cannot undo into the old image. To offer a retry button, keep the last `blob` and `type` and call `upload` again.
|
|
130
|
-
- The server receives PNG for a cleaned up document, and the format of the source
|
|
130
|
+
- The server receives PNG for a cleaned up document, and otherwise the format of the source when it is JPEG, PNG or WebP. Read [Saving the result](../guide/saving#format) to learn how PaperPic tells the format, and to choose another one.
|
|
@@ -7,7 +7,7 @@ description: How PaperPic works with the keyboard, screen readers and touch scre
|
|
|
7
7
|
|
|
8
8
|
People read and fix documents with a mouse, a finger, the keyboard or a screen reader. PaperPic aims at WCAG 2.2 AA, and most of the work is built in. This page lists what it does and what your app needs to add.
|
|
9
9
|
|
|
10
|
-
## What your app
|
|
10
|
+
## What your app needs to do
|
|
11
11
|
|
|
12
12
|
- **A description.** Pass [`alt`](../reference/options#alt), such as "Receipt from 5 November". Screen readers read it as the name of the image.
|
|
13
13
|
- **Texts in the user's language.** Screen readers announce the buttons and the changes, so translate them with [`labels`](./labels).
|
|
@@ -16,7 +16,7 @@ People read and fix documents with a mouse, a finger, the keyboard or a screen r
|
|
|
16
16
|
|
|
17
17
|
## Keyboard {#keyboard}
|
|
18
18
|
|
|
19
|
-
With the focus
|
|
19
|
+
With the focus inside the viewer:
|
|
20
20
|
|
|
21
21
|
| Key | Action |
|
|
22
22
|
| -------------------------- | ---------------------------------------------------------------------------- |
|
|
@@ -28,7 +28,7 @@ With the focus on the viewer:
|
|
|
28
28
|
| `Enter` | Confirm the open tool, or else apply the changes |
|
|
29
29
|
| `Esc` | Let go of a selected corner, close the open tool, or else cancel the changes |
|
|
30
30
|
|
|
31
|
-
On macOS, `Cmd` works like `Ctrl`. Before cancelling changes, `Esc` asks for confirmation. With `toolbar: false`, it
|
|
31
|
+
On macOS, `Cmd` works like `Ctrl`. With the focus on a button, `Enter` presses that button instead. Before cancelling changes, `Esc` asks for confirmation. With `toolbar: false`, `Esc` still closes a tool, but it does not cancel the edit: your interface decides.
|
|
32
32
|
|
|
33
33
|
- **Toolbar and edit bar.** Tab reaches each bar, and inside it the arrow keys move between the buttons, with `Home` and `End` for the first and the last.
|
|
34
34
|
- **Corner handles.** With Crop or Straighten open, Tab moves between the handles, and the arrow keys move the focused one 1 screen pixel, or 10 with Shift.
|
|
@@ -38,7 +38,7 @@ On macOS, `Cmd` works like `Ctrl`. Before cancelling changes, `Esc` asks for con
|
|
|
38
38
|
|
|
39
39
|
- The image has the role of an image, named by `alt`. Without `alt`, screen readers skip it.
|
|
40
40
|
- The toolbar and the edit bar have their own names, such as "Image controls" and "Editing controls".
|
|
41
|
-
- An announcement reports
|
|
41
|
+
- An announcement reports what the user cannot see by the focus alone: the loading of the image, the zoom level, the start of the edit mode, a selected corner and the position of a moved corner, the value of a ruler, the result of Apply, and any failure.
|
|
42
42
|
- The switch of Clean up has the role of a switch. A tool in use, which a dot marks on screen, is described as "In use".
|
|
43
43
|
|
|
44
44
|
## Touch screens
|
|
@@ -15,7 +15,7 @@ A photo of a document usually needs a few fixes before it is worth keeping. The
|
|
|
15
15
|
|
|
16
16
|
Nothing changes the image until Apply. Before that, the edits are a list that the viewer previews.
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
In a narrow viewer, the edit bar has two rows: the tools, or the panel of the open tool, above, and below, Cancel at the left and Apply, or Done, at the right. From 28rem wide, everything fits on one row. Either way, the bar keeps its height when a tool opens, so the image keeps its place. A dot marks Adjust and Clean up while their setting is in effect.
|
|
19
19
|
|
|
20
20
|
## Tools
|
|
21
21
|
|
|
@@ -70,7 +70,7 @@ export function Receipt() {
|
|
|
70
70
|
|
|
71
71
|
:::
|
|
72
72
|
|
|
73
|
-
Crop, Straighten, Adjust and Clean up open a panel in place of the tools
|
|
73
|
+
Crop, Straighten, Adjust and Clean up open a panel in place of the tools. While one of them is open, the other tools, Undo, Redo and Apply wait. Done, or `Enter`, adds what the tool chose to the edits, and Cancel this tool, or `Esc`, discards it.
|
|
74
74
|
|
|
75
75
|
Inside a panel, the image looks as the result will, Clean up included. Straighten is the exception: it shows the photo without Clean up, so the edges of the paper stay visible.
|
|
76
76
|
|
|
@@ -82,11 +82,11 @@ Apply cannot be interrupted. It blocks the controls and shows a message while it
|
|
|
82
82
|
|
|
83
83
|
## What your code receives
|
|
84
84
|
|
|
85
|
-
| Event | When
|
|
86
|
-
| -------- |
|
|
87
|
-
| `apply` | When the result is ready, with `{ blob, width, height, type }`
|
|
88
|
-
| `change` |
|
|
89
|
-
| `error` | When the image cannot be loaded, or an edit cannot be shown or applied
|
|
85
|
+
| Event | When |
|
|
86
|
+
| -------- | ---------------------------------------------------------------------- |
|
|
87
|
+
| `apply` | When the result is ready, with `{ blob, width, height, type }` |
|
|
88
|
+
| `change` | Each time the user or a method changes the [state](../reference/state) |
|
|
89
|
+
| `error` | When the image cannot be loaded, or an edit cannot be shown or applied |
|
|
90
90
|
|
|
91
91
|
:::tabs key:framework
|
|
92
92
|
== JavaScript
|
|
@@ -121,7 +121,7 @@ pic.on('error', ({ error }) => console.error(error))
|
|
|
121
121
|
## What discards the edits
|
|
122
122
|
|
|
123
123
|
- Cancel, after the user confirms, or [`cancel()`](../reference/methods#cancel), which does not ask.
|
|
124
|
-
- A new `src` while editing.
|
|
124
|
+
- A new `src`, or [`reload()`](../reference/methods#reload), while editing.
|
|
125
125
|
- A change of `editable` while editing.
|
|
126
126
|
|
|
127
127
|
After Apply, passing the same `src` again does nothing, so the result stays on display. [`reload()`](../reference/methods#reload) brings back the original.
|
|
@@ -96,7 +96,7 @@ The core also loads from a CDN that serves the files of the package as they are,
|
|
|
96
96
|
</script>
|
|
97
97
|
```
|
|
98
98
|
|
|
99
|
-
Browsers only start a worker from the origin of the page, so the editing runs on the main thread
|
|
99
|
+
Browsers only start a worker from the origin of the page, so with the package on a CDN the editing runs on the main thread: it works, but large photos freeze the page for a moment on Apply. Serve the files from your own origin, or use a bundler, to keep the worker. The Vue and React components need a bundler.
|
|
100
100
|
|
|
101
101
|
## Show an image
|
|
102
102
|
|
|
@@ -151,7 +151,7 @@ export function Receipt() {
|
|
|
151
151
|
|
|
152
152
|
:::
|
|
153
153
|
|
|
154
|
-
`src` takes a URL from the same origin as your page,
|
|
154
|
+
`src` takes a URL from the same origin as your page, a `File` that the user picks, such as from an `<input type="file">`, or a `Blob`. `alt` describes the image for screen readers. [Loading images](./loading) covers images from other origins, formats and load errors.
|
|
155
155
|
|
|
156
156
|
## Get the edited image
|
|
157
157
|
|
|
@@ -188,7 +188,7 @@ async function upload(blob: Blob) {
|
|
|
188
188
|
}
|
|
189
189
|
```
|
|
190
190
|
|
|
191
|
-
The `blob` keeps the format of the source, or is PNG when the user cleaned up the document.
|
|
191
|
+
The `blob` keeps the format of the source when it is JPEG, PNG or WebP, and is PNG when the user cleaned up the document. [Format and quality](./saving#format) explains how PaperPic tells the format, and the [`output`](../reference/options#output) option changes it.
|
|
192
192
|
|
|
193
193
|
## Remove the viewer {#destroy}
|
|
194
194
|
|
|
@@ -9,7 +9,7 @@ Photos of documents arrive skewed, shadowed and full of background. PaperPic sho
|
|
|
9
9
|
|
|
10
10
|
## What it does
|
|
11
11
|
|
|
12
|
-
- **View.** Zoom with the buttons, the wheel
|
|
12
|
+
- **View.** Zoom with the buttons, the wheel, a pinch, a double click or the keyboard, pan, and fit the whole image, its width or its height. A read-only viewer can also rotate the image.
|
|
13
13
|
- **Edit.** In the edit mode, the user can crop, straighten a photo taken at an angle, rotate, flip, adjust the brightness and the contrast, and clean up the document into black and white. Every edit can be undone until the user applies the changes.
|
|
14
14
|
- **Deliver.** Apply computes the result at full resolution and hands it to your code as a `Blob`. A download button can also save it.
|
|
15
15
|
|
|
@@ -71,7 +71,7 @@ const labels: Partial<PaperPicLabels> = {
|
|
|
71
71
|
|
|
72
72
|
## Follow the language of your app
|
|
73
73
|
|
|
74
|
-
When your app changes language, pass new
|
|
74
|
+
When your app changes language, pass the labels of the new language, and the viewer updates its texts at once. Keep one object of labels for each language, created once, so that each render passes the same object:
|
|
75
75
|
|
|
76
76
|
:::tabs key:framework
|
|
77
77
|
== JavaScript
|
|
@@ -103,11 +103,9 @@ const labels = computed(() => translations[locale.value])
|
|
|
103
103
|
|
|
104
104
|
```tsx
|
|
105
105
|
import { PaperPic } from '@paperpic/react'
|
|
106
|
-
import { useMemo } from 'react'
|
|
107
106
|
|
|
108
107
|
export function Receipt({ language }: { language: string }) {
|
|
109
|
-
|
|
110
|
-
return <PaperPic src="/receipt.jpg" labels={labels} />
|
|
108
|
+
return <PaperPic src="/receipt.jpg" labels={translations[language]} />
|
|
111
109
|
}
|
|
112
110
|
```
|
|
113
111
|
|
|
@@ -19,7 +19,7 @@ For a `File` or a `Blob`, PaperPic creates the `blob:` URL it needs, and frees i
|
|
|
19
19
|
|
|
20
20
|
## Images from another origin, or behind a login {#fetch}
|
|
21
21
|
|
|
22
|
-
PaperPic reads the pixels of the image to edit it. Browsers only allow that for an image from another origin when it arrives with CORS, which PaperPic does not request. Such an image shows, but
|
|
22
|
+
PaperPic reads the pixels of the image to edit it. Browsers only allow that for an image from another origin when it arrives with CORS, which PaperPic does not request. Such an image shows, but editing it fails: an [`error`](../reference/events#error) says so as soon as an edit needs its pixels, or on Apply.
|
|
23
23
|
|
|
24
24
|
Fetch the image yourself, and pass the `Blob` as `src`. This also covers images behind a login, because your request carries the cookies of the user:
|
|
25
25
|
|
|
@@ -119,10 +119,12 @@ export function Invoice() {
|
|
|
119
119
|
|
|
120
120
|
:::
|
|
121
121
|
|
|
122
|
+
`load` fires each time a `src` loads, also with [`reload()`](../reference/methods#reload), but not after Apply: the result arrives with the [`apply`](../reference/events#apply) event.
|
|
123
|
+
|
|
122
124
|
The `status` of [`getState()`](../reference/state) gives the same answer at any time: `'empty'`, `'loading'`, `'ready'` or `'error'`.
|
|
123
125
|
|
|
124
126
|
## Change or reload the image
|
|
125
127
|
|
|
126
128
|
- **A new `src`** loads the new image. While the user is editing, it discards the edits.
|
|
127
129
|
- **The same `src`** does nothing, so the result of Apply stays on display.
|
|
128
|
-
- **[`reload()`](../reference/methods#reload)** loads the current `src` again, which brings back the original after an Apply.
|
|
130
|
+
- **[`reload()`](../reference/methods#reload)** loads the current `src` again, which brings back the original after an Apply. While the user is editing, it discards the edits too.
|