@jhits/plugin-images 0.0.11 → 0.0.12

package/src/hooks/useImagePicker.ts

@@ -0,0 +1,344 @@
+/**
+ * Hook for Image Picker Logic
+ */
+
+import { useState, useEffect, useRef } from 'react';
+import type { ImageMetadata } from '../types';
+
+export interface UseImagePickerOptions {
+    value?: string;
+    images: ImageMetadata[];
+}
+
+export function useImagePicker({ value, images }: UseImagePickerOptions) {
+    const [selectedImage, setSelectedImage] = useState<ImageMetadata | null>(null);
+    const [uploading, setUploading] = useState(false);
+    const fileInputRef = useRef<HTMLInputElement>(null);
+    const lastResolvedValueRef = useRef<string | undefined>(undefined);
+    const isResolvingRef = useRef(false);
+    const lastImagesRef = useRef<string>('');
+
+    // Find selected image from value (can be ID or URL)
+    useEffect(() => {
+        // Create a stable reference for images array to detect actual changes
+        const imagesKey = JSON.stringify(images.map(img => ({ id: img.id, url: img.url })));
+        
+        // Prevent infinite loops by checking if we're already resolving or if value and images haven't changed
+        if (isResolvingRef.current || (lastResolvedValueRef.current === value && lastImagesRef.current === imagesKey)) {
+            return;
+        }
+        
+        lastImagesRef.current = imagesKey;
+
+        if (!value) {
+            if (selectedImage !== null) {
+                setSelectedImage(null);
+            }
+            lastResolvedValueRef.current = value;
+            return;
+        }
+
+        isResolvingRef.current = true;
+        const resolveImage = async () => {
+            // Normalize the value - extract filename if it's a URL
+            const isFullUrl = value.startsWith('http://') || value.startsWith('https://');
+            const isRelativeUrl = value.startsWith('/');
+            const isUrl = isFullUrl || isRelativeUrl;
+            
+            // Extract filename from URL if it's a URL
+            let filenameFromUrl: string | null = null;
+            let imageIdToResolve = value;
+            
+            if (isUrl) {
+                const urlParts = value.split('/');
+                filenameFromUrl = urlParts[urlParts.length - 1]?.split('?')[0] || null;
+                // If it's a full URL, try to resolve using the filename instead
+                if (isFullUrl && filenameFromUrl) {
+                    imageIdToResolve = filenameFromUrl;
+                }
+            }
+            
+            // First, try to find by ID (preferred method)
+            let found = images.find(img => img.id === value || img.id === imageIdToResolve);
+            
+            // If not found by ID, try to find by URL
+            if (!found) {
+                found = images.find(img => img.url === value);
+            }
+            
+            // If still not found, try to match by filename extracted from URL
+            if (!found && filenameFromUrl) {
+                found = images.find(img => img.id === filenameFromUrl || img.filename === filenameFromUrl);
+            }
+            
+            if (found) {
+                // Only update if the image is actually different
+                setSelectedImage(prev => {
+                    if (prev?.id === found.id && prev?.url === found.url) {
+                        return prev;
+                    }
+                    return found;
+                });
+            } else {
+                // If value is already a full URL, use it directly
+                if (isFullUrl) {
+                    const newImage = {
+                        id: value,
+                        filename: filenameFromUrl || value,
+                        url: value, // Use the full URL as-is
+                        size: 0,
+                        mimeType: 'image/jpeg',
+                        uploadedAt: new Date().toISOString(),
+                    };
+                    setSelectedImage(prev => {
+                        if (prev?.id === newImage.id && prev?.url === newImage.url) {
+                            return prev;
+                        }
+                        return newImage;
+                    });
+                    lastResolvedValueRef.current = value;
+                    isResolvingRef.current = false;
+                    return;
+                }
+                
+                // If value is a relative URL, use it directly
+                if (isRelativeUrl) {
+                    const newImage = {
+                        id: value,
+                        filename: filenameFromUrl || value,
+                        url: value, // Use the relative URL as-is
+                        size: 0,
+                        mimeType: 'image/jpeg',
+                        uploadedAt: new Date().toISOString(),
+                    };
+                    setSelectedImage(prev => {
+                        if (prev?.id === newImage.id && prev?.url === newImage.url) {
+                            return prev;
+                        }
+                        return newImage;
+                    });
+                    lastResolvedValueRef.current = value;
+                    isResolvingRef.current = false;
+                    return;
+                }
+                
+                // Check if value looks like a filename (has extension or starts with digits)
+                const isLikelyPath = /\.(jpg|jpeg|png|webp|gif|svg)$/i.test(value) || /^\d+-/.test(value);
+                
+                if (isLikelyPath) {
+                    // It's likely a filename, create image object directly
+                    const newImage = {
+                        id: value,
+                        filename: value,
+                        url: `/api/uploads/${value}`,
+                        size: 0,
+                        mimeType: 'image/jpeg',
+                        uploadedAt: new Date().toISOString(),
+                    };
+                    setSelectedImage(prev => {
+                        if (prev?.id === newImage.id && prev?.url === newImage.url) {
+                            return prev;
+                        }
+                        return newImage;
+                    });
+                    lastResolvedValueRef.current = value;
+                    isResolvingRef.current = false;
+                } else {
+                    // It might be a semantic ID, try to resolve via API
+                    // Use the extracted ID (filename) if value was a URL, otherwise use value
+                    try {
+                        const response = await fetch(`/api/plugin-images/resolve?id=${encodeURIComponent(imageIdToResolve)}`);
+                        if (response.ok) {
+                            const data = await response.json();
+                            // Normalize the URL - ensure it's a proper URL
+                            let imageUrl: string;
+                            if (data.url) {
+                                // If API returns a URL, use it (but check if it's already a full URL)
+                                if (data.url.startsWith('http://') || data.url.startsWith('https://')) {
+                                    imageUrl = data.url;
+                                } else if (data.url.startsWith('/')) {
+                                    imageUrl = data.url;
+                                } else {
+                                    // Relative path without leading slash
+                                    imageUrl = `/api/uploads/${data.url}`;
+                                }
+                            } else if (data.filename) {
+                                // Use filename to construct URL
+                                imageUrl = `/api/uploads/${data.filename}`;
+                            } else {
+                                // Fallback: if original value was a URL, use it; otherwise construct
+                                imageUrl = isFullUrl ? value : (isRelativeUrl ? value : `/api/uploads/${value}`);
+                            }
+                            
+                            const newImage = {
+                                id: value,
+                                filename: data.filename || filenameFromUrl || value,
+                                url: imageUrl,
+                                size: 0,
+                                mimeType: 'image/jpeg',
+                                uploadedAt: new Date().toISOString(),
+                            };
+                            setSelectedImage(prev => {
+                                if (prev?.id === newImage.id && prev?.url === newImage.url) {
+                                    return prev;
+                                }
+                                return newImage;
+                            });
+                            lastResolvedValueRef.current = value;
+                            isResolvingRef.current = false;
+                        } else {
+                            // API resolution failed - check if it's a semantic ID or actual filename
+                            const isLikelyFilename = /\.(jpg|jpeg|png|webp|gif|svg)$/i.test(imageIdToResolve) || /^\d+-/.test(imageIdToResolve);
+                            
+                            if (!isLikelyFilename) {
+                                // It's a semantic ID that couldn't be resolved - clear selection
+                                // This prevents showing broken URLs like /api/uploads/blog-featured-...
+                                setSelectedImage(null);
+                                lastResolvedValueRef.current = value;
+                                isResolvingRef.current = false;
+                                return;
+                            }
+                            
+                            // It's a filename, create fallback object
+                            const isFullUrl = value.startsWith('http://') || value.startsWith('https://');
+                            const isRelativeUrl = value.startsWith('/');
+                            
+                            let imageUrl: string;
+                            if (isFullUrl) {
+                                // Already a full URL, use as-is
+                                imageUrl = value;
+                            } else if (isRelativeUrl) {
+                                // Already a relative URL starting with /, use as-is
+                                imageUrl = value;
+                            } else {
+                                // It's a filename, construct the URL
+                                imageUrl = `/api/uploads/${value}`;
+                            }
+                            
+                            const urlParts = value.split('/');
+                            const filename = urlParts[urlParts.length - 1]?.split('?')[0] || value;
+                            
+                            const newImage = {
+                                id: value,
+                                filename: filename,
+                                url: imageUrl,
+                                size: 0,
+                                mimeType: 'image/jpeg',
+                                uploadedAt: new Date().toISOString(),
+                            };
+                            setSelectedImage(prev => {
+                                if (prev?.id === newImage.id && prev?.url === newImage.url) {
+                                    return prev;
+                                }
+                                return newImage;
+                            });
+                            lastResolvedValueRef.current = value;
+                            isResolvingRef.current = false;
+                        }
+                    } catch (error) {
+                        // API call failed - check if it's a semantic ID or actual filename
+                        const isLikelyFilename = /\.(jpg|jpeg|png|webp|gif|svg)$/i.test(imageIdToResolve) || /^\d+-/.test(imageIdToResolve);
+                        
+                        if (!isLikelyFilename) {
+                            // It's a semantic ID that couldn't be resolved - clear selection
+                            // This prevents showing broken URLs like /api/uploads/blog-featured-...
+                            setSelectedImage(null);
+                            lastResolvedValueRef.current = value;
+                            isResolvingRef.current = false;
+                            return;
+                        }
+                        
+                        // It's a filename, create fallback object
+                        const isFullUrl = value.startsWith('http://') || value.startsWith('https://');
+                        const isRelativeUrl = value.startsWith('/');
+                        
+                        let imageUrl: string;
+                        if (isFullUrl) {
+                            // Already a full URL, use as-is
+                            imageUrl = value;
+                        } else if (isRelativeUrl) {
+                            // Already a relative URL starting with /, use as-is
+                            imageUrl = value;
+                        } else {
+                            // It's a filename, construct the URL
+                            imageUrl = `/api/uploads/${value}`;
+                        }
+                        
+                        const urlParts = value.split('/');
+                        const filename = urlParts[urlParts.length - 1]?.split('?')[0] || value;
+                        
+                        const newImage = {
+                            id: value,
+                            filename: filename,
+                            url: imageUrl,
+                            size: 0,
+                            mimeType: 'image/jpeg',
+                            uploadedAt: new Date().toISOString(),
+                        };
+                        setSelectedImage(prev => {
+                            if (prev?.id === newImage.id && prev?.url === newImage.url) {
+                                return prev;
+                            }
+                            return newImage;
+                        });
+                        lastResolvedValueRef.current = value;
+                        isResolvingRef.current = false;
+                    }
+                }
+            }
+        };
+
+        resolveImage().catch(() => {
+            // Error already handled in catch block
+            isResolvingRef.current = false;
+        });
+    }, [value, images]);
+
+    // Handle file upload
+    const handleFileSelect = async (e?: React.ChangeEvent<HTMLInputElement> | { target: { files: File[] | null } }) => {
+        const file = e?.target?.files?.[0];
+        if (!file) return null;
+
+        setUploading(true);
+        try {
+            const formData = new FormData();
+            formData.append('file', file);
+
+            const response = await fetch('/api/plugin-images/upload', {
+                method: 'POST',
+                body: formData,
+            });
+
+            const data = await response.json();
+            
+            if (data.success && data.image) {
+                // Select the newly uploaded image
+                setSelectedImage(data.image);
+                if (fileInputRef.current) {
+                    fileInputRef.current.value = '';
+                }
+                return data.image;
+            } else {
+                alert(data.error || 'Failed to upload image');
+                return null;
+            }
+        } catch (error) {
+            console.error('Upload error:', error);
+            alert('Failed to upload image');
+            return null;
+        } finally {
+            setUploading(false);
+            if (fileInputRef.current) {
+                fileInputRef.current.value = '';
+            }
+        }
+    };
+
+    return {
+        selectedImage,
+        setSelectedImage,
+        uploading,
+        fileInputRef,
+        handleFileSelect,
+    };
+}

package/src/index.server.ts

@@ -0,0 +1,12 @@
+import 'server-only';
+/**
+ * Plugin Images - Server-Only Entry Point
+ * This file exports only server-side API handlers
+ * Used by the dynamic plugin router via @jhits/plugin-images/server
+ * 
+ * Note: This file is server-only (no 'use server' needed - that's only for Server Actions)
+ */
+
+export { handleImagesApi as handleApi } from './api/router';
+export { handleImagesApi } from './api/router'; // Keep original export for backward compatibility
+

package/src/index.tsx

@@ -0,0 +1,56 @@
+/**
+ * Plugin Images - Main Entry Point
+ * Image management plugin for uploading, searching, and managing images
+ */
+
+'use client';
+
+import React from 'react';
+import { ImageManagerView } from './views/ImageManager';
+
+export interface PluginProps {
+    subPath: string[];
+    siteId: string;
+    locale: string;
+}
+
+export default function ImagesPlugin({ subPath, siteId, locale }: PluginProps) {
+    const route = subPath[0] || 'manager';
+
+    switch (route) {
+        case 'manager':
+            return <ImageManagerView siteId={siteId} locale={locale} />;
+        
+        default:
+            return <ImageManagerView siteId={siteId} locale={locale} />;
+    }
+}
+
+// Export for use as default
+export { ImagesPlugin as Index };
+
+// Export components for use in other plugins
+export { ImagePicker } from './components/ImagePicker';
+export { GlobalImageEditor } from './components/GlobalImageEditor';
+export { ImagesPluginInit } from './components/ImagesPluginInit';
+export { Image } from './components/Image';
+export { BackgroundImage } from './components/BackgroundImage';
+export type { ImagePickerProps, ImageMetadata } from './types';
+export type { PluginImageProps } from './components/Image';
+export type { BackgroundImageProps } from './components/BackgroundImage';
+
+// Export initialization utility
+export { initImagesPlugin } from './init';
+export type { ImagesPluginConfig } from './init';
+
+// Export utility functions
+export { 
+    getFallbackImageUrl, 
+    isValidImageUrl, 
+    getSafeImageUrl,
+    constructImageUrl 
+} from './utils/fallback';
+
+// Note: API handlers are server-only and exported from ./index.ts (server entry point)
+// They are NOT exported here to prevent client/server context mixing
+

package/src/init.tsx

@@ -0,0 +1,58 @@
+/**
+ * Images Plugin Initialization Utility
+ * 
+ * Simple function to initialize the images plugin with client configuration.
+ * Call this once in your app (e.g., in root layout) to enable global image editing.
+ * 
+ * @example
+ * ```typescript
+ * import { initImagesPlugin } from '@jhits/plugin-images/init';
+ * import { imagesConfig } from '@/plugins/images-config';
+ * 
+ * // Call once when your app loads
+ * initImagesPlugin(imagesConfig);
+ * ```
+ */
+
+'use client';
+
+export interface ImagesPluginConfig {
+    /** Enable global image editor (default: true) */
+    enabled?: boolean;
+    /** Custom styling for the editor modal */
+    className?: string;
+    /** Custom styling for the modal overlay */
+    overlayClassName?: string;
+}
+
+/**
+ * Initialize the images plugin with client configuration
+ * 
+ * This function sets up the window global that the plugin reads from automatically.
+ * Call this once when your app loads, before the plugin component is rendered.
+ * 
+ * @param config - Images plugin configuration (enabled, styling, etc.)
+ */
+export function initImagesPlugin(config?: ImagesPluginConfig): void {
+    if (typeof window === 'undefined') {
+        // Server-side: no-op
+        return;
+    }
+
+    // Initialize the global plugin props object if it doesn't exist
+    if (!(window as any).__JHITS_PLUGIN_PROPS__) {
+        (window as any).__JHITS_PLUGIN_PROPS__ = {};
+    }
+
+    // Set images plugin configuration
+    (window as any).__JHITS_PLUGIN_PROPS__['plugin-images'] = {
+        enabled: config?.enabled !== undefined ? config.enabled : true,
+        className: config?.className,
+        overlayClassName: config?.overlayClassName,
+    };
+
+    console.log('[ImagesPlugin] Initialized with config:', {
+        enabled: config?.enabled !== undefined ? config.enabled : true,
+    });
+}
+

package/src/types/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Image Plugin Types
+ */
+export interface ImageMetadata {
+    /** Unique image ID */
+    id: string;
+    /** Original filename */
+    filename: string;
+    /** File path/URL */
+    url: string;
+    /** File size in bytes */
+    size: number;
+    /** MIME type */
+    mimeType: string;
+    /** Image dimensions */
+    width?: number;
+    height?: number;
+    /** Alt text */
+    alt?: string;
+    /** Upload timestamp */
+    uploadedAt: string;
+    /** Uploaded by user ID */
+    uploadedBy?: string;
+    /** Tags for searching */
+    tags?: string[];
+}
+export interface ImageUploadResponse {
+    success: boolean;
+    image?: ImageMetadata;
+    error?: string;
+}
+export interface ImageListResponse {
+    images: ImageMetadata[];
+    total: number;
+    page: number;
+    limit: number;
+}
+export interface ImagePickerProps {
+    /** Current selected image URL */
+    value?: string;
+    /** Callback when image is selected */
+    onChange: (image: ImageMetadata | null) => void;
+    /** Whether dark mode is enabled */
+    darkMode?: boolean;
+    /** Show brightness and blur controls */
+    showEffects?: boolean;
+    /** Current brightness value (0-200, 100 = normal) */
+    brightness?: number;
+    /** Current blur value (0-20) */
+    blur?: number;
+    /** Current scale value (0.1-3.0, 1.0 = normal) */
+    scale?: number;
+    /** Current X position offset (-100 to 100, 0 = center) */
+    positionX?: number;
+    /** Current Y position offset (-100 to 100, 0 = center) */
+    positionY?: number;
+    /** Aspect ratio for preview/editor (e.g., "4/5", "3/4", "16/9", "1/1") */
+    aspectRatio?: string;
+    /** Border radius class (e.g., "rounded-xl", "rounded-3xl") */
+    borderRadius?: string;
+    /** Object fit style (e.g., "cover", "contain") */
+    objectFit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';
+    /** Object position (e.g., "center", "top", "bottom") */
+    objectPosition?: string;
+    /** Callback when brightness changes */
+    onBrightnessChange?: (brightness: number) => void;
+    /** Callback when blur changes */
+    onBlurChange?: (blur: number) => void;
+    /** Callback when scale changes */
+    onScaleChange?: (scale: number) => void;
+    /** Callback when X position changes */
+    onPositionXChange?: (positionX: number) => void;
+    /** Callback when Y position changes */
+    onPositionYChange?: (positionY: number) => void;
+    /** Callback when editor "Done" button is clicked - triggers immediate save */
+    onEditorSave?: (scale: number, positionX: number, positionY: number, brightness?: number, blur?: number) => void;
+    /** Automatically open the editor when component mounts (useful for modal scenarios) */
+    autoOpenEditor?: boolean;
+}
+//# sourceMappingURL=index.d.ts.map

package/src/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,aAAa;IAC1B,sBAAsB;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,wBAAwB;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,uBAAuB;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,0BAA0B;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yBAAyB;IACzB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAC9B,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC7B,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,KAAK,IAAI,CAAC;IAChD,mCAAmC;IACnC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,wCAAwC;IACxC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kDAAkD;IAClD,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,YAAY,CAAC;IACjE,wDAAwD;IACxD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uCAAuC;IACvC,kBAAkB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IAClD,iCAAiC;IACjC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,kCAAkC;IAClC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,uCAAuC;IACvC,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,uCAAuC;IACvC,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,8EAA8E;IAC9E,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACjH,uFAAuF;IACvF,cAAc,CAAC,EAAE,OAAO,CAAC;CAC5B"}

package/src/types/index.ts

@@ -0,0 +1,84 @@
+/**
+ * Image Plugin Types
+ */
+
+export interface ImageMetadata {
+    /** Unique image ID */
+    id: string;
+    /** Original filename */
+    filename: string;
+    /** File path/URL */
+    url: string;
+    /** File size in bytes */
+    size: number;
+    /** MIME type */
+    mimeType: string;
+    /** Image dimensions */
+    width?: number;
+    height?: number;
+    /** Alt text */
+    alt?: string;
+    /** Upload timestamp */
+    uploadedAt: string;
+    /** Uploaded by user ID */
+    uploadedBy?: string;
+    /** Tags for searching */
+    tags?: string[];
+}
+
+export interface ImageUploadResponse {
+    success: boolean;
+    image?: ImageMetadata;
+    error?: string;
+}
+
+export interface ImageListResponse {
+    images: ImageMetadata[];
+    total: number;
+    page: number;
+    limit: number;
+}
+
+export interface ImagePickerProps {
+    /** Current selected image URL */
+    value?: string;
+    /** Callback when image is selected */
+    onChange: (image: ImageMetadata | null) => void;
+    /** Whether dark mode is enabled */
+    darkMode?: boolean;
+    /** Show brightness and blur controls */
+    showEffects?: boolean;
+    /** Current brightness value (0-200, 100 = normal) */
+    brightness?: number;
+    /** Current blur value (0-20) */
+    blur?: number;
+    /** Current scale value (0.1-3.0, 1.0 = normal) */
+    scale?: number;
+    /** Current X position offset (-100 to 100, 0 = center) */
+    positionX?: number;
+    /** Current Y position offset (-100 to 100, 0 = center) */
+    positionY?: number;
+    /** Aspect ratio for preview/editor (e.g., "4/5", "3/4", "16/9", "1/1") */
+    aspectRatio?: string;
+    /** Border radius class (e.g., "rounded-xl", "rounded-3xl") */
+    borderRadius?: string;
+    /** Object fit style (e.g., "cover", "contain") */
+    objectFit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';
+    /** Object position (e.g., "center", "top", "bottom") */
+    objectPosition?: string;
+    /** Callback when brightness changes */
+    onBrightnessChange?: (brightness: number) => void;
+    /** Callback when blur changes */
+    onBlurChange?: (blur: number) => void;
+    /** Callback when scale changes */
+    onScaleChange?: (scale: number) => void;
+    /** Callback when X position changes */
+    onPositionXChange?: (positionX: number) => void;
+    /** Callback when Y position changes */
+    onPositionYChange?: (positionY: number) => void;
+    /** Callback when editor "Done" button is clicked - triggers immediate save */
+    onEditorSave?: (scale: number, positionX: number, positionY: number, brightness?: number, blur?: number) => void;
+    /** Automatically open the editor when component mounts (useful for modal scenarios) */
+    autoOpenEditor?: boolean;
+}
+

package/src/utils/fallback.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Fallback image utility
+ * Provides a default fallback image URL when images fail to load or are invalid
+ * Also handles URL construction for image filenames
+ */
+/**
+ * Returns the URL for the fallback "image not found" image
+ * Served from the plugin's API route
+ */
+export declare function getFallbackImageUrl(): string;
+/**
+ * Constructs the full image URL from a filename or URL
+ * - If it's already a full URL (http://, https://, or starts with /), returns as-is
+ * - If it's a filename, constructs `/api/uploads/${filename}`
+ */
+export declare function constructImageUrl(src: string | null | undefined): string | null;
+/**
+ * Validates if a URL is valid and can be used with Next.js Image component
+ */
+export declare function isValidImageUrl(url: string | null | undefined): boolean;
+/**
+ * Gets a safe image URL with automatic URL construction and fallback
+ * - Constructs the full URL if src is a filename
+ * - Falls back to the plugin's fallback image if invalid or missing
+ */
+export declare function getSafeImageUrl(src: string | null | undefined): string;
+//# sourceMappingURL=fallback.d.ts.map

package/src/utils/fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallback.d.ts","sourceRoot":"","sources":["fallback.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAY/E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAkBvE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAUtE"}