@gjsify/adwaita-web 0.30.0 → 0.32.0

package/src/elements/adw-bottom-sheet.ts

@@ -5,6 +5,20 @@
 // layer covers the content and dismisses the sheet on click (unless `can-close`
 // is false, in which case a close attempt is signalled instead).
 //
+// The open/closed state and the dismissal gate are NOT implemented here: they
+// live in `@gjsify/adwaita-core` as `BottomSheetPresentation` +
+// `resolveBottomSheetClose`, ported from the C source and shared with
+// `@gjsify/adwaita-nativescript` (ADR 0004). This element owns only the DOM.
+// Three things changed when it moved:
+//   - `open="false"` now means CLOSED. The old getter was `hasAttribute('open')`
+//     while every other boolean used `!== 'false'`, so one element carried two
+//     incompatible conventions and `<adw-bottom-sheet open="false">` rendered
+//     open (adw-bottom-sheet.c:1670 — `open = !!open` on a strict gboolean).
+//   - `notify::open` follows the STATE, not the attribute VALUE. Rewriting the
+//     attribute to another truthy spelling no longer fires a notification
+//     carrying an unchanged payload (adw-bottom-sheet.c:1672-1682).
+//   - the drag handle is decorative, not a close button — see below.
+//
 // Children are declared as <adw-bottom-sheet-content> (the persistent content)
 // and <adw-bottom-sheet-sheet> (the slide-up sheet); both are consumed at
 // connect time. Unslotted children fall back to the content, mirroring the
@@ -13,22 +27,30 @@
 // Attributes:
 //   open             (boolean — whether the sheet is revealed; default closed)
 //   modal            (boolean — dim + block the content while open; default on)
-//   can-close        (boolean — user can dismiss via the handle / dimming / Esc;
-//                       default on. When off, a dismissal raises `close-attempt`
-//                       instead of closing — mirrors Adw.BottomSheet:can-close)
+//   can-close        (boolean — user can dismiss via the dimming / Esc / the
+//                       sheet.close action; default on. When off, a dismissal
+//                       raises `close-attempt` instead of closing — mirrors
+//                       Adw.BottomSheet:can-close)
 //   show-drag-handle (boolean — overlay the drag handle on the sheet; default on)
 //
 // Events:
 //   `notify::open` (CustomEvent, bubbles, `detail = { open }`) when the revealed
 //     state changes — mirrors the Adw.BottomSheet `open` GObject property.
-//   `close-attempt` (CustomEvent, bubbles) when a dismissal is attempted while
-//     `can-close` is false — mirrors the Adw.BottomSheet `close-attempt` signal.
+//   `close-attempt` (CustomEvent, bubbles) when a dismissal is attempted that the
+//     sheet refuses — mirrors the Adw.BottomSheet `close-attempt` signal.
+//   `sheet.close` (CustomEvent, bubbles) when the sheet.close action is used on
+//     an ALREADY-closed sheet, so an enclosing sheet/dialog can handle it — the
+//     DOM equivalent of `gtk_widget_activate_action (parent, "sheet.close")`
+//     (adw-bottom-sheet.c:382-385).
 //
 // Reference: refs/libadwaita/src/adw-bottom-sheet.c (AdwBottomSheet behaviour)
 // Reference: refs/libadwaita/src/stylesheet/widgets/_bottom-sheet.scss
 // Copyright (c) 2023-2024 GNOME Foundation Inc. (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
+import { BottomSheetPresentation } from '@gjsify/adwaita-core';
+import type { BottomSheetCloseOutcome, BottomSheetCloseSource } from '@gjsify/adwaita-core';
+
 /** The persistent content. Child of <adw-bottom-sheet>; consumed at connect time. */
 export class AdwBottomSheetContent extends HTMLElement {}
 
@@ -41,6 +63,10 @@ export class AdwBottomSheet extends HTMLElement {
     private _dimmingEl!: HTMLDivElement;
     private _sheetEl!: HTMLDivElement;
     private _dragHandleEl!: HTMLDivElement;
+    /** The shared open/can-close model — the single source of truth for both. */
+    private readonly _state = new BottomSheetPresentation();
+    /** Set while the element writes `open` back, so the write does not re-enter. */
+    private _reflecting = false;
 
     static get observedAttributes() {
         return ['open', 'modal', 'can-close', 'show-drag-handle'];
@@ -48,26 +74,25 @@ export class AdwBottomSheet extends HTMLElement {
 
     /** Whether the sheet is revealed. */
     get open(): boolean {
-        return this.hasAttribute('open');
+        return this._state.open;
     }
 
     set open(value: boolean) {
-        if (value) this.setAttribute('open', '');
-        else this.removeAttribute('open');
+        this._setOpen(!!value);
     }
 
     /** Whether the content is dimmed + blocked while the sheet is open. */
     get modal(): boolean {
-        return this._boolAttr('modal');
+        return this._boolAttr('modal', true);
     }
 
     set modal(value: boolean) {
         this._setBoolAttr('modal', value);
     }
 
-    /** Whether the user can dismiss the sheet (handle / dimming / Escape). */
+    /** Whether the user can dismiss the sheet (dimming / Escape / sheet.close). */
     get canClose(): boolean {
-        return this._boolAttr('can-close');
+        return this._state.canClose;
     }
 
     set canClose(value: boolean) {
@@ -76,13 +101,33 @@ export class AdwBottomSheet extends HTMLElement {
 
     /** Whether the overlaid drag handle is shown. */
     get showDragHandle(): boolean {
-        return this._boolAttr('show-drag-handle');
+        return this._boolAttr('show-drag-handle', true);
     }
 
     set showDragHandle(value: boolean) {
         this._setBoolAttr('show-drag-handle', value);
     }
 
+    /**
+     * Route a dismissal affordance through the shared gate and act on the
+     * verdict: close, raise `close-attempt`, forward `sheet.close` to an
+     * ancestor, or do nothing. The element calls this for the dimming layer and
+     * Escape; a close button inside the sheet calls it with `'close-button'`.
+     *
+     * The verdict differs per source — a locked sheet signals a scrim click but
+     * swallows a swipe, and the drag handle never closes anything. See
+     * `resolveBottomSheetClose` in `@gjsify/adwaita-core`.
+     */
+    requestClose(source: BottomSheetCloseSource): BottomSheetCloseOutcome {
+        const outcome = this._state.requestClose(source);
+        if (outcome === 'close-attempt') {
+            this.dispatchEvent(new CustomEvent('close-attempt', { bubbles: true }));
+        } else if (outcome === 'delegate') {
+            this.dispatchEvent(new CustomEvent('sheet.close', { bubbles: true }));
+        }
+        return outcome;
+    }
+
     connectedCallback() {
         if (this._initialized) return;
         this._initialized = true;
@@ -90,9 +135,9 @@ export class AdwBottomSheet extends HTMLElement {
         // Snapshot declared children before taking over the subtree. The sheet
         // and content are placed by slot; anything unslotted falls back to the
         // content (the AdwBottomSheet GtkBuildable default).
-        const sheetChildren = this._collectSlot('adw-bottom-sheet-sheet', 'sheet');
-        const contentChildren = this._collectSlot('adw-bottom-sheet-content', 'content');
-        const claimed = new Set<Node>([...sheetChildren, ...contentChildren]);
+        const claimed = new Set<Node>();
+        const sheetChildren = this._collectSlot('adw-bottom-sheet-sheet', 'sheet', claimed);
+        const contentChildren = this._collectSlot('adw-bottom-sheet-content', 'content', claimed);
         const unslotted = Array.from(this.childNodes).filter((n) => !claimed.has(n));
 
         // Persistent content layer.
@@ -105,25 +150,22 @@ export class AdwBottomSheet extends HTMLElement {
         // Clicking it dismisses the sheet (or raises close-attempt when locked).
         this._dimmingEl = document.createElement('div');
         this._dimmingEl.className = 'adw-bottom-sheet-dimming';
-        this._dimmingEl.addEventListener('click', () => this._attemptClose());
+        this._dimmingEl.addEventListener('click', () => this.requestClose('dimming'));
 
         // The slide-up sheet with its overlaid drag handle.
         this._sheetEl = document.createElement('div');
         this._sheetEl.className = 'adw-bottom-sheet-sheet';
 
+        // libadwaita builds the handle with can_focus = FALSE and
+        // can_target = FALSE (adw-bottom-sheet.c:1197-1198): it is a decorative
+        // pill that cannot be clicked or focused at all. Its only behavioural
+        // role is elsewhere — `allow_mouse_drag = show_drag_handle || bottom_bar`
+        // (adw-bottom-sheet.c:455-457). This element used to give it
+        // role="button", tabindex=0 and a click-to-close handler, which is the
+        // one behaviour it provably does not have.
         this._dragHandleEl = document.createElement('div');
         this._dragHandleEl.className = 'adw-bottom-sheet-drag-handle';
-        this._dragHandleEl.setAttribute('role', 'button');
-        this._dragHandleEl.setAttribute('aria-label', 'Drag handle');
-        this._dragHandleEl.tabIndex = 0;
-        // The handle is the primary pointer affordance for closing the sheet.
-        this._dragHandleEl.addEventListener('click', () => this._attemptClose());
-        this._dragHandleEl.addEventListener('keydown', (event) => {
-            if (event.key === 'Enter' || event.key === ' ') {
-                event.preventDefault();
-                this._attemptClose();
-            }
-        });
+        this._dragHandleEl.setAttribute('aria-hidden', 'true');
 
         const sheetBody = document.createElement('div');
         sheetBody.className = 'adw-bottom-sheet-sheet-body';
@@ -133,56 +175,83 @@ export class AdwBottomSheet extends HTMLElement {
 
         this.replaceChildren(this._contentEl, this._dimmingEl, this._sheetEl);
 
-        // Escape closes the sheet when open (mirrors AdwBottomSheet's Escape
-        // shortcut → maybe_close_cb).
+        // Escape → maybe_close_cb (adw-bottom-sheet.c:389-400). In GTK the
+        // shortcut sits on the sheet itself, so it fires exactly while the sheet
+        // has focus — INCLUDING while the sheet is closed, which is the corner
+        // that still emits `close-attempt`. This port has no focus transfer into
+        // the sheet, so an open sheet counts as the focused surface and a closed
+        // one only when focus is still inside its (off-screen) body.
         this.addEventListener('keydown', (event) => {
-            if (event.key === 'Escape' && this.open) {
-                event.stopPropagation();
-                this._attemptClose();
-            }
+            if (event.key !== 'Escape') return;
+            if (!this.open && !this._sheetEl.contains(event.target as Node)) return;
+            event.stopPropagation();
+            this.requestClose('escape');
+        });
+
+        // Adopt whatever the author declared, then start mirroring state changes
+        // back out. Seeding before the subscription keeps the initial value
+        // silent, as an attribute set during upgrade has always been.
+        this._state.setCanClose(this._boolAttr('can-close', true));
+        this._state.setOpen(this._boolAttr('open', false));
+        this._state.subscribe((open) => {
+            this._render();
+            this.dispatchEvent(new CustomEvent('notify::open', { bubbles: true, detail: { open } }));
         });
 
         this._render();
     }
 
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null) {
-        if (!this._initialized) return;
+        // Our own write-back of `open`; the state already holds this value.
+        if (this._reflecting) return;
         if (oldValue === newValue) return;
-        this._render();
+
+        // The state is authoritative even before the DOM exists, so an attribute
+        // set during upgrade is not lost. Only the rendering half waits.
         if (name === 'open') {
-            this.dispatchEvent(new CustomEvent('notify::open', { bubbles: true, detail: { open: this.open } }));
+            // A no-op change (one truthy spelling for another) leaves the state
+            // alone, so nothing renders and nothing notifies.
+            this._state.setOpen(this._boolAttr('open', false));
+            return;
         }
+        if (name === 'can-close') this._state.setCanClose(this._boolAttr('can-close', true));
+        if (this._initialized) this._render();
     }
 
-    private _attemptClose(): void {
-        if (!this.open) return;
-        if (!this.canClose) {
-            this.dispatchEvent(new CustomEvent('close-attempt', { bubbles: true }));
-            return;
-        }
-        // Keep the attribute in sync without re-entering the guarded callback
-        // (it no-ops on an unchanged value, but the notify::open fires from the
-        // attribute write below).
-        this.open = false;
+    /** The programmatic open/close — `AdwBottomSheet:open`, ungated by `can-close`. */
+    private _setOpen(open: boolean): void {
+        if (!this._state.setOpen(open)) return;
+        // Once connected the subscription renders (which reflects the attribute)
+        // and notifies; before that there is no DOM, so only the attribute has
+        // to be kept in step.
+        if (!this._initialized) this._reflectOpen(open);
     }
 
     private _render(): void {
-        this.classList.toggle('open', this.open);
+        const open = this._state.open;
+        this._reflectOpen(open);
+        this.classList.toggle('open', open);
         this.classList.toggle('modal', this.modal);
         this.classList.toggle('has-drag-handle', this.showDragHandle);
 
         // The dimming layer is only meaningful while modal; it fades in with the
         // sheet and is non-interactive when closed.
-        this._dimmingEl.classList.toggle('visible', this.open && this.modal);
+        this._dimmingEl.classList.toggle('visible', open && this.modal);
         this._dragHandleEl.hidden = !this.showDragHandle;
     }
 
-    /** Read a boolean attribute that defaults to `true` when absent. */
-    private _boolAttr(name: string): boolean {
+    /** Mirror the state onto the `open` attribute (the CSS + markup hook). */
+    private _reflectOpen(open: boolean): void {
+        this._reflecting = true;
+        if (open) this.setAttribute('open', '');
+        else this.removeAttribute('open');
+        this._reflecting = false;
+    }
+
+    /** Read a boolean attribute: absent → `fallback`, explicit `="false"` → off. */
+    private _boolAttr(name: string, fallback: boolean): boolean {
         const value = this.getAttribute(name);
-        // Absent attribute → default on; explicit `="false"` → off.
-        if (value === null) return name === 'modal' || name === 'can-close' || name === 'show-drag-handle';
-        return value !== 'false';
+        return value === null ? fallback : value !== 'false';
     }
 
     private _setBoolAttr(name: string, value: boolean): void {
@@ -190,13 +259,29 @@ export class AdwBottomSheet extends HTMLElement {
         else this.setAttribute(name, 'false');
     }
 
-    /** Move declared slot children out of the light-DOM tree into a list. */
-    private _collectSlot(tag: string, slot: string): Node[] {
-        const byElement = Array.from(this.querySelectorAll(`:scope > ${tag}`)).flatMap((el) =>
-            Array.from(el.childNodes),
-        );
-        const bySlotAttr = Array.from(this.querySelectorAll(`:scope > [slot="${slot}"]`));
-        return [...byElement, ...bySlotAttr];
+    /**
+     * Collect the nodes declared for one slot, in DOCUMENT order, marking every
+     * consumed child in `claimed`.
+     *
+     * The `<adw-bottom-sheet-sheet>` / `<adw-bottom-sheet-content>` wrappers are
+     * markup, not widgets — GtkBuilder's `<child type="sheet">` leaves nothing in
+     * the tree (adw-bottom-sheet.c:1278-1293) — so the wrapper itself is claimed
+     * too. It used to fall through to `unslotted` and be appended to the content
+     * layer, leaving an empty custom element behind after its children were
+     * pulled out.
+     */
+    private _collectSlot(tag: string, slot: string, claimed: Set<Node>): Node[] {
+        const nodes: Node[] = [];
+        for (const child of Array.from(this.children)) {
+            if (child.tagName.toLowerCase() === tag) {
+                claimed.add(child);
+                nodes.push(...Array.from(child.childNodes));
+            } else if (child.getAttribute('slot') === slot) {
+                claimed.add(child);
+                nodes.push(child);
+            }
+        }
+        return nodes;
     }
 }
 

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

@@ -1,67 +1,141 @@
 // <adw-button-content> — a box-like child pairing a symbolic icon with a label,
-// intended as the child of an <adw-button> (or Gtk.Button / MenuButton /
-// SplitButton in libadwaita) when it needs both an icon and a label. With
-// `can-shrink` the label ellipsizes instead of forcing the button wider.
-// Attributes: icon-name (symbolic name, e.g. "folder-download"; empty hides the
-//   icon), label (empty hides the label), can-shrink (boolean — label
-//   ellipsizes when set).
-// Events: `notify::icon-name`, `notify::label`, `notify::can-shrink`
-//   (CustomEvent, bubbles) mirroring the AdwButtonContent GObject notify signals
-//   the native story observes.
+// intended as the child of a button (or Gtk.Button / MenuButton / SplitButton in
+// libadwaita) when it needs both an icon and a label.
+// Attributes: icon-name (symbolic name, e.g. "folder-download"; EMPTY shows the
+//   `image-missing` fallback, it does not hide the icon), label (empty hides the
+//   label), use-underline (boolean — `_` marks a mnemonic), can-shrink (boolean —
+//   label ellipsizes when set).
+// Events: `notify::icon-name`, `notify::label`, `notify::use-underline`,
+//   `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.
+//
 // Reference: refs/libadwaita/src/adw-button-content.c (AdwButtonContent)
-// Reference: refs/libadwaita/src/stylesheet/widgets/_buttons.scss (buttoncontent)
+// Reference: refs/libadwaita/src/stylesheet/widgets/_buttons.scss
+//            (image-text-button :77-91 · splitbutton override :499-507 ·
+//             buttoncontent :626-645)
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
-// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web; the
+// icon node is <adw-icon>.
+
+import { BUTTON_CONTENT_STYLE_CLASS, buttonContentIconName, buttonContentLabelText } from '@gjsify/adwaita-core';
+
+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).
+ */
+const BUTTON_SELECTOR = 'button, .adw-button';
+
+/** The split-button node the class is RETARGETED to (:112-113). */
+const SPLIT_BUTTON_SELECTOR = 'adw-split-button, .adw-split-button';
 
 export class AdwButtonContent extends HTMLElement {
     private _boxEl!: HTMLDivElement;
-    private _iconEl!: HTMLSpanElement;
+    private _iconEl!: AdwIcon;
     private _labelEl!: HTMLSpanElement;
     private _initialized = false;
+    /** The node currently carrying `image-text-button`, so unroot can find it. */
+    private _styledHost: HTMLElement | null = null;
 
     static get observedAttributes() {
-        return ['icon-name', 'label', 'can-shrink'];
+        return ['icon-name', 'label', 'use-underline', 'can-shrink'];
     }
 
     connectedCallback() {
-        if (this._initialized) return;
-        this._initialized = true;
+        if (!this._initialized) {
+            this._initialized = true;
 
-        // CSS node mirrors libadwaita's `buttoncontent > box > {image, label}`.
-        this._boxEl = document.createElement('div');
-        this._boxEl.className = 'adw-button-content-box';
+            // CSS node mirrors libadwaita's `buttoncontent > box > {image, label}`.
+            this._boxEl = document.createElement('div');
+            this._boxEl.className = 'adw-button-content-box';
 
-        this._iconEl = document.createElement('span');
-        // The image node is GTK_ACCESSIBLE_ROLE_PRESENTATION in libadwaita —
-        // it is decorative, the label carries the accessible name.
-        this._iconEl.setAttribute('aria-hidden', 'true');
+            // 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.
+            this._iconEl = createAdwIcon(null);
 
-        this._labelEl = document.createElement('span');
-        this._labelEl.className = 'adw-button-content-label';
+            this._labelEl = document.createElement('span');
+            this._labelEl.className = 'adw-button-content-label';
 
-        this._boxEl.append(this._iconEl, this._labelEl);
-        this.replaceChildren(this._boxEl);
-        this._render();
+            this._boxEl.append(this._iconEl, this._labelEl);
+            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.
+        this._root();
+    }
+
+    disconnectedCallback() {
+        this._unroot();
     }
 
     attributeChangedCallback(name: string) {
         if (!this._initialized) return;
         this._render();
         // Mirror the AdwButtonContent notify::<prop> signals the native story
-        // listens to (icon-name / label / can-shrink).
+        // 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).
+     */
+    private _hostButton(): HTMLElement | null {
+        const button = this.parentElement?.closest<HTMLElement>(BUTTON_SELECTOR) ?? null;
+        if (!button) return null;
+        const parent = button.parentElement;
+        return parent?.matches(SPLIT_BUTTON_SELECTOR) ? parent : button;
+    }
+
+    private _root(): void {
+        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.
+        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.
+        this._styledHost?.classList.remove(BUTTON_CONTENT_STYLE_CLASS);
+        this._styledHost = null;
+    }
+
     private _render() {
-        const icon = this.getAttribute('icon-name') ?? '';
-        this._iconEl.className = icon ? `adw-icon adw-icon--${icon}` : '';
-        this._iconEl.hidden = icon.length === 0;
+        // 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.
+        this._iconEl.iconName = buttonContentIconName(this.getAttribute('icon-name') ?? '');
+        this._iconEl.hidden = false;
 
         const label = this.getAttribute('label') ?? '';
-        this._labelEl.textContent = 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.
         this._labelEl.hidden = label.length === 0;
 
-        // can-shrink → ellipsize the label (Gtk.Label PANGO_ELLIPSIZE_END).
+        // can-shrink → ellipsize the label (Gtk.Label PANGO_ELLIPSIZE_END, :490).
         this.classList.toggle('can-shrink', this.hasAttribute('can-shrink'));
     }
 }

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

@@ -1,24 +1,49 @@
 // <adw-button-row> — A boxed-list row that behaves like a button: a centered
-// title with an optional start 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 (symbolic name, e.g. "list-add"),
-//   activatable (default on — matches Adw.ButtonRow).
+// 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.
-// Reference: refs/libadwaita/src/adw-button-row.ui (AdwButtonRow template)
+//
+// 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.
+//
+// Reference: refs/libadwaita/src/adw-button-row.c, adw-button-row.ui
 // Reference: refs/libadwaita/src/stylesheet/widgets/_lists.scss (row.button)
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
-// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web; the
+// label/icon state composed from @gjsify/adwaita-core.
+
+import { BUTTON_ROW_ACTIVATABLE, ButtonRowState } from '@gjsify/adwaita-core';
+
+import { type AdwIcon, createAdwIcon } from './adw-icon.js';
 
 export class AdwButtonRow extends HTMLElement {
     private _contentsEl!: HTMLDivElement;
-    private _startIconEl!: HTMLSpanElement;
+    private _startIconEl!: AdwIcon;
+    private _endIconEl!: AdwIcon;
     private _titleEl!: HTMLSpanElement;
+    /** The headless title + start/end icon state (ADR 0004). */
+    private readonly _state = new ButtonRowState();
     private _initialized = false;
 
     static get observedAttributes() {
-        return ['title', 'start-icon-name', 'activatable'];
+        return ['title', 'start-icon-name', 'end-icon-name'];
     }
 
     connectedCallback() {
@@ -27,33 +52,21 @@ export class AdwButtonRow extends HTMLElement {
         this._contentsEl = document.createElement('div');
         this._contentsEl.className = 'adw-button-row-contents';
 
-        this._startIconEl = document.createElement('span');
-        this._startIconEl.setAttribute('aria-hidden', 'true');
+        this._startIconEl = createAdwIcon(null, 'start');
 
         this._titleEl = document.createElement('span');
         this._titleEl.className = 'adw-button-row-title';
 
-        this._contentsEl.append(this._startIconEl, this._titleEl);
-        this.replaceChildren(this._contentsEl);
+        this._endIconEl = createAdwIcon(null, 'end');
 
-        // Adw.ButtonRow is activatable by default; only an explicit
-        // activatable="false" turns it off. Set this while still uninitialized
-        // so the re-entrant attributeChangedCallback is a no-op — the explicit
-        // _render() below does the first render, once the elements above exist.
-        // (Setting _initialized before the elements were built made this
-        // setAttribute re-enter _render() and crash on a declaratively-parsed
-        // row, where connectedCallback runs with attributes already present.)
-        if (!this.hasAttribute('activatable')) {
-            this.setAttribute('activatable', '');
-        }
+        this._contentsEl.append(this._startIconEl, this._titleEl, this._endIconEl);
+        this.replaceChildren(this._contentsEl);
 
         this._initialized = true;
         this._render();
 
         this.addEventListener('click', () => {
-            if (this._isActivatable()) {
-                this.dispatchEvent(new CustomEvent('activated', { bubbles: true }));
-            }
+            this.dispatchEvent(new CustomEvent('activated', { bubbles: true }));
         });
     }
 
@@ -61,20 +74,31 @@ export class AdwButtonRow extends HTMLElement {
         if (this._initialized) this._render();
     }
 
-    private _isActivatable(): boolean {
-        return this.getAttribute('activatable') !== 'false';
-    }
-
     private _render() {
-        const title = this.getAttribute('title') ?? '';
-        this._titleEl.textContent = title;
-        this._titleEl.hidden = title.length === 0;
+        this._state.setTitle(this.getAttribute('title'));
+        this._state.setStartIconName(this.getAttribute('start-icon-name'));
+        this._state.setEndIconName(this.getAttribute('end-icon-name'));
+        const state = this._state.state;
+
+        this._titleEl.textContent = state.title;
+        this._titleEl.hidden = !state.titleVisible;
 
-        const icon = this.getAttribute('start-icon-name') ?? '';
-        this._startIconEl.className = icon ? `adw-icon adw-icon--${icon}` : '';
-        this._startIconEl.hidden = icon.length === 0;
+        this._paintIcon(this._startIconEl, state.startIconName, state.startIconVisible);
+        this._paintIcon(this._endIconEl, state.endIconName, state.endIconVisible);
+
+        // Unconditional: an AdwButtonRow has no way to not be activatable.
+        this.classList.toggle('activatable', BUTTON_ROW_ACTIVATABLE);
+    }
 
-        this.classList.toggle('activatable', this._isActivatable());
+    /**
+     * Paint one of the two `image.icon.{start,end}` nodes (adw-button-row.c:39-40).
+     *
+     * 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.
+     */
+    private _paintIcon(el: AdwIcon, iconName: string, visible: boolean) {
+        el.iconName = visible ? iconName : null;
+        el.hidden = !visible;
     }
 }