@gjsify/adwaita-web 0.36.0 → 0.37.0

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));

package/src/bottom-sheet.spec.ts

@@ -2,18 +2,15 @@
 // the core suite and the NativeScript renderer assert against
 // (`@gjsify/adwaita-core/conformance`).
 //
-// `Adw.BottomSheet` has four dismissal paths and they are four different gates.
-// This element used to route all of them through one `_attemptClose()`, which
-// meant: the drag handle closed the sheet (in libadwaita it is `can_target =
-// FALSE` and closes nothing), Escape on a closed-but-focused sheet did nothing
-// (libadwaita still signals `close-attempt`), and the `sheet.close` action on an
-// already-closed sheet did nothing (libadwaita forwards it to the parent).
-// Nothing failed, because nothing compared the element to the C source.
+// `Adw.BottomSheet` has four dismissal paths and they are four DIFFERENT gates, so one
+// shared `_attemptClose()` cannot express them: the drag handle is `can_target = FALSE`
+// and closes nothing; Escape on a closed-but-focused sheet still signals
+// `close-attempt`; and the `sheet.close` action on an already-closed sheet forwards to
+// the parent.
 //
-// Two element-local bugs are pinned here too, both from the same root cause —
-// the open STATE used to be read off the attribute rather than held:
-// `open="false"` rendered OPEN, and re-spelling the attribute fired a
-// `notify::open` carrying an unchanged payload.
+// The open STATE must be HELD, not read back off the attribute — reading it made
+// `open="false"` render OPEN and let a re-spelt attribute fire a `notify::open` with an
+// unchanged payload.
 import { describe, expect, it } from '@gjsify/unit';
 
 import type { AdwBottomSheet } from './elements/adw-bottom-sheet.js';
@@ -75,8 +72,8 @@ export const AdwBottomSheetTest = async () => {
                 });
 
                 expect(returned).toBe(outcome);
-                // The verdict must be VISIBLE, not just returned: a renderer that
-                // returns the right word and closes anyway is still wrong.
+                // The verdict must be VISIBLE, not just returned: returning the right word
+                // and closing anyway is still wrong.
                 expect(sheet.open).toBe(outcome === 'close' ? false : open);
                 expect(attempts).toBe(outcome === 'close-attempt' ? 1 : 0);
                 expect(delegated).toBe(outcome === 'delegate' ? 1 : 0);
@@ -120,9 +117,9 @@ export const AdwBottomSheetTest = async () => {
 
     await describe('adw-bottom-sheet open attribute semantics', async () => {
         await it('open="false" renders CLOSED', () => {
-            // The getter used to be `hasAttribute('open')` while every other
-            // boolean used `!== 'false'`, so one element carried two conventions.
-            // adw-bottom-sheet.c:1670 — `open = !!open` on a strict gboolean.
+            // `hasAttribute('open')` for the getter while every other boolean uses
+            // `!== 'false'` gives one element two conventions.
+            // adw-bottom-sheet.c — `open = !!open` on a strict gboolean.
             const sheet = document.createElement('adw-bottom-sheet') as AdwBottomSheet;
             sheet.setAttribute('open', 'false');
             document.body.appendChild(sheet);
@@ -141,10 +138,9 @@ export const AdwBottomSheetTest = async () => {
         });
 
         await it('re-spelling the attribute fires no spurious notify::open', () => {
-            // The old callback guarded only `oldValue === newValue` and then
-            // dispatched unconditionally, so `open=""` → `open="open"` fired a
-            // second notification carrying an UNCHANGED payload.
-            // adw-bottom-sheet.c:1672-1682 returns before notifying.
+            // Guarding only on `oldValue === newValue` lets `open=""` → `open="open"` fire
+            // a second notification carrying an UNCHANGED payload.
+            // adw-bottom-sheet.c returns before notifying.
             const sheet = mountSheet();
             const payloads: boolean[] = [];
             sheet.addEventListener('notify::open', (event) => {
@@ -170,9 +166,8 @@ export const AdwBottomSheetTest = async () => {
 
     await describe('adw-bottom-sheet affordances', async () => {
         await it('the drag handle is decorative — not focusable, not a button, closes nothing', () => {
-            // gtk_widget_set_can_focus/can_target (self->drag_handle, FALSE)
-            // — adw-bottom-sheet.c:1197-1198. This element used to give it
-            // role="button", tabindex=0 and a click-to-close handler.
+            // `gtk_widget_set_can_focus/can_target (self->drag_handle, FALSE)` — so no
+            // role="button", no tabindex=0 and no click-to-close handler.
             const sheet = mountSheet();
             sheet.open = true;
             const handle = dragHandle(sheet);
@@ -207,8 +202,8 @@ export const AdwBottomSheetTest = async () => {
         });
 
         await it('a dimming click on a CLOSED sheet does nothing and signals nothing', () => {
-            // The scrim is `can_target = open` (adw-bottom-sheet.c:1692), so it
-            // is not reachable at all — unlike Escape, it does not signal.
+            // The scrim is `can_target = open`, so it is not reachable at all — unlike
+            // Escape, it does not signal.
             const sheet = mountSheet();
             sheet.canClose = false;
             const { attempts } = recordSignals(sheet, () => {
@@ -228,10 +223,9 @@ export const AdwBottomSheetTest = async () => {
         });
 
         await it('Escape on a CLOSED but focused sheet still raises close-attempt', () => {
-            // maybe_close_cb's emit is the fallthrough for every case that is not
-            // (can_close && open) — adw-bottom-sheet.c:393-399. This element
-            // guarded it away twice (once in the key handler, once in
-            // `_attemptClose`), so the corner was unreachable.
+            // `maybe_close_cb`'s emit is the fallthrough for every case that is NOT
+            // (can_close && open); guarding it away in the key handler and in
+            // `_attemptClose` makes the corner unreachable.
             const sheet = mountSheet();
             const { attempts } = recordSignals(sheet, () => {
                 insideSheet(sheet).dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
@@ -254,9 +248,9 @@ export const AdwBottomSheetTest = async () => {
         });
 
         await it('sheet.close on an already-closed sheet delegates upward', () => {
-            // sheet_close_cb activates the PARENT's `sheet.close` action instead
-            // of doing nothing — adw-bottom-sheet.c:382-385. A bubbling event is
-            // the DOM equivalent, so an enclosing sheet/dialog can act on it.
+            // `sheet_close_cb` activates the PARENT's `sheet.close` action rather than
+            // doing nothing; a bubbling event is the DOM equivalent, so an enclosing
+            // sheet or dialog can act on it.
             const sheet = mountSheet();
             const host = sheet.parentElement as HTMLElement;
             let seenOnAncestor = 0;
@@ -278,10 +272,10 @@ export const AdwBottomSheetTest = async () => {
         });
 
         await it('consumes the slot wrappers instead of leaving them in the content', () => {
-            // `<child type="sheet">` is GtkBuilder markup — nothing of it survives
-            // into the widget tree (adw-bottom-sheet.c:1278-1293). The emptied
-            // <adw-bottom-sheet-sheet> / <adw-bottom-sheet-content> wrappers used
-            // to fall through to `unslotted` and land in the content layer.
+            // `<child type="sheet">` is GtkBuilder markup and nothing of it survives into
+            // the widget tree, so the emptied <adw-bottom-sheet-sheet> /
+            // <adw-bottom-sheet-content> wrappers must not fall through to `unslotted` and
+            // land in the content layer.
             const sheet = mountSheet();
             const content = sheet.querySelector('.adw-bottom-sheet-content') as HTMLElement;
             expect(Array.from(content.children).map((el) => el.tagName.toLowerCase())).toStrictEqual(['button']);

package/src/breakpoints.ts

@@ -8,10 +8,9 @@
 // `ResizeObserver` — which this module supplies under the same name, so the two
 // ports read alike.
 //
-// Until this existed, `adwaita-web` was the only one of the three renderers with
-// no size source at all: `<adw-navigation-split-view collapsed>` was a manual
-// attribute the application had to flip itself, so the same markup that adapts
-// on GTK and on NativeScript stayed frozen in one layout in the browser.
+// Without a size source `<adw-navigation-split-view collapsed>` is a manual attribute the
+// application has to flip itself, and markup that adapts on GTK and on NativeScript stays
+// frozen in one layout in the browser.
 //
 // Reference: refs/libadwaita/src/adw-breakpoint.c
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
@@ -21,19 +20,17 @@ import { AdwBreakpoint } from '@gjsify/adwaita-core';
 /**
  * Drive `breakpoints` from `element`'s own box, and return a dispose function.
  *
- * `ResizeObserver` delivers an initial observation on `observe()`, so the
- * breakpoints settle on the correct state before first paint — no flash of the
- * wrong layout, and no separate seeding pass.
- *
- * The size read is the BORDER box in CSS pixels, the browser's counterpart to
- * the `sp`/DIP units an Adwaita condition is written in.
+ * `ResizeObserver` delivers an initial observation on `observe()`, so the breakpoints
+ * settle on the correct state before first paint — no flash of the wrong layout, no
+ * separate seeding pass. The size read is the BORDER box in CSS pixels, the browser's
+ * counterpart to the `sp`/DIP units an Adwaita condition is written in.
  */
 export function addBreakpoints(element: Element, breakpoints: readonly AdwBreakpoint[]): () => void {
     const observer = new ResizeObserver((entries) => {
         const entry = entries[entries.length - 1];
         if (!entry) return;
-        // borderBoxSize is the spec'd path; contentRect is the fallback for the
-        // shape older engines report.
+        // borderBoxSize is the spec'd path; contentRect is the fallback for the shape older
+        // engines report.
         const box = entry.borderBoxSize?.[0];
         const size = box
             ? { width: box.inlineSize, height: box.blockSize }
@@ -45,13 +42,13 @@ export function addBreakpoints(element: Element, breakpoints: readonly AdwBreakp
 }
 
 /**
- * Wire a `breakpoint="<condition>"` attribute to a boolean setter, the browser
- * equivalent of an `Adw.Breakpoint` with one `add_setter()` call.
+ * Wire a `breakpoint="<condition>"` attribute to a boolean setter, the browser equivalent
+ * of an `Adw.Breakpoint` with one `add_setter()` call. Returns a dispose function; call it
+ * before re-binding and on disconnect.
  *
- * Returns a dispose function; call it before re-binding and on disconnect.
- * A missing or unparsable condition binds nothing and returns a no-op, leaving
- * whatever the attribute already says untouched — an element must not silently
- * flip state because its condition had a typo.
+ * A missing or unparsable condition binds nothing and returns a no-op, leaving whatever
+ * the attribute already says untouched — an element must not silently flip state because
+ * its condition had a typo.
  */
 export function bindBreakpointSetter(
     element: Element,