# BuyerKiosk Live Flutter - Reusable Widgets

This directory contains all reusable UI components for the BuyerKiosk Live Flutter application.

## Directory Structure

```
lib/presentation/widgets/
├── common/              # Common reusable widgets
├── charts/              # Chart components
├── dialogs/             # Dialog and modal components
├── cards/               # Card components for lists
└── widgets.dart         # Main barrel file
```

## Usage

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

Or import specific categories:
```dart
import 'package:buyerkiosk_live/presentation/widgets/common/common_widgets.dart';
import 'package:buyerkiosk_live/presentation/widgets/charts/charts.dart';
import 'package:buyerkiosk_live/presentation/widgets/dialogs/dialogs.dart';
import 'package:buyerkiosk_live/presentation/widgets/cards/cards.dart';
```

## Common Widgets

### LoadingIndicator
Centered circular progress indicator with optional message.

```dart
LoadingIndicator(
  message: 'Loading data...',
  size: 40.0,
  color: Colors.blue,
)
```

### ErrorDisplay
Error display with icon, message, and optional retry button.

```dart
ErrorDisplay(
  message: 'Failed to load data',
  onRetry: () => _loadData(),
  icon: Icons.error_outline,
  retryButtonText: 'Try Again',
)
```

### EmptyState
Empty state display with icon, title, subtitle, and optional action.

```dart
EmptyState(
  icon: Icons.inbox,
  title: 'No items found',
  subtitle: 'Try adjusting your filters',
  action: FilledButton(
    onPressed: () => _reset(),
    child: Text('Reset'),
  ),
)
```

### RefreshList
Pull-to-refresh wrapper using the pull_to_refresh package.

```dart
RefreshList(
  controller: _refreshController,
  onRefresh: _onRefresh,
  onLoading: _onLoading,
  enablePullUp: true,
  child: ListView(...),
)
```

### StoreLogo
Displays store logo based on typeNum (PC, OU, CM, SE, PA, BK).
Uses colored containers with store abbreviations until actual images are available.

```dart
StoreLogo(
  typeNum: 'PC',
  size: 48.0,
  showBorder: true,
)
```

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

### PriorityIndicator
Priority flag icon with optional label (0-3: None, Low, Medium, High).

```dart
PriorityIndicator(
  priority: 2, // 0-3
  showLabel: true,
  size: 24.0,
)
```

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

### MetricCard
Card displaying a metric with label, value, and optional icon.

```dart
MetricCard(
  label: 'Total Sales',
  value: '\$12,345',
  icon: Icons.trending_up,
  iconColor: Colors.green,
  onTap: () => _viewDetails(),
)
```

### SectionHeader
Section header with title and optional trailing widget.

```dart
SectionHeader(
  title: 'Recent Activity',
  trailing: TextButton(
    onPressed: () => _viewAll(),
    child: Text('View All'),
  ),
)
```

## Charts

### GoalProgressChart
Circular progress chart showing actual vs goal percentage.
Uses fl_chart package for rendering.

```dart
GoalProgressChart(
  actual: 75,
  goal: 100,
  label: 'Sales',
  color: Colors.blue,
  size: 120.0,
  showPercentage: true,
)
```

**Features:**
- Dynamic color based on percentage (red < 50%, orange < 75%, blue < 100%, green >= 100%)
- Shows percentage, label, and actual/goal values
- Customizable size and color

### BuyerPerformanceChart
Bar chart comparing buyer performance metrics.

```dart
BuyerPerformanceChart(
  data: [
    BuyerPerformanceData(
      buyerName: 'John',
      buyCount: 25,
      color: Colors.blue,
    ),
    BuyerPerformanceData(
      buyerName: 'Jane',
      buyCount: 32,
      color: Colors.green,
    ),
  ],
  height: 300.0,
  title: 'Buyer Performance',
)
```

**Features:**
- Interactive tooltips on hover/tap
- Automatic color assignment
- Dynamic scaling based on data
- Responsive axis labels

## Dialogs

### ConfirmationDialog
Reusable confirmation dialog with customizable buttons.

```dart
// Static method for easy usage
final result = await ConfirmationDialog.show(
  context: context,
  title: 'Delete Item',
  message: 'Are you sure you want to delete this item?',
  confirmText: 'Delete',
  cancelText: 'Cancel',
  isDestructive: true,
  icon: Icons.delete,
);

// Or use as a widget
ConfirmationDialog(
  title: 'Confirm Action',
  message: 'Do you want to proceed?',
  onConfirm: () => _handleConfirm(),
  onCancel: () => Navigator.pop(context),
)
```

### ShiftNotePopup
Modal bottom sheet for displaying shift note/task details.

```dart
// Static method for easy usage
await ShiftNotePopup.show(
  context: context,
  title: 'Urgent Task',
  comment: 'Fix the printer in the buying area',
  priority: 3,
  submitter: 'John Doe',
  createdDate: DateTime.now(),
  modifiedDate: DateTime.now(),
  status: 'In Progress',
  isTask: true,
  onDelete: () => _deleteNote(),
  onChangeStatus: () => _changeStatus(),
);
```

**Features:**
- Draggable scrollable sheet
- Priority indicator
- Status badge for tasks
- Metadata display (submitter, dates)
- Action buttons (change status, delete)

## Cards

### StoreCard
Dashboard card displaying store overview with metrics.

```dart
StoreCard(
  storeName: 'Store 123',
  storeType: 'PC',
  salesActual: 15000,
  salesGoal: 20000,
  buysActual: 45,
  buysGoal: 60,
  queueCount: 8,
  waitTime: 45, // minutes
  buyerCount: 3,
  sorterCount: 2,
  onTap: () => _navigateToStore(),
)
```

**Features:**
- Store logo with color coding
- Dual progress charts (sales and buys)
- Queue and staff metrics
- Formatted wait time display
- Tap navigation support

### QueueItemCard
Card for queue items showing customer and progress.

```dart
QueueItemCard(
  customerName: 'John Customer',
  buyerName: 'Jane Buyer',
  currentContainer: 2,
  totalContainers: 5,
  waitTimeMinutes: 35,
  isInStore: true,
  onTap: () => _viewDetails(),
)
```

**Features:**
- Customer and buyer info
- Container progress indicator
- Color-coded wait time (green < 30m, orange < 60m, red >= 60m)
- In-store badge

### CompletedBuyCard
Card for completed transactions.

```dart
CompletedBuyCard(
  customerName: 'John Customer',
  buyerName: 'Jane Buyer',
  containerCount: 5,
  completedTime: DateTime.now(),
  processTimeMinutes: 25,
  onTap: () => _viewDetails(),
)
```

**Features:**
- Completion checkmark
- Customer and buyer names
- Container count
- Completion time
- Process duration

### BuyerStatsCard
Card displaying individual buyer performance statistics.

```dart
BuyerStatsCard(
  buyerName: 'Jane Buyer',
  numberOfBuys: 25,
  numberOfBins: 120,
  avgProcessTimeMinutes: 28,
  avgTimePerBin: 5.6,
  onTap: () => _viewDetails(),
)
```

**Features:**
- Avatar with initial
- Four key metrics grid
- Color-coded icons
- Formatted time displays
- Tap for details

### ShiftNoteCard
List card for shift notes and tasks.

```dart
ShiftNoteCard(
  title: 'Check inventory levels',
  priority: 2,
  submitter: 'John Manager',
  createdDate: DateTime.now(),
  preview: 'Need to verify stock counts...',
  onTap: () => _viewNote(),
)
```

**Features:**
- Priority flag indicator
- Title and preview text
- Submitter and timestamp
- Relative time formatting (e.g., "2h ago", "Yesterday")

## Dependencies

The following packages are used by these widgets:

```yaml
dependencies:
  flutter:
    sdk: flutter
  fl_chart: ^0.66.0           # For charts
  pull_to_refresh: ^2.0.0     # For pull-to-refresh
  intl: ^0.18.0               # For date formatting
```

Make sure these are added to your `pubspec.yaml`.

## Theming

All widgets use Material 3 theming and adapt to the app's theme automatically. They access colors and text styles from `Theme.of(context)` for consistency.

## Best Practices

1. **Consistent Imports**: Use barrel files for cleaner imports
2. **Theme Compliance**: Widgets follow Material 3 design principles
3. **Responsive Design**: Cards and layouts adapt to different screen sizes
4. **Accessibility**: Proper semantics and touch targets
5. **Performance**: Optimized rendering and minimal rebuilds

## Future Enhancements

1. Replace StoreLogo colored containers with actual PNG images
2. Add skeleton loading states
3. Implement hero animations for card transitions
4. Add customizable themes per store type
5. Create storybook for widget documentation

## Contributing

When adding new widgets:
1. Place them in the appropriate category folder
2. Update the barrel file for that category
3. Follow existing naming conventions
4. Include proper documentation
5. Use theme values instead of hardcoded colors
6. Support both light and dark themes