@gjsify/adwaita-web 0.35.0 → 0.37.0

package/src/elements/adw-view-stack.ts

@@ -1,10 +1,9 @@
 // <adw-view-stack> — A standalone, named-page CONTENT container: the web
 // counterpart of Adw.ViewStack decoupled from any switcher. It holds a set of
 // named pages and shows exactly one at a time; a paired <adw-view-switcher-bar>
-// (or an adaptive header-bar switcher) binds to it and drives the selection.
-// This is the piece the web package lacked — it already had switchers that own
-// their own pages (<adw-view-switcher>, <adw-inline-view-switcher>) but no
-// standalone stack a separate switcher can drive.
+// (or an adaptive header-bar switcher) binds to it and drives the selection. The
+// alternative switchers (<adw-view-switcher>, <adw-inline-view-switcher>) own their
+// own pages instead.
 //
 // The SELECTION itself — the name lookup, the guards on an index change, the
 // first-visible-page auto-pick and which paths notify — is HEADLESS and lives in
@@ -38,11 +37,10 @@
 //                                       page falls back to the next visible one.
 // Events:
 //   `notify::visible-child` (CustomEvent, bubbles,
-//     detail = { index, name, title, interactive }) whenever the visible page
-//     changes — including the auto-shown first page, exactly as
-//     `set_visible_child` notifies there (adw-view-stack.c:1038-1039). It used to
-//     stay silent on that path, which is why a bound switcher needed a manual
-//     `refresh()`. `interactive` is false for an auto-pick.
+//     detail = { index, name, title, interactive }) whenever the visible page changes,
+//     INCLUDING the auto-shown first page — `set_visible_child` notifies there too, and
+//     a switcher that is not told needs a manual `refresh()`. `interactive` is false
+//     for an auto-pick.
 // Reference: refs/libadwaita/src/adw-view-stack.c (AdwViewStack behaviour)
 // Reference: packages/nativescript-bridge/adwaita/src/widgets/adw-view-stack.ts (NS twin)
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
@@ -51,7 +49,6 @@
 import { ViewStackState } from '@gjsify/adwaita-core';
 import type { AdwViewStackPageInfo as CorePageInfo, ViewStackStateChange } from '@gjsify/adwaita-core';
 
-/** A page descriptor exposed via `pages` (consumed by a bound switcher bar). */
 export type AdwViewStackPageInfo = CorePageInfo<HTMLElement>;
 
 export class AdwViewStack extends HTMLElement {
@@ -69,7 +66,6 @@ export class AdwViewStack extends HTMLElement {
         this._state.subscribe((change) => this._onStateChange(change));
     }
 
-    /** All pages in declaration/add order. A bound switcher reads this. */
     get pages(): readonly AdwViewStackPageInfo[] {
         return this._state.pages;
     }
@@ -83,7 +79,6 @@ export class AdwViewStack extends HTMLElement {
         this._state.setVisibleIndex(value);
     }
 
-    /** Name of the visible page, or '' when nothing is selected. */
     get visibleChildName(): string {
         return this._state.visibleName;
     }
@@ -92,7 +87,6 @@ export class AdwViewStack extends HTMLElement {
         this._state.setVisibleName(name);
     }
 
-    /** The visible page's content element, or null when nothing is selected. */
     get visibleChild(): HTMLElement | null {
         return this._state.visiblePage?.content ?? null;
     }
@@ -106,21 +100,17 @@ export class AdwViewStack extends HTMLElement {
         // otherwise overwrite the author's value with page 0's name.
         const initialName = this.getAttribute('visible-child-name');
 
-        // Adopt the declared <adw-view-stack-page> children by APPENDING them —
-        // never by replacing the page list. The old code assigned the parsed
-        // wrappers wholesale and then `replaceChildren()`d the subtree away, so a
-        // stack built imperatively before it entered the document
-        // (`createElement` → `add()` → `body.append()`) lost every page it had
-        // been given. libadwaita has no parse-once phase that can discard
-        // children: the buildable adds them one at a time
-        // (adw_view_stack_buildable_add_child, adw-view-stack.c:1666-1680) and
-        // `adw_view_stack_add` works at any point in the widget's life.
+        // Adopt the declared <adw-view-stack-page> children by APPENDING them, never by
+        // replacing the page list: a stack built imperatively before it entered the
+        // document (`createElement` → `add()` → `body.append()`) would lose every page
+        // it had been given. libadwaita has no parse-once phase that can discard
+        // children — the buildable adds them one at a time and `adw_view_stack_add`
+        // works at any point in the widget's life.
         for (const pageEl of Array.from(this.querySelectorAll(':scope > adw-view-stack-page')) as HTMLElement[]) {
-            // A declared page with no `name` is the page named '' — C stores the
-            // name verbatim (adw-view-stack.c:1170), and an invented `page-<index>`
-            // is addressable by a name the author never wrote.
+            // A declared page with no `name` is the page named '': C stores the name
+            // verbatim, and an invented `page-<index>` would be addressable by a name the
+            // author never wrote.
             const name = pageEl.getAttribute('name') ?? '';
-            // Wrapping each page's content lets us toggle exactly one.
             const element = document.createElement('div');
             element.className = 'adw-view-stack-child';
             element.dataset.name = name;
@@ -132,16 +122,15 @@ export class AdwViewStack extends HTMLElement {
                 icon: pageEl.getAttribute('icon-name'),
                 content: element,
                 // `hidden` is the DOM spelling of AdwViewStackPage:visible, which
-                // gates the auto-pick and refuses selection (adw-view-stack.c:1149-1151, :2415).
+                // gates the auto-pick and refuses selection.
                 visible: !pageEl.hasAttribute('hidden'),
             });
             this.replaceChild(element, pageEl);
         }
 
-        // An explicit `visible-child-name` selects the initial page. Only a
-        // MISSING attribute falls through to the auto-pick — an empty value is a
-        // legal lookup for a page named '' (g_strcmp0, adw-view-stack.c:901),
-        // which the old `initialName ? … : -1` falsy check silently dropped.
+        // An explicit `visible-child-name` selects the initial page; only a MISSING
+        // attribute falls through to the auto-pick. An empty value is a legal lookup for
+        // a page named '' (`g_strcmp0`), so a falsy check here is wrong.
         if (initialName !== null) this._state.setVisibleName(initialName, false);
         this._applyVisibility();
         this._reflectName();
@@ -159,7 +148,7 @@ export class AdwViewStack extends HTMLElement {
 
     /**
      * Append a page. It becomes visible when nothing is selected yet, matching
-     * `Adw.ViewStack.add()` — and, unlike before, that auto-pick NOTIFIES.
+     * `Adw.ViewStack.add()`, and that auto-pick NOTIFIES.
      */
     add(content: HTMLElement, name: string, title?: string, icon?: string): AdwViewStackPageInfo {
         content.classList.add('adw-view-stack-child');
@@ -172,7 +161,6 @@ export class AdwViewStack extends HTMLElement {
         return page;
     }
 
-    /** Convenience alias mirroring Adw.ViewStack.add_titled() (no icon). */
     addTitled(content: HTMLElement, name: string, title: string): AdwViewStackPageInfo {
         return this.add(content, name, title);
     }
@@ -181,7 +169,7 @@ export class AdwViewStack extends HTMLElement {
      * Remove the first page named `name` and detach its content. Returns whether
      * anything was removed. When the removed page was the visible one the stack
      * ends up showing NOTHING and emits no event — `stack_remove` clears
-     * `visible_child` without re-picking (adw-view-stack.c:1202-1203).
+     * `visible_child` without re-picking.
      */
     removePage(name: string): boolean {
         const content = this._state.pages[this._state.indexOfName(name)]?.content;
@@ -197,28 +185,23 @@ export class AdwViewStack extends HTMLElement {
      * Show or hide a page (`AdwViewStackPage:visible`). Returns whether the
      * SELECTION moved: hiding the visible page falls back to the next visible
      * one, and making a page visible while nothing is selected selects it
-     * (`update_child_visible`, adw-view-stack.c:1061-1082).
+     * (`update_child_visible`).
      */
     setPageVisible(name: string, visible: boolean): boolean {
         const moved = this._state.setPageVisible(name, visible);
         this._applyVisibility();
         // A visibility flip changes what the pages MODEL reports, which is what
-        // `update_bar_revealed` counts (adw-view-switcher-bar.c:340) — hiding
-        // the second-to-last visible page must retract the bar.
+        // `update_bar_revealed` counts — hiding the second-to-last visible page must
+        // retract the bar.
         this._emitItemsChanged();
         return moved;
     }
 
     /**
-     * The pages model's `items-changed`, which the DOM stack had no counterpart
-     * for at all.
-     *
-     * `AdwViewSwitcherBar` re-runs `update_bar_revealed` on it
-     * (adw-view-switcher-bar.c:340) and `AdwViewSwitcher` rebinds its buttons
-     * (adw-view-switcher.c:258-263). Both ports listened only on
-     * `notify::visible-child`, so adding a page or hiding a non-selected one
-     * left `revealed` — and the button row — stale, with a manual `refresh()`
-     * as the documented workaround.
+     * The pages model's `items-changed`: `AdwViewSwitcherBar` re-runs
+     * `update_bar_revealed` on it and `AdwViewSwitcher` rebinds its buttons. A listener
+     * on `notify::visible-child` alone leaves `revealed` and the button row stale when a
+     * page is added or a non-selected one hidden.
      */
     private _emitItemsChanged(): void {
         this.dispatchEvent(new CustomEvent('items-changed', { bubbles: true, detail: { count: this.pages.length } }));
@@ -253,11 +236,9 @@ export class AdwViewStack extends HTMLElement {
 
     private _reflectName(): void {
         // With nothing selected there is no name to mirror — C's
-        // `adw_view_stack_get_visible_child_name` returns NULL there
-        // (adw-view-stack.c:2384), and a missing attribute is the DOM spelling of
-        // that. An EMPTY name is still a name and IS reflected: the old
-        // `if (current && …)` guard meant a stack of nameless pages never
-        // reflected its selection at all.
+        // `adw_view_stack_get_visible_child_name` returns NULL, and a missing attribute
+        // is the DOM spelling of that. An EMPTY name is still a name and IS reflected: a
+        // truthiness guard here stops a stack of nameless pages reflecting at all.
         if (this._state.visibleIndex < 0) {
             this.removeAttribute('visible-child-name');
             return;

package/src/elements/adw-view-switcher-bar.ts

@@ -3,33 +3,16 @@
 // owns no pages: it reads the bound stack's `pages`, renders one homogeneous
 // button per page, and is two-way synced to the stack's visible child.
 //
-// The derivations are HEADLESS and live in `@gjsify/adwaita-core` (ADR 0004):
-// the per-button model (`buildViewSwitcherButtons`, so this bar and the header
-// switcher cannot disagree about what a page looks like) and — the rule this
-// port was missing entirely — `ViewSwitcherBarState`, which is `reveal` AND
-// MORE THAN ONE VISIBLE PAGE (`update_bar_revealed`,
-// adw-view-switcher-bar.c:104-126). A bar bound to a one-page stack used to show
-// an empty strip that libadwaita keeps collapsed.
+// The derivations are HEADLESS and live in `@gjsify/adwaita-core` (ADR 0004): the
+// per-button model (`buildViewSwitcherButtons`, so this bar and the header switcher
+// cannot disagree about what a page looks like) and `ViewSwitcherBarState`, which is
+// `reveal` AND MORE THAN ONE VISIBLE PAGE (`update_bar_revealed`) — a bar bound to a
+// one-page stack stays collapsed however loudly the layout asks.
 //
-// Also fixed here, from the same C: `disconnectedCallback` removed the stack
-// listener and `connectedCallback` only re-added it when `ref && !this._stack`,
-// so a bar that was detached and re-inserted never tracked its stack again. In
-// C the handlers are bound in `set_stack` and released only in `dispose`
-// (:330-341, :218-221) — realize/unrealize never touch them.
+// `stack` names the <adw-view-stack> to drive by id, like `<label for>`. `revealed` is
+// the LEGACY spelling of the `reveal` request and is still read as one; as a property
+// it is read-only and reports whether the bar is actually shown.
 //
-// Attributes:
-//   stack    — the id of the <adw-view-stack> to drive (like <label for>).
-//   reveal   — boolean; the REQUEST (`Adw.ViewSwitcherBar:reveal`, default off).
-//   revealed — the legacy spelling of `reveal`, still accepted as the request.
-// Properties:
-//   stack    — the bound AdwViewStack element (get/set; set also accepts an id).
-//   reveal   — the request (get/set).
-//   revealed — READ-ONLY: whether the bar is actually shown, i.e. the request
-//              AND more than one visible page.
-// Methods:
-//   setStack(stack) — bind to a stack element (or null); rebuilds the buttons.
-//   refresh()       — rebuild after pages were added to the bound stack without
-//                     changing its selection (see the note in `_rebuild`).
 // Reference: refs/libadwaita/src/adw-view-switcher-bar.c (AdwViewSwitcherBar)
 // Reference: refs/libadwaita/src/adw-view-switcher.c (the switcher it embeds)
 // Reference: packages/nativescript-bridge/adwaita/src/widgets/adw-view-switcher-bar.ts (NS twin)
@@ -91,7 +74,7 @@ export class AdwViewSwitcherBar extends HTMLElement {
 
     /**
      * Whether the bar is actually shown. READ-ONLY: a one-page stack keeps it
-     * collapsed however loudly the layout asks (adw-view-switcher-bar.c:125).
+     * collapsed however loudly the layout asks.
      * Write {@link reveal} to make the request.
      */
     get revealed(): boolean {
@@ -108,17 +91,17 @@ export class AdwViewSwitcherBar extends HTMLElement {
         }
         this._barState.setReveal(this._readReveal());
 
-        // Resolve the `stack` id ref now that the element is in the document —
-        // the referenced stack is normally earlier in the DOM (content above a
-        // bottom bar), so its pages are ready.
+        // Resolve the `stack` id ref now the element is in the document: the referenced
+        // stack is normally earlier in the DOM (content above a bottom bar), so its pages
+        // are ready.
         const ref = this.getAttribute('stack');
         if (ref && !this._stack) {
             this.setStack(this._resolveStack(ref));
             return;
         }
-        // Re-attaching must re-bind: `disconnectedCallback` released the
-        // listener, and the old `ref && !this._stack` guard could never take it
-        // back. In C the binding survives unrealize entirely.
+        // Re-attaching must re-bind, because `disconnectedCallback` released the listener.
+        // In C the binding is made in `set_stack`, released in `dispose`, and survives
+        // unrealize entirely.
         this._bindStack();
         this._rebuild();
     }
@@ -147,13 +130,9 @@ export class AdwViewSwitcherBar extends HTMLElement {
     }
 
     /**
-     * Rebuild the buttons by hand.
-     *
-     * Kept as public API — a consumer that mutates a page in place still has a
-     * way to say so — but no longer the ONLY way: the stack emits
-     * `items-changed` now and this bar binds it, which is the mechanism
-     * libadwaita uses (adw-view-switcher-bar.c:340,
-     * adw-view-switcher.c:258-263).
+     * Rebuild the buttons by hand — public API for a consumer that mutated a page in
+     * place. Not the only path: the stack emits `items-changed` and this bar binds it,
+     * which is the mechanism libadwaita uses.
      */
     refresh(): void {
         this._rebuild();
@@ -165,10 +144,9 @@ export class AdwViewSwitcherBar extends HTMLElement {
 
     private _bindStack(): void {
         this._stack?.addEventListener('notify::visible-child', this._onStackNotify);
-        // `update_bar_revealed` runs on the pages model's `items-changed` too
-        // (adw-view-switcher-bar.c:340), which is the half that was missing: a
-        // page added without moving the selection, or a non-selected page
-        // hidden, changes the COUNT the reveal is decided from.
+        // `update_bar_revealed` runs on the pages model's `items-changed` too: a page
+        // added without moving the selection, or a non-selected page hidden, changes the
+        // COUNT the reveal is decided from.
         this._stack?.addEventListener('items-changed', this._onStackNotify);
     }
 
@@ -187,18 +165,16 @@ export class AdwViewSwitcherBar extends HTMLElement {
         if (!this._initialized) return;
 
         const stackPages = this._stack?.pages ?? [];
-        // The page count is half the reveal derivation, so it is fed on every
-        // rebuild — `update_bar_revealed` is re-run from set_stack and from
-        // items-changed for exactly this reason (:340-343, :277).
+        // The page count is half the reveal derivation, so it is fed on every rebuild —
+        // which is why C re-runs `update_bar_revealed` from set_stack and items-changed.
         this._barState.setPages(stackPages);
 
         const pages = viewSwitcherPagesFromStack(stackPages);
         const models = buildViewSwitcherButtons(pages, this._stack?.visibleChildIndex ?? -1, 'narrow');
 
-        // Nodes are recreated only when the page COUNT moves. A selection change
-        // must not replace the button the user is standing on — `selection_changed_cb`
-        // only re-marks the existing buttons (adw-view-switcher.c:265-295), and a
-        // wholesale replace would drop keyboard focus mid-interaction.
+        // Nodes are recreated only when the page COUNT moves: a selection change must not
+        // replace the button the user is standing on. `selection_changed_cb` only re-marks
+        // the existing buttons, and a wholesale replace drops keyboard focus mid-interaction.
         if (models.length !== this._nodes.length) {
             this._barEl.replaceChildren();
             this._nodes = models.map((model) => this._buildButton(model.pageIndex));

package/src/elements/adw-view-switcher.ts

@@ -3,46 +3,28 @@
 // libadwaita keeps separate. Pages are declared as <adw-view-switcher-page>
 // children; their own children become the page body.
 //
-// Everything that decides WHAT to show is HEADLESS and lives in
-// `@gjsify/adwaita-core` (ADR 0004): the button-visibility rule, the
-// `image-missing` icon fallback, the mnemonic-stripped label, the badge label
-// and its screen-reader description, and the SELECTION — which is
-// `ViewSwitcherState` over the wave-1 `ViewStackState`, so this element and the
-// NativeScript twin share one set of guards and one set of conformance vectors
-// (`@gjsify/adwaita-core/conformance`). This file is the DOM half only.
+// Everything that decides WHAT to show is HEADLESS, in `@gjsify/adwaita-core`
+// (ADR 0004): `ViewSwitcherState` over the wave-1 `ViewStackState`, so this
+// element and the NativeScript twin share one set of guards and one set of
+// conformance vectors. This file is the DOM half only.
 //
-// What the lift fixed here, all of it C-derived:
-//   - a page with neither title nor icon rendered an empty, clickable,
-//     space-consuming tab; libadwaita hides the button outright
-//     (adw-view-switcher.c:178). An EMPTY title is NOT that case — it keeps its
-//     button, which is why `getAttribute` is no longer flattened with `?? ''`.
-//   - a page with no icon rendered no icon at all; libadwaita substitutes
-//     `image-missing` (adw-view-switcher-button.c:399-405).
-//   - `active="-1"` / `active="99"` were CLAMPED into range, so an out-of-range
-//     request silently switched pages; `adw_view_stack_pages_select_item`
-//     refuses (adw-view-stack.c:682-684).
-//   - `notify::visible-child` fired only for a click, never for a property or
-//     attribute set; C notifies on every path (adw-view-stack.c:1038-1039).
-//   - `notify::policy` was documented in this header and never dispatched.
-//   - the declared pages were harvested with an UNSCOPED querySelectorAll, so a
-//     nested switcher inside a page had its pages stolen by the outer one.
-//   - the 500 ms drag-hover auto-switch did not exist
-//     (adw-view-switcher-button.c:14, :58-96).
-//
-// Attributes:
-//   policy — 'wide' | 'narrow' (default 'narrow'). An unrecognised value is
-//     REJECTED and leaves the current policy alone, as `g_return_if_fail` does;
-//     removing the attribute restores the default.
-//   active — zero-based index of the selected PAGE. Out-of-range, negative and
-//     fractional values are refused and the attribute is reflected back to the
+// The C rules that are not visible in the DOM code:
+//   - a page with NEITHER title NOR icon has no button at all. An EMPTY title is not
+//     that case — it keeps its button, hence no `?? ''` flattening of `getAttribute`.
+//   - a page with no icon gets `image-missing`, not nothing.
+//   - an out-of-range, negative or fractional `active` is REFUSED, not clamped
+//     (`adw_view_stack_pages_select_item`), and the attribute is reflected back to the
 //     selection that actually holds.
-// Page attributes: name, title, icon-name, hidden (= AdwViewStackPage:visible),
-//   use-underline, badge-number, needs-attention.
-// Events:
-//   `notify::visible-child` (CustomEvent, bubbles,
-//     detail = { index, name, title, interactive }) on every selection change,
-//     including the auto-pick; `interactive` is false for a model-driven one.
-//   `notify::policy` (CustomEvent, bubbles, detail = { policy }).
+//   - `notify::visible-child` fires on EVERY path, property and attribute sets
+//     included, not only on a click.
+//   - a drag hovering a button auto-switches after 500 ms.
+//   - `policy` defaults 'narrow'; an unrecognised value is refused and leaves the
+//     current policy alone, removing the attribute restores the default.
+//
+// A page's `hidden` attribute is `AdwViewStackPage:visible` inverted. Both events
+// bubble; `notify::visible-child` carries `{ index, name, title, interactive }`, where
+// `interactive` is false for a model-driven change such as the auto-pick.
+//
 // Reference: refs/libadwaita/src/adw-view-switcher.c (AdwViewSwitcher behaviour)
 // Reference: refs/libadwaita/src/adw-view-switcher-button.c (AdwViewSwitcherButton)
 // Reference: refs/libadwaita/src/stylesheet/widgets/_view-switcher.scss
@@ -86,29 +68,19 @@ interface PageNodes {
 /**
  * A single page. Children of `<adw-view-switcher>`; consumed at connect time.
  *
- * Deliberately carries NO `observedAttributes`. It used to declare six of them
- * and no `attributeChangedCallback`, which is a dead declaration — the browser
- * computes the list and has nowhere to deliver to — so changing `badge-number`,
- * `title`, `icon-name` or `needs-attention` after connect did nothing at all,
- * where C rebinds on every page `notify` (adw-view-switcher.c:184-193, :223).
- *
- * A callback could not fix it either: the switcher consumes these elements at
- * connect and `replaceChildren`s them away, so a detached page has no `closest`
- * to reach its owner through. The switcher watches them with a `MutationObserver`
- * instead, which keeps working after the detach and needs nothing from this class.
+ * Deliberately carries NO `observedAttributes` and no `attributeChangedCallback`:
+ * the switcher consumes these elements at connect and `replaceChildren`s them
+ * away, so a detached page has no `closest` to reach its owner through. The
+ * switcher watches them with a `MutationObserver` instead — the DOM stand-in for
+ * the per-page `notify` C rebinds on.
  */
 export class AdwViewSwitcherPage extends HTMLElement {}
 
 export class AdwViewSwitcher extends HTMLElement {
     /**
-     * The dwell timer, injectable.
-     *
-     * It used to be `new ViewSwitcherState({ scheduler: domViewSwitcherScheduler })`
-     * inline, which left NOWHERE to hand a clock in — so
-     * `VIEW_SWITCHER_DRAG_VECTORS` was driven by the core suite alone, and the
-     * conformance header claimed all three suites drove it. `scheduler` is a
-     * property so a test can replace it before the element connects; the DOM one
-     * is the default, exactly as before.
+     * The dwell timer, injectable so a test can hand in a clock and drive
+     * `VIEW_SWITCHER_DRAG_VECTORS` against the real element. Replace it before the
+     * element connects.
      */
     scheduler: ViewSwitcherScheduler = domViewSwitcherScheduler;
     private _stateInstance: ViewSwitcherState | null = null;
@@ -136,11 +108,8 @@ export class AdwViewSwitcher extends HTMLElement {
 
     constructor() {
         super();
-        // Subscribing touches no attributes and no children, so it is legal in a
-        // custom element constructor — unlike anything DOM-shaped.
     }
 
-    /** The policy controlling the button layout ('wide' | 'narrow'). */
     get policy(): AdwViewSwitcherPolicy {
         return this._policy;
     }
@@ -159,7 +128,6 @@ export class AdwViewSwitcher extends HTMLElement {
         this._reflectActive();
     }
 
-    /** Name of the selected page, `''` when nothing is selected. */
     get visibleChildName(): string {
         return this._state.selectedName;
     }
@@ -168,7 +136,6 @@ export class AdwViewSwitcher extends HTMLElement {
         this._state.selectName(name);
     }
 
-    /** The resolved page records a bound layout can read. */
     get pages(): readonly AdwViewSwitcherPageInfo[] {
         return this._state.pages;
     }
@@ -176,7 +143,7 @@ export class AdwViewSwitcher extends HTMLElement {
     /**
      * Show or hide a page (`AdwViewStackPage:visible`). Returns whether the
      * SELECTION moved — hiding the selected page falls back to the first still
-     * visible one (adw-view-stack.c:1061-1082).
+     * visible one.
      */
     setPageVisible(name: string, visible: boolean): boolean {
         const moved = this._state.setPageVisible(name, visible);
@@ -186,25 +153,21 @@ export class AdwViewSwitcher extends HTMLElement {
 
     connectedCallback() {
         if (this._initialized) {
-            // Re-entering a document. `disconnectedCallback` drops the page
-            // observer on the way out, and this early return used to skip
-            // rebuilding it — so a switcher that had merely been MOVED (a
-            // slideshow slide, a client-side route change) stopped noticing
-            // page attribute changes for good, and did it silently.
+            // Re-entering a document: `disconnectedCallback` drops the page observer on
+            // the way out, so a switcher that was merely MOVED (a slideshow slide, a
+            // route change) has to get it back here or it stops noticing page changes.
             this._watchPages();
             return;
         }
 
-        // `:scope >` rather than a subtree scan: an unscoped query let an outer
-        // switcher adopt the pages of a nested one, since both use the same tag.
-        // Pages come from the stack's OWN children in C (adw-view-switcher.c:203).
+        // `:scope >`, not a subtree scan: an unscoped query lets an outer switcher
+        // adopt a nested one's pages, since both use the same tag. Pages come from
+        // the stack's OWN children in C.
         const declared = Array.from(this.querySelectorAll(':scope > adw-view-switcher-page')) as HTMLElement[];
-        // Read the declared selection BEFORE adopting any page: the auto-pick
-        // reflects its own index back into this very attribute.
+        // Read BEFORE adopting any page: the auto-pick reflects its own index back
+        // into this very attribute.
         const declaredActive = this.getAttribute('active');
 
-        // The single `viewswitcher` node holds the segmented button bar; a
-        // sibling content area shows the selected page.
         this._barEl = document.createElement('div');
         this._barEl.className = 'adw-view-switcher-bar';
         this._barEl.setAttribute('role', 'tablist');
@@ -232,19 +195,18 @@ export class AdwViewSwitcher extends HTMLElement {
     }
 
     disconnectedCallback() {
-        // A drag that leaves with the element would otherwise switch pages after
-        // the widget is gone; C drops the source in dispose the same way.
+        // A drag that leaves with the element would otherwise switch pages after the
+        // widget is gone; C drops the source in dispose the same way.
         this._state.cancelDrag();
         this._pageObserver?.disconnect();
         this._pageObserver = undefined;
     }
 
     /**
-     * Re-read every declared page and push it into the state.
-     *
-     * Called by `AdwViewSwitcherPage.attributeChangedCallback`, which is what
-     * makes a runtime `badge-number` change reach the button. `setPages` keeps
-     * the selection where it can, so this is a repaint and not a reset.
+     * Re-read every declared page and push it into the state. Driven by the
+     * `MutationObserver` in {@link _watchPages}, which is what makes a runtime
+     * `badge-number` change reach the button. `setPages` keeps the selection where it
+     * can, so this is a repaint and not a reset.
      */
     refreshPages(): void {
         if (!this._initialized) return;
@@ -253,18 +215,12 @@ export class AdwViewSwitcher extends HTMLElement {
     }
 
     /**
-     * Watch the declared pages for attribute changes.
-     *
-     * A `MutationObserver` rather than an `attributeChangedCallback` on the page:
-     * the switcher consumes those elements at connect and `replaceChildren`s them
-     * out of the tree, so a detached page cannot find its owner — but an observer
-     * bound to it keeps firing. This is the DOM's `notify::` on
-     * `AdwViewStackPage`, which the C's `update_button` handler binds per page
-     * (adw-view-switcher.c:184-193).
+     * Watch the declared pages for attribute changes — the DOM's `notify::` on
+     * `AdwViewStackPage`, which C's `update_button` binds per page. See
+     * {@link AdwViewSwitcherPage} for why an observer and not a callback.
      *
-     * It delivers on a MICROTASK where GTK's notify is synchronous. That is the
-     * DOM's contract for watching a node, it is invisible to a user, and nothing
-     * in this element reads the button back inside the setter.
+     * MODIFICATION: delivers on a MICROTASK where GTK's notify is synchronous —
+     * invisible to a user, and nothing here reads the button back inside a setter.
      */
     private _watchPages(): void {
         this._pageObserver?.disconnect();
@@ -299,9 +255,8 @@ export class AdwViewSwitcher extends HTMLElement {
         button.className = 'adw-view-switcher-button';
         button.setAttribute('role', 'tab');
 
-        // Both children always exist, exactly as AdwViewSwitcherButton's template
-        // does — the icon carries the `image-missing` fallback rather than
-        // disappearing (adw-view-switcher-button.ui).
+        // Both children always exist, as in AdwViewSwitcherButton's template — the icon
+        // carries `image-missing` rather than disappearing.
         const icon = createAdwIcon(null, 'adw-view-switcher-icon');
 
         const label = document.createElement('span');
@@ -315,16 +270,12 @@ export class AdwViewSwitcher extends HTMLElement {
         button.addEventListener('click', () => {
             this._state.setSelected(index);
         });
-        // GtkDropControllerMotion's enter/leave, which drive TIMEOUT_EXPAND.
-        //
-        // The `relatedTarget` test is the whole point: this button contains an
-        // icon and a label, and the DOM fires `dragleave` + `dragenter` when the
-        // pointer crosses BETWEEN them. `ViewSwitcherDragSwitch.leave` clears the
-        // dwell timer and `enter` re-arms a fresh 500ms, so a drag that merely
-        // slid from the icon to the label restarted the countdown and the page
-        // never switched. C has one `GtkDropControllerMotion` per BUTTON
-        // (adw-view-switcher-button.c:79-96), which has no such internal edges —
-        // `relatedTarget` containment is that same "did we really leave" test.
+        // GtkDropControllerMotion's enter/leave, which drive TIMEOUT_EXPAND. The
+        // `relatedTarget` containment test is load-bearing: the button contains an icon
+        // and a label, and the DOM fires `dragleave` + `dragenter` when the pointer
+        // crosses BETWEEN them. Since `leave` clears the dwell timer and `enter` re-arms
+        // a fresh 500 ms, an untested crossing restarts the countdown forever. C's one
+        // `GtkDropControllerMotion` per BUTTON has no such internal edges.
         button.addEventListener('dragenter', (event) => {
             if (button.contains((event as DragEvent).relatedTarget as Node | null)) return;
             this._state.dragEnter(index);
@@ -344,9 +295,9 @@ export class AdwViewSwitcher extends HTMLElement {
 
     private _readPolicyAttr(): AdwViewSwitcherPolicy {
         const raw = this.getAttribute('policy');
-        // A removed attribute falls back to the C default; an unrecognised value
-        // is refused and keeps the current policy (adw_view_switcher_set_policy
-        // is reached only through the enum, which rejects garbage).
+        // A removed attribute falls back to the C default; an unrecognised value is
+        // refused and keeps the current policy, since `adw_view_switcher_set_policy` is
+        // reached only through the enum, which rejects garbage.
         if (raw === null) return 'narrow';
         return isViewSwitcherPolicy(raw) ? raw : this._policy;
     }
@@ -369,8 +320,7 @@ export class AdwViewSwitcher extends HTMLElement {
     private _render(): void {
         if (!this._initialized) return;
 
-        // The single `viewswitcher` node carries the policy style class
-        // (adw-view-switcher.c:539-545).
+        // The single `viewswitcher` node carries the policy style class.
         for (const policy of VIEW_SWITCHER_POLICIES) this.classList.toggle(policy, policy === this._policy);
 
         const models = buildViewSwitcherButtons(this._state.pages, this._state.selected, this._policy);

package/src/elements/adw-window-title.ts

@@ -9,11 +9,11 @@
 // `@gjsify/adwaita-nativescript` composes the same state, so both ports share one
 // behaviour. Three rules from adw-window-title.c that neither renderer had:
 //   - the TITLE label hides when the title is empty (C:207-208; the template even
-//     starts it `visible=False`, adw-window-title.ui:15). Only the subtitle was
+//     starts it `visible=False`). Only the subtitle was
 //     ever hidden here, so a header bar with a subtitle and no title reserved a
 //     blank title line above it.
-//   - setting the value it already has returns early (C:203-204, :244-245).
-//   - a real change notifies (C:210, :251).
+//   - setting the value it already has returns early (C:203-204).
+//   - a real change notifies (C:210).
 //
 // Reference: refs/adwaita-web/adwaita-web/docs/widgets/windowtitle.md
 // Reference: refs/libadwaita/src/adw-window-title.c, adw-window-title.ui
@@ -56,7 +56,7 @@ export class AdwWindowTitle extends HTMLElement {
         if (!this._initialized) return;
         const changed = name === 'title' ? this._state.setTitle(value) : this._state.setSubtitle(value);
         // The early-return is the whole point: re-setting the same value paints
-        // nothing and notifies nothing (C:203-204, :244-245).
+        // nothing and notifies nothing (C:203-204).
         if (!changed) return;
         this._render();
         this.dispatchEvent(