@gjsify/adwaita-web 0.31.0 → 0.33.0

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

@@ -0,0 +1,342 @@
+// DOM-level conformance tests for the action-row family — <adw-action-row>,
+// <adw-switch-row>, <adw-button-row> and <adw-window-title> — driven by the SAME
+// vectors the NativeScript renderer asserts against
+// (`@gjsify/adwaita-core/conformance`).
+//
+// What this suite exists to catch, in the words of what it found:
+//   - NEITHER renderer hid an empty TITLE. `string_is_not_empty` is bound to the
+//     title label as much as to the subtitle (adw-action-row.ui:49-53 vs :71-75),
+//     and the browser port hand-rolled the subtitle-only half of that block six
+//     times over.
+//   - a programmatic `switchRow.active = true` emitted nothing here, because the
+//     DOM does not fire `change` for a scripted `.checked =` — while the
+//     NativeScript port, whose `checkedChange` does fire, emitted. One C source,
+//     two opposite answers, and nothing comparing them.
+//   - clicking anywhere but the handle of a switch row did nothing, though
+//     `adw_switch_row_init` makes the whole row the switch's activator.
+//   - `<adw-button-row activatable="false">` was honoured, an opt-out libadwaita
+//     does not have — and `<adw-action-row activatable="false">` meant the
+//     OPPOSITE, because that element reads the attribute by presence.
+import { describe, expect, it } from '@gjsify/unit';
+
+import {
+    ACTION_ROW_ACTIVATION_VECTORS,
+    BUTTON_ROW_ACTIVATABLE_VECTORS,
+    BUTTON_ROW_ICON_VECTORS,
+    LABEL_VISIBILITY_VECTORS,
+    SWITCH_ROW_NOTIFY_VECTORS,
+    WINDOW_TITLE_VECTORS,
+} from '@gjsify/adwaita-core/conformance';
+
+import { normalizeIconName } from '@gjsify/adwaita-core';
+
+import type { AdwActionRow } from './elements/adw-action-row.js';
+import type { AdwSwitchRow } from './elements/adw-switch-row.js';
+import type { AdwWindowTitle } from './elements/adw-window-title.js';
+
+/**
+ * Mount an element imperatively — never through parsed HTML, because several
+ * label vectors hinge on exact whitespace (`' '`, `'\t'`) that an attribute
+ * value in markup is not a reliable carrier for.
+ */
+function mount<T extends HTMLElement>(tag: string): { el: T; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const el = document.createElement(tag) as T;
+    host.appendChild(el);
+    return { el, host };
+}
+
+/** Set an attribute, where `null` means "the property is unset". */
+function setAttr(el: HTMLElement, name: string, value: string | null) {
+    if (value === null) el.removeAttribute(name);
+    else el.setAttribute(name, value);
+}
+
+/** Whether the label matching `selector` is rendered at all. */
+function labelVisible(el: HTMLElement, selector: string): boolean {
+    const label = el.querySelector(selector) as HTMLElement | null;
+    return label !== null && !label.hidden;
+}
+
+/** Collect the `detail` of every `event` dispatched on `el`. */
+function record(el: HTMLElement, event: string): unknown[] {
+    const details: unknown[] = [];
+    el.addEventListener(event, (e) => details.push((e as CustomEvent).detail));
+    return details;
+}
+
+/** Let a MutationObserver callback (the sensitivity binding) be delivered. */
+const tick = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+export const AdwActionRowsTest = async () => {
+    await describe('<adw-action-row> label visibility (libadwaita conformance vectors)', async () => {
+        for (const { text, visible, rule } of LABEL_VISIBILITY_VECTORS) {
+            await it(`title ${JSON.stringify(text)} → ${visible} — ${rule}`, () => {
+                const { el, host } = mount<AdwActionRow>('adw-action-row');
+                setAttr(el, 'title', text);
+                expect(labelVisible(el, '.adw-row-title')).toBe(visible);
+                host.remove();
+            });
+
+            await it(`subtitle ${JSON.stringify(text)} → ${visible} — ${rule}`, () => {
+                const { el, host } = mount<AdwActionRow>('adw-action-row');
+                setAttr(el, 'subtitle', text);
+                expect(labelVisible(el, '.adw-row-subtitle')).toBe(visible);
+                host.remove();
+            });
+        }
+
+        await it('renders the text it was given, whitespace included', () => {
+            const { el, host } = mount<AdwActionRow>('adw-action-row');
+            el.setAttribute('title', ' ');
+            expect((el.querySelector('.adw-row-title') as HTMLElement).textContent).toBe(' ');
+            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 () => {
+                const { el: row, host } = mount<AdwActionRow>('adw-action-row');
+                const widgets = new Map<string, HTMLButtonElement>();
+                let last: HTMLButtonElement | null = null;
+
+                for (const step of vector.steps) {
+                    switch (step.op) {
+                        case 'set-activatable-widget': {
+                            if (step.widget === null) {
+                                row.activatableWidget = null;
+                                break;
+                            }
+                            let widget = widgets.get(step.widget);
+                            if (!widget) {
+                                widget = document.createElement('button');
+                                widget.slot = 'suffix';
+                                row.suffixSection.appendChild(widget);
+                                widgets.set(step.widget, widget);
+                            }
+                            // `GtkWidget:sensitive` — `disabled` is its DOM name.
+                            widget.disabled = step.sensitive === false;
+                            row.activatableWidget = widget;
+                            last = widget;
+                            break;
+                        }
+                        case 'set-widget-sensitive':
+                            if (last) last.disabled = !step.sensitive;
+                            // The binding runs through a MutationObserver.
+                            await tick();
+                            break;
+                        case 'set-activatable':
+                            row.toggleAttribute('activatable', step.activatable);
+                            break;
+                    }
+                }
+
+                expect(row.activatable).toBe(vector.activatable);
+                expect(row.classList.contains('activatable')).toBe(vector.activatable);
+                const expectedWidget = vector.activatableWidget === null ? null : widgets.get(vector.activatableWidget);
+                expect(row.activatableWidget).toBe(expectedWidget ?? null);
+                host.remove();
+            });
+        }
+
+        await it('reads `activatable` by PRESENCE, like every other boolean attribute here', () => {
+            const { el: row, host } = mount<AdwActionRow>('adw-action-row');
+            row.setAttribute('activatable', 'false');
+            // The HTML boolean-attribute convention (`<input disabled="false">`
+            // is disabled), which is how every other boolean attribute in this
+            // package is read. NOT a libadwaita rule — libadwaita has a typed
+            // gboolean and no attribute parsing at all — so it is pinned here
+            // rather than in the cross-renderer vectors. Pinned so the next
+            // reader does not "fix" it into the string comparison
+            // <adw-button-row> used to carry, which gave one markup two
+            // opposite meanings inside one package.
+            expect(row.activatable).toBe(true);
+            host.remove();
+        });
+
+        await it('forwards an activation to the activatable widget, then emits `activated`', () => {
+            const { el: row, host } = mount<AdwActionRow>('adw-action-row');
+            const widget = document.createElement('button');
+            row.suffixSection.appendChild(widget);
+            let widgetClicks = 0;
+            widget.addEventListener('click', () => widgetClicks++);
+            row.activatableWidget = widget;
+
+            const activations = record(row, 'activated');
+            row.click();
+
+            expect(widgetClicks).toBe(1);
+            expect(activations.length).toBe(1);
+            host.remove();
+        });
+
+        await it('leaves a click that came from the widget itself to the widget', () => {
+            const { el: row, host } = mount<AdwActionRow>('adw-action-row');
+            const widget = document.createElement('button');
+            row.suffixSection.appendChild(widget);
+            let widgetClicks = 0;
+            widget.addEventListener('click', () => widgetClicks++);
+            row.activatableWidget = widget;
+            const activations = record(row, 'activated');
+
+            widget.click();
+
+            // One click, and no row activation: GtkListBox does not emit
+            // `row-activated` for a click a child widget claimed. Re-clicking the
+            // widget here would also bounce back into the row's own listener.
+            expect(widgetClicks).toBe(1);
+            expect(activations.length).toBe(0);
+            host.remove();
+        });
+
+        await it('stays silent while unactivatable', () => {
+            const { el: row, host } = mount<AdwActionRow>('adw-action-row');
+            const activations = record(row, 'activated');
+            row.click();
+            expect(activations.length).toBe(0);
+            host.remove();
+        });
+    });
+
+    await describe('<adw-switch-row> notify::active (libadwaita conformance vectors)', async () => {
+        for (const vector of SWITCH_ROW_NOTIFY_VECTORS) {
+            await it(`${vector.name} — ${vector.rule}`, () => {
+                const { el: row, host } = mount<AdwSwitchRow>('adw-switch-row');
+                const events = record(row, 'notify::active');
+
+                for (const step of vector.steps) {
+                    if (step.op === 'set-active') row.active = step.active;
+                    else row.click();
+                }
+
+                expect(row.active).toBe(vector.active);
+                expect((row.querySelector('input[type="checkbox"]') as HTMLInputElement).checked).toBe(vector.active);
+                expect(events.map((detail) => (detail as { active: boolean }).active)).toStrictEqual([
+                    ...vector.emitted,
+                ]);
+                host.remove();
+            });
+        }
+
+        await it('toggles from a click on the handle, without double-toggling', () => {
+            const { el: row, host } = mount<AdwSwitchRow>('adw-switch-row');
+            const events = record(row, 'notify::active');
+            const checkbox = row.querySelector('input[type="checkbox"]') as HTMLInputElement;
+
+            checkbox.click();
+
+            expect(row.active).toBe(true);
+            expect(events.length).toBe(1);
+            host.remove();
+        });
+
+        await it('keeps aria-checked in step with the state (adw-switch-row.c:71-74)', () => {
+            const { el: row, host } = mount<AdwSwitchRow>('adw-switch-row');
+            expect(row.getAttribute('aria-checked')).toBe('false');
+            row.active = true;
+            expect(row.getAttribute('aria-checked')).toBe('true');
+            host.remove();
+        });
+
+        for (const { text, visible, rule } of LABEL_VISIBILITY_VECTORS) {
+            await it(`title ${JSON.stringify(text)} → ${visible} — ${rule}`, () => {
+                const { el, host } = mount<AdwSwitchRow>('adw-switch-row');
+                setAttr(el, 'title', text);
+                expect(labelVisible(el, '.adw-row-title')).toBe(visible);
+                host.remove();
+            });
+        }
+    });
+
+    await describe('<adw-button-row> (libadwaita conformance vectors)', async () => {
+        for (const vector of BUTTON_ROW_ICON_VECTORS) {
+            await it(`${JSON.stringify([vector.startIconName, vector.endIconName])} — ${vector.rule}`, () => {
+                const { el: row, host } = mount<HTMLElement>('adw-button-row');
+                setAttr(row, 'start-icon-name', vector.startIconName);
+                setAttr(row, 'end-icon-name', vector.endIconName);
+
+                // The two `image.icon.{start,end}` nodes are <adw-icon> now, not
+                // hand-rolled decorative spans.
+                const icons = Array.from(row.querySelectorAll('adw-icon')) as HTMLElement[];
+                expect(icons.length).toBe(2);
+                expect(!icons[0]!.hidden).toBe(vector.startIconVisible);
+                expect(!icons[1]!.hidden).toBe(vector.endIconVisible);
+                // The mask class is the NORMALIZED name: the generated classes
+                // never carry `-symbolic`, and this row used to interpolate the
+                // raw one — so `start-icon-name="list-add-symbolic"` asked for a
+                // class that has never existed and drew an empty box.
+                if (vector.startIconVisible) {
+                    expect(icons[0]!.classList.contains(`adw-icon--${normalizeIconName(vector.startIconName)}`)).toBe(
+                        true,
+                    );
+                }
+                if (vector.endIconVisible) {
+                    expect(icons[1]!.classList.contains(`adw-icon--${normalizeIconName(vector.endIconName)}`)).toBe(
+                        true,
+                    );
+                }
+                host.remove();
+            });
+        }
+
+        for (const vector of BUTTON_ROW_ACTIVATABLE_VECTORS) {
+            await it(`activatable=${JSON.stringify(vector.declared)} — ${vector.rule}`, () => {
+                const { el: row, host } = mount<HTMLElement>('adw-button-row');
+                setAttr(row, 'activatable', vector.declared);
+                const activations = record(row, 'activated');
+                row.click();
+
+                expect(row.classList.contains('activatable')).toBe(vector.activatable);
+                expect(activations.length).toBe(1);
+                host.remove();
+            });
+        }
+
+        for (const { text, visible, rule } of LABEL_VISIBILITY_VECTORS) {
+            await it(`title ${JSON.stringify(text)} → ${visible} — ${rule}`, () => {
+                const { el: row, host } = mount<HTMLElement>('adw-button-row');
+                setAttr(row, 'title', text);
+                expect(labelVisible(row, '.adw-button-row-title')).toBe(visible);
+                host.remove();
+            });
+        }
+    });
+
+    await describe('<adw-window-title> (libadwaita conformance vectors)', async () => {
+        for (const vector of WINDOW_TITLE_VECTORS) {
+            await it(`${vector.name} — ${vector.rule}`, () => {
+                const { el, host } = mount<AdwWindowTitle>('adw-window-title');
+                const notified: string[] = [];
+                el.addEventListener('notify::title', () => notified.push('title'));
+                el.addEventListener('notify::subtitle', () => notified.push('subtitle'));
+
+                for (const step of vector.steps) {
+                    setAttr(el, step.op === 'set-title' ? 'title' : 'subtitle', step.value);
+                }
+
+                const title = el.querySelector('.adw-window-title-title') as HTMLElement;
+                const subtitle = el.querySelector('.adw-window-title-subtitle') as HTMLElement;
+                expect(title.textContent).toBe(vector.title);
+                expect(!title.hidden).toBe(vector.titleVisible);
+                expect(subtitle.textContent).toBe(vector.subtitle);
+                expect(!subtitle.hidden).toBe(vector.subtitleVisible);
+                expect(notified).toStrictEqual([...vector.notified]);
+                host.remove();
+            });
+        }
+
+        await it('adopts a declared title without calling it a change', () => {
+            const host = document.createElement('div');
+            document.body.appendChild(host);
+            host.innerHTML = '<adw-window-title title="Documents"></adw-window-title>';
+            const el = host.querySelector('adw-window-title') as AdwWindowTitle;
+            const title = el.querySelector('.adw-window-title-title') as HTMLElement;
+
+            expect(title.textContent).toBe('Documents');
+            expect(title.hidden).toBe(false);
+            host.remove();
+        });
+    });
+};

package/src/adw-avatar.spec.ts

@@ -0,0 +1,176 @@
+// DOM-level conformance tests for <adw-avatar>, driven by the SAME vectors the
+// NativeScript renderer asserts against (`@gjsify/adwaita-core/conformance`).
+//
+// The two renderers used to carry independent copies of the initials + colour
+// derivation, and the copies had drifted apart AND away from libadwaita:
+// this element rendered "AD" for `text="Ada"` where GTK and NS render "A", and
+// both hashed UTF-16 code units where GLib hashes UTF-8 bytes, so every accented
+// name was painted the wrong colour. Nothing failed, because nothing compared
+// them. This suite is that comparison.
+import { describe, expect, it } from '@gjsify/unit';
+
+import { AVATAR_MODE_VECTORS } from '@gjsify/adwaita-core/conformance';
+
+import { AVATAR_COLORS, avatarMaxFontSize } from '@gjsify/adwaita-core';
+import {
+    AVATAR_COLOR_VECTORS,
+    AVATAR_FONT_SIZE_VECTORS,
+    AVATAR_INITIALS_VECTORS,
+} from '@gjsify/adwaita-core/conformance';
+
+/**
+ * Mount an avatar and set `text` through `setAttribute`, never through parsed
+ * HTML — several vectors hinge on exact whitespace (a tab, a run of spaces),
+ * which an attribute value in markup is not a reliable carrier for.
+ */
+function mountAvatar(text: string, showInitials = true): { avatar: HTMLElement; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const avatar = document.createElement('adw-avatar');
+    if (showInitials) avatar.setAttribute('show-initials', '');
+    host.appendChild(avatar);
+    avatar.setAttribute('text', text);
+    return { avatar, host };
+}
+
+/** The rendered initials, i.e. what a user actually sees in the circle. */
+function renderedInitials(avatar: HTMLElement): string {
+    const text = avatar.querySelector('.adw-avatar-text') as HTMLElement | null;
+    if (!text || text.hidden) return '';
+    return text.textContent ?? '';
+}
+
+/** `#rrggbb` in the `rgb(r, g, b)` form the CSSOM serialises inline styles to. */
+function asRgb(hex: string): string {
+    const n = Number.parseInt(hex.slice(1), 16);
+    return `rgb(${(n >> 16) & 0xff}, ${(n >> 8) & 0xff}, ${n & 0xff})`;
+}
+
+export const AdwAvatarTest = async () => {
+    await describe('adw-avatar initials (libadwaita conformance vectors)', async () => {
+        for (const { text, initials, rule } of AVATAR_INITIALS_VECTORS) {
+            await it(`${JSON.stringify(text)} renders ${JSON.stringify(initials)} — ${rule}`, () => {
+                const { avatar, host } = mountAvatar(text);
+                expect(renderedInitials(avatar)).toBe(initials);
+                host.remove();
+            });
+        }
+
+        await it('falls back to the icon when there are no initials', () => {
+            const { avatar, host } = mountAvatar('');
+            expect(renderedInitials(avatar)).toBe('');
+            const icon = avatar.querySelector('.adw-avatar-icon') as HTMLElement;
+            expect(icon.hidden).toBe(false);
+            host.remove();
+        });
+
+        await it('shows the icon when show-initials is absent, even with a name', () => {
+            const { avatar, host } = mountAvatar('Ada Lovelace', false);
+            expect(renderedInitials(avatar)).toBe('');
+            host.remove();
+        });
+    });
+
+    await describe('adw-avatar colour (libadwaita conformance vectors)', async () => {
+        for (const { text, colorClass } of AVATAR_COLOR_VECTORS) {
+            // Only a genuinely EMPTY name drops to icon mode; a whitespace-only
+            // one stays in initials mode (blank label) and is still painted, so
+            // it belongs in this loop.
+            if (text.length === 0) continue;
+
+            await it(`${JSON.stringify(text)} paints color${colorClass}`, () => {
+                const { avatar, host } = mountAvatar(text);
+                const palette = AVATAR_COLORS[colorClass - 1]!;
+                expect(avatar.style.backgroundImage).toBe(
+                    `linear-gradient(${asRgb(palette.start)}, ${asRgb(palette.stop)})`,
+                );
+                expect(avatar.style.color).toBe(asRgb(palette.fg));
+                host.remove();
+            });
+        }
+
+        await it('drops the gradient again when the avatar falls back to its icon', () => {
+            const { avatar, host } = mountAvatar('Ada Lovelace');
+            expect(avatar.style.backgroundImage).not.toBe('');
+            avatar.removeAttribute('show-initials');
+            expect(avatar.style.backgroundImage).toBe('');
+            host.remove();
+        });
+    });
+    await describe('adw-avatar font size (Adw.Avatar update_font_size)', async () => {
+        for (const { size, maxFontSize } of AVATAR_FONT_SIZE_VECTORS) {
+            await it(`size ${size} never exceeds the ${maxFontSize}px cap`, () => {
+                const { avatar, host } = mountAvatar('Ada Lovelace');
+                avatar.setAttribute('size', String(size));
+                const label = avatar.querySelector('.adw-avatar-text') as HTMLElement;
+                const applied = Number.parseFloat(label.style.fontSize);
+                // The measured aspect ratio decides the exact value; what the
+                // element must never do is overflow the circle.
+                expect(applied <= avatarMaxFontSize(size) + 0.001).toBe(true);
+                expect(applied > 0).toBe(true);
+                host.remove();
+            });
+        }
+
+        await it('grows monotonically across the old 31px/32px discontinuity', () => {
+            const { avatar, host } = mountAvatar('Ada Lovelace');
+            const label = avatar.querySelector('.adw-avatar-text') as HTMLElement;
+            const at = (size: number) => {
+                avatar.setAttribute('size', String(size));
+                return Number.parseFloat(label.style.fontSize);
+            };
+            // The old heuristic returned 16px at 31 and 13px at 32.
+            expect(at(32) >= at(31)).toBe(true);
+            expect(at(64) >= at(48)).toBe(true);
+            host.remove();
+        });
+    });
+
+    await describe('adw-avatar mode (Adw.Avatar update_visibility)', async () => {
+        await it('keeps a whitespace-only name in initials mode with a blank label', () => {
+            const { avatar, host } = mountAvatar('   ');
+            const label = avatar.querySelector('.adw-avatar-text') as HTMLElement;
+            const icon = avatar.querySelector('.adw-avatar-icon') as HTMLElement;
+            // libadwaita gates on strlen(text), not on the derived initials.
+            expect(label.hidden).toBe(false);
+            expect(label.textContent).toBe('');
+            expect(icon.hidden).toBe(true);
+            host.remove();
+        });
+    });
+
+    await describe('<adw-avatar> mode (update_visibility, adw-avatar.c:117)', async () => {
+        // The `hasCustomImage` rows are not reachable through this element: it
+        // passes `hasCustomImage: false` unconditionally, because it has no
+        // custom-image support at all — `Adw.Avatar:custom-image` is unported.
+        // Named below rather than silently filtered.
+        for (const { hasCustomImage, showInitials, text, mode, rule } of AVATAR_MODE_VECTORS) {
+            if (hasCustomImage) continue;
+            await it(`initials=${showInitials} "${text}" → ${mode} — ${rule}`, () => {
+                const host = document.createElement('div');
+                document.body.appendChild(host);
+                const avatar = document.createElement('adw-avatar');
+                if (showInitials) avatar.setAttribute('show-initials', '');
+                if (text) avatar.setAttribute('text', text);
+                host.appendChild(avatar);
+
+                // Exactly ONE of the two reachable modes is drawn — the point of
+                // the table is the precedence, and "both visible at once" is the
+                // failure it guards against.
+                const initials = (avatar.querySelector('.adw-avatar-text') as HTMLElement).hidden === false;
+                const icon = (avatar.querySelector('.adw-avatar-icon') as HTMLElement).hidden === false;
+                expect(initials).toBe(mode === 'initials');
+                expect(icon).toBe(mode === 'icon');
+                host.remove();
+            });
+        }
+
+        await it('leaves out only the custom-image rows, which this element cannot reach', () => {
+            const unreachable = AVATAR_MODE_VECTORS.filter((vector) => vector.hasCustomImage);
+            expect(unreachable.length).toBeGreaterThan(0);
+            // Every one of them is an `image` outcome, i.e. the whole mode is
+            // missing rather than a corner of it.
+            for (const vector of unreachable) expect(vector.mode).toBe('image');
+        });
+    });
+};

package/src/adw-banner.spec.ts

@@ -0,0 +1,152 @@
+// DOM-level conformance tests for <adw-banner>, driven by the SAME vectors the
+// NativeScript renderer asserts against (`@gjsify/adwaita-core/conformance`).
+//
+// The two renderers carried independent banner logic and had drifted apart AND
+// away from libadwaita: `revealed` was opt-in here (right) and initialised TRUE
+// on NativeScript with no `visibility` written at all (wrong), `use-markup` was
+// opt-in in both with a comment here asserting that WAS the C default (it is
+// TRUE, adw-banner.c:422-425), `button-style` was in neither, and the mnemonic
+// marker the template pins onto the button (adw-banner.ui:33) was painted as a
+// literal underscore. Nothing failed, because nothing compared them.
+import { describe, expect, it } from '@gjsify/unit';
+
+import { ADW_BANNER_DEFAULTS } from '@gjsify/adwaita-core';
+import {
+    BANNER_BUTTON_STYLE_PARSE_VECTORS,
+    BANNER_BUTTON_STYLE_VECTORS,
+    BANNER_BUTTON_TEXT_VECTORS,
+    BANNER_BUTTON_VISIBLE_VECTORS,
+    BANNER_DEFAULT_VECTORS,
+} from '@gjsify/adwaita-core/conformance';
+import type { AdwBanner } from './elements/adw-banner.js';
+
+/**
+ * Mount a banner, setting attributes through `setAttribute` rather than parsed
+ * HTML — several vectors hinge on exact whitespace (`button-label=" "`), which an
+ * attribute value in markup is not a reliable carrier for.
+ */
+function mount(attributes: Record<string, string> = {}): { el: AdwBanner; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const el = document.createElement('adw-banner') as AdwBanner;
+    for (const [name, value] of Object.entries(attributes)) el.setAttribute(name, value);
+    host.appendChild(el);
+    return { el, host };
+}
+
+const titleEl = (el: AdwBanner): HTMLElement => el.querySelector('.adw-banner-title') as HTMLElement;
+const buttonEl = (el: AdwBanner): HTMLButtonElement => el.querySelector('.adw-banner-button') as HTMLButtonElement;
+
+export const AdwBannerTest = async () => {
+    await describe('adw-banner defaults (libadwaita conformance vectors)', async () => {
+        for (const { property, value, rule } of BANNER_DEFAULT_VECTORS) {
+            if (property === 'use-markup') continue; // deliberate departure, asserted below
+            await it(`${property} → ${JSON.stringify(value)} — ${rule}`, () => {
+                const { el, host } = mount();
+                const actual: Record<string, unknown> = {
+                    title: titleEl(el).textContent,
+                    'button-label': buttonEl(el).textContent,
+                    revealed: el.classList.contains('revealed'),
+                    'button-style': buttonEl(el).classList.contains('suggested-action') ? 'suggested' : 'default',
+                };
+                expect(actual[property]).toBe(value);
+                host.remove();
+            });
+        }
+
+        await it('an unrevealed banner is not laid out at all', () => {
+            const { el, host } = mount({ title: 'Metered connection' });
+            expect(getComputedStyle(el).display).toBe('none');
+            el.setAttribute('revealed', '');
+            expect(getComputedStyle(el).display === 'none').toBe(false);
+            host.remove();
+        });
+    });
+
+    await describe('adw-banner use-markup — a DELIBERATE departure from the C default', async () => {
+        // The C default is unambiguously TRUE (adw-banner.c:422-425) and core
+        // carries it as the spec value. This renderer does NOT adopt it: Pango
+        // markup is not HTML, and defaulting a `title` attribute to `innerHTML`
+        // would make an injection sink out of a widget that is not one in GTK.
+        // The departure is pinned here so it stays a decision rather than
+        // becoming a drift — and so does its cost.
+        await it('core still reports the libadwaita default as TRUE', () => {
+            expect(ADW_BANNER_DEFAULTS.useMarkup).toBe(true);
+        });
+
+        await it('the element defaults to TEXT — a title with tags shows them literally', () => {
+            const { el, host } = mount({ title: '<b>Metered</b> connection', revealed: '' });
+            expect(titleEl(el).textContent).toBe('<b>Metered</b> connection');
+            expect(titleEl(el).querySelector('b')).toBe(null);
+            host.remove();
+        });
+
+        await it('opting in renders markup, which is the developer asserting the title is trusted', () => {
+            const { el, host } = mount({ title: '<b>Metered</b> connection', revealed: '', 'use-markup': '' });
+            expect(titleEl(el).querySelector('b')?.textContent).toBe('Metered');
+            host.remove();
+        });
+    });
+
+    await describe('adw-banner button visibility (libadwaita conformance vectors)', async () => {
+        for (const { label, visible, rule } of BANNER_BUTTON_VISIBLE_VECTORS) {
+            if (label === null) continue; // an absent attribute, covered below
+            await it(`${JSON.stringify(label)} → ${visible} — ${rule}`, () => {
+                const { el, host } = mount({ revealed: '', 'button-label': label });
+                expect(buttonEl(el).hidden).toBe(!visible);
+                host.remove();
+            });
+        }
+
+        await it('no button-label attribute is the NULL case — no button', () => {
+            const { el, host } = mount({ revealed: '' });
+            expect(buttonEl(el).hidden).toBe(true);
+            host.remove();
+        });
+    });
+
+    await describe('adw-banner button text (adw-banner.ui:33 pins use-underline)', async () => {
+        for (const { label, text, rule } of BANNER_BUTTON_TEXT_VECTORS) {
+            await it(`${JSON.stringify(label)} → ${JSON.stringify(text)} — ${rule}`, () => {
+                const { el, host } = mount({ revealed: '', 'button-label': label });
+                expect(buttonEl(el).textContent).toBe(text);
+                host.remove();
+            });
+        }
+
+        await it('the TITLE keeps its underscores — adw-banner.ui:20 pins it to use-underline=False', () => {
+            const { el, host } = mount({ revealed: '', title: 'Snap_shot paused' });
+            expect(titleEl(el).textContent).toBe('Snap_shot paused');
+            host.remove();
+        });
+    });
+
+    await describe('adw-banner button-style (libadwaita conformance vectors)', async () => {
+        for (const { style, classes, rule } of BANNER_BUTTON_STYLE_VECTORS) {
+            await it(`${style} → [${classes.join(', ')}] — ${rule}`, () => {
+                const { el, host } = mount({ revealed: '', 'button-label': 'Resume', 'button-style': style });
+                const button = buttonEl(el);
+                expect(button.classList.contains('suggested-action')).toBe(classes.includes('suggested-action'));
+                expect(button.classList.contains('adw-banner-button')).toBe(true);
+                host.remove();
+            });
+        }
+
+        for (const { input, style, rule } of BANNER_BUTTON_STYLE_PARSE_VECTORS) {
+            if (input === null) continue; // an absent attribute, covered by the defaults block
+            await it(`attribute ${JSON.stringify(input)} → ${style} — ${rule}`, () => {
+                const { el, host } = mount({ revealed: '', 'button-label': 'Resume', 'button-style': input });
+                expect(buttonEl(el).classList.contains('suggested-action')).toBe(style === 'suggested');
+                host.remove();
+            });
+        }
+
+        await it('switching back to default takes the class off again (:766)', () => {
+            const { el, host } = mount({ revealed: '', 'button-label': 'Resume', 'button-style': 'suggested' });
+            expect(buttonEl(el).classList.contains('suggested-action')).toBe(true);
+            el.setAttribute('button-style', 'default');
+            expect(buttonEl(el).classList.contains('suggested-action')).toBe(false);
+            host.remove();
+        });
+    });
+};