@hussmartinez/image-sdk 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/element.d.ts CHANGED
@@ -19,6 +19,19 @@ import type { MessageOverrides } from '@hussmartinez/sdk-core';
19
19
  import { SdkCoreErrorCode } from '@hussmartinez/sdk-core';
20
20
  import { SdkError } from '@hussmartinez/sdk-core';
21
21
 
22
+ /**
23
+ * Appends strokes to a drawing layer (ADR 0009, docs/adr/0014): one stroke
24
+ * for each gesture, however many runs it has.
25
+ *
26
+ * @public
27
+ */
28
+ declare interface AddStrokesCommand {
29
+ readonly type: "image.addStrokes";
30
+ /** The drawing's key. */
31
+ readonly key: string;
32
+ readonly strokes: readonly ImageStroke[];
33
+ }
34
+
22
35
  /**
23
36
  * Registers `<hm-image-editor>`, or the tag you name, and returns its class
24
37
  * (docs/adr/0007, sdk-core ADR 0040): the attributes `theme`, `locale` and
@@ -57,6 +70,25 @@ declare type ExifOrientation = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
57
70
  */
58
71
  declare const FILTER_PRESETS: readonly ["vivid", "warm", "cool", "fade", "mono", "noir", "sepia"];
59
72
 
73
+ /**
74
+ * An arrow from one point of the scene to another (ADR 0009,
75
+ * docs/adr/0014). Its head's size follows its width, and its tip is exactly
76
+ * on `to`.
77
+ *
78
+ * @public
79
+ */
80
+ declare interface ImageArrowLayer extends ImageLayerCommon {
81
+ readonly kind: "arrow";
82
+ /** The tail. */
83
+ readonly from: ImageScenePoint;
84
+ /** The tip. It differs from `from`. */
85
+ readonly to: ImageScenePoint;
86
+ /** `#rrggbb`. */
87
+ readonly colour: string;
88
+ /** The shaft's width, in whole scene pixels: 1 to `MAX_STROKE_WIDTH`. */
89
+ readonly width: number;
90
+ }
91
+
60
92
  /**
61
93
  * The image being edited: a source, its crop and orientation, and its
62
94
  * develop adjustments and filter.
@@ -74,6 +106,13 @@ declare interface ImageBase {
74
106
  readonly filter: ImageFilter | null;
75
107
  }
76
108
 
109
+ /**
110
+ * A layer that has a box: text, a shape or an image.
111
+ *
112
+ * @public
113
+ */
114
+ declare type ImageBoxedLayer = ImageTextLayer | ImageShapeLayer | ImageImageLayer;
115
+
77
116
  /**
78
117
  * Options every port call accepts.
79
118
  *
@@ -94,7 +133,7 @@ declare interface ImageCallOptions {
94
133
  *
95
134
  * @public
96
135
  */
97
- declare type ImageCommand = SetCropCommand | SetOrientationCommand | SetOutputCommand | SetMetadataCommand | SetDevelopCommand | SetFilterCommand | InsertLayersCommand | RemoveLayersCommand | MoveLayersCommand | UpdateLayersCommand | InsertRedactionsCommand | RemoveRedactionsCommand | MoveRedactionsCommand | UpdateRedactionsCommand | ImageInverseCommand;
136
+ declare type ImageCommand = SetCropCommand | SetOrientationCommand | SetOutputCommand | SetMetadataCommand | SetDevelopCommand | SetFilterCommand | InsertLayersCommand | RemoveLayersCommand | MoveLayersCommand | UpdateLayersCommand | AddStrokesCommand | RemoveStrokesCommand | InsertRedactionsCommand | RemoveRedactionsCommand | MoveRedactionsCommand | UpdateRedactionsCommand | ImageInverseCommand;
98
137
 
99
138
  /**
100
139
  * A rectangle in whole pixels of the oriented source: `x` and `y` from its
@@ -130,6 +169,23 @@ declare interface ImageDevelop {
130
169
  readonly vibrance: number;
131
170
  }
132
171
 
172
+ /**
173
+ * Freehand strokes (ADR 0009, docs/adr/0014). A drawing has an origin and
174
+ * no box: moving it changes its origin, never its points. Its strokes are
175
+ * drawn opaque and the drawing composited as one, so strokes that cross
176
+ * don't darken each other.
177
+ *
178
+ * @public
179
+ */
180
+ declare interface ImageDrawingLayer extends ImageLayerCommon {
181
+ readonly kind: "drawing";
182
+ /** Its origin, in whole scene pixels. May be negative. */
183
+ readonly x: number;
184
+ readonly y: number;
185
+ /** 1 to `MAX_DRAWING_STROKES` strokes, in the order they're drawn. */
186
+ readonly strokes: readonly ImageStroke[];
187
+ }
188
+
133
189
  /**
134
190
  * The element's events, fired as `hm-image-editor-<name>`. None carries a
135
191
  * file name or contents (sdk-core ADR 0012):
@@ -253,6 +309,9 @@ export declare const imageEditorMessages: {
253
309
  readonly "actions.image.moveLayers": "layer order";
254
310
  readonly "actions.image.setLayerOrder": "layer order";
255
311
  readonly "actions.image.updateLayers": "layer change";
312
+ readonly "actions.image.addStrokes": "stroke";
313
+ readonly "actions.image.removeStrokes": "stroke";
314
+ readonly "actions.image.restoreStrokes": "stroke";
256
315
  readonly "actions.image.insertRedactions": "redaction";
257
316
  readonly "actions.image.removeRedactions": "redaction";
258
317
  readonly "actions.image.restoreRedactions": "redaction";
@@ -334,7 +393,10 @@ export declare const imageEditorMessages: {
334
393
  readonly "tools.add-text": "Add text";
335
394
  readonly "tools.add-rectangle": "Add a rectangle";
336
395
  readonly "tools.add-ellipse": "Add an ellipse";
396
+ readonly "tools.add-arrow": "Add an arrow";
337
397
  readonly "tools.add-image": "Add an image";
398
+ readonly "tools.draw": "Draw";
399
+ readonly "toolbar.groups.draw": "Draw";
338
400
  readonly "toolbar.groups.add": "Add";
339
401
  readonly "editor.inserting": "Adding the image…";
340
402
  readonly "layers.text": "Text";
@@ -348,6 +410,11 @@ export declare const imageEditorMessages: {
348
410
  readonly "layers.alignments.end": "End";
349
411
  readonly "layers.bold": "Bold";
350
412
  readonly "layers.colour": "Colour";
413
+ readonly "layers.arrow.from.x": "Tail, left";
414
+ readonly "layers.arrow.from.y": "Tail, top";
415
+ readonly "layers.arrow.to.x": "Tip, left";
416
+ readonly "layers.arrow.to.y": "Tip, top";
417
+ readonly "layers.arrow.width": "Width";
351
418
  readonly "layers.fill": "Fill";
352
419
  readonly "layers.outline": "Outline";
353
420
  readonly "layers.fillColour": "Fill colour";
@@ -359,6 +426,16 @@ export declare const imageEditorMessages: {
359
426
  readonly "layers.colours.yellow": "Yellow";
360
427
  readonly "layers.colours.green": "Green";
361
428
  readonly "layers.colours.blue": "Blue";
429
+ readonly "draw.panel": "Draw";
430
+ readonly "draw.intro": "Drag across the image to draw. Drawing needs a mouse, a pen or a finger; to point at something with the keyboard, add an arrow.";
431
+ readonly "draw.mode": "Draw with";
432
+ readonly "draw.modes.pen": "Pen";
433
+ readonly "draw.modes.highlighter": "Highlighter";
434
+ readonly "draw.colour": "Colour";
435
+ readonly "draw.width": "Width";
436
+ readonly "draw.removeLast": "Remove last stroke";
437
+ readonly "draw.removed": "Removed the last stroke.";
438
+ readonly "draw.done": "Done";
362
439
  readonly "tools.layers": "Layers";
363
440
  readonly "toolbar.groups.layers": "Layers";
364
441
  readonly "layers.panel": "Layers";
@@ -368,6 +445,8 @@ export declare const imageEditorMessages: {
368
445
  readonly "layers.kinds.rectangle": "Rectangle";
369
446
  readonly "layers.kinds.ellipse": "Ellipse";
370
447
  readonly "layers.kinds.image": "Image";
448
+ readonly "layers.kinds.drawing": "Drawing";
449
+ readonly "layers.kinds.arrow": "Arrow";
371
450
  readonly "layers.visible": "Show {name}";
372
451
  readonly "layers.selected": "Selected layer";
373
452
  readonly "layers.moveUp": "Move up";
@@ -385,6 +464,13 @@ export declare const imageEditorMessages: {
385
464
  readonly "layers.done": "Done";
386
465
  readonly "layers.frame": "Layer {index, number} of {count, number}: {name}";
387
466
  readonly "layers.frameDescription": "{width, number} × {height, number} pixels, from {x, number}, {y, number}, turned {degrees, number}°. Arrow keys move it; with Shift, they resize it; Delete removes it and Escape closes the layers.";
467
+ readonly "layers.drawingDescription": {
468
+ readonly $plural: "count";
469
+ } & {
470
+ readonly one: "{count} stroke, {width, number} × {height, number} pixels, from {x, number}, {y, number}. Arrow keys move it; Delete removes it and Escape closes the layers.";
471
+ readonly other: "{count, number} strokes, {width, number} × {height, number} pixels, from {x, number}, {y, number}. Arrow keys move it; Delete removes it and Escape closes the layers.";
472
+ };
473
+ readonly "layers.arrowDescription": "From {fromX, number}, {fromY, number} to {toX, number}, {toY, number}. Arrow keys move it; with Shift, they move its tip; Delete removes it and Escape closes the layers.";
388
474
  readonly "layers.movedUp": "Moved {name} up. It's layer {index, number} of {count, number}.";
389
475
  readonly "layers.movedDown": "Moved {name} down. It's layer {index, number} of {count, number}.";
390
476
  readonly "layers.duplicated": "Duplicated {name}.";
@@ -439,6 +525,7 @@ export declare const imageEditorMessages: {
439
525
  readonly "filters.strength": "Strength";
440
526
  readonly "toolbar.groups.export": "Export";
441
527
  readonly "tools.export": "Export";
528
+ readonly "tools.exportWhileCropping": "Apply or cancel the crop before exporting.";
442
529
  readonly "export.title": "Export image";
443
530
  readonly "export.description": "The file is made on this device, and nothing is uploaded.";
444
531
  readonly "export.format": "Format";
@@ -493,6 +580,7 @@ export declare const imageEditorMessages: {
493
580
  readonly "fileDropZone.hint": "or drop it here";
494
581
  readonly "fileDropZone.hintMultiple": "or drop them here";
495
582
  readonly "progress.label": "Progress";
583
+ readonly "reorderableList.moved": "{label} moved to position {position} of {count}";
496
584
  readonly "spinner.label": "Loading";
497
585
  readonly "errors.INVALID_THEME_TOKEN": "The theme setting {token} has a value that can't be used.";
498
586
  readonly "errors.INVALID_THEME_SELECTOR": "The theme can't be applied to the selector {selector}.";
@@ -517,6 +605,7 @@ export declare const imageEditorMessages: {
517
605
  readonly one: "An image can have {maximum} layer. Merge or delete layers, and try again.";
518
606
  readonly other: "An image can have up to {maximum, number} layers. Merge or delete layers, and try again.";
519
607
  };
608
+ readonly "errors.TOO_MANY_POINTS": "This image's drawings would have {actual, number} points, which is over the limit of {maximum, number}. Remove some strokes, and try again.";
520
609
  readonly "warnings.maxImagePixels": "This image is large, and may be slow to edit on some devices.";
521
610
  readonly "warnings.maxImageDimension": "This image is very wide or tall, and may be slow to edit.";
522
611
  readonly "warnings.maxFrames": {
@@ -532,6 +621,7 @@ export declare const imageEditorMessages: {
532
621
  readonly one: "This image has {actual} layer.";
533
622
  readonly other: "This image has {actual, number} layers, and may be slow to edit and export.";
534
623
  };
624
+ readonly "warnings.maxDrawingPoints": "This image has a lot of drawing, and may be slow to edit and export.";
535
625
  readonly "errors.UNKNOWN": "Something went wrong. Please try again.";
536
626
  readonly "errors.ABORTED": "The operation was cancelled.";
537
627
  readonly "errors.TIMEOUT": "The operation took too long and was stopped.";
@@ -681,6 +771,8 @@ declare class ImageError extends SdkError<ImageErrorCode> {
681
771
  * - `SESSION_TOO_LARGE`: the decoded images the session holds exceed the
682
772
  * `maxSessionSize` limit.
683
773
  * - `TOO_MANY_LAYERS`: the layer plan exceeds the `maxLayers` limit.
774
+ * - `TOO_MANY_POINTS`: the plan's drawings hold more points than the
775
+ * `maxDrawingPoints` limit.
684
776
  *
685
777
  * Limit codes carry `details` with the `limit`, its `maximum`, the `actual`
686
778
  * value and the `unit`. Other codes' `details` name the format involved,
@@ -688,7 +780,7 @@ declare class ImageError extends SdkError<ImageErrorCode> {
688
780
  *
689
781
  * @public
690
782
  */
691
- declare type ImageErrorCode = SdkCoreErrorCode | "INVALID_IMAGE" | "UNSUPPORTED_FORMAT" | "DECODE_FAILED" | "INVALID_COMMAND" | "INVALID_DOCUMENT" | "UNSUPPORTED_PLAN" | "IMAGE_TOO_LARGE" | "IMAGE_DIMENSION_TOO_LARGE" | "TOO_MANY_FRAMES" | "SESSION_TOO_LARGE" | "TOO_MANY_LAYERS";
783
+ declare type ImageErrorCode = SdkCoreErrorCode | "INVALID_IMAGE" | "UNSUPPORTED_FORMAT" | "DECODE_FAILED" | "INVALID_COMMAND" | "INVALID_DOCUMENT" | "UNSUPPORTED_PLAN" | "IMAGE_TOO_LARGE" | "IMAGE_DIMENSION_TOO_LARGE" | "TOO_MANY_FRAMES" | "SESSION_TOO_LARGE" | "TOO_MANY_LAYERS" | "TOO_MANY_POINTS";
692
784
 
693
785
  /**
694
786
  * The file an export produces (ADR 0001). `quality`, from 0 to 1, applies to
@@ -836,7 +928,7 @@ declare interface ImageInsertOptions {
836
928
  *
837
929
  * @public
838
930
  */
839
- declare type ImageInverseCommand = RestoreLayersCommand | SetLayerOrderCommand | RestoreRedactionsCommand | SetRedactionOrderCommand;
931
+ declare type ImageInverseCommand = RestoreStrokesCommand | RestoreLayersCommand | SetLayerOrderCommand | RestoreRedactionsCommand | SetRedactionOrderCommand;
840
932
 
841
933
  /**
842
934
  * The metadata fields a user may keep on export (ADR 0005). Empty strings
@@ -852,13 +944,13 @@ declare interface ImageKeepableMetadata {
852
944
  }
853
945
 
854
946
  /**
855
- * A layer over the base: text, a shape or another image (ADR 0009). Layers
856
- * are drawn bottom to top, in the plan's order, and redactions over all of
857
- * them.
947
+ * A layer over the base: text, a shape, another image, a drawing or an
948
+ * arrow (ADR 0009). Layers are drawn bottom to top, in the plan's order, and
949
+ * redactions over all of them.
858
950
  *
859
951
  * @public
860
952
  */
861
- declare type ImageLayer = ImageTextLayer | ImageShapeLayer | ImageImageLayer;
953
+ declare type ImageLayer = ImageBoxedLayer | ImageDrawingLayer | ImageArrowLayer;
862
954
 
863
955
  /**
864
956
  * Where a positioned layer is: a box in whole pixels of the scene, the
@@ -931,6 +1023,7 @@ declare type ImageLimitDefinitions = typeof imageLimitDefinitions;
931
1023
  * | `maxFrames` | `TOO_MANY_FRAMES` | 300 | 100 |
932
1024
  * | `maxSessionSize` | `SESSION_TOO_LARGE` | 1 GB | 500 MB |
933
1025
  * | `maxLayers` | `TOO_MANY_LAYERS` | 256 | none |
1026
+ * | `maxDrawingPoints` | `TOO_MANY_POINTS` | 200,000 | 100,000 |
934
1027
  *
935
1028
  * Sizes are decimal: 1 MB is 1,000,000 bytes. Decoded sizes count 4 bytes
936
1029
  * per pixel. `maxImagePixels` is the same limit, with the same name, code
@@ -973,6 +1066,12 @@ declare const imageLimitDefinitions: {
973
1066
  readonly unit: "count";
974
1067
  readonly default: 256;
975
1068
  };
1069
+ readonly maxDrawingPoints: {
1070
+ readonly code: "TOO_MANY_POINTS";
1071
+ readonly unit: "count";
1072
+ readonly default: 200000;
1073
+ readonly warning: 100000;
1074
+ };
976
1075
  readonly maxFileSize: {
977
1076
  readonly code: "FILE_TOO_LARGE";
978
1077
  readonly unit: "bytes";
@@ -1214,6 +1313,16 @@ declare interface ImageRegisterOptions extends ImageProgressOptions {
1214
1313
  */
1215
1314
  declare type ImageRotation = 0 | 90 | 180 | 270;
1216
1315
 
1316
+ /**
1317
+ * A point of the scene, in whole pixels.
1318
+ *
1319
+ * @public
1320
+ */
1321
+ declare interface ImageScenePoint {
1322
+ readonly x: number;
1323
+ readonly y: number;
1324
+ }
1325
+
1217
1326
  /**
1218
1327
  * An image editing session (ADR 0003, ADR 0008): one document, its plan
1219
1328
  * over the source it opened, edited by commands with undo and redo, and
@@ -1419,6 +1528,25 @@ declare interface ImageSourceInfo {
1419
1528
  readonly decodedBytes: number;
1420
1529
  }
1421
1530
 
1531
+ /**
1532
+ * One stroke of a drawing: what one gesture drew, from the press to the
1533
+ * release (docs/adr/0014). It has more than one run only when it's long.
1534
+ *
1535
+ * @public
1536
+ */
1537
+ declare interface ImageStroke {
1538
+ /** `#rrggbb`. */
1539
+ readonly colour: string;
1540
+ /** In whole scene pixels: 1 to `MAX_STROKE_WIDTH`. */
1541
+ readonly width: number;
1542
+ /**
1543
+ * 1 to `MAX_STROKE_RUNS` runs, each a polyline `[x0, y0, x1, y1, …]` of 1
1544
+ * to `MAX_RUN_POINTS` points, in whole pixels from the drawing's origin.
1545
+ * A run of one point is a dot.
1546
+ */
1547
+ readonly runs: readonly (readonly number[])[];
1548
+ }
1549
+
1422
1550
  /**
1423
1551
  * Text, drawn as large as fits inside its box, never distorted (ADR 0009).
1424
1552
  * Lines break only at line feeds. Emoji are text.
@@ -1545,6 +1673,18 @@ declare interface RemoveRedactionsCommand {
1545
1673
  readonly keys: readonly string[];
1546
1674
  }
1547
1675
 
1676
+ /**
1677
+ * Removes strokes from a drawing layer, by index. A drawing keeps at least
1678
+ * one stroke: to remove the last, remove the layer.
1679
+ *
1680
+ * @public
1681
+ */
1682
+ declare interface RemoveStrokesCommand {
1683
+ readonly type: "image.removeStrokes";
1684
+ readonly key: string;
1685
+ readonly indexes: readonly number[];
1686
+ }
1687
+
1548
1688
  /**
1549
1689
  * Puts removed layers back, each at its index, by rising index. It's what
1550
1690
  * undoes {@link RemoveLayersCommand}: the reducer applies it, but it isn't
@@ -1575,6 +1715,22 @@ declare interface RestoreRedactionsCommand {
1575
1715
  }[];
1576
1716
  }
1577
1717
 
1718
+ /**
1719
+ * Puts removed strokes back, each at its index, by rising index. It's what
1720
+ * undoes {@link RemoveStrokesCommand}: the reducer applies it, but it isn't
1721
+ * part of the portable command format (ADR 0009).
1722
+ *
1723
+ * @public
1724
+ */
1725
+ declare interface RestoreStrokesCommand {
1726
+ readonly type: "image.restoreStrokes";
1727
+ readonly key: string;
1728
+ readonly entries: readonly {
1729
+ readonly at: number;
1730
+ readonly stroke: ImageStroke;
1731
+ }[];
1732
+ }
1733
+
1578
1734
  /**
1579
1735
  * Sets or removes the base's crop, in whole pixels of the oriented source.
1580
1736
  *
package/dist/element.js CHANGED
@@ -1,5 +1,5 @@
1
- import { Nt as ImageError } from "./shared/core-BlFeJWak.js";
2
- import { d as imageEditorMessages, p as ExportListenerContext, t as ImageEditor } from "./shared/editor-Bjv32UmV.js";
1
+ import { Vt as ImageError } from "./shared/core-VHeENp7j.js";
2
+ import { d as imageEditorMessages, p as ExportListenerContext, t as ImageEditor } from "./shared/editor-Bj9Xo5nf.js";
3
3
  import { useEffect, useRef } from "react";
4
4
  import { jsx } from "react/jsx-runtime";
5
5
  import { createEditorElement } from "@hussmartinez/sdk-core/element";