@gjsify/adwaita-web 0.36.0 → 0.38.0

package/src/elements/adw-split-button.ts

@@ -20,26 +20,14 @@
 //                       in libadwaita's emission order.
 //   `menu-activated`  — a menu entry was chosen (detail.label / .action / .index).
 //
-// All of the behavior above lives in `@gjsify/adwaita-core` (ADR 0004) as
-// {@link SplitButtonState}; this element only paints it and translates DOM
-// events into state calls. It used to carry its own copy, and that copy rendered
-// the label AND the icon together (libadwaita clears whichever slot it is not
-// using), could not clear the label at all, hardcoded "Menu" as the dropdown's
-// accessible name, and opened an empty popover when there was no menu. The
-// shared vectors in `@gjsify/adwaita-core/conformance` now pin this element to
-// the C source — see `src/split-button.spec.ts`.
-//
-// The last piece of that copy to go was the direction→arrow table, which
-// outlived the lift and drew the `open-menu` hamburger for `direction="none"`.
-// Only the glyph→mask-class mapping is a renderer concern; see ARROW_MASK_CLASSES.
-//
-// THE POPOVER WENT THE SAME WAY, and it was the worst of the three copies: a
-// 9px (`--button-radius`) surface where libadwaita's is 15px, under a two-layer
-// shadow nothing in the vendored stylesheet has, with NO Escape dismissal and NO
-// arrow-key navigation at all — a menu you could open with the keyboard and then
-// only leave with the mouse. It is now `<adw-popover>`, so those two behaviours
-// arrive with the surface rather than having to be written a third time; the
-// spec cases for exactly them are in `src/split-button.spec.ts`.
+// All of the behaviour above lives in `@gjsify/adwaita-core` (ADR 0004) as
+// {@link SplitButtonState}; this element only paints it and translates DOM events
+// into state calls, pinned to the C source by the shared vectors in
+// `@gjsify/adwaita-core/conformance` (see `src/split-button.spec.ts`). Of the
+// element's own former copies only the glyph→mask-class mapping is a renderer
+// concern — see ARROW_MASK_CLASSES. The menu surface is `<adw-popover>`, which is
+// what brings the 15px radius, Escape dismissal and arrow-key navigation; do not
+// hand-roll a surface here instead.
 //
 // Reference: refs/libadwaita/src/adw-split-button.c (AdwSplitButton)
 // Reference: refs/adwaita-web/adwaita-web/scss/_split_button.scss
@@ -78,19 +66,17 @@ const VARIANT_CLASSES: Record<string, string> = {
 
 /**
  * libadwaita's arrow GLYPH NAMES mapped onto the mask classes
- * `_icons.generated.scss` actually ships. Renderer-specific by nature: the icon
- * set here is the `go-*` family, so no `pan-*` mask exists to map onto.
- *
- * WHICH glyph a direction gets is NOT decided here — {@link splitButtonArrowIcon}
- * owns that, and this table is keyed by its output rather than by direction. That
- * split is the point: keying by direction is how this element came to draw the
- * `open-menu` hamburger for `direction="none"`, where a split button draws the
- * down caret (`splitbutton > menubutton > button > arrow.none`,
- * _buttons.scss:621-623). The mask mapping is a fact about our asset set; the
- * glyph choice is a fact about libadwaita, and only one of them lives here.
+ * `_icons.generated.scss` actually ships. Renderer-specific by nature: the icon set
+ * here is the `go-*` family, so no `pan-*` mask exists to map onto, and
+ * `pan-up-symbolic` reuses `go-down` flipped by the caller rather than drawing a blank
+ * arrow.
  *
- * `pan-up-symbolic` has no mask at all, so it reuses `go-down` flipped by the
- * caller — the alternative is a blank arrow.
+ * WHICH glyph a direction gets is NOT decided here — {@link splitButtonArrowIcon} owns
+ * that, and this table is keyed by its OUTPUT rather than by direction. Keying by
+ * direction is how this element came to draw the `open-menu` hamburger for
+ * `direction="none"`, where a split button draws the down caret
+ * (`splitbutton > menubutton > button > arrow.none`). The mask mapping is a fact about
+ * our asset set, the glyph choice a fact about libadwaita.
  */
 const ARROW_MASK_CLASSES: Readonly<Record<AdwArrowIcon, string>> = {
     'open-menu-symbolic': 'open-menu',
@@ -100,11 +86,9 @@ const ARROW_MASK_CLASSES: Readonly<Record<AdwArrowIcon, string>> = {
     'pan-end-symbolic': 'go-next',
 };
 
-// The `-symbolic` strip AND the token guard that used to live here — as
-// `iconClass`, the ONLY copy of the guard in the package — are
-// `normalizeIconName`'s now, applied by <adw-icon>. Five other places built the
-// same class without the guard; keeping the correct one private is what let
-// them stay wrong.
+// The `-symbolic` strip and the single-CSS-token guard belong to `normalizeIconName`,
+// applied by <adw-icon>: never rebuild the mask class by hand, which is how five sites
+// in this package shipped without the guard.
 
 /**
  * Direction → the CSS axis `<adw-popover>` places the surface on. WHICH
@@ -147,7 +131,6 @@ export class AdwSplitButton extends HTMLElement {
         ];
     }
 
-    /** Whether the dropdown menu is currently open. */
     get active(): boolean {
         return this._state.open;
     }
@@ -164,8 +147,8 @@ export class AdwSplitButton extends HTMLElement {
 
     set label(value: string) {
         this.setAttribute('label', value ?? '');
-        // Setting the label clears the icon (adw-split-button.c:658-659); mirror
-        // that in the DOM so the attributes never contradict the state.
+        // Setting the label clears the icon; mirror that in the DOM so the
+        // attributes never contradict the state.
         this.removeAttribute('icon-name');
     }
 
@@ -179,7 +162,6 @@ export class AdwSplitButton extends HTMLElement {
         this.removeAttribute('label');
     }
 
-    /** The dropdown menu entries. */
     get menuItems(): readonly AdwMenuEntry[] {
         return this._state.menuModel ?? [];
     }
@@ -198,7 +180,6 @@ export class AdwSplitButton extends HTMLElement {
         this.setAttribute('dropdown-tooltip', value ?? '');
     }
 
-    /** The direction the popup opens in, and the arrow points. */
     get direction(): SplitButtonDirection {
         return this._state.direction;
     }
@@ -207,7 +188,6 @@ export class AdwSplitButton extends HTMLElement {
         this.setAttribute('direction', value);
     }
 
-    /** Whether an underline in the label marks a mnemonic. */
     get useUnderline(): boolean {
         return this._state.useUnderline;
     }
@@ -252,8 +232,8 @@ export class AdwSplitButton extends HTMLElement {
         this._menuEl = document.createElement('adw-popover') as AdwPopover;
         this._menuEl.classList.add('adw-split-button-menu');
         this._menuEl.setAttribute('role', 'menu');
-        // The dropdown half IS a GtkMenuButton (adw-split-button.c:997 passes
-        // straight through to it), so its popover is a `popover.menu`.
+        // The dropdown half IS a GtkMenuButton (the C passes straight through to
+        // one), so its popover is a `popover.menu`.
         this._menuEl.setAttribute('menu', '');
         this._menuEl.setAttribute('align', 'end');
 
@@ -315,12 +295,11 @@ export class AdwSplitButton extends HTMLElement {
         this._render();
     }
 
-    /** Seed label/icon/menu/direction/tooltip from the attributes present at connect time. */
     private _syncStateFromAttributes(): void {
         const label = this.getAttribute('label') ?? (this._inlineLabel.length > 0 ? this._inlineLabel : null);
         const iconName = this.getAttribute('icon-name');
         // With both present the icon wins — exactly where `set_label();
-        // set_icon_name();` leaves the widget (adw-split-button.c:749-771).
+        // set_icon_name();` leaves the widget.
         if (label !== null) this._state.setLabel(label);
         if (iconName !== null) this._state.setIconName(iconName);
 
@@ -334,14 +313,12 @@ export class AdwSplitButton extends HTMLElement {
     }
 
     /**
-     * Route a `label` / `icon-name` attribute mutation into the content machine.
-     *
-     * C has no independent "unset" for either slot — clearing one is a side
-     * effect of setting another — so a REMOVED attribute falls back to whichever
-     * sibling is still present, and to the empty child otherwise. That fallback
-     * is what makes `removeAttribute('label')` actually drop the label; it used
-     * to be a silent no-op, so the storybook's icon-only mode rendered the icon
-     * next to a stale "Save".
+     * Route a `label` / `icon-name` attribute mutation into the content machine. C has no
+     * independent "unset" for either slot — clearing one is a side effect of setting
+     * another — so a REMOVED attribute falls back to whichever sibling is still present,
+     * and to the empty child otherwise. Without that fallback
+     * `removeAttribute('label')` is a silent no-op and an icon-only button keeps a stale
+     * label beside its icon.
      */
     private _applyContentAttribute(name: 'label' | 'icon-name', value: string | null): void {
         if (value !== null) {
@@ -366,8 +343,7 @@ export class AdwSplitButton extends HTMLElement {
         }
         this._render();
         // Focus lands in the menu on open, AFTER _render has built the rows —
-        // without it the arrow keys the popover now provides would have nothing
-        // to move from, which is half of why this element had none.
+        // otherwise the popover's arrow keys have nothing to move from.
         if (opened) this._menuEl.items[0]?.focus();
     }
 
@@ -375,9 +351,8 @@ export class AdwSplitButton extends HTMLElement {
         const disabled = this.hasAttribute('disabled');
         this.classList.toggle('disabled', disabled);
         this._actionEl.disabled = disabled;
-        // With neither a menu model nor a popover the dropdown is INSENSITIVE
-        // (adw-split-button.c:376-378, :394-396) — it must not open an empty
-        // popover, which is what the old unguarded click handler did.
+        // With neither a menu model nor a popover the dropdown is INSENSITIVE: it must
+        // not open an empty popover.
         this._dropdownEl.disabled = disabled || !this._state.dropdownEnabled;
 
         this.classList.remove('flat', 'suggested-action', 'destructive-action');
@@ -390,12 +365,10 @@ export class AdwSplitButton extends HTMLElement {
         this._renderMenu();
     }
 
-    /** The action half + the root style classes libadwaita derives from it. */
     private _renderContent(): void {
         const { mode, label, iconName, styleClasses } = this._state;
 
-        // `splitbutton[.image-button][.text-button]` — the documented CSS node
-        // contract (adw-split-button.c:32-50, :145-165).
+        // `splitbutton[.image-button][.text-button]` — the documented CSS node contract.
         this.classList.toggle('image-button', styleClasses.includes('image-button'));
         this.classList.toggle('text-button', styleClasses.includes('text-button'));
 
@@ -417,7 +390,6 @@ export class AdwSplitButton extends HTMLElement {
         else this._actionEl.removeAttribute('aria-label');
     }
 
-    /** The dropdown half: arrow glyph, tooltip/accessible name, expanded state. */
     private _renderDropdown(): void {
         const { direction, open } = this._state;
         const glyph = splitButtonArrowIcon(direction);
@@ -425,18 +397,18 @@ export class AdwSplitButton extends HTMLElement {
         // No pan-up mask ships yet, so it is the down arrow turned over. Keyed off
         // the GLYPH, not the direction: the flip belongs to the mask substitution.
         this._arrowEl.style.transform = glyph === 'pan-up-symbolic' ? 'rotate(180deg)' : '';
-        // Where the popup goes is core's call (`none` → `down`); only the
-        // direction → CSS-axis mapping is ours.
+        // Where the popup goes is core's call (`none` → `down`); only the direction →
+        // CSS-axis mapping is ours.
         this._menuEl.position = POPOVER_POSITIONS[splitButtonPopupDirection(direction)];
 
-        // An empty value RESTORES the translated default (adw-split-button.c:1044-1051)
-        // instead of leaving the button without an accessible name.
+        // An empty value RESTORES the translated default instead of leaving the button
+        // without an accessible name.
         const { text } = resolveDropdownTooltip(this._state.dropdownTooltip);
         this._dropdownEl.title = text;
         this._dropdownEl.setAttribute('aria-label', text);
         this._dropdownEl.setAttribute('aria-expanded', String(open));
 
-        // update_state folds both halves onto the root (adw-split-button.c:118-143).
+        // update_state folds both halves onto the root.
         // The browser gives the ACTIVE half of that fold for free — CSS `:active`
         // matches the ancestors of the pressed element — so only CHECKED, which
         // the arrow half carries while the menu is open, has to be applied here.
@@ -450,7 +422,6 @@ export class AdwSplitButton extends HTMLElement {
         this.classList.toggle('active', open);
     }
 
-    /** The popover contents, one button per menu entry, dispatched BY POSITION. */
     private _renderMenu(): void {
         this._menuEl.replaceChildren();
         this._menuEl.open = this._state.open;
@@ -458,16 +429,15 @@ export class AdwSplitButton extends HTMLElement {
         for (const [index, entry] of (this._state.menuModel ?? []).entries()) {
             const item = document.createElement('button');
             item.type = 'button';
-            // `.adw-popover-item` is what makes the row navigable: it is the
-            // selector `<adw-popover>` walks for arrow/Home/End/Enter, which this
-            // element never had.
+            // `.adw-popover-item` is what makes the row navigable: it is the selector
+            // `<adw-popover>` walks for arrow/Home/End/Enter.
             item.className = 'adw-popover-item adw-split-button-menu-item';
             item.setAttribute('role', 'menuitem');
             item.tabIndex = -1;
             item.textContent = entry.label;
             item.addEventListener('click', () => {
-                // By position, never by label: two entries called "Copy" are
-                // legal and must dispatch their own action (c:385-388).
+                // By position, never by label: two entries called "Copy" are legal
+                // and must each dispatch their own action.
                 const activated = this._state.activateMenuEntry(index);
                 if (activated === null) return;
                 this.dispatchEvent(

package/src/elements/adw-switch-row.ts

@@ -1,26 +1,14 @@
-// <adw-switch-row> — Row with a title/subtitle and a trailing toggle switch.
-// Attributes: title, subtitle, active (boolean)
-// Events: notify::active (CustomEvent, mirrors GJS GObject signal naming)
+// <adw-switch-row> — row with a title/subtitle and a trailing `<adw-switch>`.
 //
-// The ACTIVE flag, its notify rule and the toggle-on-row-activation are HEADLESS
-// and live in `@gjsify/adwaita-core` (ADR 0004) as {@link SwitchRowState}; this
-// element composes it and keeps only the DOM render half — the checkbox, the
-// label column and the `notify::active` event.
-// `@gjsify/adwaita-nativescript` composes the same state, so both ports share one
-// behaviour. Two things this fixes, both from adw-switch-row.c:
-//   - a PROGRAMMATIC `row.active = true` now notifies. The DOM does not fire
-//     `change` for `.checked =`, so keying the event off the checkbox meant the
-//     row was silent — while the NativeScript port, whose `checkedChange` DOES
-//     fire on a programmatic write, notified. libadwaita has exactly one notify
-//     path (`slider_notify_active_cb`, C:66-77) and it cannot see the origin.
-//   - clicking the ROW toggles. `adw_switch_row_init` points the
-//     activatable-widget at the slider (C:160-162), so the title is part of the
-//     control; here only the handle itself worked.
-//
-// The TOGGLE itself is `<adw-switch>`. It used to be built here by hand —
-// `label.adw-switch > input[type=checkbox] + span.adw-switch-slider` — and
-// `<adw-expander-row>` built the identical thing, over a stylesheet block that
-// was a character-for-character copy of this row's.
+// The ACTIVE flag, its notify rule and the toggle-on-row-activation are HEADLESS and live
+// in `@gjsify/adwaita-core` (ADR 0004) as {@link SwitchRowState}; this element keeps only
+// the DOM half — the label column, the switch and the `notify::active` event. Two rules
+// from adw-switch-row.c that a DOM-first implementation gets wrong:
+//   - a PROGRAMMATIC `row.active = true` MUST notify. The DOM fires no `change` for
+//     `.checked =`, so an event keyed off the checkbox leaves the row silent; libadwaita
+//     has exactly one notify path (`slider_notify_active_cb`) and it cannot see the origin.
+//   - clicking the ROW toggles: `adw_switch_row_init` points the activatable-widget at the
+//     slider, so the title is part of the control, not just the handle.
 //
 // Adapted from Adwaita Web UI Framework (https://github.com/mclellac/adwaita-web).
 // Copyright (c) 2025 csm. MIT License.
@@ -30,13 +18,12 @@
 
 import { SwitchRowState, deriveRowLabels } from '@gjsify/adwaita-core';
 
-// SIDE-EFFECT import, deliberately separate from the type import below: it is
-// what guarantees `adw-switch` is defined before this module's own
-// `customElements.define` can upgrade a server-rendered `<adw-switch-row>` and
-// build one. A combined `import { AdwSwitch }` would NOT do it — the binding is
-// only ever used in type position here, and this package compiles without
-// `verbatimModuleSyntax`, so TypeScript would elide the whole statement and take
-// the registration with it.
+// SIDE-EFFECT import, deliberately separate from the type import below: it guarantees
+// `adw-switch` is defined before this module's `customElements.define` can upgrade a
+// server-rendered `<adw-switch-row>` and build one. A combined `import { AdwSwitch }`
+// would NOT do it — the binding is only used in type position, and this package compiles
+// without `verbatimModuleSyntax`, so TypeScript would elide the statement and take the
+// registration with it.
 import './adw-switch.js';
 import type { AdwSwitch } from './adw-switch.js';
 
@@ -80,23 +67,20 @@ export class AdwSwitchRow extends HTMLElement {
 
         this._state.setActive(this.hasAttribute('active'));
         this._switchEl.active = this._state.active;
-        // `gtk_widget_class_set_accessible_role (…, GTK_ACCESSIBLE_ROLE_SWITCH)`
-        // plus the initial CHECKED state (adw-switch-row.c:147, :155-158).
+        // C's `GTK_ACCESSIBLE_ROLE_SWITCH` plus the initial CHECKED state.
         this.setAttribute('role', 'switch');
         this.setAttribute('aria-checked', String(this._state.active));
 
         this._switchEl.addEventListener('notify::active', (event) => {
-            // The ROW is the public event surface — libadwaita has exactly one
-            // notify path for this property (`slider_notify_active_cb`, C:66-77).
-            // Letting the composed switch's own identically-named event escape
-            // would make every listener on the row see each toggle twice.
+            // The ROW is the public event surface, and libadwaita has exactly one notify
+            // path for the property. Letting the composed switch's identically-named event
+            // escape would make every listener on the row see each toggle twice.
             event.stopPropagation();
             this._apply(this._state.setActive(this._switchEl.active));
         });
 
-        // Activating the row inverts the state (adw-switch-row.c:23-27). A click
-        // that landed on the switch itself is already handled by the switch —
-        // toggling again here would immediately undo it.
+        // Activating the row inverts the state. A click that landed on the switch itself is
+        // already handled there; toggling again here would undo it.
         this.addEventListener('click', (event) => {
             if (event.target instanceof Node && this._switchEl.contains(event.target)) return;
             this._apply(this._state.activate());
@@ -112,17 +96,17 @@ export class AdwSwitchRow extends HTMLElement {
     }
 
     /**
-     * Push a state transition out to the DOM and emit `notify::active` — but
-     * only when something actually changed, which is the `g_object_notify`
-     * gate libadwaita puts on the same transition (C:224-225 → :76).
+     * Push a state transition out to the DOM and emit `notify::active`, but only when
+     * something actually changed — the `g_object_notify` gate libadwaita puts on the same
+     * transition.
      */
     private _apply(changed: boolean) {
         if (!changed) return;
-        // Idempotent on the switch's side too, so this write does not bounce
-        // back through the `notify::active` listener as a second transition.
+        // Idempotent on the switch's side too, so this write does not bounce back through
+        // the `notify::active` listener as a second transition.
         this._switchEl.active = this._state.active;
         this.toggleAttribute('active', this._state.active);
-        // The a11y state libadwaita updates alongside the notify (C:71-74).
+        // The a11y state libadwaita updates alongside the notify.
         this.setAttribute('aria-checked', String(this._state.active));
         this.dispatchEvent(
             new CustomEvent('notify::active', {
@@ -138,8 +122,7 @@ export class AdwSwitchRow extends HTMLElement {
             subtitle: this.getAttribute('subtitle'),
         });
         this._titleEl.textContent = title;
-        // `string_is_not_empty` applies to the TITLE too (adw-action-row.ui:49-53,
-        // inherited — AdwSwitchRow derives from AdwActionRow, adw-switch-row.c:50).
+        // `string_is_not_empty` applies to the TITLE too, inherited from AdwActionRow.
         this._titleEl.hidden = !titleVisible;
         this._subtitleEl.textContent = subtitle;
         this._subtitleEl.hidden = !subtitleVisible;

package/src/elements/adw-switch.ts

@@ -1,43 +1,27 @@
 // <adw-switch> — the Adwaita toggle, as an element. A 44×24 track with a hidden
 // checkbox behind it and a knob that slides on `active`.
 //
-// WHY IT EXISTS: `<adw-switch-row>` and `<adw-expander-row>` each built
-// `label.adw-switch > input[type=checkbox] + span.adw-switch-slider` by hand, and
-// `_expander_row.scss:73-121` was a character-for-character copy of
-// `_switch_row.scss:15-63`. The cause was structural — `_switch_row.scss:9`
-// opened `adw-switch-row {` and nested everything inside it, so `.adw-switch` did
-// not exist outside a switch row and the expander could not reuse it. The styles
-// are now the unscoped `scss/_switch.scss` and the markup is here.
+// The styles are the UNSCOPED `scss/_switch.scss`, so `.adw-switch` exists outside a
+// switch row and `<adw-expander-row>` can reuse it instead of copying the block.
 //
-// NO CORE STATE MACHINE. The state is one boolean with no derivation, no
-// ordering and no notify subtlety beyond "on change" — ADR 0004 is explicit that
-// a widget with genuinely trivial behaviour does not get a core class, and the
-// `active` ATTRIBUTE is the state (`toggleAttribute` is idempotent by
-// definition, so "notify only on a real change" needs no guard of its own).
-// `GtkSwitch` does carry a two-phase `active`/`state` pair for async toggles,
-// but `refs/gtk` is EMPTY in this tree so that is unverifiable here, and neither
-// this port nor `@gjsify/adwaita-nativescript` models it — see the ROW's state
-// (`SwitchRowState`), which is where the notify rule that IS derived from C
-// lives.
+// NO CORE STATE MACHINE. The state is one boolean with no derivation, no ordering and no
+// notify subtlety beyond "on change" — ADR 0004 is explicit that trivial behaviour gets
+// no core class, and the `active` ATTRIBUTE is the state (`toggleAttribute` is idempotent,
+// so "notify only on a real change" needs no guard). `GtkSwitch` does carry a two-phase
+// `active`/`state` pair for async toggles, but `refs/gtk` is an uninitialized submodule
+// here so that is unverifiable, and neither this port nor
+// `@gjsify/adwaita-nativescript` models it. The notify rule that IS derived from C lives
+// in the ROW's `SwitchRowState`.
 //
-// Attributes:
-//   active   — boolean; reflects (and drives) the toggled state.
-//   disabled — boolean; the control does not respond and is dimmed.
-// Properties:
-//   active   — the toggled state (get/set).
-//   disabled — whether the control is inert (get/set).
-// Events:
-//   `notify::active` (CustomEvent, bubbles, detail = { active }) — mirrors the
-//     GObject property-notify; fires on every change, programmatic included.
-//     A widget that COMPOSES this one and publishes its own `notify::active`
-//     (`<adw-switch-row>`) stops this one at the switch, so the row stays the
-//     single public event surface.
+// `notify::active` (CustomEvent, bubbles, detail `{ active }`) fires on every change,
+// programmatic included. A widget that COMPOSES this one and publishes its own
+// `notify::active` (`<adw-switch-row>`) stops this one at the switch, so the row stays
+// the single public event surface.
 //
-// A11Y: the checkbox is left bare — no `role="switch"` — because the widgets
-// that host one claim that role themselves (`adw_switch_row_init` sets
-// `GTK_ACCESSIBLE_ROLE_SWITCH` on the ROW, adw-switch-row.c:147), and a nested
-// second switch role would be announced twice. This is exactly the markup that
-// shipped inside the two rows before the extraction.
+// A11Y: the checkbox is left bare — no `role="switch"` — because the widgets that host
+// one claim that role themselves (`adw_switch_row_init` sets
+// `GTK_ACCESSIBLE_ROLE_SWITCH` on the ROW) and a nested second switch role would be
+// announced twice.
 //
 // Reference: refs/adwaita-web/adwaita-web/scss/_switch.scss
 // Reference: refs/libadwaita/src/stylesheet/widgets/_switch.scss
@@ -60,11 +44,10 @@ export class AdwSwitch extends HTMLElement {
     }
 
     set active(value: boolean) {
-        // `toggleAttribute` with a force flag is a no-op when the attribute is
-        // already in the wanted state, so re-setting the current value mutates
-        // nothing and `attributeChangedCallback` — and therefore the notify —
-        // never runs. That idempotence is what a state class would otherwise be
-        // holding.
+        // `toggleAttribute` with a force flag is a no-op when the attribute already holds
+        // the wanted state, so re-setting the current value never runs
+        // `attributeChangedCallback` and never notifies. That idempotence is what a state
+        // class would otherwise hold.
         this.toggleAttribute('active', !!value);
     }
 
@@ -89,18 +72,16 @@ export class AdwSwitch extends HTMLElement {
         this._slider.className = 'adw-switch-slider';
         this.replaceChildren(this._input, this._slider);
 
-        // Keyboard (Space on the focused checkbox) and a direct programmatic
-        // `input.click()` both arrive here; the attribute is the state, so this
-        // just writes it and lets attributeChangedCallback do the rest.
+        // Keyboard (Space on the focused checkbox) and a programmatic `input.click()` both
+        // arrive here; the attribute is the state, so this writes it and lets
+        // attributeChangedCallback do the rest.
         this._input.addEventListener('change', () => {
             this.active = this._input.checked;
         });
 
-        // The slider covers the whole track (`inset: 0`), so every pointer click
-        // lands on it rather than on the 0×0 checkbox — this is the toggle the
-        // wrapping `<label>` used to provide for free. A click that DID reach the
-        // checkbox is already handled by the listener above; toggling again here
-        // would immediately undo it.
+        // The slider covers the whole track (`inset: 0`), so every pointer click lands on
+        // it rather than on the 0×0 checkbox. A click that DID reach the checkbox is
+        // already handled by the listener above; toggling again here would undo it.
         this.addEventListener('click', (event) => {
             if (this.disabled) return;
             if (event.target === this._input) return;