@gjsify/adwaita-web 0.36.0 → 0.38.0

package/src/adw-carousel.spec.ts

@@ -1,15 +1,9 @@
 // DOM-level conformance tests for <adw-carousel>, driven by the SAME vectors the
 // NativeScript renderer asserts against (`@gjsify/adwaita-core/conformance`).
 //
-// The two renderers used to carry independent, differently-wrong copies of the
-// carousel's arithmetic, and nothing compared them: this element defaulted
-// `allow-scroll-wheel` to FALSE where libadwaita defaults it TRUE (so a plain
-// <adw-carousel> ignored the wheel while its own header claimed the opposite),
-// resolved a half-way position to the LATER page where every libadwaita lookup
-// takes the earlier one, dropped `<adw-carousel position="2">` on the floor,
-// dropped the horizontal-delta fallback its comment described, and emitted
-// `page-changed` only when the index changed — which made the documented -1
-// unreachable. This suite is that comparison.
+// The suite exists because the two renderers used to carry independent,
+// differently-wrong copies of the carousel's arithmetic with nothing comparing them;
+// each rule that drifted is pinned by a test below.
 //
 // Scrolls are made instant by overriding the track's `scroll-behavior`; the
 // element sets it as an inline style precisely so it stays overridable.
@@ -44,10 +38,9 @@ function card(label: string): HTMLElement {
 }
 
 /**
- * Mount a carousel with the given page labels.
- *
- * The host gets an explicit size because the page pitch is MEASURED — a carousel
- * with no width has no distance, and every scroll would be a no-op.
+ * Mount a carousel with the given page labels. The host gets an explicit size because
+ * the page pitch is MEASURED: a carousel with no width has no distance, so every scroll
+ * would be a no-op.
  */
 function mount(labels: readonly string[], attributes: Record<string, string> = {}) {
     const host = document.createElement('div');
@@ -61,10 +54,9 @@ function mount(labels: readonly string[], attributes: Record<string, string> = {
     host.appendChild(carousel);
 
     const track = carousel.querySelector('.adw-carousel-track') as HTMLElement;
-    // Instant scrolls: the assertions are about WHERE it lands, never about the
-    // animation getting there. Snapping is off for the same reason — `mandatory`
-    // re-snaps a programmatic `scrollLeft` to the nearest page, which is exactly
-    // the fractional position several of these tests are about.
+    // Instant scrolls: the assertions are about WHERE it lands, never the animation.
+    // Snapping is off for the same reason — `mandatory` re-snaps a programmatic
+    // `scrollLeft` to the nearest page, the very fractional position under test.
     track.style.setProperty('scroll-behavior', 'auto');
     track.style.setProperty('scroll-snap-type', 'none');
     return { carousel, host, track };
@@ -131,16 +123,15 @@ function applyPageOp(carousel: CarouselElement, op: CarouselPageOp, pages: Map<s
         case 'scrollTo':
         case 'setPosition':
         case 'settle':
-            // Position ops need a settled scroll, so they are driven separately
-            // by the scroll tests below rather than through this replay.
+            // Position ops need a settled scroll and are driven by the scroll tests
+            // below, not through this replay.
             return true;
     }
 }
 
 export const AdwCarouselTest = async () => {
     await describe('adw-carousel page list (libadwaita conformance vectors)', async () => {
-        // Only the structural rows: the element's page methods are what the DOM
-        // exposes, while position ops need a real scroll and are covered below.
+        // Only the structural rows: the page methods are what the DOM exposes.
         const structural = CAROUSEL_PAGE_LIST_VECTORS.filter((vector) =>
             vector.ops.every((op) => op.kind === 'insert' || op.kind === 'remove' || op.kind === 'reorder'),
         );
@@ -157,11 +148,11 @@ export const AdwCarouselTest = async () => {
 
                 expect(results).toStrictEqual([...vector.opResults]);
                 expect(carousel.nPages).toBe(vector.expected.nPages);
-                // The DOM order IS the model order — a reorder that only moved
-                // the model would leave the pages painted where they were.
+                // The DOM order IS the model order: a reorder that moved only the model
+                // would leave the pages painted where they were.
                 expect(domOrder(carousel)).toStrictEqual([...vector.expected.ids]);
-                // And the position compensation reached the scroll container: a
-                // page revealed before the current one must not push it aside.
+                // The position compensation reaches the scroll container: a page revealed
+                // before the current one must not push it aside.
                 expect(carousel.position).toBe(vector.expected.position);
                 host.remove();
             });
@@ -170,17 +161,15 @@ export const AdwCarouselTest = async () => {
 
     await describe('adw-carousel page lookup (libadwaita conformance vectors)', async () => {
         for (const vector of CAROUSEL_PAGE_AT_POSITION_VECTORS) {
-            // Only the rows whose snap points are a settled page list are
-            // reachable through the DOM; the mid-reveal geometry rows need a
-            // reveal ramp this port does not have.
+            // Only rows whose snap points are a settled page list are reachable through
+            // the DOM; mid-reveal geometry rows need a reveal ramp this port lacks.
             const settled = vector.snapPoints.length > 0 && vector.snapPoints.every((point, i) => point === i);
             if (!settled) continue;
 
             await it(`${vector.position} → page ${vector.page} — ${vector.rule}`, async () => {
-                // Driven through the `position` property rather than a real
-                // scroll: a scroll offset is quantised to device pixels, so the
-                // ±1e-7 rows around the tie are not expressible as a drag. The
-                // tie ITSELF is, and gets its own drag test below.
+                // Driven through the `position` property, not a real scroll: a scroll
+                // offset is quantised to device pixels, so the ±1e-7 rows around the tie
+                // are not expressible as a drag. The tie itself is, below.
                 const { carousel, host } = mount(vector.snapPoints.map((_point, index) => `p${index}`));
                 (carousel as unknown as { position: number }).position = vector.position;
                 await flush();
@@ -192,8 +181,8 @@ export const AdwCarouselTest = async () => {
 
     await describe('adw-carousel scroll wheel (scroll_cb)', async () => {
         await it('pages on a mouse wheel WITHOUT being asked to — the default is TRUE', async () => {
-            // The regression pin: this element used to require an explicit
-            // `allow-scroll-wheel` attribute, inverting adw-carousel.c:1103-1106.
+            // This element used to require an explicit `allow-scroll-wheel` attribute,
+            // inverting the libadwaita default.
             const { carousel, host } = mount(['a', 'b', 'c']);
             expect(carousel.allowScrollWheel).toBe(true);
             expect(wheel(carousel, { deltaY: 120 })).toBe(true);
@@ -212,8 +201,8 @@ export const AdwCarouselTest = async () => {
         });
 
         await it('pages on a horizontal delta — the fallback the port dropped', async () => {
-            // adw-carousel.c:554-559. The old code returned early whenever
-            // |deltaY| <= |deltaX|, so a dx-only event did nothing at all.
+            // The old code returned early whenever |deltaY| <= |deltaX|, so a dx-only
+            // event did nothing at all.
             const { carousel, host } = mount(['a', 'b', 'c']);
             expect(wheel(carousel, { deltaX: 120 })).toBe(true);
             await flush();
@@ -222,8 +211,8 @@ export const AdwCarouselTest = async () => {
         });
 
         await it('locks out a second notch for 150 ms', async () => {
-            // adw-carousel.c:22, :526. The old accumulator had no time component
-            // at all, so a fast wheel paged as many times as it had deltas.
+            // The old accumulator had no time component, so a fast wheel paged as many
+            // times as it had deltas.
             const { carousel, host } = mount(['a', 'b', 'c']);
             expect(wheel(carousel, { deltaY: 120 })).toBe(true);
             expect(wheel(carousel, { deltaY: 120 })).toBe(false);
@@ -233,8 +222,8 @@ export const AdwCarouselTest = async () => {
         });
 
         await it('leaves a touchpad gesture to the native scroll-snap', async () => {
-            // A touchpad is ignored outright (:537-538) because its own kinetic
-            // scroll already drives the strip — here, the track's scroll-snap.
+            // A touchpad is ignored outright: its own kinetic scroll already drives the
+            // strip, here the track's scroll-snap.
             const { carousel, host } = mount(['a', 'b', 'c']);
             expect(wheel(carousel, { deltaX: 12, deltaY: 7 })).toBe(false);
             await flush();
@@ -243,8 +232,8 @@ export const AdwCarouselTest = async () => {
         });
 
         await it('does not consume a wheel event it did not act on', async () => {
-            // GDK_EVENT_STOP only when it paged (:561-562 vs :576). The old code
-            // called preventDefault BEFORE its threshold test.
+            // GDK_EVENT_STOP only when it paged; the old code called preventDefault()
+            // BEFORE its threshold test.
             const { carousel, host } = mount(['a', 'b', 'c'], { interactive: 'false' });
             expect(wheel(carousel, { deltaY: 120 })).toBe(false);
             host.remove();
@@ -253,8 +242,8 @@ export const AdwCarouselTest = async () => {
 
     await describe('adw-carousel page-changed (scroll_animation_done_cb)', async () => {
         await it('reports every completed scroll, including back onto the same page', async () => {
-            // The old emission was gated on the ROUNDED index changing, so a
-            // settle back onto the page it started from said nothing.
+            // Gating the emission on the ROUNDED index means a settle back onto the page
+            // it started from says nothing.
             const { carousel, host } = mount(['a', 'b', 'c']);
             const seen: number[] = [];
             carousel.addEventListener('page-changed', (event) => {
@@ -271,8 +260,7 @@ export const AdwCarouselTest = async () => {
         await it('reports the LOWER page for a half-way settle', async () => {
             const { carousel, host } = mount(['a', 'b']);
             await dragTo(carousel, 0.5);
-            // Math.round would have said page 1 here; every libadwaita lookup
-            // resolves the tie downwards (adw-carousel.c:198-201).
+            // Math.round would say page 1; every libadwaita lookup resolves the tie down.
             expect(carousel.currentPage).toBe(0);
             host.remove();
         });
@@ -280,8 +268,8 @@ export const AdwCarouselTest = async () => {
 
     await describe('adw-carousel declarative position', async () => {
         await it('honours <adw-carousel position="2"> at upgrade time', async () => {
-            // Attribute changes are delivered BEFORE connectedCallback, and the
-            // old guard dropped them, so a declared position never applied.
+            // Attribute changes are delivered BEFORE connectedCallback, so a guard that
+            // drops them drops a declared position.
             const { carousel, host } = mount(['a', 'b', 'c'], { position: '2' });
             await flush();
             expect(carousel.currentPage).toBe(2);
@@ -360,9 +348,8 @@ export const AdwCarouselTest = async () => {
 
         await it('turns allow-long-swipes into scroll-snap-stop', async () => {
             // The property used to be inert: both branches of its ternary were
-            // `current + step`. FALSE means "each swipe can only move to the
-            // adjacent pages" (adw-carousel.c:1111-1113), which is what
-            // scroll-snap-stop: always enforces.
+            // `current + step`. FALSE means "each swipe moves only to an adjacent
+            // page", which `scroll-snap-stop: always` enforces.
             const { carousel, host } = mount(['a', 'b', 'c']);
             const slot = carousel.querySelector('.adw-carousel-page') as HTMLElement;
             expect(carousel.allowLongSwipes).toBe(false);
@@ -374,8 +361,8 @@ export const AdwCarouselTest = async () => {
         });
 
         await it('spaces the pages by the spacing property', async () => {
-            // `distance = size + spacing` (adw-carousel.c:767); with no gap in the
-            // track the property would have nowhere to show up.
+            // `distance = size + spacing`; with no gap in the track the property would
+            // have nowhere to show up.
             const { carousel, host, track } = mount(['a', 'b', 'c'], { spacing: '16' });
             expect(track.style.columnGap).toBe('16px');
             // The pitch a drag is measured in must include the gap; if it did not,

package/src/adw-checks.spec.ts

@@ -1,17 +1,15 @@
 // DOM-level tests for <adw-checkbox> and <adw-radio>, plus the browser side of
 // the `RADIO_GROUP_VECTORS` conformance table.
 //
-// THE ONE CLAIM WORTH THE MOST HERE: the browser's native radio exclusivity is
-// NOT enough. `<input type="radio" name="g">` unchecks its sibling INPUT and
-// stops there — the sibling `<adw-radio>` HOST keeps its `checked` attribute,
-// which is the element's published state AND the selector `_checks.scss` paints
-// from, so a group left to the browser draws two selected radios. Every vector
-// below reads back the HOST attribute of every member for exactly that reason.
+// The browser's native radio exclusivity is NOT enough: `<input type="radio" name="g">`
+// unchecks its sibling INPUT and stops there, while the sibling `<adw-radio>` HOST keeps
+// its `checked` attribute — the element's published state and the selector
+// `_checks.scss` paints from — so a group left to the browser draws two selected radios.
+// Every vector below reads back the HOST attribute of every member for that reason.
 //
-// The vectors run under a per-scenario group-name prefix: `RadioGroupState` is
-// document-global by design (as a bare `<input type=radio name=x>` outside a
-// form is), so two scenarios sharing the literal name `colour` would share a
-// selection. The prefix is the isolation, not a change to what is being tested.
+// The vectors run under a per-scenario group-name prefix because `RadioGroupState` is
+// document-global by design (as a bare `<input type=radio name=x>` outside a form is),
+// so two scenarios sharing the literal name `colour` would share a selection.
 
 import { describe, expect, it } from '@gjsify/unit';
 import { RADIO_GROUP_VECTORS } from '@gjsify/adwaita-core/conformance';
@@ -60,12 +58,11 @@ export const AdwChecksTest = async () => {
             expect(input).toBeTruthy();
             expect(input.type).toBe('checkbox');
             expect(indicator).toBeTruthy();
-            // The focus ring is `input:focus-visible ~ .adw-check-indicator`, so
-            // the input MUST precede the indicator.
+            // The focus ring is `input:focus-visible ~ .adw-check-indicator`, so the
+            // input MUST precede the indicator.
             expect(input.nextElementSibling).toBe(indicator);
             expect(el.checked).toBe(false);
             expect(input.getAttribute('aria-checked')).toBe('false');
-            // An empty label takes no space.
             expect(label.hidden).toBe(true);
             parent.remove();
         });
@@ -110,9 +107,8 @@ export const AdwChecksTest = async () => {
         });
 
         await it('a click on the hidden input toggles exactly once', () => {
-            // The input is 0x0 so a pointer never reaches it, but keyboard
-            // activation and `input.click()` do — and the host listener must not
-            // toggle a second time on the way out.
+            // The input is 0x0 so a pointer never reaches it, but keyboard activation and
+            // `input.click()` do — and the host listener must not toggle a second time.
             const { el, parent } = mountCheckbox();
             const events = record(el, 'notify::checked');
             parts(el).input.click();
@@ -143,18 +139,17 @@ export const AdwChecksTest = async () => {
             el.checked = true;
             el.indeterminate = true;
             const { input } = parts(el);
-            // HTML has a native mixed CHECKBOX, and an explicit aria-checked so
-            // the radio (which has no native mixed) reads the same way.
+            // HTML has a native mixed CHECKBOX; the radio has none, so an explicit
+            // aria-checked makes it read the same way.
             expect(input.indeterminate).toBe(true);
             expect(input.getAttribute('aria-checked')).toBe('mixed');
             parent.remove();
         });
 
         await it('draws the dash even when also checked', () => {
-            // `check, radio { &:indeterminate { … dash.svg } }`
-            // (_checks.scss:79-81) is re-declared AFTER both `:checked` rules at
-            // equal specificity, so the dash wins. Comparing the three states
-            // against each other proves the cascade, not just that a mask exists.
+            // In `_checks.scss` the `:indeterminate` glyph is re-declared AFTER both
+            // `:checked` rules at equal specificity, so the dash wins. Comparing all
+            // three states proves the cascade, not just that a mask exists.
             const parent = host();
             const make = (attrs: string[]) => {
                 const el = document.createElement('adw-checkbox') as AdwCheckbox;
@@ -173,7 +168,7 @@ export const AdwChecksTest = async () => {
 
         await it('activating an indeterminate checkbox clears it and checks', () => {
             // HTML's pre-click activation steps, not a reading of
-            // GtkCheckButton:inconsistent — GTK's is not verifiable in this tree.
+            // GtkCheckButton:inconsistent, which is not verifiable in this tree.
             const { el, parent } = mountCheckbox();
             el.indeterminate = true;
             el.click();
@@ -192,33 +187,31 @@ export const AdwChecksTest = async () => {
 
             for (const el of [check, radio]) {
                 const style = getComputedStyle(parts(el).indicator);
-                // GTK sizes the CONTENT box at 14px and grows the drawn control
-                // with `padding: 3px` (_checks.scss:22-26) — content-box, not
-                // the ADR-0010 descendant border-box pin.
+                // GTK sizes the CONTENT box at 14px and grows the drawn control with
+                // `padding: 3px` — content-box, not the ADR-0010 border-box pin.
                 expect(style.width).toBe('14px');
                 expect(style.height).toBe('14px');
                 expect(style.paddingTop).toBe('3px');
             }
 
-            // `check { border-radius: 6px }` (:67-68) vs
-            // `radio { border-radius: 100% }` (:73-74).
+            // `check { border-radius: 6px }` vs
+            // `radio { border-radius: 100% }`.
             expect(getComputedStyle(parts(check).indicator).borderTopLeftRadius).toBe('6px');
             expect(getComputedStyle(parts(radio).indicator).borderTopLeftRadius).toContain('%');
             parent.remove();
         });
 
         await it('a checked radio FILLS, with the SAME accent background as a checked check', () => {
-            // refs/adwaita-web's `_radio.scss:22-33` colours only the border and
-            // the dot, leaving the indicator on the view background; libadwaita
-            // fills the whole control from the block it SHARES with the checkbox
-            // (:52-60). libadwaita wins — so the two fills must be identical.
+            // refs/adwaita-web's `_radio.scss` colours only the border and the dot,
+            // leaving the indicator on the view background; libadwaita fills the whole
+            // control from the block it SHARES with the checkbox, and libadwaita wins —
+            // so the two fills must be identical.
             //
-            // THREE elements rather than one flipped in place: the indicator
-            // TRANSITIONS `background`, so a computed read taken right after
-            // `checked = true` returns the INTERPOLATED colour — still the old
-            // one. Declaring the state before insertion leaves no transition to
-            // be part-way through. The names are distinct so seeding one group
-            // cannot reach the reference radio.
+            // THREE elements rather than one flipped in place: the indicator TRANSITIONS
+            // `background`, so a computed read right after `checked = true` returns the
+            // INTERPOLATED colour. Declaring the state before insertion leaves no
+            // transition part-way through, and distinct names keep seeding one group from
+            // reaching the reference radio.
             const parent = host();
             const plain = document.createElement('adw-radio') as AdwRadio;
             plain.setAttribute('name', 'fill-plain');
@@ -243,8 +236,6 @@ export const AdwChecksTest = async () => {
         for (const [index, vector] of RADIO_GROUP_VECTORS.entries()) {
             await it(`${vector.name} — ${vector.rule}`, () => {
                 const parent = host();
-                // Per-scenario prefix: the registry is document-global, so two
-                // scenarios sharing a literal group name would share a selection.
                 const scope = (name: string) => `v${index}-${name}`;
 
                 const members = vector.members.map(([name, value]) => {
@@ -272,9 +263,8 @@ export const AdwChecksTest = async () => {
                     expect(parts(el).input.checked).toBe(shouldHold);
                 }
 
-                // Every emitted change repaints the winner, and the loser too
-                // when there was one — that second repaint is the whole reason
-                // the group state exists.
+                // Every emitted change repaints the winner AND the loser when there was
+                // one; that second repaint is why the group state exists.
                 const expectedEvents = vector.emitted.reduce(
                     (total, change) => total + (change.deselected === null ? 1 : 2),
                     0,
@@ -327,10 +317,9 @@ export const AdwChecksTest = async () => {
         });
 
         await it('a NAMELESS radio is not in a group', () => {
-            // HTML forms a radio button group only from a non-empty `name`.
-            // Without that rule every nameless radio in the document would land
-            // in one `''` group and fight over it — which is exactly what a
-            // registry keyed by name does if nothing guards the empty key.
+            // HTML forms a radio group only from a non-empty `name`; without that rule
+            // every nameless radio lands in one `''` group and fights over it, which is
+            // what a registry keyed by name does unless it guards the empty key.
             const parent = host();
             const first = document.createElement('adw-radio') as AdwRadio;
             const second = document.createElement('adw-radio') as AdwRadio;

package/src/adw-drop-down.spec.ts

@@ -1,17 +1,14 @@
-// DOM-level behaviour tests for <adw-drop-down>. Runs in a real browser via the
-// @gjsify/adwaita-web browser test axis. Asserts option parsing, selected↔value
-// sync, notify-on-change semantics, popover open/close, item selection, search
-// filtering and the disabled guard.
+// DOM-level behaviour tests for <adw-drop-down>, in a real browser via the
+// @gjsify/adwaita-web browser test axis.
 //
-// The SELECTION half is driven by the SAME table the NativeScript renderer
-// asserts against (`COMBO_SELECTION_VECTORS`, `@gjsify/adwaita-core/conformance`)
-// — replayed against the real element through the API a consumer would use, and
-// read back as what a user would see: the button label, `selected`/`selectedValue`
-// and the `change` stream. `<adw-combo-row>` composes the same `ComboState` but
-// cannot drive the table, because two of its four step ops have no DOM spelling:
-// its options come from the `items` attribute at connect time only (`items` is not
-// even observed), and it publishes no select-by-value setter. So this element is
-// the browser's driver for both.
+// The SELECTION half is driven by the SAME table the NativeScript renderer asserts
+// against (`COMBO_SELECTION_VECTORS`, `@gjsify/adwaita-core/conformance`), replayed
+// through the API a consumer would use and read back as what a user would see: the
+// button label, `selected`/`selectedValue` and the `change` stream. `<adw-combo-row>`
+// composes the same `ComboState` but cannot drive the table — two of its four step ops
+// have no DOM spelling, since its options come from the `items` attribute at connect
+// time only (`items` is not observed) and it publishes no select-by-value setter. So
+// this element is the browser's driver for both.
 import { describe, it, expect } from '@gjsify/unit';
 
 import { COMBO_SELECTION_VECTORS } from '@gjsify/adwaita-core/conformance';
@@ -53,9 +50,8 @@ function applyStep(dd: AdwDropDown, step: ComboSelectionStep): void {
         case 'select':
             openChooser(dd);
             if (step.index < 0) {
-                // The dismissed chooser: the popover closes with nothing picked,
-                // which here is an outside pointerdown rather than a cancelled
-                // native sheet.
+                // The dismissed chooser: the popover closes with nothing picked — here an
+                // outside pointerdown rather than a cancelled native sheet.
                 document.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true }));
                 return;
             }
@@ -65,13 +61,12 @@ function applyStep(dd: AdwDropDown, step: ComboSelectionStep): void {
 }
 
 /**
- * The ONE row this element answers differently, and does so on purpose: its
- * published `selected` contract REJECTS an out-of-range set (`_selectIndex` gates
- * on `ComboState.hasIndex`), where the core state accepts it and reports an empty
- * value — the split `ComboState.hasIndex`'s doc comment records and
- * `<adw-combo-row>` takes the other side of. The row is still driven below,
- * against the element's answer rather than the state's, so neither policy can
- * change silently.
+ * The ONE row this element answers differently, on purpose: its published `selected`
+ * contract REJECTS an out-of-range set (`_selectIndex` gates on `ComboState.hasIndex`)
+ * where the core state accepts it and reports an empty value — the split
+ * `ComboState.hasIndex`'s doc records and `<adw-combo-row>` takes the other side of. The
+ * row is still driven below, against the element's answer, so neither policy can change
+ * silently.
  */
 const DROP_DOWN_REJECTS = 'an index past the end';
 
@@ -102,10 +97,9 @@ export const AdwDropDownTest = async () => {
                 expect(dd.selected).toBe(vector.selected);
                 expect(dd.selectedValue).toBe(vector.value);
                 expect(labelText(dd)).toBe(vector.label);
-                // `change` is this element's DOM spelling of the `interactive`
-                // flag: it fires for a user pick and never for a programmatic
-                // set, so the interactive frames of the emission stream ARE the
-                // events a listener sees.
+                // `change` is this element's DOM spelling of the `interactive` flag: it
+                // fires for a user pick and never for a programmatic set, so the
+                // interactive frames of the stream ARE the events a listener sees.
                 expect(changes).toStrictEqual(
                     vector.emitted
                         .filter((change) => change.interactive)
@@ -119,11 +113,10 @@ export const AdwDropDownTest = async () => {
             const vector = vectorNamed(DROP_DOWN_REJECTS);
             const { dd, changes } = mountRecording();
 
-            // Everything up to the out-of-range set…
             for (const step of vector.steps.slice(0, -1)) applyStep(dd, step);
             const before = { selected: dd.selected, value: dd.selectedValue, label: labelText(dd) };
-            // …and then the set itself, which the core state would accept and
-            // report as nothing-to-draw (`value`/`label` both empty below).
+            // The out-of-range set itself, which the core state would accept and report
+            // as nothing-to-draw (`value`/`label` both empty below).
             expect(vector.value).toBe('');
             expect(vector.label).toBe('');
             applyStep(dd, vector.steps[vector.steps.length - 1]);
@@ -210,8 +203,8 @@ export const AdwDropDownTest = async () => {
         });
 
         await it('setting options + selected before connect does not crash + applies on connect', async () => {
-            // Regression: the property setters ran before connectedCallback built
-            // the DOM, so _updateLabel touched an undefined label element.
+            // The property setters can run BEFORE connectedCallback builds the DOM, where
+            // _updateLabel would touch an undefined label element.
             const dd = document.createElement('adw-drop-down') as AdwDropDown;
             dd.options = ['a', 'b', 'c'];
             dd.selected = 2;

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

@@ -1,14 +1,12 @@
 // DOM-level tests for <adw-header-bar>'s title.
 //
-// `title` was read exactly once, in `connectedCallback`, and the element declared
-// no `observedAttributes` at all — so every later write was a silent no-op. A
-// header bar whose title tracks the open document kept whatever it was created
-// with, and nothing in the build was in a position to notice: the attribute was
-// still THERE, and the element still rendered A title.
+// `title` must be OBSERVED, not read once at `connectedCallback`: a header bar tracking
+// the open document keeps its construction-time title otherwise, and nothing notices
+// because the attribute is still there and A title still renders.
 //
 // `Adw.HeaderBar` builds its centre from `title`/`subtitle` through a derived
-// `AdwWindowTitle` bound to the properties, unless a `title-widget` replaces it
-// — which is the either/or the `slot="center"` case below asserts.
+// `AdwWindowTitle` bound to the properties, unless a `title-widget` replaces it — the
+// either/or the `slot="center"` case below asserts.
 
 import { describe, expect, it } from '@gjsify/unit';
 

package/src/adw-icon.spec.ts

@@ -1,16 +1,11 @@
-// 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.
+// DOM-level tests for <adw-icon>, driven by the SAME `normalizeIconName` vectors the
+// core suite asserts against (`@gjsify/adwaita-core/conformance`).
 //
-// 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.
+// The icon-name class must never be built by hand: a name is only usable once it is
+// known to be a SINGLE CSS token, and hand-built spans skipped that check, so
+// `icon-name="a b"` interpolated a stray second class and shipped it through
+// `<adw-menu-button>` for its own icon and for every JSON menu entry's. The vectors run
+// against the ELEMENT, so hand-building the class again fails naming the input.
 import { describe, expect, it } from '@gjsify/unit';
 
 import { VIEW_STACK_ICON_NAME_VECTORS } from '@gjsify/adwaita-core/conformance';
@@ -39,13 +34,11 @@ export const AdwIconTest = async () => {
                 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.
+                // The base class is unconditional: a nameless icon is still an icon box,
+                // which `<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.
+                // …and NOTHING else is on the node — the assertion a hand-rolled copy
+                // cannot make, where `icon-name="a b"` leaves a stray `b`.
                 expect(extraClasses(el)).toStrictEqual(normalized === '' ? [] : [`adw-icon--${normalized}`]);
                 host.remove();
             });
@@ -66,8 +59,8 @@ export const AdwIconTest = async () => {
             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.
+            // Exactly one mask class at a time, and the caller's are untouched: a
+            // `className =` assignment would take them with it.
             expect(extraClasses(el)).toStrictEqual(['adw-drop-down-arrow', 'adw-icon--go-next', 'start']);
 
             el.iconName = null;
@@ -86,10 +79,9 @@ export const AdwIconTest = async () => {
             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).
+            // Sizing only the box leaves a 16px glyph floating in it. Only the axis 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`).
             expect(styled.maskSize.split(' ')[0]).toBe('32px');
             expect(styled.webkitMaskSize.split(' ')[0]).toBe('32px');
 
@@ -99,10 +91,10 @@ export const AdwIconTest = async () => {
         });
 
         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.
+            // `.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 repaints 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;
@@ -142,10 +134,9 @@ export const AdwIconTest = async () => {
         });
 
         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.
+            // Asserted structurally: a page of every icon-drawing widget, and no bare span
+            // carrying the base class — so a new hand-rolled `<span class="adw-icon …">`
+            // fails here even when it guards its own name correctly.
             const { el: page, host } = mount<HTMLElement>('div');
             page.innerHTML = `
                 <adw-button icon="go-next" label="Next"></adw-button>