image-exporter 1.1.0 → 1.2.0

package/src/capture/capture-element.ts

@@ -1,79 +0,0 @@
-import { Image, ParsedImageOptions } from "../types";
-import { handleFileNames } from "./handle-filenames";
-import * as modernScreenshot from "modern-screenshot";
-
-/**
- * captureElement
- *
- * Captures an image from an HTML element and returns it.
- */
-export async function captureElement(
-  element: HTMLElement,
-  imageOptions: ParsedImageOptions,
-  filenames: string[]
-): Promise<Image> {
-  try {
-    let dataURL = "";
-    // Final settings for capturing images.
-    let htmlToImageOptions: modernScreenshot.Options = {
-      // Ensure quality is a number
-      quality: imageOptions.quality,
-      // Ensure scale is a number
-      scale: imageOptions.scale,
-      // Ignores elements with data-ignore-capture attribute
-      filter: filter,
-    };
-
-    // If element has no background and is a JPG, default to white background
-    const styles = getComputedStyle(element);
-    const backgroundColor = styles.backgroundColor;
-    const backgroundImage = styles.backgroundImage;
-    let cleanUpBackground = false;
-    if (
-      backgroundColor === "rgba(0, 0, 0, 0)" &&
-      backgroundImage === "none" &&
-      imageOptions.format === "jpg"
-    ) {
-      element.style.backgroundColor = "#FFFFFF";
-      cleanUpBackground = true;
-    }
-
-    // Captures image based on format
-    switch (imageOptions.format) {
-      case "jpg":
-        dataURL = await modernScreenshot.domToJpeg(element, htmlToImageOptions);
-        break;
-      case "png":
-        dataURL = await modernScreenshot.domToPng(element, htmlToImageOptions);
-        break;
-      case "svg":
-        dataURL = await modernScreenshot.domToSvg(element, htmlToImageOptions);
-        break;
-      case "webp":
-        dataURL = await modernScreenshot.domToWebp(element, htmlToImageOptions);
-        break;
-    }
-
-    if (cleanUpBackground) {
-      element.style.backgroundColor = "";
-      element.style.backgroundImage = "";
-    }
-
-    return {
-      dataURL,
-      fileName: handleFileNames(imageOptions, filenames),
-    };
-  } catch (error) {
-    console.error("ImageExporter: Error in captureImage", error);
-    return { dataURL: "", fileName: "" };
-  }
-}
-
-const filter = (node: Node) => {
-  // Check if the node is an HTMLElement
-  if (node instanceof HTMLElement) {
-    return !node.hasAttribute("data-ignore-capture");
-  }
-  // If not an HTMLElement, return true to include the node
-  return true;
-};

package/src/capture/determine-total-elements.ts

@@ -1,40 +0,0 @@
-/**
- * determineTotalElements
- *
- * Just used for progress logging to show progress of all element captures.
- *
- * This emcompasses multi-scale captures unlike elements.length.
- */
-export async function determineTotalElements(
-  elements: HTMLElement[] | NodeListOf<HTMLElement>
-): Promise<number> {
-  try {
-    let totalElements = 0;
-
-    for (const element of elements) {
-      const scaleAsString = element.dataset.scale;
-      if (!scaleAsString) continue;
-
-      if (scaleAsString.includes(",")) {
-        const scales = scaleAsString
-          .trim()
-          .split(",")
-          .map((scale) => parseFloat(scale));
-
-        if (scales.some((scale) => isNaN(scale))) continue;
-        totalElements += scales.length;
-      } else {
-        const scaleAsNumber = parseFloat(scaleAsString.trim());
-        if (isNaN(scaleAsNumber)) {
-          continue;
-        } else {
-          totalElements++;
-        }
-      }
-    }
-
-    return totalElements;
-  } catch (error) {
-    return 1;
-  }
-}

package/src/capture/download-images.ts

@@ -1,69 +0,0 @@
-import { Config, Image, Label } from "../types";
-import download from "downloadjs";
-import JSZip from "jszip";
-
-/**
- * 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 async function downloadImages(images: Image[], config: Config) {
-  if (images.length === 1) {
-    const image = images[0];
-
-    await download(image.dataURL, image.fileName);
-  } else if (images.length > 1) {
-    const imagesBlob = await zipUpImages(images);
-    if (imagesBlob) await download(imagesBlob, parseLabel(config));
-  }
-}
-
-/**
- * zipUpImages
- *
- * Zips up the images and returns the zip file as a Blob.
- */
-async function zipUpImages(images: Image[]): Promise<Blob | undefined> {
-  const zip = new JSZip();
-
-  try {
-    // Loop through each image tuple and add to the zip
-    images.forEach((image) => {
-      // Extract the content from the data URL
-      const content = image.dataURL.split(",")[1]; // Assumes base64 encoding
-      zip.file(image.fileName, content, { base64: true });
-    });
-  } catch (error) {
-    console.error("Image Exporter - Error adding images to ZIP:", error);
-    return;
-  }
-
-  try {
-    // Generate the ZIP file
-    const imagesBlob = await zip.generateAsync({ type: "blob" });
-    return imagesBlob;
-  } catch (error) {
-    console.error("Image Exporter - Error generating ZIP:", error);
-    return;
-  }
-}
-
-/**
- * parseLabel
- *
- * Parses the zip label from the config and returns a valid label.
- */
-function parseLabel(config: Config): Label {
-  try {
-    // Replace spaces with dashes
-    let label = config.zipLabel;
-    label = label.replace(/\s+/g, "-");
-    // Allowed characters: a-z, A-Z, 0-9, -, _
-    return label.replace(/[^a-zA-Z0-9-_]/g, "");
-  } catch (error) {
-    console.error(error);
-    return "images";
-  }
-}

package/src/capture/get-image-options.ts

@@ -1,207 +0,0 @@
-import {
-  Quality,
-  Label,
-  Config,
-  Format,
-  ImageOptions,
-  Scale,
-  IncludeScaleInLabel,
-} 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 async function getImageOptions(
-  element: HTMLElement,
-  config: Config
-): Promise<ImageOptions> {
-  return {
-    label: parseLabel(),
-    format: parseFormat(),
-    scale: parseScale(),
-    quality: parseQuality(),
-    includeScaleInLabel: parseIncludeScaleInLabel(),
-  };
-  /**
-   * # Helper functions
-   *
-   * Format:
-   *
-   * 1. Attempt to get value from dataset
-   * 2. If found, process to correct data type and return it
-   * 3. If not found, return value from config
-   *
-   * If dataset value is invalid, returns default value.
-   */
-
-  /**
-   * Parses the label property from the element's dataset.
-   * If the property is not present, it returns the default value from the config.
-   * If the property is present, it removes any characters that are not a-z, A-Z, 0-9, -, or _ and returns the cleaned up label.
-   * If an error occurs, it returns the default value from the config.
-   */
-  function parseLabel(): Label {
-    try {
-      const label = element.dataset.label || config.defaultImageLabel;
-
-      if (label === "") return config.defaultImageLabel;
-
-      // Check if the label ends with '@#x'
-      const endsWithSpecial = /@\d+x$/.test(label);
-      let cleanedLabel = label;
-
-      // Allowed characters: a-z, A-Z, 0-9, -, _
-      // Remove all other characters using regex, except '@Nx' at the end
-      const regex = /[^a-zA-Z0-9-_]/g;
-      if (endsWithSpecial) {
-        const match = label.match(/@\d+x$/);
-        if (!match) return config.defaultImageLabel;
-        cleanedLabel = label.slice(0, -match[0].length).replace(regex, "") + match[0];
-      } else {
-        cleanedLabel = label.replace(regex, "");
-      }
-
-      return cleanedLabel;
-    } catch (error) {
-      console.error(error);
-      return config.defaultImageLabel;
-    }
-  }
-
-  /**
-   * Parses the format property from the element's dataset.
-   * If the property is not present, it returns the default value from the config.
-   * If the property is present, it checks if it's a valid format (jpg, png, or svg) and returns it.
-   * If the value is not valid, it throws an error and returns the default value from the config.
-   */
-  function parseFormat(): Format {
-    try {
-      let format = element.dataset.format || config.format;
-      format = format.trim().toLowerCase();
-      if (format === "jpg" || format === "png" || format === "svg" || format === "webp") {
-        return format;
-      } else {
-        throw new Error(
-          `ImageExporter: provided format is not valid.
-            Provided: ${format}
-            Element: ${element}
-            Accepted values: jpg, png, svg, 
-            Defaulting to: ${config.format}`
-        );
-      }
-    } catch (error) {
-      console.error(error);
-      return config.format;
-    }
-  }
-
-  /**
-   * Parses the scale property from the element's dataset.
-   * If the property is not present, it returns the default value from the config.
-   * If the property is present, it checks if it's a valid number or a comma-separated list of numbers and returns it.
-   * If the value is not valid, it throws an error and returns the default value from the config.
-   */
-  function parseScale(): Scale {
-    try {
-      const scaleAsString = element.dataset.scale;
-      if (!scaleAsString) return config.scale;
-      if (scaleAsString.includes(",")) {
-        const scales = scaleAsString
-          .trim()
-          .split(",")
-          .map((scale) => parseFloat(scale));
-        if (scales.some((scale) => isNaN(scale))) {
-          throw new Error(
-            `ImageExporter: provided scale is not valid.
-            Provided: ${scaleAsString}
-            Element: ${element}
-            Accepted values: number or csv numbers e.g. (1,2)
-            Defaulting to ${config.scale}`
-          );
-        }
-        return scales;
-      } else {
-        const scaleAsNumber = parseFloat(scaleAsString.trim());
-        if (isNaN(scaleAsNumber)) {
-          throw new Error(
-            `ImageExporter: provided scale is not valid.
-            Provided: ${scaleAsString}
-            Element: ${element}
-            Accepted values: number or csv numbers e.g. (1,2)
-            Defaulting to: ${config.scale}`
-          );
-        }
-        return scaleAsNumber;
-      }
-    } catch (error) {
-      console.error(error);
-      return config.scale;
-    }
-  }
-
-  /**
-   * Parses the quality property from the element's dataset.
-   * If the property is not present, it returns the default value from the config.
-   * If the property is present, it checks if it's a valid number and returns it.
-   * If the value is not valid, it throws an error and returns the default value from the config.
-   */
-  function parseQuality(): Quality {
-    try {
-      const qualityAsString = element.dataset.quality;
-      if (!qualityAsString) return config.quality;
-      const qualityAsNumber = parseFloat(qualityAsString.trim());
-      if (isNaN(qualityAsNumber)) {
-        throw new Error(
-          `ImageExporter: provided quality is not valid.
-            Provided: ${qualityAsString}
-            Element: ${element}
-            Accepted values: number
-            Defaulting to: ${config.quality}`
-        );
-      }
-      return qualityAsNumber;
-    } catch (error) {
-      console.error(error);
-      return config.quality;
-    }
-  }
-
-  /**
-   * Parses the includeScaleInLabel property from the element's dataset.
-   * If the property is not present, it returns the default value from the config.
-   * If the property is present, it checks if it's a valid value (true or false) and returns it.
-   * If the value is not valid, it throws an error and returns the default value from the config.
-   */
-  function parseIncludeScaleInLabel(): IncludeScaleInLabel {
-    try {
-      let includeScaleInLabel = element.dataset.includeScaleInLabel;
-      if (!includeScaleInLabel) return config.includeScaleInLabel;
-
-      includeScaleInLabel = includeScaleInLabel.trim();
-
-      if (includeScaleInLabel === "true" || includeScaleInLabel === "false") {
-        return includeScaleInLabel === "true";
-      } else {
-        throw new Error(
-          `ImageExporter: provided includeScaleInLabel is not valid.
-            Provided: ${includeScaleInLabel}
-            Element: ${element}
-            Accepted values: true or false
-            Defaulting to: ${config.includeScaleInLabel}`
-        );
-      }
-    } catch (error) {
-      console.error(error);
-      return config.includeScaleInLabel;
-    }
-  }
-}

package/src/capture/handle-filenames.ts

@@ -1,54 +0,0 @@
-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 function handleFileNames(imageOptions: ImageOptions, filenames: string[]): Label {
-  // Finish altering filenames before checking for uniqueness
-  let proposedFilename = imageOptions.label;
-  // Add scale to filename if includeScaleInLabel is true
-  if (imageOptions.includeScaleInLabel) proposedFilename += `_@${imageOptions.scale}x`;
-  // Add format to filename last
-  const extension = `.${imageOptions.format}`;
-  proposedFilename += extension;
-
-  // If filename is unique, add it to array and return as-is
-  if (!filenames.includes(proposedFilename)) {
-    filenames.push(proposedFilename);
-    return proposedFilename;
-  }
-
-  // Check if filename already ends with -n pattern
-  const numberPattern = /-(\d+)$/;
-  const match = proposedFilename.match(numberPattern);
-
-  if (match) {
-    // File ends with -n, increment the number until we find a unique name
-    const baseFilename = proposedFilename.replace(numberPattern, "");
-    let counter = parseInt(match[1], 10);
-
-    while (filenames.includes(`${baseFilename}-${counter}${extension}`)) {
-      counter++;
-    }
-
-    const newFilename = `${baseFilename}-${counter}${extension}`;
-    filenames.push(newFilename);
-    return newFilename;
-  } else {
-    // File doesn't end with -n, start with -2 and increment if needed
-    const baseFilename = proposedFilename.replace(extension, "");
-    let counter = 2;
-    while (filenames.includes(`${baseFilename}-${counter}${extension}`)) {
-      counter++;
-    }
-
-    const newFilename = `${baseFilename}-${counter}${extension}`;
-    filenames.push(newFilename);
-    return newFilename;
-  }
-}

package/src/capture/index.ts

@@ -1,102 +0,0 @@
-import { captureElement } from "./capture-element";
-import { downloadImages } from "./download-images";
-import { corsProxy } from "../cors-proxy";
-import { Config, Image, ParsedImageOptions } from "../types";
-import { getImageOptions } from "./get-image-options";
-import { defaultConfig } from "../config";
-import { removeHiddenElements } from "./remove-hidden-elements";
-import { log } from "../logger";
-import { determineTotalElements } from "./determine-total-elements";
-
-export let windowLogging = true;
-export let loggingLevel = "none";
-
-/**
- * capture
- *
- * Captures images from HTML elements and returns them or downloads them.
- */
-export async function capture(
-  elements: HTMLElement[] | NodeListOf<HTMLElement> | HTMLElement,
-  userConfig: Partial<Config> = defaultConfig
-): Promise<Image[] | null> {
-  log.group.open("image-exporter");
-  try {
-    /* --------------------------------- Config --------------------------------- */
-    const config = { ...defaultConfig, ...userConfig };
-    windowLogging = config.enableWindowLogging;
-    loggingLevel = config.loggingLevel;
-    log.verbose("config", config);
-
-    /** If the user provided a single element, convert it to an array */
-    if (elements instanceof HTMLElement) elements = [elements];
-    const originalLength = elements.length;
-    elements = removeHiddenElements(elements);
-
-    const totalElements = await determineTotalElements(elements);
-
-    if (originalLength !== elements.length)
-      log.verbose(
-        "Skipping capture of hidden elements: ",
-        originalLength - elements.length
-      );
-    log.verbose("Element to capture", elements.length);
-
-    /* ------------------------------- CORS proxy ------------------------------- */
-    if (userConfig.corsProxyBaseUrl) await corsProxy.run(config, elements);
-
-    /* --------------------------------- Capture -------------------------------- */
-    let images: Image[] = [];
-    let filenames: string[] = [];
-    let imageNumber = 1;
-
-    for (const element of elements) {
-      const imageOptions = await getImageOptions(element, config);
-      log.verbose("Image options", imageOptions);
-
-      if (imageOptions.scale instanceof Array) {
-        /* --------------------------- Multi-scale capture -------------------------- */
-        log.verbose("Multi-scale capture");
-
-        imageOptions.includeScaleInLabel = true;
-
-        for (const scale of imageOptions.scale) {
-          log.progress(imageNumber++, totalElements);
-          const image = await captureElement(
-            element,
-            { ...imageOptions, scale: scale } as ParsedImageOptions,
-            filenames
-          );
-
-          images.push(image);
-        }
-      } else if (typeof imageOptions.scale === "number") {
-        log.progress(imageNumber++, totalElements);
-        /* -------------------------- Single scale capture -------------------------- */
-        log.verbose("Single-scale capture");
-
-        const image = await captureElement(
-          element,
-          imageOptions as ParsedImageOptions,
-          filenames
-        );
-
-        images.push(image);
-      }
-    }
-
-    /* -------------------------------- Download -------------------------------- */
-    if (userConfig.downloadImages) await downloadImages(images, config);
-
-    /* --------------------------- Clean up CORS proxy -------------------------- */
-    if (userConfig.corsProxyBaseUrl) await corsProxy.cleanUp();
-
-    /** Return images optionally */
-    return images;
-  } catch (error) {
-    log.error(error);
-    return null;
-  } finally {
-    log.group.close();
-  }
-}

package/src/capture/remove-hidden-elements.ts

@@ -1,19 +0,0 @@
-export function removeHiddenElements(
-  elements: HTMLElement[] | NodeListOf<HTMLElement>
-): HTMLElement[] {
-  elements = Array.from(elements);
-  return elements.filter((element) => isVisible(element));
-}
-
-function isVisible(element: HTMLElement): boolean {
-  const computedStyle = window.getComputedStyle(element);
-
-  return (
-    element.offsetParent !== null &&
-    element.style.display !== "none" &&
-    computedStyle.visibility === "visible" &&
-    computedStyle.opacity !== "0" &&
-    computedStyle.width !== "0" &&
-    computedStyle.height !== "0"
-  );
-}

package/src/config.ts

@@ -1,19 +0,0 @@
-import { Config, ImageOptions } from "./types";
-
-export const defaultImageOptions: ImageOptions = {
-  label: "image",
-  format: "jpg",
-  scale: 1,
-  quality: 1,
-  includeScaleInLabel: false,
-};
-
-export const defaultConfig: Config = {
-  ...defaultImageOptions,
-  downloadImages: true,
-  defaultImageLabel: "image",
-  zipLabel: "images",
-  corsProxyBaseUrl: "",
-  enableWindowLogging: true,
-  loggingLevel: "none",
-};

package/src/cors-proxy/cleanup.ts

@@ -1,43 +0,0 @@
-import { log } from "../logger";
-/**
- * cleanUpCorsProxy
- *
- * Restores the CSS and images to their original state.
- */
-export async function cleanUpCorsProxy() {
-  await restoreCSS();
-  await restoreImages();
-}
-
-async function restoreCSS() {
-  const styleElements = document.querySelectorAll("style[original-link-element]");
-
-  for (let styleElement of styleElements) {
-    const originalLinkElementHTML = decodeURIComponent(
-      styleElement.getAttribute("original-link-element")!
-    );
-
-    // Create a temporary container to parse the HTML string
-    const tempContainer = document.createElement("div");
-    tempContainer.innerHTML = originalLinkElementHTML;
-
-    // Insert the parsed HTML before the style element
-    styleElement.parentNode!.insertBefore(tempContainer.firstChild!, styleElement);
-
-    styleElement.remove();
-    log.verbose("Restored: ", originalLinkElementHTML);
-  }
-}
-
-async function restoreImages() {
-  const imageElements = document.querySelectorAll(
-    "img[original-src]"
-  ) as NodeListOf<HTMLImageElement>;
-
-  for (let imageElement of imageElements) {
-    const originalSrc = imageElement.getAttribute("original-src")!;
-    imageElement.src = originalSrc;
-    imageElement.removeAttribute("original-src");
-    log.verbose("Restored: ", originalSrc);
-  }
-}

package/src/cors-proxy/index.ts

@@ -1,7 +0,0 @@
-import { runCorsProxy } from "./run";
-import { cleanUpCorsProxy } from "./cleanup";
-
-export const corsProxy = {
-  run: runCorsProxy,
-  cleanUp: cleanUpCorsProxy,
-};

package/src/cors-proxy/is-valid-url.ts

@@ -1,22 +0,0 @@
-/**
- * isValidUrl
- *
- * Checks if a string is a valid external URL.
- */
-export function isValidUrl(string: string): boolean {
-  try {
-    const url = new URL(string);
-
-    if (url.protocol === "data:") {
-      return false;
-    }
-
-    if (url.protocol !== "http:" && url.protocol !== "https:") {
-      return false;
-    }
-
-    return true;
-  } catch (_) {
-    return false;
-  }
-}