@paperpic/react 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,55 @@
1
+ ---
2
+ title: Accessibility
3
+ description: How PaperPic works with the keyboard, screen readers and touch screens, which preferences it follows, and what your app needs to provide.
4
+ ---
5
+
6
+ # Accessibility
7
+
8
+ People read and fix documents with a mouse, a finger, the keyboard or a screen reader. PaperPic aims at WCAG 2.2 AA, and most of the work is built in. This page lists what it does and what your app needs to add.
9
+
10
+ ## What your app provides
11
+
12
+ - **A description.** Pass [`alt`](../reference/options#alt), such as "Receipt from 5 November". Screen readers read it as the name of the image.
13
+ - **Texts in the user's language.** Screen readers announce the buttons and the changes, so translate them with [`labels`](./labels).
14
+ - **Your own controls, if any.** With `toolbar: false`, the buttons you build replace the built-in ones, and they need their own names and keyboard support.
15
+ - **A visible focus.** Keep your CSS from hiding the focus outline of the viewer.
16
+
17
+ ## Keyboard
18
+
19
+ With the focus on the viewer:
20
+
21
+ | Key | Action |
22
+ | -------------------------- | ---------------------------------------------------------------------------- |
23
+ | `+` and `-` | Zoom in and out |
24
+ | Arrow keys | Pan |
25
+ | `0` | Fit the whole image |
26
+ | `Ctrl+Z` | Undo |
27
+ | `Ctrl+Shift+Z` or `Ctrl+Y` | Redo |
28
+ | `Enter` | Confirm the open tool, or else apply the changes |
29
+ | `Esc` | Let go of a selected corner, close the open tool, or else cancel the changes |
30
+
31
+ On macOS, `Cmd` works like `Ctrl`. Before cancelling changes, `Esc` asks for confirmation. With `toolbar: false`, it leaves them to your interface.
32
+
33
+ - **Toolbar and edit bar.** Tab reaches each bar, and inside it the arrow keys move between the buttons, with `Home` and `End` for the first and the last.
34
+ - **Corner handles.** With Crop or Straighten open, Tab moves between the handles, and the arrow keys move the focused one 1 screen pixel, or 10 with Shift.
35
+ - **Rulers.** The rulers of Adjust and Clean up are native ranges: the arrow keys, `Page Up`, `Page Down`, `Home` and `End` move them. `Enter` keeps the value, as Done does, and `Esc` closes the tool without it.
36
+
37
+ ## Screen readers
38
+
39
+ - The image has the role of an image, named by `alt`. Without `alt`, screen readers skip it.
40
+ - The toolbar and the edit bar have their own names, such as "Image controls" and "Editing controls".
41
+ - An announcement reports each change that the user cannot see by the focus alone: the zoom level, the start of the edit mode, the position of a moved corner, the value of a ruler, and the result of Apply.
42
+ - The switch of Clean up has the role of a switch. A tool in use, which a dot marks on screen, is described as "In use".
43
+
44
+ ## Touch screens
45
+
46
+ - With `pointer: coarse`, buttons and corner handles measure at least 44 pixels.
47
+ - While a finger drags a corner, a magnifier shows the area under it.
48
+ - A corner also moves without dragging: press its handle, and then tap where it goes. This works with a mouse too.
49
+ - While the image is fitted, one finger scrolls the page, so the viewer does not trap people inside it. Once zoomed, it pans the image.
50
+
51
+ ## Preferences
52
+
53
+ - **Reduced motion.** With `prefers-reduced-motion: reduce`, the buttons change state without transitions.
54
+ - **Forced colors.** In Windows high contrast and other forced color modes, pressed buttons and the main actions keep a visible outline.
55
+ - **Dark mode.** The colors follow the `color-scheme` of your page, which can follow the system. See [Styling](./styling#dark-mode).
@@ -0,0 +1,140 @@
1
+ ---
2
+ title: Editing
3
+ description: How the edit mode of PaperPic works, from the Edit button to Apply, with the tools, Undo and Redo, the preview and the events your code receives.
4
+ ---
5
+
6
+ # Editing
7
+
8
+ A photo of a document usually needs a few fixes before it is worth keeping. The edit mode groups them: the user makes the changes, checks them, and applies them all at once. The [playground](../playground) has the whole edit mode to try.
9
+
10
+ ## The edit flow
11
+
12
+ 1. The user presses Edit, the pencil in the toolbar. The toolbar hides, so nothing covers the image, and the edit bar appears at the bottom of the viewer.
13
+ 2. Rotate left and Flip add an edit at once. The other tools open a panel in the edit bar, and Done adds what the user chose there as one edit. Undo and Redo move through the edits.
14
+ 3. Apply computes the result and goes back to viewing. Cancel discards the edits, and asks first when there are some.
15
+
16
+ Nothing changes the image until Apply. Before that, the edits are a list that the viewer previews.
17
+
18
+ The edit bar has two rows of the same height in every state: the tools, or the panel of the open tool, above, and below, Cancel at the left and Apply, or Done, at the right. So the image keeps its place when a tool opens. In a viewer at least 28rem wide, the bar fits on one row. A dot marks Adjust and Clean up while their setting is in effect.
19
+
20
+ ## Tools
21
+
22
+ | Tool | What it does | Id |
23
+ | -------------------------------------- | -------------------------------------------------------------- | ------------- |
24
+ | [Crop](./tools/crop) | Keeps the part of the image inside four corners | `crop` |
25
+ | [Straighten](./tools/straighten) | Turns a photo taken at an angle into a flat page | `perspective` |
26
+ | [Rotate left](./tools/rotate-and-flip) | Turns the image a quarter turn to the left | `rotate` |
27
+ | [Flip](./tools/rotate-and-flip) | Mirrors the image left to right | `flip` |
28
+ | [Adjust](./tools/adjust) | Changes the brightness and the contrast | `adjust` |
29
+ | [Clean up](./tools/clean-up) | Turns the document into crisp black and white, without shadows | `threshold` |
30
+
31
+ The [`tools`](../reference/options#tools) option chooses which ones the edit bar offers:
32
+
33
+ :::tabs key:framework
34
+ == JavaScript
35
+
36
+ ```ts
37
+ const pic = new PaperPic(container, {
38
+ src: '/receipt.jpg',
39
+ tools: ['crop', 'perspective', 'rotate'],
40
+ })
41
+ ```
42
+
43
+ == Vue
44
+
45
+ ```vue
46
+ <script setup lang="ts">
47
+ import type { ToolId } from '@paperpic/vue'
48
+ import { PaperPic } from '@paperpic/vue'
49
+
50
+ const tools: ToolId[] = ['crop', 'perspective', 'rotate']
51
+ </script>
52
+
53
+ <template>
54
+ <PaperPic src="/receipt.jpg" :tools />
55
+ </template>
56
+ ```
57
+
58
+ == React
59
+
60
+ ```tsx
61
+ import type { ToolId } from '@paperpic/react'
62
+ import { PaperPic } from '@paperpic/react'
63
+
64
+ const tools: ToolId[] = ['crop', 'perspective', 'rotate']
65
+
66
+ export function Receipt() {
67
+ return <PaperPic src="/receipt.jpg" tools={tools} />
68
+ }
69
+ ```
70
+
71
+ :::
72
+
73
+ Crop, Straighten, Adjust and Clean up open a panel in place of the tools, so the rest of the edit bar waits while one of them is open. Done, or `Enter`, adds what the tool chose to the edits, and Cancel this tool, or `Esc`, discards it.
74
+
75
+ Inside a panel, the image looks as the result will, Clean up included. Straighten is the exception: it shows the photo without Clean up, so the edges of the paper stay visible.
76
+
77
+ ## Preview and Apply
78
+
79
+ While editing, the viewer previews the edits on a copy of the image of about 2 megapixels, so it stays fast with large photos. Zoomed in, the preview looks softer than the result. Apply computes every edit at full resolution, or at [`maxOutputSize`](../reference/options#maxoutputsize), in a Web Worker.
80
+
81
+ Apply cannot be interrupted. It blocks the controls and shows a message while it runs. Then the result replaces the image on display, the history empties, and the viewer goes back to the view mode. If Apply fails, the edit stays open, so the user can try again.
82
+
83
+ ## What your code receives
84
+
85
+ | Event | When |
86
+ | -------- | ------------------------------------------------------------------- |
87
+ | `apply` | When the result is ready, with `{ blob, width, height, type }` |
88
+ | `change` | After each action of the user, with the [state](../reference/state) |
89
+ | `error` | When Apply fails, or when the image cannot be loaded |
90
+
91
+ :::tabs key:framework
92
+ == JavaScript
93
+
94
+ ```ts
95
+ pic.on('apply', ({ blob }) => upload(blob))
96
+ pic.on('error', ({ error }) => console.error(error))
97
+ ```
98
+
99
+ == Vue
100
+
101
+ ```vue
102
+ <PaperPic
103
+ src="/receipt.jpg"
104
+ @apply="({ blob }) => upload(blob)"
105
+ @error="({ error }) => console.error(error)"
106
+ />
107
+ ```
108
+
109
+ == React
110
+
111
+ ```tsx
112
+ <PaperPic
113
+ src="/receipt.jpg"
114
+ onApply={({ blob }) => upload(blob)}
115
+ onError={({ error }) => console.error(error)}
116
+ />
117
+ ```
118
+
119
+ :::
120
+
121
+ ## What discards the edits
122
+
123
+ - Cancel, after the user confirms, or [`cancel()`](../reference/methods#cancel), which does not ask.
124
+ - A new `src` while editing.
125
+ - A change of `editable` while editing.
126
+
127
+ After Apply, passing the same `src` again does nothing, so the result stays on display. [`reload()`](../reference/methods#reload) brings back the original.
128
+
129
+ ## Keyboard
130
+
131
+ With the focus on the viewer:
132
+
133
+ | Key | Action |
134
+ | -------------------------- | ------------------------------------------------ |
135
+ | `Ctrl+Z` | Undo |
136
+ | `Ctrl+Shift+Z` or `Ctrl+Y` | Redo |
137
+ | `Enter` | Confirm the open tool, or else apply the changes |
138
+ | `Esc` | Close the open tool, or else cancel the changes |
139
+
140
+ On macOS, `Cmd` works like `Ctrl`.
@@ -0,0 +1,144 @@
1
+ ---
2
+ title: Getting started
3
+ description: Install PaperPic for plain JavaScript, Vue or React, show your first document image and get the edited image back.
4
+ ---
5
+
6
+ # Getting started
7
+
8
+ This page takes you from installing PaperPic to showing an image and getting the edited result back. Choose your framework in any example, and the others on the site follow.
9
+
10
+ ## Installation
11
+
12
+ :::tabs key:framework
13
+ == JavaScript
14
+
15
+ ```sh
16
+ pnpm add @paperpic/core
17
+ ```
18
+
19
+ == Vue
20
+
21
+ ```sh
22
+ pnpm add @paperpic/vue
23
+ ```
24
+
25
+ `@paperpic/vue` requires Vue 3.5 or newer.
26
+
27
+ == React
28
+
29
+ ```sh
30
+ pnpm add @paperpic/react
31
+ ```
32
+
33
+ `@paperpic/react` requires React 19 or newer.
34
+
35
+ :::
36
+
37
+ ## Show an image
38
+
39
+ The viewer fills its container, so give the container a height. Import the stylesheet once in your app.
40
+
41
+ :::tabs key:framework
42
+ == JavaScript
43
+
44
+ ```html
45
+ <div id="viewer" style="height: 480px"></div>
46
+ ```
47
+
48
+ ```ts
49
+ import { PaperPic } from '@paperpic/core'
50
+ import '@paperpic/core/style.css'
51
+
52
+ const pic = new PaperPic(document.querySelector<HTMLElement>('#viewer')!, {
53
+ src: '/receipt.jpg',
54
+ alt: 'A receipt',
55
+ })
56
+ ```
57
+
58
+ == Vue
59
+
60
+ ```vue
61
+ <script setup lang="ts">
62
+ import { PaperPic } from '@paperpic/vue'
63
+ import '@paperpic/vue/style.css'
64
+ </script>
65
+
66
+ <template>
67
+ <div style="height: 480px">
68
+ <PaperPic src="/receipt.jpg" alt="A receipt" />
69
+ </div>
70
+ </template>
71
+ ```
72
+
73
+ == React
74
+
75
+ ```tsx
76
+ import { PaperPic } from '@paperpic/react'
77
+ import '@paperpic/react/style.css'
78
+
79
+ export function Receipt() {
80
+ return (
81
+ <div style={{ height: 480 }}>
82
+ <PaperPic src="/receipt.jpg" alt="A receipt" />
83
+ </div>
84
+ )
85
+ }
86
+ ```
87
+
88
+ :::
89
+
90
+ `src` takes a URL from the same origin as your page, or a `File` that the user picks, such as from an `<input type="file">`. `alt` describes the image for screen readers.
91
+
92
+ ## Get the edited image
93
+
94
+ The pencil in the toolbar starts the edit mode. When the user applies the changes, the result replaces the image on display, and the `apply` event hands it to your code:
95
+
96
+ :::tabs key:framework
97
+ == JavaScript
98
+
99
+ ```ts
100
+ pic.on('apply', ({ blob }) => upload(blob))
101
+ ```
102
+
103
+ == Vue
104
+
105
+ ```vue
106
+ <PaperPic src="/receipt.jpg" alt="A receipt" @apply="({ blob }) => upload(blob)" />
107
+ ```
108
+
109
+ == React
110
+
111
+ ```tsx
112
+ <PaperPic src="/receipt.jpg" alt="A receipt" onApply={({ blob }) => upload(blob)} />
113
+ ```
114
+
115
+ :::
116
+
117
+ Here `upload` stands for your own code, such as:
118
+
119
+ ```ts
120
+ async function upload(blob: Blob) {
121
+ const body = new FormData()
122
+ body.append('image', blob)
123
+ await fetch('/api/documents', { method: 'POST', body })
124
+ }
125
+ ```
126
+
127
+ The `blob` keeps the format of the source, or is PNG when the user cleaned up the document. The [`output`](../reference/options#output) option changes it.
128
+
129
+ ## Only show the image
130
+
131
+ To show a document that people should not change, turn editing off with `editable: false`. The [Viewer](./viewer) page shows it at work.
132
+
133
+ ## Requirements
134
+
135
+ - PaperPic works in the browsers of [Baseline Widely Available](https://web.dev/baseline).
136
+ - The editing runs in a Web Worker, which bundlers such as Vite and webpack pick up on their own. 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.
137
+ - With a Content Security Policy, allow the worker with `worker-src 'self'`, and allow `img-src blob:`, because the viewer shows attached files and results through `blob:` URLs.
138
+ - With server-side rendering, such as in Nuxt or Next.js, the Vue and React components render an empty element on the server and create the viewer in the browser. With the core, create the viewer in the browser yourself.
139
+
140
+ ## Next steps
141
+
142
+ - [Viewer](./viewer): zoom, fit and read-only use.
143
+ - [Editing](./editing): the edit mode, the tools, Undo and Apply.
144
+ - [Options](../reference/options): everything you can configure.
@@ -0,0 +1,36 @@
1
+ ---
2
+ title: What is PaperPic?
3
+ description: PaperPic is a document image viewer and editor for the web. People zoom into photos of paper, straighten them, crop them and clean them up before your app keeps them.
4
+ ---
5
+
6
+ # What is PaperPic?
7
+
8
+ Photos of documents arrive skewed, shadowed and full of background. PaperPic shows them in a viewer that people can zoom into, and lets them straighten and clean up each photo before your app keeps it, as a scanner app would.
9
+
10
+ ## What it does
11
+
12
+ - **View.** Zoom with the buttons, the wheel or a pinch, pan, and fit the whole image, its width or its height. A read-only viewer can also rotate the image.
13
+ - **Edit.** In the edit mode, the user can crop, straighten a photo taken at an angle, rotate, flip, adjust the brightness and the contrast, and clean up the document into black and white. Every edit can be undone until the user applies the changes.
14
+ - **Deliver.** Apply computes the result at full resolution and hands it to your code as a `Blob`. A download button can also save it.
15
+
16
+ Each step happens only when the user asks for it. Nothing changes the photo on its own.
17
+
18
+ ## What it does not do
19
+
20
+ - It does not upload anything. Your app decides what to do with the result.
21
+ - It does not open PDF files, only images.
22
+ - It does not find the edges of the document on its own: the user drags the corners.
23
+
24
+ ## Packages
25
+
26
+ | Package | Use it with |
27
+ | ----------------- | ---------------------------------- |
28
+ | `@paperpic/core` | Plain JavaScript, or any framework |
29
+ | `@paperpic/vue` | Vue 3.5 or newer |
30
+ | `@paperpic/react` | React 19 or newer |
31
+
32
+ The three have the same options, events and methods, and the core has no runtime dependencies. The editing runs in a Web Worker, so the page stays responsive with large photos.
33
+
34
+ ## Try it
35
+
36
+ The [playground](../playground) lets you edit a sample receipt, or a photo of your own that never leaves your browser. To add PaperPic to your app, go to [Getting started](./getting-started).
@@ -0,0 +1,120 @@
1
+ ---
2
+ title: Translating the interface
3
+ description: How to translate PaperPic or change its wording with the labels option, including the texts read to screen readers, and how to follow the language of your app.
4
+ ---
5
+
6
+ # Translating the interface
7
+
8
+ PaperPic shows its buttons, hints and messages in English, and screen readers announce what changes, also in English. The [`labels`](../reference/options#labels) option replaces any of these texts, so the component speaks the language of your app. No translations ship with the packages.
9
+
10
+ ## Replace some texts
11
+
12
+ Pass only the texts you want to change. The others keep their English text:
13
+
14
+ :::tabs key:framework
15
+ == JavaScript
16
+
17
+ ```ts
18
+ const pic = new PaperPic(container, {
19
+ src: '/receipt.jpg',
20
+ labels: { apply: 'Save', threshold: 'Black and white' },
21
+ })
22
+ ```
23
+
24
+ == Vue
25
+
26
+ ```vue
27
+ <script setup lang="ts">
28
+ import type { PaperPicLabels } from '@paperpic/vue'
29
+ import { PaperPic } from '@paperpic/vue'
30
+
31
+ const labels: Partial<PaperPicLabels> = { apply: 'Save', threshold: 'Black and white' }
32
+ </script>
33
+
34
+ <template>
35
+ <PaperPic src="/receipt.jpg" :labels />
36
+ </template>
37
+ ```
38
+
39
+ == React
40
+
41
+ ```tsx
42
+ import type { PaperPicLabels } from '@paperpic/react'
43
+ import { PaperPic } from '@paperpic/react'
44
+
45
+ const labels: Partial<PaperPicLabels> = { apply: 'Save', threshold: 'Black and white' }
46
+
47
+ export function Receipt() {
48
+ return <PaperPic src="/receipt.jpg" labels={labels} />
49
+ }
50
+ ```
51
+
52
+ :::
53
+
54
+ [Labels](../reference/labels) lists every key with its English text and where it appears.
55
+
56
+ ## Texts with a value
57
+
58
+ Five labels are functions, because their text includes a value: the zoom, the sensitivity of Clean up, a corner and its position, a selected corner, and the ruler of Adjust. Screen readers announce them. Format the numbers as your language does:
59
+
60
+ ```ts
61
+ const signed = new Intl.NumberFormat('es', { signDisplay: 'exceptZero' })
62
+
63
+ const labels: Partial<PaperPicLabels> = {
64
+ zoomLevel: percent => `Zoom ${percent} %`,
65
+ thresholdLevel: percent => `Sensibilidad ${percent} %`,
66
+ cornerMoved: (corner, x, y) => `${corner}: ${x}, ${y}`,
67
+ cornerSelected: corner => `${corner}: toca donde va`,
68
+ adjustmentLevel: (name, value) => `${name} ${signed.format(value)}`,
69
+ }
70
+ ```
71
+
72
+ ## Follow the language of your app
73
+
74
+ When your app changes language, pass new labels, and the viewer updates its texts at once. Build the object only when the language changes, so the viewer does not receive a new one on every render:
75
+
76
+ :::tabs key:framework
77
+ == JavaScript
78
+
79
+ ```ts
80
+ function setLanguage(language: string) {
81
+ pic.setOptions({ labels: translations[language] })
82
+ }
83
+ ```
84
+
85
+ == Vue
86
+
87
+ ```vue
88
+ <script setup lang="ts">
89
+ import { PaperPic } from '@paperpic/vue'
90
+ import { computed } from 'vue'
91
+ import { useI18n } from 'vue-i18n'
92
+
93
+ const { locale } = useI18n()
94
+ const labels = computed(() => translations[locale.value])
95
+ </script>
96
+
97
+ <template>
98
+ <PaperPic src="/receipt.jpg" :labels />
99
+ </template>
100
+ ```
101
+
102
+ == React
103
+
104
+ ```tsx
105
+ import { PaperPic } from '@paperpic/react'
106
+ import { useMemo } from 'react'
107
+
108
+ export function Receipt({ language }: { language: string }) {
109
+ const labels = useMemo(() => translations[language], [language])
110
+ return <PaperPic src="/receipt.jpg" labels={labels} />
111
+ }
112
+ ```
113
+
114
+ :::
115
+
116
+ Here `translations` stands for your own object of labels for each language.
117
+
118
+ ## A starting point
119
+
120
+ This site shows the component in nine languages besides English. Their labels are in [`paperpic-labels.ts`](https://github.com/paperpic/paperpic/blob/development/apps/docs/.vitepress/theme/components/paperpic-labels.ts), and you can copy them into your app.
@@ -0,0 +1,39 @@
1
+ ---
2
+ title: Performance and support
3
+ description: Where PaperPic does its work, what bundlers, Content Security Policy and server-side rendering need, how it handles large phone photos, and which browsers it supports.
4
+ ---
5
+
6
+ # Performance and support
7
+
8
+ Phone photos have 12 megapixels or more, and editing them takes real work. This page explains where that work runs, what your build and your server need, and which browsers PaperPic supports.
9
+
10
+ ## A Web Worker does the work
11
+
12
+ Clean up and Straighten take more than a second on a 12-megapixel photo on a phone. 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
+
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
+
16
+ ## Content Security Policy
17
+
18
+ With a Content Security Policy, allow:
19
+
20
+ - `worker-src 'self'`, for the worker.
21
+ - `img-src blob:`, because the viewer shows attached files and the results of Apply through `blob:` URLs.
22
+
23
+ ## Large photos
24
+
25
+ - **While editing**, the preview works on a copy of about 2 megapixels, so rulers and tools stay fluid with any photo.
26
+ - **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
+ - **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
+
29
+ ## Images it accepts
30
+
31
+ `src` takes a URL from the same origin as your page, or a `File` or `Blob` attached on the client. PaperPic reads the pixels of the image, and browsers only allow that for images from other origins under CORS, which PaperPic does not request. Serve the images from your own domain, or fetch them yourself and pass the `Blob`.
32
+
33
+ ## Server-side rendering
34
+
35
+ PaperPic needs a browser. The Vue and React components render an empty element on the server, such as in Nuxt or Next.js, and create the viewer in the browser. With the core, create the viewer in the browser yourself, such as when your component mounts.
36
+
37
+ ## Browser support
38
+
39
+ PaperPic supports the browsers of [Baseline Widely Available](https://web.dev/baseline): the features that have worked in all the major browsers for at least 30 months. The packages are built for that target, which means Chrome and Edge 124, Firefox 125 and Safari 17.5 or newer, so you do not need to transpile them.