@delightui/components 0.1.104 → 0.1.106

package/docs/components/molecules/GridItem.md

@@ -0,0 +1,834 @@
+# GridItem
+
+## Description
+
+An individual grid item component designed to work within the Grid component. Provides flexible control over item positioning and spanning with columnSpan and rowSpan properties, enabling complex grid layouts with items that can occupy multiple cells.
+
+## Aliases
+
+- GridItem
+- GridCell
+- GridChild
+- GridElement
+- LayoutItem
+
+## Props Breakdown
+
+**Extends:** HTMLAttributes<HTMLDivElement> (inherits all div element properties)
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `columnSpan` | `number` | `1` | No | Number of columns the item should span |
+| `rowSpan` | `number` | `1` | No | Number of rows the item should span |
+| `children` | `ReactNode` | - | Yes | Content to be displayed within the grid item |
+| `className` | `string` | - | No | Additional CSS class names |
+| `style` | `CSSProperties` | - | No | Inline styles for the grid item |
+
+## Examples
+
+### Basic Grid Items
+```tsx
+import { Grid, GridItem, Card, Text } from '@delightui/components';
+
+function BasicGridItemExample() {
+  return (
+    <Grid columns={3} className="basic-grid">
+      <GridItem>
+        <Card>
+          <Text type="Heading6">Regular Item</Text>
+          <Text>This item spans 1 column and 1 row</Text>
+        </Card>
+      </GridItem>
+      
+      <GridItem columnSpan={2}>
+        <Card>
+          <Text type="Heading6">Wide Item</Text>
+          <Text>This item spans 2 columns and 1 row</Text>
+        </Card>
+      </GridItem>
+      
+      <GridItem rowSpan={2}>
+        <Card>
+          <Text type="Heading6">Tall Item</Text>
+          <Text>This item spans 1 column and 2 rows</Text>
+        </Card>
+      </GridItem>
+      
+      <GridItem>
+        <Card>
+          <Text type="Heading6">Regular Item</Text>
+          <Text>Another regular item</Text>
+        </Card>
+      </GridItem>
+      
+      <GridItem columnSpan={2} rowSpan={2}>
+        <Card>
+          <Text type="Heading6">Large Item</Text>
+          <Text>This item spans 2 columns and 2 rows</Text>
+        </Card>
+      </GridItem>
+    </Grid>
+  );
+}
+```
+
+### News Layout Grid
+```tsx
+function NewsLayoutExample() {
+  const articles = [
+    {
+      id: 1,
+      title: 'Breaking: Major Tech Announcement',
+      excerpt: 'Industry leaders gather to discuss the future of technology...',
+      category: 'Technology',
+      image: '/news1.jpg',
+      featured: true
+    },
+    {
+      id: 2,
+      title: 'Market Update: Stocks Rise',
+      excerpt: 'Financial markets show positive trends...',
+      category: 'Finance',
+      image: '/news2.jpg'
+    },
+    {
+      id: 3,
+      title: 'Sports: Championship Finals',
+      excerpt: 'Teams prepare for the ultimate showdown...',
+      category: 'Sports',
+      image: '/news3.jpg'
+    },
+    {
+      id: 4,
+      title: 'Weather Alert: Storm Approaching',
+      excerpt: 'Meteorologists warn of severe weather conditions...',
+      category: 'Weather',
+      image: '/news4.jpg'
+    },
+    {
+      id: 5,
+      title: 'Health: New Research Findings',
+      excerpt: 'Scientists discover breakthrough in medical research...',
+      category: 'Health',
+      image: '/news5.jpg'
+    }
+  ];
+
+  return (
+    <div className="news-layout">
+      <Text type="Heading3">Latest News</Text>
+      
+      <Grid columns={4} className="news-grid">
+        {articles.map((article, index) => (
+          <GridItem 
+            key={article.id}
+            columnSpan={article.featured ? 2 : 1}
+            rowSpan={article.featured ? 2 : 1}
+          >
+            <Card className={`news-card ${article.featured ? 'featured' : ''}`}>
+              <Image 
+                src={article.image} 
+                alt={article.title}
+                className="news-image"
+                fit="Cover"
+              />
+              
+              <div className="news-content">
+                <Chip size="Small" className="category-chip">
+                  {article.category}
+                </Chip>
+                
+                <Text 
+                  type={article.featured ? 'Heading4' : 'Heading6'}
+                  className="news-title"
+                >
+                  {article.title}
+                </Text>
+                
+                <Text 
+                  type={article.featured ? 'Body' : 'BodySmall'}
+                  className="news-excerpt"
+                >
+                  {article.excerpt}
+                </Text>
+                
+                <Button type="Text" size="Small">
+                  Read More →
+                </Button>
+              </div>
+            </Card>
+          </GridItem>
+        ))}
+      </Grid>
+    </div>
+  );
+}
+```
+
+### Dashboard Widgets
+```tsx
+function DashboardWidgetsExample() {
+  const widgets = [
+    {
+      id: 'sales',
+      title: 'Sales Overview',
+      type: 'chart',
+      columnSpan: 2,
+      rowSpan: 2,
+      data: { revenue: '$45,230', growth: '+12%' }
+    },
+    {
+      id: 'users',
+      title: 'Active Users',
+      type: 'metric',
+      columnSpan: 1,
+      rowSpan: 1,
+      data: { count: '1,234', change: '+8%' }
+    },
+    {
+      id: 'orders',
+      title: 'Recent Orders',
+      type: 'metric',
+      columnSpan: 1,
+      rowSpan: 1,
+      data: { count: '89', change: '-3%' }
+    },
+    {
+      id: 'activity',
+      title: 'Activity Feed',
+      type: 'list',
+      columnSpan: 2,
+      rowSpan: 3,
+      data: [
+        'User John signed up',
+        'Order #1234 completed',
+        'Payment processed',
+        'New review posted'
+      ]
+    },
+    {
+      id: 'performance',
+      title: 'Performance Metrics',
+      type: 'chart',
+      columnSpan: 2,
+      rowSpan: 1,
+      data: { score: '94%', trend: 'up' }
+    }
+  ];
+
+  const renderWidget = (widget) => {
+    switch (widget.type) {
+      case 'chart':
+        return (
+          <Card className="dashboard-widget chart-widget">
+            <Text type="Heading5">{widget.title}</Text>
+            <div className="chart-content">
+              <Text type="Heading3">{widget.data.revenue || widget.data.score}</Text>
+              <Text type="BodySmall" className="metric-change">
+                {widget.data.growth || `Trending ${widget.data.trend}`}
+              </Text>
+            </div>
+          </Card>
+        );
+      
+      case 'metric':
+        return (
+          <Card className="dashboard-widget metric-widget">
+            <Text type="Heading6">{widget.title}</Text>
+            <Text type="Heading3">{widget.data.count}</Text>
+            <Text type="BodySmall" className="metric-change">
+              {widget.data.change}
+            </Text>
+          </Card>
+        );
+      
+      case 'list':
+        return (
+          <Card className="dashboard-widget list-widget">
+            <Text type="Heading5">{widget.title}</Text>
+            <List className="activity-list">
+              {widget.data.map((item, index) => (
+                <ListItem key={index}>{item}</ListItem>
+              ))}
+            </List>
+          </Card>
+        );
+      
+      default:
+        return null;
+    }
+  };
+
+  return (
+    <div className="dashboard-widgets">
+      <Text type="Heading3">Dashboard</Text>
+      
+      <Grid columns={4} className="widgets-grid">
+        {widgets.map(widget => (
+          <GridItem 
+            key={widget.id}
+            columnSpan={widget.columnSpan}
+            rowSpan={widget.rowSpan}
+          >
+            {renderWidget(widget)}
+          </GridItem>
+        ))}
+      </Grid>
+    </div>
+  );
+}
+```
+
+### Product Showcase
+```tsx
+function ProductShowcaseExample() {
+  const products = [
+    {
+      id: 1,
+      name: 'Premium Headphones',
+      price: '$299',
+      image: '/headphones.jpg',
+      featured: true,
+      badge: 'Best Seller'
+    },
+    {
+      id: 2,
+      name: 'Smart Watch',
+      price: '$199',
+      image: '/watch.jpg',
+      badge: 'New'
+    },
+    {
+      id: 3,
+      name: 'Wireless Earbuds',
+      price: '$129',
+      image: '/earbuds.jpg'
+    },
+    {
+      id: 4,
+      name: 'Laptop Stand',
+      price: '$79',
+      image: '/stand.jpg'
+    },
+    {
+      id: 5,
+      name: 'USB-C Hub',
+      price: '$49',
+      image: '/hub.jpg'
+    },
+    {
+      id: 6,
+      name: 'Wireless Mouse',
+      price: '$39',
+      image: '/mouse.jpg'
+    }
+  ];
+
+  return (
+    <div className="product-showcase">
+      <Text type="Heading3">Featured Products</Text>
+      
+      <Grid columns={4} className="showcase-grid">
+        {products.map((product, index) => (
+          <GridItem 
+            key={product.id}
+            columnSpan={product.featured ? 2 : 1}
+            rowSpan={product.featured ? 2 : 1}
+          >
+            <Card className={`product-card ${product.featured ? 'featured' : ''}`}>
+              {product.badge && (
+                <Chip className="product-badge" size="Small">
+                  {product.badge}
+                </Chip>
+              )}
+              
+              <Image 
+                src={product.image} 
+                alt={product.name}
+                className="product-image"
+                fit="Cover"
+              />
+              
+              <div className="product-info">
+                <Text 
+                  type={product.featured ? 'Heading4' : 'Heading6'}
+                  className="product-name"
+                >
+                  {product.name}
+                </Text>
+                
+                <Text 
+                  type={product.featured ? 'Heading5' : 'Heading6'}
+                  className="product-price"
+                >
+                  {product.price}
+                </Text>
+                
+                <Button 
+                  size={product.featured ? 'Medium' : 'Small'}
+                  className="add-to-cart"
+                >
+                  Add to Cart
+                </Button>
+              </div>
+            </Card>
+          </GridItem>
+        ))}
+      </Grid>
+    </div>
+  );
+}
+```
+
+### Social Media Feed
+```tsx
+function SocialMediaFeedExample() {
+  const posts = [
+    {
+      id: 1,
+      type: 'image',
+      user: 'john_doe',
+      content: 'Beautiful sunset at the beach! 🌅',
+      image: '/sunset.jpg',
+      likes: 245,
+      comments: 18,
+      size: 'large'
+    },
+    {
+      id: 2,
+      type: 'text',
+      user: 'jane_smith',
+      content: 'Just finished reading an amazing book. Highly recommend "The Art of Coding" to all developers out there!',
+      likes: 89,
+      comments: 12,
+      size: 'regular'
+    },
+    {
+      id: 3,
+      type: 'video',
+      user: 'tech_guru',
+      content: 'Quick tutorial on React hooks',
+      thumbnail: '/video-thumb.jpg',
+      likes: 156,
+      comments: 23,
+      size: 'regular'
+    },
+    {
+      id: 4,
+      type: 'image',
+      user: 'foodie_life',
+      content: 'Homemade pasta night! 🍝',
+      image: '/pasta.jpg',
+      likes: 92,
+      comments: 8,
+      size: 'regular'
+    }
+  ];
+
+  return (
+    <div className="social-feed">
+      <Text type="Heading3">Social Feed</Text>
+      
+      <Grid columns={3} className="feed-grid">
+        {posts.map(post => (
+          <GridItem 
+            key={post.id}
+            columnSpan={post.size === 'large' ? 2 : 1}
+            rowSpan={post.size === 'large' ? 2 : 1}
+          >
+            <Card className={`feed-post ${post.size === 'large' ? 'large-post' : ''}`}>
+              <div className="post-header">
+                <div className="user-info">
+                  <div className="user-avatar">
+                    <Image 
+                      src={`/avatars/${post.user}.jpg`} 
+                      alt={post.user}
+                      className="avatar"
+                    />
+                  </div>
+                  <Text type="Heading6">@{post.user}</Text>
+                </div>
+                
+                <IconButton size="Small">
+                  <Icon icon="More" />
+                </IconButton>
+              </div>
+              
+              <div className="post-content">
+                <Text type="Body">{post.content}</Text>
+                
+                {post.image && (
+                  <Image 
+                    src={post.image} 
+                    alt="Post image"
+                    className="post-image"
+                    fit="Cover"
+                  />
+                )}
+                
+                {post.thumbnail && (
+                  <div className="video-thumbnail">
+                    <Image 
+                      src={post.thumbnail} 
+                      alt="Video thumbnail"
+                      fit="Cover"
+                    />
+                    <Icon icon="PlayCircle" className="play-button" />
+                  </div>
+                )}
+              </div>
+              
+              <div className="post-actions">
+                <Button type="Text" size="Small">
+                  <Icon icon="Heart" /> {post.likes}
+                </Button>
+                <Button type="Text" size="Small">
+                  <Icon icon="Comment" /> {post.comments}
+                </Button>
+                <Button type="Text" size="Small">
+                  <Icon icon="Share" />
+                </Button>
+              </div>
+            </Card>
+          </GridItem>
+        ))}
+      </Grid>
+    </div>
+  );
+}
+```
+
+### Portfolio Gallery
+```tsx
+function PortfolioGalleryExample() {
+  const portfolioItems = [
+    {
+      id: 1,
+      title: 'E-commerce Website',
+      category: 'Web Design',
+      image: '/portfolio1.jpg',
+      size: 'large',
+      tech: ['React', 'Node.js', 'MongoDB']
+    },
+    {
+      id: 2,
+      title: 'Mobile Banking App',
+      category: 'UI/UX Design',
+      image: '/portfolio2.jpg',
+      size: 'regular',
+      tech: ['React Native', 'Firebase']
+    },
+    {
+      id: 3,
+      title: 'Brand Identity',
+      category: 'Branding',
+      image: '/portfolio3.jpg',
+      size: 'regular',
+      tech: ['Illustrator', 'Photoshop']
+    },
+    {
+      id: 4,
+      title: 'Dashboard Analytics',
+      category: 'Data Visualization',
+      image: '/portfolio4.jpg',
+      size: 'wide',
+      tech: ['D3.js', 'React', 'Python']
+    },
+    {
+      id: 5,
+      title: 'Landing Page',
+      category: 'Web Design',
+      image: '/portfolio5.jpg',
+      size: 'regular',
+      tech: ['HTML', 'CSS', 'JavaScript']
+    }
+  ];
+
+  const getGridSpan = (size) => {
+    switch (size) {
+      case 'large':
+        return { columnSpan: 2, rowSpan: 2 };
+      case 'wide':
+        return { columnSpan: 2, rowSpan: 1 };
+      case 'tall':
+        return { columnSpan: 1, rowSpan: 2 };
+      default:
+        return { columnSpan: 1, rowSpan: 1 };
+    }
+  };
+
+  return (
+    <div className="portfolio-gallery">
+      <div className="portfolio-header">
+        <Text type="Heading3">My Portfolio</Text>
+        <Text>A collection of my recent work and projects</Text>
+      </div>
+      
+      <Grid columns={3} className="portfolio-grid">
+        {portfolioItems.map(item => {
+          const { columnSpan, rowSpan } = getGridSpan(item.size);
+          
+          return (
+            <GridItem 
+              key={item.id}
+              columnSpan={columnSpan}
+              rowSpan={rowSpan}
+            >
+              <Card className={`portfolio-item ${item.size}`}>
+                <Image 
+                  src={item.image} 
+                  alt={item.title}
+                  className="portfolio-image"
+                  fit="Cover"
+                />
+                
+                <div className="portfolio-overlay">
+                  <div className="portfolio-info">
+                    <Text type="Heading6" className="portfolio-title">
+                      {item.title}
+                    </Text>
+                    
+                    <Text type="BodySmall" className="portfolio-category">
+                      {item.category}
+                    </Text>
+                    
+                    <div className="portfolio-tech">
+                      {item.tech.map(tech => (
+                        <Chip key={tech} size="Small" className="tech-chip">
+                          {tech}
+                        </Chip>
+                      ))}
+                    </div>
+                  </div>
+                  
+                  <div className="portfolio-actions">
+                    <IconButton size="Small" className="view-button">
+                      <Icon icon="Eye" />
+                    </IconButton>
+                    <IconButton size="Small" className="link-button">
+                      <Icon icon="ExternalLink" />
+                    </IconButton>
+                  </div>
+                </div>
+              </Card>
+            </GridItem>
+          );
+        })}
+      </Grid>
+    </div>
+  );
+}
+```
+
+### Event Calendar Grid
+```tsx
+function EventCalendarExample() {
+  const events = [
+    {
+      id: 1,
+      title: 'Team Meeting',
+      time: '9:00 AM',
+      duration: 1, // hours
+      color: 'blue'
+    },
+    {
+      id: 2,
+      title: 'Project Review',
+      time: '2:00 PM',
+      duration: 2,
+      color: 'green'
+    },
+    {
+      id: 3,
+      title: 'Client Call',
+      time: '4:00 PM',
+      duration: 1,
+      color: 'orange'
+    },
+    {
+      id: 4,
+      title: 'Workshop',
+      time: '10:00 AM',
+      duration: 3,
+      color: 'purple'
+    }
+  ];
+
+  const timeSlots = Array.from({ length: 9 }, (_, i) => `${i + 9}:00`);
+
+  return (
+    <div className="event-calendar">
+      <Text type="Heading3">Today's Schedule</Text>
+      
+      <Grid columns={4} className="calendar-grid">
+        {timeSlots.map((time, index) => (
+          <GridItem key={time} className="time-slot">
+            <Text type="BodySmall" className="time-label">
+              {time}
+            </Text>
+          </GridItem>
+        ))}
+        
+        {events.map(event => (
+          <GridItem 
+            key={event.id}
+            columnSpan={1}
+            rowSpan={event.duration}
+            className={`event-item ${event.color}`}
+          >
+            <Card className="event-card">
+              <Text type="Heading6" className="event-title">
+                {event.title}
+              </Text>
+              <Text type="BodySmall" className="event-time">
+                {event.time}
+              </Text>
+              <Text type="BodySmall" className="event-duration">
+                {event.duration}h
+              </Text>
+            </Card>
+          </GridItem>
+        ))}
+      </Grid>
+    </div>
+  );
+}
+```
+
+### Masonry-Style Layout
+```tsx
+function MasonryLayoutExample() {
+  const items = [
+    { id: 1, title: 'Short Content', content: 'Brief description here.', height: 1 },
+    { id: 2, title: 'Medium Content', content: 'This is a medium-length content item with more text to display.', height: 2 },
+    { id: 3, title: 'Long Content', content: 'This is a much longer content item that spans multiple lines and contains detailed information about the topic being discussed.', height: 3 },
+    { id: 4, title: 'Short Content', content: 'Another brief item.', height: 1 },
+    { id: 5, title: 'Medium Content', content: 'Another medium-length content item with descriptive text.', height: 2 },
+    { id: 6, title: 'Short Content', content: 'Brief content here.', height: 1 }
+  ];
+
+  return (
+    <div className="masonry-layout">
+      <Text type="Heading3">Masonry-Style Grid</Text>
+      
+      <Grid columns={3} className="masonry-grid">
+        {items.map(item => (
+          <GridItem 
+            key={item.id}
+            rowSpan={item.height}
+          >
+            <Card className={`masonry-item height-${item.height}`}>
+              <Text type="Heading6">{item.title}</Text>
+              <Text type="Body">{item.content}</Text>
+              
+              <div className="item-meta">
+                <Text type="BodySmall">
+                  Height: {item.height} unit{item.height > 1 ? 's' : ''}
+                </Text>
+              </div>
+            </Card>
+          </GridItem>
+        ))}
+      </Grid>
+    </div>
+  );
+}
+```
+
+### Responsive Grid Items
+```tsx
+function ResponsiveGridItemsExample() {
+  const [screenSize, setScreenSize] = useState('desktop');
+  
+  const items = [
+    { id: 1, title: 'Header', priority: 'high' },
+    { id: 2, title: 'Sidebar', priority: 'medium' },
+    { id: 3, title: 'Main Content', priority: 'high' },
+    { id: 4, title: 'Widget 1', priority: 'low' },
+    { id: 5, title: 'Widget 2', priority: 'low' },
+    { id: 6, title: 'Footer', priority: 'medium' }
+  ];
+
+  const getItemSpan = (item, screen) => {
+    if (screen === 'mobile') {
+      return { columnSpan: 4, rowSpan: 1 }; // Full width on mobile
+    }
+    
+    if (screen === 'tablet') {
+      switch (item.id) {
+        case 1: return { columnSpan: 4, rowSpan: 1 }; // Header full width
+        case 2: return { columnSpan: 1, rowSpan: 2 }; // Sidebar
+        case 3: return { columnSpan: 3, rowSpan: 2 }; // Main content
+        case 4:
+        case 5: return { columnSpan: 2, rowSpan: 1 }; // Widgets half width
+        case 6: return { columnSpan: 4, rowSpan: 1 }; // Footer full width
+        default: return { columnSpan: 1, rowSpan: 1 };
+      }
+    }
+    
+    // Desktop layout
+    switch (item.id) {
+      case 1: return { columnSpan: 4, rowSpan: 1 }; // Header
+      case 2: return { columnSpan: 1, rowSpan: 3 }; // Sidebar
+      case 3: return { columnSpan: 2, rowSpan: 2 }; // Main content
+      case 4:
+      case 5: return { columnSpan: 1, rowSpan: 1 }; // Widgets
+      case 6: return { columnSpan: 4, rowSpan: 1 }; // Footer
+      default: return { columnSpan: 1, rowSpan: 1 };
+    }
+  };
+
+  return (
+    <div className="responsive-grid-items">
+      <div className="layout-controls">
+        <Text type="Heading4">Responsive Layout Demo</Text>
+        
+        <ButtonGroup>
+          <Button 
+            type={screenSize === 'mobile' ? 'Primary' : 'Outlined'}
+            onClick={() => setScreenSize('mobile')}
+          >
+            Mobile
+          </Button>
+          <Button 
+            type={screenSize === 'tablet' ? 'Primary' : 'Outlined'}
+            onClick={() => setScreenSize('tablet')}
+          >
+            Tablet
+          </Button>
+          <Button 
+            type={screenSize === 'desktop' ? 'Primary' : 'Outlined'}
+            onClick={() => setScreenSize('desktop')}
+          >
+            Desktop
+          </Button>
+        </ButtonGroup>
+      </div>
+      
+      <Grid columns={4} className={`responsive-grid ${screenSize}`}>
+        {items.map(item => {
+          const { columnSpan, rowSpan } = getItemSpan(item, screenSize);
+          
+          return (
+            <GridItem 
+              key={item.id}
+              columnSpan={columnSpan}
+              rowSpan={rowSpan}
+            >
+              <Card className={`layout-item ${item.title.toLowerCase().replace(' ', '-')}`}>
+                <Text type="Heading6">{item.title}</Text>
+                <Text type="BodySmall">
+                  Span: {columnSpan}×{rowSpan}
+                </Text>
+                <Text type="BodySmall">
+                  Priority: {item.priority}
+                </Text>
+              </Card>
+            </GridItem>
+          );
+        })}
+      </Grid>
+    </div>
+  );
+}
+```