@gjsify/adwaita-web 0.53.0 → 0.55.0

package/src/gtk-search-bar.spec.ts

@@ -0,0 +1,179 @@
+// DOM-level tests for `<gtk-search-bar>`: the revealer IS `search-mode-enabled`
+// (gtksearchbar.c:183-205), and the four ways a search starts and the two it stops are all in
+// gtksearchbar.c.
+//
+// The one rule worth a row of its own is that hiding CLEARS the entry (gtksearchbar.c:197-203):
+// a search that is dismissed must leave nothing behind, and that is a rule about the STATE,
+// not about the animation.
+
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { GtkSearchBar } from './elements/gtk-search-bar.js';
+
+function mount(showClose = true): GtkSearchBar {
+    const el = document.createElement('gtk-search-bar') as GtkSearchBar;
+    const field = document.createElement('input');
+    field.className = 'adw-entry';
+    el.appendChild(field);
+    if (showClose) el.setAttribute('show-close-button', '');
+    document.body.appendChild(el);
+    return el;
+}
+
+function unmountAll(): void {
+    for (const el of Array.from(document.querySelectorAll('gtk-search-bar'))) el.remove();
+}
+
+/** The box the C builds around the child, named because `inert` is not on `Element`. */
+function boxOf(el: GtkSearchBar): HTMLElement {
+    return el.querySelector<HTMLElement>('.adw-search-bar-box') as HTMLElement;
+}
+
+const key = (target: HTMLElement, name: string, init: KeyboardEventInit = {}): KeyboardEvent => {
+    const event = new KeyboardEvent('keydown', { key: name, bubbles: true, cancelable: true, ...init });
+    target.dispatchEvent(event);
+    return event;
+};
+
+export const GtkSearchBarTest = async () => {
+    await describe('<gtk-search-bar> search mode', async () => {
+        await it('starts collapsed and inert, as a revealer whose child is not mapped', () => {
+            const el = mount();
+            expect(el.searchModeEnabled).toBe(false);
+            expect(el.classList.contains('revealed')).toBe(false);
+            expect(boxOf(el).inert).toBe(true);
+            unmountAll();
+        });
+
+        await it('reveals, focuses the entry and leaves the collapsed state', () => {
+            const el = mount();
+            el.searchModeEnabled = true;
+            expect(el.classList.contains('revealed')).toBe(true);
+            expect(boxOf(el).inert).toBe(false);
+            expect(document.activeElement).toBe(el.entry);
+            unmountAll();
+        });
+
+        await it('clears the entry when it is hidden, and only then', () => {
+            const el = mount();
+            const entry = el.entry as HTMLInputElement;
+            el.searchModeEnabled = true;
+            entry.value = 'ada';
+            expect(entry.value).toBe('ada');
+            el.searchModeEnabled = false;
+            expect(entry.value).toBe('');
+            unmountAll();
+        });
+
+        await it('notifies once per real change', () => {
+            const el = mount();
+            const seen: unknown[] = [];
+            el.addEventListener('notify::search-mode-enabled', (event) => seen.push((event as CustomEvent).detail));
+            el.searchModeEnabled = true;
+            el.searchModeEnabled = true;
+            el.searchModeEnabled = false;
+            expect(seen).toStrictEqual([{ searchModeEnabled: true }, { searchModeEnabled: false }]);
+            unmountAll();
+        });
+    });
+
+    await describe('<gtk-search-bar> the close button', async () => {
+        await it('is hidden until `show-close-button` is set', () => {
+            const without = mount(false);
+            expect(without.showCloseButton).toBe(false);
+            expect(without.querySelector<HTMLButtonElement>('.adw-search-bar-close')?.hidden).toBe(true);
+            const with_ = mount(true);
+            expect(with_.showCloseButton).toBe(true);
+            expect(with_.querySelector<HTMLButtonElement>('.adw-search-bar-close')?.hidden).toBe(false);
+            unmountAll();
+        });
+
+        await it('turns the search off when pressed', () => {
+            const el = mount();
+            el.searchModeEnabled = true;
+            (el.querySelector('.adw-search-bar-close') as HTMLButtonElement).click();
+            expect(el.searchModeEnabled).toBe(false);
+            unmountAll();
+        });
+
+        await it('notifies once per real change', () => {
+            const el = mount(false);
+            const seen: unknown[] = [];
+            el.addEventListener('notify::show-close-button', (event) => seen.push((event as CustomEvent).detail));
+            el.showCloseButton = true;
+            el.showCloseButton = true;
+            expect(seen).toStrictEqual([{ showCloseButton: true }]);
+            unmountAll();
+        });
+    });
+
+    await describe('<gtk-search-bar> what starts a search', async () => {
+        await it('Escape inside the bar hides it', () => {
+            const el = mount();
+            el.searchModeEnabled = true;
+            key(el, 'Escape');
+            expect(el.searchModeEnabled).toBe(false);
+            unmountAll();
+        });
+
+        await it('typing into the connected editable reveals it', () => {
+            const el = mount();
+            const entry = el.entry as HTMLInputElement;
+            entry.value = 'a';
+            entry.dispatchEvent(new Event('input', { bubbles: true }));
+            expect(el.searchModeEnabled).toBe(true);
+            unmountAll();
+        });
+
+        await it('a printable key on the capture widget opens the bar and goes into the entry', () => {
+            const el = mount();
+            const capture = document.createElement('div');
+            document.body.appendChild(capture);
+            el.keyCaptureWidget = capture;
+            const event = key(capture, 'a');
+            expect(event.defaultPrevented).toBe(true);
+            expect(el.searchModeEnabled).toBe(true);
+            expect(el.entry?.value).toBe('a');
+            unmountAll();
+            capture.remove();
+        });
+
+        await it('a modified or functional key is left to the widget that owns it', () => {
+            const el = mount();
+            const capture = document.createElement('div');
+            document.body.appendChild(capture);
+            el.keyCaptureWidget = capture;
+            key(capture, 'a', { ctrlKey: true });
+            key(capture, 'ArrowDown');
+            expect(el.searchModeEnabled).toBe(false);
+            unmountAll();
+            capture.remove();
+        });
+
+        await it('stops listening once the capture widget is dropped', () => {
+            const el = mount();
+            const capture = document.createElement('div');
+            document.body.appendChild(capture);
+            el.keyCaptureWidget = capture;
+            el.keyCaptureWidget = null;
+            key(capture, 'a');
+            expect(el.searchModeEnabled).toBe(false);
+            unmountAll();
+            capture.remove();
+        });
+    });
+
+    await describe('<gtk-search-bar> a11y', async () => {
+        await it('carries the `search` role GTK declares for it', () => {
+            const el = mount();
+            expect(el.getAttribute('role')).toBe('search');
+            unmountAll();
+        });
+
+        await it("keeps the author's child inside the box the C builds around it", () => {
+            const el = mount();
+            expect(el.querySelector('.adw-search-bar-center input')).not.toBeNull();
+            unmountAll();
+        });
+    });
+};

package/src/gtk-search-entry.spec.ts

@@ -0,0 +1,142 @@
+// DOM-level tests for <gtk-search-entry>. Its whole reason to exist is the DELAY: typing
+// queues `search-changed`, emptying the field fires it at once and cancels the queue, and
+// the two keybinding signals are dispatched rather than acted on.
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { GtkSearchEntry } from './elements/gtk-search-entry.js';
+
+function mount(attrs: Record<string, string> = {}): { el: GtkSearchEntry; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const el = document.createElement('gtk-search-entry') as GtkSearchEntry;
+    for (const [name, value] of Object.entries(attrs)) el.setAttribute(name, value);
+    host.appendChild(el);
+    return { el, host };
+}
+
+function inner(el: GtkSearchEntry): HTMLInputElement {
+    return el.querySelector('input') as HTMLInputElement;
+}
+
+function clear(el: GtkSearchEntry): HTMLButtonElement {
+    return el.querySelector('.adw-search-entry-clear') as HTMLButtonElement;
+}
+
+/** Wait past the default 150ms delay, which is what `search-changed` is for. */
+function settle(ms = 220): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export const GtkSearchEntryTest = async () => {
+    await describe('<gtk-search-entry> the two icons', async () => {
+        await it('shows the search glyph always and the clear button only with text', () => {
+            const { el, host } = mount();
+            expect(el.querySelector('.adw-search-entry-icon')).not.toBeNull();
+            expect(clear(el).hidden).toBe(true);
+            inner(el).value = 'gjs';
+            inner(el).dispatchEvent(new Event('input'));
+            expect(clear(el).hidden).toBe(false);
+            host.remove();
+        });
+
+        await it('is a search box to assistive technology', () => {
+            const { el, host } = mount();
+            expect(el.getAttribute('role')).toBe('searchbox');
+            expect(el.querySelector('.adw-search-entry-clear')?.getAttribute('aria-label')).toBe('Clear Entry');
+            host.remove();
+        });
+
+        await it('the clear button empties the field, as gtk_icon_release does', () => {
+            const { el, host } = mount({ value: 'gtk' });
+            clear(el).click();
+            expect(inner(el).value).toBe('');
+            expect(clear(el).hidden).toBe(true);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-search-entry> search-delay', async () => {
+        await it('defaults to 150ms, which is the pspec default', () => {
+            const { el, host } = mount();
+            expect(el.searchDelay).toBe(150);
+            el.setAttribute('search-delay', '0');
+            expect(el.searchDelay).toBe(0);
+            host.remove();
+        });
+
+        await it('a keystroke queues search-changed instead of firing it at once', async () => {
+            const { el, host } = mount();
+            const seen: unknown[] = [];
+            el.addEventListener('search-changed', (e) => seen.push((e as CustomEvent).detail));
+            inner(el).value = 'g';
+            inner(el).dispatchEvent(new Event('input'));
+            expect(seen.length).toBe(0);
+            await settle();
+            expect(seen).toStrictEqual([{ value: 'g' }]);
+            host.remove();
+        });
+
+        await it('two keystrokes make ONE signal — the timeout is replaced, not queued', async () => {
+            const { el, host } = mount();
+            let count = 0;
+            el.addEventListener('search-changed', () => (count += 1));
+            for (const text of ['g', 'gj', 'gjs']) {
+                inner(el).value = text;
+                inner(el).dispatchEvent(new Event('input'));
+            }
+            await settle();
+            expect(count).toBe(1);
+            host.remove();
+        });
+
+        await it('emptying the field fires at once and cancels what was pending', async () => {
+            const { el, host } = mount({ value: 'gjs' });
+            const seen: unknown[] = [];
+            el.addEventListener('search-changed', (e) => seen.push((e as CustomEvent).detail));
+            clear(el).click();
+            expect(seen).toStrictEqual([{ value: '' }]);
+            await settle();
+            expect(seen.length).toBe(1);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-search-entry> keys', async () => {
+        await it('Enter activates and Escape stops the search', () => {
+            const { el, host } = mount();
+            const seen: string[] = [];
+            for (const name of ['activate', 'stop-search', 'next-match', 'previous-match']) {
+                el.addEventListener(name, () => seen.push(name));
+            }
+            const press = (key: string, init: KeyboardEventInit = {}) =>
+                inner(el).dispatchEvent(
+                    new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true, ...init }),
+                );
+            press('Enter');
+            press('Escape');
+            press('g', { ctrlKey: true });
+            press('g', { ctrlKey: true, shiftKey: true });
+            expect(seen).toStrictEqual(['activate', 'stop-search', 'next-match', 'previous-match']);
+            host.remove();
+        });
+
+        await it('a bare g is text, not next-match', () => {
+            const { el, host } = mount();
+            let count = 0;
+            el.addEventListener('next-match', () => (count += 1));
+            inner(el).dispatchEvent(new KeyboardEvent('keydown', { key: 'g', bubbles: true, cancelable: true }));
+            expect(count).toBe(0);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-search-entry> as an entry', async () => {
+        await it('keeps the value, placeholder and disabled behaviour it inherits', () => {
+            const { el, host } = mount({ value: 'gtk', placeholder: 'Search…', disabled: '' });
+            expect(el.value).toBe('gtk');
+            expect(inner(el).placeholder).toBe('Search…');
+            expect(inner(el).disabled).toBe(true);
+            host.remove();
+        });
+    });
+};

package/src/gtk-separator.spec.ts

@@ -0,0 +1,74 @@
+// DOM-level tests for <gtk-separator>: the orientation property is GtkOrientable's (shared
+// parser with <gtk-box>), the host carries the orientation as the CSS state the stylesheet
+// selects on, and the RENDERED box is a one-pixel rule, or a 12px gap for `.spacer`.
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { GtkSeparator } from './elements/gtk-separator.js';
+
+function mount(attrs: Record<string, string> = {}): { el: GtkSeparator; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const el = document.createElement('gtk-separator') as GtkSeparator;
+    for (const [name, value] of Object.entries(attrs)) el.setAttribute(name, value);
+    host.appendChild(el);
+    return { el, host };
+}
+
+export const GtkSeparatorTest = async () => {
+    await describe('<gtk-separator> orientation', async () => {
+        await it('is horizontal by default and says so to CSS and to assistive technology', () => {
+            const { el, host } = mount();
+            expect(el.orientation).toBe('horizontal');
+            expect(el.classList.contains('horizontal')).toBe(true);
+            expect(el.classList.contains('vertical')).toBe(false);
+            expect(el.getAttribute('role')).toBe('separator');
+            expect(el.getAttribute('aria-orientation')).toBe('horizontal');
+            host.remove();
+        });
+
+        await it('follows the attribute and the property, and an unknown value is the default', () => {
+            const { el, host } = mount({ orientation: 'vertical' });
+            expect(el.orientation).toBe('vertical');
+            expect(el.classList.contains('vertical')).toBe(true);
+            el.orientation = 'horizontal';
+            expect(el.getAttribute('orientation')).toBe('horizontal');
+            expect(el.classList.contains('horizontal')).toBe(true);
+            expect(el.classList.contains('vertical')).toBe(false);
+            el.setAttribute('orientation', 'diagonal');
+            expect(el.orientation).toBe('horizontal');
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-separator> geometry', async () => {
+        await it('a horizontal rule is 1px tall and takes the width it is given', () => {
+            const { el, host } = mount();
+            host.style.width = '200px';
+            const box = el.getBoundingClientRect();
+            expect(box.height).toBe(1);
+            expect(box.width).toBe(200);
+            host.remove();
+        });
+
+        await it('a vertical rule is 1px wide', () => {
+            const { el, host } = mount({ orientation: 'vertical' });
+            expect(el.getBoundingClientRect().width).toBe(1);
+            host.remove();
+        });
+
+        await it('.spacer draws nothing and reserves 12px along its axis', () => {
+            const { el, host } = mount();
+            el.classList.add('spacer');
+            host.style.width = '200px';
+            expect(getComputedStyle(el).backgroundImage).toBe('none');
+            expect(getComputedStyle(el).backgroundColor).toBe('rgba(0, 0, 0, 0)');
+            const vertical = mount({ orientation: 'vertical' });
+            vertical.el.classList.add('spacer');
+            const box = vertical.el.getBoundingClientRect();
+            expect(box.height).toBe(12);
+            expect(box.width).toBe(1);
+            host.remove();
+            vertical.host.remove();
+        });
+    });
+};

package/src/gtk-spin-button.spec.ts

@@ -0,0 +1,186 @@
+// DOM-level tests for <gtk-spin-button>. It is an entry with two arrows, so what matters
+// here is `Gtk.SpinButton`'s own half: the child ORDER C parents them in, `real_spin`'s
+// wrap branches, `update`'s two policies, `snap-to-ticks` and the arrows' sensitivity.
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { GtkSpinButton } from './elements/gtk-spin-button.js';
+
+function mount(attrs: Record<string, string> = {}): { el: GtkSpinButton; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const el = document.createElement('gtk-spin-button') as GtkSpinButton;
+    for (const [name, value] of Object.entries(attrs)) el.setAttribute(name, value);
+    host.appendChild(el);
+    return { el, host };
+}
+
+function record(el: HTMLElement, event: string): unknown[] {
+    const details: unknown[] = [];
+    el.addEventListener(event, (e) => details.push((e as CustomEvent).detail));
+    return details;
+}
+
+function arrows(el: GtkSpinButton): { up: HTMLButtonElement; down: HTMLButtonElement } {
+    return {
+        up: el.querySelector('.image-button.up') as HTMLButtonElement,
+        down: el.querySelector('.image-button.down') as HTMLButtonElement,
+    };
+}
+
+export const GtkSpinButtonTest = async () => {
+    await describe('<gtk-spin-button> structure', async () => {
+        await it('parents text, down, up horizontally — the order C builds them in', () => {
+            const { el, host } = mount();
+            const parts = [...el.children];
+            expect(parts.map((n) => n.className.split(' ')[0])).toStrictEqual([
+                'adw-spin-button-text',
+                'adw-button',
+                'adw-button',
+            ]);
+            expect((parts[2] as HTMLElement).classList.contains('up')).toBe(true);
+            expect(el.getAttribute('role')).toBe('spinbutton');
+            host.remove();
+        });
+
+        await it('a vertical spin button moves the up arrow to the front', () => {
+            const { el, host } = mount({ orientation: 'vertical' });
+            expect((el.children[0] as HTMLElement).classList.contains('up')).toBe(true);
+            expect((el.children[2] as HTMLElement).classList.contains('down')).toBe(true);
+            host.remove();
+        });
+
+        await it('the field shows the formatted value and one digit is the default', () => {
+            const { el, host } = mount({ adjustment: '{"lower":0,"upper":10,"stepIncrement":0.5}', value: '2.5' });
+            // `digits` is 0, so the field shows the value rounded to a whole number — which
+            // is exactly what `gtk_spin_button_format_for_value`'s `%0.*f` does.
+            expect(el.digits).toBe(0);
+            expect(el.text.value).toBe('3');
+            el.setAttribute('digits', '1');
+            expect(el.text.value).toBe('2.5');
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-spin-button> stepping', async () => {
+        await it('an arrow press steps by the adjustment step and notifies once', () => {
+            const { el, host } = mount({ adjustment: '{"lower":0,"upper":10,"stepIncrement":2}' });
+            const changed = record(el, 'value-changed');
+            arrows(el).up.click();
+            expect(el.value).toBe(2);
+            arrows(el).down.click();
+            expect(el.value).toBe(0);
+            expect(changed).toStrictEqual([{ value: 2 }, { value: 0 }]);
+            host.remove();
+        });
+
+        await it('without wrap an arrow goes insensitive at the bound, as C computes it', () => {
+            const { el, host } = mount({ adjustment: '{"lower":0,"upper":10,"stepIncrement":1}' });
+            const { up, down } = arrows(el);
+            // At the lower bound the DOWN arrow has nowhere to go and the UP arrow does.
+            expect(down.disabled).toBe(true);
+            expect(up.disabled).toBe(false);
+            el.value = 10;
+            expect(up.disabled).toBe(true);
+            expect(down.disabled).toBe(false);
+            host.remove();
+        });
+
+        await it('with wrap an arrow at the bound jumps to the other end and emits wrapped', () => {
+            const { el, host } = mount({ adjustment: '{"lower":0,"upper":10,"stepIncrement":1}', wrap: '' });
+            const wrapped = record(el, 'wrapped');
+            const { up, down } = arrows(el);
+            expect(up.disabled).toBe(false);
+            expect(down.disabled).toBe(false);
+            up.click();
+            expect(el.value).toBe(1);
+            expect(wrapped.length).toBe(0);
+            el.value = 10;
+            up.click();
+            // `gtk_spin_button_real_spin`'s wrap branch sets the OTHER BOUND, not "one step
+            // away from it": an arrow pressed at 10 in a range of 0…10 lands on 0.
+            expect(el.value).toBe(0);
+            down.click();
+            expect(el.value).toBe(10);
+            expect(wrapped.length).toBe(2);
+            host.remove();
+        });
+
+        await it('an arrow key steps and Page Up pages', () => {
+            const { el, host } = mount({ adjustment: '{"lower":0,"upper":100,"stepIncrement":1,"pageIncrement":10}' });
+            const press = (key: string) =>
+                el.text.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true }));
+            press('ArrowUp');
+            expect(el.value).toBe(1);
+            press('PageUp');
+            expect(el.value).toBe(11);
+            press('ArrowDown');
+            expect(el.value).toBe(10);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-spin-button> committing', async () => {
+        await it('always clamps a typed value that is out of range', () => {
+            const { el, host } = mount({ adjustment: '{"lower":0,"upper":10,"stepIncrement":1}' });
+            el.text.value = '99';
+            el.text.dispatchEvent(new Event('change'));
+            expect(el.value).toBe(10);
+            host.remove();
+        });
+
+        await it('if-valid leaves the committed value alone and re-formats the field', () => {
+            const { el, host } = mount({
+                adjustment: '{"lower":0,"upper":10,"stepIncrement":1,"value":5}',
+                'update-policy': 'if-valid',
+            });
+            el.text.value = '99';
+            el.text.dispatchEvent(new Event('change'));
+            expect(el.value).toBe(5);
+            expect(el.text.value).toBe('5');
+            host.remove();
+        });
+
+        await it('snap-to-ticks lands a typed value on the step grid', () => {
+            const { el, host } = mount({
+                adjustment: '{"lower":0,"upper":10,"stepIncrement":4}',
+                'snap-to-ticks': '',
+            });
+            el.text.value = '7';
+            el.text.dispatchEvent(new Event('change'));
+            expect(el.value).toBe(8);
+            host.remove();
+        });
+
+        await it('numeric refuses letters, a second point and a trailing sign', () => {
+            const { el, host } = mount({ numeric: '', digits: '2' });
+            // A refused character restores the FORMATTED value, so the field reads `0.00`
+            // at the two digits this story sets — not a bare `0`.
+            el.text.value = '1a';
+            el.text.dispatchEvent(new Event('input'));
+            expect(el.text.value).toBe('0.00');
+            el.text.value = '1.5';
+            el.text.dispatchEvent(new Event('input'));
+            expect(el.text.value).toBe('1.5');
+            el.text.value = '1.5.';
+            el.text.dispatchEvent(new Event('input'));
+            expect(el.text.value).toBe('0.00');
+            el.text.value = '-3';
+            el.text.dispatchEvent(new Event('input'));
+            expect(el.text.value).toBe('-3');
+            host.remove();
+        });
+
+        await it('Enter activates only when the text was not edited', () => {
+            const { el, host } = mount({ adjustment: '{"lower":0,"upper":10,"stepIncrement":1}' });
+            const activated = record(el, 'activate');
+            el.text.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, cancelable: true }));
+            expect(activated.length).toBe(1);
+            el.text.value = '3';
+            el.text.dispatchEvent(new Event('input'));
+            el.text.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, cancelable: true }));
+            expect(el.value).toBe(3);
+            expect(activated.length).toBe(1);
+            host.remove();
+        });
+    });
+};