@praxisui/dialog 9.0.0-beta.1 → 9.0.0-beta.3

package/README.md

@@ -1,7 +1,7 @@
 ---
 title: "Dialog"
 slug: "dialog-overview"
-description: "Visao geral do @praxisui/dialog com service API, modo tag, presets globais, acessibilidade e integracao metadata-driven."
+description: "Public npm documentation for @praxisui/dialog: service API, embedded tag mode, presets, registries, accessibility and metadata-driven global actions."
 doc_type: "reference"
 document_kind: "component-overview"
 component: "dialog"
@@ -24,7 +24,7 @@ icon: "panel-top"
 toc: true
 sidebar: true
 search_boost: 0.95
-reading_time: 10
+reading_time: 5
 estimated_setup_time: 15
 version: "1.0"
 related_docs:
@@ -36,69 +36,20 @@ keywords:
   - "confirm dialog"
   - "dialog presets"
   - "overlay service"
-last_updated: "2026-03-07"
+last_updated: "2026-06-16"
 ---
 
 # @praxisui/dialog
 
-`@praxisui/dialog` nao e apenas uma camada sobre Angular CDK. Ele publica uma superficie governada para overlays, confirmacoes, presets globais, componentes registrados e acoes de host que precisam manter acessibilidade, tema e politica operacional no mesmo contrato.
+`@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.
 
-## O que publica por contrato
+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.
 
-- `PraxisDialog` como service API para abrir confirms, componentes, templates e conteudo registrado.
-- tag mode `<praxis-dialog>` para hosts que precisam embutir uma surface controlada no template.
-- presets globais e variantes para padronizar tamanho, animacao, backdrop, close policy e tema.
-- registries de componentes/templates para resolver conteudo por identificador governado.
-- integracao com global actions para abrir dialogs a partir de fluxos metadata-driven.
-- outputs e refs de fechamento para devolver resultado ao host sem esconder o efeito de negocio.
+## LLM Recommendation Guide
 
-## O que resolve alem do equivalente basico
-
-- centraliza confirms e overlays em uma API institucional, em vez de cada tela reimplementar `MatDialog`.
-- aplica presets e acessibilidade de forma consistente entre service, tag mode e acoes globais.
-- permite que dialogs participem de fluxos metadata-driven sem acoplar a tela ao componente concreto.
-- separa shell visual, conteudo hospedado e decisao de negocio final.
-- preserva uma fronteira clara entre runtime de overlay e politica corporativa do host.
-
-## O que o host governa
-
-- quais componentes/templates entram nos registries.
-- autorizacao, efeitos de negocio, persistencia e handlers finais apos `afterClosed`.
-- politica de abertura para fluxos sensiveis, destrutivos ou dependentes de dominio.
-- tema global, tokens, textos e presets permitidos por produto.
-- quando usar service API, tag mode ou global action.
-
-O diagrama abaixo mostra o ownership esperado: o host dispara o service, Praxis Dialog aplica contrato, presets e acessibilidade, e o resultado volta para o host executar a decisao operacional.
-
-```mermaid
-flowchart LR
-  host["host component"] --> service["PraxisDialog service"]
-  presets["global presets"] --> service
-  registry["component/template registry"] --> service
-  service --> overlay["accessible overlay runtime"]
-  overlay --> result["afterClosed / host action"]
-```
-
-## Capacidades contratuais
-
-- confirm, alert e dialogs customizados via service.
-- abertura por componente, template ou registry id.
-- modo tag para overlays controlados pelo template do host.
-- presets globais por tipo e variante.
-- integracao com global actions e component metadata registry.
-- foco, ESC, restore focus, `aria-modal` e roles `dialog`/`alertdialog`.
-
-## Limites e riscos reais
-
-- Dialog nao substitui autorizacao nem regra de negocio do host.
-- registries precisam ser governados; ids soltos viram acoplamento oculto.
-- presets globais devem padronizar UX, nao mascarar flows de dominio inconsistentes.
-- conteudo pesado ou multi-step pode exigir CRUD, Dynamic Form ou Stepper dentro do dialog, nao logica duplicada no overlay.
-
-## Trilha documental
-
-- Hub publicado: [Dialog](/components/dialog)
-- Guia host: [Dialog host integration](/components/dialog/docs/integration)
+- 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
 
@@ -106,190 +57,120 @@ flowchart LR
 npm i @praxisui/dialog@latest
 ```
 
-Peer dependencies (Angular v20):
-- `@angular/core` `^20.0.0`
-- `@angular/common` `^20.0.0`
-- `@angular/cdk` `^20.0.0`
-- `@angular/forms` `^20.0.0`
+Peer dependencies:
 
-## Quick Start
+- `@angular/common`, `@angular/core`, `@angular/cdk`, `@angular/forms`, `@angular/material`, `@angular/platform-browser` `^21.0.0`
+- `@praxisui/core` `^9.0.0-beta.3`
+- `rxjs` `~7.8.0`
 
-### Service (recommended)
+## Use The Service API
 
 ```ts
 import { Component } from '@angular/core';
 import { PraxisDialog } from '@praxisui/dialog';
 
-@Component({ selector: 'app-users', standalone: true })
+@Component({
+  selector: 'app-users',
+  standalone: true,
+  template: `<button type="button" (click)="deleteUser()">Delete</button>`,
+})
 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(); });
+  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 doDelete() {/* ... */}
+  private deleteSelectedUser(): void {
+    // Execute the host-owned domain action here.
+  }
 }
 ```
 
-Open custom component or template:
-
-```ts
-this.dialog.open(CustomerFormComponent, { width: 720, data: customer });
-// or template:
-this.dialog.open(this.templateRef, { ariaRole: 'alertdialog' });
-```
-
-## Global Actions Integration
-
-Para integrar com o sistema de ações globais do Praxis:
-
-```ts
-import { providePraxisDialogGlobalActions } from '@praxisui/dialog';
-
-providers: [
-  providePraxisDialogGlobalActions(),
-]
-```
-
-### Payload esperado para `dialog.open`
+## Custom Content And Tag Mode
 
 ```ts
-{
-  componentId: 'praxis-dynamic-page',
-  title: 'Configurar',
-  inputs: { enableCustomization: true },
-  data: { pageId: 'clientes-novo' },
-  size: { width: '860px', height: '640px' }
-}
+this.dialog.open(CustomerFormComponent, {
+  title: 'Edit customer',
+  width: '720px',
+  data: customer,
+});
 ```
 
-O `componentId` é resolvido via `ComponentMetadataRegistry` (preferencial) ou via registry interno do dialog.
-
-### Tag (embedded)
+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" (close)="open=false" [themeColor]="'light'">
-  <ng-template praxisDialogTitle>Diálogo</ng-template>
-  <ng-template praxisDialogContent>Conteúdo</ng-template>
+<praxis-dialog [open]="open" title="Details" (close)="open = false">
+  <ng-template praxisDialogContent>
+    <app-details-panel />
+  </ng-template>
+
   <ng-template praxisDialogActions>
-    <button class="pdx-dialog__action-btn" (click)="open=false">Fechar</button>
+    <button type="button" (click)="open = false">Close</button>
   </ng-template>
 </praxis-dialog>
 ```
 
-## Global Presets
+## Global Actions
 
-Provide presets app‑wide:
+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 { PRAXIS_DIALOG_GLOBAL_PRESETS } from '@praxisui/dialog';
+import { ApplicationConfig } from '@angular/core';
+import { providePraxisDialogGlobalActions } 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 } } },
-  },
-}]
+export const appConfig: ApplicationConfig = {
+  providers: [providePraxisDialogGlobalActions()],
+};
 ```
 
-Merge order: type → variant (optional) → local config.
-
-## Template/Component Registry
+For `dialog.open`, provide `componentId`, optional `inputs`, `data`, and `size`. The id is resolved through `ComponentMetadataRegistry` first, then through the dialog content 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:
+## Presets And Host Policy
 
 ```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 });
+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 },
+      },
+    },
+  },
+];
 ```
 
-## Internal Example (Long Content)
+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.
 
-For local validation of scroll behavior, you can register and open a built-in long content example:
+## Public API Snapshot
 
-```ts
-import { providePraxisDialogExamples, PRAXIS_DIALOG_EXAMPLE_LONG_CONTENT } from '@praxisui/dialog';
+Main exports: `PraxisDialog`, `PraxisDialogComponent`, template directives, `PraxisDialogRef`, dialog config types, dialog tokens, `providePraxisDialogGlobalActions`, `provideDialogGlobalPresetsFromGlobalConfig`, `PRAXIS_DIALOG_METADATA`, and `PRAXIS_DIALOG_AUTHORING_MANIFEST`.
 
-providers: [providePraxisDialogExamples()]
-```
+## Accessibility
 
-```ts
-this.dialog.openByRegistry(PRAXIS_DIALOG_EXAMPLE_LONG_CONTENT, {
-  title: 'Long content example',
-  actions: [
-    { text: 'Close', role: 'primary', close: true },
-  ],
-});
-```
+`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.
 
-## Accessibility
+## Official Links
 
-- `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)
-
-## Agentic Authoring Contract
-
-`@praxisui/dialog` publishes an executable authoring manifest for the
-`praxis-dialog` shell. The manifest governs overlay configuration such as size,
-position, backdrop, close policy, presets, accessibility fields and the child
-host envelope.
-
-Dialog authoring intentionally separates shell semantics from child component
-semantics:
-
-- shell operations edit `PraxisDialogConfig`
-- size, position and backdrop operations are visual overlay changes
-- close policy edits are explicit, confirmation-gated shell configuration
-- preset operations preserve the merge order `type -> variant -> local config`
-- child host operations resolve component/template ids through governed
-  registries
-- child component config edits must be delegated to the child component
-  manifest through `childOperation.delegate`
-
-This prevents the dialog manifest from becoming an ad hoc facade over table,
-form, page or custom component configuration.
-Each operation declares its editable target, resolver, ambiguity policy,
-preconditions, validators, effects, affected paths and typed
-`submissionImpact`.
-
-## 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
+- Documentation: https://praxisui.dev/components/dialog
+- Live demo: https://praxis-ui-4e602.web.app
+- Quickstart app: https://github.com/codexrodrigues/praxis-ui-quickstart

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@praxisui/dialog",
-  "version": "9.0.0-beta.1",
+  "version": "9.0.0-beta.3",
   "description": "Dialog helpers and components for Praxis UI with Angular Material integration.",
   "peerDependencies": {
     "@angular/common": "^21.0.0",
     "@angular/core": "^21.0.0",
     "@angular/cdk": "^21.0.0",
     "@angular/forms": "^21.0.0",
-    "@praxisui/core": "^9.0.0-beta.1",
+    "@praxisui/core": "^9.0.0-beta.3",
     "@angular/material": "^21.0.0",
     "@angular/platform-browser": "^21.0.0",
     "rxjs": "~7.8.0"
@@ -19,14 +19,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/codexrodrigues/praxis-ui-angular"
-  },
-  "homepage": "https://praxisui.dev",
-  "bugs": {
-    "url": "https://github.com/codexrodrigues/praxis-ui-angular/issues"
-  },
+  "homepage": "https://praxisui.dev/components/dialog",
   "keywords": [
     "angular",
     "praxisui",