eamco_office_frontend/COMPONENTS.md

# Component Library Documentation

## Overview
This document provides usage examples for all the enhanced UI components created for the EAMCO frontend.

---

## Components

### 1. StatCard
Animated statistics card with trend indicators.

**Props:**
- `label` (string, required) - Card label
- `value` (number | string, required) - Value to display
- `color` (string) - Color variant (primary, secondary, accent, info, success, warning, error)
- `trend` (string) - Trend text
- `trendDirection` (string) - up, down, or neutral
- `animate` (boolean) - Enable number counting animation
- `wrapperClass` (string) - Additional CSS classes

**Usage:**
```vue
<StatCard
  label="Total Deliveries"
  :value="deliveryCount"
  color="primary"
  trend="+12% from yesterday"
  trendDirection="up"
  :animate="true"
>
  <template #icon>
    <TruckIcon />
  </template>
</StatCard>
```

---

### 2. FloatingInput
Modern input with floating label animation.

**Props:**
- `id` (string, required) - Input ID
- `label` (string, required) - Label text
- `modelValue` (string | number, required) - v-model value
- `type` (string) - Input type (default: 'text')
- `error` (string) - Error message
- `hint` (string) - Hint text
- `disabled` (boolean) - Disabled state
- `required` (boolean) - Required field

**Usage:**
```vue
<FloatingInput
  id="customer-name"
  label="Customer Name"
  v-model="customerName"
  :error="errors.name"
  hint="Enter full legal name"
  required
/>
```

---

### 3. EnhancedTable
Feature-rich table with sticky headers and zebra striping.

**Props:**
- `columns` (Column[], required) - Column definitions
- `data` (any[], required) - Table data
- `title` (string) - Table title
- `description` (string) - Table description
- `stickyHeader` (boolean) - Enable sticky header
- `zebra` (boolean) - Enable zebra striping
- `rowKey` (string) - Unique row key (default: 'id')

**Usage:**
```vue
<EnhancedTable
  :columns="columns"
  :data="customers"
  title="Customer List"
  description="All active customers"
  sticky-header
  zebra
  @row-click="handleRowClick"
>
  <template #cell-status="{ value }">
    <EnhancedBadge :variant="getStatusColor(value)">
      {{ value }}
    </EnhancedBadge>
  </template>
</EnhancedTable>
```

---

### 4. EnhancedButton
Button with loading states, success animations, and ripple effects.

**Props:**
- `variant` (string) - primary, secondary, accent, success, warning, error, ghost, outline
- `size` (string) - xs, sm, md, lg
- `type` (string) - button, submit, reset
- `disabled` (boolean) - Disabled state
- `loading` (boolean) - Loading state
- `success` (boolean) - Success state
- `icon` (Component) - Icon component
- `fullWidth` (boolean) - Full width button

**Usage:**
```vue
<EnhancedButton
  variant="primary"
  size="md"
  :loading="isSubmitting"
  :success="submitSuccess"
  @click="handleSubmit"
>
  Save Changes
</EnhancedButton>
```

---

### 5. EnhancedBadge
Badge component with variants, pulse animations, and icons.

**Props:**
- `variant` (string) - primary, secondary, accent, info, success, warning, error, ghost
- `size` (string) - xs, sm, md, lg
- `outline` (boolean) - Outline style
- `dot` (boolean) - Show status dot
- `pulse` (boolean) - Pulse animation
- `icon` (Component) - Icon component

**Usage:**
```vue
<EnhancedBadge variant="success" dot pulse>
  Active
</EnhancedBadge>

<EnhancedBadge variant="warning" outline>
  Pending
</EnhancedBadge>
```

---

### 6. EnhancedModal
Modal dialog with backdrop blur and smooth animations.

**Props:**
- `modelValue` (boolean, required) - v-model for open/close state
- `title` (string) - Modal title
- `description` (string) - Modal description
- `size` (string) - sm, md, lg, xl, full
- `hideHeader` (boolean) - Hide header
- `hideClose` (boolean) - Hide close button
- `closeOnOverlay` (boolean) - Close on overlay click
- `noPadding` (boolean) - Remove body padding

**Usage:**
```vue
<EnhancedModal
  v-model="showModal"
  title="Edit Customer"
  description="Update customer information"
  size="lg"
>
  <CustomerForm :customer="selectedCustomer" />
  
  <template #footer>
    <EnhancedButton variant="ghost" @click="showModal = false">
      Cancel
    </EnhancedButton>
    <EnhancedButton variant="primary" @click="saveCustomer">
      Save
    </EnhancedButton>
  </template>
</EnhancedModal>
```

---

### 7. PageTransition
Wrapper component for page transitions.

**Props:**
- `name` (string) - fade, slide-left, slide-right, slide-up, slide-down, scale, rotate

**Usage:**
```vue
<PageTransition name="fade">
  <router-view />
</PageTransition>
```

---

### 8. LoadingCard
Skeleton loader for cards.

**Usage:**
```vue
<LoadingCard v-if="loading" />
<StatCard v-else :value="data" />
```

---

### 9. EmptyState
Empty state component with icon and action button.

**Props:**
- `title` (string, required) - Title text
- `description` (string, required) - Description text
- `actionLabel` (string) - Action button label

**Usage:**
```vue
<EmptyState
  title="No deliveries found"
  description="There are no deliveries scheduled for today."
  actionLabel="Create Delivery"
  @action="createDelivery"
>
  <template #icon>
    <TruckIcon />
  </template>
</EmptyState>
```

---

## Design Tokens

### Shadow Utilities
- `.shadow-soft` - Subtle elevation
- `.shadow-medium` - Standard elevation
- `.shadow-strong` - Strong elevation

### Hover Effects
- `.hover-lift` - Lift on hover with shadow

### Animations
- `animate-fade-in` - Fade in animation
- `animate-slide-up` - Slide up animation
- `animate-slide-down` - Slide down animation
- `animate-scale-in` - Scale in animation

---

## Best Practices

1. **Consistency**: Use the same component variants throughout the app
2. **Accessibility**: Always provide labels and ARIA attributes
3. **Performance**: Use loading states to indicate async operations
4. **Feedback**: Show success/error states after user actions
5. **Responsiveness**: Test components on all screen sizes