hy-masonry
Version:
Animated Masonry Layout as Web Component - Living organisms that morph and breathe
1,057 lines (1,037 loc) • 23.1 kB
TypeScript
export declare class AnimationEngine {
private animations;
private animationFrame;
private isRunning;
private lastTime;
constructor();
/**
* Add animation to an item
*/
addAnimation(itemId: string, animationType: string, options?: AnimationOptions): void;
/**
* Remove animation from an item
*/
removeAnimation(itemId: string): void;
/**
* Create animation function based on type
*/
private createAnimation;
/**
* Start animation loop
*/
start(): void;
/**
* Stop animation loop
*/
stop(): void;
/**
* Main animation loop
*/
private animate;
/**
* Get animation count
*/
getAnimationCount(): number;
/**
* Clear all animations
*/
clear(): void;
}
/**
* Custom animation function type
*/
export declare interface AnimationFunction {
(element: HTMLElement, deltaTime: number): void;
}
/**
* Animation options
*/
export declare interface AnimationOptions {
/**
* Animation speed
*/
speed?: number;
/**
* Animation intensity
*/
intensity?: number;
/**
* Animation phase
*/
phase?: number;
/**
* Animation easing
*/
easing?: string;
/**
* Animation delay
*/
delay?: number;
}
/**
* Individual breakpoint configuration
*/
export declare interface Breakpoint {
/**
* Minimum width for this breakpoint
*/
minWidth?: number;
/**
* Maximum width for this breakpoint
*/
maxWidth?: number;
/**
* Number of columns at this breakpoint
*/
columns: number;
/**
* Gap between items at this breakpoint
*/
gap: number;
/**
* Padding at this breakpoint
*/
padding?: number;
/**
* Custom configuration for this breakpoint
*/
config?: Partial<MasonryConfig>;
}
/**
* Breakpoint configuration for responsive design
*/
export declare interface BreakpointConfig {
/**
* Mobile breakpoint (≤768px)
*/
mobile?: Breakpoint;
/**
* Tablet breakpoint (769px-1024px)
*/
tablet?: Breakpoint;
/**
* Desktop breakpoint (>1024px)
*/
desktop?: Breakpoint;
/**
* Large desktop breakpoint (>1440px)
*/
largeDesktop?: Breakpoint;
/**
* Custom breakpoints
*/
[key: string]: Breakpoint | undefined;
}
/**
* Calculated dimensions
*/
export declare interface CalculatedDimensions {
/**
* Width in pixels
*/
width: number;
/**
* Height in pixels
*/
height: number;
}
/**
* Custom event map for TypeScript
*/
export declare interface CustomEventMap {
'item:added': MasonryEvent;
'item:removed': MasonryEvent;
'item:updated': MasonryEvent;
'item:morphed': MasonryEvent;
'layout:updated': MasonryEvent;
'animation:start': MasonryEvent;
'animation:end': MasonryEvent;
'breakpoint:changed': MasonryEvent;
'performance:metrics': MasonryEvent;
'error:occurred': MasonryEvent;
}
declare class HyMasonry extends HTMLElement {
private config;
private items;
private animationEngine;
private morphingManager;
private interactionHandler;
private layout;
private resizeObserver;
private intersectionObserver;
private container;
constructor();
/**
* Get default configuration
*/
private getDefaultConfig;
/**
* Read configuration from HTML attributes
*/
private readAttributes;
/**
* Connected callback - when element is added to DOM
*/
connectedCallback(): void;
/**
* Disconnected callback - when element is removed from DOM
*/
disconnectedCallback(): void;
/**
* Attribute changed callback
*/
static get observedAttributes(): string[];
attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
/**
* Setup component structure
*/
private setupComponent;
/**
* Setup event listeners
*/
private setupEventListeners;
/**
* Setup observers
*/
private setupObservers;
/**
* Apply theme
*/
private applyTheme;
/**
* Add item to masonry
*/
addItem(item: MasonryItem): void;
/**
* Remove item from masonry
*/
removeItem(itemId: string): void;
/**
* Update item
*/
updateItem(itemId: string, newConfig: Partial<MasonryItem>): void;
/**
* Create item element
*/
private createItemElement;
/**
* Update item element
*/
private updateItemElement;
/**
* Refresh layout
*/
refresh(): void;
/**
* Morph item
*/
morphItem(itemId: string, newSize: string, duration?: number): void;
/**
* Reset item to original size
*/
resetItem(itemId: string): void;
/**
* Get item by ID
*/
getItem(itemId: string): MasonryItem | undefined;
/**
* Get all items
*/
getItems(): MasonryItem[];
/**
* Get layout information
*/
getLayoutInfo(): LayoutInfo | null;
/**
* Update configuration
*/
updateConfig(newConfig: Partial<MasonryConfig>): void;
/**
* Throttle function
*/
private throttle;
/**
* Dispatch custom event
*/
private dispatchCustomEvent;
/**
* Cleanup resources
*/
private cleanup;
/**
* Destroy component
*/
destroy(): void;
}
export { HyMasonry }
export default HyMasonry;
export declare class InteractionHandler {
private longPressTimers;
private touchStartPositions;
private longPressDelay;
private touchEnabled;
constructor(config?: {
longPressDelay?: number;
touchEnabled?: boolean;
});
/**
* Setup event listeners for an item
*/
setupItemListeners(item: MasonryItem, element: HTMLElement): void;
/**
* Handle mouse enter
*/
private handleMouseEnter;
/**
* Handle mouse leave
*/
private handleMouseLeave;
/**
* Handle click
*/
private handleClick;
/**
* Handle touch start
*/
private handleTouchStart;
/**
* Handle touch end
*/
private handleTouchEnd;
/**
* Handle touch move
*/
private handleTouchMove;
/**
* Handle long press
*/
private handleLongPress;
/**
* Handle key down
*/
private handleKeyDown;
/**
* Dispatch morph event
*/
private dispatchMorphEvent;
/**
* Dispatch custom event
*/
private dispatchEvent;
/**
* Clean up event listeners
*/
cleanupItemListeners(element: HTMLElement): void;
/**
* Get active timers count
*/
getActiveTimersCount(): number;
/**
* Clear all timers
*/
clearAllTimers(): void;
}
/**
* Layout information
*/
export declare interface LayoutInfo {
/**
* Number of columns
*/
columns: number;
/**
* Gap between items
*/
gap: number;
/**
* Container padding
*/
padding: number;
/**
* Container width
*/
containerWidth: number;
/**
* Container height
*/
containerHeight: number;
/**
* Number of items
*/
itemCount: number;
/**
* Heights of each column
*/
columnHeights: number[];
/**
* Current breakpoint
*/
breakpoint?: string;
/**
* Layout algorithm used
*/
algorithm?: string;
}
/**
* HY Live Masonry Configuration Interface
*
* This interface defines all available configuration options for the HY Live Masonry component.
* Each section is clearly documented with its purpose and usage.
*/
export declare interface MasonryConfig {
/**
* Number of columns in the masonry grid
* @default 4
* @min 1
* @max 12
*/
columns?: number;
/**
* Gap between masonry items in pixels
* @default 16
* @min 0
* @max 50
*/
gap?: number;
/**
* Padding around the masonry container in pixels
* @default 20
* @min 0
* @max 100
*/
padding?: number;
/**
* Layout algorithm to use for positioning items
* - 'packed': Items are packed tightly (default)
* - 'loose': Items are positioned with more space
* - 'grid': Strict grid layout
*/
layoutAlgorithm?: 'packed' | 'loose' | 'grid';
/**
* Whether to maintain aspect ratio of items
* @default false
*/
maintainAspectRatio?: boolean;
/**
* Minimum item width in pixels
* @default 100
*/
minItemWidth?: number;
/**
* Maximum item width in pixels
* @default null (unlimited)
*/
maxItemWidth?: number;
/**
* Enable/disable all animations
* @default true
*/
animation?: boolean;
/**
* Duration of animations in milliseconds
* @default 300
* @min 100
* @max 2000
*/
animationDuration?: number;
/**
* Animation easing function
* @default 'ease'
*/
animationEasing?: 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'cubic-bezier(0.4, 0, 0.2, 1)';
/**
* Enable breathing effect on items
* @default true
*/
breathingEffect?: boolean;
/**
* Speed of breathing animation in milliseconds
* @default 2000
* @min 1000
* @max 10000
*/
breathingSpeed?: number;
/**
* Intensity of breathing effect (0-1)
* @default 0.05
* @min 0
* @max 0.2
*/
breathingIntensity?: number;
/**
* Enable entrance animations when items are added
* @default true
*/
entranceAnimation?: boolean;
/**
* Stagger delay between entrance animations in milliseconds
* @default 100
*/
entranceStagger?: number;
/**
* Enable/disable morphing functionality
* @default true
*/
morphing?: boolean;
/**
* Duration of morphing animations in milliseconds
* @default 500
* @min 200
* @max 2000
*/
morphDuration?: number;
/**
* Enable morphing on hover
* @default true
*/
hoverMorph?: boolean;
/**
* Enable morphing on long press
* @default true
*/
longPressMorph?: boolean;
/**
* Enable morphing on click
* @default false
*/
clickMorph?: boolean;
/**
* Default morph size for items
* @default '2x2'
*/
defaultMorphSize?: string;
/**
* Whether to animate morphing transitions
* @default true
*/
animateMorphing?: boolean;
/**
* Morphing easing function
* @default 'cubic-bezier(0.4, 0, 0.2, 1)'
*/
morphEasing?: string;
/**
* Enable responsive behavior
* @default true
*/
responsive?: boolean;
/**
* Breakpoint configuration for different screen sizes
*/
breakpoints?: BreakpointConfig;
/**
* Whether to automatically adjust columns based on container width
* @default true
*/
autoColumns?: boolean;
/**
* Minimum columns to show regardless of screen size
* @default 1
*/
minColumns?: number;
/**
* Maximum columns to show regardless of screen size
* @default 8
*/
maxColumns?: number;
/**
* Delay for long press detection in milliseconds
* @default 500
* @min 200
* @max 2000
*/
longPressDelay?: number;
/**
* Enable touch interactions
* @default true
*/
touchEnabled?: boolean;
/**
* Enable mouse interactions
* @default true
*/
mouseEnabled?: boolean;
/**
* Enable keyboard navigation
* @default false
*/
keyboardEnabled?: boolean;
/**
* Whether items are draggable
* @default false
*/
draggable?: boolean;
/**
* Whether items are sortable
* @default false
*/
sortable?: boolean;
/**
* Enable item selection
* @default false
*/
selectable?: boolean;
/**
* Allow multiple item selection
* @default false
*/
multiSelect?: boolean;
/**
* Theme to apply to the masonry
* @default 'default'
*/
theme?: 'default' | 'dark' | 'minimal' | 'glass' | 'neon' | 'custom';
/**
* Border radius for items in pixels
* @default 8
* @min 0
* @max 50
*/
borderRadius?: number;
/**
* Border width for items in pixels
* @default 1
* @min 0
* @max 10
*/
borderWidth?: number;
/**
* Enable shadows on items
* @default true
*/
shadow?: boolean;
/**
* Shadow intensity (0-1)
* @default 0.1
*/
shadowIntensity?: number;
/**
* Enable hover effects
* @default true
*/
hoverEffects?: boolean;
/**
* Scale factor on hover (1.0 = no scale)
* @default 1.02
* @min 1.0
* @max 1.2
*/
hoverScale?: number;
/**
* Custom CSS class to apply to the masonry container
*/
containerClass?: string;
/**
* Custom CSS class to apply to masonry items
*/
itemClass?: string;
/**
* Custom CSS variables for theming
*/
cssVariables?: Record<string, string>;
/**
* Throttle resize events in milliseconds
* @default 100
* @min 50
* @max 500
*/
throttleResize?: number;
/**
* Use CSS transforms for better performance
* @default true
*/
useTransform?: boolean;
/**
* Enable hardware acceleration
* @default true
*/
hardwareAcceleration?: boolean;
/**
* Enable intersection observer for performance
* @default true
*/
intersectionObserver?: boolean;
/**
* Threshold for intersection observer (0-1)
* @default 0.1
*/
intersectionThreshold?: number;
/**
* Enable virtual scrolling for large datasets
* @default false
*/
virtualScrolling?: boolean;
/**
* Number of items to render in virtual scrolling
* @default 50
*/
virtualItemCount?: number;
/**
* Debounce time for layout updates in milliseconds
* @default 50
*/
layoutDebounce?: number;
/**
* Enable ARIA labels and roles
* @default true
*/
accessibility?: boolean;
/**
* Screen reader announcements
* @default true
*/
screenReaderAnnouncements?: boolean;
/**
* Focus management
* @default true
*/
focusManagement?: boolean;
/**
* High contrast mode support
* @default false
*/
highContrast?: boolean;
/**
* Enable debug mode
* @default false
*/
debug?: boolean;
/**
* Show layout grid overlay
* @default false
*/
showGrid?: boolean;
/**
* Log performance metrics
* @default false
*/
performanceLogging?: boolean;
/**
* Show item boundaries
* @default false
*/
showBoundaries?: boolean;
}
/**
* Masonry event interface
*/
export declare interface MasonryEvent {
detail: {
item?: MasonryItem;
layout?: LayoutInfo;
animation?: string;
morphing?: MorphingState;
breakpoint?: string;
performance?: PerformanceMetrics;
};
}
/**
* Masonry item configuration
*/
export declare interface MasonryItem {
/**
* Unique identifier for the item
*/
id: string;
/**
* Size of the item in format 'colsxrows' (e.g., '1x1', '2x1', '1x2', '2x2')
*/
size: string;
/**
* Minimum size constraint
*/
minSize?: string;
/**
* Maximum size constraint
*/
maxSize?: string;
/**
* HTML content for the item
*/
content?: string;
/**
* Background image URL
*/
image?: string;
/**
* Background color
*/
backgroundColor?: string;
/**
* Text color
*/
textColor?: string;
/**
* Animation type for the item
*/
animationType?: 'breathing' | 'pulse' | 'float' | 'none';
/**
* Delay before animation starts in milliseconds
*/
animationDelay?: number;
/**
* Custom animation function
*/
customAnimation?: AnimationFunction;
/**
* Whether item morphs on hover
*/
morphOnHover?: boolean;
/**
* Whether item morphs on long press
*/
morphOnLongPress?: boolean;
/**
* Target size when morphing
*/
morphSize?: string;
/**
* Duration of morphing animation
*/
morphDuration?: number;
/**
* Whether item is clickable
*/
clickable?: boolean;
/**
* Whether item is hoverable
*/
hoverable?: boolean;
/**
* Whether item is draggable
*/
draggable?: boolean;
/**
* Click event handler
*/
onClick?: (event: Event, item: MasonryItem) => void;
/**
* Hover event handler
*/
onHover?: (event: Event, item: MasonryItem) => void;
/**
* Long press event handler
*/
onLongPress?: (event: Event, item: MasonryItem) => void;
/**
* Morph start event handler
*/
onMorph?: (event: Event, item: MasonryItem) => void;
/**
* Morph end event handler
*/
onMorphEnd?: (event: Event, item: MasonryItem) => void;
/**
* Custom CSS classes for the item
*/
className?: string;
/**
* Custom data attributes
*/
data?: Record<string, string>;
/**
* Whether item is visible
*/
visible?: boolean;
/**
* Z-index for the item
*/
zIndex?: number;
}
export declare class MorphingManager {
private morphingItems;
private originalSizes;
private morphAnimationFrame;
private isRunning;
constructor();
/**
* Morph item to new size
*/
morphItem(itemId: string, targetSize: string, duration?: number): void;
/**
* Reset item to original size
*/
resetItem(itemId: string, duration?: number): void;
/**
* Check if item is currently morphing
*/
isMorphing(itemId: string): boolean;
/**
* Store original size for an item
*/
storeOriginalSize(itemId: string, size: string): void;
/**
* Start morphing animation loop
*/
start(): void;
/**
* Stop morphing animation loop
*/
stop(): void;
/**
* Main morphing animation loop
*/
private animate;
/**
* Dispatch custom event
*/
private dispatchEvent;
/**
* Get morphing items count
*/
getMorphingCount(): number;
/**
* Clear all morphing states
*/
clear(): void;
/**
* Get morphing state for an item
*/
getMorphingState(itemId: string): MorphingState | undefined;
}
/**
* Morphing state information
*/
export declare interface MorphingState {
/**
* Original size before morphing
*/
originalSize: string;
/**
* Target size for morphing
*/
targetSize: string;
/**
* Duration of morphing animation
*/
duration: number;
/**
* Start time of morphing
*/
startTime: number;
/**
* Current progress (0-1)
*/
progress: number;
/**
* Update function for morphing
*/
update: (currentTime: number) => number;
/**
* Check if morphing is complete
*/
isComplete: () => boolean;
}
/**
* Performance metrics
*/
declare interface PerformanceMetrics {
/**
* Layout calculation time in milliseconds
*/
layoutTime: number;
/**
* Animation frame rate
*/
fps: number;
/**
* Memory usage in bytes
*/
memoryUsage: number;
/**
* Number of DOM operations
*/
domOperations: number;
/**
* Timestamp of measurement
*/
timestamp: number;
}
export declare class SizeCalculator {
/**
* Parse size string (e.g., "2x3") into dimensions
*/
static parseSize(sizeString: string): SizeDimensions;
/**
* Calculate actual dimensions for a grid item
*/
static calculateDimensions(size: string, containerWidth: number, gap: number, columns: number): CalculatedDimensions;
/**
* Morph size between original and target
*/
static morphSize(originalSize: string, targetSize: string, progress: number): string;
/**
* Validate size string format
*/
static isValidSize(size: string): boolean;
/**
* Get minimum size for an item
*/
static getMinSize(size: string): string;
/**
* Get maximum size for an item
*/
static getMaxSize(size: string): string;
/**
* Calculate grid position for an item
*/
static calculateGridPosition(_itemIndex: number, _columns: number, columnHeights: number[]): {
x: number;
y: number;
};
/**
* Update column heights after placing an item
*/
static updateColumnHeights(columnHeights: number[], columnIndex: number, itemHeight: number, gap: number): number[];
}
/**
* Size dimensions
*/
export declare interface SizeDimensions {
/**
* Number of columns
*/
cols: number;
/**
* Number of rows
*/
rows: number;
}
/**
* Theme configuration
*/
export declare interface ThemeConfig {
/**
* Theme name
*/
name: string;
/**
* Color palette
*/
colors: {
background: string;
text: string;
border: string;
shadow: string;
hoverShadow: string;
accent: string;
secondary: string;
};
/**
* Border radius
*/
borderRadius: number;
/**
* Shadow configuration
*/
shadow: string;
/**
* Hover shadow configuration
*/
hoverShadow: string;
/**
* Custom CSS variables
*/
variables?: Record<string, string>;
}
export { }