@gjsify/adwaita-web 0.64.1 → 0.64.2-next.254

package/src/elements/gtk-box.ts

@@ -19,15 +19,35 @@
 // Children are not moved or wrapped: the element IS the flex container, so a child in the
 // light DOM is a child of the layout, which is what `gtk_box_append` means.
 //
+// EXPAND IS THE COMPUTED VALUE, not the attribute: GtkBoxLayout grows a child when
+// `gtk_widget_compute_expand` says so (gtkboxlayout.c:391), and that is true for a bin whose
+// descendant set `hexpand` too. `compute-expand.ts` computes it; the box writes it on each
+// child that authored no value of its own as `data-computed-hexpand` / `-vexpand`, which
+// `_widget.scss` grows like the attribute. A MutationObserver over the box's subtree is the
+// substitute for `gtk_widget_queue_compute_expand`, which walks up from any widget whose
+// expand or visibility changed — so a runtime reparent or a toggled `hexpand` deep inside a
+// child lands one microtask later.
+//
 // Reference: refs/gtk/gtk/gtkbox.c (the three properties, the `box` CSS name)
 // Copyright (c) The GTK Team. LGPLv2.1+.
 
 import { normalizeBoxOrientation, normalizeBoxSpacing, type BoxOrientation } from '@gjsify/adwaita-core';
+import { WidgetElement } from '../widget-element.js';
+
+import { computeExpand, explicitExpand, type ExpandOrientation } from '../compute-expand.js';
 
 /** The attributes that carry a property — also the `notify::` roster. */
 const PROPERTY_ATTRIBUTES = ['orientation', 'spacing', 'homogeneous'] as const;
 
-export class GtkBox extends HTMLElement {
+/** The marker per axis a child carries while its computed expand is true. */
+const COMPUTED_EXPAND: Record<ExpandOrientation, string> = {
+    horizontal: 'data-computed-hexpand',
+    vertical: 'data-computed-vexpand',
+};
+
+export class GtkBox extends WidgetElement {
+    private _expandObserver: MutationObserver | null = null;
+
     static get observedAttributes() {
         return [...PROPERTY_ATTRIBUTES];
     }
@@ -61,6 +81,22 @@ export class GtkBox extends HTMLElement {
 
     connectedCallback() {
         this._sync();
+        this._syncComputedExpand();
+        if (this._expandObserver) return;
+        this._expandObserver = new MutationObserver((records) => {
+            if (records.some(affectsExpand)) this._syncComputedExpand();
+        });
+        this._expandObserver.observe(this, {
+            childList: true,
+            subtree: true,
+            attributes: true,
+            attributeFilter: ['hexpand', 'vexpand', 'hidden'],
+        });
+    }
+
+    disconnectedCallback() {
+        this._expandObserver?.disconnect();
+        this._expandObserver = null;
     }
 
     attributeChangedCallback(name: string, old: string | null, value: string | null) {
@@ -82,6 +118,25 @@ export class GtkBox extends HTMLElement {
         this.style.flexDirection = this.orientation === 'vertical' ? 'column' : 'row';
         this.style.gap = `${this.spacing}px`;
     }
+
+    private _syncComputedExpand(): void {
+        for (const child of this.children) {
+            for (const orientation of ['horizontal', 'vertical'] as const) {
+                const grows = explicitExpand(child, orientation) === undefined && computeExpand(child, orientation);
+                child.toggleAttribute(COMPUTED_EXPAND[orientation], grows);
+            }
+        }
+    }
+}
+
+/**
+ * Text rewritten inside a label (a hex dump does it every frame) adds and removes only text
+ * nodes; no widget came or went, so the computed expand cannot have changed.
+ */
+function affectsExpand(record: MutationRecord): boolean {
+    if (record.type !== 'childList') return true;
+    const isElement = (node: Node): boolean => node.nodeType === Node.ELEMENT_NODE;
+    return [...record.addedNodes].some(isElement) || [...record.removedNodes].some(isElement);
 }
 
 customElements.define('gtk-box', GtkBox);

package/src/elements/gtk-button.ts

@@ -16,14 +16,16 @@
 
 import { buttonStyleClasses } from '@gjsify/adwaita-core';
 
+import { FORWARDED_ARIA, forwardAccessibleName } from '../accessible.js';
 import { bindSlottedChildren } from '../slotted-children.js';
 import type { DispatchedSignals } from '../signals.js';
 import { createGtkImage } from './gtk-image.js';
+import { TooltipElement } from '../widget-element.js';
 
 /** The boolean attributes that select a style class; the mapping lives in the core. */
 const STYLE_ATTRIBUTES = ['flat', 'suggested', 'destructive', 'circular', 'pill'] as const;
 
-export class GtkButton extends HTMLElement {
+export class GtkButton extends TooltipElement {
     /** The GTK signals this element dispatches, each with the DOM event it arrives as (ADR 0093). */
     static readonly signals: DispatchedSignals = { clicked: 'click' };
 
@@ -47,12 +49,14 @@ export class GtkButton extends HTMLElement {
             'circular',
             'pill',
             'class',
+            ...FORWARDED_ARIA,
         ];
     }
 
     /**
-     * `Gtk.Button:icon-name` and `Gtk.Widget:tooltip-text`, the GObject spellings: a class that
-     * holds a button as a template child writes `button.icon_name = …`, which must reach the DOM.
+     * `Gtk.Button:icon-name`, the GObject spelling: a class that holds a button as a template
+     * child writes `button.icon_name = …`, which must reach the DOM. `Gtk.Widget:tooltip-text`
+     * comes from `TooltipElement`.
      */
     get icon_name(): string | null {
         return this.getAttribute('icon-name');
@@ -66,18 +70,6 @@ export class GtkButton extends HTMLElement {
     set iconName(value: string | null) {
         this.icon_name = value;
     }
-    get tooltip_text(): string | null {
-        return this.getAttribute('tooltip-text');
-    }
-    set tooltip_text(value: string | null) {
-        this.reflect('tooltip-text', value);
-    }
-    get tooltipText(): string | null {
-        return this.tooltip_text;
-    }
-    set tooltipText(value: string | null) {
-        this.tooltip_text = value;
-    }
 
     private reflect(attribute: string, value: string | null): void {
         if (value === null || value === undefined) this.removeAttribute(attribute);
@@ -148,13 +140,9 @@ export class GtkButton extends HTMLElement {
         const tooltip = this.getAttribute('tooltip') ?? this.getAttribute('tooltip-text');
         btn.title = tooltip ?? '';
         // An icon-only button has no text content, so screen readers would
-        // announce it as unlabeled. Give it an accessible name — prefer the
-        // tooltip, fall back to the symbolic icon name (WCAG 4.1.2).
-        if (icon && !label) {
-            btn.setAttribute('aria-label', tooltip ?? icon);
-        } else {
-            btn.removeAttribute('aria-label');
-        }
+        // announce it as unlabeled. Give it an accessible name — the one the tree
+        // wrote first, then the tooltip, then the symbolic icon name (WCAG 4.1.2).
+        if (!forwardAccessibleName(this, btn) && icon && !label) btn.setAttribute('aria-label', tooltip ?? icon);
         btn.disabled = this.hasAttribute('disabled');
         this.decorate(btn);
     }

package/src/elements/gtk-calendar.ts

@@ -68,6 +68,7 @@ import {
 } from '@gjsify/adwaita-core';
 
 import { createGtkImage } from './gtk-image.js';
+import { WidgetElement } from '../widget-element.js';
 
 /** The seven abbreviated day names, Sunday first — `default_abbreviated_dayname` (:745-757). */
 const DAY_NAMES = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
@@ -99,7 +100,7 @@ const ARROWS: readonly { step: AdwCalendarStep; icon: string; tooltip: string }[
 /** The arrow a cell's disabled state keys off — `calendar_update_navigation_buttons` (:1055-1084). */
 type ArrowName = 'previousMonth' | 'nextMonth' | 'previousYear' | 'nextYear';
 
-export class GtkCalendar extends HTMLElement {
+export class GtkCalendar extends WidgetElement {
     private _headerEl!: HTMLDivElement;
     private _monthEl!: HTMLSpanElement;
     private _yearEl!: HTMLSpanElement;

package/src/elements/gtk-center-box.ts

@@ -41,6 +41,7 @@
 import { labelYalignAlignItems } from '@gjsify/adwaita-core';
 
 import { bindSlottedChildren } from '../slotted-children.js';
+import { WidgetElement } from '../widget-element.js';
 
 /** `Gtk.BaselinePosition`'s three nicks, in the order GTK measures them (gtkcenterbox.c:267-271). */
 const BASELINE_POSITIONS = { top: 0, center: 0.5, bottom: 1 } as const;
@@ -51,7 +52,7 @@ export type BaselinePosition = keyof typeof BASELINE_POSITIONS;
 const SHRINK_FIRST = 100;
 const SHRINK_LAST = 1;
 
-export class GtkCenterBox extends HTMLElement {
+export class GtkCenterBox extends WidgetElement {
     static get observedAttributes() {
         return ['baseline-position', 'shrink-center-last'];
     }

package/src/elements/gtk-color-dialog-button.ts

@@ -37,6 +37,7 @@
 // Reference: refs/libadwaita/src/stylesheet/widgets/_linked.scss:6 (`colorbutton > button`)
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+import { WidgetElement } from '../widget-element.js';
 
 /** A `GdkRGBA` — the four channels of `GtkColorDialogButton:rgba`, each 0…1. */
 export interface GdkRgbaValue {
@@ -62,7 +63,7 @@ export interface ColorDialogParameters {
 /** `gtk_color_dialog_button_init`'s own colour: `{ 0.75, 0.25, 0.25, 1.0 }` (:170). */
 const INITIAL_RGBA: GdkRgbaValue = { red: 0.75, green: 0.25, blue: 0.25, alpha: 1 };
 
-export class GtkColorDialogButton extends HTMLElement {
+export class GtkColorDialogButton extends WidgetElement {
     private _buttonEl!: HTMLButtonElement;
     private _swatchEl!: HTMLSpanElement;
     private _inputEl!: HTMLInputElement;

package/src/elements/gtk-drag-icon.ts

@@ -53,6 +53,9 @@
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
+import { bindSlottedChildren } from '../slotted-children.js';
+import { WidgetElement } from '../widget-element.js';
+
 /** The `rgba()` string a `GdkRGBA` value paints, as the colour swatch shows it. */
 interface Rgba {
     readonly red: number;
@@ -64,7 +67,7 @@ interface Rgba {
 /** One icon per drag operation, keyed on the `dataTransfer` a browser gives per drag. */
 const ICON_BY_DRAG = new WeakMap<DataTransfer, GtkDragIcon>();
 
-export class GtkDragIcon extends HTMLElement {
+export class GtkDragIcon extends WidgetElement {
     private _pointerX = 0;
     private _pointerY = 0;
     private _dragging = false;
@@ -166,6 +169,8 @@ export class GtkDragIcon extends HTMLElement {
         // `gtk_widget_set_can_target (self, FALSE)` (:386-390), in CSS: the icon is pointed
         // at, and takes no pointer event of any kind.
         this.style.pointerEvents = 'none';
+        // The NAME only, for the reason `adw-bin.ts` gives: the child already IS the content.
+        bindSlottedChildren(this, [{ name: 'child', into: this }]);
         if (this._dragging) this._observe();
     }
 

package/src/elements/gtk-drawing-area.ts

@@ -53,6 +53,7 @@
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
 import { glibClamp } from '@gjsify/adwaita-core';
+import { WidgetElement } from '../widget-element.js';
 
 /**
  * `GtkDrawingAreaDrawFunc` with the `user_data` / `destroy` pair dropped — see the header.
@@ -78,7 +79,7 @@ function intAttribute(element: HTMLElement, name: string): number {
     return Number.isFinite(raw) ? raw : 0;
 }
 
-export class GtkDrawingArea extends HTMLElement {
+export class GtkDrawingArea extends WidgetElement {
     private _canvas!: HTMLCanvasElement;
     private _context: CanvasRenderingContext2D | null = null;
     private _initialized = false;

package/src/elements/gtk-drop-down.ts

@@ -75,6 +75,7 @@ import type { DispatchedSignals } from '../signals.js';
 import { stringListSlot } from '../string-list-slot.js';
 
 import { createGtkImage } from './gtk-image.js';
+import { WidgetElement } from '../widget-element.js';
 
 /**
  * A dropdown option — `value` is the stable id, `label` the shown text. An alias of
@@ -83,7 +84,7 @@ import { createGtkImage } from './gtk-image.js';
  */
 export type GtkDropDownOption = AdwComboOption;
 
-export class GtkDropDown extends HTMLElement {
+export class GtkDropDown extends WidgetElement {
     /** The GTK signals this element dispatches, each with the DOM event it arrives as (ADR 0093). */
     static readonly signals: DispatchedSignals = {
         'notify::selected': 'notify::selected',

package/src/elements/gtk-editable-label.ts

@@ -38,11 +38,12 @@
 //   (`label {}`, `editablelabel > stack > text`)
 // Copyright (c) The GTK Team, GNOME contributors. LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+import { WidgetElement } from '../widget-element.js';
 
 /** The C's grace period between a focus leaving the widget and the commit it triggers. */
 const FOCUS_OUT_GRACE_MS = 100;
 
-export class GtkEditableLabel extends HTMLElement {
+export class GtkEditableLabel extends WidgetElement {
     private _label!: HTMLSpanElement;
     private _entry!: HTMLInputElement;
     private _initialized = false;

package/src/elements/gtk-emoji-chooser.ts

@@ -103,6 +103,11 @@ export class GtkEmojiChooser extends GtkPopover {
      */
     private _ctrl = false;
 
+    /** The chooser's template is the child (gtkemojichooser.ui). */
+    protected override takesChild(): boolean {
+        return false;
+    }
+
     connectedCallback(): void {
         super.connectedCallback();
         if (this._built) return;

package/src/elements/gtk-entry.ts

@@ -23,8 +23,9 @@
 import { ENTRY_ROW_MAX_LENGTH_LIMIT, clampEntryText, entryTextLength } from '@gjsify/adwaita-core';
 
 import type { DispatchedSignals } from '../signals.js';
+import { WidgetElement } from '../widget-element.js';
 
-export class GtkEntry extends HTMLElement {
+export class GtkEntry extends WidgetElement {
     /**
      * `protected`, not `private`: `GtkPasswordEntry` and `GtkSearchEntry` subclass this
      * element and restyle or wrap the very input it builds (the password field's Caps Lock

package/src/elements/gtk-expander.ts

@@ -78,6 +78,7 @@ import { attachRowActivation } from './row-activation.js';
 // elided by TypeScript and take the `customElements.define` with it.
 import './gtk-label.js';
 import type { GtkLabel } from './gtk-label.js';
+import { WidgetElement } from '../widget-element.js';
 
 /** `expander { -gtk-icon-source: -gtk-icontheme('pan-end-symbolic') }` (_expanders.scss). */
 const ARROW_ICON = 'pan-end';
@@ -85,7 +86,7 @@ const ARROW_ICON = 'pan-end';
 /** Stable ids for the `aria-controls` relation, which GTK sets on the child itself. */
 let labelChildCounter = 0;
 
-export class GtkExpander extends HTMLElement {
+export class GtkExpander extends WidgetElement {
     private _box!: HTMLDivElement;
     private _titleEl!: HTMLDivElement;
     private _arrowEl!: HTMLElement;

package/src/elements/gtk-fixed.ts

@@ -32,8 +32,9 @@
 // Reference: refs/gtk/gtk/gtkfixedlayout.c:224-300
 // Copyright (c) The GTK Team. LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+import { WidgetElement } from '../widget-element.js';
 
-export class GtkFixed extends HTMLElement {
+export class GtkFixed extends WidgetElement {
     private _resize: ResizeObserver | null = null;
     private _mutations: MutationObserver | null = null;
 

package/src/elements/gtk-flow-box-child.ts

@@ -26,8 +26,9 @@
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
 import { bindSlottedChildren } from '../slotted-children.js';
+import { WidgetElement } from '../widget-element.js';
 
-export class GtkFlowBoxChild extends HTMLElement {
+export class GtkFlowBoxChild extends WidgetElement {
     private _contentsEl!: HTMLDivElement;
     private _initialized = false;
 
@@ -38,7 +39,9 @@ export class GtkFlowBoxChild extends HTMLElement {
         this._contentsEl = document.createElement('div');
         this._contentsEl.className = 'adw-flow-box-child-contents';
 
-        bindSlottedChildren(this, [{ into: this._contentsEl }]).install(this._contentsEl);
+        bindSlottedChildren(this, [{ name: 'child', into: this._contentsEl }, { into: this._contentsEl }]).install(
+            this._contentsEl,
+        );
 
         this.setAttribute('role', 'gridcell');
         // `gtk_flow_box_child_init` makes the cell focusable (:578-580) — the box's cursor

package/src/elements/gtk-flow-box.ts

@@ -66,6 +66,7 @@ import { attachRovingFocus } from './roving-focus.js';
 // `gtk-list-box.ts` states at its own: a combined import would be elided and take the
 // registration with it.
 import './gtk-flow-box-child.js';
+import { WidgetElement } from '../widget-element.js';
 
 /** `GtkFlowBox:max-children-per-line`'s default — `DEFAULT_MAX_CHILDREN_PER_LINE` (:728). */
 export const ADW_FLOW_BOX_MAX_CHILDREN_PER_LINE = 7;
@@ -73,7 +74,7 @@ export const ADW_FLOW_BOX_MAX_CHILDREN_PER_LINE = 7;
 /** `GtkFlowBox:orientation` — HORIZONTAL by default here, unlike a `GtkListBase` (:3981). */
 export type AdwFlowBoxOrientation = 'horizontal' | 'vertical';
 
-export class GtkFlowBox extends HTMLElement {
+export class GtkFlowBox extends WidgetElement {
     private _children: GtkFlowBoxChild[] = [];
     private _selection: number[] = [];
     /** `priv->selected_child`, `-1` for the C's NULL. */

package/src/elements/gtk-font-dialog-button.ts

@@ -71,6 +71,7 @@ import './gtk-popover.js';
 import type { GtkPopover } from './gtk-popover.js';
 
 import './gtk-separator.js';
+import { WidgetElement } from '../widget-element.js';
 
 /** `GtkFontLevel`'s four values, under the nicks a string property carries. */
 export type FontLevel = 'family' | 'face' | 'font' | 'features';
@@ -103,7 +104,7 @@ const FACE_GRID: readonly { weight: number; slant: PangoFontDescription['slant']
     { weight: 700, slant: 'italic' },
 ];
 
-export class GtkFontDialogButton extends HTMLElement {
+export class GtkFontDialogButton extends WidgetElement {
     private _buttonEl!: HTMLButtonElement;
     private _labelEl!: HTMLSpanElement;
     private _sizeBoxEl!: HTMLSpanElement;

package/src/elements/gtk-frame.ts

@@ -32,6 +32,7 @@
 import { glibClamp, labelYalignAlignItems } from '@gjsify/adwaita-core';
 
 import { bindSlottedChildren } from '../slotted-children.js';
+import { WidgetElement } from '../widget-element.js';
 
 /** `Gtk.Frame:label-xalign`'s pspec default (gtkframe.c:180-183, and `:253`). */
 const LABEL_XALIGN_DEFAULT = 0;
@@ -42,7 +43,7 @@ function normalizeLabelXalign(value: string | null): number {
     return Number.isFinite(parsed) ? glibClamp(parsed, 0, 1) : LABEL_XALIGN_DEFAULT;
 }
 
-export class GtkFrame extends HTMLElement {
+export class GtkFrame extends WidgetElement {
     private _mutations: MutationObserver | null = null;
 
     static get observedAttributes() {

package/src/elements/gtk-gl-area.ts

@@ -58,6 +58,7 @@
 // Reference: refs/gtk/gtk/gtkglarea.c
 // Copyright (c) The GTK Team. LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+import { WidgetElement } from '../widget-element.js';
 
 /** `GdkGLAPI`'s nicks, as `GdkGLAPINickSet` spells them. */
 const APIS = ['gl', 'gles'] as const;
@@ -85,7 +86,7 @@ function booleanAttribute(element: HTMLElement, name: string, fallback: boolean)
     return raw !== 'false' && raw !== '0';
 }
 
-export class GtkGLArea extends HTMLElement {
+export class GtkGLArea extends WidgetElement {
     private _canvas!: HTMLCanvasElement;
     private _messageEl: HTMLDivElement | null = null;
     private _initialized = false;

package/src/elements/gtk-graphics-offload.ts

@@ -42,6 +42,7 @@
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
 import { bindSlottedChildren } from '../slotted-children.js';
+import { WidgetElement } from '../widget-element.js';
 
 /** `GtkGraphicsOffloadEnabled`, spelled as the GIR's enum nicks. */
 type OffloadEnabled = 'enabled' | 'disabled';
@@ -52,7 +53,7 @@ function booleanAttribute(element: HTMLElement, name: string, fallback: boolean)
     return raw !== 'false' && raw !== '0';
 }
 
-export class GtkGraphicsOffload extends HTMLElement {
+export class GtkGraphicsOffload extends WidgetElement {
     private _childEl!: HTMLDivElement;
     private _initialized = false;
 
@@ -98,7 +99,9 @@ export class GtkGraphicsOffload extends HTMLElement {
         this._childEl.className = 'adw-graphics-offload-child';
         // `GTK_TYPE_BIN_LAYOUT` gives the child the whole allocation, and `child` is the one
         // GtkBuildable slot the widget has, so it is the default one here.
-        bindSlottedChildren(this, [{ into: this._childEl }]).install(this._childEl);
+        bindSlottedChildren(this, [{ name: 'child', into: this._childEl }, { into: this._childEl }]).install(
+            this._childEl,
+        );
         this.replaceChildren(this._childEl);
         this._render();
     }

package/src/elements/gtk-grid.ts

@@ -38,8 +38,9 @@
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
 import { normalizeBoxOrientation, normalizeBoxSpacing, type BoxOrientation } from '@gjsify/adwaita-core';
+import { WidgetElement } from '../widget-element.js';
 
-export class GtkGrid extends HTMLElement {
+export class GtkGrid extends WidgetElement {
     static get observedAttributes() {
         return ['column-spacing', 'row-spacing', 'column-homogeneous', 'row-homogeneous', 'orientation'];
     }

package/src/elements/gtk-header-bar.ts

@@ -64,8 +64,9 @@ import { bindSlottedChildren } from '../slotted-children.js';
 // Registers <gtk-window-controls>: `show-title-buttons` builds two of them, so importing
 // the bar alone must still define them.
 import './gtk-window-controls.js';
+import { WidgetElement } from '../widget-element.js';
 
-export class GtkHeaderBar extends HTMLElement {
+export class GtkHeaderBar extends WidgetElement {
     private _initialized = false;
     private _handle!: HTMLDivElement;
     private _box!: HTMLDivElement;

package/src/elements/gtk-image.ts

@@ -1,15 +1,15 @@
 // <gtk-image> — the icon node as an element. A symbolic icon 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. A full-colour icon registered
-// through `registerColorIcon` is the same box with the image as its background and no
+// `currentColor`, so it themes with whatever contains it. A full-colour icon from a
+// `Gtk.IconTheme` resource path is the same box with the image as its background and no
 // mask. Which of the two a name reaches is decided once, in `../icon-theme.ts`, in the
 // order GTK's own theme tries them; the symbolic name derivation and its guard live once
 // in `@gjsify/adwaita-core`'s {@link normalizeIconName}, the markup once here.
 //
 // Attributes:
 //   icon-name — icon name, `-symbolic` suffix optional. A name that is neither a
-//               registered colour icon nor a single CSS token (a space, a quote, an
-//               unregistered reverse-DNS application id) never reaches a class — it
+//               resource file nor a single CSS token (a space, a quote, a reverse-DNS
+//               application id no resource ships) never reaches a class — it
 //               draws {@link MISSING_ICON_NAME}, which is what GTK draws for it, rather
 //               than injecting markup.
 //   size      — rendered edge length in px. Absent leaves the stylesheet's 16px in
@@ -36,6 +36,7 @@
 import { normalizeIconName } from '@gjsify/adwaita-core';
 
 import { lookupIcon, onIconThemeChanged, type IconRequest } from '../icon-theme.js';
+import { WidgetElement } from '../widget-element.js';
 
 /** `url` as one CSS string token, whatever quotes or backslashes it holds. */
 function cssUrl(url: string): string {
@@ -43,9 +44,7 @@ function cssUrl(url: string): string {
 }
 
 /**
- * The generated mask-class prefix — the one place the `--` spelling appears. `icon-registry`
- * builds the same class for a runtime registration and imports it from here rather than
- * spelling it twice.
+ * The generated mask-class prefix — the one place the `--` spelling appears.
  */
 export const MASK_CLASS_PREFIX = 'adw-icon--';
 
@@ -63,7 +62,7 @@ export const MISSING_ICON_NAME = 'image-missing';
  */
 export const COLOR_ICON_CLASS = 'adw-icon-color';
 
-export class GtkImage extends HTMLElement {
+export class GtkImage extends WidgetElement {
     static get observedAttributes() {
         return ['icon-name', 'size'];
     }
@@ -80,8 +79,8 @@ export class GtkImage extends HTMLElement {
 
     /**
      * The name the SYMBOLIC lookup works with — `''` when the icon-name is absent, empty,
-     * or not usable as one CSS token. A registered colour icon can still draw for a name
-     * that answers `''` here (`org.gnome.Builder`); whether a name draws anything but
+     * or not usable as one CSS token. A resource file can still draw for a name that
+     * answers `''` here (`org.gnome.Builder`); whether a name draws anything but
      * `image-missing` is `isIconAvailable`'s question.
      *
      * `''` does NOT mean the box draws nothing: an unusable name that was given still
@@ -152,13 +151,13 @@ export class GtkImage extends HTMLElement {
         const looked = lookupIcon(this.getAttribute('icon-name'), this._request());
         // A resource file the browser cannot draw (XPM, compressed) is GTK's `image-missing`.
         const found = looked?.kind === 'resource' && looked.url === null ? ({ kind: 'missing' } as const) : looked;
-        const asIs = found?.kind === 'color' || (found?.kind === 'resource' && !found.symbolic) ? found.url : null;
+        const asIs = found?.kind === 'resource' && !found.symbolic ? found.url : null;
         const mask = found?.kind === 'resource' && found.symbolic ? found.url : null;
         this.classList.toggle(COLOR_ICON_CLASS, asIs !== null);
         if (asIs !== null) {
             // Drawn as-is: `_icon.scss` drops the mask and the `currentColor` fill for this
-            // modifier, so only the image paints. `url` is a data-URI, a blob or a resolved href;
-            // the quote and backslash escapes keep it one CSS string either way.
+            // modifier, so only the image paints. `url` is a blob URL; the quote and backslash
+            // escapes keep it one CSS string.
             this.style.backgroundImage = cssUrl(asIs);
         } else {
             this.style.removeProperty('background-image');
@@ -177,8 +176,8 @@ export class GtkImage extends HTMLElement {
         if (found?.kind === 'symbolic') {
             this.classList.add(`${MASK_CLASS_PREFIX}${found.name}`);
         } else if (found?.kind === 'missing') {
-            // A name was GIVEN and nothing answers it — not a colour icon, and not one CSS
-            // token (a space, a quote, an unregistered reverse-DNS application id). GTK has
+            // A name was GIVEN and nothing answers it — no resource file, and not one CSS
+            // token (a space, a quote, a reverse-DNS application id no resource ships). GTK has
             // no such state: `gtk_icon_theme_lookup_icon` never returns NULL, it returns the
             // always-available `image-missing` (refs/gtk/gtk/gtkicontheme.c —
             // `gtk_icon_paintable_get_icon_name`'s own docs say so). So the same glyph is

package/src/elements/gtk-inscription.ts

@@ -95,6 +95,7 @@ import {
     labelYalignAlignItems,
     type LabelWrapMode,
 } from '@gjsify/adwaita-core';
+import { WidgetElement } from '../widget-element.js';
 
 /** `GtkInscriptionOverflow`, in enum order (gtkinscription.h:44-48). */
 export const INSCRIPTION_OVERFLOW_MODES = ['clip', 'ellipsize-start', 'ellipsize-middle', 'ellipsize-end'] as const;
@@ -150,7 +151,7 @@ function normalizeCount(value: unknown): number {
     return Math.max(0, Math.trunc(parsed));
 }
 
-export class GtkInscription extends HTMLElement {
+export class GtkInscription extends WidgetElement {
     private _initialized = false;
 
     static get observedAttributes() {

package/src/elements/gtk-label.ts

@@ -78,6 +78,7 @@ import {
 } from '@gjsify/adwaita-core';
 
 import { JUSTIFY_TEXT_ALIGN } from './justification.js';
+import { WidgetElement } from '../widget-element.js';
 
 /** The attributes that carry a property — also the `notify::` roster. */
 const PROPERTY_ATTRIBUTES = [
@@ -96,7 +97,7 @@ const PROPERTY_ATTRIBUTES = [
     'selectable',
 ] as const;
 
-export class GtkLabel extends HTMLElement {
+export class GtkLabel extends WidgetElement {
     /**
      * The rendered text's own box — present while {@link wrap} is set (so it can be pinned
      * to its measured wrap width, see `_remeasure`) OR while {@link ellipsize} is not
@@ -291,9 +292,9 @@ export class GtkLabel extends HTMLElement {
 
     private _remeasure(): void {
         if (!this._wrapSpan || !this.isConnected) return;
-        this._wrapSpan.style.width = '';
+        this._wrapSpan.style.maxWidth = '';
         const width = measuredWrapWidth(this._wrapSpan);
-        this._wrapSpan.style.width = width !== null ? `${width}px` : '';
+        this._wrapSpan.style.maxWidth = width !== null ? `min(100%, ${width}px)` : '';
     }
 
     attributeChangedCallback(name: string, old: string | null, value: string | null) {
@@ -393,9 +394,15 @@ export class GtkLabel extends HTMLElement {
      * here, not the narrower width GTK's Pango layout actually wrapped to. So this measures
      * instead, in two passes: first let {@link _wrapSpan} wrap at the FULL container width
      * (`width: ''`, the same collapse above, which is exactly the width GTK's own
-     * allocation wraps against), then pin the span to its widest resulting line via
+     * allocation wraps against), then cap the span at its widest resulting line via
      * `Range.getClientRects()`, which gives the pseudo spacers real free space to split.
-     * Approximate on purpose, and cheap: one synchronous reflow per render. The pinned
+     * A CAP, `max-width`, and never `width`: a pinned `width` is also the span's
+     * min-content, so the label could no longer shrink below the width it first wrapped
+     * at, and a card holding it in a narrower pane grew past the pane and was clipped.
+     * GtkLabel's wrapping minimum is its widest word (`gtk_label_measure`), which a capped
+     * flex item keeps as its min-content; the cap itself only resolves against a definite
+     * container, so the label's max-content stays its text on one line, GTK's natural.
+     * Approximate on purpose, and cheap: one synchronous reflow per render. The measured
      * width goes stale whenever the available width or the font changes, and a page does
      * both (a rotated phone, an opened sidebar, a web font arriving late), so
      * {@link connectedCallback} re-measures on each resize and once the fonts have loaded.