@paperpic/react 0.1.0 → 0.3.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.
@@ -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, phase: 'load' | 'preview' | 'apply' }
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.
@@ -31,17 +31,17 @@ The component fills its parent element, so give the parent a height.
31
31
 
32
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
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.
34
+ An object or array with the same contents as before, such as `:tools="['crop', 'rotate']"`, changes nothing, so the template can build them. A function is new on every render of the parent, so build `labels` that hold functions, such as `zoomLevel`, with `computed`.
35
35
 
36
36
  ## Events
37
37
 
38
- | Event | Payload |
39
- | ---------- | -------------------------------------- |
40
- | `apply` | `{ blob, width, height, type }` |
41
- | `change` | [`PaperPicState`](./state) |
42
- | `download` | `{ source, filename, preventDefault }` |
43
- | `error` | `{ error }` |
44
- | `load` | `{ width, height }` |
38
+ | Event | Payload |
39
+ | ---------- | ---------------------------------------------- |
40
+ | `apply` | [`ExportedImage`](./types#exportedimage) |
41
+ | `change` | [`PaperPicState`](./state) |
42
+ | `download` | [`PaperPicDownload`](./types#paperpicdownload) |
43
+ | `error` | `{ error, phase }` |
44
+ | `load` | [`Size`](./types#size) |
45
45
 
46
46
  [Events](./events) describes each one. A change of a prop never emits `change`.
47
47
 
@@ -69,9 +69,9 @@ const pic = useTemplateRef('pic')
69
69
 
70
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
71
 
72
- ## Types
72
+ ## Types {#types}
73
73
 
74
- `@paperpic/vue` exports the types you need, so you do not need to install `@paperpic/core`: `PaperPicProps`, `PaperPicState`, `PaperPicEvents`, `PaperPicIcons`, `PaperPicLabels`, `PaperPicOutput`, `PaperPicDownload`, `ExportedImage` and `ToolId`.
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
75
 
76
76
  ## Server-side rendering
77
77
 
package/dist/index.d.ts CHANGED
@@ -1,13 +1,13 @@
1
- import { ExportedImage, PaperPic as PaperPic$1, PaperPicDownload, PaperPicEvents, PaperPicEvents as PaperPicEvents$1, PaperPicIcons, PaperPicLabels, PaperPicOptions, PaperPicOutput, PaperPicState, ToolId } from "@paperpic/core";
1
+ import { ExportedImage, Fit, PaperPic as PaperPic$1, PaperPicDownload, PaperPicEvents, PaperPicEvents as PaperPicEvents$1, PaperPicIcons, PaperPicLabels, PaperPicOptions, PaperPicOptions as PaperPicOptions$1, PaperPicOutput, PaperPicSource, PaperPicState, Rotation, Size, ToolId, ViewPoint } from "@paperpic/core";
2
2
  import { CSSProperties, Ref } from "react";
3
3
  /** The viewer that `ref` receives, with the methods of `@paperpic/core`, such as `zoomIn()` or `reload()`. */
4
4
  type PaperPicInstance = PaperPic$1;
5
- interface PaperPicProps extends PaperPicOptions {
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
  /** The user applied the changes. The result is already on display. */
9
9
  onApply?: (result: PaperPicEvents$1['apply']) => void;
10
- /** The user changed the view or the edit. A change of props never calls it. */
10
+ /** The user changed something in the state, such as the zoom or the edit. A pan and a change of props never call it. */
11
11
  onChange?: (state: PaperPicEvents$1['change']) => void;
12
12
  /** The image is about to be saved. Call `preventDefault()` to save it another way. */
13
13
  onDownload?: (download: PaperPicEvents$1['download']) => void;
@@ -33,4 +33,4 @@ interface PaperPicProps extends PaperPicOptions {
33
33
  * </div>
34
34
  */
35
35
  export declare function PaperPic({ ref, className, style, onApply, onChange, onDownload, onError, onLoad, alt, aspectRatio, download, editable, filename, icons, labels, maxOutputSize, output, softness, src, toolbar, tools, wheelZoom }: PaperPicProps): import("react").JSX.Element;
36
- export type { ExportedImage, PaperPicDownload, PaperPicEvents, PaperPicIcons, PaperPicInstance, PaperPicLabels, PaperPicOutput, PaperPicProps, PaperPicState, ToolId };
36
+ export type { ExportedImage, Fit, PaperPicDownload, PaperPicEvents, PaperPicIcons, PaperPicInstance, PaperPicLabels, PaperPicOptions, PaperPicOutput, PaperPicProps, PaperPicSource, PaperPicState, Rotation, Size, ToolId, ViewPoint };
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "@paperpic/react",
3
3
  "type": "module",
4
- "version": "0.1.0",
5
- "description": "React components to view and edit document images with PaperPic.",
4
+ "version": "0.3.0",
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",
8
8
  "homepage": "https://paperpic.dev",
@@ -42,7 +42,7 @@
42
42
  "react": "^19.0.0"
43
43
  },
44
44
  "dependencies": {
45
- "@paperpic/core": "0.1.0"
45
+ "@paperpic/core": "0.3.0"
46
46
  },
47
47
  "devDependencies": {
48
48
  "@arethetypeswrong/core": "0.18.5",