@gjsify/adwaita-web 0.31.0 → 0.33.0

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

@@ -1,90 +1,210 @@
 // <adw-view-switcher> — An adaptive, tab-style switcher driving a set of named
-// pages (the web counterpart of Adw.ViewSwitcher paired with an Adw.ViewStack).
-// Pages are declared as <adw-view-switcher-page> children with `name`, `title`
-// and `icon-name` attributes; their own children become the page body. The
-// switcher renders one toggle button per page (always icon + label) and shows
-// exactly one page at a time, exactly like libadwaita's single `viewswitcher`
-// CSS node with the `.wide` / `.narrow` policy style classes.
-//   - wide:   icon and label side by side (horizontal button layout)
-//   - narrow: icon stacked above the label (vertical button layout)
+// pages: the web counterpart of Adw.ViewSwitcher, bundled with the Adw.ViewStack
+// 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.
+//
+// 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', matching libadwaita's default).
-//   active — zero-based index of the selected page (default 0).
+//   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
+//     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 = { name, index }) when
-//     the selected page changes — mirrors Adw.ViewStack's `visible-child-name`.
-//   `notify::policy` (CustomEvent, bubbles, detail = { policy }) when the policy
-//     changes — mirrors the Adw.ViewSwitcher `policy` GObject property.
+//   `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 }).
 // 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
-// Reference: refs/adwaita-web/adwaita-web/scss/_viewswitcher.scss
+// Reference: packages/nativescript-bridge/adwaita/src/widgets/view-switcher-model.ts (NS twin)
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
-type Policy = 'wide' | 'narrow';
+import {
+    VIEW_SWITCHER_POLICIES,
+    ViewSwitcherState,
+    buildViewSwitcherButtons,
+    isViewSwitcherPolicy,
+} from '@gjsify/adwaita-core';
+import type { ViewSwitcherScheduler } from '@gjsify/adwaita-core';
+// Aliased because `AdwViewSwitcherPage` is already this module's page ELEMENT —
+// the custom element the package has always exported under that name.
+import type {
+    AdwViewSwitcherPage as AdwViewSwitcherPageInfo,
+    AdwViewSwitcherPolicy,
+    ViewSwitcherStateChange,
+} from '@gjsify/adwaita-core';
 
-interface PageInfo {
-    name: string;
-    title: string;
-    icon: string;
-    body: HTMLElement;
+import {
+    applyDescription,
+    applyIndicator,
+    applySwitcherIcon,
+    domViewSwitcherScheduler,
+    readSwitcherPage,
+} from './view-switcher-dom.js';
+import { type AdwIcon, createAdwIcon } from './adw-icon.js';
+
+/** The DOM nodes one page owns — the switcher paints the derived model onto them. */
+interface PageNodes {
     button: HTMLButtonElement;
+    icon: AdwIcon;
+    label: HTMLSpanElement;
+    indicator: HTMLSpanElement;
+    body: HTMLDivElement;
 }
 
-/** A single page. Children of <adw-view-switcher>; consumed at connect time. */
-export class AdwViewSwitcherPage extends HTMLElement {
-    static get observedAttributes() {
-        return ['name', 'title', 'icon-name'];
-    }
-}
+/**
+ * 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.
+ */
+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.
+     */
+    scheduler: ViewSwitcherScheduler = domViewSwitcherScheduler;
+    private _stateInstance: ViewSwitcherState | null = null;
+
+    /** Built on first access, so a `scheduler` set before connect is the one used. */
+    private get _state(): ViewSwitcherState {
+        if (!this._stateInstance) {
+            this._stateInstance = new ViewSwitcherState({ scheduler: this.scheduler });
+            this._stateInstance.subscribe((change) => this._onStateChange(change));
+        }
+        return this._stateInstance;
+    }
     private _barEl!: HTMLDivElement;
     private _contentEl!: HTMLDivElement;
-    private _pages: PageInfo[] = [];
-    private _active = 0;
-    private _policy: Policy = 'narrow';
+    private _nodes: PageNodes[] = [];
+    /** The page ELEMENTS, kept because the switcher detaches them from the tree. */
+    private _declared: HTMLElement[] = [];
+    private _pageObserver: MutationObserver | undefined;
+    private _policy: AdwViewSwitcherPolicy = 'narrow';
     private _initialized = false;
 
     static get observedAttributes() {
         return ['policy', 'active'];
     }
 
+    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(): Policy {
+    get policy(): AdwViewSwitcherPolicy {
         return this._policy;
     }
 
-    set policy(value: Policy) {
+    set policy(value: AdwViewSwitcherPolicy) {
         this.setAttribute('policy', value);
     }
 
-    /** Zero-based index of the active page. */
+    /** Zero-based index of the selected page, `-1` when nothing is selected. */
     get active(): number {
-        return this._active;
+        return this._state.selected;
     }
 
     set active(value: number) {
-        this.setAttribute('active', String(value));
+        this._state.setSelected(value);
+        this._reflectActive();
+    }
+
+    /** Name of the selected page, `''` when nothing is selected. */
+    get visibleChildName(): string {
+        return this._state.selectedName;
+    }
+
+    set visibleChildName(name: string | null | undefined) {
+        this._state.selectName(name);
+    }
+
+    /** The resolved page records a bound layout can read. */
+    get pages(): readonly AdwViewSwitcherPageInfo[] {
+        return this._state.pages;
     }
 
-    /** The name of the currently visible page, or null when there are none. */
-    get visibleChildName(): string | null {
-        return this._pages[this._active]?.name ?? null;
+    /**
+     * 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).
+     */
+    setPageVisible(name: string, visible: boolean): boolean {
+        const moved = this._state.setPageVisible(name, visible);
+        this._render();
+        return moved;
     }
 
     connectedCallback() {
-        if (this._initialized) return;
-        this._initialized = true;
+        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.
+            this._watchPages();
+            return;
+        }
 
-        // Snapshot the declared <adw-view-switcher-page> children before we take
-        // over the subtree — their name / title / icon-name + their own child
-        // nodes become the rendered tabs and page bodies.
-        const declaredPages = Array.from(this.querySelectorAll('adw-view-switcher-page')) as AdwViewSwitcherPage[];
+        // `: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).
+        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.
+        const declaredActive = this.getAttribute('active');
 
-        // The single `viewswitcher` node holds the segmented button bar; a sibling
-        // content area shows the active page (the web stand-in for the paired
-        // Adw.ViewStack the switcher would otherwise drive).
+        // 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');
@@ -92,107 +212,198 @@ export class AdwViewSwitcher extends HTMLElement {
         this._contentEl = document.createElement('div');
         this._contentEl.className = 'adw-view-switcher-content';
 
-        this._pages = declaredPages.map((pageEl, index) => {
-            const name = pageEl.getAttribute('name') ?? `page-${index}`;
-            const title = pageEl.getAttribute('title') ?? '';
-            const icon = (pageEl.getAttribute('icon-name') ?? '').replace(/-symbolic$/, '');
-
-            const button = document.createElement('button');
-            button.type = 'button';
-            button.className = 'adw-view-switcher-button';
-            button.setAttribute('role', 'tab');
-
-            const iconEl = document.createElement('span');
-            iconEl.className = `adw-icon${icon ? ` adw-icon--${icon}` : ''}`;
-            iconEl.setAttribute('aria-hidden', 'true'); // decorative (mask-image only)
-            iconEl.hidden = icon.length === 0;
-
-            const labelEl = document.createElement('span');
-            labelEl.className = 'adw-view-switcher-label';
-            labelEl.textContent = title;
-            labelEl.hidden = title.length === 0;
-
-            button.append(iconEl, labelEl);
-            // An icon-only tab has no visible text — give it an accessible name.
-            if (icon && !title) button.setAttribute('aria-label', icon);
-
-            button.addEventListener('click', () => this._selectIndex(index));
+        this._declared = declared;
+        this._watchPages();
+        this._nodes = declared.map((pageEl, index) => this._buildPage(pageEl, index));
+        this._barEl.append(...this._nodes.map((nodes) => nodes.button));
+        this._contentEl.append(...this._nodes.map((nodes) => nodes.body));
+        this.replaceChildren(this._barEl, this._contentEl);
 
-            const body = document.createElement('div');
-            body.className = 'adw-view-switcher-page';
-            body.dataset.name = name;
-            for (const child of Array.from(pageEl.childNodes)) body.appendChild(child);
+        this._policy = this._readPolicyAttr();
+        this._initialized = true;
 
-            return { name, title, icon, body, button };
-        });
+        this._state.setPages(declared.map((pageEl) => readSwitcherPage(pageEl)));
+        if (declaredActive !== null) {
+            const index = Number.parseInt(declaredActive, 10);
+            // A declared selection is not a user activation.
+            if (!Number.isNaN(index)) this._state.setSelected(index, false);
+        }
+        this._render();
+    }
 
-        this._barEl.append(...this._pages.map((p) => p.button));
-        this._contentEl.append(...this._pages.map((p) => p.body));
-        this.replaceChildren(this._barEl, this._contentEl);
+    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.
+        this._state.cancelDrag();
+        this._pageObserver?.disconnect();
+        this._pageObserver = undefined;
+    }
 
-        this._policy = this._readPolicyAttr();
-        this._active = this._readActiveAttr();
+    /**
+     * 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.
+     */
+    refreshPages(): void {
+        if (!this._initialized) return;
+        this._state.setPages(this._declared.map((pageEl) => readSwitcherPage(pageEl)));
         this._render();
     }
 
+    /**
+     * 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).
+     *
+     * 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.
+     */
+    private _watchPages(): void {
+        this._pageObserver?.disconnect();
+        this._pageObserver = new MutationObserver(() => this.refreshPages());
+        for (const pageEl of this._declared) this._pageObserver.observe(pageEl, { attributes: true });
+    }
+
     attributeChangedCallback(name: string) {
         if (!this._initialized) return;
         if (name === 'policy') {
             const next = this._readPolicyAttr();
-            if (next !== this._policy) {
-                this._policy = next;
-                this._render();
-            }
+            if (next === this._policy) return;
+            this._policy = next;
+            this._render();
+            this.dispatchEvent(new CustomEvent('notify::policy', { bubbles: true, detail: { policy: next } }));
             return;
         }
         if (name === 'active') {
-            const next = this._readActiveAttr();
-            if (next !== this._active) {
-                this._active = next;
-                this._render();
-            }
+            const raw = this.getAttribute('active');
+            const index = raw === null ? Number.NaN : Number.parseInt(raw, 10);
+            if (!Number.isNaN(index)) this._state.setSelected(index);
+            // A refused request must not leave the attribute claiming something
+            // the widget is not showing; re-reflecting is what makes "refused,
+            // not clamped" observable in the DOM.
+            this._reflectActive();
         }
     }
 
-    private _readPolicyAttr(): Policy {
-        return this.getAttribute('policy') === 'wide' ? 'wide' : 'narrow';
+    private _buildPage(pageEl: HTMLElement, index: number): PageNodes {
+        const button = document.createElement('button');
+        button.type = 'button';
+        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).
+        const icon = createAdwIcon(null, 'adw-view-switcher-icon');
+
+        const label = document.createElement('span');
+        label.className = 'adw-view-switcher-label';
+
+        const indicator = document.createElement('span');
+        indicator.className = 'adw-view-switcher-indicator';
+        indicator.setAttribute('aria-hidden', 'true'); // announced via aria-description
+
+        button.append(icon, label, indicator);
+        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.
+        button.addEventListener('dragenter', (event) => {
+            if (button.contains((event as DragEvent).relatedTarget as Node | null)) return;
+            this._state.dragEnter(index);
+        });
+        button.addEventListener('dragleave', (event) => {
+            if (button.contains((event as DragEvent).relatedTarget as Node | null)) return;
+            this._state.dragLeave(index);
+        });
+
+        const body = document.createElement('div');
+        body.className = 'adw-view-switcher-page';
+        body.dataset.name = pageEl.getAttribute('name') ?? '';
+        for (const child of Array.from(pageEl.childNodes)) body.appendChild(child);
+
+        return { button, icon, label, indicator, body };
     }
 
-    private _readActiveAttr(): number {
-        const raw = Number.parseInt(this.getAttribute('active') ?? '0', 10);
-        if (Number.isNaN(raw)) return 0;
-        const max = Math.max(0, this._pages.length - 1);
-        return Math.min(Math.max(raw, 0), max);
+    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).
+        if (raw === null) return 'narrow';
+        return isViewSwitcherPolicy(raw) ? raw : this._policy;
     }
 
-    private _selectIndex(index: number): void {
-        if (index === this._active) return;
-        this._active = index;
-        // Keep the attribute in sync without re-entering the guarded callback
-        // (value already matches, so attributeChangedCallback no-ops).
-        this.setAttribute('active', String(index));
+    private _onStateChange(change: ViewSwitcherStateChange): void {
         this._render();
-        const page = this._pages[index];
         this.dispatchEvent(
             new CustomEvent('notify::visible-child', {
                 bubbles: true,
-                detail: { name: page?.name ?? null, index },
+                detail: {
+                    index: change.selected,
+                    name: change.name,
+                    title: change.title,
+                    interactive: change.interactive,
+                },
             }),
         );
     }
 
     private _render(): void {
-        // Single `viewswitcher` node carries the `.wide` / `.narrow` policy class.
-        this.classList.toggle('wide', this._policy === 'wide');
-        this.classList.toggle('narrow', this._policy === 'narrow');
-
-        this._pages.forEach((page, index) => {
-            const isActive = index === this._active;
-            page.button.classList.toggle('active', isActive);
-            page.button.setAttribute('aria-selected', String(isActive));
-            page.button.tabIndex = isActive ? 0 : -1;
-            page.body.classList.toggle('active-view', isActive);
+        if (!this._initialized) return;
+
+        // The single `viewswitcher` node carries the policy style class
+        // (adw-view-switcher.c:539-545).
+        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);
+        models.forEach((model, index) => {
+            const nodes = this._nodes[index];
+            if (!nodes) return;
+
+            nodes.button.hidden = !model.visible;
+            nodes.button.classList.toggle('active', model.selected);
+            nodes.button.setAttribute('aria-selected', String(model.selected));
+            nodes.button.tabIndex = model.selected ? 0 : -1;
+
+            applySwitcherIcon(nodes.icon, model.iconName);
+            nodes.label.textContent = model.label;
+            nodes.label.hidden = model.label.length === 0;
+            applyIndicator(nodes.indicator, model.badgeLabel, model.needsAttention);
+            applyDescription(nodes.button, model.description);
+
+            // A tab with no visible text still needs an accessible name; the
+            // icon name is the only thing left to build one from.
+            if (model.label) nodes.button.removeAttribute('aria-label');
+            else nodes.button.setAttribute('aria-label', model.iconName);
+
+            nodes.body.classList.toggle('active-view', model.selected);
+            nodes.body.hidden = !model.selected;
         });
+
+        this._reflectActive();
+    }
+
+    private _reflectActive(): void {
+        const current = String(this._state.selected);
+        if (this.getAttribute('active') !== current) this.setAttribute('active', current);
     }
 }
 

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

@@ -1,15 +1,33 @@
 // <adw-window-title> — A composite title + subtitle for a header bar.
 // Attributes: title, subtitle.
-// Mirrors Adw.WindowTitle: two centered, ellipsized labels stacked vertically;
-// the subtitle is hidden when empty.
+// Events: notify::title / notify::subtitle (CustomEvent, mirroring the GObject
+//   notify names Adw.WindowTitle emits).
+//
+// The two labels, their visibility and the change-detection are HEADLESS and
+// live in `@gjsify/adwaita-core` (ADR 0004) as {@link WindowTitleState}; this
+// element composes it and keeps only the DOM render half.
+// `@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
+//     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).
+//
 // Reference: refs/adwaita-web/adwaita-web/docs/widgets/windowtitle.md
-// Reference: refs/libadwaita (Adw.WindowTitle)
+// Reference: refs/libadwaita/src/adw-window-title.c, adw-window-title.ui
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
-// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web; the
+// title/subtitle state composed from @gjsify/adwaita-core.
+
+import { WindowTitleState } from '@gjsify/adwaita-core';
 
 export class AdwWindowTitle extends HTMLElement {
     private _titleEl!: HTMLSpanElement;
     private _subtitleEl!: HTMLSpanElement;
+    /** The headless title/subtitle pair + change detection (ADR 0004). */
+    private readonly _state = new WindowTitleState();
     private _initialized = false;
 
     static get observedAttributes() {
@@ -27,21 +45,36 @@ export class AdwWindowTitle extends HTMLElement {
         this._subtitleEl.className = 'adw-window-title-subtitle';
 
         this.replaceChildren(this._titleEl, this._subtitleEl);
+        // Adopt the declared attributes without notifying: this is the initial
+        // value, not a change (`adw_window_title_new` sets both at construction).
+        this._state.setTitle(this.getAttribute('title'));
+        this._state.setSubtitle(this.getAttribute('subtitle'));
         this._render();
     }
 
-    attributeChangedCallback() {
-        if (this._initialized) this._render();
+    attributeChangedCallback(name: string, _old: string | null, value: string | null) {
+        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).
+        if (!changed) return;
+        this._render();
+        this.dispatchEvent(
+            new CustomEvent(`notify::${name}`, {
+                bubbles: true,
+                detail: { [name]: name === 'title' ? this._state.title : this._state.subtitle },
+            }),
+        );
     }
 
     private _render() {
-        const title = this.getAttribute('title') ?? '';
-        const subtitle = this.getAttribute('subtitle') ?? '';
+        const { title, titleVisible, subtitle, subtitleVisible } = this._state.state;
         this._titleEl.textContent = title;
+        this._titleEl.hidden = !titleVisible;
         this._subtitleEl.textContent = subtitle;
-        // Hide the subtitle slot entirely when empty so the title stays
-        // vertically centered (matches Adw.WindowTitle).
-        this._subtitleEl.hidden = subtitle.length === 0;
+        // Hiding the empty label entirely keeps the other one vertically
+        // centered, which is what the GTK box does when a child is invisible.
+        this._subtitleEl.hidden = !subtitleVisible;
     }
 }