@gjsify/adwaita-web 0.54.0 → 0.56.0

package/scss/adwaita-skin.scss

@@ -27,6 +27,15 @@
 @use 'labels';
 // <gtk-box>. Before every widget, which may place its own children in one.
 @use 'box';
+// The five Gtk layout containers after it, and they are here for ONE reason each: nothing
+// downstream of `box` needs to place children in one, and the frame's 1px border is the
+// only rule libadwaita writes for any of the five (`_misc.scss:4-15`) — so they belong with
+// the primitive they build on rather than in the widget run below.
+@use 'frame';
+@use 'aspect_frame';
+@use 'center_box';
+@use 'grid';
+@use 'fixed';
 // The REST of libadwaita's documented style-class surface — the widget-
 // independent half: the surfaces (`.background`, `.view`, `.frame`), `.card` and
 // the two boxed lists, `.toolbar`, `.spacer`, `.osd`, `.linked`, the app-icon
@@ -37,14 +46,32 @@
 // documented surface and fails on a class with no rule behind it.
 @use 'style_classes';
 @use 'window';
+@use 'application_window';
+// <adw-header-bar>, <gtk-header-bar> AND <gtk-window-controls>, in ONE partial because
+// upstream's `_header-bar.scss` styles `headerbar`, `windowcontrols` and `windowtitle`
+// together — and because a bar's frame buttons ARE its window controls.
 @use 'headerbar';
 @use 'action_bar';
 @use 'window_title';
 @use 'button';
+// The four button-derived nodes below, in the order of `src/elements/`: each one
+// renders a `.adw-button` of its own, so each rule comes AFTER `button` rather than
+// before it — `button.link`'s transparent background is the whole point of a link and
+// `.adw-button`'s resting fill must not win it on source order.
+@use 'link';
+@use 'scale_button';
+@use 'color_button';
+@use 'font_button';
 @use 'button_content';
 // The ONE popover surface. Emitted BEFORE the widgets that host one, so a
 // consumer's (or a widget's) own higher-specificity rule still wins over it.
 @use 'popover';
+// <gtk-popover-menu>, <gtk-popover-menu-bar> and <gtk-popover-bin>. All three AFTER
+// `popover`, because every surface they own is `<gtk-popover>`'s and none of them restates
+// it — they add the menubar's item rules and the bin's `.has-open-popup`, and libadwaita
+// puts both in the same file as `popover.menu` for the same reason.
+@use 'popover_menu_bar';
+@use 'popover_bin';
 @use 'split_button';
 @use 'menu_button';
 @use 'drop_down';
@@ -54,14 +81,73 @@
 // own copy of it until it was lifted out of `adw-switch-row {}`.
 @use 'switch';
 @use 'entry';
+@use 'search_entry';
+@use 'password_entry';
+@use 'separator';
+// `<gtk-text>`, `<gtk-text-view>` and `<gtk-editable-label>` — the widgets whose content is
+// text, and the two libadwaita blocks that paint a `text` node.
+@use 'text';
+// `<gtk-search-bar>`, which reads the header-bar tokens rather than the header bar's rules.
+@use 'search_bar';
+// <gtk-drawing-area>, the one widget of the gtk/drawing page that carries a rule of its
+// own. No dependency on anything above it — it styles one canvas — so the order here is
+// placement, not precedence.
+@use 'drawing';
+// The `dnd` node, which libadwaita styles once for the whole widget
+// (`_common.scss:30-32`) and which is otherwise geometry: a drag icon has no parent to lay
+// out in, because it is a GtkRoot with its own surface. No dependency on anything above it.
+@use 'drag_icon';
+// The layout CONTAINERS GTK owns and libadwaita only styles. `_paned` draws the divider as
+// an inset box-shadow on the `separator` node a `GtkPanedHandle` carries, which is a
+// different rule from `<gtk-separator>`'s own fill — so it needs its own partial rather
+// than a class the separator's rule would fight over.
+@use 'overlay';
+@use 'revealer';
+@use 'paned';
+@use 'expander';
 // The two form-control primitives, in ONE partial because upstream merges them
 // (there is no `_radio.scss` in libadwaita) — see _checks.scss.
 @use 'checks';
+@use 'spin_button';
+@use 'scale';
 @use 'progress_bar';
+// <gtk-level-bar>, next to the progress bar it is easy to confuse with. It has no
+// dependency on anything above it, so the order here is readability, not precedence.
+@use 'level_bar';
+// The three views, in dependency order: `list_view` declares the selectable-row mixin
+// and the rubber band that the other two include.
+@use 'list_view';
+@use 'grid_view';
+@use 'column_view';
+@use 'tree_expander';
+// The media group, in dependency order and nothing else: `picture` fits a replaced
+// element, `inscription` is text measured in characters and lines, `video` lays an
+// overlay out and hosts a `media_controls` inside its revealer, so `media_controls`
+// comes after `video` only in the sense that `video` NAMES it — neither partial reads
+// the other, and the order here is readability, not precedence.
+@use 'picture';
+@use 'inscription';
+@use 'video';
+@use 'media_controls';
+// The two child-holding containers. `list_box` comes first only because it reads like
+// `list_view`; nothing here is a `@use` of the other, and `flow_box` includes the selectable
+// mixin from `list_view` above for the cell's four state colours.
+@use 'list_box';
+@use 'flow_box';
+@use 'calendar';
 @use 'preferences';
+@use 'preferences_row';
 @use 'card';
 @use 'data_grid';
+@use 'bin';
 @use 'clamp';
+// <gtk-stack> AND <gtk-stack-switcher> AND <gtk-stack-sidebar>, in ONE partial: upstream
+// styles the switcher's buttons out of `_buttons.scss` and the sidebar's rows out of
+// `_sidebars.scss`, so a stack and the two things that switch over it share styles.
+@use 'stack';
+@use 'clamp_scrollable';
+// <adw-spinner> AND <gtk-spinner>, in ONE partial because upstream's
+// `_spinner.scss` styles `spinner` and `image.spinner` in the same file.
 @use 'spinner';
 // <adw-shortcut-label>'s keycaps. After `labels`, because a separator inside it
 // is an ordinary `.dimmed`.
@@ -80,24 +166,47 @@
 @use 'password_entry_row';
 @use 'toast';
 @use 'toolbar_view';
+// The scrolling trio, beside `_scrolling.scss`'s edge indicators: the scrollbar first,
+// because the scrolled window's grid places it, and the viewport before the window, because
+// the window's grid has a cell for it.
+@use 'scrollbar';
+@use 'viewport';
+@use 'scrolled_window';
+@use 'window_handle';
 @use 'scrolling';
 @use 'wrap_box';
 @use 'panes';
 @use 'overlay_split_view';
 @use 'navigation_split_view';
 @use 'carousel';
+// <adw-tab-bar> BEFORE <adw-tab-view>, and only because upstream writes both in ONE file:
+// `tabbar`, `tabbox` and `tab` (_tab-view.scss:1-95). The chip rules here and the merged
+// bar's are the same declarations against the same class names, so whichever partial is
+// emitted second would win on source order for a document that nests one bar in the other.
+@use 'tab_bar';
 @use 'tab_view';
 @use 'view_switcher';
 @use 'inline_view_switcher';
 @use 'view_stack';
 @use 'view_switcher_bar';
+@use 'tab_button';
+@use 'tab_overview';
+@use 'view_switcher_sidebar';
 @use 'navigation_view';
 @use 'bottom_sheet';
 @use 'sidebar';
+// GTK's own dialogs: the about window's layout, the emoji chooser's nodes, and the two
+// Unix print dialogs. After `popover` and `entry`, which the emoji chooser hosts.
+@use 'gtk_about_dialog';
+@use 'emoji_chooser';
+@use 'print_dialogs';
 @use 'about_dialog';
 @use 'alert_dialog';
 @use 'preferences_dialog';
 @use 'dialog';
+// After 'dialog': the shortcuts dialog IS an <adw-dialog> and adds sections and rows
+// inside its content area, so its own rules have to come after the chrome they sit in.
+@use 'shortcuts_dialog';
 // Last among the widgets: an authored `halign` / `valign` is placement the author asked
 // for, and an element rule that sets a margin must not win it back on source order.
 @use 'widget';

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

@@ -13,6 +13,8 @@
 //   - libadwaita has no activatable opt-out for a button row, and
 //     `<adw-action-row activatable="false">` reads by PRESENCE, so it means the
 //     opposite of what it says.
+//   - the row `title-lines`/`subtitle-lines` clamp is observed as RENDERED GEOMETRY, not
+//     as computed style (see `renderedLineCount`).
 import { describe, expect, it } from '@gjsify/unit';
 
 import {
@@ -30,6 +32,9 @@ import { isIconAvailable } from './icon-registry.js';
 import { fallbackMask, maskOf } from './icon-registry.spec.js';
 
 import type { AdwActionRow } from './elements/adw-action-row.js';
+import type { AdwComboRow } from './elements/adw-combo-row.js';
+import type { AdwExpanderRow } from './elements/adw-expander-row.js';
+import type { AdwSpinRow } from './elements/adw-spin-row.js';
 import type { AdwSwitchRow } from './elements/adw-switch-row.js';
 import type { AdwWindowTitle } from './elements/adw-window-title.js';
 
@@ -196,6 +201,134 @@ export const AdwActionRowsTest = async () => {
         });
     });
 
+    /**
+     * The number of lines a row title/subtitle element actually RENDERS, measured from its
+     * height divided by one line box's height.
+     *
+     * NOT the number of rects a `Range` over the element reports. Firefox reports a rect per
+     * laid-out line box and `-webkit-line-clamp` truncates the BOX without re-laying out the
+     * text, so a label clamped to one line still lists every line it would have taken:
+     * measured on a real `adw-switch-row`, `title-lines=1` gave 5 rects for a box that
+     * collapsed from 90px to 18px, and an isolated `display:-webkit-box;
+     * -webkit-line-clamp:1` probe gave 3 rects / 22px against 3 rects / 66px unclamped —
+     * identical rect counts, opposite line counts. Only the HEIGHT moves, so only the height
+     * can carry the claim; the rect count was never a line count and no `-webkit-line-clamp`
+     * implementation can satisfy `expect(rects.length).toBe(1)`.
+     *
+     * The step is the FIRST line box, not the computed `line-height`: the stylesheet sets no
+     * line-height on these labels, so `getComputedStyle().lineHeight` reads `normal` — which
+     * computes to no number at all.
+     */
+    function renderedLineCount(el: HTMLElement): number {
+        const range = document.createRange();
+        range.selectNodeContents(el);
+        const rects = range.getClientRects();
+        const lineBox = rects.length > 0 ? rects[0]!.height : 0;
+        if (!(lineBox > 0)) return Number.NaN;
+        return Math.round(el.getBoundingClientRect().height / lineBox);
+    }
+
+    // Default (0 = unlimited, the AdwActionRow pspec's sentinel): wraps freely.
+    await describe('<adw-action-row> title-lines / subtitle-lines (libadwaita conformance)', async () => {
+        await it('title-lines=0 (default) wraps to multiple lines in narrow container', () => {
+            const { el, host } = mount<AdwActionRow>('adw-action-row');
+            el.setAttribute(
+                'title',
+                'A very long title that should wrap across multiple lines when the container is narrow',
+            );
+            host.style.width = '200px';
+            const lines = renderedLineCount(el.querySelector('.adw-row-title')!);
+            expect(lines).toBeGreaterThan(1);
+            host.remove();
+        });
+
+        await it('subtitle-lines=0 (default) wraps to multiple lines in narrow container', () => {
+            const { el, host } = mount<AdwActionRow>('adw-action-row');
+            el.setAttribute(
+                'subtitle',
+                'A very long subtitle that should wrap across multiple lines when the container is narrow',
+            );
+            host.style.width = '200px';
+            const lines = renderedLineCount(el.querySelector('.adw-row-subtitle')!);
+            expect(lines).toBeGreaterThan(1);
+            host.remove();
+        });
+
+        // title-lines > 0: clamps to N lines
+        await it('title-lines=1 clamps to exactly 1 line', () => {
+            const { el, host } = mount<AdwActionRow>('adw-action-row');
+            el.setAttribute('title', 'Title that is long enough to wrap if allowed');
+            el.setAttribute('title-lines', '1');
+            host.style.width = '150px';
+            const lines = renderedLineCount(el.querySelector('.adw-row-title')!);
+            expect(lines).toBe(1);
+            host.remove();
+        });
+
+        await it('subtitle-lines=2 clamps to exactly 2 lines', () => {
+            const { el, host } = mount<AdwActionRow>('adw-action-row');
+            el.setAttribute('subtitle', 'Subtitle that is long enough to wrap into three lines if allowed');
+            el.setAttribute('subtitle-lines', '2');
+            host.style.width = '150px';
+            const lines = renderedLineCount(el.querySelector('.adw-row-subtitle')!);
+            expect(lines).toBe(2);
+            host.remove();
+        });
+
+        // Dynamic attribute change
+        await it('changing title-lines from 0 to 1 applies clamping visually', () => {
+            const { el, host } = mount<AdwActionRow>('adw-action-row');
+            el.setAttribute('title', 'Title that is long enough to wrap if allowed');
+            el.setAttribute('title-lines', '0');
+            host.style.width = '150px';
+            let lines = renderedLineCount(el.querySelector('.adw-row-title')!);
+            expect(lines).toBeGreaterThan(1);
+
+            el.setAttribute('title-lines', '1');
+            // Force reflow
+            el.getBoundingClientRect();
+            lines = renderedLineCount(el.querySelector('.adw-row-title')!);
+            expect(lines).toBe(1);
+            host.remove();
+        });
+
+        await it('changing title-lines from 1 to 0 removes clamping visually', () => {
+            const { el, host } = mount<AdwActionRow>('adw-action-row');
+            el.setAttribute('title', 'Title that is long enough to wrap if allowed');
+            el.setAttribute('title-lines', '1');
+            host.style.width = '150px';
+            let lines = renderedLineCount(el.querySelector('.adw-row-title')!);
+            expect(lines).toBe(1);
+
+            el.setAttribute('title-lines', '0');
+            el.getBoundingClientRect();
+            lines = renderedLineCount(el.querySelector('.adw-row-title')!);
+            expect(lines).toBeGreaterThan(1);
+            host.remove();
+        });
+
+        // Invalid/non-numeric values treated as 0 (unlimited) — AdwActionRow pspec range is 0..G_MAXINT
+        await it('title-lines="invalid" treated as unlimited (wraps)', () => {
+            const { el, host } = mount<AdwActionRow>('adw-action-row');
+            el.setAttribute('title', 'Title that is long enough to wrap if allowed');
+            el.setAttribute('title-lines', 'invalid');
+            host.style.width = '150px';
+            const lines = renderedLineCount(el.querySelector('.adw-row-title')!);
+            expect(lines).toBeGreaterThan(1);
+            host.remove();
+        });
+
+        await it('subtitle-lines="-1" treated as unlimited (wraps)', () => {
+            const { el, host } = mount<AdwActionRow>('adw-action-row');
+            el.setAttribute('subtitle', 'Subtitle that is long enough to wrap if allowed');
+            el.setAttribute('subtitle-lines', '-1');
+            host.style.width = '150px';
+            const lines = renderedLineCount(el.querySelector('.adw-row-subtitle')!);
+            expect(lines).toBeGreaterThan(1);
+            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}`, () => {
@@ -244,6 +377,152 @@ export const AdwActionRowsTest = async () => {
                 host.remove();
             });
         }
+
+        // title-lines / subtitle-lines tests (same behavior as adw-action-row)
+        await it('title-lines=0 (default) wraps to multiple lines in narrow container', () => {
+            const { el, host } = mount<AdwSwitchRow>('adw-switch-row');
+            el.setAttribute(
+                'title',
+                'A very long title that should wrap across multiple lines when the container is narrow',
+            );
+            host.style.width = '200px';
+            const lines = renderedLineCount(el.querySelector('.adw-row-title')!);
+            expect(lines).toBeGreaterThan(1);
+            host.remove();
+        });
+
+        await it('subtitle-lines=0 (default) wraps to multiple lines in narrow container', () => {
+            const { el, host } = mount<AdwSwitchRow>('adw-switch-row');
+            el.setAttribute(
+                'subtitle',
+                'A very long subtitle that should wrap across multiple lines when the container is narrow',
+            );
+            host.style.width = '200px';
+            const lines = renderedLineCount(el.querySelector('.adw-row-subtitle')!);
+            expect(lines).toBeGreaterThan(1);
+            host.remove();
+        });
+
+        await it('title-lines=1 clamps to exactly 1 line', () => {
+            const { el, host } = mount<AdwSwitchRow>('adw-switch-row');
+            el.setAttribute('title', 'Title that is long enough to wrap if allowed');
+            el.setAttribute('title-lines', '1');
+            host.style.width = '150px';
+            const lines = renderedLineCount(el.querySelector('.adw-row-title')!);
+            expect(lines).toBe(1);
+            host.remove();
+        });
+
+        await it('subtitle-lines=2 clamps to exactly 2 lines', () => {
+            const { el, host } = mount<AdwSwitchRow>('adw-switch-row');
+            el.setAttribute('subtitle', 'Subtitle that is long enough to wrap into three lines if allowed');
+            el.setAttribute('subtitle-lines', '2');
+            host.style.width = '150px';
+            const lines = renderedLineCount(el.querySelector('.adw-row-subtitle')!);
+            expect(lines).toBe(2);
+            host.remove();
+        });
+
+        await it('changing title-lines from 0 to 1 applies clamping visually', () => {
+            const { el, host } = mount<AdwSwitchRow>('adw-switch-row');
+            el.setAttribute('title', 'Title that is long enough to wrap if allowed');
+            el.setAttribute('title-lines', '0');
+            host.style.width = '150px';
+            let lines = renderedLineCount(el.querySelector('.adw-row-title')!);
+            expect(lines).toBeGreaterThan(1);
+
+            el.setAttribute('title-lines', '1');
+            el.getBoundingClientRect();
+            lines = renderedLineCount(el.querySelector('.adw-row-title')!);
+            expect(lines).toBe(1);
+            host.remove();
+        });
+
+        await it('title-lines="invalid" treated as unlimited (wraps)', () => {
+            const { el, host } = mount<AdwSwitchRow>('adw-switch-row');
+            el.setAttribute('title', 'Title that is long enough to wrap if allowed');
+            el.setAttribute('title-lines', 'invalid');
+            host.style.width = '150px';
+            const lines = renderedLineCount(el.querySelector('.adw-row-title')!);
+            expect(lines).toBeGreaterThan(1);
+            host.remove();
+        });
+    });
+
+    await describe('<adw-switch-row> prefix slot (inherited add_prefix)', async () => {
+        // Routing a live child and then deriving the box's emptiness are TWO observers in
+        // a chain: `slotted-children` moves the node into the box, and only that move is
+        // what `bindEmptySections` observes. One checkpoint sees the routing, two see the
+        // derivation.
+        const settleSlot = async () => {
+            await Promise.resolve();
+            await Promise.resolve();
+        };
+        await it('routes a DECLARED slot="prefix" child into the prefix box', () => {
+            // Adw.SwitchRow IS an AdwActionRow (adw-switch-row.c:50), so `add_prefix`
+            // and the box that carries it are inherited, not a web-only addition.
+            // The child is authored BEFORE the row reaches the document, which is the
+            // install pass rather than the observer.
+            const host = document.createElement('div');
+            document.body.appendChild(host);
+            const row = document.createElement('adw-switch-row') as AdwSwitchRow;
+            const icon = document.createElement('span');
+            icon.id = 'lead';
+            icon.setAttribute('slot', 'prefix');
+            row.appendChild(icon);
+            host.appendChild(row);
+
+            expect(icon.parentElement?.className).toBe('adw-switch-row-prefix');
+            host.remove();
+        });
+
+        await it('hides the box while it is empty', () => {
+            const { el: row, host } = mount<AdwSwitchRow>('adw-switch-row');
+            const box = row.querySelector('.adw-switch-row-prefix') as HTMLElement;
+            expect(box.hidden).toBe(true);
+            host.remove();
+        });
+
+        await it('routes a prefix appended AFTER connect, and un-hides the box', async () => {
+            // The live half: a renderer mounts the row and then appends the icon, which
+            // is a MutationObserver callback rather than the install pass — the incident
+            // `src/slotted-children.ts` records for 42 elements that snapshotted instead.
+            const { el: row, host } = mount<AdwSwitchRow>('adw-switch-row');
+            const box = row.querySelector('.adw-switch-row-prefix') as HTMLElement;
+
+            const icon = document.createElement('span');
+            icon.setAttribute('slot', 'prefix');
+            row.appendChild(icon);
+            await settleSlot();
+
+            expect(icon.parentElement).toBe(box);
+            expect(box.hidden).toBe(false);
+            host.remove();
+        });
+
+        await it('shows it again when the last prefix child leaves', async () => {
+            const { el: row, host } = mount<AdwSwitchRow>('adw-switch-row');
+            const icon = document.createElement('span');
+            icon.setAttribute('slot', 'prefix');
+            row.appendChild(icon);
+            await settleSlot();
+            const box = row.querySelector('.adw-switch-row-prefix') as HTMLElement;
+
+            expect(box.hidden).toBe(false);
+            icon.remove();
+            await Promise.resolve();
+            expect(box.hidden).toBe(true);
+            host.remove();
+        });
+
+        await it('exposes the box as prefixSection for the imperative spelling', () => {
+            const { el: row, host } = mount<AdwSwitchRow>('adw-switch-row');
+            const icon = document.createElement('span');
+            row.prefixSection.appendChild(icon);
+
+            expect(icon.parentElement).toBe(row.prefixSection);
+            host.remove();
+        });
     });
 
     await describe('<adw-button-row> (libadwaita conformance vectors)', async () => {
@@ -343,4 +622,56 @@ export const AdwActionRowsTest = async () => {
             host.remove();
         });
     });
+
+    // Line-clamping tests for other row types that inherit title-lines/subtitle-lines
+    await describe('<adw-combo-row> title-lines / subtitle-lines', async () => {
+        await it('title-lines=0 wraps, title-lines=1 clamps to 1 line', () => {
+            const { el, host } = mount<AdwComboRow>('adw-combo-row');
+            el.setAttribute('title', 'Title that is long enough to wrap if allowed');
+            el.setAttribute('title-lines', '0');
+            host.style.width = '150px';
+            let lines = renderedLineCount(el.querySelector('.adw-row-title')!);
+            expect(lines).toBeGreaterThan(1);
+
+            el.setAttribute('title-lines', '1');
+            el.getBoundingClientRect();
+            lines = renderedLineCount(el.querySelector('.adw-row-title')!);
+            expect(lines).toBe(1);
+            host.remove();
+        });
+    });
+
+    await describe('<adw-spin-row> title-lines / subtitle-lines', async () => {
+        await it('title-lines=0 wraps, title-lines=1 clamps to 1 line', () => {
+            const { el, host } = mount<AdwSpinRow>('adw-spin-row');
+            el.setAttribute('title', 'Title that is long enough to wrap if allowed');
+            el.setAttribute('title-lines', '0');
+            host.style.width = '150px';
+            let lines = renderedLineCount(el.querySelector('.adw-row-title')!);
+            expect(lines).toBeGreaterThan(1);
+
+            el.setAttribute('title-lines', '1');
+            el.getBoundingClientRect();
+            lines = renderedLineCount(el.querySelector('.adw-row-title')!);
+            expect(lines).toBe(1);
+            host.remove();
+        });
+    });
+
+    await describe('<adw-expander-row> title-lines / subtitle-lines', async () => {
+        await it('title-lines=0 wraps, title-lines=1 clamps to 1 line', () => {
+            const { el, host } = mount<AdwExpanderRow>('adw-expander-row');
+            el.setAttribute('title', 'Title that is long enough to wrap if allowed');
+            el.setAttribute('title-lines', '0');
+            host.style.width = '150px';
+            let lines = renderedLineCount(el.querySelector('.adw-row-title')!);
+            expect(lines).toBeGreaterThan(1);
+
+            el.setAttribute('title-lines', '1');
+            el.getBoundingClientRect();
+            lines = renderedLineCount(el.querySelector('.adw-row-title')!);
+            expect(lines).toBe(1);
+            host.remove();
+        });
+    });
 };

package/src/adw-application-window.spec.ts

@@ -0,0 +1,118 @@
+// DOM-level behaviour tests for <adw-application-window>. Runs in a real browser via the
+// @gjsify/adwaita-web browser test axis (tests/browser Playwright harness). The custom
+// elements are registered by importing the package root in test.browser.mts; these specs
+// create elements via document.createElement and assert their DOM behaviour.
+//
+// The subject is the MENUBAR and the inheritance: `Adw.ApplicationWindow` is
+// `Adw.Window` plus `Gtk.ApplicationWindow:show-menubar`, so the window half is
+// <adw-window>'s spec and only the delta is asserted here.
+import { describe, it, expect } from '@gjsify/unit';
+
+import type { AdwApplicationWindow } from './elements/adw-application-window.js';
+
+const MENU_MODEL = [
+    {
+        label: 'File',
+        submenu: [
+            { label: 'New Window', action: 'app.new-window' },
+            { label: 'Quit', action: 'app.quit' },
+        ],
+    },
+    { label: 'Help', action: 'app.help' },
+];
+
+function makeWindow(model: unknown = MENU_MODEL): AdwApplicationWindow {
+    const el = document.createElement('adw-application-window') as AdwApplicationWindow;
+    el.setAttribute('menu-model', JSON.stringify(model));
+    el.innerHTML = '<p>Content</p>';
+    document.body.appendChild(el);
+    return el;
+}
+
+export const AdwApplicationWindowTest = async () => {
+    await describe('adw-application-window is an adw-window', async () => {
+        await it('places children in the inherited content area', async () => {
+            const win = makeWindow();
+            expect(win.querySelector('.adw-window-content')?.querySelector('p')?.textContent).toBe('Content');
+            win.remove();
+        });
+
+        await it('keeps the inherited size request', async () => {
+            const win = makeWindow();
+            expect(win.style.width).toBe('360px');
+            win.setAttribute('width', '520');
+            expect(win.style.width).toBe('520px');
+            win.remove();
+        });
+    });
+
+    await describe('adw-application-window menubar', async () => {
+        await it('draws no bar without show-menubar', async () => {
+            const win = makeWindow();
+            expect(win.showMenubar).toBe(false);
+            expect(win.menubar?.hidden).toBe(true);
+            win.remove();
+        });
+
+        await it('draws no bar for an application that installed no menu', async () => {
+            // The GTK half of the same rule: a window with no model has no menubar,
+            // however the flag reads.
+            const win = makeWindow([]);
+            win.setAttribute('show-menubar', '');
+            expect(win.menubar?.hidden).toBe(true);
+            win.remove();
+        });
+
+        await it('a submenu becomes a menu button and a bare item a flat button', async () => {
+            const win = makeWindow();
+            win.setAttribute('show-menubar', '');
+
+            expect(win.menubar?.hidden).toBe(false);
+            const menuButton = win.menubar?.querySelector('gtk-menu-button');
+            expect(menuButton?.getAttribute('menu-title')).toBe('File');
+            const help = win.menubar?.querySelector('gtk-button');
+            expect(help?.getAttribute('label')).toBe('Help');
+            win.remove();
+        });
+
+        await it('the menubar sits above the content, inside the content area', async () => {
+            // It is a child of `.adw-window-content` rather than a sibling: the window's
+            // own slot binding would re-home a sibling into the content on the next tick.
+            const win = makeWindow();
+            win.setAttribute('show-menubar', '');
+            expect(win.contentArea.firstElementChild).toBe(win.menubar);
+            win.remove();
+        });
+
+        await it('the flag alone shows and hides the bar without a rebuild', async () => {
+            const win = makeWindow();
+            win.setAttribute('show-menubar', '');
+            expect(win.menubar?.hidden).toBe(false);
+            win.removeAttribute('show-menubar');
+            expect(win.menubar?.hidden).toBe(true);
+            win.remove();
+        });
+
+        await it('a bare item reports its activation the way every menu surface does', async () => {
+            const win = makeWindow();
+            win.setAttribute('show-menubar', '');
+            const seen: unknown[] = [];
+            win.addEventListener('menu-item-activated', (e) => seen.push((e as CustomEvent).detail));
+            (win.menubar?.querySelector('gtk-button') as HTMLButtonElement | null)?.click();
+            expect(seen).toStrictEqual([{ id: 'Help', label: 'Help', path: [1] }]);
+            win.remove();
+        });
+
+        await it('a broken model is dropped rather than thrown', async () => {
+            // `parseMenuModel` is total by construction: a typo in markup must not take
+            // the window down with it.
+            const win = document.createElement('adw-application-window') as AdwApplicationWindow;
+            win.setAttribute('menu-model', '{not json');
+            win.setAttribute('show-menubar', '');
+            document.body.appendChild(win);
+            expect(win.menuModel).toStrictEqual([]);
+            expect(win.menubar?.hidden).toBe(true);
+            win.remove();
+        });
+    });
+};