image-exporter 1.2.3 → 1.3.0

package/README.md

@@ -1,7 +1,7 @@
 # image-exporter
 
 [![npm version](https://img.shields.io/npm/v/image-exporter.svg)](https://www.npmjs.com/package/image-exporter)
-[![license](https://img.shields.io/npm/l/image-exporter.svg)](https://github.com/briantuckerdesign/image-exporter/blob/main/LICENSE)
+[![license](https://img.shields.io/npm/l/image-exporter.svg)](https://github.com/briantuckerdesign/image-exporter/blob/main/LICENSE.md)
 
 A client-side JavaScript tool that downloads DOM elements as images. It can be imported using your favorite package manager or attached directly to the window.
 
@@ -34,7 +34,11 @@ const images = await capture(artboards, {
 ### Browser
 
 ```html
-<script src="your-path/image-exporter.umd.js" type="text/javascript"></script>
+<!-- Self-hosted -->
+<script src="your-path/index.browser.js" type="text/javascript"></script>
+
+<!-- Or via CDN -->
+<script src="https://unpkg.com/image-exporter" type="text/javascript"></script>
 
 <div class="artboard">I will be downloaded.</div>
 
@@ -64,8 +68,11 @@ Captures images from HTML elements.
 
 ```typescript
 interface Image {
+  /** base64 data URL. Empty when `output` is `"blob"`. */
   dataURL: string;
   fileName: string;
+  /** Populated when `config.output` is `"blob"` or `"both"`. */
+  blob?: Blob;
 }
 ```
 
@@ -83,6 +90,19 @@ await downloadImages(images);
 
 In the browser, this is available as `window.imageExporterDownload`.
 
+### `copyImageToClipboard(image)`
+
+Copies a single captured image to the system clipboard. Must be called from a user gesture (e.g. a click). Use `format: "png"` for the best browser compatibility.
+
+```typescript
+import { capture, copyImageToClipboard } from "image-exporter";
+
+const images = await capture(element, { downloadImages: false, format: "png" });
+await copyImageToClipboard(images[0]);
+```
+
+In the browser, this is available as `window.imageExporterCopyToClipboard`.
+
 ## Config
 
 Config options are passed to the `capture` function. Image options (label, format, scale, quality, includeScaleInLabel) can also be set at the config level as defaults.
@@ -102,6 +122,15 @@ interface Config {
   /** Logging level for debugging. Default: "none" */
   loggingLevel: "none" | "info" | "error" | "verbose";
 
+  /** Called after each capture with (completed, total). */
+  onProgress?: (completed: number, total: number) => void;
+  /** Cancel an in-progress capture; returns the images captured so far. */
+  signal?: AbortSignal;
+  /** Extra options forwarded to modern-screenshot (fonts, width/height, pixelRatio, etc.). */
+  screenshotOptions?: Partial<import("modern-screenshot").Options>;
+  /** What the returned images carry. Default: "dataurl" */
+  output?: "dataurl" | "blob" | "both";
+
   // Default image options (can be overridden per-element)
   /** Default: "image" */
   label: string;
@@ -186,4 +215,4 @@ Bundled with Bun and written in TypeScript.
 
 ## License
 
-ISC License - see [LICENSE](LICENSE) for details.
+Apache-2.0 License - see [LICENSE.md](LICENSE.md) for details.

package/dist/capture/capture-element.d.ts

@@ -1,8 +1,9 @@
 import { Image, ParsedImageOptions } from "../types";
+import * as modernScreenshot from "modern-screenshot";
 /**
  * captureElement
  *
  * Captures an image from an HTML element and returns it.
  */
-export declare function captureElement(element: HTMLElement, imageOptions: ParsedImageOptions, filenames: string[]): Promise<Image>;
+export declare function captureElement(element: HTMLElement, imageOptions: ParsedImageOptions, seen: Set<string>, screenshotOptions?: Partial<modernScreenshot.Options>): Promise<Image>;
 //# sourceMappingURL=capture-element.d.ts.map

package/dist/capture/capture-element.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capture-element.d.ts","sourceRoot":"","sources":["../../src/capture/capture-element.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAIrD;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,WAAW,EACpB,YAAY,EAAE,kBAAkB,EAChC,SAAS,EAAE,MAAM,EAAE,GAClB,OAAO,CAAC,KAAK,CAAC,CAwDhB"}
+{"version":3,"file":"capture-element.d.ts","sourceRoot":"","sources":["../../src/capture/capture-element.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAErD,OAAO,KAAK,gBAAgB,MAAM,mBAAmB,CAAC;AAEtD;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,WAAW,EACpB,YAAY,EAAE,kBAAkB,EAChC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,EACjB,iBAAiB,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,OAAO,CAAC,GACpD,OAAO,CAAC,KAAK,CAAC,CAgEhB"}

package/dist/capture/capture.dom.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=capture.dom.test.d.ts.map

package/dist/capture/capture.dom.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.dom.test.d.ts","sourceRoot":"","sources":["../../src/capture/capture.dom.test.ts"],"names":[],"mappings":""}

package/dist/capture/copy-to-clipboard.d.ts

@@ -0,0 +1,13 @@
+import { Image } from "../types";
+/**
+ * copyImageToClipboard
+ *
+ * Copies a single captured image to the system clipboard. Must be called from a
+ * user gesture (click/keypress) due to browser security. The clipboard holds
+ * one image at a time, so pass the specific image you want to copy.
+ *
+ * Note: browsers most reliably support `image/png` on the clipboard — capture
+ * with `format: "png"` for best compatibility.
+ */
+export declare function copyImageToClipboard(image: Image): Promise<void>;
+//# sourceMappingURL=copy-to-clipboard.d.ts.map

package/dist/capture/copy-to-clipboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"copy-to-clipboard.d.ts","sourceRoot":"","sources":["../../src/capture/copy-to-clipboard.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAGjC;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAGtE"}

package/dist/capture/copy-to-clipboard.dom.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=copy-to-clipboard.dom.test.d.ts.map

package/dist/capture/copy-to-clipboard.dom.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"copy-to-clipboard.dom.test.d.ts","sourceRoot":"","sources":["../../src/capture/copy-to-clipboard.dom.test.ts"],"names":[],"mappings":""}

package/dist/capture/cors-cleanup.dom.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cors-cleanup.dom.test.d.ts.map

package/dist/capture/cors-cleanup.dom.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cors-cleanup.dom.test.d.ts","sourceRoot":"","sources":["../../src/capture/cors-cleanup.dom.test.ts"],"names":[],"mappings":""}

package/dist/capture/data-url-to-blob.d.ts

@@ -0,0 +1,9 @@
+/**
+ * dataUrlToBlob
+ *
+ * Converts a data URL (base64 or URL-encoded, e.g. SVG) into a Blob, preserving
+ * the MIME type. Lets callers work with binary Blobs instead of large base64
+ * strings.
+ */
+export declare function dataUrlToBlob(dataURL: string): Blob;
+//# sourceMappingURL=data-url-to-blob.d.ts.map

package/dist/capture/data-url-to-blob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-url-to-blob.d.ts","sourceRoot":"","sources":["../../src/capture/data-url-to-blob.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAiBnD"}

package/dist/capture/data-url-to-blob.node.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data-url-to-blob.node.test.d.ts.map

package/dist/capture/data-url-to-blob.node.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-url-to-blob.node.test.d.ts","sourceRoot":"","sources":["../../src/capture/data-url-to-blob.node.test.ts"],"names":[],"mappings":""}

package/dist/capture/dedup-consistency.node.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=dedup-consistency.node.test.d.ts.map

package/dist/capture/dedup-consistency.node.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedup-consistency.node.test.d.ts","sourceRoot":"","sources":["../../src/capture/dedup-consistency.node.test.ts"],"names":[],"mappings":""}

package/dist/capture/determine-total-elements.d.ts

@@ -1,9 +1,13 @@
+import { Config } from "../types";
 /**
  * determineTotalElements
  *
- * Just used for progress logging to show progress of all element captures.
+ * Computes how many captures will occur across all elements, so progress
+ * logging reflects multi-scale captures (not just elements.length).
  *
- * This emcompasses multi-scale captures unlike elements.length.
+ * Each element produces at least one capture. A `data-scale` comma-list
+ * produces one capture per scale. An element with no (or an invalid)
+ * `data-scale` falls back to `config.scale`, mirroring `getImageOptions`.
  */
-export declare function determineTotalElements(elements: HTMLElement[] | NodeListOf<HTMLElement>): Promise<number>;
+export declare function determineTotalElements(elements: HTMLElement[] | NodeListOf<HTMLElement>, config: Config): Promise<number>;
 //# sourceMappingURL=determine-total-elements.d.ts.map

package/dist/capture/determine-total-elements.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"determine-total-elements.d.ts","sourceRoot":"","sources":["../../src/capture/determine-total-elements.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,WAAW,EAAE,GAAG,UAAU,CAAC,WAAW,CAAC,GAChD,OAAO,CAAC,MAAM,CAAC,CA8BjB"}
+{"version":3,"file":"determine-total-elements.d.ts","sourceRoot":"","sources":["../../src/capture/determine-total-elements.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAElC;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,WAAW,EAAE,GAAG,UAAU,CAAC,WAAW,CAAC,EACjD,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAUjB"}

package/dist/capture/determine-total-elements.dom.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=determine-total-elements.dom.test.d.ts.map

package/dist/capture/determine-total-elements.dom.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"determine-total-elements.dom.test.d.ts","sourceRoot":"","sources":["../../src/capture/determine-total-elements.dom.test.ts"],"names":[],"mappings":""}

package/dist/capture/download-images.d.ts

@@ -7,4 +7,12 @@ import { Config, Image } from "../types";
  * If multiple images are provided, they will be zipped and downloaded as a file.
  */
 export declare function downloadImages(images: Image[], userConfig?: Config): Promise<void>;
+/**
+ * ensureUniqueFileNames
+ *
+ * Ensures all image filenames are unique by adding -2, -3, etc. to duplicates
+ * before the file extension. Uses the shared `makeUnique` helper so this public
+ * entry point dedups identically to capture-time naming.
+ */
+export declare function ensureUniqueFileNames(images: Image[]): Image[];
 //# sourceMappingURL=download-images.d.ts.map

package/dist/capture/download-images.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"download-images.d.ts","sourceRoot":"","sources":["../../src/capture/download-images.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,EAAS,MAAM,UAAU,CAAC;AAIhD;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,KAAK,EAAE,EACf,UAAU,GAAE,MAAsB,iBAcnC"}
+{"version":3,"file":"download-images.d.ts","sourceRoot":"","sources":["../../src/capture/download-images.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,EAAS,MAAM,UAAU,CAAC;AAKhD;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,KAAK,EAAE,EACf,UAAU,GAAE,MAAsB,iBAenC;AAmED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,CAO9D"}

package/dist/capture/get-image-options.dom.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=get-image-options.dom.test.d.ts.map

package/dist/capture/get-image-options.dom.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-image-options.dom.test.d.ts","sourceRoot":"","sources":["../../src/capture/get-image-options.dom.test.ts"],"names":[],"mappings":""}

package/dist/capture/handle-filenames.d.ts

@@ -1,11 +1,10 @@
 import { ImageOptions, Label } from "../types";
 /**
- * Handles the generation of unique filenames based on a proposed filename and an array of existing filenames.
+ * handleFileNames
  *
- * If the proposed filename is unique, it is added to the filenames array and returned as-is.
- * If the proposed filename is not unique, the function will check if it already ends with a "-n" pattern.
- * If it does, the function will increment the number until a unique filename is found.
- * If it doesn't, the function will start with "-2" and increment the number until a unique filename is found.
+ * Builds the filename for an image from its options (label + optional scale +
+ * format extension), then ensures it is unique against `seen` via the shared
+ * `makeUnique` helper.
  */
-export declare function handleFileNames(imageOptions: ImageOptions, filenames: string[]): Label;
+export declare function handleFileNames(imageOptions: ImageOptions, seen: Set<string>): Label;
 //# sourceMappingURL=handle-filenames.d.ts.map

package/dist/capture/handle-filenames.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handle-filenames.d.ts","sourceRoot":"","sources":["../../src/capture/handle-filenames.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAE/C;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,KAAK,CA2CtF"}
+{"version":3,"file":"handle-filenames.d.ts","sourceRoot":"","sources":["../../src/capture/handle-filenames.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAG/C;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,YAAY,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,KAAK,CAQpF"}

package/dist/capture/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/capture/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,EAAE,KAAK,EAAsB,MAAM,UAAU,CAAC;AAO7D,eAAO,IAAI,aAAa,SAAO,CAAC;AAChC,eAAO,IAAI,YAAY,QAAS,CAAC;AAEjC;;;;GAIG;AACH,wBAAsB,OAAO,CAC3B,QAAQ,EAAE,WAAW,EAAE,GAAG,UAAU,CAAC,WAAW,CAAC,GAAG,WAAW,EAC/D,UAAU,GAAE,OAAO,CAAC,MAAM,CAAiB,GAC1C,OAAO,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,CAgFzB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/capture/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,EAAE,KAAK,EAA8B,MAAM,UAAU,CAAC;AAQrE,eAAO,IAAI,aAAa,SAAO,CAAC;AAChC,eAAO,IAAI,YAAY,QAAS,CAAC;AAEjC;;;;GAIG;AACH,wBAAsB,OAAO,CAC3B,QAAQ,EAAE,WAAW,EAAE,GAAG,UAAU,CAAC,WAAW,CAAC,GAAG,WAAW,EAC/D,UAAU,GAAE,OAAO,CAAC,MAAM,CAAiB,GAC1C,OAAO,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,CAyGzB"}

package/dist/capture/make-unique.d.ts

@@ -0,0 +1,14 @@
+/**
+ * makeUnique
+ *
+ * Returns a filename guaranteed not to collide with any name in `seen`, and
+ * records the result in `seen`. Duplicates get a `-2`, `-3`, ... suffix before
+ * the extension. If the proposed name already ends with `-n`, numbering
+ * continues from there (e.g. `a-2.png` -> `a-3.png`) rather than nesting
+ * (`a-2-2.png`).
+ *
+ * Shared by `handleFileNames` (capture time) and `downloadImages` (public
+ * entry point) so both paths dedup identically.
+ */
+export declare function makeUnique(fileName: string, seen: Set<string>): string;
+//# sourceMappingURL=make-unique.d.ts.map

package/dist/capture/make-unique.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"make-unique.d.ts","sourceRoot":"","sources":["../../src/capture/make-unique.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,CA2BtE"}

package/dist/capture/make-unique.node.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=make-unique.node.test.d.ts.map

package/dist/capture/make-unique.node.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"make-unique.node.test.d.ts","sourceRoot":"","sources":["../../src/capture/make-unique.node.test.ts"],"names":[],"mappings":""}