@gjsify/adwaita-web 0.54.0 → 0.56.0

package/src/elements/adw-sidebar.ts

@@ -22,9 +22,14 @@
 //   <adw-sidebar-section title="…"> — a titled group of items. An untitled
 //     section renders a separator before its rows (first section: nothing),
 //     mirroring AdwSidebar's stack header (title vs separator child).
-//   <adw-sidebar-item title="…" subtitle="…" icon-name="…" disabled hidden> —
+//   <adw-sidebar-item title="…" subtitle="…" icon-name="…" disabled hidden
+//     needs-attention badge-number="3"> —
 //     one row. `disabled` is AdwSidebarItem:enabled=false (bound to the row's
-//     `sensitive`), `hidden` is AdwSidebarItem:visible=false.
+//     `sensitive`), `hidden` is AdwSidebarItem:visible=false, and the last two are the
+//     INDICATOR `AdwViewSwitcherSidebar` puts in `AdwSidebarItem:suffix`
+//     (`update_badge`, adw-view-switcher-sidebar.c:133-181): a bare dot for
+//     `needs-attention` with no count, a `999+`-capped label once there is one, and
+//     `.needs-attention` on the bin when attention is asked for either way.
 // Attributes (on <adw-sidebar>):
 //   mode (sidebar | page, default sidebar) — mirrors Adw.Sidebar:mode.
 //   selected (zero-based flat item index; anything that is not a valid position
@@ -45,6 +50,7 @@
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web; the
 // icon nodes are <gtk-image>.
 
+import { viewSwitcherBadgeLabel } from '@gjsify/adwaita-core';
 import {
     ADW_SIDEBAR_NO_SELECTION,
     SidebarState,
@@ -58,6 +64,7 @@ import {
 
 import { createGtkImage } from './gtk-image.js';
 import { attachRovingFocus } from './roving-focus.js';
+import { booleanAttribute } from '../attributes.js';
 
 // The sidebar consumes its declared children and drops them from the tree, so a later
 // `setAttribute` on one cannot find its sidebar with `closest()`. These keep the link —
@@ -69,28 +76,51 @@ const sectionBindings = new WeakMap<AdwSidebarSection, { sidebar: AdwSidebar; sp
 /** A single sidebar item. Child of <adw-sidebar-section>; consumed at connect time. */
 export class AdwSidebarItem extends HTMLElement {
     static get observedAttributes() {
-        return ['title', 'subtitle', 'icon-name', 'disabled', 'hidden'];
+        return [
+            'title',
+            'subtitle',
+            'icon-name',
+            'disabled',
+            'hidden',
+            'enabled',
+            'visible',
+            'needs-attention',
+            'badge-number',
+        ];
     }
 
     /**
-     * `AdwSidebarItem:enabled`, under the GIR name — the `disabled` attribute inverted. The
-     * property is what lets an authored `enabled: false` reach this item through the
+     * `AdwSidebarItem:enabled`, under the GIR name — the `disabled` attribute inverted.
+     * The property is what lets an authored `enabled: false` reach this item through the
      * shared-tree builder, which writes a `false` through the element's own property.
+     * Reads both the presence-based `disabled` and value-based `enabled` attributes.
      */
     get enabled(): boolean {
+        // Value-based `enabled` attribute takes precedence (shared-tree builder writes it).
+        const enabledAttr = this.getAttribute('enabled');
+        if (enabledAttr !== null) return booleanAttribute(enabledAttr, true);
+        // Fall back to presence-based `disabled` attribute.
         return !this.hasAttribute('disabled');
     }
 
     set enabled(value: boolean) {
+        // Write both for compatibility: value-based `enabled` and presence-based `disabled`.
+        this.setAttribute('enabled', value ? 'true' : 'false');
         this.toggleAttribute('disabled', !value);
     }
 
     /** `AdwSidebarItem:visible` — the `hidden` attribute inverted, for the same reason. */
     get visible(): boolean {
+        // Value-based `visible` attribute takes precedence (shared-tree builder writes it).
+        const visibleAttr = this.getAttribute('visible');
+        if (visibleAttr !== null) return booleanAttribute(visibleAttr, true);
+        // Fall back to presence-based `hidden` attribute.
         return !this.hasAttribute('hidden');
     }
 
     set visible(value: boolean) {
+        // Write both for compatibility: value-based `visible` and presence-based `hidden`.
+        this.setAttribute('visible', value ? 'true' : 'false');
         this.toggleAttribute('hidden', !value);
     }
 
@@ -103,7 +133,11 @@ export class AdwSidebarItem extends HTMLElement {
         else if (name === 'subtitle') binding.spec.subtitle = value;
         else if (name === 'icon-name') binding.spec.iconName = value;
         else if (name === 'disabled') binding.spec.enabled = newValue === null;
+        else if (name === 'enabled') binding.spec.enabled = booleanAttribute(newValue, true);
         else if (name === 'hidden') binding.spec.visible = newValue === null;
+        else if (name === 'visible') binding.spec.visible = booleanAttribute(newValue, true);
+        else if (name === 'needs-attention') binding.spec.needsAttention = newValue === null;
+        else if (name === 'badge-number') binding.spec.badgeNumber = Number.parseInt(value, 10) || 0;
 
         binding.sidebar.refresh();
     }
@@ -255,8 +289,12 @@ export class AdwSidebar extends HTMLElement {
                     title: itemEl.getAttribute('title') ?? '',
                     subtitle: itemEl.getAttribute('subtitle') ?? '',
                     iconName: itemEl.getAttribute('icon-name') ?? '',
-                    enabled: !itemEl.hasAttribute('disabled'),
-                    visible: !itemEl.hasAttribute('hidden'),
+                    // Use the element's own property getters, which read both value-based
+                    // (`enabled`/`visible`) and presence-based (`disabled`/`hidden`) attributes.
+                    enabled: itemEl.enabled,
+                    visible: itemEl.visible,
+                    badgeNumber: Number.parseInt(itemEl.getAttribute('badge-number') ?? '0', 10) || 0,
+                    needsAttention: itemEl.hasAttribute('needs-attention'),
                 };
                 itemBindings.set(itemEl, { sidebar: this, spec: item });
                 items.push(item);
@@ -391,6 +429,12 @@ export class AdwSidebar extends HTMLElement {
 
         row.appendChild(textEl);
 
+        // `update_badge` (adw-view-switcher-sidebar.c:133-181): no attention and no count
+        // means NO bin at all, a count means the bin loses `.dot` and gains the label, and
+        // a drop back to zero takes the label away and puts `.dot` back. The cap is
+        // `> 999`, which is `viewSwitcherBadgeLabel`'s rule, so 999 itself prints.
+        row.appendChild(this._createIndicator(item));
+
         // Page mode adds a trailing chevron on every row, the way the boxed-list
         // AdwActionRow carries a `go-next-symbolic` arrow.
         row.appendChild(createGtkImage('go-next', 'adw-sidebar-item-arrow'));
@@ -400,6 +444,29 @@ export class AdwSidebar extends HTMLElement {
         return row;
     }
 
+    /**
+     * The item's INDICATOR bin — C's `AdwBin` with `.indicator`, `.dot` and the
+     * optional `.needs-attention`, holding an `AdwFadingLabel`'s worth of text.
+     */
+    private _createIndicator(item: AdwSidebarItemSpec): HTMLElement {
+        const badge = item.badgeNumber ?? 0;
+        const attention = item.needsAttention === true;
+        const bin = document.createElement('span');
+        bin.className = 'indicator';
+        // Hidden, not absent: `set_suffix (item, NULL)` in C REMOVES the bin, and the
+        // difference is only observable through the suffix property.
+        bin.hidden = !attention && badge === 0;
+        bin.classList.toggle('dot', badge === 0);
+        bin.classList.toggle('needs-attention', attention);
+        if (badge > 0) {
+            const label = document.createElement('span');
+            label.className = 'numeric';
+            label.textContent = viewSwitcherBadgeLabel(badge);
+            bin.appendChild(label);
+        }
+        return bin;
+    }
+
     private _applyMode(): void {
         const page = this._state.mode === 'page';
         this.classList.toggle('page', page);

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

@@ -24,6 +24,11 @@
 // `adjustment:` sets the property to a whole new object: an unwritten field takes the
 // adjustment's own default, not what the row held (`ADJUSTMENT_AUTHORED_VECTORS`).
 //
+// ATTRIBUTES: `adjustment` (the range, JSON), `value`, `title`, `subtitle`, and
+// `title-lines` / `subtitle-lines` — clamp either label to N lines, `0` = unlimited,
+// the AdwActionRow pspec's sentinel (`@girs/adw-1`, min 0, default 0).
+// `tooltip-text` (`Gtk.Widget:tooltip-text`) — the row's tooltip (`src/row-tooltip.ts`).
+
 // Adapted from Adwaita Web UI Framework (https://github.com/mclellac/adwaita-web).
 // Copyright (c) 2025 csm. MIT License.
 // Modifications: Reimplemented as Web Component for @gjsify/adwaita-web;
@@ -34,7 +39,9 @@ import { SpinState, deriveRowLabels, normalizeAdjustment, parseAdjustment } from
 import type { AdwAdjustment, AdwAdjustmentInput } from '@gjsify/adwaita-core';
 import { attributeOf } from '@gjsify/adwaita-core/tags';
 
+import { applyRowTooltip } from '../row-tooltip.js';
 import { bindSlottedChildren } from '../slotted-children.js';
+import { applyRowLineClamp, parseRowLinesAttribute } from '../row-line-clamp.js';
 
 /** `Gtk.Adjustment`'s six properties, as `AdwAdjustmentInput` names them. */
 const ADJUSTMENT_FIELDS = ['value', 'lower', 'upper', 'stepIncrement', 'pageIncrement', 'pageSize'] as const;
@@ -58,6 +65,10 @@ function authoredAdjustment(node: Node): AdwAdjustmentInput {
 
 export class AdwSpinRow extends HTMLElement {
     private _input!: HTMLInputElement;
+    /** The label column — kept for `tooltip-text`, which the browser reads off a PART. */
+    private _textEl!: HTMLDivElement;
+    /** The −/input/+ box — the other half of the row's surface. */
+    private _controlEl!: HTMLDivElement;
     private _titleEl!: HTMLSpanElement;
     private _subtitleEl!: HTMLSpanElement;
     /** The headless adjustment: the range, the clamp and the two signals (ADR 0004, ADR 0047). */
@@ -65,7 +76,7 @@ export class AdwSpinRow extends HTMLElement {
     private _initialized = false;
 
     static get observedAttributes() {
-        return ['title', 'subtitle', 'value', 'adjustment'];
+        return ['title', 'subtitle', 'value', 'adjustment', 'tooltip-text', 'title-lines', 'subtitle-lines'];
     }
 
     get value(): number {
@@ -107,6 +118,7 @@ export class AdwSpinRow extends HTMLElement {
 
         const text = document.createElement('div');
         text.className = 'adw-row-text';
+        this._textEl = text;
         this._titleEl = document.createElement('span');
         this._titleEl.className = 'adw-row-title';
         this._subtitleEl = document.createElement('span');
@@ -115,6 +127,7 @@ export class AdwSpinRow extends HTMLElement {
 
         const control = document.createElement('div');
         control.className = 'adw-spin-control';
+        this._controlEl = control;
 
         const decBtn = document.createElement('button');
         decBtn.className = 'adw-spin-dec';
@@ -164,7 +177,16 @@ export class AdwSpinRow extends HTMLElement {
 
     attributeChangedCallback(name: string, _old: string | null, val: string | null) {
         if (!this._initialized) return;
-        if (name === 'title' || name === 'subtitle') {
+        if (
+            name === 'title' ||
+            name === 'subtitle' ||
+            name === 'tooltip-text' ||
+            // The two `*-lines` attributes are LABEL geometry, not the adjustment: without
+            // this branch they fell through to the `setValue` below, so `title-lines="1"`
+            // set the numeric value to 1 and clamped nothing.
+            name === 'title-lines' ||
+            name === 'subtitle-lines'
+        ) {
             this._renderText();
             return;
         }
@@ -186,6 +208,19 @@ export class AdwSpinRow extends HTMLElement {
         this._titleEl.hidden = !labels.titleVisible;
         this._subtitleEl.textContent = labels.subtitle;
         this._subtitleEl.hidden = !labels.subtitleVisible;
+        applyRowTooltip(this, [this._textEl, this._controlEl]);
+        this._applyLineClamping();
+    }
+
+    /** Apply CSS line-clamping based on title-lines/subtitle-lines attributes. */
+    private _applyLineClamping(): void {
+        applyRowLineClamp({
+            titleEl: this._titleEl,
+            subtitleEl: this._subtitleEl,
+            textContainerEl: this._titleEl.parentElement!,
+            getTitleLines: () => parseRowLinesAttribute(this.getAttribute('title-lines')),
+            getSubtitleLines: () => parseRowLinesAttribute(this.getAttribute('subtitle-lines')),
+        });
     }
 
     /** A stepper press — the interactive path, so it emits `notify::value`. */

package/src/elements/adw-status-page.ts

@@ -1,9 +1,10 @@
 // <adw-status-page> — A centered empty/placeholder state: a large symbolic
 // icon, a title, a description and an optional action (slotted child).
 // Attributes: icon (symbolic name, with or without -symbolic) or icon-name, the GObject
-// spelling a projected `.blp` writes; title, description.
+// spelling a projected `.blp` writes; title, description, and the boolean compact.
 // Reference: refs/adwaita-web/adwaita-web/scss/_status_page.scss
 // Reference: refs/libadwaita/src/stylesheet/widgets/_misc.scss (AdwStatusPage)
+// Reference: refs/libadwaita/doc/style-classes.md (Compact Status Page)
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web; the
 // icon node is <gtk-image>.
@@ -22,7 +23,7 @@ export class AdwStatusPage extends HTMLElement {
     private _initialized = false;
 
     static get observedAttributes() {
-        return ['icon', 'icon-name', 'title', 'description'];
+        return ['icon', 'icon-name', 'title', 'description', 'compact'];
     }
 
     connectedCallback() {
@@ -64,6 +65,13 @@ export class AdwStatusPage extends HTMLElement {
     }
 
     private _render() {
+        // `.compact` (style-classes.md "Compact Status Page") is keyed off the HOST by
+        // `_status_page.scss`, so this door writes the class itself. ADDED, never toggled:
+        // `shared-tree-builder.ts` puts a `.blp`'s `styles ["compact"]` on this same class,
+        // and a `toggle` would strip it on the first attribute change — `title`, on any page
+        // that sets one. Additive, the way `gtk_button_add_css_class` is.
+        if (this.hasAttribute('compact')) this.classList.add('compact');
+
         const icon = this.getAttribute('icon') ?? this.getAttribute('icon-name');
         // The element swaps the mask class and keeps the size class.
         this._iconEl.iconName = icon;

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

@@ -10,6 +10,14 @@
 //   - clicking the ROW toggles: `adw_switch_row_init` points the activatable-widget at the
 //     slider, so the title is part of the control, not just the handle.
 //
+// Slots: `slot="prefix"` holds a leading icon/widget, exactly as on
+// `<adw-action-row>` — libadwaita's AdwSwitchRow IS an AdwActionRow
+// (adw-switch-row.c:50), so `add_prefix` is inherited, not invented here.
+//
+// ATTRIBUTES: `title`, `subtitle`, `active`, `tooltip-text` (`Gtk.Widget:tooltip-text`),
+// and `title-lines` / `subtitle-lines` —
+// clamp either label to N lines, `0` = unlimited, the AdwActionRow pspec's sentinel
+// (`@girs/adw-1`, min 0, default 0).
 // Adapted from Adwaita Web UI Framework (https://github.com/mclellac/adwaita-web).
 // Copyright (c) 2025 csm. MIT License.
 // Modifications: Reimplemented as Web Component for @gjsify/adwaita-web;
@@ -18,6 +26,11 @@
 
 import { SwitchRowState, deriveRowLabels } from '@gjsify/adwaita-core';
 
+import { bindEmptySections } from '../empty-sections.js';
+import { applyRowTooltip } from '../row-tooltip.js';
+import { bindSlottedChildren } from '../slotted-children.js';
+import { applyRowLineClamp, parseRowLinesAttribute } from '../row-line-clamp.js';
+
 // SIDE-EFFECT import, deliberately separate from the type import below: it guarantees
 // `gtk-switch` is defined before this module's `customElements.define` can upgrade a
 // server-rendered `<adw-switch-row>` and build one. A combined `import { GtkSwitch }`
@@ -30,6 +43,9 @@ import type { GtkSwitch } from './gtk-switch.js';
 
 export class AdwSwitchRow extends HTMLElement {
     private _switchEl!: GtkSwitch;
+    private _prefixEl!: HTMLDivElement;
+    /** The label column — kept for `tooltip-text`, which the browser reads off a PART. */
+    private _textEl!: HTMLDivElement;
     private _titleEl!: HTMLSpanElement;
     private _subtitleEl!: HTMLSpanElement;
     /** The headless active flag + its notify rule (ADR 0004). */
@@ -37,7 +53,12 @@ export class AdwSwitchRow extends HTMLElement {
     private _initialized = false;
 
     static get observedAttributes() {
-        return ['title', 'subtitle', 'active'];
+        return ['title', 'subtitle', 'active', 'tooltip-text', 'title-lines', 'subtitle-lines'];
+    }
+
+    /** The start (prefix) section — append icons/widgets here imperatively. */
+    get prefixSection(): HTMLDivElement {
+        return this._prefixEl;
     }
 
     get active(): boolean {
@@ -56,17 +77,32 @@ export class AdwSwitchRow extends HTMLElement {
 
         const text = document.createElement('div');
         text.className = 'adw-row-text';
+        this._textEl = text;
         this._titleEl = document.createElement('span');
         this._titleEl.className = 'adw-row-title';
         this._subtitleEl = document.createElement('span');
         this._subtitleEl.className = 'adw-row-subtitle';
         text.append(this._titleEl, this._subtitleEl);
 
+        this._prefixEl = document.createElement('div');
+        this._prefixEl.className = 'adw-switch-row-prefix';
+
         this._switchEl = document.createElement('gtk-switch') as GtkSwitch;
         // adw-switch-row.c:159 — the slider is not a focus target; the ROW is.
         this._switchEl.unfocusable = true;
 
-        this.replaceChildren(text, this._switchEl);
+        // The prefix stays LIVE, as on every other slotted row: an icon appended with
+        // `slot="prefix"` after connect has to land where the declared one does.
+        // `src/slotted-children.ts` carries the incident.
+        bindSlottedChildren(this, [{ name: 'prefix', into: this._prefixEl }]).install(
+            this._prefixEl,
+            text,
+            this._switchEl,
+        );
+        // Same reason as the action row's: an icon appended into `prefixSection` is a
+        // childList change no attribute callback hears, so the section would stay hidden
+        // and the icon measure 0x0. AFTER the routing — it derives once synchronously.
+        bindEmptySections(this._prefixEl);
 
         this._state.setActive(this.hasAttribute('active'));
         this._switchEl.active = this._state.active;
@@ -133,6 +169,21 @@ export class AdwSwitchRow extends HTMLElement {
         this._titleEl.hidden = !titleVisible;
         this._subtitleEl.textContent = subtitle;
         this._subtitleEl.hidden = !subtitleVisible;
+        // The switch is NOT a part here: `unfocusable` and consumer-facing, and a
+        // tooltip the consumer put on it has to keep winning over the row's.
+        applyRowTooltip(this, [this._prefixEl, this._textEl]);
+        this._applyLineClamping();
+    }
+
+    /** Apply CSS line-clamping based on title-lines/subtitle-lines attributes. */
+    private _applyLineClamping(): void {
+        applyRowLineClamp({
+            titleEl: this._titleEl,
+            subtitleEl: this._subtitleEl,
+            textContainerEl: this._titleEl.parentElement!,
+            getTitleLines: () => parseRowLinesAttribute(this.getAttribute('title-lines')),
+            getSubtitleLines: () => parseRowLinesAttribute(this.getAttribute('subtitle-lines')),
+        });
     }
 }