@paperpic/core 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.
@@ -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 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:
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
- pic.on('change', ({ canApply, busy }) => {
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
- | 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 |
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 from the same origin, or a `File` or `Blob` attached on the client. The `source` of [`PaperPicDownload`](#paperpicdownload) has the same type.
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 every [method](./methods). It is `null` until the component mounts:
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
@@ -249,7 +249,7 @@ interface PaperPicState {
249
249
  };
250
250
  /** Whether the changes are being applied. */
251
251
  busy: boolean;
252
- /** Whether there are changes to apply. Rotations that cancel out are no change. */
252
+ /** Whether there are changes to apply. Rotations and flips that cancel out are no change. */
253
253
  canApply: boolean;
254
254
  /** Whether there is an edit to bring back. */
255
255
  canRedo: boolean;
@@ -257,11 +257,14 @@ interface PaperPicState {
257
257
  canUndo: boolean;
258
258
  /** The fit in effect, or `null` once the user has zoomed by hand. */
259
259
  fit: Fit | null;
260
- /** The size of the image on display in pixels, with the edits so far, or `null` if there is none. */
260
+ /**
261
+ * The size of the image in pixels, at full resolution and with the edits so far, but without the turn of `rotation`,
262
+ * or `null` if there is none.
263
+ */
261
264
  image: Size | null;
262
265
  /** Whether the user is viewing or editing the image. */
263
266
  mode: 'view' | 'edit';
264
- /** How far the image on display is turned, in degrees clockwise. */
267
+ /** How far the image on display is turned from `image`, in degrees clockwise. */
265
268
  rotation: Rotation;
266
269
  /** Whether there is an image, and whether it loaded. */
267
270
  status: 'empty' | 'loading' | 'ready' | 'error';
@@ -279,9 +282,12 @@ interface PaperPicState {
279
282
  * @see https://paperpic.dev/reference/events
280
283
  */
281
284
  interface PaperPicEvents {
282
- /** The user applied the changes. The result is already on display. */
285
+ /** Apply finished, from the button, `Enter` or `apply()`. The result is already on display. */
283
286
  apply: ExportedImage;
284
- /** The user changed something in the state, such as the zoom or the edit. A pan and `setOptions()` never trigger it. */
287
+ /**
288
+ * The user or a method changed the state, such as the zoom or the edit. A loaded image comes with `load`, and a failed
289
+ * Apply with `error`, instead. A pan, `setOptions()` and the props of the components never trigger it.
290
+ */
285
291
  change: PaperPicState;
286
292
  /** The image is about to be saved. Call `preventDefault()` to save it another way. */
287
293
  download: PaperPicDownload;
@@ -293,7 +299,7 @@ interface PaperPicEvents {
293
299
  error: Error;
294
300
  phase: 'load' | 'preview' | 'apply';
295
301
  };
296
- /** The image is ready. */
302
+ /** The image of `src` is ready, also after `reload()`. Apply does not trigger it. */
297
303
  load: Size;
298
304
  }
299
305
  type Listener<Name extends keyof PaperPicEvents> = (payload: PaperPicEvents[Name]) => void;
@@ -462,7 +468,7 @@ export declare class PaperPic {
462
468
  cancel(): void;
463
469
  /**
464
470
  * Applies the edits. The result becomes the image on display, and the `apply` event carries it.
465
- * If it fails, the `error` event reports it and the edit stays open.
471
+ * If it fails, the `error` event reports it and the edit stays open. The promise resolves either way.
466
472
  *
467
473
  * @example
468
474
  * pic.on('apply', ({ blob, type }) => upload(blob, type))
package/dist/index.js CHANGED
@@ -2752,7 +2752,7 @@ var PaperPic = class {
2752
2752
  }
2753
2753
  /**
2754
2754
  * Applies the edits. The result becomes the image on display, and the `apply` event carries it.
2755
- * If it fails, the `error` event reports it and the edit stays open.
2755
+ * If it fails, the `error` event reports it and the edit stays open. The promise resolves either way.
2756
2756
  *
2757
2757
  * @example
2758
2758
  * pic.on('apply', ({ blob, type }) => upload(blob, type))
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@paperpic/core",
3
3
  "type": "module",
4
- "version": "0.3.0",
4
+ "version": "0.3.1",
5
5
  "description": "Document image viewer and editor for the browser: straighten, crop, rotate and clean up phone photos, scans and any image with text. Use it with plain JavaScript or through a PaperPic wrapper.",
6
6
  "author": "Marco Caparrós <hello@paperpic.dev>",
7
7
  "license": "MIT",