# Component Documentation Catalog > **For AI:** This is your component documentation map. Use it to load only what you need. > **Props completas:** Usar MCP tool `widgets-get-component-props`. Este catΓ‘logo documenta solo convenciones y gotchas. > **Dynamic UI 2.0 IMPORTANT:** All styled components use `color` prop (NOT `theme`). Valid values: "primary" | "secondary" | "success" | "danger" | "warning" | "info" | "light" | "dark" --- ## ⚠️ Icons: Lucide en PascalCase Dynamic UI 2.0 usa **Lucide Icons** con formato **PascalCase**. πŸ“– **Referencia completa:** `modyo://docs/widgets/components-icons` --- ## 🎯 Quick Component Finder ### Hooks & Context **File:** `hooks.md` - **useDPortalContext** - Modal/portal management (openPortal, closePortal) - **useFormatCurrency** - Currency formatting with locale --- ### Charts (Recharts Patterns) πŸ“Š **File:** `charts.md` - **BarChart** - Bar chart for categorical data comparison (Recharts pattern) - **PieChart** - Pie/donut chart for proportions (Recharts pattern) - **RadialBarChart** - Radial gauge for percentages (Recharts pattern) - **LineChart (minimal)** - Sparkline for inline trends (Recharts pattern) - **LineChart (multi)** - Multi-series line chart for time comparisons (Recharts pattern) - ⚠️ **NOT library components** β€” These are Recharts usage patterns, not D-prefixed components - ⚠️ **CRITICAL:** Requires `recharts@~3.3.0` as peer dependency - ⚠️ **CRITICAL:** All charts require container with defined dimensions --- ### Buttons & Actions **File:** `buttons.md` - **DButton** - Primary action button ⚠️ **BREAKING CHANGE:** `pill` prop removed in v2.0 - **DButtonIcon** - Icon-only button --- ### Form Inputs **File:** `inputs.md` - **DInput** - Text input with validation (also handles search with iconStart) - **DInputSelect** - Native HTML select with Dynamic UI styling ⚠️ Simpler alternative to DSelect - **DInputPin** - PIN code input - **DInputPassword** - Password with toggle visibility - **DInputCheck** - Checkbox input - **DInputSwitch** - Toggle switch - **DInputCurrency** - Currency input with formatting - **DInputPhone** - Phone number input - **DInputRange** - Range/slider input ⚠️ **Exception:** onChange receives event - ⚠️ **CRITICAL:** Read "Handler Convention" section first - ⚠️ **NOTE:** DInputSearch removed in 2.0 - use DInput with type="search" ### Form Inputs (Advanced) **File:** `inputs-advanced.md` - **DInputMask** - Masked text input ⚠️ **Exception:** onChange receives event - **DInputCounter** - Number counter with increment/decrement buttons - **DBoxFile** - File upload with drag & drop ⚠️ maxSize in BYTES --- ### Select Dropdowns **File:** `selects.md` - **DSelect** - Dropdown select (react-select based) - ⚠️ **CRITICAL:** DSelect uses special object-based API - ⚠️ **NOTE:** DSelectNative removed in 2.0 β€” use `DInputSelect` (see `inputs.md`) --- ### Date & Time **File:** `date-time.md` - **DDatePicker** - Date picker (react-datepicker based) - ⚠️ Store dates as ISO strings (not Date objects) --- ### Navigation **File:** `navigation.md` - **DTabs** - Tab navigation with content panels - **DStepper** - Wizard step indicator - **DPaginator** - Pagination controls - ⚠️ **NOTE:** DBreadcrumb removed in 2.0 β€” use Bootstrap breadcrumb HTML - ⚠️ **NOTE:** DNavbar removed in 2.0 β€” use Bootstrap navbar HTML --- ### Modals & Overlays **File:** `modals.md` - **DModal** - Modal dialog - **DOffcanvas** - Slide-in panel - ⚠️ **CRITICAL:** Must register in DContextProvider.availablePortals --- ### Feedback & Indicators **File:** `feedback.md` - **DAlert** - Alert messages (v2.0: extended color support) - **DToastContainer** - Toast container (place once in app root) - **useDToast** - Toast hook ⚠️ Returns `toast()` function with `ToastData` - **DBadge** - Badge labels - **DChip** - Removable chip/tag for selected items - **DSpinner** - Loading spinner --- ### Layout & Structure **File:** `layout.md` - **DCard** - Card container - **DBox** - Flex box utility - **DLayout** / **DLayoutPane** - Grid-based responsive layout system ✨ NEW in v2.0 - **DContainer** - Max-width container - **DRow** / **DCol** - Grid system - **DCollapse** - Collapsible content container ⚠️ Controlled component --- ### Icons **File:** `icons.md` - **DIcon** - Lucide Icons en PascalCase --- ### Other Components **File:** `other.md` - **DAvatar** - User avatars - **DCreditCard** - Credit card display ⚠️ **BREAKING CHANGE:** Size props removed in v2.0 - **DListGroup** - List group container with `DListGroup.Item` compound pattern - **DCurrencyText** - Formatted currency display (alternative to useFormatCurrency hook) - **DProgress** - Progress bar (v2.0: added `height` prop) - **DOtp** - OTP verification with timer - **DTimeline** - Timeline/process steps - **DBox** - Semantic container --- ## πŸ—ΊοΈ Loading Strategy by Widget Type ### Form-Heavy Widget (Quote, Application, Calculator) **You need:** Form inputs, dropdowns, buttons, maybe dates **Load these files (in order):** 1. `_index.md` (this file) - Identify components 2. `inputs.md` - DInput, DInputCurrency, DInputSwitch - ⚠️ **CRITICAL:** Read "Handler Convention" section FIRST - Learn: `onChange={(value) => setValue(value)}` NOT `onChange={(e) => ...}` 3. `selects.md` - DSelect for dropdowns - ⚠️ **CRITICAL:** Read "Value and onChange Pattern" section - Learn: `value={options.find(...)}` NOT `value={selectedValue}` 4. `buttons.md` - DButton for submit/cancel - Learn: `text` prop, `color` vs `variant` 5. `date-time.md` - DDatePicker (ONLY if form has date fields) - Learn: Use Date objects, store ISO strings **Skip:** navigation.md, modals.md, layout.md, icons.md, feedback.md, other.md **Token usage:** ~5-7K **Critical mistakes to avoid:** - ❌ Using `e.target.value` with inputs - ❌ Using string value for DSelect - ❌ Using `variant` on DBadge (use `color`) - ❌ Forgetting to register modals in availablePortals --- ### List/Dashboard Widget **You need:** Cards, badges, icons, pagination **Load these files (in order):** 1. `_index.md` (this file) 2. `layout.md` - DCard for list items - Learn: DCard.Header, DCard.Body, DCard.Footer structure 3. `feedback.md` - DBadge for status indicators - ⚠️ **CRITICAL:** Read props table - uses `color` NOT `variant` - Learn: `` 4. `icons.md` - DIcon for visual elements - ⚠️ **CRITICAL:** Uses Lucide icons with PascalCase names - Learn: `` - see icons.md for mapping table 5. `typography.md` - DHeading, DText 6. `other.md` - DPaginator, DAvatar (if needed) **Skip:** inputs.md, selects.md, date-time.md, buttons.md, navigation.md, modals.md **Token usage:** ~6-8K **Critical mistakes to avoid:** - ❌ Using `variant` instead of `color` on badges - ❌ Using Bootstrap `bi-*` icons (use Lucide PascalCase) - ❌ Using children instead of `text` on DBadge --- ### Wizard/Multi-Step Widget **You need:** Steps indicator, form inputs, navigation buttons **Load these files (in order):** 1. `_index.md` (this file) 2. `navigation.md` - DStepper, DTabs - ⚠️ **CRITICAL:** DStepper requires numeric step values - Learn: Create mapping `{ step1: 1, step2: 2 }` 3. `inputs.md` - Form inputs - ⚠️ **CRITICAL:** Read "Handler Convention" section 4. `selects.md` - Dropdowns (if needed) 5. `buttons.md` - Next/Previous/Submit buttons 6. `date-time.md` - Dates (if needed) **Skip:** modals.md, layout.md, feedback.md, icons.md, other.md **Token usage:** ~7-9K **Critical mistakes to avoid:** - ❌ Using string step names with DStepper - ❌ Using `e.target.value` with inputs - ❌ Wrong DTabOption structure --- ### Modal/Dialog Widget **You need:** Modal management, buttons, maybe forms **Load these files (in order):** 1. `_index.md` (this file) 2. `hooks.md` - useDPortalContext - ⚠️ **CRITICAL:** Read complete signature - Learn: `openPortal(name, props)` - 2 args required - Learn: `closePortal()` - 0 args 3. `modals.md` - DModal, DOffcanvas - ⚠️ **CRITICAL:** Read "Registration" section - Learn: Must register in `DContextProvider.availablePortals` 4. `buttons.md` - Modal actions 5. `inputs.md` - Form in modal (if needed) **Skip:** navigation.md, layout.md, feedback.md, icons.md, other.md **Token usage:** ~5-6K **Critical mistakes to avoid:** - ❌ Forgetting to register modal in availablePortals - ❌ Passing 1 argument to openPortal - ❌ Passing arguments to closePortal - ❌ Using `open` instead of registering portal --- ### Tabs/Navigation Widget **You need:** Tab navigation, content panels **Load these files (in order):** 1. `_index.md` (this file) 2. `navigation.md` - DTabs - ⚠️ **CRITICAL:** Read DTabOption interface - Learn: State stores DTabOption object, not string 3. `layout.md` - DCard for tab content 4. `buttons.md` - Actions in tabs 5. Other files based on tab content **Token usage:** ~4-6K **Critical mistakes to avoid:** - ❌ Using string for tab state - ❌ Passing DTabOption object to defaultSelected --- ### Dashboard/Analytics Widget (NEW in v2.0) **You need:** Charts, KPI cards, data visualization **Load these files (in order):** 1. `_index.md` (this file) 2. `charts.md` - Recharts patterns (BarChart, PieChart, RadialBarChart, LineChart) - ⚠️ **CRITICAL:** Install `recharts@~3.3.0` first - ⚠️ **CRITICAL:** All charts need container with defined dimensions 3. `layout.md` - DCard for metric cards 4. `feedback.md` - DBadge for status indicators 5. `typography.md` - DHeading, DText for labels **Skip:** inputs.md, selects.md, date-time.md, navigation.md, modals.md **Token usage:** ~6-8K **Critical mistakes to avoid:** - ❌ Not installing recharts dependency - ❌ Not defining container dimensions (charts won't render) - ❌ Trying to use charts without wrapping in sized container --- ## πŸ” Alphabetical Component Index Quick lookup table (component β†’ file): | Component | File | Notes | |-----------|------|-------| | DAlert | feedback.md | Uses `color` prop (v2.0 extended colors) | | DAvatar | other.md | - | | DBadge | feedback.md | Uses `text` and `color` props | | DBox | other.md | Semantic container (v2.0) | | ~~DBreadcrumb~~ | navigation.md | ❌ **REMOVED in 2.0** β€” use Bootstrap breadcrumb HTML | | DButton | buttons.md | ⚠️ BREAKING: `pill` prop removed in v2.0 | | DButtonIcon | buttons.md | Uses `color` prop (v2.0) | | DCard | layout.md | - | | DChip | feedback.md | Removable chip/tag for selected items | | DCol | layout.md | - | | DCollapse | layout.md | Collapsible content container | | DContainer | layout.md | - | | **DCreditCard** | **other.md** | **⚠️ BREAKING: Size props removed in v2.0** | | **DCurrencyText** | **other.md** | Formatted currency display | | DDatePicker | date-time.md | ⚠️ Date object vs string | | ~~DHeading~~ | β€” | ⚠️ PLANNED β€” not yet in Dynamic UI 2.x | | DIcon | icons.md | Lucide Icons (PascalCase) | | DInput | inputs.md | ⚠️ Handler convention; replaces DInputSearch | | DInputCheck | inputs.md | ⚠️ Handler convention | | DInputCounter | inputs-advanced.md | Number counter with +/- buttons | | DInputCurrency | inputs.md | ⚠️ Handler convention | | DInputMask | inputs-advanced.md | ⚠️ Exception: onChange receives event | | DInputPassword | inputs.md | ⚠️ Handler convention | | DInputPhone | inputs.md | ⚠️ Handler convention | | DInputPin | inputs.md | ⚠️ Handler convention | | DInputRange | inputs.md | ⚠️ Exception: onChange receives event | | **DInputSelect** | **inputs.md** | Native HTML select β€” simpler alternative to DSelect | | DInputSwitch | inputs.md | ⚠️ Handler convention | | **DLayout** | **layout.md** | **✨ NEW v2.0: Grid-based layout system** | | **DLayoutPane** | **layout.md** | **✨ NEW v2.0: Grid pane (use DLayout.Pane)** | | ~~DLink~~ | β€” | ⚠️ PLANNED β€” not yet in Dynamic UI 2.x | | **DListGroup** | **other.md** | Container + DListGroup.Item compound pattern | | DModal | modals.md | ⚠️ Must register in availablePortals | | ~~DNavbar~~ | navigation.md | ❌ **REMOVED in 2.0** β€” use Bootstrap navbar HTML | | DOffcanvas | modals.md | ⚠️ Must register in availablePortals | | DOtp | other.md | OTP verification (v2.0) | | DPaginator | navigation.md | Pagination controls (controlled state) | | **DProgress** | **other.md** | **NEW v2.0: height prop** | | DRow | layout.md | - | | DSelect | selects.md | ⚠️ Special object API | | ~~DSelectNative~~ | selects.md | ❌ **REMOVED in 2.0** β€” use DInputSelect | | DSpinner | feedback.md | - | | DStepper | navigation.md | ⚠️ Numeric values required | | DTabs | navigation.md | ⚠️ DTabOption interface | | ~~DText~~ | β€” | ⚠️ PLANNED β€” not yet in Dynamic UI 2.x | | DTimeline | other.md | Timeline/steps (v2.0) | | **DToastContainer** | **feedback.md** | Place once in app root for toast system | | useFormatCurrency | hooks.md | ⚠️ Destructure `format` method | | **useDToast** | **feedback.md** | Returns `toast()` function with ToastData | | useDPortalContext | hooks.md | ⚠️ openPortal signature | **Components removed in 2.0:** DInputSearch (use DInput with type="search"), DList/DListItem (use DListGroup), DSelectNative (use DInputSelect), DBreadcrumb (use Bootstrap HTML), DNavbar (use Bootstrap HTML), DQuickAction* components, DSkeleton **Recharts patterns (not library components):** BarChart, PieChart, RadialBarChart, LineChart β€” see `charts.md` for usage patterns. Requires `recharts@~3.3.0`. --- ## ⚠️ Critical Sections to Read First Before generating ANY code with these components, read these sections: 1. **icons.md** β†’ Lucide Icons en PascalCase 2. **inputs.md** β†’ "Handler Convention" section - All Dynamic UI inputs pass VALUES directly (not events) - Prevents 80% of input-related errors 3. **hooks.md** β†’ "useDPortalContext" signature - openPortal requires 2 arguments - closePortal requires 0 arguments 4. **feedback.md** β†’ "Toast System" (DToastContainer + useDToast) - Place DToastContainer once in app root - useDToast returns `toast()` function accepting ToastData 5. **selects.md** β†’ "Value and onChange Pattern" - DSelect requires full option object for `value` - onChange receives option object 6. **modals.md** β†’ "Modal Registration" - All modals must be in DContextProvider.availablePortals 7. **charts.md** β†’ "Dependency" and "Container Pattern" (NEW in v2.0) - Requires recharts@~3.3.0 installation - All charts need container with defined dimensions --- ## πŸ“Š Token Usage Guide | File | Approx. Lines | Approx. Tokens | |------|---------------|----------------| | hooks.md | ~150 | ~2K | | **charts.md** | **~280** | **~3.5K** | | icon-migration-guide.md | ~280 | ~3.5K | | buttons.md | ~100 | ~1.5K | | inputs.md | ~880 | ~4K | | inputs-advanced.md | ~1480 | ~6K | | selects.md | ~120 | ~2K | | date-time.md | ~130 | ~2K | | navigation.md | ~180 | ~2.5K | | modals.md | ~150 | ~2K | | feedback.md | ~100 | ~1.5K | | layout.md | ~120 | ~1.5K | | ~~typography.md~~ | β€” | removed | | icons.md | ~150 | ~2K | | other.md | ~100 | ~1.5K | **Total if reading all:** ~30K tokens ❌ **Typical widget needs:** ~5-8K tokens βœ… --- ## 🎯 Usage Examples ### Example 1: Insurance Quote Form ``` User request: "Generate insurance quote form with vehicle info, personal details, coverage selection" Analysis: - Form inputs needed βœ“ - Dropdowns for selections βœ“ - Date picker for birthdate βœ“ - Submit button βœ“ Load: 1. _index.md (this file) - find components 2. inputs.md - DInput, DInputCurrency 3. selects.md - DSelect 4. date-time.md - DDatePicker 5. buttons.md - DButton Skip: navigation.md, modals.md, layout.md, icons.md, other.md Result: ~7K tokens vs 25K (72% savings) ``` --- ### Example 2: Policy Dashboard ``` User request: "Generate dashboard showing policy cards with status badges" Analysis: - Card layout βœ“ - Badge for status βœ“ - Icons for policy types βœ“ - No forms needed βœ— Load: 1. _index.md (this file) 2. layout.md - DCard 3. feedback.md - DBadge 4. icons.md - DIcon 5. typography.md - DHeading, DText Skip: inputs.md, selects.md, date-time.md, buttons.md, navigation.md, modals.md Result: ~6K tokens vs 25K (76% savings) ``` --- ## 🎯 Quick Component Lookup **"I need to display a status label"** β†’ Read `feedback.md` β†’ DBadge β†’ Critical: Uses `text` prop and `color` prop **"I need a text input"** β†’ Read `inputs.md` β†’ DInput β†’ Critical: Handler receives value directly, not event **"I need a dropdown"** β†’ Read `selects.md` β†’ DSelect (react-select, advanced) β†’ Or read `inputs.md` β†’ DInputSelect (native select, simpler) β†’ Critical: DSelect value must be option object, not string **"I need a date picker"** β†’ Read `date-time.md` β†’ DDatePicker β†’ Critical: selected prop receives Date, store as ISO string **"I need a modal"** β†’ Read `hooks.md` + `modals.md` β†’ useDPortalContext + DModal β†’ Critical: Must register in availablePortals **"I need tabs"** β†’ Read `navigation.md` β†’ DTabs β†’ Critical: State stores DTabOption object **"I need step indicator"** β†’ Read `navigation.md` β†’ DStepper β†’ Critical: Step values must be numbers **"I need an icon"** β†’ Read `icons.md` β†’ DIcon β†’ Critical: Lucide Icons en PascalCase **"I need alert/notification"** β†’ Read `feedback.md` β†’ DAlert β†’ Critical: Uses `color` prop, not `theme` or `variant` **"I need toast notifications"** β†’ Read `feedback.md` β†’ DToastContainer + useDToast β†’ Critical: Place DToastContainer once in root, use `toast()` from useDToast hook **"I need loading spinner"** β†’ Read `feedback.md` β†’ DSpinner β†’ Critical: Uses `color` prop **"I need a search input"** β†’ Read `inputs.md` β†’ DInput with type="search" and iconStart="Search" β†’ Critical: DInputSearch removed in v2.0, use DInput instead **"I need charts/data visualization"** β†’ Read `charts.md` β†’ Recharts patterns (BarChart, PieChart, RadialBarChart, LineChart) β†’ Critical: Install recharts@~3.3.0, wrap charts in container with dimensions --- ## πŸš€ Next Steps 1. βœ… You've read the catalog 2. β†’ Identify which components your widget needs 3. β†’ Load only those specific files 4. β†’ Start coding with patterns from loaded docs --- **Remember:** Quality over quantity. Loading 3 relevant files beats loading all 12 files.