@gjsify/adwaita-web 0.36.0 → 0.37.0

package/src/elements/adw-icon.ts

@@ -1,43 +1,27 @@
-// <adw-icon> — the symbolic icon node, as an element instead of a shape you
-// retype. Every icon in this package is a CSS-masked box whose glyph comes from
-// a generated `.adw-icon--<name>` class and whose colour is `currentColor`, so
-// it themes with whatever contains it.
-//
-// WHY IT EXISTS: `<span class="adw-icon adw-icon--<name>" aria-hidden="true">`
-// was built by hand at TWENTY-THREE sites across SEVENTEEN files, NINE of which
-// re-derived the name (`name.replace(/-symbolic$/, '')`) on the spot — one of
-// them unanchored. Exactly ONE site (`<adw-split-button>`) also checked the
-// result was a single CSS token. The others did not, so `icon-name="a b"`
-// interpolated into `class="adw-icon adw-icon--a b"` and shipped a stray `b`
-// class; that was live on `<adw-menu-button>`, for its own icon and for every
-// JSON menu entry's. The derivation now happens once, in
-// `@gjsify/adwaita-core`'s {@link normalizeIconName} (guard included), and the
-// markup happens once, here.
+// <adw-icon> — the symbolic icon node as an element. Every icon in this package is a
+// CSS-masked box whose glyph comes from a generated `.adw-icon--<name>` class and
+// whose colour is `currentColor`, so it themes with whatever contains it. The name
+// derivation and its guard live once in `@gjsify/adwaita-core`'s
+// {@link normalizeIconName}, the markup once here.
 //
 // Attributes:
-//   icon-name — symbolic name, with or without the `-symbolic` suffix. A name
-//               that is not a single CSS token (a space, a quote, a
-//               reverse-DNS application id) resolves to NO icon rather than to
-//               injected markup — see `normalizeIconName`.
-//   size      — the rendered edge length in px. Absent leaves the stylesheet's
-//               16px in charge; a context that sizes its own icons through CSS
-//               (`.adw-about-dialog-icon`, the split button's 14px arrows) keeps
-//               doing exactly that and should NOT set this.
-// Properties:
-//   iconName         — the declared name (get/set; reflects to the attribute).
-//   resolvedIconName — what actually reached the mask class ('' = no icon).
-//   size             — the px size, or null when the stylesheet decides (get/set).
+//   icon-name — symbolic name, with or without the `-symbolic` suffix. A name that is
+//               not a single CSS token (a space, a quote, a reverse-DNS application
+//               id) resolves to NO icon rather than to injected markup.
+//   size      — rendered edge length in px. Absent leaves the stylesheet's 16px in
+//               charge; a context that sizes its own icons through CSS
+//               (`.adw-about-dialog-icon`, the split button's 14px arrows) keeps doing
+//               exactly that and should NOT set this.
 //
-// THE ELEMENT *IS* THE ICON BOX — it carries `.adw-icon` itself rather than
-// wrapping a span. A wrapper would have inserted a layout node into flex rows,
-// button interiors and absolutely-positioned arrows that were all measured
-// against the icon box directly; carrying the class keeps every existing
-// class-scoped rule (`.adw-drop-down-arrow`, `.adw-tab-icon`, `.adw-row-edit`, …)
-// matching the same node it always matched.
+// THE ELEMENT *IS* THE ICON BOX — it carries `.adw-icon` itself rather than wrapping a
+// span, because a wrapper would insert a layout node into flex rows, button interiors
+// and absolutely-positioned arrows that are all measured against the icon box, and
+// would stop every class-scoped rule (`.adw-drop-down-arrow`, `.adw-tab-icon`, …)
+// matching the node it matches today.
 //
-// Reference: refs/libadwaita/src/stylesheet/_common.scss:34-41 — `.normal-icons`
-//   / `.large-icons` set `-gtk-icon-size`; libadwaita has NO `_icon.scss`, the
-//   icon is a GtkImage and its size is a GTK property, not a stylesheet rule.
+// Reference: refs/libadwaita/src/stylesheet/_common.scss — `.normal-icons` /
+//   `.large-icons` set `-gtk-icon-size`; libadwaita has NO `_icon.scss`, the icon is a
+//   GtkImage and its size is a GTK property, not a stylesheet rule.
 // Reference: refs/adwaita-web/adwaita-web/scss/_icon.scss — the vendored web
 //   port's `.adw-icon` (an inline-flex SVG holder; this package masks instead).
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
@@ -93,25 +77,20 @@ export class AdwIcon extends HTMLElement {
         this._render();
     }
 
-    // ── internals ──────────────────────────────────────────────────────────
-
     private _render(): void {
         this.classList.add('adw-icon');
 
-        // Swap ONLY the mask class: the callers put their own positioning class
-        // on the same node (`adw-drop-down-arrow`, `adw-sidebar-item-arrow`, …),
-        // and a `className =` assignment here would take those with it. The list
-        // is collected BEFORE removing — `classList` is live, so removing while
-        // iterating it would skip the entry after each hit.
+        // Swap ONLY the mask class: callers put their own positioning class on the same
+        // node, and a `className =` assignment would take those with it. The list is
+        // collected BEFORE removing — `classList` is live, so removing while iterating it
+        // would skip the entry after each hit.
         const stale = [...this.classList].filter((existing) => existing.startsWith(MASK_CLASS_PREFIX));
         this.classList.remove(...stale);
         const name = this.resolvedIconName;
         if (name !== '') this.classList.add(`${MASK_CLASS_PREFIX}${name}`);
 
-        // A masked box has no text, so assistive tech has nothing to announce —
-        // the accessible name belongs to the control that HOSTS the icon. Every
-        // hand-rolled copy that thought about it said the same thing; the ones
-        // that did not were the inconsistency, not the intent.
+        // A masked box has no text, so assistive tech has nothing to announce — the
+        // accessible name belongs to the control that HOSTS the icon.
         this.setAttribute('aria-hidden', 'true');
 
         const size = this.size;
@@ -124,8 +103,8 @@ export class AdwIcon extends HTMLElement {
             const px = `${size}px`;
             this.style.width = px;
             this.style.height = px;
-            // The box and the mask scale together — sizing only the box leaves a
-            // 16px glyph floating in the middle of it.
+            // The box and the mask scale together: sizing only the box leaves a 16px glyph
+            // floating in the middle of it.
             this.style.setProperty('mask-size', px);
             this.style.setProperty('-webkit-mask-size', px);
         }
@@ -133,10 +112,8 @@ export class AdwIcon extends HTMLElement {
 }
 
 /**
- * Build one icon node: the three lines every caller would otherwise write.
- *
- * `extraClasses` are the caller's own positioning/context classes, added
- * alongside the managed `.adw-icon` + mask class rather than replacing them.
+ * Build one icon node. `extraClasses` are the caller's own positioning/context
+ * classes, added alongside the managed `.adw-icon` + mask class, not replacing them.
  */
 export function createAdwIcon(iconName: string | null, ...extraClasses: string[]): AdwIcon {
     const icon = document.createElement('adw-icon') as AdwIcon;

package/src/elements/adw-inline-view-switcher.ts

@@ -4,28 +4,16 @@
 // and exactly one page is visible at a time.
 //
 // Everything that decides WHAT to show is HEADLESS and lives in
-// `@gjsify/adwaita-core` (ADR 0004) — including the TWO INDEX SPACES this widget
-// is built on: a hidden page produces NO toggle, so the compacted toggle index
-// and the page index diverge, and libadwaita reconciles them through the
-// `child-index` it stashes on every toggle (adw-inline-view-switcher.c:346,
-// :114-129, :434-453). `buildInlineToggles` carries both indices, so this file
-// never has to reconcile them itself.
+// `@gjsify/adwaita-core` (ADR 0004) — including the TWO INDEX SPACES this widget is
+// built on: a hidden page produces NO toggle, so the compacted toggle index and the
+// page index diverge, and libadwaita reconciles them through the `child-index` it
+// stashes on every toggle. `buildInlineToggles` carries both indices, so this file
+// never reconciles them itself.
 //
-// What the lift fixed here, all of it C-derived:
-//   - hidden pages were not filtered at all, so the two index spaces collapsed
-//     into one and `AdwViewStackPage:visible` had no spelling (:370-378).
-//   - the display-mode default was 'both'; libadwaita's is 'labels' (:657, :715).
-//   - an unrecognised display-mode value REPLACED the current mode with 'both';
-//     `g_return_if_fail (mode <= …_BOTH)` rejects it and keeps the current one
-//     (:819).
-//   - the icons-mode tooltip used the RAW title, so `title="_Files"` showed the
-//     underscore; C strips the mnemonic when use-underline is set (:180-188).
-//   - a page with no icon rendered no icon; C substitutes `image-missing`
-//     (:137-142) in every mode that builds an image at all.
-//   - `active` was CLAMPED into range instead of refused, `notify::display-mode`
-//     was documented but never dispatched, the page query was unscoped (so a
-//     nested switcher lost its pages to the outer one), and the 500 ms
-//     drag-hover auto-switch did not exist (:80, :194-236).
+// Two of the core's derivations are easy to get wrong by hand: the icons-mode tooltip
+// STRIPS the mnemonic when use-underline is set (`title="_Files"` must not show the
+// underscore), and a page with no icon gets `image-missing` substituted in every mode
+// that builds an image at all.
 //
 // Attributes:
 //   active — zero-based index of the visible PAGE (not of the toggle). Refused,
@@ -77,14 +65,10 @@ export class AdwViewStackPage extends HTMLElement {
 
 export class AdwInlineViewSwitcher extends HTMLElement {
     /**
-     * The dwell timer, injectable.
-     *
-     * It used to be `new ViewSwitcherState({ scheduler: domViewSwitcherScheduler })`
-     * inline, which left NOWHERE to hand a clock in — so
-     * `VIEW_SWITCHER_DRAG_VECTORS` was driven by the core suite alone, and the
-     * conformance header claimed all three suites drove it. `scheduler` is a
-     * property so a test can replace it before the element connects; the DOM one
-     * is the default, exactly as before.
+     * The dwell timer, injectable: a property rather than an inline
+     * `new ViewSwitcherState({ scheduler: domViewSwitcherScheduler })`, so a test can
+     * replace the clock before the element connects and drive
+     * `VIEW_SWITCHER_DRAG_VECTORS` here too. The DOM scheduler is the default.
      */
     scheduler: ViewSwitcherScheduler = domViewSwitcherScheduler;
     private _stateInstance: ViewSwitcherState | null = null;
@@ -127,14 +111,12 @@ export class AdwInlineViewSwitcher extends HTMLElement {
 
     /**
      * Index of the ACTIVE TOGGLE, `-1` when the visible page has none because it
-     * is hidden — the port-safe `GTK_INVALID_LIST_POSITION`
-     * (adw-inline-view-switcher.c:441-446).
+     * is hidden — the port-safe `GTK_INVALID_LIST_POSITION`.
      */
     get activeToggle(): number {
         return toggleIndexForPage(this._state.pages, this._state.selected);
     }
 
-    /** What the toggles display: 'labels', 'icons' or 'both'. */
     get displayMode(): AdwInlineViewSwitcherDisplayMode {
         return this._displayMode;
     }
@@ -152,7 +134,6 @@ export class AdwInlineViewSwitcher extends HTMLElement {
         this._state.selectName(name);
     }
 
-    /** The resolved page records. */
     get pages(): readonly AdwViewSwitcherPage[] {
         return this._state.pages;
     }
@@ -160,8 +141,7 @@ export class AdwInlineViewSwitcher extends HTMLElement {
     /**
      * Show or hide a page. Returns whether the SELECTION moved. Rebuilds the
      * toggle row, because a hidden page has no toggle at all — C reacts to a
-     * page's `notify::visible` with `recreate_toggles`
-     * (adw-inline-view-switcher.c:425, :471-477).
+     * page's `notify::visible` with `recreate_toggles`.
      */
     setPageVisible(name: string, visible: boolean): boolean {
         const moved = this._state.setPageVisible(name, visible);
@@ -222,11 +202,9 @@ export class AdwInlineViewSwitcher extends HTMLElement {
     }
 
     /**
-     * Re-read every declared page and push it into the state.
-     *
-     * Driven by {@link _watchPages}, which is what makes a runtime
-     * `badge-number` or `icon-name` change reach the toggle — C rebinds on every
-     * page `notify` (adw-view-switcher.c:184-193) and this element did not.
+     * Re-read every declared page and push it into the state. Driven by
+     * {@link _watchPages}, which is what makes a runtime `badge-number` or `icon-name`
+     * change reach the toggle, as C's per-page `notify` bindings do.
      */
     refreshPages(): void {
         if (!this._initialized) return;
@@ -236,13 +214,11 @@ export class AdwInlineViewSwitcher extends HTMLElement {
 
     /**
      * Watch the declared pages for attribute changes — the DOM's `notify::` on
-     * `AdwViewStackPage`, which C binds per page (adw-view-switcher.c:184-193).
-     *
-     * A `MutationObserver` rather than an `attributeChangedCallback`: this
-     * element consumes the page elements at connect and `replaceChildren`s them
-     * out of the tree, so a detached page cannot find its owner. It delivers on
-     * a MICROTASK where GTK's notify is synchronous — invisible to a user, and
-     * nothing here reads the toggle back inside the setter.
+     * `AdwViewStackPage`. A `MutationObserver` rather than an
+     * `attributeChangedCallback`, because this element consumes the page elements at
+     * connect and `replaceChildren`s them out of the tree, so a detached page cannot
+     * find its owner. It delivers on a MICROTASK where GTK's notify is synchronous —
+     * invisible to a user, and nothing here reads the toggle back inside the setter.
      */
     private _watchPages(): void {
         this._pageObserver?.disconnect();
@@ -264,14 +240,13 @@ export class AdwInlineViewSwitcher extends HTMLElement {
             if (next === this._displayMode) return;
             this._displayMode = next;
             // C rebuilds every toggle's child on a mode change rather than
-            // toggling visibility on the existing ones (:852-854).
+            // toggling visibility on the existing ones.
             this._rebuildToggles();
             this.dispatchEvent(
                 new CustomEvent('notify::display-mode', { bubbles: true, detail: { displayMode: next } }),
             );
             return;
         }
-        // flat / round are styling-only.
         this._applyStyleClasses();
     }
 
@@ -282,11 +257,10 @@ export class AdwInlineViewSwitcher extends HTMLElement {
     }
 
     /**
-     * Rebuild the toggle row from the derived models. One node per VISIBLE page,
-     * in compacted order — the structural half of `recreate_toggles`. Selection
-     * alone never lands here: `selection_changed_cb` only sets the active toggle
-     * (adw-inline-view-switcher.c:434-453), and rebuilding mid-drag would drop
-     * the dwell the drag has already armed.
+     * Rebuild the toggle row from the derived models: one node per VISIBLE page, in
+     * compacted order — the structural half of `recreate_toggles`. Selection alone never
+     * lands here (`selection_changed_cb` only sets the active toggle), because
+     * rebuilding mid-drag would drop the dwell the drag has already armed.
      */
     private _rebuildToggles(): void {
         if (!this._initialized) return;
@@ -327,13 +301,12 @@ export class AdwInlineViewSwitcher extends HTMLElement {
             toggle.addEventListener('click', () => {
                 this._state.setSelected(model.pageIndex);
             });
-            // The `relatedTarget` test is load-bearing: a toggle holds an icon,
-            // a label and an indicator, and the DOM fires `dragleave` +
-            // `dragenter` when the pointer crosses BETWEEN them — which cleared
-            // the dwell timer and re-armed a fresh 500ms, so a drag that merely
-            // slid across the toggle never switched the page. C has one
-            // `GtkDropControllerMotion` per BUTTON widget
-            // (adw-view-switcher-button.c:79-96), which has no internal edges.
+            // The `relatedTarget` test is load-bearing: a toggle holds an icon, a label
+            // and an indicator, and the DOM fires `dragleave` + `dragenter` when the
+            // pointer crosses BETWEEN them, which clears the dwell timer and re-arms a
+            // fresh 500 ms — so a drag that merely slid across the toggle would never
+            // switch the page. C has one `GtkDropControllerMotion` per BUTTON widget,
+            // which has no internal edges.
             toggle.addEventListener('dragenter', (event) => {
                 if (toggle.contains((event as DragEvent).relatedTarget as Node | null)) return;
                 this._state.dragEnter(model.pageIndex);
@@ -389,18 +362,16 @@ export class AdwInlineViewSwitcher extends HTMLElement {
     }
 
     private _applyStyleClasses(): void {
-        // `css_classes_changed_cb` (adw-inline-view-switcher.c:528-545) forwards
-        // THREE classes onto the toggle group, not two: `flat`, `round` and
-        // `osd`. This element carried the first two and only onto the host, so an
-        // `osd` inline switcher — the one in a floating overlay, where the class
-        // exists to make it legible — styled nothing at all.
+        // `css_classes_changed_cb` forwards THREE classes onto the toggle group, not
+        // two: `flat`, `round` AND `osd` — the last is what makes an inline switcher in a
+        // floating overlay legible, so dropping it styles nothing.
         for (const name of ['flat', 'round', 'osd'] as const) {
             const present = this.hasAttribute(name);
             this.classList.toggle(name, present);
             this._groupEl?.classList.toggle(name, present);
         }
         // The group carries the display-mode class, mirroring libadwaita's
-        // inline-view-switcher > toggle-group.{labels,icons,both} (:826-850).
+        // `inline-view-switcher > toggle-group.{labels,icons,both}`.
         for (const mode of INLINE_VIEW_SWITCHER_DISPLAY_MODES) {
             this._groupEl.classList.toggle(mode, mode === this._displayMode);
         }

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

@@ -1,43 +1,19 @@
-// <adw-menu-button> — An icon button that opens a popover menu, the web
-// counterpart of Adw.MenuButton / a Gtk.MenuButton. By default it is the flat
-// `open-menu-symbolic` primary/app-menu button used at the end of a header bar
-// (About / Preferences / Keyboard Shortcuts / Quit …). Clicking it toggles a
-// real Adwaita-styled popover positioned under the button; the popover is
-// dismissed on an outside click or Escape and supports arrow-key navigation.
+// <adw-menu-button> — the web counterpart of Adw.MenuButton / Gtk.MenuButton: by
+// default the flat `open-menu-symbolic` app-menu button used at the end of a header
+// bar. Clicking it toggles an Adwaita-styled popover under the button, dismissed on
+// an outside click or Escape, with arrow-key navigation.
 //
 // The popover is `<adw-popover>` and the dismissal/keyboard machine is
-// `@gjsify/adwaita-core`'s (ADR 0004). This element used to build both by hand,
-// as did `<adw-drop-down>` and `<adw-split-button>` — three surfaces that
-// disagreed with libadwaita and with each other on radius, shadow and padding,
-// and two copies of the same `(current ± 1 + n) % n` arithmetic. This element
-// keeps only what is a menu button: the icon, the item model, the title.
+// `@gjsify/adwaita-core`'s (ADR 0004); this element keeps only what is a menu button:
+// the icon, the item model, the title. Icons go through `<adw-icon>`, whose
+// `normalizeIconName` guard is what keeps a multi-token `icon-name="a b"` from
+// shipping a stray CSS class — for the button icon and for every menu entry's.
 //
-// THE ICON WENT THE SAME WAY, and it is where the drift actually bit: this
-// element interpolated `class="adw-icon adw-menu-button-icon adw-icon--<name>"`
-// while `<adw-split-button>` — alone among six copies — first checked the name
-// was one CSS token. So `icon-name="a b"` shipped a stray `b` class here, and so
-// did every JSON menu entry's `icon`. Both are `<adw-icon>` now, and the guard
-// is `normalizeIconName`'s.
+// The `menu` attribute is a JSON array of `{ "id"?, "label", "icon"? }`. Choosing an
+// item closes the popover and fires `menu-item-activated` (CustomEvent, bubbles,
+// detail `{ id, label, index }`) with `id` falling back to `label`, matching the NS
+// twin.
 //
-// Attributes:
-//   icon-name  — symbolic icon (no `-symbolic` suffix), default `open-menu`.
-//   menu-title — optional heading shown atop the popover.
-//   menu       — JSON array of items, each `{ "id"?, "label", "icon"? }`.
-//   disabled   — boolean; a disabled button does not open the menu.
-//   flat       — boolean style class (default: flat, like the header app menu).
-//   circular   — boolean style class (round 34×34 button).
-//   direction  — none | up | down | left | right (default down); where the
-//                popover opens. `none` behaves as `down`, which is
-//                Gtk.MenuButton's own rule, not ours — see
-//                {@link menuButtonPopupDirection}.
-// Properties (mirroring Adw.MenuButton / the NS twin):
-//   menuItems  — the menu entries ({ id?, label, icon? }[]) (get/set).
-//   menuTitle  — the popover heading (get/set).
-//   active     — whether the popover is open (get).
-// Events:
-//   `menu-item-activated` (CustomEvent, bubbles, detail = { id, label, index })
-//     when an item is chosen — `id` falls back to `label` when omitted (matches
-//     the NS twin). The popover closes on activation.
 // Reference: refs/libadwaita/src/adw-menu-button.c (AdwMenuButton)
 // Reference: refs/libadwaita/src/stylesheet/widgets/_menus.scss (popover.menu / modelbutton)
 // Reference: packages/nativescript-bridge/adwaita/src/widgets/adw-menu-button.ts (NS twin)
@@ -47,13 +23,12 @@
 import { isSplitButtonDirection, menuButtonPopupDirection } from '@gjsify/adwaita-core';
 import type { SplitButtonDirection } from '@gjsify/adwaita-core';
 
-// SIDE-EFFECT import, deliberately separate from the type import below: it is
-// what guarantees `adw-popover` is defined before this module's own
-// `customElements.define` can upgrade a server-rendered `<adw-menu-button>` and
-// build one. A combined `import { AdwPopover }` 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-popover` is defined before this module's `customElements.define` can upgrade a
+// server-rendered `<adw-menu-button>` and build one. A combined
+// `import { AdwPopover }` 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-popover.js';
 import type { AdwPopover } from './adw-popover.js';
 
@@ -67,14 +42,12 @@ export interface AdwMenuItem {
 }
 
 /**
- * Where the popover sits, per `GtkArrowType`. `menuButtonPopupDirection` folds
- * `none` onto `down` (adw-split-button.c:415 — a pass-through to
- * `gtk_menu_button_set_direction`, so it is GtkMenuButton's rule); this table is
- * only the direction→CSS-axis mapping, which is a renderer fact.
+ * Where the popover sits, per `GtkArrowType`. `menuButtonPopupDirection` folds `none`
+ * onto `down` — GtkMenuButton's rule, not ours; this table is only the
+ * direction→CSS-axis mapping, which is a renderer fact.
  *
- * `left`/`right` become `start`/`end` because the surface is placed with
- * logical properties, so it follows the writing direction the way GTK's
- * `:dir(rtl)` popovers do.
+ * `left`/`right` become `start`/`end` because the surface is placed with logical
+ * properties, so it follows the writing direction as GTK's `:dir(rtl)` popovers do.
  */
 const POPOVER_POSITIONS = {
     down: 'bottom',
@@ -163,9 +136,8 @@ export class AdwMenuButton extends HTMLElement {
 
         // Seed items from the `menu` attribute if the property was not set.
         if (this._items.length === 0) this._items = this._parseMenuAttr();
-        // Default to the flat header idiom unless another variant is requested.
-        // Set only now the DOM exists, so the observed-attribute callback (which
-        // renders) never runs before `_buttonEl` is created.
+        // The flat default is set only now the DOM exists, so the observed-attribute
+        // callback (which renders) never runs before `_buttonEl` is created.
         if (!this.hasAttribute('flat') && !this.hasAttribute('circular')) this.setAttribute('flat', '');
         this._render();
     }
@@ -197,7 +169,6 @@ export class AdwMenuButton extends HTMLElement {
     private _onPopoverToggled(open: boolean): void {
         this.classList.toggle('active', open);
         this._buttonEl.setAttribute('aria-expanded', String(open));
-        // Move focus into the menu for keyboard navigation.
         if (open) this._itemButtons[0]?.focus();
     }
 
@@ -238,9 +209,9 @@ export class AdwMenuButton extends HTMLElement {
             item.setAttribute('role', 'menuitem');
             item.tabIndex = -1;
 
-            // An entry with no USABLE icon gets no icon node at all, rather than
-            // an empty 16px box — the element itself answers whether the name
-            // resolved, so the `-symbolic`-only and bad-token cases agree.
+            // An entry with no USABLE icon gets no icon node at all rather than an empty
+            // 16px box; `<adw-icon>` itself answers whether the name resolved, so the
+            // `-symbolic`-only and bad-token cases agree.
             const entryIcon = createAdwIcon(entry.icon ?? null, 'adw-menu-button-item-icon');
             if (entryIcon.resolvedIconName !== '') item.appendChild(entryIcon);
             const labelEl = document.createElement('span');
@@ -262,7 +233,6 @@ export class AdwMenuButton extends HTMLElement {
             this._itemButtons.push(item);
         }
 
-        // A menu-button with no entries can never open.
         if (this._items.length === 0) this._popoverEl.popdown();
     }
 }