@ecopages/image-processor 0.2.0-beta.4 → 0.2.0-beta.40

package/README.md

@@ -9,7 +9,7 @@ It provides automatic image processing (e.g. converting and compressing to WebP)
 - **Automatic Image Optimization**: Converts and compresses images to modern formats at build time.
 - **Responsive Image Generation**: Creates multiple variants for different screen sizes.
 - **Virtual Module Integration**: Type-safe imports through `ecopages:images`.
-- **Ecopages Components**: Ready-to-use HTML (`EcoImage`) and React (`EcoImage`) components.
+- **Ecopages Components**: Ready-to-use HTML, Ecopages JSX, and React (`EcoImage`) components.
 - **Multiple Layout Options**: Fixed, constrained, and full-width layouts built-in.
 
 ## Installation
@@ -70,9 +70,9 @@ import { heroImage, profilePicture } from 'ecopages:images';
 
 ### Components
 
-The plugin provides ready-to-use components for HTML (`@kitajs/html`) and React:
+The plugin provides ready-to-use components for string HTML (KitaJS), Ecopages JSX, and React.
 
-**HTML Component:**
+**HTML Component** (returns a markup string; use as a function, or in string-based JSX runtimes like KitaJS):
 
 ```typescript
 import { EcoImage } from '@ecopages/image-processor/component/html';
@@ -85,6 +85,14 @@ EcoImage({
 });
 ```
 
+**Ecopages JSX Component:**
+
+```jsx
+import { EcoImage } from '@ecopages/image-processor/component/jsx';
+
+<EcoImage {...heroImage} alt="Hero banner" layout="constrained" priority />;
+```
+
 **React Component:**
 
 ```jsx

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/image-processor",
-  "version": "0.2.0-beta.4",
+  "version": "0.2.0-beta.40",
   "description": "Image processor, transform and optimize images for web",
   "keywords": [
     "image",
@@ -11,14 +11,20 @@
   "type": "module",
   "repository": {
     "type": "git",
-    "url": "https://github.com/ecopages/ecopages.git",
+    "url": "git+https://github.com/ecopages/ecopages.git",
     "directory": "packages/processors/image-processor"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-beta.4"
+    "@ecopages/core": "0.2.0-beta.40",
+    "@ecopages/jsx": ">=0.3.0-beta.6"
+  },
+  "peerDependenciesMeta": {
+    "@ecopages/jsx": {
+      "optional": true
+    }
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-beta.4",
+    "@ecopages/file-system": "0.2.0-beta.40",
     "@ecopages/logger": "^0.2.3",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
@@ -36,6 +42,10 @@
       "default": "./src/component/html.js",
       "types": "./src/component/html.d.ts"
     },
+    "./component/jsx": {
+      "default": "./src/component/jsx.js",
+      "types": "./src/component/jsx.d.ts"
+    },
     "./component/react": {
       "default": "./src/component/react.js",
       "types": "./src/component/react.d.ts"
@@ -47,6 +57,10 @@
       "default": "./src/component/html.js",
       "types": "./src/component/html.d.ts"
     },
+    "./component/jsx.ts": {
+      "default": "./src/component/jsx.js",
+      "types": "./src/component/jsx.d.ts"
+    },
     "./component/react.ts": {
       "default": "./src/component/react.js",
       "types": "./src/component/react.d.ts"

package/src/bun-plugins.js

@@ -1,33 +1,52 @@
-import { anyCaseToCamelCase } from "./utils.js";
+/**
+ * This file contains the plugins for bundling the image specifications.
+ * @module @ecopages/image-processor/bun-plugins
+ */
+import { anyCaseToCamelCase } from './utils.js';
+/**
+ * This function creates the plugin result for the image specifications.
+ */
 function createPluginResult(exports) {
-  return {
-    contents: `${Object.entries(exports).map(([key, value]) => `export const ${anyCaseToCamelCase(key)} = ${JSON.stringify(value)};`).join("\n")}`,
-    loader: "ts"
-  };
+    return {
+        contents: `${Object.entries(exports)
+            .map(([key, value]) => `export const ${anyCaseToCamelCase(key)} = ${JSON.stringify(value)};`)
+            .join('\n')}`,
+        loader: 'ts',
+    };
 }
-function createImagePlugin(exports) {
-  return {
-    name: "ecopages:images",
-    setup(build) {
-      build.module("ecopages:images", () => createPluginResult(exports));
-    }
-  };
+/**
+ * This function creates a plugin for bundling the image specifications.
+ * https://bun.sh/docs/runtime/plugins#virtual-modules
+ * @param exports
+ * @returns
+ */
+export function createImagePlugin(exports) {
+    return {
+        name: 'ecopages:images',
+        setup(build) {
+            build.module('ecopages:images', () => createPluginResult(exports));
+        },
+    };
 }
-function createImagePluginBundler(exports) {
-  return {
-    name: "ecopages:images",
-    setup(build) {
-      build.onResolve({ filter: /^ecopages:images$/ }, () => {
-        return {
-          namespace: "ecopages-images",
-          path: "ecopages:images"
-        };
-      });
-      build.onLoad({ filter: /.*/, namespace: "ecopages-images" }, () => createPluginResult(exports));
-    }
-  };
+/**
+ * This function creates a plugin for bundling the image specifications.
+ * Due to some limitations in the bundler, we need to use a different approach.
+ * https://bun.sh/docs/runtime/plugins#virtual-modules > bun-v1.2.5
+ * (This feature is currently only available at runtime with Bun.plugin and not yet supported in the bundler, but you can mimic the behavior using onResolve and onLoad.)
+ * @param exports
+ * @returns
+ */
+export function createImagePluginBundler(exports) {
+    return {
+        name: 'ecopages:images',
+        setup(build) {
+            build.onResolve({ filter: /^ecopages:images$/ }, () => {
+                return {
+                    namespace: 'ecopages-images',
+                    path: 'ecopages:images',
+                };
+            });
+            build.onLoad({ filter: /.*/, namespace: 'ecopages-images' }, () => createPluginResult(exports));
+        },
+    };
 }
-export {
-  createImagePlugin,
-  createImagePluginBundler
-};

package/src/component/html.js

@@ -1,7 +1,13 @@
-import { renderer } from "../image-renderer.js";
-const EcoImage = (props) => {
-  return renderer.renderToString(props);
-};
-export {
-  EcoImage
+/**
+ * Image component that renders the image as a string.
+ * @module @ecopages/image-processor/component/html
+ */
+import { renderer } from '../image-renderer.js';
+/**
+ * EcoImage
+ * This component generates the image element based on the provided props as a string
+ * @param props {@link EcoImageProps}
+ */
+export const EcoImage = (props) => {
+    return renderer.renderToString(props);
 };

package/src/component/jsx.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Image component that renders as an Ecopages JSX element.
+ * @module @ecopages/image-processor/component/jsx
+ */
+import { type JsxRenderable } from '@ecopages/jsx';
+import { type EcoImageProps } from '../image-renderer.js';
+/**
+ * EcoImage
+ * This component generates the image element based on the provided props as JSX
+ * @param props {@link EcoImageProps}
+ */
+export declare const EcoImage: (props: EcoImageProps) => JsxRenderable;

package/src/component/jsx.js

@@ -0,0 +1,18 @@
+/**
+ * Image component that renders as an Ecopages JSX element.
+ * @module @ecopages/image-processor/component/jsx
+ */
+import { jsx } from '@ecopages/jsx';
+import { renderer } from '../image-renderer.js';
+/**
+ * EcoImage
+ * This component generates the image element based on the provided props as JSX
+ * @param props {@link EcoImageProps}
+ */
+export const EcoImage = (props) => {
+    const attributes = renderer.generateAttributes(props);
+    if (!attributes) {
+        return null;
+    }
+    return jsx('img', attributes);
+};

package/src/component/react.js

@@ -1,11 +1,18 @@
-import { createElement } from "react";
-import { renderer } from "../image-renderer.js";
-const EcoImage = (props) => {
-  return createElement("img", {
-    ...renderer.generateAttributesJsx(props),
-    suppressHydrationWarning: true
-  });
-};
-export {
-  EcoImage
+/**
+ * Image component that renders the image as a string.
+ * @module @ecopages/image-processor/component/react
+ */
+import { createElement } from 'react';
+import { renderer } from '../image-renderer.js';
+/**
+ * EcoImage
+ * This component generates the image element based on the provided props as JSX
+ * @param props {@link EcoImageProps}
+ * @returns
+ */
+export const EcoImage = (props) => {
+    return createElement('img', {
+        ...renderer.generateAttributesJsx(props),
+        suppressHydrationWarning: true,
+    });
 };

package/src/constants.js

@@ -1,4 +1,5 @@
-const DEFAULT_LAYOUT = "constrained";
-export {
-  DEFAULT_LAYOUT
-};
+/**
+ * Default image layout
+ * @constant "constrained"
+ */
+export const DEFAULT_LAYOUT = 'constrained';

package/src/image-plugins.js

@@ -1,33 +1,52 @@
-import { anyCaseToCamelCase } from "./utils.js";
+/**
+ * This file contains the plugins for bundling the image specifications.
+ * @module @ecopages/image-processor/image-plugins
+ */
+import { anyCaseToCamelCase } from './utils.js';
+/**
+ * This function creates the plugin result for the image specifications.
+ */
 function createPluginResult(exports) {
-  return {
-    contents: `${Object.entries(exports).map(([key, value]) => `export const ${anyCaseToCamelCase(key)} = ${JSON.stringify(value)};`).join("\n")}`,
-    loader: "ts"
-  };
+    return {
+        contents: `${Object.entries(exports)
+            .map(([key, value]) => `export const ${anyCaseToCamelCase(key)} = ${JSON.stringify(value)};`)
+            .join('\n')}`,
+        loader: 'ts',
+    };
 }
-function createImagePlugin(exports) {
-  return {
-    name: "ecopages:images",
-    setup(build) {
-      build.module("ecopages:images", () => createPluginResult(exports));
-    }
-  };
+/**
+ * This function creates a plugin for bundling the image specifications.
+ * https://bun.sh/docs/runtime/plugins#virtual-modules
+ * @param exports
+ * @returns
+ */
+export function createImagePlugin(exports) {
+    return {
+        name: 'ecopages:images',
+        setup(build) {
+            build.module('ecopages:images', () => createPluginResult(exports));
+        },
+    };
 }
-function createImagePluginBundler(exports) {
-  return {
-    name: "ecopages:images",
-    setup(build) {
-      build.onResolve({ filter: /^ecopages:images$/ }, () => {
-        return {
-          namespace: "ecopages-images",
-          path: "ecopages:images"
-        };
-      });
-      build.onLoad({ filter: /.*/, namespace: "ecopages-images" }, () => createPluginResult(exports));
-    }
-  };
+/**
+ * This function creates a plugin for bundling the image specifications.
+ * Due to some limitations in the bundler, we need to use a different approach.
+ * https://bun.sh/docs/runtime/plugins#virtual-modules > bun-v1.2.5
+ * (This feature is currently only available at runtime with Bun.plugin and not yet supported in the bundler, but you can mimic the behavior using onResolve and onLoad.)
+ * @param exports
+ * @returns
+ */
+export function createImagePluginBundler(exports) {
+    return {
+        name: 'ecopages:images',
+        setup(build) {
+            build.onResolve({ filter: /^ecopages:images$/ }, () => {
+                return {
+                    namespace: 'ecopages-images',
+                    path: 'ecopages:images',
+                };
+            });
+            build.onLoad({ filter: /.*/, namespace: 'ecopages-images' }, () => createPluginResult(exports));
+        },
+    };
 }
-export {
-  createImagePlugin,
-  createImagePluginBundler
-};

package/src/image-processor.js

@@ -1,141 +1,153 @@
-import path from "node:path";
-import { mergeProcessorOptions } from "@ecopages/core/plugins/processor";
-import { fileSystem } from "@ecopages/file-system";
-import { Logger } from "@ecopages/logger";
-import sharp from "sharp";
-import { ImageUtils } from "./image-utils.js";
-const appLogger = new Logger("[@ecopages/image-processor]", {
-  debug: process.env.ECOPAGES_LOGGER_DEBUG === "true"
+import path from 'node:path';
+import { mergeProcessorOptions } from '@ecopages/core/plugins/processor';
+import { fileSystem } from '@ecopages/file-system';
+import { Logger } from '@ecopages/logger';
+import sharp from 'sharp';
+import { ImageUtils } from './image-utils.js';
+const appLogger = new Logger('[@ecopages/image-processor]', {
+    debug: process.env.ECOPAGES_LOGGER_DEBUG === 'true',
 });
-class ImageProcessor {
-  config;
-  cacheManager;
-  constructor(config, cacheManager) {
-    this.config = mergeProcessorOptions({ cacheEnabled: true }, config);
-    this.cacheManager = cacheManager;
-    fileSystem.ensureDir(this.config.outputDir);
-  }
-  async calculateDimensions(metadata, targetWidth) {
-    const originalWidth = metadata.width || 0;
-    const originalHeight = metadata.height || 0;
-    const aspectRatio = originalHeight / originalWidth;
-    const width = Math.min(targetWidth, originalWidth);
-    const height = Math.round(width * aspectRatio);
-    return { width, height };
-  }
-  getOutputPath(imagePath, width) {
-    const hash = fileSystem.hash(imagePath);
-    const ext = path.extname(imagePath);
-    const base = path.basename(imagePath, ext);
-    const filename = `${base}-${hash}-${width}.${this.config.format}`;
-    return path.join(this.config.outputDir, filename);
-  }
-  async processImage(imagePath) {
-    try {
-      const fileHash = fileSystem.hash(imagePath);
-      const cacheKey = `${path.basename(imagePath)}:${fileHash}`;
-      if (this.config.cacheEnabled) {
-        const cached = await this.cacheManager.readCache(cacheKey);
-        if (cached) {
-          const mainFilePath = path.join(process.cwd(), cached.attributes.src);
-          const mainFileExists = fileSystem.exists(mainFilePath);
-          const variantsExist = cached.variants.every(
-            (v) => fileSystem.exists(path.join(process.cwd(), v.src))
-          );
-          if (mainFileExists && variantsExist) {
-            appLogger.debug(`Cache hit for ${imagePath}`);
-            return cached;
-          }
-          appLogger.debug(`Cache invalid for ${imagePath}, reprocessing`);
+/**
+ * ImageProcessor
+ * This is the core class for processing images.
+ * It uses the sharp library to resize and optimize images.
+ */
+export class ImageProcessor {
+    config;
+    cacheManager;
+    constructor(config, cacheManager) {
+        this.config = mergeProcessorOptions({ cacheEnabled: true }, config);
+        this.cacheManager = cacheManager;
+        fileSystem.ensureDir(this.config.outputDir);
+    }
+    async calculateDimensions(metadata, targetWidth) {
+        const originalWidth = metadata.width || 0;
+        const originalHeight = metadata.height || 0;
+        const aspectRatio = originalHeight / originalWidth;
+        const width = Math.min(targetWidth, originalWidth);
+        const height = Math.round(width * aspectRatio);
+        return { width, height };
+    }
+    getOutputPath(imagePath, width) {
+        const hash = fileSystem.hash(imagePath);
+        const ext = path.extname(imagePath);
+        const base = path.basename(imagePath, ext);
+        const filename = `${base}-${hash}-${width}.${this.config.format}`;
+        return path.join(this.config.outputDir, filename);
+    }
+    async processImage(imagePath) {
+        try {
+            const fileHash = fileSystem.hash(imagePath);
+            const cacheKey = `${path.basename(imagePath)}:${fileHash}`;
+            if (this.config.cacheEnabled) {
+                const cached = await this.cacheManager.readCache(cacheKey);
+                if (cached) {
+                    const mainFilePath = path.join(this.config.outputDir, path.basename(cached.attributes.src));
+                    const mainFileExists = fileSystem.exists(mainFilePath);
+                    const variantsExist = cached.variants.every((variant) => fileSystem.exists(path.join(this.config.outputDir, path.basename(variant.src))));
+                    if (mainFileExists && variantsExist) {
+                        appLogger.debug(`Cache hit for ${imagePath}`);
+                        return cached;
+                    }
+                    appLogger.debug(`Cache invalid for ${imagePath}, reprocessing`);
+                }
+            }
+            fileSystem.ensureDir(this.config.outputDir);
+            const metadata = await sharp(imagePath).metadata();
+            const originalWidth = metadata.width || 0;
+            const originalHeight = metadata.height || 0;
+            if (this.config.sizes.length === 0) {
+                const outputPath = this.getOutputPath(imagePath, originalWidth);
+                if (fileSystem.exists(outputPath)) {
+                    appLogger.debug(`Using existing file for ${imagePath}`);
+                }
+                else {
+                    await sharp(imagePath)
+                        .toFormat(this.config.format, { quality: this.config.quality })
+                        .toFile(outputPath);
+                }
+                const src = path.join(this.config.publicPath, path.basename(outputPath));
+                const imageSpecifications = {
+                    attributes: {
+                        src,
+                        width: originalWidth,
+                        height: originalHeight,
+                        sizes: '',
+                    },
+                    variants: [],
+                    cacheKey,
+                };
+                if (this.config.cacheEnabled) {
+                    await this.cacheManager.writeCache(cacheKey, imageSpecifications);
+                }
+                return imageSpecifications;
+            }
+            let applicableSizes = this.config.sizes
+                .filter((size) => size.width <= originalWidth)
+                .sort((a, b) => b.width - a.width);
+            if (applicableSizes.length === 0) {
+                applicableSizes = this.config.sizes.sort((a, b) => b.width - a.width).slice(0, 1);
+            }
+            const variants = await Promise.all(applicableSizes.map(async ({ width: targetWidth, label }) => {
+                const { width, height } = await this.calculateDimensions(metadata, targetWidth);
+                const outputPath = this.getOutputPath(imagePath, width);
+                if (fileSystem.exists(outputPath)) {
+                    appLogger.debug(`Variant ${width}px already exists for ${imagePath}`);
+                }
+                else {
+                    await sharp(imagePath)
+                        .resize(width, height)
+                        .toFormat(this.config.format, { quality: this.config.quality })
+                        .toFile(outputPath);
+                }
+                const src = path.join(this.config.publicPath, path.basename(outputPath));
+                return {
+                    width,
+                    height,
+                    src,
+                    label,
+                };
+            }));
+            const mainVariant = variants[0];
+            const attributes = {
+                src: mainVariant.src,
+                width: mainVariant.width,
+                height: mainVariant.height,
+                sizes: ImageUtils.generateSizes(variants),
+                srcset: ImageUtils.generateSrcset(variants),
+            };
+            const imageSpecifications = {
+                attributes,
+                variants,
+                cacheKey,
+            };
+            if (this.config.cacheEnabled) {
+                await this.cacheManager.writeCache(cacheKey, imageSpecifications);
+            }
+            return imageSpecifications;
         }
-      }
-      fileSystem.ensureDir(this.config.outputDir);
-      const metadata = await sharp(imagePath).metadata();
-      const originalWidth = metadata.width || 0;
-      const originalHeight = metadata.height || 0;
-      if (this.config.sizes.length === 0) {
-        const outputPath = this.getOutputPath(imagePath, originalWidth);
-        if (fileSystem.exists(outputPath)) {
-          appLogger.debug(`Using existing file for ${imagePath}`);
-        } else {
-          await sharp(imagePath).toFormat(this.config.format, { quality: this.config.quality }).toFile(outputPath);
+        catch (error) {
+            appLogger.error(`Failed to process image ${imagePath}:`, error);
+            return null;
+        }
+    }
+    async processDirectory() {
+        const acceptedFormats = this.config.acceptedFormats || ['jpg', 'jpeg', 'png', 'webp'];
+        const images = await fileSystem.glob([`${this.config.sourceDir}/**/*.{${acceptedFormats.join(',')}}`]);
+        appLogger.debugTime('Processing images');
+        const results = (await Promise.all(images.map(async (file) => {
+            const processed = await this.processImage(file);
+            if (!processed)
+                return null;
+            return [path.basename(file), processed];
+        }))).filter(Boolean);
+        appLogger.debugTimeEnd('Processing images');
+        if (process.env.ECOPAGES_BENCH === '1' && process.env.ECOPAGES_BENCH_VERBOSE !== '1') {
+            appLogger.debug(`Processed ${results.length} images`);
         }
-        const src = path.join(this.config.publicPath, path.basename(outputPath));
-        const imageSpecifications2 = {
-          attributes: {
-            src,
-            width: originalWidth,
-            height: originalHeight,
-            sizes: ""
-          },
-          variants: [],
-          cacheKey
-        };
-        if (this.config.cacheEnabled) {
-          await this.cacheManager.writeCache(cacheKey, imageSpecifications2);
+        else {
+            appLogger.info(`Processed ${results.length} images`);
         }
-        return imageSpecifications2;
-      }
-      let applicableSizes = this.config.sizes.filter((size) => size.width <= originalWidth).sort((a, b) => b.width - a.width);
-      if (applicableSizes.length === 0) {
-        applicableSizes = this.config.sizes.sort((a, b) => b.width - a.width).slice(0, 1);
-      }
-      const variants = await Promise.all(
-        applicableSizes.map(async ({ width: targetWidth, label }) => {
-          const { width, height } = await this.calculateDimensions(metadata, targetWidth);
-          const outputPath = this.getOutputPath(imagePath, width);
-          if (fileSystem.exists(outputPath)) {
-            appLogger.debug(`Variant ${width}px already exists for ${imagePath}`);
-          } else {
-            await sharp(imagePath).resize(width, height).toFormat(this.config.format, { quality: this.config.quality }).toFile(outputPath);
-          }
-          const src = path.join(this.config.publicPath, path.basename(outputPath));
-          return {
-            width,
-            height,
-            src,
-            label
-          };
-        })
-      );
-      const mainVariant = variants[0];
-      const attributes = {
-        src: mainVariant.src,
-        width: mainVariant.width,
-        height: mainVariant.height,
-        sizes: ImageUtils.generateSizes(variants),
-        srcset: ImageUtils.generateSrcset(variants)
-      };
-      const imageSpecifications = {
-        attributes,
-        variants,
-        cacheKey
-      };
-      if (this.config.cacheEnabled) {
-        await this.cacheManager.writeCache(cacheKey, imageSpecifications);
-      }
-      return imageSpecifications;
-    } catch (error) {
-      appLogger.error(`Failed to process image ${imagePath}:`, error);
-      return null;
+        return Object.fromEntries(results);
     }
-  }
-  async processDirectory() {
-    const acceptedFormats = this.config.acceptedFormats || ["jpg", "jpeg", "png", "webp"];
-    const images = await fileSystem.glob([`${this.config.sourceDir}/**/*.{${acceptedFormats.join(",")}}`]);
-    appLogger.debugTime("Processing images");
-    const results = (await Promise.all(
-      images.map(async (file) => {
-        const processed = await this.processImage(file);
-        if (!processed) return null;
-        return [path.basename(file), processed];
-      })
-    )).filter(Boolean);
-    appLogger.debugTimeEnd("Processing images");
-    appLogger.info(`Processed ${results.length} images`);
-    return Object.fromEntries(results);
-  }
 }
-export {
-  ImageProcessor
-};