# UI Patterns

> For AI: how to compose Dynamic UI components for the screens widgets usually need. **Start from an official pattern**: read `modyo://widgets/catalog/patterns` and, if one matches the request, its full content in `modyo://widgets/catalog/patterns/{patternId}` (see `modyo://docs/widgets/INDEX`, Pattern Discovery). This page covers the composition rules around those patterns. Component details: `modyo://docs/widgets/components-_index`.

---

## Component props over utility classes

When a component has a prop for something, use the prop: `color` instead of `text-*`/`bg-*` on a component, `variant="outline"` instead of an `btn-outline-*` class, `hint` + `invalid` instead of a separate error element, `loading` instead of a manual spinner. Utility classes are for layout and spacing around components (`d-flex`, `gap-3`, `mb-4`, …).

---

## Forms

```tsx
<DInput
  label={t('entities.create.name')}
  value={name}
  onChange={setName}
  invalid={isError}
  hint={isError ? t('entities.create.error') : undefined}
/>
```

- Every field has a `label` (or `aria-label`).
- Errors go in `hint` with `invalid`, on the field they belong to.
- Actions at the end: the primary action last, secondary actions with `variant="outline"`, and `loading` on the button that started the operation:

```tsx
<DButton text={t('common.cancel')} variant="outline" onClick={() => closePortal()} />
<DButton text={t('common.save')} loading={isPending} onClick={() => { void submit(); }} />
```

- Two columns on larger screens with `DLayout`:

```tsx
<DLayout gap={3}>
  <DLayout.Pane cols={12} colsMd={6}>
    <DInput label={t('profile.firstName')} value={firstName} onChange={setFirstName} />
  </DLayout.Pane>
  <DLayout.Pane cols={12} colsMd={6}>
    <DInput label={t('profile.lastName')} value={lastName} onChange={setLastName} />
  </DLayout.Pane>
</DLayout>
```

Inputs by type: `modyo://docs/widgets/components-inputs`, `modyo://docs/widgets/components-selects`, `modyo://docs/widgets/components-date-time`.

---

## Lists

Render remote lists through `DDataStateWrapper`, so loading, error, empty and data states are always handled:

```tsx
<DDataStateWrapper
  isLoading={isLoading}
  isError={isError}
  data={data}
  onRetry={retry}
  renderLoading={<LoadingState variant="list" items={5} />}
  renderEmpty={<EmptyState message={t('entities.list.empty')} />}
  renderError={<ErrorState message={t('entities.list.error')} onRetry={retry} />}
>
  {(entities) => (
    <DListGroup ariaLabel={t('entities.list.title')}>
      {entities.map((entity) => (
        <DListGroup.Item key={entity.id}>{entity.name}</DListGroup.Item>
      ))}
    </DListGroup>
  )}
</DDataStateWrapper>
```

- `LoadingState`, `EmptyState` and `ErrorState` are the template's shared states in `src/shared/ui`. States in detail: `modyo://docs/widgets/patterns-data-states`.
- A search box above the list: `DInputSearch` (debounced) or `DInput` with a debounce hook, with the search term in the query key.
- Pagination: `DPaginator` with the page in the query key (`modyo://docs/widgets/components-navigation`).
- Actions per item: buttons inside the item, or a `DDropdown` for several actions (`modyo://docs/widgets/components-overlay-widgets`). Keep actions visible; do not rely on hover.

---

## Master-detail

A list and the detail of the selected item.

- **Wide screens:** two panes, the list marking the selected item with `active`:

```tsx
<DLayout gap={4}>
  <DLayout.Pane cols={12} colsLg={4}>
    <DListGroup ariaLabel={t('accounts.title')}>
      {accounts.map((account) => (
        <DListGroup.Item
          key={account.id}
          as="button"
          active={account.id === selectedId}
          onClick={() => setSelectedId(account.id)}
        >
          {account.name}
        </DListGroup.Item>
      ))}
    </DListGroup>
  </DLayout.Pane>
  <DLayout.Pane cols={12} colsLg={8}>
    <AccountDetail id={selectedId} />
  </DLayout.Pane>
</DLayout>
```

- **Narrow screens, or detail on demand:** open the detail in a `DOffcanvas` portal (`modyo://docs/widgets/components-overlay`). `useMediaBreakpointUpLg` tells which layout applies.

---

## Summary and quick actions

Cards in a grid, built with `DLayout` and `DCard`:

```tsx
<DLayout gap={3}>
  <DLayout.Pane cols={12} colsMd={4}>
    <DCard>
      <DCard.Body>
        <DIcon icon="Wallet" color="primary" size="2rem" hasCircle />
        <p className="mb-0">{t('summary.balance')}</p>
        <DCurrencyText value={balance} />
      </DCard.Body>
    </DCard>
  </DLayout.Pane>
</DLayout>
```

Quick actions are `DButton`s (with `iconStart` and `text`) or `DButtonIcon`s (carrying `aria-label`) in a `DLayout`.

---

## Modals, side panels and confirmations

| Need | Use |
|------|-----|
| Create or edit in a short form | `DModal` portal |
| Detail, filters or a longer form next to the content | `DOffcanvas` portal |
| Yes/no confirmation | `useConfirmModal` |
| Feedback after an action | `useDToast`, or an inline `DAlert` |

Portals are registered in `availablePortals` only if the widget opens them, and receive their actions in the payload (they render outside the `QueryProvider`). Guide: `modyo://docs/widgets/components-overlay`.

---

## Loading and empty states

- Loading content: `DSkeleton` (or the template's `LoadingState`), not a spinner component (Dynamic UI has none).
- An action in progress: `loading` on its `DButton`.
- No data: the template's `EmptyState` inside `DDataStateWrapper`.

---

## Responsive layout

- Grids: `DLayout.Pane` widths per breakpoint (`cols`, `colsSm` … `colsXxl`) and `DLayout` gaps per breakpoint (`gapSm` … `gapXxl`).
- Behavior that changes with the viewport: `useMediaBreakpointUpSm` … `useMediaBreakpointUpXxl`, or `useMediaQuery`.
- In the widget's own SCSS: `df.media-breakpoint-up(md)` from Dynamic's `abstracts/+import` partial (`modyo://docs/widgets/reference-theming`).
- Breakpoints come from the site's CSS (`--bs-breakpoint-*`).
