@gjsify/adwaita-web 0.36.0 → 0.38.0

package/src/elements/adw-drop-down.ts

@@ -13,19 +13,15 @@
 // type-ahead (typing jumps to the next matching option).
 //
 // The popover is `<adw-popover>` and the dismissal/keyboard machine is
-// `@gjsify/adwaita-core`'s (ADR 0004). So is the SELECTION: the options list,
-// the index↔value mapping, the bounds guards and the
-// programmatic-vs-interactive split are {@link ComboState}, the same state
-// machine `<adw-combo-row>` composes — this element imported NOTHING from core
-// and re-derived all of it, which is how the two selectors ended up accepting
-// different option vocabularies (this one took `{value,label}` descriptors, the
-// row only bare strings). What stays here is what is genuinely a DROP-DOWN: the
-// search filter and the type-ahead buffer.
+// `@gjsify/adwaita-core`'s (ADR 0004). So is the SELECTION: the options list, the
+// index↔value mapping, the bounds guards and the programmatic-vs-interactive split are
+// {@link ComboState}, the same state machine `<adw-combo-row>` composes — so both
+// selectors accept one option vocabulary. What stays here is what is genuinely a
+// DROP-DOWN: the search filter and the type-ahead buffer.
 //
-// The arrow/Home/End wrap arithmetic left earlier, with the popover lift — it
-// was a second copy of `<adw-menu-button>`'s, and both had the same bug (ArrowUp
-// from an unfocused list landed on the SECOND-TO-LAST option, which
-// `enable-search` hit on every single open because it focuses the entry).
+// The arrow/Home/End wrap arithmetic belongs to the popover, not here: a per-element
+// copy is how ArrowUp from an unfocused list lands on the SECOND-TO-LAST option, which
+// `enable-search` hits on every open because it focuses the entry.
 //
 // Attributes:
 //   options / items — JSON array: `["a","b"]` or `[{"value":"a","label":"A"}]`.
@@ -66,11 +62,9 @@ import type { AdwComboOption, AdwComboOptionInput } from '@gjsify/adwaita-core';
 import { createAdwIcon } from './adw-icon.js';
 
 /**
- * A dropdown option — `value` is the stable id, `label` the shown text.
- *
- * An alias of core's {@link AdwComboOption}: the drop-down and the combo row are
- * the same selection model behind two chromes, and they had two names for one
- * descriptor. Kept exported so the published type name does not break.
+ * A dropdown option — `value` is the stable id, `label` the shown text. An alias of
+ * core's {@link AdwComboOption}, since the drop-down and the combo row are the same
+ * selection model behind two chromes; still exported so the published name keeps working.
  */
 export type AdwDropDownOption = AdwComboOption;
 
@@ -103,7 +97,6 @@ export class AdwDropDown extends HTMLElement {
         if (this._initialized) this._renderAll();
     }
 
-    /** Alias of `options` (Gtk.DropDown's model is often called "items"). */
     get items(): AdwDropDownOption[] {
         return this._state.options;
     }
@@ -131,12 +124,10 @@ export class AdwDropDown extends HTMLElement {
         if (index >= 0) this._selectIndex(index);
     }
 
-    /** The selected option descriptor, or null when empty. */
     get selectedItem(): AdwDropDownOption | null {
         return this._state.options[this._state.selectedIndex] ?? null;
     }
 
-    /** Whether the search entry is shown in the popover. */
     get enableSearch(): boolean {
         return this.hasAttribute('enable-search');
     }
@@ -146,7 +137,6 @@ export class AdwDropDown extends HTMLElement {
         else this.removeAttribute('enable-search');
     }
 
-    /** Whether the popover is currently open. */
     get active(): boolean {
         return this._popoverEl?.open ?? false;
     }
@@ -177,19 +167,17 @@ export class AdwDropDown extends HTMLElement {
         this._popoverEl = document.createElement('adw-popover') as AdwPopover;
         this._popoverEl.classList.add('adw-drop-down-popover');
         this._popoverEl.setAttribute('role', 'listbox');
-        // A dropdown's popover is a `popover.menu` too — `dropdown { popover.menu
-        // { … } }` (_dropdowns.scss:22) — even though its rows are ARIA `option`s
-        // rather than `menuitem`s. The style class and the role answer different
-        // questions, so neither is derived from the other.
+        // A dropdown's popover is a `popover.menu` too — `dropdown { popover.menu { … } }`
+        // — even though its rows are ARIA `option`s rather than `menuitem`s. The style
+        // class and the role answer different questions, so neither derives the other.
         this._popoverEl.setAttribute('menu', '');
 
         this._listEl = document.createElement('div');
         this._listEl.className = 'adw-drop-down-list';
         this._popoverEl.appendChild(this._listEl);
 
-        // Seed options from the property (already set) or the JSON attribute,
-        // BEFORE anything subscribes, so building the initial DOM below is not
-        // driven by a change notification.
+        // Seed options BEFORE anything subscribes, so building the initial DOM below is
+        // not driven by a change notification.
         if (this._state.count === 0) this._state.setOptions(this._parseOptionsAttr());
         const attrSelected = Number.parseInt(this.getAttribute('selected') ?? '', 10);
         if (this._state.hasIndex(attrSelected)) this._state.setSelectedIndex(attrSelected);
@@ -197,9 +185,9 @@ export class AdwDropDown extends HTMLElement {
         this.replaceChildren(this._buttonEl, this._popoverEl);
         this._popoverEl.anchor = this._buttonEl;
         this._popoverEl.subscribe((open) => this._onPopoverToggled(open));
-        // Type-ahead is the ONE key class the shared popover deliberately leaves
-        // to the renderer (`resolvePopoverKey` returns 'none' for printables), so
-        // it needs a listener of its own alongside the popover's.
+        // Type-ahead is the ONE key class the shared popover deliberately leaves to the
+        // renderer (`resolvePopoverKey` returns 'none' for printables), so it needs a
+        // listener of its own alongside the popover's.
         this._popoverEl.addEventListener('keydown', (event) => this._onPopoverTypeAhead(event));
         this._renderAll();
     }
@@ -220,14 +208,12 @@ export class AdwDropDown extends HTMLElement {
         }
     }
 
-    // ── internals ──────────────────────────────────────────────────────────
-
     private _parseOptionsAttr(): AdwDropDownOption[] {
         const raw = this.getAttribute('options') ?? this.getAttribute('items');
         if (!raw) return [];
         try {
-            // `normalizeComboOptions` already guards a non-array, so a JSON
-            // object or scalar yields the empty model rather than a throw.
+            // `normalizeComboOptions` already guards a non-array, so a JSON object or
+            // scalar yields the empty model rather than a throw.
             return normalizeComboOptions(JSON.parse(raw) as AdwComboOptionInput[]);
         } catch {
             return [];
@@ -237,12 +223,11 @@ export class AdwDropDown extends HTMLElement {
     private _selectIndex(index: number, opts: { fromAttr?: boolean; fromUser?: boolean } = {}): void {
         // The bounds arithmetic is `ComboState`'s; the POLICY of rejecting an
         // out-of-range set is this element's published `selected` contract, and
-        // `<adw-combo-row>` deliberately answers it the other way — see
-        // `ComboState.hasIndex`.
+        // `<adw-combo-row>` deliberately answers it the other way (`ComboState.hasIndex`).
         if (!this._state.hasIndex(index)) return;
-        // Both core setters return "did it change", which is what gates the
-        // notify — no second copy of the current index is kept here to compare
-        // against, and `setOptions`' own label re-sync cannot masquerade as one.
+        // Both core setters return "did it change", which is what gates the notify — no
+        // second copy of the current index is kept here, so `setOptions`' own label
+        // re-sync cannot masquerade as one.
         const changed = opts.fromUser ? this._state.select(index) : this._state.setSelectedIndex(index);
         this._updateLabel();
         this._updateSelectedStates();
@@ -252,13 +237,12 @@ export class AdwDropDown extends HTMLElement {
         }
         if (changed) {
             const option = this._state.options[index];
-            // `notify::selected` mirrors GObject property-notify: it fires on EVERY change,
+            // `notify::selected` mirrors GObject property-notify: EVERY change,
             // programmatic included.
             this.dispatchEvent(new CustomEvent('notify::selected', { bubbles: true, detail: { selected: index } }));
-            // `change` mirrors the DOM <select> contract: it fires ONLY on a user-initiated change.
-            // A programmatic `.selected`/`.selectedValue`/`selected`-attribute assignment stays silent
-            // (just as native `select.value = x` fires no `change`), so consumers can set the value
-            // without guarding against a spurious user-style event.
+            // `change` mirrors the DOM <select> contract: ONLY a user-initiated change. A
+            // programmatic assignment stays silent, just as native `select.value = x` fires
+            // no `change`, so consumers can set the value without guarding against it.
             if (opts.fromUser) {
                 this.dispatchEvent(
                     new CustomEvent('change', {
@@ -302,7 +286,6 @@ export class AdwDropDown extends HTMLElement {
         this._typeAhead(event.key);
     }
 
-    /** Type-ahead: accumulate keys, focus/select the next matching option. */
     private _typeAhead(char: string): void {
         this._typeAheadBuffer += char.toLowerCase();
         if (this._typeAheadTimer) clearTimeout(this._typeAheadTimer);
@@ -313,7 +296,6 @@ export class AdwDropDown extends HTMLElement {
         else this._selectIndex(match, { fromUser: true });
     }
 
-    /** Filter the visible items by a search query (case-insensitive substring). */
     private _filter(query: string): void {
         const q = query.trim().toLowerCase();
         this._itemButtons.forEach((button, index) => {
@@ -334,8 +316,8 @@ export class AdwDropDown extends HTMLElement {
     }
 
     private _updateLabel(): void {
-        // The setters (`options`/`selected`) may run before connectedCallback
-        // builds the DOM — stay a no-op until the label element exists.
+        // The setters may run before connectedCallback builds the DOM — a no-op until the
+        // label element exists.
         if (!this._labelEl) return;
         this._labelEl.textContent = this._state.selectedLabel;
     }
@@ -360,7 +342,6 @@ export class AdwDropDown extends HTMLElement {
             this._searchEl.placeholder = 'Search…';
             this._searchEl.setAttribute('aria-label', 'Search');
             this._searchEl.addEventListener('input', () => this._filter(this._searchEl?.value ?? ''));
-            // Prepend before the list so it sits atop the options.
             this._popoverEl.insertBefore(this._searchEl, this._listEl);
         } else {
             const existing = this._popoverEl.querySelector('.adw-drop-down-search');
@@ -378,7 +359,6 @@ export class AdwDropDown extends HTMLElement {
             label.className = 'adw-drop-down-item-label';
             label.textContent = option.label;
 
-            // A check icon marks the selected option (Gtk.DropDown's selected row).
             const check = document.createElement('span');
             check.className = 'adw-drop-down-item-check';
             check.setAttribute('aria-hidden', 'true');

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

@@ -16,12 +16,11 @@
 //   activatesDefault, editing.
 // Events:
 //   `changed` + `notify::text` — every buffer change. libadwaita implements
-//     GtkEditable through a delegate (adw-entry-row.c:87-93, :821-834) so it
-//     emits BOTH spellings; the two ports had each picked one and drifted, so
-//     this emits both and code written against either runs against the other.
-//   `notify::text-length` — on_length_changed (C:268-273).
-//   `apply` — the apply button, or Enter while it shows (C:240).
-//   `entry-activated` — Enter otherwise (C:256), AFTER the default was activated.
+//     GtkEditable through a delegate, so it emits BOTH spellings and so does this:
+//     code written against either runs against the other.
+//   `notify::text-length` — `on_length_changed`.
+//   `apply` — the apply button, or Enter while it shows.
+//   `entry-activated` — Enter otherwise, AFTER the default was activated.
 //
 // Reference: refs/libadwaita/src/adw-entry-row.c, adw-entry-row.ui
 // Reference: refs/adwaita-web/adwaita-web/docs/widgets/entryrow.md
@@ -41,13 +40,10 @@ import {
 import { type AdwIcon, createAdwIcon } from './adw-icon.js';
 
 /**
- * Show/hide a rendered part.
- *
- * `hidden` carries the semantics and is what the conformance suite reads, but
- * author CSS beats the UA `[hidden]` rule: `.adw-icon` already ships its own
- * `&[hidden] { display: none }` override in `_icon.scss` and `.adw-button`
- * does not, so a hidden apply button would still paint. The inline `display`
- * rides along until the entry-row SCSS pass lands.
+ * Show/hide a rendered part. `hidden` carries the semantics and is what the conformance
+ * suite reads, but author CSS beats the UA `[hidden]` rule: `.adw-icon` ships its own
+ * `&[hidden]` override in `_icon.scss` and `.adw-button` does not, so a hidden apply
+ * button would still paint without the inline `display`.
  */
 function setPartVisible(part: HTMLElement, visible: boolean): void {
     part.hidden = !visible;
@@ -93,7 +89,6 @@ export class AdwEntryRow extends HTMLElement {
         return 'adw-entry-row';
     }
 
-    /** The editable text. */
     get text(): string {
         return this._state.text;
     }
@@ -143,7 +138,6 @@ export class AdwEntryRow extends HTMLElement {
         this._state.setActivatesDefault(value);
     }
 
-    /** Whether the embedded entry currently has focus. */
     get editing(): boolean {
         return this._state.editing;
     }
@@ -166,7 +160,7 @@ export class AdwEntryRow extends HTMLElement {
         this._renderTitle();
 
         // Subclass parts first, THEN the author's children: `AdwPasswordEntryRow`
-        // installs its peek toggle from its own `init` (C:152), so a consumer
+        // installs its peek toggle from its own `init`, so a consumer
         // suffix lands after it and both remain.
         this._onConnected();
         this._adoptAuthored();
@@ -202,9 +196,9 @@ export class AdwEntryRow extends HTMLElement {
     }
 
     /**
-     * Add a widget after the editable area — `adw_entry_row_add_suffix`
-     * (adw-entry-row.c:885-899), which APPENDS into a box, so several suffixes
-     * coexist and the password row's own peek toggle survives a consumer's.
+     * Add a widget after the editable area — `adw_entry_row_add_suffix`, which APPENDS
+     * into a box, so several suffixes coexist and the password row's own peek toggle
+     * survives a consumer's.
      */
     addSuffix(node: Node): void {
         this._suffixes.append(node);
@@ -212,9 +206,9 @@ export class AdwEntryRow extends HTMLElement {
     }
 
     /**
-     * Add a widget before the editable area — `adw_entry_row_add_prefix`
-     * (C:864-880). PREPENDS, like the `gtk_box_prepend` it mirrors, so several
-     * prefixes stack in reverse call order exactly as they do in GTK.
+     * Add a widget before the editable area — `adw_entry_row_add_prefix`. PREPENDS, like
+     * the `gtk_box_prepend` it mirrors, so several prefixes stack in reverse call order
+     * exactly as they do in GTK.
      */
     addPrefix(node: Node): void {
         this._prefixes.prepend(node);
@@ -223,32 +217,32 @@ export class AdwEntryRow extends HTMLElement {
 
     /**
      * Drive the trailing indicator — `adw_entry_row_set_show_indicator`
-     * (adw-entry-row-private.h, C:1281-1296). Private-to-the-library upstream,
-     * public here because `<adw-password-entry-row>` is a separate custom element
-     * rather than a C subclass with access to the private header.
+     * (adw-entry-row-private.h). Private-to-the-library upstream, public here because
+     * `<adw-password-entry-row>` is a separate custom element rather than a C subclass
+     * with access to the private header.
      */
     setShowIndicator(show: boolean): void {
         this._state.setShowIndicator(show);
     }
 
-    /** `adw_entry_row_set_indicator_icon_name` (C:1263-1273). */
+    /** `adw_entry_row_set_indicator_icon_name`. */
     setIndicatorIconName(iconName: string): void {
         this._indicator.dataset.iconName = iconName;
     }
 
-    /** `adw_entry_row_set_indicator_tooltip` (C:1275-1279). */
+    /** `adw_entry_row_set_indicator_tooltip`. */
     setIndicatorTooltip(tooltip: string): void {
         this._indicator.title = tooltip;
         this._indicator.setAttribute('aria-label', tooltip);
     }
 
-    /** Apply the pending edit — the apply button click (C:229-241). */
+    /** Apply the pending edit — the apply button click. */
     apply(): void {
         this._state.apply();
         this.dispatchEvent(new CustomEvent('apply', { bubbles: true }));
     }
 
-    /** Focus the entry without selecting — `adw_entry_row_grab_focus_without_selecting` (C:1379-1389). */
+    /** Focus the entry without selecting — `adw_entry_row_grab_focus_without_selecting`. */
     grabFocusWithoutSelecting(): boolean {
         this._input.focus();
         return this._state.editing;
@@ -271,11 +265,11 @@ export class AdwEntryRow extends HTMLElement {
         this._suffixes = document.createElement('div');
         this._suffixes.className = `${prefix}-suffixes`;
 
-        // TWO title labels, exactly like adw-entry-row.ui: `empty_title` is the
-        // large placeholder shown while the row is empty, `title` the small label
-        // above the value. GTK cross-fades them over EMPTY_ANIMATION_DURATION_MS
-        // (C:433-439); until the SCSS pass lands this is a hard swap at the two
-        // animation endpoints, which is why the render reads `emptyTarget`.
+        // TWO title labels, exactly like adw-entry-row.ui: `empty_title` is the large
+        // placeholder shown while the row is empty, `title` the small label above the
+        // value. GTK cross-fades them over EMPTY_ANIMATION_DURATION_MS; here it is a hard
+        // swap at the two animation endpoints, which is why the render reads
+        // `emptyTarget`.
         this._emptyTitle = document.createElement('span');
         this._emptyTitle.className = `adw-row-title ${prefix}-empty-title`;
         this._title = document.createElement('span');
@@ -328,8 +322,8 @@ export class AdwEntryRow extends HTMLElement {
         this._editIcon = createAdwIcon('document-edit', 'adw-row-edit', `${prefix}-edit`);
         this._editIcon.dataset.iconName = ENTRY_ROW_EDIT_ICON_NAME;
 
-        // Snapshot order: indicator → apply → edit icon inside the editable area
-        // (C:429-431), with the prefixes/suffixes boxes outside it.
+        // Snapshot order: indicator → apply → edit icon inside the editable area, with
+        // the prefixes/suffixes boxes outside it.
         this.replaceChildren(
             this._prefixes,
             this._area,
@@ -345,9 +339,8 @@ export class AdwEntryRow extends HTMLElement {
     }
 
     /**
-     * Re-home the children the author wrote. libadwaita's buildable maps an
-     * untyped `<child>` to a suffix (C:796-812); `slot="prefix"` is the web
-     * spelling of its `type="prefix"`.
+     * Re-home the children the author wrote. libadwaita's buildable maps an untyped
+     * `<child>` to a suffix; `slot="prefix"` is the web spelling of `type="prefix"`.
      */
     private _adoptAuthored(): void {
         for (const node of this._authored) {
@@ -358,10 +351,10 @@ export class AdwEntryRow extends HTMLElement {
     }
 
     /**
-     * `pressed_cb` (C:201-227): a click landing on the row, the editable area,
-     * the indicator or either affordance box grabs focus; anything else (a suffix
-     * control, the apply button) is left alone. The pencil is `can-target=False`
-     * in the .ui, so a click on it picks the editable area — hence it focuses too.
+     * `pressed_cb`: a click landing on the row, the editable area, the indicator or
+     * either affordance box grabs focus; anything else (a suffix control, the apply
+     * button) is left alone. The pencil is `can-target=False` in the .ui, so a click on
+     * it picks the editable area — hence it focuses too.
      */
     private _maybeFocus(event: MouseEvent): void {
         const target = event.target;
@@ -379,15 +372,15 @@ export class AdwEntryRow extends HTMLElement {
         }
     }
 
-    /** `text_activated_cb` (C:243-266) — exactly one of the two signals. */
+    /** `text_activated_cb` — exactly one of the two signals. */
     private _activate(): void {
         const activation = this._state.activate();
         if (activation.signal === 'apply') {
             this.dispatchEvent(new CustomEvent('apply', { bubbles: true }));
             return;
         }
-        // C:253-256 — the default widget is activated BEFORE `entry-activated`.
-        // Implicit form submission is the web's default-widget activation.
+        // The default widget is activated BEFORE `entry-activated`; implicit form
+        // submission is the web's default-widget activation.
         if (activation.activateDefault) this.closest('form')?.requestSubmit();
         this.dispatchEvent(new CustomEvent('entry-activated', { bubbles: true }));
     }

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

@@ -1,28 +1,16 @@
-// <adw-expander-row> — A boxed-list row that discloses nested rows when expanded,
+// <adw-expander-row> — a boxed-list row that discloses nested rows when expanded,
 // with an optional enable switch. Mirrors Adw.ExpanderRow.
-// Attributes: title, subtitle, expanded (boolean), enable-expansion (boolean),
-//   show-enable-switch (boolean).
-// Slots: slot="prefix" / slot="suffix" widgets sit in the header row beside the
-//   title (before the enable switch + disclosure chevron), like Adw.ExpanderRow's
-//   add_prefix / add_suffix; any other child <adw-*-row> is moved into the
-//   disclosed content listbox.
-// Properties: expanded, enableExpansion (get/set, reflect to attributes).
-// Events: notify::expanded (CustomEvent), notify::enable-expansion (CustomEvent)
-//   — mirror Adw.ExpanderRow's GObject signal names so the same code path drives
-//   both the web and GTK renderers.
+//
+// Slots: `slot="prefix"` / `slot="suffix"` children sit in the HEADER row beside the
+// title (before the enable switch and disclosure chevron), like Adw.ExpanderRow's
+// add_prefix/add_suffix; every other child is moved into the disclosed content
+// listbox. The `notify::expanded` / `notify::enable-expansion` events are named after
+// Adw.ExpanderRow's GObject signals so one code path drives the web and GTK renderers.
 //
 // The DISCLOSURE state (the expanded flag and its idempotent, notify-on-change
 // transitions) is HEADLESS and lives in `@gjsify/adwaita-core` (ADR 0004) as
-// {@link ExpanderState}; this element composes it and keeps only the DOM render
-// half — the header/content markup, the `expanded` attribute reflection and the
-// `notify::expanded` event. `@gjsify/adwaita-nativescript` composes the same
-// state machine, so both ports share one behaviour.
-//
-// The optional enable switch is `<adw-switch>`. Both the markup and the
-// stylesheet block behind it used to be hand-built copies of
-// `<adw-switch-row>`'s — `_expander_row.scss:73-121` was character-for-character
-// `_switch_row.scss:15-63` — because `.adw-switch` was nested inside
-// `adw-switch-row {` and unusable from here.
+// {@link ExpanderState}; this element keeps only the DOM half — header/content markup,
+// the `expanded` attribute reflection and the event.
 //
 // Reference: refs/adwaita-web/adwaita-web/scss/_expander_row.scss
 // Reference: refs/libadwaita/src/stylesheet/widgets/_expander-row.scss
@@ -33,13 +21,12 @@
 
 import { ExpanderState, deriveRowLabels } from '@gjsify/adwaita-core';
 
-// SIDE-EFFECT imports, deliberately separate from the type import below: they
-// are what guarantee `adw-switch` / `adw-icon` are defined before this module's
-// own `customElements.define` can upgrade a server-rendered `<adw-expander-row>`
-// and build them. A combined `import { AdwSwitch }` would NOT do it — the
-// binding is only ever used in type position here, and this package compiles
-// without `verbatimModuleSyntax`, so TypeScript would elide the whole statement
-// and take the registration with it.
+// SIDE-EFFECT import, deliberately separate from the type import below: it guarantees
+// `adw-switch` is defined before this module's `customElements.define` can upgrade a
+// server-rendered `<adw-expander-row>` and build one. A combined
+// `import { AdwSwitch }` would NOT do it — the binding is only used in type position,
+// and this package compiles without `verbatimModuleSyntax`, so TypeScript would elide
+// the statement and take the registration with it.
 import './adw-switch.js';
 import type { AdwSwitch } from './adw-switch.js';
 import { type AdwIcon, createAdwIcon } from './adw-icon.js';
@@ -65,10 +52,10 @@ export class AdwExpanderRow extends HTMLElement {
 
     constructor() {
         super();
-        // Subscribed in the constructor (NOT connectedCallback) so a disclosure
-        // set before the element is connected still reflects to the attribute.
-        // The custom-element constructor rules allow this — nothing touches the
-        // DOM until the state actually changes.
+        // Subscribed in the constructor, NOT connectedCallback, so a disclosure set
+        // before the element is connected still reflects to the attribute. The
+        // custom-element constructor rules allow it: nothing touches the DOM until the
+        // state actually changes.
         this._state.subscribe((expanded) => {
             if (expanded) this.setAttribute('expanded', '');
             else this.removeAttribute('expanded');
@@ -115,15 +102,11 @@ export class AdwExpanderRow extends HTMLElement {
         if (this._initialized) return;
         this._initialized = true;
 
-        // Slotted prefix/suffix widgets go in the header; everything else is a
-        // nested row to disclose.
         const prefixChildren = Array.from(this.querySelectorAll(':scope > [slot="prefix"]'));
         const suffixChildren = Array.from(this.querySelectorAll(':scope > [slot="suffix"]'));
         const claimed = new Set<Node>([...prefixChildren, ...suffixChildren]);
         const rows = Array.from(this.childNodes).filter((node) => !claimed.has(node));
 
-        // Header row — looks like an action row: a text column, an optional
-        // enable switch, and the disclosure chevron.
         this._headerEl = document.createElement('div');
         this._headerEl.className = 'adw-expander-row-header';
 
@@ -135,15 +118,13 @@ export class AdwExpanderRow extends HTMLElement {
         this._subtitleEl.className = 'adw-row-subtitle';
         textEl.append(this._titleEl, this._subtitleEl);
 
-        // Optional enable switch (the same toggle Adw.ExpanderRow shows when
-        // show-enable-switch is set). Clicking it does NOT toggle the disclosure.
+        // Clicking the enable switch does NOT toggle the disclosure.
         this._enableSwitch = document.createElement('adw-switch') as AdwSwitch;
         this._enableSwitch.classList.add('adw-expander-row-enable-switch');
         this._enableSwitch.active = this.enableExpansion;
 
         this._chevronEl = createAdwIcon('go-down', 'adw-expander-row-chevron');
 
-        // Header prefix / suffix widget slots (Adw.ExpanderRow add_prefix/add_suffix).
         this._prefixEl = document.createElement('div');
         this._prefixEl.className = 'adw-expander-row-prefix';
         for (const child of prefixChildren) this._prefixEl.appendChild(child);
@@ -154,7 +135,6 @@ export class AdwExpanderRow extends HTMLElement {
 
         this._headerEl.append(this._prefixEl, textEl, this._suffixEl, this._enableSwitch, this._chevronEl);
 
-        // Disclosed content — a nested listbox holding the rows.
         this._contentEl = document.createElement('div');
         this._contentEl.className = 'adw-expander-row-content';
         for (const row of rows) this._contentEl.appendChild(row);
@@ -164,9 +144,9 @@ export class AdwExpanderRow extends HTMLElement {
         this._headerEl.addEventListener('click', (event) => {
             // Clicks on the enable switch toggle expansion-enable, not disclosure.
             if (this._enableSwitch.contains(event.target as Node)) return;
-            // The core state machine flips + reflects + re-renders; the event is
-            // emitted here so only a USER disclosure notifies (a programmatic
-            // `expanded = …` stays silent, as it always has on this port).
+            // The core state machine flips, reflects and re-renders; the event is emitted
+            // here so only a USER disclosure notifies — a programmatic `expanded = …`
+            // stays silent.
             if (this._state.toggle()) {
                 this.dispatchEvent(
                     new CustomEvent('notify::expanded', { bubbles: true, detail: { expanded: this.expanded } }),
@@ -175,10 +155,9 @@ export class AdwExpanderRow extends HTMLElement {
         });
 
         this._enableSwitch.addEventListener('notify::active', (event) => {
-            // The switch's own notify is stopped at the row: the row publishes
-            // `notify::enable-expansion`, and letting an identically-shaped
-            // `notify::active` past would put a second, differently-named event
-            // for the same user action on every ancestor listener.
+            // The switch's own notify stops at the row: the row publishes
+            // `notify::enable-expansion`, and letting `notify::active` past would give
+            // every ancestor listener a second, differently-named event for one action.
             event.stopPropagation();
             if (this._reflectingEnable) return;
             const enabled = this._enableSwitch.active;
@@ -191,23 +170,21 @@ export class AdwExpanderRow extends HTMLElement {
             );
         });
 
-        // Seed the disclosure from the parsed markup — attributeChangedCallback
-        // is guarded until the element is initialized, so a declarative
-        // `expanded` attribute has to be adopted here.
+        // Seed the disclosure from the parsed markup: attributeChangedCallback is guarded
+        // until the element is initialized, so a declarative `expanded` lands here.
         this._state.setExpanded(this.hasAttribute('expanded'));
         this._render();
     }
 
     attributeChangedCallback(name: string) {
         if (!this._initialized) return;
-        // The `expanded` attribute is the declarative face of the core state.
         if (name === 'expanded') this._state.setExpanded(this.hasAttribute('expanded'));
         this._render();
     }
 
     private _render() {
-        // 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, not
+        // just the subtitle.
         const labels = deriveRowLabels({
             title: this.getAttribute('title'),
             subtitle: this.getAttribute('subtitle'),