@delightui/components 0.1.104 → 0.1.106

package/docs/components/molecules/Grid.md

@@ -0,0 +1,577 @@
+# Grid
+
+## Description
+
+A flexible CSS Grid layout component that provides a structured way to arrange child elements in rows and columns. Offers responsive grid layouts with configurable column and row counts, supporting modern CSS Grid features for complex layouts and spacing control.
+
+## Aliases
+
+- Grid
+- GridLayout
+- CSSGrid
+- GridContainer
+- LayoutGrid
+
+## Props Breakdown
+
+**Extends:** HTMLAttributes<HTMLDivElement> (inherits all div element properties)
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `columns` | `number` | - | No | Number of columns in the grid |
+| `rows` | `number` | - | No | Number of rows in the grid |
+| `children` | `ReactNode` | - | Yes | Grid items to be arranged |
+| `className` | `string` | - | No | Additional CSS class names |
+| `style` | `CSSProperties` | - | No | Inline styles for the grid container |
+
+## Examples
+
+### Basic Grid Layout
+```tsx
+import { Grid, GridItem, Card, Text } from '@delightui/components';
+
+function BasicGridExample() {
+  return (
+    <Grid columns={3} className="basic-grid">
+      <GridItem>
+        <Card>
+          <Text type="Heading6">Item 1</Text>
+          <Text>First grid item</Text>
+        </Card>
+      </GridItem>
+      
+      <GridItem>
+        <Card>
+          <Text type="Heading6">Item 2</Text>
+          <Text>Second grid item</Text>
+        </Card>
+      </GridItem>
+      
+      <GridItem>
+        <Card>
+          <Text type="Heading6">Item 3</Text>
+          <Text>Third grid item</Text>
+        </Card>
+      </GridItem>
+      
+      <GridItem>
+        <Card>
+          <Text type="Heading6">Item 4</Text>
+          <Text>Fourth grid item</Text>
+        </Card>
+      </GridItem>
+    </Grid>
+  );
+}
+```
+
+### Photo Gallery Grid
+```tsx
+function PhotoGalleryExample() {
+  const photos = [
+    { id: 1, src: '/photo1.jpg', title: 'Sunset Beach' },
+    { id: 2, src: '/photo2.jpg', title: 'Mountain View' },
+    { id: 3, src: '/photo3.jpg', title: 'City Lights' },
+    { id: 4, src: '/photo4.jpg', title: 'Forest Path' },
+    { id: 5, src: '/photo5.jpg', title: 'Ocean Waves' },
+    { id: 6, src: '/photo6.jpg', title: 'Desert Dunes' }
+  ];
+
+  return (
+    <div className="photo-gallery">
+      <Text type="Heading4">Photo Gallery</Text>
+      
+      <Grid columns={3} className="gallery-grid">
+        {photos.map(photo => (
+          <GridItem key={photo.id}>
+            <Card className="photo-card">
+              <Image 
+                src={photo.src} 
+                alt={photo.title}
+                fit="Cover"
+                className="gallery-image"
+              />
+              <div className="photo-info">
+                <Text type="BodySmall">{photo.title}</Text>
+              </div>
+            </Card>
+          </GridItem>
+        ))}
+      </Grid>
+    </div>
+  );
+}
+```
+
+### Dashboard Layout
+```tsx
+function DashboardExample() {
+  return (
+    <div className="dashboard">
+      <Text type="Heading3">Analytics Dashboard</Text>
+      
+      <Grid columns={4} rows={3} className="dashboard-grid">
+        <GridItem columnSpan={2}>
+          <Card className="chart-card">
+            <Text type="Heading5">Revenue Chart</Text>
+            <div className="chart-placeholder">
+              <Text type="BodyLarge">📊 Chart goes here</Text>
+            </div>
+          </Card>
+        </GridItem>
+        
+        <GridItem>
+          <Card className="metric-card">
+            <Text type="Heading6">Total Users</Text>
+            <Text type="Heading3">1,234</Text>
+            <Text type="BodySmall" className="metric-change positive">
+              +12% from last month
+            </Text>
+          </Card>
+        </GridItem>
+        
+        <GridItem>
+          <Card className="metric-card">
+            <Text type="Heading6">Revenue</Text>
+            <Text type="Heading3">$45,678</Text>
+            <Text type="BodySmall" className="metric-change positive">
+              +8% from last month
+            </Text>
+          </Card>
+        </GridItem>
+        
+        <GridItem columnSpan={2} rowSpan={2}>
+          <Card className="activity-card">
+            <Text type="Heading5">Recent Activity</Text>
+            <List>
+              <ListItem>User John Doe logged in</ListItem>
+              <ListItem>New order #1234 received</ListItem>
+              <ListItem>Payment processed successfully</ListItem>
+              <ListItem>User Jane Smith updated profile</ListItem>
+            </List>
+          </Card>
+        </GridItem>
+        
+        <GridItem>
+          <Card className="metric-card">
+            <Text type="Heading6">Orders</Text>
+            <Text type="Heading3">89</Text>
+            <Text type="BodySmall" className="metric-change negative">
+              -3% from last month
+            </Text>
+          </Card>
+        </GridItem>
+        
+        <GridItem>
+          <Card className="metric-card">
+            <Text type="Heading6">Conversion</Text>
+            <Text type="Heading3">3.4%</Text>
+            <Text type="BodySmall" className="metric-change positive">
+              +0.8% from last month
+            </Text>
+          </Card>
+        </GridItem>
+      </Grid>
+    </div>
+  );
+}
+```
+
+### Product Catalog Grid
+```tsx
+function ProductCatalogExample() {
+  const products = [
+    { id: 1, name: 'Wireless Headphones', price: '$99.99', image: '/headphones.jpg', rating: 4.5 },
+    { id: 2, name: 'Smart Watch', price: '$299.99', image: '/watch.jpg', rating: 4.8 },
+    { id: 3, name: 'Laptop Stand', price: '$49.99', image: '/stand.jpg', rating: 4.2 },
+    { id: 4, name: 'USB-C Hub', price: '$79.99', image: '/hub.jpg', rating: 4.6 },
+    { id: 5, name: 'Wireless Mouse', price: '$39.99', image: '/mouse.jpg', rating: 4.3 },
+    { id: 6, name: 'Keyboard', price: '$129.99', image: '/keyboard.jpg', rating: 4.7 }
+  ];
+
+  return (
+    <div className="product-catalog">
+      <div className="catalog-header">
+        <Text type="Heading3">Featured Products</Text>
+        <Button type="Outlined">View All</Button>
+      </div>
+      
+      <Grid columns={3} className="products-grid">
+        {products.map(product => (
+          <GridItem key={product.id}>
+            <Card className="product-card">
+              <Image 
+                src={product.image} 
+                alt={product.name}
+                className="product-image"
+                fit="Cover"
+              />
+              
+              <div className="product-info">
+                <Text type="Heading6">{product.name}</Text>
+                
+                <div className="product-rating">
+                  {[...Array(5)].map((_, i) => (
+                    <Icon 
+                      key={i}
+                      icon={i < Math.floor(product.rating) ? 'StarFilled' : 'Star'}
+                      className="star-icon"
+                    />
+                  ))}
+                  <Text type="BodySmall">({product.rating})</Text>
+                </div>
+                
+                <div className="product-footer">
+                  <Text type="Heading5" className="product-price">
+                    {product.price}
+                  </Text>
+                  <Button size="Small">Add to Cart</Button>
+                </div>
+              </div>
+            </Card>
+          </GridItem>
+        ))}
+      </Grid>
+    </div>
+  );
+}
+```
+
+### Team Members Grid
+```tsx
+function TeamMembersExample() {
+  const teamMembers = [
+    { id: 1, name: 'Sarah Johnson', role: 'Product Manager', avatar: '/sarah.jpg', email: 'sarah@company.com' },
+    { id: 2, name: 'Mike Chen', role: 'Lead Developer', avatar: '/mike.jpg', email: 'mike@company.com' },
+    { id: 3, name: 'Emily Davis', role: 'UX Designer', avatar: '/emily.jpg', email: 'emily@company.com' },
+    { id: 4, name: 'Alex Rodriguez', role: 'Backend Engineer', avatar: '/alex.jpg', email: 'alex@company.com' },
+    { id: 5, name: 'Jessica Wong', role: 'Frontend Engineer', avatar: '/jessica.jpg', email: 'jessica@company.com' },
+    { id: 6, name: 'David Kim', role: 'DevOps Engineer', avatar: '/david.jpg', email: 'david@company.com' }
+  ];
+
+  return (
+    <div className="team-section">
+      <Text type="Heading3">Meet Our Team</Text>
+      <Text>Get to know the talented individuals behind our success</Text>
+      
+      <Grid columns={3} className="team-grid">
+        {teamMembers.map(member => (
+          <GridItem key={member.id}>
+            <Card className="team-member-card">
+              <div className="member-avatar">
+                <Image 
+                  src={member.avatar} 
+                  alt={member.name}
+                  className="avatar-image"
+                  fit="Cover"
+                />
+              </div>
+              
+              <div className="member-info">
+                <Text type="Heading6">{member.name}</Text>
+                <Text type="BodySmall" className="member-role">
+                  {member.role}
+                </Text>
+                <Text type="BodySmall" className="member-email">
+                  {member.email}
+                </Text>
+              </div>
+              
+              <div className="member-actions">
+                <IconButton size="Small" aria-label="Send email">
+                  <Icon icon="Email" />
+                </IconButton>
+                <IconButton size="Small" aria-label="View profile">
+                  <Icon icon="Person" />
+                </IconButton>
+              </div>
+            </Card>
+          </GridItem>
+        ))}
+      </Grid>
+    </div>
+  );
+}
+```
+
+### Blog Posts Grid
+```tsx
+function BlogPostsExample() {
+  const blogPosts = [
+    {
+      id: 1,
+      title: 'Getting Started with React Hooks',
+      excerpt: 'Learn the fundamentals of React Hooks and how they can simplify your components.',
+      author: 'John Doe',
+      date: '2024-02-10',
+      image: '/blog1.jpg',
+      category: 'React'
+    },
+    {
+      id: 2,
+      title: 'CSS Grid vs Flexbox: When to Use Which',
+      excerpt: 'A comprehensive guide to choosing between CSS Grid and Flexbox for your layouts.',
+      author: 'Jane Smith',
+      date: '2024-02-08',
+      image: '/blog2.jpg',
+      category: 'CSS'
+    },
+    {
+      id: 3,
+      title: 'Building Accessible Web Applications',
+      excerpt: 'Best practices for creating web applications that work for everyone.',
+      author: 'Mike Johnson',
+      date: '2024-02-05',
+      image: '/blog3.jpg',
+      category: 'Accessibility'
+    }
+  ];
+
+  return (
+    <div className="blog-section">
+      <div className="blog-header">
+        <Text type="Heading3">Latest Blog Posts</Text>
+        <Button type="Outlined">View All Posts</Button>
+      </div>
+      
+      <Grid columns={2} className="blog-grid">
+        {blogPosts.map((post, index) => (
+          <GridItem key={post.id} columnSpan={index === 0 ? 2 : 1}>
+            <Card className={`blog-post-card ${index === 0 ? 'featured' : ''}`}>
+              <Image 
+                src={post.image} 
+                alt={post.title}
+                className="post-image"
+                fit="Cover"
+              />
+              
+              <div className="post-content">
+                <Chip size="Small" className="category-chip">
+                  {post.category}
+                </Chip>
+                
+                <Text type={index === 0 ? 'Heading4' : 'Heading6'}>
+                  {post.title}
+                </Text>
+                
+                <Text type="Body" className="post-excerpt">
+                  {post.excerpt}
+                </Text>
+                
+                <div className="post-meta">
+                  <Text type="BodySmall">By {post.author}</Text>
+                  <Text type="BodySmall">{post.date}</Text>
+                </div>
+                
+                <Button type="Text" className="read-more">
+                  Read More →
+                </Button>
+              </div>
+            </Card>
+          </GridItem>
+        ))}
+      </Grid>
+    </div>
+  );
+}
+```
+
+### Settings Panel Grid
+```tsx
+function SettingsPanelExample() {
+  const settingsSections = [
+    {
+      id: 'profile',
+      title: 'Profile Settings',
+      icon: 'Person',
+      description: 'Update your personal information and preferences'
+    },
+    {
+      id: 'security',
+      title: 'Security & Privacy',
+      icon: 'Security',
+      description: 'Manage your password and privacy settings'
+    },
+    {
+      id: 'notifications',
+      title: 'Notifications',
+      icon: 'Notifications',
+      description: 'Control how and when you receive notifications'
+    },
+    {
+      id: 'billing',
+      title: 'Billing & Plans',
+      icon: 'CreditCard',
+      description: 'View your subscription and billing information'
+    },
+    {
+      id: 'integrations',
+      title: 'Integrations',
+      icon: 'Apps',
+      description: 'Connect with third-party services and applications'
+    },
+    {
+      id: 'support',
+      title: 'Help & Support',
+      icon: 'Help',
+      description: 'Get help and contact our support team'
+    }
+  ];
+
+  return (
+    <div className="settings-panel">
+      <Text type="Heading3">Settings</Text>
+      <Text>Manage your account settings and preferences</Text>
+      
+      <Grid columns={2} className="settings-grid">
+        {settingsSections.map(section => (
+          <GridItem key={section.id}>
+            <Card className="settings-card" clickable>
+              <div className="settings-icon">
+                <Icon icon={section.icon} size="Large" />
+              </div>
+              
+              <div className="settings-content">
+                <Text type="Heading6">{section.title}</Text>
+                <Text type="BodySmall" className="settings-description">
+                  {section.description}
+                </Text>
+              </div>
+              
+              <div className="settings-arrow">
+                <Icon icon="ChevronRight" />
+              </div>
+            </Card>
+          </GridItem>
+        ))}
+      </Grid>
+    </div>
+  );
+}
+```
+
+### Responsive Grid Layout
+```tsx
+function ResponsiveGridExample() {
+  const [viewMode, setViewMode] = useState('grid');
+  
+  const items = Array.from({ length: 12 }, (_, i) => ({
+    id: i + 1,
+    title: `Item ${i + 1}`,
+    description: `Description for item ${i + 1}`
+  }));
+
+  const getGridColumns = () => {
+    switch (viewMode) {
+      case 'single':
+        return 1;
+      case 'double':
+        return 2;
+      case 'triple':
+        return 3;
+      case 'quad':
+        return 4;
+      default:
+        return 3;
+    }
+  };
+
+  return (
+    <div className="responsive-grid-demo">
+      <div className="grid-controls">
+        <Text type="Heading4">Responsive Grid Demo</Text>
+        
+        <ButtonGroup>
+          <Button 
+            type={viewMode === 'single' ? 'Primary' : 'Outlined'}
+            onClick={() => setViewMode('single')}
+          >
+            1 Column
+          </Button>
+          <Button 
+            type={viewMode === 'double' ? 'Primary' : 'Outlined'}
+            onClick={() => setViewMode('double')}
+          >
+            2 Columns
+          </Button>
+          <Button 
+            type={viewMode === 'triple' ? 'Primary' : 'Outlined'}
+            onClick={() => setViewMode('triple')}
+          >
+            3 Columns
+          </Button>
+          <Button 
+            type={viewMode === 'quad' ? 'Primary' : 'Outlined'}
+            onClick={() => setViewMode('quad')}
+          >
+            4 Columns
+          </Button>
+        </ButtonGroup>
+      </div>
+      
+      <Grid columns={getGridColumns()} className="responsive-grid">
+        {items.map(item => (
+          <GridItem key={item.id}>
+            <Card className="responsive-item">
+              <Text type="Heading6">{item.title}</Text>
+              <Text type="Body">{item.description}</Text>
+              <Button size="Small" type="Outlined">
+                View Details
+              </Button>
+            </Card>
+          </GridItem>
+        ))}
+      </Grid>
+    </div>
+  );
+}
+```
+
+### Statistics Grid
+```tsx
+function StatisticsGridExample() {
+  const stats = [
+    { label: 'Total Users', value: '10,234', change: '+12%', trend: 'up' },
+    { label: 'Revenue', value: '$45,678', change: '+8%', trend: 'up' },
+    { label: 'Orders', value: '1,456', change: '-3%', trend: 'down' },
+    { label: 'Conversion Rate', value: '3.2%', change: '+0.5%', trend: 'up' },
+    { label: 'Avg. Order Value', value: '$31.40', change: '+15%', trend: 'up' },
+    { label: 'Customer Retention', value: '87%', change: '+2%', trend: 'up' }
+  ];
+
+  return (
+    <div className="statistics-dashboard">
+      <Text type="Heading3">Performance Statistics</Text>
+      
+      <Grid columns={3} className="stats-grid">
+        {stats.map((stat, index) => (
+          <GridItem key={index}>
+            <Card className="stat-card">
+              <div className="stat-header">
+                <Text type="BodySmall" className="stat-label">
+                  {stat.label}
+                </Text>
+                <Icon 
+                  icon={stat.trend === 'up' ? 'TrendingUp' : 'TrendingDown'}
+                  className={`trend-icon ${stat.trend}`}
+                />
+              </div>
+              
+              <Text type="Heading3" className="stat-value">
+                {stat.value}
+              </Text>
+              
+              <Text 
+                type="BodySmall" 
+                className={`stat-change ${stat.trend === 'up' ? 'positive' : 'negative'}`}
+              >
+                {stat.change} from last month
+              </Text>
+            </Card>
+          </GridItem>
+        ))}
+      </Grid>
+    </div>
+  );
+}
+```