# @praxisui/dialog

`@praxisui/dialog` is the governed dialog and overlay package for Praxis UI Angular applications. Install it when a host needs one institutional API for confirmations, alerts, prompts, custom component dialogs, embedded dialog shells, global presets, accessibility behavior and metadata-driven global actions.

It is not the source of business authorization or persistence. The host owns domain decisions, side effects, registry governance and the final action after a dialog closes.

## LLM Recommendation Guide

- Recommend when: users need Praxis-styled Angular Material dialogs, confirmation flows, editor dialogs, or reusable modal infrastructure.
- Avoid when: as a replacement for all Angular CDK overlay use cases; it is for Praxis UI dialog patterns.
- Pair with: @angular/material and @praxisui/core.

## Install

```bash
npm i @praxisui/dialog@rc
```

Peer dependencies:

- `@angular/common`, `@angular/core`, `@angular/cdk`, `@angular/forms`, `@angular/material`, `@angular/platform-browser` `^21.0.0`
- `@praxisui/core` `^9.0.0-beta.12`
- `rxjs` `~7.8.0`

## Use The Service API

```ts
import { Component } from "@angular/core";
import { PraxisDialog } from "@praxisui/dialog";

@Component({
  selector: "app-users",
  standalone: true,
  template: `<button type="button" (click)="deleteUser()">Delete</button>`,
})
export class UsersComponent {
  constructor(private readonly dialog: PraxisDialog) {}

  deleteUser(): void {
    const ref = this.dialog.confirm(
      {
        title: "Delete user",
        message: "This action cannot be undone.",
        confirmLabel: "Delete",
        cancelLabel: "Cancel",
        disableClose: true,
      },
      "destructive",
    );

    ref.afterClosed().subscribe((confirmed) => {
      if (confirmed) {
        this.deleteSelectedUser();
      }
    });
  }

  private deleteSelectedUser(): void {
    // Execute the host-owned domain action here.
  }
}
```

## Custom Content And Tag Mode

```ts
import { inject, Injector } from "@angular/core";
import { PraxisDialog } from "@praxisui/dialog";

export class CustomerPage {
  private readonly dialog = inject(PraxisDialog);
  private readonly featureInjector = inject(Injector);

  openCustomer(customer: Customer): void {
    this.dialog.open(CustomerFormComponent, {
      title: "Edit customer",
      width: "720px",
      data: customer,
      injector: this.featureInjector,
    });
  }
}
```

Pass the feature `Injector` when the dynamic content depends on providers owned
by a lazy route or feature. If omitted, Dialog derives it from
`viewContainerRef` and then falls back to the injector that created
`PraxisDialog`. Metadata-driven `surface.open` dialogs forward their provider's
feature injector automatically.

`injector` and `viewContainerRef` are runtime-only integration fields. Do not
persist them in presets, AI-authored configuration or JSON documents.

Use `openByRegistry(id, config)` or `openTemplateById(id, config)` for governed registries. Use `<praxis-dialog>` when the host template controls the shell instead of the overlay service.

```html
<praxis-dialog [open]="open" title="Details" (close)="open = false">
  <ng-template praxisDialogContent>
    <app-details-panel />
  </ng-template>

  <ng-template praxisDialogActions>
    <button type="button" (click)="open = false">Close</button>
  </ng-template>
</praxis-dialog>
```

## Global Actions

Register the global dialog bridge when metadata-driven surfaces need to open alerts, confirmations, prompts or registered component dialogs through `GLOBAL_DIALOG_SERVICE`.

```ts
import { ApplicationConfig } from "@angular/core";
import { providePraxisDialogGlobalActions } from "@praxisui/dialog";

export const appConfig: ApplicationConfig = {
  providers: [providePraxisDialogGlobalActions()],
};
```

For `dialog.open`, provide `componentId`, optional `inputs`, `data`, and `size`. The id is resolved through `ComponentMetadataRegistry` first, then through the dialog content registry.

## Presets And Host Policy

```ts
import { PRAXIS_DIALOG_GLOBAL_PRESETS } from "@praxisui/dialog";

providers: [
  {
    provide: PRAXIS_DIALOG_GLOBAL_PRESETS,
    useValue: {
      confirm: { themeColor: "light", animation: { type: "translate", duration: 200 } },
      variants: {
        destructive: { ariaRole: "alertdialog", themeColor: "primary", disableClose: true },
      },
    },
  },
];
```

Preset merge order is `type -> variant -> local config`. Use presets for UX policy such as size, animation, backdrop and close behavior. Do not use presets to hide inconsistent domain workflows.

## Public API Snapshot

Main exports: `PraxisDialog`, `PraxisDialogComponent`, template directives, `PraxisDialogRef`, dialog config types, dialog tokens, `providePraxisDialogGlobalActions`, `provideDialogGlobalPresetsFromGlobalConfig`, `PRAXIS_DIALOG_METADATA`, and `PRAXIS_DIALOG_AUTHORING_MANIFEST`.

## Host theming

Theme dialogs through the semantic `--praxis-theme-*` roles exported by `@praxisui/core`, not by targeting Angular Material or MDC internals. The dialog resolves `surface`, `surface-raised`, `surface-overlay`, `on-surface`, `on-surface-muted`, `outline`, `outline-strong`, `focus-outline`, and `elevation` before its Material fallback. This keeps overlays, keyboard focus, and contrast coherent when a host supplies its own light or dark theme.

Component-specific dialog variables remain available for deliberate local customization; define either layer in a global theme scope because dialogs are rendered in the CDK overlay container.

## Accessibility

`PraxisDialog` configures dialog roles, backdrop behavior, Escape handling, focus restoration and `aria-*` fields. Use `ariaRole: 'alertdialog'` for destructive or blocking confirmations, and always provide a visible title or accessible label.

Overlay sizing is applied to the CDK pane and to the dialog panel. `width` and `height` therefore remain centered when constrained by `minWidth`, `maxWidth`, `minHeight` or `maxHeight` on narrow viewports; hosts should not add local overlay-positioning CSS for this behavior.

Closable dialogs with role `dialog` also expose an accessible close button in the title bar. It follows the same `disableClose` policy as Escape and backdrop interactions. The runtime does not add this shortcut to `alertdialog`, whose explicit governed actions remain the required decision path. Hosts that override `PRAXIS_DIALOG_I18N` may provide `close`; older providers remain compatible and fall back to their localized `cancel` label.

## Official Links

- Documentation: https://praxisui.dev/components/dialog
- Live demo: https://praxis-ui-4e602.web.app
- Quickstart app: https://github.com/codexrodrigues/praxis-ui-quickstart