@gjsify/adwaita-web 0.35.0 → 0.37.0

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

@@ -3,9 +3,7 @@
 // `flex-wrap: wrap` with a gap). Mirrors Adw.WrapBox.
 //
 // Attributes — all fourteen of the widget's properties, each with a
-// `notify::<property>` (adw-wrap-box.c:284-497). The element used to carry nine
-// attributes and notify for two, so a consumer binding to any of the other
-// twelve was listening to a signal that could not fire.
+// `notify::<property>`:
 //
 //   child-spacing / line-spacing        (int >= 0, default 0) -> column-gap / row-gap
 //   child-spacing-unit / line-spacing-unit ("px" | "pt" | "sp", default "px")
@@ -19,10 +17,9 @@
 //   wrap-policy      ("minimum" | "natural", default "natural")
 //   natural-line-length (int >= -1, default -1 = unset) + -unit
 //
-// The property CONTRACT — the normalisers and the justify/align/last-line
-// decision — is `@gjsify/adwaita-core`'s `wrap-box.ts`, held to
-// `WRAP_BOX_LINE_VECTORS` and friends, which the NativeScript suite drives too.
-// This element used to carry its own copy of all of it.
+// The property CONTRACT — the normalisers and the justify/align/last-line decision —
+// is `@gjsify/adwaita-core`'s `wrap-box.ts`, held to `WRAP_BOX_LINE_VECTORS` and
+// friends, which the NativeScript suite drives too.
 //
 // Reference: refs/libadwaita/src/adw-wrap-box.c / adw-wrap-layout.c (Adw.WrapBox)
 // Reference: refs/adwaita-web/adwaita-web/scss/_wrap_box.scss
@@ -72,12 +69,10 @@ const PROPERTY_ATTRIBUTES = [
 type PropertyValue = string | number | boolean;
 
 /**
- * `align` as a `justify-content` keyword.
- *
- * C offsets the whole line block by `roundf (length_delta * align)` — a
- * continuum. Flexbox has three main-axis positions, so the nearest one is taken;
- * that is the renderer's approximation, not libadwaita's rule, which is why it
- * lives here and not in the conformance table.
+ * `align` as a `justify-content` keyword. C offsets the whole line block by
+ * `roundf (length_delta * align)` — a continuum — while flexbox has three main-axis
+ * positions, so the nearest one is taken. That approximation is the renderer's, not
+ * libadwaita's rule, which is why it lives here and not in the conformance table.
  */
 function alignToJustifyContent(align: number): string {
     if (align < 0.25) return 'flex-start';
@@ -92,8 +87,6 @@ export class AdwWrapBox extends HTMLElement {
         return [...PROPERTY_ATTRIBUTES];
     }
 
-    // --- properties ---
-
     /** Spacing between children on the same line, in `child-spacing-unit`. */
     get childSpacing(): number {
         return normalizeWrapBoxSpacing(this.getAttribute('child-spacing'));
@@ -103,7 +96,6 @@ export class AdwWrapBox extends HTMLElement {
         this.setAttribute('child-spacing', String(value));
     }
 
-    /** The unit `child-spacing` is written in. Defaults to `px`, as in C. */
     get childSpacingUnit(): AdwLengthUnit {
         return normalizeWrapBoxLengthUnit(this.getAttribute('child-spacing-unit'));
     }
@@ -121,7 +113,6 @@ export class AdwWrapBox extends HTMLElement {
         this.setAttribute('line-spacing', String(value));
     }
 
-    /** The unit `line-spacing` is written in. Defaults to `px`, as in C. */
     get lineSpacingUnit(): AdwLengthUnit {
         return normalizeWrapBoxLengthUnit(this.getAttribute('line-spacing-unit'));
     }
@@ -139,7 +130,6 @@ export class AdwWrapBox extends HTMLElement {
         this.setAttribute('align', String(value));
     }
 
-    /** Whether and how each line is stretched to fill the widget. */
     get justify(): 'none' | 'fill' | 'spread' {
         return normalizeWrapBoxJustify(this.getAttribute('justify'));
     }
@@ -166,7 +156,6 @@ export class AdwWrapBox extends HTMLElement {
         this.setAttribute('wrap-policy', value);
     }
 
-    /** The direction children are packed in each line. */
     get packDirection(): 'start-to-end' | 'end-to-start' {
         return normalizeWrapBoxPackDirection(this.getAttribute('pack-direction'));
     }
@@ -184,7 +173,6 @@ export class AdwWrapBox extends HTMLElement {
         this.toggleAttribute('wrap-reverse', !!value);
     }
 
-    /** Whether every line takes the same amount of space. */
     get lineHomogeneous(): boolean {
         return this.hasAttribute('line-homogeneous');
     }
@@ -202,7 +190,6 @@ export class AdwWrapBox extends HTMLElement {
         this.setAttribute('natural-line-length', String(value));
     }
 
-    /** The unit `natural-line-length` is written in. Defaults to `px`, as in C. */
     get naturalLineLengthUnit(): AdwLengthUnit {
         return normalizeWrapBoxLengthUnit(this.getAttribute('natural-line-length-unit'));
     }
@@ -211,7 +198,6 @@ export class AdwWrapBox extends HTMLElement {
         this.setAttribute('natural-line-length-unit', value);
     }
 
-    /** The axis children are packed along. */
     get orientation(): 'horizontal' | 'vertical' {
         return this.getAttribute('orientation') === 'vertical' ? 'vertical' : 'horizontal';
     }
@@ -220,37 +206,31 @@ export class AdwWrapBox extends HTMLElement {
         this.setAttribute('orientation', value);
     }
 
-    // --- child list (adw_wrap_box_insert_child_after / reorder / remove_all) ---
-    //
-    // `adw_wrap_box_append`, `_prepend` and `_remove` are deliberately NOT
-    // redeclared: `ParentNode.append` / `.prepend` and `Node.removeChild` are
-    // those three, with the same semantics, and shadowing them would give this
-    // element two spellings of one operation. Only the three the DOM has no
-    // counterpart for are added.
+    // `adw_wrap_box_append`, `_prepend` and `_remove` are deliberately NOT redeclared:
+    // `ParentNode.append` / `.prepend` and `Node.removeChild` ARE those three, with the
+    // same semantics, and shadowing them would give this element two spellings of one
+    // operation. Only the three the DOM has no counterpart for are added.
 
-    /** The element children, which are what the layout actually lays out. */
     private get _children(): Element[] {
         return [...this.children];
     }
 
     /**
-     * `adw_wrap_box_insert_child_after` (adw-wrap-box.c:1283-1300).
-     *
-     * A NULL/absent `sibling` inserts at the FIRST position, not the last —
-     * `gtk_widget_insert_after`'s documented rule, pinned by
-     * `WRAP_BOX_CHILD_ORDER_VECTORS`. Returns whether the insert happened; a
-     * refusal is where C would have hit a `g_return_if_fail`.
+     * `adw_wrap_box_insert_child_after`. A NULL/absent `sibling` inserts at the FIRST
+     * position, not the last — `gtk_widget_insert_after`'s documented rule, pinned by
+     * `WRAP_BOX_CHILD_ORDER_VECTORS`. Returns whether the insert happened; a refusal is
+     * where C would have hit a `g_return_if_fail`.
      */
     insertChildAfter(child: Element, sibling: Element | null = null): boolean {
         return this._applyOrder('insert-after', child, sibling);
     }
 
-    /** `adw_wrap_box_reorder_child_after` (adw-wrap-box.c:1315-1332). Same NULL rule. */
+    /** `adw_wrap_box_reorder_child_after`. Same NULL rule. */
     reorderChildAfter(child: Element, sibling: Element | null = null): boolean {
         return this._applyOrder('reorder-after', child, sibling);
     }
 
-    /** `adw_wrap_box_remove_all` (adw-wrap-box.c:1406-1414). */
+    /** `adw_wrap_box_remove_all`. */
     removeAll(): void {
         for (const child of this._children) this.removeChild(child);
     }
@@ -267,8 +247,6 @@ export class AdwWrapBox extends HTMLElement {
         return true;
     }
 
-    // --- lifecycle ---
-
     connectedCallback() {
         if (this._initialized) return;
         this._initialized = true;
@@ -278,10 +256,9 @@ export class AdwWrapBox extends HTMLElement {
     attributeChangedCallback(name: string, old: string | null, value: string | null) {
         if (!this._initialized) return;
         this._sync();
-        // C compares AFTER normalising and returns early when nothing changed
-        // (adw-wrap-box.c:592-593), so `child-spacing="-5"` on a box already at 0
-        // notifies nobody. The same gate applies to every property, not just the
-        // two spacings this element used to special-case.
+        // C compares AFTER normalising and returns early when nothing changed, so
+        // `child-spacing="-5"` on a box already at 0 notifies nobody. The gate applies to
+        // EVERY property, not just the two spacings.
         const next = this._normalized(name, value);
         if (next === this._normalized(name, old)) return;
         this.dispatchEvent(new CustomEvent(`notify::${name}`, { bubbles: true, detail: { [name]: next } }));
@@ -319,7 +296,6 @@ export class AdwWrapBox extends HTMLElement {
         const style = this.style;
         const vertical = this.orientation === 'vertical';
 
-        // Main axis is the packing direction; lines wrap along the cross axis.
         const direction = vertical ? 'column' : 'row';
         style.flexDirection = this.packDirection === 'end-to-start' ? `${direction}-reverse` : direction;
         style.flexWrap = this.wrapReverse ? 'wrap-reverse' : 'wrap';
@@ -345,14 +321,13 @@ export class AdwWrapBox extends HTMLElement {
         const justifyLastLine = this.justifyLastLine;
         const align = this.align;
 
-        // A flex container has ONE `justify-content` and applies it to every
-        // line, so it carries the COMPLETE-line rule; the final-line rule is
-        // published beside it for the stylesheet, which reaches that line through
-        // the only two selectors CSS offers — `:only-child` (a box with one child
-        // has one line, and it is the last) and the generated `::after` filler.
-        // The pair is deliberately never collapsed into one attribute: flexbox
-        // cannot express "every line but the last", and pretending otherwise is
-        // what made `justify-last-line` a no-op in the first place.
+        // A flex container has ONE `justify-content` and applies it to every line, so it
+        // carries the COMPLETE-line rule; the final-line rule is published beside it for
+        // the stylesheet, which reaches that line through the only two selectors CSS
+        // offers — `:only-child` (a box with one child has one line, and it is the last)
+        // and the generated `::after` filler. Never collapse the pair into one attribute:
+        // flexbox cannot express "every line but the last", and pretending it can is what
+        // makes `justify-last-line` a no-op.
         const line = resolveWrapBoxLine({ justify, justifyLastLine, align, lastLine: false, childrenInLine: 2 });
         const lastLine = resolveWrapBoxLine({ justify, justifyLastLine, align, lastLine: true, childrenInLine: 2 });
         this.dataset.lineJustify = line.justify;
@@ -367,12 +342,11 @@ export class AdwWrapBox extends HTMLElement {
         // flexbox approximates by stretching the lines across the cross axis.
         style.alignContent = this.lineHomogeneous ? 'stretch' : 'flex-start';
 
-        // `wrap-policy` decides whether an overflowing line squeezes its children
-        // or lets them spill. CSS defaults `flex-shrink` to 1, i.e. to
-        // ADW_WRAP_MINIMUM — the value libadwaita does NOT default to, so an
-        // unset policy has been drawing the wrong one on every wrap box. What
-        // flexbox cannot do either way is pack MORE children onto a line, since
-        // line breaking runs on hypothetical sizes; see `wrapPolicyFlexShrink`.
+        // `wrap-policy` decides whether an overflowing line squeezes its children or lets
+        // them spill. CSS defaults `flex-shrink` to 1, i.e. to ADW_WRAP_MINIMUM — which is
+        // NOT libadwaita's default, so the policy has to be written out explicitly. What
+        // flexbox cannot do either way is pack MORE children onto a line, since line
+        // breaking runs on hypothetical sizes; see `wrapPolicyFlexShrink`.
         style.setProperty('--adw-wrap-box-child-shrink', String(wrapPolicyFlexShrink(this.wrapPolicy)));
 
         // DELIBERATE DEVIATION: libadwaita's `natural-line-length` caps the box's

package/src/elements/view-switcher-dom.ts

@@ -9,11 +9,8 @@
 // NAME turned into a CSS mask class, an indicator span, and a `setTimeout`
 // wrapped in the scheduler seam the core takes for the drag-hover dwell.
 //
-// Shared by all three switcher elements because it was three copies before:
-// `<adw-view-switcher>`, `<adw-inline-view-switcher>` and
-// `<adw-view-switcher-bar>` each built their own icon span and their own page
-// parsing, and the copies had already drifted (a titleless page rendered `''` in
-// one and `page-<index>` in another).
+// Shared by `<adw-view-switcher>`, `<adw-inline-view-switcher>` and
+// `<adw-view-switcher-bar>`, so their icon nodes and page parsing cannot drift apart.
 //
 // Reference: refs/libadwaita/src/adw-view-switcher.c
 // Reference: refs/libadwaita/src/adw-indicator-bin.c
@@ -26,11 +23,9 @@ import type { AdwViewSwitcherPageInit, ViewSwitcherScheduler, ViewSwitcherTimerH
 import { type AdwIcon, createAdwIcon } from './adw-icon.js';
 
 /**
- * The browser's timer behind the core's scheduler seam.
- *
- * One shared instance rather than one per element: it holds no state, and the
- * seam exists so the CORE stays free of a global timer, not so each element
- * invents its own.
+ * The browser's timer behind the core's scheduler seam. One shared instance rather than
+ * one per element: it holds no state, and the seam exists so the CORE stays free of a
+ * global timer, not so each element invents its own.
  */
 export const domViewSwitcherScheduler: ViewSwitcherScheduler = {
     schedule(callback: () => void, ms: number): ViewSwitcherTimerHandle {
@@ -62,19 +57,17 @@ export function applySwitcherIcon(icon: AdwIcon, iconName: string): void {
 /**
  * Read a declared page element into the core's page init.
  *
- * `getAttribute` returns `null` for an absent attribute, which is EXACTLY C's
- * NULL — so the values are passed through unchanged rather than defaulted to
- * `''`. That `?? ''` is what made the button-visibility rule unimplementable in
- * the old code: once an absent title has become the empty string, "the page has
- * no title" is no longer expressible.
+ * `getAttribute` returns `null` for an absent attribute, which is EXACTLY C's NULL, so
+ * values are passed through unchanged rather than defaulted to `''`. Do not add a
+ * `?? ''`: once an absent title has become the empty string, "the page has no title" is
+ * no longer expressible and the button-visibility rule cannot be implemented.
  */
 export function readSwitcherPage(element: Element): AdwViewSwitcherPageInit {
     const badge = Number.parseInt(element.getAttribute('badge-number') ?? '', 10);
     return {
-        // A page with no `name` is the page named '' — the same choice
-        // `<adw-view-stack>` made, and for the same reason: C stores the name
-        // verbatim (adw-view-stack.c:1170) and an invented `page-<index>` is
-        // addressable by a name the author never wrote.
+        // A page with no `name` is the page named '', as in `<adw-view-stack>`: C stores
+        // the name verbatim, and an invented `page-<index>` would be addressable by a
+        // name the author never wrote.
         name: element.getAttribute('name') ?? '',
         title: element.getAttribute('title'),
         iconName: element.getAttribute('icon-name'),
@@ -88,8 +81,8 @@ export function readSwitcherPage(element: Element): AdwViewSwitcherPageInit {
 
 /**
  * Paint `AdwIndicatorBin`'s badge/dot onto a span: the badge text when there is
- * one, a bare dot when only `needs-attention` is set, nothing otherwise
- * (adw-indicator-bin.c:58-68 + the `.needs-attention` style class).
+ * one, a bare dot when only `needs-attention` is set, nothing otherwise — C's
+ * `AdwIndicatorBin` plus the `.needs-attention` style class.
  */
 export function applyIndicator(indicator: HTMLElement, badgeLabel: string, needsAttention: boolean): void {
     indicator.textContent = badgeLabel;
@@ -100,7 +93,7 @@ export function applyIndicator(indicator: HTMLElement, badgeLabel: string, needs
 /**
  * Mirror the derived screen-reader description onto the element, REMOVING the
  * attribute when there is none — `update_description_cb` resets the accessible
- * property rather than setting it to `""` (adw-view-switcher-button.c:104-113).
+ * property rather than setting it to `""`.
  */
 export function applyDescription(element: HTMLElement, description: string): void {
     if (description) element.setAttribute('aria-description', description);

package/src/entry-rows.spec.ts

@@ -2,12 +2,10 @@
 // driven by the SAME vectors the NativeScript renderer asserts against
 // (`@gjsify/adwaita-core/conformance`).
 //
-// Everything these vectors describe used to be MISSING here, not merely
-// different: `update_empty`'s truth table, the apply button (declared `true` in
-// the shared story metadata all along), the Enter key, max-length, the caps-lock
-// warning and its two suppression rules. Nothing failed, because nothing
-// compared this renderer to the C. This suite is that comparison — it drives the
-// real elements through each scenario and reads back what a user would see.
+// The vectors cover `update_empty`'s truth table, the apply button, the Enter key,
+// max-length, and the caps-lock warning with its two suppression rules — all of which
+// were missing from this renderer, not merely different. Each scenario drives the real
+// elements and reads back what a user would see.
 import { describe, expect, it } from '@gjsify/unit';
 
 import {
@@ -141,9 +139,8 @@ export const AdwEntryRowsTest = async () => {
                 parts.row.maxLength = 0;
                 parts.row.text = '';
                 parts.row.maxLength = maxLength;
-                // Type it: the `input` event path must clamp exactly like the
-                // property path, which is why `input.maxLength` (UTF-16 units)
-                // is deliberately left unset.
+                // The `input` event path must clamp exactly like the property path, which
+                // is why `input.maxLength` (UTF-16 units) is deliberately left unset.
                 parts.input.value = text;
                 parts.input.dispatchEvent(new Event('input', { bubbles: true }));
                 expect(parts.input.value).toBe(clamped);
@@ -166,8 +163,8 @@ export const AdwEntryRowsTest = async () => {
         }
 
         await it('activates the default BEFORE emitting entry-activated', () => {
-            // C:253-256 — gtk_widget_activate_default is line 254, the signal is
-            // line 256. Implicit form submission is the web's default activation.
+            // `gtk_widget_activate_default` runs before the `entry-activated` signal;
+            // implicit form submission is the web's spelling of that default activation.
             const host = document.createElement('div');
             document.body.appendChild(host);
             host.innerHTML = '<form><adw-entry-row title="T" activates-default></adw-entry-row></form>';
@@ -210,9 +207,8 @@ export const AdwEntryRowsTest = async () => {
 
     await describe('adw-entry-row change signals', async () => {
         await it('emits both GtkEditable spellings on every buffer change', () => {
-            // libadwaita implements GtkEditable through a delegate (C:87-93,
-            // :821-834), so an AdwEntryRow emits `changed` AND `notify::text`.
-            // The two ports had each picked one and drifted apart.
+            // libadwaita implements GtkEditable through a DELEGATE, so an AdwEntryRow emits
+            // `changed` AND `notify::text` — a port must not pick just one.
             const parts = mount('adw-entry-row', 'adw-entry-row');
             const recorded = recordEvents(parts.row, ['changed', 'notify::text', 'notify::text-length']);
             parts.row.text = 'Ada';
@@ -255,8 +251,8 @@ export const AdwEntryRowsTest = async () => {
 
     await describe('adw-entry-row light-DOM children (GtkBuildable)', async () => {
         await it('keeps author children instead of discarding them', () => {
-            // `replaceChildren(text, edit)` used to throw every authored child
-            // away silently. add_suffix (C:885-899) appends into a BOX.
+            // `replaceChildren(text, edit)` throws every authored child away silently,
+            // where `add_suffix` appends into a BOX.
             const parts = mount('adw-entry-row', 'adw-entry-row', '<button id="go">Go</button>');
             const go = parts.row.querySelector('#go') as HTMLElement;
             expect(go).not.toBe(null);
@@ -281,9 +277,8 @@ export const AdwEntryRowsTest = async () => {
 
     await describe('adw-entry-row click-to-focus (pressed_cb)', async () => {
         await it('focuses the entry when the row body is clicked', () => {
-            // C:201-227 — the click lands on the row, the header, the editable
-            // area, the indicator or an affordance box, and grabs focus. The port
-            // had this inverted: only the pencil focused, the body was inert.
+            // The click lands on the row, the header, the editable area, the indicator or
+            // an affordance box, and grabs focus — not only on the pencil.
             const parts = mount('adw-entry-row', 'adw-entry-row');
             parts.row.click();
             expect(document.activeElement).toBe(parts.input);
@@ -365,20 +360,19 @@ export const AdwEntryRowsTest = async () => {
         });
 
         await it('keeps the peek toggle when a consumer adds a suffix', () => {
-            // add_suffix appends into a box (C:885-899) and the toggle is
-            // installed through it (adw-password-entry-row.c:152), so both stay.
+            // `add_suffix` appends into a box and the toggle is installed through it, so
+            // both stay.
             const parts = mount('adw-password-entry-row', 'adw-password-entry-row', '<button id="go">Go</button>');
             const suffixes = parts.row.querySelector('.adw-password-entry-row-suffixes') as HTMLElement;
             expect(suffixes.querySelector('.adw-password-entry-row-toggle')).not.toBe(null);
             expect(suffixes.querySelector('#go')).not.toBe(null);
-            // C:152 — the row's own toggle is the FIRST suffix.
+            // The row's own toggle is the FIRST suffix.
             expect(suffixes.children[0]?.classList.contains('adw-password-entry-row-toggle')).toBe(true);
             parts.host.remove();
         });
 
         await it('inherits the entry row rather than copying it', () => {
-            // The two element files used to be a normalized-diff-identical
-            // copy-paste; the password row now IS an entry row.
+            // The password row IS an entry row, not a copy-paste of one.
             const parts = mount('adw-password-entry-row', 'adw-password-entry-row');
             parts.row.showApplyButton = true;
             parts.input.focus();

package/src/index.ts

@@ -8,11 +8,10 @@
 import '@gjsify/adwaita-fonts'; // Registers @font-face (fontsource pattern)
 import { ADWAITA_WEB_CSS } from './styles.generated.js';
 
-// Self-apply the compiled stylesheet on import. This makes `import
-// '@gjsify/adwaita-web'` enough to style the components under ANY bundler —
+// Self-applied so `import '@gjsify/adwaita-web'` styles the components under ANY bundler:
 // a separate `import '@gjsify/adwaita-web/style.css'` is a no-op under a gjsify
-// `--app browser` build (css-as-string yields a string a side-effect import
-// discards), which used to leave consumers unstyled. Idempotent + browser-only.
+// `--app browser` build, where css-as-string yields a string a side-effect import
+// discards and the consumer ends up unstyled. Idempotent + browser-only.
 if (typeof document !== 'undefined' && !document.getElementById('adwaita-web-style')) {
     const style = document.createElement('style');
     style.id = 'adwaita-web-style';
@@ -24,7 +23,6 @@ if (typeof document !== 'undefined' && !document.getElementById('adwaita-web-sty
 // `AdwBreakpoint`, and the `breakpoint="…"` attribute wiring the split views use.
 export { addBreakpoints, bindBreakpointSetter } from './breakpoints.js';
 
-// Register custom elements (side-effect imports)
 export { AdwAvatar } from './elements/adw-avatar.js';
 export { AdwBanner } from './elements/adw-banner.js';
 export { AdwCard } from './elements/adw-card.js';
@@ -43,23 +41,23 @@ export { AdwHeaderBar } from './elements/adw-header-bar.js';
 export { AdwWindowTitle } from './elements/adw-window-title.js';
 export { AdwButton } from './elements/adw-button.js';
 export { AdwButtonContent } from './elements/adw-button-content.js';
-// The ONE symbolic-icon node and the ONE toggle. Exported before the widgets
-// that build them so the barrel's definition order matches theirs; each host
-// ALSO imports them directly, which is what actually guarantees the tags are
-// defined before a server-rendered host upgrades.
+// The ONE symbolic-icon node and the ONE toggle, exported before the widgets that build
+// them so the barrel's definition order matches theirs. Each host ALSO imports them
+// directly, which is what actually guarantees the tags are defined before a
+// server-rendered host upgrades.
 export { AdwIcon, createAdwIcon } from './elements/adw-icon.js';
 export { AdwSwitch } from './elements/adw-switch.js';
 // The two form-control primitives. ONE module, because upstream merges their
 // stylesheet (`_checks.scss`; there is no `_radio.scss` in libadwaita) and
 // everything but the corner radius, the glyph and the group is shared.
 export { AdwCheckbox, AdwRadio } from './elements/adw-checks.js';
-// The determinate progress indicator — <adw-spinner> covers only the
-// indeterminate case.
+// The determinate progress indicator — <adw-spinner> covers only the indeterminate case.
 export { AdwProgressBar } from './elements/adw-progress-bar.js';
-// The ONE popover surface. Exported before its three hosts so the barrel's own
-// definition order matches theirs; each host ALSO imports it directly, which is
-// what actually guarantees `adw-popover` is defined before a server-rendered
-// host upgrades and builds one.
+// A keyboard shortcut, drawn as keycaps. The accelerator GRAMMAR lives in
+// @gjsify/adwaita-core; this element only builds the nodes.
+export { AdwShortcutLabel } from './elements/adw-shortcut-label.js';
+// The ONE popover surface, exported before its three hosts for the same reason as
+// <adw-icon> above.
 export { AdwPopover } from './elements/adw-popover.js';
 export type { AdwPopoverAlign, AdwPopoverPosition, AdwPopoverRole } from './elements/adw-popover.js';
 export { AdwSplitButton } from './elements/adw-split-button.js';

package/src/navigation-view.spec.ts

@@ -2,14 +2,11 @@
 // vectors the NativeScript renderer and the headless core assert against
 // (`@gjsify/adwaita-core/conformance`).
 //
-// The two renderers used to carry independent copies of the whole stack machine,
-// and both had drifted away from libadwaita in different directions. Four rows in
-// the shared table fail against the pre-lift code here: `pop()` refused a
-// `can-pop="false"` page (the C documents the opposite), `replace(['some-tag'])`
-// blanked the view when the tag belonged to a dynamically-pushed page,
-// `popToTag()` stopped early at a `can-pop="false"` page and emitted N separate
-// transitions instead of one, and a duplicate `tag` was accepted silently.
-// Nothing failed, because nothing compared them. This suite is that comparison.
+// Four rows of the shared table are the ones independent copies of the stack machine got
+// wrong: a programmatic `pop()` IGNORES `can-pop` (which gates only the back button and
+// the shortcut pops), `replace(['some-tag'])` resolves a tag belonging to a
+// dynamically-pushed page, `popToTag()` pops in ONE atomic splice emitting one
+// transition rather than N, and a duplicate `tag` is refused, not silently accepted.
 import { describe, expect, it } from '@gjsify/unit';
 
 import {
@@ -269,7 +266,7 @@ export const AdwNavigationViewTest = async () => {
             expect(backButton(view)).toBe(null);
             view.pushByTag('detail');
             // The old element hardcoded "Back" here, where the C uses the title of
-            // the page the button reveals (adw-back-button.c query_tooltip:411-417).
+            // the page the button reveals (adw-back-button.c query_tooltip).
             expect(backButton(view)?.getAttribute('tooltip')).toBe('Home');
 
             view.pop();
@@ -406,7 +403,7 @@ export const AdwNavigationViewTest = async () => {
 
         await it('stops Alt+Left WITHOUT popping a can-pop="false" page', () => {
             // GDK_EVENT_STOP so the key never reaches an enclosing navigation view
-            // (pop_shortcut_cb:1150-1152).
+            // (pop_shortcut_cb).
             const { adapter, view, host, page } = mountView();
             adapter.add(page('root'));
             adapter.add(page('detail'));

package/src/preferences-search.ts

@@ -7,7 +7,7 @@
 // the core reasons over.
 //
 // Reference: refs/libadwaita/src/adw-preferences-dialog.c
-//   (adw_preferences_dialog_init's page/group/row model, :617-641)
+//   (adw_preferences_dialog_init's page/group/row model)
 // Reference: refs/libadwaita/src/adw-action-row.c, adw-entry-row.c,
 //   adw-expander-row.c, adw-button-row.c (which rows ARE action rows)
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
@@ -22,16 +22,14 @@ import {
 } from '@gjsify/adwaita-core';
 
 /**
- * The rows that derive from `AdwActionRow` and therefore have their SUBTITLE
- * searched (`filter_search_results`, adw-preferences-dialog.c:140-146).
+ * The rows that derive from `AdwActionRow` and therefore have their SUBTITLE searched
+ * (`filter_search_results`).
  *
- * A tag-name set rather than an `instanceof` chain, because the browser
- * elements are all direct `HTMLElement` subclasses — the GObject hierarchy is
- * not reproduced in the DOM, so the distinction has to be stated. It is not
- * "has a subtitle": `adw-entry-row`, `adw-expander-row` and `adw-button-row`
- * all derive from `AdwPreferencesRow` in C (adw-entry-row.c:90,
- * adw-expander-row.c:72, adw-button-row.c:74), so the text typed into an entry
- * row is deliberately NOT searchable.
+ * A tag-name set rather than an `instanceof` chain, because the browser elements are all
+ * direct `HTMLElement` subclasses: the GObject hierarchy is not reproduced in the DOM, so
+ * the distinction has to be stated. The test is NOT "has a subtitle" —
+ * `adw-entry-row`, `adw-expander-row` and `adw-button-row` derive from
+ * `AdwPreferencesRow` in C, so text typed into an entry row is deliberately not searchable.
  */
 const ACTION_ROW_TAGS: ReadonlySet<string> = new Set([
     'adw-action-row',
@@ -42,11 +40,9 @@ const ACTION_ROW_TAGS: ReadonlySet<string> = new Set([
 
 /**
  * `ADW_IS_PREFERENCES_ROW` for the browser elements — the first clause of
- * `row_has_title` (adw-preferences-group.c:158-173).
- *
- * Spelled out rather than inferred from the `adw-` prefix, because a group's
- * boxed list legitimately holds other things: a bare `<adw-button>` dropped in
- * as a footer is not a preferences row and must not be searchable.
+ * `row_has_title`. Spelled out rather than inferred from the `adw-` prefix, because a
+ * group's boxed list legitimately holds other things: a bare `<adw-button>` dropped in as
+ * a footer is not a preferences row and must not be searchable.
  */
 const PREFERENCES_ROW_TAGS: ReadonlySet<string> = new Set([
     ...ACTION_ROW_TAGS,

package/src/preferences.spec.ts

@@ -2,14 +2,12 @@
 // <adw-preferences-dialog>, driven by the SAME vectors the NativeScript
 // renderer asserts against (`@gjsify/adwaita-core/conformance`).
 //
-// Two things are being held here. First, the group header: this element derived
-// two of the five states by hand and was missing the other three, so an empty
-// group kept painting a `.boxed-list` card (its `box-shadow` strokes a
-// full-width hairline over nothing) and no header ever carried the `single-line`
-// class the stylesheet keys its metrics off. Second, the search: it did not
-// exist in this port at all, and the dialog actively prevented it by hoisting
-// every page's children out of the page element and discarding the pages —
-// leaving nothing to derive `General → Appearance` from.
+// Two things are held here. The GROUP HEADER has five states, all five derived: an empty
+// group must not paint a `.boxed-list` card (its `box-shadow` strokes a full-width
+// hairline over nothing) and a one-line header carries the `single-line` class the
+// stylesheet keys its metrics off. The SEARCH needs the page elements to survive — a
+// dialog that hoists every page's children out and discards the pages leaves nothing to
+// derive `General → Appearance` from.
 import { describe, expect, it } from '@gjsify/unit';
 
 import {
@@ -49,8 +47,8 @@ function mountGroup(options: {
     }
 
     host.appendChild(group);
-    // Set AFTER connect so the attribute path is exercised, and via
-    // setAttribute so exact whitespace survives (` ` is a visible title).
+    // Set AFTER connect to exercise the attribute path, and via setAttribute so exact
+    // whitespace survives (` ` is a visible title).
     if (options.title !== undefined && options.title !== null) group.setAttribute('title', options.title);
     if (options.description !== undefined && options.description !== null) {
         group.setAttribute('description', options.description);
@@ -97,8 +95,8 @@ function mountSearchDialog(pages: readonly PreferencesSearchPage[]): {
             if (group.visible === false) groupEl.hidden = true;
 
             for (const row of group.rows) {
-                // An action row has a searchable subtitle; an entry row does
-                // not, and that difference is the point of the vector.
+                // An action row has a searchable subtitle and an entry row does not — the
+                // point of the vector.
                 const rowEl = document.createElement(row.isActionRow ? 'adw-action-row' : 'adw-entry-row');
                 rowEl.setAttribute('title', row.title);
                 if (row.subtitle) rowEl.setAttribute('subtitle', row.subtitle);
@@ -107,8 +105,8 @@ function mountSearchDialog(pages: readonly PreferencesSearchPage[]): {
             }
             pageEl.appendChild(groupEl);
         }
-        // Through the public add(), i.e. AFTER connect — the path that used to
-        // leave a page rendering outside the dialog card.
+        // Through the public add(), i.e. AFTER connect: the path that can leave a page
+        // rendering outside the dialog card.
         dialog.add(pageEl);
     }
     return { dialog, host };
@@ -170,7 +168,7 @@ export const AdwPreferencesTest = async () => {
             const { group, host } = mountGroup({ title: 'Account', rowCount: 1 });
             const foreign = document.createElement('adw-action-row');
             document.body.appendChild(foreign);
-            // ADW_CRITICAL_CANNOT_REMOVE_CHILD (adw-preferences-group.c:437).
+            // ADW_CRITICAL_CANNOT_REMOVE_CHILD.
             expect(group.removeRow(foreign)).toBe(false);
             foreign.remove();
             host.remove();