@gjsify/adwaita-web 0.53.0 → 0.55.0

package/src/font-description.ts

@@ -0,0 +1,238 @@
+// A `PangoFontDescription` as plain data — the shape `Gtk.FontDialogButton:font-desc`
+// carries (gtkfontdialogbutton.c:340-345), and the only one a browser can hold.
+//
+// WHY A MODULE AND NOT THE ELEMENT. The description is a VALUE with a grammar: Pango's
+// own string form in and out, an equality test, and a projection onto CSS. All three are
+// pure and all three outlive the element — the NativeScript port needs the same parse to
+// give its XML attribute the same meaning, and a copy inside `<gtk-font-dialog-button>`
+// would be the second spelling the second renderer drifts from.
+//
+// THE GRAMMAR IS PANGO'S, and only the part the button uses is here. `from_string` reads
+// a trailing number as the size and every recognised word as a style, in any order, and
+// `to_string` writes them back in ITS order — weight, then slant, then width, then size
+// (`pango_font_description_to_string`). Both are reproduced, including the words
+// themselves, because the string is what `font-desc` carries on the wire and what the
+// C's `pango_font_description_equal` compares.
+//
+// THE FOUR STYLE WORDS A BROWSER HAS. Pango knows twelve weights and three slants; CSS
+// has numbers 1…1000 and two slants, so the projection is total in one direction and
+// lossy in the other: Pango's `ULTRALIGHT` is CSS's `200` and `SEMIBOLD` is `600`, both
+// exactly, because Pango's weights ARE the CSS numbers. Nothing is approximated.
+//
+// Reference: refs/gtk/gtk/gtkfontdialogbutton.c (font_desc, font_description_style_equal,
+//   update_font_info's size format, apply_use_font)
+// `pango_font_description_to_string` itself is PANGO's, not GTK's: the pinned refs/gtk has no
+// pango/ tree, so the word order above is transcribed from Pango's own
+// `pango_font_description_to_string` and there is no refs/ coordinate for a reader to open.
+// `refs/gtk/gtk/gtkfontchooserwidget.c:1549` is the GTK-side counterpart — GTK's one call
+// site that puts the round-tripped string back on the wire.
+// Copyright (c) GNOME contributors (Pango). LGPLv2.1+.
+// Modifications: Implemented for @gjsify/adwaita-web as plain data.
+
+/** The horizontal slant Pango spells. CSS has `italic` and `oblique`, and so does this. */
+export type FontSlant = 'normal' | 'italic' | 'oblique';
+
+/** The four widths Pango distinguishes; CSS `font-stretch` names the same three. */
+export type FontWidth = 'normal' | 'condensed' | 'expanded';
+
+/**
+ * The fields `GtkFontDialogButton` reads. `variant` and the exact family/face are
+ * deliberately absent: the C compares them in `font_description_style_equal`
+ * (gtkfontdialogbutton.c:586-592) to pick a face out of a font map, and a browser page
+ * has no font map — see `font-button`'s header for what stands in for it.
+ */
+export interface PangoFontDescription {
+    /** The family name, or `''` for the "unset" a fresh description carries. */
+    family: string;
+    slant: FontSlant;
+    /** Pango's numeric weight, which is also CSS's `font-weight` number. */
+    weight: number;
+    width: FontWidth;
+    /** The size as written. `unit` says what it is counted in. */
+    size: number;
+    /** `pango_font_description_set_size_is_absolute` — `true` means the size is pixels. */
+    absolute: boolean;
+}
+
+/** The description `gtk_font_dialog_button_init` builds: `pango_font_description_from_string ("Sans 12")`. */
+export const PANGO_FONT_DESCRIPTION_DEFAULT: PangoFontDescription = {
+    family: 'Sans',
+    slant: 'normal',
+    weight: 400,
+    width: 'normal',
+    size: 12,
+    absolute: false,
+};
+
+/**
+ * Pango's style words, and what each one sets. `to_string` emits them in THIS order
+ * (weight, then slant, then width), so a description round-trips to the same string.
+ */
+const STYLE_WORDS: readonly { word: string; set: Partial<Omit<PangoFontDescription, 'family' | 'size'>> }[] = [
+    { word: 'Thin', set: { weight: 100 } },
+    { word: 'UltraLight', set: { weight: 200 } },
+    { word: 'Light', set: { weight: 300 } },
+    { word: 'SemiLight', set: { weight: 350 } },
+    { word: 'Book', set: { weight: 375 } },
+    { word: 'Medium', set: { weight: 500 } },
+    { word: 'SemiBold', set: { weight: 600 } },
+    { word: 'Bold', set: { weight: 700 } },
+    { word: 'UltraBold', set: { weight: 800 } },
+    { word: 'Heavy', set: { weight: 900 } },
+    { word: 'Black', set: { weight: 1000 } },
+    { word: 'Italic', set: { slant: 'italic' } },
+    { word: 'Oblique', set: { slant: 'oblique' } },
+    { word: 'Condensed', set: { width: 'condensed' } },
+    { word: 'Expanded', set: { width: 'expanded' } },
+];
+
+/**
+ * `pango_font_description_from_string` — family, style words and a trailing size, in any
+ * order.
+ *
+ * Total, like the C: an unrecognised word is not a style, and a family is whatever is
+ * left over once the styles and the size are gone — which is why the tokens are consumed
+ * from the END, where Pango reads the size, and a token that matches no style word stays
+ * in the family.
+ */
+export function parseFontDescription(text: string): PangoFontDescription {
+    const description: PangoFontDescription = { ...PANGO_FONT_DESCRIPTION_DEFAULT, family: '' };
+    const tokens = text
+        .trim()
+        .split(/\s+/)
+        .filter((token) => token !== '');
+    // The size is the LAST token that parses as a number, and Pango remembers whether it
+    // was written in pixels.
+    for (let end = tokens.length; end > 0; end--) {
+        const size = /^(-?\d+(?:\.\d+)?)(px)?$/.exec(tokens[end - 1]);
+        if (size === null) continue;
+        description.size = Number(size[1]);
+        description.absolute = size[2] === 'px';
+        tokens.length = end - 1;
+        break;
+    }
+    const family: string[] = [];
+    for (const token of tokens) {
+        const word = STYLE_WORDS.find((entry) => entry.word.toLowerCase() === token.toLowerCase());
+        if (word === undefined) {
+            family.push(token);
+            continue;
+        }
+        Object.assign(description, word.set);
+    }
+    description.family = family.join(' ');
+    return description;
+}
+
+/** `pango_font_description_to_string` — the same words, in the same order. */
+export function formatFontDescription(description: PangoFontDescription): string {
+    const words: string[] = [];
+    for (const { word, set } of STYLE_WORDS) {
+        const matches = Object.entries(set).every(
+            ([key, value]) => description[key as keyof PangoFontDescription] === value,
+        );
+        if (matches && !words.includes(word)) words.push(word);
+    }
+    const size = `${description.size}${description.absolute ? 'px' : ''}`;
+    return [description.family, ...words, size].filter((part) => part !== '').join(' ');
+}
+
+/**
+ * `pango_font_description_equal` — every field, as Pango's own comparison is. `font-desc`
+ * is `G_PARAM_EXPLICIT_NOTIFY` (:345), so a write of the description already held must be
+ * the write that changes nothing (gtkfontdialogbutton.c:869-871).
+ */
+export function fontDescriptionEqual(a: PangoFontDescription, b: PangoFontDescription): boolean {
+    return (
+        a.family === b.family &&
+        a.slant === b.slant &&
+        a.weight === b.weight &&
+        a.width === b.width &&
+        a.size === b.size &&
+        a.absolute === b.absolute
+    );
+}
+
+/**
+ * `update_font_info`'s size format, `g_strdup_printf ("%2.4g%s", size / PANGO_SCALE, …)`
+ * (gtkfontdialogbutton.c:669-673) — four significant digits with the zeros stripped, and
+ * `px` when the size is absolute. `%g` is what `Number#toPrecision` computes and
+ * `Number#toString` then tidies, which is the whole of the difference between `12` and
+ * `12.00`.
+ */
+export function formatFontSize(size: number, absolute: boolean): string {
+    return `${Number(size.toPrecision(4))}${absolute ? 'px' : ''}`;
+}
+
+/**
+ * The CSS projection of a description — `apply_use_font`'s attribute list
+ * (gtkfontdialogbutton.c:689-720), as the four LONGHANDS Pango's own attribute list sets.
+ *
+ * `use_size` is the one field `apply_use_font` may unset, and it is a parameter here for
+ * that reason: `PANGO_FONT_MASK_SIZE` goes only when the size is not wanted.
+ *
+ * The longhands rather than the `font` SHORTHAND, because the shorthand is all-or-nothing:
+ * one rejected token discards the family with it, and a description is half its fields.
+ * `cssFontShorthand` is the same projection for the one caller that needs a string —
+ * `FontFaceSet.check()`, which takes nothing else.
+ *
+ * THE SIZE CARRIES A UNIT, and Pango's own string does not — which is the one place this
+ * projection is not a rename. A bare `12` is a size in Pango (points, because
+ * `PangoFontDescription`'s size is divided by `PANGO_SCALE` and Pango's renderer reads
+ * points) and a length a CSS declaration REJECTS. `pt` is the unit Pango means — one point
+ * is 1/72 inch in both — so an absolute size keeps `px` and everything else becomes `pt`.
+ */
+export interface CssFontParts {
+    fontFamily: string;
+    fontWeight: string;
+    fontStyle: string;
+    fontStretch: string;
+    fontSize: string;
+}
+
+/** An unset family is "None" as a LABEL, not a font to render in — so the generic is. */
+export function cssFontParts(description: PangoFontDescription, useSize: boolean): CssFontParts {
+    return {
+        fontFamily: description.family === '' ? 'sans-serif' : `"${description.family}"`,
+        fontWeight: String(description.weight),
+        fontStyle: description.slant,
+        fontStretch: description.width,
+        fontSize: useSize ? `${description.size}${description.absolute ? 'px' : 'pt'}` : '',
+    };
+}
+
+/** {@link cssFontParts} as one `font` shorthand, for the string-shaped caller. */
+export function cssFontShorthand(description: PangoFontDescription, useSize: boolean): string {
+    const parts = cssFontParts(description, useSize);
+    const shorthand: string[] = [];
+    if (parts.fontStyle !== 'normal') shorthand.push(parts.fontStyle);
+    if (parts.fontWeight !== '400') shorthand.push(parts.fontWeight);
+    if (parts.fontStretch !== 'normal') shorthand.push(parts.fontStretch);
+    if (parts.fontSize !== '') shorthand.push(parts.fontSize);
+    if (shorthand.length > 0) shorthand.push('');
+    return `${shorthand.join(' ')}${parts.fontFamily}`.trim();
+}
+
+/**
+ * Pango's feature list as the TAGS a CSS `font-feature-settings` value is built from — the
+ * one place this module translates rather than renames.
+ *
+ * `pango_font_features_to_string` writes a comma-separated list of bare tags with `-` for
+ * off, which is the same LIST and not the same SYNTAX: CSS wants each tag quoted (`"liga"`).
+ *
+ * The tags come back as a LIST on purpose. `font-feature-settings` is all-or-nothing, and
+ * MEASURED in Firefox: the declaration `"liga", "-kern"` is DROPPED WHOLE — an unknown tag
+ * invalidates the value, not just itself — while `"liga"` alone stands. A single joined
+ * string would therefore lose every tag the browser does not know, which is a silent
+ * difference from Pango's "keep what you recognise". The caller applies the tags one at a
+ * time so a rejection costs one feature.
+ *
+ * `tnum=1` keeps its `=1`, which is Pango's own spelling for "on with a value".
+ */
+export function cssFontFeatureTags(features: string): string[] {
+    return features
+        .split(',')
+        .map((feature) => feature.trim())
+        .filter((feature) => feature !== '')
+        .map((feature) => `"${feature}"`);
+}

package/src/gtk-about-dialog.spec.ts

@@ -0,0 +1,250 @@
+// DOM-level tests for <gtk-about-dialog>. What is worth asserting is the page
+// VISIBILITY derivation — it is the one thing a reader of the rendered dialog cannot work
+// out by looking, and the three rules in `gtkaboutdialog.c` disagree with each other on
+// purpose: a licence page for a CUSTOM licence only, a system page for any text at all, and
+// a credits page for any credit list or extra section.
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { GtkAboutDialog } from './elements/gtk-about-dialog.js';
+import { splitLinks } from './elements/gtk-about-dialog.js';
+
+function mount(attrs: Record<string, string> = {}): { el: GtkAboutDialog; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const el = document.createElement('gtk-about-dialog') as GtkAboutDialog;
+    for (const [name, value] of Object.entries(attrs)) el.setAttribute(name, value);
+    host.appendChild(el);
+    return { el, host };
+}
+
+/** The pages the stack switcher currently offers. */
+function pages(el: GtkAboutDialog): string[] {
+    return [...el.querySelectorAll('.adw-gtk-about-dialog-switcher-item')].map((item) => item.textContent ?? '');
+}
+
+export const GtkAboutDialogTest = async () => {
+    await describe('<gtk-about-dialog> chrome', async () => {
+        await it('is an AdwDialog sheet, and its title is "About <name>"', () => {
+            // update_name_version (gtkaboutdialog.c:1066-1073) — the WINDOW title, which
+            // the headerbar does not display: the `.ui` gives the titlebar a stack switcher
+            // and no title widget.
+            const { el, host } = mount({ 'program-name': 'Calculator' });
+            expect(el.classList.contains('adw-dialog')).toBe(true);
+            expect(el.title).toBe('About Calculator');
+            expect(el.querySelector('.adw-dialog-title')).toBe(null);
+            host.remove();
+        });
+
+        await it('an unset program-name falls back to the application name', () => {
+            // gtk_about_dialog_set_program_name (gtkaboutdialog.c:1095-1112) —
+            // `g_get_application_name ()`, which in a document is its own title.
+            const { el, host } = mount();
+            expect(el.title).toBe(`About ${document.title}`);
+            expect(el.querySelector('.adw-gtk-about-dialog-name')?.textContent).toBe(document.title);
+            host.remove();
+        });
+
+        await it('presenting traps focus and closing gives it back', () => {
+            const opener = document.createElement('button');
+            document.body.appendChild(opener);
+            opener.focus();
+            const { el, host } = mount({ 'program-name': 'Calculator' });
+            el.present();
+            expect(el.open).toBe(true);
+            // The role and `aria-modal` live on the modal SURFACE, as for every dialog
+            // (`surface` in keyboard-operable.spec.ts) — the host carries neither.
+            expect(el.querySelector('.adw-dialog-box')?.getAttribute('aria-modal')).toBe('true');
+            el.close();
+            expect(el.open).toBe(false);
+            expect(document.activeElement).toBe(opener);
+            opener.remove();
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-about-dialog> page visibility', async () => {
+        await it('shows no switcher for a dialog with nothing extra', () => {
+            // update_stack_switcher_visibility (gtkaboutdialog.c:657-670) — the switcher is
+            // visible only when one of the three pages is, so a plain about dialog has an
+            // EMPTY headerbar, exactly as in GTK.
+            const { el, host } = mount({ 'program-name': 'Calculator', version: '1.0' });
+            expect(pages(el)).toStrictEqual([]);
+            expect(el.querySelector('.adw-gtk-about-dialog-switcher')?.hasAttribute('hidden')).toBe(true);
+            host.remove();
+        });
+
+        await it('a licence page needs a CUSTOM licence with text', () => {
+            // update_license_button_visibility (gtkaboutdialog.c:686-696) — the type AND a
+            // non-empty string, which is why `license-type="mit-x11"` alone shows nothing.
+            const { el, host } = mount({ 'program-name': 'Calculator', 'license-type': 'mit-x11' });
+            expect(pages(el)).toStrictEqual([]);
+            el.license = 'Permission is hereby granted, free of charge, …';
+            expect(pages(el)).toStrictEqual(['License']);
+            host.remove();
+        });
+
+        await it('a system page needs text, and clearing it takes the page away', () => {
+            // update_system_button_visibility (gtkaboutdialog.c:700-710).
+            const { el, host } = mount({ 'program-name': 'Calculator' });
+            el.setAttribute('system-information', 'GTK 4.24.0\nglibc 2.42');
+            expect(pages(el)).toStrictEqual(['System']);
+            el.removeAttribute('system-information');
+            expect(pages(el)).toStrictEqual([]);
+            host.remove();
+        });
+
+        await it('credits come from authors, documenters, artists, translators or a section', () => {
+            // populate_credits_page (gtkaboutdialog.c:2029-2080) and its visibility rule
+            // (update_credits_button_visibility, :700-717).
+            const { el, host } = mount({ 'program-name': 'Calculator' });
+            el.authors = ['Ada Lovelace <ada@example.org>', 'Grace Hopper'];
+            expect(pages(el)).toStrictEqual(['Credits']);
+            el.authors = [];
+            expect(pages(el)).toStrictEqual([]);
+            el.addCreditSection('Reviewed by', ['Barbara Liskov']);
+            expect(pages(el)).toStrictEqual(['Credits']);
+            host.remove();
+        });
+
+        await it('an untranslated translator-credits sentinel shows no credits page', () => {
+            // :2064-2068 — the string "translator-credits" comes back unchanged from gettext
+            // in an untranslated locale, and showing THAT to the user is the bug.
+            const { el, host } = mount({ 'program-name': 'Calculator' });
+            el.translatorCredits = 'translator-credits';
+            expect(pages(el)).toStrictEqual([]);
+            el.translatorCredits = 'Ada Lovelace\nGrace Hopper';
+            expect(pages(el)).toStrictEqual(['Credits']);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-about-dialog> content', async () => {
+        await it('the main page shows version, comments, website, copyright and licence', () => {
+            const { el, host } = mount({
+                'program-name': 'Calculator',
+                version: '48.1',
+                comments: 'A four-function calculator.',
+                website: 'https://gitlab.gnome.org/World/gnome-calculator',
+                'website-label': 'GNOME Calculator',
+                copyright: '© 2026 The GNOME Project',
+            });
+            const main = el.querySelector('.adw-gtk-about-dialog-page[data-page="main"]')!;
+            expect(main.querySelector('.adw-gtk-about-dialog-version')?.textContent).toBe('48.1');
+            expect(main.querySelector('.adw-gtk-about-dialog-comments')?.textContent).toBe(
+                'A four-function calculator.',
+            );
+            // update_website (gtkaboutdialog.c:1009-1041) — the LABEL is the link text when
+            // one is set, and the word "Website" when it is not.
+            expect(main.querySelector('a.adw-gtk-about-dialog-website')?.textContent).toBe('GNOME Calculator');
+            expect(main.querySelector('a.adw-gtk-about-dialog-website')?.getAttribute('href')).toBe(
+                'https://gitlab.gnome.org/World/gnome-calculator',
+            );
+            expect(main.querySelector('.adw-gtk-about-dialog-copyright')?.textContent).toBe('© 2026 The GNOME Project');
+            host.remove();
+        });
+
+        await it('a website with no label links the bare word "Website"', () => {
+            const { el, host } = mount({
+                'program-name': 'Calculator',
+                website: 'https://gjsify.org',
+            });
+            expect(el.querySelector('a.adw-gtk-about-dialog-website')?.textContent).toBe('Website');
+            host.remove();
+        });
+
+        await it('a known licence type writes the warranty preamble and wraps it', async () => {
+            // gtk_about_dialog_set_license_type (gtkaboutdialog.c:2259-2313) — a licence
+            // other than CUSTOM OVERWRITES `license` with the disclaimer, links it to that
+            // licence's URL and sets wrap-license TRUE. The disclaimer is the MAIN page's
+            // label (`gtk_label_set_markup`, :2354), NOT a stack page: the License TAB
+            // needs CUSTOM with text (`update_license_button_visibility`, :674-685).
+            const { el, host } = mount({ 'program-name': 'Calculator', website: 'https://gjsify.org' });
+            el.setAttribute('license-type', 'gpl-3-0');
+            const licence = el.querySelector('.adw-gtk-about-dialog-license')!;
+            expect(licence.textContent).toContain('absolutely no warranty');
+            const link = licence.querySelector('a')!;
+            expect(link.getAttribute('href')).toBe('https://www.gnu.org/licenses/gpl-3.0.html');
+            expect(link.textContent).toBe('GNU General Public License, version 3 or later');
+            expect(el.wrapLicense).toBe(false);
+            expect(pages(el)).toStrictEqual([]);
+            host.remove();
+        });
+
+        await it('licence and system text turn <…> and bare URLs into links', async () => {
+            const { el, host } = mount({
+                'program-name': 'Calculator',
+                'system-information': 'Build host: <build@example.org>\nDocs: https://gjsify.org/gtk end',
+            });
+            el.setAttribute('system-information', 'Build host: <build@example.org>\nDocs: https://gjsify.org/gtk end');
+            await Promise.resolve();
+            // Lazy population: the System page is built the first time it is SHOWN
+            // (stack_visible_child_notify, gtkaboutdialog.c:297-333), so open it first.
+            el.showPage('system');
+            const page = el.querySelector('.adw-gtk-about-dialog-page[data-page="system"]')!;
+            const mail = page.querySelector('a[href^="mailto:"]');
+            const url = page.querySelector('a[href="https://gjsify.org/gtk"]');
+            expect(mail?.textContent).toBe('build@example.org');
+            expect(url?.textContent).toBe('https://gjsify.org/gtk');
+            host.remove();
+        });
+
+        await it("the credits page names every section in the C's order", () => {
+            const { el, host } = mount({ 'program-name': 'Calculator' });
+            el.authors = ['Ada Lovelace'];
+            el.documenters = ['Grace Hopper'];
+            el.translatorCredits = 'Barbara Liskov';
+            el.artists = ['Margaret Hamilton'];
+            el.addCreditSection('Reviewed by', ['Tony Hoare']);
+            el.showPage('credits');
+            const headings = [...el.querySelectorAll('.adw-gtk-about-dialog-credits-heading')].map(
+                (heading) => heading.textContent,
+            );
+            expect(headings).toStrictEqual([
+                'Created by',
+                'Documented by',
+                'Translated by',
+                'Design by',
+                'Reviewed by',
+            ]);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-about-dialog> activate-link', async () => {
+        await it('a link click raises a cancelable activate-link', () => {
+            // emit_activate_link (gtkaboutdialog.c:646-655) — BOOLEAN__STRING with the
+            // true-handled accumulator, which is what `preventDefault()` spells.
+            const { el, host } = mount({ 'program-name': 'Calculator', website: 'https://gjsify.org' });
+            const seen: unknown[] = [];
+            el.addEventListener('activate-link', (event) => {
+                seen.push((event as CustomEvent).detail);
+                event.preventDefault();
+            });
+            el.querySelector('a.adw-gtk-about-dialog-website')!.dispatchEvent(
+                new MouseEvent('click', { bubbles: true, cancelable: true }),
+            );
+            expect(seen).toStrictEqual([{ uri: 'https://gjsify.org' }]);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-about-dialog> link scanning', async () => {
+        await it('splits angle-bracket emails, bare URLs and plain text', () => {
+            // text_buffer_new (gtkaboutdialog.c:1903-2028) — the three shapes, in order.
+            expect(splitLinks('a <b@c.org> d')).toStrictEqual([
+                { text: 'a ', uri: null },
+                { text: 'b@c.org', uri: 'mailto:b@c.org' },
+                { text: ' d', uri: null },
+            ]);
+            expect(splitLinks('see https://gjsify.org/x now')).toStrictEqual([
+                { text: 'see ', uri: null },
+                { text: 'https://gjsify.org/x', uri: 'https://gjsify.org/x' },
+                { text: ' now', uri: null },
+            ]);
+        });
+
+        await it('leaves a name that is only a word alone', () => {
+            expect(splitLinks('Ada Lovelace')).toStrictEqual([{ text: 'Ada Lovelace', uri: null }]);
+        });
+    });
+};

package/src/gtk-action-bar.spec.ts

@@ -0,0 +1,89 @@
+// DOM-level tests for <gtk-action-bar>. The bar has ONE property, `revealed`, and everything
+// else about it is WHERE a child lands: `[start]` appends, `[end]` PREpends, `[center]` is the
+// centre widget and a child with no type packs from the start (gtkactionbar.c:220-235,
+// `gtk_action_bar_pack_end` :262-277).
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { GtkActionBar } from './elements/gtk-action-bar.js';
+
+function mount(attrs: Record<string, string> = {}): { el: GtkActionBar; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const el = document.createElement('gtk-action-bar') as GtkActionBar;
+    for (const [name, value] of Object.entries(attrs)) el.setAttribute(name, value);
+    host.appendChild(el);
+    return { el, host };
+}
+
+function child(slot: string | undefined, text: string): HTMLElement {
+    const el = document.createElement('span');
+    if (slot !== undefined) el.setAttribute('slot', slot);
+    el.textContent = text;
+    return el;
+}
+
+export const GtkActionBarTest = async () => {
+    await describe('<gtk-action-bar> placement', async () => {
+        await it('appends a `start` child and PREPENDS an `end` one', async () => {
+            // gtk_action_bar_pack_start is an append and pack_end a PREPEND, so the FIRST
+            // `[end]` child sits nearest the edge (gtkactionbar.c:255-277).
+            const { el, host } = mount();
+            el.append(child('start', 'a'), child('end', 'z'), child('start', 'b'), child('end', 'y'));
+            // Adoption is the MutationObserver's, so it lands on the next microtask
+            // (`src/slotted-children.ts`).
+            await Promise.resolve();
+            expect([...(el.startSection?.children ?? [])].map((n) => n.textContent)).toStrictEqual(['a', 'b']);
+            expect([...(el.endSection?.children ?? [])].map((n) => n.textContent)).toStrictEqual(['y', 'z']);
+            host.remove();
+        });
+
+        await it('packs an untyped child from the start', async () => {
+            // gtkactionbar.c:233-234 — `type == NULL` is pack_start.
+            const { el, host } = mount();
+            const loose = child(undefined, 'loose');
+            el.appendChild(loose);
+            await Promise.resolve();
+            expect(loose.parentElement).toBe(el.startSection);
+            host.remove();
+        });
+
+        await it('routes `center` to the centre section', async () => {
+            // gtk_action_bar_set_center_widget (:306-...) — there is no `center-widget`
+            // PROPERTY in GTK, which is why the slot is spelled `center`.
+            const { el, host } = mount();
+            const centre = child('center', 'mid');
+            el.appendChild(centre);
+            await Promise.resolve();
+            expect(centre.parentElement).toBe(el.centerSection);
+            host.remove();
+        });
+
+        await it('a late child reaches the same place a declared one does', async () => {
+            const { el, host } = mount();
+            const late = child('end', 'late');
+            el.appendChild(late);
+            await Promise.resolve();
+            expect(late.parentElement).toBe(el.endSection);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-action-bar> revealed', async () => {
+        await it('defaults to TRUE, so only revealed="false" hides the bar', () => {
+            // gtkactionbar.c:183 — the property's default is TRUE.
+            const { el, host } = mount();
+            expect(el.revealed).toBe(true);
+            expect(el.hidden).toBe(false);
+            host.remove();
+        });
+
+        await it('hides and shows through the property', () => {
+            const { el, host } = mount({ revealed: 'false' });
+            expect(el.revealed).toBe(false);
+            expect(el.hidden).toBe(true);
+            el.revealed = true;
+            expect(el.hidden).toBe(false);
+            host.remove();
+        });
+    });
+};