@paperpic/core 0.1.0 → 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.
@@ -30,7 +30,7 @@ pic.on('apply', ({ blob }) => upload(blob))
30
30
 
31
31
  ## `load`
32
32
 
33
- - **Payload:** `{ width: number, height: number }`
33
+ - **Payload:** [`Size`](./types#size)
34
34
 
35
35
  The image is loaded and on display. `width` and `height` are its size in pixels.
36
36
 
@@ -48,13 +48,13 @@ The user changed the view or the edit, such as by zooming, opening a tool or und
48
48
 
49
49
  ## `apply`
50
50
 
51
- - **Payload:** `{ blob: Blob, width: number, height: number, type: string }`
51
+ - **Payload:** [`ExportedImage`](./types#exportedimage)
52
52
 
53
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.
54
54
 
55
55
  ## `download`
56
56
 
57
- - **Payload:** `{ source: string | Blob, filename: string, preventDefault: () => void }`
57
+ - **Payload:** [`PaperPicDownload`](./types#paperpicdownload)
58
58
 
59
59
  The image is about to be saved, from the download button or from [`download()`](./methods#download). `source` is the image on display: the result of the last Apply, or else the `src`. `filename` is the name of the file.
60
60
 
@@ -58,7 +58,7 @@ Returns what the viewer is showing, such as the zoom, the mode and whether there
58
58
  ### `on()`
59
59
 
60
60
  ```ts
61
- function on(name: keyof PaperPicEvents, listener: (payload) => void): () => void
61
+ function on<Name extends keyof PaperPicEvents>(name: Name, listener: (payload: PaperPicEvents[Name]) => void): () => void
62
62
  ```
63
63
 
64
64
  Listens to an event, and returns a function that stops listening. [Events](./events) describes each event.
@@ -90,20 +90,20 @@ Zooms out one step, around the center of the viewer.
90
90
  ### `zoomTo()`
91
91
 
92
92
  ```ts
93
- function zoomTo(zoom: number, point?: { x: number, y: number }): void
93
+ function zoomTo(zoom: number, point?: ViewPoint): void
94
94
  ```
95
95
 
96
- Sets the zoom, where `1` shows one pixel of the image per screen pixel. `point` stays in place: it is in CSS pixels from the top left corner of the viewer, and its center by default.
96
+ Sets the zoom, where `1` shows one pixel of the image per screen pixel. [`point`](./types#viewpoint) stays in place: it is in CSS pixels from the top left corner of the viewer, and its center by default.
97
97
 
98
98
  The zoom goes from the fit of the whole image, or `1` if that is smaller, up to `8`. A value out of range is clamped.
99
99
 
100
100
  ### `fit()`
101
101
 
102
102
  ```ts
103
- function fit(fit: 'image' | 'width' | 'height'): void
103
+ function fit(fit: Fit): void
104
104
  ```
105
105
 
106
- Fits the whole image, its width or its height to the viewer.
106
+ Fits the whole image, its width or its height to the viewer. `fit` is a [`Fit`](./types#fit): `'image'`, `'width'` or `'height'`.
107
107
 
108
108
  ## Editing
109
109
 
@@ -19,7 +19,7 @@ pic.setOptions({ editable: false })
19
19
 
20
20
  ### `src`
21
21
 
22
- - **Type:** `string | Blob`
22
+ - **Type:** [`PaperPicSource`](./types#paperpicsource)
23
23
  - **Default:** none
24
24
 
25
25
  The image to show: a URL from the same origin, or a `File` or `Blob` attached on the client.
@@ -51,7 +51,7 @@ Whether to show the built-in toolbar and edit bar. Without them, build your own
51
51
 
52
52
  ### `tools`
53
53
 
54
- - **Type:** `readonly ToolId[]`
54
+ - **Type:** [`readonly ToolId[]`](./types#toolid)
55
55
  - **Default:** every tool
56
56
 
57
57
  The tools the edit bar offers. They keep the order of this table, whatever the order of the array.
@@ -81,14 +81,14 @@ Whether the toolbar has a button that saves the image on display: the result of
81
81
 
82
82
  ### `labels`
83
83
 
84
- - **Type:** `Partial<PaperPicLabels>`
84
+ - **Type:** [`Partial<PaperPicLabels>`](./types#paperpiclabels)
85
85
  - **Default:** the English texts
86
86
 
87
87
  Replaces any of the texts that the component shows or announces. [Labels](./labels) lists every key.
88
88
 
89
89
  ### `icons`
90
90
 
91
- - **Type:** `Partial<PaperPicIcons>`
91
+ - **Type:** [`Partial<PaperPicIcons>`](./types#paperpicicons)
92
92
  - **Default:** the built-in icons
93
93
 
94
94
  Replaces any of the icons with your own markup of one element, such as an `<svg>`. The markup goes into the page as HTML, so pass only markup you trust. An empty string leaves the buttons of that icon without one. [Styling](../guide/styling#icons) shows an example.
@@ -122,7 +122,7 @@ Each key names an icon, and some icons appear on two buttons:
122
122
 
123
123
  ### `output`
124
124
 
125
- - **Type:** `{ type?: string, quality?: number }`
125
+ - **Type:** [`PaperPicOutput`](./types#paperpicoutput)
126
126
  - **Default:** the format of the source
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.
@@ -40,19 +40,19 @@ Objects and arrays, such as `labels` or `tools`, reach the viewer again whenever
40
40
 
41
41
  ## Events
42
42
 
43
- | Prop | Payload |
44
- | ------------ | -------------------------------------- |
45
- | `onApply` | `{ blob, width, height, type }` |
46
- | `onChange` | [`PaperPicState`](./state) |
47
- | `onDownload` | `{ source, filename, preventDefault }` |
48
- | `onError` | `{ error }` |
49
- | `onLoad` | `{ width, height }` |
43
+ | Prop | Payload |
44
+ | ------------ | ---------------------------------------------- |
45
+ | `onApply` | [`ExportedImage`](./types#exportedimage) |
46
+ | `onChange` | [`PaperPicState`](./state) |
47
+ | `onDownload` | [`PaperPicDownload`](./types#paperpicdownload) |
48
+ | `onError` | `{ error }` |
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`.
52
52
 
53
53
  ## Methods
54
54
 
55
- `ref` receives the viewer, of type `PaperPicInstance`, with every [method](./methods). It is `null` until the component mounts:
55
+ `ref` receives the viewer, of type [`PaperPicInstance`](./types#paperpicinstance), with every [method](./methods). It is `null` until the component mounts:
56
56
 
57
57
  ```tsx
58
58
  import type { PaperPicInstance } from '@paperpic/react'
@@ -75,9 +75,9 @@ export function Viewer({ src }: { src: string }) {
75
75
 
76
76
  Passing the same `src` again does not reload the image, so it keeps the result of an edit. To bring back the original, call `picRef.current.reload()`.
77
77
 
78
- ## Types
78
+ ## Types {#types}
79
79
 
80
- `@paperpic/react` exports the types you need, so you do not need to install `@paperpic/core`: `PaperPicProps`, `PaperPicInstance`, `PaperPicState`, `PaperPicEvents`, `PaperPicIcons`, `PaperPicLabels`, `PaperPicOutput`, `PaperPicDownload`, `ExportedImage` and `ToolId`.
80
+ `@paperpic/react` exports every type of `@paperpic/core`, so you do not need to install it: [Types](./types) shows each one. It also exports the types of the component: [`PaperPicProps`](./types#paperpicprops), with its props, and [`PaperPicInstance`](./types#paperpicinstance), the viewer that `ref` receives.
81
81
 
82
82
  ## Server-side rendering
83
83
 
@@ -15,16 +15,16 @@ pic.on('change', ({ canApply, busy }) => {
15
15
 
16
16
  | Field | Type | Description |
17
17
  | ------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
18
- | `activeTool` | `ToolId \| null` | The open tool, such as `'crop'` or `'adjust'`, or `null` |
18
+ | `activeTool` | [`ToolId \| null`](./types#toolid) | The open tool, such as `'crop'` or `'adjust'`, or `null` |
19
19
  | `adjustments` | `{ brightness, contrast }` | The brightness and the contrast, each from -1 to 1. Clean up leaves them out. While Adjust is open, the values it shows |
20
20
  | `busy` | `boolean` | Whether Apply is running |
21
21
  | `canApply` | `boolean` | Whether there are changes to apply. Rotations and flips that cancel out are no change |
22
22
  | `canRedo` | `boolean` | Whether there is an edit to bring back |
23
23
  | `canUndo` | `boolean` | Whether there is an edit to undo |
24
- | `fit` | `'image' \| 'width' \| 'height' \| null` | The fit in effect, or `null` once the user has zoomed by hand |
25
- | `image` | `{ width, height } \| null` | The size of the image on display in pixels, with the edits so far, or `null` without an image |
24
+ | `fit` | [`Fit \| null`](./types#fit) | The fit in effect, or `null` once the user has zoomed by hand |
25
+ | `image` | [`Size \| null`](./types#size) | The size of the image on display in pixels, with the edits so far, or `null` without an image |
26
26
  | `mode` | `'view' \| 'edit'` | Whether the user is viewing or editing the image |
27
- | `rotation` | `0 \| 90 \| 180 \| 270` | How far the image on display is turned, in degrees clockwise |
27
+ | `rotation` | [`Rotation`](./types#rotation) | How far the image on display is turned, in degrees clockwise |
28
28
  | `status` | `'empty' \| 'loading' \| 'ready' \| 'error'` | Whether there is an image, and whether it loaded |
29
29
  | `threshold` | `{ enabled, sensitivity }` | Whether Clean up is on, and its sensitivity from 0 to 1. While Clean up is open, what it shows |
30
30
  | `zoom` | `number` | Screen pixels per pixel of the image |
@@ -0,0 +1,301 @@
1
+ ---
2
+ title: Types
3
+ description: Every TypeScript type that PaperPic exports, with its definition, the page that explains it and how to import it from the package you installed.
4
+ ---
5
+
6
+ # Types
7
+
8
+ The reference and the examples name types such as `ExportedImage` or `ToolId`. This page shows what each one holds, so you can type your own code. Each type links to the page that explains it.
9
+
10
+ Import the types from the package you installed. `@paperpic/vue` and `@paperpic/react` export every type of `@paperpic/core`, so you do not need to install it:
11
+
12
+ :::tabs key:framework
13
+ == JavaScript
14
+
15
+ ```ts
16
+ import type { ExportedImage, PaperPicState, ToolId } from '@paperpic/core'
17
+ ```
18
+
19
+ == Vue
20
+
21
+ ```ts
22
+ import type { ExportedImage, PaperPicState, ToolId } from '@paperpic/vue'
23
+ ```
24
+
25
+ == React
26
+
27
+ ```ts
28
+ import type { ExportedImage, PaperPicState, ToolId } from '@paperpic/react'
29
+ ```
30
+
31
+ :::
32
+
33
+ ## Options
34
+
35
+ ### `PaperPicOptions`
36
+
37
+ ```ts
38
+ interface PaperPicOptions {
39
+ alt?: string
40
+ aspectRatio?: number
41
+ download?: boolean
42
+ editable?: boolean
43
+ filename?: string
44
+ icons?: Partial<PaperPicIcons>
45
+ labels?: Partial<PaperPicLabels>
46
+ maxOutputSize?: number
47
+ output?: PaperPicOutput
48
+ softness?: number
49
+ src?: PaperPicSource
50
+ toolbar?: boolean
51
+ tools?: readonly ToolId[]
52
+ wheelZoom?: boolean
53
+ }
54
+ ```
55
+
56
+ What the constructor and [`setOptions()`](./methods#setoptions) take. In Vue and React, these are the props of the component. [Options](./options) explains each one.
57
+
58
+ ### `PaperPicSource`
59
+
60
+ ```ts
61
+ type PaperPicSource = string | Blob
62
+ ```
63
+
64
+ The image in [`src`](./options#src): a URL from the same origin, or a `File` or `Blob` attached on the client. The `source` of [`PaperPicDownload`](#paperpicdownload) has the same type.
65
+
66
+ ### `PaperPicOutput`
67
+
68
+ ```ts
69
+ interface PaperPicOutput {
70
+ quality?: number
71
+ type?: string
72
+ }
73
+ ```
74
+
75
+ The format of the edited image, in [`output`](./options#output).
76
+
77
+ ### `ToolId`
78
+
79
+ ```ts
80
+ type ToolId = 'adjust' | 'crop' | 'flip' | 'perspective' | 'rotate' | 'threshold'
81
+ ```
82
+
83
+ A tool of the edit bar, in [`tools`](./options#tools), [`openTool()`](./methods#opentool) and the `activeTool` of the [state](./state). [`tools`](./options#tools) gives the button of each one.
84
+
85
+ ### `PaperPicLabels`
86
+
87
+ ```ts
88
+ interface PaperPicLabels {
89
+ adjust: string
90
+ adjustmentLevel: (name: string, value: number) => string
91
+ applied: string
92
+ apply: string
93
+ applyError: string
94
+ brightness: string
95
+ cancel: string
96
+ cancelTool: string
97
+ confirm: string
98
+ contrast: string
99
+ cornerBottomLeft: string
100
+ cornerBottomRight: string
101
+ cornerMoved: (corner: string, x: number, y: number) => string
102
+ cornerSelected: (corner: string) => string
103
+ cornerTopLeft: string
104
+ cornerTopRight: string
105
+ crop: string
106
+ cropHint: string
107
+ discard: string
108
+ discardQuestion: string
109
+ download: string
110
+ edit: string
111
+ editBar: string
112
+ editing: string
113
+ fitHeight: string
114
+ fitWidth: string
115
+ flip: string
116
+ inUse: string
117
+ keepEditing: string
118
+ loadError: string
119
+ loading: string
120
+ perspective: string
121
+ perspectiveHint: string
122
+ processing: string
123
+ redo: string
124
+ rotateLeft: string
125
+ rotateRight: string
126
+ threshold: string
127
+ thresholdLevel: (percent: number) => string
128
+ thresholdSensitivity: string
129
+ toolbar: string
130
+ undo: string
131
+ viewer: string
132
+ zoomIn: string
133
+ zoomLevel: (percent: number) => string
134
+ zoomOut: string
135
+ }
136
+ ```
137
+
138
+ Every text of the interface, in [`labels`](./options#labels). The texts that include a value, such as the zoom level, are functions. [Labels](./labels) gives the English text of each one.
139
+
140
+ ### `PaperPicIcons`
141
+
142
+ ```ts
143
+ interface PaperPicIcons {
144
+ adjust: string
145
+ apply: string
146
+ brightness: string
147
+ cancel: string
148
+ contrast: string
149
+ crop: string
150
+ download: string
151
+ edit: string
152
+ fitHeight: string
153
+ fitWidth: string
154
+ flip: string
155
+ perspective: string
156
+ redo: string
157
+ rotateDocument: string
158
+ rotateLeft: string
159
+ rotateRight: string
160
+ threshold: string
161
+ undo: string
162
+ zoomIn: string
163
+ zoomOut: string
164
+ }
165
+ ```
166
+
167
+ Every icon of the interface, as the markup of one element, in [`icons`](./options#icons), which gives the buttons of each one.
168
+
169
+ ## State
170
+
171
+ ### `PaperPicState`
172
+
173
+ ```ts
174
+ interface PaperPicState {
175
+ activeTool: ToolId | null
176
+ adjustments: { brightness: number, contrast: number }
177
+ busy: boolean
178
+ canApply: boolean
179
+ canRedo: boolean
180
+ canUndo: boolean
181
+ fit: Fit | null
182
+ image: Size | null
183
+ mode: 'view' | 'edit'
184
+ rotation: Rotation
185
+ status: 'empty' | 'loading' | 'ready' | 'error'
186
+ threshold: { enabled: boolean, sensitivity: number }
187
+ zoom: number
188
+ }
189
+ ```
190
+
191
+ What [`getState()`](./methods#getstate) returns and the [`change`](./events#change) event carries. [State](./state) explains each field.
192
+
193
+ ### `Fit`
194
+
195
+ ```ts
196
+ type Fit = 'image' | 'width' | 'height'
197
+ ```
198
+
199
+ How the image fits the viewer: whole, by its width or by its height. [`fit()`](./methods#fit) takes it, and the `fit` of the [state](./state) holds it.
200
+
201
+ ### `Rotation`
202
+
203
+ ```ts
204
+ type Rotation = 0 | 90 | 180 | 270
205
+ ```
206
+
207
+ How far the image on display is turned, in degrees clockwise, in the `rotation` of the [state](./state).
208
+
209
+ ### `Size`
210
+
211
+ ```ts
212
+ interface Size {
213
+ height: number
214
+ width: number
215
+ }
216
+ ```
217
+
218
+ A width and a height in pixels, such as the `image` of the [state](./state) or what the [`load`](./events#load) event carries.
219
+
220
+ ## Events
221
+
222
+ ### `PaperPicEvents`
223
+
224
+ ```ts
225
+ interface PaperPicEvents {
226
+ apply: ExportedImage
227
+ change: PaperPicState
228
+ download: PaperPicDownload
229
+ error: { error: Error }
230
+ load: Size
231
+ }
232
+ ```
233
+
234
+ Each event with what it carries, for [`on()`](./methods#on). [Events](./events) explains each one.
235
+
236
+ ### `ExportedImage`
237
+
238
+ ```ts
239
+ interface ExportedImage {
240
+ blob: Blob
241
+ height: number
242
+ type: string
243
+ width: number
244
+ }
245
+ ```
246
+
247
+ The edited image, which the [`apply`](./events#apply) event carries. `type` is the format of `blob`, which [`output`](./options#output) chooses.
248
+
249
+ ### `PaperPicDownload`
250
+
251
+ ```ts
252
+ interface PaperPicDownload {
253
+ filename: string
254
+ preventDefault: () => void
255
+ source: PaperPicSource
256
+ }
257
+ ```
258
+
259
+ What the [`download`](./events#download) event carries. Call `preventDefault()` to save the file another way.
260
+
261
+ ## Methods
262
+
263
+ ### `ViewPoint`
264
+
265
+ ```ts
266
+ interface ViewPoint {
267
+ x: number
268
+ y: number
269
+ }
270
+ ```
271
+
272
+ A point in CSS pixels from the top left corner of the viewer, for [`zoomTo()`](./methods#zoomto).
273
+
274
+ ## Vue and React
275
+
276
+ `@paperpic/vue` and `@paperpic/react` also export the types of their component. [Vue](./vue) and [React](./react) show how to use it.
277
+
278
+ ### `PaperPicInstance`
279
+
280
+ ```ts
281
+ type PaperPicInstance = PaperPic
282
+ ```
283
+
284
+ The viewer that the component gives you: `instance` in Vue, and what `ref` receives in React. It is the class `PaperPic` of `@paperpic/core`, with every [method](./methods).
285
+
286
+ ### `PaperPicProps`
287
+
288
+ ```ts
289
+ interface PaperPicProps extends PaperPicOptions {
290
+ className?: string
291
+ onApply?: (result: PaperPicEvents['apply']) => void
292
+ onChange?: (state: PaperPicEvents['change']) => void
293
+ onDownload?: (download: PaperPicEvents['download']) => void
294
+ onError?: (failure: PaperPicEvents['error']) => void
295
+ onLoad?: (size: PaperPicEvents['load']) => void
296
+ ref?: Ref<PaperPicInstance>
297
+ style?: CSSProperties
298
+ }
299
+ ```
300
+
301
+ The props of the component in React: the options, plus the classes and styles of its element, a callback for each event, and `ref`. In Vue, the props have the same fields as [`PaperPicOptions`](#paperpicoptions), and the events are component events.
@@ -35,13 +35,13 @@ Objects and arrays that the template builds, such as `:labels="{ apply: t('apply
35
35
 
36
36
  ## Events
37
37
 
38
- | Event | Payload |
39
- | ---------- | -------------------------------------- |
40
- | `apply` | `{ blob, width, height, type }` |
41
- | `change` | [`PaperPicState`](./state) |
42
- | `download` | `{ source, filename, preventDefault }` |
43
- | `error` | `{ error }` |
44
- | `load` | `{ width, height }` |
38
+ | Event | Payload |
39
+ | ---------- | ---------------------------------------------- |
40
+ | `apply` | [`ExportedImage`](./types#exportedimage) |
41
+ | `change` | [`PaperPicState`](./state) |
42
+ | `download` | [`PaperPicDownload`](./types#paperpicdownload) |
43
+ | `error` | `{ error }` |
44
+ | `load` | [`Size`](./types#size) |
45
45
 
46
46
  [Events](./events) describes each one. A change of a prop never emits `change`.
47
47
 
@@ -69,9 +69,9 @@ const pic = useTemplateRef('pic')
69
69
 
70
70
  Passing the same `src` again does not reload the image, so it keeps the result of an edit. To bring back the original, call `instance.reload()`.
71
71
 
72
- ## Types
72
+ ## Types {#types}
73
73
 
74
- `@paperpic/vue` exports the types you need, so you do not need to install `@paperpic/core`: `PaperPicProps`, `PaperPicState`, `PaperPicEvents`, `PaperPicIcons`, `PaperPicLabels`, `PaperPicOutput`, `PaperPicDownload`, `ExportedImage` and `ToolId`.
74
+ `@paperpic/vue` exports every type of `@paperpic/core`, so you do not need to install it: [Types](./types) shows each one. It also exports the types of the component: [`PaperPicProps`](./types#paperpicprops), with its props, and [`PaperPicInstance`](./types#paperpicinstance), the viewer in `instance`.
75
75
 
76
76
  ## Server-side rendering
77
77
 
package/dist/index.d.ts CHANGED
@@ -1,47 +1,64 @@
1
- /** What the `download` event carries. */
2
- interface PaperPicDownload {
3
- /** The name of the file, with the extension of its format. */
4
- filename: string;
5
- /** Stops the browser from saving the file, so you can save it another way. */
6
- preventDefault: () => void;
7
- /** The image to save: the result of the last Apply, or else the `src`. */
8
- source: string | Blob;
9
- }
10
- export type Rotation = 0 | 90 | 180 | 270;
11
1
  /**
12
- * Rounds an angle in degrees to the nearest multiple of 90 and wraps it into [0, 360).
2
+ * How far the image is turned, in degrees clockwise.
13
3
  *
14
- * @throws {RangeError} If `degrees` is not a finite number.
4
+ * @see https://paperpic.dev/reference/state
5
+ */
6
+ type Rotation = 0 | 90 | 180 | 270;
7
+ /**
8
+ * The format of the image that editing produces.
9
+ *
10
+ * @see https://paperpic.dev/reference/options#output
15
11
  */
16
- export declare function normalizeRotation(degrees: number): Rotation;
17
- /** The format of the image that editing produces. */
18
12
  interface PaperPicOutput {
19
13
  /** From 0 to 1, for JPEG and WebP. */
20
14
  quality?: number;
21
15
  /** `image/jpeg`, `image/png` or `image/webp`. By default, the format of the source. */
22
16
  type?: string;
23
17
  }
24
- /** The image that editing produces. */
18
+ /**
19
+ * The image that editing produces, which the `apply` event carries.
20
+ *
21
+ * @see https://paperpic.dev/reference/events#apply
22
+ */
25
23
  interface ExportedImage {
24
+ /** The edited image, ready to upload. */
26
25
  blob: Blob;
26
+ /** In pixels. */
27
27
  height: number;
28
28
  /** The format of `blob`. A browser that cannot encode the requested one gives PNG. */
29
29
  type: string;
30
+ /** In pixels. */
30
31
  width: number;
31
32
  }
32
- /** A size in CSS pixels. */
33
+ /**
34
+ * A width and a height in pixels.
35
+ *
36
+ * @see https://paperpic.dev/reference/types#size
37
+ */
33
38
  interface Size {
34
39
  height: number;
35
40
  width: number;
36
41
  }
37
- /** A position in CSS pixels, relative to the top left corner of the viewport. */
42
+ /**
43
+ * A position in CSS pixels, relative to the top left corner of the viewer.
44
+ *
45
+ * @see https://paperpic.dev/reference/methods#zoomto
46
+ */
38
47
  interface ViewPoint {
39
48
  x: number;
40
49
  y: number;
41
50
  }
42
- /** How the image adapts to the viewport: the whole image, its width or its height. */
51
+ /**
52
+ * How the image adapts to the viewer: the whole image, its width or its height.
53
+ *
54
+ * @see https://paperpic.dev/reference/methods#fit
55
+ */
43
56
  type Fit = 'image' | 'width' | 'height';
44
- /** Every text the component shows or announces. */
57
+ /**
58
+ * Every text the component shows or announces. The texts with values are functions.
59
+ *
60
+ * @see https://paperpic.dev/reference/labels
61
+ */
45
62
  interface PaperPicLabels {
46
63
  /** Opens the ruler of brightness and contrast. */
47
64
  adjust: string;
@@ -115,9 +132,17 @@ interface PaperPicLabels {
115
132
  zoomLevel: (percent: number) => string;
116
133
  zoomOut: string;
117
134
  }
118
- /** The tools the edit bar can offer. */
135
+ /**
136
+ * The tools the edit bar can offer. `perspective` is Straighten, and `threshold` is Clean up.
137
+ *
138
+ * @see https://paperpic.dev/reference/options#tools
139
+ */
119
140
  type ToolId = 'adjust' | 'crop' | 'flip' | 'perspective' | 'rotate' | 'threshold';
120
- /** Every icon of the interface, as the markup of one element, such as an `<svg>`. One icon can appear on several buttons. */
141
+ /**
142
+ * Every icon of the interface, as the markup of one element, such as an `<svg>`. One icon can appear on several buttons.
143
+ *
144
+ * @see https://paperpic.dev/reference/options#icons
145
+ */
121
146
  interface PaperPicIcons {
122
147
  /** Adjust, which opens the ruler of brightness and contrast. */
123
148
  adjust: string;
@@ -151,9 +176,18 @@ interface PaperPicIcons {
151
176
  zoomIn: string;
152
177
  zoomOut: string;
153
178
  }
154
- /** The image to show: a URL from the same origin, or a file attached on the client. */
155
- export type PaperPicSource = string | Blob;
156
- export interface PaperPicOptions {
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
+ /**
186
+ * What the constructor and `setOptions()` take.
187
+ *
188
+ * @see https://paperpic.dev/reference/options
189
+ */
190
+ interface PaperPicOptions {
157
191
  /** Describes the image for screen readers. Without it, they skip the image, as they skip an `<img>` with an empty `alt`. */
158
192
  alt?: string;
159
193
  /** The real proportions of the document, as width divided by height, such as `210 / 297` for A4. Without it, straightening estimates them. */
@@ -192,8 +226,12 @@ export interface PaperPicOptions {
192
226
  /** Whether the wheel zooms. Turn it off when the viewer sits in a long page. */
193
227
  wheelZoom?: boolean;
194
228
  }
195
- /** What the viewer is showing. */
196
- export interface PaperPicState {
229
+ /**
230
+ * What the viewer is showing, which `getState()` returns and the `change` event carries.
231
+ *
232
+ * @see https://paperpic.dev/reference/state
233
+ */
234
+ interface PaperPicState {
197
235
  /** The open tool, such as Crop or Adjust, or `null`. Done or Cancel closes it. */
198
236
  activeTool: ToolId | null;
199
237
  /**
@@ -208,7 +246,9 @@ export interface PaperPicState {
208
246
  busy: boolean;
209
247
  /** Whether there are changes to apply. Rotations that cancel out are no change. */
210
248
  canApply: boolean;
249
+ /** Whether there is an edit to bring back. */
211
250
  canRedo: boolean;
251
+ /** Whether there is an edit to undo. */
212
252
  canUndo: boolean;
213
253
  /** The fit in effect, or `null` once the user has zoomed by hand. */
214
254
  fit: Fit | null;
@@ -216,7 +256,9 @@ export interface PaperPicState {
216
256
  image: Size | null;
217
257
  /** Whether the user is viewing or editing the image. */
218
258
  mode: 'view' | 'edit';
259
+ /** How far the image on display is turned, in degrees clockwise. */
219
260
  rotation: Rotation;
261
+ /** Whether there is an image, and whether it loaded. */
220
262
  status: 'empty' | 'loading' | 'ready' | 'error';
221
263
  /** Whether the document gets cleaned up, and how much. While Clean up is open, what it shows, which Done would keep. */
222
264
  threshold: {
@@ -226,7 +268,12 @@ export interface PaperPicState {
226
268
  /** Screen pixels per image pixel. */
227
269
  zoom: number;
228
270
  }
229
- export interface PaperPicEvents {
271
+ /**
272
+ * Each event of `on()`, with what it carries.
273
+ *
274
+ * @see https://paperpic.dev/reference/events
275
+ */
276
+ interface PaperPicEvents {
230
277
  /** The user applied the changes. The result is already on display. */
231
278
  apply: ExportedImage;
232
279
  /** The user changed the view or the edit. `setOptions()` never triggers it. */
@@ -238,10 +285,7 @@ export interface PaperPicEvents {
238
285
  error: Error;
239
286
  };
240
287
  /** The image is ready. */
241
- load: {
242
- height: number;
243
- width: number;
244
- };
288
+ load: Size;
245
289
  }
246
290
  type Listener<Name extends keyof PaperPicEvents> = (payload: PaperPicEvents[Name]) => void;
247
291
  /**
@@ -495,4 +539,17 @@ export declare class PaperPic {
495
539
  /** Runs a key's command. Returns whether it did something, so other keys keep their usual effect. */
496
540
  private runKey;
497
541
  }
498
- export type { ExportedImage, Fit, PaperPicDownload, PaperPicIcons, PaperPicLabels, PaperPicOutput, Size, ToolId, ViewPoint };
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
+ export type { ExportedImage, Fit, PaperPicDownload, PaperPicEvents, PaperPicIcons, PaperPicLabels, PaperPicOptions, PaperPicOutput, PaperPicSource, PaperPicState, Rotation, Size, ToolId, ViewPoint };
package/dist/index.js CHANGED
@@ -3162,4 +3162,4 @@ var PaperPic = class {
3162
3162
  }
3163
3163
  }
3164
3164
  };
3165
- export { PaperPic, normalizeRotation };
3165
+ export { PaperPic };
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@paperpic/core",
3
3
  "type": "module",
4
- "version": "0.1.0",
4
+ "version": "0.2.0",
5
5
  "description": "Framework-agnostic document image viewer and editor, for use with plain JavaScript or through a PaperPic wrapper.",
6
6
  "author": "Marco Caparrós <hello@paperpic.dev>",
7
7
  "license": "MIT",