@gjsify/adwaita-web 0.36.0 → 0.37.0

package/src/elements/adw-checks.ts

@@ -1,32 +1,28 @@
-// <adw-checkbox> and <adw-radio> — the two form-control primitives, in ONE
-// module, for the same reason `scss/_checks.scss` is one partial: upstream
-// merges them (`refs/libadwaita/src/stylesheet/widgets/_checks.scss` has no
-// `_radio.scss` beside it), and everything but the corner radius, the glyph and
-// the group is shared. `refs/adwaita-web` split them into two files and the two
-// promptly drifted apart.
+// <adw-checkbox> and <adw-radio> — the two form-control primitives, in ONE module,
+// for the same reason `scss/_checks.scss` is one partial: upstream merges them
+// (`refs/libadwaita/src/stylesheet/widgets/_checks.scss` has no `_radio.scss` beside
+// it), and everything but the corner radius, the glyph and the group is shared.
+// Splitting them, as `refs/adwaita-web` does, is what lets the two drift apart.
 //
-// WHAT LIVES IN `@gjsify/adwaita-core`, AND WHAT DOES NOT
-//
-// The checkbox has no core class: it is one boolean plus a third state, which
-// ADR 0004 calls out as too trivial to model. What IS core is the pair of
-// pieces a second renderer would otherwise re-invent:
+// The checkbox has no core class: it is one boolean plus a third state, which ADR 0004
+// calls out as too trivial to model. What IS core is the pair a second renderer would
+// otherwise re-invent:
 //
 //   - {@link RadioGroupState} — group exclusivity. The browser gives the inner
 //     `<input type="radio" name="…">` exclusivity for free, and STOPS THERE: it
-//     unchecks the sibling INPUT and leaves the sibling `<adw-radio>` host's
-//     `checked` attribute — the published state, and the selector
-//     `_checks.scss` paints from — stale, so a group left to the browser draws
-//     two selected radios. The shared state is what repaints the loser.
-//   - {@link resolveCheckState} — indeterminate outranks checked, which is read
-//     off the cascade in `_checks.scss:79-81` and is what `aria-checked` needs.
+//     unchecks the sibling INPUT and leaves the sibling `<adw-radio>` host's `checked`
+//     attribute — the published state, and the selector `_checks.scss` paints from —
+//     stale, so a group left to the browser draws two selected radios. The shared
+//     state is what repaints the loser.
+//   - {@link resolveCheckState} — indeterminate outranks checked, read off the cascade
+//     in libadwaita's `_checks.scss`, and what `aria-checked` needs.
 //
-// WHAT IS NOT VERIFIABLE IN THIS TREE. `GtkCheckButton` is a GTK widget:
-// `refs/gtk` is EMPTY here and libadwaita vendors no `adw-checkbox.c`, so its
-// group semantics (`gtk_check_button_set_group`, whether a fresh group starts
-// with a member active) and the exact meaning of `GtkCheckButton:inconsistent`
-// are NOT verifiable and are not guessed at. Where a rule was needed the HTML
-// one is used and cited as such — clearing `indeterminate` on activation is the
-// HTML pre-click activation step, not a reading of GTK.
+// NOT DERIVED FROM GTK. `GtkCheckButton` is a GTK widget and libadwaita has no
+// `adw-checkbox.c`, so its group semantics (`gtk_check_button_set_group`, whether a
+// fresh group starts with a member active) and the exact meaning of
+// `GtkCheckButton:inconsistent` are not guessed at. Where a rule was needed the HTML
+// one is used and cited as such — clearing `indeterminate` on activation is the HTML
+// pre-click activation step, not a reading of GTK.
 //
 // NAMING. The state attribute is `checked`, not GtkCheckButton's `active`:
 // these elements wrap a real `<input>`, `checked` is the spelling every author
@@ -67,8 +63,8 @@ import { RadioGroupState, resolveCheckState } from '@gjsify/adwaita-core';
 
 /**
  * The document's radio groups. ONE registry, as global as a bare
- * `<input type="radio" name="x">` outside a form is — two independent groups
- * therefore need two names.
+ * `<input type="radio" name="x">` outside a form is — two independent groups therefore
+ * need two names.
  */
 const radioGroups = new RadioGroupState();
 
@@ -85,15 +81,13 @@ abstract class AdwCheckBase extends HTMLElement {
     /** What a click / Space / arrow key on the control means for this kind. */
     protected abstract activate(): void;
 
-    /** Whether the control is checked. */
     get checked(): boolean {
         return this.hasAttribute('checked');
     }
 
     set checked(value: boolean) {
-        // `toggleAttribute` with a force flag is a no-op when the attribute
-        // already holds that state, so re-setting the current value mutates
-        // nothing and the notify never runs.
+        // `toggleAttribute` with a force flag is a no-op when the attribute already
+        // holds that state, so re-setting the current value never notifies.
         this.toggleAttribute('checked', !!value);
     }
 
@@ -106,7 +100,6 @@ abstract class AdwCheckBase extends HTMLElement {
         this.toggleAttribute('indeterminate', !!value);
     }
 
-    /** Whether the control is inert. */
     get disabled(): boolean {
         return this.hasAttribute('disabled');
     }
@@ -115,7 +108,6 @@ abstract class AdwCheckBase extends HTMLElement {
         this.toggleAttribute('disabled', !!value);
     }
 
-    /** The label text beside the indicator. */
     get label(): string {
         return this.getAttribute('label') ?? this._label?.textContent ?? '';
     }
@@ -131,8 +123,8 @@ abstract class AdwCheckBase extends HTMLElement {
         }
         this._initialized = true;
 
-        // Captured BEFORE the element takes over its own children: a
-        // server-rendered `<adw-checkbox>Enable</adw-checkbox>` keeps its text.
+        // Captured BEFORE the element takes over its own children, so a server-rendered
+        // `<adw-checkbox>Enable</adw-checkbox>` keeps its text.
         const authored = [...this.childNodes];
 
         this._input = document.createElement('input');
@@ -154,9 +146,9 @@ abstract class AdwCheckBase extends HTMLElement {
         // and a direct programmatic `input.click()` both surface as `change`.
         this._input.addEventListener('change', () => this.activate());
 
-        // The indicator and the label cover the control; the input is 0x0, so
-        // every pointer click lands on one of them. A click that DID reach the
-        // input is already handled above — activating again would undo it.
+        // The indicator and the label cover the control; the input is 0x0, so every
+        // pointer click lands on one of them. A click that DID reach the input is already
+        // handled above — activating again would undo it.
         this.addEventListener('click', (event) => {
             if (this.disabled) return;
             if (event.target === this._input) return;
@@ -184,19 +176,16 @@ abstract class AdwCheckBase extends HTMLElement {
         }
     }
 
-    /** Extra wiring for a subclass on connect. */
     protected onConnected(): void {}
 
-    /** Extra teardown for a subclass on disconnect. */
     protected onDisconnected(): void {}
 
     protected render(): void {
         const state = resolveCheckState(this.checked, this.indeterminate);
         this._input.checked = state === 'checked';
         this._input.indeterminate = state === 'indeterminate';
-        // Explicit, because HTML has a native mixed CHECKBOX (the property
-        // above) but no mixed radio — this is the one spelling that announces
-        // the third state for both.
+        // Explicit, because HTML has a native mixed CHECKBOX (the property above) but no
+        // mixed radio — this is the one spelling that announces the third state for both.
         this._input.setAttribute('aria-checked', state === 'indeterminate' ? 'mixed' : String(state === 'checked'));
         this._input.disabled = this.disabled;
         this._label.hidden = this._label.childNodes.length === 0;
@@ -214,10 +203,9 @@ export class AdwCheckbox extends AdwCheckBase {
     }
 
     protected activate(): void {
-        // HTML's pre-click activation steps clear `indeterminate` before the
-        // toggle, so a user can always reach a definite state. That rule is the
-        // HTML spec's, not a reading of GtkCheckButton:inconsistent, whose
-        // behaviour is not verifiable in this tree.
+        // HTML's pre-click activation steps clear `indeterminate` before the toggle, so a
+        // user can always reach a definite state. That rule is the HTML spec's, not a
+        // reading of `GtkCheckButton:inconsistent`.
         this.indeterminate = false;
         this.checked = !this.checked;
     }
@@ -235,7 +223,6 @@ export class AdwRadio extends AdwCheckBase {
         return 'radio';
     }
 
-    /** The group this member belongs to. */
     get name(): string {
         return this.getAttribute('name') ?? '';
     }
@@ -245,8 +232,8 @@ export class AdwRadio extends AdwCheckBase {
     }
 
     /**
-     * This member's value. Falls back to the label text so a group authored
-     * without values still has members the group state can tell apart.
+     * This member's value. Falls back to the label text so a group authored without
+     * values still has members the group state can tell apart.
      */
     get value(): string {
         return this.getAttribute('value') ?? this.label.trim();
@@ -258,17 +245,17 @@ export class AdwRadio extends AdwCheckBase {
 
     protected activate(): void {
         this.indeterminate = false;
-        // An UNNAMED radio is not in a group — HTML forms a radio button group
-        // only from a non-empty `name`, so a nameless one checks itself and
-        // never unchecks anything. Without this guard every nameless radio in
-        // the document would join one `''` group and fight over it.
+        // An UNNAMED radio is not in a group — HTML forms a radio button group only from
+        // a non-empty `name`, so a nameless one checks itself and never unchecks anything.
+        // Without this guard every nameless radio in the document would join one `''`
+        // group and fight over it.
         if (this.name === '') {
             this.checked = true;
             return;
         }
-        // The pick goes through the shared state, never straight onto this
-        // element: the member that LOSES the selection is a different element
-        // and only the state knows which one it is.
+        // The pick goes through the shared state, never straight onto this element: the
+        // member that LOSES the selection is a different element and only the state knows
+        // which one it is.
         radioGroups.select(this.name, this.value);
     }
 

package/src/elements/adw-clamp.ts

@@ -1,16 +1,15 @@
 // <adw-clamp> — Constrains its children to a maximum width and centers them.
 // Attributes: maximum-size (px, default 600), tightening-threshold (px, default 400).
 //
-// The clamp is NOT a `max-width`, which is what this element used to be. Adwaita
-// eases the child from "all the available width" into the cap across a tightening
-// region, and stamps a `small`/`medium`/`large` class on it — the arithmetic lives
-// in `@gjsify/adwaita-core` (`clampAllocate`) so this element and the NativeScript
-// widget produce the same width for the same viewport.
+// The clamp is NOT a `max-width`: Adwaita eases the child from "all the available width"
+// into the cap across a tightening region and stamps a `small`/`medium`/`large` class on
+// it. The arithmetic lives in `@gjsify/adwaita-core` (`clampAllocate`), so this element and
+// the NativeScript widget produce the same width for the same viewport.
 //
-// The cap now sits on the CHILDREN, not on this element. The element has to keep
-// reporting the AVAILABLE width — it is what the curve is evaluated against — and
-// an element that caps itself reports the capped width back to its own
-// ResizeObserver, which is a feedback loop, not a measurement.
+// The cap sits on the CHILDREN, not on this element, which has to keep reporting the
+// AVAILABLE width — that is what the curve is evaluated against. An element that caps
+// itself reports the capped width back to its own ResizeObserver, which is a feedback
+// loop, not a measurement.
 //
 // `childMin` is passed as 0 rather than measured. libadwaita's
 // `lower = MAX (…, child_min)` says a child is never squeezed below its own

package/src/elements/adw-combo-row.ts

@@ -1,15 +1,11 @@
-// <adw-combo-row> — Row with a title/subtitle and a dropdown select.
-// Attributes: title, subtitle, items (JSON string[]), selected (index number)
-// Events: notify::selected (CustomEvent, mirrors GJS GObject signal naming)
-// The native <select> is stretched invisibly over the row so clicking anywhere opens it.
+// <adw-combo-row> — row with a title/subtitle and a dropdown select. `items` is a JSON
+// `string[]`, `selected` an index, and the native <select> is stretched invisibly over the
+// row so clicking anywhere opens it.
 //
-// The SELECTION state machine (the options list, the two-way index↔value mapping,
-// the empty/out-of-range guards and the programmatic-vs-interactive notify split)
-// is HEADLESS and lives in `@gjsify/adwaita-core` (ADR 0004) as {@link ComboState};
-// this element composes it and keeps only the DOM render half — the <select>, the
-// inline value label and the `notify::selected` event.
-// `@gjsify/adwaita-nativescript` composes the same state machine, so both ports
-// share one behaviour.
+// The SELECTION state machine (the options list, the two-way index↔value mapping, the
+// empty/out-of-range guards and the programmatic-vs-interactive notify split) is HEADLESS
+// and lives in `@gjsify/adwaita-core` (ADR 0004) as {@link ComboState}; this element keeps
+// only the DOM half — the <select>, the inline value label and `notify::selected`.
 //
 // Adapted from Adwaita Web UI Framework (https://github.com/mclellac/adwaita-web).
 // Copyright (c) 2025 csm. MIT License.
@@ -45,10 +41,9 @@ export class AdwComboRow extends HTMLElement {
         this._initialized = true;
 
         const items: string[] = JSON.parse(this.getAttribute('items') || '[]');
-        // Seed the headless state BEFORE subscribing, so building the initial DOM
-        // below is not driven by a change notification. The string→descriptor
-        // mapping is core's: `<adw-drop-down>` had its own, richer copy, so the
-        // two selectors accepted different option vocabularies.
+        // Seed the headless state BEFORE subscribing, so building the initial DOM below is
+        // not driven by a change notification. The string→descriptor mapping is core's, so
+        // this row and `<adw-drop-down>` accept one option vocabulary.
         this._state.setOptions(normalizeComboOptions(items));
         this._state.setSelectedIndex(parseInt(this.getAttribute('selected') || '0', 10));
         const selectedIdx = this._state.selectedIndex;
@@ -61,12 +56,10 @@ export class AdwComboRow extends HTMLElement {
         this._subtitleEl.className = 'adw-row-subtitle';
         text.append(this._titleEl, this._subtitleEl);
 
-        // Visible selected value display
         this._valueEl = document.createElement('span');
         this._valueEl.className = 'adw-row-value';
         this._valueEl.textContent = this._state.selectedLabel;
 
-        // Hidden select overlaying the entire row
         const select = document.createElement('select');
         items.forEach((item, i) => {
             const option = document.createElement('option');
@@ -118,13 +111,13 @@ export class AdwComboRow extends HTMLElement {
     }
 
     /**
-     * `model_changed` (adw-combo-row.c:187-195) — one option or none is not a
-     * choice, so the arrow goes and the row stops being activatable.
+     * `model_changed`: one option or none is not a choice, so the arrow goes and the row
+     * stops being activatable.
      *
-     * Both halves have to be expressed: `data-presents-chooser` gates the
-     * `.adw-row-value::after` mask in the stylesheet, and DISABLING the overlaid
-     * `<select>` is what makes the row inert — hiding the arrow alone would leave
-     * a row that still opens a one-entry popup on click.
+     * Both halves have to be expressed — `data-presents-chooser` gates the
+     * `.adw-row-value::after` mask in the stylesheet, and DISABLING the overlaid `<select>`
+     * is what makes the row inert. Hiding the arrow alone leaves a row that still opens a
+     * one-entry popup on click.
      */
     private _syncChooser() {
         const presents = this._state.presentsChooser;
@@ -133,8 +126,7 @@ export class AdwComboRow extends HTMLElement {
     }
 
     private _renderText() {
-        // The `string_is_not_empty` label rule, from core — this block was one of
-        // six hand-rolled copies, all of which omitted the TITLE half.
+        // The `string_is_not_empty` label rule, from core — it hides the TITLE too.
         const labels = deriveRowLabels({
             title: this.getAttribute('title'),
             subtitle: this.getAttribute('subtitle'),

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

@@ -1,18 +1,15 @@
-// <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.
+// <adw-data-grid> — A slim, Adwaita-styled ALIGNED data grid: the web mirror of the
+// native Gtk.Grid an accounting app uses for its financial statements (BWA / P&L,
+// invoice line-items). 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, 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.
+// PRESENTATIONAL ONLY: layout, alignment and emphasis, never formatting or sorting.
+// Cell values are PRE-FORMATTED strings (locale currency formatting stays in the app,
+// e.g. `1.234,50 €`); sorting is a data op driven externally, so there are no
+// clickable-sortable column headers here.
 //
 // Columns (the `columns` property, or a JSON `columns` attribute):
 //   { key, label?, align?, width?, flex?, monospace?, numeric? }
@@ -51,13 +48,12 @@
 // 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.
-// The derivations are HEADLESS and live in `@gjsify/adwaita-core` (ADR 0004):
-// the column tracks, the cell classes, the two normalisers, the cell text and
-// the activation rule. `@gjsify/adwaita-nativescript` renders the same widget
-// over `GridLayout` `ItemSpec`s — NativeScript has no subgrid — so the TRACK
-// rule is emitted as a renderer-neutral descriptor and only the mapping onto
-// `grid-template-columns` stays here. `@gjsify/adwaita-core/conformance`'s
-// `DATA_GRID_*_VECTORS` is the table both ports are held to.
+// The derivations are HEADLESS and live in `@gjsify/adwaita-core` (ADR 0004): the
+// column tracks, the cell classes, the two normalisers, the cell text and the activation
+// rule. `@gjsify/adwaita-nativescript` renders the same widget over `GridLayout`
+// `ItemSpec`s — NativeScript has no subgrid — so the TRACK rule is a renderer-neutral
+// descriptor and only the mapping onto `grid-template-columns` stays here. Both ports
+// are held to `@gjsify/adwaita-core/conformance`'s `DATA_GRID_*_VECTORS`.
 // 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+.
@@ -94,7 +90,6 @@ export class AdwDataGrid extends HTMLElement {
         return ['columns', 'rows', 'caption', 'interactive'];
     }
 
-    /** The column descriptors. Setting rebuilds the grid. */
     get columns(): AdwDataGridColumn[] {
         return this._columns;
     }
@@ -104,7 +99,6 @@ export class AdwDataGrid extends HTMLElement {
         if (this._initialized) this._render();
     }
 
-    /** The row objects. Setting rebuilds the body. */
     get rows(): AdwDataGridRow[] {
         return this._rows;
     }
@@ -124,7 +118,6 @@ export class AdwDataGrid extends HTMLElement {
         else this.removeAttribute('caption');
     }
 
-    /** Whether every `normal` row is clickable (element-level flag). */
     get interactive(): boolean {
         return this.hasAttribute('interactive');
     }
@@ -176,8 +169,6 @@ export class AdwDataGrid extends HTMLElement {
         void value;
     }
 
-    // ── internals ──────────────────────────────────────────────────────────
-
     private _parseJsonAttr<T>(name: string, coerce: (v: unknown) => T): T {
         const raw = this.getAttribute(name);
         if (!raw) return coerce(undefined);
@@ -195,13 +186,11 @@ export class AdwDataGrid extends HTMLElement {
     }
 
     /**
-     * The CSS `grid-template-columns` value derived from the column descriptors.
-     *
-     * The DERIVATION is core's (`dataGridTracks`), because NativeScript needs the
-     * same one for its `ItemSpec`s and can do nothing with a CSS string; the
-     * mapping onto CSS text — including the `minmax(0px, 1fr)` slack track whose
-     * `0px` must keep its unit to round-trip through the CSSOM — is
-     * `dataGridTrackTemplate`.
+     * The CSS `grid-template-columns` value derived from the column descriptors. The
+     * DERIVATION is core's (`dataGridTracks`), because NativeScript needs the same one for
+     * its `ItemSpec`s and can do nothing with a CSS string; the mapping onto CSS text —
+     * including the `minmax(0px, 1fr)` slack track whose `0px` must keep its unit to
+     * round-trip through the CSSOM — is `dataGridTrackTemplate`.
      */
     private _trackTemplate(): string {
         return dataGridTrackTemplate(dataGridTracks(this._columns));
@@ -220,7 +209,6 @@ export class AdwDataGrid extends HTMLElement {
         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');
@@ -242,8 +230,8 @@ export class AdwDataGrid extends HTMLElement {
             row.setAttribute('role', 'row');
 
             if (variant === 'section') {
-                // A section header spans all columns; its text is the first
-                // column's value (the section title).
+                // 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';
@@ -261,8 +249,8 @@ export class AdwDataGrid extends HTMLElement {
                 }
             }
 
-            // 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.
+            // 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.
             if (dataGridRowInteractive(variant, rowData.interactive, elementInteractive)) {
                 row.classList.add('interactive');
                 row.tabIndex = 0;

package/src/elements/adw-dialog.ts

@@ -1,44 +1,23 @@
-// <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`.
+// <adw-dialog> — the web counterpart of Adw.Dialog: arbitrary content in a floating
+// card over a full-cover scrim on wide viewports, re-anchored as a bottom sheet
+// (full-width, rounded top corners) on narrow ones. The adaptive switch is a CSS
+// media query keyed on `presentation-mode`, not an AdwBreakpoint object.
 //
 // 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.
+// <adw-about-dialog>) this one imposes no content model of its own: its default slot
+// holds any markup, and the flat header bar (title + trailing close button) renders
+// only when a `title` is set or `show-header` is used.
 //
-// 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).
+// Starts hidden; `present()` (or the `open` attribute) reveals it and `close()`
+// dismisses it — gated by `can-close`, so while locked Escape / scrim-click /
+// close-button raise `close-attempt` instead. 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); one already in the DOM is 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).
+// Events, all bubbling CustomEvents: `notify::open` (detail `{ open }`), `closed`
+// (Adw.Dialog::closed), `close-attempt` (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)
@@ -51,7 +30,6 @@ 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])',
@@ -163,25 +141,24 @@ export class AdwDialog extends HTMLElement {
 
     connectedCallback() {
         if (this._initialized) {
-            // A re-attach (e.g. present() on a previously-connected dialog) must
-            // not rebuild the subtree — the DOM already exists.
+            // A re-attach (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.
+        // Snapshot before the subtree is replaced: 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.
+        // Focusable so the box receives keys even when the content has none, and clicks
+        // inside must not reach the scrim's dismiss handler.
         this._boxEl = document.createElement('div');
         this._boxEl.className = 'adw-dialog-box';
         this._boxEl.setAttribute('role', 'dialog');
@@ -190,8 +167,6 @@ export class AdwDialog extends HTMLElement {
         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';
 
@@ -208,14 +183,12 @@ export class AdwDialog extends HTMLElement {
         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>).
+        // 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);
@@ -238,8 +211,6 @@ export class AdwDialog extends HTMLElement {
         }
     }
 
-    // ── internals ──────────────────────────────────────────────────────────
-
     /** A dismissal was requested: honour `can-close`, else raise close-attempt. */
     private _attemptClose(): void {
         if (!this.open) return;
@@ -306,20 +277,18 @@ export class AdwDialog extends HTMLElement {
         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).
+        // The CSS reads both of these: the dataset picks floating vs bottom sheet, the
+        // custom properties carry the size constraints.
         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);