@ng-zen/cli 21.1.1 → 21.2.0-next.1

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [21.2.0-next.1](https://github.com/kstepien3/ng-zen/compare/v21.1.1...v21.2.0-next.1) (2026-03-09)
+
+### 🚀 New Features
+
+* **dialog:** add reusable dialog component with service and tests ([#387](https://github.com/kstepien3/ng-zen/issues/387)) ([1cb90f6](https://github.com/kstepien3/ng-zen/commit/1cb90f6c5b89b63a461abe6d45da74869275ff12))
+
+### 📚 Documentation
+
+* **README:** update storybook tag ([#395](https://github.com/kstepien3/ng-zen/issues/395)) ([114dfdc](https://github.com/kstepien3/ng-zen/commit/114dfdc87614345784b264a6bde6be73b5e93aa7))
+
 ## [21.1.1](https://github.com/kstepien3/ng-zen/compare/v21.1.0...v21.1.1) (2026-02-25)
 
 ### 🐛 Bug Fixes

package/README.md

@@ -22,7 +22,7 @@
       <img src="https://img.shields.io/badge/-Repository-181818?style=flat&logo=github&logoColor=white" alt="Repository" />
     </a>
     <a href="https://kstepien3.github.io/ng-zen/">
-      <img src="https://img.shields.io/badge/-Storybook%20Demo-FF4785?style=flat&logo=storybook&logoColor=white" alt="Storybook Demo" />
+      <img src="https://img.shields.io/badge/-Storybook%20Demo-FF4785?style=flat&logo=storybook&logoColor=white" alt="Storybook" />
     </a>
   </p>
 
@@ -39,7 +39,7 @@ Unlike traditional UI libraries that give you `<library-button>` black boxes, @n
 
 ### 🏎️ **Instant Productivity**
 
-- **Production-Ready UI Elements:** Alert, Avatar, Button, Checkbox, Divider, Form Control, Icon, Input, Popover, Radio, Skeleton, Switch, Textarea
+- **Production-Ready UI Elements:** Alert, Avatar, Button, Checkbox, Dialog, Divider, Form Control, Icon, Input, Popover, Radio, Skeleton, Switch, Textarea
 - **Zero Configuration:** Works with Angular 20+ out of the box
 - **Complete Setup:** Each component includes unit tests, Storybook stories, and documentation
 
@@ -146,6 +146,7 @@ export class MyComponent {}
 | **Alert**        | Informational messages           | Customizable styles, dismissible options                                  |
 | **Button**       | Interactive buttons              | Primary/secondary variants, loading states, icons                         |
 | **Checkbox**     | Form checkboxes                  | Indeterminate state, custom styling, validation                           |
+| **Dialog**       | Native modal dialogs             | Native dialog element, service API, size variants, backdrop config        |
 | **Divider**      | Visual separators                | Horizontal/vertical, with labels, custom thickness                        |
 | **Form Control** | Form field wrapper               | Labels, validation messages, required indicators                          |
 | **Icon**         | SVG icon system                  | Huge Icons integration, size variants, colors                             |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ng-zen/cli",
-  "version": "21.1.1",
+  "version": "21.2.0-next.1",
   "description": "Angular UI components generator – Zen UI Kit CLI for schematics-based creation of customizable components like avatar, button, checkbox, divider, form-control, icon, input, skeleton, switch, textarea with Storybook demos.",
   "license": "BSD-2-Clause",
   "private": false,
@@ -49,6 +49,7 @@
     "avatar",
     "button",
     "checkbox",
+    "dialog",
     "divider",
     "form-control",
     "icon",

package/schematics/ui/files/dialog/dialog.scss

@@ -0,0 +1,144 @@
+$transition-duration: var(--zen-transition-duration, 0.3s);
+$content-max-height-offset: 100px;
+$sizes: (
+  sm: 300px,
+  md: 500px,
+  lg: 800px,
+  xl: 1100px,
+);
+
+:host {
+  --zen-dialog-padding: 1rem;
+  --zen-dialog-bg: white;
+  --zen-dialog-border-radius: 8px;
+  --zen-dialog-shadow: 0 4px 24px rgb(0 0 0 / 20%);
+  --zen-dialog-max-height: 90vh;
+  --zen-dialog-max-width: 90vw;
+  --zen-dialog-header-gap: 1rem;
+  --zen-dialog-header-padding-bottom: 0.75rem;
+  --zen-dialog-close-btn-size: 2rem;
+  --zen-dialog-close-btn-color: hsl(0deg 0% 40%);
+  --zen-dialog-close-btn-hover-color: hsl(0deg 0% 20%);
+  --zen-dialog-backdrop-bg: rgb(0 0 0 / 50%);
+}
+
+/* stylelint-disable-next-line no-duplicate-selectors -- separate variables and styles */
+:host {
+  padding: var(--zen-dialog-padding);
+  background: var(--zen-dialog-bg);
+  border: none;
+  border-radius: var(--zen-dialog-border-radius);
+  box-shadow: var(--zen-dialog-shadow);
+  max-height: var(--zen-dialog-max-height);
+  max-width: var(--zen-dialog-max-width);
+  overflow: auto;
+  transition:
+    opacity $transition-duration ease,
+    transform $transition-duration ease,
+    overlay $transition-duration allow-discrete,
+    display $transition-duration allow-discrete;
+  opacity: 0;
+  transform: translateY(-10px);
+
+  &[open] {
+    opacity: 1;
+    transform: translateY(0);
+
+    @starting-style {
+      opacity: 0;
+      transform: translateY(-10px);
+    }
+  }
+
+  @each $name, $width in $sizes {
+    &[data-size='#{$name}'] {
+      width: $width;
+    }
+  }
+
+  &[data-size='full'] {
+    width: 100%;
+    height: 100%;
+    max-width: 100%;
+    max-height: 100%;
+    border-radius: 0;
+    transform: none;
+
+    &[open] {
+      @starting-style {
+        transform: none;
+      }
+    }
+  }
+
+  &::backdrop {
+    background: var(--zen-dialog-backdrop-bg);
+    transition:
+      opacity $transition-duration ease,
+      overlay $transition-duration allow-discrete,
+      display $transition-duration allow-discrete;
+    opacity: 0;
+  }
+
+  &[open]::backdrop {
+    opacity: 1;
+
+    @starting-style {
+      opacity: 0;
+    }
+  }
+}
+
+.zen-dialog-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--zen-dialog-header-gap);
+  padding-bottom: var(--zen-dialog-header-padding-bottom);
+  margin-bottom: var(--zen-dialog-padding);
+  border-bottom: 1px solid hsl(0deg 0% 90%);
+
+  h2 {
+    margin: 0;
+    font-size: 1.125rem;
+    font-weight: 600;
+    line-height: 1.4;
+  }
+}
+
+.zen-dialog-close {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--zen-dialog-close-btn-size);
+  height: var(--zen-dialog-close-btn-size);
+  padding: 0;
+  background: transparent;
+  border: none;
+  border-radius: 4px;
+  color: var(--zen-dialog-close-btn-color);
+  cursor: pointer;
+  transition:
+    background-color $transition-duration ease,
+    color $transition-duration ease;
+
+  &:hover {
+    color: var(--zen-dialog-close-btn-hover-color);
+    background-color: hsl(0deg 0% 96%);
+  }
+
+  &:focus-visible {
+    outline: 2px solid hsl(200deg 100% 50% / 50%);
+    outline-offset: 2px;
+  }
+
+  zen-icon {
+    display: flex;
+    line-height: 0;
+  }
+}
+
+.zen-dialog-content {
+  overflow: auto;
+  max-height: calc(var(--zen-dialog-max-height) - #{$content-max-height-offset});
+}

package/schematics/ui/files/dialog/dialog.service.stories.ts

@@ -0,0 +1,174 @@
+import { Component, inject, input, output } from '@angular/core';
+import { Meta, moduleMetadata, StoryObj } from '@storybook/angular';
+
+import { ZenButton } from '../button';
+import { ZenDialog } from './dialog';
+import { DIALOG_REF, DialogConfig, ZenDialogService } from './dialog.service';
+
+type Story = StoryObj<ZenDialogService>;
+
+const component = `
+
+ZenDialogService stories demonstrate dynamic dialog usage via service.
+
+### Usage
+
+\`\`\`typescript
+// Dialog content component
+@Component({
+  template: \`
+    <p>{{ message() }}</p>
+    <button (click)="confirm.emit()">Confirm</button>
+  \`
+})
+class MyDialogContent {
+  readonly message = input<string>();
+  readonly confirm = output<void>();
+}
+
+// Open dialog
+@Component({
+  template: \`<button (click)="open()">Open</button>\`,
+   providers: [ZenDialogService],
+})
+export class OpenComponent {
+  private readonly dialogService = inject(ZenDialogService);
+
+  open(): void {
+    const ref = this.dialogService.open(MyDialogContent, {
+      header: 'My Dialog',
+      size: 'md',
+      inputs: { message: 'Hello!' },
+      outputs: { confirm: () => ref.close() },
+    });
+  }
+}
+\`\`\`
+
+### DIALOG_REF
+
+Close dialog from within the content component:
+
+\`\`\`typescript
+@Component({...})
+class MyDialogContent {
+  private readonly dialogRef = inject(DIALOG_REF);
+
+  close() {
+    this.dialogRef.close();
+  }
+}
+\`\`\`
+
+See [GitHub](https://github.com/kstepien3/ng-zen), [MDN Dialog Element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog)
+`;
+
+@Component({
+  template: `
+    <p>{{ message() }}</p>
+    <div style="display: flex; gap: 0.5rem; margin-top: 1rem;">
+      <button (click)="confirmClick.emit('confirmed!')" zen-btn>Confirm</button>
+      <button (click)="cancel()" zen-btn>Cancel</button>
+    </div>
+  `,
+  standalone: true,
+  imports: [ZenButton],
+})
+class DemoDialogContent {
+  readonly message = input.required<string>();
+  readonly confirmClick = output<string>();
+  readonly cancelClick = output<void>();
+  readonly dialogRef = inject(DIALOG_REF);
+
+  cancel(): void {
+    this.cancelClick.emit();
+    this.dialogRef.close();
+  }
+}
+
+@Component({
+  // eslint-disable-next-line @angular-eslint/component-selector
+  selector: 'app-service-demo',
+  template: `
+    <button (click)="openDialog()" zen-btn>Open via Service</button>
+  `,
+  standalone: true,
+  imports: [ZenButton],
+  providers: [ZenDialogService],
+})
+class ServiceDemoComponent {
+  readonly args = input<DialogConfig<DemoDialogContent>>();
+
+  private readonly dialogService = inject(ZenDialogService);
+
+  openDialog(): void {
+    const ref = this.dialogService.open(DemoDialogContent, {
+      ...this.args(),
+      inputs: { message: 'This dialog was opened via service!' },
+      outputs: {
+        confirmClick: (value: string) => {
+          alert(`Confirmed: ${value}`);
+          ref.close();
+        },
+        cancelClick: () => {
+          console.info('Actually canceled via DIALOG_REF');
+        },
+      },
+    });
+  }
+}
+
+const meta = {
+  title: 'UI/Dialog/Dynamic',
+  component: ZenDialog,
+  tags: [],
+  parameters: {
+    docs: {
+      description: {
+        component,
+      },
+      canvas: {
+        sourceState: 'none',
+      },
+    },
+  },
+  decorators: [
+    moduleMetadata({
+      imports: [ServiceDemoComponent],
+      providers: [ZenDialogService],
+    }),
+  ],
+  argTypes: {
+    size: {
+      name: 'size',
+      control: 'select',
+      options: ['sm', 'md', 'lg', 'xl', 'full'],
+      table: {
+        category: 'inputs',
+        type: { summary: 'string' },
+        defaultValue: { summary: 'md' },
+      },
+    },
+    header: { control: 'text', table: { category: 'inputs' } },
+    closable: { control: 'boolean', table: { category: 'inputs', defaultValue: { summary: 'true' } } },
+    backdrop: { control: 'boolean', table: { category: 'inputs', defaultValue: { summary: 'true' } } },
+    closeOnEscape: { control: 'boolean', table: { category: 'inputs', defaultValue: { summary: 'true' } } },
+    open: { control: 'boolean', table: { disable: true } },
+  },
+  args: {
+    size: 'md',
+    header: 'Dialog Title',
+    closable: true,
+    backdrop: true,
+    closeOnEscape: true,
+  },
+} satisfies Meta<ZenDialog>;
+
+export default meta;
+
+export const Default: Story = {
+  render: args => ({
+    props: { args },
+    template: `<app-service-demo [args]="args" />`,
+  }),
+};

package/schematics/ui/files/dialog/dialog.service.ts

@@ -0,0 +1,211 @@
+import {
+  ApplicationRef,
+  ComponentRef,
+  createComponent,
+  DestroyRef,
+  EnvironmentInjector,
+  inject,
+  Injectable,
+  InjectionToken,
+  Injector,
+  OutputRef,
+  Type,
+  ViewContainerRef,
+} from '@angular/core';
+
+import { ZenDialog } from './dialog';
+
+type SignalValue<T> = T extends (...args: []) => infer V ? V : never;
+
+type ComponentInputs<T> = Partial<{
+  [K in keyof T as T[K] extends OutputRef<unknown> ? never : K]: SignalValue<T[K]>;
+}>;
+
+type ExtractOutputValue<T> = T extends OutputRef<infer V> ? V : never;
+
+type ComponentOutputs<T> = Partial<{
+  [K in keyof T as T[K] extends OutputRef<unknown> ? K : never]: (value: ExtractOutputValue<T[K]>) => void;
+}>;
+
+type ZenDialogInputs = Partial<ComponentInputs<Omit<ZenDialog, 'open'>>>;
+
+/**
+ * Configuration options for opening a dialog via `ZenDialogService.open()`.
+ *
+ * @typeParam T - The dynamic component type that will be rendered inside the dialog.
+ *
+ * @example
+ * ```typescript
+ * interface MyComponent {
+ *   readonly message: InputSignal<string>;
+ *   readonly confirm: OutputRef<string>;
+ * }
+ *
+ * const config: DialogConfig<MyComponent> = {
+ *   header: 'Confirm Action',
+ *   size: 'md',
+ *   inputs: { message: 'Are you sure?' },
+ *   outputs: {
+ *     confirm: (value) => console.log(value),
+ *   },
+ * };
+ * ```
+ */
+
+interface DialogConfig<T, TInputs = ComponentInputs<T>, TOutputs = ComponentOutputs<T>> extends ZenDialogInputs {
+  /** Input values for the dynamic component. */
+  inputs?: TInputs;
+
+  /** Output handlers for the dynamic component's outputs. */
+  outputs?: TOutputs;
+}
+
+/** Reference to an opened dialog. Provides `close()` and `componentInstance`. */
+class DialogRef<T> {
+  public componentInstance!: T;
+
+  constructor(private readonly closeFn: () => void) {}
+
+  close(): void {
+    this.closeFn();
+  }
+}
+
+/** Injection token to access DialogRef from within the dynamic component. */
+const DIALOG_REF = new InjectionToken<DialogRef<unknown>>('DIALOG_REF');
+
+/**
+ * ZenDialogService provides methods to dynamically open dialogs with custom components.
+ *
+ * @example
+ * ```typescript
+ * const ref = this.dialogService.open(MyComponent, {
+ *   header: 'My Dialog',
+ *   size: 'md',
+ *   inputs: { message: 'Hello!' },
+ *   outputs: { confirm: () => ref.close() },
+ * });
+ * ```
+ *
+ * @author Konrad Stępień
+ * @license {@link https://github.com/kstepien3/ng-zen/blob/master/LICENSE|BSD-2-Clause}
+ * @see [GitHub](https://github.com/kstepien3/ng-zen)
+ * @see [MDN Dialog Element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog)
+ */
+@Injectable()
+class ZenDialogService {
+  private readonly appRef = inject(ApplicationRef);
+  private readonly injector = inject(EnvironmentInjector);
+
+  private dialogRef: ComponentRef<ZenDialog> | null = null;
+  private contentRef: ComponentRef<unknown> | null = null;
+
+  private readonly destroyRef = inject(DestroyRef);
+
+  constructor() {
+    this.destroyRef.onDestroy(() => this.closeInternal());
+  }
+
+  /**
+   * Opens a dialog with the specified component as content.
+   *
+   * @example
+   * ```typescript
+   * const ref = this.dialog.open(MyComponent, {
+   *   header: 'My Dialog',
+   *   size: 'md',
+   *   inputs: { message: 'Hello!' },
+   *   outputs: { confirm: () => ref.close() },
+   * });
+   * ```
+   */
+  open<T>(component: Type<T>, config?: DialogConfig<T>): DialogRef<T> {
+    if (this.dialogRef) {
+      this.closeInternal();
+    }
+
+    this.dialogRef = createComponent(ZenDialog, {
+      environmentInjector: this.injector,
+    });
+
+    this.dialogRef.instance.open.set(true);
+
+    const { inputs, outputs, ...inputMappings } = config || {};
+
+    for (const [key, value] of Object.entries(inputMappings)) {
+      if (value !== undefined) {
+        this.dialogRef.setInput(key, value);
+      }
+    }
+
+    this.appRef.attachView(this.dialogRef.hostView);
+
+    const dialogElement = this.dialogRef.location.nativeElement as HTMLDialogElement;
+    document.body.appendChild(dialogElement);
+
+    const dialogRefInstance = new DialogRef<T>(() => this.closeInternal());
+
+    const elementInjector = Injector.create({
+      parent: this.dialogRef.injector,
+      providers: [{ provide: DIALOG_REF, useValue: dialogRefInstance }],
+    });
+
+    this.contentRef = this.dialogRef.injector.get(ViewContainerRef).createComponent(component, {
+      environmentInjector: this.injector,
+      injector: elementInjector,
+    });
+
+    dialogRefInstance.componentInstance = this.contentRef.instance as T;
+
+    const contentElement = this.contentRef.location.nativeElement;
+    const contentContainer = dialogElement.querySelector('.zen-dialog-content');
+    contentContainer?.appendChild(contentElement);
+
+    if (inputs) {
+      for (const [key, value] of Object.entries(inputs)) {
+        this.contentRef.setInput(key, value);
+      }
+    }
+
+    if (outputs) {
+      const destroyRef = this.contentRef.injector.get(DestroyRef);
+
+      for (const [key, handler] of Object.entries(outputs as Record<string, (value: unknown) => void>)) {
+        const output = (this.contentRef.instance as Record<string, unknown>)[key];
+        if (this.isOutputRef(output)) {
+          const subscription = output.subscribe(handler);
+
+          destroyRef.onDestroy(() => subscription.unsubscribe());
+        }
+      }
+    }
+
+    dialogElement.addEventListener('close', () => this.closeInternal(), { once: true });
+
+    return dialogRefInstance;
+  }
+
+  private isOutputRef(value: unknown): value is OutputRef<unknown> {
+    return value !== null && typeof value === 'object' && 'subscribe' in value;
+  }
+
+  private closeInternal(): void {
+    if (!this.dialogRef) return;
+
+    const dialogElement = this.dialogRef.location.nativeElement as HTMLDialogElement;
+    if (dialogElement.open) {
+      dialogElement.close();
+    }
+
+    this.contentRef?.destroy();
+    this.contentRef = null;
+
+    dialogElement.remove();
+
+    this.dialogRef.destroy();
+    this.dialogRef = null;
+  }
+}
+
+export { DIALOG_REF, ZenDialogService };
+export type { DialogConfig, DialogRef };

package/schematics/ui/files/dialog/dialog.spec.ts

@@ -0,0 +1,249 @@
+import { Component, input, output, provideZonelessChangeDetection, signal } from '@angular/core';
+import { ComponentFixture, TestBed } from '@angular/core/testing';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { ZenDialog } from './dialog';
+import { ZenDialogService } from './dialog.service';
+
+@Component({
+  template: `
+    <dialog
+      [backdrop]="backdrop()"
+      [closeOnEscape]="closeOnEscape()"
+      [header]="header()"
+      [id]="id()"
+      [size]="size()"
+      [(open)]="isOpen"
+      zen-dialog
+    >
+      <p>Dialog content</p>
+    </dialog>
+  `,
+  standalone: true,
+  imports: [ZenDialog],
+})
+class DialogTestComponent {
+  readonly isOpen = signal(false);
+  readonly header = signal('Test Dialog');
+  readonly size = signal<'sm' | 'md' | 'lg' | 'xl' | 'full'>('md');
+  readonly id = signal('test-dialog');
+  readonly backdrop = signal(true);
+  readonly closeOnEscape = signal(true);
+}
+
+@Component({
+  template: `
+    <p>{{ message() }}</p>
+    <button (click)="onConfirm()">Confirm</button>
+    <button (click)="onCancel()">Cancel</button>
+  `,
+  standalone: true,
+})
+class TestDialogContent {
+  readonly message = input.required<string>();
+  readonly confirmClick = output<string>();
+  readonly cancelClick = output<void>();
+
+  onConfirm(): void {
+    this.confirmClick.emit('confirmed');
+  }
+
+  onCancel(): void {
+    this.cancelClick.emit();
+  }
+}
+
+function getDialogEl(fixture: ComponentFixture<unknown>): HTMLDialogElement | null {
+  return fixture.nativeElement.querySelector('dialog[zen-dialog]') as HTMLDialogElement | null;
+}
+
+function getDialogElFromBody(): HTMLDialogElement | null {
+  return document.body.querySelector('dialog[zen-dialog]') as HTMLDialogElement | null;
+}
+
+describe('ZenDialog', () => {
+  beforeEach(async () => {
+    HTMLDialogElement.prototype.showModal = vi.fn();
+    HTMLDialogElement.prototype.close = vi.fn();
+  });
+
+  describe('Component usage', () => {
+    beforeEach(async () => {
+      await TestBed.configureTestingModule({
+        imports: [DialogTestComponent],
+        providers: [provideZonelessChangeDetection()],
+      }).compileComponents();
+    });
+
+    it('should create', () => {
+      const fixture = TestBed.createComponent(DialogTestComponent);
+      fixture.detectChanges();
+      expect(getDialogEl(fixture)).toBeTruthy();
+    });
+
+    it('should call showModal when open is set to true', async () => {
+      const fixture = TestBed.createComponent(DialogTestComponent);
+      fixture.detectChanges();
+
+      const dialogEl = getDialogEl(fixture)!;
+      expect(dialogEl.showModal).not.toHaveBeenCalled();
+
+      fixture.componentInstance.isOpen.set(true);
+      fixture.detectChanges();
+      await fixture.whenStable();
+
+      expect(dialogEl.showModal).toHaveBeenCalledTimes(1);
+    });
+
+    it('should call close when open is set to false', async () => {
+      const fixture = TestBed.createComponent(DialogTestComponent);
+      fixture.componentInstance.isOpen.set(true);
+      fixture.detectChanges();
+      await fixture.whenStable();
+
+      const dialogEl = getDialogEl(fixture)!;
+      Object.defineProperty(dialogEl, 'open', { value: true, writable: true });
+
+      fixture.componentInstance.isOpen.set(false);
+      fixture.detectChanges();
+      await fixture.whenStable();
+
+      expect(dialogEl.close).toHaveBeenCalled();
+    });
+
+    it('should render header when provided', () => {
+      const fixture = TestBed.createComponent(DialogTestComponent);
+      fixture.detectChanges();
+
+      const header = fixture.nativeElement.querySelector('.zen-dialog-header h2');
+      expect(header?.textContent).toBe('Test Dialog');
+    });
+
+    it('should apply size attribute', () => {
+      const fixture = TestBed.createComponent(DialogTestComponent);
+      fixture.componentInstance.size.set('lg');
+      fixture.detectChanges();
+
+      const dialogEl = getDialogEl(fixture)!;
+      expect(dialogEl.getAttribute('data-size')).toBe('lg');
+    });
+
+    it('should close when close button is clicked', async () => {
+      const fixture = TestBed.createComponent(DialogTestComponent);
+      fixture.componentInstance.isOpen.set(true);
+      fixture.detectChanges();
+      await fixture.whenStable();
+
+      const closeBtn = fixture.nativeElement.querySelector('.zen-dialog-close') as HTMLButtonElement;
+      closeBtn?.click();
+      fixture.detectChanges();
+
+      expect(fixture.componentInstance.isOpen()).toBe(false);
+    });
+
+    it('should not close when backdrop is clicked and backdrop is false', async () => {
+      const fixture = TestBed.createComponent(DialogTestComponent);
+      fixture.componentInstance.isOpen.set(true);
+      fixture.componentInstance.backdrop.set(false);
+      fixture.detectChanges();
+      await fixture.whenStable();
+
+      const dialogEl = getDialogEl(fixture)!;
+      Object.defineProperty(dialogEl, 'tagName', { value: 'DIALOG' });
+      dialogEl.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+      fixture.detectChanges();
+
+      expect(fixture.componentInstance.isOpen()).toBe(true);
+    });
+
+    it('should not close on escape when closeOnEscape is false', async () => {
+      const fixture = TestBed.createComponent(DialogTestComponent);
+      fixture.componentInstance.isOpen.set(true);
+      fixture.componentInstance.closeOnEscape.set(false);
+      fixture.detectChanges();
+      await fixture.whenStable();
+
+      const dialogEl = getDialogEl(fixture)!;
+      const cancelEvent = new Event('cancel', { bubbles: true, cancelable: true });
+      dialogEl.dispatchEvent(cancelEvent);
+      fixture.detectChanges();
+
+      expect(fixture.componentInstance.isOpen()).toBe(true);
+    });
+
+    it('should apply id to dialog element', () => {
+      const fixture = TestBed.createComponent(DialogTestComponent);
+      fixture.componentInstance.id.set('custom-dialog-id');
+      fixture.detectChanges();
+
+      const dialogEl = getDialogEl(fixture)!;
+      expect(dialogEl.id).toBe('custom-dialog-id');
+    });
+  });
+});
+
+describe('ZenDialogService', () => {
+  beforeEach(async () => {
+    HTMLDialogElement.prototype.showModal = vi.fn();
+    HTMLDialogElement.prototype.close = vi.fn();
+
+    await TestBed.configureTestingModule({
+      providers: [provideZonelessChangeDetection(), ZenDialogService],
+    }).compileComponents();
+  });
+
+  afterEach(() => {
+    const dialogEl = getDialogElFromBody();
+    if (dialogEl) {
+      dialogEl.remove();
+    }
+  });
+
+  it('should open dialog with component', () => {
+    const service = TestBed.inject(ZenDialogService);
+
+    const ref = service.open(TestDialogContent, { header: 'Service Dialog' });
+
+    expect(ref).toBeDefined();
+    expect(ref.componentInstance).toBeInstanceOf(TestDialogContent);
+  });
+
+  it('should pass inputs to component', () => {
+    const service = TestBed.inject(ZenDialogService);
+
+    const ref = service.open(TestDialogContent, {
+      inputs: { message: 'Hello from service' } as Record<string, unknown>,
+    });
+
+    expect(ref.componentInstance.message()).toBe('Hello from service');
+  });
+
+  it('should subscribe to outputs', () => {
+    const service = TestBed.inject(ZenDialogService);
+    const confirmHandler = vi.fn();
+    const cancelHandler = vi.fn();
+
+    service.open(TestDialogContent, {
+      outputs: {
+        confirmClick: confirmHandler,
+        cancelClick: cancelHandler,
+      },
+    });
+
+    const confirmBtn = document.body.querySelector('button') as HTMLButtonElement;
+    confirmBtn?.click();
+
+    expect(confirmHandler).toHaveBeenCalledWith('confirmed');
+  });
+
+  it('should close dialog via DialogRef', async () => {
+    const service = TestBed.inject(ZenDialogService);
+
+    const ref = service.open(TestDialogContent);
+
+    ref.close();
+
+    const dialogEl = getDialogElFromBody();
+    expect(dialogEl).toBeNull();
+  });
+});

package/schematics/ui/files/dialog/dialog.stories.ts

@@ -0,0 +1,105 @@
+import { signal } from '@angular/core';
+import { argsToTemplate, Meta, moduleMetadata, StoryObj } from '@storybook/angular';
+
+import { ZenButton } from '../button';
+import { ZenDialog } from './dialog';
+
+type DialogSize = 'sm' | 'md' | 'lg' | 'xl' | 'full';
+
+type Story = StoryObj<ZenDialog>;
+
+const meta = {
+  title: 'UI/Dialog/Dialog',
+  component: ZenDialog,
+  tags: ['autodocs'],
+  decorators: [
+    moduleMetadata({
+      imports: [ZenButton, ZenDialog],
+    }),
+  ],
+  argTypes: {
+    size: {
+      name: 'size',
+      control: 'select',
+      options: ['sm', 'md', 'lg', 'xl', 'full'] satisfies DialogSize[],
+      table: {
+        category: 'inputs',
+        type: { summary: 'string' },
+        defaultValue: { summary: 'md' satisfies DialogSize },
+      },
+    },
+    header: { control: 'text', table: { category: 'inputs' } },
+    closable: { control: 'boolean', table: { category: 'inputs', defaultValue: { summary: 'true' } } },
+    backdrop: { control: 'boolean', table: { category: 'inputs', defaultValue: { summary: 'true' } } },
+    closeOnEscape: { control: 'boolean', table: { category: 'inputs', defaultValue: { summary: 'true' } } },
+    open: { control: 'boolean', table: { readonly: false, category: 'models' } },
+  },
+  args: {
+    size: 'md',
+    header: 'Dialog Title',
+    closable: true,
+    backdrop: true,
+    closeOnEscape: true,
+    open: false,
+  },
+} satisfies Meta<ZenDialog>;
+
+export default meta;
+
+export const Default: Story = {
+  render: ({ open, ...args }) => {
+    const mutatedArgs = { ...args, open: signal(open) };
+    return {
+      props: { ...mutatedArgs },
+      template: `
+      <button zen-btn (click)="open.set(true)">Open Dialog</button>
+
+      <dialog zen-dialog [(open)]="open" ${argsToTemplate(args)}>
+        <p>This is the dialog content. You can put any content here.</p>
+        <button zen-btn (click)="open.set(false)">Close</button>
+      </dialog>
+    `,
+    };
+  },
+};
+
+export const Sizes: Story = {
+  render: () => ({
+    props: {
+      openSm: signal(false),
+      openMd: signal(false),
+      openLg: signal(false),
+      openXl: signal(false),
+      openFull: signal(false),
+    },
+    template: `
+      <div style="display: flex; gap: 0.5rem; flex-wrap: wrap;">
+        <button zen-btn (click)="openSm.set(true)">Small</button>
+        <button zen-btn (click)="openMd.set(true)">Medium</button>
+        <button zen-btn (click)="openLg.set(true)">Large</button>
+        <button zen-btn (click)="openXl.set(true)">Extra Large</button>
+        <button zen-btn (click)="openFull.set(true)">Full Screen</button>
+      </div>
+
+      <dialog zen-dialog [(open)]="openSm" header="Small Dialog" size="sm">
+        <p>Small dialog content</p>
+      </dialog>
+
+      <dialog zen-dialog [(open)]="openMd" header="Medium Dialog" size="md">
+        <p>Medium dialog content</p>
+      </dialog>
+
+      <dialog zen-dialog [(open)]="openLg" header="Large Dialog" size="lg">
+        <p>Large dialog content with more space for complex layouts.</p>
+      </dialog>
+
+      <dialog zen-dialog [(open)]="openXl" header="Extra Large Dialog" size="xl">
+        <p>Extra large dialog content for data tables, forms, etc.</p>
+      </dialog>
+
+      <dialog zen-dialog [(open)]="openFull" header="Full Screen Dialog" size="full">
+        <p>Full screen dialog content</p>
+      </dialog>
+    `,
+  }),
+};

package/schematics/ui/files/dialog/dialog.ts

@@ -0,0 +1,143 @@
+import { ChangeDetectionStrategy, Component, effect, ElementRef, inject, input, model, untracked } from '@angular/core';
+import { Cancel01Icon } from '@hugeicons/core-free-icons';
+
+import { ZenIcon } from '../icon';
+
+type DialogSize = 'sm' | 'md' | 'lg' | 'xl' | 'full';
+
+/**
+ * ZenDialog is a reusable dialog component built on the native HTML `<dialog>` element.
+ * It provides a modal dialog with customizable header, size, and content.
+ *
+ * @example
+ * ```html
+ * <dialog zen-dialog [(open)]="isOpen" header="Dialog Title" size="md">
+ *   <p>Dialog content</p>
+ * </dialog>
+ * ```
+ *
+ * ### CSS Custom Properties
+ *
+ * You can customize the component using CSS custom properties:
+ * ```css
+ * :root {
+ *   --zen-dialog-padding: 1rem;
+ *   --zen-dialog-bg: white;
+ *   --zen-dialog-border-radius: 8px;
+ *   --zen-dialog-shadow: 0 4px 24px rgb(0 0 0 / 20%);
+ *   --zen-dialog-max-height: 90vh;
+ *   --zen-dialog-max-width: 90vw;
+ *   --zen-dialog-backdrop-bg: rgba(0, 0, 0, 0.5);
+ * }
+ * ```
+ *
+ * @author Konrad Stępień
+ * @license {@link https://github.com/kstepien3/ng-zen/blob/master/LICENSE|BSD-2-Clause}
+ * @see [GitHub](https://github.com/kstepien3/ng-zen)
+ * @see [MDN Dialog Element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog)
+ */
+@Component({
+  // eslint-disable-next-line @angular-eslint/component-selector
+  selector: 'dialog[zen-dialog]',
+  template: `
+    @if (header()) {
+      <header class="zen-dialog-header">
+        <h2>{{ header() }}</h2>
+        @if (closable()) {
+          <button (click)="onClose()" aria-label="Close dialog" class="zen-dialog-close" type="button">
+            <zen-icon [icon]="closeIcon" [size]="20" />
+          </button>
+        }
+      </header>
+    }
+    <div class="zen-dialog-content">
+      <ng-content />
+    </div>
+  `,
+  styleUrl: './dialog.scss',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [ZenIcon],
+  host: {
+    '[attr.aria-label]': 'header()',
+    '[attr.data-size]': 'size()',
+    '(close)': 'onClose()',
+    '(cancel)': 'onCancel($event)',
+    '(click)': 'onDialogClick($event)',
+  },
+})
+export class ZenDialog {
+  /**
+   * Controls the open state of the dialog.
+   * Supports two-way binding via `[(open)]` syntax.
+   * When set to `true`, calls `showModal()` on the native dialog element.
+   * When set to `false`, calls `close()` on the native dialog element.
+   */
+  readonly open = model<boolean>(false);
+
+  /**
+   * Header title displayed at the top of the dialog.
+   * Also used as the `aria-label` for accessibility.
+   */
+  readonly header = input<string>('');
+
+  /**
+   * Size variant of the dialog.
+   * Affects the width of the dialog via the `data-size` attribute.
+   */
+  readonly size = input<DialogSize>('md');
+
+  /**
+   * Whether to show the close button (X) in the header.
+   */
+  readonly closable = input(true);
+
+  /**
+   * Whether clicking the backdrop closes the dialog.
+   * This is a native dialog feature.
+   */
+  readonly backdrop = input(true);
+
+  /**
+   * Whether pressing the Escape key closes the dialog.
+   * This is a native dialog feature.
+   */
+  readonly closeOnEscape = input(true);
+
+  protected readonly closeIcon = Cancel01Icon;
+
+  private readonly elementRef = inject(ElementRef<HTMLDialogElement>);
+
+  constructor() {
+    effect(() => {
+      const isOpen = this.open();
+      const element = this.elementRef.nativeElement;
+
+      untracked(() => {
+        if (isOpen) {
+          element.showModal();
+        } else if (element.open) {
+          element.close();
+        }
+      });
+    });
+  }
+
+  /** Close on backdrop click */
+  protected onDialogClick(event: MouseEvent): void {
+    if (!this.backdrop()) return;
+
+    if ((event.target as HTMLElement).tagName === 'DIALOG') {
+      this.onClose();
+    }
+  }
+
+  protected onCancel(event: Event): void {
+    if (!this.closeOnEscape()) {
+      event.preventDefault();
+    }
+  }
+
+  protected onClose(): void {
+    this.open.set(false);
+  }
+}

package/schematics/ui/files/dialog/index.ts

@@ -0,0 +1,3 @@
+export { ZenDialog } from './dialog';
+export type { DialogConfig, DialogRef } from './dialog.service';
+export { DIALOG_REF, ZenDialogService } from './dialog.service';

package/schematics/ui/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../../../src/schematics/ui/schema.ts"],"names":[],"mappings":"","sourcesContent":["import { GeneratorSchemaBase } from '../../types';\n\nexport type UiType =\n  | 'alert'\n  | 'avatar'\n  | 'button'\n  | 'checkbox'\n  | 'divider'\n  | 'form-control'\n  | 'icon'\n  | 'input'\n  | 'popover'\n  | 'radio'\n  | 'skeleton'\n  | 'switch'\n  | 'textarea';\n\nexport interface Schema extends GeneratorSchemaBase {\n  ui: UiType[];\n}\n"]}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../../../src/schematics/ui/schema.ts"],"names":[],"mappings":"","sourcesContent":["import { GeneratorSchemaBase } from '../../types';\n\nexport type UiType =\n  | 'alert'\n  | 'avatar'\n  | 'button'\n  | 'checkbox'\n  | 'dialog'\n  | 'divider'\n  | 'form-control'\n  | 'icon'\n  | 'input'\n  | 'popover'\n  | 'radio'\n  | 'skeleton'\n  | 'switch'\n  | 'textarea';\n\nexport interface Schema extends GeneratorSchemaBase {\n  ui: UiType[];\n}\n"]}

package/schematics/ui/schema.json

@@ -41,6 +41,7 @@
           "avatar",
           "button",
           "checkbox",
+          "dialog",
           "divider",
           "form-control",
           "icon",

package/schematics/ui/schema.ts

@@ -5,6 +5,7 @@ export type UiType =
   | 'avatar'
   | 'button'
   | 'checkbox'
+  | 'dialog'
   | 'divider'
   | 'form-control'
   | 'icon'