@gjsify/adwaita-web 0.54.0 → 0.55.0

package/src/adw-view-switcher-sidebar.spec.ts

@@ -0,0 +1,281 @@
+// DOM-level tests for <adw-view-switcher-sidebar>: the sidebar-shaped switcher that
+// drives an <adw-view-stack>. What is C here is the GROUPING (`populate_sidebar`), the
+// index for activation (`activated_cb`), the indicator's three states (`update_badge`)
+// and the direction of the selection (`selection_changed_cb`) — so those are what the
+// rows below pin, on top of the shared section vectors.
+import { describe, expect, it } from '@gjsify/unit';
+
+import { VIEW_SWITCHER_SIDEBAR_SECTION_VECTORS } from '@gjsify/adwaita-core/conformance';
+import { createViewSwitcherPage, viewSwitcherSidebarSections } from '@gjsify/adwaita-core';
+
+import type { AdwViewSwitcherSidebar } from './elements/adw-view-switcher-sidebar.js';
+import type { AdwViewStack } from './elements/adw-view-stack.js';
+
+interface PageSpec {
+    name: string;
+    title?: string;
+    icon?: string;
+    startsSection?: string;
+    badge?: string;
+    attention?: boolean;
+    hidden?: boolean;
+}
+
+function mount(
+    pages: PageSpec[],
+    attrs = '',
+): {
+    sidebar: AdwViewSwitcherSidebar;
+    stack: AdwViewStack;
+    host: HTMLElement;
+} {
+    const host = document.createElement('div');
+    const inner = pages
+        .map(
+            (page) =>
+                `<adw-view-stack-page name="${page.name}"${page.title ? ` title="${page.title}"` : ''}` +
+                `${page.icon ? ` icon-name="${page.icon}"` : ''}${page.startsSection ? ` starts-section` : ''}` +
+                `${page.startsSection && page.startsSection !== 'true' ? ` section-title="${page.startsSection}"` : ''}` +
+                `${page.badge ? ` badge-number="${page.badge}"` : ''}${page.attention ? ' needs-attention' : ''}` +
+                `${page.hidden ? ' hidden' : ''}></adw-view-stack-page>`,
+        )
+        .join('');
+    // A plain row, NOT an <adw-navigation-split-view>: libadwaita refuses anything but an
+    // `Adw.NavigationPage` in either pane (`g_return_if_fail (ADW_IS_NAVIGATION_PAGE …)`,
+    // adw-navigation-split-view.c), so the split view would drop both of these rather
+    // than showing them side by side.
+    host.innerHTML =
+        `<div class="stage" style="display:flex">` +
+        `<adw-view-switcher-sidebar ${attrs}></adw-view-switcher-sidebar>` +
+        `<adw-view-stack>${inner}</adw-view-stack>` +
+        `</div>`;
+    document.body.appendChild(host);
+    return {
+        sidebar: host.querySelector('adw-view-switcher-sidebar') as AdwViewSwitcherSidebar,
+        stack: host.querySelector('adw-view-stack') as AdwViewStack,
+        host,
+    };
+}
+
+const rows = (sidebar: AdwViewSwitcherSidebar): HTMLElement[] =>
+    Array.from(sidebar.querySelectorAll('adw-sidebar > .adw-sidebar-list .adw-sidebar-item'));
+const headings = (sidebar: AdwViewSwitcherSidebar): string[] =>
+    Array.from(sidebar.querySelectorAll('adw-sidebar .adw-sidebar-section-heading')).map((el) => el.textContent ?? '');
+const indicator = (sidebar: AdwViewSwitcherSidebar, row: number): HTMLElement =>
+    rows(sidebar)[row].querySelector('.indicator') as HTMLElement;
+
+export const AdwViewSwitcherSidebarTest = async () => {
+    await describe('viewSwitcherSidebarSections (populate_sidebar)', async () => {
+        await it('drives the same grouping the conformance table pins', async () => {
+            for (const vector of VIEW_SWITCHER_SIDEBAR_SECTION_VECTORS) {
+                const names = vector.pages === '' ? [] : vector.pages.split(',');
+                const starts = vector.starts === '' ? [] : vector.starts.split(',');
+                const pages = names.map((name) =>
+                    createViewSwitcherPage({
+                        name,
+                        startsSection: starts.includes(name),
+                        sectionTitle: vector.sections.split(',')[starts.indexOf(name)] ?? null,
+                    }),
+                );
+                const sections = viewSwitcherSidebarSections(pages);
+                expect(sections.map((section) => section.pages.map((page) => page.name).join(','))).toStrictEqual(
+                    vector.groups === '' ? [] : vector.groups.split('/'),
+                );
+            }
+        });
+    });
+
+    await describe('<adw-view-switcher-sidebar> sections', async () => {
+        await it('gives every stack page a row, in stack order', async () => {
+            const { sidebar, host } = mount([
+                { name: 'inbox', title: 'Inbox', icon: 'mail-unread' },
+                { name: 'drafts', title: 'Drafts' },
+            ]);
+            expect(rows(sidebar)).toHaveLength(2);
+            expect(rows(sidebar)[0].querySelector('.adw-sidebar-item-title')?.textContent).toBe('Inbox');
+            expect(rows(sidebar)[1].querySelector('.adw-sidebar-item-title')?.textContent).toBe('Drafts');
+            expect((rows(sidebar)[0].querySelector('.adw-sidebar-item-icon') as HTMLElement).hidden).toBe(false);
+            host.remove();
+        });
+
+        await it('splits the pages at starts-section, headed by section-title', async () => {
+            const { sidebar, host } = mount([
+                { name: 'inbox', title: 'Inbox' },
+                { name: 'drafts', title: 'Drafts' },
+                { name: 'archive', title: 'Archive', startsSection: 'Archive' },
+            ]);
+            expect(rows(sidebar)).toHaveLength(3);
+            expect(headings(sidebar)).toStrictEqual(['Archive']);
+            // ONE header, and it is the titled one: the leading untitled section draws
+            // NOTHING, because `create_header` binds that stack's `visible` to
+            // `string_is_not_empty (title)` (adw-sidebar.c:1461-1467) — the header C builds
+            // there is invisible, so there is no separator to count either.
+            expect(sidebar.querySelectorAll('adw-sidebar .adw-sidebar-section-header')).toHaveLength(1);
+            host.remove();
+        });
+
+        await it('draws a separator, not a second heading, for an untitled section after the first', async () => {
+            // The untitled section opens on `archive` and holds `spam` with it, so the
+            // separator C binds (`get_header_stack_page` → "separator", :1425-1434) is the
+            // only header between the two.
+            const { sidebar, host } = mount([
+                { name: 'inbox', title: 'Inbox' },
+                { name: 'archive', title: 'Archive', startsSection: 'true' },
+                { name: 'spam', title: 'Spam' },
+            ]);
+            expect(rows(sidebar)).toHaveLength(3);
+            // The leading section is untitled too — `section-title` is the only thing that
+            // titles a section, and `inbox` declares none — so `Archive`'s section is the
+            // separator's and there is no heading at all.
+            expect(headings(sidebar)).toStrictEqual([]);
+            expect(sidebar.querySelectorAll('adw-sidebar .adw-sidebar-section-header.separator')).toHaveLength(1);
+            host.remove();
+        });
+
+        await it('keeps a hidden page as a row, because C binds visible rather than dropping it', async () => {
+            const { sidebar, host } = mount([
+                { name: 'inbox', title: 'Inbox' },
+                { name: 'drafts', title: 'Drafts', hidden: true },
+            ]);
+            expect(rows(sidebar)).toHaveLength(2);
+            expect(rows(sidebar)[1].hidden).toBe(true);
+            host.remove();
+        });
+    });
+
+    await describe('<adw-view-switcher-sidebar> selection and activation', async () => {
+        await it('marks the row of the stack’s visible page, and follows a later change', async () => {
+            const { sidebar, stack, host } = mount([
+                { name: 'inbox', title: 'Inbox' },
+                { name: 'drafts', title: 'Drafts' },
+            ]);
+            expect(rows(sidebar)[0].classList.contains('selected')).toBe(true);
+            stack.visibleChildName = 'drafts';
+            expect(rows(sidebar)[1].classList.contains('selected')).toBe(true);
+            expect(rows(sidebar)[0].classList.contains('selected')).toBe(false);
+            host.remove();
+        });
+
+        await it('activates the page at the same index, and only then emits activated', async () => {
+            const { sidebar, stack, host } = mount([
+                { name: 'inbox', title: 'Inbox' },
+                { name: 'drafts', title: 'Drafts' },
+                { name: 'sent', title: 'Sent' },
+            ]);
+            const seen: { index: number; visible: string }[] = [];
+            sidebar.addEventListener('activated', (event) => {
+                seen.push({
+                    index: (event as CustomEvent).detail.index,
+                    // The stack has ALREADY moved — that is the C order (:104-112).
+                    visible: stack.visibleChildName,
+                });
+            });
+            rows(sidebar)[0].click();
+            const afterFirst = seen.length;
+            rows(sidebar)[2].click();
+            // ONE event per click, and `seen` is BOTH of them: the first row was the
+            // visible page already, and C activates a selected row like any other.
+            expect({ afterFirst, name: stack.visibleChildName, seen }).toStrictEqual({
+                afterFirst: 1,
+                name: 'sent',
+                seen: [
+                    { index: 0, visible: 'inbox' },
+                    { index: 2, visible: 'sent' },
+                ],
+            });
+            host.remove();
+        });
+    });
+
+    await describe('<adw-view-switcher-sidebar> indicator (update_badge)', async () => {
+        await it('draws no bin at all for a page with neither dot nor count', async () => {
+            const { sidebar, host } = mount([{ name: 'inbox', title: 'Inbox' }]);
+            expect(indicator(sidebar, 0).hidden).toBe(true);
+            host.remove();
+        });
+
+        await it('draws a bare dot for needs-attention with no count', async () => {
+            const { sidebar, host } = mount([{ name: 'inbox', title: 'Inbox', attention: true }]);
+            const bin = indicator(sidebar, 0);
+            expect(bin.hidden).toBe(false);
+            expect(bin.classList.contains('dot')).toBe(true);
+            expect(bin.classList.contains('needs-attention')).toBe(true);
+            expect(bin.querySelector('.numeric')).toBeNull();
+            host.remove();
+        });
+
+        await it('replaces the dot with the count, and caps it above 999', async () => {
+            const { sidebar, host } = mount([
+                { name: 'a', title: 'A', badge: '3' },
+                { name: 'b', title: 'B', badge: '999' },
+                { name: 'c', title: 'C', badge: '1000', attention: true },
+            ]);
+            expect(indicator(sidebar, 0).classList.contains('dot')).toBe(false);
+            expect(indicator(sidebar, 0).querySelector('.numeric')?.textContent).toBe('3');
+            // `> 999`, so 999 itself prints.
+            expect(indicator(sidebar, 1).querySelector('.numeric')?.textContent).toBe('999');
+            expect(indicator(sidebar, 2).querySelector('.numeric')?.textContent).toBe('999+');
+            expect(indicator(sidebar, 2).classList.contains('needs-attention')).toBe(true);
+            host.remove();
+        });
+    });
+
+    await describe('<adw-view-switcher-sidebar> mode, filter and placeholder', async () => {
+        await it('switches the sidebar between sidebar and page mode', async () => {
+            const { sidebar, host } = mount([{ name: 'inbox', title: 'Inbox' }]);
+            const inner = sidebar.querySelector('adw-sidebar') as HTMLElement;
+            expect(inner.classList.contains('page')).toBe(false);
+            sidebar.setAttribute('mode', 'page');
+            expect(sidebar.mode).toBe('page');
+            expect(inner.classList.contains('page')).toBe(true);
+            host.remove();
+        });
+
+        await it('shows the placeholder when the filter takes every row, and hides it again', async () => {
+            const { sidebar, host } = mount([
+                { name: 'inbox', title: 'Inbox' },
+                { name: 'drafts', title: 'Drafts' },
+            ]);
+            const placeholder = sidebar.querySelector('.view-switcher-sidebar-placeholder') as HTMLElement;
+            expect(placeholder.hidden).toBe(true);
+
+            const status = document.createElement('adw-status-page');
+            status.setAttribute('icon', 'system-search');
+            status.setAttribute('title', 'Nothing Found');
+            sidebar.placeholder = status;
+            // EVERY row, which is the condition `update_placeholder` binds the placeholder
+            // to — a filter that leaves one row standing leaves the placeholder hidden, so
+            // `() => false` is the only predicate this test's name describes.
+            sidebar.filter = () => false;
+            expect(placeholder.hidden).toBe(false);
+            expect(placeholder.contains(status)).toBe(true);
+
+            sidebar.filter = null;
+            expect(placeholder.hidden).toBe(true);
+            host.remove();
+        });
+
+        await it('accepts a stack by id, the way the property takes the element', async () => {
+            const host = document.createElement('div');
+            host.innerHTML =
+                `<adw-view-stack id="pages"><adw-view-stack-page name="a" title="A"></adw-view-stack-page></adw-view-stack>` +
+                `<adw-view-switcher-sidebar stack="pages"></adw-view-switcher-sidebar>`;
+            document.body.appendChild(host);
+            const sidebar = host.querySelector('adw-view-switcher-sidebar') as AdwViewSwitcherSidebar;
+            expect(sidebar.stack).toBe(host.querySelector('adw-view-stack'));
+            expect(rows(sidebar)).toHaveLength(1);
+            host.remove();
+        });
+
+        await it('keeps prefix and suffix out of the item list', async () => {
+            const host = document.createElement('div');
+            host.innerHTML = `<adw-view-switcher-sidebar><span slot="prefix">Top</span><span slot="suffix">Bottom</span></adw-view-switcher-sidebar>`;
+            document.body.appendChild(host);
+            const sidebar = host.querySelector('adw-view-switcher-sidebar') as AdwViewSwitcherSidebar;
+            expect(sidebar.prefixWidget?.textContent).toBe('Top');
+            expect(sidebar.suffixWidget?.textContent).toBe('Bottom');
+            expect(rows(sidebar)).toHaveLength(0);
+            host.remove();
+        });
+    });
+};

package/src/adw-window.spec.ts

@@ -0,0 +1,129 @@
+// DOM-level behaviour tests for <adw-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 (content area, breakpoints, dialog tracking).
+import { describe, it, expect } from '@gjsify/unit';
+
+import type { AdwWindow } from './elements/adw-window.js';
+
+function makeWindow(html = '<p>Content</p>'): AdwWindow {
+    const el = document.createElement('adw-window') as AdwWindow;
+    el.innerHTML = html;
+    document.body.appendChild(el);
+    return el;
+}
+
+/** Wait for a ResizeObserver delivery (it runs after layout, before paint). */
+function settle(): Promise<void> {
+    return new Promise((resolve) => {
+        requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+    });
+}
+
+export const AdwWindowTest = async () => {
+    await describe('adw-window content', async () => {
+        await it('places children in the content area', async () => {
+            const win = makeWindow('<p id="hello">Hello</p>');
+            const content = win.querySelector('.adw-window-content');
+            expect(content?.querySelector('#hello')?.textContent).toBe('Hello');
+            win.remove();
+        });
+
+        await it('content property returns the first child of the content area', async () => {
+            const win = makeWindow('<p id="first">First</p><p id="second">Second</p>');
+            expect(win.content?.id).toBe('first');
+            win.remove();
+        });
+
+        await it('content setter moves an element into the content area', async () => {
+            const win = makeWindow();
+            const p = document.createElement('p');
+            p.id = 'moved';
+            win.content = p;
+            expect(win.querySelector('.adw-window-content')?.querySelector('#moved')).toBe(p);
+            win.remove();
+        });
+
+        await it('applies the default 360×200 size', async () => {
+            const win = makeWindow();
+            expect(win.style.width).toBe('360px');
+            expect(win.style.height).toBe('200px');
+            win.remove();
+        });
+
+        await it('width/height attributes override the default size', async () => {
+            const win = document.createElement('adw-window') as AdwWindow;
+            win.setAttribute('width', '500');
+            win.setAttribute('height', '400');
+            document.body.appendChild(win);
+            expect(win.style.width).toBe('500px');
+            expect(win.style.height).toBe('400px');
+            win.remove();
+        });
+    });
+
+    await describe('adw-window breakpoints', async () => {
+        await it('addBreakpoint() returns a breakpoint and tracks it', async () => {
+            const win = makeWindow();
+            const bp = win.addBreakpoint('max-width: 500px');
+            expect(win.breakpoints.length).toBe(1);
+            expect(win.breakpoints[0]).toBe(bp);
+            win.remove();
+        });
+
+        await it('currentBreakpoint is null when no breakpoint is applied', async () => {
+            const win = makeWindow();
+            win.addBreakpoint('max-width: 100px');
+            // The window is wider than 100px in the test viewport.
+            expect(win.currentBreakpoint).toBeNull();
+            win.remove();
+        });
+
+        // A window is what a client-side route change re-parents, and `disconnectedCallback`
+        // releases the observer — so the bind has to come back on the next connect.
+        await it('re-binds the breakpoints after the window is re-attached', async () => {
+            const win = makeWindow();
+            win.addBreakpoint('max-width: 300px');
+            await settle();
+            expect(win.dataset.breakpoint).toBeUndefined();
+
+            win.remove();
+            document.body.appendChild(win);
+            win.setAttribute('width', '200');
+            await settle();
+
+            expect(win.dataset.breakpoint).toBe('max-width: 300px');
+            expect(win.currentBreakpoint).toBe(win.breakpoints[0]!);
+            win.remove();
+        });
+    });
+
+    await describe('adw-window dialog tracking', async () => {
+        await it('tracks open dialogs presented inside the window', async () => {
+            const win = makeWindow();
+            const dialog = document.createElement('adw-dialog') as HTMLElement & { present(): void };
+            dialog.innerHTML = '<p>Dialog content</p>';
+            win.appendChild(dialog);
+            dialog.present();
+            expect(win.dialogs.length).toBe(1);
+            expect(win.visibleDialog).toBe(dialog);
+            dialog.remove();
+            win.remove();
+        });
+
+        await it('stops tracking a dialog when it closes', async () => {
+            const win = makeWindow();
+            const dialog = document.createElement('adw-dialog') as HTMLElement & { present(): void; close(): void };
+            dialog.innerHTML = '<p>Dialog content</p>';
+            win.appendChild(dialog);
+            dialog.present();
+            expect(win.dialogs.length).toBe(1);
+            dialog.close();
+            expect(win.dialogs.length).toBe(0);
+            expect(win.visibleDialog).toBeNull();
+            dialog.remove();
+            win.remove();
+        });
+    });
+};

package/src/breakpoints.ts

@@ -16,31 +16,48 @@
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 
 import { AdwBreakpoint } from '@gjsify/adwaita-core';
+import type { BreakpointSize } from '@gjsify/adwaita-core';
 
 /**
- * Drive `breakpoints` from `element`'s own box, and return a dispose function.
+ * The SIZE SOURCE both adaptive shapes in this package share: a `ResizeObserver` on
+ * `element`, handing every delivery's BORDER box to `onSize`.
  *
- * `ResizeObserver` delivers an initial observation on `observe()`, so the breakpoints
- * settle on the correct state before first paint — no flash of the wrong layout, no
+ * Split out of {@link addBreakpoints} because a second consumer needs the box without
+ * the `AdwBreakpoint` state machine: `<adw-breakpoint-bin>` drives `BreakpointBinState`
+ * (core), which evaluates a LIST of breakpoints and answers with the writes to perform,
+ * so it cannot be handed one `AdwBreakpoint` per condition. Two readers of
+ * `borderBoxSize` would be two shapes of the fallback, and the fallback is the half that
+ * only matters on the engines that do not report `borderBoxSize` at all.
+ *
+ * `ResizeObserver` delivers an initial observation on `observe()`, so the caller
+ * settles on the correct state before first paint — no flash of the wrong layout, no
  * separate seeding pass. The size read is the BORDER box in CSS pixels, the browser's
  * counterpart to the `sp`/DIP units an Adwaita condition is written in.
  */
-export function addBreakpoints(element: Element, breakpoints: readonly AdwBreakpoint[]): () => void {
+export function observeAdaptiveSize(element: Element, onSize: (size: BreakpointSize) => void): () => void {
     const observer = new ResizeObserver((entries) => {
         const entry = entries[entries.length - 1];
         if (!entry) return;
         // borderBoxSize is the spec'd path; contentRect is the fallback for the shape older
         // engines report.
         const box = entry.borderBoxSize?.[0];
-        const size = box
-            ? { width: box.inlineSize, height: box.blockSize }
-            : { width: entry.contentRect.width, height: entry.contentRect.height };
-        for (const breakpoint of breakpoints) breakpoint.evaluate(size);
+        onSize(
+            box
+                ? { width: box.inlineSize, height: box.blockSize }
+                : { width: entry.contentRect.width, height: entry.contentRect.height },
+        );
     });
     observer.observe(element);
     return () => observer.disconnect();
 }
 
+/** Drive `breakpoints` from `element`'s own box, and return a dispose function. */
+export function addBreakpoints(element: Element, breakpoints: readonly AdwBreakpoint[]): () => void {
+    return observeAdaptiveSize(element, (size) => {
+        for (const breakpoint of breakpoints) breakpoint.evaluate(size);
+    });
+}
+
 /**
  * Wire a `breakpoint="<condition>"` attribute to a boolean setter, the browser equivalent
  * of an `Adw.Breakpoint` with one `add_setter()` call. Returns a dispose function; call it

package/src/capabilities.d.mts

@@ -0,0 +1,3 @@
+import type { ConstructCapabilities } from '@gjsify/adwaita-core/conformance';
+
+export const capabilities: ConstructCapabilities;

package/src/capabilities.mjs

@@ -0,0 +1,18 @@
+// Which template constructs `adwaita-web`'s tree builder builds (ADR 0093 § 2). Pure data, so a
+// build plugin can read it without importing the renderer — and plain `.mjs`, because the
+// plugin loads it under Node from a published package, where Node refuses to strip types.
+
+/** @type {import('./capabilities.d.mts').capabilities} */
+export const capabilities = {
+    layout: {
+        refused:
+            'an <adw-…> element is placed by DOM order and slot=, so a layout-manager placement has no door in the markup this package reads (ADR 0092)',
+    },
+    strings: 'implemented',
+    responses: 'implemented',
+    page: 'implemented',
+    extern: 'implemented',
+    signal: 'implemented',
+    bind: 'implemented',
+    breakpoint: 'implemented',
+};

package/src/connect-lifecycle.spec.ts

@@ -38,6 +38,10 @@ import { exportedElementClasses } from './exported-elements.js';
  */
 const NON_RENDERING = new Set([
     'input',
+    // Not a void element, but the same shape for this driver: a `<textarea>` renders its own
+    // `value` and lays out no children, so a probe appended into one measures 0 forever.
+    // `<gtk-text-view>.textarea` is the handle, the way `<gtk-entry>.input` is.
+    'textarea',
     'img',
     'br',
     'hr',
@@ -72,6 +76,14 @@ function reveal(el: HTMLElement): void {
     if (typeof dialog.present === 'function') dialog.present();
     // `<adw-expander-row>.contentSection` is merely COLLAPSED — it is the disclosure.
     if (el.localName === 'adw-expander-row') el.setAttribute('expanded', '');
+    // `<adw-application-window>.menubar` is merely EMPTY: GTK draws no menubar for an
+    // application that installed none, so the strip stays hidden until BOTH the flag and
+    // a model are there. Keyed by tag for the same reason the expander is — the pair is
+    // its own idea, and no other widget in this package has it.
+    if (el.localName === 'adw-application-window') {
+        el.setAttribute('show-menubar', '');
+        el.setAttribute('menu-model', '[{"label":"File","submenu":[{"label":"Quit"}]}]');
+    }
 }
 
 /**