@gjsify/adwaita-web 0.53.0 → 0.55.0

package/src/gtk-scrollbar.spec.ts

@@ -0,0 +1,244 @@
+// DOM-level tests for <gtk-scrollbar>: the two properties it has (an adjustment and an
+// orientation), `GtkRange`'s slider geometry in the two fractions upstream computes, and the
+// keys `GtkScrollbar`'s own documentation names.
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { GtkScrollbar } from './elements/gtk-scrollbar.js';
+
+/** A scrollbar of a known size, so the trough's own length — the fraction's denominator — is exact. */
+function mount(vertical = false): { el: GtkScrollbar; host: HTMLElement } {
+    const host = document.createElement('div');
+    host.style.width = '300px';
+    host.style.height = '300px';
+    document.body.appendChild(host);
+    const el = document.createElement('gtk-scrollbar') as GtkScrollbar;
+    if (vertical) el.setAttribute('orientation', 'vertical');
+    el.style.height = vertical ? '200px' : '24px';
+    el.style.width = vertical ? '24px' : '200px';
+    host.appendChild(el);
+    return { el, host };
+}
+
+const parts = (bar: GtkScrollbar): { trough: HTMLElement; slider: HTMLElement } => ({
+    trough: bar.querySelector('.adw-scrollbar-trough') as HTMLElement,
+    slider: bar.querySelector('.adw-scrollbar-slider') as HTMLElement,
+});
+
+/** `--adw-scrollbar-size` / `--adw-scrollbar-position`, which is what `_render` computed. */
+const geometry = (slider: HTMLElement): { size: number; position: number } => ({
+    size: Number.parseFloat(slider.style.getPropertyValue('--adw-scrollbar-size')),
+    position: Number.parseFloat(slider.style.getPropertyValue('--adw-scrollbar-position')),
+});
+
+const press = (el: HTMLElement, key: string): void => {
+    el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true }));
+};
+
+export const GtkScrollbarTest = async () => {
+    await describe('<gtk-scrollbar> its two properties', async () => {
+        await it('is a horizontal scrollbar with NO adjustment, which is the pspec default', async () => {
+            const { el, host } = mount();
+            expect(el.orientation).toBe('horizontal');
+            expect(el.classList.contains('horizontal')).toBe(true);
+            expect(el.getAttribute('role')).toBe('scrollbar');
+            expect(el.getAttribute('aria-orientation')).toBe('horizontal');
+            // A NULL adjustment is not a null range: `gtk_range_set_adjustment` answers one
+            // with `gtk_adjustment_new (0, 0, 0, 0, 0, 0)` (gtkrange.c:687-688), so the
+            // property reads back a real adjustment whose `upper` is 0.
+            expect(el.adjustment.upper).toBe(0);
+            expect(el.adjustment.lower).toBe(0);
+            // `upper - lower == 0` puts the thumb at 0, and the accessible range is all zeros
+            // too — which is `upper - page_size`, `lower` and `value` (gtkscrollbar.c:309-313).
+            expect(el.getAttribute('aria-valuemin')).toBe('0');
+            expect(el.getAttribute('aria-valuemax')).toBe('0');
+            expect(el.getAttribute('aria-valuenow')).toBe('0');
+            // And NO insensitivity: nothing in gtkscrollbar.c, gtkrange.c or
+            // gtkscrolledwindow.c ever calls `gtk_widget_set_sensitive` on a bar.
+            expect(el.getAttribute('aria-disabled')).toBe(null);
+            expect(el.hasAttribute('disabled')).toBe(false);
+            host.remove();
+        });
+
+        await it('leaves the thumb at its own size when there is no range to scroll', async () => {
+            const { el, host } = mount(true);
+            const { trough, slider } = parts(el);
+            // `upper - lower != 0` is the condition the C guards its fraction with
+            // (gtkrange.c:2779-2782); without it the slider takes its OWN measured size,
+            // which is why no length is written and the stylesheet's `$_slider_min_length`
+            // floor stands in for what GTK measured.
+            expect(trough.clientHeight > 0).toBe(true);
+            expect(slider.style.getPropertyValue('--adw-scrollbar-size')).toBe('');
+            // The POSITION is 0 either way — `upper - lower - page_size != 0` is the C's
+            // own guard for it (gtkrange.c:2790-2793) — but it is always written.
+            expect(slider.style.getPropertyValue('--adw-scrollbar-position')).toBe('0px');
+            host.remove();
+        });
+
+        await it('reads the adjustment from its JSON attribute and announces the range', async () => {
+            const { el, host } = mount(true);
+            el.setAttribute('adjustment', '{"upper":200,"pageSize":50,"stepIncrement":10,"pageIncrement":40}');
+            expect(el.adjustment.upper).toBe(200);
+            expect(el.getAttribute('aria-valuemin')).toBe('0');
+            // `aria-valuemax` is `upper - page_size`, the position the bar can reach.
+            expect(el.getAttribute('aria-valuemax')).toBe('150');
+            expect(el.getAttribute('aria-valuenow')).toBe('0');
+            expect(el.classList.contains('vertical')).toBe(true);
+            host.remove();
+        });
+
+        await it('notifies the property when the adjustment is replaced', async () => {
+            const { el, host } = mount();
+            const seen: unknown[] = [];
+            el.addEventListener('notify::adjustment', (e) => seen.push((e as CustomEvent).detail));
+            el.adjustment = { lower: 0, upper: 10, stepIncrement: 1, pageIncrement: 1, pageSize: 0, value: 0 };
+            expect(seen.length).toBe(1);
+            el.setAttribute('adjustment', '{"upper":20}');
+            // A partial write MERGES, which is `gtk_adjustment_configure`'s contract.
+            expect(el.adjustment.upper).toBe(20);
+            expect(el.adjustment.stepIncrement).toBe(1);
+            host.remove();
+        });
+
+        await it('clamps the value it is given, which is what the setter promises', async () => {
+            const { el, host } = mount();
+            el.adjustment = { lower: 0, upper: 100, stepIncrement: 1, pageIncrement: 10, pageSize: 0, value: 0 };
+            el.value = 500;
+            expect(el.value).toBe(100);
+            el.value = -20;
+            expect(el.value).toBe(0);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-scrollbar> the trough pointer rules', async () => {
+        await it('warps on a primary click outside the slider, wherever in the bar it lands', async () => {
+            const { el, host } = mount();
+            el.adjustment = { lower: 0, upper: 200, stepIncrement: 10, pageIncrement: 40, pageSize: 50, value: 0 };
+            const { trough, slider } = parts(el);
+            const box = trough.getBoundingClientRect();
+            // The BAR, not the trough: `gtk_range_click_gesture_pressed` folds everything
+            // that is not the slider into the trough (gtkrange.c:2052-2058), and libadwaita
+            // gives the trough its own `margin: 9px` (`_scrolling.scss:7`), so the margin
+            // between the bar's edge and the trough's is trough to GTK.
+            expect(box.left - el.getBoundingClientRect().left).toBeGreaterThan(0);
+            el.dispatchEvent(
+                new PointerEvent('pointerdown', {
+                    button: 0,
+                    bubbles: true,
+                    cancelable: true,
+                    clientX: box.left + box.width * 0.75,
+                    clientY: box.top + box.height / 2,
+                }),
+            );
+            // `gtk-primary-button-warps-slider` defaults TRUE (gtksettings.c:734-736), so the
+            // slider jumps to three quarters of the trough.
+            expect(el.value > 100).toBe(true);
+            expect(slider.classList.contains('fine-tune')).toBe(false);
+            host.remove();
+        });
+
+        await it('pages on a middle click instead, and Shift is the fine adjustment', async () => {
+            const { el, host } = mount();
+            el.adjustment = { lower: 0, upper: 400, stepIncrement: 10, pageIncrement: 40, pageSize: 0, value: 0 };
+            const { trough, slider } = parts(el);
+            const box = trough.getBoundingClientRect();
+            const at = (button: number, shiftKey: boolean, fraction: number): void => {
+                el.dispatchEvent(
+                    new PointerEvent('pointerdown', {
+                        button,
+                        shiftKey,
+                        bubbles: true,
+                        cancelable: true,
+                        clientX: box.left + box.width * fraction,
+                        clientY: box.top + box.height / 2,
+                    }),
+                );
+            };
+            at(1, false, 0.9);
+            // A middle button PAGES toward the click (gtkrange.c:2097-2115), so a whole
+            // page increment rather than the click's own position.
+            expect(el.value).toBe(40);
+            // The direction is `click_value > value` — a bisection by click position, so
+            // the clicks are taken clearly to either side of where 40 sits (a tenth of the
+            // free space) rather than exactly on it, where the comparison is a tie.
+            at(0, true, 0.05);
+            expect(el.value).toBe(0);
+            at(0, true, 0.5);
+            expect(el.value).toBe(40);
+            // Shift on the SLIDER is the fine adjustment, not a page.
+            at(0, true, 0.5);
+            expect(slider.classList.contains('fine-tune')).toBe(false);
+            host.remove();
+        });
+    });
+
+    await describe("<gtk-scrollbar> GtkRange's slider geometry", async () => {
+        await it('sizes the slider by page_size over the whole range, and places it by the SCROLLABLE one', async () => {
+            const { el, host } = mount(true);
+            el.adjustment = { lower: 0, upper: 400, stepIncrement: 10, pageIncrement: 40, pageSize: 100, value: 0 };
+            const { trough, slider } = parts(el);
+            const length = trough.clientHeight;
+            expect(length > 0).toBe(true);
+            // Two DIFFERENT denominators: the length is a quarter of the range, the position
+            // a fraction of the 300 that is left once the page is out of it.
+            expect(geometry(slider).size).toBe(length * 0.25);
+            expect(geometry(slider).position).toBe(0);
+            el.value = 300;
+            expect(geometry(slider).position).toBe(length - length * 0.25);
+            host.remove();
+        });
+
+        await it('puts the slider at the far end for the last reachable value', async () => {
+            const { el, host } = mount();
+            el.adjustment = { lower: 0, upper: 200, stepIncrement: 10, pageIncrement: 40, pageSize: 50, value: 150 };
+            const { trough, slider } = parts(el);
+            const length = trough.clientWidth;
+            expect(geometry(slider).position).toBe(length - length * 0.25);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-scrollbar> the keys its own doc names', async () => {
+        await it('steps with the arrows, pages with Page Up/Down and jumps with Home/End', async () => {
+            const { el, host } = mount();
+            el.adjustment = { lower: 0, upper: 100, stepIncrement: 5, pageIncrement: 25, pageSize: 0, value: 0 };
+            el.focus();
+            press(el, 'ArrowRight');
+            expect(el.value).toBe(5);
+            press(el, 'ArrowLeft');
+            expect(el.value).toBe(0);
+            press(el, 'PageDown');
+            expect(el.value).toBe(25);
+            press(el, 'Home');
+            expect(el.value).toBe(0);
+            press(el, 'End');
+            expect(el.value).toBe(100);
+            host.remove();
+        });
+
+        await it('answers only the arrows on its OWN axis', async () => {
+            const { el, host } = mount(true);
+            el.adjustment = { lower: 0, upper: 100, stepIncrement: 5, pageIncrement: 25, pageSize: 0, value: 0 };
+            el.focus();
+            // A horizontal bar's keys must not move a vertical one, and the other way round.
+            press(el, 'ArrowRight');
+            expect(el.value).toBe(0);
+            press(el, 'ArrowDown');
+            expect(el.value).toBe(5);
+            host.remove();
+        });
+
+        await it('clamps every key back to zero without an adjustment', async () => {
+            const { el, host } = mount();
+            el.focus();
+            // Not because the keys are refused — `resolveRangeKey` answers and
+            // `scrollBy` runs — but because `set_value` over the zero adjustment clamps to
+            // 0 and reports no change, which is the same answer `upper - page_size` gives.
+            press(el, 'End');
+            expect(el.value).toBe(0);
+            press(el, 'ArrowRight');
+            expect(el.value).toBe(0);
+            host.remove();
+        });
+    });
+};

package/src/gtk-scrolled-window.spec.ts

@@ -0,0 +1,262 @@
+// DOM-level tests for <gtk-scrolled-window>: the parts are GTK's (a viewport and two
+// scrollbars), the visibility rule is `upper - lower > page_size` and nothing else, and the
+// keys are the ones `gtk_scrolled_window_class_init` installs — Control for the arrows, and
+// Page Up/Down on the vertical axis bare while Ctrl+Page Up/Down is the horizontal one.
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { GtkScrolledWindow } from './elements/gtk-scrolled-window.js';
+
+/**
+ * A host of a known size and a window of its own, because GTK gives this widget an
+ * ALLOCATION and a browser one has to be given the same: an auto-height scrolled window grows
+ * with its content and has nothing to scroll.
+ */
+function mount(width = 200, height = 100): { el: GtkScrolledWindow; host: HTMLElement } {
+    const host = document.createElement('div');
+    host.style.width = `${width}px`;
+    host.style.height = `${height}px`;
+    document.body.appendChild(host);
+    const el = document.createElement('gtk-scrolled-window') as GtkScrolledWindow;
+    el.style.height = `${height}px`;
+    host.appendChild(el);
+    return { el, host };
+}
+
+/**
+ * One frame plus a microtask, which is where the slot observer's callback and the viewport's
+ * content watcher both land: the observer that adopts a late child is a microtask, and the one
+ * that re-measures the content is a `ResizeObserver`, delivered before the next paint.
+ */
+const settle = async (): Promise<void> => {
+    await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+};
+
+/**
+ * A column of labels taller than the window, which is what makes a bar appear.
+ *
+ * Appended AFTER connect on purpose — the binding is live, so a child added later lands where
+ * a declared one does, and the tests below are written against that rather than against a
+ * parse-time snapshot.
+ */
+async function fill(el: GtkScrolledWindow, rows = 10): Promise<void> {
+    for (let i = 0; i < rows; i++) {
+        const label = document.createElement('gtk-label');
+        label.setAttribute('label', `Row ${i}`);
+        // A flex item is blockified, so the height on the label is the box the viewport
+        // measures; an inline label would ignore it.
+        label.style.height = '40px';
+        el.appendChild(label);
+    }
+    await settle();
+}
+
+const bars = (el: GtkScrolledWindow): { horizontal: HTMLElement; vertical: HTMLElement } => ({
+    horizontal: el.hscrollbar() as HTMLElement,
+    vertical: el.vscrollbar() as HTMLElement,
+});
+
+/** The `detail` of every `event` dispatched on (or bubbling to) `el`. */
+function record(el: HTMLElement, event: string): unknown[] {
+    const details: unknown[] = [];
+    el.addEventListener(event, (e) => details.push((e as CustomEvent).detail));
+    return details;
+}
+
+const press = (el: HTMLElement, key: string, init: KeyboardEventInit = {}): void => {
+    el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true, ...init }));
+};
+
+export const GtkScrolledWindowTest = async () => {
+    await describe('<gtk-scrolled-window> its parts', async () => {
+        await it('builds a viewport and two scrollbars, and routes the child into the viewport', async () => {
+            const { el, host } = mount();
+            await fill(el, 2);
+            // GTK wraps a non-scrollable child in a GtkViewport and parents THAT
+            // (gtkscrolledwindow.c:785-793), which is what the DOM says here.
+            expect(el.viewport.localName).toBe('gtk-viewport');
+            expect(el.viewport.childElementCount).toBe(2);
+            expect(bars(el).vertical.getAttribute('orientation')).toBe('vertical');
+            expect(bars(el).horizontal.getAttribute('orientation')).toBe('horizontal');
+            expect(el.getAttribute('role')).toBe('generic');
+            host.remove();
+        });
+
+        await it('keeps a child appended after connect in the viewport', async () => {
+            const { el, host } = mount();
+            const late = document.createElement('gtk-label');
+            el.appendChild(late);
+            await settle();
+            expect(el.viewport.contains(late)).toBe(true);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-scrolled-window> the policies', async () => {
+        await it('shows an automatic bar only while the content is longer than the window', async () => {
+            const { el, host } = mount();
+            expect(bars(el).vertical.hidden).toBe(true);
+            await fill(el, 10);
+            expect(bars(el).vertical.hidden).toBe(false);
+            host.remove();
+        });
+
+        await it('draws an ALWAYS bar with nothing to scroll, and no NEVER bar ever', async () => {
+            const { el, host } = mount();
+            el.setAttribute('vscrollbar-policy', 'always');
+            expect(bars(el).vertical.hidden).toBe(false);
+            el.setAttribute('vscrollbar-policy', 'never');
+            expect(bars(el).vertical.hidden).toBe(true);
+            await fill(el, 10);
+            expect(bars(el).vertical.hidden).toBe(true);
+            // An unknown nick is the pspec's `automatic`, not a silent never.
+            el.setAttribute('vscrollbar-policy', 'sideways');
+            expect(el.vscrollbarPolicy).toBe('automatic');
+            expect(bars(el).vertical.hidden).toBe(false);
+            host.remove();
+        });
+
+        await it('carries the corner and the frame as classes, and the sizes as CSS', async () => {
+            const { el, host } = mount();
+            expect(el.classList.contains('top-left')).toBe(true);
+            el.setAttribute('window-placement', 'bottom-right');
+            expect(el.classList.contains('bottom-right')).toBe(true);
+            expect(el.classList.contains('top-left')).toBe(false);
+            el.setAttribute('has-frame', '');
+            expect(el.classList.contains('frame')).toBe(true);
+            // -1 is the pspec's default and writes NOTHING, as a size request of no value.
+            el.setAttribute('min-content-width', '200');
+            el.setAttribute('max-content-height', '300');
+            expect(el.style.minWidth).toBe('200px');
+            expect(el.style.maxHeight).toBe('300px');
+            expect(el.style.minHeight).toBe('');
+            expect(el.minContentWidth).toBe(200);
+            expect(el.maxContentHeight).toBe(300);
+            host.remove();
+        });
+
+        await it('adds the child size request to the scrollport, natural or minimum', async () => {
+            const { el, host } = mount();
+            await fill(el, 10);
+            // No request is made until one of the two asks for it: GTK only measures the
+            // child when `propagate-natural-*` or a NEVER policy does (gtkscrolledwindow.c:1841-1844).
+            expect(el.viewport.style.minHeight).toBe('');
+            // The NATURAL request is the child's `max-content` size, propagated up.
+            el.setAttribute('propagate-natural-height', '');
+            expect(el.propagateNaturalHeight).toBe(true);
+            expect(el.viewport.style.minHeight).toBe('max-content');
+            // A NEVER policy adds the child's MINIMUM request instead — and the natural one
+            // is the larger of the two, so it wins when both are asked for. Both are FALSE in
+            // the pspec, so their ATTRIBUTE is their presence, as `has-frame` is.
+            el.removeAttribute('propagate-natural-height');
+            el.setAttribute('vscrollbar-policy', 'never');
+            expect(el.viewport.style.minHeight).toBe('min-content');
+            // With both asked for on ONE axis the natural wins, and the other axis keeps
+            // its own answer.
+            el.setAttribute('propagate-natural-width', '');
+            expect(el.viewport.style.minWidth).toBe('max-content');
+            expect(el.viewport.style.minHeight).toBe('min-content');
+            el.setAttribute('propagate-natural-height', '');
+            expect(el.viewport.style.minHeight).toBe('max-content');
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-scrolled-window> scrolling it', async () => {
+        await it('moves the position with the keys class_init binds, and emits scroll-child', async () => {
+            const { el, host } = mount();
+            await fill(el, 10);
+            const seen = record(el, 'scroll-child');
+            el.focus();
+            // Ctrl+ArrowDown is a vertical STEP, and the bare pair is not bound at all.
+            press(el, 'ArrowDown');
+            expect(el.viewport.vadjustment.value).toBe(0);
+            press(el, 'ArrowDown', { ctrlKey: true });
+            expect(el.viewport.vadjustment.value).toBe(10);
+            press(el, 'PageDown');
+            expect(el.viewport.vadjustment.value).toBe(100);
+            press(el, 'End', { ctrlKey: true });
+            // Ctrl+End is the HORIZONTAL end, and `may_hscroll` is false — nothing scrolls
+            // sideways here — so no third `scroll-child` is emitted. Two events, not three.
+            expect(el.viewport.hadjustment.value).toBe(0);
+            expect(seen.length).toBe(2);
+            expect((seen[0] as { scroll: string }).scroll).toBe('step-forward');
+            expect((seen[0] as { horizontal: boolean }).horizontal).toBe(false);
+            expect((seen[1] as { scroll: string }).scroll).toBe('page-forward');
+            host.remove();
+        });
+
+        await it('binds Home and End bare as well, on the vertical axis', async () => {
+            const { el, host } = mount();
+            await fill(el, 10);
+            const seen = record(el, 'scroll-child');
+            el.focus();
+            // Home and End are bound TWICE (gtkscrolledwindow.c:904-907): bare for the
+            // VERTICAL axis and with CONTROL for the horizontal one. Dropping the bare pair
+            // would leave both dead on the only axis a window usually scrolls.
+            el.viewport.scrollAxis('vertical', 120);
+            press(el, 'End');
+            expect(el.viewport.vadjustment.value).toBe(300);
+            expect((seen[0] as { scroll: string }).scroll).toBe('end');
+            expect((seen[0] as { horizontal: boolean }).horizontal).toBe(false);
+            press(el, 'Home');
+            expect(el.viewport.vadjustment.value).toBe(0);
+            expect((seen[1] as { scroll: string }).scroll).toBe('start');
+            expect((seen[1] as { horizontal: boolean }).horizontal).toBe(false);
+            host.remove();
+        });
+
+        await it('emits move-focus-out for Ctrl+Tab, which GTK hands to the root', async () => {
+            const { el, host } = mount();
+            const seen = record(el, 'move-focus-out');
+            press(el, 'Tab', { ctrlKey: true, shiftKey: true });
+            expect(seen.length).toBe(1);
+            // `toEqual` compares with `==` in this runner, so a detail object is read field by
+            // field rather than compared as one value.
+            expect((seen[0] as { directionType: string }).directionType).toBe('backward');
+            host.remove();
+        });
+
+        await it('announces edge-reached when the position lands on a limit', async () => {
+            const { el, host } = mount();
+            await fill(el, 10);
+            const seen = record(el, 'edge-reached');
+            el.focus();
+            // A page is 90% of the window, so it takes a few of them to reach the far edge —
+            // and only the move that LANDS on the limit emits, which is what
+            // `maybe_emit_edge_reached` checks.
+            for (let i = 0; i < 6; i++) press(el, 'PageDown');
+            const edges = seen.map((detail) => (detail as { pos: string }).pos);
+            expect(edges.includes('bottom')).toBe(true);
+            expect(edges.includes('top')).toBe(false);
+            el.viewport.scrollAxis('vertical', 0);
+            expect(seen.map((detail) => (detail as { pos: string }).pos).includes('top')).toBe(true);
+            host.remove();
+        });
+
+        await it('drives the bar from the position, and the position from the bar', async () => {
+            const { el, host } = mount();
+            await fill(el, 10);
+            const bar = bars(el).vertical;
+            // A bar that is dragged is a viewport that scrolls: one writer per side.
+            (bar as unknown as { value: number }).value = 120;
+            expect(el.viewport.vadjustment.value).toBe(120);
+            el.viewport.scrollAxis('vertical', 60);
+            expect((bar as unknown as { value: number }).value).toBe(60);
+            host.remove();
+        });
+
+        await it('marks the edge indicators on the viewport, which is where the shading lives', async () => {
+            const { el, host } = mount();
+            await fill(el, 10);
+            const seen = record(el, 'edge-overshot');
+            // The shading controller reads the wheel deltas a clamped scrollport threw away,
+            // so a wheel past the end is what publishes `edge-overshot`.
+            el.viewport.scrollAxis('vertical', 100000);
+            el.viewport.dispatchEvent(new WheelEvent('wheel', { deltaY: 400, bubbles: true, cancelable: true }));
+            const overshots = seen.map((detail) => (detail as { pos: string }).pos);
+            expect(overshots.length > 0).toBe(true);
+            expect(overshots.includes('bottom')).toBe(true);
+            host.remove();
+        });
+    });
+};