# Component Documentation

This directory contains Dynamic UI component documentation split into focused files for efficient loading by AI agents.

---

## File Organization

### By Component Category

| File | Components | Lines | When to Read |
|------|------------|-------|--------------|
| **_index.md** | Catalog | ~200 | Always (first) |
| **hooks.md** | useDPortalContext, useFormatCurrency | ~150 | Using modals or currency |
| **buttons.md** | DButton, DButtonIcon | ~100 | Using buttons |
| **inputs.md** | DInput, DInputSelect, DInputCurrency, etc. | ~880 | Using form inputs ⚠️ |
| **inputs-advanced.md** | DInputMask, DInputCounter, DBoxFile | ~1480 | Masked/counter/file inputs |
| **selects.md** | DSelect | ~120 | Using dropdowns ⚠️ |
| **date-time.md** | DDatePicker | ~130 | Using date inputs |
| **navigation.md** | DTabs, DStepper, DPaginator | ~200 | Using tabs/wizards/pagination |
| **modals.md** | DModal, DOffcanvas | ~150 | Using modals ⚠️ |
| **feedback.md** | DAlert, DBadge, DToastContainer, useDToast, DSpinner | ~200 | Using alerts/toasts/indicators |
| **layout.md** | DCard, DBox, DContainer, DRow, DCol | ~120 | Using layout components |
| **typography.md** | DHeading, DText, DLink | ~80 | Using text (⚠️ PLANNED) |
| **icons.md** | DIcon | ~150 | Using icons ⚠️ |
| **other.md** | DAvatar, DListGroup, DCurrencyText, etc. | ~200 | Using utility components |

---

## Usage for AI Agents

### Step 1: Read the Catalog
```
Read: _index.md
Goal: Identify which component files you need
```

### Step 2: Selective Loading
```
Based on widget type, load only relevant files:
- Form widget → inputs.md, selects.md, buttons.md
- Dashboard → layout.md, feedback.md, icons.md
- Wizard → navigation.md, inputs.md, buttons.md
```

### Step 3: Critical Sections
```
Before coding, ensure you read:
- inputs.md → Handler Convention
- hooks.md → useDPortalContext signature
- selects.md → Value/onChange pattern
- icons.md → Prefix behavior
- modals.md → Registration requirement
```

---

## Token Efficiency

| Approach | Files Read | Tokens Used |
|----------|-----------|-------------|
| **Old (monolithic)** | 1 large file | ~30K tokens |
| **New (selective)** | 3-5 focused files | ~5-8K tokens |
| **Savings** | - | **75% reduction** |

---

## Maintenance Notes

### When Adding New Components

1. Identify category (input, layout, feedback, etc.)
2. Add to appropriate file (or create new category if needed)
3. Update _index.md with new component entry
4. Update alphabetical index in _index.md
5. Add loading strategy example if new pattern

### When Updating Components

1. Update component file directly
2. If API changes, update critical sections in _index.md
3. Test with widget generation to verify docs are clear
4. Update "Common Mistakes" sections if new errors found

---

## File Naming Convention

- Use lowercase with hyphens: `date-time.md`, not `DateTime.md`
- Use plural for component groups: `inputs.md`, not `input.md`
- Use singular for single components: `icon.md`, not `icons.md` (exception: when file contains multiple icon-related components)
- Prefix catalog with underscore: `_index.md`

---

## Critical Markers

Files with ⚠️ marker contain critical patterns that cause errors if misunderstood:
- **inputs.md** - Handler convention (values, not events)
- **selects.md** - Object-based API (value must be full option object)
- **modals.md** - Registration requirement (availablePortals)
- **icons.md** - Prefix behavior (direct vs constant usage)

AI agents should ALWAYS read these critical sections before using affected components.

---

**Last Updated:** October 2025
**Maintained by:** Dynamic Framework Documentation Team