@gjsify/adwaita-web 0.36.0 → 0.38.0

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

@@ -9,18 +9,15 @@
 //   `notify::can-shrink` (CustomEvent, bubbles) mirroring the AdwButtonContent
 //   GObject notify signals the native story observes.
 //
-// The derivations come from `@gjsify/adwaita-core` (ADR 0004). THE STYLE CLASS IS
-// WHY THIS WAS TOUCHED: `AdwButtonContent` puts `image-text-button` on the button
-// hosting it (adw-button-content.c:115) and removes it on unroot (:126), and 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 this package used to return NOTHING, so every icon+label button here was
-// drawn with a plain button's padding.
+// The derivations come from `@gjsify/adwaita-core` (ADR 0004). THE STYLE CLASS IS THE
+// POINT: `AdwButtonContent` puts `image-text-button` on the button hosting it and removes
+// it on unroot, and the stylesheet gives that class `padding-left/right: 9px` where a
+// plain text button has 17px. Without the class, an icon+label button is drawn with a
+// plain button's padding.
 //
 // Reference: refs/libadwaita/src/adw-button-content.c (AdwButtonContent)
 // Reference: refs/libadwaita/src/stylesheet/widgets/_buttons.scss
-//            (image-text-button :77-91 · splitbutton override :499-507 ·
-//             buttoncontent :626-645)
+//            (image-text-button · the splitbutton override · buttoncontent)
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web; the
 // icon node is <adw-icon>.
@@ -30,14 +27,13 @@ import { BUTTON_CONTENT_STYLE_CLASS, buttonContentIconName, buttonContentLabelTe
 import { type AdwIcon, createAdwIcon } from './adw-icon.js';
 
 /**
- * What `gtk_widget_get_ancestor (…, GTK_TYPE_BUTTON)` (:95) looks like in the
- * DOM: a native `<button>`, or anything wearing the Adwaita button class (the
- * `<adw-button>` element renders an inner `<button class="adw-button">`, and the
- * stories style a plain one with the same class set).
+ * What `gtk_widget_get_ancestor (…, GTK_TYPE_BUTTON)` looks like in the DOM: a native
+ * `<button>`, or anything wearing the Adwaita button class — `<adw-button>` renders an
+ * inner button with it, and the stories put it on plain ones.
  */
 const BUTTON_SELECTOR = 'button, .adw-button';
 
-/** The split-button node the class is RETARGETED to (:112-113). */
+/** The split-button node the class is RETARGETED to. */
 const SPLIT_BUTTON_SELECTOR = 'adw-split-button, .adw-split-button';
 
 export class AdwButtonContent extends HTMLElement {
@@ -60,9 +56,9 @@ export class AdwButtonContent extends HTMLElement {
             this._boxEl = document.createElement('div');
             this._boxEl.className = 'adw-button-content-box';
 
-            // The image node is GTK_ACCESSIBLE_ROLE_PRESENTATION in libadwaita —
-            // it is decorative, the label carries the accessible name, which is
-            // what <adw-icon>'s own `aria-hidden` says.
+            // The image node is GTK_ACCESSIBLE_ROLE_PRESENTATION in libadwaita: decorative,
+            // with the label carrying the accessible name — what `<adw-icon>`'s own
+            // `aria-hidden` already says.
             this._iconEl = createAdwIcon(null);
 
             this._labelEl = document.createElement('span');
@@ -72,8 +68,8 @@ export class AdwButtonContent extends HTMLElement {
             this.replaceChildren(this._boxEl);
             this._render();
         }
-        // `adw_button_content_root` runs on every rooting, not just the first
-        // (:99-116), so a re-parented content re-stamps its new host.
+        // `adw_button_content_root` runs on every rooting, not just the first, so a
+        // re-parented content re-stamps its new host.
         this._root();
     }
 
@@ -84,16 +80,14 @@ export class AdwButtonContent extends HTMLElement {
     attributeChangedCallback(name: string) {
         if (!this._initialized) return;
         this._render();
-        // Mirror the AdwButtonContent notify::<prop> signals the native story
-        // listens to.
+        // Mirrors the AdwButtonContent notify::<prop> signals the native story listens to.
         this.dispatchEvent(new CustomEvent(`notify::${name}`, { bubbles: true }));
     }
 
     /**
-     * `adw_button_content_root` (:108-116): the nearest button ancestor, unless
-     * that button's DIRECT parent is a split button — then the split button
-     * takes the class, because `splitbutton.image-text-button > button` is the
-     * rule that styles it (_buttons.scss:499-507).
+     * `adw_button_content_root`: the nearest button ancestor, unless that button's DIRECT
+     * parent is a split button — then the split button takes the class, because
+     * `splitbutton.image-text-button > button` is the rule that styles it.
      */
     private _hostButton(): HTMLElement | null {
         const button = this.parentElement?.closest<HTMLElement>(BUTTON_SELECTOR) ?? null;
@@ -106,36 +100,35 @@ export class AdwButtonContent extends HTMLElement {
         const host = this._hostButton();
         if (host === this._styledHost) return;
         this._unroot();
-        // A content with no button ancestor styles nothing. The C would pass
-        // NULL to `gtk_widget_get_parent`/`add_css_class` here (:112-115) — two
-        // CRITICALs — so there is nothing to reproduce.
+        // A content with no button ancestor styles nothing: the C would pass NULL to
+        // `gtk_widget_get_parent`/`add_css_class`, i.e. two CRITICALs, so there is nothing
+        // to reproduce.
         if (!host) return;
         host.classList.add(BUTTON_CONTENT_STYLE_CLASS);
         this._styledHost = host;
     }
 
     private _unroot(): void {
-        // `adw_button_content_unroot` (:126) — a button that loses its content
-        // goes back to plain-button padding.
+        // `adw_button_content_unroot`: a button that loses its content goes back to
+        // plain-button padding.
         this._styledHost?.classList.remove(BUTTON_CONTENT_STYLE_CLASS);
         this._styledHost = null;
     }
 
     private _render() {
-        // An empty `icon-name` resolves to `image-missing` and the image node
-        // stays visible (:355-356). The docs at :228/:343 say the icon is not
-        // shown; the code never hides it, and this follows the code — see the
-        // `BUTTON_CONTENT_ICON_VECTORS` rule string.
+        // An empty `icon-name` resolves to `image-missing` and the image node stays
+        // VISIBLE. libadwaita's own docs say the icon is not shown, but its code never
+        // hides it; this follows the code — see `BUTTON_CONTENT_ICON_VECTORS`.
         this._iconEl.iconName = buttonContentIconName(this.getAttribute('icon-name') ?? '');
         this._iconEl.hidden = false;
 
         const label = this.getAttribute('label') ?? '';
         this._labelEl.textContent = buttonContentLabelText(label, this.hasAttribute('use-underline'));
-        // `gtk_widget_set_visible (self->label, label[0])` (:398) — the RAW
-        // label decides, not the mnemonic-resolved text.
+        // `gtk_widget_set_visible (self->label, label[0])`: the RAW label decides, not the
+        // mnemonic-resolved text.
         this._labelEl.hidden = label.length === 0;
 
-        // can-shrink → ellipsize the label (Gtk.Label PANGO_ELLIPSIZE_END, :490).
+        // can-shrink → ellipsize the label (Gtk.Label PANGO_ELLIPSIZE_END).
         this.classList.toggle('can-shrink', this.hasAttribute('can-shrink'));
     }
 }

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

@@ -1,27 +1,17 @@
-// <adw-button-row> — A boxed-list row that behaves like a button: a centered
-// title between an optional start icon and an optional end icon, spanning the
-// full width of the list. The `suggested-action` / `destructive-action` style
-// classes recolor it like the matching Adwaita button variants.
-// Attributes: title, start-icon-name, end-icon-name (symbolic names, e.g.
-//   "list-add" / "go-next").
-// Events: `activated` (CustomEvent, bubbles) when the row is clicked — mirrors
-//   the Adw.ButtonRow `activated` GObject signal.
+// <adw-button-row> — a boxed-list row that behaves like a button: a centred title between
+// an optional start and end icon, spanning the full width of the list. The
+// `suggested-action` / `destructive-action` style classes recolour it like the matching
+// Adwaita button variants, and `activated` (CustomEvent, bubbles) mirrors the
+// Adw.ButtonRow GObject signal.
 //
-// The label/icon visibility rules are HEADLESS and live in
-// `@gjsify/adwaita-core` (ADR 0004) as {@link ButtonRowState}; this element
-// composes it and keeps only the DOM render half.
-// `@gjsify/adwaita-nativescript` composes the same state, so both ports share one
-// behaviour. Two things this fixes, both from adw-button-row.c:
-//   - `end-icon-name` (C:213-223, bound at adw-button-row.ui:52-65) exists since
-//     libadwaita 1.6 and neither renderer had it, so the trailing-chevron shape
-//     the property exists for could not be expressed.
-//   - THERE IS NO `activatable` OPT-OUT. `<property name="activatable">True
-//     </property>` is in the template (adw-button-row.ui:5), the class docs say
-//     "AdwButtonRow is always activatable." (C:31), and the whole public surface
-//     (C:270-352) is `new` plus the two icon-name pairs. This element used to
-//     honour an invented `activatable="false"`, which also gave the same markup
-//     two opposite meanings inside one package — `<adw-action-row>` reads
-//     `activatable` by PRESENCE, so `activatable="false"` there meant TRUE.
+// The label/icon visibility rules are HEADLESS and live in `@gjsify/adwaita-core`
+// (ADR 0004) as {@link ButtonRowState}; this element keeps only the DOM render half.
+//
+// THERE IS NO `activatable` OPT-OUT, and inventing one would be wrong twice over: the
+// upstream template hardcodes `activatable=True` and the class docs say "AdwButtonRow is
+// always activatable", while `<adw-action-row>` in this same package reads `activatable`
+// by PRESENCE — so `activatable="false"` means TRUE there, and one spelling would carry
+// two opposite meanings.
 //
 // Reference: refs/libadwaita/src/adw-button-row.c, adw-button-row.ui
 // Reference: refs/libadwaita/src/stylesheet/widgets/_lists.scss (row.button)
@@ -91,7 +81,7 @@ export class AdwButtonRow extends HTMLElement {
     }
 
     /**
-     * Paint one of the two `image.icon.{start,end}` nodes (adw-button-row.c:39-40).
+     * Paint one of the two `image.icon.{start,end}` nodes.
      *
      * The `start` / `end` position class is set once at construction — it is
      * where the node sits, not what it draws — so only the name changes here.