@gjsify/adwaita-web 0.54.0 → 0.55.0

package/src/adw-breakpoint-bin.spec.ts

@@ -0,0 +1,324 @@
+// DOM-level tests for `<adw-breakpoint-bin>`, driven by the SAME breakpoint-bin
+// vectors the core suite asserts (`@gjsify/adwaita-core/conformance`).
+//
+// Every row runs against a real element in a real document, resized by a real
+// `ResizeObserver`, and read back off the DOM — not off `BreakpointBinState`, which a
+// renderer could call without ever wiring it to a size. That matters most for these two
+// tables: the pick order (the LAST match wins, not the narrowest) and the restore order
+// (a property both breakpoints set is written ONCE) are the two rules a port gets wrong
+// by reading the source the intuitive way.
+//
+// HOW A VECTOR READS BACK. The tables name objects and properties; here an object is a
+// labelled `<gtk-label id="…">` inside the bin and a property is an ATTRIBUTE on it,
+// which is the form the `breakpoints` attribute writes and therefore the only thing
+// observable. Every original starts ABSENT, so `orig:<object>.<property>` in a table —
+// the value `adw_breakpoint_add_setter` captures — means "the attribute is gone again",
+// which is `removeAttribute` and is half the behaviour under test.
+import { describe, expect, it } from '@gjsify/unit';
+
+import { BREAKPOINT_PICK_VECTORS, BREAKPOINT_TRANSITION_VECTORS } from '@gjsify/adwaita-core/conformance';
+import type { AdwBreakpointBin } from './elements/adw-breakpoint-bin.js';
+
+/** Two frame callbacks — where a `ResizeObserver` delivery lands. */
+function settle(): Promise<void> {
+    return new Promise((resolve) => {
+        requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+    });
+}
+
+/** One `[object, property]` per pair any setter in `breakpoints` names. */
+function universe(
+    breakpoints: readonly (readonly [string, readonly (readonly [string, string, string])[]])[],
+): string[] {
+    const keys = new Set<string>();
+    for (const [, setters] of breakpoints) for (const [object, property] of setters) keys.add(`${object}.${property}`);
+    return [...keys].sort();
+}
+
+/** `obj.prop=value`, or `obj.prop=<absent>` when the element does not carry it. */
+function read(objects: ReadonlyMap<string, Element>, keys: readonly string[]): string[] {
+    return keys.map((key) => {
+        const dot = key.lastIndexOf('.');
+        const value = objects.get(key.slice(0, dot))?.getAttribute(key.slice(dot + 1));
+        return value === undefined ? key : `${key}=${value ?? '<absent>'}`;
+    });
+}
+
+/**
+ * The state a transition is expected to leave, over the whole universe of pairs.
+ *
+ * Read as a STATE rather than replayed as writes, because that is the only way the skip
+ * shows up at all: restoring `title` and then setting it again lands on the same value as
+ * setting it once, and only the pair LIST says which happened — every pair the transition
+ * did not write is at its original, which is absent here.
+ */
+function spell(row: (typeof BREAKPOINT_TRANSITION_VECTORS)[number], step: number): string[] {
+    const written = new Map<string, string>();
+    for (const write of row.writes[step] ?? []) {
+        const equals = write.indexOf('=');
+        const value = write.slice(equals + 1);
+        written.set(write.slice(0, equals), value.startsWith('orig:') ? '<absent>' : value);
+    }
+    return universe(row.breakpoints)
+        .map((key) => `${key}=${written.get(key) ?? '<absent>'}`)
+        .sort();
+}
+
+/**
+ * Mount one bin filling a host of the given size, with these breakpoints and one child
+ * per object.
+ *
+ * The bin FILLS its host: a GTK widget takes the allocation its parent gives it, and a
+ * block-level div only fills the width. Both axes of the pick table are measured, so the
+ * stage has to hand over a height as well — which is the C's own advice to set
+ * `width-request`/`height-request` on a bin that carries breakpoints.
+ */
+async function mount(
+    width: number,
+    height: number,
+    breakpoints: string,
+    objects: readonly string[],
+): Promise<{ bin: AdwBreakpointBin; host: HTMLElement; children: Map<string, Element> }> {
+    const host = document.createElement('div');
+    host.style.width = `${width}px`;
+    host.style.height = `${height}px`;
+    document.body.appendChild(host);
+    const bin = document.createElement('adw-breakpoint-bin') as AdwBreakpointBin;
+    bin.style.height = '100%';
+    bin.setAttribute('breakpoints', breakpoints);
+    host.appendChild(bin);
+    const children = new Map<string, Element>();
+    for (const name of objects) {
+        const el = document.createElement('gtk-label');
+        el.id = name;
+        bin.appendChild(el);
+        children.set(name, el);
+    }
+    await settle();
+    return { bin, host, children };
+}
+
+/** `breaks` as the attribute takes it, with each target a selector on its object. */
+const authored = (
+    breakpoints: readonly (readonly [string, readonly (readonly [string, string, string])[]])[],
+): string =>
+    JSON.stringify(
+        breakpoints.map(([condition, setters]) => ({
+            condition,
+            setters: setters.map(([target, property, value]) => ({ target: `#${target}`, property, value })),
+        })),
+    );
+
+export const AdwBreakpointBinTest = async () => {
+    for (const row of BREAKPOINT_PICK_VECTORS) {
+        await it(`picks the right breakpoint — ${row.rule}`, async () => {
+            // No setters at all: this table is about WHICH condition wins, and a setter
+            // would add a second thing the row could be failing at.
+            // One child, because a bin with no child picks nothing at all
+            // (`adw_breakpoint_bin_size_allocate` returns before the loop, :427) and this
+            // table is about WHICH condition wins.
+            const { bin, host } = await mount(
+                row.size.width,
+                row.size.height,
+                JSON.stringify(row.conditions.map((condition) => ({ condition, setters: [] }))),
+                ['child'],
+            );
+            await settle();
+            const picked = bin.currentBreakpoint;
+            host.remove();
+            expect(`[${row.conditions.join(' | ')}] @ ${row.size.width}×${row.size.height} → ${picked ?? 'none'}`).toBe(
+                `[${row.conditions.join(' | ')}] @ ${row.size.width}×${row.size.height} → ${row.pick ?? 'none'}`,
+            );
+        });
+    }
+
+    for (const row of BREAKPOINT_TRANSITION_VECTORS) {
+        await it(`transitions — ${row.rule}`, async () => {
+            const keys = universe(row.breakpoints);
+            const names = [...new Set(row.breakpoints.flatMap(([, setters]) => setters.map(([o]) => o)))].sort();
+            const { host, children } = await mount(800, 600, authored(row.breakpoints), names);
+            let previous = read(children, keys);
+            const observed: string[][] = [];
+            const wanted: string[][] = [];
+            for (const [at, size] of row.sizes.entries()) {
+                // A `null` step means NO transition at all, so the state after it is the
+                // state before it — which is the assertion, not a copy of what was read.
+                if (row.writes[at] === null) wanted.push(previous);
+                else wanted.push(spell(row, at));
+                host.style.width = `${size.width}px`;
+                host.style.height = `${size.height}px`;
+                await settle();
+                const now = read(children, keys);
+                observed.push(now);
+                previous = now;
+            }
+            host.remove();
+            for (let at = 0; at < observed.length; at++) {
+                expect(`${row.rule} step ${at}: ${JSON.stringify(observed[at])}`).toBe(
+                    `${row.rule} step ${at}: ${JSON.stringify(wanted[at])}`,
+                );
+            }
+        });
+    }
+
+    await describe('<adw-breakpoint-bin> the bin itself', async () => {
+        await it('has no minimum size while it holds breakpoints, and clips like the C', async () => {
+            const { bin, host } = await mount(
+                400,
+                600,
+                JSON.stringify([{ condition: 'max-width: 720px', setters: [] }]),
+                [],
+            );
+            const style = getComputedStyle(bin);
+            const report = `min-width:${style.minWidth} overflow:${style.overflow}`;
+            host.remove();
+            expect(report).toBe('min-width:0px overflow:hidden');
+        });
+
+        await it('signals unapply BEFORE the writes and apply AFTER them', async () => {
+            // Mounted WIDE and listening before the first write, so the apply is in the
+            // log rather than already done.
+            const { bin, host, children } = await mount(
+                900,
+                600,
+                JSON.stringify([
+                    {
+                        condition: 'max-width: 720px',
+                        setters: [{ target: '#caption', property: 'label', value: 'Narrow' }],
+                    },
+                ]),
+                ['caption'],
+            );
+            const caption = children.get('caption') as Element;
+            const log: string[] = [];
+            bin.addEventListener('breakpoint-unapply', () => log.push(`unapply:${caption.getAttribute('label')}`));
+            bin.addEventListener('breakpoint-apply', () => log.push(`apply:${caption.getAttribute('label')}`));
+            bin.addEventListener('notify::current-breakpoint', () => log.push(`notify:${bin.currentBreakpoint}`));
+            host.style.width = '400px';
+            await settle();
+            host.style.width = '900px';
+            await settle();
+            host.remove();
+            // A listener on the APPLY end sees the value its own breakpoint wrote and one
+            // on the UNAPPLY end still sees the OUTGOING value — the signal precedes the
+            // restore, so neither end observes the restore at all.
+            expect(log.join(' | ')).toBe('apply:Narrow | notify:0 | unapply:Narrow | notify:null');
+        });
+
+        await it('writes a property both breakpoints set ONCE, not restored and re-set', async () => {
+            const { host, children } = await mount(
+                500,
+                600,
+                JSON.stringify([
+                    {
+                        condition: 'max-width: 720px',
+                        setters: [
+                            { target: '#view', property: 'title', value: 'narrow' },
+                            { target: '#view', property: 'collapsed', value: 'true' },
+                        ],
+                    },
+                    {
+                        condition: 'max-width: 400px',
+                        setters: [{ target: '#view', property: 'collapsed', value: 'false' }],
+                    },
+                ]),
+                ['view'],
+            );
+            const view = children.get('view') as Element;
+            // 500 is inside the FIRST breakpoint only, so the second is entered by a
+            // resize and the skip is the difference between one mutation per property
+            // and two on the one both breakpoints set. Without it the restore would write
+            // `collapsed` twice — once removing it, once setting `false` — and the final
+            // state would be identical either way, which is why the COUNT is the assertion.
+            const mutations = new Map<string, number>();
+            new MutationObserver((records) => {
+                for (const record of records) {
+                    mutations.set(record.attributeName, (mutations.get(record.attributeName) ?? 0) + 1);
+                }
+            }).observe(view, { attributes: true });
+            host.style.width = '300px';
+            await settle();
+            const report = `${[...mutations]
+                .sort()
+                .map(([k, v]) => `${k}x${v}`)
+                .join(' ')} collapsed:${view.getAttribute('collapsed')} title:${view.hasAttribute('title')}`;
+            host.remove();
+            expect(report).toBe('collapsedx1 titlex1 collapsed:false title:false');
+        });
+
+        await it('keeps tracking its conditions after a re-parent', async () => {
+            const first = document.createElement('div');
+            first.style.width = '400px';
+            first.style.height = '600px';
+            document.body.appendChild(first);
+            const bin = document.createElement('adw-breakpoint-bin') as AdwBreakpointBin;
+            bin.setAttribute(
+                'breakpoints',
+                JSON.stringify([
+                    {
+                        condition: 'max-width: 720px',
+                        setters: [{ target: '#caption', property: 'label', value: 'Narrow' }],
+                    },
+                ]),
+            );
+            const caption = document.createElement('gtk-label');
+            caption.id = 'caption';
+            caption.setAttribute('label', 'Wide');
+            bin.appendChild(caption);
+            first.appendChild(bin);
+            await settle();
+
+            // 800 → 500 → 900 is the cycle `BreakpointBinState.inherit` was added for: a
+            // bin rebuilt at "none applied" hears no unapply on the way back to 900px and
+            // the caption stays narrow for good.
+            const second = document.createElement('div');
+            second.style.width = '500px';
+            second.style.height = '600px';
+            document.body.appendChild(second);
+            second.appendChild(bin);
+            await settle();
+            const narrow = caption.getAttribute('label');
+
+            second.style.width = '900px';
+            await settle();
+            const wide = caption.getAttribute('label');
+
+            first.remove();
+            second.remove();
+            expect(`500px:${narrow} → 900px:${wide}`).toBe('500px:Narrow → 900px:Wide');
+        });
+
+        await it('picks nothing while it has no child, as `adw_breakpoint_bin_size_allocate` does', async () => {
+            const { bin, host } = await mount(
+                400,
+                600,
+                JSON.stringify([
+                    {
+                        condition: 'max-width: 720px',
+                        setters: [{ target: '#caption', property: 'label', value: 'Narrow' }],
+                    },
+                ]),
+                [],
+            );
+            const childless = bin.currentBreakpoint;
+            bin.appendChild(document.createElement('gtk-label'));
+            // A child arriving is not a size change, and the C only re-picks on an
+            // allocation — so the next allocation is what this test waits for.
+            host.style.width = '401px';
+            await settle();
+            host.style.width = '400px';
+            await settle();
+            const withChild = bin.currentBreakpoint;
+            host.remove();
+            expect(`childless:${childless} with:${withChild}`).toBe('childless:null with:0');
+        });
+
+        await it('applies nothing from an attribute that is not JSON', async () => {
+            const { bin, host } = await mount(400, 600, 'not json', []);
+            await settle();
+            const dropped = bin.currentBreakpoint;
+            host.remove();
+            expect(`dropped:${dropped}`).toBe('dropped:null');
+        });
+    });
+};

package/src/adw-clamp-scrollable.spec.ts

@@ -0,0 +1,189 @@
+// DOM-level tests for <adw-clamp-scrollable>: the SAME clamp arithmetic as
+// `<adw-clamp>` (adw-clamp-layout.c:156-235) but measured along the ORIENTATION the
+// class overrides (adw-clamp-scrollable.c:78-92), and with the scrollport on the
+// element rather than the child — the port's one deviation, and the reason
+// `hscroll-policy`/`vscroll-policy` write `overflow` here
+// (adw-clamp-scrollable.c:440-455).
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { AdwClampScrollable } from './elements/adw-clamp-scrollable.js';
+
+/** Wait for a ResizeObserver delivery (it runs after layout, before paint). */
+function settle(): Promise<void> {
+    return new Promise((resolve) => {
+        requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+    });
+}
+
+/** A scrollport in a fixed host, with one plain block child — the shape every story uses. */
+function mount(
+    available: number,
+    attributes: Record<string, string> = {},
+): { el: AdwClampScrollable; child: HTMLElement; host: HTMLElement } {
+    const host = document.createElement('div');
+    host.style.width = `${available}px`;
+    host.style.height = `${available}px`;
+    document.body.appendChild(host);
+    const el = document.createElement('adw-clamp-scrollable') as AdwClampScrollable;
+    for (const [name, value] of Object.entries(attributes)) el.setAttribute(name, value);
+    const child = document.createElement('div');
+    child.textContent = 'clamped';
+    el.appendChild(child);
+    host.appendChild(el);
+    return { el, child, host };
+}
+
+/** `clampAllocate`'s three classes, as the element stamps them 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;
+}
+
+export const AdwClampScrollableTest = async () => {
+    await describe('<adw-clamp-scrollable> cap along the clamped axis', async () => {
+        await it('caps the CHILD, never itself', async () => {
+            const { el, child, host } = mount(1000);
+            await settle();
+            expect(child.style.maxWidth).toBe('600px');
+            expect(Math.round(child.getBoundingClientRect().width)).toBe(600);
+            // The element is the scrollport: a cap on itself would feed its own capped
+            // width back into its own ResizeObserver.
+            expect(el.style.maxWidth).toBe('');
+            expect(el.clientWidth).toBe(1000);
+            host.remove();
+        });
+
+        await it('stamps the size class the clamp layout would', async () => {
+            const large = mount(1000);
+            await settle();
+            expect(sizeClassOf(large.child)).toBe('large');
+            large.host.remove();
+
+            // 700 sits in the easing region between `lower` 400 and `upper`
+            // 400 + 3·200, so the cap bites only halfway.
+            const medium = mount(700);
+            await settle();
+            expect(medium.child.style.maxWidth).toBe('575px');
+            expect(sizeClassOf(medium.child)).toBe('medium');
+            medium.host.remove();
+
+            const small = mount(300);
+            await settle();
+            expect(sizeClassOf(small.child)).toBe('small');
+            small.host.remove();
+        });
+
+        await it('tightens below the cap, easing the transition into it', async () => {
+            const { el, child, host } = mount(700);
+            el.maximumSize = 600;
+            el.tighteningThreshold = 400;
+            await settle();
+            expect(child.style.maxWidth).toBe('575px');
+            host.remove();
+        });
+
+        await it('a threshold ABOVE the maximum removes the easing region', async () => {
+            const { el, child, host } = mount(700);
+            el.maximumSize = 600;
+            el.tighteningThreshold = 800;
+            await settle();
+            expect(child.style.maxWidth).toBe('600px');
+            host.remove();
+        });
+
+        await it('follows `unit`, through the conversion C does per property', async () => {
+            const { el, child, host } = mount(1000);
+            el.unit = 'pt';
+            el.maximumSize = 450;
+            await settle();
+            // 450pt at 96dpi is the same 600px the default 600sp is.
+            expect(child.style.maxWidth).toBe('600px');
+            host.remove();
+        });
+
+        await it('a VERTICAL clamp caps the height and centres on the block axis', async () => {
+            const { el, child, host } = mount(1000, { orientation: 'vertical' });
+            el.style.height = '1000px';
+            await settle();
+            expect(child.style.maxHeight).toBe('600px');
+            expect(child.style.maxWidth).toBe('');
+            expect(child.style.marginBlock).toBe('auto');
+            expect(child.style.marginInline).toBe('');
+            host.remove();
+        });
+
+        await it('follows the scrollport instead of pinning the child to the cap', async () => {
+            const { child, host } = mount(1000);
+            await settle();
+            host.style.width = '360px';
+            await settle();
+            expect(child.style.maxWidth).toBe('360px');
+            expect(Math.round(child.getBoundingClientRect().width)).toBe(360);
+            host.remove();
+        });
+
+        await it('caps a child appended after connect', async () => {
+            const { el, host } = mount(1000);
+            await settle();
+            const late = document.createElement('div');
+            el.appendChild(late);
+            await settle();
+            expect(late.style.maxWidth).toBe('600px');
+            host.remove();
+        });
+
+        await it('reports the GIR defaults before anything is set', () => {
+            const { el, host } = mount(1000);
+            expect(el.maximumSize).toBe(600);
+            expect(el.tighteningThreshold).toBe(400);
+            expect(el.unit).toBe('sp');
+            expect(el.orientation).toBe('horizontal');
+            host.remove();
+        });
+    });
+
+    await describe('<adw-clamp-scrollable> the policies decide whether it scrolls', async () => {
+        await it('defaults to GTK_POLICY_AUTOMATIC on both axes', async () => {
+            const { el, host } = mount(400);
+            await settle();
+            expect(el.style.overflowX).toBe('auto');
+            expect(el.style.overflowY).toBe('auto');
+            host.remove();
+        });
+
+        await it('`never` clamps the axis shut and `always` always shows it', async () => {
+            const { el, host } = mount(400, { 'hscroll-policy': 'never', 'vscroll-policy': 'always' });
+            await settle();
+            expect(el.style.overflowX).toBe('hidden');
+            expect(el.style.overflowY).toBe('scroll');
+            host.remove();
+        });
+
+        await it('`automatic` scrolls exactly when the content does', async () => {
+            // The clamp caps the WIDTH here, so the height is what scrolls.
+            const { el, child, host } = mount(400);
+            el.style.height = '200px';
+            await settle();
+            // A child that fits is not scrollable, which is what AUTOMATIC means.
+            expect(el.scrollHeight <= el.clientHeight).toBe(true);
+            child.style.height = '900px';
+            await settle();
+            expect(el.scrollHeight).toBeGreaterThan(el.clientHeight);
+            host.remove();
+        });
+
+        await it('a scrollport with nothing to measure against does not collapse the child', async () => {
+            const { el, child, host } = mount(1000, { orientation: 'vertical' });
+            el.style.height = '0px';
+            await settle();
+            // GTK's equivalent is `for_size = -1`: hand the child nothing rather than
+            // capping it at 0 and taking the page with it.
+            expect(child.style.maxHeight).toBe('');
+            expect(child.style.maxWidth).toBe('');
+            expect(sizeClassOf(child)).toBeNull();
+            host.remove();
+        });
+    });
+};