@gjsify/adwaita-web 0.53.0 → 0.55.0

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

@@ -0,0 +1,332 @@
+// <adw-view-switcher-sidebar> — an adaptive sidebar that drives an `<adw-view-stack>`
+// (the web counterpart of Adw.ViewSwitcherSidebar, libadwaita 1.9). It is an
+// `<adw-sidebar>` filled from the stack's page list, which is the whole difference
+// from every other Adw switcher: the pages can be GROUPED into sections, each row
+// carries an icon, a title and an unread dot or a badge, and the whole thing collapses
+// from a sidebar into a page of boxed lists (`mode`).
+//
+// It is a COMPOSITE and it says so: this element owns one `<adw-sidebar>` and drives it
+// from the stack, rather than reimplementing a sidebar. The rows, the section headers,
+// the selection, the filter and the empty state are the `<adw-sidebar>` element's; what
+// lives here is the C half — `populate_sidebar`, `activated_cb` and the properties.
+//
+// THE RULES THAT ARE C AND NOT MARKUP (adw-view-switcher-sidebar.c):
+//
+//   · `populate_sidebar` (:225-249): a page with `starts-section` opens a section and the
+//     one before it is flushed; the FIRST page opens a section whatever it says, because
+//     the test is `if (!section || get_starts_section (page))`; and the heading is the
+//     opening page's `section-title`. The grouping itself is core's
+//     {@link viewSwitcherSidebarSections}, pinned by the conformance vectors.
+//   · `add_item` (:184-206): each item's title, icon, use-underline and visibility are BOUND
+//     to the page's, so a later change reaches the row without a rebuild here.
+//   · `update_badge` (:133-181): no attention and no count means NO indicator at all; a
+//     count replaces the dot with a label capped at `999+` (`> 999`, so 999 prints); and
+//     `.needs-attention` rides on the bin whether or not there is a number. The bin is the
+//     item's `suffix`, which is what `<adw-sidebar>`'s `badge-number` /`needs-attention`
+//     attributes spell.
+//   · `activated_cb` (:104-112): activating a row selects the stack page at the SAME index
+//     and only then emits `activated` — the signal an `Adw.NavigationSplitView` listens to
+//     in order to reveal its content pane, so firing it before the selection moved would
+//     reveal the previous page.
+//   · `selection_changed_cb` (:258-271): the row follows the stack, not the other way round,
+//     which is what keeps a programmatic `visible-child-name` write highlighted.
+//
+// `stack`, `filter`, `placeholder`, `prefix` and `suffix` are all widget- or object-valued
+// properties: `stack` is an element id in the attribute and an element in the property,
+// `filter` is a property (a function, which no attribute can carry), and the three widget
+// ones are `slot="…"` children — the `AdwTabPage:child` rule, because a `.blp`'s
+// `placeholder: …` authors a slot.
+//
+// A11Y: `<adw-sidebar>` carries `role="listbox"`, so the host adds nothing; the sections
+// are headings inside it, and the C signal has no row identity of its own to forward.
+//
+// KNOWN_GAPS: none — `mode` is this widget's only scalar property and it is observed.
+//
+// Reference: refs/libadwaita/src/adw-view-switcher-sidebar.c (populate_sidebar,
+//   add_item, update_badge, activated_cb, selection_changed_cb, the six pspecs)
+// Reference: refs/libadwaita/src/adw-sidebar.c (the widget it drives)
+// Reference: refs/libadwaita/src/stylesheet/widgets/_sidebars.scss:250-277
+//   (`view-switcher-sidebar .indicator`)
+// Copyright (c) 2025 GNOME Foundation Inc. (libadwaita). LGPLv2.1-or-later.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web; the sidebar it
+// drives is a real `<adw-sidebar>` and the icon nodes are <gtk-image>.
+
+import { viewSwitcherPagesFromStack, viewSwitcherSidebarSections } from '@gjsify/adwaita-core';
+import type { AdwSidebarItemSpec, AdwSidebarSectionSpec, SidebarItemFilter } from '@gjsify/adwaita-core';
+
+import { bindSlottedChildren } from '../slotted-children.js';
+import type { AdwSidebar } from './adw-sidebar.js';
+import type { AdwViewStack } from './adw-view-stack.js';
+
+export class AdwViewSwitcherSidebar extends HTMLElement {
+    private _sidebar!: AdwSidebar;
+    private _placeholderEl!: HTMLDivElement;
+    private _prefixEl!: HTMLDivElement;
+    private _suffixEl!: HTMLDivElement;
+    private _stack: AdwViewStack | null = null;
+    private _filter: SidebarItemFilter | null = null;
+    private _initialized = false;
+
+    static get observedAttributes() {
+        return ['stack', 'mode'];
+    }
+
+    /** `AdwViewSwitcherSidebar:stack` — the stack the sidebar controls. */
+    get stack(): AdwViewStack | null {
+        return this._stack;
+    }
+
+    set stack(value: AdwViewStack | string | null) {
+        this.setStack(value === null ? null : typeof value === 'string' ? this._resolveStack(value) : value);
+    }
+
+    /**
+     * `adw_view_switcher_sidebar_set_stack`: unbind the old stack's four connections, bind
+     * the new one's, and populate. A NULL stack is refused, exactly as C is
+     * (`g_return_if_fail (!stack)`, :284) — an overview-less sidebar is not a state the C
+     * has, and inventing one here would give a reader a widget libadwaita cannot build.
+     */
+    setStack(stack: AdwViewStack | null): void {
+        if (stack === null) return;
+        if (this._stack === stack) return;
+        this._unbindStack();
+        this._stack = stack;
+        this._bindStack();
+        this._populate();
+        this._syncSelection();
+        this.dispatchEvent(new CustomEvent('notify::stack', { bubbles: true, detail: { stack } }));
+    }
+
+    /** `AdwViewSwitcherSidebar:mode` — `sidebar` (default) or `page`. */
+    get mode(): 'sidebar' | 'page' {
+        return this.getAttribute('mode') === 'page' ? 'page' : 'sidebar';
+    }
+
+    set mode(value: 'sidebar' | 'page') {
+        this.setAttribute('mode', value);
+    }
+
+    /**
+     * `AdwViewSwitcherSidebar:filter` — a `GtkFilter`, which on this renderer is the
+     * sidebar's own predicate. A property and not an attribute: it is a FUNCTION, and
+     * markup cannot carry one.
+     */
+    get filter(): SidebarItemFilter | null {
+        return this._filter;
+    }
+
+    set filter(value: SidebarItemFilter | null) {
+        this._filter = value;
+        if (this._initialized) {
+            this._sidebar.filter = value;
+            this._applyEmptyState();
+        }
+    }
+
+    /** `AdwViewSwitcherSidebar:placeholder` — shown when no item survives. */
+    get placeholder(): HTMLElement | null {
+        return this._placeholderEl.firstElementChild as HTMLElement | null;
+    }
+
+    set placeholder(value: HTMLElement | null) {
+        if (value === null) this._placeholderEl.replaceChildren();
+        else this._placeholderEl.replaceChildren(value);
+        this._applyEmptyState();
+    }
+
+    /**
+     * `AdwViewSwitcherSidebar:prefix` (1.10) — shown above the items.
+     *
+     * NOT `prefix`. `HTMLElement.prefix` is the RDFa attribute and a STRING, and a
+     * property of a different type cannot shadow it (TS2416). The GIR name is kept in the
+     * SLOT (`slot="prefix"`, what a `.blp`'s `prefix: …` authors) and here in the header.
+     */
+    get prefixWidget(): HTMLElement | null {
+        return this._prefixEl.firstElementChild as HTMLElement | null;
+    }
+
+    set prefixWidget(value: HTMLElement | null) {
+        if (value === null) this._prefixEl.replaceChildren();
+        else this._prefixEl.replaceChildren(value);
+    }
+
+    /** `AdwViewSwitcherSidebar:suffix` (1.10) — shown below the items. `suffixWidget`, as `prefixWidget`. */
+    get suffixWidget(): HTMLElement | null {
+        return this._suffixEl.firstElementChild as HTMLElement | null;
+    }
+
+    set suffixWidget(value: HTMLElement | null) {
+        if (value === null) this._suffixEl.replaceChildren();
+        else this._suffixEl.replaceChildren(value);
+    }
+
+    connectedCallback() {
+        if (this._initialized) {
+            this._bindStack();
+            this._populate();
+            return;
+        }
+        this._initialized = true;
+
+        this._prefixEl = document.createElement('div');
+        this._prefixEl.className = 'view-switcher-sidebar-prefix';
+        this._suffixEl = document.createElement('div');
+        this._suffixEl.className = 'view-switcher-sidebar-suffix';
+        this._placeholderEl = document.createElement('div');
+        this._placeholderEl.className = 'view-switcher-sidebar-placeholder';
+        this._placeholderEl.hidden = true;
+
+        // The widget C composes (`adw_view_switcher_sidebar_init`, :555-560): an
+        // `AdwSidebar`, parented to the widget, with `activated` re-emitted.
+        this._sidebar = document.createElement('adw-sidebar') as AdwSidebar;
+        this._sidebar.addEventListener('activated', this._onSidebarActivated);
+
+        const box = document.createElement('div');
+        box.className = 'view-switcher-sidebar-box';
+        box.append(this._sidebar, this._placeholderEl);
+
+        // `placeholder`, `prefix` and `suffix` are widget PROPERTIES, so a `.blp`'s
+        // `placeholder: …` authors `slot="placeholder"` — the rule `adw-tab-page` states.
+        // `install` is what routes the author's children out BEFORE the host is emptied,
+        // and it takes the structure this element owns; a bare `replaceChildren` here
+        // would destroy every declared slotted child.
+        bindSlottedChildren(this, [
+            { name: 'placeholder', into: this._placeholderEl },
+            { name: 'prefix', into: this._prefixEl },
+            { name: 'suffix', into: this._suffixEl },
+        ]).install(this._prefixEl, box, this._suffixEl);
+        this._applyMode();
+
+        const declared = this.getAttribute('stack');
+        this.setStack(declared === null ? this._findStack() : this._resolveStack(declared));
+        // A widget with NO stack is C's own starting state (`set_stack` refuses NULL, so
+        // `populate_sidebar` never ran) and it reads as the empty sidebar plus the
+        // placeholder — which only `_applyEmptyState` decides.
+        this._applyEmptyState();
+    }
+
+    disconnectedCallback() {
+        this._unbindStack();
+    }
+
+    attributeChangedCallback(name: string, _old: string | null, value: string | null) {
+        if (!this._initialized) return;
+        if (name === 'stack') this.setStack(value === null ? this._findStack() : this._resolveStack(value));
+        else if (name === 'mode') this._applyMode();
+    }
+
+    private _resolveStack(ref: string): AdwViewStack | null {
+        return (document.getElementById(ref) as AdwViewStack | null) ?? this._findStack();
+    }
+
+    /** The stack this sidebar is next to, when the author named no id. */
+    private _findStack(): AdwViewStack | null {
+        const parent = this.parentElement;
+        return (parent?.querySelector('adw-view-stack') as AdwViewStack | null) ?? null;
+    }
+
+    /** `set_stack`'s four connections (:270-282), read off the stack's own events. */
+    private _bindStack(): void {
+        this._unbindStack();
+        for (const type of STACK_EVENTS) this._stack?.addEventListener(type, this._onStackChange);
+    }
+
+    private _unbindStack(): void {
+        for (const type of STACK_EVENTS) this._stack?.removeEventListener(type, this._onStackChange);
+    }
+
+    private _onStackChange = (): void => {
+        this._populate();
+        this._syncSelection();
+    };
+
+    /**
+     * `activated_cb` (:104-112) — the row's index is the stack's index, so the two lists
+     * are kept one for one. The selection moves FIRST: `activated` is the signal a split
+     * view reveals its content pane on, and a handler that read the stack in that callback
+     * would otherwise see the page the user was leaving.
+     */
+    private _onSidebarActivated = (event: Event): void => {
+        // The `<adw-sidebar>` is an IMPLEMENTATION DETAIL of this composite — the widget C
+        // parents in `adw_view_switcher_sidebar_init` is private, and only `activated` is
+        // re-emitted from it. Its own event bubbles, so without this a listener on the
+        // host sees the inner one AND the re-emission, and `index` arrives twice.
+        event.stopPropagation();
+        const index = (event as CustomEvent).detail.index as number;
+        const stack = this._stack;
+        if (stack === null) return;
+        stack.selectNthPage(index);
+        this.dispatchEvent(new CustomEvent('activated', { bubbles: true, detail: { index } }));
+    };
+
+    /**
+     * `populate_sidebar` (:225-249) — one `AdwSidebarSection` per group of pages, each
+     * holding one `AdwSidebarItem` per page. The grouping is core's, so the browser and
+     * any second renderer derive the sections from the same table.
+     */
+    private _populate(): void {
+        const stack = this._stack;
+        if (stack === null) {
+            this._sidebar.sections = [];
+            this._applyEmptyState();
+            return;
+        }
+        const pages = viewSwitcherPagesFromStack(stack.pages);
+        this._sidebar.sections = viewSwitcherSidebarSections(pages).map((section) => this._toSectionSpec(section));
+        this._applyEmptyState();
+    }
+
+    private _toSectionSpec(section: ReturnType<typeof viewSwitcherSidebarSections>[number]): AdwSidebarSectionSpec {
+        const items: AdwSidebarItemSpec[] = section.pages.map((page) => ({
+            // `g_object_bind_property (page, "title", item, "title", …)`: the row shows the
+            // page's title, never a resolved fallback — `createViewSwitcherPage` has already
+            // resolved it against the page NAME, which is what C binds too.
+            title: page.title ?? '',
+            iconName: page.iconName ?? '',
+            visible: page.visible,
+            badgeNumber: page.badgeNumber,
+            needsAttention: page.needsAttention,
+        }));
+        // `section-title` bound to the SECTION's title; an empty one is the separator
+        // header, which is `<adw-sidebar-section>`'s own rule (`update_header_page_cb`).
+        return { title: section.title, items };
+    }
+
+    /**
+     * `selection_changed_cb` (:258-271) — the row follows the stack's visible page. Read as
+     * the INDEX, because the sidebar's flat index space is the unfiltered one (ADR 0004),
+     * so page position and row position are the same number.
+     */
+    private _syncSelection(): void {
+        const stack = this._stack;
+        if (stack === null) return;
+        const index = stack.visibleChildIndex;
+        if (index < 0) return;
+        if (this._sidebar.selected !== index) this._sidebar.selected = index;
+    }
+
+    private _applyMode(): void {
+        const page = this.mode === 'page';
+        this.classList.toggle('page', page);
+        this._sidebar.mode = this.mode;
+    }
+
+    /**
+     * `placeholder` (:449-460) — shown when the sidebar has no items, or when the filter
+     * took them all. The `<adw-sidebar>` knows the filtered list (`visibleItems` is empty),
+     * which is the C condition in `AdwSidebar`'s own words.
+     */
+    private _applyEmptyState(): void {
+        // `<adw-sidebar>`'s OWN answer, which counts the FILTERED model — the condition
+        // `update_placeholder` binds the placeholder to. Counting the DOM rows here would
+        // find them all still standing, because a filter HIDES a row and never removes it.
+        const empty = this._sidebar.classList.contains('empty');
+        this._placeholderEl.hidden = !empty;
+        this.classList.toggle('empty', empty);
+    }
+}
+
+/** The stack signals `set_stack` connects to: the page list, its sections and the selection. */
+const STACK_EVENTS = ['items-changed', 'notify::visible-child'] as const;
+
+customElements.define('adw-view-switcher-sidebar', AdwViewSwitcherSidebar);

package/src/elements/adw-window.ts

@@ -1,17 +1,191 @@
-// <adw-window> — Adwaita application window frame.
-// Provides rounded corners, shadow, and flex column layout.
-// Adapted from Adwaita Web UI Framework (https://github.com/mclellac/adwaita-web).
-// Copyright (c) 2025 csm. MIT License.
-// Modifications: Reimplemented as Web Component for @gjsify/adwaita-web.
+// <adw-window> — the web counterpart of Adw.Window: a freeform window with no
+// titlebar area. Adw.Window styles nothing itself — you pair it with
+// Adw.ToolbarView and an Adw.HeaderBar (or a Gtk.HeaderBar) to get the chrome —
+// so this element owns the FRAME and the window's own state, and the chrome is
+// whatever you put in it.
+//
+// THE FRAME IS IN-PAGE, and that is the whole difference from GTK. A document has
+// no window manager, so this element is a box on the page, not a toplevel: no
+// titlebar, no `.tiled`/`.maximized`/`.solid-csd` decoration classes, no focus
+// stealing on present. What IS ported is the frame libadwaita draws for a CSD
+// window (border-radius, the three-layer shadow, the 1px outline), the size
+// request GTK makes for an AdwWindow, the content property, the breakpoints and
+// the open-dialog bookkeeping.
+//
+// Children are placed in the content area (the Adw.Window:content property).
+// The window supports breakpoints via addBreakpoint() and tracks open dialogs
+// presented inside it. The default size is 360×200, matching the C source.
+//
+// Attributes:
+//   width, height — the size REQUEST in px, the one `gtk_widget_set_size_request
+//     (GTK_WIDGET (self), 360, 200)` makes in adw_window_init (C:344). Absent, the
+//     element keeps that default; an explicit attribute overrides it.
+//
+// Properties: `content` (the Adw.Window:content child), `breakpoints`,
+// `currentBreakpoint` (Adw.Window:current-breakpoint), `dialogs` and
+// `visibleDialog` (Adw.Window:dialogs / :visible-dialog), `contentArea`.
+//
+// NOT PORTED: `adaptive-preview` — a debug mode that lets you resize the window to
+// a set of device sizes, opened from GTK Inspector or Ctrl+Shift+M. A browser has
+// no inspector and no device to simulate; a CSS media query does the same job and
+// the breakpoints below are how libadwaita itself does it. Ledgered in KNOWN_GAPS.
+//
+// Reference: refs/libadwaita/src/adw-window.c (AdwWindow behaviour)
+// Reference: refs/libadwaita/src/stylesheet/widgets/_window.scss (window frame)
+// Copyright (c) 2020-2023 Alice Mikhaylenko / Purism SPC (libadwaita). LGPLv2.1+
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+import { AdwBreakpoint } from '@gjsify/adwaita-core';
+import { addBreakpoints } from '../breakpoints.js';
+import { bindSlottedChildren } from '../slotted-children.js';
+
+/** The default minimum size of an AdwWindow, from adw_window_init (C:344). */
+const DEFAULT_WIDTH = 360;
+const DEFAULT_HEIGHT = 200;
 
 export class AdwWindow extends HTMLElement {
+    private _initialized = false;
+    private _contentEl!: HTMLDivElement;
+    private _breakpoints: AdwBreakpoint[] = [];
+    private _disposeBreakpoints: (() => void) | null = null;
+    private _openDialogs: HTMLElement[] = [];
+
+    static get observedAttributes() {
+        return ['width', 'height'];
+    }
+
+    /** The content area — the Adw.Window:content property. */
+    get contentArea(): HTMLDivElement {
+        return this._contentEl;
+    }
+
+    /** The content widget — the first child of the content area. */
+    get content(): HTMLElement | null {
+        return this._contentEl.firstElementChild as HTMLElement | null;
+    }
+
+    set content(value: HTMLElement | null) {
+        if (value) {
+            this._contentEl.appendChild(value);
+        }
+    }
+
+    /** The breakpoints added to this window. */
+    get breakpoints(): readonly AdwBreakpoint[] {
+        return this._breakpoints;
+    }
+
+    /** The currently applied breakpoint, or null when none is. */
+    get currentBreakpoint(): AdwBreakpoint | null {
+        return this._breakpoints.find((bp) => bp.applied) ?? null;
+    }
+
+    /** The open dialogs presented inside this window (Adw.Window:dialogs). */
+    get dialogs(): readonly HTMLElement[] {
+        // A dialog taken out of the document never raises `notify::open` on the way
+        // out, so a dialog that was REMOVED while open would otherwise stay listed
+        // for the rest of the window's life.
+        this._openDialogs = this._openDialogs.filter((dialog) => dialog.isConnected);
+        return this._openDialogs;
+    }
+
+    /** The currently visible dialog, or null when none is (Adw.Window:visible-dialog). */
+    get visibleDialog(): HTMLElement | null {
+        const dialogs = this.dialogs;
+        return dialogs.length > 0 ? (dialogs[dialogs.length - 1] as HTMLElement) : null;
+    }
+
+    /**
+     * Add a breakpoint to this window (adw_window_add_breakpoint).
+     * The breakpoint evaluates against the window's own box and sets a
+     * `data-breakpoint` attribute when applied.
+     */
+    addBreakpoint(condition: string): AdwBreakpoint {
+        const bp = new AdwBreakpoint(condition, {
+            onApply: () => (this.dataset.breakpoint = condition),
+            onUnapply: () => {
+                if (this.dataset.breakpoint === condition) delete this.dataset.breakpoint;
+            },
+        });
+        this._breakpoints.push(bp);
+        // Re-evaluated against a box that may have changed since the last add.
+        this._bindBreakpoints();
+        return bp;
+    }
+
     connectedCallback() {
-        // Light DOM: children remain in place, element itself is the styled container.
-        // Set dimensions from attributes if provided.
-        const w = this.getAttribute('width');
-        const h = this.getAttribute('height');
-        if (w) this.style.width = `${w}px`;
-        if (h) this.style.height = `${h}px`;
+        this._buildOnce();
+        // EVERY connect, not only the first — see `_bindBreakpoints`.
+        this._bindBreakpoints();
+    }
+
+    disconnectedCallback() {
+        this._disposeBreakpoints?.();
+        this._disposeBreakpoints = null;
+    }
+
+    attributeChangedCallback(name: string) {
+        // The size request is read from the ATTRIBUTE, so it is applied on every
+        // change — including one that arrived before the element was connected, which
+        // is the ordinary case for markup already sitting in a document.
+        if (name === 'width' || name === 'height') this._applySizeRequest();
+    }
+
+    private _buildOnce() {
+        if (this._initialized) return;
+        this._initialized = true;
+
+        this._applySizeRequest();
+
+        this._contentEl = document.createElement('div');
+        this._contentEl.className = 'adw-window-content';
+
+        // Children are the content — the Adw.Window buildable default, and `content` is
+        // ALSO its name, because a `.blp` writes `content:` on the window and an authored
+        // tree needs the name to route it: `refuseUnknownSlots` in
+        // `src/shared-tree-builder.ts` throws on a slot a defined element does not
+        // declare, and `showcases/gtk/effect-adw-services/src/window.blp` is rooted at
+        // one. The content area becomes the host's own child, so a child appended later
+        // lands in it too (`bindSlottedChildren` is LIVE, see `src/slotted-children.ts`).
+        bindSlottedChildren(this, [{ name: 'content', into: this._contentEl }, { into: this._contentEl }]).install(
+            this._contentEl,
+        );
+
+        // Track open dialogs presented inside this window: an AdwDialog raises
+        // `notify::open`, which bubbles to here.
+        this.addEventListener('notify::open', (e) => {
+            const dialog = e.target as HTMLElement;
+            if (dialog === this) return;
+            if (dialog.hasAttribute('open')) {
+                if (!this._openDialogs.includes(dialog)) this._openDialogs.push(dialog);
+            } else {
+                this._openDialogs = this._openDialogs.filter((d) => d !== dialog);
+            }
+        });
+    }
+
+    /**
+     * Bind the breakpoints to THIS box.
+     *
+     * NOT once per lifetime: `disconnectedCallback` releases the disposer, so a
+     * window moved between parents would come back deaf — and a window is exactly
+     * the thing a client-side route change re-parents. Re-binding is cheap and
+     * idempotent, and it re-measures the new box on the way.
+     */
+    private _bindBreakpoints() {
+        this._disposeBreakpoints?.();
+        this._disposeBreakpoints = null;
+        if (this._initialized && this._breakpoints.length > 0) {
+            this._disposeBreakpoints = addBreakpoints(this, this._breakpoints);
+        }
+    }
+
+    /** The window's size request — GTK's, not CSS's, so an absent attribute means the default. */
+    private _applySizeRequest() {
+        const width = this.getAttribute('width');
+        const height = this.getAttribute('height');
+        this.style.width = width ? `${width}px` : `${DEFAULT_WIDTH}px`;
+        this.style.height = height ? `${height}px` : `${DEFAULT_HEIGHT}px`;
     }
 }
 

package/src/elements/checks.ts

@@ -17,12 +17,36 @@
 //   - {@link resolveCheckState} — indeterminate outranks checked, read off the cascade
 //     in libadwaita's `_checks.scss`, and what `aria-checked` needs.
 //
-// NOT DERIVED FROM GTK. `GtkCheckButton` is a GTK widget and libadwaita has no
-// `adw-checkbox.c`, so its group semantics (`gtk_check_button_set_group`, whether a
-// fresh group starts with a member active) and the exact meaning of
-// `GtkCheckButton:inconsistent` are not guessed at. Where a rule was needed the HTML
-// one is used and cited as such — clearing `indeterminate` on activation is the HTML
-// pre-click activation step, not a reading of GTK.
+// WHAT C SAYS, NOW THAT IT IS READABLE. `GtkCheckButton` is a GTK widget and libadwaita
+// has no `adw-checkbox.c`, so everything here is read off
+// `refs/gtk/gtk/gtkcheckbutton.c`:
+//
+//   · The state attribute is `checked`, not GIR's `active` (gtkcheckbutton.c:647-658),
+//     and the third state is `indeterminate`, not GIR's `inconsistent` (:680-691) — the
+//     CSS node GTK raises is `GTK_STATE_FLAG_INCONSISTENT` (:871-880) and libadwaita
+//     styles `.adw-check-indicator:indeterminate`, so the browser names both states the
+//     way the cascade reads them.
+//   · `inconsistent` OUTRANKS `active`, and that is not an inference:
+//     `update_accessible_state` tests inconsistent first and only then active
+//     (:409-426). {@link resolveCheckState} is that order.
+//   · A grouped check button is a check button with `group` set: GTK then names the
+//     indicator node `radio` instead of `check` and raises
+//     `GTK_ACCESSIBLE_ROLE_RADIO` on BOTH members (gtkcheckbutton.c:99-108, :1115,
+//     :1140-1141) — which is why `<adw-radio>` is this same class with a different
+//     `inputType`.
+//   · The active member of a group cannot be clicked off: both the gesture handler and
+//     `real_activate` return early when the button is active AND has a group neighbour
+//     (:395-396, :617-622). `<adw-radio>` gets this from `RadioGroupState`, and
+//     `<gtk-check-button>` cannot reach a group at all here.
+//
+// ONE PLACE THIS PORT DIVERGES, DELIBERATELY AND CITED. GTK does NOT clear
+// `inconsistent` when the user activates the button — `real_activate` only flips
+// `active` (gtkcheckbutton.c:617-628) and the property's own documentation says turning
+// the inconsistent state off again "has to be done manually" (:855-856). HTML's
+// pre-click activation steps clear `indeterminate` before the toggle, and this element
+// wraps a real `<input>`, so the clear happens for us. That is the HTML spec's rule, not
+// a reading of GTK, and it is the one behaviour an application cannot observe a
+// difference over: the result is a definite state either way.
 //
 // NAMING. The state attribute is `checked`, not GtkCheckButton's `active`:
 // these elements wrap a real `<input>`, `checked` is the spelling every author
@@ -53,9 +77,11 @@
 // indeterminate state announces as `mixed` for BOTH — HTML has a native mixed
 // checkbox (`input.indeterminate`) but no mixed radio.
 //
+// Reference: refs/gtk/gtk/gtkcheckbutton.c:99-112,395-426,617-628,647-714,773-774,849-886,925-974
 // Reference: refs/libadwaita/src/stylesheet/widgets/_checks.scss
 // Reference: refs/adwaita-web/adwaita-web/scss/{_checkbox,_radio}.scss
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Copyright (c) The GTK Team. LGPLv2.1+.
 // Copyright (c) 2025 csm (adwaita-web). MIT License.
 // Modifications: Implemented as Web Components for @gjsify/adwaita-web.
 
@@ -211,8 +237,9 @@ export class GtkCheckButton extends AdwCheckBase {
 
     protected activate(): void {
         // HTML's pre-click activation steps clear `indeterminate` before the toggle, so a
-        // user can always reach a definite state. That rule is the HTML spec's, not a
-        // reading of `GtkCheckButton:inconsistent`.
+        // user can always reach a definite state. GTK does NOT: `gtk_check_button_real_activate`
+        // only flips `active` (gtkcheckbutton.c:617-628) and says turning the inconsistent
+        // state off again "has to be done manually" (:855-856). This is the HTML rule.
         this.indeterminate = false;
         this.checked = !this.checked;
     }