# Quick Reference: Dynamic UI Conventions

> For AI: the conventions shared by Dynamic UI components, on one page. Exact props of any component, subcomponent, context or hook: `widgets-get-component-props`. Component guides: `modyo://docs/widgets/components-_index`.

---

## Props

| Convention | Correct | Wrong |
|------------|---------|-------|
| Semantic color | `color="danger"` | `theme="danger"` (no component has `theme`) |
| Button and badge text | `<DButton text={t('common.save')} />`, `<DBadge text="New" />` | Text as the only children of `DBadge` |
| Alert text | `<DAlert color="info">{t('…')}</DAlert>` (children) | `<DAlert text="…">` |
| Button style | `variant`: `solid` (default), `outline`, `link`, `soft` | `variant="primary"`, `variant="secondary"` (those are colors) |
| Button and badge size | `size="sm"`, `size="lg"`, or no `size` | `size="md"`, `size="xs"` |
| Soft badge | `<DBadge soft />` | `<DBadge variant="soft" />` |
| Boolean props | `disabled`, `loading`, `invalid`, `centered` | `isDisabled`, `isLoading` |
| Icons | Lucide names in PascalCase: `iconStart="CreditCard"` | `iconStart="credit-card"` |
| Accessible name of a button | `aria-label="…"` on `DButton`/`DButtonIcon` | `ariaLabel` on a button |
| Subcomponents | Through the accessor: `DCard.Body`, `DModal.Header`, `DTabs.Tab`, `DLayout.Pane` | Inventing a prop for the part |

`DAlert.color` accepts `success`, `danger`, `warning` and `info`. `color` on buttons, badges, chips and icons takes any theme color name (`primary`, `secondary`, `success`, `danger`, `warning`, `info`, …).

---

## What `onChange` receives

| Component | Receives |
|-----------|----------|
| `DInput`, `DInputPassword`, `DInputMask`, `DInputPin`, `DPasswordStrengthMeter` | `string` |
| `DInputSearch` | `string`, debounced (`onImmediateChange`: every keystroke) |
| `DInputCurrency`, `DInputCounter` | `number \| undefined` |
| `DInputSwitch` | `boolean` |
| `DInputCheck`, `DInputRange` | the change **event** |
| `DInputPhone` | `{ phone, inputValue, country, isValid }` |
| `DInputSelect` | the selected **item** |
| `DSelect` | the selected **option object** (react-select) |
| `DDatePicker` | `Date \| null` (`[start, end]` with `selectsRange`) |
| `DTabs` | the selected option `{ tab, label }` |
| `DCollapse` | `boolean` |

---

## Opening things

| Need | Use |
|------|-----|
| A modal or side panel | Register in `availablePortals` of `DContextProvider` (`src/app/main.tsx`), open with `openPortal(name, payload)`, close with `closePortal()` |
| A yes/no confirmation | `useConfirmModal` |
| A toast | `useDToast` + a `DToastContainer` in the tree |
| A collapsible section | `DCollapse` (`defaultCollapsed`, `onChange`) |

`DModal`, `DOffcanvas` and `DCollapse` have no `open` prop. Guide: `modyo://docs/widgets/components-overlay`.

---

## Components that exist and are often missed

| Need | Component |
|------|-----------|
| Loading placeholder | `DSkeleton` (`DSkeleton.Text`, `.Block`, `.Circle`) |
| Loading, error, empty and data states in one place | `DDataStateWrapper` |
| Search with debounce | `DInputSearch` |
| Menu of actions | `DDropdown` |
| Tab bar and panels in different places | `DTabs.Provider` |
| Icon-only button | `DButtonIcon` |
| Error boundary | `DErrorBoundary` (the template re-exports it as `ErrorBoundary` from `src/shared/ui`) |

## Components that do not exist

`DRow`, `DCol`, `DContainer`, `DGrid` (use `DLayout` + `DLayout.Pane`, or Bootstrap grid classes), `DTable` (use a Bootstrap table), `DForm` (use a `<form>`), `DSpinner` (use `DSkeleton`, or `loading` on the button), `DText`, `DHeading`, `DLink`, `DButtonGroup`. Dynamic UI has no chart component.

---

## Layout of the widget's root

The template renders the page inside a card in `src/app/App.tsx`:

```tsx
<DCard className="container my-md-14">
  <DCard.Body className="d-flex flex-column gap-4 p-4 p-md-14">
```

The validator warns about `container-fluid` (*No container-fluid*).
