GUILD OF GLEKS UIv21.19.0

gog-dialog

Dialog

A service-driven modal outlet — mount <gog-dialog /> once and open any component as its body through DialogService. Supports stacking, dragging, a built-in focus trap, and a ready-made confirmation dialog.

Overview

Import DialogComponent and mount <gog-dialog /> once, near the root of the app. Every DialogService.open() renders through that one outlet. Both come from @guildofgleks/ui/dialog, with the confirmation dialog and the dialog tokens — a dialog opened only behind a lazy route keeps its own code out of the initial bundle. What it imports from the root package (the button, icon and scroll area it renders) loads wherever the root package already does.

typescript
import { DialogComponent, DialogService } from '@guildofgleks/ui/dialog';

@Component({
  // ...
  imports: [DialogComponent],
})
export class AppComponent {
  // Mount <gog-dialog /> once, near the root of your app.
}

Basic usage — the library's ConfirmationDialogComponent for a confirm/cancel prompt. It shows the question as its own heading, so the dialog is named by that heading: ariaLabelledBy on the config and titleId in its data 21.15.0 are the same id. afterClosed resolves with true, false, or undefined when dismissed.

afterClosed: none yet

<gog-button severity="danger" (gogClick)="confirm()">Delete workspace</gog-button>

<p>afterClosed: {{ result() }}</p>

Examples

Modal, closable, draggable, role, title

modal, closable and draggable are all on by default. Off, modal drops the dimmed backdrop, the focus trap and the body scroll lock, and a press on the page reaches the page and leaves the dialog open 21.15.0; closable removes the close button, Escape and the backdrop press, leaving the content's own buttons; draggable keeps the header but stops it moving. Without a title the header holds only the close button — and the dialog has no name, which dev mode warns about.

last afterClosed: none yet

@for (row of rows; track row.name) {
  <gog-button variant="outline" size="sm" (gogClick)="open(row)">{{ row.name }}</gog-button>
}

<p>last afterClosed: {{ result() }}</p>

Your own component

Any component can be the body: it reads DIALOG_DATA and closes itself through DIALOG_REF, and what it closes with resolves afterClosed — Save with an object, Cancel and the close button with undefined. The select needs appendToBody: the dialog's body is a scroller, and a list rendered inside it is clipped under the header. Escape closes the open list first and the dialog only on the next press 21.15.0; a control of your own can claim the key the same way, with preventDefault().

afterClosed: none yet

<gog-button variant="outline" (gogClick)="rename()">Rename report</gog-button>

<p>afterClosed: {{ result() }}</p>

<!-- rename-dialog.html -->
<div style="display: grid; gap: 16px">
  <gog-inputfield label="Name" [(value)]="name" />
  <!-- appendToBody: the dialog body scrolls, and a list inside it would be clipped. -->
  <gog-select label="Folder" [options]="folders" appendToBody [(value)]="folder" />
  <div style="display: flex; justify-content: flex-end; gap: 12px">
    <gog-button variant="ghost" (gogClick)="ref.close()">Cancel</gog-button>
    <gog-button (gogClick)="save()">Save</gog-button>
  </div>
</div>

width and maxWidth

Both are CSS lengths written onto the panel; maxWidth wins when the two disagree. Unset, the panel is as wide as its content, up to 90vw.

@for (row of rows; track row.name) {
  <gog-button variant="outline" size="sm" (gogClick)="open(row)">{{ row.name }}</gog-button>
}

Long content

The body scrolls inside the panel, capped by --gog-dialog-body-max-height, and the header — with the close button and the drag handle — stays put.

<gog-button variant="outline" (gogClick)="open()">Release notes</gog-button>

<!-- long-dialog.html -->
@for (paragraph of paragraphs; track paragraph) {
  <p>{{ paragraph }}. The body scrolls inside the panel; the header stays where it is.</p>
}
<gog-button (gogClick)="ref.close()">Done</gog-button>

closeIconName and closeIconTemplate

Only the look of the close button changes: it keeps its name, its focus ring and Escape.

<gog-button variant="outline" (gogClick)="open('name')">closeIconName</gog-button>
<gog-button variant="outline" (gogClick)="open('template')">closeIconTemplate</gog-button>
<ng-template #closeGlyph><gog-icon name="minus" /></ng-template>

Stacking, and closeAll

Open one, then another from inside it — the body injects DialogService like any other consumer. Each opens above the last; Escape closes only the top one, and closing the last returns focus to what had it before the first opened. Close all resolves every open dialog's afterClosed with the value it is given.

afterClosed: none yet

<gog-button variant="outline" (gogClick)="open()">Open a stack</gog-button>

<p>afterClosed: {{ result() }}</p>

<!-- stack-dialog.html -->
<p>Dialog {{ data.depth }}. Each new one opens above the last; Escape closes only the top one.</p>
<div style="display: flex; justify-content: flex-end; gap: 12px">
  <!-- closeAll resolves every open dialog's afterClosed with the value it is given. -->
  <gog-button variant="ghost" (gogClick)="dialogs.closeAll('closeAll')">Close all</gog-button>
  <gog-button (gogClick)="openAnother()">Open another</gog-button>
</div>

Accessibility

The panel is role="dialog" (or alertdialog), aria-modal while modal, and named by its title through aria-labelledby.

  • Name — every dialog needs a title or an ariaLabelledBy; dev mode warns about one with neither. When the content carries its own heading, point ariaLabelledBy at it instead of repeating it as a title — for ConfirmationDialogComponent, pass the same id as data.titleId.
  • Keyboard — the top dialog takes focus; Tab and Shift+Tab cycle inside a modal one, a non-modal one lets focus leave. Escape closes the top dialog, after anything inside that claimed it. Closing the last one returns focus to what had it before the first opened.
  • Dismissing — Escape, the close button, and a press that both starts and ends on the backdrop; a drag that starts in the panel and is released outside does not close. All three resolve afterClosed with undefined.
  • Close button — named by closeAriaLabel, or GOG_CONFIG.labels.closeDialog app-wide.
  • Overlays inside — a tooltip or a dropdown opened from a dialog stacks above it: the panel raises --gog-tooltip-z and --gog-dropdown-z.

API Reference

DialogConfig

NameTypeDefaultDescription
componentType<unknown>requiredThe component rendered as the dialog body.
titlestringundefinedHeader title, and the dialog's accessible name unless ariaLabelledBy is set. The header renders if either title or closable is set. A dialog with neither title nor ariaLabelledBy is unnamed, and dev mode warns.
ariaLabelledBy21.15.0stringundefinedId of a heading inside the body component that names the dialog; wins over title. Use it when the content shows its own heading, rather than repeating it as a title above — ConfirmationDialogComponent renders its heading with data.titleId for exactly this.
dataunknownundefinedPassed to the body component via the DIALOG_DATA injection token.
modalbooleantrueDims the page, locks body scroll, traps Tab focus inside the panel, and restores focus to the trigger on close. false leaves the page usable: a press on it reaches the page and leaves the dialog open (since 21.15.0), which then closes by its own buttons, the close button or Escape.
closablebooleantrueShows the header close button and enables Escape/backdrop-click to close.
draggablebooleantrueLets the header be dragged to reposition the panel. Only takes effect when a header renders.
closeIconNameGogIconName'close'Icon for the header close button.
closeIconTemplateTemplateRef<unknown> | nullnullReplaces the close button icon entirely.
widthstring'auto'CSS width of the panel.
maxWidthstring'90vw'CSS max-width of the panel.
role'dialog' | 'alertdialog''dialog'ARIA role for the panel. Use 'alertdialog' for confirmation-style prompts.
zIndexnumberauto-incrementing from 1000Backdrop z-index. Dropdowns rendered inside the dialog use zIndex + 10.

DialogService methods

SignatureDescription
open<TResult>(config: DialogConfig): DialogHandle<TResult>Opens a dialog. Returns a handle with close(result?) and an afterClosed promise that resolves once the dialog closes, with whatever value close() was called with.
closeAll(result?: unknown): voidCloses every open dialog, resolving each afterClosed with the same result.

Injection tokens

SignatureDescription
DIALOG_DATA: InjectionToken<unknown>Inject inside the body component to read the data passed to open().
DIALOG_REF: InjectionToken<DialogRef<unknown>>Inject inside the body component to call close(result?) and dismiss the dialog from within.

ConfirmationDialogComponent

A ready-made body for confirm/cancel prompts — pass it as component with a ConfirmDialogData as data: { title, titleId?, description, confirmText, cancelText }. It closes itself with true on confirm and false on cancel.

Global Configuration

Set any of these once with provideGogConfig() instead of repeating them on every instance — an instance's own input still wins when it sets one itself. See Global Configuration for the full reference.

  • GOG_CONFIG.labels.closeDialog

Styling Tokens

Every CSS custom property the dialog paints with. Override any of them — on a single instance, a subtree, or a theme — to restyle it. See the Theming guide for the full token-layering model, or the Theme Generator to tweak these live.

TokenDescription
--gog-dialog-backdrop-bg / -backdrop-blurScrim behind the dialog.
--gog-dialog-bg / -color / -border / -radius / -shadowPanel surface.
--gog-dialog-title-font-size / -title-line-heightThe dialog’s <h2>. New tokens in 21.11.0 and the value is the size it was already rendering — the title had simply been inheriting from the browser rather than reading the type scale, so it was outside a theme’s reach.
--gog-dialog-header-padding / -body-paddingSection padding.
--gog-dialog-close-color / -close-hover-color / -close-hover-bgClose button.
--gog-confirmation-dialog-color / -description-color / -actions-gapConfirmation dialog variant.
--gog-confirmation-dialog-title-font-size / -description-font-size (and their line heights)The title and the description, on the type scale since 21.11.0 rather than inherited. The description is the one that visibly moved: 16px to 14px, a step smaller than it was.
--gog-confirmation-dialog-max-widthThe panel’s cap, in ch since 21.11.0 so raising the font size widens the panel with it. It resolves against .confirm-dialog’s own inherited size, not the description’s — a ch cap always reads the font of the element carrying max-width, never a descendant’s.