@gjsify/adwaita-web 0.64.12 → 0.64.13

package/lib/types/widget-element.d.ts

@@ -9,7 +9,13 @@ export declare class WidgetElement extends HTMLElement {
     get_visible(): boolean;
     /** `gtk_widget_set_visible`. */
     set_visible(visible: boolean): void;
-    /** `gtk_widget_get_first_child`: the first child element, `null` for a leaf. */
+    /**
+     * `gtk_widget_get_first_child`: the first child WIDGET, `null` for a leaf.
+     *
+     * The five walkers skip the elements a port builds for its own insides — `isWidgetNode`
+     * in `@gjsify/adwaita-core` carries the rule and the incident behind it, and the
+     * registered-class copy in `widgetTreeMembers()` answers from the same function.
+     */
     get_first_child(): Element | null;
     /** `gtk_widget_get_last_child`. */
     get_last_child(): Element | null;
@@ -17,7 +23,7 @@ export declare class WidgetElement extends HTMLElement {
     get_next_sibling(): Element | null;
     /** `gtk_widget_get_prev_sibling`. */
     get_prev_sibling(): Element | null;
-    /** `gtk_widget_get_parent`. */
+    /** `gtk_widget_get_parent`: the nearest ancestor that is a widget, not a port's own wrapper. */
     get_parent(): Element | null;
     /** `gtk_widget_get_width`: the layout box in CSS px; 0 until the widget is rendered. */
     get_width(): number;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-web",
-    "version": "0.64.12",
+    "version": "0.64.13",
     "description": "Adwaita/Libadwaita web components for browser targets",
     "type": "module",
     "main": "./src/index.ts",
@@ -58,14 +58,14 @@
         "@codemirror/language": "^6.12.4",
         "@codemirror/state": "^6.7.0",
         "@codemirror/view": "^6.43.4",
-        "@gjsify/adwaita-core": "^0.64.12",
-        "@gjsify/adwaita-fonts": "^0.64.12",
-        "@gjsify/adwaita-icons": "^0.64.12",
-        "@gjsify/gtksource-core": "^0.64.12",
+        "@gjsify/adwaita-core": "^0.64.13",
+        "@gjsify/adwaita-fonts": "^0.64.13",
+        "@gjsify/adwaita-icons": "^0.64.13",
+        "@gjsify/gtksource-core": "^0.64.13",
         "@lezer/highlight": "^1.2.3"
     },
     "peerDependencies": {
-        "@gjsify/app-settings": "^0.64.12"
+        "@gjsify/app-settings": "^0.64.13"
     },
     "peerDependenciesMeta": {
         "@gjsify/app-settings": {
@@ -73,11 +73,11 @@
         }
     },
     "devDependencies": {
-        "@gjsify/app-settings": "^0.64.12",
-        "@gjsify/blueprint": "^0.64.12",
-        "@gjsify/cli": "^0.64.12",
-        "@gjsify/unit": "^0.64.12",
-        "@gjsify/vite-plugin-blueprint": "^0.64.12",
+        "@gjsify/app-settings": "^0.64.13",
+        "@gjsify/blueprint": "^0.64.13",
+        "@gjsify/cli": "^0.64.13",
+        "@gjsify/unit": "^0.64.13",
+        "@gjsify/vite-plugin-blueprint": "^0.64.13",
         "sass": "^1.101.0",
         "typescript": "^6.0.3"
     },

package/scss/_labels.scss

@@ -109,6 +109,25 @@ gtk-label {
     max-width: 100%;
   }
 
+  // `gtk-label.ts`'s run-render path, SINGLE-LINE: the markup's runs move into this span
+  // because this element is a flex container (the two spacers above), and a node directly
+  // under one is a FLEX ITEM, not text — `vertical-align` does not apply to a flex item,
+  // so `<sup>`/`<sub>` stop being raised, and `align-items` centres each run on its own
+  // instead of the line sharing one baseline. Plain text never needed a box: a bare text
+  // node is ONE anonymous item, where a run list is one item per run.
+  //
+  // NO `max-width` HERE, unlike `.adw-label-text`: this box only ever holds ONE line (the
+  // host's `white-space: pre`, and this path is the not-wrapping, not-ellipsizing case),
+  // so there is no shrink-to-fit collapse to measure around — a single-line label as wide
+  // as its text, overflowing a narrower container, is what GtkLabel does and what
+  // `gtk-label.spec.ts` already pins for the plain-text path. The box's own size is its
+  // text's: `flex-basis: auto` over `width: auto` is the item's max-content width, which
+  // leaves the two spacers the free space `xalign` splits.
+  .adw-label-runs {
+    // Blockified by spec as a flex item; spelled out as `.adw-label-text` spells it out.
+    display: block;
+  }
+
   // `wrap-mode` — Pango's break-opportunity choice — is a real `word-break`/
   // `overflow-wrap` mapping, not a declared gap: CSS's `break-all` is Pango's CHAR (break
   // anywhere), and `overflow-wrap: anywhere` is Pango's WORD_CHAR (word boundaries, falling

package/scss/_link.scss

@@ -1,12 +1,26 @@
 // _link.scss — `link` and `button.link`, libadwaita's link treatment.
 //
-// ONLY `button.link`, not a bare `.link`. Upstream's rule names the `link` NODE and
-// `button.link` (`_links.scss:1-2`); the `link` node is the inner node of a `Gtk.Label`'s
-// `<a>` markup, which no element here renders. The `.link` style CLASS on anything but a
-// button is unstyled upstream: `AdwLinkRow` adds it to its row (adw-link-row.c:377), and
-// no rule matches `row.link`, so its title stays in the row's own colour. A bare `.link`
-// here painted the About dialog's link rows blue and underlined. `<gtk-link-button>`
-// renders an inner `<button class="adw-button link">`, which the selector below reads.
+// TWO NODES, NEVER A BARE `.link`. Upstream's rule names the `link` NODE and
+// `button.link` (`_links.scss:1-2`). `button.link` is `<gtk-link-button>`'s inner
+// `<button class="adw-button link">`, which the first selector below reads. The `link`
+// node is the inner node of a `Gtk.Label`'s `<a>` markup, and `<gtk-label>` now DRAWS
+// that — an `<a href>` per link in the markup (`label-markup.ts`) — so the second
+// selector is upstream's `link` rule, ported onto the element that finally exists.
+//
+// The `.link` style CLASS on anything but those two is unstyled upstream: `AdwLinkRow`
+// adds it to its row (adw-link-row.c:377), and no rule matches `row.link`, so its title
+// stays in the row's own colour. A bare `.link` here painted the About dialog's link rows
+// blue and underlined. It would now also hit `<gtk-label>` ITSELF, which gains the class
+// whenever its markup has a link (gtklabel.c:3896) — the label is not a link, its anchors
+// are. So both selectors name a node, and neither matches a class alone.
+//
+// THE LABEL'S ANCHORS ARE NOT STYLED THROUGH `:visited`, the CSS pseudo-class, even
+// though they are real `<a href>` elements that would match it. A browser's `:visited` is
+// the user's BROWSING HISTORY: a link followed in another tab, or last year, would come
+// up visited in a label that has never been clicked, which `Gtk.Label` never does. Its
+// `visited` is per-label state carried by URI across a re-parse
+// (`labelLinksInheritVisited`), painted as `.visited` by `_paintVisited` — the same class
+// `<gtk-link-button>` writes for the same reason one paragraph down.
 //
 // THE TWO COLOURS ARE THE PALETTE'S, not new tokens: `$link_color: var(--accent-color)`
 // and `$link_visited_color: color-mix(in srgb, var(--accent-color) 80%, var(--view-fg-color))`
@@ -36,6 +50,7 @@
 $link-color: var(--accent-color);
 $link-visited-color: color-mix(in srgb, var(--accent-color) 80%, var(--view-fg-color));
 $osd-link-color: color-mix(in srgb, var(--accent-bg-color) 50%, white);
+$osd-link-visited-color: color-mix(in srgb, var(--accent-bg-color) 75%, white);
 
 .adw-button.link {
   color: $link-color;
@@ -82,4 +97,55 @@ $osd-link-color: color-mix(in srgb, var(--accent-bg-color) 50%, white);
   &.checked {
     background-color: transparent;
   }
+}
+
+// Upstream's bare `link` node — a `Gtk.Label`'s `<a href>` markup, which `<gtk-label>`
+// draws as a real anchor per link (`label-markup.ts`, `buildAnchor`).
+//
+// THE SELECTOR IS THE ATTRIBUTE, not the class. `data-gtk-link` is written by the renderer
+// and by nothing else, so it names the node the way upstream's `link` names a GTK node;
+// the `.link` class on the same anchor is GTK's own style class, which a consumer may also
+// put on anything (and `<gtk-label>` ITSELF carries it whenever its markup has a link —
+// see the header). Scoped under `gtk-label` so an `<a>` a consumer put in a label's slot
+// for its own reasons is untouched.
+gtk-label a[data-gtk-link] {
+  color: $link-color;
+  text-decoration: underline;
+  font-weight: inherit;
+
+  &:hover {
+    color: hsl(from $link-color h calc(s * 1.1) calc(l * 1.1));
+  }
+
+  &:active {
+    color: $link-color;
+  }
+
+  // `.visited` and NOT `:visited` — the pseudo-class is the user's browsing history, where
+  // `Gtk.Label`'s `visited` is per-label state carried by URI (`_paintVisited`, and the
+  // paragraph in the header).
+  &.visited {
+    color: $link-visited-color;
+  }
+
+  .osd & {
+    color: $osd-link-color;
+
+    &.visited {
+      color: $osd-link-visited-color;
+    }
+
+    &:active {
+      color: $osd-link-color;
+    }
+  }
+
+  // `link { @include focus-ring() }` (_links.scss:33-35) — the mixin is a 2px outline at
+  // offset -2px (`_drawing.scss`), spelled out as `_expander.scss` and `_checks.scss`
+  // spell it out. `:focus-visible` rather than `:focus`: GTK draws the ring on keyboard
+  // focus, and a click on a link must not leave one behind.
+  &:focus-visible {
+    outline: 2px solid var(--accent-color);
+    outline-offset: -2px;
+  }
 }

package/src/adw-action-rows.spec.ts

@@ -19,6 +19,7 @@ import { describe, expect, it } from '@gjsify/unit';
 
 import {
     ACTION_ROW_ACTIVATION_VECTORS,
+    ACTION_ROW_SUBTITLE_VECTORS,
     BUTTON_ROW_ACTIVATABLE_VECTORS,
     BUTTON_ROW_ICON_VECTORS,
     LABEL_VISIBILITY_VECTORS,
@@ -98,6 +99,24 @@ export const AdwActionRowsTest = async () => {
         });
     });
 
+    await describe('<adw-action-row> subtitle (libadwaita conformance vectors)', async () => {
+        // The element is attribute-driven and publishes no `notify::subtitle`, so only the
+        // value the vectors hold afterwards is observable; `null` is an absent attribute.
+        for (const vector of ACTION_ROW_SUBTITLE_VECTORS) {
+            await it(`${vector.name} — ${vector.rule}`, () => {
+                const { el: row, host } = mount<AdwActionRow>('adw-action-row');
+                for (const step of vector.steps) {
+                    if (step.write === null) row.removeAttribute('subtitle');
+                    else row.setAttribute('subtitle', step.write);
+                    const label = row.querySelector('.adw-row-subtitle') as HTMLElement;
+                    expect(label.textContent).toBe(step.subtitle);
+                    expect(label.hidden).toBe(step.subtitle === '');
+                }
+                host.remove();
+            });
+        }
+    });
+
     await describe('<adw-action-row> activatable-widget (libadwaita conformance vectors)', async () => {
         for (const vector of ACTION_ROW_ACTIVATION_VECTORS) {
             await it(`${vector.name} — ${vector.rule}`, async () => {

package/src/adw-bin.spec.ts

@@ -61,6 +61,26 @@ export const AdwBinTest = async () => {
             other.remove();
         });
 
+        await it('answers `get_child()` / `set_child()` too, the spelling GI-built code uses', () => {
+            // `Adw.Bin:child` has two doors, and markup only takes one of them: code written
+            // against GI calls the methods, which is what a `.blp`-driven widget shared with
+            // GJS and NativeScript does. Both of those renderers answer them; the web did not,
+            // and shared code died here with `get_child is not a function`.
+            const { el, host } = mount();
+            expect(el.get_child()).toBeNull();
+            const child = document.createElement('div');
+            el.set_child(child);
+            expect(el.get_child()).toBe(child);
+            expect(el.child).toBe(child);
+            const next = document.createElement('span');
+            el.set_child(next);
+            expect(el.get_child()).toBe(next);
+            expect(el.childElementCount).toBe(1);
+            el.set_child(null);
+            expect(el.get_child()).toBeNull();
+            host.remove();
+        });
+
         await it('a bin is a column flex box, and its only child fills it', () => {
             const { el, host } = mount([document.createElement('div')]);
             // A bin takes the size it is GIVEN and hands all of it to the child, which

package/src/adw-row-state.spec.ts

@@ -15,6 +15,9 @@ import {
     COMBO_CHOOSER_VECTORS,
     COMBO_ITEMS_CHANGED_VECTORS,
     COMBO_SELECTION_VECTORS,
+    EXPANDER_ROW_CONSTRUCT_VECTORS,
+    EXPANDER_ROW_INITIAL,
+    EXPANDER_ROW_VECTORS,
     LIST_ITEMS_CHANGED_VECTORS,
     LIST_MODEL_OWNERSHIP_VECTORS,
     LIST_NORMALIZE_VECTORS,
@@ -779,6 +782,83 @@ export const AdwRowStateTest = async () => {
             host.remove();
         });
 
+        for (const vector of EXPANDER_ROW_VECTORS) {
+            await it(`holds ${vector.name} (shared conformance vectors)`, async () => {
+                const { el: row, host } = parse<AdwExpanderRow>(
+                    '<adw-expander-row title="More"><adw-action-row title="Nested"></adw-action-row></adw-expander-row>',
+                    'adw-expander-row',
+                );
+                expect(row.expanded).toBe(EXPANDER_ROW_INITIAL.expanded);
+                expect(row.enableExpansion).toBe(EXPANDER_ROW_INITIAL.enableExpansion);
+                for (const step of vector.steps) {
+                    if (step.op === 'expanded') row.expanded = step.value;
+                    else row.enableExpansion = step.value;
+                    // A DOM element publishes only the user's notifications, so `notified` is
+                    // not observable here — the held values and what they reflect to are.
+                    expect(row.expanded).toBe(step.expanded);
+                    expect(row.enableExpansion).toBe(step.enableExpansion);
+                    expect(row.hasAttribute('expanded')).toBe(step.expanded);
+                    expect(row.classList.contains('expanded')).toBe(step.expanded);
+                }
+                host.remove();
+            });
+        }
+
+        for (const vector of EXPANDER_ROW_CONSTRUCT_VECTORS) {
+            await it(`parses expanded=${vector.expanded}, enable-expansion=${vector.enableExpansion} — ${vector.rule}`, async () => {
+                const enable = `enable-expansion="${vector.enableExpansion}"`;
+                const expanded = vector.expanded ? 'expanded' : '';
+                // Both attribute orders: the parser delivers them in source order.
+                for (const attributes of [`${enable} ${expanded}`, `${expanded} ${enable}`]) {
+                    const { el: row, host } = parse<AdwExpanderRow>(
+                        `<adw-expander-row title="x" ${attributes}></adw-expander-row>`,
+                        'adw-expander-row',
+                    );
+                    expect(row.enableExpansion).toBe(vector.enableExpansion);
+                    expect(row.expanded).toBe(vector.resultExpanded);
+                    expect(row.hasAttribute('expanded')).toBe(vector.resultExpanded);
+                    host.remove();
+                }
+            });
+        }
+
+        await it('does not open on a header click while expansion is disabled', async () => {
+            const { el: row, host } = parse<AdwExpanderRow>(
+                '<adw-expander-row title="More" enable-expansion="false"></adw-expander-row>',
+                'adw-expander-row',
+            );
+            const header = row.querySelector('.adw-expander-row-header') as HTMLDivElement;
+            const events = record(row, 'notify::expanded');
+            header.click();
+            expect(row.expanded).toBe(false);
+            expect(events.details.length).toBe(0);
+            events.stop();
+            host.remove();
+        });
+
+        await it('the enable switch publishes expanded BEFORE enable-expansion, as libadwaita emits them', async () => {
+            const { el: row, host } = parse<AdwExpanderRow>(
+                '<adw-expander-row title="More" show-enable-switch enable-expansion="false"></adw-expander-row>',
+                'adw-expander-row',
+            );
+            const seen: string[] = [];
+            row.addEventListener('notify::expanded', () => seen.push('expanded'));
+            row.addEventListener('notify::enable-expansion', () => seen.push('enable-expansion'));
+            const toggle = row.querySelector('.adw-expander-row-enable-switch') as HTMLElement & { active: boolean };
+
+            toggle.active = true;
+            expect(seen.join()).toBe('expanded,enable-expansion');
+            expect(row.expanded).toBe(true);
+            expect(row.hasAttribute('expanded')).toBe(true);
+
+            seen.length = 0;
+            toggle.active = false;
+            expect(seen.join()).toBe('expanded,enable-expansion');
+            expect(row.expanded).toBe(false);
+            expect(row.hasAttribute('expanded')).toBe(false);
+            host.remove();
+        });
+
         await it('adopts a declarative expanded attribute', async () => {
             const { el: row, host } = parse<AdwExpanderRow>(
                 '<adw-expander-row title="Open" expanded></adw-expander-row>',

package/src/elements/adw-bin.ts

@@ -24,7 +24,7 @@
 // default `GENERIC` and a bin contributes nothing to the accessibility tree of its own.
 //
 // KNOWN_GAPS: none — `AdwBin`'s only property is `child`, a widget, which is a SLOT on
-// every renderer.
+// every renderer, and it is reachable BOTH ways: `child` and `get_child()`/`set_child()`.
 //
 // Reference: refs/libadwaita/src/adw-bin.c (adw_bin_set_child, class_init)
 // Copyright (c) 2021 Purism SPC / GNOME contributors (libadwaita). LGPLv2.1+.
@@ -46,6 +46,25 @@ export class AdwBin extends WidgetElement {
         this.setChild(value);
     }
 
+    /**
+     * `adw_bin_get_child` / `adw_bin_set_child` — the METHOD spelling of {@link child}.
+     *
+     * The property alone is not the whole door. `Adw.Bin:child` is reached two ways and only
+     * one of them is a property: markup writes `child:`, but code built against GI calls
+     * `bin.get_child()` / `bin.set_child(w)`, which is the spelling a `.blp`-driven widget
+     * shared across renderers uses — GJS and the NativeScript bridge both answer it
+     * (`AdwSingleChildBase`), and here it was missing, so the shared code died with
+     * `get_child is not a function` on the web and nowhere else.
+     */
+    get_child(): Element | null {
+        return this.child;
+    }
+
+    /** `adw_bin_set_child`. Refuses a child that already has a parent, as {@link setChild} does. */
+    set_child(child: Element | null): void {
+        this.setChild(child);
+    }
+
     connectedCallback() {
         // The NAME only. Every child of a bin already IS its content — there is no
         // internal structure to route into — so `.install()` is deliberately not called

package/src/elements/adw-expander-row.ts

@@ -13,10 +13,10 @@
 // listbox. The `notify::expanded` / `notify::enable-expansion` events are named after
 // Adw.ExpanderRow's GObject signals so one code path drives the web and GTK renderers.
 //
-// The DISCLOSURE state (the expanded flag and its idempotent, notify-on-change
-// transitions) is HEADLESS and lives in `@gjsify/adwaita-core` (ADR 0004) as
-// {@link ExpanderState}; this element keeps only the DOM half — header/content markup,
-// the `expanded` attribute reflection and the event.
+// The DISCLOSURE state (the expanded flag, the `enable-expansion` gate over it and their
+// idempotent, notify-on-change transitions) is HEADLESS and lives in `@gjsify/adwaita-core`
+// (ADR 0004) as {@link ExpanderState}; this element keeps only the DOM half — header/content
+// markup, the `expanded` / `enable-expansion` attribute reflection and the events.
 //
 // Reference: refs/adwaita-web/adwaita-web/scss/_expander_row.scss
 // Reference: refs/libadwaita/src/stylesheet/widgets/_lists.scss (AdwExpanderRow)
@@ -70,8 +70,7 @@ export class AdwExpanderRow extends TooltipElement {
         // custom-element constructor rules allow it: nothing touches the DOM until the
         // state actually changes.
         this._state.subscribe((expanded) => {
-            if (expanded) this.setAttribute('expanded', '');
-            else this.removeAttribute('expanded');
+            this._reflectExpanded(expanded);
             if (this._initialized) this._render();
         });
     }
@@ -98,7 +97,7 @@ export class AdwExpanderRow extends TooltipElement {
     }
 
     get enableExpansion(): boolean {
-        return !this.hasAttribute('enable-expansion') || this.getAttribute('enable-expansion') !== 'false';
+        return this._state.enableExpansion;
     }
 
     set enableExpansion(value: boolean) {
@@ -138,7 +137,7 @@ export class AdwExpanderRow extends TooltipElement {
         // Clicking the enable switch does NOT toggle the disclosure.
         this._enableSwitch = document.createElement('gtk-switch') as GtkSwitch;
         this._enableSwitch.classList.add('adw-expander-row-enable-switch');
-        this._enableSwitch.active = this.enableExpansion;
+        this._enableSwitch.active = this._state.enableExpansion;
 
         this._chevronEl = createGtkImage('go-down', 'adw-expander-row-chevron');
 
@@ -197,27 +196,58 @@ export class AdwExpanderRow extends TooltipElement {
             event.stopPropagation();
             if (this._reflectingEnable) return;
             const enabled = this._enableSwitch.active;
+            // The state drives `expanded` BEFORE it notifies `enable-expansion`, and reports
+            // both in that order, so the events leave in the order libadwaita emits them.
+            const notified = this._state.setEnableExpansion(enabled);
             this.setAttribute('enable-expansion', enabled ? 'true' : 'false');
-            this.dispatchEvent(
-                new CustomEvent('notify::enable-expansion', {
-                    bubbles: true,
-                    detail: { enableExpansion: enabled },
-                }),
-            );
+            for (const property of notified) {
+                this.dispatchEvent(
+                    new CustomEvent(`notify::${property}`, {
+                        bubbles: true,
+                        detail: property === 'expanded' ? { expanded: this.expanded } : { enableExpansion: enabled },
+                    }),
+                );
+            }
         });
 
         // Seed the disclosure from the parsed markup: attributeChangedCallback is guarded
         // until the element is initialized, so a declarative `expanded` lands here.
+        // `enable-expansion` is already in the state (see attributeChangedCallback), so a
+        // markup `expanded` on a disabled row is refused as libadwaita refuses it.
         this._state.setExpanded(this.hasAttribute('expanded'));
+        this._reflectExpanded(this._state.expanded);
         this._render();
     }
 
     attributeChangedCallback(name: string) {
+        if (name === 'enable-expansion') {
+            // Taken before the init guard so `enableExpansion` answers a parsed attribute
+            // before the element connects. A programmatic write: the state drives `expanded`
+            // with it and the subscriber reflects that, silently. Only the switch publishes
+            // `notify::enable-expansion`.
+            this._state.setEnableExpansion(this._enableAttribute());
+        }
         if (!this._initialized) return;
-        if (name === 'expanded') this._state.setExpanded(this.hasAttribute('expanded'));
+        if (name === 'expanded') {
+            this._state.setExpanded(this.hasAttribute('expanded'));
+            // A refusal (disabled row) changes nothing, so no subscriber would take the
+            // attribute back down: the state is the truth, the attribute its reflection.
+            this._reflectExpanded(this._state.expanded);
+        }
         this._render();
     }
 
+    /** The `enable-expansion` attribute as a flag: on unless it says `false`. */
+    private _enableAttribute(): boolean {
+        return this.getAttribute('enable-expansion') !== 'false';
+    }
+
+    private _reflectExpanded(expanded: boolean): void {
+        if (this.hasAttribute('expanded') === expanded) return;
+        if (expanded) this.setAttribute('expanded', '');
+        else this.removeAttribute('expanded');
+    }
+
     private _render() {
         // The `string_is_not_empty` label rule, from core — it hides the TITLE too, not
         // just the subtitle.
@@ -234,7 +264,7 @@ export class AdwExpanderRow extends TooltipElement {
         this._enableSwitch.hidden = !showSwitch;
         // OUR write, not the user's — see `_reflectingEnable`.
         this._reflectingEnable = true;
-        this._enableSwitch.active = this.enableExpansion;
+        this._enableSwitch.active = this._state.enableExpansion;
         this._reflectingEnable = false;
 
         this.classList.toggle('expanded', this.expanded);