social-masonry 1.0.0 → 1.0.1

package/README.md

@@ -1,291 +1,103 @@
 <div align="center">
-  <img src="https://raw.githubusercontent.com/tkana-dev/social-masonry/main/assets/logo.svg" alt="Social Masonry" width="120" />
   <h1>Social Masonry</h1>
-  <p><strong>Beautiful masonry layout for X (Twitter) and Instagram embeds</strong></p>
-  
+  <p><strong>Masonry layout for X (Twitter) and Instagram embeds using official widgets</strong></p>
+
   [![npm version](https://img.shields.io/npm/v/social-masonry.svg)](https://www.npmjs.com/package/social-masonry)
   [![bundle size](https://img.shields.io/bundlephobia/minzip/social-masonry)](https://bundlephobia.com/package/social-masonry)
   [![license](https://img.shields.io/npm/l/social-masonry.svg)](https://github.com/tkana-dev/social-masonry/blob/main/LICENSE)
   [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
-  
-  <a href="https://social-masonry.dev">Demo</a> · <a href="#installation">Installation</a> · <a href="#usage">Usage</a> · <a href="#api">API</a>
 </div>
 
 ---
 
-<p align="center">
-  <img src="https://raw.githubusercontent.com/tkana-dev/social-masonry/main/assets/demo.gif" alt="Demo" width="100%" />
-</p>
-
-## ✨ Features
+## Features
 
-- 🎨 **Beautiful Cards** - Native-looking X and Instagram post cards with 5 design variants
-- ⚡ **High Performance** - Virtual scrolling for smooth rendering of thousands of posts
-- 📱 **Responsive** - Adaptive column layouts that look great on any screen size
-- 🎭 **Themeable** - Light, dark, and auto themes with full customization
-- 🔄 **Infinite Scroll** - Built-in load more functionality
-- 🎯 **TypeScript** - Full type safety and excellent DX
-- ⚛️ **React Ready** - First-class React component with hooks
-- 🪶 **Lightweight** - ~8KB gzipped with zero dependencies
+- **Official Widgets** - Uses Twitter's `widgets.js` and Instagram's `embed.js` for native embeds
+- **Auto-sizing** - Embeds automatically adjust to their content height
+- **Responsive** - Adaptive column layouts that look great on any screen size
+- **Themeable** - Light and dark theme support for Twitter embeds
+- **TypeScript** - Full type safety
+- **React Ready** - First-class React component with ref support
+- **Lightweight** - Minimal bundle size, widgets loaded on-demand
 
-## 📦 Installation
+## Installation
 
 ```bash
-# npm
 npm install social-masonry
-
-# yarn
-yarn add social-masonry
-
-# pnpm
-pnpm add social-masonry
 ```
 
-## 🚀 Quick Start
-
-### Vanilla JavaScript
-
-```javascript
-import { createSocialMasonry } from 'social-masonry';
-import 'social-masonry/styles';
-
-const masonry = createSocialMasonry({
-  container: '#posts',
-  posts: [
-    {
-      platform: 'twitter',
-      id: '1',
-      url: 'https://twitter.com/user/status/123',
-      author: {
-        username: 'johndoe',
-        displayName: 'John Doe',
-        avatarUrl: 'https://...',
-        verified: true,
-      },
-      content: {
-        text: 'Hello, world! 🌍',
-      },
-      metrics: {
-        likes: 1234,
-        retweets: 567,
-        replies: 89,
-      },
-      createdAt: '2024-01-15T10:30:00Z',
-    },
-    // ... more posts
-  ],
-});
-
-// Add more posts
-masonry.addPosts(newPosts);
-
-// Clean up
-masonry.destroy();
-```
+## Quick Start
 
 ### React
 
 ```tsx
 import { SocialMasonry } from 'social-masonry/react';
-import 'social-masonry/styles';
 
 function App() {
-  const posts = usePosts();
-  
+  const posts = [
+    {
+      id: '1',
+      platform: 'twitter',
+      url: 'https://twitter.com/username/status/1234567890',
+    },
+    {
+      id: '2',
+      platform: 'instagram',
+      url: 'https://www.instagram.com/p/ABC123xyz/',
+    },
+  ];
+
   return (
     <SocialMasonry
       posts={posts}
       columns={[
-        { columns: 4, minWidth: 1200 },
-        { columns: 3, minWidth: 900 },
-        { columns: 2, minWidth: 600 },
+        { columns: 4, minWidth: 1536 },
+        { columns: 3, minWidth: 1024 },
+        { columns: 2, minWidth: 640 },
         { columns: 1, minWidth: 0 },
       ]}
       gap={16}
-      variant="elevated"
-      theme="auto"
-      onPostClick={(post) => window.open(post.url)}
+      theme="light"
     />
   );
 }
 ```
 
-## 📖 Usage
-
-### Post Types
+## API
 
-#### Twitter/X Post
+### SocialMasonry Props
 
-```typescript
-const twitterPost: TwitterPost = {
-  platform: 'twitter',
-  id: 'unique-id',
-  url: 'https://twitter.com/user/status/123',
-  author: {
-    username: 'johndoe',
-    displayName: 'John Doe',
-    avatarUrl: 'https://example.com/avatar.jpg',
-    verified: true,
-  },
-  content: {
-    text: 'This is my tweet! #awesome',
-    html: 'This is my tweet! <a href="#">#awesome</a>', // Optional: pre-rendered HTML
-  },
-  media: [
-    {
-      type: 'image',
-      url: 'https://example.com/image.jpg',
-      aspectRatio: 16 / 9,
-    },
-  ],
-  metrics: {
-    likes: 1234,
-    retweets: 567,
-    replies: 89,
-    views: 50000,
-  },
-  quotedPost: { /* nested TwitterPost */ }, // Optional
-  createdAt: '2024-01-15T10:30:00Z',
-};
-```
-
-#### Instagram Post
-
-```typescript
-const instagramPost: InstagramPost = {
-  platform: 'instagram',
-  id: 'unique-id',
-  url: 'https://instagram.com/p/ABC123',
-  author: {
-    username: 'janedoe',
-    displayName: 'Jane Doe',
-    avatarUrl: 'https://example.com/avatar.jpg',
-    verified: false,
-  },
-  content: {
-    caption: 'Beautiful sunset 🌅 #photography',
-  },
-  media: {
-    type: 'image', // 'image' | 'video' | 'carousel'
-    url: 'https://example.com/image.jpg',
-    aspectRatio: 1, // Square
-    carouselItems: [ /* for carousel type */ ],
-  },
-  metrics: {
-    likes: 5678,
-    comments: 123,
-  },
-  createdAt: '2024-01-15T10:30:00Z',
-};
-```
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `posts` | `SocialPost[]` | `[]` | Array of posts to display |
+| `columns` | `number \| ColumnConfig[]` | `3` | Number of columns or responsive config |
+| `gap` | `number` | `16` | Gap between items in pixels |
+| `theme` | `'light' \| 'dark'` | `'light'` | Theme for Twitter embeds |
+| `className` | `string` | - | Custom class for container |
+| `style` | `CSSProperties` | - | Custom styles for container |
+| `onEmbedLoad` | `(post: SocialPost) => void` | - | Called when an embed loads |
+| `onEmbedError` | `(post: SocialPost, error: Error) => void` | - | Called on embed error |
 
-### Configuration Options
+### SocialPost Type
 
 ```typescript
-const masonry = createSocialMasonry({
-  // Required
-  container: '#posts', // Element or selector
-  posts: [], // Array of SocialPost
-  
-  // Layout
-  gap: 16, // Gap between cards (px)
-  columns: [ // Responsive breakpoints
-    { columns: 4, minWidth: 1200 },
-    { columns: 3, minWidth: 900 },
-    { columns: 2, minWidth: 600 },
-    { columns: 1, minWidth: 0 },
-  ],
-  padding: 0, // Container padding
-  
-  // Animation
-  animate: true,
-  animationDuration: 300,
-  easing: 'cubic-bezier(0.4, 0, 0.2, 1)',
-  
-  // Card Styling
-  variant: 'default', // 'default' | 'minimal' | 'elevated' | 'bordered' | 'glass'
-  theme: 'auto', // 'light' | 'dark' | 'auto'
-  borderRadius: 12,
-  hoverEffect: true,
-  
-  // Content
-  showPlatformIcon: true,
-  showAuthor: true,
-  showMetrics: true,
-  showTimestamp: true,
-  
-  // Custom Formatters
-  formatDate: (date) => formatRelativeTime(date),
-  formatNumber: (num) => formatNumber(num),
-  
-  // Image Loading
-  imageLoading: 'lazy', // 'lazy' | 'eager'
-  fallbackImage: 'https://...', // Fallback for broken images
-  
-  // Virtualization (for large lists)
-  virtualization: {
-    enabled: false,
-    overscan: 3,
-    estimatedItemHeight: 400,
-    scrollContainer: null, // Default: window
-  },
-  
-  // Infinite Scroll
-  loadMoreThreshold: 500,
-  showLoading: true,
-  loadingElement: '<div>Loading...</div>',
-  emptyMessage: 'No posts to display',
-  
-  // Events
-  onPostClick: (post, event) => {},
-  onAuthorClick: (post, event) => {},
-  onMediaClick: (post, mediaIndex, event) => {},
-  onLayoutComplete: (positions) => {},
-  onLoadMore: async () => {},
-  onImageError: (post, error) => {},
-});
+interface SocialPost {
+  id?: string;                         // Optional unique identifier
+  platform: 'twitter' | 'instagram';   // Social platform
+  url: string;                         // Post URL
+}
 ```
 
-### Card Variants
-
-| Variant | Description |
-|---------|-------------|
-| `default` | Clean card with subtle border and shadow |
-| `minimal` | No background, perfect for embedding |
-| `elevated` | Floating card with prominent shadow |
-| `bordered` | Strong border, no shadow |
-| `glass` | Glassmorphism effect with blur |
-
-### API Methods
+### ColumnConfig Type
 
 ```typescript
-// Add posts to the end
-masonry.addPosts(newPosts);
-
-// Replace all posts
-masonry.setPosts(posts);
-
-// Remove a post
-masonry.removePost(postId);
-
-// Update options
-masonry.setOptions({ theme: 'dark' });
-
-// Get current state
-const state = masonry.getLayoutState();
-const posts = masonry.getPosts();
-
-// Scroll to a post
-masonry.scrollToPost(postId, 'smooth');
-
-// Recalculate layout
-masonry.refresh();
-
-// Clean up
-masonry.destroy();
+interface ColumnConfig {
+  columns: number;   // Number of columns
+  minWidth: number;  // Minimum container width for this config
+}
 ```
 
-### React Hooks
+### Ref Methods
 
 ```tsx
 import { useRef } from 'react';
@@ -293,87 +105,71 @@ import { SocialMasonry, SocialMasonryRef } from 'social-masonry/react';
 
 function App() {
   const masonryRef = useRef<SocialMasonryRef>(null);
-  
+
   const handleAddPost = () => {
     masonryRef.current?.addPosts([newPost]);
   };
-  
+
   return (
     <SocialMasonry
       ref={masonryRef}
       posts={posts}
-      // ...
     />
   );
 }
 ```
 
-## 🎨 Customization
-
-### CSS Variables
-
-Override the default theme using CSS variables:
-
-```css
-:root {
-  /* Colors */
-  --sm-bg: #ffffff;
-  --sm-bg-hover: #f7f9fa;
-  --sm-text: #0f1419;
-  --sm-text-secondary: #536471;
-  --sm-text-muted: #8b98a5;
-  --sm-border: #eff3f4;
-  --sm-link: #1d9bf0;
-  
-  /* Brand Colors */
-  --sm-twitter-primary: #1d9bf0;
-  --sm-instagram-primary: #e1306c;
-  
-  /* Shadows */
-  --sm-shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.04);
-  --sm-shadow-md: 0 4px 12px rgba(0, 0, 0, 0.08);
-  --sm-shadow-lg: 0 8px 24px rgba(0, 0, 0, 0.12);
-  
-  /* Transitions */
-  --sm-transition-fast: 150ms ease;
-  --sm-transition-base: 200ms ease;
-}
-```
+Available ref methods:
 
-### Custom Classes
+| Method | Description |
+|--------|-------------|
+| `addPosts(posts)` | Add posts to the end |
+| `setPosts(posts)` | Replace all posts |
+| `removePost(id)` | Remove a post by ID |
+| `refresh()` | Re-process embeds |
 
-Add custom classes to cards:
+## Supported URL Formats
 
-```typescript
-createSocialMasonry({
-  className: 'my-custom-card',
-  // ...
-});
-```
+### Twitter/X
+
+- `https://twitter.com/username/status/1234567890`
+- `https://x.com/username/status/1234567890`
 
-## 📊 Performance
+### Instagram
 
-Social Masonry is optimized for performance:
+- `https://www.instagram.com/p/ABC123xyz/`
+- `https://www.instagram.com/reel/ABC123xyz/`
 
-- **Virtual Scrolling**: Only renders visible cards, enabling smooth scrolling with 10,000+ posts
-- **Efficient Layout**: Uses a columnar algorithm with O(n) complexity
-- **Smart Updates**: Batched DOM updates and position caching
-- **Lazy Loading**: Images load only when cards enter the viewport
+## Utilities
 
-Enable virtualization for large datasets:
+The library exports utility functions for URL parsing:
 
 ```typescript
-createSocialMasonry({
-  virtualization: {
-    enabled: true,
-    overscan: 3, // Extra items to render above/below viewport
-    estimatedItemHeight: 400,
-  },
-  // ...
-});
+import {
+  extractTweetId,
+  extractInstagramId,
+  detectPlatform,
+} from 'social-masonry';
+
+// Extract tweet ID from URL
+extractTweetId('https://x.com/user/status/123456'); // '123456'
+
+// Extract Instagram post ID
+extractInstagramId('https://instagram.com/p/ABC123'); // 'ABC123'
+
+// Detect platform from URL
+detectPlatform('https://x.com/user/status/123'); // 'twitter'
+detectPlatform('https://instagram.com/p/ABC'); // 'instagram'
 ```
 
-## 🌐 Browser Support
+## How It Works
+
+1. **Script Loading**: Twitter's `widgets.js` and Instagram's `embed.js` are loaded on-demand when needed
+2. **Widget Creation**: Official APIs (`twttr.widgets.createTweet` and `instgrm.Embeds.process`) create native embeds
+3. **Masonry Layout**: Posts are distributed across columns using a simple round-robin algorithm
+4. **Auto-sizing**: Each embed automatically sizes to its content - no fixed heights
+
+## Browser Support
 
 | Browser | Version |
 |---------|---------|
@@ -382,13 +178,6 @@ createSocialMasonry({
 | Safari | 14+ |
 | Edge | 80+ |
 
-## 📄 License
+## License
 
-MIT © [tkana_dev](https://github.com/tkana-dev)
-
----
-
-<div align="center">
-  <p>If you find this project useful, please consider giving it a ⭐️</p>
-  <a href="https://github.com/tkana-dev/social-masonry">GitHub</a> · <a href="https://www.npmjs.com/package/social-masonry">npm</a> · <a href="https://social-masonry.dev">Demo</a>
-</div>
+MIT