# Modals and Offcanvas

`DModal` (a centered dialog) and `DOffcanvas` (a side or edge panel) open as **portals**: they are registered once in `DContextProvider` and opened by name. Neither has an `open` prop. Exact props: `widgets-get-component-props`.

---

## When to use which

| Use | Component |
|-----|-----------|
| A short task that needs the user's full attention: confirm, create, a short form | `DModal` |
| Details, filters or a longer form next to the content the user is looking at | `DOffcanvas` |
| A yes/no confirmation | `useConfirmModal` (see below) |

---

## 1. Write the portal component

The component receives its `payload` and closes itself with `closePortal()`. From the template's reference feature (`src/features/entities/ui/EntityCreateModal.tsx`):

```tsx
import type { PortalProps } from '@dynamic-framework/ui-react';
import {
  DButton,
  DInput,
  DModal,
  useDPortalContext,
} from '@dynamic-framework/ui-react';

export type EntityCreatePayload = {
  onCreate: (data: CreateEntityData) => Promise<unknown>;
};

export type EntityPortals = {
  'entity-create': EntityCreatePayload;
};

export function EntityCreateModal({ payload }: PortalProps<EntityCreatePayload>) {
  const { t } = useTranslation();
  const { closePortal } = useDPortalContext<EntityPortals>();
  // … local state: name, isPending, isError, submit()

  return (
    <DModal name="entity-create" centered>
      <DModal.Header onClose={closePortal} showCloseButton>
        <h5 className="fw-bold">{t('entities.create.title')}</h5>
      </DModal.Header>
      <DModal.Body className="py-3 px-5">
        <DInput
          label={t('entities.create.name')}
          value={name}
          onChange={setName}
          invalid={isError}
          hint={isError ? t('entities.create.error') : undefined}
        />
      </DModal.Body>
      <DModal.Footer>
        <DButton text={t('common.cancel')} variant="outline" onClick={() => closePortal()} />
        <DButton text={t('common.save')} loading={isPending} onClick={() => { void submit(); }} />
      </DModal.Footer>
    </DModal>
  );
}
```

- `name` is required and must match the key under which the component is registered.
- The portal type (`EntityPortals`) maps each portal name to its payload, so `openPortal` is type-checked.

## 2. Register it

The canonical template mounts `DContextProvider` in `src/app/main.tsx` with `availablePortals={{}}`. Register a portal there only if the widget opens it (registering bundles `DModal` and its animation library):

```tsx
import { EntityCreateModal, type EntityPortals } from '@/features/entities';

<DContextProvider<EntityPortals> availablePortals={{ 'entity-create': EntityCreateModal }}>
```

Opening a name that is not registered throws: `No component registered for portal "<name>". Ensure "<name>" has an entry in the availablePortals map on DContextProvider.`

## 3. Open it

```tsx
const { openPortal } = useDPortalContext<EntityPortals>();

<DButton
  text={t('entities.list.create')}
  iconStart="Plus"
  onClick={() => openPortal('entity-create', { onCreate: createEntity })}
/>
```

`openPortal(name, payload)` takes both arguments; `closePortal()` closes the portal on top; `stack` lists the open portals.

**Portals render outside the `QueryProvider`.** A portal component does not call TanStack Query hooks: the component that opens it passes the action in the payload, as above. See `modyo://docs/widgets/patterns-tanstack-query`.

---

## DModal

| Prop | Use |
|------|-----|
| `name` | Required; the registered portal name |
| `size` | `sm`, `lg` or `xl` |
| `centered`, `scrollable`, `staticBackdrop` | Position, body scroll, and a backdrop that does not close on click |
| `fullScreen`, `fullScreenFrom` | Full screen always, or below a breakpoint |
| `ariaLabel` | Accessible name when the dialog has no visible title |

Parts: `DModal.Header` (`showCloseButton`, `onClose`, `icon`), `DModal.Body`, `DModal.Footer` (`actionPlacement`: `start`, `end`, `fill` or `center`).

## DOffcanvas

```tsx
<DOffcanvas name="filters" openFrom="end" ariaLabel={t('filters.title')}>
  <DOffcanvas.Header showCloseButton onClose={closePortal}>
    <h5>{t('filters.title')}</h5>
  </DOffcanvas.Header>
  <DOffcanvas.Body>{/* … */}</DOffcanvas.Body>
  <DOffcanvas.Footer actionPlacement="fill">
    <DButton text={t('filters.apply')} onClick={apply} />
  </DOffcanvas.Footer>
</DOffcanvas>
```

| Prop | Use |
|------|-----|
| `name` | Required; the registered portal name |
| `openFrom` | `end` (default), `start`, `top` or `bottom`; also a responsive map by breakpoint |
| `width`, `height`, `scrollable`, `staticBackdrop` | Size and behavior |
| `ariaLabel` | Accessible name when the panel has no visible title |

Parts: `DOffcanvas.Header`, `DOffcanvas.Body`, `DOffcanvas.Footer`, with the same props as the modal parts.

## Accessibility

`DModal` and `DOffcanvas` are announced as modal dialogs. Their accessible name comes from the title in the header, or from `ariaLabel` when there is no visible title. Focus moves into the dialog when it opens, and elements that cannot receive focus are left out of the focus cycle.

---

## Confirmations: useConfirmModal

For a yes/no confirmation, `useConfirmModal` opens a ready-made dialog without writing a portal component:

```tsx
const { open } = useConfirmModal({
  title: t('entities.delete.title'),
  message: t('entities.delete.message'),
  confirmLabel: t('common.delete'),
  cancelLabel: t('common.cancel'),
  confirmColor: 'danger',
  onConfirm: () => deleteEntity(id),
});
```

It renders into the node of a `DConfirmModalContainer`, which must be mounted inside `DContextProvider` (as described in the `DContextProvider` catalog entry). Check the full config with `widgets-get-component-props` (`useConfirmModal`).

---

## Common mistakes

| Wrong | Right |
|-------|-------|
| `<DModal open={isOpen} onClose={…}>` | Register the modal and call `openPortal('name', payload)`; close with `closePortal()` |
| `<DOffcanvas placement="end">` | `openFrom="end"` |
| `openPortal('name')` without a payload | `openPortal('name', payload)` |
| Query hooks inside the modal | Pass the action in the payload from a component inside the `QueryProvider` |
| Registering every modal "just in case" | Register only the portals the widget opens |
| A dialog without a title or `ariaLabel` | Give it a visible title or `ariaLabel` |
