@gjsify/adwaita-web 0.31.0 → 0.32.0

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

@@ -1,19 +1,50 @@
 // <adw-action-row> — A boxed-list row with a title, optional subtitle, and
 // prefix / suffix widget slots. The most fundamental Adwaita row type.
 // Attributes: title, subtitle, activatable.
+// Properties: activatableWidget (get/set) — the Adw.ActionRow:activatable-widget
+//   the row forwards its activation to, and whose sensitivity drives whether the
+//   row is activatable at all.
 // Slots: slot="prefix" (icons/widgets before the text), slot="suffix" (controls
 //   after the text — switches, buttons, value labels).
 // Events: `activated` (CustomEvent) when an `activatable` row is clicked.
+//
+// The LABEL VISIBILITY rule and the activatable-widget coupling are HEADLESS and
+// live in `@gjsify/adwaita-core` (ADR 0004) as {@link ActionRowState}; this
+// element composes it and keeps only the DOM render half.
+// `@gjsify/adwaita-nativescript` composes the same state, so both ports share one
+// behaviour.
+//
 // Reference: refs/adwaita-web/adwaita-web/docs/widgets/actionrow.md
+// Reference: refs/libadwaita/src/adw-action-row.c, adw-action-row.ui
 // Reference: refs/libadwaita/src/stylesheet/widgets/_lists.scss (.row styling)
 // 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 + activation state composed from @gjsify/adwaita-core.
+
+import { ActionRowState } from '@gjsify/adwaita-core';
+
+/**
+ * Attributes whose change means the activatable widget's sensitivity may have
+ * changed. `disabled` is the DOM's `GtkWidget:sensitive` for form controls;
+ * `aria-disabled` is the only spelling a non-form element has.
+ */
+const SENSITIVITY_ATTRIBUTES = ['disabled', 'aria-disabled'];
+
+/** Whether `widget` is sensitive, i.e. NOT disabled in either DOM spelling. */
+function isSensitive(widget: HTMLElement): boolean {
+    if ((widget as HTMLElement & { disabled?: boolean }).disabled === true) return false;
+    return widget.getAttribute('aria-disabled') !== 'true';
+}
 
 export class AdwActionRow extends HTMLElement {
     private _titleEl!: HTMLSpanElement;
     private _subtitleEl!: HTMLSpanElement;
     private _suffixEl!: HTMLDivElement;
     private _prefixEl!: HTMLDivElement;
+    /** The headless labels + activatable-widget coupling (ADR 0004). */
+    private readonly _state = new ActionRowState<HTMLElement>();
+    /** Watches the activatable widget's `disabled`/`aria-disabled` — the live binding. */
+    private _sensitivityObserver: MutationObserver | null = null;
     private _initialized = false;
 
     static get observedAttributes() {
@@ -30,6 +61,28 @@ export class AdwActionRow extends HTMLElement {
         return this._prefixEl;
     }
 
+    /** `Adw.ActionRow:activatable-widget` — the widget this row activates. */
+    get activatableWidget(): HTMLElement | null {
+        return this._state.activatableWidget;
+    }
+
+    /**
+     * Set the activatable widget. Its sensitivity is copied into `activatable`
+     * right away and then tracked, exactly as libadwaita's `sensitive` →
+     * `activatable` binding does (adw-action-row.c:729-732) — including the part
+     * that surprises: clearing the widget LEAVES the row activatable (C:709).
+     */
+    set activatableWidget(widget: HTMLElement | null) {
+        if (!this._state.setActivatableWidget(widget, widget ? isSensitive(widget) : true)) return;
+        this._observeSensitivity(widget);
+        this._syncActivatable();
+    }
+
+    /** Whether a click activates this row — `GtkListBoxRow:activatable`. */
+    get activatable(): boolean {
+        return this._state.activatable;
+    }
+
     connectedCallback() {
         if (this._initialized) return;
         this._initialized = true;
@@ -54,28 +107,85 @@ export class AdwActionRow extends HTMLElement {
         for (const child of suffixChildren) this._suffixEl.appendChild(child);
 
         this.replaceChildren(this._prefixEl, textEl, this._suffixEl);
+        // Adopt the declared attributes; `attributeChangedCallback` was guarded
+        // until now, so a parsed row would otherwise start with a stale state.
+        this._adoptAttributes();
         this._render();
 
-        this.addEventListener('click', () => {
-            if (this.hasAttribute('activatable')) {
-                this.dispatchEvent(new CustomEvent('activated', { bubbles: true }));
-            }
-        });
+        this.addEventListener('click', (event) => this._onClick(event));
+    }
+
+    /** Copy the declarative attributes into the headless state. */
+    private _adoptAttributes() {
+        this._state.setTitle(this.getAttribute('title'));
+        this._state.setSubtitle(this.getAttribute('subtitle'));
+        this._state.setActivatable(this.hasAttribute('activatable'));
+    }
+
+    disconnectedCallback() {
+        this._sensitivityObserver?.disconnect();
+        this._sensitivityObserver = null;
     }
 
     attributeChangedCallback() {
+        if (!this._initialized) return;
+        this._adoptAttributes();
+        this._render();
+    }
+
+    /**
+     * `adw_action_row_activate_real` (adw-action-row.c:297-307): forward the
+     * activation to the activatable widget, then emit `activated`.
+     *
+     * A click that ORIGINATED inside the activatable widget does not activate the
+     * row at all — no forwarding, no `activated`. That is GTK's answer too: the
+     * widget claims the gesture, so `GtkListBox` never emits `row-activated`, and
+     * `pressed_cb` denies anything picked below the row / header / prefixes /
+     * suffixes (C:120-137). It is also what keeps the forwarding from looping —
+     * the synthetic click dispatched below bubbles straight back into this same
+     * listener, and without the guard one activation emitted `activated` twice.
+     */
+    private _onClick(event: Event) {
+        if (!this._state.activatable) return;
+        const target = this._state.activate();
+        if (target && event.target instanceof Node && target.contains(event.target)) return;
+        target?.click();
+        this.dispatchEvent(new CustomEvent('activated', { bubbles: true }));
+    }
+
+    /** (Re)point the sensitivity watcher at `widget`, or stop watching. */
+    private _observeSensitivity(widget: HTMLElement | null) {
+        this._sensitivityObserver?.disconnect();
+        if (!widget) {
+            this._sensitivityObserver = null;
+            return;
+        }
+        this._sensitivityObserver ??= new MutationObserver(() => {
+            const current = this._state.activatableWidget;
+            if (current && this._state.setActivatableWidgetSensitive(isSensitive(current))) this._syncActivatable();
+        });
+        this._sensitivityObserver.observe(widget, { attributeFilter: SENSITIVITY_ATTRIBUTES });
+    }
+
+    /** Reflect the state's `activatable` back onto the attribute + class. */
+    private _syncActivatable() {
+        // Re-enters attributeChangedCallback, whose `setActivatable` is then a
+        // no-op — the state already holds this value.
+        this.toggleAttribute('activatable', this._state.activatable);
         if (this._initialized) this._render();
     }
 
     private _render() {
-        const title = this.getAttribute('title') ?? '';
-        const subtitle = this.getAttribute('subtitle') ?? '';
+        const { title, titleVisible, subtitle, subtitleVisible } = this._state.state;
         this._titleEl.textContent = title;
+        // `string_is_not_empty` applies to the TITLE as much as to the subtitle
+        // (adw-action-row.ui:49-53) — an empty title used to keep its line here.
+        this._titleEl.hidden = !titleVisible;
         this._subtitleEl.textContent = subtitle;
-        this._subtitleEl.hidden = subtitle.length === 0;
+        this._subtitleEl.hidden = !subtitleVisible;
         this._prefixEl.hidden = this._prefixEl.childElementCount === 0;
         this._suffixEl.hidden = this._suffixEl.childElementCount === 0;
-        this.classList.toggle('activatable', this.hasAttribute('activatable'));
+        this.classList.toggle('activatable', this._state.activatable);
     }
 }
 

package/src/elements/adw-avatar.ts

@@ -3,53 +3,26 @@
 // Attributes: text, size (px, default 48), show-initials (boolean),
 //   icon (symbolic fallback name, with or without -symbolic).
 // Reference: refs/adwaita-web/adwaita-web/scss/_avatar.scss
-// Reference: refs/libadwaita/src/adw-avatar.c (initials + colour derivation)
 // 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
+// fallback icon node is <adw-icon>.
+//
+// The two derivations — initials from the name, and the palette colour the name
+// hashes to — are HEADLESS and live in `@gjsify/adwaita-core` (ADR 0004) as
+// {@link avatarInitials} / {@link avatarColor}; this element only paints them.
+// They used to be a local copy that had drifted from both libadwaita and the
+// NativeScript renderer (single-word names rendered TWO letters here and one
+// there, and accented names picked the wrong colour in both). The shared
+// vectors in `@gjsify/adwaita-core/conformance` now pin this element to the C
+// source — see `src/adw-avatar.spec.ts`.
 
-// A subset of the libadwaita avatar palette (saturated background + light text).
-// The exact libadwaita avatar palette: 14 entries of { fg (a light tint), and a
-// start→stop gradient background }. Reference:
-// refs/libadwaita/src/stylesheet/widgets/_avatar.scss ($avatarcolorlist).
-const AVATAR_COLORS: ReadonlyArray<{ fg: string; start: string; stop: string }> = [
-    { fg: '#cfe1f5', start: '#83b6ec', stop: '#337fdc' }, // blue
-    { fg: '#caeaf2', start: '#7ad9f1', stop: '#0f9ac8' }, // cyan
-    { fg: '#cef8d8', start: '#8de6b1', stop: '#29ae74' }, // green
-    { fg: '#e6f9d7', start: '#b5e98a', stop: '#6ab85b' }, // lime
-    { fg: '#f9f4e1', start: '#f8e359', stop: '#d29d09' }, // yellow
-    { fg: '#ffead1', start: '#ffcb62', stop: '#d68400' }, // gold
-    { fg: '#ffe5c5', start: '#ffa95a', stop: '#ed5b00' }, // orange
-    { fg: '#f8d2ce', start: '#f78773', stop: '#e62d42' }, // raspberry
-    { fg: '#fac7de', start: '#e973ab', stop: '#e33b6a' }, // magenta
-    { fg: '#e7c2e8', start: '#cb78d4', stop: '#9945b5' }, // purple
-    { fg: '#d5d2f5', start: '#9e91e8', stop: '#7a59ca' }, // violet
-    { fg: '#f2eade', start: '#e3cf9c', stop: '#b08952' }, // beige
-    { fg: '#e5d6ca', start: '#be916d', stop: '#785336' }, // brown
-    { fg: '#d8d7d3', start: '#c0bfbc', stop: '#6e6d71' }, // gray
-];
+import { avatarColor, avatarFontSize, avatarInitials, avatarMaxFontSize, avatarMode } from '@gjsify/adwaita-core';
 
-function initialsOf(text: string): string {
-    const words = text.trim().split(/\s+/).filter(Boolean);
-    if (words.length === 0) return '';
-    if (words.length === 1) return words[0].slice(0, 2).toUpperCase();
-    return (words[0][0] + words[words.length - 1][0]).toUpperCase();
-}
-
-// GLib's g_str_hash (DJB2 variant: h = h*33 + c, as uint32) so the picked colour
-// matches Adw.Avatar exactly (it uses g_str_hash(text) % 14).
-function gStrHash(text: string): number {
-    let h = 5381;
-    for (let i = 0; i < text.length; i++) h = (Math.imul(h, 33) + text.charCodeAt(i)) >>> 0;
-    return h >>> 0;
-}
-
-function colorFor(text: string): { fg: string; start: string; stop: string } {
-    return AVATAR_COLORS[gStrHash(text) % AVATAR_COLORS.length];
-}
+import { type AdwIcon, createAdwIcon } from './adw-icon.js';
 
 export class AdwAvatar extends HTMLElement {
     private _textEl!: HTMLSpanElement;
-    private _iconEl!: HTMLSpanElement;
+    private _iconEl!: AdwIcon;
     private _initialized = false;
 
     static get observedAttributes() {
@@ -63,9 +36,7 @@ export class AdwAvatar extends HTMLElement {
         this._textEl = document.createElement('span');
         this._textEl.className = 'adw-avatar-text';
 
-        this._iconEl = document.createElement('span');
-        this._iconEl.className = 'adw-avatar-icon adw-icon';
-        this._iconEl.setAttribute('aria-hidden', 'true');
+        this._iconEl = createAdwIcon(null, 'adw-avatar-icon');
 
         this.replaceChildren(this._textEl, this._iconEl);
         this._render();
@@ -79,30 +50,53 @@ export class AdwAvatar extends HTMLElement {
         const size = parseFloat(this.getAttribute('size') || '48');
         this.style.width = `${size}px`;
         this.style.height = `${size}px`;
-        this.style.fontSize = `${Math.round(size * (size < 32 ? 0.5 : 0.4))}px`;
 
         const text = this.getAttribute('text') ?? '';
-        const initials = initialsOf(text);
-        const showInitials = this.hasAttribute('show-initials') && initials.length > 0;
+        // The gate is the TEXT, not the derived initials — `update_visibility`
+        // keeps a whitespace-only name in initials mode with a blank label.
+        const mode = avatarMode({
+            hasCustomImage: false,
+            showInitials: this.hasAttribute('show-initials'),
+            text,
+        });
 
-        if (showInitials) {
-            const { fg, start, stop } = colorFor(text || 'default');
+        if (mode === 'initials') {
+            const { fg, start, stop } = avatarColor(text);
             this.style.backgroundImage = `linear-gradient(${start}, ${stop})`;
             this.style.color = fg;
-            this._textEl.textContent = initials;
+            this._textEl.textContent = avatarInitials(text);
             this._textEl.hidden = false;
             this._iconEl.hidden = true;
+            this._applyFontSize(size);
         } else {
             this.style.backgroundImage = '';
             this.style.color = '';
             this._textEl.hidden = true;
-            const icon = (this.getAttribute('icon') ?? 'avatar-default').replace(/-symbolic$/, '');
-            this._iconEl.className = `adw-avatar-icon adw-icon adw-icon--${icon}`;
-            this._iconEl.style.width = `${Math.round(size * 0.55)}px`;
-            this._iconEl.style.height = `${Math.round(size * 0.55)}px`;
+            this._iconEl.iconName = this.getAttribute('icon') ?? 'avatar-default';
+            // The glyph scales with the avatar: `size` sizes the BOX and the mask
+            // together, which is what `.adw-avatar-icon`'s `mask-size: contain`
+            // was there to approximate.
+            this._iconEl.size = Math.round(size * 0.55);
             this._iconEl.hidden = false;
         }
     }
+
+    /**
+     * Size the initials the way `update_font_size` does: measure the label, then
+     * scale its aspect ratio against the cap.
+     *
+     * Only the ratio matters and it is font-size invariant, so measuring AT the
+     * cap is the browser's equivalent of Pango's reset-then-measure. The old
+     * `size * (size < 32 ? 0.5 : 0.4)` guess overflowed that cap at sizes 28, 30,
+     * 31 and everything from 64 up — the initials spilled out of the circle —
+     * and was not monotonic across the 32px boundary.
+     */
+    private _applyFontSize(size: number) {
+        const cap = avatarMaxFontSize(size);
+        this._textEl.style.fontSize = `${cap}px`;
+        const { width, height } = this._textEl.getBoundingClientRect();
+        this._textEl.style.fontSize = `${avatarFontSize(size, { width, height })}px`;
+    }
 }
 
 customElements.define('adw-avatar', AdwAvatar);

package/src/elements/adw-banner.ts

@@ -1,19 +1,36 @@
 // <adw-banner> — A full-width strip carrying a single in-context message and an
 // optional action button.
-// Attributes: title, button-label, revealed (boolean), use-markup (boolean).
+// Attributes: title, button-label, revealed (boolean), use-markup (boolean),
+//   button-style ("default" | "suggested").
 // Events: `button-clicked` (CustomEvent) when the action button is pressed.
-// Reference: refs/adwaita-web/adwaita-web/scss/_banner.scss
-// Reference: refs/libadwaita/src/stylesheet/widgets/_banner.scss
+//
+// The defaults and the derivations come from `@gjsify/adwaita-core` (ADR 0004),
+// so this element and `@gjsify/adwaita-nativescript` answer the same markup the
+// same way. They used not to: `revealed` was opt-in here and initialised TRUE
+// there, and neither renderer had `button-style` (Since 1.7) or stripped the
+// mnemonic marker the template pins onto the button (adw-banner.ui:33).
+//
+// Reference: refs/libadwaita/src/adw-banner.c (AdwBanner)
+// Reference: refs/libadwaita/src/adw-banner.ui
+// Reference: refs/libadwaita/src/stylesheet/widgets/_toolbars.scss (banner :243-262)
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
+import {
+    ADW_BANNER_BUTTON_STYLE_CLASSES,
+    bannerButtonStyleClasses,
+    bannerButtonText,
+    bannerButtonVisible,
+    parseBannerButtonStyle,
+} from '@gjsify/adwaita-core';
+
 export class AdwBanner extends HTMLElement {
     private _titleEl!: HTMLSpanElement;
     private _button!: HTMLButtonElement;
     private _initialized = false;
 
     static get observedAttributes() {
-        return ['title', 'button-label', 'revealed', 'use-markup'];
+        return ['title', 'button-label', 'revealed', 'use-markup', 'button-style'];
     }
 
     connectedCallback() {
@@ -39,17 +56,36 @@ export class AdwBanner extends HTMLElement {
 
     private _render() {
         const title = this.getAttribute('title') ?? '';
-        // `use-markup` mirrors Adw.Banner.use_markup: an opt-in (off by default)
-        // for developer-supplied markup in the title, not user input. Plain text
-        // goes through textContent.
+        // DELIBERATE DEPARTURE FROM THE C DEFAULT. `Adw.Banner:use-markup`
+        // defaults to TRUE (adw-banner.c:422-425) and `@gjsify/adwaita-core`
+        // carries that as the spec value — but Pango markup is not HTML. Pango
+        // has a fixed tag set and no scripting; `innerHTML` will run an
+        // `onerror` handler. Adopting the C default here would turn every
+        // `title` attribute into an injection sink for a widget that is not one
+        // in GTK, so on this renderer markup is OPT-IN and the default is text.
+        // The opt-in is the developer asserting the title is trusted.
+        // The title label carries `use-underline=False` in the template
+        // (adw-banner.ui:20), so its underscores are literal — no stripping here.
         if (this.hasAttribute('use-markup')) this._titleEl.innerHTML = title;
         else this._titleEl.textContent = title;
 
+        // `label && label[0]` (:663) — a first-character test, so a label of
+        // spaces still shows a button. The template pins the BUTTON to
+        // `use-underline=True` (adw-banner.ui:33), so the painted text drops the
+        // mnemonic markers the attribute keeps.
         const buttonLabel = this.getAttribute('button-label') ?? '';
-        this._button.textContent = buttonLabel;
-        this._button.hidden = buttonLabel.length === 0;
+        this._button.textContent = bannerButtonText(buttonLabel);
+        this._button.hidden = !bannerButtonVisible(buttonLabel);
+
+        // `button-style` (Since 1.7, :443-447) adds or removes exactly one class
+        // (:764-774) — swap within the managed set so nothing else is touched.
+        const style = parseBannerButtonStyle(this.getAttribute('button-style'));
+        const applied = bannerButtonStyleClasses(style);
+        for (const cls of ADW_BANNER_BUTTON_STYLE_CLASSES) {
+            this._button.classList.toggle(cls, applied.includes(cls));
+        }
 
-        // `revealed` (default false to match Adw.Banner) slides the strip in/out.
+        // `revealed` (default FALSE, :456-459) slides the strip in/out.
         this.classList.toggle('revealed', this.hasAttribute('revealed'));
     }
 }