# Icons - Lucide Icon System (v2.0)

**CRITICAL:** Dynamic UI 2.0 uses Lucide Icons with PascalCase names.

---

## 🚨 Quick Reference: Top 30 Icons

Use this table when generating widgets to find correct icon names FAST.

| Use Case | Bootstrap (OLD ❌) | Lucide (NEW ✅) | Example |
|----------|-------------------|-----------------|---------|
| Credit card | `credit-card`, `credit-card-2-front` | `CreditCard` | `<DIcon icon="CreditCard" />` |
| Calendar | `calendar`, `calendar-event` | `Calendar` | `<DIcon icon="Calendar" />` |
| Calendar done | `calendar-check` | `CalendarCheck` | `<DIcon icon="CalendarCheck" />` |
| Money | `cash`, `cash-stack`, `currency-dollar` | `DollarSign` | `<DIcon icon="DollarSign" />` |
| Wallet | `wallet`, `wallet2` | `Wallet` | `<DIcon icon="Wallet" />` |
| Users (plural) | `people`, `people-fill` | `Users` | `<DIcon icon="Users" />` |
| User (single) | `person`, `person-fill` | `User` | `<DIcon icon="User" />` |
| Info | `info-circle`, `info-circle-fill` | `Info` | `<DIcon icon="Info" />` |
| Lock | `lock`, `lock-fill` | `Lock` | `<DIcon icon="Lock" />` |
| Warning | `exclamation-triangle`, `exclamation-triangle-fill` | `AlertTriangle` | `<DIcon icon="AlertTriangle" />` |
| Error | `exclamation-circle`, `exclamation-circle-fill` | `AlertCircle` | `<DIcon icon="AlertCircle" />` |
| Clock/Time | `clock`, `clock-fill` | `Clock` | `<DIcon icon="Clock" />` |
| Receipt | `receipt`, `receipt-cutoff` | `Receipt` | `<DIcon icon="Receipt" />` |
| Store/Shop | `shop`, `shop-window` | `Store` | `<DIcon icon="Store" />` |
| Document | `file-text`, `file-earmark-text` | `FileText` | `<DIcon icon="FileText" />` |
| ID/Number | `hash` | `Hash` | `<DIcon icon="Hash" />` |
| Shopping | `cart`, `cart-fill` | `ShoppingCart` | `<DIcon icon="ShoppingCart" />` |
| Download | `arrow-down-circle` | `ArrowDownCircle` | `<DIcon icon="ArrowDownCircle" />` |
| Upload | `arrow-up-circle` | `ArrowUpCircle` | `<DIcon icon="ArrowUpCircle" />` |
| Percentage | `percent` | `Percent` | `<DIcon icon="Percent" />` |
| Search | `search` | `Search` | `<DIcon icon="Search" />` |
| Filter | `funnel`, `funnel-fill` | `Filter` | `<DIcon icon="Filter" />` |
| Close | `x`, `x-circle` | `XCircle` | `<DIcon icon="XCircle" />` |
| Mail | `envelope`, `envelope-fill` | `Mail` | `<DIcon icon="Mail" />` |
| Inbox | `inbox`, `inbox-fill` | `Inbox` | `<DIcon icon="Inbox" />` |
| Next | `chevron-right` | `ChevronRight` | `<DIcon icon="ChevronRight" />` |
| Previous | `chevron-left` | `ChevronLeft` | `<DIcon icon="ChevronLeft" />` |
| More options | `three-dots`, `three-dots-vertical` | `MoreHorizontal`, `MoreVertical` | `<DIcon icon="MoreHorizontal" />` |
| Home | `house`, `house-door` | `Home` | `<DIcon icon="Home" />` |
| Settings | `gear`, `gear-fill` | `Settings` | `<DIcon icon="Settings" />` |

---

## 🔍 How to Find Icon Names

### Method 1: Use This Table (Fastest)
Look in the table above for the icon you need.

### Method 2: Browse Lucide (If Not in Table)
1. Go to https://lucide.dev/icons/
2. Search for the icon visually
3. Note the name shown (it's in kebab-case on the site)
4. Convert to PascalCase: `arrow-right` → `ArrowRight`

### Method 3: Search This File
Use Cmd+F (Mac) or Ctrl+F (Windows) to search this file for the Bootstrap name.

---

## ⚠️ Common Mistakes

### Mistake #1: Using Kebab-Case
```tsx
// ❌ WRONG - Will show "?"
<DIcon icon="credit-card" />
<DButton iconStart="calendar-event" text="Schedule" />

// ✅ CORRECT
<DIcon icon="CreditCard" />
<DButton iconStart="Calendar" text="Schedule" />
```

### Mistake #2: Using Bootstrap Icon Names
```tsx
// ❌ WRONG - Bootstrap Icon names don't exist in v2.0
<DIcon icon="house" />
<DIcon icon="person" />

// ✅ CORRECT - Use Lucide names (PascalCase)
<DIcon icon="Home" />
<DIcon icon="User" />
```

### Mistake #3: Icon Constants in Wrong Format
```tsx
// ❌ WRONG
const ICONS = {
  user: 'person',           // Wrong!
  home: 'house-door',       // Wrong!
  calendar: 'calendar-event' // Wrong!
};

// ✅ CORRECT
const ICONS = {
  user: 'User',             // Correct!
  home: 'Home',             // Correct!
  calendar: 'Calendar'      // Correct!
};
```

---

## 🔧 Why Icons Show as "?"

If you see "?" instead of an icon, the issue is in `DIconBase.tsx`:

```typescript
// DIconBase.tsx lookup logic
const icons = LucideIcons as unknown as Record<string, ComponentType>;
return icons[icon] || null;  // ❌ Returns null for "credit-card"
                              // ✅ Returns component for "CreditCard"
```

**Root cause:** JavaScript object keys are case-sensitive. Lucide exports icons as PascalCase (`CreditCard`), so kebab-case lookups (`credit-card`) fail.

---

## Icons by Domain

**Financial**: `ShoppingCart`, `ShoppingBag`, `Store`, `Receipt`, `CreditCard`, `DollarSign`, `Wallet`, `Coins`, `Building`, `Landmark`, `PiggyBank`
**Transport**: `Car`, `Bus`, `Train`, `Plane`, `Bike`, `Truck`, `Taxi`, `MapPin`, `Fuel`, `TrendingUp`
**Entertainment**: `Film`, `Music`, `Gamepad2`, `Theater`, `Ticket`, `Coffee`, `UtensilsCrossed`, `Pizza`, `Beer`
**Utilities**: `Settings`, `Zap`, `Lightbulb`, `Plug`, `Wifi`, `Phone`, `Wrench`, `Package`, `Home`
**Health**: `Heart`, `Activity`, `Pill`, `Syringe`, `Stethoscope`, `Cross`, `Ambulance`, `Hospital`
**Business**: `Briefcase`, `Calendar`, `Clock`, `FileText`, `Folder`, `Clipboard`, `Printer`, `Calculator`, `BarChart3`, `TrendingUp`, `TrendingDown`

**Finding icons not listed here:** Browse https://lucide.dev/icons/, find the kebab-case name, convert to PascalCase (`arrow-right-circle` -> `ArrowRightCircle`).

---

## 🎯 DIcon Component API

### Component Props Reference

DIcon and DIconBase provide these props (**always prefer these over utility classes**):

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `icon` | `string` | Required | Lucide icon name in PascalCase |
| `size` | `string` | `"1em"` | Icon size (e.g., "24px", "2rem") |
| `color` | `ComponentColor` | `undefined` | Theme color name |
| `hasCircle` | `boolean` | `false` | Add circular background |
| `strokeWidth` | `number` | `2` | Lucide stroke width |
| `className` | `string` | `undefined` | Additional CSS classes (use sparingly) |

---

### Key Props

- **`hasCircle`**: Auto-creates circular background (10% opacity of `color`, padding scales at 40% of size). Use this instead of manual `<div className="rounded-circle">` wrappers.
- **`color`**: Use `color="success"` instead of `className="text-success"`. Type-safe and theme-integrated.

---

### Available Colors

`"primary"`, `"secondary"`, `"success"`, `"danger"`, `"warning"`, `"info"`, `"light"`, `"dark"`

### Common Patterns

```tsx
// Summary card icon
<DIcon icon="TrendingUp" size="24px" color="success" hasCircle />

// Status indicator
const statusConfig = { active: { icon: 'CheckCircle', color: 'success' }, pending: { icon: 'Clock', color: 'warning' }, error: { icon: 'XCircle', color: 'danger' } };
<DIcon icon={statusConfig[status].icon} size="16px" color={statusConfig[status].color} />

// Empty state
<DIcon icon="Inbox" size="48px" color="secondary" className="mb-3" />
```

---

### Debugging

If icons show "?": check for kebab-case names (`grep -rn 'icon="[a-z]+-' src/`). All icon names must be PascalCase.

## Bootstrap to Lucide Migration Table

| Bootstrap (OLD) | Lucide (NEW) | Bootstrap (OLD) | Lucide (NEW) |
|----------------|--------------|----------------|--------------|
| `person` | `User` | `people` | `Users` |
| `person-plus` | `UserPlus` | `person-x` | `UserX` |
| `chevron-left/right/up/down` | `ChevronLeft/Right/Up/Down` | `arrow-left/right/up/down` | `ArrowLeft/Right/Up/Down` |
| `house` | `Home` | `list` | `List` |
| `plus`/`plus-circle` | `Plus`/`CirclePlus` | `dash`/`dash-circle` | `Minus`/`CircleMinus` |
| `x`/`x-circle` | `X`/`XCircle` | `check`/`check-circle` | `Check`/`CircleCheck` |
| `pencil` | `Pencil` | `trash` | `Trash2` |
| `envelope` | `Mail` | `telephone` | `Phone` |
| `chat` | `MessageCircle` | `bell` | `Bell` |
| `calendar` | `Calendar` | `clock` | `Clock` |
| `info-circle` | `Info` | `exclamation-triangle` | `AlertTriangle` |
| `exclamation-circle` | `AlertCircle` | `question-circle` | `HelpCircle` |
| `file-text` | `FileText` | `folder` | `Folder` |
| `lock` | `Lock` | `unlock` | `Unlock` |
| `shield` | `Shield` | `key` | `Key` |
| `eye` | `Eye` | `eye-slash` | `EyeOff` |
| `play` | `Play` | `pause` | `Pause` |
| `image` | `Image` | `camera` | `Camera` |
| `cart` | `ShoppingCart` | `bag` | `ShoppingBag` |
| `tag` | `Tag` | `search` | `Search` |
| `funnel` | `Filter` | `gear` | `Settings` |
| `three-dots` | `MoreHorizontal` | `bookmark` | `Bookmark` |
| `star` | `Star` | `flag` | `Flag` |
| `download` | `Download` | `upload` | `Upload` |

**Full reference:** https://lucide.dev/icons/ (1000+ icons)

---

**Tip**: For type-safe icon names: `import type * as LucideIcons from 'lucide-react'; type IconName = keyof typeof LucideIcons;`