@gjsify/adwaita-web 0.31.0 → 0.33.0

package/src/adw-icon.spec.ts

@@ -0,0 +1,167 @@
+// DOM-level tests for <adw-icon>, driven by the SAME `normalizeIconName` vectors
+// the core suite asserts against (`@gjsify/adwaita-core/conformance`), plus the
+// REGRESSION PROOF for the drift the element was extracted to close.
+//
+// The drift: `<span class="adw-icon adw-icon--<name>" aria-hidden="true">` was
+// built by hand at twenty-three sites across seventeen files, nine of them
+// re-deriving `name.replace(/-symbolic$/, '')` on the spot. Exactly ONE site —
+// `<adw-split-button>` — also checked the result was a single CSS token. So
+// `icon-name="a b"` interpolated into `class="adw-icon adw-icon--a b"` and shipped
+// a stray `b` class through `<adw-menu-button>`, for its own icon AND for every
+// JSON menu entry's, while the one element that guarded kept passing its spec.
+// The vectors below now run against the ELEMENT, so a renderer that starts
+// building the class by hand again fails naming the input.
+import { describe, expect, it } from '@gjsify/unit';
+
+import { VIEW_STACK_ICON_NAME_VECTORS } from '@gjsify/adwaita-core/conformance';
+
+import type { AdwIcon } from './elements/adw-icon.js';
+import type { AdwMenuButton } from './elements/adw-menu-button.js';
+
+function mount<T extends HTMLElement>(tag: string): { el: T; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const el = document.createElement(tag) as T;
+    host.appendChild(el);
+    return { el, host };
+}
+
+/** Every class on the node that is not the base `.adw-icon`. */
+function extraClasses(el: HTMLElement): string[] {
+    return [...el.classList].filter((c) => c !== 'adw-icon').sort();
+}
+
+export const AdwIconTest = async () => {
+    await describe('<adw-icon> mask class (normalizeIconName vectors)', async () => {
+        for (const { icon, normalized, rule } of VIEW_STACK_ICON_NAME_VECTORS) {
+            await it(`${JSON.stringify(icon)} → ${JSON.stringify(normalized)} — ${rule}`, () => {
+                const { el, host } = mount<AdwIcon>('adw-icon');
+                el.iconName = icon ?? null;
+
+                expect(el.resolvedIconName).toBe(normalized);
+                // The base class is unconditional — a nameless icon is still an
+                // icon box, which is what `<adw-status-page>` hides rather than
+                // omits.
+                expect(el.classList.contains('adw-icon')).toBe(true);
+                // …and NOTHING else is on the node. This is the assertion the
+                // hand-rolled copies could not make: `icon-name="a b"` used to
+                // leave a stray `b` here.
+                expect(extraClasses(el)).toStrictEqual(normalized === '' ? [] : [`adw-icon--${normalized}`]);
+                host.remove();
+            });
+        }
+    });
+
+    await describe('<adw-icon> node contract', async () => {
+        await it('is decorative — the accessible name belongs to the host control', () => {
+            const { el, host } = mount<AdwIcon>('adw-icon');
+            expect(el.getAttribute('aria-hidden')).toBe('true');
+            host.remove();
+        });
+
+        await it('swaps ONLY the mask class, keeping the caller position classes', () => {
+            const { el, host } = mount<AdwIcon>('adw-icon');
+            el.classList.add('adw-drop-down-arrow', 'start');
+            el.iconName = 'go-down';
+            expect(extraClasses(el)).toStrictEqual(['adw-drop-down-arrow', 'adw-icon--go-down', 'start']);
+
+            el.iconName = 'go-next';
+            // Exactly one mask class at a time, and the caller's are untouched —
+            // a `className =` assignment would have taken them with it.
+            expect(extraClasses(el)).toStrictEqual(['adw-drop-down-arrow', 'adw-icon--go-next', 'start']);
+
+            el.iconName = null;
+            expect(extraClasses(el)).toStrictEqual(['adw-drop-down-arrow', 'start']);
+            host.remove();
+        });
+
+        await it('sizes the box AND the mask together', () => {
+            const { el, host } = mount<AdwIcon>('adw-icon');
+            el.iconName = 'go-next';
+            // Unset: the stylesheet's 16px.
+            expect(el.size).toBe(null);
+            expect(getComputedStyle(el).width).toBe('16px');
+
+            el.size = 32;
+            const styled = getComputedStyle(el);
+            expect(styled.width).toBe('32px');
+            expect(styled.height).toBe('32px');
+            // Sizing only the box would leave a 16px glyph floating in it. Only
+            // the axis we set is asserted: `mask-size: 32px` means "32px wide,
+            // height from the aspect ratio", and the CSSOM re-serializes the
+            // omitted half (Firefox reports `32px auto`, in the inline style too).
+            expect(styled.maskSize.split(' ')[0]).toBe('32px');
+            expect(styled.webkitMaskSize.split(' ')[0]).toBe('32px');
+
+            el.size = null;
+            expect(getComputedStyle(el).width).toBe('16px');
+            host.remove();
+        });
+
+        await it('paints in the INHERITED colour, not the boundary reset colour', () => {
+            // `.adw-icon` masks with `currentColor`, and <adw-icon> is a custom
+            // element — so the ADR-0010 `$adw-components` reset re-roots `color`
+            // on it. Without `color: inherit` in `_icon.scss` every icon would
+            // repaint in `--window-fg-color` regardless of the button it sits in.
+            const { el: box, host } = mount<HTMLElement>('div');
+            box.style.color = 'rgb(255, 0, 0)';
+            const icon = document.createElement('adw-icon') as AdwIcon;
+            icon.iconName = 'go-next';
+            box.appendChild(icon);
+            expect(getComputedStyle(icon).backgroundColor).toBe('rgb(255, 0, 0)');
+            host.remove();
+        });
+    });
+
+    await describe('the hand-rolled copies are gone', async () => {
+        await it('<adw-menu-button> no longer injects a stray class from its icon-name', () => {
+            const { el, host } = mount<AdwMenuButton>('adw-menu-button');
+            el.setAttribute('icon-name', 'a b');
+            const icon = el.querySelector('.adw-icon') as HTMLElement;
+            // `adw-icon--a b` would have added a second, unrelated `b` class.
+            expect(extraClasses(icon)).toStrictEqual(['adw-menu-button-icon']);
+            host.remove();
+        });
+
+        await it('<adw-menu-button> menu entries guard their icons too', () => {
+            const { el, host } = mount<AdwMenuButton>('adw-menu-button');
+            el.menuItems = [
+                { label: 'Bad', icon: 'a b' },
+                { label: 'Good', icon: 'view-refresh-symbolic' },
+                { label: 'None' },
+            ];
+            const items = [...el.querySelectorAll('.adw-menu-button-item')];
+            expect(items.length).toBe(3);
+            // An unusable name draws nothing rather than injecting markup, and
+            // an entry with no icon still gets no icon node at all.
+            expect(items[0].querySelector('.adw-icon')).toBe(null);
+            expect(items[2].querySelector('.adw-icon')).toBe(null);
+            const good = items[1].querySelector('.adw-icon') as HTMLElement;
+            expect(extraClasses(good)).toStrictEqual(['adw-icon--view-refresh', 'adw-menu-button-item-icon']);
+            host.remove();
+        });
+
+        await it('every icon in the package is an <adw-icon>', () => {
+            // The point of the extraction, asserted structurally: build a page of
+            // the widgets that draw icons and check no bare span carries the
+            // base class. A new hand-rolled `<span class="adw-icon …">` fails
+            // here even if it happens to guard its own name correctly.
+            const { el: page, host } = mount<HTMLElement>('div');
+            page.innerHTML = `
+                <adw-button icon="go-next" label="Next"></adw-button>
+                <adw-button-row title="Row" start-icon-name="list-add" end-icon-name="go-next"></adw-button-row>
+                <adw-status-page icon="folder" title="Empty"></adw-status-page>
+                <adw-split-button label="Save" menu='[{"label":"Save As"}]'></adw-split-button>
+                <adw-drop-down options='["a","b"]'></adw-drop-down>
+                <adw-expander-row title="More" show-enable-switch></adw-expander-row>
+                <adw-avatar text="Ada" icon="avatar-default"></adw-avatar>
+                <adw-toggle-group><adw-toggle icon-name="view-list"></adw-toggle></adw-toggle-group>
+            `;
+            const bareSpans = [...host.querySelectorAll('span.adw-icon')];
+            expect(bareSpans.length).toBe(0);
+            // …and the icons really are there, so the check is not vacuous.
+            expect(host.querySelectorAll('adw-icon.adw-icon').length > 5).toBe(true);
+            host.remove();
+        });
+    });
+};

package/src/adw-progress-bar.spec.ts

@@ -0,0 +1,173 @@
+// DOM-level tests for <adw-progress-bar>.
+//
+// Three things here are worth more than the attribute round-trips: the CLAMP is
+// GLib's (`glibClamp`, shared from `@gjsify/adwaita-core`, not a local
+// `Math.min/max`), the ZERO fraction has to make the indicator VANISH rather
+// than draw a rounded stub (`> trough.empty > progress { all: unset }`,
+// _progress-bar.scss:85), and the text node has to actually PICK UP `.dimmed` +
+// `.numeric` from `_labels.scss` — that composition is the reason those classes
+// exist, and a `@extend` that silently reached nothing would look identical in
+// the source.
+
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { AdwProgressBar } from './elements/adw-progress-bar.js';
+
+function mount(): { el: AdwProgressBar; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const el = document.createElement('adw-progress-bar') as AdwProgressBar;
+    host.appendChild(el);
+    return { el, host };
+}
+
+/** The parts, by the markup contract the stylesheet selects on. */
+function parts(bar: AdwProgressBar): { trough: HTMLElement; progress: HTMLElement; text: HTMLElement } {
+    return {
+        trough: bar.querySelector('.adw-progress-bar-trough') as HTMLElement,
+        progress: bar.querySelector('.adw-progress-bar-progress') as HTMLElement,
+        text: bar.querySelector('.adw-progress-bar-text') as HTMLElement,
+    };
+}
+
+export const AdwProgressBarTest = async () => {
+    await describe('<adw-progress-bar> fraction', async () => {
+        await it('starts empty, with the trough flagged so the indicator disappears', () => {
+            const { el, host } = mount();
+            const { trough, progress } = parts(el);
+            expect(el.fraction).toBe(0);
+            expect(trough).toBeTruthy();
+            expect(progress).toBeTruthy();
+            expect(trough.classList.contains('empty')).toBe(true);
+            expect(el.getAttribute('role')).toBe('progressbar');
+            expect(el.getAttribute('aria-valuenow')).toBe('0');
+            host.remove();
+        });
+
+        await it('fills to the fraction and drops the empty flag', () => {
+            const { el, host } = mount();
+            el.fraction = 0.25;
+            const { trough, progress } = parts(el);
+            expect(trough.classList.contains('empty')).toBe(false);
+            expect(progress.style.width).toBe('25%');
+            expect(el.getAttribute('aria-valuenow')).toBe('0.25');
+            host.remove();
+        });
+
+        await it('clamps out-of-range and unusable fractions', () => {
+            const { el, host } = mount();
+            el.fraction = 1.5;
+            expect(el.fraction).toBe(1);
+            expect(parts(el).progress.style.width).toBe('100%');
+            el.fraction = -3;
+            expect(el.fraction).toBe(0);
+            // A garbage attribute is GtkProgressBar's default 0, never NaN —
+            // NaN would reach both the width and `aria-valuenow`.
+            el.setAttribute('fraction', 'later');
+            expect(el.fraction).toBe(0);
+            expect(el.getAttribute('aria-valuenow')).toBe('0');
+            host.remove();
+        });
+    });
+
+    await describe('<adw-progress-bar> indeterminate', async () => {
+        await it('pulse() enters the pulsing state and drops aria-valuenow', () => {
+            const { el, host } = mount();
+            el.fraction = 0.4;
+            expect(el.getAttribute('aria-valuenow')).toBe('0.4');
+
+            el.pulse();
+
+            expect(el.pulsing).toBe(true);
+            expect(el.hasAttribute('pulsing')).toBe(true);
+            // ARIA spells "indeterminate" as an ABSENT valuenow; a stale 0.4
+            // would be announced as real progress.
+            expect(el.hasAttribute('aria-valuenow')).toBe(false);
+            // A pulsing bar is never `.empty` — the bouncing block is what says
+            // "working", so it must not be unset away.
+            expect(parts(el).trough.classList.contains('empty')).toBe(false);
+            host.remove();
+        });
+
+        await it('leaving the pulsing state restores the determinate value', () => {
+            const { el, host } = mount();
+            el.fraction = 0;
+            el.pulse();
+            el.pulsing = false;
+            expect(el.getAttribute('aria-valuenow')).toBe('0');
+            expect(parts(el).trough.classList.contains('empty')).toBe(true);
+            host.remove();
+        });
+    });
+
+    await describe('<adw-progress-bar> text', async () => {
+        await it('hides the text node until show-text, then shows the percentage', () => {
+            const { el, host } = mount();
+            expect(parts(el).text.hidden).toBe(true);
+
+            el.fraction = 0.42;
+            el.showText = true;
+
+            expect(parts(el).text.hidden).toBe(false);
+            expect(parts(el).text.textContent).toBe('42%');
+            host.remove();
+        });
+
+        await it('an explicit text wins over the percentage', () => {
+            const { el, host } = mount();
+            el.showText = true;
+            el.fraction = 0.5;
+            el.text = 'Copying 3 of 6';
+            expect(el.text).toBe('Copying 3 of 6');
+            expect(parts(el).text.textContent).toBe('Copying 3 of 6');
+            host.remove();
+        });
+
+        await it('the text node composes .dimmed and .numeric from _labels.scss', () => {
+            // `> text { @extend .dimmed; @extend .numeric; }`
+            // (_progress-bar.scss:17-21) — this asserts the extends actually
+            // REACHED the utility classes, which a source read cannot tell.
+            const { el, host } = mount();
+            el.showText = true;
+            const style = getComputedStyle(parts(el).text);
+            expect(style.getPropertyValue('font-variant-numeric')).toBe('tabular-nums');
+            expect(Number.parseFloat(style.opacity)).toBeLessThan(1);
+            host.remove();
+        });
+    });
+
+    await describe('<adw-progress-bar> variants', async () => {
+        await it('is an 8px trough by default and a 2px hairline with osd', () => {
+            // The 8px is libadwaita's (_progress-bar.scss:6) and the 2px is its
+            // `.osd` variant (:59-83) — NOT the vendored web port's 6px, which
+            // has no OSD variant at all.
+            //
+            // TWO bars rather than one flipped in place, on purpose: the trough
+            // TRANSITIONS `background`, so a computed read taken right after an
+            // attribute flip returns the INTERPOLATED colour — i.e. still the
+            // old one — and the assertion would be timing-dependent. Setting the
+            // state before the element's first style resolution leaves no
+            // transition to be part-way through.
+            const host = document.createElement('div');
+            document.body.appendChild(host);
+            const plain = document.createElement('adw-progress-bar') as AdwProgressBar;
+            const osd = document.createElement('adw-progress-bar') as AdwProgressBar;
+            osd.setAttribute('osd', '');
+            host.append(plain, osd);
+
+            expect(getComputedStyle(parts(plain).trough).height).toBe('8px');
+            const osdTrough = getComputedStyle(parts(osd).trough);
+            expect(osdTrough.height).toBe('2px');
+            expect(osdTrough.backgroundColor).toBe('rgba(0, 0, 0, 0)');
+            host.remove();
+        });
+
+        await it('inverted fills from the far end', () => {
+            const { el, host } = mount();
+            expect(getComputedStyle(parts(el).trough).justifyContent).toBe('normal');
+            el.inverted = true;
+            expect(getComputedStyle(parts(el).trough).justifyContent).toBe('flex-end');
+            host.remove();
+        });
+    });
+};

package/src/adw-row-state.spec.ts

@@ -9,6 +9,8 @@
 // display silently.
 import { describe, expect, it } from '@gjsify/unit';
 
+import { COMBO_CHOOSER_VECTORS } from '@gjsify/adwaita-core/conformance';
+
 import type { AdwComboRow } from './elements/adw-combo-row.js';
 import type { AdwExpanderRow } from './elements/adw-expander-row.js';
 import type { AdwSpinRow } from './elements/adw-spin-row.js';
@@ -72,6 +74,53 @@ export const AdwRowStateTest = async () => {
             expect((row.querySelector('.adw-row-value') as HTMLSpanElement).textContent).toBe('');
             host.remove();
         });
+
+        for (const { count, presentsChooser, rule } of COMBO_CHOOSER_VECTORS) {
+            await it(`${count} option(s) → ${presentsChooser ? 'a chooser' : 'not a chooser'}: ${rule}`, async () => {
+                const items = JSON.stringify(Array.from({ length: count }, (_, i) => `Item ${i}`));
+                const { el: row, host } = parse<AdwComboRow>(
+                    `<adw-combo-row title="Pick" items='${items}'></adw-combo-row>`,
+                    'adw-combo-row',
+                );
+                const value = row.querySelector('.adw-row-value') as HTMLSpanElement;
+                const select = row.querySelector('select') as HTMLSelectElement;
+
+                // The ARROW: `.adw-row-value::after` is masked in, and the
+                // `[data-presents-chooser='false']` block removes it. Asserted
+                // as "not none" rather than against the authored `inline-block`,
+                // because `.adw-row-value` is a flex container and blockifies
+                // its children's display.
+                expect(getComputedStyle(value, '::after').display === 'none').toBe(!presentsChooser);
+                // ...and the ROW being activatable, which on this port is the
+                // overlaid <select> taking clicks at all. Hiding the arrow
+                // without this leaves a row that still opens a one-entry popup.
+                expect(select.disabled).toBe(!presentsChooser);
+
+                host.remove();
+            });
+        }
+
+        await it('gains its arrow back when the model grows past one item', async () => {
+            const { el: row, host } = parse<AdwComboRow>(
+                `<adw-combo-row title="Pick" items='["Only"]'></adw-combo-row>`,
+                'adw-combo-row',
+            );
+            const select = row.querySelector('select') as HTMLSelectElement;
+            expect(select.disabled).toBe(true);
+
+            // `items` is read at connect only, so the model is replaced through
+            // the state the element composes — the same path a consumer has.
+            (
+                row as unknown as { _state: { setOptions(o: { label: string; value: string }[]): void } }
+            )._state.setOptions([
+                { label: 'One', value: 'a' },
+                { label: 'Two', value: 'b' },
+            ]);
+            expect(select.disabled).toBe(false);
+            expect(row.dataset.presentsChooser).toBe('true');
+
+            host.remove();
+        });
     });
 
     await describe('adw-spin-row (SpinState)', async () => {