@frybynite/image-cloud 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1514 @@
+declare interface AdaptiveSizingConfig {
+    enabled: boolean;
+    minSize: number;
+    maxSize: number;
+}
+
+declare interface AdaptiveSizingResult {
+    height: number;
+}
+
+/**
+ * Animate an element along a path using requestAnimationFrame
+ */
+export declare function animatePath(options: PathAnimationOptions): void;
+
+export declare interface AnimationConfig {
+    duration: number;
+    easing: AnimationEasingConfig;
+    queue: AnimationQueueConfig;
+    performance?: AnimationPerformanceConfig;
+    entry?: EntryAnimationConfig;
+}
+
+declare interface AnimationEasingConfig {
+    default: string;
+    bounce: string;
+    focus: string;
+}
+
+export declare class AnimationEngine {
+    private config;
+    private activeAnimations;
+    private animationIdCounter;
+    constructor(config: AnimationConfig);
+    /**
+     * Build transform string from transform params
+     * Always starts with centering transform to match image positioning system
+     */
+    private buildTransformString;
+    /**
+     * Start a cancellable transform animation using Web Animations API
+     * @param element - The element to animate
+     * @param from - Starting transform state
+     * @param to - Ending transform state
+     * @param duration - Animation duration in ms (optional)
+     * @param easing - CSS easing function (optional)
+     * @returns AnimationHandle that can be used to cancel or query the animation
+     */
+    animateTransformCancellable(element: HTMLElement, from: TransformParams, to: TransformParams, duration?: number | null, easing?: string | null): AnimationHandle;
+    /**
+     * Cancel an active animation
+     * @param handle - The animation handle to cancel
+     * @param commitStyle - If true, keeps current position; if false, no style change
+     * @returns Snapshot of where the animation was when cancelled
+     */
+    cancelAnimation(handle: AnimationHandle, commitStyle?: boolean): AnimationSnapshot;
+    /**
+     * Cancel all animations on an element
+     * Uses Web Animations API to find and cancel ALL animations, not just tracked ones
+     * @param element - The element to cancel animations for
+     */
+    cancelAllAnimations(element: HTMLElement): void;
+    /**
+     * Get current transform state of an element (works mid-animation)
+     * Uses DOMMatrix to parse the computed transform
+     * @param element - The element to query
+     * @returns Current transform snapshot
+     */
+    getCurrentTransform(element: HTMLElement): AnimationSnapshot;
+    /**
+     * Check if an element has an active animation
+     * @param element - The element to check
+     * @returns True if animation is in progress
+     */
+    hasActiveAnimation(element: HTMLElement): boolean;
+    /**
+     * Get animation handle for an element if it exists
+     * @param element - The element to query
+     * @returns AnimationHandle or undefined
+     */
+    getAnimationHandle(element: HTMLElement): AnimationHandle | undefined;
+    /**
+     * Animate element transform with smooth easing (CSS transitions - legacy method)
+     * @param element - The element to animate
+     * @param properties - Transform properties {x, y, rotation, scale}
+     * @param duration - Animation duration in ms (optional)
+     * @param easing - CSS easing function (optional)
+     * @returns Promise that resolves when animation completes
+     */
+    animateTransform(element: HTMLElement, properties: TransformParams, duration?: number | null, easing?: string | null): Promise<void>;
+    /**
+     * Reset element to its original transform
+     * @param element - The element to reset
+     * @param originalState - Original transform state {x, y, rotation, scale}
+     * @returns Promise that resolves when animation completes
+     */
+    resetTransform(element: HTMLElement, originalState: TransformParams | ImageLayout): Promise<void>;
+    /**
+     * Remove transition styles from element
+     * @param element - The element to clear
+     */
+    clearTransition(element: HTMLElement): void;
+    /**
+     * Utility: Wait for a specified duration
+     * @param ms - Milliseconds to wait
+     * @returns Promise that resolves after the specified duration
+     */
+    wait(ms: number): Promise<void>;
+}
+
+/**
+ * Handle for a cancellable animation using Web Animations API
+ */
+declare interface AnimationHandle {
+    id: string;
+    element: HTMLElement;
+    animation: Animation;
+    fromState: TransformParams;
+    toState: TransformParams;
+    startTime: number;
+    duration: number;
+}
+
+declare interface AnimationParams {
+    startTransform: string;
+    duration: number;
+    delay: number;
+    easing: string;
+}
+
+declare interface AnimationPerformanceConfig {
+    useGPU?: boolean;
+    reduceMotion?: boolean;
+}
+
+declare interface AnimationQueueConfig {
+    enabled: boolean;
+    interval: number;
+    maxConcurrent?: number;
+}
+
+/**
+ * Snapshot of an element's current transform state
+ * Used for capturing position mid-animation
+ */
+declare interface AnimationSnapshot {
+    x: number;
+    y: number;
+    rotation: number;
+    scale: number;
+}
+
+declare interface BorderConfig {
+    width?: number;
+    color?: string;
+    radius?: number;
+    style?: BorderStyle;
+}
+
+export declare type BorderStyle = 'solid' | 'dashed' | 'dotted' | 'double' | 'none' | 'groove' | 'ridge' | 'inset' | 'outset' | 'hidden';
+
+/**
+ * Bounce path presets - overshoot and settle animations
+ */
+export declare const BOUNCE_PRESETS: Record<BouncePreset, BouncePathConfig>;
+
+export declare interface BouncePathConfig {
+    overshoot: number;
+    bounces: 1 | 2 | 3;
+    decayRatio: number;
+}
+
+export declare type BouncePreset = 'energetic' | 'playful' | 'subtle';
+
+export declare interface ClusterAlgorithmConfig {
+    clusterCount: number | 'auto';
+    clusterSpread: number;
+    clusterSpacing: number;
+    density: 'uniform' | 'varied';
+    overlap: number;
+    distribution: 'gaussian' | 'uniform';
+}
+
+declare interface ClusterLayoutOptions extends Partial<LayoutConfig> {
+    fixedHeight?: number;
+}
+
+export declare class ClusterPlacementGenerator implements PlacementGenerator {
+    private config;
+    private imageConfig;
+    constructor(config: LayoutConfig, imageConfig?: ImageConfig);
+    /**
+     * Generate cluster layout positions for images
+     * @param imageCount - Number of images to layout
+     * @param containerBounds - Container dimensions {width, height}
+     * @param options - Optional overrides (includes fixedHeight)
+     * @returns Array of layout objects with position, rotation, scale
+     */
+    generate(imageCount: number, containerBounds: ContainerBounds, options?: ClusterLayoutOptions): ImageLayout[];
+    /**
+     * Calculate optimal number of clusters based on image count and container
+     */
+    private calculateClusterCount;
+    /**
+     * Generate cluster center positions with spacing constraints
+     */
+    private generateClusterCenters;
+    /**
+     * Calculate spread for a cluster (may vary if density='varied')
+     */
+    private calculateClusterSpread;
+    /**
+     * Generate a random number with approximately Gaussian distribution
+     * Using Box-Muller transform
+     */
+    private gaussianRandom;
+    /**
+     * Utility: Generate random number between min and max
+     */
+    private random;
+}
+
+export declare class CompositeLoader implements ImageLoader {
+    private loaders;
+    private debugLogging;
+    private _prepared;
+    private _discoveredUrls;
+    constructor(config: CompositeLoaderConfig);
+    /**
+     * Prepare all loaders in parallel and combine their results
+     * @param filter - Filter to apply to discovered images
+     */
+    prepare(filter: IImageFilter): Promise<void>;
+    /**
+     * Get the combined number of discovered images
+     * @throws Error if called before prepare()
+     */
+    imagesLength(): number;
+    /**
+     * Get the combined ordered list of image URLs
+     * @throws Error if called before prepare()
+     */
+    imageURLs(): string[];
+    /**
+     * Check if the loader has been prepared
+     */
+    isPrepared(): boolean;
+    /**
+     * Debug logging helper
+     * @param args - Arguments to log
+     */
+    private log;
+}
+
+export declare interface CompositeLoaderConfig {
+    loaders: ImageLoader[];
+    debugLogging?: boolean;
+}
+
+export declare interface CompositeLoaderConfigJson {
+    loaders: LoaderConfig[];
+    debugLogging?: boolean;
+}
+
+export declare interface ContainerBounds {
+    width: number;
+    height: number;
+}
+
+/**
+ * Default configuration object
+ * Frozen to prevent accidental modifications
+ */
+export declare const DEFAULT_CONFIG: ImageCloudConfig;
+
+declare interface DropShadowConfig {
+    x: number;
+    y: number;
+    blur: number;
+    color: string;
+}
+
+/**
+ * Elastic path presets - spring-like oscillation animations
+ */
+export declare const ELASTIC_PRESETS: Record<ElasticPreset, ElasticPathConfig>;
+
+export declare interface ElasticPathConfig {
+    stiffness: number;
+    damping: number;
+    mass: number;
+    oscillations: number;
+}
+
+export declare type ElasticPreset = 'gentle' | 'bouncy' | 'wobbly' | 'snappy';
+
+declare interface EntryAnimationConfig {
+    start: EntryStartConfig;
+    timing: EntryTimingConfig;
+    easing: string;
+    path?: EntryPathConfig;
+    rotation?: EntryRotationConfig;
+    scale?: EntryScaleConfig;
+}
+
+export declare class EntryAnimationEngine {
+    private config;
+    private layoutAlgorithm;
+    private resolvedStartPosition;
+    private pathConfig;
+    private rotationConfig;
+    private scaleConfig;
+    constructor(config: EntryAnimationConfig, layoutAlgorithm: LayoutAlgorithm);
+    /**
+     * Get the effective start position, considering layout-aware defaults
+     */
+    private resolveStartPosition;
+    /**
+     * Calculate the starting position for an image's entry animation
+     */
+    calculateStartPosition(finalPosition: {
+        x: number;
+        y: number;
+    }, imageSize: {
+        width: number;
+        height: number;
+    }, containerBounds: ContainerBounds, imageIndex: number, totalImages: number): StartPosition;
+    /**
+     * Calculate start position from the nearest edge (current default behavior)
+     */
+    private calculateNearestEdge;
+    /**
+     * Calculate start position from a specific edge
+     */
+    private calculateEdgePosition;
+    /**
+     * Calculate start position from center with scale animation
+     */
+    private calculateCenterPosition;
+    /**
+     * Calculate start position from a random edge
+     */
+    private calculateRandomEdge;
+    /**
+     * Calculate start position on a circle around the container
+     */
+    private calculateCircularPosition;
+    /**
+     * Get animation parameters for an image
+     */
+    getAnimationParams(imageIndex: number): AnimationParams;
+    /**
+     * Build a CSS transform string for the start position
+     * Uses pixel-based centering offset for reliable cross-browser behavior
+     */
+    buildStartTransform(startPosition: StartPosition, finalPosition: {
+        x: number;
+        y: number;
+    }, finalRotation: number, finalScale: number, imageWidth?: number, imageHeight?: number, startRotation?: number, startScale?: number): string;
+    /**
+     * Build the final CSS transform string
+     * Uses pixel-based centering offset for reliable cross-browser behavior
+     */
+    buildFinalTransform(rotation: number, scale: number, imageWidth?: number, imageHeight?: number): string;
+    /**
+     * Get the transition CSS for entry animation
+     * For JS-animated paths, only animate opacity (transform handled by JS)
+     */
+    getTransitionCSS(): string;
+    /**
+     * Check if the current path type requires JavaScript animation
+     */
+    requiresJSAnimation(): boolean;
+    /**
+     * Get the path configuration
+     */
+    getPathConfig(): EntryPathConfig;
+    /**
+     * Get the path type
+     */
+    getPathType(): EntryPathType;
+    /**
+     * Get animation timing configuration
+     */
+    getTiming(): {
+        duration: number;
+        stagger: number;
+    };
+    /**
+     * Get the rotation configuration
+     */
+    getRotationConfig(): EntryRotationConfig;
+    /**
+     * Get the rotation mode
+     */
+    getRotationMode(): EntryRotationMode;
+    /**
+     * Calculate the starting rotation for an entry animation
+     * @param finalRotation - The final rotation from the layout
+     * @returns The starting rotation in degrees
+     */
+    calculateStartRotation(finalRotation: number): number;
+    /**
+     * Resolve spin direction based on config
+     * @returns 1 for clockwise, -1 for counterclockwise
+     */
+    private resolveSpinDirection;
+    /**
+     * Check if the current rotation mode requires JavaScript animation
+     * (as opposed to CSS transitions)
+     */
+    requiresJSRotation(): boolean;
+    /**
+     * Calculate wobble rotation for a given animation progress
+     * @param progress - Animation progress from 0 to 1
+     * @param finalRotation - The final rotation in degrees
+     * @returns The current rotation in degrees
+     */
+    calculateWobbleRotation(progress: number, finalRotation: number): number;
+    /**
+     * Get the scale configuration
+     */
+    getScaleConfig(): EntryScaleConfig;
+    /**
+     * Get the scale mode
+     */
+    getScaleMode(): EntryScaleMode;
+    /**
+     * Calculate the starting scale for an entry animation
+     * @param finalScale - The final scale from the layout
+     * @returns The starting scale
+     */
+    calculateStartScale(finalScale: number): number;
+    /**
+     * Check if the current scale mode requires JavaScript animation
+     * (as opposed to CSS transitions)
+     */
+    requiresJSScale(): boolean;
+    /**
+     * Calculate pop scale for a given animation progress
+     * @param progress - Animation progress from 0 to 1
+     * @param finalScale - The final scale value
+     * @returns The current scale value with bounce effect
+     */
+    calculatePopScale(progress: number, finalScale: number): number;
+    /**
+     * Generate keyframes for scale bounce animation
+     */
+    private generateScaleBounceKeyframes;
+    /**
+     * Easing function for smooth transitions
+     */
+    private easeOutQuad;
+}
+
+declare interface EntryCircularConfig {
+    radius?: number | string;
+    distribution?: 'even' | 'random';
+}
+
+export declare interface EntryPathConfig {
+    type: EntryPathType;
+    bouncePreset?: BouncePreset;
+    elasticPreset?: ElasticPreset;
+    wavePreset?: WavePathPreset;
+    bounce?: Partial<BouncePathConfig>;
+    elastic?: Partial<ElasticPathConfig>;
+    wave?: Partial<WavePathConfig>;
+}
+
+export declare type EntryPathType = 'linear' | 'arc' | 'bounce' | 'elastic' | 'wave';
+
+declare interface EntryRotationConfig {
+    mode: EntryRotationMode;
+    startRotation?: number | {
+        min: number;
+        max: number;
+    };
+    spinCount?: number;
+    direction?: 'clockwise' | 'counterclockwise' | 'auto' | 'random';
+    wobble?: {
+        amplitude: number;
+        frequency: number;
+        decay: boolean;
+    };
+}
+
+declare type EntryRotationMode = 'none' | 'settle' | 'spin' | 'wobble' | 'random';
+
+declare interface EntryScaleConfig {
+    mode: EntryScaleMode;
+    startScale?: number;
+    range?: {
+        min: number;
+        max: number;
+    };
+    pop?: EntryScalePopConfig;
+}
+
+declare type EntryScaleMode = 'none' | 'grow' | 'shrink' | 'pop' | 'random';
+
+declare interface EntryScalePopConfig {
+    overshoot: number;
+    bounces: number;
+}
+
+declare interface EntryStartConfig {
+    position: EntryStartPosition;
+    offset?: number;
+    circular?: EntryCircularConfig;
+}
+
+declare type EntryStartPosition = 'nearest-edge' | 'top' | 'bottom' | 'left' | 'right' | 'center' | 'random-edge' | 'circular';
+
+declare interface EntryTimingConfig {
+    duration: number;
+    stagger: number;
+}
+
+declare interface FilterConfig {
+    grayscale?: number;
+    blur?: number;
+    brightness?: number;
+    contrast?: number;
+    saturate?: number;
+    opacity?: number;
+    sepia?: number;
+    hueRotate?: number;
+    invert?: number;
+    dropShadow?: DropShadowConfig | string;
+}
+
+declare interface FocusInteractionConfig {
+    scalePercent: number;
+    zIndex: number;
+    animationDuration?: number;
+}
+
+export declare type GalleryConfig = ImageCloudConfig;
+
+declare interface GestureInteractionConfig {
+    pinchToZoom?: boolean;
+    doubleTapToFocus?: boolean;
+}
+
+declare interface GoogleDriveFilesSource {
+    type: 'files';
+    files: string[];
+}
+
+declare interface GoogleDriveFolderSource {
+    type: 'folder';
+    folders: string[];
+    recursive?: boolean;
+}
+
+export declare class GoogleDriveLoader implements ImageLoader {
+    private apiKey;
+    private apiEndpoint;
+    private debugLogging;
+    private sources;
+    private _prepared;
+    private _discoveredUrls;
+    constructor(config?: Partial<GoogleDriveLoaderConfig>);
+    /**
+     * Prepare the loader by discovering all images from configured sources
+     * @param filter - Filter to apply to discovered images
+     */
+    prepare(filter: IImageFilter): Promise<void>;
+    /**
+     * Get the number of discovered images
+     * @throws Error if called before prepare()
+     */
+    imagesLength(): number;
+    /**
+     * Get the ordered list of image URLs
+     * @throws Error if called before prepare()
+     */
+    imageURLs(): string[];
+    /**
+     * Check if the loader has been prepared
+     */
+    isPrepared(): boolean;
+    /**
+     * Extract folder ID from various Google Drive URL formats
+     * @param folderUrl - Google Drive folder URL
+     * @returns Folder ID or null if invalid
+     */
+    extractFolderId(folderUrl: string): string | null;
+    /**
+     * Load images from a Google Drive folder
+     * @param folderUrl - Google Drive folder URL
+     * @param filter - Filter to apply to discovered images
+     * @param recursive - Whether to include images from subfolders
+     * @returns Promise resolving to array of image URLs
+     */
+    private loadFromFolder;
+    /**
+     * Load images from a single folder (non-recursive)
+     * @param folderId - Google Drive folder ID
+     * @param filter - Filter to apply to discovered images
+     * @returns Promise resolving to array of image URLs
+     */
+    private loadImagesFromSingleFolder;
+    /**
+     * Load specific files by their URLs or IDs
+     * @param fileUrls - Array of Google Drive file URLs or IDs
+     * @param filter - Filter to apply to discovered images
+     * @returns Promise resolving to array of image URLs
+     */
+    private loadFiles;
+    /**
+     * Extract file ID from Google Drive file URL
+     * @param fileUrl - Google Drive file URL or file ID
+     * @returns File ID or null if invalid
+     */
+    private extractFileId;
+    /**
+     * Recursively load images from a folder and all its subfolders
+     * @param folderId - Google Drive folder ID
+     * @param filter - Filter to apply to discovered images
+     * @returns Promise resolving to array of image URLs
+     */
+    private loadImagesRecursively;
+    /**
+     * Direct loading method (no API key required, but less reliable)
+     * Uses embedded folder view to scrape image IDs
+     * @param folderId - Google Drive folder ID
+     * @param filter - Filter to apply (not used in fallback mode)
+     * @returns Promise resolving to array of image URLs
+     */
+    private loadImagesDirectly;
+    /**
+     * Manually add image URLs (for testing or when auto-loading fails)
+     * @param imageIds - Array of Google Drive file IDs
+     * @returns Array of direct image URLs
+     */
+    manualImageUrls(imageIds: string[]): string[];
+    /**
+     * Debug logging helper
+     * @param args - Arguments to log
+     */
+    private log;
+}
+
+export declare interface GoogleDriveLoaderConfig {
+    apiKey: string;
+    sources: GoogleDriveSource[];
+    apiEndpoint?: string;
+    allowedExtensions?: string[];
+    debugLogging?: boolean;
+}
+
+declare type GoogleDriveSource = GoogleDriveFolderSource | GoogleDriveFilesSource;
+
+export declare interface GridAlgorithmConfig {
+    columns: number | 'auto';
+    rows: number | 'auto';
+    stagger: 'none' | 'row' | 'column';
+    jitter: number;
+    overlap: number;
+    fillDirection: 'row' | 'column';
+    alignment: 'start' | 'center' | 'end';
+    gap: number;
+    overflowOffset: number;
+}
+
+declare interface GridLayoutOptions extends Partial<LayoutConfig> {
+    fixedHeight?: number;
+}
+
+export declare class GridPlacementGenerator implements PlacementGenerator {
+    private config;
+    private imageConfig;
+    constructor(config: LayoutConfig, imageConfig?: ImageConfig);
+    /**
+     * Generate grid layout positions for images
+     * @param imageCount - Number of images to layout
+     * @param containerBounds - Container dimensions {width, height}
+     * @param options - Optional overrides (includes fixedHeight)
+     * @returns Array of layout objects with position, rotation, scale
+     */
+    generate(imageCount: number, containerBounds: ContainerBounds, options?: GridLayoutOptions): ImageLayout[];
+    /**
+     * Calculate optimal grid dimensions based on image count and container
+     */
+    private calculateGridDimensions;
+    /**
+     * Utility: Generate random number between min and max
+     */
+    private random;
+}
+
+/**
+ * ImageFilter interface for filtering images by extension
+ * Implemented by the ImageFilter class in loaders/ImageFilter.ts
+ */
+export declare interface IImageFilter {
+    isAllowed(filename: string): boolean;
+    getAllowedExtensions(): string[];
+}
+
+declare class ImageCloud {
+    private containerId;
+    private containerRef;
+    private fullConfig;
+    private imagesLoaded;
+    private imageElements;
+    private imageLayouts;
+    private currentImageHeight;
+    private currentFocusIndex;
+    private hoveredImage;
+    private resizeTimeout;
+    private displayQueue;
+    private queueInterval;
+    private loadGeneration;
+    private defaultStyles;
+    private hoverStyles;
+    private defaultClassName;
+    private hoverClassName;
+    private animationEngine;
+    private entryAnimationEngine;
+    private layoutEngine;
+    private zoomEngine;
+    private imageLoader;
+    private imageFilter;
+    private containerEl;
+    private loadingEl;
+    private errorEl;
+    constructor(options?: ImageCloudOptions);
+    /**
+     * Create image filter based on config
+     */
+    private createImageFilter;
+    /**
+     * Create appropriate image loader based on config
+     */
+    private createLoader;
+    /**
+     * Create a loader from a LoaderConfig object (supports recursive composite loaders)
+     */
+    private createLoaderFromConfig;
+    /**
+     * Initialize the gallery
+     */
+    init(): Promise<void>;
+    private setupUI;
+    private setupEventListeners;
+    /**
+     * Navigate to the next image (Right arrow)
+     */
+    private navigateToNextImage;
+    /**
+     * Navigate to the previous image (Left arrow)
+     */
+    private navigateToPreviousImage;
+    /**
+     * Navigate to a specific image by index
+     */
+    private navigateToImage;
+    private handleResize;
+    private getImageHeight;
+    /**
+     * Get container bounds for layout calculations
+     */
+    private getContainerBounds;
+    /**
+     * Load images using the unified loader interface
+     */
+    private loadImages;
+    /**
+     * Helper for debug logging
+     */
+    private logDebug;
+    private createImageCloud;
+    private handleImageClick;
+    /**
+     * Clear the image cloud and reset state
+     */
+    clearImageCloud(): void;
+    private showLoading;
+    private showError;
+    private hideError;
+    /**
+     * Destroy the gallery and clean up resources
+     */
+    destroy(): void;
+}
+export { ImageCloud }
+export { ImageCloud as ImageGallery }
+
+export declare interface ImageCloudConfig {
+    loader: LoaderConfig;
+    image: ImageConfig;
+    layout: LayoutConfig;
+    animation: AnimationConfig;
+    interaction: InteractionConfig;
+    rendering: RenderingConfig;
+    styling?: ImageStylingConfig;
+    debug: boolean;
+}
+
+export declare interface ImageCloudOptions {
+    container?: string | HTMLElement;
+    loader?: Partial<LoaderConfig>;
+    image?: Partial<ImageConfig>;
+    layout?: Partial<LayoutConfig>;
+    animation?: Partial<AnimationConfig>;
+    interaction?: Partial<InteractionConfig>;
+    rendering?: Partial<RenderingConfig>;
+    styling?: Partial<ImageStylingConfig>;
+    debug?: boolean;
+}
+
+/**
+ * Combined image configuration
+ */
+declare interface ImageConfig {
+    sizing?: ImageSizingConfig;
+    rotation?: ImageRotationConfig;
+}
+
+/**
+ * ImageFilter.ts
+ * Filters images by extension, designed for future extensibility
+ * (e.g., size filters, date filters, etc.)
+ */
+export declare class ImageFilter {
+    private allowedExtensions;
+    /**
+     * Create a new ImageFilter
+     * @param extensions - Array of allowed file extensions (without dots)
+     *                     Defaults to common image formats if not provided
+     */
+    constructor(extensions?: string[]);
+    /**
+     * Check if a filename has an allowed extension
+     * @param filename - The filename to check (can include path or query string)
+     * @returns True if the file extension is allowed
+     */
+    isAllowed(filename: string): boolean;
+    /**
+     * Get the list of allowed extensions
+     * @returns Array of allowed extensions
+     */
+    getAllowedExtensions(): string[];
+}
+
+export declare type ImageGalleryOptions = ImageCloudOptions;
+
+/**
+ * Type definitions for Image Gallery Library
+ */
+export declare interface ImageLayout {
+    id: number;
+    x: number;
+    y: number;
+    rotation: number;
+    scale: number;
+    baseSize: number;
+    zIndex?: number;
+    borderColor?: string;
+}
+
+/**
+ * ImageLoader interface with consistent lifecycle pattern:
+ * 1. Constructor - Initialize with required parameters, throw if missing
+ * 2. prepare(filter) - Async discovery of images, accepts filter
+ * 3. imagesLength() - Return count of images (after prepare)
+ * 4. imageURLs() - Return ordered list of URLs (after prepare)
+ */
+export declare interface ImageLoader {
+    /**
+     * Async preparation - discovers images and applies filter
+     * Succeeds even if 0 images found (gallery handles empty state)
+     * @param filter - Filter to apply to discovered images
+     */
+    prepare(filter: IImageFilter): Promise<void>;
+    /**
+     * Get the number of discovered images
+     * @throws Error if called before prepare() completes
+     */
+    imagesLength(): number;
+    /**
+     * Get the ordered list of image URLs
+     * @throws Error if called before prepare() completes
+     */
+    imageURLs(): string[];
+    /**
+     * Check if the loader has been prepared
+     */
+    isPrepared(): boolean;
+}
+
+/**
+ * Image rotation configuration
+ */
+declare interface ImageRotationConfig {
+    mode: ImageRotationMode;
+    range?: ImageRotationRange;
+}
+
+/**
+ * Image rotation mode
+ */
+declare type ImageRotationMode = 'none' | 'random' | 'tangent';
+
+/**
+ * Image rotation range configuration
+ */
+declare interface ImageRotationRange {
+    min: number;
+    max: number;
+}
+
+/**
+ * Image sizing configuration
+ */
+declare interface ImageSizingConfig {
+    baseHeight?: number | ResponsiveBaseHeight;
+    variance?: ImageVarianceConfig;
+    scaleDecay?: number;
+}
+
+declare interface ImageStyleState {
+    className?: string | string[];
+    border?: BorderConfig;
+    borderTop?: Partial<BorderConfig>;
+    borderRight?: Partial<BorderConfig>;
+    borderBottom?: Partial<BorderConfig>;
+    borderLeft?: Partial<BorderConfig>;
+    borderRadiusTopLeft?: number;
+    borderRadiusTopRight?: number;
+    borderRadiusBottomRight?: number;
+    borderRadiusBottomLeft?: number;
+    shadow?: ShadowPreset | string;
+    filter?: FilterConfig;
+    opacity?: number;
+    cursor?: string;
+    outline?: OutlineConfig;
+    objectFit?: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down';
+    aspectRatio?: string;
+}
+
+declare interface ImageStylingConfig {
+    default?: ImageStyleState;
+    hover?: Partial<ImageStyleState>;
+    focused?: Partial<ImageStyleState>;
+}
+
+/**
+ * Image variance configuration
+ * Controls random size variation applied to images
+ */
+declare interface ImageVarianceConfig {
+    min: number;
+    max: number;
+}
+
+declare interface InteractionConfig {
+    focus: FocusInteractionConfig;
+    navigation?: NavigationInteractionConfig;
+    gestures?: GestureInteractionConfig;
+}
+
+export declare type LayoutAlgorithm = 'random' | 'radial' | 'grid' | 'spiral' | 'cluster' | 'wave';
+
+export declare interface LayoutConfig {
+    algorithm: LayoutAlgorithm;
+    sizing: LayoutSizingConfig;
+    spacing: LayoutSpacingConfig;
+    targetCoverage?: number;
+    densityFactor?: number;
+    debugRadials?: boolean;
+    debugCenters?: boolean;
+    grid?: GridAlgorithmConfig;
+    spiral?: SpiralAlgorithmConfig;
+    cluster?: ClusterAlgorithmConfig;
+    wave?: WaveAlgorithmConfig;
+}
+
+export declare class LayoutEngine {
+    private config;
+    private imageConfig;
+    private breakpoints;
+    private layouts;
+    private generator;
+    constructor(config: LayoutEngineConfig);
+    /**
+     * Initialize the appropriate generator based on config type
+     * @returns Initialized placement generator
+     */
+    private initGenerator;
+    /**
+     * Generate layout positions for images
+     * @param imageCount - Number of images to layout
+     * @param containerBounds - Container dimensions {width, height}
+     * @param options - Optional overrides for configuration (e.g. fixedHeight)
+     * @returns Array of layout objects with position, rotation, scale
+     */
+    generateLayout(imageCount: number, containerBounds: ContainerBounds, options?: Partial<LayoutConfig>): ImageLayout[];
+    /**
+     * Get the original layout state for an image
+     * @param imageId - The image ID (number or string)
+     * @returns Original layout state or undefined if not found
+     */
+    getOriginalState(imageId: number | string): ImageLayout | undefined;
+    /**
+     * Reset all stored layouts
+     */
+    reset(): void;
+    /**
+     * Update config dynamically (useful for responsive changes)
+     * @param newConfig - Updated configuration
+     */
+    updateConfig(newConfig: Partial<LayoutEngineConfig>): void;
+    /**
+     * Resolve the effective base height based on image config and current viewport
+     * @param viewportWidth - Current viewport width
+     * @returns Resolved base height or undefined if should auto-calculate
+     */
+    resolveBaseHeight(viewportWidth: number): number | undefined;
+    /**
+     * Calculate adaptive image size based on container dimensions and image count
+     * @param containerBounds - Container dimensions {width, height}
+     * @param imageCount - Number of images to display
+     * @param responsiveHeight - Current responsive breakpoint height (upper bound)
+     * @param viewportWidth - Current viewport width for baseHeight resolution
+     * @returns Calculated sizing result with height
+     */
+    calculateAdaptiveSize(containerBounds: ContainerBounds, imageCount: number, responsiveHeight: number, viewportWidth: number): AdaptiveSizingResult;
+    /**
+     * Utility: Clamp a value between min and max
+     */
+    private clamp;
+}
+
+declare interface LayoutEngineConfig {
+    layout: LayoutConfig;
+    image: ImageConfig;
+    breakpoints?: {
+        mobile: number;
+        tablet?: number;
+    };
+}
+
+declare interface LayoutSizingConfig {
+    base: number;
+    responsive: ResponsiveHeight[];
+    adaptive?: AdaptiveSizingConfig;
+}
+
+declare interface LayoutSpacingConfig {
+    padding: number;
+    minGap: number;
+}
+
+export declare interface LoaderConfig {
+    type: 'googleDrive' | 'static' | 'composite';
+    googleDrive?: GoogleDriveLoaderConfig;
+    static?: StaticLoaderConfig;
+    composite?: CompositeLoaderConfigJson;
+}
+
+declare interface NavigationInteractionConfig {
+    keyboard?: boolean;
+    swipe?: boolean;
+    mouseWheel?: boolean;
+}
+
+declare interface OutlineConfig {
+    width?: number;
+    color?: string;
+    style?: BorderStyle;
+    offset?: number;
+}
+
+declare interface PathAnimationOptions {
+    element: HTMLElement;
+    startPosition: Point;
+    endPosition: Point;
+    pathConfig: EntryPathConfig;
+    duration: number;
+    imageWidth: number;
+    imageHeight: number;
+    rotation: number;
+    scale: number;
+    onComplete?: () => void;
+    rotationConfig?: EntryRotationConfig;
+    startRotation?: number;
+    scaleConfig?: EntryScaleConfig;
+    startScale?: number;
+}
+
+declare interface PerformanceRenderingConfig {
+    lazyLoad?: boolean;
+    preloadCount?: number;
+    imageQuality?: 'auto' | 'high' | 'medium' | 'low';
+}
+
+export declare interface PlacementGenerator {
+    generate(imageCount: number, containerBounds: ContainerBounds, options?: Partial<LayoutConfig>): ImageLayout[];
+}
+
+declare interface Point {
+    x: number;
+    y: number;
+}
+
+declare interface RadialLayoutOptions extends Partial<LayoutConfig> {
+    fixedHeight?: number;
+}
+
+export declare class RadialPlacementGenerator implements PlacementGenerator {
+    private config;
+    private imageConfig;
+    constructor(config: LayoutConfig, imageConfig?: ImageConfig);
+    /**
+     * Generate radial layout positions for images
+     * @param imageCount - Number of images to layout
+     * @param containerBounds - Container dimensions {width, height}
+     * @param options - Optional overrides
+     * @returns Array of layout objects with position, rotation, scale
+     */
+    generate(imageCount: number, containerBounds: ContainerBounds, options?: RadialLayoutOptions): ImageLayout[];
+    /**
+     * Estimate image width based on height
+     * Assumes landscape aspect ratio (approximately 1.4:1)
+     * @param height - Image height
+     * @returns Estimated width
+     */
+    private estimateWidth;
+    /**
+     * Utility: Generate random number between min and max
+     * @param min - Minimum value
+     * @param max - Maximum value
+     * @returns Random number in range
+     */
+    private random;
+}
+
+declare interface RandomLayoutOptions extends Partial<LayoutConfig> {
+    fixedHeight?: number;
+}
+
+export declare class RandomPlacementGenerator implements PlacementGenerator {
+    private config;
+    private imageConfig;
+    constructor(config: LayoutConfig, imageConfig?: ImageConfig);
+    /**
+     * Generate random layout positions for images
+     * @param imageCount - Number of images to layout
+     * @param containerBounds - Container dimensions {width, height}
+     * @param options - Optional overrides (includes fixedHeight)
+     * @returns Array of layout objects with position, rotation, scale
+     */
+    generate(imageCount: number, containerBounds: ContainerBounds, options?: RandomLayoutOptions): ImageLayout[];
+    /**
+     * Utility: Generate random number between min and max
+     * @param min - Minimum value
+     * @param max - Maximum value
+     * @returns Random number in range
+     */
+    private random;
+}
+
+declare interface RenderingConfig {
+    responsive: ResponsiveRenderingConfig;
+    ui: UIRenderingConfig;
+    performance?: PerformanceRenderingConfig;
+}
+
+/**
+ * Check if a path type requires JavaScript animation (vs CSS transitions)
+ */
+export declare function requiresJSAnimation(pathType: EntryPathType): boolean;
+
+/**
+ * Responsive base height configuration
+ * Can be a simple number or responsive breakpoint object
+ */
+declare interface ResponsiveBaseHeight {
+    default: number;
+    tablet?: number;
+    mobile?: number;
+}
+
+export declare interface ResponsiveHeight {
+    minWidth: number;
+    height: number;
+}
+
+export declare interface ResponsiveRenderingConfig {
+    breakpoints: {
+        mobile: number;
+        tablet?: number;
+        desktop?: number;
+    };
+    mobileDetection: () => boolean;
+}
+
+declare type ShadowPreset = 'none' | 'sm' | 'md' | 'lg' | 'glow';
+
+export declare interface SpiralAlgorithmConfig {
+    spiralType: 'golden' | 'archimedean' | 'logarithmic';
+    direction: 'clockwise' | 'counterclockwise';
+    tightness: number;
+    scaleDecay: number;
+    startAngle: number;
+}
+
+declare interface SpiralLayoutOptions extends Partial<LayoutConfig> {
+    fixedHeight?: number;
+}
+
+export declare class SpiralPlacementGenerator implements PlacementGenerator {
+    private config;
+    private imageConfig;
+    constructor(config: LayoutConfig, imageConfig?: ImageConfig);
+    /**
+     * Generate spiral layout positions for images
+     * @param imageCount - Number of images to layout
+     * @param containerBounds - Container dimensions {width, height}
+     * @param options - Optional overrides (includes fixedHeight)
+     * @returns Array of layout objects with position, rotation, scale
+     */
+    generate(imageCount: number, containerBounds: ContainerBounds, options?: SpiralLayoutOptions): ImageLayout[];
+    /**
+     * Calculate tangent angle for spiral curve at given position
+     * This aligns the image along the spiral's direction of travel
+     */
+    private calculateSpiralTangent;
+    /**
+     * Calculate radius for golden spiral (Vogel's model)
+     * Creates even distribution like sunflower seeds
+     */
+    private calculateGoldenRadius;
+    /**
+     * Calculate radius for Archimedean spiral
+     * r = a + b*θ (constant spacing between arms)
+     */
+    private calculateArchimedeanRadius;
+    /**
+     * Calculate radius for logarithmic (equiangular) spiral
+     * r = a * e^(b*θ)
+     */
+    private calculateLogarithmicRadius;
+    /**
+     * Utility: Generate random number between min and max
+     */
+    private random;
+}
+
+declare interface StartPosition {
+    x: number;
+    y: number;
+    useScale?: boolean;
+}
+
+export declare class StaticImageLoader implements ImageLoader {
+    private validateUrls;
+    private validationTimeout;
+    private validationMethod;
+    private sources;
+    private debugLogging;
+    private _prepared;
+    private _discoveredUrls;
+    constructor(config?: Partial<StaticLoaderConfig>);
+    /**
+     * Prepare the loader by discovering all images from configured sources
+     * @param filter - Filter to apply to discovered images
+     */
+    prepare(filter: IImageFilter): Promise<void>;
+    /**
+     * Get the number of discovered images
+     * @throws Error if called before prepare()
+     */
+    imagesLength(): number;
+    /**
+     * Get the ordered list of image URLs
+     * @throws Error if called before prepare()
+     */
+    imageURLs(): string[];
+    /**
+     * Check if the loader has been prepared
+     */
+    isPrepared(): boolean;
+    /**
+     * Process a single source object
+     * @param source - Source configuration with type, urls, basePath, files
+     * @param filter - Filter to apply to discovered images
+     * @returns Promise resolving to array of valid URLs from this source
+     */
+    private processSource;
+    /**
+     * Process a list of direct URLs
+     * @param urls - Array of image URLs
+     * @param filter - Filter to apply to discovered images
+     * @returns Promise resolving to array of validated URLs
+     */
+    private processUrls;
+    /**
+     * Process a path-based source
+     * @param basePath - Base path (relative or absolute)
+     * @param files - Array of filenames
+     * @param filter - Filter to apply to discovered images
+     * @returns Promise resolving to array of validated URLs
+     */
+    private processPath;
+    /**
+     * Validate a single URL using HEAD request
+     * @param url - URL to validate
+     * @returns Promise resolving to true if valid and accessible
+     */
+    private validateUrl;
+    /**
+     * Construct full URL from basePath and filename
+     * @param basePath - Base path (relative or absolute)
+     * @param filename - Filename to append
+     * @returns Complete URL
+     */
+    private constructUrl;
+    /**
+     * Check if URL is absolute (contains protocol)
+     * @param url - URL to check
+     * @returns True if absolute URL
+     */
+    private isAbsoluteUrl;
+    /**
+     * Debug logging helper
+     * @param args - Arguments to log
+     */
+    private log;
+}
+
+export declare interface StaticLoaderConfig {
+    sources: StaticSource[];
+    validateUrls?: boolean;
+    validationTimeout?: number;
+    validationMethod?: 'head' | 'simple' | 'none';
+    failOnAllMissing?: boolean;
+    allowedExtensions?: string[];
+    debugLogging?: boolean;
+}
+
+export declare interface StaticSource {
+    type: StaticSourceType;
+    urls?: string[];
+    basePath?: string;
+    files?: string[];
+}
+
+declare type StaticSourceType = 'urls' | 'path';
+
+export declare interface TransformParams {
+    x?: number;
+    y?: number;
+    rotation?: number;
+    scale?: number;
+}
+
+export declare interface UIRenderingConfig {
+    showLoadingSpinner: boolean;
+    showImageCounter?: boolean;
+    showThumbnails?: boolean;
+    theme?: 'light' | 'dark' | 'auto';
+}
+
+/**
+ * Wave path presets - sinusoidal path animations
+ */
+export declare const WAVE_PATH_PRESETS: Record<WavePathPreset, WavePathConfig>;
+
+declare interface WaveAlgorithmConfig {
+    rows: number;
+    amplitude: number;
+    frequency: number;
+    phaseShift: number;
+    synchronization: 'offset' | 'synchronized' | 'alternating';
+}
+
+export declare interface WavePathConfig {
+    amplitude: number;
+    frequency: number;
+    decay: boolean;
+    decayRate: number;
+    phase: number;
+}
+
+export declare type WavePathPreset = 'gentle' | 'playful' | 'serpentine' | 'flutter';
+
+export declare class ZoomEngine {
+    private config;
+    private animationEngine;
+    private state;
+    private currentFocus;
+    private focusData;
+    private outgoing;
+    private incoming;
+    private focusGeneration;
+    private defaultStyles;
+    private focusedStyles;
+    private defaultClassName;
+    private focusedClassName;
+    constructor(config: FocusInteractionConfig, animationEngine: AnimationEngine, styling?: ImageStylingConfig);
+    /**
+     * Get current state machine state
+     */
+    getState(): ZoomState;
+    /**
+     * Check if any animation is in progress
+     */
+    isAnimating(): boolean;
+    /**
+     * Normalize scalePercent value
+     */
+    private normalizeScalePercent;
+    /**
+     * Calculate target dimensions for focused image
+     * Returns actual pixel dimensions instead of scale factor for sharper rendering
+     */
+    private calculateFocusDimensions;
+    /**
+     * Calculate the transform needed to center an image (position only, no scale)
+     * Scale is handled by animating actual dimensions for sharper rendering
+     */
+    private calculateFocusTransform;
+    /**
+     * Build transform string for dimension-based zoom (no scale in transform)
+     */
+    private buildDimensionZoomTransform;
+    /**
+     * Create a Web Animation that animates both transform (position) and dimensions
+     * This provides sharper zoom by re-rendering at target size instead of scaling pixels
+     */
+    private animateWithDimensions;
+    /**
+     * Apply focused styling to an element
+     */
+    private applyFocusedStyling;
+    /**
+     * Remove focused styling from an element
+     */
+    private removeFocusedStyling;
+    /**
+     * Start focus animation for an image using dimension-based zoom
+     * Animates actual width/height for sharper rendering instead of transform scale
+     * @param fromTransform - Optional starting transform (for mid-animation reversals)
+     * @param fromDimensions - Optional starting dimensions (for mid-animation reversals)
+     */
+    private startFocusAnimation;
+    /**
+     * Start unfocus animation for an image using dimension-based zoom
+     * Animates back to original dimensions for consistent behavior
+     * @param fromDimensions - Optional starting dimensions (for mid-animation reversals)
+     */
+    private startUnfocusAnimation;
+    /**
+     * Handle animation completion
+     */
+    private waitForAnimation;
+    /**
+     * Reset an element instantly to its original position and dimensions (no animation)
+     */
+    private resetElementInstantly;
+    /**
+     * Focus (zoom) an image to center of container
+     * Implements cross-animation when swapping focus
+     */
+    focusImage(imageElement: HTMLElement, containerBounds: ContainerBounds, originalState: ImageLayout): Promise<void>;
+    /**
+     * Unfocus current image, returning it to original position
+     */
+    unfocusImage(): Promise<void>;
+    /**
+     * Swap focus from current image to a new one (alias for focusImage with cross-animation)
+     */
+    swapFocus(newImageElement: HTMLElement, containerBounds: ContainerBounds, originalState: ImageLayout): Promise<void>;
+    /**
+     * Get currently focused image element
+     */
+    getCurrentFocus(): HTMLElement | null;
+    /**
+     * Check if an image is currently focused (stable state)
+     */
+    isFocused(imageElement: HTMLElement): boolean;
+    /**
+     * Check if an image is the target of current focus animation
+     */
+    isTargetingFocus(imageElement: HTMLElement): boolean;
+    /**
+     * Check if an image is involved in any focus/animation state
+     * Returns true if the image is focused, animating in, or animating out
+     * Useful for hover state management - don't apply hover to animating images
+     */
+    isInvolved(imageElement: HTMLElement): boolean;
+    /**
+     * Reset zoom state (cancels all animations)
+     */
+    reset(): void;
+}
+
+/**
+ * State machine states for zoom/focus animations
+ */
+declare enum ZoomState {
+    IDLE = "idle",// No focus, no animations
+    FOCUSING = "focusing",// Single image animating in
+    FOCUSED = "focused",// Stable focused state
+    UNFOCUSING = "unfocusing",// Single image animating out
+    CROSS_ANIMATING = "cross_animating"
+}
+
+export { }