@place-framework/place-block-image 1.0.1 → 1.0.2

package/src/utils/index.ts

@@ -1,53 +1,130 @@
-// Shared template utilities
+// Shared utilities
 
-export interface TemplateData {
-  imagePrefix: string;
-  baseClassName: string;
-  wrapperClassName: string;
+import { CLASS_NAMES } from '../constants/index';
+
+/**
+ * Converts any image URL or path into a CSS-safe kebab-case string.
+ * Used at build time by generateImageClassName() and at runtime by
+ * the Vue/React components to derive the CSS class from the src prop.
+ */
+export const cleanImagePath = (src: string): string =>
+  src
+    .replace(/^https?:\/\/[^/]+/, '') // Strip protocol + domain
+    .replace(/^[/\\]+/, '')            // Strip leading slashes
+    .replace(/\.[^/.]+$/, '')          // Remove file extension
+    .toLowerCase()
+    .replace(/[^a-z0-9/-]/g, '-')      // Special chars → hyphens (keep / and -)
+    .replace(/\//g, '-')               // Path separators → hyphens
+    .replace(/-+/g, '-')               // Collapse duplicate hyphens
+    .replace(/^-|-$/g, '');            // Trim leading/trailing hyphens
+
+/**
+ * Generate CSS class name from a file path — path-agnostic, works with any URL format.
+ * Matches the runtime getImageClassName logic emitted by getSharedLogic().
+ *
+ * @param filePath     - Relative path from imageDir (e.g. "story/accent-orchid.png")
+ * @param imagePrefix  - The prefix to add to the class name (e.g. "image-")
+ * @param outputPrefix - Optional output path prefix prepended before filePath to mirror
+ *                       the served URL (e.g. "images/" when assetModuleFilename outputs
+ *                       to "images/…" so the browser requests "/images/story/…")
+ * @returns The generated CSS class name (e.g. "image-images-story-accent-orchid")
+ */
+export function generateImageClassName(
+  filePath: string,
+  imagePrefix: string,
+  outputPrefix: string = ''
+): string {
+  const fullPath = outputPrefix
+    ? `${outputPrefix.replace(/\/$/, '')}/${filePath}`
+    : filePath;
+
+  return `${imagePrefix}${cleanImagePath(fullPath)}`;
 }
 
-export function getTemplateData(imagePrefix: string): TemplateData {
-  return {
-    imagePrefix,
-    baseClassName: `${imagePrefix}block`,
-    wrapperClassName: `${imagePrefix}wrapper`
-  };
+/**
+ * Strips the Vite/webpack plugin's injected asset-path prefix from a src string
+ * so the remaining path matches what the plugin used when generating CSS classes.
+ *
+ * @param src       - The raw src value (may include the asset path prefix)
+ * @param assetPath - The value of __PLUGIN_ASSET_PATH__ (empty string if undefined)
+ */
+export function resolveAssetPath(src: string, assetPath: string): string {
+  if (!assetPath) return src;
+  return src.replace(new RegExp(`^${assetPath.replace(/\//g, '\\/')}\\/?`), '');
 }
 
 /**
- * Generate CSS class name from file path - shared logic for both webpack plugin and templates
- * @param filePath - The file path (can be relative path from images dir or full path)
- * @param imagePrefix - The prefix to add to the class name
- * @returns The generated CSS class name
+ * Derives the per-image CSS class from a src URL, stripping the asset-path
+ * prefix first so the class matches what the plugin generated at build time.
+ *
+ * @param src         - Raw src prop value
+ * @param imagePrefix - e.g. "image-"
+ * @param assetPath   - Value of __PLUGIN_ASSET_PATH__ (pass '' if not defined)
  */
-export function generateImageClassName(filePath: string, imagePrefix: string): string {
-  // Remove file extension and convert to kebab-case
-  const cleanName = filePath
-    .replace(/\.[^/.]+$/, '') // Remove file extension
-    .toLowerCase()
-    .replace(/[^a-z0-9-]/g, '-') // Convert special chars to hyphens
-    .replace(/-+/g, '-') // Remove duplicate hyphens
-    .replace(/^-|-$/g, ''); // Remove leading/trailing hyphens
-  
-  return `${imagePrefix}${cleanName}`;
+export function getImageClass(src: string, imagePrefix: string, assetPath: string): string {
+  if (!src) return '';
+  return `${imagePrefix}${cleanImagePath(resolveAssetPath(src, assetPath))}`;
+}
+
+/**
+ * Builds the full className string for the <picture> wrapper element.
+ *
+ * @param src         - Raw src prop value
+ * @param imagePrefix - e.g. "image-"
+ * @param assetPath   - Value of __PLUGIN_ASSET_PATH__ (pass '' if not defined)
+ * @param extraClass  - Any additional class(es) passed by the consumer (e.g. className prop)
+ */
+export function getWrapperClass(
+  src: string,
+  imagePrefix: string,
+  assetPath: string,
+  extraClass: string = ''
+): string {
+  const parts = [
+    `${imagePrefix}${CLASS_NAMES.WRAPPER_SUFFIX}`,
+    getImageClass(src, imagePrefix, assetPath),
+    extraClass,
+  ].filter(Boolean);
+  return parts.join(' ');
+}
+
+/**
+ * Returns the CSS class string for the <img> element based on lazy-load state.
+ *
+ * @param lazy     - Whether lazy loading is enabled
+ * @param isLoaded - Whether the image has been loaded (intersected)
+ */
+export function getLazyClass(lazy: boolean, isLoaded: boolean): string {
+  if (!lazy) return '';
+  return isLoaded ? `${CLASS_NAMES.LAZY} ${CLASS_NAMES.LOADED}` : CLASS_NAMES.LAZY;
+}
+
+/**
+ * Creates an IntersectionObserver that fires `onIntersect` once when the given
+ * element enters the viewport, then automatically stops observing.
+ *
+ * @param element      - The DOM element to observe
+ * @param onIntersect  - Callback invoked when the element intersects
+ * @param threshold    - Intersection threshold (default 0.1)
+ * @returns The created IntersectionObserver (call .disconnect() to clean up early)
+ */
+export function createLazyObserver(
+  element: Element,
+  onIntersect: () => void,
+  threshold: number = 0.1
+): IntersectionObserver {
+  const observer = new IntersectionObserver(
+    (entries) => {
+      entries.forEach((entry) => {
+        if (entry.isIntersecting) {
+          onIntersect();
+          observer.unobserve(entry.target);
+        }
+      });
+    },
+    { threshold }
+  );
+  observer.observe(element);
+  return observer;
 }
 
-export function getSharedLogic(imagePrefix: string): string {
-  return `
-  // Extract filename from src to generate class name
-  const getImageClassName = (imageSrc) => {
-    // Remove /images/ prefix and file extension, convert to kebab-case
-    const filename = imageSrc
-      .replace(/^.*\\/images\\//, '') // Remove path up to /images/
-      .replace(/\\.[^/.]+$/, '') // Remove file extension
-      .toLowerCase()
-      .replace(/[^a-z0-9-]/g, '-') // Convert special chars to hyphens
-      .replace(/-+/g, '-') // Remove duplicate hyphens
-      .replace(/^-|-$/g, ''); // Remove leading/trailing hyphens
-    
-    return \`${imagePrefix}\${filename}\`;
-  };
-
-  const imageClassName = getImageClassName(src);
-  const wrapperClassName = \`${imagePrefix}wrapper \${imageClassName}\`;`;
-}

package/src/vue/PlaceBlockImage.vue

@@ -0,0 +1,98 @@
+<template>
+  <picture :class="[wrapperClassName, attrs.class]">
+    <img
+      ref="imgRef"
+      :src="imageSrc"
+      :alt="alt"
+      :class="imgClassName"
+      v-bind="imgAttrs"
+    />
+  </picture>
+</template>
+
+<script setup lang="ts">
+import { computed, ref, onMounted, onUnmounted, watch, useAttrs } from 'vue';
+import { getWrapperClass, getLazyClass, createLazyObserver } from '../utils/index';
+import { IMAGE_PREFIX } from '../constants/index';
+
+declare const __PLUGIN_ASSET_PATH__: string;
+
+defineOptions({ inheritAttrs: false });
+
+/**
+ * PlaceBlockImage — prevents layout shift using CSS custom properties.
+ * Import: import PlaceBlockImage from '@place-framework/place-block-image/vue'
+ *
+ * Usage:
+ *   <PlaceBlockImage src="/assets/logo.png" alt="Logo" />
+ *   <PlaceBlockImage src="/assets/hero.jpg" alt="Hero" :lazy="true" />
+ */
+
+const attrs = useAttrs();
+
+const props = defineProps({
+  src: { type: String, required: true },
+  alt: { type: String, required: true },
+  imagePrefix: { type: String, default: () => IMAGE_PREFIX },
+  lazy: { type: Boolean, default: false }
+});
+
+// All attrs except class go to the <img>
+const imgAttrs = computed(() => {
+  const { class: _, ...rest } = attrs;
+  return rest;
+});
+
+const imgRef = ref(null);
+const imageSrc = ref(props.lazy ? '' : props.src);
+const isLoaded = ref(!props.lazy);
+let observer: IntersectionObserver | null = null;
+
+const assetPath: string = typeof __PLUGIN_ASSET_PATH__ !== 'undefined' ? __PLUGIN_ASSET_PATH__ : '';
+
+const wrapperClassName = computed(() =>
+  getWrapperClass(props.src, props.imagePrefix, assetPath)
+);
+
+const imgClassName = computed(() => getLazyClass(props.lazy, isLoaded.value));
+
+const setupLazyLoading = () => {
+  if (!props.lazy || isLoaded.value || !imgRef.value) return;
+
+  observer = createLazyObserver(imgRef.value, () => {
+    imageSrc.value = props.src;
+    isLoaded.value = true;
+  });
+};
+
+const cleanupObserver = () => {
+  if (observer) {
+    observer.disconnect();
+    observer = null;
+  }
+};
+
+onMounted(() => {
+  setupLazyLoading();
+});
+
+onUnmounted(() => {
+  cleanupObserver();
+});
+
+watch(() => props.src, (newSrc) => {
+  if (!props.lazy) {
+    imageSrc.value = newSrc;
+  } else if (!isLoaded.value) {
+    cleanupObserver();
+    setupLazyLoading();
+  }
+});
+
+watch(isLoaded, (loaded) => {
+  if (loaded) {
+    imageSrc.value = props.src;
+    cleanupObserver();
+  }
+});
+</script>

package/src/vue/index.ts

@@ -0,0 +1 @@
+export { default as PlaceBlockImage } from './PlaceBlockImage.vue';

package/src/webpack-plugin.ts

@@ -2,18 +2,33 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { glob } from 'glob';
 import sizeOf from 'image-size';
-import { Compiler } from 'webpack';
-import { getTemplate } from './templates';
+import { Compiler, DefinePlugin } from 'webpack';
 import { generateImageClassName } from './utils';
 
 export interface PlaceBlockImagePluginOptions {
   imagePrefix?: string;
   imageDir: string;
   scssPath: string;
-  // Component generation options
-  componentPath?: string;
-  componentType?: 'tsx' | 'jsx' | 'vue';
-  generateComponent?: boolean;
+  /**
+   * The URL path at which images are served (e.g. '/images').
+   * Used by the webpack plugin to inject a __PLACE_ASSET_PATH__ constant
+   * that the React/Vue components use to strip the prefix from src before
+   * generating the CSS class name — ensuring it matches what the plugin
+   * generates from the file path relative to imageDir.
+   *
+   * Defaults to the basename of imageDir prefixed with '/' (e.g. '/images').
+   */
+  assetPath?: string;
+  /**
+   * Output path prefix prepended to the relative image path when generating
+   * CSS class names — must match the prefix used in assetModuleFilename so
+   * the class name the plugin writes into the SCSS matches what the component
+   * derives from the served URL at runtime.
+   *
+   * e.g. if assetModuleFilename outputs "images/story/foo.png" (served as
+   * "/images/story/foo.png"), set outputPathPrefix: 'images'
+   */
+  outputPathPrefix?: string;
 }
 
 export interface ImageDimensions {
@@ -31,8 +46,8 @@ export class PlaceBlockImagePlugin {
   constructor(options: PlaceBlockImagePluginOptions) {
     this.options = {
       imagePrefix: 'image-',
-      generateComponent: true,
-      componentType: 'tsx',
+      outputPathPrefix: '',
+      assetPath: `/${path.basename(options.imageDir)}`,
       ...options
     };
   }
@@ -41,7 +56,12 @@ export class PlaceBlockImagePlugin {
    * Generate CSS class name from filename - uses shared logic
    */
   private generateClassName(filename: string): string {
-    return generateImageClassName(filename, this.options.imagePrefix);
+    // When outputPathPrefix is set the asset output is flat (just basename),
+    // so use only the basename to mirror the served URL: /assets/accent-orchid.png
+    const name = this.options.outputPathPrefix
+      ? path.basename(filename)
+      : filename;
+    return generateImageClassName(name, this.options.imagePrefix, this.options.outputPathPrefix);
   }
 
   /**
@@ -130,35 +150,6 @@ export class PlaceBlockImagePlugin {
     fs.writeFileSync(this.options.scssPath, scssContent);
   }
 
-  /**
-   * Generate and write component file
-   */
-  private async writeComponentFile(): Promise<void> {
-    if (!this.options.generateComponent || !this.options.componentPath || !this.options.componentType) {
-      return;
-    }
-
-    const componentFileName = `PlaceBlockImage.${this.options.componentType}`;
-    const componentFilePath = path.resolve(this.options.componentPath, componentFileName);
-    
-    // Check if component already exists
-    if (fs.existsSync(componentFilePath)) {
-      console.log(`📦 Component already exists, skipping: ${componentFilePath}`);
-      return;
-    }
-
-    const componentContent = getTemplate(this.options.componentType, this.options.imagePrefix);
-    const outputDir = path.dirname(componentFilePath);
-    
-    // Ensure output directory exists
-    if (!fs.existsSync(outputDir)) {
-      fs.mkdirSync(outputDir, { recursive: true });
-    }
-    
-    fs.writeFileSync(componentFilePath, componentContent);
-    console.log(`📦 Generated component: ${componentFilePath}`);
-  }
-
   /**
    * Check if images have changed since last generation
    */
@@ -188,6 +179,21 @@ export class PlaceBlockImagePlugin {
   }
 
   apply(compiler: Compiler): void {
+    // Inject @place-block-image alias so the Vue/React source components can
+    // resolve their shared utils/constants imports without requiring the
+    // consuming app to configure anything manually.
+    const pkgSrc = path.resolve(__dirname, '../src');
+    compiler.options.resolve.alias = {
+      ...((compiler.options.resolve.alias as Record<string, string>) || {}),
+      '@place-block-image': pkgSrc,
+    };
+
+    // Inject __PLUGIN_ASSET_PATH__ so the React/Vue components can strip the
+    // served URL prefix from src before generating the CSS class name.
+    new DefinePlugin({
+      __PLUGIN_ASSET_PATH__: JSON.stringify(this.options.assetPath),
+    }).apply(compiler);
+
     // Use environment hook to run only once at startup
     compiler.hooks.environment.tap('PlaceBlockImagePlugin', () => {
       this.generateImageStyles();
@@ -240,8 +246,7 @@ export class PlaceBlockImagePlugin {
       }
 
       await this.writeScssFile(images);
-      await this.writeComponentFile();
-      
+
       console.log(`✅ Generated CSS custom properties for ${images.length} images`);
       console.log(`📝 Output: ${this.options.scssPath}`);
       

package/tsconfig.json

@@ -2,7 +2,7 @@
   "compilerOptions": {
     "target": "ES2020",
     "module": "commonjs",
-    "lib": ["ES2020"],
+    "lib": ["ES2020", "DOM"],
     "outDir": "./dist",
     "rootDir": "./src",
     "strict": true,
@@ -13,8 +13,13 @@
     "declarationMap": true,
     "sourceMap": true,
     "moduleResolution": "node",
-    "resolveJsonModule": true
+    "resolveJsonModule": true,
+    "jsx": "react",
+    "baseUrl": ".",
+    "paths": {
+      "@place-block-image/*": ["./src/*"]
+    }
   },
   "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
+  "exclude": ["node_modules", "dist", "src/vue"]
 }

package/vite.config.mts

@@ -0,0 +1,27 @@
+import { defineConfig, build, Plugin } from 'vite';
+import { vueConfig } from './vite.vue.config.mts';
+import { reactConfig } from './vite.react.config.mts';
+
+// Runs the React build once after the Vue build completes.
+// The instance-level flag prevents closeBundle from re-firing
+// when the spawned React build itself reaches closeBundle.
+function buildReact(): Plugin {
+  let done = false;
+  return {
+    name: 'build-react',
+    apply: 'build',
+    async closeBundle() {
+      if (done) return;
+      done = true;
+      await build({ configFile: false, ...reactConfig });
+    },
+  };
+}
+
+// Builds:
+//   src/vue/PlaceBlockImage.vue   → dist/vue/PlaceBlockImage.{js,cjs}   (via vite.vue.config.mts)
+//   src/react/PlaceBlockImage.tsx → dist/react/PlaceBlockImage.{js,cjs} (via vite.react.config.mts)
+export default defineConfig({
+  ...vueConfig,
+  plugins: [...(vueConfig.plugins as Plugin[]), buildReact()],
+});

package/vite.react.config.mts

@@ -0,0 +1,25 @@
+import { resolve } from 'path';
+import type { UserConfig } from 'vite';
+
+
+// Builds src/react/PlaceBlockImage.tsx → dist/react/PlaceBlockImage.{js,cjs}
+// React and its runtime are kept external — consumers supply their own.
+export const reactConfig: UserConfig = {
+  build: {
+    outDir: 'dist/react',
+    emptyOutDir: true,
+    lib: {
+      entry: resolve(__dirname, 'src/react/PlaceBlockImage.tsx'),
+      name: 'PlaceBlockImage',
+      fileName: (format: string, name: string) => (format === 'es' ? `${name}.js` : `${name}.cjs`),
+      formats: ['es', 'cjs'],
+    },
+    rollupOptions: {
+      external: ['react', 'react/jsx-runtime'],
+      output: {
+        globals: { react: 'React' },
+        exports: 'named',
+      },
+    },
+  },
+};

package/vite.vue.config.mts

@@ -0,0 +1,26 @@
+import vue from '@vitejs/plugin-vue';
+import { resolve } from 'path';
+import type { UserConfig } from 'vite';
+
+
+// Builds src/vue/PlaceBlockImage.vue → dist/vue/PlaceBlockImage.{js,cjs}
+// Vue and its runtime are kept external — consumers supply their own.
+export const vueConfig: UserConfig = {
+  plugins: [vue()],
+  build: {
+    outDir: 'dist/vue',
+    emptyOutDir: true,
+    lib: {
+      entry: resolve(__dirname, 'src/vue/PlaceBlockImage.vue'),
+      name: 'PlaceBlockImage',
+      fileName: (format: string, name: string) => (format === 'es' ? `${name}.js` : `${name}.cjs`),
+      formats: ['es', 'cjs'],
+    },
+    rollupOptions: {
+      external: ['vue'],
+      output: {
+        globals: { vue: 'Vue' },
+      },
+    },
+  },
+};

package/src/templates/react-jsx.ts

@@ -1,27 +0,0 @@
-import { getSharedReactTemplate } from './shared/react';
-
-export function getReactJsxTemplate(imagePrefix: string): string {
-  const shared = getSharedReactTemplate(imagePrefix);
-  
-  return `${shared.imports}
-
-${shared.comment}
-export const PlaceBlockImage = ({
-  src,
-  alt,
-  lazy = false,
-  className = '',
-  ...props
-}) => {
-${shared.hooks}
-
-${shared.getImageClassName}
-
-${shared.classNames}
-
-${shared.jsx}
-};
-
-${shared.export}
-`;
-}

package/src/templates/react-tsx.ts

@@ -1,33 +0,0 @@
-import { getSharedReactTemplate } from './shared/react';
-
-export function getReactTsxTemplate(imagePrefix: string): string {
-  const shared = getSharedReactTemplate(imagePrefix);
-  
-  return `${shared.imports}
-
-interface PlaceBlockImageProps extends React.ImgHTMLAttributes<HTMLImageElement> {
-  src: string;
-  alt: string;
-  lazy?: boolean;
-}
-
-${shared.comment}
-export const PlaceBlockImage: React.FC<PlaceBlockImageProps> = ({
-  src,
-  alt,
-  lazy = false,
-  className = '',
-  ...props
-}) => {
-${shared.hooks}
-
-${shared.getImageClassName}
-
-${shared.classNames}
-
-${shared.jsx}
-};
-
-${shared.export}
-`;
-}

package/src/templates/shared/index.ts

@@ -1,47 +0,0 @@
-import { CLASS_NAMES } from '../../constants';
-
-export const getSharedTemplate = (imagePrefix: string) => ({
-  // Common comment block
-  comment: `/**
- * PlaceBlockImage component that prevents layout shift using CSS custom properties
- * Generated by place-block-image webpack plugin
- * 
- * Usage:
- * <PlaceBlockImage src="/images/logo.svg" alt="Logo" />
- * <PlaceBlockImage src="/images/hero.jpg" alt="Hero" lazy={true} />
- * 
- * This will automatically apply:
- * - .${imagePrefix}wrapper class on picture (for dimensions)
- * - .${imagePrefix}logo class on picture (specific dimensions via CSS custom properties)
- * - ${CLASS_NAMES.LAZY}/${CLASS_NAMES.LAZY}.${CLASS_NAMES.LOADED} classes for lazy loading states
- */`,
-
-  // Common filename extraction logic (as string for interpolation)
-  getImageClassNameTemplate: `// Extract filename from src to generate class name
-  const getImageClassName = (imageSrc: string): string => {
-    // Remove /images/ prefix and file extension, convert to kebab-case
-    const filename = imageSrc
-      .replace(/^.*\\/images\\//, '') // Remove path up to /images/
-      .replace(/\\.[^/.]+$/, '') // Remove file extension
-      .toLowerCase()
-      .replace(/[^a-z0-9-]/g, '-') // Convert special chars to hyphens
-      .replace(/-+/g, '-') // Remove duplicate hyphens
-      .replace(/^-|-$/g, ''); // Remove leading/trailing hyphens
-    
-    return \`${imagePrefix}\${filename}\`;
-  };`,
-
-  // Common intersection observer logic
-  intersectionObserverTemplate: `const observer = new IntersectionObserver(
-      (entries) => {
-        entries.forEach((entry) => {
-          if (entry.isIntersecting) {
-            setImageSrc(src);
-            setIsLoaded(true);
-            observer.unobserve(entry.target);
-          }
-        });
-      },
-      { threshold: 0.1 }
-    );`
-});

package/src/templates/shared/react.ts

@@ -1,51 +0,0 @@
-import { getSharedTemplate } from './index';
-import { CLASS_NAMES } from '../../constants';
-
-export const getSharedReactTemplate = (imagePrefix: string) => {
-  const shared = getSharedTemplate(imagePrefix);
-  
-  return {
-    imports: `import React, { useRef, useEffect, useState } from 'react';`,
-    
-    comment: shared.comment,
-
-    hooks: `  const imgRef = useRef(null);
-  const [imageSrc, setImageSrc] = useState(lazy ? '' : src);
-  const [isLoaded, setIsLoaded] = useState(!lazy);
-
-  useEffect(() => {
-    if (!lazy || isLoaded) return;
-
-    ${shared.intersectionObserverTemplate}
-
-    if (imgRef.current) {
-      observer.observe(imgRef.current);
-    }
-
-    return () => observer.disconnect();
-  }, [src, lazy, isLoaded]);`,
-
-    getImageClassName: shared.getImageClassNameTemplate,
-
-    classNames: `  const imageClassName = getImageClassName(src);
-  const wrapperClassName = \`${imagePrefix}wrapper \${imageClassName} \${className || ''}\`.trim();
-  
-  // Build img className with lazy states
-  const lazyClass = lazy ? (isLoaded ? '${CLASS_NAMES.LAZY} ${CLASS_NAMES.LOADED}' : '${CLASS_NAMES.LAZY}') : '';
-  const imgClassName = \`${CLASS_NAMES.IMAGE_BLOCK} \${lazyClass}\`.trim();`,
-
-    jsx: `  return (
-    <picture className={wrapperClassName}>
-      <img
-        ref={imgRef}
-        src={imageSrc}
-        alt={alt}
-        className={imgClassName}
-        {...props}
-      />
-    </picture>
-  );`,
-
-    export: `export default PlaceBlockImage;`
-  };
-};