# Shared Components Architecture - ECM Platform

## Status: ✅ COMPLETE

Reusable shared frontend component system for the ECM MT5 Investment Platform.

## Overview
Production-grade component library with finance-safe formatting, responsive design, and dark mode support.

## Component Categories

### 1. Card Components

#### BaseCard (`src/components/common/BaseCard.vue`)
**Purpose:** Generic card container with header/content/footer slots.

**Features:**
- Header, content, and footer slots
- Variant support (default, success, danger, warning)
- Optional padding
- Dark mode support
- Responsive

**Props:**
- `variant` - Card variant
- `noPadding` - Remove padding

**Usage:**
```vue
<BaseCard>
  <template #header>
    <h2>Card Title</h2>
  </template>
  <p>Card content</p>
  <template #footer>
    <button>Action</button>
  </template>
</BaseCard>
```

---

#### FinanceCard (`src/components/finance/FinanceCard.vue`)
**Purpose:** Finance-specific card for displaying metrics.

**Features:**
- Title and value display
- Icon with colored background
- Trend indicator
- Variant support (default, success, danger, warning)
- Automatic number formatting
- Dark mode support

**Props:**
- `title` - Card title
- `value` - Card value (number or string)
- `icon` - Emoji icon
- `variant` - Color variant
- `trend` - Trend text
- `trendPositive` - Trend direction

**Usage:**
```vue
<FinanceCard
  title="Total Balance"
  :value="balance"
  icon="💰"
  variant="success"
  trend="+5.2%"
  :trend-positive="true"
/>
```

---

### 2. Table Components

#### FinanceTable (`src/components/finance/FinanceTable.vue`)
**Purpose:** Finance table with formatting and pagination.

**Features:**
- Column configuration
- Format support (currency, number, percentage, date)
- Loading state
- Empty state
- Pagination integration
- Responsive overflow
- Dark mode support

**Props:**
- `columns` - Array of column definitions
- `data` - Array of data rows
- `loading` - Boolean loading state
- `currentPage` - Current page number
- `totalPages` - Total pages
- `totalItems` - Total items count
- `showPagination` - Boolean to show/hide pagination

**Column Definition:**
```javascript
{
  key: 'amount',
  label: 'Amount',
  format: 'currency'
}
```

**Usage:**
```vue
<FinanceTable
  :columns="columns"
  :data="data"
  :loading="loading"
  :current-page="currentPage"
  :total-pages="totalPages"
  @page-change="onPageChange"
/>
```

---

### 3. Chart Components

#### ChartPlaceholder (`src/components/finance/ChartPlaceholder.vue`)
**Purpose:** Placeholder for future chart implementation.

**Features:**
- Custom message
- Icon display
- Centered layout

**Props:**
- `message` - Placeholder message

**Usage:**
```vue
<ChartPlaceholder message="Chart coming soon" />
```

---

#### ChartWrapper (`src/components/shared/ChartWrapper.vue`)
**Purpose:** Wrapper for actual chart libraries.

**Features:**
- Loading state
- Error state
- Empty state
- Configurable height
- Optional border
- Legend slot
- Dark mode support

**Props:**
- `loading` - Boolean loading state
- `error` - Error message
- `hasData` - Boolean data availability
- `height` - Chart height
- `emptyIcon` - Empty state icon
- `emptyTitle` - Empty state title
- `emptyMessage` - Empty state message
- `bordered` - Show border

**Usage:**
```vue
<ChartWrapper
  :loading="loading"
  :error="error"
  :has-data="hasData"
  height="300px"
>
  <!-- Chart library content -->
</ChartWrapper>
```

---

### 4. Modal Components

#### BaseModal (`src/components/shared/BaseModal.vue`)
**Purpose:** Generic modal component.

**Features:**
- Teleport to body
- Backdrop with blur
- Animated transitions
- Multiple sizes (sm, md, lg, xl, full)
- Header, content, footer slots
- Close on backdrop click
- Close button
- Dark mode support

**Props:**
- `isOpen` - Boolean visibility
- `title` - Modal title
- `size` - Modal size
- `closeable` - Show close button
- `closeOnBackdrop` - Close on backdrop click

**Events:**
- `close` - Modal closed

**Usage:**
```vue
<BaseModal
  :is-open="isOpen"
  title="Modal Title"
  size="lg"
  @close="isOpen = false"
>
  <p>Modal content</p>
  <template #footer>
    <button @click="isOpen = false">Close</button>
  </template>
</BaseModal>
```

---

#### ConfirmationModal (`src/components/admin/ConfirmationModal.vue`)
**Purpose:** Confirmation modal for destructive actions.

**Features:**
- Teleport to body
- Backdrop blur
- Animated transitions
- Loading state support
- Multiple variants (danger, warning, primary)
- Custom icon, title, message
- Optional details section
- Close on backdrop click

**Props:**
- `isOpen` - Boolean visibility
- `title` - Modal title
- `message` - Modal message
- `details` - Optional details text
- `icon` - Modal icon
- `confirmText` - Confirm button text
- `variant` - Button variant
- `loading` - Loading state
- `closeOnBackdrop` - Close on backdrop click

**Events:**
- `close` - Modal closed
- `confirm` - Action confirmed

**Usage:**
```vue
<ConfirmationModal
  :is-open="showModal"
  title="Delete Record"
  message="Are you sure you want to delete this record?"
  details="This action cannot be undone."
  confirm-text="Delete"
  variant="danger"
  :loading="deleting"
  @close="showModal = false"
  @confirm="deleteRecord"
/>
```

---

### 5. Alert Components

#### Alert (`src/components/shared/Alert.vue`)
**Purpose:** Display alert messages.

**Features:**
- Multiple types (success, error, warning, info)
- Title support
- Dismissible
- Icons
- Dark mode support

**Props:**
- `type` - Alert type
- `title` - Alert title
- `message` - Alert message
- `dismissible` - Show close button

**Events:**
- `close` - Alert closed

**Usage:**
```vue
<Alert
  type="success"
  title="Success"
  message="Operation completed successfully."
  :dismissible="true"
  @close="alertVisible = false"
/>
```

---

### 6. Loading State Components

#### BaseLoading (`src/components/common/BaseLoading.vue`)
**Purpose:** Display loading spinner.

**Features:**
- Spinner animation
- Dark mode support
- Centered display

**Usage:**
```vue
<BaseLoading />
```

---

### 7. Empty State Components

#### EmptyState (`src/components/ui/EmptyState.vue`)
**Purpose:** Display empty state message.

**Features:**
- Icon display
- Title and message
- Dark mode support

**Props:**
- `icon` - Empty state icon
- `title` - Empty state title
- `message` - Empty state message

**Usage:**
```vue
<EmptyState
  icon="📭"
  title="No Data"
  message="There is no data to display."
/>
```

---

### 8. Pagination Components

#### Pagination (`src/components/ui/Pagination.vue`)
**Purpose:** Pagination controls.

**Features:**
- Page navigation
- Page info display
- Dark mode support

**Props:**
- `currentPage` - Current page number
- `totalPages` - Total pages
- `totalItems` - Total items

**Events:**
- `page-change` - Page changed

**Usage:**
```vue
<Pagination
  :current-page="currentPage"
  :total-pages="totalPages"
  :total-items="totalItems"
  @page-change="onPageChange"
/>
```

---

### 9. Notification Components

#### Notification (`src/components/shared/Notification.vue`)
**Purpose:** Toast notification display.

**Features:**
- Teleport to body
- Multiple types (success, error, warning, info)
- Animated transitions
- Auto-dismiss
- Stack display
- Dark mode support

**Props:**
- `notifications` - Array of notification objects

**Events:**
- `remove` - Notification removed

**Usage:**
```vue
<Notification
  :notifications="notifications"
  @remove="removeNotification"
/>
```

---

#### useNotification Composable (`src/composables/useNotification.js`)
**Purpose:** Notification management composable.

**Features:**
- Add notifications
- Remove notifications
- Type-specific methods (success, error, warning, info)
- Auto-dismiss
- Clear all

**Methods:**
- `add({ type, title, message, duration })` - Add notification
- `remove(id)` - Remove notification
- `success(message, title, duration)` - Add success notification
- `error(message, title, duration)` - Add error notification
- `warning(message, title, duration)` - Add warning notification
- `info(message, title, duration)` - Add info notification
- `clear()` - Clear all notifications

**Usage:**
```javascript
const { success, error, warning, info } = useNotification()

success('Operation completed')
error('Operation failed')
warning('Warning message')
info('Info message')
```

---

### 10. Badge Components

#### Badge (`src/components/shared/Badge.vue`)
**Purpose:** Display status badges.

**Features:**
- Multiple types (default, primary, success, danger, warning, info, gray)
- Multiple sizes (sm, md, lg)
- Rounded or square
- Dot style
- Dark mode support

**Props:**
- `type` - Badge type
- `size` - Badge size
- `text` - Badge text
- `rounded` - Rounded corners
- `dot` - Dot style

**Usage:**
```vue
<Badge type="success" text="Active" />
<Badge type="warning" text="Pending" :rounded="true" />
<Badge type="danger" text="Error" size="sm" />
```

---

### 11. Status Indicator Components

#### StatusIndicator (`src/components/admin/StatusIndicator.vue`)
**Purpose:** Display system status with color-coded indicator.

**Features:**
- Color-coded status
- Status label
- Compact display

**Status Values:**
- `operational` - Green
- `degraded` - Yellow
- `down` - Red
- `maintenance` - Blue

**Props:**
- `label` - Status label
- `status` - Status value

**Usage:**
```vue
<StatusIndicator
  label="Settlement Engine"
  :status="systemStatus.settlement"
/>
```

---

### 12. Formatting Utilities

#### useFormat Composable (`src/composables/useFormat.js`)
**Purpose:** Formatting utilities for display.

**Features:**
- Currency formatting
- Percentage formatting
- Date formatting
- Number formatting

**Methods:**
- `formatCurrency(value, currency)` - Format currency
- `formatPercentage(value, decimals)` - Format percentage
- `formatDate(date, format)` - Format date
- `formatNumber(value)` - Format number

**Usage:**
```javascript
const { formatCurrency, formatPercentage, formatDate, formatNumber } = useFormat()

formatCurrency(1234.56) // $1,234.56
formatPercentage(0.1234) // 12.34%
formatDate('2024-01-15', 'short') // Jan 15, 2024
formatNumber(1234567) // 1,234,567
```

---

#### Format Utils (`src/utils/format.js`)
**Purpose:** Low-level formatting functions.

**Functions:**
- `formatCurrency(value, currency)` - Format currency
- `formatPercentage(value, decimals)` - Format percentage
- `formatDate(date, format)` - Format date
- `formatNumber(value)` - Format number
- `truncateText(text, maxLength)` - Truncate text
- `formatFileSize(bytes)` - Format file size

**Date Formats:**
- `short` - Jan 15, 2024
- `long` - Monday, January 15, 2024
- `time` - 10:30 AM
- `datetime` - Jan 15, 2024, 10:30 AM

**IMPORTANT:**
All formatting functions are for display only. No calculations performed.

---

## Component Hierarchy

```
Shared Components
├── Cards
│   ├── BaseCard
│   └── FinanceCard
├── Tables
│   └── FinanceTable
├── Charts
│   ├── ChartPlaceholder
│   └── ChartWrapper
├── Modals
│   ├── BaseModal
│   └── ConfirmationModal
├── Alerts
│   └── Alert
├── Loading States
│   └── BaseLoading
├── Empty States
│   └── EmptyState
├── Pagination
│   └── Pagination
├── Notifications
│   ├── Notification
│   └── useNotification
├── Badges
│   └── Badge
├── Status Indicators
│   └── StatusIndicator
└── Formatting
    ├── useFormat
    └── format.js
```

---

## Design Principles

### 1. Reusability
- Components are generic and flexible
- Slot-based customization
- Variant support
- Configurable props

### 2. API-Safe
- No finance calculations in frontend
- Formatting only
- Display backend values
- No business logic

### 3. Responsive
- Mobile-first approach
- Breakpoint-aware
- Touch-friendly
- Adaptive layouts

### 4. Dark Mode Ready
- All components support dark mode
- Consistent color schemes
- Automatic theme detection
- Manual toggle support

### 5. Finance-Dashboard Ready
- Currency formatting
- Percentage formatting
- Date formatting
- Number formatting
- Status indicators
- Trend indicators

---

## File Structure

```
src/
├── components/
│   ├── common/
│   │   ├── BaseCard.vue
│   │   ├── BaseLoading.vue
│   │   ├── BaseButton.vue
│   │   └── BaseInput.vue
│   ├── finance/
│   │   ├── FinanceCard.vue
│   │   ├── FinanceTable.vue
│   │   └── ChartPlaceholder.vue
│   ├── shared/
│   │   ├── Alert.vue
│   │   ├── Badge.vue
│   │   ├── Notification.vue
│   │   ├── BaseModal.vue
│   │   └── ChartWrapper.vue
│   ├── admin/
│   │   ├── ConfirmationModal.vue
│   │   └── StatusIndicator.vue
│   ├── ui/
│   │   ├── EmptyState.vue
│   │   └── Pagination.vue
│   └── public/
│       ├── PublicNavbar.vue
│       ├── PublicFooter.vue
│       ├── PublicSection.vue
│       ├── PublicCTA.vue
│       ├── PublicFeatureCard.vue
│       ├── PublicStat.vue
│       └── PublicStep.vue
├── composables/
│   ├── useFormat.js
│   ├── useNotification.js
│   ├── useAuth.js
│   ├── useApi.js
│   └── useDebounce.js
└── utils/
    └── format.js
```

---

## Usage Patterns

### Pattern 1: Card with Table
```vue
<BaseCard>
  <template #header>
    <h2>Transactions</h2>
  </template>
  <FinanceTable
    :columns="columns"
    :data="data"
    :loading="loading"
  />
</BaseCard>
```

### Pattern 2: Alert with Dismiss
```vue
<Alert
  v-if="error"
  type="error"
  :message="error"
  :dismissible="true"
  @close="error = null"
/>
```

### Pattern 3: Modal with Confirmation
```vue
<BaseModal
  :is-open="isOpen"
  title="Confirm Action"
  @close="isOpen = false"
>
  <p>Are you sure?</p>
  <template #footer>
    <button @click="isOpen = false">Cancel</button>
    <button @click="confirm">Confirm</button>
  </template>
</BaseModal>
```

### Pattern 4: Notification System
```vue
<template>
  <div>
    <Notification
      :notifications="notifications"
      @remove="removeNotification"
    />
    <button @click="showSuccess">Show Success</button>
  </div>
</template>

<script setup>
import { useNotification } from '@/composables/useNotification'

const { success, notifications } = useNotification()

function showSuccess() {
  success('Operation completed successfully')
}

function removeNotification(id) {
  const index = notifications.value.findIndex(n => n.id === id)
  if (index > -1) {
    notifications.value.splice(index, 1)
  }
}
</script>
```

---

## Testing Checklist

- [ ] All components render correctly
- [ ] Dark mode works for all components
- [ ] Responsive design tested
- [ ] Slots work correctly
- [ ] Props validation works
- [ ] Events emit correctly
- [ ] Formatting functions work
- [ ] Loading states display
- [ ] Error states display
- [ ] Empty states display
- [ ] Transitions animate correctly
- [ ] Accessibility attributes present
- [ ] Cross-browser testing

---

## Next Steps

Shared component architecture is complete and ready for:
1. Chart library integration (Chart.js, ECharts, etc.)
2. Form component enhancements
3. Advanced table features (sorting, filtering)
4. More modal variants
5. Additional badge styles
6. More notification types
7. Accessibility enhancements
8. Performance optimizations