@gjsify/adwaita-web 0.53.0 → 0.55.0

package/src/elements/adw-shortcuts-item.ts

@@ -0,0 +1,171 @@
+// <adw-shortcuts-item> — one shortcut row: a title, an optional subtitle and an
+// accelerator, drawn as keycaps. The browser counterpart of `AdwShortcutsItem`,
+// which upstream is a plain `GObject` (adw-shortcuts-item.c:39) holding four
+// strings and a text direction, and is a row rather than a widget — hence a tag
+// here, the same shape `<adw-sidebar-item>` and `<adw-toggle>` are.
+//
+// THE ACCELERATOR IS `<adw-shortcut-label>`'s to draw. The C validates the string
+// against `AdwShortcutLabel`'s own grammar (adw-shortcuts-item.c:19-24) and this
+// element hands the very same attribute to the very same element, so the parse is
+// core's `parseShortcutLabel` once rather than a second grammar that drifts from it.
+//
+// `action-name` is the OTHER half and the port has nothing to resolve it with: an
+// accelerator for an action comes from `Gtk.Application.set_accels_for_action`, and a
+// document has no application to ask. So it is kept as an attribute — a reader can
+// still see which action a row stands for — and the accelerator beside it is what is
+// DRAWN. That is the fallback the class itself documents ("If both are specified, the
+// accelerator will be used if the action couldn't be found", adw-shortcuts-item.c:19-23).
+//
+// `direction` is honoured the way the class means it: a row for a direction the
+// document is not in is hidden, which is how one dialog lists both an LTR and an RTL
+// accelerator for the same action (adw-shortcuts-item.c:25-28).
+//
+// Attributes:
+//   title        (AdwShortcutsItem:title — the row's name)
+//   subtitle     (AdwShortcutsItem:subtitle — the line under it, drawn dimmed and
+//     caption-sized, the `.title-box > .subtitle` rule at _shortcuts-dialog.scss:23-26)
+//   accelerator  (AdwShortcutsItem:accelerator — `<Control>C`, `<Shift>A Home`; the
+//     `<adw-shortcut-label>` grammar)
+//   action-name  (AdwShortcutsItem:action-name — resolved on GTK, kept here)
+//   direction    (AdwShortcutsItem:direction — `ltr` | `rtl` | `none`; a row for the
+//     other direction is hidden)
+//
+// Properties: `itemType` — whether an accelerator was given, `hasAccelerator`.
+//
+// Reference: refs/libadwaita/src/adw-shortcuts-item.c
+// Reference: refs/libadwaita/src/stylesheet/widgets/_shortcuts-dialog.scss:16-27
+// Copyright (c) 2025 GNOME Foundation Inc. (libadwaita). LGPLv2.1+
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+/**
+ * `AdwShortcutsItem:direction` is a `GtkTextDirection`, so it carries `none` beside the
+ * two directions — and `none` is the default, meaning "show this row either way".
+ *
+ * NOT `AdwTextDirection` from core: that one is the split views' pair (`'ltr' | 'rtl'`,
+ * split-view.ts:41), which cannot hold the value the C defaults this property to.
+ */
+export type AdwShortcutsItemDirection = 'ltr' | 'rtl' | 'none';
+
+const DIRECTIONS: readonly AdwShortcutsItemDirection[] = ['ltr', 'rtl', 'none'];
+
+export class AdwShortcutsItem extends HTMLElement {
+    private _initialized = false;
+    private _titleEl!: HTMLSpanElement;
+    private _subtitleEl!: HTMLSpanElement;
+    private _labelEl!: HTMLElement;
+
+    static get observedAttributes() {
+        return ['title', 'subtitle', 'accelerator', 'action-name', 'direction'];
+    }
+
+    /** The row's title (AdwShortcutsItem:title). */
+    get title(): string {
+        return this.getAttribute('title') ?? '';
+    }
+
+    set title(value: string) {
+        this.setAttribute('title', value);
+    }
+
+    /** The row's subtitle (AdwShortcutsItem:subtitle). */
+    get subtitle(): string {
+        return this.getAttribute('subtitle') ?? '';
+    }
+
+    set subtitle(value: string) {
+        this.setAttribute('subtitle', value);
+    }
+
+    /** The accelerator, in `<adw-shortcut-label>`'s grammar (AdwShortcutsItem:accelerator). */
+    get accelerator(): string {
+        return this.getAttribute('accelerator') ?? '';
+    }
+
+    set accelerator(value: string) {
+        if (value) this.setAttribute('accelerator', value);
+        else this.removeAttribute('accelerator');
+    }
+
+    /** The action this row stands for; resolved by a GtkApplication on GTK. */
+    get actionName(): string {
+        return this.getAttribute('action-name') ?? '';
+    }
+
+    set actionName(value: string) {
+        if (value) this.setAttribute('action-name', value);
+        else this.removeAttribute('action-name');
+    }
+
+    /** The text direction this row belongs to (AdwShortcutsItem:direction). */
+    get direction(): AdwShortcutsItemDirection {
+        const value = this.getAttribute('direction') as AdwShortcutsItemDirection | null;
+        return value && DIRECTIONS.includes(value) ? value : 'none';
+    }
+
+    set direction(value: AdwShortcutsItemDirection) {
+        this.setAttribute('direction', value);
+    }
+
+    /** Whether a row carries an accelerator or stands for an action alone. */
+    get hasAccelerator(): boolean {
+        return this.accelerator.length > 0;
+    }
+
+    connectedCallback() {
+        if (this._initialized) return;
+        this._initialized = true;
+
+        // `GTK_ACCESSIBLE_ROLE_LIST_ITEM` in spirit: a row in a list of shortcuts, and
+        // the accelerator beside it is already `role="img"` with its own name.
+        this.setAttribute('role', 'listitem');
+
+        this._titleEl = document.createElement('span');
+        this._titleEl.className = 'adw-shortcuts-item-title';
+
+        this._subtitleEl = document.createElement('span');
+        this._subtitleEl.className = 'adw-shortcuts-item-subtitle';
+
+        // The keycaps: the one element that owns the accelerator grammar.
+        this._labelEl = document.createElement('adw-shortcut-label');
+        this._labelEl.className = 'adw-shortcuts-item-label';
+
+        this.replaceChildren(this._titleEl, this._subtitleEl, this._labelEl);
+        this._render();
+    }
+
+    attributeChangedCallback(name: string) {
+        if (!this._initialized) return;
+        if (name === 'direction' || name === 'accelerator' || name === 'action-name') this._render();
+        else if (name === 'title') this._titleEl.textContent = this.title;
+        else if (name === 'subtitle') this._renderSubtitle();
+    }
+
+    private _render(): void {
+        this._titleEl.textContent = this.title;
+        this._renderSubtitle();
+        this._labelEl.setAttribute('accelerator', this.accelerator);
+
+        // A row that stands for an action alone has nothing to draw on the trailing
+        // side — `AdwShortcutLabel` shows its `disabled-text` placeholder for an empty
+        // accelerator, which is the wrong picture for a row that never had one.
+        this._labelEl.hidden = !this.hasAccelerator;
+
+        // The class's own rule (adw-shortcuts-item.c:25-28): a direction-specific row
+        // is shown only in that direction, so one dialog can carry both.
+        const direction = this.direction;
+        if (direction !== 'none') {
+            const ours = getComputedStyle(this).direction;
+            this.hidden = ours !== direction;
+        } else {
+            this.hidden = false;
+        }
+    }
+
+    private _renderSubtitle(): void {
+        const subtitle = this.subtitle;
+        this._subtitleEl.textContent = subtitle;
+        this._subtitleEl.hidden = subtitle.length === 0;
+    }
+}
+
+customElements.define('adw-shortcuts-item', AdwShortcutsItem);

package/src/elements/adw-shortcuts-section.ts

@@ -0,0 +1,86 @@
+// <adw-shortcuts-section> — one titled group of shortcuts inside an
+// <adw-shortcuts-dialog>: the browser counterpart of `AdwShortcutsSection`, which
+// upstream is a plain `GObject` (`G_DEFINE_FINAL_TYPE_WITH_CODE (…, G_TYPE_OBJECT)`
+// in adw-shortcuts-section.c:44) implementing `GtkBuildable` and `Gio.ListModel`.
+// It has no look of its own — libadwaita draws it as a preferences GROUP inside the
+// dialog's page, and every row is a `AdwShortcutsItem` (`.shortcut-row`, styled at
+// _shortcuts-dialog.scss:16-27).
+//
+// A tag anyway, and that is the same shape `<adw-sidebar-item>` and `<adw-toggle>`
+// are: a GObject that is not a GtkWidget has no tag in a table of concrete widgets,
+// and the mark-up form of `GtkBuildable`'s add-child is the only way a document can
+// declare one. `scripts/check-vocabulary-alignment.mjs` records that in
+// `WEB_ELEMENT_ALIGNMENT`.
+//
+// Children are `<adw-shortcuts-item>` elements, and they stay LIVE: a shortcut added
+// after connect lands in the section (`bindSlottedChildren`).
+//
+// Attributes:
+//   title (AdwShortcutsSection:title — the heading; an untitled section is the
+//     "subdivide a section into groups" case the class documents)
+//
+// Properties: `items` (the section's shortcuts, in document order).
+//
+// Reference: refs/libadwaita/src/adw-shortcuts-section.c
+// Reference: refs/libadwaita/src/stylesheet/widgets/_shortcuts-dialog.scss:1-14
+// Copyright (c) 2025 GNOME Foundation Inc. (libadwaita). LGPLv2.1+
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+import { bindSlottedChildren } from '../slotted-children.js';
+
+export class AdwShortcutsSection extends HTMLElement {
+    private _initialized = false;
+    private _bodyEl!: HTMLDivElement;
+    private _titleEl!: HTMLElement;
+
+    static get observedAttributes() {
+        return ['title'];
+    }
+
+    /** The section title (AdwShortcutsSection:title). */
+    get title(): string {
+        return this.getAttribute('title') ?? '';
+    }
+
+    set title(value: string) {
+        this.setAttribute('title', value);
+    }
+
+    /** The shortcuts in this section, in document order (AdwShortcutsSection:n-items' list). */
+    get items(): readonly HTMLElement[] {
+        return [...this._bodyEl.children] as HTMLElement[];
+    }
+
+    connectedCallback() {
+        if (this._initialized) return;
+        this._initialized = true;
+
+        this._titleEl = document.createElement('div');
+        this._titleEl.className = 'adw-shortcuts-section-title';
+
+        this._bodyEl = document.createElement('div');
+        this._bodyEl.className = 'adw-shortcuts-section-body';
+
+        // A `Gio.ListModel` the section can also be read as, so the row list is a
+        // container with a name rather than bare children.
+        this.setAttribute('role', 'group');
+        bindSlottedChildren(this, [{ into: this._bodyEl }]).install(this._titleEl, this._bodyEl);
+
+        this._render();
+    }
+
+    attributeChangedCallback(name: string) {
+        if (!this._initialized) return;
+        if (name === 'title') this._render();
+    }
+
+    private _render(): void {
+        const title = this.title;
+        // An untitled section is a legal thing to write: the class documents it as the
+        // way to subdivide a section into groups, and libadwaita draws no heading for it.
+        this._titleEl.textContent = title;
+        this._titleEl.hidden = title.length === 0;
+    }
+}
+
+customElements.define('adw-shortcuts-section', AdwShortcutsSection);

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,
@@ -69,7 +75,7 @@ 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', 'needs-attention', 'badge-number'];
     }
 
     /**
@@ -104,6 +110,8 @@ export class AdwSidebarItem extends HTMLElement {
         else if (name === 'icon-name') binding.spec.iconName = value;
         else if (name === 'disabled') binding.spec.enabled = newValue === null;
         else if (name === 'hidden') binding.spec.visible = newValue === null;
+        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();
     }
@@ -257,6 +265,8 @@ export class AdwSidebar extends HTMLElement {
                     iconName: itemEl.getAttribute('icon-name') ?? '',
                     enabled: !itemEl.hasAttribute('disabled'),
                     visible: !itemEl.hasAttribute('hidden'),
+                    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 +401,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 +416,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-switch-row.ts

@@ -10,6 +10,10 @@
 //   - 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.
+//
 // 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 +22,9 @@
 
 import { SwitchRowState, deriveRowLabels } from '@gjsify/adwaita-core';
 
+import { bindEmptySections } from '../empty-sections.js';
+import { bindSlottedChildren } from '../slotted-children.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 +37,7 @@ import type { GtkSwitch } from './gtk-switch.js';
 
 export class AdwSwitchRow extends HTMLElement {
     private _switchEl!: GtkSwitch;
+    private _prefixEl!: HTMLDivElement;
     private _titleEl!: HTMLSpanElement;
     private _subtitleEl!: HTMLSpanElement;
     /** The headless active flag + its notify rule (ADR 0004). */
@@ -40,6 +48,11 @@ export class AdwSwitchRow extends HTMLElement {
         return ['title', 'subtitle', 'active'];
     }
 
+    /** The start (prefix) section — append icons/widgets here imperatively. */
+    get prefixSection(): HTMLDivElement {
+        return this._prefixEl;
+    }
+
     get active(): boolean {
         return this._initialized ? this._state.active : this.hasAttribute('active');
     }
@@ -62,11 +75,25 @@ export class AdwSwitchRow extends HTMLElement {
         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;