gh-trabian-fluxwing-skills/skills/fluxwing-component-creator/templates/custom-widget.md

# Custom Widget Component

A specialized widget component that extends the basic card with custom properties for dashboard and data display.

## Dashboard Widget

```
┌────────────────────────────────┐
│ {{data.icon}} {{data.title}}    │⟳│
├────────────────────────────────┤
│                                │
│      {{data.value}}            │
│                                │
│ {{data.trend}}                 │
└────────────────────────────────┘
```

## Compact Widget

```
┌─────────────────────────┐
│ {{data.icon}} {{data.title}} │⟳│
│ {{data.value}} {{data.trend}} │
└─────────────────────────┘
```

## Loading State

```
┌────────────────────────────────┐
│ ⟳ Loading...                   │
├────────────────────────────────┤
│                                │
│ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░   │
│                                │
│ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░   │
└────────────────────────────────┘
```

## Error State

```
┌────────────────────────────────┐
│ ⚠ Error Loading Data           │
├────────────────────────────────┤
│                                │
│ Failed to load widget data.    │
│ Click to retry.                │
│                                │
└────────────────────────────────┘
```

## Widget Types

### Analytics Widget
```
┌────────────────────────────────┐
│ 📊 Sales Analytics             │⟳│
├────────────────────────────────┤
│                                │
│      $45,678                   │
│                                │
│ ↗ +23% vs last month          │
└────────────────────────────────┘
```

### Status Widget
```
┌────────────────────────────────┐
│ 🟢 System Status               │⟳│
├────────────────────────────────┤
│                                │
│      All Systems               │
│      Operational               │
│                                │
└────────────────────────────────┘
```

### Counter Widget
```
┌────────────────────────────────┐
│ 👥 Active Users                │⟳│
├────────────────────────────────┤
│                                │
│      2,347                     │
│                                │
│ +12 new this hour              │
└────────────────────────────────┘
```

### Progress Widget
```
┌────────────────────────────────┐
│ 🎯 Goal Progress               │⟳│
├────────────────────────────────┤
│                                │
│ ████████████████░░░░ 80%       │
│                                │
│ 8 of 10 completed              │
└────────────────────────────────┘
```

## Interactive Elements

### Refreshable Widget
```
┌────────────────────────────────┐
│ {{data.icon}} {{data.title}}    │⟳│ ← Click to refresh
├────────────────────────────────┤
│                                │
│      {{data.value}}            │
│                                │
│ Last updated: 2 min ago        │
└────────────────────────────────┘
```

### Auto-Refresh Indicator
```
┌────────────────────────────────┐
│ {{data.icon}} {{data.title}}    │●│ ← Auto-refresh active
├────────────────────────────────┤
│                                │
│      {{data.value}}            │
│                                │
│ Next refresh: 25s              │
└────────────────────────────────┘
```

## Dimensions

- **Standard**: 30×8 characters
- **Compact**: 25×4 characters
- **Large**: 40×10 characters
- **Full Width**: Responsive to container

## Variables

- `widgetType` (string): Type of widget ("dashboard", "analytics", "status", "counter", "progress")
- `data` (object): Widget data with title, value, trend, and icon
  - `title` (string): Widget heading
  - `value` (string): Main display value
  - `trend` (string): Trend indicator (optional)
  - `icon` (string): Widget icon (emoji or symbol)
- `refreshable` (boolean): Whether widget can be manually refreshed
- `autoRefresh` (number): Auto-refresh interval in milliseconds (0 = disabled)
- `compact` (boolean): Use compact layout

## Accessibility

- **Role**: widget or region
- **Focusable**: Yes, if interactive
- **Keyboard Support**:
  - Enter/Space: Refresh widget (if refreshable)
  - Tab: Navigate to next widget
- **ARIA**:
  - `aria-label`: Widget title and current value
  - `aria-live`: "polite" for auto-updating widgets
  - `aria-busy`: "true" when loading

## Usage Examples

### Sales Dashboard Widget
```
┌────────────────────────────────┐
│ 💰 Monthly Revenue             │⟳│
├────────────────────────────────┤
│                                │
│      $127,890                  │
│                                │
│ ↗ +15.3% vs last month        │
└────────────────────────────────┘
```

### Server Monitoring Widget
```
┌────────────────────────────────┐
│ 🖥 Server Load                 │⟳│
├────────────────────────────────┤
│                                │
│      CPU: 45%                  │
│      RAM: 67%                  │
│      Disk: 23%                 │
└────────────────────────────────┘
```

### Task Progress Widget
```
┌────────────────────────────────┐
│ ✅ Sprint Progress             │⟳│
├────────────────────────────────┤
│                                │
│ ████████████░░░░░░░░ 67%       │
│                                │
│ 12 of 18 tasks completed       │
└────────────────────────────────┘
```

## Component Behavior

### Data Loading

1. **Initial Load**: Show loading state while fetching data
2. **Error Handling**: Display error message and retry option
3. **Success**: Show formatted data with trend indicators
4. **Auto-Refresh**: Periodically update data in background

### Refresh Functionality

- **Manual Refresh**: Click refresh icon to update immediately
- **Auto-Refresh**: Configurable interval for automatic updates
- **Loading Feedback**: Visual indication during data fetch
- **Error Recovery**: Retry mechanism for failed requests

### State Management

- **Loading**: Semi-transparent with spinner
- **Error**: Red border with error message
- **Success**: Normal display with data
- **Stale**: Subtle indication when data is outdated

## Design Tokens

### Visual Elements
- `┌─┐└┘─│` = Widget container borders
- `⟳` = Refresh button icon
- `●` = Auto-refresh active indicator
- `░` = Loading placeholder blocks
- `⚠` = Error/warning indicator
- Emoji icons for widget types (📊, 💰, 🟢, etc.)

### Status Colors
- **Success**: Green indicators for positive trends
- **Warning**: Yellow for caution states
- **Error**: Red for error states
- **Neutral**: Gray for normal/inactive states

## Related Components

- **Card**: Base component that this extends
- **Dashboard**: Container for multiple widgets
- **Chart**: Data visualization components
- **Metric**: Simple numeric display components

## Implementation Notes

This widget component extends the base card component with:

1. **Data Management**: Built-in data fetching and state management
2. **Auto-Refresh**: Configurable automatic data updates
3. **Error Handling**: Robust error states and recovery
4. **Accessibility**: Full screen reader and keyboard support
5. **Customization**: Flexible widget types and layouts
6. **Performance**: Efficient rendering and update mechanisms

## Extension Points

- **Custom Widget Types**: Add new widget variations
- **Data Sources**: Integrate with different APIs
- **Visualization**: Add charts and graphs
- **Theming**: Custom color schemes and layouts
- **Interactions**: Additional click handlers and actions