@gjsify/adwaita-web 0.30.0 → 0.32.0

package/src/bottom-sheet.spec.ts

@@ -0,0 +1,325 @@
+// DOM-level conformance tests for <adw-bottom-sheet>, driven by the SAME vectors
+// the core suite and the NativeScript renderer assert against
+// (`@gjsify/adwaita-core/conformance`).
+//
+// `Adw.BottomSheet` has four dismissal paths and they are four different gates.
+// This element used to route all of them through one `_attemptClose()`, which
+// meant: the drag handle closed the sheet (in libadwaita it is `can_target =
+// FALSE` and closes nothing), Escape on a closed-but-focused sheet did nothing
+// (libadwaita still signals `close-attempt`), and the `sheet.close` action on an
+// already-closed sheet did nothing (libadwaita forwards it to the parent).
+// Nothing failed, because nothing compared the element to the C source.
+//
+// Two element-local bugs are pinned here too, both from the same root cause —
+// the open STATE used to be read off the attribute rather than held:
+// `open="false"` rendered OPEN, and re-spelling the attribute fired a
+// `notify::open` carrying an unchanged payload.
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { AdwBottomSheet } from './elements/adw-bottom-sheet.js';
+import {
+    BOTTOM_SHEET_CLOSE_VECTORS,
+    BOTTOM_SHEET_PRESENTATION_VECTORS,
+    runBottomSheetSteps,
+} from '@gjsify/adwaita-core/conformance';
+import type { BottomSheetCloseOutcome } from '@gjsify/adwaita-core';
+
+/** A mounted sheet with one child in each slot, ready to be driven. */
+function mountSheet(markup = ''): AdwBottomSheet {
+    const sheet = document.createElement('adw-bottom-sheet') as AdwBottomSheet;
+    sheet.innerHTML =
+        markup ||
+        '<adw-bottom-sheet-content><button id="under">Under</button></adw-bottom-sheet-content>' +
+            '<adw-bottom-sheet-sheet><button id="inside">Inside</button></adw-bottom-sheet-sheet>';
+    document.body.appendChild(sheet);
+    return sheet;
+}
+
+function dimming(sheet: AdwBottomSheet): HTMLElement {
+    return sheet.querySelector('.adw-bottom-sheet-dimming') as HTMLElement;
+}
+
+function dragHandle(sheet: AdwBottomSheet): HTMLElement {
+    return sheet.querySelector('.adw-bottom-sheet-drag-handle') as HTMLElement;
+}
+
+function insideSheet(sheet: AdwBottomSheet): HTMLElement {
+    return sheet.querySelector('.adw-bottom-sheet-sheet-body > button') as HTMLElement;
+}
+
+/** Count the dismissal signals a sheet raises while `run` executes. */
+function recordSignals(sheet: AdwBottomSheet, run: () => void): { attempts: number; delegated: number } {
+    let attempts = 0;
+    let delegated = 0;
+    const onAttempt = () => attempts++;
+    const onDelegate = () => delegated++;
+    sheet.addEventListener('close-attempt', onAttempt);
+    sheet.addEventListener('sheet.close', onDelegate);
+    run();
+    sheet.removeEventListener('close-attempt', onAttempt);
+    sheet.removeEventListener('sheet.close', onDelegate);
+    return { attempts, delegated };
+}
+
+export const AdwBottomSheetTest = async () => {
+    await describe('adw-bottom-sheet dismissal gate (libadwaita conformance vectors)', async () => {
+        for (const { source, open, canClose, outcome, rule } of BOTTOM_SHEET_CLOSE_VECTORS) {
+            await it(`${source} · open=${open} · canClose=${canClose} → ${outcome} — ${rule}`, () => {
+                const sheet = mountSheet();
+                sheet.canClose = canClose;
+                sheet.open = open;
+
+                let returned: BottomSheetCloseOutcome | null = null;
+                const { attempts, delegated } = recordSignals(sheet, () => {
+                    returned = sheet.requestClose(source);
+                });
+
+                expect(returned).toBe(outcome);
+                // The verdict must be VISIBLE, not just returned: a renderer that
+                // returns the right word and closes anyway is still wrong.
+                expect(sheet.open).toBe(outcome === 'close' ? false : open);
+                expect(attempts).toBe(outcome === 'close-attempt' ? 1 : 0);
+                expect(delegated).toBe(outcome === 'delegate' ? 1 : 0);
+                sheet.remove();
+            });
+        }
+    });
+
+    await describe('adw-bottom-sheet presentation (libadwaita conformance vectors)', async () => {
+        for (const vector of BOTTOM_SHEET_PRESENTATION_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 = runBottomSheetSteps(
+                    {
+                        setOpen: (open) => {
+                            sheet.open = open;
+                        },
+                        setCanClose: (canClose) => {
+                            sheet.canClose = canClose;
+                        },
+                        requestClose: (source) => sheet.requestClose(source),
+                    },
+                    vector.steps,
+                );
+
+                expect(outcomes).toStrictEqual([...vector.outcomes]);
+                expect(notifications).toStrictEqual([...vector.notifications]);
+                expect(sheet.open).toBe(vector.open);
+                // The `open` attribute is the CSS hook, so it must track the state.
+                expect(sheet.hasAttribute('open')).toBe(vector.open);
+                expect(sheet.classList.contains('open')).toBe(vector.open);
+                sheet.remove();
+            });
+        }
+    });
+
+    await describe('adw-bottom-sheet open attribute semantics', async () => {
+        await it('open="false" renders CLOSED', () => {
+            // The getter used to be `hasAttribute('open')` while every other
+            // boolean used `!== 'false'`, so one element carried two conventions.
+            // adw-bottom-sheet.c:1670 — `open = !!open` on a strict gboolean.
+            const sheet = document.createElement('adw-bottom-sheet') as AdwBottomSheet;
+            sheet.setAttribute('open', 'false');
+            document.body.appendChild(sheet);
+            expect(sheet.open).toBe(false);
+            expect(sheet.classList.contains('open')).toBe(false);
+            sheet.remove();
+        });
+
+        await it('open="" and open="open" both render OPEN', () => {
+            const sheet = mountSheet();
+            sheet.setAttribute('open', '');
+            expect(sheet.open).toBe(true);
+            sheet.setAttribute('open', 'open');
+            expect(sheet.open).toBe(true);
+            sheet.remove();
+        });
+
+        await it('re-spelling the attribute fires no spurious notify::open', () => {
+            // The old callback guarded only `oldValue === newValue` and then
+            // dispatched unconditionally, so `open=""` → `open="open"` fired a
+            // second notification carrying an UNCHANGED payload.
+            // adw-bottom-sheet.c:1672-1682 returns before notifying.
+            const sheet = mountSheet();
+            const payloads: boolean[] = [];
+            sheet.addEventListener('notify::open', (event) => {
+                payloads.push((event as CustomEvent).detail.open);
+            });
+            sheet.setAttribute('open', '');
+            sheet.setAttribute('open', 'open');
+            sheet.setAttribute('open', 'false');
+            expect(payloads).toStrictEqual([true, false]);
+            sheet.remove();
+        });
+
+        await it('an attribute set before connect survives the upgrade', () => {
+            const sheet = document.createElement('adw-bottom-sheet') as AdwBottomSheet;
+            sheet.setAttribute('can-close', 'false');
+            sheet.setAttribute('open', '');
+            document.body.appendChild(sheet);
+            expect(sheet.open).toBe(true);
+            expect(sheet.canClose).toBe(false);
+            sheet.remove();
+        });
+    });
+
+    await describe('adw-bottom-sheet affordances', async () => {
+        await it('the drag handle is decorative — not focusable, not a button, closes nothing', () => {
+            // gtk_widget_set_can_focus/can_target (self->drag_handle, FALSE)
+            // — adw-bottom-sheet.c:1197-1198. This element used to give it
+            // role="button", tabindex=0 and a click-to-close handler.
+            const sheet = mountSheet();
+            sheet.open = true;
+            const handle = dragHandle(sheet);
+            expect(handle.getAttribute('role')).toBe(null);
+            expect(handle.hasAttribute('tabindex')).toBe(false);
+            expect(handle.getAttribute('aria-hidden')).toBe('true');
+
+            const { attempts } = recordSignals(sheet, () => {
+                handle.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+                handle.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
+                handle.dispatchEvent(new KeyboardEvent('keydown', { key: ' ', bubbles: true }));
+            });
+            expect(sheet.open).toBe(true);
+            expect(attempts).toBe(0);
+            sheet.remove();
+        });
+
+        await it('a dimming click closes an unlocked sheet and signals a locked one', () => {
+            const sheet = mountSheet();
+            sheet.open = true;
+            dimming(sheet).dispatchEvent(new MouseEvent('click', { bubbles: true }));
+            expect(sheet.open).toBe(false);
+
+            sheet.open = true;
+            sheet.canClose = false;
+            const { attempts } = recordSignals(sheet, () => {
+                dimming(sheet).dispatchEvent(new MouseEvent('click', { bubbles: true }));
+            });
+            expect(sheet.open).toBe(true);
+            expect(attempts).toBe(1);
+            sheet.remove();
+        });
+
+        await it('a dimming click on a CLOSED sheet does nothing and signals nothing', () => {
+            // The scrim is `can_target = open` (adw-bottom-sheet.c:1692), so it
+            // is not reachable at all — unlike Escape, it does not signal.
+            const sheet = mountSheet();
+            sheet.canClose = false;
+            const { attempts } = recordSignals(sheet, () => {
+                dimming(sheet).dispatchEvent(new MouseEvent('click', { bubbles: true }));
+            });
+            expect(sheet.open).toBe(false);
+            expect(attempts).toBe(0);
+            sheet.remove();
+        });
+
+        await it('Escape closes an open sheet', () => {
+            const sheet = mountSheet();
+            sheet.open = true;
+            insideSheet(sheet).dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+            expect(sheet.open).toBe(false);
+            sheet.remove();
+        });
+
+        await it('Escape on a CLOSED but focused sheet still raises close-attempt', () => {
+            // maybe_close_cb's emit is the fallthrough for every case that is not
+            // (can_close && open) — adw-bottom-sheet.c:393-399. This element
+            // guarded it away twice (once in the key handler, once in
+            // `_attemptClose`), so the corner was unreachable.
+            const sheet = mountSheet();
+            const { attempts } = recordSignals(sheet, () => {
+                insideSheet(sheet).dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+            });
+            expect(sheet.open).toBe(false);
+            expect(attempts).toBe(1);
+            sheet.remove();
+        });
+
+        await it('Escape from the CONTENT of a closed sheet stays silent', () => {
+            // The shortcut lives on the sheet in GTK, so a key pressed outside it
+            // while the sheet is closed reaches nothing.
+            const sheet = mountSheet();
+            const under = sheet.querySelector('#under') as HTMLElement;
+            const { attempts } = recordSignals(sheet, () => {
+                under.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+            });
+            expect(attempts).toBe(0);
+            sheet.remove();
+        });
+
+        await it('sheet.close on an already-closed sheet delegates upward', () => {
+            // sheet_close_cb activates the PARENT's `sheet.close` action instead
+            // of doing nothing — adw-bottom-sheet.c:382-385. A bubbling event is
+            // the DOM equivalent, so an enclosing sheet/dialog can act on it.
+            const sheet = mountSheet();
+            const host = sheet.parentElement as HTMLElement;
+            let seenOnAncestor = 0;
+            const onAncestor = () => seenOnAncestor++;
+            host.addEventListener('sheet.close', onAncestor);
+            expect(sheet.requestClose('close-button')).toBe('delegate');
+            host.removeEventListener('sheet.close', onAncestor);
+            expect(seenOnAncestor).toBe(1);
+            sheet.remove();
+        });
+    });
+
+    await describe('adw-bottom-sheet slots + flags', async () => {
+        await it('keeps the declared content and sheet children apart', () => {
+            const sheet = mountSheet();
+            expect((sheet.querySelector('.adw-bottom-sheet-content > button') as HTMLElement).id).toBe('under');
+            expect(insideSheet(sheet).id).toBe('inside');
+            sheet.remove();
+        });
+
+        await it('consumes the slot wrappers instead of leaving them in the content', () => {
+            // `<child type="sheet">` is GtkBuilder markup — nothing of it survives
+            // into the widget tree (adw-bottom-sheet.c:1278-1293). The emptied
+            // <adw-bottom-sheet-sheet> / <adw-bottom-sheet-content> wrappers used
+            // to fall through to `unslotted` and land in the content layer.
+            const sheet = mountSheet();
+            const content = sheet.querySelector('.adw-bottom-sheet-content') as HTMLElement;
+            expect(Array.from(content.children).map((el) => el.tagName.toLowerCase())).toStrictEqual(['button']);
+            sheet.remove();
+        });
+
+        await it('mixes wrapper and slot="…" children in document order', () => {
+            const sheet = mountSheet(
+                '<span slot="sheet" id="first">1</span>' +
+                    '<adw-bottom-sheet-sheet><span id="second">2</span></adw-bottom-sheet-sheet>',
+            );
+            const body = sheet.querySelector('.adw-bottom-sheet-sheet-body') as HTMLElement;
+            expect(Array.from(body.children).map((el) => el.id)).toStrictEqual(['first', 'second']);
+            sheet.remove();
+        });
+
+        await it('modal and show-drag-handle default on and honour ="false"', () => {
+            const sheet = mountSheet();
+            expect(sheet.modal).toBe(true);
+            expect(sheet.showDragHandle).toBe(true);
+            expect(sheet.classList.contains('modal')).toBe(true);
+            expect(dragHandle(sheet).hidden).toBe(false);
+
+            sheet.showDragHandle = false;
+            expect(dragHandle(sheet).hidden).toBe(true);
+            sheet.modal = false;
+            expect(sheet.classList.contains('modal')).toBe(false);
+            sheet.remove();
+        });
+
+        await it('the dimming layer becomes interactive only while open AND modal', () => {
+            const sheet = mountSheet();
+            expect(dimming(sheet).classList.contains('visible')).toBe(false);
+            sheet.open = true;
+            expect(dimming(sheet).classList.contains('visible')).toBe(true);
+            sheet.modal = false;
+            expect(dimming(sheet).classList.contains('visible')).toBe(false);
+            sheet.remove();
+        });
+    });
+};

package/src/breakpoints.spec.ts

@@ -0,0 +1,147 @@
+// Breakpoint binding — the browser size source for `@gjsify/adwaita-core`.
+//
+// The behaviour under test is the one adwaita-web did not have: markup that
+// adapts by itself, the way the same markup already adapts on GTK (Adw.Breakpoint)
+// and on NativeScript (addBreakpoints). Sizes are driven by actually resizing a
+// host element and awaiting a real ResizeObserver delivery, not by faking one.
+import { describe, expect, it } from '@gjsify/unit';
+
+import { AdwBreakpoint } from '@gjsify/adwaita-core';
+
+import { addBreakpoints } from './breakpoints.js';
+import type { AdwNavigationSplitView } from './elements/adw-navigation-split-view.js';
+import type { AdwOverlaySplitView } from './elements/adw-overlay-split-view.js';
+
+/** A fixed-width host appended to the document, plus a way to resize it. */
+function mountSized(width: number): { host: HTMLElement; resize: (w: number) => Promise<void> } {
+    const host = document.createElement('div');
+    host.style.width = `${width}px`;
+    document.body.appendChild(host);
+    return {
+        host,
+        resize: async (w: number) => {
+            host.style.width = `${w}px`;
+            await settle();
+        },
+    };
+}
+
+/** Wait for a ResizeObserver delivery (it runs after layout, before paint). */
+function settle(): Promise<void> {
+    return new Promise((resolve) => {
+        requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+    });
+}
+
+export const AdwBreakpointsTest = async () => {
+    await describe('addBreakpoints (ResizeObserver size source)', async () => {
+        await it('seeds from the initial observation, without a wrong-layout flash', async () => {
+            const { host } = mountSized(400);
+            const seen: boolean[] = [];
+            const dispose = addBreakpoints(host, [
+                new AdwBreakpoint('max-width: 720px', {
+                    onApply: () => seen.push(true),
+                    onUnapply: () => seen.push(false),
+                }),
+            ]);
+            await settle();
+            // Narrow at construction → applied once, never "unapplied first".
+            expect(seen).toStrictEqual([true]);
+            dispose();
+            host.remove();
+        });
+
+        await it('applies and unapplies on the transitions only', async () => {
+            const { host, resize } = mountSized(400);
+            const seen: boolean[] = [];
+            const dispose = addBreakpoints(host, [
+                new AdwBreakpoint('max-width: 720px', {
+                    onApply: () => seen.push(true),
+                    onUnapply: () => seen.push(false),
+                }),
+            ]);
+            await settle();
+            await resize(900); // crosses out
+            await resize(1000); // still wide — no second unapply
+            await resize(500); // crosses back in
+            expect(seen).toStrictEqual([true, false, true]);
+            dispose();
+            host.remove();
+        });
+
+        await it('stops evaluating once disposed', async () => {
+            const { host, resize } = mountSized(900);
+            const seen: boolean[] = [];
+            const dispose = addBreakpoints(host, [
+                new AdwBreakpoint('max-width: 720px', { onApply: () => seen.push(true) }),
+            ]);
+            await settle();
+            dispose();
+            await resize(300);
+            expect(seen).toStrictEqual([]);
+            host.remove();
+        });
+    });
+
+    await describe('split views collapse themselves from a breakpoint attribute', async () => {
+        await it('collapses <adw-navigation-split-view> below the condition', async () => {
+            const { host, resize } = mountSized(1000);
+            host.innerHTML =
+                '<adw-navigation-split-view breakpoint="max-width: 720px">' +
+                '<div slot="sidebar">s</div><div slot="content">c</div>' +
+                '</adw-navigation-split-view>';
+            const view = host.querySelector('adw-navigation-split-view') as AdwNavigationSplitView;
+            await settle();
+            expect(view.collapsed).toBe(false);
+
+            await resize(500);
+            expect(view.collapsed).toBe(true);
+            expect(view.classList.contains('collapsed')).toBe(true);
+
+            await resize(1000);
+            expect(view.collapsed).toBe(false);
+            host.remove();
+        });
+
+        await it('collapses <adw-overlay-split-view> below the condition', async () => {
+            const { host, resize } = mountSized(1000);
+            host.innerHTML =
+                '<adw-overlay-split-view breakpoint="max-width: 720px">' +
+                '<div slot="sidebar">s</div><div slot="content">c</div>' +
+                '</adw-overlay-split-view>';
+            const view = host.querySelector('adw-overlay-split-view') as AdwOverlaySplitView;
+            await settle();
+            expect(view.collapsed).toBe(false);
+
+            await resize(500);
+            expect(view.collapsed).toBe(true);
+            host.remove();
+        });
+
+        await it('leaves collapsed alone when no breakpoint is set', async () => {
+            const { host, resize } = mountSized(1000);
+            host.innerHTML =
+                '<adw-navigation-split-view collapsed>' +
+                '<div slot="sidebar">s</div><div slot="content">c</div>' +
+                '</adw-navigation-split-view>';
+            const view = host.querySelector('adw-navigation-split-view') as AdwNavigationSplitView;
+            await resize(1400);
+            // Without a condition the application owns the attribute — a wide
+            // viewport must not silently expand a deliberately collapsed view.
+            expect(view.collapsed).toBe(true);
+            host.remove();
+        });
+
+        await it('ignores an unparsable condition rather than flipping state', async () => {
+            const { host, resize } = mountSized(1000);
+            host.innerHTML =
+                '<adw-navigation-split-view breakpoint="not a condition">' +
+                '<div slot="sidebar">s</div><div slot="content">c</div>' +
+                '</adw-navigation-split-view>';
+            const view = host.querySelector('adw-navigation-split-view') as AdwNavigationSplitView;
+            await resize(300);
+            expect(view.collapsed).toBe(false);
+            host.remove();
+        });
+    });
+};

package/src/breakpoints.ts

@@ -0,0 +1,67 @@
+// Breakpoint binding for the browser renderer.
+//
+// The condition grammar, the evaluator and the transition-only apply/unapply
+// state machine are HEADLESS and live in `@gjsify/adwaita-core` (ADR 0004).
+// What each renderer must supply is the SIZE SOURCE: GTK has
+// `Adw.Window::notify::default-width`, NativeScript has a view's `layoutChanged`
+// (`addBreakpoints` in `@gjsify/adwaita-nativescript`), and the browser has
+// `ResizeObserver` — which this module supplies under the same name, so the two
+// ports read alike.
+//
+// Until this existed, `adwaita-web` was the only one of the three renderers with
+// no size source at all: `<adw-navigation-split-view collapsed>` was a manual
+// attribute the application had to flip itself, so the same markup that adapts
+// on GTK and on NativeScript stayed frozen in one layout in the browser.
+//
+// Reference: refs/libadwaita/src/adw-breakpoint.c
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+
+import { AdwBreakpoint } from '@gjsify/adwaita-core';
+
+/**
+ * Drive `breakpoints` from `element`'s own box, and return a dispose function.
+ *
+ * `ResizeObserver` delivers an initial observation on `observe()`, so the
+ * breakpoints settle on the correct state before first paint — no flash of the
+ * wrong layout, and 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 {
+    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);
+    });
+    observer.observe(element);
+    return () => observer.disconnect();
+}
+
+/**
+ * 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 before re-binding and on disconnect.
+ * A missing or unparsable condition binds nothing and returns a no-op, leaving
+ * whatever the attribute already says untouched — an element must not silently
+ * flip state because its condition had a typo.
+ */
+export function bindBreakpointSetter(
+    element: Element,
+    condition: string | null,
+    setValue: (active: boolean) => void,
+): () => void {
+    if (!condition) return () => {};
+    const breakpoint = new AdwBreakpoint(condition, {
+        onApply: () => setValue(true),
+        onUnapply: () => setValue(false),
+    });
+    return addBreakpoints(element, [breakpoint]);
+}