@gjsify/adwaita-web 0.54.0 → 0.56.0

package/src/elements/adw-overlay-split-view.ts

@@ -26,6 +26,7 @@ import {
 } from '@gjsify/adwaita-core';
 
 import { bindBreakpointSetter } from '../breakpoints.js';
+import type { DispatchedSignals } from '../signals.js';
 import { bindSlottedChildren } from '../slotted-children.js';
 
 /**
@@ -80,6 +81,9 @@ function readTriStateAttr(element: Element, name: string, fallback: boolean): bo
 }
 
 export class AdwOverlaySplitView extends HTMLElement {
+    /** The GTK signals this element dispatches, which is what a `.blp` `bind` of `show-sidebar` follows. */
+    static readonly signals: DispatchedSignals = { 'notify::show-sidebar': 'notify::show-sidebar' };
+
     private _initialized = false;
     private _sidebarEl!: HTMLDivElement;
     private _contentEl!: HTMLDivElement;
@@ -97,6 +101,8 @@ export class AdwOverlaySplitView extends HTMLElement {
      * `show-sidebar` + `pin-sidebar` mean together, held to `OVERLAY_COLLAPSE_VECTORS`.
      */
     private _state = new OverlaySplitViewState();
+    /** The `show-sidebar` the last `notify::show-sidebar` (or the first read) settled on. */
+    private _notifiedShowSidebar: boolean | null = null;
     /** Re-entrancy guard for {@link _reflectShowSidebar}. */
     private _reflecting = false;
     /** The view's own width in CSS px — the size the sidebar fraction is OF. */
@@ -329,13 +335,30 @@ export class AdwOverlaySplitView extends HTMLElement {
     private _reflectShowSidebar() {
         if (this._reflecting) return;
         const wanted = this._state.showSidebar ? '' : 'false';
-        if (this.getAttribute('show-sidebar') === wanted) return;
-        this._reflecting = true;
-        try {
-            this.setAttribute('show-sidebar', wanted);
-        } finally {
-            this._reflecting = false;
+        if (this.getAttribute('show-sidebar') !== wanted) {
+            this._reflecting = true;
+            try {
+                this.setAttribute('show-sidebar', wanted);
+            } finally {
+                this._reflecting = false;
+            }
         }
+        this._notifyShowSidebar();
+    }
+
+    /**
+     * `notify::show-sidebar`, raised on the EFFECTIVE value — the state's, after an auto-hide on
+     * collapse — and only when it changed, the way GObject notifies. Every path that moves it
+     * (the attribute, the property, a breakpoint, a gesture) ends in {@link _reflectShowSidebar},
+     * so this is the one place it is raised. The first read only records the baseline: a bind
+     * reads the current value itself.
+     */
+    private _notifyShowSidebar() {
+        const shown = this._state.showSidebar;
+        const previous = this._notifiedShowSidebar;
+        this._notifiedShowSidebar = shown;
+        if (previous === null || previous === shown) return;
+        this.dispatchEvent(new CustomEvent('notify::show-sidebar', { bubbles: true, detail: { showSidebar: shown } }));
     }
 
     private _syncBreakpoint() {

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

@@ -0,0 +1,153 @@
+// <adw-preferences-row> — the row every boxed-list row derives from: a
+// `Gtk.ListBoxRow` carrying a `title` that `Adw.PreferencesDialog` searches for
+// (adw-preferences-row.c:12-23).
+//
+// FOUR PROPERTIES, AND EVERY ONE OF THEM IS ABOUT THE TITLE LABEL:
+// `title` (Pango markup unless `use-markup` is FALSE), `use-markup`, `use-underline`
+// (an embedded `_` marks a mnemonic) and `title-selectable` (the user may copy it) —
+// the property docs are at adw-preferences-row.c:118-170. Inherited from `GtkWidget`,
+// every row also takes `tooltip-text` (`src/row-tooltip.ts`).
+//
+// ONE DELIBERATE PORT DECISION, named here because C says the opposite in so many
+// words: "It doesn't present the title in any way and lets you present the preference
+// as you please" (adw-preferences-row.c:20). A browser element has no subclassing
+// mechanism, so a base row that presented NOTHING would be an empty box — and three of
+// the four properties describe a label this element would not have. It therefore
+// presents the title the way every derived row does (`<adw-action-row>` renders the same
+// `.adw-row-title` beside its subtitle), keeps `use-markup`/`use-underline` on it through
+// the shared `labelDisplayText` reduction rather than an `innerHTML` sink, and lets a
+// caller put the preference's own controls beside it through the `child` slot.
+//
+// MODIFICATION: `use-markup` DEFAULTS TRUE in C (adw-preferences-row.c:166-169) and an
+// HTML boolean attribute cannot spell a TRUE default, so the attribute is opt-IN here —
+// the arrangement `<adw-tab-view autohide>` and `<adw-navigation-page can-pop>` already
+// carry, and for the same reason. What it decides is whether a title written as
+// `<b>Dark</b>` Style shows the word `Dark` (markup reduced, C's default) or the literal
+// text; either way the string is TEXT in the DOM, never markup.
+//
+// `activatable` is `GtkListBoxRow`'s, not this class's: the group's list box drives it,
+// and the derived rows in this package (`<adw-action-row>`, `<adw-switch-row>`) are where
+// it is implemented. So it is neither observed nor listed in KNOWN_GAPS — the property
+// check reads the OWN body, and `AdwPreferencesRow` declares only the four above.
+//
+// A11Y: `role="listitem"`. The row IS a `GtkListBoxRow` inside the group's list, and
+// `<adw-preferences-group>` sets `role="group"` on itself for exactly this reason.
+//
+// KNOWN_GAPS: none — all four scalar properties are observed.
+//
+// Reference: refs/libadwaita/src/adw-preferences-row.c (the four pspecs and their
+//   defaults, `adw_preferences_row_set_title`'s NULL → "" normalisation)
+// Reference: refs/libadwaita/src/adw-preferences-dialog.c (row_has_title, make_comparable)
+// Reference: refs/libadwaita/src/stylesheet/widgets/_lists.scss (`row`, `list > row`)
+// Copyright (c) 2019 Purism SPC / GNOME contributors (libadwaita). LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+import { labelDisplayText, stringIsNotEmpty } from '@gjsify/adwaita-core';
+
+import { applyRowTooltip } from '../row-tooltip.js';
+import { bindEmptySections } from '../empty-sections.js';
+import { bindSlottedChildren } from '../slotted-children.js';
+
+export class AdwPreferencesRow extends HTMLElement {
+    private _titleEl!: HTMLSpanElement;
+    private _contentEl!: HTMLDivElement;
+    private _initialized = false;
+
+    static get observedAttributes() {
+        return ['title', 'title-selectable', 'use-markup', 'use-underline', 'tooltip-text'];
+    }
+
+    /** `Adw.PreferencesRow:title` — Pango markup unless {@link useMarkup} is false. */
+    get title(): string {
+        // `adw_preferences_row_set_title` normalises NULL to the empty string
+        // (adw-preferences-row.c:235), and an absent attribute is exactly that NULL.
+        return this.getAttribute('title') ?? '';
+    }
+
+    set title(value: string) {
+        if (value === '') this.removeAttribute('title');
+        else this.setAttribute('title', value);
+    }
+
+    /** `Adw.PreferencesRow:title-selectable` — the user may copy the title. Default false. */
+    get titleSelectable(): boolean {
+        return this.hasAttribute('title-selectable');
+    }
+
+    set titleSelectable(value: boolean) {
+        this.toggleAttribute('title-selectable', value);
+    }
+
+    /** `Adw.PreferencesRow:use-markup` — the title is Pango markup, reduced to its text. */
+    get useMarkup(): boolean {
+        return this.hasAttribute('use-markup');
+    }
+
+    set useMarkup(value: boolean) {
+        this.toggleAttribute('use-markup', value);
+    }
+
+    /** `Adw.PreferencesRow:use-underline` — `_` marks a mnemonic. Default false. */
+    get useUnderline(): boolean {
+        return this.hasAttribute('use-underline');
+    }
+
+    set useUnderline(value: boolean) {
+        this.toggleAttribute('use-underline', value);
+    }
+
+    /** `Adw.PreferencesRow:child` (inherited from `Gtk.ListBoxRow`) — the row's content. */
+    get child(): Element | null {
+        return this._contentEl?.firstElementChild ?? null;
+    }
+
+    set child(value: Element | null) {
+        this._contentEl?.replaceChildren(...(value === null ? [] : [value]));
+    }
+
+    connectedCallback() {
+        if (this._initialized) return;
+        this._initialized = true;
+
+        this._titleEl = document.createElement('span');
+        this._titleEl.className = 'adw-row-title';
+
+        this._contentEl = document.createElement('div');
+        this._contentEl.className = 'adw-preferences-row-content';
+
+        // `child` is a widget property, so a `.blp`'s `child: …` authors `slot="child"`
+        // and an unnamed child is the same placement (GtkListBoxRow's own buildable).
+        bindSlottedChildren(this, [{ name: 'child', into: this._contentEl }]).install(this._titleEl, this._contentEl);
+        bindEmptySections(this._contentEl);
+
+        this.setAttribute('role', 'listitem');
+        this._render();
+    }
+
+    attributeChangedCallback(name: string, _old: string | null, value: string | null) {
+        if (!this._initialized) return;
+        this._render();
+        this.dispatchEvent(new CustomEvent(`notify::${name}`, { bubbles: true, detail: { [name]: value } }));
+    }
+
+    /**
+     * The title label and the copy permission.
+     *
+     * `labelDisplayText` reduces Pango markup to its text and strips the mnemonic marker
+     * in C's order (markup first, `_` second) — the same reduction `<gtk-label>` uses, so
+     * a title written once reads the same in both.
+     */
+    private _render(): void {
+        const text = labelDisplayText(this.title, this.useMarkup, this.useUnderline);
+        this._titleEl.textContent = text;
+        // `string_is_not_empty`, the rule every row's label binding uses: a row with no
+        // title shows no line, and `row_has_title` keeps it out of the search too.
+        this._titleEl.hidden = !stringIsNotEmpty(text);
+        // `Gtk.Label:selectable` puts a label in GTK_SELECTION_TEXT; the DOM's spelling
+        // of "this text may be copied" is `user-select: text`.
+        this._titleEl.style.userSelect = this.titleSelectable ? 'text' : '';
+        applyRowTooltip(this, [this._titleEl, this._contentEl]);
+    }
+}
+
+customElements.define('adw-preferences-row', AdwPreferencesRow);

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

@@ -0,0 +1,52 @@
+// <adw-shortcuts-dialog> — the window that shows an application's keyboard
+// shortcuts, as `AdwShortcutsDialog` since libadwaita 1.8.
+//
+// IT IS THE GENERIC DIALOG plus a content model: the class is `final` and its parent
+// is `Adw.Dialog` (Adw-1.gir), and upstream it declares no property and one method —
+// `add(section)`. So this element EXTENDS <adw-dialog> and inherits the whole chrome
+// (the scrim, the flat header with its close button, the focus trap, the bottom-sheet
+// switch), and the only thing it adds is the sections.
+//
+// A browser document cannot call `add()`, so the sections are CHILDREN: one
+// `<adw-shortcuts-section>` per group, each holding `<adw-shortcuts-item>` rows. That
+// is `AdwShortcutsDialog`'s GtkBuildable form — the GIR documents "add it as a child
+// when using UI files" — and it is the same mark-up-only-objection `GtkBuildable`
+// answers for `<adw-sidebar-item>` and `<adw-toggle>`.
+//
+// The title is the DIALOG's, so it inherits from the base and is not re-observed.
+// libadwaita spells the dialog's own class list `dialog.shortcuts`, and the stylesheet
+// gives the rows their padding and the shortcut labels their keycaps
+// (_shortcuts-dialog.scss:16-58) — the labels themselves are `<adw-shortcut-label>`,
+// which already ports those rules.
+//
+// Reference: refs/libadwaita/src/adw-shortcuts-dialog.c (a final Adw.Dialog with `add`)
+// Reference: refs/libadwaita/src/stylesheet/widgets/_shortcuts-dialog.scss
+// Copyright (c) 2025 GNOME Foundation Inc. (libadwaita). LGPLv2.1+
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+import { AdwDialog } from './adw-dialog.js';
+
+export class AdwShortcutsDialog extends AdwDialog {
+    /**
+     * The sections in this dialog, in document order (AdwShortcutsDialog:add, in markup).
+     *
+     * READ OFF THE CONTENT AREA rather than off a wrapper this class builds, because the
+     * base routes every child there through its own LIVE `bindSlottedChildren` and a
+     * wrapper of our own would be a second destination the routing knows nothing about:
+     * a section appended after connect would land beside the wrapper, not inside it.
+     */
+    get sections(): readonly HTMLElement[] {
+        return [...this.contentArea.children].filter((el) => el.localName === 'adw-shortcuts-section') as HTMLElement[];
+    }
+
+    connectedCallback() {
+        // FIRST: the base builds its subtree here, and `contentArea` is one of the things
+        // it builds — this class reads it on the line after.
+        super.connectedCallback();
+        // Once, and a re-attach must not throw the sections away: the base's
+        // `_initialized` guard is what makes its subtree survive the move.
+        this.classList.add('adw-shortcuts-dialog');
+    }
+}
+
+customElements.define('adw-shortcuts-dialog', AdwShortcutsDialog);

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);