@gjsify/adwaita-web 0.15.1 → 0.16.1

package/src/elements/adw-data-grid.ts

@@ -0,0 +1,335 @@
+// <adw-data-grid> — A slim, Adwaita-styled ALIGNED data grid: the web mirror of
+// the native Gtk.Grid an accounting app (Buchhaltung) uses for its financial
+// statements (the BWA / P&L, invoice line-items). It is DELIBERATELY NOT a
+// heavyweight sortable Gtk.ColumnView / TreeView — boxed lists (<adw-action-row>
+// inside <adw-preferences-group>) stay the default for record lists. Reach for
+// this ONLY for genuinely tabular numeric data where columns of figures must
+// line up (labels left, amounts right-aligned with tabular figures), with the
+// accounting row emphasis a statement needs: section headers, subtotals and a
+// bold final total.
+//
+// It is a PLAIN presentational element — it does layout, alignment and emphasis;
+// it never formats or sorts. Cell values are PRE-FORMATTED strings (locale
+// currency formatting stays in the app, e.g. `1.234,50 €`); the grid renders the
+// strings and aligns them. Sorting is a data op driven externally (e.g. an
+// <adw-drop-down>) — there are no clickable-sortable column headers here.
+//
+// Columns (the `columns` property, or a JSON `columns` attribute):
+//   { key, label?, align?, width?, flex?, monospace?, numeric? }
+//     key       — the row-object key this column reads.
+//     label     — header text (defaults to `key`).
+//     align     — 'start' | 'end' | 'center' (default 'start'; a `numeric`
+//                 column defaults to 'end' so figures right-align).
+//     width     — a fixed CSS track size ('80px', '6rem') — pins the column.
+//     flex      — a fractional track weight (→ `<flex>fr`) — grows the column.
+//     monospace — render cells in a monospace family (tabular figures either way).
+//     numeric   — convenience: right-aligns + applies tabular-nums (the point of
+//                 the grid vs a boxed list — numeric columns of figures line up).
+//   With neither width nor flex declared anywhere, the FIRST column absorbs the
+//   slack (so trailing numeric columns hug the right edge) and the rest size to
+//   content — the faithful "label left, amounts right" statement shape.
+//
+// Rows (the `rows` property, or a JSON `rows` attribute) — row objects keyed by
+// column key, PLUS optional accounting metadata:
+//   variant?     — 'normal' | 'section' | 'subtotal' | 'total'
+//     section  — a bold group header spanning all columns (its text = the value
+//                under the FIRST column's key). Nests a BWA into its sections.
+//     subtotal — bold, with a hairline rule above (Gesamtleistung, Rohertrag…).
+//     total    — bold + a stronger rule above (the final result — Betriebsergebnis).
+//     normal   — a plain data row (the default).
+//   interactive? — make just this row clickable (see `row-activated`).
+//
+// Attributes / properties:
+//   caption      — an optional title shown above the grid.
+//   interactive  — element-level flag: every `normal` row becomes clickable
+//                  (a row may opt out with `interactive: false`); mainly for a
+//                  master-detail list. Section/subtotal/total rows never activate.
+// Events:
+//   `row-activated` (CustomEvent, bubbles, detail = { index, row }) — a clickable
+//     row was activated by click or Enter/Space. `index` is the row's index in
+//     the `rows` array; `row` is the original row object.
+// Responsive: the grid scrolls horizontally within its OWN container on narrow
+//   viewports (it never overflows the page); it sits inside an <adw-card>/boxed
+//   surface and follows light + dark via the adwaita-web CSS variables.
+// Reference: Gtk.Grid usage in the Buchhaltung BWA view (native financial grid).
+// Reference: refs/libadwaita/src/stylesheet/_colors.scss (separator / card tokens).
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+/** Horizontal alignment of a column's header + cells. */
+export type AdwDataGridAlign = 'start' | 'end' | 'center';
+
+/** Accounting row emphasis. `normal` is the default plain data row. */
+export type AdwDataGridRowVariant = 'normal' | 'section' | 'subtotal' | 'total';
+
+/** A column descriptor — what to read (`key`), how to label + align it. */
+export interface AdwDataGridColumn {
+    /** The row-object key this column renders. */
+    key: string;
+    /** Header text (defaults to `key`). */
+    label?: string;
+    /** 'start' | 'end' | 'center'. Defaults to 'start' (or 'end' when numeric). */
+    align?: AdwDataGridAlign;
+    /** Fixed CSS track size (e.g. '80px', '6rem') — pins the column width. */
+    width?: string;
+    /** Fractional track weight (→ `<flex>fr`) — lets the column grow. */
+    flex?: number;
+    /** Render cells in a monospace family (tabular figures apply regardless). */
+    monospace?: boolean;
+    /** Convenience: right-align + tabular-nums (numeric columns of figures). */
+    numeric?: boolean;
+}
+
+/** A row: cell values keyed by column key + optional accounting metadata. */
+export interface AdwDataGridRow {
+    /** Accounting emphasis. Default 'normal'. */
+    variant?: AdwDataGridRowVariant;
+    /** Make just this row clickable (overrides the element-level flag). */
+    interactive?: boolean;
+    /** Cell values keyed by column key (pre-formatted strings, or numbers). */
+    [key: string]: string | number | boolean | AdwDataGridRowVariant | undefined;
+}
+
+const VARIANTS: ReadonlySet<string> = new Set(['normal', 'section', 'subtotal', 'total']);
+
+export class AdwDataGrid extends HTMLElement {
+    private _captionEl!: HTMLDivElement;
+    private _scrollEl!: HTMLDivElement;
+    private _tableEl!: HTMLDivElement;
+    private _columns: AdwDataGridColumn[] = [];
+    private _rows: AdwDataGridRow[] = [];
+    private _initialized = false;
+
+    static get observedAttributes() {
+        return ['columns', 'rows', 'caption', 'interactive'];
+    }
+
+    /** The column descriptors. Setting rebuilds the grid. */
+    get columns(): AdwDataGridColumn[] {
+        return this._columns;
+    }
+
+    set columns(value: ReadonlyArray<AdwDataGridColumn>) {
+        this._columns = normalizeColumns(value);
+        if (this._initialized) this._render();
+    }
+
+    /** The row objects. Setting rebuilds the body. */
+    get rows(): AdwDataGridRow[] {
+        return this._rows;
+    }
+
+    set rows(value: ReadonlyArray<AdwDataGridRow>) {
+        this._rows = Array.isArray(value) ? value.map((r) => ({ ...r })) : [];
+        if (this._initialized) this._render();
+    }
+
+    /** The optional grid caption/title (reflected to the attribute). */
+    get caption(): string {
+        return this.getAttribute('caption') ?? '';
+    }
+
+    set caption(value: string) {
+        if (value) this.setAttribute('caption', value);
+        else this.removeAttribute('caption');
+    }
+
+    /** Whether every `normal` row is clickable (element-level flag). */
+    get interactive(): boolean {
+        return this.hasAttribute('interactive');
+    }
+
+    set interactive(value: boolean) {
+        if (value) this.setAttribute('interactive', '');
+        else this.removeAttribute('interactive');
+    }
+
+    connectedCallback() {
+        if (this._initialized) return;
+        this._initialized = true;
+
+        this.classList.add('adw-data-grid');
+
+        this._captionEl = document.createElement('div');
+        this._captionEl.className = 'adw-data-grid-caption';
+        this._captionEl.hidden = true;
+
+        this._scrollEl = document.createElement('div');
+        this._scrollEl.className = 'adw-data-grid-scroll';
+
+        this._tableEl = document.createElement('div');
+        this._tableEl.className = 'adw-data-grid-table';
+        this._tableEl.setAttribute('role', 'table');
+        this._scrollEl.appendChild(this._tableEl);
+
+        // Seed from JSON attributes only when the properties were not set.
+        if (this._columns.length === 0) this._columns = this._parseJsonAttr('columns', normalizeColumns);
+        if (this._rows.length === 0) this._rows = this._parseJsonAttr('rows', (v) => (Array.isArray(v) ? v : []));
+
+        this.replaceChildren(this._captionEl, this._scrollEl);
+        this._render();
+    }
+
+    attributeChangedCallback(name: string, _old: string | null, value: string | null) {
+        if (!this._initialized) return;
+        if (name === 'columns') {
+            this._columns = this._parseJsonAttr('columns', normalizeColumns);
+            this._render();
+        } else if (name === 'rows') {
+            this._rows = this._parseJsonAttr('rows', (v) => (Array.isArray(v) ? (v as AdwDataGridRow[]) : []));
+            this._render();
+        } else if (name === 'caption') {
+            this._renderCaption();
+        } else if (name === 'interactive') {
+            this._render();
+        }
+        void value;
+    }
+
+    // ── internals ──────────────────────────────────────────────────────────
+
+    private _parseJsonAttr<T>(name: string, coerce: (v: unknown) => T): T {
+        const raw = this.getAttribute(name);
+        if (!raw) return coerce(undefined);
+        try {
+            return coerce(JSON.parse(raw) as unknown);
+        } catch {
+            return coerce(undefined);
+        }
+    }
+
+    private _renderCaption(): void {
+        const caption = this.getAttribute('caption') ?? '';
+        this._captionEl.textContent = caption;
+        this._captionEl.hidden = caption.length === 0;
+    }
+
+    /** The CSS `grid-template-columns` value derived from the column descriptors. */
+    private _trackTemplate(): string {
+        const anyExplicit = this._columns.some((c) => c.width !== undefined || c.flex !== undefined);
+        return this._columns
+            .map((column, index) => {
+                if (column.width !== undefined) return column.width;
+                if (column.flex !== undefined) return `${column.flex}fr`;
+                // With no explicit sizing anywhere, the first (label) column
+                // absorbs slack so trailing numeric columns hug the right edge.
+                // `0px` (not `0`) is the CSSOM-canonical form so it round-trips.
+                if (!anyExplicit && index === 0) return 'minmax(0px, 1fr)';
+                return 'auto';
+            })
+            .join(' ');
+    }
+
+    private _columnClasses(column: AdwDataGridColumn): string {
+        const align: AdwDataGridAlign = column.align ?? (column.numeric ? 'end' : 'start');
+        const classes = ['adw-data-grid-cell', `align-${align}`];
+        if (column.numeric) classes.push('numeric');
+        if (column.monospace) classes.push('mono');
+        return classes.join(' ');
+    }
+
+    private _render(): void {
+        if (!this._tableEl) return;
+        this._renderCaption();
+        this._tableEl.style.gridTemplateColumns = this._trackTemplate();
+        this._tableEl.replaceChildren();
+
+        const columnCount = this._columns.length;
+        if (columnCount === 0) return;
+
+        // Header row (dim, small-caps) — column labels, aligned per column.
+        const header = document.createElement('div');
+        header.className = 'adw-data-grid-row header';
+        header.setAttribute('role', 'row');
+        for (const column of this._columns) {
+            const cell = document.createElement('div');
+            cell.className = `${this._columnClasses(column)} header-cell`;
+            cell.setAttribute('role', 'columnheader');
+            cell.textContent = column.label ?? column.key;
+            header.appendChild(cell);
+        }
+        this._tableEl.appendChild(header);
+
+        const elementInteractive = this.hasAttribute('interactive');
+
+        this._rows.forEach((rowData, index) => {
+            const variant = normalizeVariant(rowData.variant);
+            const row = document.createElement('div');
+            row.className = `adw-data-grid-row variant-${variant}`;
+            row.setAttribute('role', 'row');
+
+            if (variant === 'section') {
+                // A section header spans all columns; its text is the first
+                // column's value (the section title).
+                const firstKey = this._columns[0]?.key ?? '';
+                const cell = document.createElement('div');
+                cell.className = 'adw-data-grid-cell align-start section-cell';
+                cell.setAttribute('role', 'cell');
+                cell.style.gridColumn = '1 / -1';
+                cell.textContent = cellText(rowData[firstKey]);
+                row.appendChild(cell);
+            } else {
+                for (const column of this._columns) {
+                    const cell = document.createElement('div');
+                    cell.className = this._columnClasses(column);
+                    cell.setAttribute('role', 'cell');
+                    cell.textContent = cellText(rowData[column.key]);
+                    row.appendChild(cell);
+                }
+            }
+
+            // A row is clickable only when it is a plain data row AND either the
+            // element opts everything in or the row opts itself in.
+            const rowInteractive =
+                variant === 'normal' &&
+                rowData.interactive !== false &&
+                (rowData.interactive === true || elementInteractive);
+            if (rowInteractive) {
+                row.classList.add('interactive');
+                row.tabIndex = 0;
+                row.addEventListener('click', () => this._activate(index, rowData));
+                row.addEventListener('keydown', (event) => {
+                    if (event.key === 'Enter' || event.key === ' ') {
+                        event.preventDefault();
+                        this._activate(index, rowData);
+                    }
+                });
+            }
+
+            this._tableEl.appendChild(row);
+        });
+    }
+
+    private _activate(index: number, row: AdwDataGridRow): void {
+        this.dispatchEvent(new CustomEvent('row-activated', { bubbles: true, detail: { index, row } }));
+    }
+}
+
+/** Coerce a cell value to display text — pre-formatted strings pass through. */
+function cellText(value: string | number | boolean | AdwDataGridRowVariant | undefined): string {
+    if (value === undefined || value === null) return '';
+    return String(value);
+}
+
+/** Clamp an arbitrary variant to the known set (unknown → 'normal'). */
+function normalizeVariant(variant: unknown): AdwDataGridRowVariant {
+    return typeof variant === 'string' && VARIANTS.has(variant) ? (variant as AdwDataGridRowVariant) : 'normal';
+}
+
+/** Normalise raw column descriptors to a stable list (drops malformed entries). */
+function normalizeColumns(raw: unknown): AdwDataGridColumn[] {
+    if (!Array.isArray(raw)) return [];
+    return raw
+        .filter((c): c is AdwDataGridColumn => typeof c === 'object' && c !== null && 'key' in c)
+        .map((c) => ({
+            key: String(c.key),
+            label: c.label !== undefined ? String(c.label) : undefined,
+            align: c.align,
+            width: c.width !== undefined ? String(c.width) : undefined,
+            flex: typeof c.flex === 'number' ? c.flex : undefined,
+            monospace: c.monospace === true,
+            numeric: c.numeric === true,
+        }));
+}
+
+customElements.define('adw-data-grid', AdwDataGrid);

package/src/elements/adw-dialog.ts

@@ -0,0 +1,329 @@
+// <adw-dialog> — A generic adaptive dialog: the web counterpart of Adw.Dialog.
+// It wraps arbitrary content in a floating card centred over a full-cover scrim
+// on wide viewports, and re-anchors it as a bottom sheet (full-width, rounded
+// top corners) on narrow ones — the adaptive presentation Adw.Dialog gets for
+// free from AdwBreakpoint on GTK. There is no Adw.Breakpoint primitive on the
+// web, so the switch is a CSS media query keyed on the `presentation-mode`.
+//
+// Unlike the specialised dialogs (<adw-alert-dialog>, <adw-preferences-dialog>,
+// <adw-about-dialog>) this one imposes no content model of its own: its default
+// slot holds any markup, and it renders an OPTIONAL flat header bar (a title +
+// a trailing close button) only when a `title` is set or `show-header` is used.
+// It is the generic base those specialised dialogs could later be built on.
+//
+// Like Adw.Dialog it starts hidden; `present()` (or the `open` attribute)
+// reveals it and `close()` dismisses it — gated by `can-close` (Escape /
+// scrim-click / close-button raise `close-attempt` instead of closing while
+// locked). Presenting traps focus inside the dialog and returns it to the
+// previously-focused element on close. A disconnected element is attached to
+// `document.body` on present (the Adw.Dialog.present(parent) idiom); a
+// declaratively-authored dialog already in the DOM is simply revealed in place
+// (and stays reusable — close hides, it does not detach).
+//
+// Attributes:
+//   title             (the header title — Adw.Dialog:title; presence renders the header)
+//   open              (boolean — whether the dialog is revealed; default hidden)
+//   can-close         (boolean — user may dismiss; default on. `="false"` locks it
+//                        so a dismissal raises `close-attempt` — Adw.Dialog:can-close)
+//   content-width     (max content width in px — Adw.Dialog:content-width; default 360)
+//   content-height    (max content height in px — Adw.Dialog:content-height; default unset)
+//   presentation-mode (`auto` | `floating` | `bottom-sheet`; default `auto` —
+//                        Adw.Dialog:presentation-mode. `auto` = floating when wide,
+//                        bottom sheet when narrow)
+//   show-header       (boolean — render the header bar even without a title)
+//
+// Properties: open, title, canClose, contentWidth, contentHeight, presentationMode.
+// Methods:    present(), close(), forceClose().
+// Events:
+//   `notify::open`   (CustomEvent, bubbles, detail = { open }) — revealed state changed.
+//   `closed`         (CustomEvent, bubbles) — the dialog finished closing (Adw.Dialog::closed).
+//   `close-attempt`  (CustomEvent, bubbles) — a dismissal was attempted while locked
+//                      (Adw.Dialog::close-attempt).
+//
+// Reference: refs/libadwaita/src/adw-dialog.c (present/close/can-close, Escape, focus)
+// Reference: refs/libadwaita/src/stylesheet/widgets/_dialogs.scss (floating sheet + bottom sheet)
+// Copyright (c) 2023-2024 GNOME Foundation Inc. (libadwaita). LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+/** Adaptive presentation of the dialog — mirrors Adw.DialogPresentationMode. */
+export type AdwDialogPresentationMode = 'auto' | 'floating' | 'bottom-sheet';
+
+const DEFAULT_CONTENT_WIDTH = 360;
+const PRESENTATION_MODES: readonly AdwDialogPresentationMode[] = ['auto', 'floating', 'bottom-sheet'];
+
+// Selector matching the tabbable elements a focus trap must cycle through.
+const FOCUSABLE_SELECTOR = [
+    'a[href]',
+    'button:not([disabled])',
+    'input:not([disabled])',
+    'select:not([disabled])',
+    'textarea:not([disabled])',
+    '[tabindex]:not([tabindex="-1"])',
+].join(',');
+
+export class AdwDialog extends HTMLElement {
+    private _initialized = false;
+    private _scrimEl!: HTMLDivElement;
+    private _boxEl!: HTMLDivElement;
+    private _headerEl!: HTMLDivElement;
+    private _titleEl!: HTMLSpanElement;
+    private _closeBtn!: HTMLButtonElement;
+    private _contentEl!: HTMLDivElement;
+    // The element focused before present(), restored on close (return-focus).
+    private _previouslyFocused: HTMLElement | null = null;
+
+    static get observedAttributes() {
+        return ['title', 'open', 'can-close', 'content-width', 'content-height', 'presentation-mode', 'show-header'];
+    }
+
+    /** Whether the dialog is currently revealed. */
+    get open(): boolean {
+        return this.hasAttribute('open');
+    }
+
+    set open(value: boolean) {
+        if (value) this.setAttribute('open', '');
+        else this.removeAttribute('open');
+    }
+
+    /** The header title (Adw.Dialog:title). Setting a title renders the header. */
+    get title(): string {
+        return this.getAttribute('title') ?? '';
+    }
+
+    set title(value: string) {
+        this.setAttribute('title', value);
+    }
+
+    /** Whether the user can dismiss the dialog (scrim / Escape / close button). */
+    get canClose(): boolean {
+        const value = this.getAttribute('can-close');
+        // Absent → default on; explicit `="false"` → off (mirrors the boxed dialogs).
+        if (value === null) return true;
+        return value !== 'false';
+    }
+
+    set canClose(value: boolean) {
+        if (value) this.setAttribute('can-close', '');
+        else this.setAttribute('can-close', 'false');
+    }
+
+    /** The dialog's preferred/max content width in px (Adw.Dialog:content-width). */
+    get contentWidth(): number {
+        const raw = Number.parseInt(this.getAttribute('content-width') ?? '', 10);
+        return Number.isNaN(raw) ? DEFAULT_CONTENT_WIDTH : raw;
+    }
+
+    set contentWidth(value: number) {
+        this.setAttribute('content-width', String(value));
+    }
+
+    /** The dialog's max content height in px, or 0 for "unconstrained" (Adw.Dialog:content-height). */
+    get contentHeight(): number {
+        const raw = Number.parseInt(this.getAttribute('content-height') ?? '', 10);
+        return Number.isNaN(raw) ? 0 : raw;
+    }
+
+    set contentHeight(value: number) {
+        if (value > 0) this.setAttribute('content-height', String(value));
+        else this.removeAttribute('content-height');
+    }
+
+    /** The adaptive presentation mode (Adw.Dialog:presentation-mode). */
+    get presentationMode(): AdwDialogPresentationMode {
+        const value = this.getAttribute('presentation-mode') as AdwDialogPresentationMode | null;
+        return value && PRESENTATION_MODES.includes(value) ? value : 'auto';
+    }
+
+    set presentationMode(value: AdwDialogPresentationMode) {
+        this.setAttribute('presentation-mode', value);
+    }
+
+    /** The content container — arbitrary child markup lives here after connect. */
+    get contentArea(): HTMLDivElement {
+        return this._contentEl;
+    }
+
+    /** Reveal the dialog (mirrors Adw.Dialog.present). Auto-attaches if disconnected. */
+    present(parent?: Element): void {
+        if (!this.isConnected) (parent ?? document.body).appendChild(this);
+        this.open = true;
+    }
+
+    /** Dismiss the dialog, respecting `can-close` (mirrors Adw.Dialog.close). */
+    close(): void {
+        this._attemptClose();
+    }
+
+    /** Dismiss the dialog regardless of `can-close` (mirrors Adw.Dialog.force_close). */
+    forceClose(): void {
+        if (!this.open) return;
+        this.open = false;
+    }
+
+    connectedCallback() {
+        if (this._initialized) {
+            // A re-attach (e.g. present() on a previously-connected dialog) must
+            // not rebuild the subtree — the DOM already exists.
+            return;
+        }
+        this._initialized = true;
+
+        this.classList.add('adw-dialog');
+
+        // Everything the author placed inside becomes the dialog content.
+        const contentChildren = Array.from(this.childNodes);
+
+        // Full-cover scrim — a flex container that centres the box; clicking it
+        // (outside the box) attempts to dismiss the dialog.
+        this._scrimEl = document.createElement('div');
+        this._scrimEl.className = 'adw-dialog-scrim';
+        this._scrimEl.addEventListener('click', () => this._attemptClose());
+
+        // The dialog box (the "sheet"). Focusable so it can receive keys even
+        // when the content has none; clicks inside must not reach the scrim.
+        this._boxEl = document.createElement('div');
+        this._boxEl.className = 'adw-dialog-box';
+        this._boxEl.setAttribute('role', 'dialog');
+        this._boxEl.setAttribute('aria-modal', 'true');
+        this._boxEl.tabIndex = -1;
+        this._boxEl.addEventListener('click', (event) => event.stopPropagation());
+        this._boxEl.addEventListener('keydown', (event) => this._onBoxKeyDown(event));
+
+        // Optional flat header bar (title + trailing close button), strictly
+        // centred like an AdwHeaderBar.
+        this._headerEl = document.createElement('div');
+        this._headerEl.className = 'adw-dialog-header';
+
+        const leading = document.createElement('div');
+        leading.className = 'adw-dialog-header-side';
+
+        this._titleEl = document.createElement('span');
+        this._titleEl.className = 'adw-dialog-title';
+
+        const trailing = document.createElement('div');
+        trailing.className = 'adw-dialog-header-side adw-dialog-header-side--end';
+
+        this._closeBtn = document.createElement('button');
+        this._closeBtn.type = 'button';
+        this._closeBtn.className = 'adw-dialog-close';
+        this._closeBtn.setAttribute('aria-label', 'Close');
+        // No `window-close` symbolic ships in @gjsify/adwaita-icons; the "×"
+        // glyph is drawn in CSS (same approach as <adw-preferences-dialog>).
+        this._closeBtn.addEventListener('click', () => this._attemptClose());
+        trailing.appendChild(this._closeBtn);
+
+        this._headerEl.append(leading, this._titleEl, trailing);
+
+        // The content area — the author's markup.
+        this._contentEl = document.createElement('div');
+        this._contentEl.className = 'adw-dialog-content';
+        for (const child of contentChildren) this._contentEl.appendChild(child);
+
+        this._boxEl.append(this._headerEl, this._contentEl);
+        this._scrimEl.appendChild(this._boxEl);
+        this.replaceChildren(this._scrimEl);
+
+        this._render();
+    }
+
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null) {
+        if (!this._initialized) return;
+        if (oldValue === newValue) return;
+        this._render();
+        if (name === 'open') {
+            this.dispatchEvent(new CustomEvent('notify::open', { bubbles: true, detail: { open: this.open } }));
+            if (this.open) this._onPresented();
+            else this._onClosed();
+        }
+    }
+
+    // ── internals ──────────────────────────────────────────────────────────
+
+    /** A dismissal was requested: honour `can-close`, else raise close-attempt. */
+    private _attemptClose(): void {
+        if (!this.open) return;
+        if (!this.canClose) {
+            this.dispatchEvent(new CustomEvent('close-attempt', { bubbles: true }));
+            return;
+        }
+        // Drives attributeChangedCallback → notify::open + closed + return-focus.
+        this.open = false;
+    }
+
+    /** Focus trap + Escape while the box has focus. */
+    private _onBoxKeyDown(event: KeyboardEvent): void {
+        if (event.key === 'Escape' && this.open) {
+            event.stopPropagation();
+            this._attemptClose();
+            return;
+        }
+        if (event.key !== 'Tab') return;
+        const focusables = this._focusables();
+        if (focusables.length === 0) {
+            // Nothing tabbable inside — keep focus on the box.
+            event.preventDefault();
+            this._boxEl.focus();
+            return;
+        }
+        const first = focusables[0];
+        const last = focusables[focusables.length - 1];
+        const active = document.activeElement;
+        if (event.shiftKey && (active === first || active === this._boxEl)) {
+            event.preventDefault();
+            last.focus();
+        } else if (!event.shiftKey && active === last) {
+            event.preventDefault();
+            first.focus();
+        }
+    }
+
+    private _focusables(): HTMLElement[] {
+        return Array.from(this._boxEl.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)).filter(
+            (el) => !el.hasAttribute('disabled') && !el.hidden,
+        );
+    }
+
+    /** On present: remember focus, then move it into the dialog. */
+    private _onPresented(): void {
+        const active = document.activeElement;
+        this._previouslyFocused = active instanceof HTMLElement && active !== this ? active : null;
+        const target = this._focusables()[0] ?? this._boxEl;
+        target.focus();
+    }
+
+    /** On close: emit `closed` and return focus to where it was before present. */
+    private _onClosed(): void {
+        this.dispatchEvent(new CustomEvent('closed', { bubbles: true }));
+        const restore = this._previouslyFocused;
+        this._previouslyFocused = null;
+        if (restore && restore.isConnected) restore.focus();
+    }
+
+    private _render(): void {
+        this.classList.toggle('open', this.open);
+
+        const title = this.title;
+        this._titleEl.textContent = title;
+
+        // The header shows when there is a title or the author forces it.
+        const hasHeader = title.length > 0 || this.hasAttribute('show-header');
+        this._headerEl.hidden = !hasHeader;
+
+        // Presentation mode drives the CSS layout (floating vs bottom sheet).
+        this.dataset.presentation = this.presentationMode;
+
+        // Size constraints as CSS custom properties consumed by the box.
+        this._boxEl.style.setProperty('--adw-dialog-content-width', `${this.contentWidth}px`);
+        const height = this.contentHeight;
+        if (height > 0) this._boxEl.style.setProperty('--adw-dialog-content-height', `${height}px`);
+        else this._boxEl.style.removeProperty('--adw-dialog-content-height');
+
+        // A locked dialog's close button has no effect; reflect that.
+        const locked = !this.canClose;
+        this._closeBtn.disabled = locked;
+        this._closeBtn.classList.toggle('locked', locked);
+    }
+}
+
+customElements.define('adw-dialog', AdwDialog);