@delightui/components 0.1.105 → 0.1.107

package/docs/components/molecules/ActionCard.md

@@ -0,0 +1,546 @@
+# ActionCard
+
+## Description
+
+An interactive card component that serves as a clickable container for navigation and actions. Combines the visual structure of a card with the functionality of a link or button, supporting both internal routing and external navigation while maintaining accessibility and user experience standards.
+
+## Aliases
+
+- ActionCard
+- ClickableCard
+- NavigationCard
+- LinkCard
+- InteractiveCard
+
+## Props Breakdown
+
+**Extends:** `HTMLAttributes<HTMLDivElement>` & `Omit<LinkProps, 'to'>`
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `children` | `ReactNode` | - | Yes | The content to be displayed within the action card |
+| `disabled` | `boolean` | `false` | No | Specifies if the action card is disabled |
+| `className` | `string` | - | No | Additional CSS class names |
+| `to` | `string \| -1` | - | No | Destination URL or path for navigation. External URLs (starting with 'https') render as anchor tags, internal paths use router navigation |
+
+## Examples
+
+### Basic Usage
+```tsx
+import { ActionCard, Text, Icon } from '@delightui/components';
+
+function BasicExample() {
+  return (
+    <ActionCard to="/dashboard">
+      <div className="action-card-content">
+        <Icon icon="Dashboard" size="Large" />
+        <Text type="Heading6">Dashboard</Text>
+        <Text type="BodySmall">View your analytics and metrics</Text>
+      </div>
+    </ActionCard>
+  );
+}
+```
+
+### Feature Cards Grid
+```tsx
+function FeatureCardsExample() {
+  const features = [
+    {
+      icon: "Analytics",
+      title: "Analytics",
+      description: "Track your performance metrics",
+      path: "/analytics"
+    },
+    {
+      icon: "Settings",
+      title: "Settings",
+      description: "Manage your preferences",
+      path: "/settings"
+    },
+    {
+      icon: "Users",
+      title: "Team",
+      description: "Collaborate with your team",
+      path: "/team"
+    },
+    {
+      icon: "Help",
+      title: "Support",
+      description: "Get help when you need it",
+      path: "/support"
+    }
+  ];
+
+  return (
+    <div className="feature-grid">
+      {features.map((feature, index) => (
+        <ActionCard key={index} to={feature.path} className="feature-card">
+          <div className="card-icon">
+            <Icon icon={feature.icon} size="Large" />
+          </div>
+          <div className="card-content">
+            <Text type="Heading6">{feature.title}</Text>
+            <Text type="BodySmall">{feature.description}</Text>
+          </div>
+          <div className="card-arrow">
+            <Icon icon="ArrowForward" size="Small" />
+          </div>
+        </ActionCard>
+      ))}
+    </div>
+  );
+}
+```
+
+### Product Cards
+```tsx
+function ProductCardsExample() {
+  const products = [
+    {
+      id: 1,
+      name: "Premium Headphones",
+      price: "$299.99",
+      image: "/headphones.jpg",
+      rating: 4.8,
+      inStock: true
+    },
+    {
+      id: 2,
+      name: "Wireless Speaker",
+      price: "$159.99",
+      image: "/speaker.jpg",
+      rating: 4.6,
+      inStock: false
+    }
+  ];
+
+  return (
+    <div className="product-grid">
+      {products.map(product => (
+        <ActionCard 
+          key={product.id} 
+          to={`/products/${product.id}`}
+          disabled={!product.inStock}
+          className="product-card"
+        >
+          <div className="product-image">
+            <Image src={product.image} alt={product.name} />
+            {!product.inStock && (
+              <div className="out-of-stock-overlay">
+                <Chip size="Small" style="C">Out of Stock</Chip>
+              </div>
+            )}
+          </div>
+          
+          <div className="product-info">
+            <Text type="Heading6">{product.name}</Text>
+            <div className="product-rating">
+              <Icon icon="Star" size="Small" />
+              <Text type="BodySmall">{product.rating}</Text>
+            </div>
+            <Text type="Heading6" className="product-price">
+              {product.price}
+            </Text>
+          </div>
+        </ActionCard>
+      ))}
+    </div>
+  );
+}
+```
+
+### External Link Cards
+```tsx
+function ExternalLinksExample() {
+  const externalResources = [
+    {
+      title: "GitHub Repository",
+      description: "View our open source code",
+      url: "https://github.com/company/project",
+      icon: "GitHub"
+    },
+    {
+      title: "Documentation",
+      description: "Read the full documentation",
+      url: "https://docs.company.com",
+      icon: "Book"
+    },
+    {
+      title: "Community Forum",
+      description: "Join the discussion",
+      url: "https://community.company.com",
+      icon: "Forum"
+    }
+  ];
+
+  return (
+    <div className="external-links">
+      {externalResources.map((resource, index) => (
+        <ActionCard key={index} to={resource.url} className="external-link-card">
+          <div className="link-content">
+            <div className="link-header">
+              <Icon icon={resource.icon} />
+              <Text type="Heading6">{resource.title}</Text>
+              <Icon icon="ExternalLink" size="Small" />
+            </div>
+            <Text type="BodySmall">{resource.description}</Text>
+          </div>
+        </ActionCard>
+      ))}
+    </div>
+  );
+}
+```
+
+### Service Cards with Status
+```tsx
+function ServiceCardsExample() {
+  const services = [
+    {
+      name: "API Gateway",
+      status: "active",
+      uptime: "99.9%",
+      path: "/services/api-gateway"
+    },
+    {
+      name: "Database",
+      status: "warning",
+      uptime: "98.5%",
+      path: "/services/database"
+    },
+    {
+      name: "Message Queue",
+      status: "error",
+      uptime: "95.2%",
+      path: "/services/message-queue"
+    }
+  ];
+
+  const getStatusColor = (status) => {
+    switch (status) {
+      case 'active': return 'A';
+      case 'warning': return 'B';
+      case 'error': return 'C';
+      default: return 'B';
+    }
+  };
+
+  return (
+    <div className="service-cards">
+      {services.map((service, index) => (
+        <ActionCard key={index} to={service.path} className="service-card">
+          <div className="service-header">
+            <Text type="Heading6">{service.name}</Text>
+            <Chip size="Small" style={getStatusColor(service.status)}>
+              {service.status}
+            </Chip>
+          </div>
+          
+          <div className="service-metrics">
+            <div className="metric">
+              <Text type="BodySmall">Uptime</Text>
+              <Text type="Heading6">{service.uptime}</Text>
+            </div>
+          </div>
+          
+          <div className="service-actions">
+            <Text type="BodySmall">Click to view details</Text>
+            <Icon icon="ArrowForward" size="Small" />
+          </div>
+        </ActionCard>
+      ))}
+    </div>
+  );
+}
+```
+
+### User Profile Cards
+```tsx
+function UserProfileCardsExample() {
+  const users = [
+    {
+      id: 1,
+      name: "Sarah Johnson",
+      role: "Product Manager",
+      avatar: "/sarah.jpg",
+      online: true,
+      projects: 12
+    },
+    {
+      id: 2,
+      name: "Mike Chen",
+      role: "Developer",
+      avatar: "/mike.jpg",
+      online: false,
+      projects: 8
+    },
+    {
+      id: 3,
+      name: "Emily Davis",
+      role: "Designer",
+      avatar: "/emily.jpg",
+      online: true,
+      projects: 15
+    }
+  ];
+
+  return (
+    <div className="user-cards">
+      {users.map(user => (
+        <ActionCard key={user.id} to={`/users/${user.id}`} className="user-card">
+          <div className="user-avatar">
+            <Image src={user.avatar} alt={user.name} className="avatar-image" />
+            <div className={`status-indicator ${user.online ? 'online' : 'offline'}`} />
+          </div>
+          
+          <div className="user-info">
+            <Text type="Heading6">{user.name}</Text>
+            <Text type="BodySmall">{user.role}</Text>
+            
+            <div className="user-stats">
+              <Text type="BodySmall">{user.projects} projects</Text>
+              <Text type="BodySmall">{user.online ? 'Online' : 'Offline'}</Text>
+            </div>
+          </div>
+          
+          <div className="user-actions">
+            <IconButton icon="Message" size="Small" />
+            <IconButton icon="MoreVertical" size="Small" />
+          </div>
+        </ActionCard>
+      ))}
+    </div>
+  );
+}
+```
+
+### Quick Actions Dashboard
+```tsx
+function QuickActionsExample() {
+  const quickActions = [
+    {
+      title: "Create New Project",
+      description: "Start a new project from template",
+      path: "/projects/new",
+      icon: "Add",
+      color: "primary"
+    },
+    {
+      title: "Import Data",
+      description: "Import existing data files",
+      path: "/import",
+      icon: "Upload",
+      color: "secondary"
+    },
+    {
+      title: "Generate Report",
+      description: "Create a new analytics report",
+      path: "/reports/new",
+      icon: "BarChart",
+      color: "tertiary"
+    },
+    {
+      title: "Invite Team Member",
+      description: "Add someone to your team",
+      path: "/team/invite",
+      icon: "PersonAdd",
+      color: "success"
+    }
+  ];
+
+  return (
+    <div className="quick-actions-grid">
+      {quickActions.map((action, index) => (
+        <ActionCard 
+          key={index} 
+          to={action.path} 
+          className={`quick-action-card ${action.color}`}
+        >
+          <div className="action-icon">
+            <Icon icon={action.icon} size="Large" />
+          </div>
+          
+          <div className="action-content">
+            <Text type="Heading6">{action.title}</Text>
+            <Text type="BodySmall">{action.description}</Text>
+          </div>
+          
+          <div className="action-indicator">
+            <Icon icon="ArrowForward" size="Small" />
+          </div>
+        </ActionCard>
+      ))}
+    </div>
+  );
+}
+```
+
+### Interactive Dashboard Cards
+```tsx
+function InteractiveDashboardExample() {
+  const [cardData, setCardData] = useState({
+    revenue: { value: '$24,500', change: '+12%' },
+    users: { value: '1,234', change: '+5%' },
+    orders: { value: '89', change: '-2%' },
+    conversion: { value: '3.4%', change: '+0.8%' }
+  });
+
+  return (
+    <div className="dashboard-cards">
+      <ActionCard to="/analytics/revenue" className="metric-card revenue">
+        <div className="metric-header">
+          <Icon icon="TrendingUp" />
+          <Text type="BodySmall">Revenue</Text>
+        </div>
+        
+        <div className="metric-value">
+          <Text type="Heading4">{cardData.revenue.value}</Text>
+          <Chip size="Small" style="A">{cardData.revenue.change}</Chip>
+        </div>
+        
+        <div className="metric-footer">
+          <Text type="BodySmall">vs last month</Text>
+          <Icon icon="ArrowForward" size="Small" />
+        </div>
+      </ActionCard>
+      
+      <ActionCard to="/analytics/users" className="metric-card users">
+        <div className="metric-header">
+          <Icon icon="Users" />
+          <Text type="BodySmall">Active Users</Text>
+        </div>
+        
+        <div className="metric-value">
+          <Text type="Heading4">{cardData.users.value}</Text>
+          <Chip size="Small" style="A">{cardData.users.change}</Chip>
+        </div>
+        
+        <div className="metric-footer">
+          <Text type="BodySmall">this week</Text>
+          <Icon icon="ArrowForward" size="Small" />
+        </div>
+      </ActionCard>
+      
+      <ActionCard to="/analytics/orders" className="metric-card orders">
+        <div className="metric-header">
+          <Icon icon="Package" />
+          <Text type="BodySmall">Orders</Text>
+        </div>
+        
+        <div className="metric-value">
+          <Text type="Heading4">{cardData.orders.value}</Text>
+          <Chip size="Small" style="C">{cardData.orders.change}</Chip>
+        </div>
+        
+        <div className="metric-footer">
+          <Text type="BodySmall">today</Text>
+          <Icon icon="ArrowForward" size="Small" />
+        </div>
+      </ActionCard>
+    </div>
+  );
+}
+```
+
+### Disabled and Loading States
+```tsx
+function StateVariationsExample() {
+  const [loading, setLoading] = useState(false);
+
+  return (
+    <div className="state-cards">
+      <ActionCard to="/available" className="available-card">
+        <div className="card-content">
+          <Icon icon="Check" />
+          <Text type="Heading6">Available Action</Text>
+          <Text type="BodySmall">This card is interactive</Text>
+        </div>
+      </ActionCard>
+      
+      <ActionCard disabled className="disabled-card">
+        <div className="card-content">
+          <Icon icon="Lock" />
+          <Text type="Heading6">Disabled Action</Text>
+          <Text type="BodySmall">This card is disabled</Text>
+        </div>
+      </ActionCard>
+      
+      <ActionCard 
+        to={loading ? undefined : "/action"}
+        className="loading-card"
+        onClick={() => {
+          setLoading(true);
+          setTimeout(() => setLoading(false), 2000);
+        }}
+      >
+        <div className="card-content">
+          {loading ? (
+            <>
+              <Spinner size="Small" />
+              <Text type="Heading6">Loading...</Text>
+              <Text type="BodySmall">Please wait</Text>
+            </>
+          ) : (
+            <>
+              <Icon icon="Refresh" />
+              <Text type="Heading6">Refresh Data</Text>
+              <Text type="BodySmall">Click to reload</Text>
+            </>
+          )}
+        </div>
+      </ActionCard>
+    </div>
+  );
+}
+```
+
+### Complex Content Cards
+```tsx
+function ComplexContentExample() {
+  return (
+    <div className="complex-cards">
+      <ActionCard to="/projects/1" className="project-card">
+        <div className="project-header">
+          <div className="project-info">
+            <Text type="Heading5">Website Redesign</Text>
+            <Text type="BodySmall">Due: March 15, 2024</Text>
+          </div>
+          <Chip size="Small" style="B">In Progress</Chip>
+        </div>
+        
+        <div className="project-description">
+          <Text type="BodyMedium">
+            Complete redesign of the company website with modern UI/UX
+            and improved performance.
+          </Text>
+        </div>
+        
+        <div className="project-team">
+          <Text type="BodySmall">Team:</Text>
+          <div className="team-avatars">
+            <Image src="/team1.jpg" alt="Team member" className="team-avatar" />
+            <Image src="/team2.jpg" alt="Team member" className="team-avatar" />
+            <Image src="/team3.jpg" alt="Team member" className="team-avatar" />
+            <div className="team-count">+3</div>
+          </div>
+        </div>
+        
+        <div className="project-progress">
+          <div className="progress-header">
+            <Text type="BodySmall">Progress</Text>
+            <Text type="BodySmall">68%</Text>
+          </div>
+          <ProgressBar value={68} />
+        </div>
+        
+        <div className="project-tags">
+          <Chip size="Small" style="A">Design</Chip>
+          <Chip size="Small" style="A">Frontend</Chip>
+          <Chip size="Small" style="A">High Priority</Chip>
+        </div>
+      </ActionCard>
+    </div>
+  );
+}
+```