social-masonry 1.0.0 → 1.0.1

package/dist/index.d.ts

@@ -1,72 +1,16 @@
 /**
  * Social Masonry - Type Definitions
- * Beautiful masonry layout for social media embeds
+ * Masonry layout for social media iframe embeds
  */
 type SocialPlatform = 'twitter' | 'instagram';
-interface TwitterPost {
-    platform: 'twitter';
-    id: string;
+interface SocialPost {
+    /** Unique identifier (auto-generated from URL if not provided) */
+    id?: string;
+    /** Social media platform */
+    platform: SocialPlatform;
+    /** Post URL */
     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;
@@ -74,74 +18,36 @@ interface ColumnConfig {
     minWidth: number;
 }
 interface MasonryConfig {
-    /** Gap between items (px or CSS value) */
-    gap?: number | string;
+    /** Gap between items (px) */
+    gap?: number;
     /** Responsive column configuration */
     columns?: number | ColumnConfig[];
-    /** Default number of columns */
-    defaultColumns?: number;
-    /** Padding around the container */
-    padding?: number | string;
+    /** Padding around the container (px) */
+    padding?: number;
     /** 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 EmbedConfig {
+    /** Theme for embeds: 'light' or 'dark' */
+    theme?: 'light' | 'dark';
+    /** Default height for Twitter embeds (px) */
+    twitterHeight?: number;
+    /** Default height for Instagram embeds (px) */
+    instagramHeight?: number;
+    /** Hide Twitter card (show only text) */
+    twitterHideCard?: boolean;
+    /** Hide Twitter conversation thread */
+    twitterHideThread?: boolean;
 }
 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;
+    /** Called when an embed loads */
+    onEmbedLoad?: (post: SocialPost) => void;
+    /** Called when an embed fails to load */
+    onEmbedError?: (post: SocialPost, error: Error) => void;
 }
 interface ItemPosition {
     id: string;
@@ -157,152 +63,19 @@ interface LayoutState {
     containerHeight: number;
     columnWidth: number;
 }
-interface VirtualItem {
-    index: number;
-    post: SocialPost;
-    position: ItemPosition;
-    isVisible: boolean;
-}
-interface SocialMasonryOptions extends MasonryConfig, CardConfig, MasonryEvents {
+interface SocialMasonryOptions extends MasonryConfig, EmbedConfig, 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;
+    /** Container element or selector (for vanilla JS) */
+    container?: HTMLElement | string;
 }
 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
@@ -311,6 +84,8 @@ declare function createSocialMasonry(options: SocialMasonryOptions): SocialMason
 interface LayoutEngineOptions extends MasonryConfig {
     containerWidth: number;
     itemHeights: Map<string, number>;
+    twitterHeight?: number;
+    instagramHeight?: number;
 }
 declare class LayoutEngine {
     private options;
@@ -321,11 +96,11 @@ declare class LayoutEngine {
      */
     calculate(posts: SocialPost[]): LayoutState;
     /**
-     * Estimate item height based on content
+     * Get default height for embed based on platform
      */
-    private estimateHeight;
+    private getDefaultHeight;
     /**
-     * Update single item height and recalculate affected items
+     * Update single item height
      */
     updateItemHeight(id: string, height: number): void;
     /**
@@ -344,10 +119,6 @@ declare class LayoutEngine {
      * Get current column count
      */
     getColumnCount(): number;
-    /**
-     * Get CSS variables for animations
-     */
-    getCSSVariables(): Record<string, string>;
 }
 /**
  * Create a new layout engine instance
@@ -355,196 +126,50 @@ declare class LayoutEngine {
 declare function createLayoutEngine(options: LayoutEngineOptions): LayoutEngine;
 
 /**
- * Social Masonry - Virtualization Engine
- * Handles virtual scrolling for large lists
+ * Social Masonry - Utility Functions
  */
 
-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
+ * Extract tweet ID from Twitter/X URL
  */
-declare function createVirtualizationEngine(options: VirtualizationEngineOptions): VirtualizationEngine;
-
+declare function extractTweetId(url: string): string | null;
 /**
- * Social Masonry - Card Renderer
- * Renders social media post cards with proper styling
+ * Extract post ID from Instagram URL
  */
-
-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;
-}
+declare function extractInstagramId(url: string): string | null;
 /**
- * Create a new card renderer instance
+ * Detect platform from URL
  */
-declare function createCardRenderer(options?: CardRendererOptions): CardRenderer;
-
+declare function detectPlatform(url: string): SocialPlatform | null;
 /**
- * Default responsive column configuration
+ * Generate embed URL for Twitter
  */
-declare const defaultColumnConfig: ColumnConfig[];
+declare function getTwitterEmbedUrl(tweetId: string, options?: {
+    theme?: 'light' | 'dark';
+    hideCard?: boolean;
+    hideThread?: boolean;
+}): string;
 /**
- * Format number with abbreviations (1K, 1M, etc.)
+ * Generate embed URL for Instagram
  */
-declare function formatNumber(num: number): string;
+declare function getInstagramEmbedUrl(postId: string): string;
 /**
- * Format relative time
+ * Generate unique ID from post URL
  */
-declare function formatRelativeTime(date: Date): string;
+declare function generatePostId(post: SocialPost): string;
 /**
- * Type guard for Twitter posts
+ * Get number of columns based on viewport width
  */
-declare function isTwitterPost(post: SocialPost): post is TwitterPost;
+declare function getColumnCount(columns: number | ColumnConfig[], containerWidth: number): number;
+/**
+ * Default responsive column configuration
+ */
+declare const defaultColumnConfig: ColumnConfig[];
 /**
- * Type guard for Instagram posts
+ * Default embed heights
  */
-declare function isInstagramPost(post: SocialPost): post is InstagramPost;
+declare const DEFAULT_TWITTER_HEIGHT = 500;
+declare const DEFAULT_INSTAGRAM_HEIGHT = 600;
 
-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 };
+export { DEFAULT_INSTAGRAM_HEIGHT, DEFAULT_TWITTER_HEIGHT, LayoutEngine, createLayoutEngine, defaultColumnConfig, detectPlatform, extractInstagramId, extractTweetId, generatePostId, getColumnCount, getInstagramEmbedUrl, getTwitterEmbedUrl };
+export type { ColumnConfig, EmbedConfig, ItemPosition, LayoutState, MasonryConfig, MasonryEvents, SocialMasonryOptions, SocialMasonryProps, SocialPlatform, SocialPost };