@gjsify/adwaita-web 0.30.0 → 0.32.0

package/src/chrome.spec.ts

@@ -0,0 +1,301 @@
+// DOM-level conformance tests for the chrome elements — <adw-clamp>,
+// <adw-spinner> and <adw-toolbar-view> — driven by the SAME vectors the
+// NativeScript renderer asserts against (`@gjsify/adwaita-core/conformance`).
+//
+// Each of the three used to answer a question libadwaita had already answered,
+// and answered it differently from the NativeScript port: the clamp was a plain
+// `max-width` with no tightening and a `maximum-size="0"` that collapsed the
+// child to nothing, the spinner defaulted to 24px and stroked a 2px ring where
+// Adwaita strokes 3px, and the toolbar view carried none of the four style
+// classes at all. Nothing failed, because nothing compared them.
+//
+// Sizes are driven by really resizing a host element and awaiting a real
+// ResizeObserver delivery, the same way `breakpoints.spec.ts` does — never by
+// faking one.
+import { describe, expect, it } from '@gjsify/unit';
+
+import { ADW_SPINNER_MIN_SIZE, spinnerGeometry } from '@gjsify/adwaita-core';
+import {
+    CLAMP_ALLOCATE_VECTORS,
+    CLAMP_PROPERTY_VECTORS,
+    SPINNER_GEOMETRY_VECTORS,
+    SPINNER_SIZE_VECTORS,
+    TOOLBAR_VIEW_CLASS_VECTORS,
+} from '@gjsify/adwaita-core/conformance';
+
+/** Wait for a ResizeObserver delivery (it runs after layout, before paint). */
+function settle(): Promise<void> {
+    return new Promise((resolve) => {
+        requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+    });
+}
+
+/** A fixed-width host in 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();
+        },
+    };
+}
+
+/** A clamp with one block child, mounted in a host of `available` px. */
+function mountClamp(available: number): {
+    host: HTMLElement;
+    clamp: HTMLElement;
+    child: HTMLElement;
+    resize: (w: number) => Promise<void>;
+} {
+    const { host, resize } = mountSized(available);
+    const clamp = document.createElement('adw-clamp');
+    const child = document.createElement('div');
+    // A bare block child fills the clamp and is capped by the max-width the
+    // element writes — the same shape every story uses.
+    child.textContent = 'clamped';
+    clamp.appendChild(child);
+    host.appendChild(clamp);
+    return { host, clamp, child, resize };
+}
+
+/** The child width a clamp settles on, rounded to the pixel it renders at. */
+function clampedWidth(child: HTMLElement): number {
+    return Math.round(child.getBoundingClientRect().width);
+}
+
+/** The three classes `adw_clamp_layout_allocate` stamps on the child. */
+function sizeClassOf(child: HTMLElement): string | null {
+    for (const cls of ['small', 'medium', 'large']) {
+        if (child.classList.contains(cls)) return cls;
+    }
+    return null;
+}
+
+/** A toolbar view with bars of the given pixel heights (0 = no bar at all). */
+function mountToolbarView(topBarHeight: number, bottomBarHeight: number): { host: HTMLElement; view: HTMLElement } {
+    const { host } = mountSized(400);
+    host.style.height = '300px';
+    const view = document.createElement('adw-toolbar-view');
+    for (const [slot, height] of [
+        ['top', topBarHeight],
+        ['bottom', bottomBarHeight],
+    ] as const) {
+        if (height <= 0) continue;
+        const bar = document.createElement('div');
+        bar.setAttribute('slot', slot);
+        bar.style.height = `${height}px`;
+        view.appendChild(bar);
+    }
+    host.appendChild(view);
+    return { host, view };
+}
+
+export const AdwChromeTest = async () => {
+    await describe('adw-clamp allocation (AdwClampLayout conformance vectors)', async () => {
+        // The browser resolves the child's own minimum through the normal
+        // `min-width` cascade, so only the rows that pass a zero child minimum
+        // describe what this element can be held to.
+        const vectors = CLAMP_ALLOCATE_VECTORS.filter((v) => v.params.childMin === 0);
+
+        for (const { availableSize, params, childSize, sizeClass, offset, rule } of vectors) {
+            await it(`${availableSize}px available → a ${childSize}px ${sizeClass} child — ${rule}`, async () => {
+                const { host, clamp, child } = mountClamp(availableSize);
+                clamp.setAttribute('maximum-size', String(params.maximumSize));
+                clamp.setAttribute('tightening-threshold', String(params.tighteningThreshold));
+                await settle();
+
+                expect(clampedWidth(child)).toBe(childSize);
+                expect(sizeClassOf(child)).toBe(sizeClass);
+                // `margin-inline: auto` splits the remainder evenly; libadwaita
+                // truncates, so the two can differ by half a pixel.
+                const leading = child.getBoundingClientRect().left - clamp.getBoundingClientRect().left;
+                expect(Math.abs(leading - offset) <= 1).toBe(true);
+
+                host.remove();
+            });
+        }
+
+        await it('follows the viewport instead of pinning the child to the maximum', async () => {
+            // The NativeScript twin's bug in browser form: a narrow clamp must
+            // hand the child ALL of the available width, not the cap.
+            const { host, clamp, child, resize } = mountClamp(1000);
+            await settle();
+            expect(clampedWidth(child)).toBe(600);
+            await resize(360);
+            expect(clampedWidth(child)).toBe(360);
+            expect(Math.round(clamp.getBoundingClientRect().width)).toBe(360);
+            host.remove();
+        });
+
+        await it('honours tightening-threshold, which the element used to ignore', async () => {
+            // The storybook has exposed this control all along and only the GTK
+            // pane responded to it.
+            const { host, clamp, child } = mountClamp(700);
+            clamp.setAttribute('maximum-size', '600');
+            clamp.setAttribute('tightening-threshold', '400');
+            await settle();
+            expect(clampedWidth(child)).toBe(575);
+
+            // Raising the threshold above the maximum removes the easing.
+            clamp.setAttribute('tightening-threshold', '800');
+            await settle();
+            expect(clampedWidth(child)).toBe(600);
+            host.remove();
+        });
+
+        await it('clamps children appended after it was connected', async () => {
+            // The element only saw its children once, at connect time — the same
+            // "evaluated once" shape the toolbar view's empty-bar handling has.
+            const { host } = mountSized(1000);
+            const clamp = document.createElement('adw-clamp');
+            host.appendChild(clamp);
+            await settle();
+
+            const late = document.createElement('div');
+            late.textContent = 'appended later';
+            clamp.appendChild(late);
+            await settle();
+
+            expect(clampedWidth(late)).toBe(600);
+            host.remove();
+        });
+    });
+
+    await describe('adw-clamp maximum-size parsing (g_param_spec_int range)', async () => {
+        for (const { value, fallback, size, rule } of CLAMP_PROPERTY_VECTORS) {
+            // Only the rows whose fallback is the real property default describe
+            // what an attribute on THIS element resolves to.
+            if (fallback !== 600) continue;
+
+            await it(`maximum-size ${JSON.stringify(value ?? null)} caps at ${size}px — ${rule}`, async () => {
+                const { host, clamp, child } = mountClamp(1000);
+                // `null`/`undefined` are the ABSENT attribute, so nothing is set.
+                if (value !== null && value !== undefined) clamp.setAttribute('maximum-size', String(value));
+                await settle();
+
+                // 1000px is past `upper` for every cap in the table, so the child
+                // sits exactly at the resolved property and it is readable off
+                // the rendered width.
+                expect(clampedWidth(child)).toBe(size);
+                host.remove();
+            });
+        }
+
+        await it('recovers the default after an unparsable value, instead of freezing on the old cap', async () => {
+            // `parseFloat('abc')` produced `max-width: NaNpx`, which the CSSOM
+            // rejects — so the element silently kept whatever cap it had.
+            const { host, clamp, child } = mountClamp(1000);
+            clamp.setAttribute('maximum-size', '300');
+            await settle();
+            expect(clampedWidth(child)).toBe(300);
+
+            clamp.setAttribute('maximum-size', 'abc');
+            await settle();
+            expect(clampedWidth(child)).toBe(600);
+            host.remove();
+        });
+    });
+
+    await describe('adw-spinner geometry (AdwSpinnerPaintable conformance vectors)', async () => {
+        for (const { width, height, diameter, lineWidth, rule } of SPINNER_GEOMETRY_VECTORS) {
+            // The element is the ring itself, so only the square, allocatable
+            // boxes describe what a `size` attribute can produce.
+            if (width !== height || width < ADW_SPINNER_MIN_SIZE) continue;
+
+            await it(`size ${width} draws a ${diameter}px ring stroked ${lineWidth}px — ${rule}`, () => {
+                const { host } = mountSized(200);
+                const spinner = document.createElement('adw-spinner');
+                spinner.setAttribute('size', String(width));
+                host.appendChild(spinner);
+
+                expect(spinner.offsetWidth).toBe(diameter);
+                expect(spinner.offsetHeight).toBe(diameter);
+                expect(Number.parseFloat(spinner.style.borderWidth)).toBe(lineWidth);
+                host.remove();
+            });
+        }
+
+        await it('strokes 3px at 24 and 6px at 48, where it used to stroke 2 and 4', () => {
+            const { host } = mountSized(200);
+            const spinner = document.createElement('adw-spinner');
+            host.appendChild(spinner);
+            const strokeAt = (size: number) => {
+                spinner.setAttribute('size', String(size));
+                return Number.parseFloat(spinner.style.borderWidth);
+            };
+            expect(strokeAt(24)).toBe(3);
+            expect(strokeAt(48)).toBe(6);
+            expect(strokeAt(64)).toBe(8);
+            host.remove();
+        });
+    });
+
+    await describe('adw-spinner sizing (adw_spinner_measure minimum = natural)', async () => {
+        for (const { value, size, rule } of SPINNER_SIZE_VECTORS) {
+            await it(`size ${JSON.stringify(value ?? null)} → a ${spinnerGeometry(size, size).diameter}px ring — ${rule}`, () => {
+                const { host } = mountSized(400);
+                const spinner = document.createElement('adw-spinner');
+                if (value !== null && value !== undefined) spinner.setAttribute('size', String(value));
+                host.appendChild(spinner);
+
+                expect(spinner.offsetWidth).toBe(spinnerGeometry(size, size).diameter);
+                host.remove();
+            });
+        }
+
+        await it('defaults to the measured 16, not the invented 24', () => {
+            const { host } = mountSized(400);
+            const spinner = document.createElement('adw-spinner');
+            host.appendChild(spinner);
+            expect(spinner.offsetWidth).toBe(ADW_SPINNER_MIN_SIZE);
+            host.remove();
+        });
+    });
+
+    await describe('adw-toolbar-view style classes (update_undershoots + the style setters)', async () => {
+        for (const { input, view, topBar, bottomBar, rule } of TOOLBAR_VIEW_CLASS_VECTORS) {
+            await it(`${input.topBarStyle}/${input.bottomBarStyle} → [${view.join(' ')}] — ${rule}`, () => {
+                const { host, view: element } = mountToolbarView(input.topBarHeight, input.bottomBarHeight);
+                element.setAttribute('top-bar-style', input.topBarStyle);
+                element.setAttribute('bottom-bar-style', input.bottomBarStyle);
+                if (input.extendContentToTopEdge) element.setAttribute('extend-content-to-top-edge', '');
+                if (input.extendContentToBottomEdge) element.setAttribute('extend-content-to-bottom-edge', '');
+
+                const topEl = element.querySelector('.adw-toolbar-view-top') as HTMLElement;
+                const bottomEl = element.querySelector('.adw-toolbar-view-bottom') as HTMLElement;
+
+                for (const cls of ['undershoot-top', 'undershoot-bottom']) {
+                    expect(element.classList.contains(cls)).toBe(view.includes(cls));
+                }
+                for (const cls of ['raised', 'border']) {
+                    expect(topEl.classList.contains(cls)).toBe(topBar.includes(cls));
+                    expect(bottomEl.classList.contains(cls)).toBe(bottomBar.includes(cls));
+                }
+                host.remove();
+            });
+        }
+
+        await it('drops the undershoot again when the style stops being flat', () => {
+            const { host, view } = mountToolbarView(46, 0);
+            expect(view.classList.contains('undershoot-top')).toBe(true);
+            view.setAttribute('top-bar-style', 'raised');
+            expect(view.classList.contains('undershoot-top')).toBe(false);
+            view.setAttribute('top-bar-style', 'flat');
+            expect(view.classList.contains('undershoot-top')).toBe(true);
+            host.remove();
+        });
+
+        await it('treats an unknown style as flat, the way the enum guard does', () => {
+            const { host, view } = mountToolbarView(46, 0);
+            view.setAttribute('top-bar-style', 'shadowed');
+            const topEl = view.querySelector('.adw-toolbar-view-top') as HTMLElement;
+            expect(topEl.classList.contains('raised')).toBe(false);
+            expect(view.classList.contains('undershoot-top')).toBe(true);
+            host.remove();
+        });
+    });
+};