@gjsify/adwaita-web 0.51.1 → 0.52.0

package/src/blueprint-markup.spec.ts

@@ -0,0 +1,155 @@
+// The custom-element markup of the `index.html` file the gallery's Web Components tab shows for
+// a one-Blueprint block, PARSED back by the browser and held to the tree `buildSharedTree`
+// makes from the same `.blp`.
+//
+// The website renders that markup with `@gjsify/adwaita-core/markup` from the block's
+// `?shared-tree` projection, on every build. Markup a reader copies has to build the same
+// widget: an attribute spelled against `attributeOf`, a boolean written as `"true"` where the
+// element reads presence, or a slot dropped would each parse fine and mount something else. So every `.blp` under
+// `website/src/blueprints/` is imported below — `scripts/check-website-blueprint-markup.mjs`
+// fails on one that is not.
+
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { SharedTreeNode } from '@gjsify/adwaita-core/conformance';
+import { sharedTreeHtml } from '@gjsify/adwaita-core/markup';
+import { hostTagOf } from '@gjsify/adwaita-core/tags';
+
+import adwaitaActionRowTree from '../../../../website/src/blueprints/adwaita/action-row.blp?shared-tree';
+import adwaitaAvatarTree from '../../../../website/src/blueprints/adwaita/avatar.blp?shared-tree';
+import adwaitaBannerTree from '../../../../website/src/blueprints/adwaita/banner.blp?shared-tree';
+import adwaitaBottomSheetTree from '../../../../website/src/blueprints/adwaita/bottom-sheet.blp?shared-tree';
+import adwaitaButtonContentTree from '../../../../website/src/blueprints/adwaita/button-content.blp?shared-tree';
+import adwaitaButtonRowTree from '../../../../website/src/blueprints/adwaita/button-row.blp?shared-tree';
+import adwaitaCarouselTree from '../../../../website/src/blueprints/adwaita/carousel.blp?shared-tree';
+import clampTree from '../../../../website/src/blueprints/adwaita/clamp.blp?shared-tree';
+import adwaitaComboRowTree from '../../../../website/src/blueprints/adwaita/combo-row.blp?shared-tree';
+import adwaitaEntryRowTree from '../../../../website/src/blueprints/adwaita/entry-row.blp?shared-tree';
+import adwaitaExpanderRowTree from '../../../../website/src/blueprints/adwaita/expander-row.blp?shared-tree';
+import adwaitaHeaderBarTree from '../../../../website/src/blueprints/adwaita/header-bar.blp?shared-tree';
+import adwaitaNavigationSplitViewTree from '../../../../website/src/blueprints/adwaita/navigation-split-view.blp?shared-tree';
+import adwaitaNavigationViewTree from '../../../../website/src/blueprints/adwaita/navigation-view.blp?shared-tree';
+import adwaitaOverlaySplitViewTree from '../../../../website/src/blueprints/adwaita/overlay-split-view.blp?shared-tree';
+import adwaitaPasswordEntryRowTree from '../../../../website/src/blueprints/adwaita/password-entry-row.blp?shared-tree';
+import adwaitaPreferencesGroupTree from '../../../../website/src/blueprints/adwaita/preferences-group.blp?shared-tree';
+import adwaitaShortcutLabelTree from '../../../../website/src/blueprints/adwaita/shortcut-label.blp?shared-tree';
+import adwaitaSidebarTree from '../../../../website/src/blueprints/adwaita/sidebar.blp?shared-tree';
+import adwaitaSpinRowTree from '../../../../website/src/blueprints/adwaita/spin-row.blp?shared-tree';
+import adwaitaSplitButtonTree from '../../../../website/src/blueprints/adwaita/split-button.blp?shared-tree';
+import adwaitaStatusPageTree from '../../../../website/src/blueprints/adwaita/status-page.blp?shared-tree';
+import adwaitaSwitchRowTree from '../../../../website/src/blueprints/adwaita/switch-row.blp?shared-tree';
+import adwaitaToggleGroupTree from '../../../../website/src/blueprints/adwaita/toggle-group.blp?shared-tree';
+import adwaitaToolbarViewTree from '../../../../website/src/blueprints/adwaita/toolbar-view.blp?shared-tree';
+import adwaitaViewSwitcherBarTree from '../../../../website/src/blueprints/adwaita/view-switcher-bar.blp?shared-tree';
+import adwaitaWindowTitleTree from '../../../../website/src/blueprints/adwaita/window-title.blp?shared-tree';
+import adwaitaWrapBoxTree from '../../../../website/src/blueprints/adwaita/wrap-box.blp?shared-tree';
+import gtkButtonTree from '../../../../website/src/blueprints/gtk/button.blp?shared-tree';
+import gtkMenuButtonTree from '../../../../website/src/blueprints/gtk/menu-button.blp?shared-tree';
+
+import { buildSharedTree } from './shared-tree-builder.js';
+
+/** Every one-Blueprint `.blp` of the gallery, by its path under `website/src/blueprints/`. */
+export const GALLERY_BLUEPRINTS: Readonly<Record<string, SharedTreeNode>> = {
+    'adwaita/action-row.blp': adwaitaActionRowTree,
+    'adwaita/avatar.blp': adwaitaAvatarTree,
+    'adwaita/banner.blp': adwaitaBannerTree,
+    'adwaita/bottom-sheet.blp': adwaitaBottomSheetTree,
+    'adwaita/button-content.blp': adwaitaButtonContentTree,
+    'adwaita/button-row.blp': adwaitaButtonRowTree,
+    'adwaita/carousel.blp': adwaitaCarouselTree,
+    'adwaita/clamp.blp': clampTree,
+    'adwaita/combo-row.blp': adwaitaComboRowTree,
+    'adwaita/entry-row.blp': adwaitaEntryRowTree,
+    'adwaita/expander-row.blp': adwaitaExpanderRowTree,
+    'adwaita/header-bar.blp': adwaitaHeaderBarTree,
+    'adwaita/navigation-split-view.blp': adwaitaNavigationSplitViewTree,
+    'adwaita/navigation-view.blp': adwaitaNavigationViewTree,
+    'adwaita/overlay-split-view.blp': adwaitaOverlaySplitViewTree,
+    'adwaita/password-entry-row.blp': adwaitaPasswordEntryRowTree,
+    'adwaita/preferences-group.blp': adwaitaPreferencesGroupTree,
+    'adwaita/shortcut-label.blp': adwaitaShortcutLabelTree,
+    'adwaita/sidebar.blp': adwaitaSidebarTree,
+    'adwaita/spin-row.blp': adwaitaSpinRowTree,
+    'adwaita/split-button.blp': adwaitaSplitButtonTree,
+    'adwaita/status-page.blp': adwaitaStatusPageTree,
+    'adwaita/switch-row.blp': adwaitaSwitchRowTree,
+    'adwaita/toggle-group.blp': adwaitaToggleGroupTree,
+    'adwaita/toolbar-view.blp': adwaitaToolbarViewTree,
+    'adwaita/view-switcher-bar.blp': adwaitaViewSwitcherBarTree,
+    'adwaita/window-title.blp': adwaitaWindowTitleTree,
+    'adwaita/wrap-box.blp': adwaitaWrapBoxTree,
+    'gtk/button.blp': gtkButtonTree,
+    'gtk/menu-button.blp': gtkMenuButtonTree,
+};
+
+/**
+ * An attribute's value as the comparison reads it. `style` is read as the declarations it
+ * sets, one longhand each and sorted: which of the builder's margin and an element's own
+ * `flex-direction` was written first, and whether the serialiser folds two margins into a
+ * `margin-inline`, is text neither side chose and no style resolves differently for.
+ */
+const attributeText = (el: Element, attribute: Attr): string => {
+    if (attribute.name !== 'style') return attribute.value;
+    const style = (el as HTMLElement).style;
+    return [...style]
+        .map((property) => `${property}: ${style.getPropertyValue(property)}`)
+        .sort()
+        .join('; ');
+};
+
+/**
+ * An element tree as text a comparison can hold: the tag, the attributes SORTED (their order is
+ * the one thing markup and a builder may legitimately disagree on, and no element reads it), and
+ * the children, with the indentation between elements dropped since the builder never makes any.
+ */
+const canonical = (el: Element, depth = 0): string => {
+    const attributes = [...el.attributes].map((a) => `${a.name}=${JSON.stringify(attributeText(el, a))}`).sort();
+    const pad = '  '.repeat(depth);
+    const lines = [`${pad}<${el.localName}${attributes.map((a) => ` ${a}`).join('')}>`];
+    for (const node of el.childNodes) {
+        if (node.nodeType === Node.ELEMENT_NODE) lines.push(canonical(node as Element, depth + 1));
+        else if (node.nodeType === Node.TEXT_NODE && node.textContent?.trim() !== '') {
+            lines.push(`${pad}  ${JSON.stringify(node.textContent)}`);
+        }
+    }
+    return lines.join('\n');
+};
+
+const withIds = (node: SharedTreeNode, into: SharedTreeNode[] = []): SharedTreeNode[] => {
+    if (node.id !== undefined) into.push(node);
+    for (const child of node.children ?? []) withIds(child, into);
+    return into;
+};
+
+export const AdwBlueprintMarkupTest = async () => {
+    await describe('adwaita-web: the gallery’s markup, parsed', async () => {
+        for (const [file, tree] of Object.entries(GALLERY_BLUEPRINTS)) {
+            // Both sides DETACHED and upgraded: a detached build runs each element's constructor
+            // and attribute callbacks (a label renders its text on `label=`), and so does parsing
+            // in this document. Neither is connected, so what differs is only what was authored.
+            await it(`${file}: parses to the element tree buildSharedTree makes`, async () => {
+                const parsed = document.createRange().createContextualFragment(sharedTreeHtml(tree));
+                expect(canonical(parsed.firstElementChild!)).toBe(canonical(buildSharedTree(tree)));
+            });
+
+            await it(`${file}: mounted, every id reaches an upgraded element of its tag`, async () => {
+                const host = document.createElement('div');
+                host.innerHTML = sharedTreeHtml(tree);
+                document.body.append(host);
+                try {
+                    const nodes = withIds(tree);
+                    expect(nodes.length > 0).toBe(true);
+                    for (const node of nodes) {
+                        const found = host.querySelector(`#${node.id}`);
+                        const tag = hostTagOf(node.tag);
+                        expect(found?.localName).toBe(tag);
+                        const defined = customElements.get(tag);
+                        expect(defined !== undefined && found instanceof defined).toBe(true);
+                    }
+                } finally {
+                    host.remove();
+                }
+            });
+        }
+    });
+};

package/src/blueprint-tree.spec.ts

@@ -0,0 +1,174 @@
+// ONE `.blp`, RENDERED BY THIS RENDERER — the acceptance case for ADR 0053 clause 1's second
+// exit, taken all the way through a build.
+//
+// `./shared-trees.spec.ts` drives ADR 0051's corpus, which is authored as `SharedTreeNode`
+// literals in `scripts/adwaita-gallery-shared-trees.mjs`. This file drives the OTHER reader of
+// the same shape: a Blueprint file, parsed and projected by `@gjsify/blueprint` and handed over
+// by `@gjsify/vite-plugin-blueprint`'s `?shared-tree` exit at build time. So what is under test
+// is not the builder — that is the sibling's job — it is the JOIN: that a `.blp` a GTK showcase
+// actually ships arrives on this target as a tree this renderer mounts, with the fields ADRs
+// 0066, 0067 and 0068 put on the node still on it — `template`/`object-id`, the translatable
+// marking, and the style classes. Naming two of the three read as a complete list once 0068
+// landed, which is how a reader learns a field is not carried when it is.
+//
+// WHY A SHIPPED FILE AND NOT A FIXTURE. A fixture written for this test would be written to
+// pass it. `showcases/gtk/effect-adw-services/src/window.blp` is a real interface — an
+// `Adw.ToolbarView` with a header bar, a clamp, three preference groups and named rows — and one
+// of the shipped `.blp` whose projection declares NO loss, so nothing about it is refused before
+// it can be rendered. The reach across the tree is the shape the NativeScript driver already uses
+// for the corpus module (`packages/nativescript-bridge/adwaita/src/shared-trees.spec.ts`), for
+// the same reason: the thing under test lives outside the package that renders it.
+//
+// WHAT THIS MEASURED THAT NOTHING HAD, AND WHAT CLOSED IT: SLOT PLACEMENT WAS NOT CARRIED, AND
+// IT COST CAPTIONS. `SharedTreeNode.slot` was on the node shape and read by none of the three
+// tree builders. That went unnoticed because ADR 0051's seven-block corpus authors zero slots —
+// a `.blp` is the first source that authors any, and this one authors four. The two cases below
+// were `it.failing` markers for exactly this gap — the header bar authored `[top]` landing in the
+// toolbar view's CONTENT instead, and the `title-widget:` window title then discarded by
+// `adw-header-bar`'s own build, which derives a title element of its own when its centre is
+// empty — until the builders were given a slot reader (`shared-tree-builder.ts`,
+// `adw-header-bar.ts`, `adw-toolbar-view.ts`); both are plain `it()` now that placement holds.
+//
+// Giving `slot` a reader is a SHARED-VOCABULARY decision and not wiring: `content:`, `[top]` and
+// `title-widget:` are GtkBuilder's names, this renderer's are the unnamed slot, `top` and
+// `center`, and a table mapping one to the other inside one renderer is the per-surface
+// translator ADR 0051 § Alternatives rejected turned down on a measurement. Tracked in
+// `status/open-todos.md`.
+
+import { describe, expect, it } from '@gjsify/unit';
+
+import { hostTagOf } from '@gjsify/adwaita-core/tags';
+
+import { mountSharedTree } from './shared-tree-builder.js';
+
+// The build seam itself. `?shared-tree` is the projection; the same file without the query is
+// the GtkBuilder XML the GTK showcase compiles, and neither import moves the other.
+import windowTree from '../../../../showcases/gtk/effect-adw-services/src/window.blp?shared-tree';
+
+type Node = typeof windowTree;
+
+/** Every tag the authored tree names, in document order, so nothing is transcribed. */
+const authoredTags = (node: Node, into: string[] = []): string[] => {
+    into.push(node.tag);
+    for (const child of node.children ?? []) authoredTags(child, into);
+    return into;
+};
+
+/** Every prop value the source marked `_()`, read off the tree rather than off the `.blp`. */
+const markedCaptions = (node: Node, into: string[] = []): string[] => {
+    for (const prop of Object.keys(node.translatable ?? {})) into.push(String(node.props?.[prop]));
+    for (const child of node.children ?? []) markedCaptions(child, into);
+    return into;
+};
+
+export const AdwBlueprintTreeTest = async () => {
+    await describe('adwaita-web: a shipped .blp, mounted', async () => {
+        await it('arrives as a projected node with its composite class and markings', async () => {
+            // The three fields ADRs 0066 and 0067 added are what make a `.blp` worth reading at
+            // all: without them the root of every shipped file projected to its PARENT type and
+            // said nothing about the class the file is about.
+            expect(windowTree.tag).toBe('AdwApplicationWindow');
+            expect(windowTree.template).toBe('EffectServicesWindow');
+            expect(windowTree.props?.['default-width']).toBe(620);
+            expect(windowTree.translatable?.title !== undefined).toBe(true);
+            // Seven of the fourteen nodes are placed by slot, which is what makes this file the
+            // probe the corpus could not be.
+            expect(authoredTags(windowTree).length).toBe(14);
+        });
+
+        await it('mounts the content subtree exactly as authored', async () => {
+            // FROM THE SCROLLED WINDOW DOWN, and the bound is the measurement rather than
+            // convenience: everything the `.blp` places at `content:` on the toolbar view is
+            // reached through the UNNAMED slot, which is the one placement this renderer and
+            // GtkBuilder spell the same way. Asserting the whole tree here would PASS and prove
+            // nothing — `adw-header-bar` derives a title element of its own, so the filtered
+            // sequence has one `adw-window-title` either way and the authored one can vanish
+            // with the count intact. That node is held by the caption case below instead.
+            const { root, unmount } = mountSharedTree(windowTree);
+            try {
+                const authored = new Set(authoredTags(windowTree).map(hostTagOf));
+                const realised = [...root.querySelectorAll('*')]
+                    .map((el) => el.localName)
+                    .filter((name) => authored.has(name));
+                const from = realised.indexOf('gtk-scrolled-window');
+                expect(from >= 0).toBe(true);
+                expect(realised.slice(from).join(' ')).toBe(
+                    'gtk-scrolled-window adw-clamp gtk-box adw-preferences-group adw-entry-row ' +
+                        'adw-preferences-group adw-action-row adw-preferences-group adw-action-row adw-action-row',
+                );
+            } finally {
+                unmount();
+            }
+        });
+
+        await it('upgrades the custom elements it mounted, and carries the authored props', async () => {
+            const { root, unmount } = mountSharedTree(windowTree);
+            try {
+                // UPGRADED, not merely created: an element this package defines is an instance
+                // of its own class once connected. An unknown tag would be a plain HTMLElement,
+                // and that is what tells the two apart.
+                const defined = customElements.get('adw-preferences-group');
+                expect(defined !== undefined).toBe(true);
+                expect(root.querySelector('adw-preferences-group') instanceof defined!).toBe(true);
+
+                // An authored property, through `attributeOf`'s case rule and nothing else.
+                expect(root.getAttribute('default-width')).toBe('620');
+                expect(root.querySelector('adw-clamp')?.getAttribute('maximum-size')).toBe('560');
+
+                // And a caption that reached the SCREEN, not just an attribute: the element read
+                // it on connect and wrote it into its own label.
+                expect(root.querySelector('adw-preferences-group .adw-preferences-group-title')?.textContent).toBe(
+                    'Read a directory',
+                );
+                expect(root.querySelector('adw-action-row .adw-row-subtitle')?.textContent).toBe('Type a path above.');
+            } finally {
+                unmount();
+            }
+        });
+
+        await it('places a [top] child in the bar the .blp named', async () => {
+            const { root, unmount } = mountSharedTree(windowTree);
+            try {
+                const headerBar = root.querySelector('adw-header-bar');
+                expect(headerBar?.parentElement?.className).toBe('adw-toolbar-view-top');
+            } finally {
+                unmount();
+            }
+        });
+
+        // The TypeScript beside a `.blp` addresses a widget by its Blueprint id, as GTK's
+        // `InternalChildren` does. An id the builder dropped would leave that code nothing to find.
+        await it('reaches a widget by the id the .blp gave it', async () => {
+            const { root, unmount } = mountSharedTree(windowTree);
+            try {
+                expect(root.querySelector('#pathRow')?.localName).toBe('adw-entry-row');
+            } finally {
+                unmount();
+            }
+        });
+
+        // This `.blp` authors no `styles [ ]`, so the tree is written out here.
+        await it('carries the style classes a tree authors', async () => {
+            const { root, unmount } = mountSharedTree({ tag: 'AdwClamp', styleClasses: ['card', 'dim-label'] });
+            try {
+                expect([...root.classList].filter((name) => name === 'card' || name === 'dim-label')).toStrictEqual([
+                    'card',
+                    'dim-label',
+                ]);
+            } finally {
+                unmount();
+            }
+        });
+
+        await it('renders every caption the .blp marks for translation', async () => {
+            const { root, unmount } = mountSharedTree(windowTree);
+            try {
+                const text = root.textContent ?? '';
+                const missing = markedCaptions(windowTree).filter((caption) => !text.includes(caption));
+                expect(missing.join(' | ')).toBe('');
+            } finally {
+                unmount();
+            }
+        });
+    });
+};

package/src/bottom-sheet.spec.ts

@@ -15,11 +15,14 @@ import { describe, expect, it } from '@gjsify/unit';
 
 import type { AdwBottomSheet } from './elements/adw-bottom-sheet.js';
 import {
+    BOTTOM_SHEET_BOTTOM_BAR_VECTORS,
     BOTTOM_SHEET_CLOSE_VECTORS,
+    BOTTOM_SHEET_OPEN_VECTORS,
     BOTTOM_SHEET_PRESENTATION_VECTORS,
+    runBottomSheetBottomBarSteps,
     runBottomSheetSteps,
 } from '@gjsify/adwaita-core/conformance';
-import type { BottomSheetCloseOutcome } from '@gjsify/adwaita-core';
+import type { BottomSheetChrome, BottomSheetCloseOutcome } from '@gjsify/adwaita-core';
 
 /** A mounted sheet with one child in each slot, ready to be driven. */
 function mountSheet(markup = ''): AdwBottomSheet {
@@ -44,6 +47,34 @@ function insideSheet(sheet: AdwBottomSheet): HTMLElement {
     return sheet.querySelector('.adw-bottom-sheet-sheet-body > button') as HTMLElement;
 }
 
+function bottomBar(sheet: AdwBottomSheet): HTMLButtonElement {
+    return sheet.querySelector('.adw-bottom-sheet-bottom-bar') as HTMLButtonElement;
+}
+
+/** A bar child, the shape an app declares: one label inside the bin. */
+function barLabel(text = 'Help'): HTMLElement {
+    const label = document.createElement('span');
+    label.textContent = text;
+    return label;
+}
+
+/**
+ * The chrome, read back off the REAL DOM rather than off the state that produced it.
+ *
+ * `surfaceVisible` has no element of its own: the sheet bin's on-screen-ness is a CSS
+ * transform here (`gtk_widget_set_child_visible` has no DOM counterpart that keeps the
+ * slide), and the two classes that drive that transform are what it is readable from.
+ */
+function chromeOf(sheet: AdwBottomSheet): BottomSheetChrome {
+    const bar = bottomBar(sheet);
+    return {
+        layer: bar.hidden ? 'sheet' : 'bottom-bar',
+        surfaceVisible: sheet.classList.contains('open') || sheet.classList.contains('showing-bottom-bar'),
+        bottomBarInert: bar.classList.contains('inert'),
+        dimmed: dimming(sheet).classList.contains('visible'),
+    };
+}
+
 /** Count the dismissal signals a sheet raises while `run` executes. */
 function recordSignals(sheet: AdwBottomSheet, run: () => void): { attempts: number; delegated: number } {
     let attempts = 0;
@@ -115,6 +146,140 @@ export const AdwBottomSheetTest = async () => {
         }
     });
 
+    await describe('adw-bottom-sheet open gate (libadwaita conformance vectors)', async () => {
+        for (const vector of BOTTOM_SHEET_OPEN_VECTORS) {
+            const { source, open, canOpen, hasBottomBar, revealBottomBar, outcome, rule } = vector;
+            const gates = `canOpen=${canOpen} · bar=${hasBottomBar} · revealed=${revealBottomBar}`;
+            const label = `${source} · open=${open} · ${gates}`;
+            await it(`${label} → ${outcome} — ${rule}`, () => {
+                const sheet = mountSheet();
+                sheet.setBottomBar(hasBottomBar ? barLabel() : null);
+                sheet.canOpen = canOpen;
+                sheet.revealBottomBar = revealBottomBar;
+                sheet.open = open;
+
+                expect(sheet.requestOpen(source)).toBe(outcome);
+                // Returning the right word and opening anyway is still wrong.
+                expect(sheet.open).toBe(outcome === 'open' ? true : open);
+                sheet.remove();
+            });
+        }
+    });
+
+    await describe('adw-bottom-sheet bottom bar (libadwaita conformance vectors)', async () => {
+        for (const vector of BOTTOM_SHEET_BOTTOM_BAR_VECTORS) {
+            await it(vector.rule, () => {
+                const sheet = mountSheet();
+                const notifications: boolean[] = [];
+                sheet.addEventListener('notify::open', (event) => {
+                    notifications.push((event as CustomEvent).detail.open);
+                });
+
+                const outcomes = runBottomSheetBottomBarSteps(
+                    {
+                        setBottomBar: (present) => {
+                            sheet.setBottomBar(present ? barLabel() : null);
+                        },
+                        setCanOpen: (canOpen) => {
+                            sheet.canOpen = canOpen;
+                        },
+                        setRevealBottomBar: (reveal) => {
+                            sheet.revealBottomBar = reveal;
+                        },
+                        setModal: (modal) => {
+                            sheet.modal = modal;
+                        },
+                        setOpen: (open) => {
+                            sheet.open = open;
+                        },
+                        requestOpen: (source) => sheet.requestOpen(source),
+                    },
+                    vector.steps,
+                );
+
+                expect(outcomes).toStrictEqual([...vector.outcomes]);
+                expect(notifications).toStrictEqual([...vector.notifications]);
+                expect(sheet.open).toBe(vector.open);
+                expect(chromeOf(sheet)).toStrictEqual({ ...vector.chrome });
+                sheet.remove();
+            });
+        }
+    });
+
+    await describe('adw-bottom-sheet bottom-bar affordance', async () => {
+        await it('a real click on the bar opens the sheet', () => {
+            // The vectors above call `requestOpen` directly, which proves the GATE and
+            // not the wiring: an element that never listens for the click passes every
+            // one of them. This is the event path an app actually gets.
+            const sheet = mountSheet();
+            sheet.setBottomBar(barLabel());
+            expect(sheet.open).toBe(false);
+            bottomBar(sheet).dispatchEvent(new MouseEvent('click', { bubbles: true }));
+            expect(sheet.open).toBe(true);
+            sheet.remove();
+        });
+
+        await it('declares the bar in markup, and the slot wrapper leaves nothing behind', () => {
+            const sheet = mountSheet(
+                '<adw-bottom-sheet-content><button id="under">Under</button></adw-bottom-sheet-content>' +
+                    '<adw-bottom-sheet-bottom-bar><span id="bar">Help</span></adw-bottom-sheet-bottom-bar>' +
+                    '<adw-bottom-sheet-sheet><button id="inside">Inside</button></adw-bottom-sheet-sheet>',
+            );
+            expect(sheet.querySelector('adw-bottom-sheet-bottom-bar')).toBe(null);
+            expect((sheet.bottomBar as HTMLElement).id).toBe('bar');
+            expect(chromeOf(sheet).layer).toBe('bottom-bar');
+            bottomBar(sheet).dispatchEvent(new MouseEvent('click', { bubbles: true }));
+            expect(sheet.open).toBe(true);
+            sheet.remove();
+        });
+
+        await it('keeps the inert bar enabled and focusable', () => {
+            // `can-open` off adds a style class and nothing else
+            // (adw-bottom-sheet.c:2033-2036). `disabled` would remove the focus stop and
+            // silence the click at the DOM instead of at the gate, which is a different
+            // widget: the bar is still the thing a screen reader announces.
+            const sheet = mountSheet();
+            sheet.setBottomBar(barLabel());
+            sheet.canOpen = false;
+            const bar = bottomBar(sheet);
+            expect(bar.disabled).toBe(false);
+            expect(bar.classList.contains('inert')).toBe(true);
+            bar.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+            expect(sheet.open).toBe(false);
+            sheet.remove();
+        });
+
+        await it('shows the bar again after the sheet is dismissed', () => {
+            // The morph has to run BOTH ways. A port that switched the bin to the sheet
+            // page on open and never switched back leaves a sheet that can be opened
+            // exactly once, and every state assertion above still passes.
+            const sheet = mountSheet();
+            sheet.setBottomBar(barLabel());
+            bottomBar(sheet).dispatchEvent(new MouseEvent('click', { bubbles: true }));
+            expect(chromeOf(sheet).layer).toBe('sheet');
+            dimming(sheet).dispatchEvent(new MouseEvent('click', { bubbles: true }));
+            expect(sheet.open).toBe(false);
+            expect(chromeOf(sheet).layer).toBe('bottom-bar');
+            bottomBar(sheet).dispatchEvent(new MouseEvent('click', { bubbles: true }));
+            expect(sheet.open).toBe(true);
+            sheet.remove();
+        });
+
+        await it('a sheet with no bar has no way in but its owner', () => {
+            // REGRESSION PIN: this element shipped without a bottom bar at all, so an app
+            // whose only affordance is the bar had to reach past the widget and write
+            // `open` itself. Nothing on screen opens this one.
+            const sheet = mountSheet();
+            expect(bottomBar(sheet).hidden).toBe(true);
+            expect(sheet.requestOpen('bottom-bar')).toBe('ignored');
+            expect(sheet.requestOpen('swipe')).toBe('ignored');
+            expect(sheet.open).toBe(false);
+            sheet.open = true;
+            expect(sheet.open).toBe(true);
+            sheet.remove();
+        });
+    });
+
     await describe('adw-bottom-sheet open attribute semantics', async () => {
         await it('open="false" renders CLOSED', () => {
             // `hasAttribute('open')` for the getter while every other boolean uses

package/src/chrome.spec.ts

@@ -503,12 +503,15 @@ export const AdwChromeTest = async () => {
         });
 
         await it('centres a status page in the pane rather than against its top bar', async () => {
-            const host = mountPreview(STATUS_PANE_PREVIEW);
+            // 400px, not the preview's 340: at upstream's metrics this page needs 298px, and
+            // in the 293px a 340px view leaves under its bar GTK would scroll it rather than
+            // centre it.
+            const host = mountPreview(STATUS_PANE_PREVIEW, 400);
             await settle();
             const area = host.querySelector('.adw-toolbar-view-content') as HTMLElement;
             const status = host.querySelector('adw-status-page') as HTMLElement;
 
-            expect(heightOf(area) > 0 && heightOf(area) < 340).toBe(true);
+            expect(heightOf(area) > 0 && heightOf(area) < 400).toBe(true);
             expect(heightOf(status)).toBe(heightOf(area));
 
             // What the reader actually sees, and the discriminator at the same time: