# Card Component

A flexible card container component that displays content in a structured format with optional header, action bar, and various styling options. Perfect for displaying structured information, user profiles, product details, and more.

## Features

- **Flexible Structure**: Header, content, and action bar sections
- **Multiple Header Options**: Simple title or custom header content via slots
- **Action Bar Support**: Built-in action buttons with icons/images and callbacks
- **Visual Variants**: Plain and 3D shadow variants
- **Custom Styling**: Flexible style customization
- **Slot-Based Content**: Rich content support through slots
- **Interactive Actions**: Click handling with debouncing and hover hints

## Basic Usage

```svelte
<script>
import Card from '@ticatec/uniface-element/Card';

const cardData = { id: 1, name: 'John Doe' };
</script>

<Card 
  title="User Profile"
  data={cardData}
>
  <p>This is the card content area.</p>
</Card>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `style` | `string` | `''` | Custom CSS styles |
| `title` | `string` | `null` | Simple header title text |
| `actions` | `CardAction[]` | `[]` | Array of action buttons |
| `variant` | `'plain' \| '3d'` | `'plain'` | Card visual variant |
| `iconColor` | `string \| null` | `null` | Custom color for action icons |
| `data` | `any` | `null` | Data object passed to action callbacks |

## CardAction Interface

```typescript
interface CardAction {
  icon?: string;          // Icon font class (e.g., FontAwesome)
  img?: string;           // Image URL for custom icons
  hint?: string;          // Tooltip text on hover
  disabled?: boolean;     // Whether the action is disabled
  callback: (data: any) => void;  // Action callback function
}
```

## Slots

| Slot | Description |
|------|-------------|
| `header-bar` | Custom header content (overrides title prop) |
| `default` | Main card content |
| `action-bar` | Custom action bar content (when no actions prop) |

## Card Variants

```svelte
<!-- Plain card (default) -->
<Card title="Plain Card" variant="plain">
  <p>Simple flat card design</p>
</Card>

<!-- 3D shadow card -->
<Card title="3D Card" variant="3d">
  <p>Card with shadow effect</p>
</Card>
```

## With Actions

```svelte
<script>
import Card, { type CardAction } from '@ticatec/uniface-element/Card';

const userData = { id: 1, name: 'John Doe', email: 'john@example.com' };

const actions: CardAction[] = [
  {
    icon: 'fas fa-edit',
    hint: 'Edit user',
    callback: (data) => editUser(data)
  },
  {
    icon: 'fas fa-trash',
    hint: 'Delete user',
    callback: (data) => deleteUser(data)
  },
  {
    icon: 'fas fa-share',
    hint: 'Share profile',
    callback: (data) => shareProfile(data)
  }
];

const editUser = (user) => {
  console.log('Editing user:', user);
};

const deleteUser = (user) => {
  console.log('Deleting user:', user);
};

const shareProfile = (user) => {
  console.log('Sharing profile:', user);
};
</script>

<Card 
  title="User Profile"
  {actions}
  data={userData}
  variant="3d"
>
  <div class="profile-content">
    <h3>{userData.name}</h3>
    <p>{userData.email}</p>
  </div>
</Card>
```

## Custom Header with Slot

```svelte
<Card variant="3d">
  <div slot="header-bar" class="custom-header">
    <div class="header-left">
      <img src="/avatar.jpg" alt="User" class="avatar" />
      <h3>John Doe</h3>
    </div>
    <div class="header-right">
      <span class="status online">Online</span>
    </div>
  </div>
  
  <div class="profile-details">
    <p>Software Developer</p>
    <p>San Francisco, CA</p>
  </div>
</Card>

<style>
  .custom-header {
    display: flex;
    justify-content: space-between;
    align-items: center;
    padding: 16px;
  }
  
  .header-left {
    display: flex;
    align-items: center;
    gap: 12px;
  }
  
  .avatar {
    width: 40px;
    height: 40px;
    border-radius: 50%;
  }
  
  .status.online {
    color: #22c55e;
    font-weight: 500;
  }
</style>
```

## Custom Action Bar

```svelte
<Card title="Project Card">
  <div class="project-info">
    <h4>Project Alpha</h4>
    <p>A revolutionary new application</p>
  </div>
  
  <div slot="action-bar" class="custom-actions">
    <button class="btn-primary">View Details</button>
    <button class="btn-secondary">Edit</button>
    <button class="btn-danger">Delete</button>
  </div>
</Card>
```

## Advanced Examples

### Product Card

```svelte
<script>
const product = {
  id: 101,
  name: 'Wireless Headphones',
  price: 199.99,
  image: '/headphones.jpg'
};

const productActions = [
  {
    icon: 'fas fa-heart',
    hint: 'Add to favorites',
    callback: (data) => addToFavorites(data)
  },
  {
    icon: 'fas fa-shopping-cart',
    hint: 'Add to cart',
    callback: (data) => addToCart(data)
  },
  {
    icon: 'fas fa-share',
    hint: 'Share product',
    callback: (data) => shareProduct(data)
  }
];
</script>

<Card 
  actions={productActions}
  data={product}
  variant="3d"
  style="max-width: 300px;"
>
  <div slot="header-bar" class="product-header">
    <img src={product.image} alt={product.name} class="product-image" />
  </div>
  
  <div class="product-details">
    <h3>{product.name}</h3>
    <div class="price">${product.price}</div>
    <div class="rating">
      ⭐⭐⭐⭐⭐ (128 reviews)
    </div>
  </div>
</Card>
```

### Dashboard Widget

```svelte
<script>
const widgetData = { 
  title: 'Sales Overview',
  value: 12345,
  change: '+15.3%'
};

const widgetActions = [
  {
    icon: 'fas fa-refresh',
    hint: 'Refresh data',
    callback: (data) => refreshWidget(data)
  },
  {
    icon: 'fas fa-cog',
    hint: 'Settings',
    callback: (data) => openSettings(data)
  }
];
</script>

<Card 
  title={widgetData.title}
  actions={widgetActions}
  data={widgetData}
  iconColor="#007acc"
>
  <div class="widget-content">
    <div class="metric-value">${widgetData.value.toLocaleString()}</div>
    <div class="metric-change positive">{widgetData.change}</div>
  </div>
</Card>

<style>
  .widget-content {
    text-align: center;
    padding: 20px;
  }
  
  .metric-value {
    font-size: 2rem;
    font-weight: bold;
    color: #333;
  }
  
  .metric-change {
    font-size: 1rem;
    margin-top: 8px;
  }
  
  .metric-change.positive {
    color: #22c55e;
  }
</style>
```

### Blog Post Card

```svelte
<script>
const post = {
  id: 1,
  title: 'Getting Started with Svelte',
  excerpt: 'Learn the basics of Svelte framework...',
  author: 'Jane Smith',
  date: '2024-03-15',
  tags: ['svelte', 'javascript', 'tutorial']
};

const postActions = [
  {
    icon: 'fas fa-bookmark',
    hint: 'Bookmark post',
    callback: (data) => bookmarkPost(data)
  },
  {
    icon: 'fas fa-share',
    hint: 'Share post',
    callback: (data) => sharePost(data)
  }
];
</script>

<Card 
  actions={postActions}
  data={post}
  variant="plain"
>
  <div slot="header-bar" class="post-header">
    <h2 class="post-title">{post.title}</h2>
    <div class="post-meta">
      <span>By {post.author}</span>
      <span>{post.date}</span>
    </div>
  </div>
  
  <div class="post-content">
    <p>{post.excerpt}</p>
    <div class="tags">
      {#each post.tags as tag}
        <span class="tag">#{tag}</span>
      {/each}
    </div>
  </div>
</Card>
```

### Contact Card

```svelte
<script>
const contact = {
  name: 'Sarah Johnson',
  role: 'Project Manager',
  email: 'sarah@company.com',
  phone: '+1 (555) 123-4567',
  avatar: '/sarah.jpg'
};

const contactActions = [
  {
    icon: 'fas fa-envelope',
    hint: 'Send email',
    callback: (data) => sendEmail(data.email)
  },
  {
    icon: 'fas fa-phone',
    hint: 'Call',
    callback: (data) => makeCall(data.phone)
  },
  {
    icon: 'fas fa-edit',
    hint: 'Edit contact',
    callback: (data) => editContact(data)
  }
];
</script>

<Card 
  actions={contactActions}
  data={contact}
  variant="3d"
>
  <div class="contact-card">
    <img src={contact.avatar} alt={contact.name} class="contact-avatar" />
    <h3>{contact.name}</h3>
    <p class="contact-role">{contact.role}</p>
    <div class="contact-info">
      <div class="contact-item">
        <i class="fas fa-envelope"></i>
        <span>{contact.email}</span>
      </div>
      <div class="contact-item">
        <i class="fas fa-phone"></i>
        <span>{contact.phone}</span>
      </div>
    </div>
  </div>
</Card>
```

### Settings Card

```svelte
<script>
let notifications = true;
let darkMode = false;

const settingsData = { notifications, darkMode };

const saveSettings = (data) => {
  console.log('Saving settings:', data);
  // Save settings logic
};

const resetSettings = (data) => {
  notifications = true;
  darkMode = false;
};

const settingsActions = [
  {
    icon: 'fas fa-save',
    hint: 'Save settings',
    callback: saveSettings
  },
  {
    icon: 'fas fa-undo',
    hint: 'Reset to defaults',
    callback: resetSettings
  }
];
</script>

<Card 
  title="Preferences"
  actions={settingsActions}
  data={settingsData}
>
  <div class="settings-form">
    <div class="setting-item">
      <label>
        <input type="checkbox" bind:checked={notifications} />
        Enable notifications
      </label>
    </div>
    <div class="setting-item">
      <label>
        <input type="checkbox" bind:checked={darkMode} />
        Dark mode
      </label>
    </div>
  </div>
</Card>
```

## Action Types

### Icon Actions

```svelte
<script>
const iconActions = [
  {
    icon: 'fas fa-star',
    hint: 'Mark as favorite',
    callback: (data) => toggleFavorite(data)
  },
  {
    icon: 'fas fa-download',
    hint: 'Download',
    callback: (data) => downloadFile(data)
  }
];
</script>
```

### Image Actions

```svelte
<script>
const imageActions = [
  {
    img: '/icons/custom-icon.svg',
    hint: 'Custom action',
    callback: (data) => customAction(data)
  }
];
</script>
```

### Disabled Actions

```svelte
<script>
const mixedActions = [
  {
    icon: 'fas fa-edit',
    hint: 'Edit (available)',
    callback: (data) => editItem(data)
  },
  {
    icon: 'fas fa-trash',
    hint: 'Delete (not available)',
    disabled: true,
    callback: (data) => deleteItem(data)
  }
];
</script>
```

## Styling

The component uses the following CSS classes:

- `.uniface-card` - Main card container
- `.shadowBox` - Applied when variant="3d"
- `.card-header` - Header section container
- `.card-header.simple` - Simple header with title only
- `.card-content` - Main content area
- `.card-action-bar` - Action bar container
- `.card-action-bar.simple` - Built-in action bar
- `.action-item` - Individual action button
- `.action-item.disabled` - Disabled action styling

### Example CSS

```css
.uniface-card {
  border: 1px solid #e5e7eb;
  border-radius: 8px;
  background: white;
  overflow: hidden;
}

.uniface-card.shadowBox {
  box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
}

.card-header {
  border-bottom: 1px solid #e5e7eb;
  padding: 16px;
  background: #f9fafb;
}

.card-content {
  padding: 16px;
}

.card-action-bar {
  border-top: 1px solid #e5e7eb;
  padding: 8px 16px;
  background: #f9fafb;
  display: flex;
  gap: 12px;
  justify-content: flex-end;
}

.action-item {
  cursor: pointer;
  padding: 8px;
  border-radius: 4px;
  transition: background-color 0.2s;
}

.action-item:hover:not(.disabled) {
  background: rgba(0, 0, 0, 0.05);
}

.action-item.disabled {
  opacity: 0.5;
  cursor: not-allowed;
}
```

## Best Practices

1. **Consistent Data Structure**: Use consistent data objects for similar card types
2. **Meaningful Actions**: Provide clear, actionable operations with descriptive hints
3. **Appropriate Variants**: Use 3D variant sparingly for emphasis
4. **Accessible Content**: Ensure content is readable and actions are clearly labeled
5. **Responsive Design**: Consider how cards stack and resize on different screen sizes
6. **Loading States**: Show loading indicators for dynamic content
7. **Error Handling**: Handle action callback errors gracefully

## Common Patterns

### Card Grid

```svelte
<div class="card-grid">
  {#each items as item}
    <Card title={item.title} actions={cardActions} data={item}>
      <p>{item.description}</p>
    </Card>
  {/each}
</div>

<style>
  .card-grid {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
    gap: 16px;
    padding: 16px;
  }
</style>
```

### Card List

```svelte
<div class="card-list">
  {#each items as item}
    <Card variant="plain" actions={listActions} data={item}>
      <div class="list-item">
        <h4>{item.title}</h4>
        <p>{item.description}</p>
      </div>
    </Card>
  {/each}
</div>
```

### Dashboard Layout

```svelte
<div class="dashboard">
  <div class="dashboard-row">
    <Card title="Revenue" variant="3d">
      <div class="metric">$45,230</div>
    </Card>
    <Card title="Users" variant="3d">
      <div class="metric">1,234</div>
    </Card>
  </div>
</div>
```

## Accessibility

- Use semantic HTML within card content
- Provide meaningful action hints for screen readers
- Ensure sufficient color contrast
- Support keyboard navigation for actions
- Use appropriate heading levels in card content

## Browser Support

The Card component works in all modern browsers that support:
- ES6+ JavaScript
- CSS Grid and Flexbox
- Modern DOM APIs

## Performance

- Efficient action handling with built-in debouncing
- Minimal re-renders with proper key usage
- Lightweight DOM structure
- Optional lazy loading for card content