Image Data Generation

/**
 * Generates modern Gatsby image data compatible with gatsby-plugin-image
 * @param options - Configuration object
 * @param options.file - FileNode representing the source image
 * @param options.args - Sharp Gatsby image arguments
 * @param options.pathPrefix - URL path prefix for generated images
 * @param options.reporter - Gatsby reporter instance
 * @param options.cache - Gatsby cache instance for optimization
 * @returns Promise resolving to IGatsbyImageData or undefined if processing fails
 */
function generateImageData(options: {
  file: FileNode;
  args: ISharpGatsbyImageArgs;
  pathPrefix: string;
  reporter: Reporter;
  cache: GatsbyCache;
}): Promise<IGatsbyImageData | undefined>;

interface IGatsbyImageData {
  layout: "fixed" | "fullWidth" | "constrained";
  placeholder?: {
    fallback: string; // Base64 or dominant color placeholder
  };
  backgroundColor?: string;
  width?: number;
  height?: number;
  images: {
    fallback: {
      src: string;
      srcSet: string;
      sizes: string;
    };
    sources: Array<{
      srcSet: string;
      type: string;
      sizes: string;
    }>;
  };
}

import { generateImageData } from "gatsby-plugin-sharp";

// Generate responsive image data
const imageData = await generateImageData({
  file: fileNode,
  args: {
    layout: "constrained",
    width: 800,
    placeholder: "blurred",
    formats: ["auto", "webp", "avif"]
  },
  pathPrefix: "/",
  reporter,
  cache
});

// Generate fixed-size image data
const fixedImageData = await generateImageData({
  file: fileNode,
  args: {
    layout: "fixed",
    width: 400,
    height: 300,
    placeholder: "dominantColor",
    formats: ["auto", "webp"]
  },
  pathPrefix: "/static/",
  reporter,
  cache
});

// Generate full-width image data with custom breakpoints
const fullWidthImageData = await generateImageData({
  file: fileNode,
  args: {
    layout: "fullWidth",
    breakpoints: [640, 768, 1024, 1280, 1536],
    formats: ["auto", "webp", "avif"],
    quality: 85
  },
  pathPrefix: "",
  reporter,
  cache
});

/**
 * Retrieves comprehensive image metadata
 * @param file - FileNode representing the image
 * @param getDominantColor - Whether to extract dominant color (slower)
 * @param cache - Optional Gatsby cache instance
 * @returns Promise resolving to image metadata
 */
function getImageMetadata(
  file: FileNode,
  getDominantColor?: boolean,
  cache?: GatsbyCache
): Promise<IImageMetadata>;

interface IImageMetadata {
  width?: number;        // Image width in pixels
  height?: number;       // Image height in pixels
  format?: string;       // Image format (jpeg, png, webp, etc.)
  density?: number;      // Image density/DPI
  dominantColor?: string; // Hex color of dominant color
}

import { getImageMetadata } from "gatsby-plugin-sharp";

// Get basic metadata
const metadata = await getImageMetadata(fileNode);
console.log(`${metadata.width}x${metadata.height} ${metadata.format}`);

// Get metadata with dominant color
const metadataWithColor = await getImageMetadata(fileNode, true, cache);
console.log(`Dominant color: ${metadataWithColor.dominantColor}`);

interface ISharpGatsbyImageArgs {
  /** Image layout type */
  layout?: "fixed" | "fullWidth" | "constrained";
  /** Image width in pixels */
  width?: number;
  /** Image height in pixels */
  height?: number;
  /** Aspect ratio (width/height) */
  aspectRatio?: number;
  /** Placeholder type */
  placeholder?: "blurred" | "dominantColor" | "none";
  /** Output formats */
  formats?: Array<"auto" | "webp" | "avif" | "png" | "jpg">;
  /** Image quality (1-100) */
  quality?: number;
  /** Custom breakpoints for responsive images */
  breakpoints?: number[];
  /** Background color for transparent areas */
  backgroundColor?: string;
  /** Transform options */
  transformOptions?: {
    fit?: "cover" | "contain" | "fill" | "inside" | "outside";
    cropFocus?: "center" | "top" | "bottom" | "left" | "right" | "attention" | "entropy";
    grayscale?: boolean;
    duotone?: {
      highlight: string;
      shadow: string;
      opacity?: number;
    };
  };
  /** Format-specific options */
  jpgOptions?: {
    quality?: number;
    progressive?: boolean;
  };
  pngOptions?: {
    quality?: number;
    compressionLevel?: number;
  };
  webpOptions?: {
    quality?: number;
  };
  avifOptions?: {
    quality?: number;
  };
  /** Blurred placeholder options */
  blurredOptions?: {
    width?: number;
    toFormat?: "png" | "jpg" | "webp";
  };
}

const imageData = await generateImageData({
  file: fileNode,
  args: {
    layout: "fullWidth",
    breakpoints: [480, 768, 1024, 1200, 1600], // Custom responsive breakpoints
    formats: ["auto", "webp"]
  },
  pathPrefix: "/",
  reporter,
  cache
});

const imageData = await generateImageData({
  file: fileNode,
  args: {
    layout: "constrained",
    width: 800,
    quality: 85, // Global quality
    jpgOptions: { quality: 90, progressive: true }, // JPEG-specific
    webpOptions: { quality: 80 }, // WebP-specific
    avifOptions: { quality: 75 }  // AVIF-specific
  },
  pathPrefix: "/",
  reporter,
  cache
});

const imageData = await generateImageData({
  file: fileNode,
  args: {
    layout: "constrained",
    width: 600,
    transformOptions: {
      fit: "cover",
      cropFocus: "attention", // AI-powered crop focus
      grayscale: true,
      duotone: {
        highlight: "#0066cc",
        shadow: "#003366",
        opacity: 0.8
      }
    }
  },
  pathPrefix: "/",
  reporter,
  cache
});