@praxisui/dialog/README.md

Dialog helpers and components for Praxis UI with Angular Material integration.

# @praxisui/dialog

> Unified dialog for Praxis built on Angular CDK. Provides a service API (MatDialog-like) and a tag mode (`<praxis-dialog>`) with theming, CSS-only animations, accessibility and metadata integration.

## 🔰 Exemplos / Quickstart

Para ver esta biblioteca em funcionamento em uma aplicação completa, utilize o projeto de exemplo (Quickstart):

- Repositório: https://github.com/codexrodrigues/praxis-ui-quickstart
- O Quickstart demonstra a integração das bibliotecas `@praxisui/*` em um app Angular, incluindo instalação, configuração e uso em telas reais.

## Install

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

Peer dependencies (Angular v20):
- `@angular/core` `^20.0.0`
- `@angular/common` `^20.0.0`
- `@angular/cdk` `^20.0.0`
- `@angular/forms` `^20.0.0`

## Quick Start

### Service (recommended)

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

@Component({ selector: 'app-users', standalone: true })
export class UsersComponent {
  constructor(private dialog: PraxisDialog) {}

  deleteUser() {
    const ref = this.dialog.confirm({
      title: 'Confirmar Exclusão',
      message: 'Deseja excluir este item?',
      disableClose: true,
    }, 'question'); // variant: question

    ref.afterClosed().subscribe((ok) => { if (ok) this.doDelete(); });
  }

  private doDelete() {/* ... */}
}
```

Open custom component or template:

```ts
this.dialog.open(CustomerFormComponent, { width: 720, data: customer });
// or template:
this.dialog.open(this.templateRef, { ariaRole: 'alertdialog' });
```

### Tag (embedded)

```html
<praxis-dialog [open]="open" (close)="open=false" [themeColor]="'light'">
  <ng-template praxisDialogTitle>Diálogo</ng-template>
  <ng-template praxisDialogContent>Conteúdo</ng-template>
  <ng-template praxisDialogActions>
    <button class="pdx-dialog__action-btn" (click)="open=false">Fechar</button>
  </ng-template>
</praxis-dialog>
```

## Global Presets

Provide presets app‑wide:

```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: { question: { themeColor: 'dark', animation: { type: 'fade', duration: 150 } } },
  },
}]
```

Merge order: type → variant (optional) → local config.

## Template/Component Registry

- Component registry: `PRAXIS_DIALOG_CONTENT_REGISTRY` (string → ComponentType)
- Template registry: `PRAXIS_DIALOG_TEMPLATE_REGISTRY` (string → TemplateRef)

Register via `ENVIRONMENT_INITIALIZER` and open by id:

```ts
providers: [{
  provide: ENVIRONMENT_INITIALIZER,
  multi: true,
  useFactory: (reg: Record<string, any>) => () => reg['CustomerForm'] = CustomerFormComponent,
  deps: [PRAXIS_DIALOG_CONTENT_REGISTRY],
}]

this.dialog.openByRegistry('CustomerForm', { width: 720 });
```

## Accessibility

- `role="dialog|alertdialog"`, `aria-modal`, `aria-*` inputs
- Focus trap + ESC (respects `disableClose`)
- In `alertdialog`, focuses the primary action when present
- Restores focus on close (service and tag)

## Theming & Styles

- `themeColor: 'light' | 'dark' | 'primary'`
- Style tokens via `styles` map to CSS vars (e.g. `containerShape`, `contentPadding`, `typography` fields)
- Size props (`width/height/min/max`) are top‑level inputs

## API (quick reference)

Exports:
- Service: `PraxisDialog`
- Component + directives: `PraxisDialogComponent`, `PraxisDialogTitleDirective`, `PraxisDialogContentDirective`, `PraxisDialogActionsDirective`
- Ref: `PraxisDialogRef`
- Tokens: `PRAXIS_DIALOG_DATA`, `PRAXIS_DIALOG_DEFAULTS`, `PRAXIS_DIALOG_GLOBAL_PRESETS`, `PRAXIS_DIALOG_I18N`, registries
- Types: `PraxisDialogConfig`, `PraxisConfirmConfig`, `PraxisAlertConfig`, `PraxisPromptConfig`

Highlights:
- `afterAllClosed`, `afterOpened`, `openDialogs`, `closeAll()`, `getDialogById(id)`
- `PraxisDialogRef`: `afterOpened/beforeClosed/afterClosed`, `backdropClick`, `keydownEvents`, `close()`, `updateSize/Position()`

## Links
- Repo: https://github.com/codexrodrigues/praxis
- Issues: https://github.com/codexrodrigues/praxis/issues