@ticatec/uniface-element 0.2.3 → 0.3.0

package/dist/card/README.md

@@ -0,0 +1,666 @@
+# 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