@gjsify/adwaita-web 0.54.0 → 0.56.0

package/src/gtk-center-box.spec.ts

@@ -0,0 +1,125 @@
+// DOM-level tests for <gtk-center-box>: the three slots are read off each child's `slot=`
+// (so the markup order is not the layout's), `shrink-center-last` becomes the flex WEIGHTS
+// that reproduce GTK's order, and `baseline-position` only moves the children when authored.
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { GtkCenterBox } from './elements/gtk-center-box.js';
+
+const SLOT_CHILD = (role: string, text: string): HTMLElement => {
+    const el = document.createElement('gtk-label');
+    el.setAttribute('slot', role);
+    el.setAttribute('label', text);
+    return el;
+};
+
+function mount(attrs: Record<string, string> = {}): { el: GtkCenterBox; host: HTMLElement } {
+    const host = document.createElement('div');
+    host.style.width = '300px';
+    document.body.appendChild(host);
+    const el = document.createElement('gtk-center-box') as GtkCenterBox;
+    for (const [name, value] of Object.entries(attrs)) el.setAttribute(name, value);
+    el.append(
+        SLOT_CHILD('start-widget', 'Start'),
+        SLOT_CHILD('center-widget', 'Centre'),
+        SLOT_CHILD('end-widget', 'End'),
+    );
+    host.appendChild(el);
+    return { el, host };
+}
+
+/** The `flex-shrink` the element wrote on each of the three slots. */
+const weights = (el: GtkCenterBox): Record<string, string> => ({
+    start: (el.startWidget as HTMLElement).style.flexShrink,
+    center: (el.centerWidget as HTMLElement).style.flexShrink,
+    end: (el.endWidget as HTMLElement).style.flexShrink,
+});
+
+export const GtkCenterBoxTest = async () => {
+    await describe('<gtk-center-box> slots', async () => {
+        await it('reads the three widgets off their slot names', () => {
+            const { el, host } = mount();
+            expect(el.startWidget?.getAttribute('label')).toBe('Start');
+            expect(el.centerWidget?.getAttribute('label')).toBe('Centre');
+            expect(el.endWidget?.getAttribute('label')).toBe('End');
+            expect(el.getAttribute('role')).toBe('generic');
+            host.remove();
+        });
+
+        await it('a child assigned through the property takes that slot', () => {
+            const { el, host } = mount();
+            const late = document.createElement('gtk-label');
+            late.setAttribute('label', 'Late');
+            el.endWidget = late;
+            expect(el.endWidget).toBe(late);
+            expect(el.endWidget?.style.flexShrink).toBe('100');
+            host.remove();
+        });
+
+        await it('the children sit at the start, the middle and the end of the box', () => {
+            const { el, host } = mount();
+            const box = el.getBoundingClientRect();
+            expect(Math.round((el.startWidget as HTMLElement).getBoundingClientRect().left - box.left)).toBe(0);
+            expect(Math.round(box.right - (el.endWidget as HTMLElement).getBoundingClientRect().right)).toBe(0);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-center-box> shrink-center-last', async () => {
+        await it('is TRUE by default, and the centre then carries the small weight', () => {
+            const { el, host } = mount();
+            expect(el.shrinkCenterLast).toBe(true);
+            // The START and END children are the ones that shrink FIRST, so they get the
+            // large weight (gtkcenterlayout.c:150-158 with the default TRUE).
+            expect(weights(el)).toStrictEqual({ start: '100', center: '1', end: '100' });
+            host.remove();
+        });
+
+        await it('flips the weights when the attribute says the centre shrinks first', () => {
+            const { el, host } = mount({ 'shrink-center-last': 'false' });
+            expect(el.shrinkCenterLast).toBe(false);
+            expect(weights(el)).toStrictEqual({ start: '1', center: '100', end: '1' });
+            host.remove();
+        });
+
+        await it('an unknown nick is the default, and writing the value already held notifies nothing', () => {
+            const { el, host } = mount();
+            const notified: unknown[] = [];
+            el.addEventListener('notify::shrink-center-last', (e) => notified.push((e as CustomEvent).detail));
+            // The pspec default is TRUE, and the setter compares against it
+            // (gtkcenterbox.c:596-602), so writing TRUE back is not a change — while the
+            // write that IS one notifies exactly once.
+            el.shrinkCenterLast = true;
+            expect(el.shrinkCenterLast).toBe(true);
+            expect(notified).toStrictEqual([]);
+            el.shrinkCenterLast = false;
+            expect(el.getAttribute('shrink-center-last')).toBe('false');
+            el.shrinkCenterLast = false;
+            expect(notified).toStrictEqual([{ 'shrink-center-last': false }]);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-center-box> baseline-position', async () => {
+        await it('is the centre position by default and leaves the stylesheet to stretch', () => {
+            const { el, host } = mount();
+            expect(el.baselinePosition).toBe('center');
+            // Nothing inline: the default position must not change the default look, and the
+            // stylesheet's `align-items: stretch` is what a box of FILL children draws.
+            expect(el.style.alignItems).toBe('');
+            expect(getComputedStyle(el).alignItems).toBe('stretch');
+            host.remove();
+        });
+
+        await it('the three nicks move the children in the extra space', () => {
+            const { el, host } = mount({ 'baseline-position': 'top' });
+            expect(el.baselinePosition).toBe('top');
+            expect(el.style.alignItems).toBe('flex-start');
+            el.baselinePosition = 'bottom';
+            expect(el.style.alignItems).toBe('flex-end');
+            el.setAttribute('baseline-position', 'middle');
+            expect(el.baselinePosition).toBe('center');
+            expect(el.style.alignItems).toBe('center');
+            host.remove();
+        });
+    });
+};

package/src/gtk-color-dialog-button.spec.ts

@@ -0,0 +1,141 @@
+// DOM-level tests for <gtk-color-dialog-button>. The ported rules are GTK's: the button is
+// INSENSITIVE until a dialog is set, `set_rgba` refuses a write of the colour it already
+// holds, and the swatch's accessible name is the channel percentages — with the Alpha
+// clause only while the colour is translucent.
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { GtkColorDialogButton } from './elements/gtk-color-dialog-button.js';
+
+function mount(attrs: Record<string, string> = {}): {
+    el: GtkColorDialogButton;
+    host: HTMLElement;
+    button: HTMLButtonElement;
+    input: HTMLInputElement;
+} {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const el = document.createElement('gtk-color-dialog-button') as GtkColorDialogButton;
+    for (const [name, value] of Object.entries(attrs)) el.setAttribute(name, value);
+    host.appendChild(el);
+    const button = el.querySelector('button') as HTMLButtonElement;
+    const input = el.querySelector('input') as HTMLInputElement;
+    // The chooser is a native `<input type="color">`; opening it for real would block the
+    // suite, so the click on it is what stands in for the platform picker.
+    input.click = () => {};
+    return { el, host, button, input };
+}
+
+export const GtkColorDialogButtonTest = async () => {
+    await describe('<gtk-color-dialog-button> sensitivity', async () => {
+        await it('is insensitive until a dialog is set — the first half of the C’s rule', () => {
+            const { el, host, button } = mount();
+            expect(button.disabled).toBe(true);
+            el.dialog = {};
+            expect(button.disabled).toBe(false);
+            el.dialog = null;
+            expect(button.disabled).toBe(true);
+            host.remove();
+        });
+
+        await it('a dialog written in markup counts as one', () => {
+            const { host, button } = mount({ dialog: '' });
+            expect(button.disabled).toBe(false);
+            host.remove();
+        });
+
+        await it('the disabled attribute is the author’s own switch, beside the dialog gate', () => {
+            const { el, host, button } = mount({ dialog: '' });
+            el.setAttribute('disabled', '');
+            expect(button.disabled).toBe(true);
+            el.removeAttribute('disabled');
+            expect(button.disabled).toBe(false);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-color-dialog-button> rgba', async () => {
+        await it('opens on the colour init gives it, not on black', () => {
+            const { el, host } = mount();
+            expect(el.rgba.red).toBe(0.75);
+            expect(el.rgba.green).toBe(0.25);
+            expect(el.rgba.blue).toBe(0.25);
+            expect(el.rgba.alpha).toBe(1);
+            host.remove();
+        });
+
+        await it('reads every CSS colour the browser knows, because CSSOM parses it', () => {
+            const { el, host } = mount({ rgba: '#3584e4' });
+            expect(el.rgba.red).toBeCloseTo(53 / 255, 4);
+            expect(el.rgba.green).toBeCloseTo(132 / 255, 4);
+            expect(el.rgba.blue).toBeCloseTo(228 / 255, 4);
+            el.setAttribute('rgba', 'rgba(255, 0, 0, 0.5)');
+            expect(el.rgba.alpha).toBe(0.5);
+            el.setAttribute('rgba', 'not-a-colour');
+            expect(el.rgba.red).toBeCloseTo(1, 4);
+            host.remove();
+        });
+
+        await it('a write of the colour already held changes nothing and notifies nothing', () => {
+            const { el, host } = mount({ rgba: '#ff0000' });
+            const notified: unknown[] = [];
+            el.addEventListener('notify::rgba', (e) => notified.push((e as CustomEvent).detail));
+            el.rgba = '#ff0000';
+            expect(notified.length).toBe(0);
+            el.rgba = { red: 0, green: 0, blue: 1, alpha: 1 };
+            expect(notified.length).toBe(1);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-color-dialog-button> accessible name', async () => {
+        await it('is the channel percentages, with Alpha only while translucent', () => {
+            const { el, host, button } = mount();
+            expect(button.getAttribute('aria-label')).toBe('Red 75%, Green 25%, Blue 25%');
+            el.rgba = 'rgba(255, 0, 0, 0.5)';
+            expect(button.getAttribute('aria-label')).toBe('Red 100%, Green 0%, Blue 0%, Alpha 50%');
+            host.remove();
+        });
+
+        await it('rounds half up, the way scale_round does', () => {
+            const { el, host, button } = mount();
+            // 0.255 is exactly the case a truncating round gets wrong.
+            el.rgba = { red: 0.255, green: 0.754, blue: 0.5, alpha: 1 };
+            expect(button.getAttribute('aria-label')).toBe('Red 26%, Green 75%, Blue 50%');
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-color-dialog-button> chooser', async () => {
+        await it('a chosen colour lands on the button, and the alpha it already had survives', () => {
+            const { el, host, input } = mount({ dialog: '', rgba: '#ff0000' });
+            el.rgba = 'rgba(255, 0, 0, 0.25)';
+            el.activate();
+            expect(input.value).toBe('#ff0000');
+            input.value = '#0000ff';
+            input.dispatchEvent(new Event('change'));
+            expect(el.rgba.blue).toBe(1);
+            expect(el.rgba.alpha).toBe(0.25);
+            host.remove();
+        });
+
+        await it('is a group with a popup button, as GTK marks it', () => {
+            const { host, button } = mount({ dialog: '' });
+            expect(host.ownerDocument.activeElement).not.toBe(button);
+            expect(button.getAttribute('aria-haspopup')).toBe('dialog');
+            expect(host.firstElementChild?.getAttribute('role')).toBe('group');
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-color-dialog-button> look', async () => {
+        await it('paints the swatch with the colour, and marks a translucent one', () => {
+            const { el, host } = mount({ rgba: '#3584e4' });
+            const swatch = el.querySelector('.color-button-swatch') as HTMLElement;
+            expect(getComputedStyle(swatch).backgroundColor).toBe('rgb(53, 132, 228)');
+            expect(swatch.dataset.translucent).toBe('false');
+            el.rgba = 'rgba(53, 132, 228, 0.5)';
+            expect(swatch.dataset.translucent).toBe('true');
+            host.remove();
+        });
+    });
+};

package/src/gtk-column-view.spec.ts

@@ -0,0 +1,154 @@
+// DOM-level tests for <gtk-column-view>: the header, one cell per visible column, the
+// per-column factory, and the sort state a header click produces. The rows, the model and
+// the selection are <gtk-list-view>'s and are asserted there; what is checked here is
+// that they still arrive through the subclass.
+import { describe, expect, it } from '@gjsify/unit';
+
+import { COLUMN_VIEW_SORT_VECTORS } from '@gjsify/adwaita-core/conformance';
+
+import type { GtkColumnView } from './elements/gtk-column-view.js';
+
+const COLUMNS =
+    '[{"key":"label","id":"name","title":"Name","sortable":true},{"key":"value","id":"code","title":"Code"}]';
+
+function mount(attrs: Record<string, string> = {}): { el: GtkColumnView; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const el = document.createElement('gtk-column-view') as GtkColumnView;
+    for (const [name, value] of Object.entries(attrs)) el.setAttribute(name, value);
+    host.appendChild(el);
+    return { el, host };
+}
+
+const headers = (el: GtkColumnView): HTMLElement[] => [
+    ...el.querySelectorAll<HTMLElement>('.adw-column-view-header-cell'),
+];
+const rows = (el: GtkColumnView): HTMLElement[] => [...el.querySelectorAll<HTMLElement>('.adw-column-view-row')];
+const cellsOf = (row: HTMLElement): string[] =>
+    [...row.querySelectorAll<HTMLElement>('.adw-column-view-cell')].map((cell) => cell.textContent ?? '');
+
+const MODEL = '[{"value":"de","label":"German"},{"value":"fr","label":"French"}]';
+
+export const GtkColumnViewTest = async () => {
+    await describe('<gtk-column-view> header and cells', async () => {
+        await it('draws one header button per column and one cell per column per row', () => {
+            const { el, host } = mount({ columns: COLUMNS, model: MODEL });
+            expect(headers(el).map((button) => button.textContent?.trim())).toStrictEqual(['Name', 'Code']);
+            expect(rows(el).length).toBe(2);
+            expect(cellsOf(rows(el)[0]!)).toStrictEqual(['German', 'de']);
+            expect(cellsOf(rows(el)[1]!)).toStrictEqual(['French', 'fr']);
+            host.remove();
+        });
+
+        await it('announces itself as a grid of rows, headers and cells', () => {
+            const { el, host } = mount({ columns: COLUMNS, model: MODEL });
+            expect(el.getAttribute('role')).toBe('grid');
+            expect(headers(el)[0]!.getAttribute('role')).toBe('columnheader');
+            expect(rows(el)[0]!.getAttribute('role')).toBe('row');
+            expect(rows(el)[0]!.querySelector('.adw-column-view-cell')?.getAttribute('role')).toBe('gridcell');
+            host.remove();
+        });
+
+        await it('leaves an invisible column out of both the header and the rows', () => {
+            const { el, host } = mount({ model: MODEL });
+            el.columns = [
+                { key: 'label', id: 'name', title: 'Name' },
+                { key: 'value', id: 'code', title: 'Code', visible: false },
+            ];
+            expect(headers(el).length).toBe(1);
+            expect(cellsOf(rows(el)[0]!)).toStrictEqual(['German']);
+            host.remove();
+        });
+
+        await it('gives the header and every row the same track list', () => {
+            const { el, host } = mount({ model: MODEL });
+            el.columns = [
+                { key: 'label', id: 'name', fixedWidth: 120 },
+                { key: 'value', id: 'code', expand: true },
+            ];
+            const header = el.querySelector<HTMLElement>('.adw-column-view-header')!;
+            expect(header.style.gridTemplateColumns).toBe('120px 1fr');
+            expect(rows(el)[0]!.style.gridTemplateColumns).toBe('120px 1fr');
+            host.remove();
+        });
+
+        await it('draws a column with a factory instead of its portable field', () => {
+            const { el, host } = mount({ columns: COLUMNS, model: MODEL });
+            el.columnFactories = {
+                code: (context) => {
+                    const node = document.createElement('code');
+                    node.textContent = context.item.value.toUpperCase();
+                    return node;
+                },
+            };
+            expect(cellsOf(rows(el)[0]!)).toStrictEqual(['German', 'DE']);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-column-view> drives the sort vectors with real header clicks', async () => {
+        for (const vector of COLUMN_VIEW_SORT_VECTORS) {
+            await it(vector.rule, () => {
+                const { el, host } = mount({ model: MODEL });
+                el.columns = [
+                    { key: 'label', id: 'name', title: 'Name', sortable: true },
+                    { key: 'value', id: 'code', title: 'Code', sortable: vector.sortable },
+                ];
+                el.sorter = vector.current;
+                headers(el)
+                    .find((button) => button.dataset.columnId === vector.column)!
+                    .click();
+                expect(el.sorter).toStrictEqual(vector.next);
+                host.remove();
+            });
+        }
+    });
+
+    await describe('<gtk-column-view> sorting', async () => {
+        await it('sorts ascending on the first click and inverts on the second', () => {
+            const { el, host } = mount({ columns: COLUMNS, model: MODEL });
+            const seen: (string | null)[] = [];
+            el.addEventListener('notify::sorter', (event) => {
+                const sorter = (event as CustomEvent).detail.sorter as { column: string; descending: boolean } | null;
+                seen.push(sorter === null ? null : `${sorter.column}/${sorter.descending}`);
+            });
+            headers(el)[0]!.click();
+            expect(el.sorter).toStrictEqual({ column: 'name', descending: false });
+            expect(headers(el)[0]!.getAttribute('aria-sort')).toBe('ascending');
+            headers(el)[0]!.click();
+            expect(el.sorter).toStrictEqual({ column: 'name', descending: true });
+            expect(headers(el)[0]!.getAttribute('aria-sort')).toBe('descending');
+            expect(seen).toStrictEqual(['name/false', 'name/true']);
+            host.remove();
+        });
+
+        await it('does not sort by a column that declares no sorter', () => {
+            const { el, host } = mount({ columns: COLUMNS, model: MODEL });
+            headers(el)[1]!.click();
+            expect(el.sorter).toBe(null);
+            expect(headers(el)[1]!.hasAttribute('aria-sort')).toBe(false);
+            host.remove();
+        });
+
+        await it('REORDERS nothing by itself, the way gtk_column_view_get_sorter does not', () => {
+            // The view publishes the sort and the consumer re-assigns the model; a view
+            // that reordered its own rows would fight whatever model the consumer holds.
+            const { el, host } = mount({ columns: COLUMNS, model: MODEL });
+            headers(el)[0]!.click();
+            expect(rows(el).map((row) => cellsOf(row)[0])).toStrictEqual(['German', 'French']);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-column-view> separators', async () => {
+        await it('colours the cell borders only while show-column-separators is set', () => {
+            const { el, host } = mount({ columns: COLUMNS, model: MODEL });
+            expect(el.classList.contains('column-separators')).toBe(false);
+            el.showColumnSeparators = true;
+            expect(el.classList.contains('column-separators')).toBe(true);
+            el.showRowSeparators = true;
+            expect(el.classList.contains('separators')).toBe(true);
+            host.remove();
+        });
+    });
+};

package/src/gtk-drag-icon.spec.ts

@@ -0,0 +1,190 @@
+// DOM-level tests for <gtk-drag-icon>. A drag icon exists only WHILE a drag is in flight and
+// GTK destroys it with the drag, so what a test can reach is the whole lifecycle: the child
+// the icon carries, the per-drag cache `getForDrag` is, the icon following the pointer, and
+// the hide that stands in for the destroy.
+import { describe, expect, it } from '@gjsify/unit';
+
+import { GtkDragIcon } from './elements/gtk-drag-icon.js';
+
+function mount(child?: string): { el: GtkDragIcon; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const el = document.createElement('gtk-drag-icon') as GtkDragIcon;
+    if (child !== undefined) el.innerHTML = child;
+    host.appendChild(el);
+    return { el, host };
+}
+
+/** A drag event of its own: `getForDrag` keys on the `dataTransfer`, so each one is new. */
+function dragEvent(x = 0, y = 0, type = 'dragstart'): DragEvent {
+    const event = new DragEvent(type, { clientX: x, clientY: y });
+    // `DataTransfer` is not in the event dictionary's constructor options in every engine,
+    // and the icon's own code reads it defensively; a test must not depend on that.
+    Object.defineProperty(event, 'dataTransfer', { value: new DataTransfer() });
+    return event;
+}
+
+export const GtkDragIconTest = async () => {
+    await describe('<gtk-drag-icon> child', async () => {
+        await it('is null until it is given one', () => {
+            const { el, host } = mount();
+            expect(el.child).toBe(null);
+            host.remove();
+        });
+
+        await it('takes the child it is set, in light DOM, and keeps only that one', () => {
+            // :478-485 — `gtk_widget_unparent (self->child)` then `gtk_widget_set_parent`
+            // on the new one, so the old child LEAVES rather than being duplicated.
+            const { el, host } = mount();
+            const first = document.createElement('gtk-label');
+            const second = document.createElement('gtk-image');
+            el.child = first;
+            expect(el.child).toBe(first);
+            el.child = second;
+            expect(el.child).toBe(second);
+            expect(el.children.length).toBe(1);
+            expect(first.isConnected).toBe(false);
+            host.remove();
+        });
+
+        await it('reads a child declared in markup without a call', () => {
+            // The getter is the light-DOM child, which is what makes the declared form work.
+            const { el, host } = mount('<gtk-label label="A drag icon can be markup"></gtk-label>');
+            expect(el.child?.tagName).toBe('GTK-LABEL');
+            host.remove();
+        });
+
+        await it('notifies once per real change and never for an echo', () => {
+            // :475 — `if (self->child == child) return;` — and `G_PARAM_EXPLICIT_NOTIFY`,
+            // so the one notify at :489 is the only signal this class emits.
+            const { el, host } = mount();
+            const detail: unknown[] = [];
+            el.addEventListener('notify::child', (event) => detail.push((event as CustomEvent).detail['child']));
+            const child = document.createElement('gtk-label');
+            el.child = child;
+            el.child = child;
+            el.child = null;
+            expect(detail).toStrictEqual([child, null]);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-drag-icon> the drag', async () => {
+        await it('is hidden and idle until a drag begins', () => {
+            // `gtk_drag_icon_get_for_drag` (:400-421) creates the icon and shows it only
+            // once a child is set, which in a browser is the drag itself.
+            const { el, host } = mount('<gtk-label label="x"></gtk-label>');
+            expect(el.dragging).toBe(false);
+            expect(el.hidden).toBe(false);
+            el.endDrag();
+            expect(el.hidden).toBe(true);
+            host.remove();
+        });
+
+        await it('follows the pointer once a drag is in flight', () => {
+            // `gtk_drag_icon_move_resize` (:138-150) is the whole of "moves with the
+            // pointer", and the hotspot is (0, 0) — see the header for why.
+            const { el, host } = mount('<gtk-label label="drag me"></gtk-label>');
+            el.beginDrag(dragEvent(40, 12));
+            expect(el.dragging).toBe(true);
+            expect(el.hidden).toBe(false);
+            expect(el.style.transform).toBe('translate3d(40px, 12px, 0px)');
+            document.dispatchEvent(new DragEvent('dragover', { clientX: 41, clientY: 13 }));
+            expect(el.style.transform).toBe('translate3d(41px, 13px, 0px)');
+            el.endDrag();
+            expect(el.dragging).toBe(false);
+            expect(el.hidden).toBe(true);
+            host.remove();
+        });
+
+        await it('stops following when the drag ends', () => {
+            const { el, host } = mount('<gtk-label label="drag me"></gtk-label>');
+            el.beginDrag(dragEvent(4, 4));
+            document.dispatchEvent(new DragEvent('dragover', { clientX: 90, clientY: 90 }));
+            document.dispatchEvent(new DragEvent('dragend', {}));
+            expect(el.dragging).toBe(false);
+            expect(el.hidden).toBe(true);
+            const before = el.style.transform;
+            document.dispatchEvent(new DragEvent('dragover', { clientX: 120, clientY: 120 }));
+            expect(el.style.transform).toBe(before);
+            host.remove();
+        });
+    });
+
+    await describe('GtkDragIcon.getForDrag', async () => {
+        await it('gives one icon per drag and the same one twice', () => {
+            // `g_object_get_qdata (G_OBJECT (drag), drag_icon_quark)` (:408-419): the icon
+            // is cached ON THE DRAG, so a second call for the same drag is the same widget.
+            const event = dragEvent();
+            const icon = GtkDragIcon.getForDrag(event);
+            expect(GtkDragIcon.getForDrag(event)).toBe(icon);
+            // No declared icon is free in this state, so the second drag is a new node.
+            const other = GtkDragIcon.getForDrag(dragEvent());
+            expect(other).not.toBe(icon);
+            for (const el of [icon, other]) {
+                el.endDrag();
+                el.remove();
+            }
+        });
+
+        await it('reuses a declared <gtk-drag-icon> instead of adding another', () => {
+            const declared = document.createElement('gtk-drag-icon');
+            document.body.appendChild(declared);
+            const icon = GtkDragIcon.getForDrag(dragEvent());
+            expect(icon).toBe(declared);
+            expect(document.querySelectorAll('gtk-drag-icon').length).toBe(1);
+            icon.endDrag();
+            declared.remove();
+        });
+
+        await it('gives a drag whose declared icon is busy a node of its own', () => {
+            // One icon per drag is the C's contract, so a declared icon already following
+            // a pointer belongs to that drag — the reuse is for the ONE drag markup names.
+            const declared = document.createElement('gtk-drag-icon');
+            document.body.appendChild(declared);
+            const first = GtkDragIcon.getForDrag(dragEvent());
+            expect(first).toBe(declared);
+            const second = GtkDragIcon.getForDrag(dragEvent());
+            expect(second).not.toBe(declared);
+            expect(second.dragging).toBe(true);
+            // The busy icon is left to its own drag: it still follows that pointer.
+            expect(first.dragging).toBe(true);
+            for (const el of [first, second]) el.endDrag();
+            for (const el of document.querySelectorAll('gtk-drag-icon')) el.remove();
+        });
+
+        await it('detaches the platform drag image so only the mirror shows', () => {
+            // The browser's own ghost is asked away with a 1×1 transparent image; where a
+            // browser refuses that, the platform ghost shows as well — the header says so.
+            const icon = GtkDragIcon.getForDrag(dragEvent(3, 4));
+            expect(icon.style.transform).toBe('translate3d(3px, 4px, 0px)');
+            icon.endDrag();
+            for (const el of document.querySelectorAll('gtk-drag-icon')) el.remove();
+        });
+    });
+
+    await describe('GtkDragIcon.createWidgetForValue', async () => {
+        await it('builds a label for a string', () => {
+            // :531-534 — `G_VALUE_HOLDS (value, G_TYPE_STRING)` → `gtk_label_new`.
+            const widget = GtkDragIcon.createWidgetForValue('Report.odt');
+            expect(widget?.tagName).toBe('GTK-LABEL');
+            expect(widget?.getAttribute('label')).toBe('Report.odt');
+        });
+
+        await it('builds a swatch carrying the colour for an RGBA', () => {
+            // :544-553 — a `GtkColorSwatch` with can-drag and can-drop FALSE, so for a drag
+            // icon it is nothing but the colour. The div is this package's swatch.
+            const widget = GtkDragIcon.createWidgetForValue({ red: 1, green: 0, blue: 0, alpha: 0.5 });
+            expect(widget?.className).toBe('adw-drag-icon-swatch');
+            // The alpha is half, so every engine keeps the `rgba()` form a swatch needs to
+            // read as translucent; at alpha 1 Firefox serializes it back to `rgb()`.
+            expect((widget as HTMLElement | null)?.style.backgroundColor).toBe('rgba(255, 0, 0, 0.5)');
+        });
+
+        await it('returns null for a value it cannot make a widget for', () => {
+            // :603-605 — and the four types between :535-602 have no browser answer, which
+            // the header names: no icon query for a file, no painted selection for a buffer.
+            expect(GtkDragIcon.createWidgetForValue(null)).toBe(null);
+        });
+    });
+};