@gjsify/adwaita-web 0.36.0 → 0.38.0

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

@@ -1,13 +1,11 @@
 // 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.
+// Three things matter more than the attribute round-trips: the CLAMP is GLib's
+// (`glibClamp` from `@gjsify/adwaita-core`, not a local `Math.min/max`); a ZERO fraction
+// makes the indicator VANISH rather than draw a rounded stub
+// (`> trough.empty > progress { all: unset }` in `_progress-bar.scss`); and the text node
+// really PICKS UP `.dimmed` + `.numeric` from `_labels.scss` — a `@extend` that reached
+// nothing would look identical in the source.
 
 import { describe, expect, it } from '@gjsify/unit';
 
@@ -124,8 +122,8 @@ export const AdwProgressBarTest = async () => {
         });
 
         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
+            // `> text { @extend.dimmed; @extend.numeric; }`
+            // (_progress-bar.scss) — this asserts the extends actually
             // REACHED the utility classes, which a source read cannot tell.
             const { el, host } = mount();
             el.showText = true;
@@ -138,8 +136,8 @@ export const AdwProgressBarTest = async () => {
 
     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
+            // The 8px is libadwaita's (_progress-bar.scss) and the 2px is its
+            // `.osd` variant — 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

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

@@ -85,15 +85,14 @@ export const AdwRowStateTest = async () => {
                 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.
+                // 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.
                 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.
+                // …and the ROW being activatable, which here is the overlaid <select>
+                // taking clicks at all: hiding the arrow alone leaves a row that still
+                // opens a one-entry popup.
                 expect(select.disabled).toBe(!presentsChooser);
 
                 host.remove();
@@ -108,8 +107,8 @@ export const AdwRowStateTest = async () => {
             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.
+            // `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([

package/src/adw-shortcut-label.spec.ts

@@ -0,0 +1,112 @@
+// <adw-shortcut-label> against `SHORTCUT_LABEL_VECTORS` — the same table the
+// core suite drives, so a divergence between the parse and what this element
+// actually renders fails a test naming the accelerator.
+//
+// The serialiser below walks the REAL DOM and produces the table's compact form.
+// That is the whole point of the shared format: if this file built its own
+// expectation strings instead, the two suites could agree with each other while
+// both disagreeing with libadwaita.
+import { describe, expect, it } from '@gjsify/unit';
+import { SHORTCUT_LABEL_VECTORS } from '@gjsify/adwaita-core/conformance';
+
+import '@gjsify/adwaita-web';
+
+/** The rendered element in the table's compact form (see conformance/shortcut-label.ts). */
+const serialize = (host: HTMLElement): string =>
+    [...host.children]
+        .map((child) => {
+            if (child.classList.contains('adw-shortcut-label-disabled'))
+                return `(disabled: ${child.textContent ?? ''})`;
+            if (child.classList.contains('dimmed')) return child.textContent ?? '';
+
+            return [...child.children]
+                .map((cap) => {
+                    const side = cap.querySelector('.adw-shortcut-label-side');
+                    // The marker rides INSIDE the keycap, so its text has to come
+                    // back out of the label before the two are compared.
+                    const label = (cap.textContent ?? '').slice(
+                        0,
+                        (cap.textContent ?? '').length - (side?.textContent?.length ?? 0),
+                    );
+                    return `[${side ? `${label} (${side.textContent})` : label}]`;
+                })
+                .join('');
+        })
+        .join(' ')
+        .trim();
+
+export const AdwShortcutLabelTest = async () => {
+    await describe('<adw-shortcut-label> (conformance vectors)', async () => {
+        for (const vector of SHORTCUT_LABEL_VECTORS) {
+            // The Apple glyph set is a build constant in the C and an option in
+            // core; the ELEMENT reads its platform from nothing, so the two
+            // Apple rows have no element to drive. They stay core-only.
+            if (vector.platform === 'apple') continue;
+
+            await it(`${vector.accelerator || '(empty)'} — ${vector.rule}`, async () => {
+                const host = document.createElement('adw-shortcut-label');
+                host.setAttribute('accelerator', vector.accelerator);
+                if (vector.disabledText !== undefined) host.setAttribute('disabled-text', vector.disabledText);
+                // RTL comes from the rendered direction, so the vector's
+                // direction has to be a real attribute on a CONNECTED element.
+                if (vector.direction === 'rtl') host.setAttribute('dir', 'rtl');
+                document.body.appendChild(host);
+
+                expect(serialize(host)).toBe(vector.expected);
+                if (vector.accessibleLabel !== undefined) {
+                    expect(host.getAttribute('aria-label')).toBe(vector.accessibleLabel);
+                }
+
+                host.remove();
+            });
+        }
+
+        await it('re-renders when the accelerator changes', async () => {
+            const host = document.createElement('adw-shortcut-label');
+            host.setAttribute('accelerator', '<Control>C');
+            document.body.appendChild(host);
+
+            let notified = 0;
+            host.addEventListener('notify::accelerator', () => notified++);
+            host.setAttribute('accelerator', '<Control>V');
+
+            expect(serialize(host)).toBe('[Ctrl][V]');
+            expect(notified).toBe(1);
+
+            host.remove();
+        });
+
+        await it('draws the keycaps of one combination left-to-right inside an RTL context', async () => {
+            // `gtk_widget_set_direction (box, GTK_TEXT_DIR_LTR)` (:380): the
+            // modifier order belongs to the shortcut, not to the surrounding
+            // text — only the SEQUENCE arrow flips.
+            const host = document.createElement('adw-shortcut-label');
+            host.setAttribute('dir', 'rtl');
+            host.setAttribute('accelerator', '<Control>C+<Control>X');
+            document.body.appendChild(host);
+
+            const box = host.querySelector<HTMLElement>('.adw-shortcut-label-keys');
+            expect(box?.getAttribute('dir')).toBe('ltr');
+            expect(getComputedStyle(box as HTMLElement).direction).toBe('ltr');
+            expect(host.querySelector('.dimmed')?.textContent).toBe('←');
+
+            host.remove();
+        });
+
+        await it('gives its keycaps the styling libadwaita gives them', async () => {
+            // The rule exists, and it reaches the node the element builds — the
+            // half a class-name assertion cannot see (`_shortcuts-dialog.scss:42-53`).
+            const host = document.createElement('adw-shortcut-label');
+            host.setAttribute('accelerator', '<Control>C');
+            document.body.appendChild(host);
+
+            const cap = host.querySelector<HTMLElement>('.keycap');
+            const style = getComputedStyle(cap as HTMLElement);
+            expect(style.borderTopLeftRadius).toBe('6px');
+            expect(style.paddingTop).toBe('6px');
+            expect(Number.parseFloat(style.minWidth)).toBe(20);
+
+            host.remove();
+        });
+    });
+};

package/src/adw-sidebar.spec.ts

@@ -1,13 +1,10 @@
 // DOM-level conformance tests for <adw-sidebar>, driven by the SAME vectors the
 // NativeScript renderer asserts against (`@gjsify/adwaita-core/conformance`).
 //
-// The two renderers used to carry independent selection logic, and it had
-// drifted apart AND away from libadwaita: `selected = 5` on a 3-item sidebar
-// gave "no selection" in GTK, `2` here (it clamped to the last row) and `0` on
-// NativeScript (it dropped the write). This element also keyed section headers
-// off the DECLARATION index, so an empty leading section drew a stray separator
-// and cost the next section its `.first` flush-to-top padding. Nothing failed,
-// because nothing compared them. This suite is that comparison.
+// Two rules independent selection logic drifted from: an out-of-range `selected` means
+// NO selection in GTK, not a clamp to the last row and not a dropped write; and section
+// headers key off the RENDERED index, not the declaration index, or an empty leading
+// section draws a stray separator and costs the next section its `.first` padding.
 import { describe, expect, it } from '@gjsify/unit';
 
 import type { AdwSidebarItemSpec, AdwSidebarSectionSpec } from '@gjsify/adwaita-core';
@@ -22,9 +19,8 @@ import {
 import type { AdwSidebar } from './elements/adw-sidebar.js';
 
 /**
- * Mount a sidebar built from DECLARED children, the way an author writes it —
- * the element consumes them at connect time, so they all have to exist before
- * the host is appended.
+ * Mount a sidebar from DECLARED children, the way an author writes it: the element
+ * consumes them at connect time, so they must all exist before the host is appended.
  */
 function mountSidebar(
     sections: ReadonlyArray<AdwSidebarSectionSpec>,
@@ -144,8 +140,8 @@ export const AdwSidebarTest = async () => {
         }
 
         await it('draws no section container for a section that renders no rows', () => {
-            // The old element appended a header AND an empty `.adw-sidebar-section`
-            // per DECLARED section, which in page mode is a visible empty card.
+            // A header plus an empty `.adw-sidebar-section` per DECLARED section is a
+            // visible empty card in page mode.
             const { sidebar, host } = mountSidebar([{ title: 'Empty', items: [] }, { items: [{ title: 'A' }] }]);
             expect(sidebar.querySelectorAll('.adw-sidebar-section')).toHaveLength(1);
             expect(headersOf(sidebar)).toHaveLength(0);
@@ -303,10 +299,9 @@ export const AdwSidebarTest = async () => {
         });
 
         await it('follows a declared item attribute change without touching the selection', () => {
-            // <adw-sidebar-item> declared `observedAttributes` with no
-            // attributeChangedCallback behind it, so every post-construction
-            // change was silently lost. The declared element is detached once
-            // consumed, so the link back to its spec cannot be a DOM lookup.
+            // `observedAttributes` with no attributeChangedCallback behind it loses every
+            // post-construction change. The declared element is detached once consumed, so
+            // the link back to its spec cannot be a DOM lookup.
             const declared = createItem({ title: 'A' });
             const sectionEl = document.createElement('adw-sidebar-section');
             sectionEl.append(declared, createItem({ title: 'B' }));
@@ -330,15 +325,13 @@ export const AdwSidebarTest = async () => {
         });
     });
 
-    // A row's own box, which nothing had ever measured.
+    // A row's own BOX, which asking what a row contains never measures.
     //
-    // `.adw-sidebar-item` carried `width: 100%` ON TOP of `margin: 0 6px 2px`.
-    // The list is a column flex container, so a row already stretches to it and
-    // stretching subtracts margins; `width: 100%` resolves against the
-    // containing block instead, which does not, so every row came out 12px too
-    // wide — inset on the left, hanging past the right edge with its rounded
-    // corners clipped away. Every earlier test asked what a row CONTAINED, so
-    // all of them passed.
+    // `width: 100%` on top of `margin: 0 6px 2px` makes a row 12px too wide: the list is a
+    // column flex container, so the row already stretches to it and stretching subtracts
+    // margins, while `width: 100%` resolves against the containing block, which does not —
+    // leaving the row inset on the left and hanging past the right edge with its rounded
+    // corners clipped.
     await describe('a sidebar row sits inside its list, not over its edge', async () => {
         await it('leaves the same margin on both sides', async () => {
             const { sidebar, host } = mountSidebar([{ items: [{ title: 'Inbox' }, { title: 'Starred' }] }], {

package/src/adw-switch.spec.ts

@@ -1,20 +1,14 @@
-// DOM-level tests for <adw-switch>, plus the REGRESSION PROOF that lifting it
-// out of <adw-switch-row> and <adw-expander-row> left both rows working.
+// DOM-level tests for <adw-switch>, plus the proof that both <adw-switch-row> and
+// <adw-expander-row> still work now that the switch is lifted out of them. Two
+// invariants:
 //
-// What the extraction removed: `_expander_row.scss:73-121` was a
-// character-for-character copy of `_switch_row.scss:15-63` (same 44×24 box, same
-// hidden input, same 20px knob, same `translateX(20px)`, same focus ring),
-// because `_switch_row.scss:9` opened `adw-switch-row {` and nested `.adw-switch`
-// inside it — so the class did not exist anywhere else and the expander row could
-// not reuse it. Two consequences this suite pins down:
-//
-//   - the GEOMETRY now comes from ONE unscoped partial. `measure()` compares the
-//     computed box of the row's switch against the expander's; before the lift
-//     they were two independently-maintained blocks that happened to agree, and
-//     deleting either one silently unstyled its widget.
-//   - the EVENTS are unchanged. Both rows compose an element that emits its own
-//     `notify::active`, so each row stops it at the switch and publishes its own
-//     name — a row listener must still see exactly one event per toggle.
+//   - the GEOMETRY comes from ONE unscoped partial, so `measure()` compares the
+//     computed box of the row's switch against the expander's. Scoping `.adw-switch`
+//     inside `adw-switch-row {` is what forced the expander row to keep a duplicate
+//     block, where deleting either copy silently unstyled its widget.
+//   - the EVENTS are unchanged: both rows compose an element emitting its own
+//     `notify::active`, so each row stops it at the switch and publishes under its own
+//     name — a row listener must see exactly one event per toggle.
 import { describe, expect, it } from '@gjsify/unit';
 
 import type { AdwExpanderRow } from './elements/adw-expander-row.js';
@@ -59,7 +53,7 @@ export const AdwSwitchTest = async () => {
             expect(el.active).toBe(false);
             expect(input).toBeTruthy();
             expect(input.checked).toBe(false);
-            // The focus ring is `input:focus-visible + .adw-switch-slider`, so the
+            // The focus ring is `input:focus-visible +.adw-switch-slider`, so the
             // slider MUST be the input's immediate next sibling.
             expect(input.nextElementSibling).toBe(slider);
             expect(el.classList.contains('adw-switch')).toBe(true);

package/src/adw-tab-view.spec.ts

@@ -1,12 +1,9 @@
-// DOM-level behaviour tests for <adw-tab-view>. Runs in a real browser via the
-// @gjsify/adwaita-web browser test axis (the entry self-applies the compiled
-// stylesheet, so computed-style assertions are valid). Asserts page building,
-// selected↔click sync, notify/close events, and the expand-tabs / no-close
-// attributes — i.e. the DOM/CSS surface.
+// The DOM/CSS surface of <adw-tab-view>, in a real browser via the @gjsify/adwaita-web
+// test axis — the entry self-applies the compiled stylesheet, so computed-style
+// assertions are valid.
 //
-// The MODEL is asserted in `tab-view.spec.ts`, against the shared libadwaita
-// conformance vectors. Keep the split: this file is about markup and computed
-// style, that one is about behaviour both renderers must agree on.
+// Keep the split: the MODEL is asserted in `tab-view.spec.ts` against the shared
+// libadwaita conformance vectors, this file is markup and computed style only.
 import { describe, expect, it } from '@gjsify/unit';
 
 import type { AdwTabView } from './elements/adw-tab-view.js';
@@ -65,10 +62,10 @@ export const AdwTabViewTest = async () => {
             expect(closed).toBe(1);
             // The element used to emit and remove NOTHING, so every close was
             // permanently denied; the default handler now confirms a non-pinned
-            // page (close_page_cb, adw-tab-view.c:1990-1991).
+            // page (close_page_cb).
             expect(view.querySelectorAll('.adw-tab').length).toBe(2);
             // Closing a page BEFORE the selection must not also select the tab,
-            // and must leave the selected PAGE selected (adw-tab-view.c:1864-1865).
+            // and must leave the selected PAGE selected.
             expect(view.selected).toBe(0);
             view.parentElement?.remove();
         });

package/src/adw-toast-overlay.spec.ts

@@ -1,16 +1,12 @@
-// DOM-level behaviour tests for <adw-toast-overlay>. Runs in a real browser via
-// the @gjsify/adwaita-web browser test axis.
+// DOM-level behaviour tests for <adw-toast-overlay>, in a real browser via the
+// @gjsify/adwaita-web browser test axis.
 //
-// The regression these guard: the overlay used to append EVERY toast as its own
-// strip the moment `addToast()` was called, so three calls stacked three visible
-// toasts and each ran its own timer. `Adw.ToastOverlay` shows exactly ONE toast
-// at a time and queues the rest FIFO, advancing only when the visible one is
-// dismissed (manually or by its timeout) — the policy `AdwToastQueue` in
-// `@gjsify/adwaita-core` owns and this element now composes.
+// `Adw.ToastOverlay` shows exactly ONE toast at a time and queues the rest FIFO,
+// advancing only when the visible one is dismissed (manually or by its timeout) — the
+// policy `AdwToastQueue` owns in `@gjsify/adwaita-core` and this element composes.
 //
-// Timing is driven through core's injected `ToastScheduler` seam (a virtual
-// clock), so the auto-dismiss lifecycle is asserted deterministically with no
-// real timers.
+// Timing runs through core's injected `ToastScheduler` seam (a virtual clock), so the
+// auto-dismiss lifecycle is deterministic with no real timers.
 import { describe, expect, it } from '@gjsify/unit';
 
 import type { AdwToastOverlay, ToastScheduler, ToastTimerHandle } from './elements/adw-toast-overlay.js';

package/src/adw-view-switcher-bar.spec.ts

@@ -1,17 +1,13 @@
-// adw-view-switcher-bar visibility regression (browser axis). Guards that the
-// derived reveal state actually shows/hides the bar. The bar's base scss sets
-// `display: block`, an AUTHOR rule that would defeat the UA `[hidden]{display:none}`
-// the component relies on (cascade origin beats specificity) — so an unrevealed
-// bar rendered visible until scss/_view_switcher_bar.scss re-asserted
-// `&[hidden] { display: none }`. This test pins that fix.
+// That the derived reveal state actually shows and hides the bar. The bar's base scss
+// sets `display: block`, an AUTHOR rule that defeats the UA `[hidden]{display:none}` the
+// component relies on (cascade origin beats specificity), so
+// `scss/_view_switcher_bar.scss` has to re-assert `&[hidden] { display: none }`.
 //
-// It now stages the bar against a real two-page <adw-view-stack>, because the
-// request alone is no longer enough: `update_bar_revealed` reveals the bar only
-// when `reveal` is set AND MORE THAN ONE page is visible
-// (refs/libadwaita/src/adw-view-switcher-bar.c:104-126), a rule the port used to
-// skip entirely. The one-page case is asserted here too — it is the state the old
-// bar rendered as an empty strip. The full derivation is driven from the shared
-// conformance vectors in `view-switcher.spec.ts`.
+// Staged against a real two-page <adw-view-stack>, because the request alone is not
+// enough: `update_bar_revealed` (refs/libadwaita/src/adw-view-switcher-bar.c) reveals
+// the bar only when `reveal` is set AND MORE THAN ONE page is visible. The one-page case
+// is asserted here too. The full derivation is driven from the shared conformance
+// vectors in `view-switcher.spec.ts`.
 import { describe, expect, it } from '@gjsify/unit';
 
 import type { AdwViewStack } from './elements/adw-view-stack.js';
@@ -66,7 +62,7 @@ export const AdwViewSwitcherBarTest = async () => {
         });
 
         await it('stays collapsed for a ONE-page stack, however loudly the layout asks', () => {
-            // `count > 1` (adw-view-switcher-bar.c:125). The old bar showed an
+            // `count > 1`. The old bar showed an
             // empty strip here because it never consulted the page count.
             const { bar, host } = mountBar(1);
             bar.reveal = true;

package/src/adw-wrap-box.spec.ts

@@ -1,24 +1,17 @@
 // DOM-level conformance tests for <adw-wrap-box>, driven by the SAME tables the
 // NativeScript renderer asserts against (`@gjsify/adwaita-core/conformance`).
 //
-// There were no wrap-box specs at all, which is how sixteen divergences from
-// `Adw.WrapBox` sat untouched (issue #1048). Three of them were wrong answers to
-// the one question that IS portable — where a line's leftover space goes:
+// The portable question is where a line's leftover space goes, and three `Adw.WrapBox`
+// rules answer it: `align` is a MAIN-axis offset of the whole line block, not
+// `align-items` on the cross axis (writing it there pushes children DOWN); `fill` grows
+// the CHILDREN where `spread` grows the GAPS, so they are not both `space-between`; and
+// `justify-last-line` governs the final line, whose C default is NOT justified.
 //
-//   - `align` was written to `align-items`, the CROSS axis, where libadwaita
-//     applies it as a MAIN-axis offset of the whole line block
-//     (adw-wrap-layout.c:717-725), so `align="1"` pushed children DOWN;
-//   - `JUSTIFY_MAP` mapped `fill` and `spread` to the same `space-between`,
-//     where C grows the CHILDREN for one and the GAPS for the other
-//     (adw-wrap-layout.c:317-341);
-//   - `justify-last-line` was observed and never read, so the final line was
-//     always justified — the opposite of the C default (adw-wrap-box.c:379-381).
-//
-// The element publishes its resolved decision as `data-line-justify` (what
-// governs a complete line) and `data-last-line-justify` (what governs the final
-// one), which is both what the stylesheet keys off and what these vectors read:
-// the rendered `justify-content` / `flex-grow` are asserted alongside, so a
-// correct data attribute with a stylesheet that ignores it still fails.
+// The element publishes its resolved decision as `data-line-justify` (complete lines)
+// and `data-last-line-justify` (the final one) — what the stylesheet keys off and what
+// these vectors read. The rendered `justify-content` / `flex-grow` are asserted
+// alongside, so a correct data attribute with a stylesheet that ignores it still
+// fails.
 
 import { describe, expect, it } from '@gjsify/unit';
 
@@ -61,10 +54,9 @@ function label(value: unknown): string {
 /**
  * `justify-content` for an un-justified line at `align`.
  *
- * C offsets the line block by `roundf (length_delta * align)`, a continuum;
- * flexbox has three positions, so the port takes the nearest one. That
- * approximation lives here rather than in the vectors because it is the browser
- * renderer's, not libadwaita's.
+ * C offsets the line block by `roundf (length_delta * align)`, a continuum, where
+ * flexbox has three positions — so the port takes the nearest. The approximation lives
+ * here rather than in the vectors because it is the browser renderer's, not libadwaita's.
  */
 function expectedJustifyContent(align: number): string {
     if (align < 0.25) return 'flex-start';
@@ -82,10 +74,9 @@ export const AdwWrapBoxTest = async () => {
             await it(`${title}: ${vector.rule}`, () => {
                 const attrs: Record<string, string> = { justify: vector.justify, align: String(vector.align) };
                 if (vector.justifyLastLine) attrs['justify-last-line'] = '';
-                // A box with ONE child has exactly one line, and that line is the
-                // final one — the only line membership CSS can know without a
-                // layout pass, and the reason the stylesheet has an `:only-child`
-                // rule at all.
+                // A box with ONE child has exactly one line and it is the final one — the
+                // only line membership CSS can know without a layout pass, and why the
+                // stylesheet has an `:only-child` rule.
                 const childCount = vector.childrenInLine === 1 ? 1 : 3;
                 const { box, children } = mountWrapBox(attrs, childCount);
 
@@ -93,9 +84,8 @@ export const AdwWrapBoxTest = async () => {
                 expect(resolved).toBe(vector.layout.justify);
 
                 if (!vector.lastLine && vector.childrenInLine > 1) {
-                    // `justify-content` is the container knob, and a flex
-                    // container applies it to every line — so it carries the
-                    // COMPLETE-line rule.
+                    // `justify-content` is the container knob and a flex container applies
+                    // it to every line, so it carries the COMPLETE-line rule.
                     expect(getComputedStyle(box).justifyContent).toBe(
                         vector.layout.growGaps ? 'space-between' : expectedJustifyContent(vector.layout.align),
                     );
@@ -114,7 +104,7 @@ export const AdwWrapBoxTest = async () => {
             const style = getComputedStyle(box);
             expect(style.justifyContent).toBe('flex-end');
             // The cross axis is libadwaita's `h = line_size` — every child takes
-            // the full line extent (adw-wrap-layout.c:746-751).
+            // the full line extent.
             expect(style.alignItems).toBe('stretch');
             unmountAll();
         });
@@ -134,9 +124,8 @@ export const AdwWrapBoxTest = async () => {
 
         await it('a spread box whose last line is not justified gets the filler that packs it', () => {
             const { box } = mountWrapBox({ justify: 'spread' });
-            // The only per-line hook flexbox offers: a generated flex item on the
-            // final line that absorbs its leftover, so the line packs at the start
-            // the way an un-justified line does.
+            // The only per-line hook flexbox offers: a generated flex item on the final
+            // line absorbs its leftover, so the line packs at the start.
             expect(getComputedStyle(box, '::after').flexGrow).toBe('1');
             unmountAll();
 
@@ -216,8 +205,8 @@ export const AdwWrapBoxTest = async () => {
         });
 
         for (const { value, unit, dpi, px, rule } of WRAP_BOX_LENGTH_VECTORS) {
-            // The element resolves at the default dpi; the scaled rows are the
-            // core suite's, since a browser has no `gtk-xft-dpi` to report.
+            // The element resolves at the default dpi; the scaled rows are the core
+            // suite's, since a browser has no `gtk-xft-dpi` to report.
             if (dpi !== 96 || value < 0) continue;
             await it(`child-spacing ${value}${String(unit)} → ${px}px: ${rule}`, () => {
                 const attrs: Record<string, string> = { 'child-spacing': String(value) };
@@ -314,8 +303,8 @@ export const AdwWrapBoxTest = async () => {
                     return view;
                 };
                 for (const id of children) box.appendChild(make(id));
-                // The child being placed may be one of the mounted ones (a
-                // reorder, or the "already parented" refusal) or a fresh one.
+                // The child placed may be one of the mounted ones (a reorder, or the
+                // "already parented" refusal) or a fresh one.
                 const target = byId.get(child) ?? make(child);
                 // A sibling the box does not have still has to be a real element.
                 const after = sibling === null ? null : (byId.get(sibling) ?? make(sibling));