@paperpic/core 0.2.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.
Files changed (37) hide show
  1. package/dist/docs/examples/attach-and-scan.md +202 -0
  2. package/dist/docs/examples/custom-toolbar.md +196 -2
  3. package/dist/docs/examples/dialog.md +191 -0
  4. package/dist/docs/examples/fixed-proportions.md +1 -0
  5. package/dist/docs/examples/form.md +156 -0
  6. package/dist/docs/examples/upload.md +1 -1
  7. package/dist/docs/guide/accessibility.md +5 -5
  8. package/dist/docs/guide/editing.md +9 -18
  9. package/dist/docs/guide/getting-started.md +84 -11
  10. package/dist/docs/guide/introduction.md +1 -1
  11. package/dist/docs/guide/labels.md +2 -4
  12. package/dist/docs/guide/loading.md +130 -0
  13. package/dist/docs/guide/performance.md +17 -3
  14. package/dist/docs/guide/saving.md +17 -9
  15. package/dist/docs/guide/styling.md +2 -0
  16. package/dist/docs/guide/tools/adjust.md +4 -2
  17. package/dist/docs/guide/tools/clean-up.md +1 -1
  18. package/dist/docs/guide/tools/crop.md +3 -1
  19. package/dist/docs/guide/tools/rotate-and-flip.md +3 -1
  20. package/dist/docs/guide/tools/straighten.md +1 -1
  21. package/dist/docs/guide/troubleshooting.md +45 -0
  22. package/dist/docs/guide/viewer.md +12 -10
  23. package/dist/docs/reference/events.md +20 -7
  24. package/dist/docs/reference/labels.md +2 -2
  25. package/dist/docs/reference/methods.md +71 -15
  26. package/dist/docs/reference/options.md +9 -9
  27. package/dist/docs/reference/react.md +8 -4
  28. package/dist/docs/reference/state.md +113 -19
  29. package/dist/docs/reference/types.md +2 -2
  30. package/dist/docs/reference/vue.md +8 -6
  31. package/dist/index.d.ts +75 -50
  32. package/dist/index.js +1469 -1350
  33. package/dist/{pipeline-MP1RPlXT.js → steps-DuGiMvk0.js} +236 -75
  34. package/dist/types-C3ZHKId1.d.ts +31 -0
  35. package/dist/worker.d.ts +13 -61
  36. package/dist/worker.js +3 -10
  37. package/package.json +2 -2
@@ -21,19 +21,19 @@ Apply computes the result and fires [`apply`](../reference/events#apply) with:
21
21
  == JavaScript
22
22
 
23
23
  ```ts
24
- pic.on('apply', result => upload(result))
24
+ pic.on('apply', ({ blob, type }) => upload(blob, type))
25
25
  ```
26
26
 
27
27
  == Vue
28
28
 
29
29
  ```vue
30
- <PaperPic src="/receipt.jpg" @apply="upload" />
30
+ <PaperPic src="/receipt.jpg" @apply="({ blob, type }) => upload(blob, type)" />
31
31
  ```
32
32
 
33
33
  == React
34
34
 
35
35
  ```tsx
36
- <PaperPic src="/receipt.jpg" onApply={upload} />
36
+ <PaperPic src="/receipt.jpg" onApply={({ blob, type }) => upload(blob, type)} />
37
37
  ```
38
38
 
39
39
  :::
@@ -45,7 +45,7 @@ After Apply, the result is the image on display, the history is empty, and the n
45
45
  Send the `blob` as a file in a form:
46
46
 
47
47
  ```ts
48
- async function upload({ blob, type }: { blob: Blob, type: string }) {
48
+ async function upload(blob: Blob, type: string) {
49
49
  const body = new FormData()
50
50
  body.append('image', blob, `document.${type.split('/')[1]}`)
51
51
  const response = await fetch('/api/documents', { method: 'POST', body })
@@ -57,9 +57,9 @@ async function upload({ blob, type }: { blob: Blob, type: string }) {
57
57
 
58
58
  The viewer shows the result at once, whether or not it reaches your server, so tell the user when the upload fails.
59
59
 
60
- ## Format and quality
60
+ ## Format and quality {#format}
61
61
 
62
- Without options, the result keeps the format of the source: JPEG, PNG or WebP. A cleaned up document is PNG, because JPEG would add artifacts around its sharp edges. Any other source, such as a GIF, gives PNG.
62
+ Without options, the result keeps the format of the source when it is JPEG, PNG or WebP. PaperPic reads it from the extension of the URL, such as `.jpg`, or from the type of the `File` or `Blob`. A cleaned up document is PNG, because JPEG would add artifacts around its sharp edges. Any other source gives PNG too, such as a GIF, or a URL without an extension like `/api/documents/42`, even when it serves a JPEG.
63
63
 
64
64
  [`output`](../reference/options#output) chooses the format, and its quality from 0 to 1 for JPEG and WebP, with 0.92 by default:
65
65
 
@@ -127,13 +127,21 @@ const pic = new PaperPic(container, {
127
127
 
128
128
  :::
129
129
 
130
- The preview while editing is always about 2 megapixels, so `maxOutputSize` changes only the result.
130
+ The preview while editing has at most about 2 megapixels, so `maxOutputSize` changes only the result.
131
131
 
132
- ## The download button
132
+ Safari on iOS limits a canvas to about 16 megapixels, and recent iPhones take photos of 24 megapixels or more, so Apply can fail at full resolution. If your users edit photos from an iPhone, set `maxOutputSize`. 3000 pixels keeps documents readable and stays well below the limit. [Apply fails with a large photo](./troubleshooting#too-large) shows the error.
133
+
134
+ ## Metadata {#metadata}
135
+
136
+ The result of Apply carries no metadata. PaperPic draws the image on a canvas, so the EXIF data of the photo, such as the GPS position, the camera and the date, is gone. The download button saves the source as it is until the first Apply, with its metadata.
137
+
138
+ ## The download button {#download}
133
139
 
134
140
  [`download: true`](../reference/options#download) adds a button at the end of the toolbar that saves the image on display: the result of the last Apply, or else the source as it is. It is hidden while editing, because the edits are not applied yet. [`download()`](../reference/methods#download) does the same from code, with or without the button. The browser's context menu does not open over the viewer, so this button is the way to save the image from it.
135
141
 
136
- The file keeps the name of the source and takes the extension of its format, so a cleaned up `receipt.jpg` saves as `receipt.png`. [`filename`](../reference/options#filename) sets another name. Without any name, such as for a `Blob`, the file is called `image`.
142
+ The file keeps the name of the source and takes the extension of its format, so a cleaned up `receipt.jpg` saves as `receipt.png`. [`filename`](../reference/options#filename) sets another name. Without any name, such as for a `Blob`, the file is called `image`. Before the first Apply, a URL without an extension saves without one, because its format is unknown.
143
+
144
+ With a `src` from another origin, browsers do not save the file before the first Apply: they open the image instead, and the user leaves your page. Pass the image as a `Blob`, as [Loading images](./loading#fetch) shows, or save it yourself in the `download` event.
137
145
 
138
146
  ### Save it another way
139
147
 
@@ -55,6 +55,8 @@ Five [CSS tokens](../reference/css-tokens) set the surface, the text, the accent
55
55
  }
56
56
  ```
57
57
 
58
+ <Demo src="/samples/receipt.jpg" alt="A receipt" style="--paperpic-color-accent: #c2410c; --paperpic-radius: 0" />
59
+
58
60
  The tokens are inherited, so a class on the container of one viewer, or on the Vue or React component, changes that viewer only:
59
61
 
60
62
  ```css
@@ -7,13 +7,15 @@ description: How the Adjust tool of PaperPic changes the brightness and the cont
7
7
 
8
8
  Photos taken in poor light come out dark or gray. Adjust changes the brightness and the contrast and keeps the colors, for documents that should not become black and white, such as colored forms or photos.
9
9
 
10
+ <Demo src="/samples/receipt.jpg" alt="A receipt" :tools="['adjust']" />
11
+
10
12
  ## Use it
11
13
 
12
14
  1. Press Edit, then Adjust. Its panel takes the place of the tools: a ruler, and Brightness and Contrast to choose which tone it changes.
13
15
  2. Drag the ruler. The preview changes while you drag. Choose Contrast to change the other tone with the same ruler.
14
16
  3. Press Done to keep both tones as one edit, which Undo removes. Cancel this tool leaves the image as it was.
15
17
 
16
- The middle of the ruler leaves the image as it is, and the needle catches there, so no change is easy to find again. Screen readers announce the value from -100 to 100, such as "Brightness +30". A dot on Adjust marks values that are not 0.
18
+ The middle of the ruler leaves the image as it is, and the needle catches there, so it is easy to go back to no change. Screen readers announce the value from -100 to 100, such as "Brightness +30". A dot on Adjust marks values that are not 0.
17
19
 
18
20
  Adjust runs after the other edits, so Crop and Straighten show the image with it.
19
21
 
@@ -25,7 +27,7 @@ Adjust runs after the other edits, so Crop and Straighten show the image with it
25
27
  | For colored forms, stamps and photos | For text on paper |
26
28
  | Keeps the format of the source | Gives PNG |
27
29
 
28
- While Clean up is on, Adjust is disabled, because a cleaned up document has tones of its own.
30
+ While Clean up is on, Adjust is disabled. Clean up compares each pixel with its surroundings, so brightness and contrast would barely change its result.
29
31
 
30
32
  ## From code
31
33
 
@@ -17,7 +17,7 @@ Straighten the receipt first, then clean it up.
17
17
  2. Drag the ruler. Higher sensitivity darkens more pixels, which recovers faint or worn text. Lower sensitivity gives a cleaner page, without the print that shows through from the back.
18
18
  3. Press Done to keep it as one edit, or Cancel this tool to leave the image as it was.
19
19
 
20
- To turn off a Clean up that is already an edit, open it again: a switch next to the ruler turns it off, and the edits that came after it stay. Undo would take those edits away first.
20
+ To turn off a Clean up that is already an edit, open it again: a switch next to the ruler turns it off, and the edits that came after it stay. Undo, instead, would also remove those edits.
21
21
 
22
22
  Clean up always runs after the other edits. Crop shows the image cleaned up, as it will be. Straighten shows it without Clean up, because the edges of the paper are hard to find on a cleaned up page.
23
23
 
@@ -7,6 +7,8 @@ description: How the Crop tool of PaperPic keeps the part of a photo that holds
7
7
 
8
8
  A photo of a document often shows the table, a hand or other papers around it. Crop keeps the rectangle that holds the document and drops the rest.
9
9
 
10
+ <Demo src="/samples/receipt.jpg" alt="A receipt" :tools="['crop']" />
11
+
10
12
  ## Use it
11
13
 
12
14
  1. Press Edit, then Crop. A rectangle appears inside the image, with a handle at each corner.
@@ -18,7 +20,7 @@ While Crop is open, the image looks as the result will, with Adjust and Clean up
18
20
  ## Corner handles
19
21
 
20
22
  - The handles stay inside the image, and the rectangle never turns inside out.
21
- - On a touch screen, a magnifier shows the area under the finger while it drags a corner, so the finger does not hide where the corner lands.
23
+ - With a finger or a pen, a magnifier shows the area under it while it drags a corner, so it does not hide where the corner lands.
22
24
  - Without dragging, press a handle and then tap where its corner goes. The handle stays highlighted until then, the zoom buttons zoom toward its corner, and `Esc` lets go of it.
23
25
  - With the keyboard, Tab moves between the handles, and the arrow keys move the focused handle 1 screen pixel, or 10 with Shift. `+` and `-` zoom toward the focused handle. Screen readers announce each move.
24
26
 
@@ -7,6 +7,8 @@ description: How to rotate and flip a document image in PaperPic, in the edit mo
7
7
 
8
8
  Phones often save a photo of a document sideways or upside down, and some scans come out mirrored. Rotate left and Flip fix the orientation and leave the rest of the image as it is.
9
9
 
10
+ <Demo src="/samples/receipt.jpg" alt="A receipt" :tools="['rotate', 'flip']" />
11
+
10
12
  ## Rotate
11
13
 
12
14
  In the edit bar, Rotate left turns the image a quarter turn counterclockwise, as in photo galleries. Press it twice for a half turn, or three times for a quarter turn clockwise.
@@ -22,7 +24,7 @@ pic.rotate(-1)
22
24
 
23
25
  ## Flip
24
26
 
25
- Flip mirrors the image left to right, as it is on display, so after a quarter turn it still mirrors left to right on the screen. To turn an image upside down, flip it and rotate it twice.
27
+ Flip mirrors the image left to right, as it is on display, so after a quarter turn it still mirrors left to right on the screen. To mirror an image top to bottom, flip it and rotate it twice.
26
28
 
27
29
  Flips and rotations that cancel out leave nothing to apply. From code, call [`flip()`](../../reference/methods#flip).
28
30
 
@@ -57,7 +57,7 @@ const pic = new PaperPic(container, {
57
57
  | US Letter sheet, portrait | `8.5 / 11` |
58
58
  | ID card, landscape | `85.6 / 53.98` |
59
59
 
60
- For a sheet in landscape, swap the numbers, such as `297 / 210`.
60
+ For a sheet in landscape, swap the numbers, such as `297 / 210`. The proportions apply to the page as it shows on screen, so turn a sideways photo with [Rotate left](./rotate-and-flip) before you straighten it.
61
61
 
62
62
  ## Corners cut off by the photo
63
63
 
@@ -0,0 +1,45 @@
1
+ ---
2
+ title: Troubleshooting
3
+ description: What to do when the PaperPic viewer has no height or no style, Tailwind CSS changes it, an image does not load or cannot be edited, the page freezes on Apply, or a large photo fails.
4
+ ---
5
+
6
+ # Troubleshooting
7
+
8
+ Most problems with PaperPic come from its setup, and not from the image. Find what you see, and the fix below it.
9
+
10
+ ## The viewer is a thin strip, or does not show {#no-height}
11
+
12
+ The viewer fills its container, and a container without a height collapses to the minimum height of the viewer, 16rem. Give the container a height, such as `height: 480px`, or a place in a flex or grid layout that gives it one. [Styling](./styling) shows both.
13
+
14
+ ## The buttons have no style, and the console warns {#no-stylesheet}
15
+
16
+ The console says `PaperPic: the stylesheet is missing, so the viewer has no layout.` Import the stylesheet once in your app: `@paperpic/core/style.css`, or the `style.css` of `@paperpic/vue` or `@paperpic/react`.
17
+
18
+ ## Tailwind CSS removes the borders and the padding of the viewer {#tailwind}
19
+
20
+ The reset of Tailwind CSS 4 wins over the stylesheet of PaperPic when the cascade layers come in the wrong order. Name the layers before you import both, as [Styling](./styling#tailwind) shows.
21
+
22
+ ## The image shows, but editing it fails {#other-origin}
23
+
24
+ The [`error`](../reference/events#error) says that the image comes from another origin. Browsers do not let PaperPic read the pixels of such an image. Fetch it yourself and pass the `Blob`, as [Loading images](./loading#fetch) shows.
25
+
26
+ ## The image does not load {#load-error}
27
+
28
+ The viewer shows that the image could not be loaded, and `error` carries `phase: 'load'`. Check that the URL exists, and that the browser opens the format: HEIC only opens in Safari, and an SVG needs `width` and `height` attributes. [Loading images](./loading#formats) lists the formats.
29
+
30
+ ## The page freezes while Apply runs {#worker}
31
+
32
+ The worker did not start, so the editing runs on the main thread. It still works, but large photos freeze the page for a moment. The usual causes are:
33
+
34
+ - A Content Security Policy without `worker-src 'self'`, or one that requires Trusted Types without a `default` policy. [Performance and support](./performance) lists what to allow.
35
+ - The package loaded from a CDN, from another origin than the page. Browsers only start a worker from the origin of the page.
36
+
37
+ The network panel of the browser shows whether the page requested the worker file, whose name starts with `worker`.
38
+
39
+ ## Apply fails with a large photo {#too-large}
40
+
41
+ The `error` says `The browser could not read an image of …`, or `could not save an image of …`. Browsers limit the size of a canvas, and Safari on iOS the most. Set [`maxOutputSize`](../reference/options#maxoutputsize), such as to 3000 pixels, which keeps documents readable.
42
+
43
+ ## The wheel zooms the image instead of scrolling the page {#wheel}
44
+
45
+ Set [`wheelZoom: false`](../reference/options#wheelzoom). The buttons, the keyboard and a pinch still zoom.
@@ -18,31 +18,33 @@ Small print and long receipts are hard to read at a glance on a screen. The view
18
18
  | Switch between the fit and 100% | Double click | Double tap | |
19
19
  | Fit the whole image | | | `0` |
20
20
 
21
- The keyboard works with the focus on the viewer. A pinch zooms around the point between the fingers. On a touch screen, one finger scrolls the page while the image is fitted, and pans the image once it is zoomed in.
21
+ The keys work while the focus is inside the viewer. On a button, the arrow keys move between the buttons instead, and while there is nothing to move, they scroll the page. A pinch zooms around the point between the fingers. On a touch screen, one finger scrolls the page while the image is fitted, and pans the image once it is zoomed in.
22
22
 
23
23
  The zoom goes from the fit of the whole image, or 100% for a small image, up to 800%. An image that fits stays centered, and one that overflows pans up to its edges.
24
24
 
25
25
  When the image loads, it fits the viewer whole, and it keeps its fit when the viewer changes size, until the user zooms by hand.
26
26
 
27
- In a long page, the wheel would zoom the image instead of scrolling the page. Set `wheelZoom: false` there: the buttons, the keyboard and a pinch on a touch screen still zoom.
27
+ In a long page, the wheel would zoom the image instead of scrolling the page. Set `wheelZoom: false` there: the buttons, the keyboard and a pinch on a touch screen still zoom. A pinch on a trackpad no longer zooms the image, because the browser reports it as the wheel.
28
28
 
29
29
  ## The toolbar
30
30
 
31
31
  The toolbar sits at the right of the viewer, and scrolls when the viewer is too short for its buttons. It hides while editing, so it never covers a corner of Crop or Straighten.
32
32
 
33
- | Button | What it does |
34
- | --------------------------- | ---------------------------------------------------------------- |
35
- | Edit | Starts the [edit mode](./editing). Hidden with `editable: false` |
36
- | Zoom in, Zoom out | Zoom one step, around the center |
37
- | Fit to width, Fit to height | Fit the width, which suits long documents, or the height |
38
- | Rotate left, Rotate right | Only in a read-only viewer: turn the image on display |
39
- | Download | Only with `download: true`: save the image on display |
33
+ | Button | What it does |
34
+ | --------------------------- | ----------------------------------------------------------------------------------------------------- |
35
+ | Edit | Starts the [edit mode](./editing). It shows once the image is ready, and never with `editable: false` |
36
+ | Zoom in, Zoom out | Zoom one step of 25%, around the center |
37
+ | Fit to width, Fit to height | Fit the width, which suits long documents, or the height |
38
+ | Rotate left, Rotate right | Only in a read-only viewer: turn the image on display |
39
+ | Download | Only with `download: true`: save the image on display |
40
+
41
+ Fit to width and Fit to height stay pressed while their fit holds. No button fits the whole image again: press `0`, or zoom out all the way.
40
42
 
41
43
  With `toolbar: false`, the toolbar and the edit bar are hidden, and you can build your own controls with the [methods](../reference/methods).
42
44
 
43
45
  ## Read-only viewer {#read-only}
44
46
 
45
- With `editable: false`, the Edit button goes away, and the toolbar gets two buttons that rotate the image. That rotation only changes the display, and nothing is saved. Use it for documents that people should read but not change, such as the attachments of a record.
47
+ With `editable: false`, the Edit button goes away, and the toolbar gets two buttons that rotate the image. That rotation only changes the display, and nothing is saved: Download saves the image without it. Use it for documents that people should read but not change, such as the attachments of a record.
46
48
 
47
49
  :::tabs key:framework
48
50
  == JavaScript
@@ -1,11 +1,11 @@
1
1
  ---
2
2
  title: Events
3
- description: The events of PaperPic and what each one carries, load, error, change, apply and download, with how to listen to them in JavaScript, Vue and React.
3
+ description: The events of PaperPic (load, error, change, apply and download), what each one carries, and how to listen to them in JavaScript, Vue and React.
4
4
  ---
5
5
 
6
6
  # Events
7
7
 
8
- Events tell your code what happens in the viewer. Listen to them with [`on()`](./methods#on). In Vue they are component events, such as `@apply`, and in React they are props, such as `onApply`.
8
+ Events tell your code what happens in the viewer. Listen to them with [`on()`](./methods#on). In Vue they are component events, such as `@apply`, and in React they are props, such as `onApply`. A listener that throws does not stop the viewer: the page gets the error as any uncaught one, and the other listeners still run.
9
9
 
10
10
  :::tabs key:framework
11
11
  == JavaScript
@@ -32,25 +32,38 @@ pic.on('apply', ({ blob }) => upload(blob))
32
32
 
33
33
  - **Payload:** [`Size`](./types#size)
34
34
 
35
- The image is loaded and on display. `width` and `height` are its size in pixels.
35
+ The image is loaded and on display. `width` and `height` are its size in pixels. It fires each time a `src` loads, also with [`reload()`](./methods#reload), but not after Apply, whose result comes with [`apply`](#apply).
36
36
 
37
37
  ## `error`
38
38
 
39
- - **Payload:** `{ error: Error }`
39
+ - **Payload:** `{ error: Error, phase: 'load' | 'preview' | 'apply' }`
40
40
 
41
- The image could not be loaded, or the edits could not be applied. After a failed Apply, the edit stays open.
41
+ Something failed, and `phase` says what:
42
+
43
+ - `'load'`: the image could not be loaded.
44
+ - `'preview'`: an edit could not be shown, as when the image is too large for the browser. The edit stays open.
45
+ - `'apply'`: the changes could not be applied. The edit stays open.
42
46
 
43
47
  ## `change`
44
48
 
45
49
  - **Payload:** [`PaperPicState`](./state)
46
50
 
47
- The user changed the view or the edit, such as by zooming, opening a tool or undoing. It also reports the start of Apply, with `busy: true`. `setOptions()` and the props of the components never emit it.
51
+ The state changed, through the user or through a method, such as by zooming, opening a tool or undoing. It carries the whole state, the same that [`getState()`](./methods#getstate) would return at that moment. Apply emits it twice: when it starts, with `busy: true`, and when it ends well, after [`apply`](#apply).
52
+
53
+ These change the state without emitting `change`:
54
+
55
+ - Loading an image, which [`load`](#load) or [`error`](#error) reports.
56
+ - An Apply that fails, which [`error`](#error) reports. `busy` is `false` again.
57
+ - `setOptions()` and the props of the components, so two-way bindings do not loop.
58
+ - A resize of the viewer, which changes `zoom` while a fit is in effect.
59
+
60
+ A pan emits nothing, because the state does not hold the position of the image. [State](./state#in-step) shows how to keep controls of your own in step.
48
61
 
49
62
  ## `apply`
50
63
 
51
64
  - **Payload:** [`ExportedImage`](./types#exportedimage)
52
65
 
53
- The user applied the edits, and the result is already on display. `blob` holds the image in the format `type`, which [`output`](./options#output) chooses.
66
+ Apply finished, from the button, `Enter` or [`apply()`](./methods#apply), and the result is already on display. `blob` holds the image in the format `type`, which [`output`](./options#output) chooses.
54
67
 
55
68
  ## `download`
56
69
 
@@ -18,7 +18,7 @@ const pic = new PaperPic(container, {
18
18
  })
19
19
  ```
20
20
 
21
- Five labels are functions, because their text includes a value. Create the object once, and not on every render, so the viewer does not receive it again each time.
21
+ Five labels are functions, because their text includes a value. A function is new each time it is created, and the viewer takes a new one as a change, so create the labels that hold functions once, and not on every render.
22
22
 
23
23
  | Key | English | Use |
24
24
  | ---------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
@@ -26,7 +26,7 @@ Five labels are functions, because their text includes a value. Create the objec
26
26
  | `adjustmentLevel` | Brightness +30 | Function of the name and the value from -100 to 100, announced after moving the ruler of Adjust |
27
27
  | `applied` | Changes applied | Announced when the changes are applied |
28
28
  | `apply` | Apply | The button that applies the changes |
29
- | `applyError` | The changes could not be applied | Shown when Apply fails |
29
+ | `applyError` | The changes could not be applied | Shown when Apply fails, or when an edit cannot be shown |
30
30
  | `brightness` | Brightness | The choice of brightness in Adjust, and the name of its ruler |
31
31
  | `cancel` | Cancel | The button that leaves the edit mode |
32
32
  | `cancelTool` | Cancel this tool | The button that closes a tool and discards its changes |
@@ -5,7 +5,10 @@ description: Every method of the PaperPic class, to control the viewer from your
5
5
 
6
6
  # Methods
7
7
 
8
- The methods control the viewer from your own code, such as from buttons of your own with [`toolbar: false`](./options#toolbar). In Vue and React, the component ref gives you the viewer: see [Vue](./vue) and [React](./react).
8
+ The methods control the viewer from your own code, such as from buttons of your own with [`toolbar: false`](./options#toolbar). With the core, call them on the `PaperPic` you create. In Vue, the component exposes the viewer as `instance`, and in React, `ref` receives it. Both are `null` until the component mounts:
9
+
10
+ :::tabs key:framework
11
+ == JavaScript
9
12
 
10
13
  ```ts
11
14
  import { PaperPic } from '@paperpic/core'
@@ -15,6 +18,51 @@ const pic = new PaperPic(container, { src: '/receipt.jpg' })
15
18
  pic.zoomIn()
16
19
  ```
17
20
 
21
+ == Vue
22
+
23
+ ```vue
24
+ <script setup lang="ts">
25
+ import { PaperPic } from '@paperpic/vue'
26
+ import { useTemplateRef } from 'vue'
27
+
28
+ const pic = useTemplateRef('pic')
29
+ </script>
30
+
31
+ <template>
32
+ <button type="button" @click="pic?.instance?.zoomIn()">
33
+ Zoom in
34
+ </button>
35
+ <div style="height: 480px">
36
+ <PaperPic ref="pic" src="/receipt.jpg" />
37
+ </div>
38
+ </template>
39
+ ```
40
+
41
+ == React
42
+
43
+ ```tsx
44
+ import type { PaperPicInstance } from '@paperpic/react'
45
+ import { PaperPic } from '@paperpic/react'
46
+ import { useRef } from 'react'
47
+
48
+ export function Receipt() {
49
+ const picRef = useRef<PaperPicInstance>(null)
50
+
51
+ return (
52
+ <>
53
+ <button type="button" onClick={() => picRef.current?.zoomIn()}>Zoom in</button>
54
+ <div style={{ height: 480 }}>
55
+ <PaperPic ref={picRef} src="/receipt.jpg" />
56
+ </div>
57
+ </>
58
+ )
59
+ }
60
+ ```
61
+
62
+ :::
63
+
64
+ In Vue and React, the component creates and destroys the viewer, and takes the options as props and the events as events of its own. So do not call [`new PaperPic()`](#new-paperpic), [`destroy()`](#destroy), [`setOptions()`](#setoptions) or [`on()`](#on) there.
65
+
18
66
  ## Create and destroy
19
67
 
20
68
  ### `new PaperPic()`
@@ -27,7 +75,9 @@ class PaperPic {
27
75
 
28
76
  Creates the viewer inside `container`, which it fills. Give the container a height, or the viewer stays at its minimum height. [Options](./options) lists what `options` takes.
29
77
 
30
- It throws a `TypeError` if `container` is not an element. Create the viewer once the element exists, such as on mount.
78
+ It throws a `TypeError` if `container` is not an element. Create the viewer once the element exists, such as on mount. It throws a `RangeError` if an option is out of its range.
79
+
80
+ Only with the core: the Vue and React components create the viewer when they mount.
31
81
 
32
82
  ### `destroy()`
33
83
 
@@ -37,6 +87,8 @@ function destroy(): void
37
87
 
38
88
  Removes the viewer and releases everything it holds, such as its worker and the memory of its images. Calling it twice is safe.
39
89
 
90
+ Only with the core: the Vue and React components call it when they unmount. Called on their viewer, it would leave the component empty.
91
+
40
92
  ## Options and state
41
93
 
42
94
  ### `setOptions()`
@@ -45,7 +97,9 @@ Removes the viewer and releases everything it holds, such as its worker and the
45
97
  function setOptions(options: PaperPicOptions): void
46
98
  ```
47
99
 
48
- Changes the options you pass and keeps the others. `undefined` brings an option back to its default. It never emits `change`, so two-way bindings do not loop.
100
+ Changes the options you pass and keeps the others. `undefined` brings an option back to its default. It never emits `change`, so two-way bindings do not loop. It throws a `RangeError` if an option is out of its range, and then no option changes.
101
+
102
+ In Vue and React, change the props instead. The next change of any prop sends every option again, which would undo a change made with `setOptions()`.
49
103
 
50
104
  ### `getState()`
51
105
 
@@ -53,7 +107,7 @@ Changes the options you pass and keeps the others. `undefined` brings an option
53
107
  function getState(): PaperPicState
54
108
  ```
55
109
 
56
- Returns what the viewer is showing, such as the zoom, the mode and whether there are changes to apply. [State](./state) describes every field.
110
+ Returns the current state of the viewer, such as the zoom, the mode and whether there are changes to apply. To hear of each change instead of asking, listen to [`change`](./events#change). [State](./state) describes every field, and how the two fit together.
57
111
 
58
112
  ### `on()`
59
113
 
@@ -69,6 +123,8 @@ const off = pic.on('apply', ({ blob }) => upload(blob))
69
123
  off()
70
124
  ```
71
125
 
126
+ In Vue and React, listen to the events of the component instead, such as `@apply` or `onApply`.
127
+
72
128
  ## View
73
129
 
74
130
  ### `zoomIn()`
@@ -121,7 +177,7 @@ Starts editing. It does nothing if the image is not ready or [`editable`](./opti
121
177
  function rotate(direction?: 1 | -1): void
122
178
  ```
123
179
 
124
- Turns the image a quarter turn: clockwise with `1`, the default, and counterclockwise with `-1`. While editing, it is an edit that [`apply()`](#apply) makes permanent. In a read-only viewer, it only changes the display. Otherwise, it does nothing.
180
+ Turns the image a quarter turn: clockwise with `1`, the default, and counterclockwise with `-1`. While editing, it adds an edit that [`apply()`](#apply) makes permanent, and it does nothing while a tool is open or Apply runs. In a read-only viewer, it only changes the display. Otherwise, it does nothing.
125
181
 
126
182
  ### `flip()`
127
183
 
@@ -129,7 +185,7 @@ Turns the image a quarter turn: clockwise with `1`, the default, and countercloc
129
185
  function flip(): void
130
186
  ```
131
187
 
132
- Mirrors the image left to right as it is on display, so after a quarter turn it still mirrors left to right. To turn the image upside down, flip it and rotate it twice. It is an edit, and it does nothing outside the edit mode or while a tool is open.
188
+ Mirrors the image left to right as it is on display, so after a quarter turn it still mirrors left to right. To mirror it top to bottom, flip it and rotate it twice. It is an edit, and it does nothing outside the edit mode or while a tool is open.
133
189
 
134
190
  ### `openTool()`
135
191
 
@@ -137,7 +193,7 @@ Mirrors the image left to right as it is on display, so after a quarter turn it
137
193
  function openTool(id: ToolId): void
138
194
  ```
139
195
 
140
- Opens a tool with a panel: Crop, with `'crop'`, Straighten, with `'perspective'`, Adjust, with `'adjust'`, or Clean up, with `'threshold'`, which turns on as it opens. The tool stays open until [`confirmTool()`](#confirmtool) or [`cancelTool()`](#canceltool), and meanwhile the other edits, Undo, Redo and Apply do nothing. It does nothing outside the edit mode, while another tool is open, for Adjust while Clean up is on, and for Crop and Straighten while a preview is on its way.
196
+ Opens a tool with a panel: Crop (`'crop'`), Straighten (`'perspective'`), Adjust (`'adjust'`) or Clean up (`'threshold'`), which turns on as it opens. The tool stays open until [`confirmTool()`](#confirmtool) or [`cancelTool()`](#canceltool). Meanwhile, no other edit can start, and Undo, Redo and Apply do nothing. It does nothing outside the edit mode, while another tool is open, for Adjust while Clean up is on, and for Crop and Straighten while a preview is on its way.
141
197
 
142
198
  ### `confirmTool()`
143
199
 
@@ -171,7 +227,7 @@ It throws a `RangeError` if `sensitivity` is not between 0 and 1.
171
227
  function setAdjustments(setting: { brightness?: number, contrast?: number }): void
172
228
  ```
173
229
 
174
- Changes the brightness or the contrast, each from -1 to 1, where 0 leaves the image as it is. They run after the other edits. While Adjust is open, it changes what Adjust shows, and [`confirmTool()`](#confirmtool) keeps it as one edit. It does nothing outside the edit mode, while another tool is open or while Clean up is on, because a cleaned up document has tones of its own.
230
+ Changes the brightness or the contrast, each from -1 to 1, where 0 leaves the image as it is. They run after the other edits. While Adjust is open, it changes what Adjust shows, and [`confirmTool()`](#confirmtool) keeps it as one edit. It does nothing outside the edit mode, while another tool is open or while Clean up is on: Clean up compares each pixel with its surroundings, so brightness and contrast would barely change its result.
175
231
 
176
232
  It throws a `RangeError` if a value is not between -1 and 1.
177
233
 
@@ -181,7 +237,7 @@ It throws a `RangeError` if a value is not between -1 and 1.
181
237
  function undo(): void
182
238
  ```
183
239
 
184
- Undoes the last edit.
240
+ Undoes the last edit. It does nothing outside the edit mode, while a tool is open or while Apply runs.
185
241
 
186
242
  ### `redo()`
187
243
 
@@ -189,7 +245,7 @@ Undoes the last edit.
189
245
  function redo(): void
190
246
  ```
191
247
 
192
- Brings back the last edit undone.
248
+ Brings back the last edit undone. It does nothing outside the edit mode, while a tool is open or while Apply runs.
193
249
 
194
250
  ### `apply()`
195
251
 
@@ -197,9 +253,9 @@ Brings back the last edit undone.
197
253
  function apply(): Promise<void>
198
254
  ```
199
255
 
200
- Applies the edits at full resolution, or at [`maxOutputSize`](./options#maxoutputsize). The result becomes the image on display, the history empties, the viewer goes back to the view mode, and the [`apply`](./events#apply) event carries the result. Apply cannot be interrupted, and it blocks the controls while it runs.
256
+ Applies the edits at full resolution, or at [`maxOutputSize`](./options#maxoutputsize). The result becomes the image on display, the history empties, the viewer goes back to the view mode, and the [`apply`](./events#apply) event carries the result. Apply cannot be interrupted, and it blocks the controls while it runs. It does nothing outside the edit mode, while a tool is open, or when there is nothing to apply.
201
257
 
202
- If it fails, the [`error`](./events#error) event reports it and the edit stays open.
258
+ If it fails, the [`error`](./events#error) event reports it and the edit stays open. The promise resolves when Apply ends, also when it fails, so listen to `error` instead of catching it.
203
259
 
204
260
  ### `cancel()`
205
261
 
@@ -207,7 +263,7 @@ If it fails, the [`error`](./events#error) event reports it and the edit stays o
207
263
  function cancel(): void
208
264
  ```
209
265
 
210
- Discards the edits and goes back to the view mode. It does not ask first: the built-in Cancel button and `Esc` do.
266
+ Discards the edits and goes back to the view mode. It does not ask first: the built-in Cancel button and `Esc` do. It does nothing while Apply runs.
211
267
 
212
268
  ## Image
213
269
 
@@ -217,7 +273,7 @@ Discards the edits and goes back to the view mode. It does not ask first: the bu
217
273
  function download(): void
218
274
  ```
219
275
 
220
- Saves the image on display as a file: the result of the last Apply, or else the source. It works without the [`download`](./options#download) option, which only shows a button. The [`download`](./events#download) event comes first and can stop it. It does nothing while editing, because the edits are not applied yet.
276
+ Saves the image on display as a file: the result of the last Apply, or else the source. It works without the [`download`](./options#download) option, which only shows a button. The [`download`](./events#download) event comes first and can stop it. It does nothing while editing, because the edits are not applied yet. Before the first Apply, a `src` from another origin opens in the browser instead: see [Saving the result](../guide/saving#download).
221
277
 
222
278
  ### `reload()`
223
279
 
@@ -225,4 +281,4 @@ Saves the image on display as a file: the result of the last Apply, or else the
225
281
  function reload(): void
226
282
  ```
227
283
 
228
- Loads the current [`src`](./options#src) again, which brings back the original after an Apply.
284
+ Loads the current [`src`](./options#src) again, which brings back the original after an Apply. While editing, it discards the edits. Without a `src`, it does nothing.
@@ -13,7 +13,7 @@ const pic = new PaperPic(container, { src: '/receipt.jpg', alt: 'A receipt' })
13
13
  pic.setOptions({ editable: false })
14
14
  ```
15
15
 
16
- `setOptions()` changes only the options you pass, and `undefined` brings an option back to its default. It never emits `change`.
16
+ `setOptions()` changes only the options you pass, and `undefined` brings an option back to its default. It never emits `change`. An option out of its range throws a `RangeError` that names it, such as a `softness` of 2.
17
17
 
18
18
  ## Image
19
19
 
@@ -22,7 +22,7 @@ pic.setOptions({ editable: false })
22
22
  - **Type:** [`PaperPicSource`](./types#paperpicsource)
23
23
  - **Default:** none
24
24
 
25
- The image to show: a URL from the same origin, or a `File` or `Blob` attached on the client.
25
+ The image to show: a URL, or a `File` or a `Blob`. An image from another origin shows, but cannot be edited: [Loading images](../guide/loading#fetch) explains why, and what to do.
26
26
 
27
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
28
 
@@ -54,7 +54,7 @@ Whether to show the built-in toolbar and edit bar. Without them, build your own
54
54
  - **Type:** [`readonly ToolId[]`](./types#toolid)
55
55
  - **Default:** every tool
56
56
 
57
- The tools the edit bar offers. They keep the order of this table, whatever the order of the array.
57
+ The tools the edit bar offers. They keep the order of this table, whatever the order of the array. It only chooses the buttons: the [methods](./methods) work with every tool.
58
58
 
59
59
  | Id | Button |
60
60
  | --------------- | ----------------------------------- |
@@ -70,14 +70,14 @@ The tools the edit bar offers. They keep the order of this table, whatever the o
70
70
  - **Type:** `boolean`
71
71
  - **Default:** `true`
72
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.
73
+ Whether the wheel zooms the image. Turn it off when the viewer sits in a long page, so the wheel scrolls the page. A pinch on a trackpad stops zooming the image too, because the browser reports it as the wheel.
74
74
 
75
75
  ### `download`
76
76
 
77
77
  - **Type:** `boolean`
78
78
  - **Default:** `false`
79
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.
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. Before the first Apply, a `src` from another origin opens in the browser instead of saving: [Saving the result](../guide/saving#download) explains what to do.
81
81
 
82
82
  ### `labels`
83
83
 
@@ -123,11 +123,11 @@ Each key names an icon, and some icons appear on two buttons:
123
123
  ### `output`
124
124
 
125
125
  - **Type:** [`PaperPicOutput`](./types#paperpicoutput)
126
- - **Default:** the format of the source
126
+ - **Default:** the format of the source, or PNG
127
127
 
128
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
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.
130
+ Without a `type`, a cleaned up image is PNG, because JPEG would damage its sharp edges. Any other image keeps the format of the source when it is JPEG, PNG or WebP, which PaperPic reads from the extension of the URL or the type of the `File` or `Blob`. Otherwise, the result is PNG, as it is when the browser cannot encode the format.
131
131
 
132
132
  ### `maxOutputSize`
133
133
 
@@ -141,7 +141,7 @@ The longest side of the edited image, in pixels. A larger result is scaled down.
141
141
  - **Type:** `string`
142
142
  - **Default:** the name of the source
143
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`.
144
+ The name of the saved file. Give it without an extension: PaperPic adds the one of the format, 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`. Before the first Apply, a URL without an extension saves without one, because its format is unknown.
145
145
 
146
146
  ## Tools
147
147
 
@@ -150,7 +150,7 @@ The name of the saved file. Its extension follows the format of the image, so a
150
150
  - **Type:** `number`
151
151
  - **Default:** estimated
152
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.
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. Crop does not use them: its rectangle stays free.
154
154
 
155
155
  ### `softness`
156
156