@delightui/components 0.1.104 → 0.1.106

package/docs/components/molecules/GridList.md

@@ -0,0 +1,244 @@
+# GridList
+
+## Description
+
+A grid-based list component that extends the standard List component with CSS Grid layout functionality. It automatically arranges list items in a responsive grid format with customizable columns and spacing, providing an organized way to display collections of data in a grid pattern.
+
+## Aliases
+
+- GridList
+- GridCollection
+- DataGrid
+- GridContainer
+
+## Props Breakdown
+
+**Extends:** All `List` component props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `columns` | `number` | `1` | No | Number of columns in the grid layout |
+| `gap` | `string \| number` | - | No | Gap spacing between grid items (CSS gap property) |
+| `className` | `string` | - | No | Additional CSS class names |
+| `component` | `React.ComponentType<T>` | - | Yes | Component to render for each list item |
+| `data` | `T[]` | - | Yes | Array of data items to render |
+
+Plus all standard List component properties (sorting, callbacks, etc.).
+
+## Examples
+
+### Basic Grid Layout
+```tsx
+import { GridList } from '@delightui/components';
+
+const ProductCard = ({ name, price, image }) => (
+  <div className="product-card">
+    <img src={image} alt={name} />
+    <h3>{name}</h3>
+    <p>${price}</p>
+  </div>
+);
+
+function BasicGridExample() {
+  const products = [
+    { id: 1, name: 'Product 1', price: 29.99, image: '/product1.jpg' },
+    { id: 2, name: 'Product 2', price: 39.99, image: '/product2.jpg' },
+    { id: 3, name: 'Product 3', price: 19.99, image: '/product3.jpg' },
+  ];
+
+  return (
+    <GridList
+      data={products}
+      component={ProductCard}
+      columns={3}
+      gap="16px"
+    />
+  );
+}
+```
+
+### Responsive Grid
+```tsx
+function ResponsiveGridExample() {
+  const images = [
+    { id: 1, src: '/image1.jpg', alt: 'Image 1' },
+    { id: 2, src: '/image2.jpg', alt: 'Image 2' },
+    { id: 3, src: '/image3.jpg', alt: 'Image 3' },
+    { id: 4, src: '/image4.jpg', alt: 'Image 4' },
+  ];
+
+  const ImageCard = ({ src, alt }) => (
+    <div className="image-card">
+      <img src={src} alt={alt} />
+    </div>
+  );
+
+  return (
+    <div className="responsive-grids">
+      {/* Mobile: 1 column */}
+      <div className="mobile-grid">
+        <GridList
+          data={images}
+          component={ImageCard}
+          columns={1}
+          gap="12px"
+        />
+      </div>
+      
+      {/* Tablet: 2 columns */}
+      <div className="tablet-grid">
+        <GridList
+          data={images}
+          component={ImageCard}
+          columns={2}
+          gap="16px"
+        />
+      </div>
+      
+      {/* Desktop: 4 columns */}
+      <div className="desktop-grid">
+        <GridList
+          data={images}
+          component={ImageCard}
+          columns={4}
+          gap="20px"
+        />
+      </div>
+    </div>
+  );
+}
+```
+
+### Card Grid with Actions
+```tsx
+import { Button, Text } from '@delightui/components';
+
+function CardGridExample() {
+  const users = [
+    { id: 1, name: 'John Doe', email: 'john@example.com', avatar: '/avatar1.jpg' },
+    { id: 2, name: 'Jane Smith', email: 'jane@example.com', avatar: '/avatar2.jpg' },
+    { id: 3, name: 'Bob Johnson', email: 'bob@example.com', avatar: '/avatar3.jpg' },
+  ];
+
+  const UserCard = ({ name, email, avatar, onEdit, onDelete }) => (
+    <div className="user-card">
+      <img src={avatar} alt={name} className="user-avatar" />
+      <Text type="Heading" size="Small">{name}</Text>
+      <Text type="Body" size="Small" color="Secondary">{email}</Text>
+      <div className="card-actions">
+        <Button size="Small" onClick={() => onEdit(id)}>Edit</Button>
+        <Button size="Small" style="Destructive" onClick={() => onDelete(id)}>Delete</Button>
+      </div>
+    </div>
+  );
+
+  const handleEdit = (userId) => {
+    console.log('Edit user:', userId);
+  };
+
+  const handleDelete = (userId) => {
+    console.log('Delete user:', userId);
+  };
+
+  return (
+    <GridList
+      data={users.map(user => ({ ...user, onEdit: handleEdit, onDelete: handleDelete }))}
+      component={UserCard}
+      columns={3}
+      gap="24px"
+      className="user-grid"
+    />
+  );
+}
+```
+
+### Variable Gap Spacing
+```tsx
+function GapSpacingExample() {
+  const items = Array.from({ length: 9 }, (_, i) => ({
+    id: i + 1,
+    content: `Item ${i + 1}`
+  }));
+
+  const SimpleCard = ({ content }) => (
+    <div className="simple-card">{content}</div>
+  );
+
+  return (
+    <div className="gap-examples">
+      {/* Tight spacing */}
+      <GridList
+        data={items}
+        component={SimpleCard}
+        columns={3}
+        gap="8px"
+      />
+      
+      {/* Medium spacing */}
+      <GridList
+        data={items}
+        component={SimpleCard}
+        columns={3}
+        gap="16px"
+      />
+      
+      {/* Large spacing */}
+      <GridList
+        data={items}
+        component={SimpleCard}
+        columns={3}
+        gap="32px"
+      />
+    </div>
+  );
+}
+```
+
+### Mixed Content Grid
+```tsx
+function MixedContentExample() {
+  const content = [
+    { id: 1, type: 'text', title: 'Article 1', summary: 'Lorem ipsum...' },
+    { id: 2, type: 'image', src: '/image.jpg', alt: 'Featured image' },
+    { id: 3, type: 'video', thumbnail: '/video-thumb.jpg', duration: '5:30' },
+    { id: 4, type: 'text', title: 'Article 2', summary: 'Dolor sit amet...' },
+  ];
+
+  const ContentCard = ({ type, title, summary, src, alt, thumbnail, duration }) => {
+    switch (type) {
+      case 'text':
+        return (
+          <div className="text-card">
+            <h3>{title}</h3>
+            <p>{summary}</p>
+          </div>
+        );
+      case 'image':
+        return (
+          <div className="image-card">
+            <img src={src} alt={alt} />
+          </div>
+        );
+      case 'video':
+        return (
+          <div className="video-card">
+            <img src={thumbnail} alt="Video thumbnail" />
+            <div className="video-duration">{duration}</div>
+          </div>
+        );
+      default:
+        return null;
+    }
+  };
+
+  return (
+    <GridList
+      data={content}
+      component={ContentCard}
+      columns={2}
+      gap="20px"
+      className="mixed-content-grid"
+    />
+  );
+}
+```