@paperpic/react 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/dist/index.d.ts +7 -4
- package/package.json +2 -2
|
@@ -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
|
|
|
@@ -29,7 +29,7 @@ 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
|
|
|
@@ -43,11 +43,11 @@ An object or array with the same contents as before, such as `:tools="['crop', '
|
|
|
43
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
|
@@ -5,15 +5,18 @@ type PaperPicInstance = PaperPic$1;
|
|
|
5
5
|
interface PaperPicProps extends PaperPicOptions$1 {
|
|
6
6
|
/** Classes for the element that holds the viewer, on top of `paperpic-host`. */
|
|
7
7
|
className?: string;
|
|
8
|
-
/**
|
|
8
|
+
/** Apply finished, from the button, `Enter` or `apply()`. The result is already on display. */
|
|
9
9
|
onApply?: (result: PaperPicEvents$1['apply']) => void;
|
|
10
|
-
/**
|
|
10
|
+
/**
|
|
11
|
+
* The user or a method changed the state, such as the zoom or the edit. A loaded image comes with `onLoad`, and a
|
|
12
|
+
* failed Apply with `onError`, instead. A pan and a change of props never call it.
|
|
13
|
+
*/
|
|
11
14
|
onChange?: (state: PaperPicEvents$1['change']) => void;
|
|
12
15
|
/** The image is about to be saved. Call `preventDefault()` to save it another way. */
|
|
13
16
|
onDownload?: (download: PaperPicEvents$1['download']) => void;
|
|
14
|
-
/** The image could not be loaded, or
|
|
17
|
+
/** The image could not be loaded, or an edit could not be shown or applied. */
|
|
15
18
|
onError?: (failure: PaperPicEvents$1['error']) => void;
|
|
16
|
-
/** The image is ready. */
|
|
19
|
+
/** The image of `src` is ready, also after `reload()`. Apply does not call it. */
|
|
17
20
|
onLoad?: (size: PaperPicEvents$1['load']) => void;
|
|
18
21
|
/** Receives the viewer, for a custom interface. It is `null` until the component mounts. */
|
|
19
22
|
ref?: Ref<PaperPicInstance>;
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@paperpic/react",
|
|
3
3
|
"type": "module",
|
|
4
|
-
"version": "0.3.
|
|
4
|
+
"version": "0.3.1",
|
|
5
5
|
"description": "React 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",
|
|
@@ -42,7 +42,7 @@
|
|
|
42
42
|
"react": "^19.0.0"
|
|
43
43
|
},
|
|
44
44
|
"dependencies": {
|
|
45
|
-
"@paperpic/core": "0.3.
|
|
45
|
+
"@paperpic/core": "0.3.1"
|
|
46
46
|
},
|
|
47
47
|
"devDependencies": {
|
|
48
48
|
"@arethetypeswrong/core": "0.18.5",
|