@gjsify/adwaita-web 0.38.1 → 0.40.0

package/lib/types/adw-button.spec.d.ts

@@ -0,0 +1 @@
+export declare const AdwButtonTest: () => Promise<void>;

package/lib/types/adw-entry.spec.d.ts

@@ -0,0 +1 @@
+export declare const AdwEntryTest: () => Promise<void>;

package/lib/types/adw-menu-button.spec.d.ts

@@ -0,0 +1 @@
+export declare const AdwMenuButtonTest: () => Promise<void>;

package/lib/types/elements/adw-entry.d.ts

@@ -1,9 +1,15 @@
 export declare class AdwEntry extends HTMLElement {
     private _input;
     private _initialized;
+    private _maxLength;
     static get observedAttributes(): string[];
     get value(): string;
     set value(v: string);
+    /** `Gtk.Entry:max-length` — 0 means unlimited. Counted in CODE POINTS. */
+    get maxLength(): number;
+    set maxLength(value: number);
+    /** `Gtk.Entry:text-length` — code points, not UTF-16 units. */
+    get textLength(): number;
     /** The inner native input (for focus/selection). */
     get input(): HTMLInputElement;
     connectedCallback(): void;

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

@@ -1,12 +1,13 @@
+import './adw-window-title.js';
 export declare class AdwHeaderBar extends HTMLElement {
     private _initialized;
     private _startEl;
     private _centerEl;
     private _endEl;
     /**
-     * The generated title span, 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.
+     * 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.
      */
     private _titleEl;
     static get observedAttributes(): string[];
@@ -24,6 +25,6 @@ export declare class AdwHeaderBar extends HTMLElement {
      * kept whatever it was created with. `Adw.HeaderBar`'s derived title widget
      * is bound to the property and re-renders on every change.
      */
-    attributeChangedCallback(name: string): void;
+    attributeChangedCallback(): void;
     private _renderTitle;
 }

package/lib/types/elements/adw-menu-button.d.ts

@@ -1,11 +1,14 @@
-import type { SplitButtonDirection } from '@gjsify/adwaita-core';
+import type { AdwMenuEntry, SplitButtonDirection } from '@gjsify/adwaita-core';
 import './adw-popover.js';
-/** A menu entry. `id` defaults to `label` on activation; `icon` is optional. */
-export interface AdwMenuItem {
-    id?: string;
-    label: string;
-    icon?: string;
-}
+/**
+ * A menu entry — `@gjsify/adwaita-core`'s {@link AdwMenuEntry}, re-exported under the
+ * name this element has always used.
+ *
+ * It used to be a SECOND declaration of the same shape, and the NativeScript menu
+ * button declared a THIRD that was missing `icon` entirely. One type, so a consumer
+ * writing menu entries writes the same object for either renderer.
+ */
+export type AdwMenuItem = AdwMenuEntry;
 export declare class AdwMenuButton extends HTMLElement {
     private _buttonEl;
     private _popoverEl;
@@ -27,6 +30,14 @@ export declare class AdwMenuButton extends HTMLElement {
     set direction(value: SplitButtonDirection);
     connectedCallback(): void;
     attributeChangedCallback(name: string): void;
+    /**
+     * The `menu` attribute, through the core parser the split button already used.
+     *
+     * The copy this replaces was weaker in a way markup can reach: it kept `id` and
+     * `icon` WHATEVER their runtime type, so `{"label":"Open","id":7}` produced an
+     * entry whose `id` is a number in a field typed `string` — and `id` is what the
+     * activation event reports. The core parser keeps only string-typed extras.
+     */
     private _parseMenuAttr;
     private _onPopoverToggled;
     private _render;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-web",
-    "version": "0.38.1",
+    "version": "0.40.0",
     "description": "Adwaita/Libadwaita web components for browser targets",
     "type": "module",
     "main": "./src/index.ts",
@@ -41,14 +41,14 @@
         "@codemirror/language": "^6.12.4",
         "@codemirror/state": "^6.7.0",
         "@codemirror/view": "^6.43.4",
-        "@gjsify/adwaita-core": "^0.38.1",
-        "@gjsify/adwaita-fonts": "^0.38.1",
-        "@gjsify/adwaita-icons": "^0.38.1",
+        "@gjsify/adwaita-core": "^0.40.0",
+        "@gjsify/adwaita-fonts": "^0.40.0",
+        "@gjsify/adwaita-icons": "^0.40.0",
         "@lezer/highlight": "^1.2.3"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.38.1",
-        "@gjsify/unit": "^0.38.1",
+        "@gjsify/cli": "^0.40.0",
+        "@gjsify/unit": "^0.40.0",
         "sass": "^1.101.0",
         "typescript": "^6.0.3"
     },

package/src/adw-button.spec.ts

@@ -0,0 +1,59 @@
+// DOM-level tests for <adw-button>'s style classes.
+//
+// The element and its NativeScript twin each kept their own attribute→class table,
+// and the two disagreed: `circular` was here and not there. The table now lives in
+// `@gjsify/adwaita-core`, and these drive its vectors through the REAL element, so a
+// renderer that goes back to a private copy fails on the row that names the class.
+
+import { describe, expect, it } from '@gjsify/unit';
+import { BUTTON_STYLE_CLASS_VECTORS } from '@gjsify/adwaita-core/conformance';
+
+/** The boolean attributes this element exposes — the short spellings. */
+const WEB_ATTRIBUTES = new Set(['flat', 'suggested', 'destructive', 'circular', 'pill']);
+
+/** Mount a button carrying the given boolean attributes; return the inner classes. */
+function mountWithStyles(names: readonly string[]): string[] {
+    const el = document.createElement('adw-button');
+    el.setAttribute('label', 'Click me');
+    for (const name of names) el.setAttribute(name, '');
+    document.body.appendChild(el);
+    const btn = el.querySelector('button') as HTMLButtonElement;
+    return Array.from(btn.classList).filter((cls) => cls !== 'adw-button');
+}
+
+function unmountAll(): void {
+    for (const el of Array.from(document.querySelectorAll('adw-button'))) el.remove();
+}
+
+export const AdwButtonTest = async () => {
+    // Rows naming a class the LONG way (`suggested-action`) are the NativeScript
+    // variant spelling — this element has no such attribute. They are partitioned
+    // out here rather than skipped inside the loop, and the partition is asserted,
+    // so a row cannot fall out of coverage unnoticed.
+    const reachable = BUTTON_STYLE_CLASS_VECTORS.filter((v) => v.names.every((n) => WEB_ATTRIBUTES.has(n)));
+    const unreachable = BUTTON_STYLE_CLASS_VECTORS.filter((v) => !v.names.every((n) => WEB_ATTRIBUTES.has(n)));
+
+    await describe('<adw-button> style classes', async () => {
+        for (const { names, classes, rule } of reachable) {
+            await it(`[${names.join(', ')}] → [${classes.join(', ')}] — ${rule}`, () => {
+                expect(mountWithStyles(names)).toStrictEqual([...classes]);
+                unmountAll();
+            });
+        }
+
+        await it('the rows this element cannot express are exactly the long spellings', () => {
+            const names = unreachable.flatMap((v) => v.names).filter((n) => !WEB_ATTRIBUTES.has(n));
+            expect(names).toStrictEqual(['suggested-action', 'suggessted', 'not-a-style']);
+        });
+
+        await it('a style attribute added later is picked up', () => {
+            const el = document.createElement('adw-button');
+            el.setAttribute('label', 'Send');
+            document.body.appendChild(el);
+            el.setAttribute('suggested', '');
+            const btn = el.querySelector('button') as HTMLButtonElement;
+            expect(btn.classList.contains('suggested-action')).toBe(true);
+            unmountAll();
+        });
+    });
+};

package/src/adw-entry.spec.ts

@@ -0,0 +1,73 @@
+// DOM-level tests for <adw-entry>'s length arithmetic.
+//
+// The element had NO max length and no text length, while its NativeScript twin has
+// composed `@gjsify/adwaita-core`'s since it shipped — so the same consumer got a
+// limit on one renderer and none on the other. These drive the core's own vectors
+// against the real element, which is what makes the delegation checkable rather
+// than merely claimed: a re-implementation that counts UTF-16 units instead of code
+// points fails on the row that names it.
+
+import { describe, expect, it } from '@gjsify/unit';
+import { ENTRY_MAX_LENGTH_VECTORS, ENTRY_TEXT_LENGTH_VECTORS } from '@gjsify/adwaita-core/conformance';
+
+import type { AdwEntry } from './elements/adw-entry.js';
+
+/** Mount an entry with the given attributes. */
+function mountEntry(attrs: Record<string, string> = {}): AdwEntry {
+    const entry = document.createElement('adw-entry') as AdwEntry;
+    for (const [name, value] of Object.entries(attrs)) entry.setAttribute(name, value);
+    document.body.appendChild(entry);
+    return entry;
+}
+
+function unmountAll(): void {
+    for (const entry of Array.from(document.querySelectorAll('adw-entry'))) entry.remove();
+}
+
+export const AdwEntryTest = async () => {
+    await describe('<adw-entry> text length', async () => {
+        for (const { text, length, rule } of ENTRY_TEXT_LENGTH_VECTORS) {
+            await it(`${JSON.stringify(text)} → ${length} — ${rule}`, () => {
+                const entry = mountEntry();
+                entry.value = text;
+                expect(entry.textLength).toBe(length);
+                unmountAll();
+            });
+        }
+    });
+
+    await describe('<adw-entry> max length', async () => {
+        for (const { text, maxLength, clamped, length, rule } of ENTRY_MAX_LENGTH_VECTORS) {
+            await it(`${JSON.stringify(text)} @ ${maxLength} — ${rule}`, () => {
+                const entry = mountEntry({ maxlength: String(maxLength) });
+                entry.value = text;
+                expect(entry.value).toBe(clamped);
+                expect(entry.textLength).toBe(length);
+                unmountAll();
+            });
+        }
+
+        await it('clamps what the ATTRIBUTE writes, not only the property', () => {
+            const entry = mountEntry({ maxlength: '5' });
+            entry.setAttribute('value', 'Ada Lovelace');
+            expect(entry.value).toBe('Ada L');
+            unmountAll();
+        });
+
+        await it('re-clamps when the limit is lowered under the current text', () => {
+            const entry = mountEntry();
+            entry.value = 'Ada Lovelace';
+            entry.maxLength = 3;
+            expect(entry.value).toBe('Ada');
+            unmountAll();
+        });
+
+        await it('an unusable limit means unlimited, never "truncate to empty"', () => {
+            const entry = mountEntry({ maxlength: 'nonsense' });
+            entry.value = 'Ada Lovelace';
+            expect(entry.maxLength).toBe(0);
+            expect(entry.value).toBe('Ada Lovelace');
+            unmountAll();
+        });
+    });
+};

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

@@ -78,4 +78,39 @@ export const AdwHeaderBarTest = async () => {
             unmountAll();
         });
     });
+
+    // The centre is the `<adw-window-title>` Adw.HeaderBar itself derives, 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 () => {
+        await it('builds one rather than a bare span', () => {
+            const bar = mountHeaderBar({ title: 'Documents' });
+            expect(bar.querySelector('adw-window-title')).toBeTruthy();
+            unmountAll();
+        });
+
+        await it('renders a subtitle, which it could not before', () => {
+            const bar = mountHeaderBar({ title: 'Documents', subtitle: '12 items' });
+            expect(centerText(bar)).toContain('Documents');
+            expect(centerText(bar)).toContain('12 items');
+            unmountAll();
+        });
+
+        await it('hides the title line when the title is empty — the blank-line bug', () => {
+            // adw-window-title.c:207-208. A header bar with only a subtitle used to
+            // reserve an empty line above it, because the span was always there.
+            const bar = mountHeaderBar({ title: '', subtitle: 'Loading…' });
+            const titleEl = bar.querySelector('.adw-window-title-title') as HTMLElement | null;
+            expect(titleEl?.hidden).toBe(true);
+            unmountAll();
+        });
+
+        await it('a subtitle survives a title write', () => {
+            const bar = mountHeaderBar({ title: 'Documents', subtitle: '12 items' });
+            bar.setAttribute('title', 'Pictures');
+            expect(centerText(bar)).toContain('Pictures');
+            expect(centerText(bar)).toContain('12 items');
+            unmountAll();
+        });
+    });
 };

package/src/adw-menu-button.spec.ts

@@ -0,0 +1,52 @@
+// DOM-level tests for <adw-menu-button>'s `menu` attribute.
+//
+// The element parsed the JSON itself, and the copy was weaker than the core parser
+// the split button next to it already used: it kept `id` and `icon` whatever their
+// runtime type, so author markup could put a number in a field typed `string` — and
+// `id` is exactly what the activation event reports. These drive the core's parse
+// vectors against the real element.
+
+import { describe, expect, it } from '@gjsify/unit';
+import { SPLIT_BUTTON_MENU_PARSE_VECTORS } from '@gjsify/adwaita-core/conformance';
+
+/** Mount a menu button carrying `menu` as JSON, and return its rendered item labels. */
+function mountWithMenu(json: string): { el: HTMLElement; labels: string[] } {
+    const el = document.createElement('adw-menu-button');
+    el.setAttribute('menu', json);
+    document.body.appendChild(el);
+    const labels = Array.from(el.querySelectorAll('.adw-popover button')).map((b) => b.textContent?.trim() ?? '');
+    return { el, labels };
+}
+
+function unmountAll(): void {
+    for (const el of Array.from(document.querySelectorAll('adw-menu-button'))) el.remove();
+}
+
+export const AdwMenuButtonTest = async () => {
+    await describe('<adw-menu-button> menu attribute', async () => {
+        for (const { json, entries, rule } of SPLIT_BUTTON_MENU_PARSE_VECTORS) {
+            await it(`${rule}`, () => {
+                const { labels } = mountWithMenu(json ?? '');
+                expect(labels).toStrictEqual(entries.map((entry) => entry.label));
+                unmountAll();
+            });
+        }
+
+        await it('drops a non-string id instead of leaking a number into the event', () => {
+            const el = document.createElement('adw-menu-button');
+            el.setAttribute('menu', '[{"label":"Open","id":7}]');
+            document.body.appendChild(el);
+
+            let seen: unknown = 'not fired';
+            el.addEventListener('menu-item-activated', (e) => {
+                seen = (e as CustomEvent<{ id: string }>).detail.id;
+            });
+            (el.querySelector('.adw-popover button') as HTMLElement | null)?.click();
+
+            // `id` fell back to the label, which is the documented default — rather
+            // than arriving as the number 7 in a field every consumer reads as text.
+            expect(seen).toBe('Open');
+            unmountAll();
+        });
+    });
+};

package/src/elements/adw-button.ts

@@ -9,15 +9,12 @@
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web; the
 // icon node is <adw-icon>.
 
+import { buttonStyleClasses } from '@gjsify/adwaita-core';
+
 import { createAdwIcon } from './adw-icon.js';
 
-const VARIANT_CLASSES: Record<string, string> = {
-    flat: 'flat',
-    suggested: 'suggested-action',
-    destructive: 'destructive-action',
-    circular: 'circular',
-    pill: 'pill',
-};
+/** The boolean attributes that select a style class; the mapping lives in the core. */
+const STYLE_ATTRIBUTES = ['flat', 'suggested', 'destructive', 'circular', 'pill'] as const;
 
 export class AdwButton extends HTMLElement {
     private _button!: HTMLButtonElement;
@@ -50,9 +47,10 @@ export class AdwButton extends HTMLElement {
     private _render() {
         const btn = this._button;
         btn.className = 'adw-button';
-        for (const [attr, cls] of Object.entries(VARIANT_CLASSES)) {
-            if (this.hasAttribute(attr)) btn.classList.add(cls);
-        }
+        // The attribute → class mapping is `@gjsify/adwaita-core`'s, so this element
+        // and the NativeScript one cannot disagree about which classes exist —
+        // `circular` was in this table and missing from that one.
+        btn.classList.add(...buttonStyleClasses(STYLE_ATTRIBUTES.filter((attr) => this.hasAttribute(attr))));
 
         const icon = this.getAttribute('icon');
         const label = (this.getAttribute('label') ?? this._label).trim();

package/src/elements/adw-entry.ts

@@ -1,18 +1,33 @@
 // <adw-entry> — Adwaita single-line text entry (e.g. a browser URL bar).
-// Attributes: value, placeholder, type, disabled.
-// Property: value (get/set, proxies the inner input).
+// Attributes: value, placeholder, type, disabled, maxlength.
+// Properties: value (get/set, proxies the inner input), maxLength, textLength.
 // Events: native `input` bubbles from the inner input; `activate` (CustomEvent)
 //   fires on Enter — mirroring Gtk.Entry's `activate` signal.
+//
+// The character arithmetic is HEADLESS and lives in `@gjsify/adwaita-core`
+// (ADR 0004): `entryTextLength` counts CODE POINTS and `clampEntryText` truncates
+// on them. `@gjsify/adwaita-nativescript`'s AdwEntry has composed the same two
+// since it shipped; this element counted nothing at all, so the same consumer
+// got a max length on one renderer and none on the other — and the native
+// `maxlength` attribute would not have closed the gap, because the browser
+// counts UTF-16 code units: `'🔒é'` is 2 characters to GTK and to NativeScript,
+// and 3 to `input.maxLength`. That is why the clamp is applied here rather than
+// handed to the platform.
+//
 // Reference: refs/libadwaita/src/stylesheet/widgets/_entries.scss
 // 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
+// length arithmetic composed from @gjsify/adwaita-core.
+
+import { ENTRY_ROW_MAX_LENGTH_LIMIT, clampEntryText, entryTextLength } from '@gjsify/adwaita-core';
 
 export class AdwEntry extends HTMLElement {
     private _input!: HTMLInputElement;
     private _initialized = false;
+    private _maxLength = 0;
 
     static get observedAttributes() {
-        return ['value', 'placeholder', 'type', 'disabled'];
+        return ['value', 'placeholder', 'type', 'disabled', 'maxlength'];
     }
 
     get value(): string {
@@ -20,8 +35,26 @@ export class AdwEntry extends HTMLElement {
     }
 
     set value(v: string) {
-        if (this._input) this._input.value = v;
-        else this.setAttribute('value', v);
+        const clamped = clampEntryText(v ?? '', this._maxLength);
+        if (this._input) this._input.value = clamped;
+        else this.setAttribute('value', clamped);
+    }
+
+    /** `Gtk.Entry:max-length` — 0 means unlimited. Counted in CODE POINTS. */
+    get maxLength(): number {
+        return this._maxLength;
+    }
+
+    set maxLength(value: number) {
+        this._maxLength = Number.isFinite(value)
+            ? Math.min(ENTRY_ROW_MAX_LENGTH_LIMIT, Math.max(0, Math.trunc(value)))
+            : 0;
+        if (this._input) this._input.value = clampEntryText(this._input.value, this._maxLength);
+    }
+
+    /** `Gtk.Entry:text-length` — code points, not UTF-16 units. */
+    get textLength(): number {
+        return entryTextLength(this.value);
     }
 
     /** The inner native input (for focus/selection). */
@@ -33,12 +66,20 @@ export class AdwEntry extends HTMLElement {
         if (this._initialized) return;
         this._initialized = true;
 
+        this.maxLength = Number(this.getAttribute('maxlength') ?? 0);
+
         const input = document.createElement('input');
         input.className = 'adw-entry';
         input.type = this.getAttribute('type') || 'text';
-        input.value = this.getAttribute('value') ?? '';
+        input.value = clampEntryText(this.getAttribute('value') ?? '', this._maxLength);
         input.placeholder = this.getAttribute('placeholder') ?? '';
         input.disabled = this.hasAttribute('disabled');
+        // Typing past the limit is clamped here, on the way in — the same place
+        // NativeScript clamps it, so both renderers refuse the same character.
+        input.addEventListener('input', () => {
+            const clamped = clampEntryText(input.value, this._maxLength);
+            if (clamped !== input.value) input.value = clamped;
+        });
         input.addEventListener('keydown', (e) => {
             if (e.key === 'Enter') {
                 this.dispatchEvent(new CustomEvent('activate', { bubbles: true, detail: { value: input.value } }));
@@ -50,8 +91,12 @@ export class AdwEntry extends HTMLElement {
     }
 
     attributeChangedCallback(name: string, _old: string | null, value: string | null) {
+        if (name === 'maxlength') {
+            this.maxLength = Number(value ?? 0);
+            return;
+        }
         if (!this._input) return;
-        if (name === 'value') this._input.value = value ?? '';
+        if (name === 'value') this._input.value = clampEntryText(value ?? '', this._maxLength);
         else if (name === 'placeholder') this._input.placeholder = value ?? '';
         else if (name === 'type') this._input.type = value || 'text';
         else if (name === 'disabled') this._input.disabled = value !== null;

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

@@ -1,22 +1,37 @@
 // <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
+// `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
+// subtitle at all. So a header bar could not show what its own NativeScript twin
+// could, and the fix is delegation rather than a fourth copy of the derivation.
+//
+// Reference: refs/libadwaita/src/adw-header-bar.c
 // 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.
 
+// Registers <adw-window-title>: the derived centre is one, so importing the bar
+// alone must still define it.
+import './adw-window-title.js';
+
 export class AdwHeaderBar extends HTMLElement {
     private _initialized = false;
     private _startEl: HTMLDivElement | null = null;
     private _centerEl: HTMLDivElement | null = null;
     private _endEl: HTMLDivElement | null = null;
     /**
-     * The generated title span, 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.
+     * 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.
      */
-    private _titleEl: HTMLSpanElement | null = null;
+    private _titleEl: HTMLElement | null = null;
 
     static get observedAttributes() {
-        return ['title'];
+        return ['title', 'subtitle'];
     }
 
     /** The start (left) section container — append buttons/widgets here. */
@@ -56,7 +71,7 @@ export class AdwHeaderBar extends HTMLElement {
         if (centerChildren.length > 0) {
             for (const child of centerChildren) this._centerEl.appendChild(child);
         } else {
-            this._titleEl = document.createElement('span');
+            this._titleEl = document.createElement('adw-window-title');
             this._titleEl.className = 'adw-header-bar-title';
             this._centerEl.appendChild(this._titleEl);
         }
@@ -77,15 +92,23 @@ export class AdwHeaderBar extends HTMLElement {
      * kept whatever it was created with. `Adw.HeaderBar`'s derived title widget
      * is bound to the property and re-renders on every change.
      */
-    attributeChangedCallback(name: string) {
-        if (this._initialized && name === 'title') this._renderTitle();
+    attributeChangedCallback() {
+        if (this._initialized) this._renderTitle();
     }
 
     private _renderTitle() {
         // A `slot="center"` widget replaced the derived title, so there is
         // nothing for the attribute to write to — the same either/or as
         // `Adw.HeaderBar:title-widget`.
-        if (this._titleEl) this._titleEl.textContent = this.getAttribute('title') ?? '';
+        if (!this._titleEl) return;
+        // Forwarded as ATTRIBUTES, so the window title's own change detection and
+        // empty-string collapse do the work. Removing rather than writing `''`
+        // keeps "unset" distinguishable from "set to empty" on the child.
+        for (const name of ['title', 'subtitle']) {
+            const value = this.getAttribute(name);
+            if (value === null) this._titleEl.removeAttribute(name);
+            else this._titleEl.setAttribute(name, value);
+        }
     }
 }
 

package/src/elements/adw-menu-button.ts

@@ -20,8 +20,8 @@
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
-import { isSplitButtonDirection, menuButtonPopupDirection } from '@gjsify/adwaita-core';
-import type { SplitButtonDirection } from '@gjsify/adwaita-core';
+import { isSplitButtonDirection, menuButtonPopupDirection, parseMenuEntries } from '@gjsify/adwaita-core';
+import type { AdwMenuEntry, SplitButtonDirection } from '@gjsify/adwaita-core';
 
 // SIDE-EFFECT import, deliberately separate from the type import below: it guarantees
 // `adw-popover` is defined before this module's `customElements.define` can upgrade a
@@ -34,12 +34,15 @@ import type { AdwPopover } from './adw-popover.js';
 
 import { createAdwIcon } from './adw-icon.js';
 
-/** A menu entry. `id` defaults to `label` on activation; `icon` is optional. */
-export interface AdwMenuItem {
-    id?: string;
-    label: string;
-    icon?: string;
-}
+/**
+ * A menu entry — `@gjsify/adwaita-core`'s {@link AdwMenuEntry}, re-exported under the
+ * name this element has always used.
+ *
+ * It used to be a SECOND declaration of the same shape, and the NativeScript menu
+ * button declared a THIRD that was missing `icon` entirely. One type, so a consumer
+ * writing menu entries writes the same object for either renderer.
+ */
+export type AdwMenuItem = AdwMenuEntry;
 
 /**
  * Where the popover sits, per `GtkArrowType`. `menuButtonPopupDirection` folds `none`
@@ -152,18 +155,16 @@ export class AdwMenuButton extends HTMLElement {
         this._render();
     }
 
+    /**
+     * The `menu` attribute, through the core parser the split button already used.
+     *
+     * The copy this replaces was weaker in a way markup can reach: it kept `id` and
+     * `icon` WHATEVER their runtime type, so `{"label":"Open","id":7}` produced an
+     * entry whose `id` is a number in a field typed `string` — and `id` is what the
+     * activation event reports. The core parser keeps only string-typed extras.
+     */
     private _parseMenuAttr(): AdwMenuItem[] {
-        const raw = this.getAttribute('menu');
-        if (!raw) return [];
-        try {
-            const parsed: unknown = JSON.parse(raw);
-            if (!Array.isArray(parsed)) return [];
-            return parsed
-                .filter((e): e is AdwMenuItem => typeof e === 'object' && e !== null && 'label' in e)
-                .map((e) => ({ id: e.id, label: String(e.label), icon: e.icon }));
-        } catch {
-            return [];
-        }
+        return parseMenuEntries(this.getAttribute('menu'));
     }
 
     private _onPopoverToggled(open: boolean): void {

package/src/elements/adw-status-page.ts

@@ -7,6 +7,8 @@
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web; the
 // icon node is <adw-icon>.
 
+import { stringIsNotEmpty } from '@gjsify/adwaita-core';
+
 import { type AdwIcon, createAdwIcon } from './adw-icon.js';
 
 export class AdwStatusPage extends HTMLElement {
@@ -51,13 +53,16 @@ export class AdwStatusPage extends HTMLElement {
         this._iconEl.iconName = this.getAttribute('icon');
         this._iconEl.hidden = this._iconEl.resolvedIconName === '';
 
+        // `string_is_not_empty` from the core, not a local `.length === 0`: the same
+        // closure the NativeScript port binds its labels to, and the reason a title of
+        // `'   '` stays VISIBLE — it reads the first byte, it never trims.
         const title = this.getAttribute('title') ?? '';
         this._titleEl.textContent = title;
-        this._titleEl.hidden = title.length === 0;
+        this._titleEl.hidden = !stringIsNotEmpty(title);
 
         const description = this.getAttribute('description') ?? '';
         this._descEl.textContent = description;
-        this._descEl.hidden = description.length === 0;
+        this._descEl.hidden = !stringIsNotEmpty(description);
 
         this._childEl.hidden = this._childEl.childElementCount === 0;
     }

package/src/test.browser.mts

@@ -33,6 +33,9 @@ import { AdwViewSwitcherBarTest } from './adw-view-switcher-bar.spec.js';
 import { AdwStyleIsolationTest } from './style-isolation.spec.js';
 import { AdwWrapBoxTest } from './adw-wrap-box.spec.js';
 import { AdwHeaderBarTest } from './adw-header-bar.spec.js';
+import { AdwEntryTest } from './adw-entry.spec.js';
+import { AdwMenuButtonTest } from './adw-menu-button.spec.js';
+import { AdwButtonTest } from './adw-button.spec.js';
 import { AdwBannerTest } from './adw-banner.spec.js';
 import { AdwButtonContentTest } from './adw-button-content.spec.js';
 import { AdwIconTest } from './adw-icon.spec.js';
@@ -77,6 +80,9 @@ run({
     AdwStyleIsolationTest,
     AdwWrapBoxTest,
     AdwHeaderBarTest,
+    AdwEntryTest,
+    AdwMenuButtonTest,
+    AdwButtonTest,
     AdwViewStackTest,
     AdwNavigationViewTest,
     AdwSidebarTest,