# Widget Quick Reference Guide

Quick lookup for all BuyerKiosk Live widgets.

## Import Statement

```dart
import 'package:buyerkiosk_live/presentation/widgets/widgets.dart';
```

---

## Common Widgets (8)

| Widget | Purpose | Key Props |
|--------|---------|-----------|
| `LoadingIndicator` | Show loading state | `message`, `size`, `color` |
| `ErrorDisplay` | Show errors | `message`, `onRetry`, `icon` |
| `EmptyState` | Empty list state | `icon`, `title`, `subtitle`, `action` |
| `RefreshList` | Pull-to-refresh wrapper | `controller`, `onRefresh`, `child` |
| `StoreLogo` | Store type logo | `typeNum`, `size`, `showBorder` |
| `PriorityIndicator` | Priority flag | `priority` (0-3), `showLabel` |
| `MetricCard` | Metric display | `label`, `value`, `icon` |
| `SectionHeader` | Section title | `title`, `trailing` |

---

## Charts (2)

| Widget | Purpose | Key Props |
|--------|---------|-----------|
| `GoalProgressChart` | Circular progress | `actual`, `goal`, `label`, `size` |
| `BuyerPerformanceChart` | Bar chart | `data`, `height`, `title` |

### Chart Data Classes

```dart
// For BuyerPerformanceChart
BuyerPerformanceData(
  buyerName: 'John',
  buyCount: 25,
  color: Colors.blue, // optional
)
```

---

## Dialogs (2)

| Widget | Purpose | Key Props |
|--------|---------|-----------|
| `ConfirmationDialog` | Confirm actions | `title`, `message`, `isDestructive` |
| `ShiftNotePopup` | Note details modal | `title`, `comment`, `priority`, `isTask` |

### Dialog Usage

```dart
// Confirmation
final result = await ConfirmationDialog.show(
  context: context,
  title: 'Delete?',
  message: 'Cannot be undone',
  isDestructive: true,
);

// Shift note
await ShiftNotePopup.show(
  context: context,
  title: 'Task',
  comment: 'Fix printer',
  priority: 3,
  submitter: 'John',
  createdDate: DateTime.now(),
  onDelete: () {},
);
```

---

## Cards (5)

| Widget | Purpose | Key Props |
|--------|---------|-----------|
| `StoreCard` | Store dashboard item | `storeName`, `storeType`, sales/buys goals, queue metrics |
| `QueueItemCard` | Queue item | `customerName`, `buyerName`, containers, `waitTimeMinutes` |
| `CompletedBuyCard` | Completed transaction | `customerName`, `buyerName`, `containerCount`, times |
| `BuyerStatsCard` | Buyer performance | `buyerName`, `numberOfBuys`, `numberOfBins`, avg times |
| `ShiftNoteCard` | Note list item | `title`, `priority`, `submitter`, `createdDate` |

---

## Color Coding Reference

### Store Types (StoreLogo)
- **PC**: Blue (#2196F3)
- **OU**: Red (#F44336)
- **CM**: Green (#4CAF50)
- **SE**: Orange (#FF9800)
- **PA**: Purple (#9C27B0)
- **BK**: Blue Grey (#607D8B) - Default

### Priority Levels (PriorityIndicator)
- **0**: Grey - None
- **1**: Green - Low
- **2**: Orange - Medium
- **3**: Red - High

### Wait Time Colors (QueueItemCard)
- **< 30min**: Green
- **< 60min**: Orange
- **≥ 60min**: Red

### Progress Colors (GoalProgressChart)
- **< 50%**: Red
- **< 75%**: Orange
- **< 100%**: Blue
- **≥ 100%**: Green

---

## Common Patterns

### Loading State
```dart
if (isLoading) {
  return const LoadingIndicator(message: 'Loading...');
}
```

### Error State
```dart
if (error != null) {
  return ErrorDisplay(
    message: error,
    onRetry: _reload,
  );
}
```

### Empty State
```dart
if (items.isEmpty) {
  return EmptyState(
    icon: Icons.inbox,
    title: 'No items',
    subtitle: 'Items will appear here',
  );
}
```

### Pull-to-Refresh List
```dart
RefreshList(
  controller: _controller,
  onRefresh: _reload,
  child: ListView(...),
)
```

### Confirmation Before Delete
```dart
final confirmed = await ConfirmationDialog.show(
  context: context,
  title: 'Delete?',
  message: 'Cannot be undone',
  isDestructive: true,
);

if (confirmed == true) {
  _delete();
}
```

---

## Time Formatting Helpers

All time formatting is handled internally by the widgets:

- **Wait time**: Automatically converts minutes to "Xh Ym" or "Xm"
- **Dates**: Relative format ("2h ago", "Yesterday", "Jan 15")
- **Process time**: Same as wait time format

---

## Required Dependencies

```yaml
dependencies:
  fl_chart: ^0.66.0
  pull_to_refresh: ^2.0.0
  intl: ^0.18.0
```

---

## File Organization

```
lib/presentation/widgets/
├── common/              # 8 common widgets + barrel
├── charts/              # 2 chart widgets + barrel
├── dialogs/             # 2 dialog widgets + barrel
├── cards/               # 5 card widgets + barrel
├── widgets.dart         # Main barrel file
├── README.md            # Full documentation
├── EXAMPLES.md          # Usage examples
└── QUICK_REFERENCE.md   # This file
```

---

## Widget Sizing Guidelines

| Widget | Default Size | Customizable |
|--------|-------------|--------------|
| `LoadingIndicator` | 40px | ✓ via `size` |
| `StoreLogo` | 48px | ✓ via `size` |
| `PriorityIndicator` | 24px | ✓ via `size` |
| `GoalProgressChart` | 120px | ✓ via `size` |
| `BuyerPerformanceChart` | 300px height | ✓ via `height` |

---

## Theming

All widgets use Material 3 theme colors:

- `colorScheme.primary` - Primary brand color
- `colorScheme.surface` - Card backgrounds
- `colorScheme.error` - Error states
- `colorScheme.onSurface` - Text colors

Widgets automatically adapt to light/dark mode.

---

## Performance Tips

1. **Use const constructors** where possible
2. **Provide keys** for list items that can be reordered
3. **Limit chart data points** to reasonable amounts (< 20 buyers)
4. **Use RefreshController** properly - always dispose!
5. **Avoid rebuilding entire lists** - use itemBuilder

---

## Common Issues

### Pull-to-refresh not working
```dart
// ✗ Wrong - not disposing controller
final _controller = RefreshController();

// ✓ Correct - dispose in StatefulWidget
@override
void dispose() {
  _refreshController.dispose();
  super.dispose();
}
```

### Charts not showing
```dart
// ✗ Wrong - no data
BuyerPerformanceChart(data: [])

// ✓ Correct - check for empty data
if (data.isEmpty) {
  return EmptyState(...);
}
return BuyerPerformanceChart(data: data);
```

### Dialog not dismissing
```dart
// ✗ Wrong - not closing
onConfirm: () => _doSomething(),

// ✓ Correct - close first
onConfirm: () {
  Navigator.pop(context);
  _doSomething();
}
```

---

## Quick Checklist for New Screens

- [ ] Import widgets barrel file
- [ ] Add loading state with `LoadingIndicator`
- [ ] Add error state with `ErrorDisplay`
- [ ] Add empty state with `EmptyState`
- [ ] Wrap lists with `RefreshList`
- [ ] Use section headers with `SectionHeader`
- [ ] Add confirmation dialogs for destructive actions
- [ ] Test with different data states (empty, loading, error, success)
- [ ] Dispose controllers in `dispose()`

---

## Need More Help?

- Full documentation: `README.md`
- Usage examples: `EXAMPLES.md`
- Widget source: Individual `.dart` files