@frybynite/image-cloud 0.10.3 → 0.11.0

package/dist/index.d.ts

@@ -138,6 +138,17 @@ declare interface AnimationSnapshot {
     scale: number;
 }
 
+export declare interface BeforeLoadContext {
+    url: string;
+    index: number;
+    totalImages: number;
+}
+
+export declare interface BeforeLoadResult {
+    url?: string;
+    fetch?: RequestInit;
+}
+
 export declare interface BorderConfig {
     width?: number;
     color?: string;
@@ -456,11 +467,34 @@ export declare class EntryAnimationEngine {
     private easeOutQuad;
 }
 
+export declare interface EntryAnimPoint {
+    x: number;
+    y: number;
+    rotation: number;
+    scale: number;
+}
+
 declare interface EntryCircularConfig {
     radius?: number | string;
     distribution?: 'even' | 'random';
 }
 
+export declare interface EntryCompleteContext {
+    element: HTMLElement;
+    index: number;
+    layout: ImageLayout;
+    startTime: number;
+    endTime: number;
+    duration: number;
+}
+
+declare interface EntryCurrentState {
+    x: number;
+    y: number;
+    rotation: number;
+    scale: number;
+}
+
 export declare interface EntryPathConfig {
     type: EntryPathType;
     bouncePreset?: BouncePreset;
@@ -473,6 +507,13 @@ export declare interface EntryPathConfig {
 
 export declare type EntryPathType = 'linear' | 'bounce' | 'elastic' | 'wave';
 
+export declare interface EntryProgressContext extends EntryStartContext {
+    progress: number;
+    rawProgress: number;
+    elapsed: number;
+    current: EntryAnimPoint;
+}
+
 export declare interface EntryRotationConfig {
     mode: EntryRotationMode;
     startRotation?: number | {
@@ -513,6 +554,17 @@ declare interface EntryStartConfig {
     circular?: EntryCircularConfig;
 }
 
+export declare interface EntryStartContext {
+    element: HTMLElement;
+    index: number;
+    totalImages: number;
+    layout: ImageLayout;
+    from: EntryAnimPoint;
+    to: EntryAnimPoint;
+    startTime: number;
+    duration: number;
+}
+
 declare type EntryStartPosition = 'nearest-edge' | 'top' | 'bottom' | 'left' | 'right' | 'center' | 'random-edge' | 'circular';
 
 declare interface EntryTimingConfig {
@@ -554,6 +606,12 @@ declare interface FocusInteractionConfig {
  */
 export declare const FUNCTIONAL_CSS = "\n.fbn-ic-gallery {\n  position: relative;\n  width: 100%;\n  height: 100%;\n  overflow: hidden;\n  perspective: 1000px;\n}\n\n.fbn-ic-image {\n  position: absolute;\n  cursor: pointer;\n  transition: transform 0.6s cubic-bezier(0.4, 0, 0.2, 1),\n    box-shadow 0.6s cubic-bezier(0.4, 0, 0.2, 1),\n    filter 0.3s cubic-bezier(0.4, 0, 0.2, 1),\n    opacity 0.3s cubic-bezier(0.4, 0, 0.2, 1),\n    border 0.3s cubic-bezier(0.4, 0, 0.2, 1),\n    outline 0.3s cubic-bezier(0.4, 0, 0.2, 1),\n    z-index 0s 0.6s;\n  will-change: transform;\n  user-select: none;\n  backface-visibility: hidden;\n  -webkit-backface-visibility: hidden;\n}\n\n.fbn-ic-image.fbn-ic-focused {\n  z-index: 1000;\n  transition: transform 0.6s cubic-bezier(0.4, 0, 0.2, 1),\n    box-shadow 0.6s cubic-bezier(0.4, 0, 0.2, 1),\n    filter 0.3s cubic-bezier(0.4, 0, 0.2, 1),\n    opacity 0.3s cubic-bezier(0.4, 0, 0.2, 1),\n    border 0.3s cubic-bezier(0.4, 0, 0.2, 1),\n    outline 0.3s cubic-bezier(0.4, 0, 0.2, 1),\n    z-index 0s 0s;\n  will-change: auto;\n}\n\n.fbn-ic-counter {\n  position: fixed;\n  bottom: 24px;\n  left: 50%;\n  transform: translateX(-50%);\n  z-index: 10001;\n  pointer-events: none;\n}\n\n.fbn-ic-gallery:focus,\n.fbn-ic-gallery.fbn-ic-has-focus {\n  outline: 2px solid rgba(147, 197, 253, 0.8);\n  outline-offset: -4px;\n}\n.fbn-ic-gallery.fbn-ic-suppress-outline:focus {\n  outline: none;\n}\n.fbn-ic-gallery.fbn-ic-suppress-outline.fbn-ic-has-focus {\n  outline: 2px solid rgba(99, 102, 241, 0.6);\n  outline-offset: -4px;\n}\n\n.fbn-ic-nav-btn {\n  position: absolute;\n  top: 50%;\n  transform: translateY(-50%);\n  z-index: 10001;\n  cursor: pointer;\n  border: none;\n  background: none;\n  padding: 0;\n  line-height: 1;\n}\n.fbn-ic-nav-btn-prev {\n  left: 12px;\n}\n.fbn-ic-nav-btn-next {\n  right: 12px;\n}\n\n.fbn-ic-hidden {\n  display: none !important;\n}\n";
 
+export declare interface GalleryReadyContext {
+    totalImages: number;
+    failedImages: number;
+    loadDuration: number;
+}
+
 export declare interface GoogleDriveFilesSource {
     files: string[];
 }
@@ -734,9 +792,9 @@ export declare interface IdleBlinkConfig {
     style: 'snap' | 'fade';
 }
 
-declare type IdleCustomAnimationFn = (ctx: IdleCustomContext) => Animation | (() => void);
+export declare type IdleCustomAnimationFn = (ctx: IdleCustomContext) => Animation | (() => void);
 
-declare interface IdleCustomContext {
+export declare interface IdleCustomContext {
     element: HTMLElement;
     index: number;
     totalImages: number;
@@ -796,6 +854,7 @@ export declare class ImageCloud {
     private swipeEngine;
     private imageLoader;
     private imageFilter;
+    private callbacks;
     private containerEl;
     private loadingEl;
     private errorEl;
@@ -881,6 +940,22 @@ export declare class ImageCloud {
 
 export declare function imageCloud(options: ImageCloudOptions): Promise<ImageCloud>;
 
+export declare interface ImageCloudCallbacks {
+    onImageHover?: (ctx: ImageStateContext) => void;
+    onImageUnhover?: (ctx: ImageStateContext) => void;
+    onImageFocus?: (ctx: ImageStateContext) => void;
+    onImageUnfocus?: (ctx: ImageStateContext) => void;
+    onBeforeImageLoad?: (ctx: BeforeLoadContext) => BeforeLoadResult | void | Promise<BeforeLoadResult | void>;
+    onImageLoaded?: (ctx: ImageLoadedContext) => void;
+    onImageError?: (ctx: ImageErrorContext) => void;
+    onLoadProgress?: (ctx: LoadProgressContext) => void;
+    onGalleryReady?: (ctx: GalleryReadyContext) => void;
+    onLayoutComplete?: (ctx: LayoutCompleteContext) => void;
+    onEntryStart?: (ctx: EntryStartContext) => void;
+    onEntryProgress?: (ctx: EntryProgressContext) => void;
+    onEntryComplete?: (ctx: EntryCompleteContext) => void;
+}
+
 export declare interface ImageCloudConfig {
     loaders: LoaderEntry[];
     config: ConfigSection;
@@ -903,6 +978,7 @@ export declare interface ImageCloudOptions {
     interaction?: Partial<InteractionConfig>;
     ui?: Partial<UIConfig>;
     styling?: Partial<ImageStylingConfig>;
+    on?: ImageCloudCallbacks;
 }
 
 /**
@@ -913,6 +989,12 @@ export declare interface ImageConfig {
     rotation?: ImageRotationConfig;
 }
 
+export declare interface ImageErrorContext {
+    url: string;
+    index: number;
+    totalImages: number;
+}
+
 /**
  * ImageFilter.ts
  * Filters images by extension, designed for future extensibility
@@ -952,6 +1034,14 @@ export declare interface ImageLayout {
     zIndex?: number;
 }
 
+export declare interface ImageLoadedContext {
+    element: HTMLImageElement;
+    url: string;
+    index: number;
+    totalImages: number;
+    loadTime: number;
+}
+
 /**
  * ImageLoader interface with consistent lifecycle pattern:
  * 1. Constructor - Initialize with required parameters, throw if missing
@@ -1014,6 +1104,13 @@ export declare interface ImageSizingConfig {
     variance?: ImageVarianceConfig;
 }
 
+export declare interface ImageStateContext {
+    element: HTMLElement;
+    index: number;
+    url: string;
+    layout: ImageLayout;
+}
+
 export declare interface ImageStyleState {
     className?: string | string[];
     border?: BorderConfig;
@@ -1064,6 +1161,13 @@ export declare interface InteractionConfig {
 
 export declare type LayoutAlgorithm = 'random' | 'radial' | 'grid' | 'spiral' | 'cluster' | 'wave' | 'honeycomb';
 
+export declare interface LayoutCompleteContext {
+    layouts: ImageLayout[];
+    containerBounds: ContainerBounds;
+    algorithm: LayoutAlgorithm;
+    imageCount: number;
+}
+
 export declare interface LayoutConfig {
     algorithm: LayoutAlgorithm;
     spacing: LayoutSpacingConfig;
@@ -1159,6 +1263,13 @@ declare interface LayoutSpacingConfig {
 
 export declare type LoaderEntry = StaticLoaderEntry | GoogleDriveLoaderEntry;
 
+export declare interface LoadProgressContext {
+    loaded: number;
+    failed: number;
+    total: number;
+    percent: number;
+}
+
 declare interface NavigationInteractionConfig {
     keyboard?: boolean;
     swipe?: boolean;
@@ -1182,6 +1293,7 @@ declare interface PathAnimationOptions {
     rotation: number;
     scale: number;
     onComplete?: () => void;
+    onProgress?: (t: number, elapsed: number, current: EntryCurrentState) => void;
     rotationConfig?: EntryRotationConfig;
     startRotation?: number;
     scaleConfig?: EntryScaleConfig;

package/dist/react.d.ts

@@ -138,6 +138,17 @@ declare interface AnimationSnapshot {
     scale: number;
 }
 
+export declare interface BeforeLoadContext {
+    url: string;
+    index: number;
+    totalImages: number;
+}
+
+export declare interface BeforeLoadResult {
+    url?: string;
+    fetch?: RequestInit;
+}
+
 export declare interface BorderConfig {
     width?: number;
     color?: string;
@@ -456,11 +467,34 @@ export declare class EntryAnimationEngine {
     private easeOutQuad;
 }
 
+export declare interface EntryAnimPoint {
+    x: number;
+    y: number;
+    rotation: number;
+    scale: number;
+}
+
 declare interface EntryCircularConfig {
     radius?: number | string;
     distribution?: 'even' | 'random';
 }
 
+export declare interface EntryCompleteContext {
+    element: HTMLElement;
+    index: number;
+    layout: ImageLayout;
+    startTime: number;
+    endTime: number;
+    duration: number;
+}
+
+declare interface EntryCurrentState {
+    x: number;
+    y: number;
+    rotation: number;
+    scale: number;
+}
+
 export declare interface EntryPathConfig {
     type: EntryPathType;
     bouncePreset?: BouncePreset;
@@ -473,6 +507,13 @@ export declare interface EntryPathConfig {
 
 export declare type EntryPathType = 'linear' | 'bounce' | 'elastic' | 'wave';
 
+export declare interface EntryProgressContext extends EntryStartContext {
+    progress: number;
+    rawProgress: number;
+    elapsed: number;
+    current: EntryAnimPoint;
+}
+
 export declare interface EntryRotationConfig {
     mode: EntryRotationMode;
     startRotation?: number | {
@@ -513,6 +554,17 @@ declare interface EntryStartConfig {
     circular?: EntryCircularConfig;
 }
 
+export declare interface EntryStartContext {
+    element: HTMLElement;
+    index: number;
+    totalImages: number;
+    layout: ImageLayout;
+    from: EntryAnimPoint;
+    to: EntryAnimPoint;
+    startTime: number;
+    duration: number;
+}
+
 declare type EntryStartPosition = 'nearest-edge' | 'top' | 'bottom' | 'left' | 'right' | 'center' | 'random-edge' | 'circular';
 
 declare interface EntryTimingConfig {
@@ -554,6 +606,12 @@ declare interface FocusInteractionConfig {
  */
 export declare const FUNCTIONAL_CSS = "\n.fbn-ic-gallery {\n  position: relative;\n  width: 100%;\n  height: 100%;\n  overflow: hidden;\n  perspective: 1000px;\n}\n\n.fbn-ic-image {\n  position: absolute;\n  cursor: pointer;\n  transition: transform 0.6s cubic-bezier(0.4, 0, 0.2, 1),\n    box-shadow 0.6s cubic-bezier(0.4, 0, 0.2, 1),\n    filter 0.3s cubic-bezier(0.4, 0, 0.2, 1),\n    opacity 0.3s cubic-bezier(0.4, 0, 0.2, 1),\n    border 0.3s cubic-bezier(0.4, 0, 0.2, 1),\n    outline 0.3s cubic-bezier(0.4, 0, 0.2, 1),\n    z-index 0s 0.6s;\n  will-change: transform;\n  user-select: none;\n  backface-visibility: hidden;\n  -webkit-backface-visibility: hidden;\n}\n\n.fbn-ic-image.fbn-ic-focused {\n  z-index: 1000;\n  transition: transform 0.6s cubic-bezier(0.4, 0, 0.2, 1),\n    box-shadow 0.6s cubic-bezier(0.4, 0, 0.2, 1),\n    filter 0.3s cubic-bezier(0.4, 0, 0.2, 1),\n    opacity 0.3s cubic-bezier(0.4, 0, 0.2, 1),\n    border 0.3s cubic-bezier(0.4, 0, 0.2, 1),\n    outline 0.3s cubic-bezier(0.4, 0, 0.2, 1),\n    z-index 0s 0s;\n  will-change: auto;\n}\n\n.fbn-ic-counter {\n  position: fixed;\n  bottom: 24px;\n  left: 50%;\n  transform: translateX(-50%);\n  z-index: 10001;\n  pointer-events: none;\n}\n\n.fbn-ic-gallery:focus,\n.fbn-ic-gallery.fbn-ic-has-focus {\n  outline: 2px solid rgba(147, 197, 253, 0.8);\n  outline-offset: -4px;\n}\n.fbn-ic-gallery.fbn-ic-suppress-outline:focus {\n  outline: none;\n}\n.fbn-ic-gallery.fbn-ic-suppress-outline.fbn-ic-has-focus {\n  outline: 2px solid rgba(99, 102, 241, 0.6);\n  outline-offset: -4px;\n}\n\n.fbn-ic-nav-btn {\n  position: absolute;\n  top: 50%;\n  transform: translateY(-50%);\n  z-index: 10001;\n  cursor: pointer;\n  border: none;\n  background: none;\n  padding: 0;\n  line-height: 1;\n}\n.fbn-ic-nav-btn-prev {\n  left: 12px;\n}\n.fbn-ic-nav-btn-next {\n  right: 12px;\n}\n\n.fbn-ic-hidden {\n  display: none !important;\n}\n";
 
+export declare interface GalleryReadyContext {
+    totalImages: number;
+    failedImages: number;
+    loadDuration: number;
+}
+
 export declare interface GoogleDriveFilesSource {
     files: string[];
 }
@@ -734,9 +792,9 @@ export declare interface IdleBlinkConfig {
     style: 'snap' | 'fade';
 }
 
-declare type IdleCustomAnimationFn = (ctx: IdleCustomContext) => Animation | (() => void);
+export declare type IdleCustomAnimationFn = (ctx: IdleCustomContext) => Animation | (() => void);
 
-declare interface IdleCustomContext {
+export declare interface IdleCustomContext {
     element: HTMLElement;
     index: number;
     totalImages: number;
@@ -796,6 +854,7 @@ export declare class ImageCloud {
     private swipeEngine;
     private imageLoader;
     private imageFilter;
+    private callbacks;
     private containerEl;
     private loadingEl;
     private errorEl;
@@ -881,6 +940,22 @@ export declare class ImageCloud {
 
 export declare function imageCloud(options: ImageCloudOptions): Promise<ImageCloud>;
 
+export declare interface ImageCloudCallbacks {
+    onImageHover?: (ctx: ImageStateContext) => void;
+    onImageUnhover?: (ctx: ImageStateContext) => void;
+    onImageFocus?: (ctx: ImageStateContext) => void;
+    onImageUnfocus?: (ctx: ImageStateContext) => void;
+    onBeforeImageLoad?: (ctx: BeforeLoadContext) => BeforeLoadResult | void | Promise<BeforeLoadResult | void>;
+    onImageLoaded?: (ctx: ImageLoadedContext) => void;
+    onImageError?: (ctx: ImageErrorContext) => void;
+    onLoadProgress?: (ctx: LoadProgressContext) => void;
+    onGalleryReady?: (ctx: GalleryReadyContext) => void;
+    onLayoutComplete?: (ctx: LayoutCompleteContext) => void;
+    onEntryStart?: (ctx: EntryStartContext) => void;
+    onEntryProgress?: (ctx: EntryProgressContext) => void;
+    onEntryComplete?: (ctx: EntryCompleteContext) => void;
+}
+
 export declare interface ImageCloudConfig {
     loaders: LoaderEntry[];
     config: ConfigSection;
@@ -903,6 +978,7 @@ export declare interface ImageCloudOptions {
     interaction?: Partial<InteractionConfig>;
     ui?: Partial<UIConfig>;
     styling?: Partial<ImageStylingConfig>;
+    on?: ImageCloudCallbacks;
 }
 
 /**
@@ -913,6 +989,12 @@ export declare interface ImageConfig {
     rotation?: ImageRotationConfig;
 }
 
+export declare interface ImageErrorContext {
+    url: string;
+    index: number;
+    totalImages: number;
+}
+
 /**
  * ImageFilter.ts
  * Filters images by extension, designed for future extensibility
@@ -952,6 +1034,14 @@ export declare interface ImageLayout {
     zIndex?: number;
 }
 
+export declare interface ImageLoadedContext {
+    element: HTMLImageElement;
+    url: string;
+    index: number;
+    totalImages: number;
+    loadTime: number;
+}
+
 /**
  * ImageLoader interface with consistent lifecycle pattern:
  * 1. Constructor - Initialize with required parameters, throw if missing
@@ -1014,6 +1104,13 @@ export declare interface ImageSizingConfig {
     variance?: ImageVarianceConfig;
 }
 
+export declare interface ImageStateContext {
+    element: HTMLElement;
+    index: number;
+    url: string;
+    layout: ImageLayout;
+}
+
 export declare interface ImageStyleState {
     className?: string | string[];
     border?: BorderConfig;
@@ -1064,6 +1161,13 @@ export declare interface InteractionConfig {
 
 export declare type LayoutAlgorithm = 'random' | 'radial' | 'grid' | 'spiral' | 'cluster' | 'wave' | 'honeycomb';
 
+export declare interface LayoutCompleteContext {
+    layouts: ImageLayout[];
+    containerBounds: ContainerBounds;
+    algorithm: LayoutAlgorithm;
+    imageCount: number;
+}
+
 export declare interface LayoutConfig {
     algorithm: LayoutAlgorithm;
     spacing: LayoutSpacingConfig;
@@ -1159,6 +1263,13 @@ declare interface LayoutSpacingConfig {
 
 export declare type LoaderEntry = StaticLoaderEntry | GoogleDriveLoaderEntry;
 
+export declare interface LoadProgressContext {
+    loaded: number;
+    failed: number;
+    total: number;
+    percent: number;
+}
+
 declare interface NavigationInteractionConfig {
     keyboard?: boolean;
     swipe?: boolean;
@@ -1182,6 +1293,7 @@ declare interface PathAnimationOptions {
     rotation: number;
     scale: number;
     onComplete?: () => void;
+    onProgress?: (t: number, elapsed: number, current: EntryCurrentState) => void;
     rotationConfig?: EntryRotationConfig;
     startRotation?: number;
     scaleConfig?: EntryScaleConfig;