@hussmartinez/image-sdk 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,1530 @@
1
+ /**
2
+ * React editor of the image SDK: `ImageEditor`, its building blocks and hooks.
3
+ *
4
+ * @remarks
5
+ * A client entry: it starts with `"use client"`, which the build keeps
6
+ * (ADR 0007). React and React DOM 18.3 or later are optional peer
7
+ * dependencies. Hosts import `@hussmartinez/ui/styles.css` once, then this
8
+ * package's `styles.css` (sdk-core ADR 0036).
9
+ *
10
+ * @packageDocumentation
11
+ */
12
+
13
+ import { FilePolicy } from '@hussmartinez/sdk-core';
14
+ import { FilePolicyOverrides } from '@hussmartinez/sdk-core';
15
+ import { ForwardRefExoticComponent } from 'react';
16
+ import { IconComponent } from '@hussmartinez/ui/react';
17
+ import { MessageOverrides } from '@hussmartinez/sdk-core';
18
+ import type { Messages } from '@hussmartinez/sdk-core';
19
+ import { ReactNode } from 'react';
20
+ import { RefAttributes } from 'react';
21
+ import { SdkCoreErrorCode } from '@hussmartinez/sdk-core';
22
+ import { SdkError } from '@hussmartinez/sdk-core';
23
+ import type { ShortcutRegistry } from '@hussmartinez/sdk-core';
24
+ import type { Store } from '@hussmartinez/sdk-core';
25
+ import type { Tool } from '@hussmartinez/sdk-core';
26
+ import type { ToolRegistry } from '@hussmartinez/sdk-core';
27
+
28
+ /**
29
+ * An EXIF orientation, 1 to 8: how the stored pixels must be turned to be
30
+ * upright. 1 means they already are (ADR 0005).
31
+ *
32
+ * @public
33
+ */
34
+ declare type ExifOrientation = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
35
+
36
+ /**
37
+ * The filter presets (ADR 0006). Names are part of the document format:
38
+ * presets are only ever added.
39
+ *
40
+ * @public
41
+ */
42
+ declare const FILTER_PRESETS: readonly ["vivid", "warm", "cool", "fade", "mono", "noir", "sepia"];
43
+
44
+ /**
45
+ * The Adjust panel (docs/adr/0006, docs/adr/0007): a slider per develop
46
+ * adjustment, in the order they're applied, from −100 to 100. A slider's
47
+ * gesture previews on the stage and is one undo step when it ends; each
48
+ * slider resets to 0 with its button, or by double-clicking it, and "Reset
49
+ * all" resets every one in one step.
50
+ *
51
+ * @public
52
+ */
53
+ export declare function ImageAdjustPanel(props: ImageAdjustPanelProps): ReactNode;
54
+
55
+ /**
56
+ * Props of {@link ImageAdjustPanel}.
57
+ *
58
+ * @public
59
+ */
60
+ export declare interface ImageAdjustPanelProps {
61
+ readonly className?: string;
62
+ }
63
+
64
+ /**
65
+ * The crop frame's geometry (docs/adr/0007): pure functions over crops in
66
+ * whole pixels of the oriented source, which the editor's frame, keys and
67
+ * fields share, so every way of cropping gives the same result.
68
+ */
69
+ /**
70
+ * An aspect ratio the crop panel offers: free, the source's own, or width
71
+ * over height.
72
+ *
73
+ * @public
74
+ */
75
+ declare type ImageAspect = "free" | "original" | readonly [number, number];
76
+
77
+ /**
78
+ * The image being edited: a source, its crop and orientation, and its
79
+ * develop adjustments and filter.
80
+ *
81
+ * @public
82
+ */
83
+ declare interface ImageBase {
84
+ /** The id of a registered source. */
85
+ readonly source: string;
86
+ /** The crop, or `null` for the whole image. */
87
+ readonly crop: ImageCrop | null;
88
+ readonly orientation: ImageOrientation_2;
89
+ readonly develop: ImageDevelop;
90
+ /** The filter, or `null` for none. */
91
+ readonly filter: ImageFilter | null;
92
+ }
93
+
94
+ /**
95
+ * Options every port call accepts.
96
+ *
97
+ * @public
98
+ */
99
+ declare interface ImageCallOptions {
100
+ /**
101
+ * Cancels the call. It then rejects with an `ImageError` whose code is
102
+ * `ABORTED`, `TIMEOUT`, or the code of an `SdkError` given as the abort
103
+ * reason, such as `PROCESSING_TIME_EXCEEDED`.
104
+ */
105
+ readonly signal?: AbortSignal;
106
+ }
107
+
108
+ /**
109
+ * Every edit to an {@link ImagePlan}: plain, structured-cloneable data
110
+ * (ADR 0003). Feature pull requests add their own commands to this union.
111
+ *
112
+ * @public
113
+ */
114
+ declare type ImageCommand = SetCropCommand | SetOrientationCommand | SetOutputCommand | SetMetadataCommand | SetDevelopCommand | SetFilterCommand;
115
+
116
+ /**
117
+ * A rectangle in whole pixels of the oriented source: `x` and `y` from its
118
+ * top left, `width` and `height` at least 1 (ADR 0003).
119
+ *
120
+ * @public
121
+ */
122
+ declare interface ImageCrop {
123
+ readonly x: number;
124
+ readonly y: number;
125
+ readonly width: number;
126
+ readonly height: number;
127
+ }
128
+
129
+ /**
130
+ * The crop panel (docs/adr/0007): the crop's position and size in source
131
+ * pixels as number fields, the aspect presets, and Apply, Cancel and Whole
132
+ * image. It's the alternative to dragging the frame (WCAG 2.5.7), shown while
133
+ * cropping.
134
+ *
135
+ * @public
136
+ */
137
+ export declare function ImageCropPanel(props: ImageCropPanelProps): ReactNode;
138
+
139
+ /**
140
+ * Props of {@link ImageCropPanel}.
141
+ *
142
+ * @public
143
+ */
144
+ export declare interface ImageCropPanelProps {
145
+ readonly className?: string;
146
+ }
147
+
148
+ /**
149
+ * The base's tonal and colour adjustments (ADR 0006). Each is an integer
150
+ * from -100 to 100, where 0 is unchanged, applied in this order.
151
+ *
152
+ * @public
153
+ */
154
+ declare interface ImageDevelop {
155
+ /** Warmer (positive) or cooler (negative). */
156
+ readonly temperature: number;
157
+ /** Toward magenta (positive) or green (negative). */
158
+ readonly tint: number;
159
+ /** In fiftieths of a stop: 100 is two stops brighter. */
160
+ readonly exposure: number;
161
+ readonly highlights: number;
162
+ readonly shadows: number;
163
+ readonly contrast: number;
164
+ readonly saturation: number;
165
+ /** Saturation weighted toward the least saturated colours. */
166
+ readonly vibrance: number;
167
+ }
168
+
169
+ /**
170
+ * The image editor (docs/adr/0007): a toolbar and a stage over an image
171
+ * session, with the family's shortcuts while focus is inside it. It creates
172
+ * its engine, processor and session unless you pass them, and destroys only
173
+ * what it created. Import `@hussmartinez/ui/styles.css` once, then this
174
+ * package's `styles.css`: ui's stylesheet carries the focus rings and target
175
+ * sizes the editor's accessibility relies on (sdk-core ADR 0036).
176
+ *
177
+ * @example
178
+ * ```tsx
179
+ * <ImageEditor initialFile={file} onChange={(plan) => save(plan)} />
180
+ * ```
181
+ *
182
+ * @public
183
+ */
184
+ export declare const ImageEditor: ForwardRefExoticComponent<ImageEditorProps & RefAttributes<ImageEditorHandle>>;
185
+
186
+ /**
187
+ * Which of the editor's capabilities are on (docs/adr/0007): the inspector's
188
+ * panels and export. Each is on unless set to `false`. The toolbar's tools
189
+ * are chosen with `tools` and `toolbar` instead.
190
+ *
191
+ * @public
192
+ */
193
+ export declare interface ImageEditorFeatures {
194
+ /** The Adjust panel's develop sliders. */
195
+ readonly adjust?: boolean;
196
+ /** The Filters panel's presets. */
197
+ readonly filters?: boolean;
198
+ /** The Info panel. */
199
+ readonly info?: boolean;
200
+ /**
201
+ * The Export tool and its dialog. Off, the editor offers no export, and
202
+ * the ref handle's `export()` still returns the file to the host.
203
+ */
204
+ readonly export?: boolean;
205
+ }
206
+
207
+ /**
208
+ * What a ref to {@link ImageEditor} gives the host.
209
+ *
210
+ * @public
211
+ */
212
+ export declare interface ImageEditorHandle {
213
+ /** The editor's session, for state and commands beyond the handle's. */
214
+ readonly session: ImageSession;
215
+ /** Opens an image, replacing the current one once it has opened. */
216
+ open(file: Blob): Promise<void>;
217
+ /** Applies commands as one undoable step. */
218
+ execute(commands: ImageCommand | readonly ImageCommand[]): void;
219
+ /** Renders and encodes the image as it is now. */
220
+ export(format: ImageExportFormat): Promise<ImageSessionExport>;
221
+ /** Undoes the last edit, if there is one. */
222
+ undo(): void;
223
+ /** Redoes the last undone edit, if there is one. */
224
+ redo(): void;
225
+ }
226
+
227
+ /**
228
+ * The parts of `ImageEditor` that take extra classes through `classNames`.
229
+ *
230
+ * @public
231
+ */
232
+ export declare type ImageEditorPart = "root" | "toolbar" | "stage" | "inspector";
233
+
234
+ /**
235
+ * Props of {@link ImageEditor}. The session props are the provider's: pass
236
+ * a `session` of your own over your `engine`, or let the editor create one.
237
+ *
238
+ * @public
239
+ */
240
+ export declare interface ImageEditorProps extends Omit<ImageEditorProviderProps, "children"> {
241
+ /** An image to open on mount. Images the user opens in the editor replace it. */
242
+ readonly initialFile?: Blob;
243
+ /**
244
+ * The plan, for a host that holds it: the controlled form. When it changes,
245
+ * the editor applies it as one undoable step (`session.applyPlan`). Use it
246
+ * with `onChange`, which gets the plans the editor makes.
247
+ */
248
+ readonly plan?: ImagePlan;
249
+ /** Called with the plan after each committed edit, open, undo or redo, never during a gesture. */
250
+ readonly onChange?: (plan: ImagePlan) => void;
251
+ /** Which tools are present, by id, in order. All of them by default. */
252
+ readonly tools?: readonly string[];
253
+ /** The toolbar's groups, as tool ids. */
254
+ readonly toolbar?: readonly (readonly string[])[];
255
+ /** Icon components by name, over ui's. */
256
+ readonly icons?: Readonly<Record<string, IconComponent>>;
257
+ /** Extra classes on the root. */
258
+ readonly className?: string;
259
+ /** Extra classes on each part. */
260
+ readonly classNames?: Readonly<Partial<Record<ImageEditorPart, string>>>;
261
+ /** Drop the visual styles, keeping layout and accessibility. */
262
+ readonly unstyled?: boolean;
263
+ /** Which capabilities are on: the inspector's panels and export. All of them by default. */
264
+ readonly features?: ImageEditorFeatures;
265
+ /** The colour mode, set as `data-hm-theme` on the editor's root. Unset, it inherits the page's. */
266
+ readonly theme?: ImageEditorTheme;
267
+ /**
268
+ * Takes the exported file instead of the export dialog's download button;
269
+ * the dialog closes once it's called.
270
+ */
271
+ readonly onExport?: (blob: Blob, details: ImageSessionExport) => void;
272
+ }
273
+
274
+ /**
275
+ * Provides an image session, its engine, the stage's view and the SDK's
276
+ * text to the components below it: `ImageStage`, `ImageToolbar` and the
277
+ * hooks (docs/adr/0007). `ImageEditor` renders one itself.
278
+ *
279
+ * @example
280
+ * ```tsx
281
+ * <ImageEditorProvider locale="de" messages={{ "editor.empty": "Öffnen Sie ein Bild." }}>
282
+ * <ImageToolbar />
283
+ * <ImageStage />
284
+ * </ImageEditorProvider>
285
+ * ```
286
+ *
287
+ * @public
288
+ */
289
+ export declare function ImageEditorProvider(props: ImageEditorProviderProps): ReactNode;
290
+
291
+ /**
292
+ * Props of {@link ImageEditorProvider}.
293
+ *
294
+ * @public
295
+ */
296
+ export declare interface ImageEditorProviderProps {
297
+ /**
298
+ * The engine that probes, decodes and holds images, and draws the stage.
299
+ * Defaults to the SDK's own, created with `assetsUrl`. A session of your own
300
+ * must use this engine.
301
+ */
302
+ readonly engine?: ImageEngine;
303
+ /** The processor for exports. Defaults to the SDK's own, on the engine. */
304
+ readonly processor?: ImageProcessor;
305
+ /** A session of your own, over `engine`, instead of one the provider creates. */
306
+ readonly session?: ImageSession;
307
+ /**
308
+ * Where the application serves the package's `dist/assets/` directory, for
309
+ * the engine the provider creates (docs/adr/0002).
310
+ */
311
+ readonly assetsUrl?: string | URL;
312
+ /** File limits for a session the provider creates (docs/adr/0004). */
313
+ readonly filePolicy?: ImageFilePolicyOverrides;
314
+ /** Anonymous usage events from a session the provider creates. */
315
+ readonly onEvent?: (event: ImageSessionEvent) => void;
316
+ /** Text overrides, typed against the English catalogue (ADR 0019). */
317
+ readonly messages?: MessageOverrides<ImageMessageCatalogue>;
318
+ /** The locale for numbers and plurals. Defaults to `"en"`. */
319
+ readonly locale?: string;
320
+ /** The components that use the session, such as `ImageStage`. */
321
+ readonly children?: ReactNode;
322
+ }
323
+
324
+ /**
325
+ * The editor's own state, outside the session and its history
326
+ * (docs/adr/0007): the active tool, a crop in progress, and a gesture's
327
+ * transient plan, which the stage renders instead of the session's.
328
+ *
329
+ * @public
330
+ */
331
+ export declare interface ImageEditorState {
332
+ /** The tool that takes over the stage, such as `crop`, or `null`. */
333
+ readonly tool: "crop" | null;
334
+ /** The crop being made, in whole pixels of the oriented source, and its aspect. */
335
+ readonly crop: {
336
+ readonly pending: ImageCrop;
337
+ readonly aspect: ImageAspect;
338
+ } | null;
339
+ /**
340
+ * A gesture's plan while it runs: the session's plan with the gesture's
341
+ * change, which isn't an edit until the gesture ends.
342
+ */
343
+ readonly preview: ImagePlan | null;
344
+ /** The dialog the editor shows over the stage, such as `export`, or `null`. */
345
+ readonly dialog: "export" | null;
346
+ }
347
+
348
+ /**
349
+ * The editor's colour mode: ui's light or dark theme, or the system's. Unset,
350
+ * it inherits the page's.
351
+ *
352
+ * @public
353
+ */
354
+ export declare type ImageEditorTheme = "light" | "dark" | "system";
355
+
356
+ /**
357
+ * The port for reading images: probe a file's headers, decode it into a
358
+ * source the engine holds, make thumbnails and release sources (ADR 0001,
359
+ * ADR 0002, ADR 0003, ADR 0008). The SDK's own adapter probes with its own
360
+ * readers and decodes with `createImageBitmap`, both in its render worker;
361
+ * hosts can pass their own to the editor's `engine` prop, and every
362
+ * implementation must pass the engine's contract tests.
363
+ *
364
+ * `register` checks a file's own limits, from `filePolicy`, against the
365
+ * engine's own probe before decoding it, so a host can't decode past them by
366
+ * passing a probe of another file. Session-wide limits, such as
367
+ * `maxSessionSize`, are the session's (ADR 0004).
368
+ *
369
+ * Failures reject with `ImageError`: `INVALID_IMAGE` for a malformed file,
370
+ * one whose headers claim more than its data holds, or one whose decoded
371
+ * size differs from the probe's; `UNSUPPORTED_FORMAT` for one the probe
372
+ * can't bound; `DECODE_FAILED` when the browser can't decode it; and
373
+ * sdk-core's codes for cancellation and worker failures.
374
+ *
375
+ * @public
376
+ */
377
+ declare interface ImageEngine {
378
+ /** Reads a file's headers and metadata, without decoding it. */
379
+ probe(file: Blob, options?: ImageCallOptions): Promise<ImageProbe>;
380
+ /**
381
+ * Decodes a probed file into a source with the given id, upright. The
382
+ * decoded size must equal the probe's oriented size, or the call rejects
383
+ * with `INVALID_IMAGE` and keeps nothing. A file over one of
384
+ * `filePolicy`'s per-file limits rejects with that limit's code, before
385
+ * anything decodes it. An id already in use is a
386
+ * `TypeError`.
387
+ */
388
+ register(id: string, file: Blob, probe: ImageProbe, options?: ImageRegisterOptions): Promise<ImageSourceInfo>;
389
+ /**
390
+ * A rendering of a source that fits inside `maxSize` × `maxSize`, keeping
391
+ * its aspect ratio and never enlarging it. An unknown id is a `TypeError`.
392
+ */
393
+ thumbnail(id: string, maxSize: number, options?: ImageCallOptions): Promise<ImageThumbnail>;
394
+ /** Frees a source's pixels. Releasing an unknown id does nothing. */
395
+ release(id: string): Promise<void>;
396
+ /** Releases the engine, its sources and its worker. Pending calls reject, and later calls throw. */
397
+ destroy(): Promise<void>;
398
+ }
399
+
400
+ /**
401
+ * The error `@hussmartinez/image-sdk` throws and rejects with, with a stable
402
+ * `code`, structured `details` and the underlying error as `cause`. Show
403
+ * users the text for its code from {@link imageMessages}, never its
404
+ * `message`, which is for developers and may contain text from the file.
405
+ *
406
+ * @example
407
+ * ```ts
408
+ * try {
409
+ * await session.open(file);
410
+ * } catch (error) {
411
+ * if (isImageError(error, "DECODE_FAILED")) {
412
+ * suggestConvertingToPng();
413
+ * } else {
414
+ * show(messages.error(error));
415
+ * }
416
+ * }
417
+ * ```
418
+ *
419
+ * @public
420
+ */
421
+ declare class ImageError extends SdkError<ImageErrorCode> {
422
+ /** Always `"ImageError"`, which survives minification and worker boundaries. */
423
+ readonly name = "ImageError";
424
+ }
425
+
426
+ /**
427
+ * Error codes of `@hussmartinez/image-sdk`: sdk-core's own codes, such as
428
+ * `ABORTED`, `WORKER_CRASHED` and `FILE_TOO_LARGE`, plus the image SDK's
429
+ * (ADR 0001, ADR 0004). They never change meaning once released.
430
+ *
431
+ * - `INVALID_IMAGE`: the file is malformed, its headers claim more than its
432
+ * data can carry or less than its decoder would produce, or its decoded
433
+ * size differs from what its headers declare.
434
+ * - `UNSUPPORTED_FORMAT`: the format isn't recognised, its bound can't be
435
+ * read, or the browser can't encode the requested export format.
436
+ * `details.format` names it.
437
+ * - `DECODE_FAILED`: the browser couldn't decode a file the SDK probed,
438
+ * usually because it lacks the format. `details.format` names it.
439
+ * - `INVALID_COMMAND`: an edit command doesn't apply to the plan, such as a
440
+ * crop outside its source. `details.reason` says why, as a stable token
441
+ * (`ImageCommandRejection`).
442
+ * - `INVALID_DOCUMENT`: a plan document, such as a saved project, isn't
443
+ * valid in its format. `details.reason` says why (`ImageDocumentRejection`).
444
+ * A document of another format, or a later version, is `UNSUPPORTED_FORMAT`
445
+ * instead, with `details.reason` `unknown-format` or `unknown-format-version`.
446
+ * - `IMAGE_TOO_LARGE`: an image, a frame, the canvas or the export exceeds
447
+ * the `maxImagePixels` limit.
448
+ * - `IMAGE_DIMENSION_TOO_LARGE`: a width or height exceeds the
449
+ * `maxImageDimension` limit.
450
+ * - `TOO_MANY_FRAMES`: an animation exceeds the `maxFrames` limit.
451
+ * - `SESSION_TOO_LARGE`: the decoded images the session holds exceed the
452
+ * `maxSessionSize` limit.
453
+ * - `TOO_MANY_LAYERS`: the layer plan exceeds the `maxLayers` limit.
454
+ *
455
+ * Limit codes carry `details` with the `limit`, its `maximum`, the `actual`
456
+ * value and the `unit`. Other codes' `details` name the format involved,
457
+ * and a `reason`, never data from the file.
458
+ *
459
+ * @public
460
+ */
461
+ declare type ImageErrorCode = SdkCoreErrorCode | "INVALID_IMAGE" | "UNSUPPORTED_FORMAT" | "DECODE_FAILED" | "INVALID_COMMAND" | "INVALID_DOCUMENT" | "IMAGE_TOO_LARGE" | "IMAGE_DIMENSION_TOO_LARGE" | "TOO_MANY_FRAMES" | "SESSION_TOO_LARGE" | "TOO_MANY_LAYERS";
462
+
463
+ /**
464
+ * The export dialog (docs/adr/0007). Export is irreversible, so it shows a
465
+ * summary before anything is written: the output's size and format, the
466
+ * metadata the source carried that the file won't, and the fields the user
467
+ * chose to keep. Then a progress bar that can stop the export, and a
468
+ * download button, which gets focus, with the file's size.
469
+ *
470
+ * It opens when the editor state's `dialog` is `export`, as the export tool
471
+ * sets it. On Export, the chosen size and fields become one undoable step
472
+ * of the plan, so the plan records what was exported. A format the browser
473
+ * can't encode shows the catalogue's text, and keeps the choices.
474
+ *
475
+ * @public
476
+ */
477
+ export declare function ImageExportDialog(props: ImageExportDialogProps): ReactNode;
478
+
479
+ /**
480
+ * Props of {@link ImageExportDialog}.
481
+ *
482
+ * @public
483
+ */
484
+ export declare interface ImageExportDialogProps {
485
+ /**
486
+ * Takes the exported file instead of the dialog's download button: the
487
+ * dialog closes once it's called.
488
+ */
489
+ readonly onExport?: (blob: Blob, details: ImageSessionExport) => void;
490
+ /** The downloaded file's name, without its extension. Defaults to `image`. */
491
+ readonly fileName?: string;
492
+ /** Extra classes on the dialog. */
493
+ readonly className?: string;
494
+ }
495
+
496
+ /**
497
+ * The file an export produces (ADR 0001). `quality`, from 0 to 1, applies to
498
+ * the lossy formats; it defaults to 0.92. WebP is encoded only where the
499
+ * browser can, and otherwise rejects with `UNSUPPORTED_FORMAT`.
500
+ *
501
+ * @public
502
+ */
503
+ declare type ImageExportFormat = {
504
+ readonly type: "png";
505
+ } | {
506
+ readonly type: "jpeg";
507
+ readonly quality?: number;
508
+ } | {
509
+ readonly type: "webp";
510
+ readonly quality?: number;
511
+ };
512
+
513
+ /**
514
+ * One export: a plan over sources registered with the same engine, and the
515
+ * output format. The plan's kept metadata goes into the file, and nothing
516
+ * else does (ADR 0005).
517
+ *
518
+ * @public
519
+ */
520
+ declare interface ImageExportJob {
521
+ readonly plan: ImagePlan;
522
+ readonly format: ImageExportFormat;
523
+ }
524
+
525
+ /**
526
+ * Options for exporting.
527
+ *
528
+ * @public
529
+ */
530
+ declare interface ImageExportOptions extends ImageProgressOptions {
531
+ /**
532
+ * The limits the output canvas is checked against before it's allocated:
533
+ * `maxImageDimension` and `maxImagePixels` (ADR 0004). The defaults of
534
+ * `imageLimits` when omitted.
535
+ */
536
+ readonly filePolicy?: ImageFilePolicy;
537
+ }
538
+
539
+ /**
540
+ * A resolved file policy for the image SDK. Violations throw
541
+ * {@link ImageError}.
542
+ *
543
+ * @public
544
+ */
545
+ declare type ImageFilePolicy = FilePolicy<ImageLimitDefinitions>;
546
+
547
+ /**
548
+ * A host's `filePolicy`: a new maximum, or `{ maximum, warning }`, for any of
549
+ * the image SDK's limits. `Infinity` disables a maximum, which removes a
550
+ * protection against hostile files, or disables a warning. Unknown limit
551
+ * names throw `TypeError` when the policy is resolved.
552
+ *
553
+ * @example
554
+ * ```ts
555
+ * // Large scans: raise the pixel and decoded sizes together.
556
+ * const filePolicy: ImageFilePolicyOverrides = {
557
+ * maxImagePixels: 100_000_000,
558
+ * maxDecodedSize: { maximum: 2e9, warning: 800e6 },
559
+ * };
560
+ * ```
561
+ *
562
+ * @public
563
+ */
564
+ declare type ImageFilePolicyOverrides = FilePolicyOverrides<ImageLimitDefinitions>;
565
+
566
+ /**
567
+ * A filter preset and its strength, an integer from 0 (no effect) to 100.
568
+ *
569
+ * @public
570
+ */
571
+ declare interface ImageFilter {
572
+ readonly preset: ImageFilterPreset;
573
+ readonly strength: number;
574
+ }
575
+
576
+ /**
577
+ * The Filters panel (docs/adr/0006, docs/adr/0007): the presets, "None"
578
+ * first, as one choice, each one undo step; and the chosen preset's
579
+ * strength, whose slider gesture is one undo step.
580
+ *
581
+ * @public
582
+ */
583
+ export declare function ImageFilterPanel(props: ImageFilterPanelProps): ReactNode;
584
+
585
+ /**
586
+ * Props of {@link ImageFilterPanel}.
587
+ *
588
+ * @public
589
+ */
590
+ export declare interface ImageFilterPanelProps {
591
+ readonly className?: string;
592
+ }
593
+
594
+ /**
595
+ * A filter preset's name.
596
+ *
597
+ * @public
598
+ */
599
+ declare type ImageFilterPreset = (typeof FILTER_PRESETS)[number];
600
+
601
+ /**
602
+ * The formats the probe recognises, by their signature bytes (ADR 0001).
603
+ *
604
+ * @public
605
+ */
606
+ declare type ImageFormat = "png" | "jpeg" | "webp" | "gif" | "avif" | "heif" | "bmp";
607
+
608
+ /**
609
+ * The components of the icons the editor's tools name, from ui's set
610
+ * (sdk-core ADR 0030). A host's `icons` prop overrides any of them.
611
+ *
612
+ * @public
613
+ */
614
+ export declare const imageIcons: Readonly<Record<string, IconComponent>>;
615
+
616
+ /**
617
+ * The Info panel (docs/adr/0007): what the editor knows of the open image,
618
+ * as a list of terms: its upright size, format, frames and file size, the
619
+ * kinds of metadata the file carries, and the fields kept on export. It
620
+ * shows only what the session already holds, and never a file name
621
+ * (sdk-core ADR 0012).
622
+ *
623
+ * @public
624
+ */
625
+ export declare function ImageInfoPanel(props: ImageInfoPanelProps): ReactNode;
626
+
627
+ /**
628
+ * Props of {@link ImageInfoPanel}.
629
+ *
630
+ * @public
631
+ */
632
+ export declare interface ImageInfoPanelProps {
633
+ readonly className?: string;
634
+ }
635
+
636
+ /**
637
+ * The metadata fields a user may keep on export (ADR 0005). Empty strings
638
+ * mean the field isn't written.
639
+ *
640
+ * @public
641
+ */
642
+ declare interface ImageKeepableMetadata {
643
+ readonly title: string;
644
+ readonly description: string;
645
+ readonly artist: string;
646
+ readonly copyright: string;
647
+ }
648
+
649
+ /**
650
+ * The type of {@link imageLimitDefinitions}.
651
+ *
652
+ * @public
653
+ */
654
+ declare type ImageLimitDefinitions = typeof imageLimitDefinitions;
655
+
656
+ /**
657
+ * The image SDK's limit definitions: sdk-core's core limits with image
658
+ * defaults, plus five for images (ADR 0004).
659
+ *
660
+ * | Limit | Code | Default maximum | Default warning |
661
+ * |---|---|---|---|
662
+ * | `maxFileSize` | `FILE_TOO_LARGE` | 100 MB | 50 MB |
663
+ * | `maxFiles` | `TOO_MANY_FILES` | 20 | none |
664
+ * | `maxDecodedSize` | `DECODED_SIZE_TOO_LARGE` | 1 GB | 400 MB |
665
+ * | `maxProcessingTime` | `PROCESSING_TIME_EXCEEDED` | 120 s | none |
666
+ * | `maxImagePixels` | `IMAGE_TOO_LARGE` | 50 megapixels | 24 megapixels |
667
+ * | `maxImageDimension` | `IMAGE_DIMENSION_TOO_LARGE` | 16,384 pixels | none |
668
+ * | `maxFrames` | `TOO_MANY_FRAMES` | 300 | 100 |
669
+ * | `maxSessionSize` | `SESSION_TOO_LARGE` | 1 GB | 500 MB |
670
+ * | `maxLayers` | `TOO_MANY_LAYERS` | 256 | none |
671
+ *
672
+ * Sizes are decimal: 1 MB is 1,000,000 bytes. Decoded sizes count 4 bytes
673
+ * per pixel. `maxImagePixels` is the same limit, with the same name, code
674
+ * and unit, as `pdf-sdk`'s. `maxImageDimension` is a side length, in pixels.
675
+ *
676
+ * @public
677
+ */
678
+ declare const imageLimitDefinitions: {
679
+ readonly maxDecodedSize: {
680
+ readonly default: 1000000000;
681
+ readonly warning: 400000000;
682
+ readonly code: "DECODED_SIZE_TOO_LARGE";
683
+ readonly unit: "bytes";
684
+ };
685
+ readonly maxImagePixels: {
686
+ readonly code: "IMAGE_TOO_LARGE";
687
+ readonly unit: "pixels";
688
+ readonly default: 50000000;
689
+ readonly warning: 24000000;
690
+ };
691
+ readonly maxImageDimension: {
692
+ readonly code: "IMAGE_DIMENSION_TOO_LARGE";
693
+ readonly unit: "pixels";
694
+ readonly default: 16384;
695
+ };
696
+ readonly maxFrames: {
697
+ readonly code: "TOO_MANY_FRAMES";
698
+ readonly unit: "count";
699
+ readonly default: 300;
700
+ readonly warning: 100;
701
+ };
702
+ readonly maxSessionSize: {
703
+ readonly code: "SESSION_TOO_LARGE";
704
+ readonly unit: "bytes";
705
+ readonly default: 1000000000;
706
+ readonly warning: 500000000;
707
+ };
708
+ readonly maxLayers: {
709
+ readonly code: "TOO_MANY_LAYERS";
710
+ readonly unit: "count";
711
+ readonly default: 256;
712
+ };
713
+ readonly maxFileSize: {
714
+ readonly code: "FILE_TOO_LARGE";
715
+ readonly unit: "bytes";
716
+ readonly default: 100000000;
717
+ readonly warning: 50000000;
718
+ };
719
+ readonly maxFiles: {
720
+ readonly code: "TOO_MANY_FILES";
721
+ readonly unit: "count";
722
+ readonly default: 20;
723
+ };
724
+ readonly maxProcessingTime: {
725
+ readonly code: "PROCESSING_TIME_EXCEEDED";
726
+ readonly unit: "milliseconds";
727
+ readonly default: 120000;
728
+ };
729
+ };
730
+
731
+ /**
732
+ * The names of the image SDK's limits.
733
+ *
734
+ * @public
735
+ */
736
+ declare type ImageLimitName = keyof ImageLimitDefinitions;
737
+
738
+ /**
739
+ * The type of {@link imageMessages}, for typing a host's overrides with
740
+ * `MessageOverrides<ImageMessageCatalogue>`.
741
+ *
742
+ * @public
743
+ */
744
+ declare type ImageMessageCatalogue = typeof imageMessages;
745
+
746
+ /**
747
+ * The image SDK's English message catalogue: sdk-core's and ui's messages, and text
748
+ * for every {@link ImageErrorCode} and every limit's warning. Pass it to
749
+ * `createMessages` from `@hussmartinez/sdk-core`, with the host's locale and
750
+ * overrides. It also has the editor's text: its labels, states,
751
+ * announcements and tool names.
752
+ *
753
+ * Error text is looked up by code, with the error's `details` as
754
+ * parameters, and never taken from `error.message` (ADR 0019).
755
+ *
756
+ * @example
757
+ * ```ts
758
+ * const messages = createMessages(imageMessages, { locale: "en", overrides: props.messages });
759
+ * messages.error(error); // "This animation has 400 frames, which is over the 300-frame limit."
760
+ * messages.t("warnings.maxSessionSize", { actual: 600e6 });
761
+ * ```
762
+ *
763
+ * @public
764
+ */
765
+ declare const imageMessages: {
766
+ readonly "errors.INVALID_IMAGE": "This file isn't a valid image, or it's too damaged to open.";
767
+ readonly "errors.UNSUPPORTED_FORMAT": "This image format isn't supported. Try converting the file to PNG or JPEG, then open it again.";
768
+ readonly "errors.DECODE_FAILED": "This browser can't open this kind of image. Try another browser, or convert the file to PNG or JPEG.";
769
+ readonly "errors.INVALID_COMMAND": "This edit couldn't be made. Please try again.";
770
+ readonly "errors.INVALID_DOCUMENT": "This project is damaged, or it isn't an image project.";
771
+ readonly "errors.IMAGE_TOO_LARGE": "This image has more pixels than the editor can handle. Try a smaller version of it.";
772
+ readonly "errors.IMAGE_DIMENSION_TOO_LARGE": "This image is {actual, number} pixels across, which is over the {maximum, number}-pixel limit.";
773
+ readonly "errors.TOO_MANY_FRAMES": {
774
+ readonly $plural: "maximum";
775
+ } & {
776
+ readonly one: "This animation has {actual, number} frames, which is over the {maximum}-frame limit.";
777
+ readonly other: "This animation has {actual, number} frames, which is over the {maximum, number}-frame limit.";
778
+ };
779
+ readonly "errors.SESSION_TOO_LARGE": "The open images would use {actual, fileSize} of memory, which is over the {maximum, fileSize} limit. Close an image, or clear the undo history, and try again.";
780
+ readonly "errors.TOO_MANY_LAYERS": {
781
+ readonly $plural: "maximum";
782
+ } & {
783
+ readonly one: "An image can have {maximum} layer. Merge or delete layers, and try again.";
784
+ readonly other: "An image can have up to {maximum, number} layers. Merge or delete layers, and try again.";
785
+ };
786
+ readonly "warnings.maxImagePixels": "This image is large, and may be slow to edit on some devices.";
787
+ readonly "warnings.maxImageDimension": "This image is very wide or tall, and may be slow to edit.";
788
+ readonly "warnings.maxFrames": {
789
+ readonly $plural: "actual";
790
+ } & {
791
+ readonly one: "This animation has {actual} frame.";
792
+ readonly other: "This animation has {actual, number} frames, and may be slow to edit and export.";
793
+ };
794
+ readonly "warnings.maxSessionSize": "The open images use {actual, fileSize} of memory. Clearing the undo history frees memory.";
795
+ readonly "warnings.maxLayers": {
796
+ readonly $plural: "actual";
797
+ } & {
798
+ readonly one: "This image has {actual} layer.";
799
+ readonly other: "This image has {actual, number} layers, and may be slow to edit and export.";
800
+ };
801
+ readonly "editor.label": "Image editor";
802
+ readonly "editor.preview": "Edited image preview, {width, number} × {height, number}";
803
+ readonly "editor.empty": "Open an image to start editing. It stays on this device.";
804
+ readonly "editor.choose": "Choose an image";
805
+ readonly "editor.dropHint": "or drop it here";
806
+ readonly "editor.opening": "Opening the image…";
807
+ readonly "editor.cancel": "Cancel";
808
+ readonly "editor.opened": "Image opened, {width, number} × {height, number}.";
809
+ readonly "editor.undid": "Undid {action}.";
810
+ readonly "editor.redid": "Redid {action}.";
811
+ readonly "actions.image.setCrop": "crop";
812
+ readonly "actions.image.setOrientation": "rotate or flip";
813
+ readonly "actions.image.setOutput": "size";
814
+ readonly "actions.image.setMetadata": "metadata";
815
+ readonly "actions.image.setDevelop": "adjustment";
816
+ readonly "actions.image.setFilter": "filter";
817
+ readonly "toolbar.label": "Image tools";
818
+ readonly "toolbar.groups.file": "File";
819
+ readonly "toolbar.groups.history": "History";
820
+ readonly "toolbar.groups.orientation": "Rotate";
821
+ readonly "toolbar.groups.zoom": "Zoom";
822
+ readonly "toolbar.groups.other": "More tools";
823
+ readonly "tools.open": "Open image";
824
+ readonly "tools.undo": "Undo";
825
+ readonly "tools.redo": "Redo";
826
+ readonly "tools.rotate-left": "Rotate left";
827
+ readonly "tools.rotate-right": "Rotate right";
828
+ readonly "tools.zoom-in": "Zoom in";
829
+ readonly "tools.zoom-out": "Zoom out";
830
+ readonly "tools.zoom-fit": "Fit to the stage";
831
+ readonly "tools.crop": "Crop";
832
+ readonly "tools.flip-horizontal": "Flip horizontally";
833
+ readonly "tools.flip-vertical": "Flip vertically";
834
+ readonly "toolbar.groups.crop": "Crop";
835
+ readonly "crop.frame": "Crop area";
836
+ readonly "crop.frameDescription": "{width, number} × {height, number} pixels, from {x, number}, {y, number}. Arrow keys move it; with Alt, they resize it; Enter applies and Escape cancels.";
837
+ readonly "crop.size": "{width, number} × {height, number}, from {x, number}, {y, number}";
838
+ readonly "crop.panel": "Crop";
839
+ readonly "crop.x": "Left";
840
+ readonly "crop.y": "Top";
841
+ readonly "crop.width": "Width";
842
+ readonly "crop.height": "Height";
843
+ readonly "crop.aspect": "Aspect ratio";
844
+ readonly "crop.aspects.free": "Free";
845
+ readonly "crop.aspects.original": "Original";
846
+ readonly "crop.aspects.ratio": "{width}:{height}";
847
+ readonly "crop.apply": "Apply crop";
848
+ readonly "crop.cancel": "Cancel";
849
+ readonly "crop.reset": "Whole image";
850
+ readonly "crop.applied": "Cropped to {width, number} × {height, number}.";
851
+ readonly "inspector.label": "Panels";
852
+ readonly "inspector.adjust": "Adjust";
853
+ readonly "inspector.filters": "Filters";
854
+ readonly "inspector.info": "Info";
855
+ readonly "notices.label": "Notices";
856
+ readonly "notices.dismiss": "Dismiss";
857
+ readonly "notices.colourProfile": "This image has a colour profile. Colours outside sRGB will be clipped in the exported file.";
858
+ readonly "info.panel": "Image info";
859
+ readonly "info.size": "Size";
860
+ readonly "info.sizeValue": "{width, number} × {height, number} pixels";
861
+ readonly "info.format": "Format";
862
+ readonly "info.formats.png": "PNG";
863
+ readonly "info.formats.jpeg": "JPEG";
864
+ readonly "info.formats.webp": "WebP";
865
+ readonly "info.formats.gif": "GIF";
866
+ readonly "info.formats.avif": "AVIF";
867
+ readonly "info.formats.heif": "HEIF";
868
+ readonly "info.formats.bmp": "BMP";
869
+ readonly "info.frames": "Frames";
870
+ readonly "info.fileSize": "File size";
871
+ readonly "info.fileSizeValue": "{size, fileSize}";
872
+ readonly "info.metadata": "Metadata in the file";
873
+ readonly "info.metadataNone": "None";
874
+ readonly "info.kept": "Kept on export";
875
+ readonly "info.keptNone": "Nothing";
876
+ readonly "develop.panel": "Adjust";
877
+ readonly "develop.temperature": "Temperature";
878
+ readonly "develop.tint": "Tint";
879
+ readonly "develop.exposure": "Exposure";
880
+ readonly "develop.highlights": "Highlights";
881
+ readonly "develop.shadows": "Shadows";
882
+ readonly "develop.contrast": "Contrast";
883
+ readonly "develop.saturation": "Saturation";
884
+ readonly "develop.vibrance": "Vibrance";
885
+ readonly "develop.reset": "Reset {name}";
886
+ readonly "develop.resetAll": "Reset all";
887
+ readonly "develop.wasReset": "All adjustments reset.";
888
+ readonly "filters.panel": "Filters";
889
+ readonly "filters.label": "Filter";
890
+ readonly "filters.none": "None";
891
+ readonly "filters.vivid": "Vivid";
892
+ readonly "filters.warm": "Warm";
893
+ readonly "filters.cool": "Cool";
894
+ readonly "filters.fade": "Fade";
895
+ readonly "filters.mono": "Mono";
896
+ readonly "filters.noir": "Noir";
897
+ readonly "filters.sepia": "Sepia";
898
+ readonly "filters.strength": "Strength";
899
+ readonly "toolbar.groups.export": "Export";
900
+ readonly "tools.export": "Export";
901
+ readonly "export.title": "Export image";
902
+ readonly "export.description": "The file is made on this device, and nothing is uploaded.";
903
+ readonly "export.format": "Format";
904
+ readonly "export.formats.png": "PNG";
905
+ readonly "export.formats.jpeg": "JPEG";
906
+ readonly "export.formats.webp": "WebP";
907
+ readonly "export.quality": "Quality";
908
+ readonly "export.qualityValue": "{quality, number}%";
909
+ readonly "export.size": "Size";
910
+ readonly "export.sizes.scale": "Scale";
911
+ readonly "export.sizes.fit": "Fit in a box";
912
+ readonly "export.scale": "Scale, in percent";
913
+ readonly "export.fitWidth": "Largest width";
914
+ readonly "export.fitHeight": "Largest height";
915
+ readonly "export.fields": "Details to include";
916
+ readonly "export.fieldsHint": "Only what you fill in is written to the file.";
917
+ readonly "export.field.title": "Title";
918
+ readonly "export.field.description": "Description";
919
+ readonly "export.field.artist": "Artist";
920
+ readonly "export.field.copyright": "Copyright";
921
+ readonly "export.summary": "Summary";
922
+ readonly "export.output": "{width, number} × {height, number} pixels, {format}";
923
+ readonly "export.removed": "Removed from the file";
924
+ readonly "export.removedNone": "The image had no other details to remove.";
925
+ readonly "export.kind.location": "Location";
926
+ readonly "export.kind.camera": "Camera details";
927
+ readonly "export.kind.timestamps": "Dates and times";
928
+ readonly "export.kind.thumbnail": "Embedded thumbnail";
929
+ readonly "export.kind.colourProfile": "Colour profile: colours outside sRGB are clipped";
930
+ readonly "export.kind.other": "Other metadata";
931
+ readonly "export.kept": "Kept in the file";
932
+ readonly "export.confirm": "Export";
933
+ readonly "export.cancel": "Cancel";
934
+ readonly "export.progress": "Exporting the image";
935
+ readonly "export.stop": "Stop exporting";
936
+ readonly "export.cancelled": "Export stopped.";
937
+ readonly "export.done": "Exported a {format} of {size, fileSize}.";
938
+ readonly "export.ready": "{width, number} × {height, number} pixels, {format}, {size, fileSize}";
939
+ readonly "export.download": "Download";
940
+ readonly "export.close": "Done";
941
+ readonly "dialog.close": "Close";
942
+ readonly "fileDropZone.choose": "Choose a file";
943
+ readonly "fileDropZone.chooseMultiple": "Choose files";
944
+ readonly "fileDropZone.hint": "or drop it here";
945
+ readonly "fileDropZone.hintMultiple": "or drop them here";
946
+ readonly "progress.label": "Progress";
947
+ readonly "spinner.label": "Loading";
948
+ readonly "errors.INVALID_THEME_TOKEN": "The theme setting {token} has a value that can't be used.";
949
+ readonly "errors.INVALID_THEME_SELECTOR": "The theme can't be applied to the selector {selector}.";
950
+ readonly "errors.UNKNOWN": "Something went wrong. Please try again.";
951
+ readonly "errors.ABORTED": "The operation was cancelled.";
952
+ readonly "errors.TIMEOUT": "The operation took too long and was stopped.";
953
+ readonly "errors.WORKER_START_FAILED": "The file processor couldn't start. Reload the page and try again.";
954
+ readonly "errors.WORKER_PROTOCOL_MISMATCH": "The file processor is out of date. Reload the page to update it.";
955
+ readonly "errors.WORKER_CRASHED": "The file processor stopped unexpectedly. Please try again.";
956
+ readonly "errors.WORKER_TERMINATED": "The operation was stopped before it finished. Please try again.";
957
+ readonly "errors.WORKER_METHOD_NOT_FOUND": "This operation isn't available. Reload the page and try again.";
958
+ readonly "errors.WORKER_DATA_NOT_CLONEABLE": "Something went wrong while processing the file. Please try again.";
959
+ readonly "errors.UNSUPPORTED_ENVIRONMENT": "This browser doesn't support a feature this tool needs. Update your browser, or try another one.";
960
+ readonly "errors.FILE_TOO_LARGE": "This file is {actual, fileSize}, which is over the {maximum, fileSize} limit.";
961
+ readonly "errors.TOO_MANY_FILES": {
962
+ readonly $plural: "maximum";
963
+ } & {
964
+ readonly one: "You can add {maximum} file at a time.";
965
+ readonly other: "You can add up to {maximum} files at a time.";
966
+ };
967
+ readonly "errors.DECODED_SIZE_TOO_LARGE": "This file expands to more than {maximum, fileSize} when opened, which is over the limit.";
968
+ readonly "errors.PROCESSING_TIME_EXCEEDED": "Processing this file took too long and was stopped.";
969
+ readonly "warnings.maxFileSize": "This file is {actual, fileSize}. Large files may be slow to process.";
970
+ readonly "warnings.maxFiles": "Adding {actual} files at once may be slow.";
971
+ readonly "warnings.maxDecodedSize": "This file is very large once opened and may be slow to process.";
972
+ readonly "warnings.maxProcessingTime": "This is taking longer than usual.";
973
+ readonly "keys.control": "Ctrl";
974
+ readonly "keys.alt": "Alt";
975
+ readonly "keys.shift": "Shift";
976
+ readonly "keys.meta": "Meta";
977
+ readonly "keys.apple.control": "\u2303";
978
+ readonly "keys.apple.alt": "\u2325";
979
+ readonly "keys.apple.shift": "\u21E7";
980
+ readonly "keys.apple.meta": "\u2318";
981
+ readonly "keys.space": "Space";
982
+ readonly "keys.enter": "Enter";
983
+ readonly "keys.escape": "Esc";
984
+ readonly "keys.tab": "Tab";
985
+ readonly "keys.delete": "Delete";
986
+ readonly "keys.backspace": "Backspace";
987
+ readonly "keys.arrowUp": "\u2191";
988
+ readonly "keys.arrowDown": "\u2193";
989
+ readonly "keys.arrowLeft": "\u2190";
990
+ readonly "keys.arrowRight": "\u2192";
991
+ readonly "keys.home": "Home";
992
+ readonly "keys.end": "End";
993
+ readonly "keys.pageUp": "Page Up";
994
+ readonly "keys.pageDown": "Page Down";
995
+ };
996
+
997
+ /**
998
+ * Which kinds of metadata a file carries, as presence flags, never values,
999
+ * so the editor can say what an export removes (ADR 0005).
1000
+ *
1001
+ * @public
1002
+ */
1003
+ declare interface ImageMetadataPresence {
1004
+ readonly location: boolean;
1005
+ readonly camera: boolean;
1006
+ readonly timestamps: boolean;
1007
+ readonly thumbnail: boolean;
1008
+ readonly colourProfile: boolean;
1009
+ /** Any other field, such as maker notes or unknown tags. */
1010
+ readonly other: boolean;
1011
+ }
1012
+
1013
+ /**
1014
+ * The plan's own rotation and flips, applied after the crop. They're user
1015
+ * edits, separate from the file's EXIF orientation, which decoding has
1016
+ * already applied (ADR 0005).
1017
+ *
1018
+ * @public
1019
+ */
1020
+ declare interface ImageOrientation_2 {
1021
+ readonly rotate: ImageRotation;
1022
+ /** Mirrors left to right, after the rotation. */
1023
+ readonly flipX: boolean;
1024
+ /** Mirrors top to bottom, after the rotation. */
1025
+ readonly flipY: boolean;
1026
+ }
1027
+
1028
+ /**
1029
+ * The export's size: the composition scaled by a factor up to 1, or fitted
1030
+ * inside a box without enlarging it.
1031
+ *
1032
+ * @public
1033
+ */
1034
+ declare type ImageOutput = {
1035
+ readonly kind: "scale";
1036
+ readonly scale: number;
1037
+ } | {
1038
+ readonly kind: "fit";
1039
+ readonly width: number;
1040
+ readonly height: number;
1041
+ };
1042
+
1043
+ /**
1044
+ * The session's document: a description of the edits over an immutable
1045
+ * source, rendered to pixels only for display and export (ADR 0003).
1046
+ *
1047
+ * @public
1048
+ */
1049
+ declare interface ImagePlan {
1050
+ readonly base: ImageBase;
1051
+ readonly output: ImageOutput;
1052
+ /** The fields the user chose to keep on export. Never a location (ADR 0005). */
1053
+ readonly metadata: ImageKeepableMetadata;
1054
+ }
1055
+
1056
+ /**
1057
+ * What the probe learned about a file before anything decodes it (ADR 0001,
1058
+ * ADR 0004, ADR 0005). Limits are checked against it.
1059
+ *
1060
+ * @public
1061
+ */
1062
+ declare interface ImageProbe {
1063
+ readonly format: ImageFormat;
1064
+ /** The size of the stored pixels, before orientation. */
1065
+ readonly stored: ImageSize;
1066
+ /** The upright size, after orientation: the size the decoder must return. */
1067
+ readonly oriented: ImageSize;
1068
+ /** The EXIF or `irot`/`imir` orientation; 1 when there's none. */
1069
+ readonly orientation: ExifOrientation;
1070
+ /** 1 for a still image, otherwise the number of frames the probe walked. */
1071
+ readonly frames: number;
1072
+ readonly hasAlpha: boolean;
1073
+ /**
1074
+ * The most pixels the decoder can produce for the file: frames × the
1075
+ * oriented size for most formats, and for AVIF and HEIF the sum over every
1076
+ * item decoded with the primary, such as grid tiles and auxiliary planes.
1077
+ * A file with an orientation counts one more oriented frame, which the
1078
+ * worker needs when it applies the orientation itself (ADR 0005).
1079
+ * Never a count declared by one header (ADR 0001).
1080
+ */
1081
+ readonly decodedPixelBound: number;
1082
+ readonly metadata: ImageMetadataPresence;
1083
+ /** The keepable fields the file carries, length-limited, shown only as text. */
1084
+ readonly keepable: ImageKeepableMetadata;
1085
+ }
1086
+
1087
+ /**
1088
+ * The port for exporting: render a plan at its output size and encode it
1089
+ * (ADR 0001, ADR 0003, ADR 0008). It renders sources registered with its
1090
+ * engine, so the SDK's own adapter shares the engine's render worker; hosts
1091
+ * can pass their own to the editor's `processor` prop, and every
1092
+ * implementation must pass the processor's contract tests.
1093
+ *
1094
+ * Failures reject with `ImageError` for cancellation, worker failures and
1095
+ * formats the browser can't encode, and `TypeError` for a plan whose source
1096
+ * isn't registered.
1097
+ *
1098
+ * @public
1099
+ */
1100
+ declare interface ImageProcessor {
1101
+ /**
1102
+ * Renders and encodes a plan, and returns the file. It writes only the
1103
+ * plan's kept metadata, and never a location, a camera's details,
1104
+ * timestamps, a thumbnail or an orientation. An output over `filePolicy`'s
1105
+ * `maxImageDimension` or `maxImagePixels` rejects with that limit's code
1106
+ * before anything is drawn.
1107
+ */
1108
+ export(job: ImageExportJob, options?: ImageExportOptions): Promise<Blob>;
1109
+ /** Releases the processor. Pending calls reject, and later calls throw. */
1110
+ destroy(): Promise<void>;
1111
+ }
1112
+
1113
+ /**
1114
+ * Options for long calls, which report how far they've got.
1115
+ *
1116
+ * @public
1117
+ */
1118
+ declare interface ImageProgressOptions extends ImageCallOptions {
1119
+ /**
1120
+ * Called with the fraction done, from 0 to 1. It only moves forward, and
1121
+ * it's called with 1 before the call resolves.
1122
+ */
1123
+ readonly onProgress?: (fraction: number) => void;
1124
+ }
1125
+
1126
+ /**
1127
+ * Options for registering a source.
1128
+ *
1129
+ * @public
1130
+ */
1131
+ declare interface ImageRegisterOptions extends ImageProgressOptions {
1132
+ /**
1133
+ * The limits checked against the engine's own probe of the file before
1134
+ * anything decodes it: `maxFileSize`, `maxImageDimension`,
1135
+ * `maxImagePixels`, `maxFrames` and `maxDecodedSize` (ADR 0004). The
1136
+ * defaults of `imageLimits` when omitted. The session checks the same
1137
+ * policy first, so this is defence in depth for hosts that use the engine
1138
+ * directly.
1139
+ */
1140
+ readonly filePolicy?: ImageFilePolicy;
1141
+ }
1142
+
1143
+ /**
1144
+ * A quarter-turn rotation, clockwise, in degrees.
1145
+ *
1146
+ * @public
1147
+ */
1148
+ declare type ImageRotation = 0 | 90 | 180 | 270;
1149
+
1150
+ /**
1151
+ * An image editing session (ADR 0003, ADR 0008): one document, its plan
1152
+ * over the source it opened, edited by commands with undo and redo, and
1153
+ * exported through its processor.
1154
+ *
1155
+ * @public
1156
+ */
1157
+ declare interface ImageSession {
1158
+ getSnapshot(): ImageSessionSnapshot;
1159
+ /** Calls the listener after every change. Returns a function that unsubscribes. */
1160
+ subscribe(listener: () => void): () => void;
1161
+ /**
1162
+ * Probes, checks and decodes a file, and makes it the document, with a new
1163
+ * plan and an empty history; the previous source is released (ADR 0003,
1164
+ * ADR 0004). The newest open wins: an open that finishes after a later one
1165
+ * started applies nothing, releases its source and rejects with
1166
+ * `ABORTED`. A failed or cancelled open leaves the current document as it
1167
+ * was.
1168
+ */
1169
+ open(file: Blob, options?: {
1170
+ readonly signal?: AbortSignal;
1171
+ }): Promise<ImageSessionSource>;
1172
+ /**
1173
+ * Applies commands as one undoable step. They're checked by the reducer,
1174
+ * then the output against `maxImageDimension` and `maxImagePixels`; a
1175
+ * failure throws `ImageError` and changes nothing.
1176
+ */
1177
+ execute(commands: ImageCommand | readonly ImageCommand[]): void;
1178
+ /**
1179
+ * Makes the document's plan equal to `plan`, as one undoable step of the
1180
+ * commands that reach it, checked as `execute` checks them (ADR 0003). A
1181
+ * plan equal to the current one changes nothing. A plan over another
1182
+ * source is `INVALID_COMMAND`. For editors whose host holds the plan.
1183
+ */
1184
+ applyPlan(plan: ImagePlan): void;
1185
+ /**
1186
+ * Runs `fn`, and records every step it executes as one undoable step, for
1187
+ * a gesture such as dragging a crop handle (ADR 0003). `fn` must be
1188
+ * synchronous.
1189
+ */
1190
+ group<T>(fn: () => T): T;
1191
+ /** Undoes the last step. Returns whether there was one. */
1192
+ undo(): boolean;
1193
+ /** Redoes the last undone step. Returns whether there was one. */
1194
+ redo(): boolean;
1195
+ /**
1196
+ * Renders and encodes the document (ADR 0003). An export that finishes
1197
+ * after another file was opened rejects with `ABORTED`.
1198
+ */
1199
+ export(format: ImageExportFormat, options?: {
1200
+ readonly signal?: AbortSignal;
1201
+ readonly onProgress?: (fraction: number) => void;
1202
+ }): Promise<ImageSessionExport>;
1203
+ /** Releases the source the session holds. Later calls throw. */
1204
+ destroy(): Promise<void>;
1205
+ }
1206
+
1207
+ /**
1208
+ * An anonymous usage event for the host's `onEvent` (ADR 0003). It never
1209
+ * carries file names, pixels, text the user typed or metadata values.
1210
+ *
1211
+ * @public
1212
+ */
1213
+ declare interface ImageSessionEvent {
1214
+ readonly type: "open" | "execute" | "undo" | "redo" | "export";
1215
+ readonly outcome: "done" | "failed" | "cancelled";
1216
+ /** The types of the commands applied or undone. */
1217
+ readonly commands: readonly ImageCommand["type"][];
1218
+ }
1219
+
1220
+ /**
1221
+ * What an export produced, and what the summary before a download shows
1222
+ * (ADR 0003, ADR 0005).
1223
+ *
1224
+ * @public
1225
+ */
1226
+ declare interface ImageSessionExport {
1227
+ readonly blob: Blob;
1228
+ readonly width: number;
1229
+ readonly height: number;
1230
+ /**
1231
+ * The kinds of metadata the source carried that the file doesn't: every
1232
+ * kind, since exports keep only the fields the user chose, which are
1233
+ * never these. Empty when the source carried none.
1234
+ */
1235
+ readonly removed: readonly (keyof ImageMetadataPresence)[];
1236
+ /** The fields the user kept, which the file carries. */
1237
+ readonly kept: readonly (keyof ImageKeepableMetadata)[];
1238
+ }
1239
+
1240
+ /**
1241
+ * The session's state, for `useSyncExternalStore`: a new object on every
1242
+ * change (ADR 0003).
1243
+ *
1244
+ * @public
1245
+ */
1246
+ declare interface ImageSessionSnapshot {
1247
+ /** `empty` until a file opens; `opening` while the first one is; then `ready`. */
1248
+ readonly status: "empty" | "opening" | "ready";
1249
+ /** The document, or `null` before a file is open. */
1250
+ readonly plan: ImagePlan | null;
1251
+ /** The document's source, or `null` before a file is open. */
1252
+ readonly source: ImageSessionSource | null;
1253
+ readonly canUndo: boolean;
1254
+ readonly canRedo: boolean;
1255
+ /** Whether a file is being opened. The current document stays until it's ready. */
1256
+ readonly opening: boolean;
1257
+ /** Whether an export is in progress. */
1258
+ readonly exporting: boolean;
1259
+ /** The limits the last open, edit or export came near: at or above their warnings. */
1260
+ readonly warnings: readonly ImageLimitName[];
1261
+ /** The last failure, until the next successful open, edit or export. */
1262
+ readonly error: ImageError | null;
1263
+ }
1264
+
1265
+ /**
1266
+ * The document's source, as the editor shows it: its size and format, and
1267
+ * what metadata the file carried, which the export summary reports as
1268
+ * removed unless the user kept it (ADR 0005).
1269
+ *
1270
+ * @public
1271
+ */
1272
+ declare interface ImageSessionSource extends ImageSourceInfo {
1273
+ /** The file's size in bytes, as it was opened. Never its name. */
1274
+ readonly fileSize: number;
1275
+ /** Which kinds of metadata the file carried, never their values. */
1276
+ readonly metadata: ImageMetadataPresence;
1277
+ /** The fields the user may choose to keep, as the file had them. */
1278
+ readonly keepable: ImageKeepableMetadata;
1279
+ }
1280
+
1281
+ /**
1282
+ * A width and a height, in whole pixels.
1283
+ *
1284
+ * @public
1285
+ */
1286
+ declare interface ImageSize {
1287
+ readonly width: number;
1288
+ readonly height: number;
1289
+ }
1290
+
1291
+ /**
1292
+ * A source the session holds, without its pixels: what the snapshot shows
1293
+ * (ADR 0003). Its size is the oriented size.
1294
+ *
1295
+ * @public
1296
+ */
1297
+ declare interface ImageSourceInfo {
1298
+ readonly id: string;
1299
+ readonly format: ImageFormat;
1300
+ readonly width: number;
1301
+ readonly height: number;
1302
+ readonly frames: number;
1303
+ readonly hasAlpha: boolean;
1304
+ /** The bytes the decoded source takes in the worker: frames × width × height × 4. */
1305
+ readonly decodedBytes: number;
1306
+ }
1307
+
1308
+ /**
1309
+ * The editor's stage (docs/adr/0007): the preview canvas, drawn by the
1310
+ * engine's render worker, with the designed states around it. With no image
1311
+ * it's a drop zone with a button to choose one; while an image opens, a
1312
+ * spinner with a cancel button over the current one; after a failure, the
1313
+ * catalogue's text for it.
1314
+ *
1315
+ * The canvas is `role="img"`, named with the image's size, and isn't in the
1316
+ * tab order. It's created in an effect, never rendered by React: a canvas
1317
+ * transferred to a worker can't be transferred again, and StrictMode mounts
1318
+ * effects twice.
1319
+ *
1320
+ * @public
1321
+ */
1322
+ export declare function ImageStage(props: ImageStageProps): ReactNode;
1323
+
1324
+ /**
1325
+ * Props of {@link ImageStage}.
1326
+ *
1327
+ * @public
1328
+ */
1329
+ export declare interface ImageStageProps {
1330
+ /** Extra classes on the stage. */
1331
+ readonly className?: string;
1332
+ }
1333
+
1334
+ /**
1335
+ * A small rendering of a source for lists and frame strips. An `ImageBitmap`
1336
+ * is one; tests can supply their own. Close it when it's no longer shown.
1337
+ *
1338
+ * @public
1339
+ */
1340
+ declare interface ImageThumbnail {
1341
+ readonly width: number;
1342
+ readonly height: number;
1343
+ close(): void;
1344
+ }
1345
+
1346
+ /**
1347
+ * One of the editor's tools (docs/adr/0007, sdk-core ADR 0009).
1348
+ *
1349
+ * @public
1350
+ */
1351
+ export declare type ImageTool = Tool<ImageToolState, ImageToolContext, undefined>;
1352
+
1353
+ /**
1354
+ * The editor's toolbar (docs/adr/0007): ui's Toolbar, one group per toolbar
1355
+ * group of the registry, one button per tool, disabled when it can't run,
1356
+ * with the tool's shortcuts as `aria-keyshortcuts`.
1357
+ *
1358
+ * @public
1359
+ */
1360
+ export declare function ImageToolbar(props: ImageToolbarProps): ReactNode;
1361
+
1362
+ /**
1363
+ * Props of {@link ImageToolbar}.
1364
+ *
1365
+ * @public
1366
+ */
1367
+ export declare interface ImageToolbarProps {
1368
+ /** The editor's tools, from `createToolRegistry`. */
1369
+ readonly registry: ToolRegistry<ImageTool>;
1370
+ /** The editor's shortcuts, for each button's `aria-keyshortcuts`. */
1371
+ readonly shortcuts?: ShortcutRegistry;
1372
+ /** What the tools run against. */
1373
+ readonly context: ImageToolContext;
1374
+ /** Icon components by name, over the SDK's own. */
1375
+ readonly icons: Readonly<Record<string, IconComponent>>;
1376
+ readonly className?: string;
1377
+ }
1378
+
1379
+ /**
1380
+ * What a tool runs against.
1381
+ *
1382
+ * @public
1383
+ */
1384
+ export declare interface ImageToolContext {
1385
+ readonly session: ImageSession;
1386
+ readonly view: Store<{
1387
+ readonly zoom: number;
1388
+ readonly pan: {
1389
+ readonly x: number;
1390
+ readonly y: number;
1391
+ };
1392
+ }>;
1393
+ /** The editor's own state, which tools such as crop take over. */
1394
+ readonly editor: Store<ImageEditorState>;
1395
+ /** Asks the user for an image, as the open tool does. */
1396
+ readonly chooseFile: () => void;
1397
+ }
1398
+
1399
+ /**
1400
+ * Every tool the editor knows, in their default order (docs/adr/0007).
1401
+ *
1402
+ * @public
1403
+ */
1404
+ export declare const imageTools: readonly ImageTool[];
1405
+
1406
+ /**
1407
+ * What a tool reads to decide whether it's available, enabled or active.
1408
+ *
1409
+ * @public
1410
+ */
1411
+ export declare interface ImageToolState {
1412
+ readonly snapshot: ImageSessionSnapshot;
1413
+ readonly editor: ImageEditorState;
1414
+ }
1415
+
1416
+ /**
1417
+ * The stage's zoom and pan: view state, outside the session and its history
1418
+ * (ADR 0003, docs/adr/0007). Zoom 1 fits the image to the stage.
1419
+ *
1420
+ * @public
1421
+ */
1422
+ export declare interface ImageViewState {
1423
+ readonly zoom: number;
1424
+ readonly pan: {
1425
+ readonly x: number;
1426
+ readonly y: number;
1427
+ };
1428
+ }
1429
+
1430
+ /**
1431
+ * Sets or removes the base's crop, in whole pixels of the oriented source.
1432
+ *
1433
+ * @public
1434
+ */
1435
+ declare interface SetCropCommand {
1436
+ readonly type: "image.setCrop";
1437
+ readonly crop: ImageCrop | null;
1438
+ }
1439
+
1440
+ /**
1441
+ * Sets some of the base's develop adjustments; the others keep their values
1442
+ * (ADR 0006).
1443
+ *
1444
+ * @public
1445
+ */
1446
+ declare interface SetDevelopCommand {
1447
+ readonly type: "image.setDevelop";
1448
+ readonly values: Partial<ImageDevelop>;
1449
+ }
1450
+
1451
+ /**
1452
+ * Sets the base's filter preset and strength, or removes it with `null`.
1453
+ *
1454
+ * @public
1455
+ */
1456
+ declare interface SetFilterCommand {
1457
+ readonly type: "image.setFilter";
1458
+ readonly filter: ImageFilter | null;
1459
+ }
1460
+
1461
+ /**
1462
+ * Sets one metadata field to keep on export. An empty value keeps nothing.
1463
+ *
1464
+ * @public
1465
+ */
1466
+ declare interface SetMetadataCommand {
1467
+ readonly type: "image.setMetadata";
1468
+ readonly field: keyof ImageKeepableMetadata;
1469
+ readonly value: string;
1470
+ }
1471
+
1472
+ /**
1473
+ * Sets the base's rotation and flips.
1474
+ *
1475
+ * @public
1476
+ */
1477
+ declare interface SetOrientationCommand {
1478
+ readonly type: "image.setOrientation";
1479
+ readonly orientation: ImageOrientation_2;
1480
+ }
1481
+
1482
+ /**
1483
+ * Sets the export's size.
1484
+ *
1485
+ * @public
1486
+ */
1487
+ declare interface SetOutputCommand {
1488
+ readonly type: "image.setOutput";
1489
+ readonly output: ImageOutput;
1490
+ }
1491
+
1492
+ /**
1493
+ * The session's snapshot, re-rendering whenever it changes, through
1494
+ * `useSyncExternalStore`, so it's safe with concurrent and server rendering.
1495
+ *
1496
+ * @public
1497
+ */
1498
+ export declare function useImageDocument(): ImageSessionSnapshot;
1499
+
1500
+ /**
1501
+ * The editor's own state: the active tool, a crop in progress, and a
1502
+ * gesture's transient plan (docs/adr/0007).
1503
+ *
1504
+ * @public
1505
+ */
1506
+ export declare function useImageEditorState(): readonly [ImageEditorState, Store<ImageEditorState>];
1507
+
1508
+ /**
1509
+ * The SDK's text for the provider's locale and overrides (ADR 0019).
1510
+ *
1511
+ * @public
1512
+ */
1513
+ export declare function useImageMessages(): Messages<ImageMessageCatalogue>;
1514
+
1515
+ /**
1516
+ * The session of the nearest `ImageEditorProvider`, to open images, run
1517
+ * commands, undo and export.
1518
+ *
1519
+ * @public
1520
+ */
1521
+ export declare function useImageSession(): ImageSession;
1522
+
1523
+ /**
1524
+ * The stage's zoom and pan, and the store to change them (docs/adr/0007).
1525
+ *
1526
+ * @public
1527
+ */
1528
+ export declare function useImageView(): readonly [ImageViewState, Store<ImageViewState>];
1529
+
1530
+ export { }