@wiltech-labs/ngx-modals

A right-docked panel modal, built on Angular Material's MatDialog: full viewport height, a third of the screen wide by default, full screen on small screens. Give it any component and it comes back with a typed close reason plus whatever data that component wants to hand over — and if that component has unsaved changes, the panel's close button asks before losing them.

Installation

npm install @wiltech-labs/ngx-modals

Peer dependencies: @angular/core, @angular/common, @angular/cdk, @angular/material, rxjs (all matching the Angular version already in your app). Needs provideAnimationsAsync() (or provideAnimations()) at the app level, same as any other MatDialog use — nothing extra to provide for this package itself, ModalService is root-provided.

Usage

The content component

import { Component, inject, input, signal } from '@angular/core';
import { MatDialogRef } from '@angular/material/dialog';
import { ModalCloseAction, ModalCloseResult, ModalContent } from '@wiltech-labs/ngx-modals';

interface ApprovalData {
  employeeName: string;
}
interface ApprovalResult {
  approved: boolean;
}

@Component({ selector: 'app-holiday-approval' /* ... */ })
export class HolidayApprovalModal implements ModalContent {
  data = input<ApprovalData>();

  private readonly note = signal('');
  private readonly dialogRef = inject(
    MatDialogRef<HolidayApprovalModal, ModalCloseResult<ModalCloseAction, ApprovalResult>>,
  );

  // Reported to the shell's close button — return true while there's something to lose.
  hasUnsavedChanges(): boolean {
    return this.note().length > 0;
  }

  protected approve(): void {
    this.dialogRef.close({ action: ModalCloseAction.Updated, data: { approved: true } });
  }

  protected cancel(): void {
    this.dialogRef.close({ action: ModalCloseAction.Cancelled, data: { approved: false } });
  }
}

A content component is a completely ordinary component — no base class to extend, no special module. data (an input(), or @Input() data?: TData) is how it receives ModalConfig.data; ModalContent.hasUnsavedChanges() is the only optional hook this package looks for, and only if you declare it; injecting MatDialogRef and calling .close(result) is exactly how you'd close it if you'd opened it with MatDialog directly — this package doesn't change that part at all.

Opening it

import { Component, inject } from '@angular/core';
import { ModalCloseAction, ModalCloseResult, ModalService } from '@wiltech-labs/ngx-modals';

@Component({ selector: 'app-team-calendar' /* ... */ })
export class TeamCalendar {
  private readonly modals = inject(ModalService);

  protected approveRequest(employeeName: string): void {
    this.modals
      .open<ModalCloseResult<ModalCloseAction, { approved: boolean }>, ApprovalData>(
        HolidayApprovalModal,
        {
          title: 'Approve holiday request',
          data: { employeeName },
        },
      )
      .afterClosed()
      .subscribe((result) => {
        if (result?.action === ModalCloseAction.Updated && result.data.approved) {
          this.refreshTeamCalendar();
        }
      });
  }
}

The panel docks to the right edge, full height, 33vw wide by default. Pass { side: 'left' } to dock it to the left edge instead. Override the width per-open ({ width: '480px' }) or app-wide via the --ngx-modal-width CSS custom property. Below the CDK's XSmall breakpoint it's always full screen, regardless of the configured width. It can only be closed via its own close button (or the content closing itself) — Escape and a backdrop click are disabled, so the unsaved-changes guard can't be bypassed.

Modeless and minimizable panels

For a panel that sits beside what it describes (an org chart's node details), pass backdrop: false: no dimming, no click-blocking and page scroll kept, so the user can keep working with the page. minimizable: true adds a minimize button that shrinks the panel to a small bar at the bottom of its edge (title, restore, close).

To follow the user's selection without stacking panels, keep the MatDialogRef and swap what it shows with update() (this also restores a minimized panel):

if (this.panel) {
  this.modals.update(this.panel, { title: node.name, data: node });
} else {
  this.panel = this.modals.open(NodeDetail, {
    title: node.name,
    side: 'left',
    backdrop: false,
    minimizable: true,
    data: node,
  });
  this.panel.afterClosed().subscribe(() => (this.panel = null));
}

A different close-reason vocabulary

ModalCloseAction (Dismissed/Cancelled/Done/Created/Updated/Deleted) is a starting point, not a closed list. Both ModalCloseResult and open() are generic — define your own action enum when a modal's outcomes don't fit:

enum ApprovalAction {
  Approved = 'APPROVED',
  Rejected = 'REJECTED',
}

this.modals.open<ModalCloseResult<ApprovalAction, ApprovalResult>>(HolidayApprovalModal, { data });

A standalone confirm prompt

The same Yes/No prompt the unsaved-changes guard uses is available directly, for anything else that wants it (a delete confirmation, say):

this.modals
  .confirm("Delete this provider? This can't be undone.", { confirmLabel: 'Delete' })
  .subscribe((confirmed) => {
    if (confirmed) this.delete();
  });

title adds a heading above the message, tone: 'primary' drops the default danger styling for a consequential-but-safe action, and cancelLabel: null hides Cancel for an acknowledgement-only prompt ("You can't delete this yet").

Content that needs the opener's providers

The panel opens in the CDK overlay, outside the opener's injector tree, so a content component that injects a feature-local store (provided on the opening component, not root) won't find it. Pass the opener's injector along:

private readonly injector = inject(Injector);

this.modals.open(AssignProcedureModal, { title, data, injector: this.injector });

Layout

src/
├── public-api.ts        # barrel — the entire public surface; nothing outside this is exported
└── lib/
    ├── models/             # ModalCloseAction/ModalCloseResult, ModalContent, ModalConfig
    ├── components/
    │   ├── modal-shell/       # internal chrome — not part of the public API
    │   └── confirm-dialog/    # ConfirmDialogComponent
    └── services/modal.service.ts  # ModalService

Status

Not yet published to npm — under development.

Publishing

To publish this package to npm:

cd packages/modals
npm run build
cd dist
npm publish

Ensure version in the source package.json is updated before building, per semver conventions.