@gjsify/adwaita-web 0.53.0 → 0.55.0

package/src/gtk-text.spec.ts

@@ -0,0 +1,163 @@
+// DOM-level tests for `<gtk-text>`: the four properties that reach a real mechanism
+// (`max-length` in code points, `placeholder-text`, `visibility` as the mask switch,
+// `propagate-text-width` as the input's own `size`) and the `.read-only` node class the C
+// toggles with `editable`.
+//
+// `Gtk.Text` has two BOOLEAN pspecs that default TRUE (`editable`, `visibility`), which is
+// why they are read from a value and not from presence: a bare `visibility` attribute would
+// say the same as leaving it off. Those are the rows below that would fail for an element
+// that used `hasAttribute`.
+
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { GtkText } from './elements/gtk-text.js';
+
+function mount(attrs: Record<string, string> = {}): GtkText {
+    const el = document.createElement('gtk-text') as GtkText;
+    for (const [name, value] of Object.entries(attrs)) el.setAttribute(name, value);
+    document.body.appendChild(el);
+    return el;
+}
+
+function unmountAll(): void {
+    for (const el of Array.from(document.querySelectorAll('gtk-text'))) el.remove();
+}
+
+/** What a keydown reaches the inner input with — the browser does not dispatch one for a test. */
+function pressEnter(input: HTMLInputElement): void {
+    input.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, cancelable: true }));
+}
+
+export const GtkTextTest = async () => {
+    await describe('<gtk-text> text', async () => {
+        await it('seeds the field from `text` and reports the live value back', () => {
+            const el = mount({ text: 'Ada Lovelace' });
+            expect(el.text).toBe('Ada Lovelace');
+            expect(el.input.value).toBe('Ada Lovelace');
+            unmountAll();
+        });
+
+        await it('counts its length in CODE POINTS, as the buffer does', () => {
+            const el = mount({ text: '🔒é' });
+            expect(el.textLength).toBe(2);
+            unmountAll();
+        });
+
+        await it('fires `activate` on Enter, the signal GTK binds Return to', () => {
+            const el = mount({ text: 'notes' });
+            const seen: unknown[] = [];
+            el.addEventListener('activate', (event) => seen.push((event as CustomEvent).detail));
+            pressEnter(el.input);
+            expect(seen).toStrictEqual([{ text: 'notes' }]);
+            unmountAll();
+        });
+    });
+
+    await describe('<gtk-text> max length', async () => {
+        await it('clamps the seeded text on code points, where `maxlength` would not', () => {
+            const el = mount({ text: '🔒éééé', 'max-length': '3' });
+            expect(el.text).toBe('🔒éé');
+            expect(el.textLength).toBe(3);
+            unmountAll();
+        });
+
+        await it('clamps what is typed, not only what is assigned', () => {
+            const el = mount({ 'max-length': '4' });
+            el.input.value = 'abcdefgh';
+            el.input.dispatchEvent(new Event('input', { bubbles: true }));
+            expect(el.input.value).toBe('abcd');
+            unmountAll();
+        });
+
+        await it('0 means unlimited', () => {
+            const el = mount({ text: 'a long value' });
+            el.maxLength = 0;
+            expect(el.maxLength).toBe(0);
+            el.text = 'another long value';
+            expect(el.text).toBe('another long value');
+            unmountAll();
+        });
+    });
+
+    await describe('<gtk-text> visibility', async () => {
+        await it('defaults TRUE, and the pspec default is what an absent attribute means', () => {
+            const el = mount();
+            expect(el.visibility).toBe(true);
+            expect(el.input.type).toBe('text');
+            unmountAll();
+        });
+
+        await it('`visibility="false"` masks the field; a bare attribute does not', () => {
+            const masked = mount({ visibility: 'false' });
+            expect(masked.visibility).toBe(false);
+            expect(masked.input.type).toBe('password');
+            const bare = mount({ visibility: '' });
+            expect(bare.visibility).toBe(true);
+            expect(bare.input.type).toBe('text');
+            unmountAll();
+        });
+
+        await it('follows the property and leaves the default unwritten', () => {
+            const el = mount();
+            el.visibility = false;
+            expect(el.getAttribute('visibility')).toBe('false');
+            expect(el.input.type).toBe('password');
+            el.visibility = true;
+            expect(el.hasAttribute('visibility')).toBe(false);
+            expect(el.input.type).toBe('text');
+            unmountAll();
+        });
+    });
+
+    await describe('<gtk-text> editable', async () => {
+        await it("wears libadwaita's `.read-only` node class when it cannot be changed", () => {
+            const el = mount();
+            expect(el.editable).toBe(true);
+            expect(el.classList.contains('read-only')).toBe(false);
+            el.editable = false;
+            expect(el.classList.contains('read-only')).toBe(true);
+            expect(el.input.readOnly).toBe(true);
+            unmountAll();
+        });
+
+        await it('takes `editable="false"` as the value the default-TRUE pspec needs', () => {
+            const el = mount({ editable: 'false' });
+            expect(el.editable).toBe(false);
+            expect(el.input.readOnly).toBe(true);
+            unmountAll();
+        });
+    });
+
+    await describe('<gtk-text> propagate text width', async () => {
+        await it('sizes the field to its text while set, and stops on request', () => {
+            const el = mount({ text: 'abc' });
+            el.propagateTextWidth = true;
+            expect(el.classList.contains('propagate-text-width')).toBe(true);
+            expect(el.input.size).toBe(3);
+            el.text = 'abcdefgh';
+            expect(el.input.size).toBe(8);
+            el.propagateTextWidth = false;
+            expect(el.classList.contains('propagate-text-width')).toBe(false);
+            unmountAll();
+        });
+
+        await it('stays inside its container', () => {
+            const el = mount({ text: 'abc', 'propagate-text-width': '' });
+            expect(el.getBoundingClientRect().width).toBeLessThanOrEqual(document.body.clientWidth);
+            unmountAll();
+        });
+    });
+
+    await describe('<gtk-text> look', async () => {
+        await it('paints the view colours libadwaita gives a `text` node', () => {
+            const el = mount();
+            const style = getComputedStyle(el.input);
+            // `caret-color: currentColor` (_entries.scss:11) resolves against the element's
+            // own colour, and the tokens move with the OS theme — so the row compares two
+            // computed values instead of naming either of them.
+            expect(style.caretColor).toBe(getComputedStyle(el).color);
+            expect(style.backgroundColor).not.toBe('rgba(0, 0, 0, 0)');
+            unmountAll();
+        });
+    });
+};

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

@@ -0,0 +1,186 @@
+// DOM-level tests for <gtk-toggle-button>. It IS a <gtk-button>, so what matters here is
+// the one thing it adds: `active`. The state is the attribute; the inner button wears
+// libadwaita's `:checked` as `.checked` and `aria-pressed`; `toggled` and `notify::active`
+// fire on every real change and on none that did not happen.
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { GtkToggleButton } from './elements/gtk-toggle-button.js';
+
+function mount(attrs: Record<string, string> = {}): { el: GtkToggleButton; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const el = document.createElement('gtk-toggle-button') as GtkToggleButton;
+    for (const [name, value] of Object.entries(attrs)) el.setAttribute(name, value);
+    host.appendChild(el);
+    return { el, host };
+}
+
+/** Collect 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;
+}
+
+export const GtkToggleButtonTest = async () => {
+    await describe('<gtk-toggle-button> state', async () => {
+        await it('starts released, and renders as a gtk-button would', () => {
+            const { el, host } = mount({ label: 'Mute' });
+            expect(el.active).toBe(false);
+            expect(el.button.classList.contains('adw-button')).toBe(true);
+            expect(el.button.classList.contains('checked')).toBe(false);
+            expect(el.button.getAttribute('aria-pressed')).toBe('false');
+            expect(el.button.textContent).toBe('Mute');
+            host.remove();
+        });
+
+        await it('adopts a declarative active attribute without emitting', () => {
+            const host = document.createElement('div');
+            document.body.appendChild(host);
+            const el = document.createElement('gtk-toggle-button') as GtkToggleButton;
+            el.setAttribute('active', '');
+            const events = record(el, 'toggled');
+            host.appendChild(el);
+            expect(el.active).toBe(true);
+            expect(el.button.classList.contains('checked')).toBe(true);
+            expect(el.button.getAttribute('aria-pressed')).toBe('true');
+            expect(events.length).toBe(0);
+            host.remove();
+        });
+
+        await it('a click flips it, and notifies once per change', () => {
+            const { el, host } = mount({ label: 'Mute' });
+            const toggled = record(el, 'toggled');
+            const notified = record(el, 'notify::active');
+            el.button.click();
+            expect(el.active).toBe(true);
+            expect(el.button.classList.contains('checked')).toBe(true);
+            el.button.click();
+            expect(el.active).toBe(false);
+            expect(toggled.length).toBe(2);
+            expect(notified).toStrictEqual([{ active: true }, { active: false }]);
+            host.remove();
+        });
+
+        await it('a programmatic set notifies, and re-setting the same value does not', () => {
+            const { el, host } = mount();
+            const notified = record(el, 'notify::active');
+            el.active = true;
+            el.active = true;
+            expect(notified).toStrictEqual([{ active: true }]);
+            host.remove();
+        });
+
+        await it('a disabled button does not toggle on a click, but the property still applies', () => {
+            const { el, host } = mount({ disabled: '' });
+            el.button.click();
+            expect(el.active).toBe(false);
+            el.active = true;
+            expect(el.button.classList.contains('checked')).toBe(true);
+            host.remove();
+        });
+
+        await it('keeps the checked class through a re-render of the label and the styles', () => {
+            const { el, host } = mount({ label: 'Mute', active: '' });
+            el.setAttribute('label', 'Unmute');
+            el.setAttribute('flat', '');
+            expect(el.button.textContent).toBe('Unmute');
+            expect(el.button.classList.contains('flat')).toBe(true);
+            expect(el.button.classList.contains('checked')).toBe(true);
+            host.remove();
+        });
+
+        await it('an ungrouped button still toggles off when clicked', () => {
+            const { el, host } = mount({ label: 'Mute' });
+            el.button.click();
+            expect(el.active).toBe(true);
+            el.button.click();
+            expect(el.active).toBe(false);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-toggle-button> look', async () => {
+        await it('a checked button paints darker than a released one', () => {
+            const { el, host } = mount({ label: 'Mute' });
+            const released = getComputedStyle(el.button).backgroundColor;
+            el.active = true;
+            const checked = getComputedStyle(el.button).backgroundColor;
+            expect(checked === released).toBe(false);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-toggle-button> group', async () => {
+        await it('joining a group links the two ways, and leaves the attribute naming it', () => {
+            const a = mount({ id: 'group-a', label: 'A' });
+            const b = mount({ id: 'group-b', label: 'B' });
+            b.el.group = a.el;
+            expect(b.el.getAttribute('group')).toBe('group-a');
+            // `gtk_toggle_button_set_group` inserts SELF before the target, so B is the one
+            // that gains `group_next` — which is also the one a click can no longer release.
+            b.el.button.click();
+            expect(b.el.active).toBe(true);
+            b.el.button.click();
+            expect(b.el.active).toBe(true);
+            a.host.remove();
+            b.host.remove();
+        });
+
+        await it('activating a member releases the others, whichever order they were linked in', () => {
+            const a = mount({ id: 'chain-a', label: 'A' });
+            const b = mount({ id: 'chain-b', label: 'B' });
+            const c = mount({ id: 'chain-c', label: 'C' });
+            b.el.group = a.el;
+            c.el.group = a.el;
+            const toggled = record(c.el, 'toggled');
+            c.el.active = true;
+            expect(a.el.active).toBe(false);
+            expect(b.el.active).toBe(false);
+            expect(c.el.active).toBe(true);
+            a.el.active = true;
+            expect(c.el.active).toBe(false);
+            expect(b.el.active).toBe(false);
+            expect(a.el.active).toBe(true);
+            expect(toggled.length).toBe(2);
+            a.host.remove();
+            b.host.remove();
+            c.host.remove();
+        });
+
+        await it('the attribute door names the partner by id, and an unknown name changes nothing', () => {
+            const a = mount({ id: 'attr-a', label: 'A' });
+            const b = mount({ id: 'attr-b', label: 'B' });
+            b.el.setAttribute('group', 'attr-a');
+            a.el.active = true;
+            b.el.active = true;
+            expect(a.el.active).toBe(false);
+            expect(b.el.active).toBe(true);
+            b.el.setAttribute('group', 'nowhere');
+            expect(b.el.getAttribute('group')).toBe('nowhere');
+            a.el.active = true;
+            expect(b.el.active).toBe(true);
+            a.host.remove();
+            b.host.remove();
+        });
+
+        await it('leaving the group releases the links, and the same group twice notifies once', () => {
+            const a = mount({ id: 'once-a', label: 'A' });
+            const b = mount({ id: 'once-b', label: 'B' });
+            const notified = record(b.el, 'notify::group');
+            b.el.group = a.el;
+            b.el.group = a.el;
+            expect(notified.length).toBe(1);
+            b.el.group = null;
+            expect(notified.length).toBe(2);
+            expect(b.el.hasAttribute('group')).toBe(false);
+            // Unlinked, B is clickable off again — the guard is the link, not the element.
+            b.el.button.click();
+            expect(b.el.active).toBe(true);
+            b.el.button.click();
+            expect(b.el.active).toBe(false);
+            a.host.remove();
+            b.host.remove();
+        });
+    });
+};

package/src/gtk-tree-expander.spec.ts

@@ -0,0 +1,201 @@
+// DOM-level tests for <gtk-tree-expander>: the nodes it puts in front of its child, the
+// arrow that toggles, the shortcuts, and the ARIA a tree row owes a screen reader. The
+// arithmetic itself is `tree-expander.spec.ts` in @gjsify/adwaita-core; what is asserted
+// here is that the element draws what the arithmetic says.
+import { describe, expect, it } from '@gjsify/unit';
+
+import { TREE_EXPANDER_LAYOUT_VECTORS, TREE_EXPANDER_SHORTCUT_VECTORS } from '@gjsify/adwaita-core/conformance';
+
+import type { GtkTreeExpander } from './elements/gtk-tree-expander.js';
+
+function mount(attrs: Record<string, string> = {}): { el: GtkTreeExpander; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const el = document.createElement('gtk-tree-expander') as GtkTreeExpander;
+    for (const [name, value] of Object.entries(attrs)) el.setAttribute(name, value);
+    const child = document.createElement('gtk-label');
+    child.setAttribute('label', 'Row');
+    el.appendChild(child);
+    host.appendChild(el);
+    return { el, host };
+}
+
+const indents = (el: GtkTreeExpander): number => el.querySelectorAll('.adw-tree-expander-indent').length;
+const icon = (el: GtkTreeExpander): HTMLElement | null => el.querySelector('.adw-tree-expander-icon');
+
+export const GtkTreeExpanderTest = async () => {
+    await describe('<gtk-tree-expander> drives the layout vectors as real nodes', async () => {
+        // The ONE row with no counterpart here is `row: null`: upstream an expander exists
+        // before a `Gtk.TreeListRow` is assigned to it, and on this port the row IS the
+        // three attributes, so an expander with none of them is a root leaf rather than a
+        // rowless widget. The element header records the same divergence.
+        for (const vector of TREE_EXPANDER_LAYOUT_VECTORS.filter((candidate) => candidate.row !== null)) {
+            await it(vector.rule, () => {
+                const row = vector.row!;
+                const attrs: Record<string, string> = { depth: String(row.depth) };
+                if (row.expandable) attrs.expandable = '';
+                if (row.expanded) attrs.expanded = '';
+                if (vector.options.hideExpander === true) attrs['hide-expander'] = '';
+                if (vector.options.indentForDepth === false) attrs['indent-for-depth'] = 'false';
+                if (vector.options.indentForIcon === false) attrs['indent-for-icon'] = 'false';
+                const { el, host } = mount(attrs);
+
+                expect(indents(el)).toBe(vector.indents);
+                expect(
+                    icon(el) === null ? 'none' : el.getAttribute('aria-expanded') === 'true' ? 'expanded' : 'collapsed',
+                ).toBe(vector.expander);
+                expect(el.getAttribute('aria-level')).toBe(String(vector.level));
+                host.remove();
+            });
+        }
+    });
+
+    await describe('<gtk-tree-expander> drives the shortcut vectors as real key presses', async () => {
+        for (const vector of TREE_EXPANDER_SHORTCUT_VECTORS) {
+            await it(vector.rule, () => {
+                // Every row is driven from BOTH starting states, so "the key did nothing"
+                // and "the key asked for the state it was already in" cannot be confused.
+                for (const before of [false, true]) {
+                    const attrs: Record<string, string> = { expandable: '' };
+                    if (before) attrs.expanded = '';
+                    // The locale half of the arrow rule is the COMPUTED direction, which
+                    // is what the element reads and what `dir` is the markup for.
+                    if (vector.state.rtl === true) attrs.dir = 'rtl';
+                    const { el, host } = mount(attrs);
+                    el.dispatchEvent(
+                        new KeyboardEvent('keydown', {
+                            key: vector.key,
+                            ctrlKey: vector.state.ctrlKey === true,
+                            shiftKey: vector.state.shiftKey === true,
+                            bubbles: true,
+                        }),
+                    );
+                    const expected =
+                        vector.action === 'expand'
+                            ? true
+                            : vector.action === 'collapse'
+                              ? false
+                              : vector.action === 'toggle'
+                                ? !before
+                                : before;
+                    expect(el.expanded).toBe(expected);
+                    host.remove();
+                }
+            });
+        }
+    });
+
+    await describe('<gtk-tree-expander> nodes', async () => {
+        await it('draws one indent per level and an arrow for an expandable row', () => {
+            const { el, host } = mount({ depth: '2', expandable: '' });
+            expect(indents(el)).toBe(2);
+            expect(icon(el)).not.toBe(null);
+            expect(el.getAttribute('aria-expanded')).toBe('false');
+            expect(el.getAttribute('aria-level')).toBe('3');
+            host.remove();
+        });
+
+        await it('gives a LEAF one more indent instead of the arrow', () => {
+            const { el, host } = mount({ depth: '1' });
+            expect(indents(el)).toBe(2);
+            expect(icon(el)).toBe(null);
+            expect(el.hasAttribute('aria-expanded')).toBe(false);
+            host.remove();
+        });
+
+        await it('keeps the ornaments IN FRONT of the child, as insert_before does', () => {
+            const { el, host } = mount({ depth: '1', expandable: '' });
+            const names = [...el.children].map((child) => child.tagName.toLowerCase());
+            expect(names).toStrictEqual(['span', 'gtk-image', 'gtk-label']);
+            host.remove();
+        });
+
+        await it('hides the expander on request and indents like a leaf instead', () => {
+            const { el, host } = mount({ depth: '1', expandable: '', 'hide-expander': '' });
+            expect(icon(el)).toBe(null);
+            expect(indents(el)).toBe(2);
+            host.remove();
+        });
+
+        await it('stops indenting with indent-for-depth="false" but keeps the arrow', () => {
+            const { el, host } = mount({ depth: '3', expandable: '', 'indent-for-depth': 'false' });
+            expect(indents(el)).toBe(0);
+            expect(icon(el)).not.toBe(null);
+            host.remove();
+        });
+
+        await it('rebuilds when the row changes under it', () => {
+            const { el, host } = mount({ depth: '0', expandable: '' });
+            expect(indents(el)).toBe(0);
+            el.depth = 2;
+            expect(indents(el)).toBe(2);
+            el.expandable = false;
+            expect(icon(el)).toBe(null);
+            expect(indents(el)).toBe(3);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-tree-expander> expansion', async () => {
+        await it('toggles on the ARROW and notifies on every change', () => {
+            const { el, host } = mount({ expandable: '' });
+            const seen: boolean[] = [];
+            el.addEventListener('notify::expanded', (event) => {
+                seen.push((event as CustomEvent).detail.expanded as boolean);
+            });
+            icon(el)!.click();
+            expect(el.expanded).toBe(true);
+            expect(icon(el)!.classList.contains('expanded')).toBe(true);
+            el.expanded = false;
+            expect(seen).toStrictEqual([true, false]);
+            host.remove();
+        });
+
+        await it('does not let the arrow click reach the row around it', () => {
+            // Upstream the gesture sits on the expander icon, so the list view's own row
+            // click never sees it.
+            const { el, host } = mount({ expandable: '' });
+            let reachedHost = false;
+            host.addEventListener('click', () => (reachedHost = true));
+            icon(el)!.click();
+            expect(reachedHost).toBe(false);
+            host.remove();
+        });
+
+        await it('expands on + and collapses on -', () => {
+            const { el, host } = mount({ expandable: '' });
+            el.dispatchEvent(new KeyboardEvent('keydown', { key: '+', bubbles: true }));
+            expect(el.expanded).toBe(true);
+            el.dispatchEvent(new KeyboardEvent('keydown', { key: '-', bubbles: true }));
+            expect(el.expanded).toBe(false);
+            host.remove();
+        });
+
+        await it('toggles on Ctrl+Space and ignores a bare Space', () => {
+            const { el, host } = mount({ expandable: '' });
+            el.dispatchEvent(new KeyboardEvent('keydown', { key: ' ', bubbles: true }));
+            expect(el.expanded).toBe(false);
+            el.dispatchEvent(new KeyboardEvent('keydown', { key: ' ', ctrlKey: true, bubbles: true }));
+            expect(el.expanded).toBe(true);
+            host.remove();
+        });
+
+        await it('needs Shift for the arrow keys', () => {
+            const { el, host } = mount({ expandable: '' });
+            el.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowRight', bubbles: true }));
+            expect(el.expanded).toBe(false);
+            el.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowRight', shiftKey: true, bubbles: true }));
+            expect(el.expanded).toBe(true);
+            el.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowLeft', shiftKey: true, bubbles: true }));
+            expect(el.expanded).toBe(false);
+            host.remove();
+        });
+
+        await it('is a focusable button, which is what carries the shortcuts', () => {
+            const { el, host } = mount({ expandable: '' });
+            expect(el.getAttribute('role')).toBe('button');
+            expect(el.tabIndex).toBe(0);
+            host.remove();
+        });
+    });
+};