@gjsify/adwaita-web 0.44.0 → 0.45.0

package/lib/types/elements/adw-header-bar.d.ts

@@ -6,8 +6,10 @@ export declare class AdwHeaderBar extends HTMLElement {
     private _endEl;
     /**
      * The derived `<adw-window-title>`, or `null` when a `slot="center"`
-     * title-widget took the centre. `Adw.HeaderBar` has the same either/or:
-     * setting `title-widget` replaces the derived `AdwWindowTitle` outright.
+     * title-widget took the centre. `Adw.HeaderBar` has the same either/or —
+     * `adw_header_bar_set_title_widget` empties the centre bin before installing
+     * (adw-header-bar.c:1201) — over a derived `GtkLabel`, not an `AdwWindowTitle`;
+     * see the divergence at the top of this file.
      */
     private _titleEl;
     static get observedAttributes(): string[];
@@ -22,15 +24,21 @@ export declare class AdwHeaderBar extends HTMLElement {
     /**
      * `title` used to be read ONCE, in `connectedCallback`, so every later write
      * was a silent no-op — a header bar whose title tracked the open document
-     * kept whatever it was created with. `Adw.HeaderBar`'s derived title widget
-     * is bound to the property and re-renders on every change.
+     * kept whatever it was created with. `Adw.HeaderBar` never reads its title once
+     * either: it has no `title` property at all, and re-runs `update_title`
+     * (adw-header-bar.c:475) on every ancestor change that could move the answer.
      */
     attributeChangedCallback(): void;
     /**
-     * Give the centre up to a title-widget. `adw_header_bar_set_title_widget` destroys the
-     * derived `AdwWindowTitle` rather than stacking the two, so the late case has to remove
-     * it too — a bar showing both would be a shape neither GTK nor the declared markup can
-     * produce.
+     * Give the centre up to a title-widget. `adw_header_bar_set_title_widget` empties the
+     * centre bin and drops its derived label (adw-header-bar.c:1201, :1209) rather than
+     * stacking the two, so the late case has to remove ours too — a bar showing both would
+     * be a shape neither GTK nor the declared markup can produce.
+     *
+     * NOT SYMMETRIC HERE, AND KNOWN: C rebuilds the label the moment the title-widget goes
+     * away (:1211); nothing in this element brings the derived centre back, so a bar that
+     * gave it up has given it up for good. `HeaderBarState` in `@gjsify/adwaita-core` holds
+     * the rebuild, and this element adopting it is the rewiring tracked in #1343.
      */
     private _dropDerivedTitle;
     private _renderTitle;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-web",
-    "version": "0.44.0",
+    "version": "0.45.0",
     "description": "Adwaita/Libadwaita web components for browser targets",
     "type": "module",
     "main": "./src/index.ts",
@@ -45,14 +45,14 @@
         "@codemirror/language": "^6.12.4",
         "@codemirror/state": "^6.7.0",
         "@codemirror/view": "^6.43.4",
-        "@gjsify/adwaita-core": "^0.44.0",
-        "@gjsify/adwaita-fonts": "^0.44.0",
-        "@gjsify/adwaita-icons": "^0.44.0",
+        "@gjsify/adwaita-core": "^0.45.0",
+        "@gjsify/adwaita-fonts": "^0.45.0",
+        "@gjsify/adwaita-icons": "^0.45.0",
         "@lezer/highlight": "^1.2.3"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.44.0",
-        "@gjsify/unit": "^0.44.0",
+        "@gjsify/cli": "^0.45.0",
+        "@gjsify/unit": "^0.45.0",
         "sass": "^1.101.0",
         "typescript": "^6.0.3"
     },
@@ -75,6 +75,9 @@
                 "navigator",
                 "process"
             ]
+        },
+        "widgetVocabulary": {
+            "role": "renderer"
         }
     },
     "license": "MIT",

package/src/adw-header-bar.spec.ts

@@ -4,9 +4,13 @@
 // the open document keeps its construction-time title otherwise, and nothing notices
 // because the attribute is still there and A title still renders.
 //
-// `Adw.HeaderBar` builds its centre from `title`/`subtitle` through a derived
-// `AdwWindowTitle` bound to the properties, unless a `title-widget` replaces it — the
-// either/or the `slot="center"` case below asserts.
+// The either/or the `slot="center"` case below asserts IS `Adw.HeaderBar`'s: setting
+// `title-widget` empties the centre bin (adw-header-bar.c:1201), and clearing it builds the
+// derived centre again (:1211). What C builds there is a plain `gtk_label_new (NULL)`
+// (`construct_title_label`, :512) with no subtitle, and no `title` property behind it —
+// `update_title` (:475) resolves one from the ancestry. The `<adw-window-title>` centre and
+// the title/subtitle PAIR are this port's DIVERGENCE, named in `elements/adw-header-bar.ts`
+// and recorded as `HeaderBarRenderState.derivedSubtitle` in `@gjsify/adwaita-core`.
 
 import { describe, expect, it } from '@gjsify/unit';
 
@@ -122,7 +126,8 @@ export const AdwHeaderBarTest = async () => {
         });
     });
 
-    // The centre is the `<adw-window-title>` Adw.HeaderBar itself derives, so the three
+    // The centre is an `<adw-window-title>` — this port's divergence, not the bare
+    // `GtkLabel` `construct_title_label` builds (adw-header-bar.c:512) — so the three
     // rules that element holds through @gjsify/adwaita-core reach the header bar too.
     // None of them did while the centre was a bare span.
     await describe('<adw-header-bar> derives an <adw-window-title>', async () => {

package/src/adw-tab-view.spec.ts

@@ -75,6 +75,77 @@ export const AdwTabViewTest = async () => {
         });
     });
 
+    // ONE HALF of the upgrade-order defect; the other half is the define order at the
+    // foot of `elements/adw-tab-view.ts`, which no test in this realm can observe —
+    // both names are already registered by the time a spec runs, and `define` is what
+    // upgrades. What IS reproducible here is the STATE that order produced: a real
+    // `<adw-tab-page>` next to an `<adw-tab-view>` that is still an ordinary
+    // HTMLElement. `document.implementation.createHTMLDocument()` has no browsing
+    // context, so nothing it creates is ever upgraded; adopting the element carries it
+    // into this document without upgrading it, which INSERTING it would do.
+    //
+    // Constructing both with `document.createElement` instead would pass either way —
+    // both are defined, so both come back upgraded and the ancestor always has the
+    // method. The parse-then-define order the site hits is covered in
+    // `tests/browser/specs/adwaita-upgrade-order.spec.ts`.
+    await describe('adw-tab-page beside an un-upgraded view', async () => {
+        await it('reports nothing when the view has none of its methods yet', async () => {
+            const view = document.adoptNode(
+                document.implementation.createHTMLDocument('').createElement('adw-tab-view'),
+            );
+            expect('syncDeclaredPage' in view).toBe(false);
+            const page = document.createElement('adw-tab-page');
+            view.appendChild(page);
+
+            // A custom-element reaction never throws INTO its caller: the exception is
+            // REPORTED, so `setAttribute` returns normally whether or not the callback
+            // blew up and only a listener sees the difference. `preventDefault` keeps a
+            // red run from also logging it at the console.
+            const reported: string[] = [];
+            const onError = (event: ErrorEvent) => {
+                reported.push(event.message);
+                event.preventDefault();
+            };
+            window.addEventListener('error', onError);
+            page.setAttribute('title', 'One');
+            window.removeEventListener('error', onError);
+
+            expect(reported).toStrictEqual([]);
+            expect(page.getAttribute('title')).toBe('One');
+        });
+
+        await it('leaves a page appended after connect unadopted rather than throwing', async () => {
+            // The imperative surface is `appendPage`; a bare DOM append is out of
+            // contract, and the point here is only that it fails QUIETLY — the page
+            // carries no `data-page-id`, so `syncDeclaredPage` has no record to touch.
+            //
+            // "rather than throwing" is ASSERTED and not assumed. Without the listener
+            // this test measured only the two counts, and both hold whether or not the
+            // callback blew up: a custom-element reaction is REPORTED, never rethrown
+            // into `setAttribute`, so the model is untouched either way. Measured — with
+            // `syncDeclaredPage` mutated to throw on exactly this path, the whole
+            // in-bundle suite of 4631 stayed green and only an unrelated spec's global
+            // error sweep noticed.
+            const view = makeTabView();
+            const late = document.createElement('adw-tab-page');
+            view.appendChild(late);
+
+            const reported: string[] = [];
+            const onError = (event: ErrorEvent) => {
+                reported.push(event.message);
+                event.preventDefault();
+            };
+            window.addEventListener('error', onError);
+            late.setAttribute('title', 'Late');
+            window.removeEventListener('error', onError);
+
+            expect(reported).toStrictEqual([]);
+            expect(view.nPages).toBe(3);
+            expect(chips(view).length).toBe(3);
+            view.parentElement?.remove();
+        });
+    });
+
     await describe('adw-tab-view expand-tabs / no-close', async () => {
         await it('no-close hides every close affordance', async () => {
             const view = makeTabView('no-close');

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

@@ -1,8 +1,20 @@
 // <adw-header-bar> — Adwaita header bar with centered title and start/end button slots.
 //
-// The derived centre is an `<adw-window-title>`, which is what `Adw.HeaderBar`
-// itself puts there (`adw-header-bar.c`: the title widget it creates when none is
-// given IS an `AdwWindowTitle`). It used to be a bare span with
+// The derived centre is an `<adw-window-title>`. That is a DIVERGENCE, and the comment
+// here used to claim the opposite — that `Adw.HeaderBar` puts one there. Measured
+// against the source: `construct_title_label` (adw-header-bar.c:512) builds a plain
+// `gtk_label_new (NULL)` with the `title` class, `single-line-mode` and
+// `ellipsize=END`, and `Adw.HeaderBar` has NO `title` property at all — `update_title`
+// (:475) resolves one from the navigation page, then the dialog, then the root window,
+// then `g_get_application_name`, then `g_get_prgname`. An app that wants a subtitle
+// there sets an `AdwWindowTitle` as its title-widget.
+//
+// The divergence is kept: a declarative surface wants `title=` / `subtitle=` attributes
+// rather than a widget handoff, and both renderers already use them. It is recorded as
+// `HeaderBarRenderState.derivedSubtitle` in `@gjsify/adwaita-core`, so it is a named
+// difference instead of a mistaken claim of fidelity.
+//
+// It used to be a bare span with
 // `textContent = title ?? ''`, and that span carried none of the three rules the
 // window title already held in `@gjsify/adwaita-core`: an EMPTY title still
 // reserved a blank line, re-setting the same value repainted, and there was no
@@ -29,8 +41,10 @@ export class AdwHeaderBar extends HTMLElement {
     private _endEl: HTMLDivElement | null = null;
     /**
      * The derived `<adw-window-title>`, or `null` when a `slot="center"`
-     * title-widget took the centre. `Adw.HeaderBar` has the same either/or:
-     * setting `title-widget` replaces the derived `AdwWindowTitle` outright.
+     * title-widget took the centre. `Adw.HeaderBar` has the same either/or —
+     * `adw_header_bar_set_title_widget` empties the centre bin before installing
+     * (adw-header-bar.c:1201) — over a derived `GtkLabel`, not an `AdwWindowTitle`;
+     * see the divergence at the top of this file.
      */
     private _titleEl: HTMLElement | null = null;
 
@@ -86,8 +100,9 @@ export class AdwHeaderBar extends HTMLElement {
         ).install(this._startEl, this._centerEl, this._endEl);
 
         // Derived only when the centre is still free — the same either/or as
-        // `Adw.HeaderBar`, which builds an `AdwWindowTitle` exactly while no title-widget
-        // was given.
+        // `Adw.HeaderBar`, which runs `construct_title_label` exactly while no
+        // title-widget holds the centre (adw-header-bar.c:1211). What it builds there is
+        // a `GtkLabel`; this is the documented `<adw-window-title>` divergence.
         if (this._centerEl.childElementCount === 0) {
             this._titleEl = document.createElement('adw-window-title');
             this._titleEl.className = 'adw-header-bar-title';
@@ -99,18 +114,24 @@ export class AdwHeaderBar extends HTMLElement {
     /**
      * `title` used to be read ONCE, in `connectedCallback`, so every later write
      * was a silent no-op — a header bar whose title tracked the open document
-     * kept whatever it was created with. `Adw.HeaderBar`'s derived title widget
-     * is bound to the property and re-renders on every change.
+     * kept whatever it was created with. `Adw.HeaderBar` never reads its title once
+     * either: it has no `title` property at all, and re-runs `update_title`
+     * (adw-header-bar.c:475) on every ancestor change that could move the answer.
      */
     attributeChangedCallback() {
         if (this._initialized) this._renderTitle();
     }
 
     /**
-     * Give the centre up to a title-widget. `adw_header_bar_set_title_widget` destroys the
-     * derived `AdwWindowTitle` rather than stacking the two, so the late case has to remove
-     * it too — a bar showing both would be a shape neither GTK nor the declared markup can
-     * produce.
+     * Give the centre up to a title-widget. `adw_header_bar_set_title_widget` empties the
+     * centre bin and drops its derived label (adw-header-bar.c:1201, :1209) rather than
+     * stacking the two, so the late case has to remove ours too — a bar showing both would
+     * be a shape neither GTK nor the declared markup can produce.
+     *
+     * NOT SYMMETRIC HERE, AND KNOWN: C rebuilds the label the moment the title-widget goes
+     * away (:1211); nothing in this element brings the derived centre back, so a bar that
+     * gave it up has given it up for good. `HeaderBarState` in `@gjsify/adwaita-core` holds
+     * the rebuild, and this element adopting it is the rewiring tracked in #1343.
      */
     private _dropDerivedTitle() {
         this._titleEl?.remove();

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

@@ -100,8 +100,20 @@ export class AdwNavigationPage extends HTMLElement {
         // back-button derivation read the CORE's copy — so a runtime change has to
         // be pushed into it. Without this the back button only ever reflected the
         // `can-pop` value it had at the last stack mutation.
-        const view = this.closest('adw-navigation-view') as AdwNavigationView | null;
-        view?.syncPageProperty(this, name, previous);
+        //
+        // `instanceof` rather than a cast plus `?.`: the two failures the `?.`
+        // conflated are different. A MISSING ancestor is one; an ancestor that IS
+        // there but is still an ordinary HTMLElement, because its own definition has
+        // not upgraded it yet, is the other, and the cast asserted it away. Measured
+        // on `dist/test.browser.mjs` against declared markup parsed before the module
+        // loaded: `syncPageProperty is not a function`, once per observed attribute
+        // per declared page. Dropping the notification for an un-upgraded view loses
+        // nothing — such a view has not registered this page, `syncPageProperty`
+        // already returns on `!isRegistered`, and `connectedCallback` reads the
+        // properties back out of the element through `readPageProps`.
+        const view = this.closest('adw-navigation-view');
+        if (!(view instanceof AdwNavigationView)) return;
+        view.syncPageProperty(this, name, previous);
     }
 
     revertAttribute(name: string, value: string | null): void {
@@ -464,5 +476,13 @@ export class AdwNavigationView extends HTMLElement {
     }
 }
 
-customElements.define('adw-navigation-page', AdwNavigationPage);
+// The VIEW first, and the order carries weight: `define` upgrades every matching
+// element already in the document, immediately, so these two calls are a sequence and
+// not a pair. Registering the page first upgraded every declared
+// `<adw-navigation-page>` while its `<adw-navigation-view>` parent was still an
+// ordinary HTMLElement, and `AdwNavigationPage.attributeChangedCallback` reaches for
+// that parent. Parent before child keeps the window shut; the `instanceof` guard in
+// the callback is what holds when something outside this file reopens it.
+// `scripts/check-adwaita-upgrade-order.mjs` holds the order itself.
 customElements.define('adw-navigation-view', AdwNavigationView);
+customElements.define('adw-navigation-page', AdwNavigationPage);

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

@@ -74,8 +74,21 @@ export class AdwTabPage extends HTMLElement {
     attributeChangedCallback(name: string, _old: string | null, value: string | null) {
         // `closest` still finds the view after adoption: the element is moved
         // into the view's page container, not replaced by a wrapper.
-        const view = this.closest('adw-tab-view') as AdwTabView | null;
-        view?.syncDeclaredPage(this, name, value);
+        //
+        // `instanceof` rather than a cast plus `?.`, because the two failures the
+        // `?.` conflated are different: a MISSING ancestor, and an ancestor that is
+        // there but is still an ordinary HTMLElement because its own definition has
+        // not upgraded it. The cast asserted the second away, and it is the one that
+        // happened — `syncDeclaredPage is not a function`, 19 times on
+        // `/getting-started/`, once per declared page.
+        //
+        // Dropping the notification for an un-upgraded view is correct and not
+        // merely quiet: such a view has not adopted this page yet, and
+        // `_adoptDeclaredPage` reads every attribute in PAGE_ATTRIBUTES straight off
+        // the element when it does, so there is nothing to lose and nothing to defer.
+        const view = this.closest('adw-tab-view');
+        if (!(view instanceof AdwTabView)) return;
+        view.syncDeclaredPage(this, name, value);
     }
 }
 
@@ -797,5 +810,14 @@ export class AdwTabView extends HTMLElement {
     }
 }
 
-customElements.define('adw-tab-page', AdwTabPage);
+// The VIEW first, and the order carries weight: `define` upgrades every matching
+// element already in the document, immediately. Registering the page first therefore
+// upgraded every declared `<adw-tab-page>` while its `<adw-tab-view>` parent was still
+// un-upgraded, and `AdwTabPage.attributeChangedCallback` reaches for that parent.
+// Parent before child keeps the window shut; the `instanceof` guard in the callback is
+// what holds when something outside this file reopens it — and because the guard makes
+// the order UNOBSERVABLE (with it in place, page-first renders identically and every
+// test still passes, measured), the order itself is held by
+// `scripts/check-adwaita-upgrade-order.mjs` rather than by a spec.
 customElements.define('adw-tab-view', AdwTabView);
+customElements.define('adw-tab-page', AdwTabPage);