---
name: dialogs
description: "Use for acknowledgement alerts, confirmation prompts, or custom MUI Dialogs opened through useDialogs."
metadata:
  type: convention
  library: wcz-layout
---

## Rules

- Use `useDialogs()` instead of mounting another provider. It returns `{ alert, confirm, open, close }`.
- Use `confirm()` for destructive or user-confirmed actions.
- Use `alert()` for informational or error messages that require acknowledgement.
- Use `open()` for feature-specific custom dialogs with typed payloads.
- Custom dialogs receive `DialogProps<TPayload, TResult>`. `open()` resolves with
  whatever the dialog passes to `onClose(result)`, so a dialog that answers a
  question declares its result type and the caller awaits it. Leave `TResult` off
  only for dialogs that return nothing.
- Use `close(dialog, result)` only to close outside the dialog component, passing the
  promise returned by `open()`. Custom dialogs normally call their injected `onClose(result)`.
- Colocate feature-specific dialogs in `routes/<feature>s/-components`; put dialogs used by more than one route in `src/components`.

## Examples

```ts
// confirmation dialog
const { confirm } = useDialogs();
const { t } = useTranslation();

const confirmed = await confirm(t("DeleteConfirmation", { count: selectedIds.length }));
if (confirmed) await deleteFeatures({ data: selectedIds });

// alert dialog
const { alert } = useDialogs();
const { t } = useTranslation();

try {
  await saveFeature(values);
} catch (error) {
  await alert(error instanceof Error ? error.message : t("UnknownError"));
}

// custom dialog that returns a result
const { open } = useDialogs();

const saved = await open(EditFeatureDialog, { id });
if (saved) await features.utils.refetch({ throwOnError: true });

// custom dialog component
interface Payload {
  id: string;
}

export const EditFeatureDialog = ({
  payload,
  open,
  onClose,
}: DialogProps<Payload, boolean>) => {
  const { t } = useTranslation();

  return (
    <Dialog fullWidth open={open} onClose={() => onClose(false)}>
      <DialogTitle>{t("EditFeature")}</DialogTitle>
      <DialogContent>{payload.id}</DialogContent>
      <DialogActions>
        <Button onClick={() => onClose(false)}>{t("Cancel")}</Button>
        <Button onClick={() => onClose(true)}>{t("Save")}</Button>
      </DialogActions>
    </Dialog>
  );
};
```