@gjsify/adwaita-web 0.36.0 → 0.38.0

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

package/src/adw-accent.spec.ts

@@ -0,0 +1,105 @@
+// Accent application against `ACCENT_COLOR_VECTORS` — the same table the core
+// suite drives, here through the REAL computed style of a real element.
+//
+// This is what makes the table renderer-driven rather than a derivation asserted
+// against itself: the browser resolves the custom properties and the assertions
+// read them back with `getComputedStyle`, so a value that never reaches the
+// cascade fails a test naming the accent.
+import { describe, expect, it } from '@gjsify/unit';
+import { ACCENT_COLOR_VECTORS } from '@gjsify/adwaita-core/conformance';
+
+import '@gjsify/adwaita-web';
+import {
+    ACCENT_BG_PROPERTY,
+    ACCENT_PROPERTY,
+    applyAdwaitaAccent,
+    clearAdwaitaAccent,
+    isAdwaitaDark,
+} from './accent.js';
+
+/** A custom property's resolved value, whitespace trimmed. */
+const property = (element: HTMLElement, name: string): string =>
+    getComputedStyle(element).getPropertyValue(name).trim();
+
+export const AdwAccentTest = async () => {
+    await describe('applyAdwaitaAccent (conformance vectors)', async () => {
+        for (const vector of ACCENT_COLOR_VECTORS) {
+            await it(`${vector.name} — the fill and the light standalone colour reach the cascade`, async () => {
+                const host = document.createElement('div');
+                host.className = 'theme-light';
+                document.body.append(host);
+
+                applyAdwaitaAccent(vector.name, { target: host });
+
+                expect(property(host, ACCENT_BG_PROPERTY)).toBe(vector.background);
+                expect(property(host, ACCENT_PROPERTY)).toBe(vector.standaloneLight);
+
+                host.remove();
+            });
+
+            await it(`${vector.name} — the DARK standalone colour differs and is the table's`, async () => {
+                // Asserted as a pair: a renderer that ignored `dark` would pass
+                // every light row above and still be wrong in half its uses.
+                const host = document.createElement('div');
+                host.className = 'theme-dark';
+                document.body.append(host);
+
+                applyAdwaitaAccent(vector.name, { target: host });
+
+                expect(property(host, ACCENT_PROPERTY)).toBe(vector.standaloneDark);
+                expect(vector.standaloneDark).not.toBe(vector.standaloneLight);
+
+                host.remove();
+            });
+        }
+    });
+
+    await describe('accent application', async () => {
+        await it('reads the resolved scheme from the element rather than assuming light', async () => {
+            const dark = document.createElement('div');
+            dark.className = 'theme-dark';
+            const light = document.createElement('div');
+            light.className = 'theme-light';
+            document.body.append(dark, light);
+
+            expect(isAdwaitaDark(dark)).toBe(true);
+            expect(isAdwaitaDark(light)).toBe(false);
+
+            // A nested element inherits the ancestor's scheme — `closest`, not a
+            // class check on the element itself, which is how the stylesheet's
+            // `.theme-dark` scope actually behaves.
+            const nested = document.createElement('span');
+            dark.append(nested);
+            expect(isAdwaitaDark(nested)).toBe(true);
+
+            dark.remove();
+            light.remove();
+        });
+
+        await it('an explicit dark option overrides what the element resolves to', async () => {
+            const host = document.createElement('div');
+            host.className = 'theme-light';
+            document.body.append(host);
+
+            applyAdwaitaAccent('blue', { target: host, dark: true });
+            expect(property(host, ACCENT_PROPERTY)).toBe(ACCENT_COLOR_VECTORS[0].standaloneDark);
+
+            host.remove();
+        });
+
+        await it('clearing restores the stylesheet value instead of leaving the override', async () => {
+            const host = document.createElement('div');
+            host.className = 'theme-light';
+            document.body.append(host);
+
+            applyAdwaitaAccent('red', { target: host });
+            expect(property(host, ACCENT_BG_PROPERTY)).toBe(ACCENT_COLOR_VECTORS[5].background);
+
+            clearAdwaitaAccent(host);
+            // Back to whatever the cascade says — which is NOT red.
+            expect(property(host, ACCENT_BG_PROPERTY)).not.toBe(ACCENT_COLOR_VECTORS[5].background);
+
+            host.remove();
+        });
+    });
+};

package/src/adw-action-rows.spec.ts

@@ -3,20 +3,16 @@
 // vectors the NativeScript renderer asserts against
 // (`@gjsify/adwaita-core/conformance`).
 //
-// What this suite exists to catch, in the words of what it found:
-//   - NEITHER renderer hid an empty TITLE. `string_is_not_empty` is bound to the
-//     title label as much as to the subtitle (adw-action-row.ui:49-53 vs :71-75),
-//     and the browser port hand-rolled the subtitle-only half of that block six
-//     times over.
-//   - a programmatic `switchRow.active = true` emitted nothing here, because the
-//     DOM does not fire `change` for a scripted `.checked =` — while the
-//     NativeScript port, whose `checkedChange` does fire, emitted. One C source,
-//     two opposite answers, and nothing comparing them.
-//   - clicking anywhere but the handle of a switch row did nothing, though
-//     `adw_switch_row_init` makes the whole row the switch's activator.
-//   - `<adw-button-row activatable="false">` was honoured, an opt-out libadwaita
-//     does not have — and `<adw-action-row activatable="false">` meant the
-//     OPPOSITE, because that element reads the attribute by presence.
+// The rules it pins, each of which one renderer had wrong:
+//   - `string_is_not_empty` in `adw-action-row.ui` is bound to the TITLE label as much
+//     as to the subtitle, so an empty title hides too;
+//   - the DOM fires no `change` for a scripted `.checked =`, so a programmatic
+//     `switchRow.active = true` must be made to notify anyway — NativeScript's
+//     `checkedChange` does fire, and one C source must not give two answers;
+//   - `adw_switch_row_init` makes the WHOLE row the switch's activator;
+//   - libadwaita has no activatable opt-out for a button row, and
+//     `<adw-action-row activatable="false">` reads by PRESENCE, so it means the
+//     opposite of what it says.
 import { describe, expect, it } from '@gjsify/unit';
 
 import {
@@ -35,9 +31,8 @@ import type { AdwSwitchRow } from './elements/adw-switch-row.js';
 import type { AdwWindowTitle } from './elements/adw-window-title.js';
 
 /**
- * Mount an element imperatively — never through parsed HTML, because several
- * label vectors hinge on exact whitespace (`' '`, `'\t'`) that an attribute
- * value in markup is not a reliable carrier for.
+ * Mount an element imperatively, never through parsed HTML: several label vectors hinge
+ * on exact whitespace (`' '`, `'\t'`) that markup is not a reliable carrier for.
  */
 function mount<T extends HTMLElement>(tag: string): { el: T; host: HTMLElement } {
     const host = document.createElement('div');
@@ -144,13 +139,11 @@ export const AdwActionRowsTest = async () => {
         await it('reads `activatable` by PRESENCE, like every other boolean attribute here', () => {
             const { el: row, host } = mount<AdwActionRow>('adw-action-row');
             row.setAttribute('activatable', 'false');
-            // The HTML boolean-attribute convention (`<input disabled="false">`
-            // is disabled), which is how every other boolean attribute in this
-            // package is read. NOT a libadwaita rule — libadwaita has a typed
-            // gboolean and no attribute parsing at all — so it is pinned here
-            // rather than in the cross-renderer vectors. Pinned so the next
-            // reader does not "fix" it into the string comparison
-            // <adw-button-row> used to carry, which gave one markup two
+            // The HTML boolean-attribute convention (`<input disabled="false">` IS
+            // disabled), how every other boolean attribute in this package is read. NOT a
+            // libadwaita rule — libadwaita has a typed gboolean and no attribute parsing —
+            // so it is pinned here rather than in the cross-renderer vectors, and pinned so
+            // nobody "fixes" it into a string comparison that would give one markup two
             // opposite meanings inside one package.
             expect(row.activatable).toBe(true);
             host.remove();
@@ -183,9 +176,9 @@ export const AdwActionRowsTest = async () => {
 
             widget.click();
 
-            // One click, and no row activation: GtkListBox does not emit
-            // `row-activated` for a click a child widget claimed. Re-clicking the
-            // widget here would also bounce back into the row's own listener.
+            // One click, no row activation: GtkListBox does not emit `row-activated` for a
+            // click a child widget claimed, and re-clicking the widget here would bounce
+            // back into the row's own listener.
             expect(widgetClicks).toBe(1);
             expect(activations.length).toBe(0);
             host.remove();
@@ -257,16 +250,15 @@ export const AdwActionRowsTest = async () => {
                 setAttr(row, 'start-icon-name', vector.startIconName);
                 setAttr(row, 'end-icon-name', vector.endIconName);
 
-                // The two `image.icon.{start,end}` nodes are <adw-icon> now, not
-                // hand-rolled decorative spans.
+                // The two `image.icon.{start,end}` nodes are <adw-icon>, not hand-rolled
+                // decorative spans.
                 const icons = Array.from(row.querySelectorAll('adw-icon')) as HTMLElement[];
                 expect(icons.length).toBe(2);
                 expect(!icons[0]!.hidden).toBe(vector.startIconVisible);
                 expect(!icons[1]!.hidden).toBe(vector.endIconVisible);
-                // The mask class is the NORMALIZED name: the generated classes
-                // never carry `-symbolic`, and this row used to interpolate the
-                // raw one — so `start-icon-name="list-add-symbolic"` asked for a
-                // class that has never existed and drew an empty box.
+                // The mask class is the NORMALIZED name — the generated classes never
+                // carry `-symbolic`, so interpolating the raw one asks for a class that has
+                // never existed and draws an empty box.
                 if (vector.startIconVisible) {
                     expect(icons[0]!.classList.contains(`adw-icon--${normalizeIconName(vector.startIconName)}`)).toBe(
                         true,

package/src/adw-avatar.spec.ts

@@ -1,12 +1,10 @@
 // DOM-level conformance tests for <adw-avatar>, driven by the SAME vectors the
 // NativeScript renderer asserts against (`@gjsify/adwaita-core/conformance`).
 //
-// The two renderers used to carry independent copies of the initials + colour
-// derivation, and the copies had drifted apart AND away from libadwaita:
-// this element rendered "AD" for `text="Ada"` where GTK and NS render "A", and
-// both hashed UTF-16 code units where GLib hashes UTF-8 bytes, so every accented
-// name was painted the wrong colour. Nothing failed, because nothing compared
-// them. This suite is that comparison.
+// Two rules independent copies of the initials + colour derivation drifted from: GTK
+// takes ONE initial from a single-word `text`, and the colour hash runs over UTF-8 BYTES
+// as GLib's does — hashing UTF-16 code units paints every accented name the wrong
+// colour.
 import { describe, expect, it } from '@gjsify/unit';
 
 import { AVATAR_MODE_VECTORS } from '@gjsify/adwaita-core/conformance';
@@ -140,37 +138,70 @@ export const AdwAvatarTest = async () => {
     });
 
     await describe('<adw-avatar> mode (update_visibility, adw-avatar.c:117)', async () => {
-        // The `hasCustomImage` rows are not reachable through this element: it
-        // passes `hasCustomImage: false` unconditionally, because it has no
-        // custom-image support at all — `Adw.Avatar:custom-image` is unported.
-        // Named below rather than silently filtered.
+        // A 1x1 transparent GIF: a real, decodable image, so `custom-image` is
+        // exercised through the same path a photo would take — and no network.
+        const PIXEL = 'data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7';
+
         for (const { hasCustomImage, showInitials, text, mode, rule } of AVATAR_MODE_VECTORS) {
-            if (hasCustomImage) continue;
-            await it(`initials=${showInitials} "${text}" → ${mode} — ${rule}`, () => {
+            await it(`image=${hasCustomImage} initials=${showInitials} "${text}" → ${mode} — ${rule}`, () => {
                 const host = document.createElement('div');
                 document.body.appendChild(host);
                 const avatar = document.createElement('adw-avatar');
                 if (showInitials) avatar.setAttribute('show-initials', '');
                 if (text) avatar.setAttribute('text', text);
+                if (hasCustomImage) avatar.setAttribute('custom-image', PIXEL);
                 host.appendChild(avatar);
 
-                // Exactly ONE of the two reachable modes is drawn — the point of
-                // the table is the precedence, and "both visible at once" is the
+                // Exactly ONE of the three modes is drawn — the point of the
+                // table is the precedence, and "two visible at once" is the
                 // failure it guards against.
                 const initials = (avatar.querySelector('.adw-avatar-text') as HTMLElement).hidden === false;
                 const icon = (avatar.querySelector('.adw-avatar-icon') as HTMLElement).hidden === false;
+                const image = (avatar.querySelector('.adw-avatar-custom-image') as HTMLElement).hidden === false;
                 expect(initials).toBe(mode === 'initials');
                 expect(icon).toBe(mode === 'icon');
+                expect(image).toBe(mode === 'image');
                 host.remove();
             });
         }
 
-        await it('leaves out only the custom-image rows, which this element cannot reach', () => {
-            const unreachable = AVATAR_MODE_VECTORS.filter((vector) => vector.hasCustomImage);
-            expect(unreachable.length).toBeGreaterThan(0);
-            // Every one of them is an `image` outcome, i.e. the whole mode is
-            // missing rather than a corner of it.
-            for (const vector of unreachable) expect(vector.mode).toBe('image');
+        await it('drops the custom image again when the attribute goes away', () => {
+            // The mode is re-derived on every attribute change, so removing the
+            // image has to fall back to whichever mode the remaining state picks
+            // — this is where a port that only ever ADDS the image node fails.
+            const host = document.createElement('div');
+            document.body.appendChild(host);
+            const avatar = document.createElement('adw-avatar');
+            avatar.setAttribute('show-initials', '');
+            avatar.setAttribute('text', 'Ada Lovelace');
+            avatar.setAttribute('custom-image', PIXEL);
+            host.appendChild(avatar);
+
+            expect((avatar.querySelector('.adw-avatar-custom-image') as HTMLElement).hidden).toBe(false);
+
+            avatar.removeAttribute('custom-image');
+            expect((avatar.querySelector('.adw-avatar-custom-image') as HTMLElement).hidden).toBe(true);
+            expect((avatar.querySelector('.adw-avatar-text') as HTMLElement).hidden).toBe(false);
+
+            host.remove();
+        });
+
+        await it('fills the circle with the image rather than letterboxing it', () => {
+            // `object-fit` is the whole reason the image looks like an avatar and
+            // not like a photo in a round frame — a class-name assertion cannot
+            // see it, and it is one word away from being wrong.
+            const host = document.createElement('div');
+            document.body.appendChild(host);
+            const avatar = document.createElement('adw-avatar');
+            avatar.setAttribute('custom-image', PIXEL);
+            avatar.setAttribute('size', '64');
+            host.appendChild(avatar);
+
+            const image = avatar.querySelector('.adw-avatar-custom-image') as HTMLElement;
+            expect(getComputedStyle(image).objectFit).toBe('cover');
+            expect(Math.round(image.getBoundingClientRect().width)).toBe(64);
+
+            host.remove();
         });
     });
 };

package/src/adw-banner.spec.ts

@@ -1,13 +1,10 @@
 // DOM-level conformance tests for <adw-banner>, driven by the SAME vectors the
 // NativeScript renderer asserts against (`@gjsify/adwaita-core/conformance`).
 //
-// The two renderers carried independent banner logic and had drifted apart AND
-// away from libadwaita: `revealed` was opt-in here (right) and initialised TRUE
-// on NativeScript with no `visibility` written at all (wrong), `use-markup` was
-// opt-in in both with a comment here asserting that WAS the C default (it is
-// TRUE, adw-banner.c:422-425), `button-style` was in neither, and the mnemonic
-// marker the template pins onto the button (adw-banner.ui:33) was painted as a
-// literal underscore. Nothing failed, because nothing compared them.
+// The defaults independent banner logic drifted from, all of them in
+// `ADW_BANNER_DEFAULTS`: `revealed` is FALSE, `use-markup` is TRUE (opting it in inverts
+// the C), `button-style` exists, and the mnemonic marker the template pins onto the
+// button is a marker, not a literal underscore to paint.
 import { describe, expect, it } from '@gjsify/unit';
 
 import { ADW_BANNER_DEFAULTS } from '@gjsify/adwaita-core';
@@ -64,7 +61,7 @@ export const AdwBannerTest = async () => {
     });
 
     await describe('adw-banner use-markup — a DELIBERATE departure from the C default', async () => {
-        // The C default is unambiguously TRUE (adw-banner.c:422-425) and core
+        // The C default is unambiguously TRUE and core
         // carries it as the spec value. This renderer does NOT adopt it: Pango
         // markup is not HTML, and defaulting a `title` attribute to `innerHTML`
         // would make an injection sink out of a widget that is not one in GTK.

package/src/adw-button-content.spec.ts

@@ -2,15 +2,12 @@
 // vectors the NativeScript renderer asserts against
 // (`@gjsify/adwaita-core/conformance`).
 //
-// THE STYLE CLASS IS WHY THIS SUITE EXISTS. `AdwButtonContent` puts
-// `image-text-button` on the button hosting it (adw-button-content.c:115) and
-// removes it on unroot (:126); the stylesheet gives that class
-// `padding-left/right: 9px` where a plain text button has 17px
-// (_buttons.scss:77-80 against :72-75). `grep -rn "image-text-button"` over both
-// renderer trees returned NOTHING, so every icon+label button in this package
-// was drawn with the wrong horizontal padding for its whole life. `use-underline`
-// was absent, and an empty `icon-name` hid the image where the C sets
-// `image-missing` (:355-356).
+// The STYLE CLASS is why this suite exists: `AdwButtonContent` puts
+// `image-text-button` on the button hosting it and removes it on unroot, and
+// `_buttons.scss` gives that class 9px horizontal padding where a plain text button has
+// 17px — so a renderer that never sets the class draws every icon+label button with the
+// wrong padding. Also pinned: `use-underline`, and that an empty `icon-name` shows
+// `image-missing` rather than hiding the image.
 import { describe, expect, it } from '@gjsify/unit';
 
 import { BUTTON_CONTENT_DEFAULT_VECTORS } from '@gjsify/adwaita-core/conformance';
@@ -93,8 +90,8 @@ export const AdwButtonContentTest = async () => {
             host.appendChild(split);
 
             // The class goes on the `splitbutton` node, which is what
-            // `splitbutton.image-text-button > button` (:499-507) selects —
-            // a different declaration block from the plain-button one.
+            // `splitbutton.image-text-button > button` selects — a different declaration
+            // block from the plain-button one.
             expect(split.classList.contains(BUTTON_CONTENT_STYLE_CLASS)).toBe(true);
             expect(action.classList.contains(BUTTON_CONTENT_STYLE_CLASS)).toBe(false);
             // …and the padding lands on the INNER button, which is what that
@@ -134,7 +131,7 @@ export const AdwButtonContentTest = async () => {
                     maskName === '' ? 0 : 1,
                 );
                 // The image node is never hidden — `gtk_widget_set_visible` is
-                // called on the LABEL only (:300, :398).
+                // called on the LABEL only.
                 expect(icon.hidden).toBe(false);
                 host.remove();
             });

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

@@ -36,17 +36,15 @@ export const AdwButtonRowTest = async () => {
 
             expect(errors.length).toBe(0);
             expect(row.textContent).toContain('Add account');
-            // The start icon span carries the adw-icon class derived from the name.
             expect(row.querySelector('.adw-icon--list-add') !== null).toBe(true);
-            // Activatable by default.
             expect(row.classList.contains('activatable')).toBe(true);
             host.remove();
         });
 
         // DELETED: `honours activatable="false"`. It was green, and what it
         // pinned was an INVENTION — `Adw.ButtonRow` is always activatable
-        // (`<property name="activatable">True</property>`, adw-button-row.ui:5;
-        // "AdwButtonRow is always activatable.", adw-button-row.c:31), and the
+        // (`<property name="activatable">True</property>`, adw-button-row.ui;
+        // "AdwButtonRow is always activatable."), and the
         // class exposes no property, no setter and no getter for it. The opt-out
         // also gave one markup two opposite meanings inside one package, because
         // <adw-action-row> reads `activatable` by PRESENCE — so