@gjsify/adwaita-web 0.53.0 → 0.55.0

package/src/gtk-picture.spec.ts

@@ -0,0 +1,172 @@
+// DOM-level tests for <gtk-picture>. The four scalar properties all have a GIR default
+// that is TRUE, so most of what matters here is the ABSENCE cases: an attribute that is not
+// written has to read back as the C's default, not as `false`. The other half is
+// `keep-aspect-ratio`, which is a deprecated MAPPING rather than a stored boolean, and whose
+// getter is the inverse test over `content-fit` — so `cover` and `scale-down` both read it
+// back `true` and only `fill` reads `false`.
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { GtkPicture } from './elements/gtk-picture.js';
+
+function mount(attrs: Record<string, string> = {}): { el: GtkPicture; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const el = document.createElement('gtk-picture') as GtkPicture;
+    for (const [name, value] of Object.entries(attrs)) el.setAttribute(name, value);
+    host.appendChild(el);
+    return { el, host };
+}
+
+export const GtkPictureTest = async () => {
+    await describe('<gtk-picture> content-fit', async () => {
+        await it('defaults to CONTAIN, which is what the C installs in init', () => {
+            // gtkpicture.c:555 — `self->content_fit = GTK_CONTENT_FIT_CONTAIN`.
+            const { el, host } = mount();
+            expect(el.contentFit).toBe('contain');
+            host.remove();
+        });
+
+        await it('an unrecognised nick stays CONTAIN rather than becoming FILL', () => {
+            // FILL is the one value that would silently distort every picture a page writes,
+            // so the default is the safe arm — not a coercion to the first enum member.
+            const { el, host } = mount({ 'content-fit': 'squeeze' });
+            expect(el.contentFit).toBe('contain');
+            host.remove();
+        });
+
+        await it('holds all four GtkContentFit members, scale-down included', () => {
+            // gtkpicture.c:162-167 — SCALE_DOWN is the member `GtkContentFit` added and CSS
+            // already had, so this mapping is exact rather than approximate.
+            for (const mode of ['fill', 'contain', 'cover', 'scale-down'] as const) {
+                const { el, host } = mount({ 'content-fit': mode });
+                expect(el.contentFit).toBe(mode);
+                host.remove();
+            }
+        });
+
+        await it('reaches the replaced child as object-fit, which is not inherited', () => {
+            const { el, host } = mount({ 'content-fit': 'cover' });
+            expect(el.style.getPropertyValue('--gtk-picture-content-fit')).toBe('cover');
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-picture> keep-aspect-ratio', async () => {
+        await it('the setter MAPS onto content-fit rather than storing a boolean', async () => {
+            // gtkpicture.c:1017-1021 — TRUE sets CONTAIN, FALSE sets FILL.
+            const { el, host } = mount();
+            el.keepAspectRatio = true;
+            expect(el.contentFit).toBe('contain');
+            el.keepAspectRatio = false;
+            expect(el.contentFit).toBe('fill');
+            host.remove();
+        });
+
+        await it('the getter is the INVERSE test, so cover and scale-down read TRUE', () => {
+            // gtkpicture.c:1040 — `return self->content_fit != GTK_CONTENT_FIT_FILL`. Both
+            // preserve the ratio, so answering FALSE for either would be a lie.
+            for (const mode of ['contain', 'cover', 'scale-down'] as const) {
+                const { el, host } = mount({ 'content-fit': mode });
+                expect(el.keepAspectRatio).toBe(true);
+                host.remove();
+            }
+            const fill = mount({ 'content-fit': 'fill' });
+            expect(fill.el.keepAspectRatio).toBe(false);
+            fill.host.remove();
+        });
+
+        await it('notifies the deprecated property only when a FILL arm is involved', () => {
+            // gtkpicture.c:1114-1115 — `notify_keep_aspect_ratio` is computed as "the new
+            // mode or the old one is FILL", so a write between two non-FILL modes leaves the
+            // deprecated property's VALUE unchanged and must stay silent.
+            const { el, host } = mount({ 'content-fit': 'contain' });
+            const events: unknown[] = [];
+            el.addEventListener('notify::keep-aspect-ratio', (e) => events.push((e as CustomEvent).detail));
+            el.contentFit = 'cover';
+            expect(events.length).toBe(0);
+            el.contentFit = 'fill';
+            expect(events).toStrictEqual([{ 'keep-aspect-ratio': false }]);
+            el.contentFit = 'contain';
+            expect(events).toStrictEqual([{ 'keep-aspect-ratio': false }, { 'keep-aspect-ratio': true }]);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-picture> the two TRUE-defaulted booleans', async () => {
+        await it('can-shrink and isolate-contents read TRUE when the attribute is ABSENT', () => {
+            // gtkpicture.c:554-555 — both are installed TRUE in `init`, before any attribute
+            // is read. An absent attribute therefore has to mean TRUE, or every picture on a
+            // declarative page would be un-shrinkable and non-isolated.
+            const { el, host } = mount();
+            expect(el.canShrink).toBe(true);
+            expect(el.isolateContents).toBe(true);
+            host.remove();
+        });
+
+        await it('presence alone means TRUE; only the string "false" is FALSE', () => {
+            const { el, host } = mount({ 'can-shrink': '', 'isolate-contents': '' });
+            expect(el.canShrink).toBe(true);
+            expect(el.isolateContents).toBe(true);
+            host.remove();
+        });
+
+        await it('setting FALSE writes the attribute and TRUE REMOVES it', () => {
+            // The property's own boolean needs three states, not two: absent is TRUE.
+            const { el, host } = mount();
+            el.canShrink = false;
+            expect(el.getAttribute('can-shrink')).toBe('false');
+            el.canShrink = true;
+            expect(el.hasAttribute('can-shrink')).toBe(false);
+            host.remove();
+        });
+
+        await it('a programmatic set notifies once per real change', () => {
+            const { el, host } = mount();
+            const events: unknown[] = [];
+            el.addEventListener('notify::can-shrink', (e) => events.push((e as CustomEvent).detail));
+            el.canShrink = false;
+            el.canShrink = false;
+            el.canShrink = true;
+            expect(events).toStrictEqual([{ 'can-shrink': false }, { 'can-shrink': true }]);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-picture> accessibility and isolation', async () => {
+        await it('carries the IMG role and the alternative text as its accessible name', () => {
+            // gtkpicture.c:553 — `GTK_ACCESSIBLE_ROLE_IMG`, set for every picture whether or
+            // not it has a name; :474-483 — `alternative-text` is that name.
+            const { el, host } = mount({ 'alternative-text': 'A tangerine' });
+            expect(el.getAttribute('role')).toBe('img');
+            expect(el.getAttribute('aria-label')).toBe('A tangerine');
+            host.remove();
+        });
+
+        await it('an empty alternative text REMOVES the name rather than emptying it', () => {
+            const { el, host } = mount({ 'alternative-text': 'A tangerine' });
+            el.alternativeText = '';
+            expect(el.hasAttribute('aria-label')).toBe(false);
+            host.remove();
+        });
+
+        await it('establishes a stacking context without becoming a containing block', () => {
+            // `gtk_snapshot_push_isolation` (gtkpicture.c:148-149) stops the paintable's alpha
+            // compositing against what is behind it. `contain: paint` would also isolate and
+            // would ADDITIONALLY make the element a containing block for fixed and absolutely
+            // positioned descendants, which the C's isolation does not do.
+            const { el, host } = mount();
+            const style = getComputedStyle(el);
+            expect(style.isolation).toBe('isolate');
+            expect(style.contain).not.toContain('paint');
+            host.remove();
+        });
+
+        await it('clips its overflow, which is what makes cover clip rather than spill', () => {
+            // gtkpicture.c:557 — `gtk_widget_set_overflow (widget, GTK_OVERFLOW_HIDDEN)` in
+            // `init`, not a style class an application opts into.
+            const { el, host } = mount();
+            expect(getComputedStyle(el).overflow).toBe('hidden');
+            host.remove();
+        });
+    });
+};

package/src/gtk-popover-bin.spec.ts

@@ -0,0 +1,229 @@
+// `<gtk-popover-bin>` — one child, and a popover to present from it. Every behaviour here is
+// one of the four gtkpopoverbin.c has, and each of them is a rule about WHEN the popover
+// appears or what it leaves behind:
+//
+//   · `menu-model` and `popover` are ONE slot (each setter clears the other);
+//   · `handle-input` claims a CONTEXT MENU and a LONG PRESS, and denies a plain click so it
+//     reaches the child;
+//   · the child wears `.has-open-popup` while the popover is mapped;
+//   · `menu.popup` is an ACTION, so the element exposes it as an event too.
+
+import { describe, expect, it } from '@gjsify/unit';
+import type { AdwMenuInput } from '@gjsify/adwaita-core';
+
+interface PopoverBinElement extends HTMLElement {
+    menuModel: AdwMenuInput;
+    // `popoverElement`, not `popover`: `HTMLElement` already declares a `popover` STRING
+    // attribute for the DOM Popover API, and an interface cannot narrow that to a widget.
+    popoverElement: HTMLElement | null;
+    handleInput: boolean;
+    actions: Record<string, { enabled?: boolean; state?: string }> | null;
+    childElement: HTMLElement | null;
+    popup(): void;
+    popdown(): void;
+}
+
+const MENU = [{ label: 'Cut' }, { label: 'Copy' }, { label: 'Paste' }];
+
+function mount(json?: string): { el: PopoverBinElement; child: HTMLElement } {
+    const el = document.createElement('gtk-popover-bin') as PopoverBinElement;
+    const child = document.createElement('gtk-button');
+    child.setAttribute('label', 'row');
+    el.appendChild(child);
+    if (json !== undefined) el.setAttribute('menu-model', json);
+    document.body.appendChild(el);
+    return { el, child };
+}
+
+const popoverOf = (el: HTMLElement): HTMLElement | null => el.querySelector('gtk-popover-menu');
+
+function unmountAll(): void {
+    for (const el of Array.from(document.querySelectorAll('gtk-popover-bin'))) el.remove();
+}
+
+export const GtkPopoverBinTest = async () => {
+    await describe('<gtk-popover-bin> the model builds the popover', async () => {
+        await it('a menu-model creates the popover, pinned to the bottom', () => {
+            const { el } = mount(JSON.stringify(MENU));
+            const popover = popoverOf(el);
+            expect(popover).not.toBeNull();
+            // `gtk_popover_set_position (popover, GTK_POS_BOTTOM)` in the same function
+            // (gtkpopoverbin.c:493).
+            expect(popover?.getAttribute('position')).toBe('bottom');
+            expect([...el.querySelectorAll('.adw-popover-menu-item-label')].map((n) => n.textContent)).toStrictEqual([
+                'Cut',
+                'Copy',
+                'Paste',
+            ]);
+            unmountAll();
+        });
+
+        await it('an empty model leaves NO popover, as set_menu_model(NULL) does', () => {
+            const { el } = mount();
+            expect(popoverOf(el)).toBeNull();
+            unmountAll();
+        });
+
+        await it('setting the model REPLACES the popover', () => {
+            const { el } = mount(JSON.stringify(MENU));
+            const before = popoverOf(el);
+            el.menuModel = [{ label: 'Only' }];
+            expect(popoverOf(el)).not.toBe(before);
+            expect(before?.isConnected).toBe(false);
+            unmountAll();
+        });
+
+        await it('setting a popover DROPS the model — one slot, two directions', () => {
+            const { el } = mount(JSON.stringify(MENU));
+            // `set_popover` does `g_clear_object (&self->menu_model)`
+            // (gtkpopoverbin.c:548) — the two properties are one field, and this is the half
+            // that is easy to get wrong by keeping them apart.
+            const replacement = document.createElement('gtk-popover') as unknown as HTMLElement;
+            el.popoverElement = replacement;
+            expect(el.menuModel).toStrictEqual([]);
+            expect(el.popoverElement).toBe(replacement);
+            // The old popover is unparented rather than left behind as a second surface:
+            // `gtk_popover_bin_set_popover` unparents the one it displaces.
+            expect(popoverOf(el)).toBeNull();
+            unmountAll();
+        });
+
+        await it('notifies both properties when the model changes', () => {
+            const { el } = mount();
+            const seen: unknown[] = [];
+            el.addEventListener('notify::menu-model', (event) => seen.push((event as CustomEvent).detail));
+            el.menuModel = MENU;
+            // GTK notifies `:popover` AND `:menu-model` from BOTH setters
+            // (gtkpopoverbin.c:502, :586-587), so one event carrying both is the faithful
+            // reading rather than two that can disagree.
+            expect(seen.length).toBe(1);
+            expect(Object.keys(seen[0] as object).sort()).toStrictEqual(['menuModel', 'popover']);
+            unmountAll();
+        });
+    });
+
+    await describe('<gtk-popover-bin> the child wears .has-open-popup', async () => {
+        await it('while the popover is open, and not while it is closed', () => {
+            const { el, child } = mount(JSON.stringify(MENU));
+            const popover = popoverOf(el) as HTMLElement & { open: boolean };
+            // `on_popover_map` / `on_popover_unmap` (gtkpopoverbin.c:117-126) — the class is
+            // how libadwaita says WHICH row generated the popup (`_lists.scss:57`).
+            expect(child.classList.contains('has-open-popup')).toBe(false);
+            popover.open = true;
+            expect(child.classList.contains('has-open-popup')).toBe(true);
+            popover.open = false;
+            expect(child.classList.contains('has-open-popup')).toBe(false);
+            unmountAll();
+        });
+
+        await it('the class is on the CHILD, never on the bin', () => {
+            const { el, child } = mount(JSON.stringify(MENU));
+            (popoverOf(el) as HTMLElement & { open: boolean }).open = true;
+            expect(el.classList.contains('has-open-popup')).toBe(false);
+            expect(child.classList.contains('has-open-popup')).toBe(true);
+            unmountAll();
+        });
+
+        await it('`childElement` is the child, not the popover', () => {
+            const { el, child } = mount(JSON.stringify(MENU));
+            // The popover is also an element child of the bin, so a `firstElementChild`
+            // that did not skip it would paint `.has-open-popup` on the popup.
+            expect(el.childElement).toBe(child);
+            unmountAll();
+        });
+    });
+
+    await describe('<gtk-popover-bin> handle-input', async () => {
+        await it('defaults to FALSE, so a right click does nothing', () => {
+            const { el } = mount(JSON.stringify(MENU));
+            // `g_param_spec_boolean ("handle-input", NULL, NULL, FALSE, …)`
+            // (gtkpopoverbin.c:370-374).
+            expect(el.handleInput).toBe(false);
+            el.dispatchEvent(new MouseEvent('contextmenu', { bubbles: true, cancelable: true }));
+            expect((popoverOf(el) as HTMLElement & { open: boolean }).open).toBe(false);
+            unmountAll();
+        });
+
+        await it('with it on, a context menu opens the popover and is consumed', () => {
+            const { el } = mount(JSON.stringify(MENU));
+            el.handleInput = true;
+            const event = new MouseEvent('contextmenu', { bubbles: true, cancelable: true });
+            el.dispatchEvent(event);
+            // `pressed_cb` only claims when `gdk_event_triggers_context_menu`, and then
+            // CLAIMS + resets the controller (gtkpopoverbin.c:165-175) — so the browser's
+            // own context menu must not also appear.
+            expect(event.defaultPrevented).toBe(true);
+            expect((popoverOf(el) as HTMLElement & { open: boolean }).open).toBe(true);
+            unmountAll();
+        });
+
+        await it('a plain click still reaches the child', () => {
+            const { el } = mount(JSON.stringify(MENU));
+            el.handleInput = true;
+            const event = new MouseEvent('click', { bubbles: true, cancelable: true });
+            el.dispatchEvent(event);
+            // The gesture DENIES any sequence it does not claim (gtkpopoverbin.c:185-186),
+            // which in the DOM is doing nothing at all.
+            expect(event.defaultPrevented).toBe(false);
+            expect((popoverOf(el) as HTMLElement & { open: boolean }).open).toBe(false);
+            unmountAll();
+        });
+
+        await it('a mouse long press does NOT open it — GTK’s is touch-only', async () => {
+            const { el } = mount(JSON.stringify(MENU));
+            el.handleInput = true;
+            el.dispatchEvent(new PointerEvent('pointerdown', { pointerType: 'mouse', bubbles: true }));
+            await new Promise((resolve) => setTimeout(resolve, 600));
+            // `gtk_gesture_single_set_touch_only (…, TRUE)` (gtkpopoverbin.c:657).
+            expect((popoverOf(el) as HTMLElement & { open: boolean }).open).toBe(false);
+            unmountAll();
+        });
+
+        await it('turning it OFF cancels a long press already under way', async () => {
+            const { el } = mount(JSON.stringify(MENU));
+            el.handleInput = true;
+            el.dispatchEvent(new PointerEvent('pointerdown', { pointerType: 'touch', bubbles: true }));
+            el.handleInput = false;
+            await new Promise((resolve) => setTimeout(resolve, 600));
+            // `set_handle_input (FALSE)` removes both gestures (gtkpopoverbin.c:668-672), so
+            // the timer it armed must not survive the turn-off.
+            expect((popoverOf(el) as HTMLElement & { open: boolean }).open).toBe(false);
+            unmountAll();
+        });
+    });
+
+    await describe('<gtk-popover-bin> menu.popup is an ACTION', async () => {
+        await it('the method opens the popover and announces the activation', () => {
+            const { el } = mount(JSON.stringify(MENU));
+            let announced = false;
+            el.addEventListener('menu.popup', () => {
+                announced = true;
+            });
+            el.popup();
+            // `gtk_widget_class_install_action (widget_class, "menu.popup", NULL,
+            // popup_action)` (gtkpopoverbin.c:381) — an action is GTK plumbing a browser
+            // cannot host, so the activation is an event and the call is `popup()`.
+            expect(announced).toBe(true);
+            expect((popoverOf(el) as HTMLElement & { open: boolean }).open).toBe(true);
+            unmountAll();
+        });
+
+        await it('the Menu key opens it, which is the shortcut beside the gestures', () => {
+            const { el } = mount(JSON.stringify(MENU));
+            el.dispatchEvent(new KeyboardEvent('keydown', { key: 'ContextMenu', bubbles: true, cancelable: true }));
+            // `gtk_shortcut_trigger_create_for_menu` (gtkpopoverbin.c:643-649) beside the
+            // named action, so a keyboard can reach the same popup the gesture does.
+            expect((popoverOf(el) as HTMLElement & { open: boolean }).open).toBe(true);
+            el.popdown();
+            expect((popoverOf(el) as HTMLElement & { open: boolean }).open).toBe(false);
+            unmountAll();
+        });
+
+        await it('without a popover there is nothing to activate', () => {
+            const { el } = mount();
+            el.popup();
+            expect(popoverOf(el)).toBeNull();
+            unmountAll();
+        });
+    });
+};