social-masonry 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,550 @@
+/**
+ * Social Masonry - Type Definitions
+ * Beautiful masonry layout for social media embeds
+ */
+type SocialPlatform = 'twitter' | 'instagram';
+interface TwitterPost {
+    platform: 'twitter';
+    id: string;
+    url: string;
+    author: {
+        username: string;
+        displayName: string;
+        avatarUrl?: string;
+        verified?: boolean;
+    };
+    content: {
+        text: string;
+        html?: string;
+    };
+    media?: {
+        type: 'image' | 'video' | 'gif';
+        url: string;
+        thumbnailUrl?: string;
+        aspectRatio?: number;
+        width?: number;
+        height?: number;
+    }[];
+    metrics?: {
+        likes?: number;
+        retweets?: number;
+        replies?: number;
+        views?: number;
+    };
+    createdAt: string | Date;
+    quotedPost?: Omit<TwitterPost, 'quotedPost'>;
+}
+interface InstagramPost {
+    platform: 'instagram';
+    id: string;
+    url: string;
+    author: {
+        username: string;
+        displayName?: string;
+        avatarUrl?: string;
+        verified?: boolean;
+    };
+    content: {
+        caption?: string;
+    };
+    media: {
+        type: 'image' | 'video' | 'carousel';
+        url: string;
+        thumbnailUrl?: string;
+        aspectRatio?: number;
+        width?: number;
+        height?: number;
+        carouselItems?: {
+            type: 'image' | 'video';
+            url: string;
+            thumbnailUrl?: string;
+        }[];
+    };
+    metrics?: {
+        likes?: number;
+        comments?: number;
+    };
+    createdAt: string | Date;
+}
+type SocialPost = TwitterPost | InstagramPost;
+interface ColumnConfig {
+    /** Number of columns at this breakpoint */
+    columns: number;
+    /** Minimum viewport width for this config (px) */
+    minWidth: number;
+}
+interface MasonryConfig {
+    /** Gap between items (px or CSS value) */
+    gap?: number | string;
+    /** Responsive column configuration */
+    columns?: number | ColumnConfig[];
+    /** Default number of columns */
+    defaultColumns?: number;
+    /** Padding around the container */
+    padding?: number | string;
+    /** Animation duration for layout changes (ms) */
+    animationDuration?: number;
+    /** Enable/disable animations */
+    animate?: boolean;
+    /** Transition easing function */
+    easing?: string;
+}
+interface VirtualizationConfig {
+    /** Enable virtualization */
+    enabled?: boolean;
+    /** Number of items to render outside viewport */
+    overscan?: number;
+    /** Estimated item height for initial render */
+    estimatedItemHeight?: number;
+    /** Scroll container element (default: window) */
+    scrollContainer?: HTMLElement | Window | null;
+}
+type CardVariant = 'default' | 'minimal' | 'elevated' | 'bordered' | 'glass';
+type CardTheme = 'light' | 'dark' | 'auto';
+interface CardConfig {
+    /** Card visual variant */
+    variant?: CardVariant;
+    /** Color theme */
+    theme?: CardTheme;
+    /** Border radius (px or CSS value) */
+    borderRadius?: number | string;
+    /** Show platform icon */
+    showPlatformIcon?: boolean;
+    /** Show author info */
+    showAuthor?: boolean;
+    /** Show metrics (likes, comments, etc.) */
+    showMetrics?: boolean;
+    /** Show timestamp */
+    showTimestamp?: boolean;
+    /** Date format function */
+    formatDate?: (date: Date) => string;
+    /** Number format function */
+    formatNumber?: (num: number) => string;
+    /** Custom CSS class */
+    className?: string;
+    /** Enable hover effects */
+    hoverEffect?: boolean;
+    /** Image loading strategy */
+    imageLoading?: 'lazy' | 'eager';
+    /** Fallback image URL */
+    fallbackImage?: string;
+}
+interface MasonryEvents {
+    /** Called when a post card is clicked */
+    onPostClick?: (post: SocialPost, event: MouseEvent) => void;
+    /** Called when author is clicked */
+    onAuthorClick?: (post: SocialPost, event: MouseEvent) => void;
+    /** Called when media is clicked */
+    onMediaClick?: (post: SocialPost, mediaIndex: number, event: MouseEvent) => void;
+    /** Called when layout is recalculated */
+    onLayoutComplete?: (positions: ItemPosition[]) => void;
+    /** Called when scrolling reaches near the end */
+    onLoadMore?: () => void | Promise<void>;
+    /** Called when an image fails to load */
+    onImageError?: (post: SocialPost, error: Error) => void;
+}
+interface ItemPosition {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    column: number;
+}
+interface LayoutState {
+    positions: Map<string, ItemPosition>;
+    columnHeights: number[];
+    containerHeight: number;
+    columnWidth: number;
+}
+interface VirtualItem {
+    index: number;
+    post: SocialPost;
+    position: ItemPosition;
+    isVisible: boolean;
+}
+interface SocialMasonryOptions extends MasonryConfig, CardConfig, MasonryEvents {
+    /** Posts to display */
+    posts: SocialPost[];
+    /** Container element or selector */
+    container: HTMLElement | string;
+    /** Virtualization settings */
+    virtualization?: VirtualizationConfig;
+    /** Load more threshold (px from bottom) */
+    loadMoreThreshold?: number;
+    /** Show loading indicator */
+    showLoading?: boolean;
+    /** Custom loading element */
+    loadingElement?: HTMLElement | string;
+    /** Empty state message */
+    emptyMessage?: string;
+    /** Custom empty state element */
+    emptyElement?: HTMLElement | string;
+    /** Enable debug mode */
+    debug?: boolean;
+}
+interface SocialMasonryProps extends Omit<SocialMasonryOptions, 'container'> {
+    /** Additional CSS class for container */
+    className?: string;
+    /** Inline styles for container */
+    style?: React.CSSProperties;
+    /** Ref to container element */
+    containerRef?: React.RefObject<HTMLDivElement>;
+}
+
+declare class SocialMasonry {
+    private options;
+    private container;
+    private posts;
+    private layoutEngine;
+    private virtualizationEngine;
+    private cardRenderer;
+    private cards;
+    private itemHeights;
+    private resizeObserver;
+    private isLoading;
+    private instanceId;
+    constructor(options: SocialMasonryOptions);
+    /**
+     * Setup container styles
+     */
+    private setupContainer;
+    /**
+     * Setup resize observer
+     */
+    private setupResizeObserver;
+    /**
+     * Handle container resize
+     */
+    private handleResize;
+    /**
+     * Initialize virtualization
+     */
+    private initVirtualization;
+    /**
+     * Handle visible items change (for virtualization)
+     */
+    private handleVisibleItemsChange;
+    /**
+     * Setup infinite scroll
+     */
+    private setupInfiniteScroll;
+    /**
+     * Load more posts
+     */
+    private loadMore;
+    /**
+     * Show loading indicator
+     */
+    private showLoadingIndicator;
+    /**
+     * Hide loading indicator
+     */
+    private hideLoadingIndicator;
+    /**
+     * Render all posts
+     */
+    private render;
+    /**
+     * Render a single card
+     */
+    private renderCard;
+    /**
+     * Recalculate layout
+     */
+    private recalculateLayout;
+    /**
+     * Show empty state
+     */
+    private showEmptyState;
+    /**
+     * Hide empty state
+     */
+    private hideEmptyState;
+    /**
+     * Add posts
+     */
+    addPosts(posts: SocialPost[]): void;
+    /**
+     * Set posts (replace all)
+     */
+    setPosts(posts: SocialPost[]): void;
+    /**
+     * Remove post
+     */
+    removePost(id: string): void;
+    /**
+     * Update options
+     */
+    setOptions(options: Partial<SocialMasonryOptions>): void;
+    /**
+     * Get layout state
+     */
+    getLayoutState(): LayoutState;
+    /**
+     * Get posts
+     */
+    getPosts(): SocialPost[];
+    /**
+     * Scroll to post
+     */
+    scrollToPost(id: string, behavior?: ScrollBehavior): void;
+    /**
+     * Refresh layout
+     */
+    refresh(): void;
+    /**
+     * Destroy instance
+     */
+    destroy(): void;
+}
+/**
+ * Create a new SocialMasonry instance
+ */
+declare function createSocialMasonry(options: SocialMasonryOptions): SocialMasonry;
+
+/**
+ * Social Masonry - Layout Engine
+ * Calculates positions for masonry grid items
+ */
+
+interface LayoutEngineOptions extends MasonryConfig {
+    containerWidth: number;
+    itemHeights: Map<string, number>;
+}
+declare class LayoutEngine {
+    private options;
+    private state;
+    constructor(options: LayoutEngineOptions);
+    /**
+     * Calculate layout for all posts
+     */
+    calculate(posts: SocialPost[]): LayoutState;
+    /**
+     * Estimate item height based on content
+     */
+    private estimateHeight;
+    /**
+     * Update single item height and recalculate affected items
+     */
+    updateItemHeight(id: string, height: number): void;
+    /**
+     * Get current layout state
+     */
+    getState(): LayoutState;
+    /**
+     * Get position for specific item
+     */
+    getPosition(id: string): ItemPosition | undefined;
+    /**
+     * Update container width
+     */
+    setContainerWidth(width: number): void;
+    /**
+     * Get current column count
+     */
+    getColumnCount(): number;
+    /**
+     * Get CSS variables for animations
+     */
+    getCSSVariables(): Record<string, string>;
+}
+/**
+ * Create a new layout engine instance
+ */
+declare function createLayoutEngine(options: LayoutEngineOptions): LayoutEngine;
+
+/**
+ * Social Masonry - Virtualization Engine
+ * Handles virtual scrolling for large lists
+ */
+
+interface VirtualizationEngineOptions extends VirtualizationConfig {
+    posts: SocialPost[];
+    positions: Map<string, ItemPosition>;
+    onVisibleItemsChange?: (items: VirtualItem[]) => void;
+}
+declare class VirtualizationEngine {
+    private options;
+    private posts;
+    private positions;
+    private visibleItems;
+    private scrollHandler;
+    private rafId;
+    private lastScrollTop;
+    private isScrolling;
+    private scrollEndTimeout;
+    private onVisibleItemsChange?;
+    constructor(options: VirtualizationEngineOptions);
+    /**
+     * Initialize scroll listener
+     */
+    init(): void;
+    /**
+     * Destroy and cleanup
+     */
+    destroy(): void;
+    /**
+     * Handle scroll event
+     */
+    private handleScroll;
+    /**
+     * Calculate which items are visible
+     */
+    calculateVisibleItems(): VirtualItem[];
+    /**
+     * Check if visible items have changed
+     */
+    private hasVisibleItemsChanged;
+    /**
+     * Update posts and positions
+     */
+    update(posts: SocialPost[], positions: Map<string, ItemPosition>): void;
+    /**
+     * Get visible items
+     */
+    getVisibleItems(): VirtualItem[];
+    /**
+     * Get all items (for non-virtualized mode)
+     */
+    getAllItems(): VirtualItem[];
+    /**
+     * Check if scrolling
+     */
+    getIsScrolling(): boolean;
+    /**
+     * Get scroll direction
+     */
+    getScrollDirection(): 'up' | 'down' | 'none';
+    /**
+     * Check if near bottom (for infinite scroll)
+     */
+    isNearBottom(threshold?: number): boolean;
+    /**
+     * Scroll to item
+     */
+    scrollToItem(id: string, behavior?: ScrollBehavior): void;
+    /**
+     * Get render range for optimization
+     */
+    getRenderRange(): {
+        start: number;
+        end: number;
+    };
+}
+/**
+ * Create a new virtualization engine instance
+ */
+declare function createVirtualizationEngine(options: VirtualizationEngineOptions): VirtualizationEngine;
+
+/**
+ * Social Masonry - Card Renderer
+ * Renders social media post cards with proper styling
+ */
+
+interface CardRendererOptions extends CardConfig {
+    onPostClick?: (post: SocialPost, event: MouseEvent) => void;
+    onAuthorClick?: (post: SocialPost, event: MouseEvent) => void;
+    onMediaClick?: (post: SocialPost, mediaIndex: number, event: MouseEvent) => void;
+    onImageError?: (post: SocialPost, error: Error) => void;
+}
+declare class CardRenderer {
+    private options;
+    constructor(options?: CardRendererOptions);
+    /**
+     * Render a single card
+     */
+    render(post: SocialPost, position: ItemPosition): HTMLElement;
+    /**
+     * Get CSS classes for card
+     */
+    private getCardClasses;
+    /**
+     * Build card HTML
+     */
+    private buildCardHTML;
+    /**
+     * Render platform icon
+     */
+    private renderPlatformIcon;
+    /**
+     * Render card header
+     */
+    private renderHeader;
+    /**
+     * Render card content
+     */
+    private renderContent;
+    /**
+     * Render Twitter content
+     */
+    private renderTwitterContent;
+    /**
+     * Render Instagram content
+     */
+    private renderInstagramContent;
+    /**
+     * Render media
+     */
+    private renderMedia;
+    /**
+     * Render Twitter media
+     */
+    private renderTwitterMedia;
+    /**
+     * Render Instagram media
+     */
+    private renderInstagramMedia;
+    /**
+     * Render footer with metrics
+     */
+    private renderFooter;
+    /**
+     * Render metrics
+     */
+    private renderMetrics;
+    /**
+     * Linkify text (URLs, mentions, hashtags)
+     */
+    private linkifyText;
+    /**
+     * Attach event listeners
+     */
+    private attachEventListeners;
+    /**
+     * Update card position
+     */
+    updatePosition(card: HTMLElement, position: ItemPosition): void;
+    /**
+     * Update options
+     */
+    setOptions(options: Partial<CardRendererOptions>): void;
+}
+/**
+ * Create a new card renderer instance
+ */
+declare function createCardRenderer(options?: CardRendererOptions): CardRenderer;
+
+/**
+ * Default responsive column configuration
+ */
+declare const defaultColumnConfig: ColumnConfig[];
+/**
+ * Format number with abbreviations (1K, 1M, etc.)
+ */
+declare function formatNumber(num: number): string;
+/**
+ * Format relative time
+ */
+declare function formatRelativeTime(date: Date): string;
+/**
+ * Type guard for Twitter posts
+ */
+declare function isTwitterPost(post: SocialPost): post is TwitterPost;
+/**
+ * Type guard for Instagram posts
+ */
+declare function isInstagramPost(post: SocialPost): post is InstagramPost;
+
+export { CardRenderer, LayoutEngine, SocialMasonry, VirtualizationEngine, createCardRenderer, createLayoutEngine, createSocialMasonry, createVirtualizationEngine, SocialMasonry as default, defaultColumnConfig, formatNumber, formatRelativeTime, isInstagramPost, isTwitterPost };
+export type { CardConfig, CardTheme, CardVariant, ColumnConfig, InstagramPost, ItemPosition, LayoutState, MasonryConfig, MasonryEvents, SocialMasonryOptions, SocialMasonryProps, SocialPlatform, SocialPost, TwitterPost, VirtualItem, VirtualizationConfig };