@paperpic/core 0.2.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.
- package/dist/docs/examples/attach-and-scan.md +196 -0
- package/dist/docs/examples/custom-toolbar.md +183 -0
- package/dist/docs/guide/accessibility.md +1 -1
- package/dist/docs/guide/editing.md +6 -15
- package/dist/docs/guide/getting-started.md +83 -10
- package/dist/docs/guide/loading.md +128 -0
- package/dist/docs/guide/performance.md +17 -3
- package/dist/docs/guide/saving.md +6 -0
- package/dist/docs/guide/styling.md +2 -0
- package/dist/docs/guide/tools/adjust.md +2 -0
- package/dist/docs/guide/tools/crop.md +2 -0
- package/dist/docs/guide/tools/rotate-and-flip.md +3 -1
- package/dist/docs/guide/troubleshooting.md +45 -0
- package/dist/docs/guide/viewer.md +1 -1
- package/dist/docs/reference/events.md +8 -4
- package/dist/docs/reference/methods.md +3 -3
- package/dist/docs/reference/options.md +2 -2
- package/dist/docs/reference/react.md +2 -2
- package/dist/docs/reference/types.md +1 -1
- package/dist/docs/reference/vue.md +2 -2
- package/dist/index.d.ts +63 -44
- package/dist/index.js +1468 -1349
- package/dist/{pipeline-MP1RPlXT.js → steps-DuGiMvk0.js} +236 -75
- package/dist/types-C3ZHKId1.d.ts +31 -0
- package/dist/worker.d.ts +13 -61
- package/dist/worker.js +3 -10
- package/package.json +2 -2
|
@@ -9,7 +9,7 @@ Phone photos have 12 megapixels or more, and editing them takes real work. This
|
|
|
9
9
|
|
|
10
10
|
## A Web Worker does the work
|
|
11
11
|
|
|
12
|
-
Clean up and Straighten take
|
|
12
|
+
Clean up and Straighten take about a second and a half on a 12-megapixel photo on a recent phone, as the [measured times](#measurements) show. On the main thread, the page would freeze for that long. PaperPic runs them in a Web Worker instead, so the page keeps responding while Apply runs.
|
|
13
13
|
|
|
14
14
|
The worker ships inside the package and starts with the standard `new Worker(new URL(…, import.meta.url))`, which bundlers such as Vite and webpack 5 pick up on their own, with no configuration. If the worker cannot start, the editing runs on the main thread: it still works, but the page can freeze for a moment with large images.
|
|
15
15
|
|
|
@@ -19,6 +19,8 @@ With a Content Security Policy, allow:
|
|
|
19
19
|
|
|
20
20
|
- `worker-src 'self'`, for the worker.
|
|
21
21
|
- `img-src blob:`, because the viewer shows attached files and the results of Apply through `blob:` URLs.
|
|
22
|
+
- `paperpic` in `trusted-types`, if your policy restricts Trusted Types policies, because the icons of the buttons go through that policy.
|
|
23
|
+
- A `default` Trusted Types policy whose `createScriptURL` accepts the URL of the worker, if your policy requires Trusted Types. Bundlers only pick up a worker created from a plain URL, which Trusted Types block, so without that policy the editing runs on the main thread.
|
|
22
24
|
|
|
23
25
|
## Large photos
|
|
24
26
|
|
|
@@ -26,9 +28,21 @@ With a Content Security Policy, allow:
|
|
|
26
28
|
- **On Apply**, every edit runs at full resolution. Large photos take a few seconds, so the viewer shows a message and blocks the controls meanwhile.
|
|
27
29
|
- **To save time and memory**, set [`maxOutputSize`](../reference/options#maxoutputsize). A limit such as 2000 or 3000 pixels keeps documents readable, and makes Apply faster and the files smaller.
|
|
28
30
|
|
|
29
|
-
##
|
|
31
|
+
## Measured times {#measurements}
|
|
30
32
|
|
|
31
|
-
|
|
33
|
+
Each step of Apply, in the worker, on a Pixel 10 Pro with Chrome 156:
|
|
34
|
+
|
|
35
|
+
| Step | 2 MP | 12 MP | 37.5 MP |
|
|
36
|
+
| --------------------------- | ------ | ------ | ------- |
|
|
37
|
+
| Clean up | 256 ms | 1.5 s | 4.8 s |
|
|
38
|
+
| Straighten | 251 ms | 1.6 s | 5.0 s |
|
|
39
|
+
| Export to PNG | 92 ms | 378 ms | 979 ms |
|
|
40
|
+
| Export to JPEG, quality 0.9 | 33 ms | 142 ms | 525 ms |
|
|
41
|
+
|
|
42
|
+
- A move of the ruler of Clean up takes about 40 ms on the same phone, because it works on the preview of about 2 MP.
|
|
43
|
+
- A desktop computer with 8 cores does each step about six times faster.
|
|
44
|
+
- At 37.5 MP, Clean up needs about 340 MB of memory at its peak.
|
|
45
|
+
- Mid-range Android phones and iPhones are not measured yet.
|
|
32
46
|
|
|
33
47
|
## Server-side rendering
|
|
34
48
|
|
|
@@ -129,6 +129,12 @@ const pic = new PaperPic(container, {
|
|
|
129
129
|
|
|
130
130
|
The preview while editing is always about 2 megapixels, so `maxOutputSize` changes only the result.
|
|
131
131
|
|
|
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
|
+
|
|
132
138
|
## The download button
|
|
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.
|
|
@@ -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,6 +7,8 @@ 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.
|
|
@@ -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.
|
|
@@ -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
|
|
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
|
|
|
@@ -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. 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 …`. 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,7 +18,7 @@ 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 keyboard works with the focus on the viewer. While there is nothing to move, the arrow keys 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
|
|
|
@@ -5,7 +5,7 @@ description: The events of PaperPic and what each one carries, load, error, chan
|
|
|
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
|
|
@@ -36,15 +36,19 @@ The image is loaded and on display. `width` and `height` are its size in pixels.
|
|
|
36
36
|
|
|
37
37
|
## `error`
|
|
38
38
|
|
|
39
|
-
- **Payload:** `{ error: Error }`
|
|
39
|
+
- **Payload:** `{ error: Error, phase: 'load' | 'preview' | 'apply' }`
|
|
40
40
|
|
|
41
|
-
|
|
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 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`. Panning the image does not emit it, because the state does not hold its position. `setOptions()` and the props of the components never emit it.
|
|
48
52
|
|
|
49
53
|
## `apply`
|
|
50
54
|
|
|
@@ -27,7 +27,7 @@ class PaperPic {
|
|
|
27
27
|
|
|
28
28
|
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
29
|
|
|
30
|
-
It throws a `TypeError` if `container` is not an element. Create the viewer once the element exists, such as on mount.
|
|
30
|
+
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.
|
|
31
31
|
|
|
32
32
|
### `destroy()`
|
|
33
33
|
|
|
@@ -45,7 +45,7 @@ Removes the viewer and releases everything it holds, such as its worker and the
|
|
|
45
45
|
function setOptions(options: PaperPicOptions): void
|
|
46
46
|
```
|
|
47
47
|
|
|
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.
|
|
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. It throws a `RangeError` if an option is out of its range, and then no option changes.
|
|
49
49
|
|
|
50
50
|
### `getState()`
|
|
51
51
|
|
|
@@ -129,7 +129,7 @@ Turns the image a quarter turn: clockwise with `1`, the default, and countercloc
|
|
|
129
129
|
function flip(): void
|
|
130
130
|
```
|
|
131
131
|
|
|
132
|
-
Mirrors the image left to right as it is on display, so after a quarter turn it still mirrors left to right. To
|
|
132
|
+
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
133
|
|
|
134
134
|
### `openTool()`
|
|
135
135
|
|
|
@@ -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
|
|
|
@@ -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
|
| --------------- | ----------------------------------- |
|
|
@@ -36,7 +36,7 @@ Every [option](./options) is a prop with the same name, such as `editable={false
|
|
|
36
36
|
| `className` | `string` | Classes on top of `paperpic-host` |
|
|
37
37
|
| `style` | `CSSProperties` | Inline styles |
|
|
38
38
|
|
|
39
|
-
|
|
39
|
+
An object or array with the same contents as before, such as `tools={['crop', 'rotate']}`, changes nothing, so inline values are fine. A function is new on every render, so define the functions of `labels`, such as `zoomLevel`, outside the component, or build those labels with `useMemo`.
|
|
40
40
|
|
|
41
41
|
## Events
|
|
42
42
|
|
|
@@ -45,7 +45,7 @@ Objects and arrays, such as `labels` or `tools`, reach the viewer again whenever
|
|
|
45
45
|
| `onApply` | [`ExportedImage`](./types#exportedimage) |
|
|
46
46
|
| `onChange` | [`PaperPicState`](./state) |
|
|
47
47
|
| `onDownload` | [`PaperPicDownload`](./types#paperpicdownload) |
|
|
48
|
-
| `onError` | `{ error }`
|
|
48
|
+
| `onError` | `{ error, phase }` |
|
|
49
49
|
| `onLoad` | [`Size`](./types#size) |
|
|
50
50
|
|
|
51
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`.
|
|
@@ -31,7 +31,7 @@ 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
|
-
|
|
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
|
|
|
@@ -40,7 +40,7 @@ Objects and arrays that the template builds, such as `:labels="{ apply: t('apply
|
|
|
40
40
|
| `apply` | [`ExportedImage`](./types#exportedimage) |
|
|
41
41
|
| `change` | [`PaperPicState`](./state) |
|
|
42
42
|
| `download` | [`PaperPicDownload`](./types#paperpicdownload) |
|
|
43
|
-
| `error` | `{ error }`
|
|
43
|
+
| `error` | `{ error, phase }` |
|
|
44
44
|
| `load` | [`Size`](./types#size) |
|
|
45
45
|
|
|
46
46
|
[Events](./events) describes each one. A change of a prop never emits `change`.
|
package/dist/index.d.ts
CHANGED
|
@@ -1,9 +1,4 @@
|
|
|
1
|
-
|
|
2
|
-
* How far the image is turned, in degrees clockwise.
|
|
3
|
-
*
|
|
4
|
-
* @see https://paperpic.dev/reference/state
|
|
5
|
-
*/
|
|
6
|
-
type Rotation = 0 | 90 | 180 | 270;
|
|
1
|
+
import { i as Size } from "./types-C3ZHKId1.js";
|
|
7
2
|
/**
|
|
8
3
|
* The format of the image that editing produces.
|
|
9
4
|
*
|
|
@@ -31,14 +26,17 @@ interface ExportedImage {
|
|
|
31
26
|
width: number;
|
|
32
27
|
}
|
|
33
28
|
/**
|
|
34
|
-
*
|
|
29
|
+
* The image to show: a URL from the same origin, or a file attached on the client.
|
|
35
30
|
*
|
|
36
|
-
* @see https://paperpic.dev/reference/
|
|
31
|
+
* @see https://paperpic.dev/reference/options#src
|
|
37
32
|
*/
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
33
|
+
type PaperPicSource = string | Blob;
|
|
34
|
+
/**
|
|
35
|
+
* How far the image is turned, in degrees clockwise.
|
|
36
|
+
*
|
|
37
|
+
* @see https://paperpic.dev/reference/state
|
|
38
|
+
*/
|
|
39
|
+
type Rotation = 0 | 90 | 180 | 270;
|
|
42
40
|
/**
|
|
43
41
|
* A position in CSS pixels, relative to the top left corner of the viewer.
|
|
44
42
|
*
|
|
@@ -62,7 +60,7 @@ type Fit = 'image' | 'width' | 'height';
|
|
|
62
60
|
interface PaperPicLabels {
|
|
63
61
|
/** Opens the ruler of brightness and contrast. */
|
|
64
62
|
adjust: string;
|
|
65
|
-
/** Announced after
|
|
63
|
+
/** Announced after moving the ruler of Adjust, with the name of the tone and its value from -100 to 100. */
|
|
66
64
|
adjustmentLevel: (name: string, value: number) => string;
|
|
67
65
|
/** Announced when the changes are applied. */
|
|
68
66
|
applied: string;
|
|
@@ -118,7 +116,7 @@ interface PaperPicLabels {
|
|
|
118
116
|
rotateRight: string;
|
|
119
117
|
/** Opens Clean up, and names its switch. */
|
|
120
118
|
threshold: string;
|
|
121
|
-
/** Announced after
|
|
119
|
+
/** Announced after moving the ruler of Clean up, with its value in percent. */
|
|
122
120
|
thresholdLevel: (percent: number) => string;
|
|
123
121
|
/** Name of the ruler of Clean up. */
|
|
124
122
|
thresholdSensitivity: string;
|
|
@@ -176,12 +174,6 @@ interface PaperPicIcons {
|
|
|
176
174
|
zoomIn: string;
|
|
177
175
|
zoomOut: string;
|
|
178
176
|
}
|
|
179
|
-
/**
|
|
180
|
-
* The image to show: a URL from the same origin, or a file attached on the client.
|
|
181
|
-
*
|
|
182
|
-
* @see https://paperpic.dev/reference/options#src
|
|
183
|
-
*/
|
|
184
|
-
type PaperPicSource = string | Blob;
|
|
185
177
|
/**
|
|
186
178
|
* What the constructor and `setOptions()` take.
|
|
187
179
|
*
|
|
@@ -221,11 +213,24 @@ interface PaperPicOptions {
|
|
|
221
213
|
src?: PaperPicSource;
|
|
222
214
|
/** Whether to show the built-in toolbar and edit bar. Without them, build your own with the public methods. */
|
|
223
215
|
toolbar?: boolean;
|
|
224
|
-
/** Which tools the edit bar offers. By default, all of them. */
|
|
216
|
+
/** Which tools the edit bar offers. By default, all of them. It only chooses the buttons: the methods work with every tool. */
|
|
225
217
|
tools?: readonly ToolId[];
|
|
226
218
|
/** Whether the wheel zooms. Turn it off when the viewer sits in a long page. */
|
|
227
219
|
wheelZoom?: boolean;
|
|
228
220
|
}
|
|
221
|
+
/**
|
|
222
|
+
* What the `download` event carries.
|
|
223
|
+
*
|
|
224
|
+
* @see https://paperpic.dev/reference/events#download
|
|
225
|
+
*/
|
|
226
|
+
interface PaperPicDownload {
|
|
227
|
+
/** The name of the file, with the extension of its format. */
|
|
228
|
+
filename: string;
|
|
229
|
+
/** Stops the browser from saving the file, so you can save it another way. */
|
|
230
|
+
preventDefault: () => void;
|
|
231
|
+
/** The image to save: the result of the last Apply, or else the `src`. */
|
|
232
|
+
source: PaperPicSource;
|
|
233
|
+
}
|
|
229
234
|
/**
|
|
230
235
|
* What the viewer is showing, which `getState()` returns and the `change` event carries.
|
|
231
236
|
*
|
|
@@ -276,13 +281,17 @@ interface PaperPicState {
|
|
|
276
281
|
interface PaperPicEvents {
|
|
277
282
|
/** The user applied the changes. The result is already on display. */
|
|
278
283
|
apply: ExportedImage;
|
|
279
|
-
/** The user changed the
|
|
284
|
+
/** The user changed something in the state, such as the zoom or the edit. A pan and `setOptions()` never trigger it. */
|
|
280
285
|
change: PaperPicState;
|
|
281
286
|
/** The image is about to be saved. Call `preventDefault()` to save it another way. */
|
|
282
287
|
download: PaperPicDownload;
|
|
283
|
-
/**
|
|
288
|
+
/**
|
|
289
|
+
* Something failed. `phase` says what: `'load'` for the image, `'preview'` for the pixels of an edit on display,
|
|
290
|
+
* which leaves the edit open, and `'apply'` for the changes.
|
|
291
|
+
*/
|
|
284
292
|
error: {
|
|
285
293
|
error: Error;
|
|
294
|
+
phase: 'load' | 'preview' | 'apply';
|
|
286
295
|
};
|
|
287
296
|
/** The image is ready. */
|
|
288
297
|
load: Size;
|
|
@@ -308,6 +317,7 @@ export declare class PaperPic {
|
|
|
308
317
|
private readonly toolbar;
|
|
309
318
|
private readonly editBar;
|
|
310
319
|
private readonly renderer;
|
|
320
|
+
private readonly gestures;
|
|
311
321
|
private readonly runner;
|
|
312
322
|
private readonly listeners;
|
|
313
323
|
private readonly cleanups;
|
|
@@ -320,14 +330,15 @@ export declare class PaperPic {
|
|
|
320
330
|
/** What the edits look like, while they need other pixels than the image. */
|
|
321
331
|
private preview;
|
|
322
332
|
private previewKey;
|
|
323
|
-
private
|
|
324
|
-
private previewing;
|
|
333
|
+
private readonly previewQueue;
|
|
325
334
|
/** The open tool with a selection of its own, such as Crop. */
|
|
326
335
|
private session;
|
|
327
336
|
/** The open Adjust or Clean up. */
|
|
328
337
|
private draft;
|
|
329
338
|
private loadStatus;
|
|
330
339
|
private loadId;
|
|
340
|
+
/** Changes when an edit ends without a trace, so an Apply that finishes afterwards knows that its edit is gone. */
|
|
341
|
+
private editId;
|
|
331
342
|
private view;
|
|
332
343
|
private viewport;
|
|
333
344
|
private mode;
|
|
@@ -338,6 +349,7 @@ export declare class PaperPic {
|
|
|
338
349
|
/**
|
|
339
350
|
* @param container The element to fill. It needs a height, or the viewer stays at its minimum height.
|
|
340
351
|
* @throws {TypeError} If `container` is not an element. Create the instance once the element exists, such as on mount.
|
|
352
|
+
* @throws {RangeError} If an option is out of its range, such as a `softness` of 2.
|
|
341
353
|
*
|
|
342
354
|
* @example
|
|
343
355
|
* const pic = new PaperPic(container, {
|
|
@@ -352,10 +364,17 @@ export declare class PaperPic {
|
|
|
352
364
|
* Changes only the options you pass, and `undefined` brings one back to its default. It does not emit `change`, so
|
|
353
365
|
* two-way bindings do not loop.
|
|
354
366
|
*
|
|
367
|
+
* @throws {RangeError} If an option is out of its range, such as a `softness` of 2. No option changes then.
|
|
368
|
+
*
|
|
355
369
|
* @example
|
|
356
370
|
* pic.setOptions({ editable: false })
|
|
357
371
|
*/
|
|
358
372
|
setOptions(options: PaperPicOptions): void;
|
|
373
|
+
/**
|
|
374
|
+
* Applies the options that changed. Options with the same values change nothing, so a wrapper can pass them all on
|
|
375
|
+
* every render, and a message on screen stays. The constructor passes `initial` to set everything up.
|
|
376
|
+
*/
|
|
377
|
+
private changeOptions;
|
|
359
378
|
/** Returns what the viewer is showing. */
|
|
360
379
|
getState(): PaperPicState;
|
|
361
380
|
/**
|
|
@@ -479,9 +498,6 @@ export declare class PaperPic {
|
|
|
479
498
|
private describeImage;
|
|
480
499
|
private scene;
|
|
481
500
|
private toolHost;
|
|
482
|
-
/** Paints the image larger around a point, inside a circle. */
|
|
483
|
-
private paintLens;
|
|
484
|
-
private canAdjust;
|
|
485
501
|
/** The open tool, with a selection or a panel of settings of its own. */
|
|
486
502
|
private openToolId;
|
|
487
503
|
/** Shows other settings in the open Adjust or Clean up, without any edit. */
|
|
@@ -489,6 +505,10 @@ export declare class PaperPic {
|
|
|
489
505
|
/** The edit that the open Adjust or Clean up would leave, or `null` if it changes nothing. */
|
|
490
506
|
private draftEdit;
|
|
491
507
|
private closeTool;
|
|
508
|
+
/**
|
|
509
|
+
* Tells the listeners of an event. A listener that throws is the app failing, not the viewer, so the page gets its
|
|
510
|
+
* error as any uncaught one, the other listeners still run, and it never looks like a failed load or Apply.
|
|
511
|
+
*/
|
|
492
512
|
private emit;
|
|
493
513
|
private hasFocus;
|
|
494
514
|
/** Puts the keyboard focus back on the toolbar, because the button that had it may be gone. */
|
|
@@ -497,7 +517,7 @@ export declare class PaperPic {
|
|
|
497
517
|
/** Changes what a download saves, and frees the address of the file it saved before. */
|
|
498
518
|
private setSaved;
|
|
499
519
|
private setImage;
|
|
500
|
-
/** Ends the edit without a trace.
|
|
520
|
+
/** Ends the edit without a trace. An Apply in progress is ignored when it finishes, because `editId` changes. */
|
|
501
521
|
private leaveEdit;
|
|
502
522
|
private addOperation;
|
|
503
523
|
private setHistory;
|
|
@@ -511,8 +531,10 @@ export declare class PaperPic {
|
|
|
511
531
|
private previewTone;
|
|
512
532
|
/** Makes the pixels on display match the edits. A change of tones of the same kind only repaints the preview. */
|
|
513
533
|
private updatePreview;
|
|
514
|
-
/**
|
|
515
|
-
private
|
|
534
|
+
/** Shows a preview that arrived, with the tones of the ruler, which may have moved while it was on its way. */
|
|
535
|
+
private showPreview;
|
|
536
|
+
/** Keeps the edit open, and reports that its pixels could not be shown. */
|
|
537
|
+
private previewFailed;
|
|
516
538
|
/**
|
|
517
539
|
* Changes the pixels on display. A new shape starts from a fitted view, and the same shape keeps the zoom, as when the threshold changes.
|
|
518
540
|
* With `null` it goes back to the image, and any preview in progress is forgotten.
|
|
@@ -525,9 +547,19 @@ export declare class PaperPic {
|
|
|
525
547
|
/** The image on display, once the viewer has a size to show it in. A hidden container has none. */
|
|
526
548
|
private measuredImage;
|
|
527
549
|
private applyViewport;
|
|
550
|
+
/** Whether the zoom can go further in each direction, from the view on display. */
|
|
551
|
+
private canZoom;
|
|
552
|
+
/** Makes the whole interface match the state: the bars, the mode and the view. */
|
|
528
553
|
private refresh;
|
|
554
|
+
/**
|
|
555
|
+
* Makes what follows the view match it: the zoom and fit buttons, the handles of an open tool, the cursor and the
|
|
556
|
+
* image. A pan or a zoom needs nothing else, and it can come on every move of the pointer.
|
|
557
|
+
*/
|
|
558
|
+
private refreshView;
|
|
559
|
+
/** Shows another view. Returns whether it differs from the one on display. */
|
|
529
560
|
private commit;
|
|
530
561
|
private resetRotation;
|
|
562
|
+
/** Moves the image. Returns whether it moved, which an image that fits, or one at its edge, does not. */
|
|
531
563
|
private pan;
|
|
532
564
|
private zoomAround;
|
|
533
565
|
/**
|
|
@@ -539,17 +571,4 @@ export declare class PaperPic {
|
|
|
539
571
|
/** Runs a key's command. Returns whether it did something, so other keys keep their usual effect. */
|
|
540
572
|
private runKey;
|
|
541
573
|
}
|
|
542
|
-
/**
|
|
543
|
-
* What the `download` event carries.
|
|
544
|
-
*
|
|
545
|
-
* @see https://paperpic.dev/reference/events#download
|
|
546
|
-
*/
|
|
547
|
-
interface PaperPicDownload {
|
|
548
|
-
/** The name of the file, with the extension of its format. */
|
|
549
|
-
filename: string;
|
|
550
|
-
/** Stops the browser from saving the file, so you can save it another way. */
|
|
551
|
-
preventDefault: () => void;
|
|
552
|
-
/** The image to save: the result of the last Apply, or else the `src`. */
|
|
553
|
-
source: PaperPicSource;
|
|
554
|
-
}
|
|
555
574
|
export type { ExportedImage, Fit, PaperPicDownload, PaperPicEvents, PaperPicIcons, PaperPicLabels, PaperPicOptions, PaperPicOutput, PaperPicSource, PaperPicState, Rotation, Size, ToolId, ViewPoint };
|