image-exporter 1.1.1 → 1.2.0

package/README.md

@@ -1,66 +1,122 @@
-# image-exporter [v1.1.0]
+# image-exporter
 
-image-exporter is a client-side javascript tool that downloads DOM elements as images. It can be imported using your favorite package manager or used directly the window.
+[![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)
 
-## Examples:
+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.
+
+## Installation
+
+```bash
+npm i image-exporter
+```
+
+```typescript
+import { capture } from "image-exporter";
+```
+
+## Examples
 
 ### Package
 
-```Typescript
-import  { capture }  from  "image-exporter";
+```typescript
+import { capture } from "image-exporter";
 
-const  artboards  =  document.querySelectorAll(".artboard");
+const artboards = document.querySelectorAll(".artboard");
 
-// Returned as [dataUrl, filename] rather than downloaded
-const images = capture(artboards, {
-	format: 'png',
-	downloadImages: false
-})
+// Returns Image[] with { dataURL, fileName } for each image
+const images = await capture(artboards, {
+  format: "png",
+  downloadImages: false,
+});
 ```
 
 ### Browser
 
-```HTML
+```html
 <script src="your-path/image-exporter.umd.js" type="text/javascript"></script>
 
 <div class="artboard">I will be downloaded.</div>
 
 <script>
-	const  capture  =  window.imageExporter;
-	const  artboards  =  document.querySelectorAll(".artboard");
-	capture(artboards)
+  const capture = window.imageExporter;
+  const artboards = document.querySelectorAll(".artboard");
+
+  // capture() is async and returns a Promise
+  capture(artboards).then((images) => {
+    console.log("Captured:", images);
+  });
 </script>
+```
+
+## API
+
+### `capture(elements, config?)`
+
+Captures images from HTML elements.
 
+**Parameters:**
+
+- `elements` - `HTMLElement | HTMLElement[] | NodeListOf<HTMLElement>` - Element(s) to capture
+- `config` - `Partial<Config>` - Optional configuration object
+
+**Returns:** `Promise<Image[] | null>` - Array of captured images, or `null` on error
+
+```typescript
+interface Image {
+  dataURL: string;
+  fileName: string;
+}
 ```
 
-## Installation
+### `downloadImages(images, config?)`
+
+Downloads previously captured images. Useful when `downloadImages: false` is set during capture.
 
-`npm i image-exporter` or whatever package manager you're using.
+```typescript
+import { capture, downloadImages } from "image-exporter";
 
-```Typescript
-import  { capture }  from  "image-exporter";
+const images = await capture(elements, { downloadImages: false });
+// ... do something with images ...
+await downloadImages(images);
 ```
 
+In the browser, this is available as `window.imageExporterDownload`.
+
 ## Config
 
-```Typescript
-{
-	/** Download images as files upon capture. */
-	downloadImages:  boolean;
-	/** Default label for images. Does not include file extension or scale. */
-	defaultImageLabel:  string;
-	/** Label for zip file. Does not include file extension or scale. */
-	zipLabel:  string;
-	/** Base URL for CORS proxy used when fetching external images. */
-	corsProxyBaseUrl:  string;
-	/** Enable window logging for use by external scripts */
-	enableWindowLogging:  boolean;
-	/** Enable verbose logging for debugging. */
-	loggingLevel:  "none"  |  "info"  |  "error"  |  "verbose";
+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.
+
+```typescript
+interface Config {
+  /** Download images as files upon capture. Default: true */
+  downloadImages: boolean;
+  /** Default label for images. Does not include file extension or scale. Default: "image" */
+  defaultImageLabel: string;
+  /** Label for zip file. Does not include file extension or scale. Default: "images" */
+  zipLabel: string;
+  /** Base URL for CORS proxy used when fetching external images. Default: "" */
+  corsProxyBaseUrl: string;
+  /** Enable window logging for use by external scripts. Default: true */
+  enableWindowLogging: boolean;
+  /** Logging level for debugging. Default: "none" */
+  loggingLevel: "none" | "info" | "error" | "verbose";
+
+  // Default image options (can be overridden per-element)
+  /** Default: "image" */
+  label: string;
+  /** Default: "jpg" */
+  format: "jpg" | "png" | "svg" | "webp";
+  /** Default: 1 */
+  scale: number | number[];
+  /** Default: 1 */
+  quality: number;
+  /** Default: false */
+  includeScaleInLabel: boolean;
 }
 ```
 
-### CORS proxy
+### CORS Proxy
 
 If your capture elements have externally hosted images or CSS inside them, you will likely hit a [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) error.
 
@@ -70,69 +126,65 @@ I recommend [cors-proxy-worker](https://github.com/briantuckerdesign/cors-proxy-
 
 Example: `https://example-cors-proxy.com/` -> `https://example-cors-proxy.com/https%3A%2F%2FmyEncodedUrl.com`
 
-## Image options
-
-Image options can also be set at the `config` level and will serve as the default if no values are provided for that specific capture element.
-
-```Typescript
-{
-	/** Label for image. Does not include file extension or scale. */
-	label:  string;
-	/** File format, jpg, png, or svg. */
-	format:  "jpg"  |  "png"  |  "svg" | "webp";
-	/** Scale of image. Can be a number or a comma-separated list of numbers. */
-	scale:  number  |  number[];
-	/** Quality of image. 0.0 to 1.0, only applies to jpg.*/
-	quality:  number;
-	/** Include scale in label. True or false. Automatically true if scale is an array. */
-	includeScaleInLabel:  boolean;
+## Image Options
+
+Image options can be set per-element using data attributes, or as defaults in the config.
+
+```typescript
+interface ImageOptions {
+  /** Label for image. Does not include file extension or scale. */
+  label: string;
+  /** File format. */
+  format: "jpg" | "png" | "svg" | "webp";
+  /** Scale of image. Can be a number or an array of numbers. */
+  scale: number | number[];
+  /** Quality of image. 0.0 to 1.0, only applies to jpg. */
+  quality: number;
+  /** Include scale in label. Automatically true if scale is an array. */
+  includeScaleInLabel: boolean;
 }
 ```
 
-### Setting image options
-
-Image options are set on the element itself using data attributes.
+### Data Attributes
 
-The attributes are:
+Set image options on elements using these data attributes:
 
-```
-data-label
-data-format
-data-scale
-data-quality
-data-include-scale-in-label
-```
+- `data-label`
+- `data-format`
+- `data-scale`
+- `data-quality`
+- `data-include-scale-in-label`
 
 #### Example
 
-```HTML
+```html
 <div
-    data-label="My custom label"
-    data-format="jpg"
-    data-scale="1,2"
-    data-quality="0.8"
-    data-include-scale-in-label="true">
-    I will be downloaded at @1x and @2x with a custom label, quality of 0.8, a JPG, and include scale in label.
+  data-label="My custom label"
+  data-format="jpg"
+  data-scale="1,2"
+  data-quality="0.8"
+  data-include-scale-in-label="true"
+>
+  I will be downloaded at @1x and @2x with a custom label, quality of 0.8, as a JPG, with
+  scale in the filename.
 </div>
 ```
 
-### Setting config options
-
-Config options are set in the `config` object passed to the `capture` function.
-
-#### Example
-
-```HTML
+```html
 <div class="artboard" data-scale="1,2">I will be downloaded at @1x and @2x.</div>
-<div class="artboard" data-format="jpg" data-quality="0.8">I will be a compressed JPG.</div>
+<div class="artboard" data-format="jpg" data-quality="0.8">
+  I will be a compressed JPG.
+</div>
 ```
 
-## Built using
-
-- [`modern-screenshot`](https://github.com/qq15725/modern-screenshot/tree/main)
+## Built Using
 
+- [`modern-screenshot`](https://github.com/qq15725/modern-screenshot)
 - [`jszip`](https://github.com/Stuk/jszip)
-
 - [`downloadjs`](https://github.com/rndme/download)
 
-Bundled in Vite and written in Typescript.
+Bundled with Vite and written in TypeScript.
+
+## License
+
+ISC License - see [LICENSE](LICENSE) for details.

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

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

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

@@ -0,0 +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"}

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

@@ -0,0 +1,9 @@
+/**
+ * determineTotalElements
+ *
+ * Just used for progress logging to show progress of all element captures.
+ *
+ * This emcompasses multi-scale captures unlike elements.length.
+ */
+export declare function determineTotalElements(elements: HTMLElement[] | NodeListOf<HTMLElement>): Promise<number>;
+//# sourceMappingURL=determine-total-elements.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,10 @@
+import { Config, Image } from "../types";
+/**
+ * downloadImages
+ *
+ * If one image is provided, it will be downloaded as a file.
+ *
+ * If multiple images are provided, they will be zipped and downloaded as a file.
+ */
+export declare function downloadImages(images: Image[], userConfig?: Config): Promise<void>;
+//# sourceMappingURL=download-images.d.ts.map

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

@@ -0,0 +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;AAKhD;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,KAAK,EAAE,EACf,UAAU,GAAE,MAAsB,iBAcnC"}

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

@@ -0,0 +1,15 @@
+import { Config, ImageOptions } from "../types";
+/**
+ * Retrieves the image options for the given element or configuration.
+ *
+ * Data attributes:
+ * - data-label: string
+ * - data-format: "jpg" | "png" | "svg"
+ * - data-scale: number | number[]
+ * - data-quality: number
+ * - data-include-scale-in-label: boolean
+ *
+ * @returns {Promise<ImageOptions>} - The parsed image options.
+ */
+export declare function getImageOptions(element: HTMLElement, config: Config): Promise<ImageOptions>;
+//# sourceMappingURL=get-image-options.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"get-image-options.d.ts","sourceRoot":"","sources":["../../src/capture/get-image-options.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,MAAM,EAEN,YAAY,EAGb,MAAM,UAAU,CAAC;AAElB;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,YAAY,CAAC,CAqLvB"}

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

@@ -0,0 +1,11 @@
+import { ImageOptions, Label } from "../types";
+/**
+ * Handles the generation of unique filenames based on a proposed filename and an array of existing filenames.
+ *
+ * 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.
+ */
+export declare function handleFileNames(imageOptions: ImageOptions, filenames: string[]): Label;
+//# sourceMappingURL=handle-filenames.d.ts.map

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

@@ -0,0 +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"}

package/dist/capture/index.d.ts

@@ -0,0 +1,10 @@
+import { Config, Image } from "../types";
+export declare let windowLogging: boolean;
+export declare let loggingLevel: string;
+/**
+ * capture
+ *
+ * Captures images from HTML elements and returns them or downloads them.
+ */
+export declare function capture(elements: HTMLElement[] | NodeListOf<HTMLElement> | HTMLElement, userConfig?: Partial<Config>): Promise<Image[] | null>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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"}

package/dist/capture/remove-hidden-elements.d.ts

@@ -0,0 +1,2 @@
+export declare function removeHiddenElements(elements: HTMLElement[] | NodeListOf<HTMLElement>): HTMLElement[];
+//# sourceMappingURL=remove-hidden-elements.d.ts.map

package/dist/capture/remove-hidden-elements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remove-hidden-elements.d.ts","sourceRoot":"","sources":["../../src/capture/remove-hidden-elements.ts"],"names":[],"mappings":"AAAA,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,WAAW,EAAE,GAAG,UAAU,CAAC,WAAW,CAAC,GAChD,WAAW,EAAE,CAGf"}

package/dist/config.d.ts

@@ -0,0 +1,4 @@
+import { Config, ImageOptions } from "./types";
+export declare const defaultImageOptions: ImageOptions;
+export declare const defaultConfig: Config;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE/C,eAAO,MAAM,mBAAmB,EAAE,YAMjC,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,MAQ3B,CAAC"}

package/dist/cors-proxy/cleanup.d.ts

@@ -0,0 +1,7 @@
+/**
+ * cleanUpCorsProxy
+ *
+ * Restores the CSS and images to their original state.
+ */
+export declare function cleanUpCorsProxy(): Promise<void>;
+//# sourceMappingURL=cleanup.d.ts.map

package/dist/cors-proxy/cleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup.d.ts","sourceRoot":"","sources":["../../src/cors-proxy/cleanup.ts"],"names":[],"mappings":"AACA;;;;GAIG;AACH,wBAAsB,gBAAgB,kBAGrC"}

package/dist/cors-proxy/index.d.ts

@@ -0,0 +1,7 @@
+import { runCorsProxy } from "./run";
+import { cleanUpCorsProxy } from "./cleanup";
+export declare const corsProxy: {
+    run: typeof runCorsProxy;
+    cleanUp: typeof cleanUpCorsProxy;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/cors-proxy/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cors-proxy/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AACrC,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7C,eAAO,MAAM,SAAS;;;CAGrB,CAAC"}

package/dist/cors-proxy/is-valid-url.d.ts

@@ -0,0 +1,7 @@
+/**
+ * isValidUrl
+ *
+ * Checks if a string is a valid external URL.
+ */
+export declare function isValidUrl(string: string): boolean;
+//# sourceMappingURL=is-valid-url.d.ts.map

package/dist/cors-proxy/is-valid-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-valid-url.d.ts","sourceRoot":"","sources":["../../src/cors-proxy/is-valid-url.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAgBlD"}

package/dist/cors-proxy/proxy-css.d.ts

@@ -0,0 +1,9 @@
+import { Config } from "../types";
+/**
+ * proxyCSS
+ *
+ * Proxies all linked CSS files and the absolute URLs inside them, including fonts and images.
+ * Upon completion of capture, the links will be restored and the style elements removed.
+ */
+export declare function proxyCSS(config: Config): Promise<void>;
+//# sourceMappingURL=proxy-css.d.ts.map

package/dist/cors-proxy/proxy-css.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy-css.d.ts","sourceRoot":"","sources":["../../src/cors-proxy/proxy-css.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAGlC;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,MAAM,EAAE,MAAM,iBAqC5C"}

package/dist/cors-proxy/proxy-images.d.ts

@@ -0,0 +1,9 @@
+import { Config } from "../types";
+/**
+ * proxyImages
+ *
+ * Proxies all images inside capture elements.
+ * The original src is stored for later restoration.
+ */
+export declare function proxyImages(config: Config, elements: HTMLElement[] | NodeListOf<HTMLElement>): Promise<void>;
+//# sourceMappingURL=proxy-images.d.ts.map

package/dist/cors-proxy/proxy-images.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy-images.d.ts","sourceRoot":"","sources":["../../src/cors-proxy/proxy-images.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAIlC;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,WAAW,EAAE,GAAG,UAAU,CAAC,WAAW,CAAC,iBAqBlD"}

package/dist/cors-proxy/run.d.ts

@@ -0,0 +1,9 @@
+import { Config } from "../types";
+/**
+ * runCorsProxy
+ *
+ * Proxies all images inside capture elements, as well as all linked CSS files and the absolute URLs inside them.
+ * Upon completion of capture, these will be reverted to their original state.
+ */
+export declare function runCorsProxy(config: Config, elements: HTMLElement[] | NodeListOf<HTMLElement>): Promise<void>;
+//# sourceMappingURL=run.d.ts.map

package/dist/cors-proxy/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/cors-proxy/run.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAIlC;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,WAAW,EAAE,GAAG,UAAU,CAAC,WAAW,CAAC,GAChD,OAAO,CAAC,IAAI,CAAC,CAUf"}