@paperpic/vue 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 +40 -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 +80 -0
- package/dist/index.js +68 -0
- package/dist/style.css +702 -0
- package/package.json +63 -3
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Options
|
|
3
|
+
description: Every option of PaperPic, with its type, its default and what it changes, for the constructor, setOptions() and the props of the Vue and React components.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Options
|
|
7
|
+
|
|
8
|
+
Options set what the viewer shows and what the user can do with it. Pass them when you create the viewer, or change them later with [`setOptions()`](./methods#setoptions). The Vue and React components take them as props with the same names.
|
|
9
|
+
|
|
10
|
+
```ts
|
|
11
|
+
const pic = new PaperPic(container, { src: '/receipt.jpg', alt: 'A receipt' })
|
|
12
|
+
|
|
13
|
+
pic.setOptions({ editable: false })
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
`setOptions()` changes only the options you pass, and `undefined` brings an option back to its default. It never emits `change`.
|
|
17
|
+
|
|
18
|
+
## Image
|
|
19
|
+
|
|
20
|
+
### `src`
|
|
21
|
+
|
|
22
|
+
- **Type:** [`PaperPicSource`](./types#paperpicsource)
|
|
23
|
+
- **Default:** none
|
|
24
|
+
|
|
25
|
+
The image to show: a URL from the same origin, or a `File` or `Blob` attached on the client.
|
|
26
|
+
|
|
27
|
+
Passing the same value again does not reload the image, so the result of an edit stays on display. Call [`reload()`](./methods#reload) to bring back the original. A new value while editing discards the edits.
|
|
28
|
+
|
|
29
|
+
### `alt`
|
|
30
|
+
|
|
31
|
+
- **Type:** `string`
|
|
32
|
+
- **Default:** `''`
|
|
33
|
+
|
|
34
|
+
Describes the image for screen readers. Without it, screen readers skip the image, as they skip an `<img>` with an empty `alt`.
|
|
35
|
+
|
|
36
|
+
## Interface
|
|
37
|
+
|
|
38
|
+
### `editable`
|
|
39
|
+
|
|
40
|
+
- **Type:** `boolean`
|
|
41
|
+
- **Default:** `true`
|
|
42
|
+
|
|
43
|
+
Whether the user can edit the image. With `false`, it is a read-only viewer, and its toolbar adds buttons to rotate the image. That rotation only changes the display. Changing this option while editing discards the edits.
|
|
44
|
+
|
|
45
|
+
### `toolbar`
|
|
46
|
+
|
|
47
|
+
- **Type:** `boolean`
|
|
48
|
+
- **Default:** `true`
|
|
49
|
+
|
|
50
|
+
Whether to show the built-in toolbar and edit bar. Without them, build your own controls with the [methods](./methods).
|
|
51
|
+
|
|
52
|
+
### `tools`
|
|
53
|
+
|
|
54
|
+
- **Type:** [`readonly ToolId[]`](./types#toolid)
|
|
55
|
+
- **Default:** every tool
|
|
56
|
+
|
|
57
|
+
The tools the edit bar offers. They keep the order of this table, whatever the order of the array.
|
|
58
|
+
|
|
59
|
+
| Id | Button |
|
|
60
|
+
| --------------- | ----------------------------------- |
|
|
61
|
+
| `'crop'` | Crop |
|
|
62
|
+
| `'perspective'` | Straighten |
|
|
63
|
+
| `'rotate'` | Rotate left |
|
|
64
|
+
| `'flip'` | Flip |
|
|
65
|
+
| `'adjust'` | Adjust, for brightness and contrast |
|
|
66
|
+
| `'threshold'` | Clean up |
|
|
67
|
+
|
|
68
|
+
### `wheelZoom`
|
|
69
|
+
|
|
70
|
+
- **Type:** `boolean`
|
|
71
|
+
- **Default:** `true`
|
|
72
|
+
|
|
73
|
+
Whether the wheel zooms the image. Turn it off when the viewer sits in a long page, so the wheel scrolls the page.
|
|
74
|
+
|
|
75
|
+
### `download`
|
|
76
|
+
|
|
77
|
+
- **Type:** `boolean`
|
|
78
|
+
- **Default:** `false`
|
|
79
|
+
|
|
80
|
+
Whether the toolbar has a button that saves the image on display: the result of the last Apply, or else the source. The button is hidden while editing. The [`download`](./events#download) event lets you save the file another way.
|
|
81
|
+
|
|
82
|
+
### `labels`
|
|
83
|
+
|
|
84
|
+
- **Type:** [`Partial<PaperPicLabels>`](./types#paperpiclabels)
|
|
85
|
+
- **Default:** the English texts
|
|
86
|
+
|
|
87
|
+
Replaces any of the texts that the component shows or announces. [Labels](./labels) lists every key.
|
|
88
|
+
|
|
89
|
+
### `icons`
|
|
90
|
+
|
|
91
|
+
- **Type:** [`Partial<PaperPicIcons>`](./types#paperpicicons)
|
|
92
|
+
- **Default:** the built-in icons
|
|
93
|
+
|
|
94
|
+
Replaces any of the icons with your own markup of one element, such as an `<svg>`. The markup goes into the page as HTML, so pass only markup you trust. An empty string leaves the buttons of that icon without one. [Styling](../guide/styling#icons) shows an example.
|
|
95
|
+
|
|
96
|
+
Each key names an icon, and some icons appear on two buttons:
|
|
97
|
+
|
|
98
|
+
| Key | Button |
|
|
99
|
+
| ---------------- | -------------------------------------------------- |
|
|
100
|
+
| `adjust` | Adjust |
|
|
101
|
+
| `apply` | Apply, and Done in every tool |
|
|
102
|
+
| `brightness` | Brightness, in the panel of Adjust |
|
|
103
|
+
| `cancel` | Cancel, and Cancel this tool |
|
|
104
|
+
| `contrast` | Contrast, in the panel of Adjust |
|
|
105
|
+
| `crop` | Crop |
|
|
106
|
+
| `download` | Download |
|
|
107
|
+
| `edit` | Edit |
|
|
108
|
+
| `fitHeight` | Fit to height |
|
|
109
|
+
| `fitWidth` | Fit to width |
|
|
110
|
+
| `flip` | Flip |
|
|
111
|
+
| `perspective` | Straighten |
|
|
112
|
+
| `redo` | Redo |
|
|
113
|
+
| `rotateDocument` | Rotate left, in the edit bar |
|
|
114
|
+
| `rotateLeft` | Rotate left, in the toolbar of a read-only viewer |
|
|
115
|
+
| `rotateRight` | Rotate right, in the toolbar of a read-only viewer |
|
|
116
|
+
| `threshold` | Clean up |
|
|
117
|
+
| `undo` | Undo |
|
|
118
|
+
| `zoomIn` | Zoom in |
|
|
119
|
+
| `zoomOut` | Zoom out |
|
|
120
|
+
|
|
121
|
+
## Result
|
|
122
|
+
|
|
123
|
+
### `output`
|
|
124
|
+
|
|
125
|
+
- **Type:** [`PaperPicOutput`](./types#paperpicoutput)
|
|
126
|
+
- **Default:** the format of the source
|
|
127
|
+
|
|
128
|
+
The format of the edited image. `type` is `'image/jpeg'`, `'image/png'` or `'image/webp'`, and `quality` goes from 0 to 1 for JPEG and WebP, with `0.92` by default.
|
|
129
|
+
|
|
130
|
+
Without a `type`, a cleaned up image is PNG, because JPEG would damage its sharp edges, and any other image keeps the format of the source. A format that the browser cannot encode gives PNG.
|
|
131
|
+
|
|
132
|
+
### `maxOutputSize`
|
|
133
|
+
|
|
134
|
+
- **Type:** `number`
|
|
135
|
+
- **Default:** the full resolution
|
|
136
|
+
|
|
137
|
+
The longest side of the edited image, in pixels. A larger result is scaled down.
|
|
138
|
+
|
|
139
|
+
### `filename`
|
|
140
|
+
|
|
141
|
+
- **Type:** `string`
|
|
142
|
+
- **Default:** the name of the source
|
|
143
|
+
|
|
144
|
+
The name of the saved file. Its extension follows the format of the image, so a cleaned up `receipt.jpg` saves as `receipt.png`. When the source has no name, such as a `Blob`, the file is called `image`.
|
|
145
|
+
|
|
146
|
+
## Tools
|
|
147
|
+
|
|
148
|
+
### `aspectRatio`
|
|
149
|
+
|
|
150
|
+
- **Type:** `number`
|
|
151
|
+
- **Default:** estimated
|
|
152
|
+
|
|
153
|
+
The real proportions of the document, as width divided by height, such as `210 / 297` for an A4 sheet. Straighten gives its result these proportions. Without them, it estimates them from the photo.
|
|
154
|
+
|
|
155
|
+
### `softness`
|
|
156
|
+
|
|
157
|
+
- **Type:** `number`, from 0 to 1
|
|
158
|
+
- **Default:** `0.25`
|
|
159
|
+
|
|
160
|
+
How much gray Clean up keeps at the edges of the letters, which makes them easier to read. Use `0` for strict black and white, which gives smaller files but breaks thin strokes.
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: React
|
|
3
|
+
description: How the PaperPic component for React maps the options, events and methods of the core to props, callback props and a ref.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# React
|
|
7
|
+
|
|
8
|
+
`@paperpic/react` wraps the viewer in a component for React 19 or newer. The options are props, the events are callback props, and the methods are on the viewer that `ref` receives.
|
|
9
|
+
|
|
10
|
+
```tsx
|
|
11
|
+
import type { ExportedImage } from '@paperpic/react'
|
|
12
|
+
import { PaperPic } from '@paperpic/react'
|
|
13
|
+
import '@paperpic/react/style.css'
|
|
14
|
+
|
|
15
|
+
function upload({ blob }: ExportedImage) {
|
|
16
|
+
// Send the edited image to your server
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
export function Receipt() {
|
|
20
|
+
return (
|
|
21
|
+
<div style={{ height: 480 }}>
|
|
22
|
+
<PaperPic src="/receipt.jpg" alt="A receipt" onApply={upload} />
|
|
23
|
+
</div>
|
|
24
|
+
)
|
|
25
|
+
}
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
The component fills its parent element, so give the parent a height.
|
|
29
|
+
|
|
30
|
+
## Props
|
|
31
|
+
|
|
32
|
+
Every [option](./options) is a prop with the same name, such as `editable={false}` or `aspectRatio={210 / 297}`. Two more props style the element that holds the viewer:
|
|
33
|
+
|
|
34
|
+
| Prop | Type | Description |
|
|
35
|
+
| ----------- | --------------- | --------------------------------- |
|
|
36
|
+
| `className` | `string` | Classes on top of `paperpic-host` |
|
|
37
|
+
| `style` | `CSSProperties` | Inline styles |
|
|
38
|
+
|
|
39
|
+
Objects and arrays, such as `labels` or `tools`, reach the viewer again whenever they are new. Define them outside the component, or with `useMemo`.
|
|
40
|
+
|
|
41
|
+
## Events
|
|
42
|
+
|
|
43
|
+
| Prop | Payload |
|
|
44
|
+
| ------------ | ---------------------------------------------- |
|
|
45
|
+
| `onApply` | [`ExportedImage`](./types#exportedimage) |
|
|
46
|
+
| `onChange` | [`PaperPicState`](./state) |
|
|
47
|
+
| `onDownload` | [`PaperPicDownload`](./types#paperpicdownload) |
|
|
48
|
+
| `onError` | `{ error }` |
|
|
49
|
+
| `onLoad` | [`Size`](./types#size) |
|
|
50
|
+
|
|
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
|
+
|
|
53
|
+
## Methods
|
|
54
|
+
|
|
55
|
+
`ref` receives the viewer, of type [`PaperPicInstance`](./types#paperpicinstance), with every [method](./methods). It is `null` until the component mounts:
|
|
56
|
+
|
|
57
|
+
```tsx
|
|
58
|
+
import type { PaperPicInstance } from '@paperpic/react'
|
|
59
|
+
import { PaperPic } from '@paperpic/react'
|
|
60
|
+
import { useRef } from 'react'
|
|
61
|
+
|
|
62
|
+
export function Viewer({ src }: { src: string }) {
|
|
63
|
+
const picRef = useRef<PaperPicInstance>(null)
|
|
64
|
+
|
|
65
|
+
return (
|
|
66
|
+
<>
|
|
67
|
+
<button type="button" onClick={() => picRef.current?.zoomIn()}>Zoom in</button>
|
|
68
|
+
<div style={{ height: 480 }}>
|
|
69
|
+
<PaperPic ref={picRef} src={src} toolbar={false} />
|
|
70
|
+
</div>
|
|
71
|
+
</>
|
|
72
|
+
)
|
|
73
|
+
}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Passing the same `src` again does not reload the image, so it keeps the result of an edit. To bring back the original, call `picRef.current.reload()`.
|
|
77
|
+
|
|
78
|
+
## Types {#types}
|
|
79
|
+
|
|
80
|
+
`@paperpic/react` exports every type of `@paperpic/core`, so you do not need to install it: [Types](./types) shows each one. It also exports the types of the component: [`PaperPicProps`](./types#paperpicprops), with its props, and [`PaperPicInstance`](./types#paperpicinstance), the viewer that `ref` receives.
|
|
81
|
+
|
|
82
|
+
## Server-side rendering
|
|
83
|
+
|
|
84
|
+
The component is marked with `'use client'`. With server-side rendering, such as in Next.js, it renders an empty element on the server and creates the viewer in the browser.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
---
|
|
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.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# State
|
|
7
|
+
|
|
8
|
+
The state describes what the viewer shows at a given moment. [`getState()`](./methods#getstate) returns it, and the [`change`](./events#change) event carries it. Use it to keep controls of your own in step, such as an Apply button:
|
|
9
|
+
|
|
10
|
+
```ts
|
|
11
|
+
pic.on('change', ({ canApply, busy }) => {
|
|
12
|
+
applyButton.disabled = !canApply || busy
|
|
13
|
+
})
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
| Field | Type | Description |
|
|
17
|
+
| ------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
|
18
|
+
| `activeTool` | [`ToolId \| null`](./types#toolid) | The open tool, such as `'crop'` or `'adjust'`, or `null` |
|
|
19
|
+
| `adjustments` | `{ brightness, contrast }` | The brightness and the contrast, each from -1 to 1. Clean up leaves them out. While Adjust is open, the values it shows |
|
|
20
|
+
| `busy` | `boolean` | Whether Apply is running |
|
|
21
|
+
| `canApply` | `boolean` | Whether there are changes to apply. Rotations and flips that cancel out are no change |
|
|
22
|
+
| `canRedo` | `boolean` | Whether there is an edit to bring back |
|
|
23
|
+
| `canUndo` | `boolean` | Whether there is an edit to undo |
|
|
24
|
+
| `fit` | [`Fit \| null`](./types#fit) | The fit in effect, or `null` once the user has zoomed by hand |
|
|
25
|
+
| `image` | [`Size \| null`](./types#size) | The size of the image on display in pixels, with the edits so far, or `null` without an image |
|
|
26
|
+
| `mode` | `'view' \| 'edit'` | Whether the user is viewing or editing the image |
|
|
27
|
+
| `rotation` | [`Rotation`](./types#rotation) | How far the image on display is turned, in degrees clockwise |
|
|
28
|
+
| `status` | `'empty' \| 'loading' \| 'ready' \| 'error'` | Whether there is an image, and whether it loaded |
|
|
29
|
+
| `threshold` | `{ enabled, sensitivity }` | Whether Clean up is on, and its sensitivity from 0 to 1. While Clean up is open, what it shows |
|
|
30
|
+
| `zoom` | `number` | Screen pixels per pixel of the image |
|
|
@@ -0,0 +1,301 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Types
|
|
3
|
+
description: Every TypeScript type that PaperPic exports, with its definition, the page that explains it and how to import it from the package you installed.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Types
|
|
7
|
+
|
|
8
|
+
The reference and the examples name types such as `ExportedImage` or `ToolId`. This page shows what each one holds, so you can type your own code. Each type links to the page that explains it.
|
|
9
|
+
|
|
10
|
+
Import the types from the package you installed. `@paperpic/vue` and `@paperpic/react` export every type of `@paperpic/core`, so you do not need to install it:
|
|
11
|
+
|
|
12
|
+
:::tabs key:framework
|
|
13
|
+
== JavaScript
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
import type { ExportedImage, PaperPicState, ToolId } from '@paperpic/core'
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
== Vue
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
import type { ExportedImage, PaperPicState, ToolId } from '@paperpic/vue'
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
== React
|
|
26
|
+
|
|
27
|
+
```ts
|
|
28
|
+
import type { ExportedImage, PaperPicState, ToolId } from '@paperpic/react'
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
:::
|
|
32
|
+
|
|
33
|
+
## Options
|
|
34
|
+
|
|
35
|
+
### `PaperPicOptions`
|
|
36
|
+
|
|
37
|
+
```ts
|
|
38
|
+
interface PaperPicOptions {
|
|
39
|
+
alt?: string
|
|
40
|
+
aspectRatio?: number
|
|
41
|
+
download?: boolean
|
|
42
|
+
editable?: boolean
|
|
43
|
+
filename?: string
|
|
44
|
+
icons?: Partial<PaperPicIcons>
|
|
45
|
+
labels?: Partial<PaperPicLabels>
|
|
46
|
+
maxOutputSize?: number
|
|
47
|
+
output?: PaperPicOutput
|
|
48
|
+
softness?: number
|
|
49
|
+
src?: PaperPicSource
|
|
50
|
+
toolbar?: boolean
|
|
51
|
+
tools?: readonly ToolId[]
|
|
52
|
+
wheelZoom?: boolean
|
|
53
|
+
}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
What the constructor and [`setOptions()`](./methods#setoptions) take. In Vue and React, these are the props of the component. [Options](./options) explains each one.
|
|
57
|
+
|
|
58
|
+
### `PaperPicSource`
|
|
59
|
+
|
|
60
|
+
```ts
|
|
61
|
+
type PaperPicSource = string | Blob
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
The image in [`src`](./options#src): a URL from the same origin, or a `File` or `Blob` attached on the client. The `source` of [`PaperPicDownload`](#paperpicdownload) has the same type.
|
|
65
|
+
|
|
66
|
+
### `PaperPicOutput`
|
|
67
|
+
|
|
68
|
+
```ts
|
|
69
|
+
interface PaperPicOutput {
|
|
70
|
+
quality?: number
|
|
71
|
+
type?: string
|
|
72
|
+
}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
The format of the edited image, in [`output`](./options#output).
|
|
76
|
+
|
|
77
|
+
### `ToolId`
|
|
78
|
+
|
|
79
|
+
```ts
|
|
80
|
+
type ToolId = 'adjust' | 'crop' | 'flip' | 'perspective' | 'rotate' | 'threshold'
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
A tool of the edit bar, in [`tools`](./options#tools), [`openTool()`](./methods#opentool) and the `activeTool` of the [state](./state). [`tools`](./options#tools) gives the button of each one.
|
|
84
|
+
|
|
85
|
+
### `PaperPicLabels`
|
|
86
|
+
|
|
87
|
+
```ts
|
|
88
|
+
interface PaperPicLabels {
|
|
89
|
+
adjust: string
|
|
90
|
+
adjustmentLevel: (name: string, value: number) => string
|
|
91
|
+
applied: string
|
|
92
|
+
apply: string
|
|
93
|
+
applyError: string
|
|
94
|
+
brightness: string
|
|
95
|
+
cancel: string
|
|
96
|
+
cancelTool: string
|
|
97
|
+
confirm: string
|
|
98
|
+
contrast: string
|
|
99
|
+
cornerBottomLeft: string
|
|
100
|
+
cornerBottomRight: string
|
|
101
|
+
cornerMoved: (corner: string, x: number, y: number) => string
|
|
102
|
+
cornerSelected: (corner: string) => string
|
|
103
|
+
cornerTopLeft: string
|
|
104
|
+
cornerTopRight: string
|
|
105
|
+
crop: string
|
|
106
|
+
cropHint: string
|
|
107
|
+
discard: string
|
|
108
|
+
discardQuestion: string
|
|
109
|
+
download: string
|
|
110
|
+
edit: string
|
|
111
|
+
editBar: string
|
|
112
|
+
editing: string
|
|
113
|
+
fitHeight: string
|
|
114
|
+
fitWidth: string
|
|
115
|
+
flip: string
|
|
116
|
+
inUse: string
|
|
117
|
+
keepEditing: string
|
|
118
|
+
loadError: string
|
|
119
|
+
loading: string
|
|
120
|
+
perspective: string
|
|
121
|
+
perspectiveHint: string
|
|
122
|
+
processing: string
|
|
123
|
+
redo: string
|
|
124
|
+
rotateLeft: string
|
|
125
|
+
rotateRight: string
|
|
126
|
+
threshold: string
|
|
127
|
+
thresholdLevel: (percent: number) => string
|
|
128
|
+
thresholdSensitivity: string
|
|
129
|
+
toolbar: string
|
|
130
|
+
undo: string
|
|
131
|
+
viewer: string
|
|
132
|
+
zoomIn: string
|
|
133
|
+
zoomLevel: (percent: number) => string
|
|
134
|
+
zoomOut: string
|
|
135
|
+
}
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Every text of the interface, in [`labels`](./options#labels). The texts that include a value, such as the zoom level, are functions. [Labels](./labels) gives the English text of each one.
|
|
139
|
+
|
|
140
|
+
### `PaperPicIcons`
|
|
141
|
+
|
|
142
|
+
```ts
|
|
143
|
+
interface PaperPicIcons {
|
|
144
|
+
adjust: string
|
|
145
|
+
apply: string
|
|
146
|
+
brightness: string
|
|
147
|
+
cancel: string
|
|
148
|
+
contrast: string
|
|
149
|
+
crop: string
|
|
150
|
+
download: string
|
|
151
|
+
edit: string
|
|
152
|
+
fitHeight: string
|
|
153
|
+
fitWidth: string
|
|
154
|
+
flip: string
|
|
155
|
+
perspective: string
|
|
156
|
+
redo: string
|
|
157
|
+
rotateDocument: string
|
|
158
|
+
rotateLeft: string
|
|
159
|
+
rotateRight: string
|
|
160
|
+
threshold: string
|
|
161
|
+
undo: string
|
|
162
|
+
zoomIn: string
|
|
163
|
+
zoomOut: string
|
|
164
|
+
}
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
Every icon of the interface, as the markup of one element, in [`icons`](./options#icons), which gives the buttons of each one.
|
|
168
|
+
|
|
169
|
+
## State
|
|
170
|
+
|
|
171
|
+
### `PaperPicState`
|
|
172
|
+
|
|
173
|
+
```ts
|
|
174
|
+
interface PaperPicState {
|
|
175
|
+
activeTool: ToolId | null
|
|
176
|
+
adjustments: { brightness: number, contrast: number }
|
|
177
|
+
busy: boolean
|
|
178
|
+
canApply: boolean
|
|
179
|
+
canRedo: boolean
|
|
180
|
+
canUndo: boolean
|
|
181
|
+
fit: Fit | null
|
|
182
|
+
image: Size | null
|
|
183
|
+
mode: 'view' | 'edit'
|
|
184
|
+
rotation: Rotation
|
|
185
|
+
status: 'empty' | 'loading' | 'ready' | 'error'
|
|
186
|
+
threshold: { enabled: boolean, sensitivity: number }
|
|
187
|
+
zoom: number
|
|
188
|
+
}
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
What [`getState()`](./methods#getstate) returns and the [`change`](./events#change) event carries. [State](./state) explains each field.
|
|
192
|
+
|
|
193
|
+
### `Fit`
|
|
194
|
+
|
|
195
|
+
```ts
|
|
196
|
+
type Fit = 'image' | 'width' | 'height'
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
How the image fits the viewer: whole, by its width or by its height. [`fit()`](./methods#fit) takes it, and the `fit` of the [state](./state) holds it.
|
|
200
|
+
|
|
201
|
+
### `Rotation`
|
|
202
|
+
|
|
203
|
+
```ts
|
|
204
|
+
type Rotation = 0 | 90 | 180 | 270
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
How far the image on display is turned, in degrees clockwise, in the `rotation` of the [state](./state).
|
|
208
|
+
|
|
209
|
+
### `Size`
|
|
210
|
+
|
|
211
|
+
```ts
|
|
212
|
+
interface Size {
|
|
213
|
+
height: number
|
|
214
|
+
width: number
|
|
215
|
+
}
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
A width and a height in pixels, such as the `image` of the [state](./state) or what the [`load`](./events#load) event carries.
|
|
219
|
+
|
|
220
|
+
## Events
|
|
221
|
+
|
|
222
|
+
### `PaperPicEvents`
|
|
223
|
+
|
|
224
|
+
```ts
|
|
225
|
+
interface PaperPicEvents {
|
|
226
|
+
apply: ExportedImage
|
|
227
|
+
change: PaperPicState
|
|
228
|
+
download: PaperPicDownload
|
|
229
|
+
error: { error: Error }
|
|
230
|
+
load: Size
|
|
231
|
+
}
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
Each event with what it carries, for [`on()`](./methods#on). [Events](./events) explains each one.
|
|
235
|
+
|
|
236
|
+
### `ExportedImage`
|
|
237
|
+
|
|
238
|
+
```ts
|
|
239
|
+
interface ExportedImage {
|
|
240
|
+
blob: Blob
|
|
241
|
+
height: number
|
|
242
|
+
type: string
|
|
243
|
+
width: number
|
|
244
|
+
}
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
The edited image, which the [`apply`](./events#apply) event carries. `type` is the format of `blob`, which [`output`](./options#output) chooses.
|
|
248
|
+
|
|
249
|
+
### `PaperPicDownload`
|
|
250
|
+
|
|
251
|
+
```ts
|
|
252
|
+
interface PaperPicDownload {
|
|
253
|
+
filename: string
|
|
254
|
+
preventDefault: () => void
|
|
255
|
+
source: PaperPicSource
|
|
256
|
+
}
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
What the [`download`](./events#download) event carries. Call `preventDefault()` to save the file another way.
|
|
260
|
+
|
|
261
|
+
## Methods
|
|
262
|
+
|
|
263
|
+
### `ViewPoint`
|
|
264
|
+
|
|
265
|
+
```ts
|
|
266
|
+
interface ViewPoint {
|
|
267
|
+
x: number
|
|
268
|
+
y: number
|
|
269
|
+
}
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
A point in CSS pixels from the top left corner of the viewer, for [`zoomTo()`](./methods#zoomto).
|
|
273
|
+
|
|
274
|
+
## Vue and React
|
|
275
|
+
|
|
276
|
+
`@paperpic/vue` and `@paperpic/react` also export the types of their component. [Vue](./vue) and [React](./react) show how to use it.
|
|
277
|
+
|
|
278
|
+
### `PaperPicInstance`
|
|
279
|
+
|
|
280
|
+
```ts
|
|
281
|
+
type PaperPicInstance = PaperPic
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
The viewer that the component gives you: `instance` in Vue, and what `ref` receives in React. It is the class `PaperPic` of `@paperpic/core`, with every [method](./methods).
|
|
285
|
+
|
|
286
|
+
### `PaperPicProps`
|
|
287
|
+
|
|
288
|
+
```ts
|
|
289
|
+
interface PaperPicProps extends PaperPicOptions {
|
|
290
|
+
className?: string
|
|
291
|
+
onApply?: (result: PaperPicEvents['apply']) => void
|
|
292
|
+
onChange?: (state: PaperPicEvents['change']) => void
|
|
293
|
+
onDownload?: (download: PaperPicEvents['download']) => void
|
|
294
|
+
onError?: (failure: PaperPicEvents['error']) => void
|
|
295
|
+
onLoad?: (size: PaperPicEvents['load']) => void
|
|
296
|
+
ref?: Ref<PaperPicInstance>
|
|
297
|
+
style?: CSSProperties
|
|
298
|
+
}
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
The props of the component in React: the options, plus the classes and styles of its element, a callback for each event, and `ref`. In Vue, the props have the same fields as [`PaperPicOptions`](#paperpicoptions), and the events are component events.
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Vue
|
|
3
|
+
description: How the PaperPic component for Vue maps the options, events and methods of the core to props, component events and a template ref.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Vue
|
|
7
|
+
|
|
8
|
+
`@paperpic/vue` wraps the viewer in a component for Vue 3.5 or newer. The options are props, the events are component events, and the methods are on the `instance` that the component exposes.
|
|
9
|
+
|
|
10
|
+
```vue
|
|
11
|
+
<script setup lang="ts">
|
|
12
|
+
import type { ExportedImage } from '@paperpic/vue'
|
|
13
|
+
import { PaperPic } from '@paperpic/vue'
|
|
14
|
+
import '@paperpic/vue/style.css'
|
|
15
|
+
|
|
16
|
+
function upload({ blob }: ExportedImage) {
|
|
17
|
+
// Send the edited image to your server
|
|
18
|
+
}
|
|
19
|
+
</script>
|
|
20
|
+
|
|
21
|
+
<template>
|
|
22
|
+
<div style="height: 480px">
|
|
23
|
+
<PaperPic src="/receipt.jpg" alt="A receipt" @apply="upload" />
|
|
24
|
+
</div>
|
|
25
|
+
</template>
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
The component fills its parent element, so give the parent a height.
|
|
29
|
+
|
|
30
|
+
## Props
|
|
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()`.
|
|
33
|
+
|
|
34
|
+
Objects and arrays that the template builds, such as `:labels="{ apply: t('apply') }"`, are new on every render of the parent, and the viewer receives them again each time. Build them with `computed` instead.
|
|
35
|
+
|
|
36
|
+
## Events
|
|
37
|
+
|
|
38
|
+
| Event | Payload |
|
|
39
|
+
| ---------- | ---------------------------------------------- |
|
|
40
|
+
| `apply` | [`ExportedImage`](./types#exportedimage) |
|
|
41
|
+
| `change` | [`PaperPicState`](./state) |
|
|
42
|
+
| `download` | [`PaperPicDownload`](./types#paperpicdownload) |
|
|
43
|
+
| `error` | `{ error }` |
|
|
44
|
+
| `load` | [`Size`](./types#size) |
|
|
45
|
+
|
|
46
|
+
[Events](./events) describes each one. A change of a prop never emits `change`.
|
|
47
|
+
|
|
48
|
+
## Methods
|
|
49
|
+
|
|
50
|
+
The component exposes the viewer as `instance`, with every [method](./methods). It is `null` until the component mounts:
|
|
51
|
+
|
|
52
|
+
```vue
|
|
53
|
+
<script setup lang="ts">
|
|
54
|
+
import { PaperPic } from '@paperpic/vue'
|
|
55
|
+
import { useTemplateRef } from 'vue'
|
|
56
|
+
|
|
57
|
+
const pic = useTemplateRef('pic')
|
|
58
|
+
</script>
|
|
59
|
+
|
|
60
|
+
<template>
|
|
61
|
+
<button type="button" @click="pic?.instance?.zoomIn()">
|
|
62
|
+
Zoom in
|
|
63
|
+
</button>
|
|
64
|
+
<div style="height: 480px">
|
|
65
|
+
<PaperPic ref="pic" src="/receipt.jpg" :toolbar="false" />
|
|
66
|
+
</div>
|
|
67
|
+
</template>
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Passing the same `src` again does not reload the image, so it keeps the result of an edit. To bring back the original, call `instance.reload()`.
|
|
71
|
+
|
|
72
|
+
## Types {#types}
|
|
73
|
+
|
|
74
|
+
`@paperpic/vue` exports every type of `@paperpic/core`, so you do not need to install it: [Types](./types) shows each one. It also exports the types of the component: [`PaperPicProps`](./types#paperpicprops), with its props, and [`PaperPicInstance`](./types#paperpicinstance), the viewer in `instance`.
|
|
75
|
+
|
|
76
|
+
## Server-side rendering
|
|
77
|
+
|
|
78
|
+
With server-side rendering, such as in Nuxt, the component renders an empty element on the server and creates the viewer in the browser.
|