@gjsify/adwaita-web 0.35.0 → 0.37.0

package/src/elements/adw-popover.ts

@@ -1,11 +1,8 @@
 // <adw-popover> — the elevated surface that pops up next to an anchor, the web
-// counterpart of GtkPopover as libadwaita styles it. It is the ONE popover in
-// this package: `<adw-menu-button>`, `<adw-drop-down>` and `<adw-split-button>`
-// each used to build their own, and no two agreed. The surface disagreed (12px /
-// 12px / 9px radius against libadwaita's 15px; two correct three-layer shadows
-// and one invented two-layer one) and so did the behaviour — the split button
-// had neither Escape dismissal nor arrow-key navigation, while the other two
-// spelled the same wrap arithmetic out twice.
+// counterpart of GtkPopover as libadwaita styles it. It is the ONE popover in this
+// package: `<adw-menu-button>`, `<adw-drop-down>` and `<adw-split-button>` all use it
+// rather than building their own, which is what keeps the 15px radius, the
+// three-layer shadow, Escape dismissal and the wrap arithmetic in one place.
 //
 // The dismissal + keyboard state machine lives in `@gjsify/adwaita-core`
 // ({@link PopoverState}, {@link resolvePopoverKey}, ADR 0004); this element owns
@@ -19,23 +16,20 @@
 //
 // Attributes:
 //   open      — boolean; reflects (and drives) the visible state.
-//   position  — bottom | top | start | end (default bottom) — which side of the
-//               anchor the surface sits on. `GtkPopover:position`'s own
-//               autohide/has-arrow semantics are NOT verifiable in this tree
-//               (refs/gtk is empty, libadwaita vendors no adw-popover.c), so only
-//               the placement axis is modelled.
+//   position  — bottom | top | start | end (default bottom) — which side of the anchor
+//               the surface sits on. Only the placement axis is modelled:
+//               `GtkPopover:position`'s autohide/has-arrow semantics belong to GTK,
+//               which libadwaita does not vendor, so they are not guessed at.
 //   align     — start | end (default start) — which edge it lines up with.
 //   role      — menu | listbox (default menu) — the ARIA role of the surface.
 //               An a11y fact ONLY; it does not pick the surface variant, see
 //               `menu` below.
-//   menu      — boolean; libadwaita's `.menu` STYLE CLASS on the popover node
-//               (0 padding on the contents, `$menu_margin` on the item box —
-//               _menus.scss:58-66), opt-in exactly as it is in GTK.
-//               DO NOT infer it from `role`: `GtkDropDown`'s popover is a
-//               `popover.menu` too (`dropdown { popover.menu { … } }`,
-//               _dropdowns.scss:22) while its rows are `option`s, not
-//               `menuitem`s. Tying the surface to the role gets that backwards
-//               and pads the drop-down like a bare content popover.
+//   menu      — boolean; libadwaita's `.menu` STYLE CLASS on the popover node (0
+//               padding on the contents, `$menu_margin` on the item box), opt-in
+//               exactly as it is in GTK. DO NOT infer it from `role`: `GtkDropDown`'s
+//               popover is a `popover.menu` too (`dropdown { popover.menu { … } }`)
+//               while its rows are `option`s, not `menuitem`s, so tying the surface to
+//               the role pads the drop-down like a bare content popover.
 // Properties:
 //   open      — whether the popover is showing (get/set).
 //   anchor    — the element the surface is positioned against and returns focus
@@ -49,8 +43,8 @@
 //   `popover-item-activated` (CustomEvent, bubbles, detail = { index }) — a row
 //     was chosen by keyboard. Click activation stays the row's own listener.
 //
-// Reference: refs/libadwaita/src/stylesheet/widgets/_popovers.scss:7-28 (popover > contents)
-// Reference: refs/libadwaita/src/stylesheet/widgets/_menus.scss:58-66, :134-156 (popover.menu, modelbutton)
+// Reference: refs/libadwaita/src/stylesheet/widgets/_popovers.scss (popover > contents)
+// Reference: refs/libadwaita/src/stylesheet/widgets/_menus.scss (popover.menu, modelbutton)
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
@@ -82,16 +76,16 @@ export class AdwPopover extends HTMLElement {
     private _onDocumentPointerDown = (event: Event): void => {
         const target = event.target as Node;
         if (this.contains(target)) return;
-        // A click on the anchor is the anchor's own toggle — closing here too
-        // would close and immediately reopen (or reopen and immediately close).
+        // A click on the anchor is the anchor's own toggle — closing here too would close
+        // and immediately reopen (or reopen and immediately close).
         if (this.anchor?.contains(target) === true) return;
         this._state.dismiss();
     };
 
     private _onDocumentKeyDown = (event: KeyboardEvent): void => {
         if (event.key !== 'Escape') return;
-        // Captured at the document, so a nested popover's Escape does not also
-        // close its parent.
+        // Captured at the document, so a nested popover's Escape does not also close its
+        // parent.
         event.stopPropagation();
         this._state.dismiss();
         this.anchor?.focus();
@@ -101,7 +95,6 @@ export class AdwPopover extends HTMLElement {
         return ['open', 'position', 'align', 'role', 'menu'];
     }
 
-    /** Whether the popover is showing. */
     get open(): boolean {
         return this._state.open;
     }
@@ -112,9 +105,8 @@ export class AdwPopover extends HTMLElement {
     }
 
     /**
-     * The element the surface is positioned against and hands focus back to.
-     * Defaults to `parentElement`, which is the common case: the popover is the
-     * last child of the widget that owns it.
+     * The element the surface is positioned against and hands focus back to. Defaults to
+     * `parentElement`: the popover is normally the last child of the widget that owns it.
      */
     get anchor(): HTMLElement | null {
         return this._anchor ?? this.parentElement;
@@ -124,7 +116,6 @@ export class AdwPopover extends HTMLElement {
         this._anchor = value;
     }
 
-    /** Which side of the anchor the surface sits on. */
     get position(): AdwPopoverPosition {
         const value = this.getAttribute('position');
         return POSITIONS.includes(value as AdwPopoverPosition) ? (value as AdwPopoverPosition) : 'bottom';
@@ -134,7 +125,6 @@ export class AdwPopover extends HTMLElement {
         this.setAttribute('position', value);
     }
 
-    /** Which edge of the anchor the surface lines up with. */
     get align(): AdwPopoverAlign {
         const value = this.getAttribute('align');
         return ALIGNS.includes(value as AdwPopoverAlign) ? (value as AdwPopoverAlign) : 'start';
@@ -144,7 +134,6 @@ export class AdwPopover extends HTMLElement {
         this.setAttribute('align', value);
     }
 
-    /** The surface's ARIA role. */
     get popoverRole(): AdwPopoverRole {
         const value = this.getAttribute('role');
         return ROLES.includes(value as AdwPopoverRole) ? (value as AdwPopoverRole) : 'menu';
@@ -176,10 +165,8 @@ export class AdwPopover extends HTMLElement {
 
         this.classList.add('adw-popover');
         if (!this.hasAttribute('role')) this.setAttribute('role', 'menu');
-        // The `menu` variant is NOT defaulted or inferred here — it is GTK's
-        // `.menu` style class, and the widget that owns the popover is what adds
-        // it, as in the C. See the attribute docs above for why role is the
-        // wrong thing to key it off.
+        // The `menu` variant is NOT defaulted or inferred here — it is GTK's `.menu`
+        // style class, added by the widget that owns the popover, as in the C.
 
         this.addEventListener('keydown', (event) => this._onKeyDown(event));
         this._state.subscribe((change) => this._onStateChange(change.open));
@@ -202,16 +189,14 @@ export class AdwPopover extends HTMLElement {
             return;
         }
         if (name === 'role' && value === null) {
-            // A removed role falls back to the default rather than leaving the
-            // surface unlabelled to assistive tech.
+            // A removed role falls back to the default rather than leaving the surface
+            // unlabelled to assistive tech.
             this.setAttribute('role', 'menu');
             return;
         }
         this._render();
     }
 
-    // ── internals ──────────────────────────────────────────────────────────
-
     private _onStateChange(open: boolean): void {
         if (open) this._bindDocument();
         else this._unbindDocument();
@@ -269,9 +254,8 @@ export class AdwPopover extends HTMLElement {
             return;
         }
         if (action === 'activate') {
-            // preventDefault BEFORE the synthetic click: a focused <button>
-            // activates natively on Enter (keydown) and Space (keyup), so
-            // without it the row would fire twice.
+            // preventDefault BEFORE the synthetic click: a focused <button> activates
+            // natively on Enter (keydown) and Space (keyup), so the row would fire twice.
             event.preventDefault();
             items[index]?.click();
             this.dispatchEvent(new CustomEvent('popover-item-activated', { bubbles: true, detail: { index } }));

package/src/elements/adw-preferences-dialog.ts

@@ -4,22 +4,18 @@
 // clamp of <adw-preferences-group> boxed lists — under a flat header bar that
 // shows the dialog title and a trailing close button.
 //
-// Pages are declared as <adw-preferences-page> children (each with optional
-// `title` / `icon-name` / `name` / `use-underline` attributes + arbitrary group
-// content) and are moved — as ELEMENTS, keeping their identity — into the
-// scrolled body. `add(page)` accepts one at any later time, mirroring
-// adw_preferences_dialog_add.
-// (Adw shows a view-switcher when there is more than one page and the window is
-// wide, and shows exactly one page at a time; the web port renders the pages
-// stacked, matching the single-page common case the storybook exercises. The
-// page COLLECTION model — visible-page, visible-page-name, the auto-pick —
-// belongs to Adw.ViewStack and is available as `ViewStackState` in
-// @gjsify/adwaita-core when this port grows a switcher.)
+// Pages are declared as <adw-preferences-page> children (each with optional `title` /
+// `icon-name` / `name` / `use-underline` attributes + arbitrary group content) and are
+// moved — as ELEMENTS, keeping their identity — into the scrolled body.
+// `add(page)` accepts one at any later time, mirroring `adw_preferences_dialog_add`.
 //
-// `search(query)` implements the dialog's search over those pages: the corpus,
-// the filter and the `page → group` result subtitles all come from
-// @gjsify/adwaita-core, so the browser and NativeScript dialogs return the same
-// results for the same tree.
+// DEVIATION: Adw shows one page at a time behind a view switcher; this port renders
+// them stacked. The page COLLECTION model belongs to Adw.ViewStack and is available as
+// `ViewStackState` in @gjsify/adwaita-core when this port grows a switcher.
+//
+// `search(query)` searches those pages: corpus, filter and `page → group` result
+// subtitles all come from @gjsify/adwaita-core, so the browser and NativeScript dialogs
+// answer identically for the same tree.
 //
 // Like Adw.Dialog the dialog starts hidden; `present()` / setting the `open`
 // attribute reveals it. It is dismissed by Escape, by clicking the scrim, or by
@@ -58,15 +54,12 @@ import { searchPreferencesDom } from '../preferences-search.js';
 const DEFAULT_CONTENT_WIDTH = 640;
 
 /**
- * A single preferences page. Child of <adw-preferences-dialog>. Carries optional
- * `title` / `icon-name` / `name` / `use-underline` attributes and any
- * <adw-preferences-group> content — mirrors Adw.PreferencesPage.
+ * A single preferences page (Adw.PreferencesPage), child of <adw-preferences-dialog>.
  *
- * The dialog keeps the page ELEMENT rather than hoisting its children out,
- * because the page's identity is load-bearing: `adw_preferences_dialog_add`
- * binds title / icon-name / name / use-underline / visible onto the view-stack
- * page (adw-preferences-dialog.c:707-711), and `create_search_row_subtitle`
- * needs the title back the moment a second page is visible.
+ * The dialog keeps the page ELEMENT rather than hoisting its children out, because the
+ * page's identity is load-bearing: `adw_preferences_dialog_add` binds title / icon-name
+ * / name / use-underline / visible onto the view-stack page, and
+ * `create_search_row_subtitle` needs the title back the moment a second page is visible.
  */
 export class AdwPreferencesPage extends HTMLElement {
     static get observedAttributes() {
@@ -100,7 +93,6 @@ export class AdwPreferencesPage extends HTMLElement {
         this.toggleAttribute('use-underline', value);
     }
 
-    /** The page's groups, in document order. */
     get groups(): HTMLElement[] {
         return Array.from(this.querySelectorAll('adw-preferences-group'));
     }
@@ -119,7 +111,6 @@ export class AdwPreferencesDialog extends HTMLElement {
         return ['title', 'open', 'can-close', 'content-width'];
     }
 
-    /** Whether the dialog is revealed. */
     get open(): boolean {
         return this.hasAttribute('open');
     }
@@ -169,27 +160,23 @@ export class AdwPreferencesDialog extends HTMLElement {
     }
 
     /**
-     * `adw_preferences_dialog_add` (adw-preferences-dialog.c:693-716) — add a
-     * page at ANY time.
-     *
-     * Before this the pages were snapshotted once, in `connectedCallback`; a
-     * page appended later stayed a sibling of the scrim and rendered OUTSIDE
-     * the dialog card. GTK and the NativeScript port both accept a page
-     * whenever it arrives.
+     * `adw_preferences_dialog_add` — add a page at ANY time. A page that is only
+     * snapshotted in `connectedCallback` stays a sibling of the scrim and renders
+     * OUTSIDE the dialog card; GTK and the NativeScript port both accept one whenever
+     * it arrives.
      */
     add(page: AdwPreferencesPage): void {
         this._pagesEl.appendChild(page);
     }
 
     /**
-     * `adw_preferences_dialog_remove` (:723-745). C logs
-     * `ADW_CRITICAL_CANNOT_REMOVE_CHILD` and no-ops for a page it does not own;
-     * returning `false` is the same contract without a console write.
+     * `adw_preferences_dialog_remove`. C logs `ADW_CRITICAL_CANNOT_REMOVE_CHILD` and
+     * no-ops for a page it does not own; returning `false` is the same contract without
+     * a console write.
      *
-     * NOT named `remove`: `ChildNode.remove()` already exists on every element
-     * and takes no arguments, so overriding it with a different signature makes
-     * the class un-assignable to `HTMLElement` — which `customElements.define`
-     * requires.
+     * NOT named `remove`: `ChildNode.remove()` exists on every element and takes no
+     * arguments, so overriding it with a different signature makes the class
+     * un-assignable to `HTMLElement` — which `customElements.define` requires.
      */
     removePage(page: AdwPreferencesPage): boolean {
         if (page.parentNode !== this._pagesEl) return false;
@@ -197,22 +184,18 @@ export class AdwPreferencesDialog extends HTMLElement {
         return true;
     }
 
-    /** The dialog's pages, in add order. */
     get pages(): AdwPreferencesPage[] {
         return Array.from(this._pagesEl.querySelectorAll('adw-preferences-page')) as AdwPreferencesPage[];
     }
 
     /**
-     * The preferences search (`filter_search_results` +
-     * `create_search_row_subtitle`), over this dialog's live page subtree.
-     *
-     * The whole pipeline is `@gjsify/adwaita-core`'s, so this dialog and the
-     * NativeScript one answer identically for the same tree — including the
-     * three corpus filters (visible page → visible group → titled visible row)
-     * and the case fold that makes `strasse` find `Straße`.
+     * The preferences search (`filter_search_results` + `create_search_row_subtitle`),
+     * over this dialog's live page subtree. The pipeline is `@gjsify/adwaita-core`'s,
+     * including the three corpus filters (visible page → visible group → titled visible
+     * row) and the case fold that makes `strasse` find `Straße`.
      *
-     * An empty query returns the WHOLE corpus, which is what C does and what
-     * makes the results list non-empty before the user types.
+     * An empty query returns the WHOLE corpus, as C does, which is what makes the
+     * results list non-empty before the user types.
      */
     search(query: string, options?: SearchPreferencesOptions): PreferencesSearchResult<Element>[] {
         return searchPreferencesDom(this._pagesEl, query, options);
@@ -222,21 +205,17 @@ export class AdwPreferencesDialog extends HTMLElement {
         if (this._initialized) return;
         this._initialized = true;
 
-        // Snapshot the declared children before taking over the subtree. The
-        // page ELEMENTS move into the body intact — their title / name /
-        // icon-name are what a search result subtitle and a view switcher read
-        // — and any unwrapped children follow them (Adw.PreferencesDialog's
-        // buildable default adds a child as a page).
+        // The page ELEMENTS move into the body intact — their title / name / icon-name
+        // are what a search result subtitle and a view switcher read — and any unwrapped
+        // children follow them (Adw.PreferencesDialog's buildable default adds a child
+        // as a page).
         const declared = Array.from(this.childNodes);
 
-        // Full-cover scrim — clicking it dismisses the dialog (or raises
-        // close-attempt when locked).
+        // Clicking the scrim dismisses the dialog, or raises close-attempt when locked.
         this._scrimEl = document.createElement('div');
         this._scrimEl.className = 'adw-preferences-dialog-scrim';
         this._scrimEl.addEventListener('click', () => this._attemptClose());
 
-        // The centred dialog box: a flat header bar (title + close button) above
-        // a scrolled preferences body.
         this._dialogEl = document.createElement('div');
         this._dialogEl.className = 'adw-preferences-dialog-box';
         this._dialogEl.setAttribute('role', 'dialog');
@@ -262,14 +241,13 @@ export class AdwPreferencesDialog extends HTMLElement {
         this._closeBtn.type = 'button';
         this._closeBtn.className = 'adw-preferences-dialog-close';
         this._closeBtn.setAttribute('aria-label', 'Close');
-        // No symbolic close icon ships in @gjsify/adwaita-icons; draw the "×"
-        // glyph in CSS (same approach as <adw-tab-view>'s close affordance).
+        // The "×" is a CSS glyph: `window-close` has no mask class, because it is not in
+        // the ICONS map in `scripts/build-scss.mjs` that generates them.
         this._closeBtn.addEventListener('click', () => this._attemptClose());
         trailing.appendChild(this._closeBtn);
 
         header.append(leading, this._titleEl, trailing);
 
-        // Scrolled body — a clamped column of the declared pages.
         this._bodyEl = document.createElement('div');
         this._bodyEl.className = 'adw-preferences-dialog-body';
 
@@ -282,9 +260,8 @@ export class AdwPreferencesDialog extends HTMLElement {
 
         this.replaceChildren(this._scrimEl, this._dialogEl);
 
-        // Escape closes the dialog while open (mirrors Adw.Dialog's Escape
-        // shortcut → maybe_close_cb). The element is focusable so it can receive
-        // the key event when the dialog has focus.
+        // Escape closes the dialog while open (Adw.Dialog's Escape shortcut →
+        // `maybe_close_cb`). The element is focusable so it can receive the key event.
         if (!this.hasAttribute('tabindex')) this.tabIndex = -1;
         this.addEventListener('keydown', (event) => {
             if (event.key === 'Escape' && this.open) {
@@ -324,8 +301,6 @@ export class AdwPreferencesDialog extends HTMLElement {
 
         this._dialogEl.style.setProperty('--adw-dialog-content-width', `${this.contentWidth}px`);
 
-        // While locked the close button has no effect; reflect that visually +
-        // for assistive tech.
         const locked = !this.canClose;
         this._closeBtn.disabled = locked;
         this._closeBtn.classList.toggle('locked', locked);

package/src/elements/adw-preferences-group.ts

@@ -1,19 +1,14 @@
-// <adw-preferences-group> — Groups child rows in a boxed list with a title,
-// an optional dimmed description line and an optional trailing header-suffix
-// widget (e.g. a flat "Sign out" button at the trailing edge of the header).
-// Attributes: title, description.
-// Property: description (get/set, proxies the attribute).
-// Header-suffix: any child carrying `slot="header-suffix"` is hoisted into the
-//   trailing edge of the header instead of the boxed list — mirroring
-//   Adw.PreferencesGroup's `header-suffix` property / buildable type.
+// <adw-preferences-group> — groups child rows in a boxed list with a title, an
+// optional dimmed description line and an optional trailing header-suffix widget.
 //
-// The five visibility states (title, description, header, `single-line`,
-// listbox) are NOT derived here: they come from
-// `derivePreferencesGroupHeader` in `@gjsify/adwaita-core`, which both this
-// element and the NativeScript group delegate to (ADR 0004). This element used
-// to compute two of the five by hand and was missing the other three — no
-// `single-line` class, and a `.boxed-list` card that stayed painted (with its
-// full-width `box-shadow` hairline) over an empty group.
+// Any child carrying `slot="header-suffix"` is hoisted into the trailing edge of the
+// header instead of the boxed list, mirroring Adw.PreferencesGroup's `header-suffix`
+// property / buildable type.
+//
+// The five visibility states (title, description, header, `single-line`, listbox) are
+// NOT derived here: they come from `derivePreferencesGroupHeader` in
+// `@gjsify/adwaita-core`, which this element and the NativeScript group both delegate
+// to (ADR 0004).
 //
 // Reference: refs/libadwaita/src/adw-preferences-group.c
 //   (update_title_visibility, update_listbox_visibility, is_single_line,
@@ -57,14 +52,13 @@ export class AdwPreferencesGroup extends HTMLElement {
     }
 
     /**
-     * `adw_preferences_group_add` (adw-preferences-group.c:396-411): a row goes
-     * into the boxed list, a `header-suffix` child into the header.
+     * `adw_preferences_group_add`: a row goes into the boxed list, a `header-suffix`
+     * child into the header.
      *
-     * Exposed as a method AND wired to a `MutationObserver` on the host, because
-     * both spellings occur: `group.addRow(row)` in code, `group.append(row)` in
-     * a framework's rendering. Before this, a child appended after connect
-     * stayed a bare child of the host — outside the card, and invisible to the
-     * row count that decides whether the card is painted at all.
+     * Exposed as a method AND wired to a `MutationObserver` on the host, because both
+     * spellings occur — `group.addRow(row)` in code, `group.append(row)` from a
+     * framework's rendering — and a bare child of the host would sit outside the card,
+     * invisible to the row count that decides whether the card is painted at all.
      */
     addRow(child: Node): void {
         if (isHeaderSuffix(child)) this._suffixEl.appendChild(child);
@@ -73,9 +67,9 @@ export class AdwPreferencesGroup extends HTMLElement {
     }
 
     /**
-     * `adw_preferences_group_remove` (:421-440). C logs
-     * `ADW_CRITICAL_CANNOT_REMOVE_CHILD` and no-ops for a child it does not
-     * own; returning `false` is the same contract without a console write.
+     * `adw_preferences_group_remove`. C logs `ADW_CRITICAL_CANNOT_REMOVE_CHILD` and
+     * no-ops for a child it does not own; returning `false` is the same contract
+     * without a console write.
      */
     removeRow(child: Node): boolean {
         const parent = child.parentNode;
@@ -93,13 +87,9 @@ export class AdwPreferencesGroup extends HTMLElement {
         this._initialized = true;
 
         const children = Array.from(this.childNodes);
-        // Children opting into the header-suffix slot are hoisted to the
-        // trailing edge of the header; everything else goes into the boxed list.
         const suffixChildren = children.filter(isHeaderSuffix);
         const rowChildren = children.filter((child) => !suffixChildren.includes(child));
 
-        // Header: a flex row with a title/description label column on the left
-        // and the optional header-suffix on the trailing edge.
         this._headerEl = document.createElement('div');
         this._headerEl.className = 'adw-preferences-group-header';
 
@@ -120,7 +110,6 @@ export class AdwPreferencesGroup extends HTMLElement {
 
         this._headerEl.append(labels, this._suffixEl);
 
-        // Boxed list container — the remaining children move into it.
         this._listboxEl = document.createElement('div');
         this._listboxEl.className = 'adw-preferences-group-listbox';
         for (const child of rowChildren) this._listboxEl.appendChild(child);
@@ -146,18 +135,17 @@ export class AdwPreferencesGroup extends HTMLElement {
      * Adopt children appended to the HOST after the subtree was built, so
      * `group.append(row)` behaves like `adw_preferences_group_add`.
      *
-     * C gets this for free — `gtk_widget_observe_children` on the listbox drives
-     * `update_listbox_visibility` through `items-changed`
-     * (adw-preferences-group.c:335-339) — and a DOM element needs the observer
-     * to have the same rule hold over time rather than only at connect.
+     * C gets this for free: `gtk_widget_observe_children` on the listbox drives
+     * `update_listbox_visibility` through `items-changed`. A DOM element needs the
+     * observer for the same rule to hold over time rather than only at connect.
      */
     private _observeHost(): void {
         if (this._observer) return;
         this._observer = new MutationObserver((records) => {
             for (const record of records) {
-                // Only the HOST's own children need re-homing. Records from the
-                // listbox are the CONSEQUENCE of that move; re-adopting them
-                // would append each row a second time and reorder the list.
+                // Only the HOST's own children need re-homing. Records from the listbox are
+                // the CONSEQUENCE of that move; re-adopting them would append each row a
+                // second time and reorder the list.
                 if (record.target !== this) continue;
                 for (const node of record.addedNodes) {
                     if (!(node instanceof Element)) continue;
@@ -183,22 +171,21 @@ export class AdwPreferencesGroup extends HTMLElement {
             title,
             description,
             hasHeaderSuffix: this._suffixEl.childElementCount > 0,
-            // The RAW child count, matching `gtk_widget_observe_children` — a
-            // row with an empty title still keeps the card painted.
+            // The RAW child count, matching `gtk_widget_observe_children`: a row with an
+            // empty title still keeps the card painted.
             rowCount: this._listboxEl.childElementCount,
-            // The labels are `textContent`, not markup: what is displayed IS the
-            // attribute value, so visibility must be judged on the raw string.
-            // libadwaita's labels are `use-markup=True`; rendering Pango markup
-            // in the browser is a separate, still-open gap, and half-closing it
-            // here would hide a title this element visibly renders.
+            // The labels are `textContent`, not markup, so visibility must be judged on
+            // the raw string. libadwaita's labels are `use-markup=True`, but rendering
+            // Pango markup in the browser is a separate open gap — half-closing it here
+            // would hide a title this element visibly renders.
             useMarkup: false,
         });
 
         this._titleEl.hidden = !state.titleVisible;
         this._descriptionEl.hidden = !state.descriptionVisible;
         this._headerEl.hidden = !state.headerVisible;
-        // `single-line` is not cosmetic: the stylesheet keys the header's
-        // min-height / margin-bottom off it.
+        // `single-line` is not cosmetic: the stylesheet keys the header's min-height and
+        // margin-bottom off it.
         this._headerEl.classList.toggle('single-line', state.singleLine);
         this._listboxEl.hidden = !state.listboxVisible;
     }

package/src/elements/adw-progress-bar.ts

@@ -1,43 +1,25 @@
 // <adw-progress-bar> — the DETERMINATE progress indicator, and the partner to
 // <adw-spinner>, which only ever covers "busy, no idea how long".
 //
-// NO CORE STATE MACHINE. The whole behaviour is `CLAMP(fraction, 0, 1)` plus a
-// pulsing flag — ADR 0004 is explicit that a widget with genuinely trivial
-// behaviour does not get a core class, and the clamp itself is already shared:
-// `glibClamp` (GLib's CLAMP, high bound tested FIRST) comes from
-// `@gjsify/adwaita-core`. Nothing was added there for this element.
+// NO CORE STATE MACHINE: the whole behaviour is `CLAMP(fraction, 0, 1)` plus a pulsing
+// flag, and ADR 0004 is explicit that trivial behaviour gets no core class. The clamp
+// is still shared — `glibClamp` (GLib's CLAMP, high bound tested FIRST) comes from
+// `@gjsify/adwaita-core`.
 //
-// WHAT IS NOT VERIFIABLE IN THIS TREE. `GtkProgressBar` is a GTK widget:
-// `refs/gtk` is EMPTY here and libadwaita vendors no `adw-progress-bar.c`, so
-// `gtk_progress_bar_pulse()`'s step semantics — the `pulse-step` default, how
-// the block reflects at the ends, whether it resets `fraction` — are NOT
-// verifiable and are NOT reproduced. What ships instead is the web idiom the
-// vendored port uses: a CSS keyframe animation that runs while `pulsing` is set
-// (scss/_progress_bar.scss, which cites which half came from which source), so
-// {@link AdwProgressBar.pulse} ENTERS that state and is idempotent afterwards
-// rather than advancing an offset nothing here could check. The
-// default `show-text` label — `NN%` — is likewise this port's, not a
-// reproduction of GTK's format string.
+// `gtk_progress_bar_pulse()`'s step semantics (the `pulse-step` default, how the block
+// reflects at the ends, whether it resets `fraction`) are NOT reproduced: GtkProgressBar
+// is a GTK widget, `refs/gtk` is an uninitialized submodule here and libadwaita vendors
+// no `adw-progress-bar.c`, so none of it is verifiable. What ships instead is the
+// vendored port's web idiom — a CSS keyframe animation that runs while `pulsing` is set
+// — so {@link AdwProgressBar.pulse} ENTERS that state and is idempotent afterwards. The
+// default `show-text` label `NN%` is likewise this port's, not GTK's format string.
 //
-// Attributes:
-//   fraction   — 0…1, clamped. How much of the bar is filled.
-//   pulsing    — boolean; indeterminate. The block bounces instead of filling.
-//   show-text  — boolean; reveal the text node under the bar.
-//   text       — the text to show. Defaults to the fraction as a percentage.
-//   inverted   — boolean; fill from the far end.
-//   osd        — boolean; libadwaita's `.osd` STYLE CLASS — a 2px troughless bar
-//                for under a header bar (_progress-bar.scss:59-83).
-//   disabled   — boolean; dims the widget.
-// Properties:
-//   fraction / pulsing / showText / text / inverted / osd / disabled (get/set).
-// Methods:
-//   pulse()    — switch to indeterminate. GtkProgressBar's own vocabulary; see
-//                the caveat above for how far the resemblance goes.
+// `osd` is libadwaita's `.osd` STYLE CLASS: a 2px troughless bar for under a header bar.
 //
-// A11Y: `role="progressbar"` with `aria-valuemin`/`aria-valuemax` fixed at 0/1
-// and `aria-valuenow` carrying the clamped fraction. While pulsing,
-// `aria-valuenow` is REMOVED — that is how ARIA spells "indeterminate", and a
-// stale value there would be announced as real progress.
+// A11Y: `role="progressbar"`, `aria-valuemin`/`aria-valuemax` fixed at 0/1,
+// `aria-valuenow` carrying the clamped fraction. While pulsing `aria-valuenow` is
+// REMOVED — that is how ARIA spells "indeterminate", and a stale value there would be
+// announced as real progress.
 //
 // Reference: refs/libadwaita/src/stylesheet/widgets/_progress-bar.scss
 // Reference: refs/adwaita-web/adwaita-web/scss/_progressbar.scss (the indeterminate animation only)
@@ -60,8 +42,8 @@ export class AdwProgressBar extends HTMLElement {
     /** How much of the bar is filled, 0…1. Always the CLAMPED value. */
     get fraction(): number {
         const raw = Number.parseFloat(this.getAttribute('fraction') ?? '');
-        // A missing or unparseable attribute is 0, GtkProgressBar's default —
-        // NOT NaN, which would reach the width and the a11y value.
+        // A missing or unparseable attribute is 0, GtkProgressBar's default — not NaN,
+        // which would reach the width and the a11y value.
         if (!Number.isFinite(raw)) return 0;
         return glibClamp(raw, 0, 1);
     }
@@ -127,10 +109,9 @@ export class AdwProgressBar extends HTMLElement {
     }
 
     /**
-     * Switch the bar to indeterminate — GtkProgressBar's method name for the
-     * same intent. See the module header: the bouncing block is a CSS animation
-     * here, so this ENTERS the state and repeat calls are no-ops; GTK's
-     * `pulse-step` arithmetic is not verifiable in this tree and is not faked.
+     * Switch the bar to indeterminate — GtkProgressBar's method name for the same
+     * intent. The bouncing block is a CSS animation here, so this ENTERS the state and
+     * repeat calls are no-ops (see the module header).
      */
     pulse(): void {
         this.pulsing = true;
@@ -167,15 +148,14 @@ export class AdwProgressBar extends HTMLElement {
         const fraction = this.fraction;
         const pulsing = this.pulsing;
 
-        // `> trough.empty > progress { all: unset }` (_progress-bar.scss:85) —
-        // the indicator has to VANISH at 0, not draw a rounded stub. A pulsing
-        // bar is never empty: its block is what says "working".
+        // `> trough.empty > progress { all: unset }`: the indicator has to VANISH at 0,
+        // not draw a rounded stub. A pulsing bar is never empty — its block is what says
+        // "working".
         const empty = !pulsing && fraction === 0;
         this._trough.classList.toggle('empty', empty);
-        // The inline width is dropped in both the pulsing and the empty case, so
-        // the rules that own the indicator there — the keyframes, and
-        // `all: unset` — are not fighting an inline declaration they cannot win
-        // against (inline styles beat any author rule, `all: unset` included).
+        // The inline width is dropped in the pulsing and the empty case so the rules that
+        // own the indicator there (the keyframes, `all: unset`) are not fighting an inline
+        // declaration they cannot win against — inline styles beat any author rule.
         this._progress.style.width = pulsing || empty ? '' : `${fraction * 100}%`;
 
         this._text.textContent = this.text;