@paperpic/core 0.0.0-stage → 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/LICENSE +21 -0
- package/README.md +32 -2
- package/dist/docs/examples/custom-toolbar.md +211 -0
- package/dist/docs/examples/fixed-proportions.md +120 -0
- package/dist/docs/examples/read-only.md +115 -0
- package/dist/docs/examples/upload.md +130 -0
- package/dist/docs/guide/accessibility.md +55 -0
- package/dist/docs/guide/editing.md +140 -0
- package/dist/docs/guide/getting-started.md +144 -0
- package/dist/docs/guide/introduction.md +36 -0
- package/dist/docs/guide/labels.md +120 -0
- package/dist/docs/guide/performance.md +39 -0
- package/dist/docs/guide/saving.md +186 -0
- package/dist/docs/guide/styling.md +266 -0
- package/dist/docs/guide/tools/adjust.md +41 -0
- package/dist/docs/guide/tools/clean-up.md +41 -0
- package/dist/docs/guide/tools/crop.md +39 -0
- package/dist/docs/guide/tools/rotate-and-flip.md +35 -0
- package/dist/docs/guide/tools/straighten.md +78 -0
- package/dist/docs/guide/viewer.md +81 -0
- package/dist/docs/reference/css-tokens.md +113 -0
- package/dist/docs/reference/events.md +68 -0
- package/dist/docs/reference/labels.md +70 -0
- package/dist/docs/reference/methods.md +228 -0
- package/dist/docs/reference/options.md +160 -0
- package/dist/docs/reference/react.md +84 -0
- package/dist/docs/reference/state.md +30 -0
- package/dist/docs/reference/types.md +301 -0
- package/dist/docs/reference/vue.md +78 -0
- package/dist/index.d.ts +555 -0
- package/dist/index.js +3165 -0
- package/dist/pipeline-MP1RPlXT.js +447 -0
- package/dist/style.css +702 -0
- package/dist/worker.d.ts +119 -0
- package/dist/worker.js +37 -0
- package/package.json +49 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 paperpic contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,33 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @paperpic/core
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Framework-agnostic document image viewer and editor, for use with plain JavaScript or through a PaperPic wrapper such as [`@paperpic/vue`](https://www.npmjs.com/package/@paperpic/vue) or [`@paperpic/react`](https://www.npmjs.com/package/@paperpic/react).
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
pnpm add @paperpic/core
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Usage
|
|
12
|
+
|
|
13
|
+
The viewer fills its container, so give the container a height:
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
import { PaperPic } from '@paperpic/core'
|
|
17
|
+
import '@paperpic/core/style.css'
|
|
18
|
+
|
|
19
|
+
const pic = new PaperPic(document.querySelector<HTMLElement>('#viewer')!, {
|
|
20
|
+
src: '/receipt.jpg',
|
|
21
|
+
alt: 'A receipt',
|
|
22
|
+
})
|
|
23
|
+
|
|
24
|
+
pic.on('apply', ({ blob }) => upload(blob))
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
The pencil opens the edit mode. When the user applies the changes, the result replaces the image on display and the `apply` event carries it. With `editable: false` it is a read-only viewer.
|
|
28
|
+
|
|
29
|
+
## Documentation
|
|
30
|
+
|
|
31
|
+
[paperpic.dev](https://paperpic.dev) has the [guide](https://paperpic.dev/guide/introduction), every [option](https://paperpic.dev/reference/options), [method](https://paperpic.dev/reference/methods) and [event](https://paperpic.dev/reference/events), and a [playground](https://paperpic.dev/playground).
|
|
32
|
+
|
|
33
|
+
The package also ships these docs in English, for the version you install, in `dist/docs`. AI coding tools can read them in `node_modules` without the network.
|
|
@@ -0,0 +1,211 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Custom toolbar
|
|
3
|
+
description: A complete example that hides the built-in toolbar of PaperPic and drives the viewer from buttons of your own, kept in step with the state of the viewer.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Custom toolbar
|
|
7
|
+
|
|
8
|
+
When the controls of the viewer must match the rest of your interface, hide the built-in ones with `toolbar: false` and call the [methods](../reference/methods) from buttons of your own. This example offers zoom, Straighten, Undo and Apply, and enables each button only when it can act.
|
|
9
|
+
|
|
10
|
+
The [`change`](../reference/events#change) event carries the [state](../reference/state) after each action, including those your buttons start. `load` and `error` report the moments when the image arrives or Apply fails.
|
|
11
|
+
|
|
12
|
+
:::tabs key:framework
|
|
13
|
+
== JavaScript
|
|
14
|
+
|
|
15
|
+
```html
|
|
16
|
+
<div id="controls">
|
|
17
|
+
<button type="button" data-action="zoomIn">Zoom in</button>
|
|
18
|
+
<button type="button" data-action="zoomOut">Zoom out</button>
|
|
19
|
+
<button type="button" data-action="edit">Edit</button>
|
|
20
|
+
<button type="button" data-action="straighten">Straighten</button>
|
|
21
|
+
<button type="button" data-action="confirmTool">Done</button>
|
|
22
|
+
<button type="button" data-action="undo">Undo</button>
|
|
23
|
+
<button type="button" data-action="cancel">Cancel</button>
|
|
24
|
+
<button type="button" data-action="apply">Apply</button>
|
|
25
|
+
</div>
|
|
26
|
+
<div id="viewer" style="height: 480px"></div>
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
```ts
|
|
30
|
+
import type { PaperPicState } from '@paperpic/core'
|
|
31
|
+
import { PaperPic } from '@paperpic/core'
|
|
32
|
+
import '@paperpic/core/style.css'
|
|
33
|
+
|
|
34
|
+
const pic = new PaperPic(document.querySelector<HTMLElement>('#viewer')!, {
|
|
35
|
+
src: '/receipt.jpg',
|
|
36
|
+
alt: 'A receipt',
|
|
37
|
+
toolbar: false,
|
|
38
|
+
})
|
|
39
|
+
|
|
40
|
+
const actions: Record<string, () => void> = {
|
|
41
|
+
zoomIn: () => pic.zoomIn(),
|
|
42
|
+
zoomOut: () => pic.zoomOut(),
|
|
43
|
+
edit: () => pic.edit(),
|
|
44
|
+
straighten: () => pic.openTool('perspective'),
|
|
45
|
+
confirmTool: () => pic.confirmTool(),
|
|
46
|
+
undo: () => pic.undo(),
|
|
47
|
+
cancel: () => pic.cancel(),
|
|
48
|
+
apply: () => pic.apply(),
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
const buttons = document.querySelectorAll<HTMLButtonElement>('[data-action]')
|
|
52
|
+
for (const button of buttons) {
|
|
53
|
+
button.addEventListener('click', () => actions[button.dataset.action!]!())
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
function update({ status, mode, activeTool, canUndo, canApply, busy }: PaperPicState) {
|
|
57
|
+
const editing = mode === 'edit'
|
|
58
|
+
const visible: Record<string, boolean> = {
|
|
59
|
+
zoomIn: true,
|
|
60
|
+
zoomOut: true,
|
|
61
|
+
edit: !editing,
|
|
62
|
+
straighten: editing && !activeTool,
|
|
63
|
+
confirmTool: Boolean(activeTool),
|
|
64
|
+
undo: editing && !activeTool,
|
|
65
|
+
cancel: editing && !activeTool,
|
|
66
|
+
apply: editing && !activeTool,
|
|
67
|
+
}
|
|
68
|
+
for (const button of buttons) {
|
|
69
|
+
const action = button.dataset.action!
|
|
70
|
+
button.hidden = !visible[action]
|
|
71
|
+
}
|
|
72
|
+
document.querySelector<HTMLButtonElement>('[data-action="edit"]')!.disabled = status !== 'ready'
|
|
73
|
+
document.querySelector<HTMLButtonElement>('[data-action="undo"]')!.disabled = !canUndo || busy
|
|
74
|
+
document.querySelector<HTMLButtonElement>('[data-action="apply"]')!.disabled = !canApply || busy
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
pic.on('change', update)
|
|
78
|
+
pic.on('load', () => update(pic.getState()))
|
|
79
|
+
pic.on('error', () => update(pic.getState()))
|
|
80
|
+
update(pic.getState())
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
== Vue
|
|
84
|
+
|
|
85
|
+
```vue
|
|
86
|
+
<script setup lang="ts">
|
|
87
|
+
import type { PaperPicState } from '@paperpic/vue'
|
|
88
|
+
import { PaperPic } from '@paperpic/vue'
|
|
89
|
+
import { computed, shallowRef, useTemplateRef } from 'vue'
|
|
90
|
+
import '@paperpic/vue/style.css'
|
|
91
|
+
|
|
92
|
+
const pic = useTemplateRef<InstanceType<typeof PaperPic>>('pic')
|
|
93
|
+
const viewer = computed(() => pic.value?.instance)
|
|
94
|
+
const state = shallowRef<PaperPicState>()
|
|
95
|
+
|
|
96
|
+
function refresh() {
|
|
97
|
+
state.value = viewer.value?.getState()
|
|
98
|
+
}
|
|
99
|
+
</script>
|
|
100
|
+
|
|
101
|
+
<template>
|
|
102
|
+
<div v-if="state">
|
|
103
|
+
<button type="button" @click="viewer?.zoomIn()">
|
|
104
|
+
Zoom in
|
|
105
|
+
</button>
|
|
106
|
+
<button type="button" @click="viewer?.zoomOut()">
|
|
107
|
+
Zoom out
|
|
108
|
+
</button>
|
|
109
|
+
<template v-if="state.mode === 'view'">
|
|
110
|
+
<button type="button" :disabled="state.status !== 'ready'" @click="viewer?.edit()">
|
|
111
|
+
Edit
|
|
112
|
+
</button>
|
|
113
|
+
</template>
|
|
114
|
+
<template v-else-if="state.activeTool">
|
|
115
|
+
<button type="button" @click="viewer?.confirmTool()">
|
|
116
|
+
Done
|
|
117
|
+
</button>
|
|
118
|
+
</template>
|
|
119
|
+
<template v-else>
|
|
120
|
+
<button type="button" @click="viewer?.openTool('perspective')">
|
|
121
|
+
Straighten
|
|
122
|
+
</button>
|
|
123
|
+
<button type="button" :disabled="!state.canUndo || state.busy" @click="viewer?.undo()">
|
|
124
|
+
Undo
|
|
125
|
+
</button>
|
|
126
|
+
<button type="button" @click="viewer?.cancel()">
|
|
127
|
+
Cancel
|
|
128
|
+
</button>
|
|
129
|
+
<button type="button" :disabled="!state.canApply || state.busy" @click="viewer?.apply()">
|
|
130
|
+
Apply
|
|
131
|
+
</button>
|
|
132
|
+
</template>
|
|
133
|
+
</div>
|
|
134
|
+
<div style="height: 480px">
|
|
135
|
+
<PaperPic
|
|
136
|
+
ref="pic"
|
|
137
|
+
src="/receipt.jpg"
|
|
138
|
+
alt="A receipt"
|
|
139
|
+
:toolbar="false"
|
|
140
|
+
@change="next => (state = next)"
|
|
141
|
+
@load="refresh"
|
|
142
|
+
@error="refresh"
|
|
143
|
+
/>
|
|
144
|
+
</div>
|
|
145
|
+
</template>
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
== React
|
|
149
|
+
|
|
150
|
+
```tsx
|
|
151
|
+
import type { PaperPicInstance, PaperPicState } from '@paperpic/react'
|
|
152
|
+
import { PaperPic } from '@paperpic/react'
|
|
153
|
+
import { useRef, useState } from 'react'
|
|
154
|
+
import '@paperpic/react/style.css'
|
|
155
|
+
|
|
156
|
+
export function Receipt() {
|
|
157
|
+
const picRef = useRef<PaperPicInstance>(null)
|
|
158
|
+
const [state, setState] = useState<PaperPicState>()
|
|
159
|
+
|
|
160
|
+
function refresh() {
|
|
161
|
+
setState(picRef.current?.getState())
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
const viewer = () => picRef.current!
|
|
165
|
+
|
|
166
|
+
return (
|
|
167
|
+
<>
|
|
168
|
+
{state && (
|
|
169
|
+
<div>
|
|
170
|
+
<button type="button" onClick={() => viewer().zoomIn()}>Zoom in</button>
|
|
171
|
+
<button type="button" onClick={() => viewer().zoomOut()}>Zoom out</button>
|
|
172
|
+
{state.mode === 'view' && (
|
|
173
|
+
<button type="button" disabled={state.status !== 'ready'} onClick={() => viewer().edit()}>Edit</button>
|
|
174
|
+
)}
|
|
175
|
+
{state.mode === 'edit' && state.activeTool && (
|
|
176
|
+
<button type="button" onClick={() => viewer().confirmTool()}>Done</button>
|
|
177
|
+
)}
|
|
178
|
+
{state.mode === 'edit' && !state.activeTool && (
|
|
179
|
+
<>
|
|
180
|
+
<button type="button" onClick={() => viewer().openTool('perspective')}>Straighten</button>
|
|
181
|
+
<button type="button" disabled={!state.canUndo || state.busy} onClick={() => viewer().undo()}>Undo</button>
|
|
182
|
+
<button type="button" onClick={() => viewer().cancel()}>Cancel</button>
|
|
183
|
+
<button type="button" disabled={!state.canApply || state.busy} onClick={() => viewer().apply()}>Apply</button>
|
|
184
|
+
</>
|
|
185
|
+
)}
|
|
186
|
+
</div>
|
|
187
|
+
)}
|
|
188
|
+
<div style={{ height: 480 }}>
|
|
189
|
+
<PaperPic
|
|
190
|
+
ref={picRef}
|
|
191
|
+
src="/receipt.jpg"
|
|
192
|
+
alt="A receipt"
|
|
193
|
+
toolbar={false}
|
|
194
|
+
onChange={setState}
|
|
195
|
+
onLoad={refresh}
|
|
196
|
+
onError={refresh}
|
|
197
|
+
/>
|
|
198
|
+
</div>
|
|
199
|
+
</>
|
|
200
|
+
)
|
|
201
|
+
}
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
:::
|
|
205
|
+
|
|
206
|
+
## Notes
|
|
207
|
+
|
|
208
|
+
- 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.
|
|
209
|
+
- 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.
|
|
210
|
+
- [`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.
|
|
211
|
+
- The keyboard shortcuts keep working with the focus on the viewer. See [Accessibility](../guide/accessibility).
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Fixed proportions
|
|
3
|
+
description: A complete example that lets the user pick the type of document, such as an A4 sheet or an ID card, so that Straighten gives the result its exact proportions.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Fixed proportions
|
|
7
|
+
|
|
8
|
+
Straighten estimates the proportions of a document from the photo, and the estimate cannot be exact. When your app knows what the user photographs, such as an A4 form or an ID card, [`aspectRatio`](../reference/options#aspectratio) gives the result its real shape. This example lets the user pick the type of document before straightening it.
|
|
9
|
+
|
|
10
|
+
:::tabs key:framework
|
|
11
|
+
== JavaScript
|
|
12
|
+
|
|
13
|
+
```html
|
|
14
|
+
<select id="type">
|
|
15
|
+
<option value="a4">A4 sheet</option>
|
|
16
|
+
<option value="letter">US Letter sheet</option>
|
|
17
|
+
<option value="idCard">ID card</option>
|
|
18
|
+
<option value="other">Other</option>
|
|
19
|
+
</select>
|
|
20
|
+
<div id="viewer" style="height: 480px"></div>
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
```ts
|
|
24
|
+
import { PaperPic } from '@paperpic/core'
|
|
25
|
+
import '@paperpic/core/style.css'
|
|
26
|
+
|
|
27
|
+
const proportions: Record<string, number | undefined> = {
|
|
28
|
+
a4: 210 / 297,
|
|
29
|
+
letter: 8.5 / 11,
|
|
30
|
+
idCard: 85.6 / 53.98,
|
|
31
|
+
other: undefined,
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
const pic = new PaperPic(document.querySelector<HTMLElement>('#viewer')!, {
|
|
35
|
+
src: '/scans/form.jpg',
|
|
36
|
+
alt: 'Signed form',
|
|
37
|
+
tools: ['perspective', 'rotate', 'threshold'],
|
|
38
|
+
aspectRatio: proportions.a4,
|
|
39
|
+
})
|
|
40
|
+
|
|
41
|
+
document.querySelector('#type')!.addEventListener('change', (event) => {
|
|
42
|
+
const type = (event.target as HTMLSelectElement).value
|
|
43
|
+
pic.setOptions({ aspectRatio: proportions[type] })
|
|
44
|
+
})
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
== Vue
|
|
48
|
+
|
|
49
|
+
```vue
|
|
50
|
+
<script setup lang="ts">
|
|
51
|
+
import type { ToolId } from '@paperpic/vue'
|
|
52
|
+
import { PaperPic } from '@paperpic/vue'
|
|
53
|
+
import { shallowRef } from 'vue'
|
|
54
|
+
import '@paperpic/vue/style.css'
|
|
55
|
+
|
|
56
|
+
const types = [
|
|
57
|
+
{ name: 'A4 sheet', aspectRatio: 210 / 297 },
|
|
58
|
+
{ name: 'US Letter sheet', aspectRatio: 8.5 / 11 },
|
|
59
|
+
{ name: 'ID card', aspectRatio: 85.6 / 53.98 },
|
|
60
|
+
{ name: 'Other', aspectRatio: undefined },
|
|
61
|
+
]
|
|
62
|
+
const tools: ToolId[] = ['perspective', 'rotate', 'threshold']
|
|
63
|
+
|
|
64
|
+
const type = shallowRef(types[0]!)
|
|
65
|
+
</script>
|
|
66
|
+
|
|
67
|
+
<template>
|
|
68
|
+
<select v-model="type">
|
|
69
|
+
<option v-for="item in types" :key="item.name" :value="item">
|
|
70
|
+
{{ item.name }}
|
|
71
|
+
</option>
|
|
72
|
+
</select>
|
|
73
|
+
<div style="height: 480px">
|
|
74
|
+
<PaperPic src="/scans/form.jpg" alt="Signed form" :tools :aspect-ratio="type.aspectRatio" />
|
|
75
|
+
</div>
|
|
76
|
+
</template>
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
== React
|
|
80
|
+
|
|
81
|
+
```tsx
|
|
82
|
+
import type { ToolId } from '@paperpic/react'
|
|
83
|
+
import { PaperPic } from '@paperpic/react'
|
|
84
|
+
import { useState } from 'react'
|
|
85
|
+
import '@paperpic/react/style.css'
|
|
86
|
+
|
|
87
|
+
const types = [
|
|
88
|
+
{ name: 'A4 sheet', aspectRatio: 210 / 297 },
|
|
89
|
+
{ name: 'US Letter sheet', aspectRatio: 8.5 / 11 },
|
|
90
|
+
{ name: 'ID card', aspectRatio: 85.6 / 53.98 },
|
|
91
|
+
{ name: 'Other', aspectRatio: undefined },
|
|
92
|
+
]
|
|
93
|
+
const tools: ToolId[] = ['perspective', 'rotate', 'threshold']
|
|
94
|
+
|
|
95
|
+
export function Form() {
|
|
96
|
+
const [index, setIndex] = useState(0)
|
|
97
|
+
|
|
98
|
+
return (
|
|
99
|
+
<>
|
|
100
|
+
<select value={index} onChange={event => setIndex(Number(event.target.value))}>
|
|
101
|
+
{types.map((item, position) => (
|
|
102
|
+
<option key={item.name} value={position}>{item.name}</option>
|
|
103
|
+
))}
|
|
104
|
+
</select>
|
|
105
|
+
<div style={{ height: 480 }}>
|
|
106
|
+
<PaperPic src="/scans/form.jpg" alt="Signed form" tools={tools} aspectRatio={types[index]!.aspectRatio} />
|
|
107
|
+
</div>
|
|
108
|
+
</>
|
|
109
|
+
)
|
|
110
|
+
}
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
:::
|
|
114
|
+
|
|
115
|
+
## Notes
|
|
116
|
+
|
|
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
|
+
- For a document in landscape, swap the numbers, such as `297 / 210`.
|
|
119
|
+
- Leave `aspectRatio` out for documents without a fixed size, such as receipts, and Straighten estimates them.
|
|
120
|
+
- [Straighten](../guide/tools/straighten) explains the estimate and how to handle corners that fall outside the photo.
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Read-only viewer
|
|
3
|
+
description: A complete example of a read-only PaperPic viewer for the attachments of a record, with a list of documents, rotation and a download button.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Read-only viewer
|
|
7
|
+
|
|
8
|
+
Some documents should be read but not changed, such as the attachments of an order or a claim. This example shows them one at a time in a read-only viewer, with a list to switch between them and a button to download them.
|
|
9
|
+
|
|
10
|
+
:::tabs key:framework
|
|
11
|
+
== JavaScript
|
|
12
|
+
|
|
13
|
+
```html
|
|
14
|
+
<select id="documents">
|
|
15
|
+
<option value="0">Invoice</option>
|
|
16
|
+
<option value="1">Delivery note</option>
|
|
17
|
+
</select>
|
|
18
|
+
<div id="viewer" style="height: 480px"></div>
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
import { PaperPic } from '@paperpic/core'
|
|
23
|
+
import '@paperpic/core/style.css'
|
|
24
|
+
|
|
25
|
+
const documents = [
|
|
26
|
+
{ src: '/orders/42/invoice.jpg', alt: 'Invoice' },
|
|
27
|
+
{ src: '/orders/42/delivery-note.jpg', alt: 'Delivery note' },
|
|
28
|
+
]
|
|
29
|
+
|
|
30
|
+
const pic = new PaperPic(document.querySelector<HTMLElement>('#viewer')!, {
|
|
31
|
+
...documents[0],
|
|
32
|
+
editable: false,
|
|
33
|
+
download: true,
|
|
34
|
+
wheelZoom: false,
|
|
35
|
+
})
|
|
36
|
+
|
|
37
|
+
document.querySelector('#documents')!.addEventListener('change', (event) => {
|
|
38
|
+
const index = Number((event.target as HTMLSelectElement).value)
|
|
39
|
+
pic.setOptions(documents[index]!)
|
|
40
|
+
})
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
== Vue
|
|
44
|
+
|
|
45
|
+
```vue
|
|
46
|
+
<script setup lang="ts">
|
|
47
|
+
import { PaperPic } from '@paperpic/vue'
|
|
48
|
+
import { shallowRef } from 'vue'
|
|
49
|
+
import '@paperpic/vue/style.css'
|
|
50
|
+
|
|
51
|
+
const documents = [
|
|
52
|
+
{ src: '/orders/42/invoice.jpg', alt: 'Invoice' },
|
|
53
|
+
{ src: '/orders/42/delivery-note.jpg', alt: 'Delivery note' },
|
|
54
|
+
]
|
|
55
|
+
|
|
56
|
+
const current = shallowRef(documents[0]!)
|
|
57
|
+
</script>
|
|
58
|
+
|
|
59
|
+
<template>
|
|
60
|
+
<select v-model="current">
|
|
61
|
+
<option v-for="item in documents" :key="item.src" :value="item">
|
|
62
|
+
{{ item.alt }}
|
|
63
|
+
</option>
|
|
64
|
+
</select>
|
|
65
|
+
<div style="height: 480px">
|
|
66
|
+
<PaperPic
|
|
67
|
+
:src="current.src"
|
|
68
|
+
:alt="current.alt"
|
|
69
|
+
:editable="false"
|
|
70
|
+
download
|
|
71
|
+
:wheel-zoom="false"
|
|
72
|
+
/>
|
|
73
|
+
</div>
|
|
74
|
+
</template>
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
== React
|
|
78
|
+
|
|
79
|
+
```tsx
|
|
80
|
+
import { PaperPic } from '@paperpic/react'
|
|
81
|
+
import { useState } from 'react'
|
|
82
|
+
import '@paperpic/react/style.css'
|
|
83
|
+
|
|
84
|
+
const documents = [
|
|
85
|
+
{ src: '/orders/42/invoice.jpg', alt: 'Invoice' },
|
|
86
|
+
{ src: '/orders/42/delivery-note.jpg', alt: 'Delivery note' },
|
|
87
|
+
]
|
|
88
|
+
|
|
89
|
+
export function Attachments() {
|
|
90
|
+
const [index, setIndex] = useState(0)
|
|
91
|
+
const current = documents[index]!
|
|
92
|
+
|
|
93
|
+
return (
|
|
94
|
+
<>
|
|
95
|
+
<select value={index} onChange={event => setIndex(Number(event.target.value))}>
|
|
96
|
+
{documents.map((item, position) => (
|
|
97
|
+
<option key={item.src} value={position}>{item.alt}</option>
|
|
98
|
+
))}
|
|
99
|
+
</select>
|
|
100
|
+
<div style={{ height: 480 }}>
|
|
101
|
+
<PaperPic src={current.src} alt={current.alt} editable={false} download wheelZoom={false} />
|
|
102
|
+
</div>
|
|
103
|
+
</>
|
|
104
|
+
)
|
|
105
|
+
}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
:::
|
|
109
|
+
|
|
110
|
+
## Notes
|
|
111
|
+
|
|
112
|
+
- With `editable: false`, the toolbar has no Edit button, and its rotate buttons only turn the image on display.
|
|
113
|
+
- `download: true` adds a button that saves the document as it is, with its own file name. The [`download`](../reference/events#download) event lets you serve it from your server instead.
|
|
114
|
+
- `wheelZoom: false` lets the wheel scroll the page, which suits a viewer inside a longer page.
|
|
115
|
+
- A new `src` loads the next document and fits it to the viewer.
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Upload to a server
|
|
3
|
+
description: A complete example that sends the image edited in PaperPic to your server and tells the user whether it was saved, in plain JavaScript, Vue and React.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Upload to a server
|
|
7
|
+
|
|
8
|
+
The viewer shows the result of Apply at once, but saving it is up to your app. This example sends the edited image to your server and tells the user how it went.
|
|
9
|
+
|
|
10
|
+
This function sends the image as a file in a form, and fails when the server does not accept it:
|
|
11
|
+
|
|
12
|
+
```ts
|
|
13
|
+
async function upload(blob: Blob, type: string) {
|
|
14
|
+
const body = new FormData()
|
|
15
|
+
body.append('file', blob, `document.${type.split('/')[1]}`)
|
|
16
|
+
const response = await fetch('/api/documents/42', { method: 'PUT', body })
|
|
17
|
+
if (!response.ok) {
|
|
18
|
+
throw new Error(`The upload failed with status ${response.status}`)
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
The viewer calls it on Apply, and a status line reports the result:
|
|
24
|
+
|
|
25
|
+
:::tabs key:framework
|
|
26
|
+
== JavaScript
|
|
27
|
+
|
|
28
|
+
```html
|
|
29
|
+
<div id="viewer" style="height: 480px"></div>
|
|
30
|
+
<p id="status" role="status"></p>
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
import { PaperPic } from '@paperpic/core'
|
|
35
|
+
import '@paperpic/core/style.css'
|
|
36
|
+
|
|
37
|
+
const status = document.querySelector('#status')!
|
|
38
|
+
|
|
39
|
+
const pic = new PaperPic(document.querySelector<HTMLElement>('#viewer')!, {
|
|
40
|
+
src: '/documents/42.jpg',
|
|
41
|
+
alt: 'Invoice 42',
|
|
42
|
+
maxOutputSize: 3000,
|
|
43
|
+
})
|
|
44
|
+
|
|
45
|
+
pic.on('apply', async ({ blob, type }) => {
|
|
46
|
+
status.textContent = 'Saving…'
|
|
47
|
+
try {
|
|
48
|
+
await upload(blob, type)
|
|
49
|
+
status.textContent = 'Saved'
|
|
50
|
+
}
|
|
51
|
+
catch {
|
|
52
|
+
status.textContent = 'The document could not be saved'
|
|
53
|
+
}
|
|
54
|
+
})
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
== Vue
|
|
58
|
+
|
|
59
|
+
```vue
|
|
60
|
+
<script setup lang="ts">
|
|
61
|
+
import type { ExportedImage } from '@paperpic/vue'
|
|
62
|
+
import { PaperPic } from '@paperpic/vue'
|
|
63
|
+
import { shallowRef } from 'vue'
|
|
64
|
+
import '@paperpic/vue/style.css'
|
|
65
|
+
|
|
66
|
+
const status = shallowRef('')
|
|
67
|
+
|
|
68
|
+
async function save({ blob, type }: ExportedImage) {
|
|
69
|
+
status.value = 'Saving…'
|
|
70
|
+
try {
|
|
71
|
+
await upload(blob, type)
|
|
72
|
+
status.value = 'Saved'
|
|
73
|
+
}
|
|
74
|
+
catch {
|
|
75
|
+
status.value = 'The document could not be saved'
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
</script>
|
|
79
|
+
|
|
80
|
+
<template>
|
|
81
|
+
<div style="height: 480px">
|
|
82
|
+
<PaperPic src="/documents/42.jpg" alt="Invoice 42" :max-output-size="3000" @apply="save" />
|
|
83
|
+
</div>
|
|
84
|
+
<p role="status">
|
|
85
|
+
{{ status }}
|
|
86
|
+
</p>
|
|
87
|
+
</template>
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
== React
|
|
91
|
+
|
|
92
|
+
```tsx
|
|
93
|
+
import type { ExportedImage } from '@paperpic/react'
|
|
94
|
+
import { PaperPic } from '@paperpic/react'
|
|
95
|
+
import { useState } from 'react'
|
|
96
|
+
import '@paperpic/react/style.css'
|
|
97
|
+
|
|
98
|
+
export function Invoice() {
|
|
99
|
+
const [status, setStatus] = useState('')
|
|
100
|
+
|
|
101
|
+
async function save({ blob, type }: ExportedImage) {
|
|
102
|
+
setStatus('Saving…')
|
|
103
|
+
try {
|
|
104
|
+
await upload(blob, type)
|
|
105
|
+
setStatus('Saved')
|
|
106
|
+
}
|
|
107
|
+
catch {
|
|
108
|
+
setStatus('The document could not be saved')
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
return (
|
|
113
|
+
<>
|
|
114
|
+
<div style={{ height: 480 }}>
|
|
115
|
+
<PaperPic src="/documents/42.jpg" alt="Invoice 42" maxOutputSize={3000} onApply={save} />
|
|
116
|
+
</div>
|
|
117
|
+
<p role="status">{status}</p>
|
|
118
|
+
</>
|
|
119
|
+
)
|
|
120
|
+
}
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
:::
|
|
124
|
+
|
|
125
|
+
## Notes
|
|
126
|
+
|
|
127
|
+
- `role="status"` makes screen readers announce the result of the upload.
|
|
128
|
+
- [`maxOutputSize`](../reference/options#maxoutputsize) keeps the file small. Documents stay readable at 3000 pixels on the longest side.
|
|
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 otherwise. Read [Saving the result](../guide/saving) to choose another one.
|