@gjsify/adwaita-web 0.36.0 → 0.37.0

package/scss/_style_classes.scss

@@ -0,0 +1,407 @@
+// _style_classes.scss — libadwaita's documented, WIDGET-INDEPENDENT style classes.
+//
+// THE GAP THIS CLOSES
+//
+// `refs/libadwaita/doc/style-classes.md` is the public contract an app author
+// reads: put `.card` on a box, `.boxed-list` on a list, `.toolbar` on a bar,
+// `.linked` around a button group. Twenty-one of those classes had NO rule in
+// this package (#1049) — and two of them looked ported because their names
+// appear in comments (`.osd`, `.linked`) while the code spells its own
+// `.adw-linked`. A consumer following the upstream documentation got nothing,
+// silently, which is the worst failure mode for a styling contract.
+//
+// Widget-scoped classes are NOT here — they live with the widget whose markup
+// they modify (`.property` in `_action_row.scss`, `.compact` in
+// `_status_page.scss`, `.devel` in `_headerbar.scss`, `.osd`'s button and
+// progress-bar variants in theirs), because that is where their selector needs
+// to see the widget's inner nodes. `scripts/check-adwaita-style-classes.mjs`
+// holds the ledger of which class lives where and fails when one has no rule at
+// all.
+//
+// Reference: refs/libadwaita/doc/style-classes.md (the documented surface)
+// Reference: refs/libadwaita/src/stylesheet/_common.scss:25-28,43-60,90-104
+// Reference: refs/libadwaita/src/stylesheet/widgets/_misc.scss:4-7,21-32,197-236
+// Reference: refs/libadwaita/src/stylesheet/widgets/_views.scss:1-18
+// Reference: refs/libadwaita/src/stylesheet/widgets/_lists.scss:520-600
+// Reference: refs/libadwaita/src/stylesheet/widgets/_toolbars.scss:91-102
+// Reference: refs/libadwaita/src/stylesheet/widgets/_linked.scss:1-45
+// Reference: refs/libadwaita/src/stylesheet/widgets/_scrolling.scss:150-166
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Modifications: Adapted for @gjsify/adwaita-web — GTK node names (`row`,
+//   `list`, `button`) become the custom-element tags and `.adw-*` structure
+//   classes this package renders, and GTK-only drawing (`image()`,
+//   `-gtk-icon-shadow`, `border-spacing` on a box) becomes its CSS equivalent.
+
+/************
+ * Surfaces *
+ ************/
+
+// _common.scss:25-28 — an opaque window-coloured background on any node.
+.background {
+  background-color: var(--window-bg-color);
+  color: var(--window-fg-color);
+}
+
+// _views.scss:1-18 — the content-area surface. `:disabled` and `:selected` are
+// GTK pseudo-classes with no DOM counterpart; `[disabled]`/`[aria-selected]`
+// are how the same states are spelled here, and both are what our own widgets
+// already set.
+.view {
+  background-color: var(--view-bg-color);
+  color: var(--view-fg-color);
+
+  &:disabled,
+  &[disabled] {
+    color: color-mix(in srgb, var(--view-fg-color) var(--disabled-opacity), transparent);
+    background-color: color-mix(in srgb, var(--window-bg-color) 60%, var(--view-bg-color));
+  }
+
+  &[aria-selected='true'] {
+    background-color: color-mix(in srgb, var(--accent-bg-color) 25%, transparent);
+    border-radius: var(--button-radius);
+  }
+}
+
+// _misc.scss:4-7 — the default border. `--border-color` is derived from
+// `currentColor`, so this follows the foreground of whatever it is drawn on.
+.frame {
+  border: 1px solid var(--border-color);
+}
+
+/*********
+ * Cards *
+ *********/
+
+// _misc.scss:197-236. The ONE card recipe: `adw-card` and the preferences
+// group's list box each carried their own copy of these five declarations
+// before this placeholder existed.
+%card {
+  background-color: var(--card-bg-color);
+  color: var(--card-fg-color);
+  border-radius: var(--card-radius);
+  box-shadow:
+    0 0 0 1px rgb(0 0 6 / 3%),
+    0 1px 3px 1px rgb(0 0 6 / 7%),
+    0 2px 6px 2px rgb(0 0 6 / 3%);
+
+  @media (prefers-contrast: more) {
+    box-shadow:
+      0 0 0 1px var(--border-color),
+      0 1px 3px 1px rgb(0 0 6 / 7%),
+      0 2px 6px 2px rgb(0 0 6 / 3%);
+  }
+}
+
+.card {
+  @extend %card;
+
+  // `.card.activatable` gets the hover/active states of an activatable row
+  // (:225-235). GTK's `background-image: image(…)` is a solid-colour layer over
+  // the background; a one-stop gradient is its CSS equivalent, and it composes
+  // with `background-color` the same way — so a re-themed card keeps its colour
+  // and only gains the wash.
+  &.activatable {
+    transition:
+      background-color 200ms cubic-bezier(0.25, 0.46, 0.45, 0.94),
+      box-shadow 200ms cubic-bezier(0.25, 0.46, 0.45, 0.94);
+
+    &:hover {
+      background-image: linear-gradient(
+        color-mix(in srgb, currentColor 3%, transparent),
+        color-mix(in srgb, currentColor 3%, transparent)
+      );
+    }
+
+    &:active {
+      background-image: linear-gradient(
+        color-mix(in srgb, currentColor 8%, transparent),
+        color-mix(in srgb, currentColor 8%, transparent)
+      );
+    }
+  }
+
+  // A card inside (or itself) an OSD surface loses its own elevation and reads
+  // as a translucent inset instead (:212-220).
+  .osd &,
+  &.osd {
+    background-color: color-mix(in srgb, currentColor 10%, transparent);
+    color: rgb(255 255 255 / 90%);
+    box-shadow: none;
+
+    @media (prefers-contrast: more) {
+      box-shadow: 0 0 0 1px var(--border-color);
+    }
+  }
+}
+
+/***************
+ * Boxed lists *
+ ***************/
+
+// _lists.scss:520-556. In GTK the row separators are drawn by the rows
+// themselves and the list only supplies the card box plus the rounding of its
+// two ends — which is exactly how this package's rows behave already
+// (`adw-action-row` and friends draw their own `border-bottom` and drop it on
+// `:last-child`), so the class is the box and the clip.
+.boxed-list {
+  @extend %card;
+
+  display: flex;
+  flex-direction: column;
+  // The rounding of the first and last row is a CLIP here rather than per-row
+  // corner radii: a row is a custom element whose own background paints over
+  // the list's corners, and every row type would otherwise need the same four
+  // radii repeated.
+  overflow: hidden;
+}
+
+// :556-600 — same content, each row its own card. The list drops its box, and
+// the rows carry it, spaced 12px apart.
+.boxed-list-separate {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  background: none;
+  color: var(--card-fg-color);
+
+  > * {
+    @extend %card;
+
+    overflow: hidden;
+    // A row that draws a separator for its neighbours must not draw one when it
+    // IS the card (:585-586: `border: none`).
+    border-bottom: none;
+  }
+}
+
+/************
+ * Toolbars *
+ ************/
+
+// _toolbars.scss:91-102 + doc "Toolbars". GTK's `border-spacing: 6px` on a box
+// is the gap between children; the flex row is what makes that expressible.
+//
+// The automatic flat appearance follows upstream's rule list exactly: icon-only
+// buttons, buttons with an `adw-button-content` (icon + label), menu buttons and
+// split buttons go flat — unless they are `.raised`, `.suggested-action`,
+// `.destructive-action`, `.opaque`, or sit inside a `.linked` group. Text-only
+// buttons keep their frame, which is why this cannot be a blanket
+// `.toolbar adw-button { … }`.
+$_keeps-frame: ':not(.raised):not(.suggested-action):not(.destructive-action):not(.opaque)';
+
+.toolbar {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 6px;
+
+  adw-button#{$_keeps-frame} .adw-button.icon-only,
+  adw-button#{$_keeps-frame}:has(adw-button-content) .adw-button,
+  adw-menu-button#{$_keeps-frame} .adw-button,
+  adw-split-button#{$_keeps-frame} .adw-button {
+    background-color: transparent;
+
+    &:hover {
+      background-color: var(--button-hover-color);
+    }
+
+    &:active {
+      background-color: var(--button-active-color);
+    }
+  }
+
+  // Inside a linked group the frames come BACK — upstream states this as its own
+  // rule (`_toolbars.scss:20-26`) rather than as an exclusion, because a linked
+  // group only reads as one control if its members are raised.
+  .linked,
+  .adw-linked {
+    adw-button#{$_keeps-frame} .adw-button,
+    adw-menu-button#{$_keeps-frame} .adw-button,
+    adw-split-button#{$_keeps-frame} .adw-button {
+      background-color: var(--button-bg-color);
+
+      &:hover {
+        background-color: var(--button-hover-color);
+      }
+
+      &:active {
+        background-color: var(--button-active-color);
+      }
+    }
+  }
+
+  // Stand-alone OSD toolbars — the floating video-player-controls shape
+  // (:99-102).
+  &.osd {
+    padding: 12px;
+    border-radius: calc(var(--button-radius) + 6px);
+  }
+}
+
+// _misc.scss:21-32 — a separator that reserves whitespace instead of drawing a
+// line, for separating groups inside a toolbar.
+.spacer {
+  background: none;
+  border: none;
+  flex-shrink: 0;
+
+  &,
+  &.horizontal {
+    min-width: 12px;
+  }
+
+  &.vertical {
+    min-height: 12px;
+  }
+}
+
+/*******
+ * OSD *
+ *******/
+
+// _common.scss:43-60. The exclusions are upstream's: a progress bar, button,
+// menu button, split button and inline view switcher each define what `.osd`
+// means for them, and must not get the dark surface treatment on top.
+//
+// This is a token REBIND, not just a colour: everything accent-coloured inside
+// an OSD surface turns white without knowing it is inside one.
+.osd:not(adw-progress-bar):not(adw-button):not(adw-menu-button):not(adw-split-button):not(
+    adw-inline-view-switcher
+  ) {
+  --accent-bg-color: rgb(255 255 255 / 75%);
+  --accent-fg-color: rgb(0 0 0 / 75%);
+  --accent-color: oklab(from var(--accent-bg-color) max(l, 0.85) a b);
+  --destructive-color: oklab(from var(--destructive-bg-color) max(l, 0.85) a b);
+  --success-color: oklab(from var(--success-bg-color) max(l, 0.85) a b);
+  --warning-color: oklab(from var(--warning-bg-color) max(l, 0.85) a b);
+  --error-color: oklab(from var(--error-bg-color) max(l, 0.85) a b);
+
+  color: rgb(255 255 255 / 90%);
+  border: none;
+  background-color: rgb(0 0 0 / 70%);
+  background-clip: padding-box;
+}
+
+/*******************
+ * Linked controls *
+ *******************/
+
+// _linked.scss:1-45 + doc "Linked Controls": the children of a linked box share
+// their touching edges. Upstream squares the inner corners and overlaps the
+// borders by -1px; this package's controls have no border, so the overlap is
+// dropped and only the corner squaring remains.
+//
+// `.adw-linked` is this package's own earlier spelling, kept as an alias — and
+// it USED to add a 2px gap between children, which is a segmented look, not a
+// linked one. The gap is gone; a consumer who wanted it can say `gap`.
+// The styled node is either the child itself (a bare `.adw-button` /
+// `.adw-entry`) or one rendered inside the child host element (`<adw-button>`,
+// `<adw-menu-button>`, `<adw-drop-down>`, …) — so both spellings are matched
+// rather than enumerating host tags the way GTK has to.
+$_linked-nodes: '.adw-button', '.adw-entry';
+
+.linked,
+.adw-linked {
+  display: inline-flex;
+
+  &:not(.vertical) > * {
+    @each $node in $_linked-nodes {
+      &:not(:first-child) #{$node},
+      &:not(:first-child)#{$node} {
+        border-start-start-radius: 0;
+        border-end-start-radius: 0;
+      }
+
+      &:not(:last-child) #{$node},
+      &:not(:last-child)#{$node} {
+        border-start-end-radius: 0;
+        border-end-end-radius: 0;
+      }
+    }
+  }
+
+  &.vertical {
+    flex-direction: column;
+
+    > * {
+      @each $node in $_linked-nodes {
+        &:not(:first-child) #{$node},
+        &:not(:first-child)#{$node} {
+          border-start-start-radius: 0;
+          border-start-end-radius: 0;
+        }
+
+        &:not(:last-child) #{$node},
+        &:not(:last-child)#{$node} {
+          border-end-start-radius: 0;
+          border-end-end-radius: 0;
+        }
+      }
+    }
+  }
+}
+
+/*************
+ * App icons *
+ *************/
+
+// _common.scss:90-104. `-gtk-icon-shadow` has no CSS counterpart; `filter:
+// drop-shadow()` is the equivalent that follows the icon's alpha rather than its
+// box, which is what makes these legible on a light background. Each upstream
+// shadow layer becomes one `drop-shadow()`.
+.lowres-icon {
+  filter: drop-shadow(0 -1px rgb(0 0 6 / 5%)) drop-shadow(1px 0 rgb(0 0 6 / 10%))
+    drop-shadow(0 1px rgb(0 0 6 / 30%)) drop-shadow(-1px 0 rgb(0 0 6 / 10%));
+}
+
+.icon-dropshadow {
+  filter: drop-shadow(0 1px 12px rgb(0 0 6 / 5%)) drop-shadow(0 -1px rgb(0 0 6 / 5%))
+    drop-shadow(1px 0 rgb(0 0 6 / 10%)) drop-shadow(0 1px rgb(0 0 6 / 30%))
+    drop-shadow(-1px 0 rgb(0 0 6 / 10%));
+}
+
+/************************
+ * Undershoot indicators *
+ ************************/
+
+// _scrolling.scss:150-166 — a shadow on the given edge of a scrolling box,
+// telling the reader there is content past it. GTK draws them with an inset
+// background; an inset `box-shadow` on the scroll container is the CSS
+// equivalent and, unlike a `::before`, stays put while the content scrolls.
+//
+// `-start`/`-end` follow text direction, same as `margin-start`/`margin-end`,
+// which `:dir()` expresses directly.
+//
+// `adw-toolbar-view` carries the same two class names for its OWN top/bottom
+// indicators, drawn on its content node against the header shade
+// (`_toolbar_view.scss:67-86`) — so it is excluded here rather than getting both
+// a host shadow and a content gradient.
+$undershoot-color: color-mix(in srgb, currentColor 6%, transparent);
+
+.undershoot-top:not(adw-toolbar-view) {
+  box-shadow: inset 0 6px 6px -6px $undershoot-color;
+}
+
+.undershoot-bottom:not(adw-toolbar-view) {
+  box-shadow: inset 0 -6px 6px -6px $undershoot-color;
+}
+
+.undershoot-start {
+  &:dir(ltr) {
+    box-shadow: inset 6px 0 6px -6px $undershoot-color;
+  }
+
+  &:dir(rtl) {
+    box-shadow: inset -6px 0 6px -6px $undershoot-color;
+  }
+}
+
+.undershoot-end {
+  &:dir(ltr) {
+    box-shadow: inset -6px 0 6px -6px $undershoot-color;
+  }
+
+  &:dir(rtl) {
+    box-shadow: inset 6px 0 6px -6px $undershoot-color;
+  }
+}

package/scss/_switch.scss

@@ -79,10 +79,11 @@
 }
 
 // libadwaita dims the whole widget (`filter: Opacity(var(--disabled-opacity))`,
-// _switch.scss:20-22). This package has no `--disabled-opacity` token, so the
-// existing `--dim-opacity` stands in rather than a fourth invented colour.
+// _switch.scss:20-22), and `--disabled-opacity` is a real token here now — it
+// used to be stood in for by `--dim-opacity`, which is a different number and
+// moves the OTHER way under high contrast.
 .adw-switch.disabled {
-  opacity: var(--dim-opacity);
+  opacity: var(--disabled-opacity);
 
   .adw-switch-slider {
     cursor: not-allowed;

package/scss/_variables.scss

@@ -117,6 +117,21 @@
   --font-size-heading: 12pt;
   --dim-opacity: 0.55;
 
+  // Borders and disabled dimming, as libadwaita's own two-step (_colors.scss:263,
+  // 317-329): an OPACITY token the high-contrast query moves, and a colour
+  // DERIVED from it against `currentColor` — so a border follows the text colour
+  // of the surface it is drawn on instead of being a fixed grey.
+  //
+  // `--disabled-opacity` had no home here, and three partials said so in a
+  // comment and reached for `--dim-opacity` instead (`_switch.scss:81-83`,
+  // `_checks.scss:164-166`, `_progress_bar.scss:87-89`). Those are different
+  // numbers upstream — 50% disabled vs 55% dimmed — and under high contrast they
+  // move in OPPOSITE directions (disabled 40%, dimmed 90%), so the stand-in was
+  // most wrong exactly where it mattered most.
+  --border-opacity: 15%;
+  --border-color: color-mix(in srgb, currentColor var(--border-opacity), transparent);
+  --disabled-opacity: 0.5;
+
   // Document + monospace families, behind `.document` / `.monospace`
   // (_labels.scss:75-84). In GTK these four are written into `:root` at RUNTIME
   // by AdwStyleManager from the desktop's font settings
@@ -134,3 +149,13 @@
   --monospace-font-family: 'Adwaita Mono', ui-monospace, 'SF Mono', 'Menlo', monospace;
   --monospace-font-size: var(--font-size-base);
 }
+
+// High contrast moves the three opacity tokens, and only those — every colour
+// that reads them follows without its own query (_colors.scss:325-329).
+@media (prefers-contrast: more) {
+  :root {
+    --border-opacity: 50%;
+    --dim-opacity: 0.9;
+    --disabled-opacity: 0.4;
+  }
+}

package/scss/adwaita-skin.scss

@@ -25,6 +25,15 @@
 // it (`_progress_bar.scss`'s text node, `_data_grid.scss`'s cells) exactly as
 // libadwaita's own `_progress-bar.scss` does.
 @use 'labels';
+// The REST of libadwaita's documented style-class surface — the widget-
+// independent half: the surfaces (`.background`, `.view`, `.frame`), `.card` and
+// the two boxed lists, `.toolbar`, `.spacer`, `.osd`, `.linked`, the app-icon
+// shadows and the undershoot indicators. Emitted here for the same two reasons
+// as `_labels.scss`: a widget's own rule then wins on ordinary specificity, and
+// `_card.scss` / `_preferences.scss` @extend `%card` from it.
+// `scripts/check-adwaita-style-classes.mjs` holds the ledger of the whole
+// documented surface and fails on a class with no rule behind it.
+@use 'style_classes';
 @use 'window';
 @use 'headerbar';
 @use 'window_title';
@@ -51,6 +60,9 @@
 @use 'data_grid';
 @use 'clamp';
 @use 'spinner';
+// <adw-shortcut-label>'s keycaps. After `labels`, because a separator inside it
+// is an ordinary `.dimmed`.
+@use 'shortcut_label';
 @use 'avatar';
 @use 'banner';
 @use 'status_page';

package/src/adw-about-dialog.spec.ts

@@ -1,13 +1,10 @@
 // DOM-level conformance tests for <adw-about-dialog>, driven by the vectors in
 // `@gjsify/adwaita-core/conformance` — the same table the core suite asserts.
 //
-// This element carried its own copy of `parse_person`, its own page-visibility
-// rules and its own set of invented fallbacks, and diverged from libadwaita on
-// thirteen counts. Two of them were not subtle: Support Questions and Report an
-// Issue were rendered on the DETAILS page, one navigation step deeper than GTK
-// puts them (adw-about-dialog.ui:146-186), and `website` was treated as Details
-// content, which is exactly the one input libadwaita leaves OUT of that
-// predicate (:1108). Nothing compared the two, so nothing failed.
+// A local copy of `parse_person`, of the page-visibility rules or of the fallbacks
+// diverges from libadwaita in thirteen ways, two of them structural: Support Questions
+// and Report an Issue belong on the MAIN page, not one navigation step deeper on Details;
+// and `website` is the one input the Details-visibility predicate leaves OUT.
 import { describe, expect, it } from '@gjsify/unit';
 
 import { ADW_ABOUT_DIALOG_LABELS, stripMnemonic } from '@gjsify/adwaita-core';
@@ -33,9 +30,9 @@ interface Mounted {
 }
 
 /**
- * Mount a dialog and set every attribute imperatively — several vectors hinge on
- * exact whitespace, which a value parsed out of markup is not a reliable
- * carrier for. `window.open` is stubbed because the link rows really do call it.
+ * Mount a dialog and set every attribute imperatively: several vectors hinge on exact
+ * whitespace, which markup is not a reliable carrier for. `window.open` is stubbed
+ * because the link rows really do call it.
  */
 function mount(attributes: Record<string, string> = {}): Mounted {
     const host = document.createElement('div');
@@ -85,10 +82,8 @@ function rowTitles(scope: Element | null): string[] {
 }
 
 /**
- * Activate a row and report the URI it asked for.
- *
- * The URI never reaches the DOM — it is captured in the row's activation
- * handler — so the only way to observe it is to drive the row and listen.
+ * Activate a row and report the URI it asked for. The URI never reaches the DOM — it is
+ * captured in the row's activation handler — so driving the row is the only way to see it.
  */
 function activateRow(dialog: HTMLElement, row: Element): string | null {
     let uri: string | null = null;
@@ -121,8 +116,8 @@ export const AdwAboutDialogTest = async () => {
         }
 
         await it('makes a row with an empty link a LINK row, not a plain one', () => {
-            // `if (link)` is a pointer test in the C, so `"Ada <>"` still links,
-            // to the URI `mailto:` — collapsing "" to null loses the row type.
+            // `if (link)` is a POINTER test in the C, so `"Ada <>"` still links, to the
+            // URI `mailto:` — collapsing "" to null loses the row type.
             const mounted = mount();
             mounted.dialog.developers = ['Ada <>'];
             const row = page(mounted.dialog, 'credits')!.querySelector('adw-action-row')!;
@@ -197,9 +192,9 @@ export const AdwAboutDialogTest = async () => {
         }
 
         await it('keeps a website-only dialog on the main page with no Details row', () => {
-            // `show_details` is `has_comments || has_custom_links` (:1108) —
-            // website is deliberately not in it, so a dialog whose only extra is
-            // a website links straight from the main page.
+            // `show_details` is `has_comments || has_custom_links`; website is
+            // deliberately not in it, so a dialog whose only extra is a website links
+            // straight from the main page.
             const mounted = mount({ 'application-name': 'Builder', website: 'https://example.org' });
             expect(page(mounted.dialog, 'details')).toBe(null);
             expect(hasRow(page(mounted.dialog, 'main'), label('websiteRow'))).toBe(true);
@@ -208,8 +203,8 @@ export const AdwAboutDialogTest = async () => {
     });
 
     await describe('adw-about-dialog main page (update_support vectors)', async () => {
-        // debug-info has no counterpart on this element (there is no
-        // Troubleshooting page), so those rows are asserted by the core suite.
+        // debug-info has no counterpart here (no Troubleshooting page), so the core
+        // suite asserts those rows.
         for (const vector of ABOUT_DIALOG_SUPPORT_VECTORS.filter((row) => !row.debugInfo)) {
             const { supportUrl, issueUrl, visible, rule } = vector;
             await it(`support=${supportUrl} issue=${issueUrl} — ${rule}`, () => {
@@ -235,8 +230,7 @@ export const AdwAboutDialogTest = async () => {
         }
 
         await it('puts the support and issue rows on the MAIN page, not on Details', () => {
-            // adw-about-dialog.ui:146-186 — `support_group` is a child of the
-            // main page, and the class docs say so outright (:87-90).
+            // In `adw-about-dialog.ui`, `support_group` is a child of the MAIN page.
             const mounted = mount({
                 'application-name': 'Builder',
                 'support-url': 'https://example.org/help',
@@ -304,9 +298,8 @@ export const AdwAboutDialogTest = async () => {
         }
 
         await it('titles the dialog "About", not "About <app name>"', () => {
-            // The main page's title is bound to AdwDialog:title, whose template
-            // default is the bare word (.ui:6, :19); the application name lives
-            // in the header revealer instead (.ui:29-31).
+            // The main page's title is bound to AdwDialog:title, whose template default
+            // is the bare word; the application name lives in the header revealer.
             const mounted = mount({ 'application-name': 'Builder' });
             expect(page(mounted.dialog, 'main')!.getAttribute('title')).toBe('About');
             mounted.dispose();
@@ -323,12 +316,11 @@ export const AdwAboutDialogTest = async () => {
         });
 
         await it('does NOT open when a handler cancels it', () => {
-            // `activate_link_cb` returns the accumulated handler result
-            // (:429-437, accumulator `g_signal_accumulator_true_handled`
-            // :2098): a handler saying "handled" suppresses the default
-            // navigation. `preventDefault()` is the web spelling of that, and it
-            // was unavailable — the event was not cancelable and `window.open`
-            // ran regardless.
+            // `activate_link_cb` returns the accumulated handler result (accumulator
+            // `g_signal_accumulator_true_handled`): a handler saying "handled"
+            // suppresses the default navigation, and `preventDefault()` is the web
+            // spelling of that — so the event must be cancelable, or `window.open` runs
+            // regardless.
             const mounted = mount({ 'application-name': 'Builder', website: 'https://example.org' });
             mounted.dialog.addEventListener('activate-link', (event) => event.preventDefault());
             const row = page(mounted.dialog, 'main')!.querySelector(`adw-action-row[title="${label('websiteRow')}"]`)!;
@@ -348,19 +340,14 @@ export const AdwAboutDialogTest = async () => {
         });
     });
 
-    // AN OPENED DIALOG HAS TO OCCUPY SPACE.
+    // An opened dialog has to OCCUPY SPACE, and no other test here can see that: they
+    // all read the built DOM, and all passed while the sheet measured 360×0.
     //
-    // Every other test in this file reads the built DOM, and all of them passed
-    // while the dialog rendered INVISIBLE — its sheet measured 360×0. The suite
-    // could not see that, because none of it looks at geometry.
-    //
-    // The sheet is `position: fixed` with a width and no height, which is what
-    // `adw-about-dialog.ui:7` declares: `content-width` 360 and no
-    // content-height, libadwaita taking the height from the content. The content
-    // could not supply one — the navigation pages were absolutely positioned, so
-    // they contributed nothing to the page stack, which contributed nothing to
-    // the view, which left the sheet at zero; and the pages, being `inset: 0` of
-    // a zero-height parent, were zero in turn.
+    // `adw-about-dialog.ui` declares `content-width` 360 and no content-height, so
+    // libadwaita takes the height from the content — which absolutely-positioned
+    // navigation pages cannot supply, since they contribute nothing to the page stack,
+    // which contributes nothing to the view, and the pages are then `inset: 0` of a
+    // zero-height parent.
     await describe('adw-about-dialog — an opened dialog is actually on screen', async () => {
         await it('gives its sheet a height derived from its content', () => {
             const mounted = mount({ 'application-name': 'Adwaita Storybook', version: '0.11.0' });
@@ -368,11 +355,9 @@ export const AdwAboutDialogTest = async () => {
 
             const sheet = mounted.dialog.querySelector('.adw-about-dialog-sheet') as HTMLElement;
             const rect = sheet.getBoundingClientRect();
-            // HEIGHT only. The width was never the defect, and pinning it here
-            // needs `calc(100vw - 48px)` restated in JS — where `100vw` and
-            // `innerWidth` disagree by the scrollbar (360 against a measured
-            // 342), so the assertion would report the harness rather than the
-            // widget. A test should assert the rule the bug broke.
+            // HEIGHT only: pinning the width needs `calc(100vw - 48px)` restated in JS,
+            // where `100vw` and `innerWidth` disagree by the scrollbar, so the assertion
+            // would report the harness rather than the widget.
             expect(rect.height > 0).toBe(true);
             // And not merely the header: the sheet has to be taller than the one
             // child that had a size of its own all along, which is what made the