@gjsify/adwaita-web 0.53.0 → 0.55.0

package/src/elements/gtk-toggle-button.ts

@@ -0,0 +1,239 @@
+// <gtk-toggle-button> — a button that stays pressed. `Gtk.ToggleButton` IS a `Gtk.Button`
+// with two more properties, `active` and `group`, so this element extends `<gtk-button>`
+// and inherits its label, icon, child and style-class attributes unchanged; only the
+// state and the mutual exclusion are new.
+//
+// `active` is the ATTRIBUTE, as it is on `<gtk-switch>` — `toggleAttribute` is
+// idempotent, so "notify only on a real change" needs no guard and no core state class
+// (ADR 0004: trivial behaviour gets none). A click, Space or Enter on the inner button
+// flips it. `toggled` (GtkToggleButton's own signal) and `notify::active` (CustomEvent,
+// bubbles, detail `{ active }`) fire on EVERY change, programmatic included, the way
+// GObject notifies.
+//
+// `group` IS `gtk_toggle_button_set_group` — the doubly-linked list of
+// `group_next`/`group_prev` (gtktogglebutton.c:121-122, 511-556), transcribed rather than
+// approximated, because THREE of its rules are visible and none of them is "only one can
+// be active":
+//
+//   · Activating a member walks `group_prev` to the FIRST of the group and deactivates
+//     every member from there along `group_next`, then activates this one — the target is
+//     deactivated even when this button was not in that group yet (:424-437).
+//   · An ACTIVE member that has at least one link cannot be clicked off (:211-212), so a
+//     group never reaches a state with nothing pressed. `b.set_group (a)` makes B the
+//     member with the link, so it is B that stops being clickable-off — not A, and this
+//     is the rule a reader gets wrong.
+//   · Setting the group to the button ITSELF is refused (`g_return_if_fail
+//     (toggle_button != group)`, :518) and a change that would put the button directly
+//     before the same target again is a no-op (:539-540). Both are what keep the list
+//     acyclic; a cycle is undefined behaviour upstream (:503) and is left undefined here
+//     rather than detected.
+//
+// The property takes the other BUTTON, like `set_group`; the `group` ATTRIBUTE names it
+// by `id`, which is the only spelling markup has for a widget reference, and it resolves
+// through `document.getElementById`. It needs an `id` on the partner for that, so the
+// property is the door that always works and the attribute the declarative one.
+//
+// `dispose` unlinks a button from its group (gtktogglebutton.c:225). The DOM has no
+// terminal moment for an element that is merely re-parented, so nothing is unlinked on
+// `disconnectedCallback`: the links are between the two buttons, and a row that moves
+// keeps its group.
+//
+// The inner button wears libadwaita's `:checked` as a `.checked` class, and `aria-pressed`
+// carries the same state for assistive technology.
+//
+// Reference: refs/gtk/gtk/gtktogglebutton.c (active, group, the clicked handler)
+// Reference: refs/libadwaita/src/stylesheet/widgets/_buttons.scss (`:checked`)
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+import type { DispatchedSignals } from '../signals.js';
+import { GtkButton } from './gtk-button.js';
+
+/**
+ * How far {@link GtkToggleButton._groupFirst} walks before it gives up. A group of real
+ * buttons is two or three long; the number only bounds what a cycle can cost.
+ */
+const GROUP_WALK_LIMIT = 1024;
+
+export class GtkToggleButton extends GtkButton {
+    static override readonly signals: DispatchedSignals = {
+        ...GtkButton.signals,
+        toggled: 'toggled',
+        'notify::active': 'notify::active',
+    };
+
+    private _wired = false;
+    /** The other end of the group link, both halves of `GtkToggleButtonPrivate`. */
+    private _groupNext: GtkToggleButton | null = null;
+    private _groupPrev: GtkToggleButton | null = null;
+    /** Guards the `group` property ↔ attribute loop, as `gtk-popover` guards its `open`. */
+    private _reflectingGroup = false;
+
+    static get observedAttributes() {
+        return [...GtkButton.observedAttributes, 'active', 'group'];
+    }
+
+    /** Whether the button is pressed in. */
+    get active(): boolean {
+        return this.hasAttribute('active');
+    }
+
+    set active(value: boolean) {
+        const next = !!value;
+        if (this.active === next) return;
+        // Before the attribute moves, so a `toggled` listener on the member being
+        // released reads this one as still released — `gtk_toggle_button_set_active`
+        // clears the group first and sets `priv->active` after (:424-439).
+        if (next && this._grouped) this._clearGroup();
+        this.toggleAttribute('active', next);
+    }
+
+    /**
+     * `Gtk.ToggleButton:group` — the button this one joins, or `null` to leave the group.
+     *
+     * `G_PARAM_WRITABLE` upstream (:310-313), so there is deliberately NO getter: the
+     * member's own links are the state, and reading them back is not what GTK offers.
+     */
+    set group(value: GtkToggleButton | null) {
+        this._reflectingGroup = true;
+        // The partner needs an `id` for the attribute to name it; without one the links
+        // below still stand, and the attribute stays absent rather than naming nothing.
+        if (value === null || value.id === '') this.removeAttribute('group');
+        else this.setAttribute('group', value.id);
+        this._reflectingGroup = false;
+        this._setGroup(value);
+    }
+
+    /** Whether this button has at least one group link — `group_prev || group_next`. */
+    private get _grouped(): boolean {
+        return this._groupNext !== null || this._groupPrev !== null;
+    }
+
+    connectedCallback() {
+        super.connectedCallback();
+        if (this._wired) return;
+        this._wired = true;
+        // A disabled native button never emits `click`, so there is no guard to write here.
+        this.button.addEventListener('click', () => {
+            // `gtk_toggle_button_clicked` refuses to release an active member that has a
+            // link, so a group always keeps exactly one button pressed.
+            if (this.active && this._grouped) return;
+            this.active = !this.active;
+        });
+        // A `group` written in server-rendered markup was seen by `attributeChangedCallback`
+        // before this element was connected — and it may name a button that is not in the
+        // DOM yet. Linking once the tree is whole is the only moment both ends exist.
+        if (this.hasAttribute('group')) {
+            this._setGroup(resolveGroupTarget(this.getAttribute('group'), this));
+        }
+    }
+
+    // Optional because `GtkButton`'s own callback declares no parameter, and an override
+    // may not demand one the base signature does not pass.
+    attributeChangedCallback(name?: string) {
+        if (name === 'group' && !this._reflectingGroup && this.isConnected) {
+            this._setGroup(resolveGroupTarget(this.getAttribute('group'), this));
+        }
+        super.attributeChangedCallback();
+        if (name !== 'active' || !this.isConnected) return;
+        // The setter already cleared the group; this arm is the DECLARATIVE door, where
+        // the attribute moved without going through it.
+        if (this.active && this._grouped) this._clearGroup();
+        this.dispatchEvent(new CustomEvent('toggled', { bubbles: true }));
+        this.dispatchEvent(new CustomEvent('notify::active', { bubbles: true, detail: { active: this.active } }));
+    }
+
+    /**
+     * `gtk_toggle_button_set_group` — insert this button DIRECTLY BEFORE `group`, or
+     * unlink it when `group` is null. The three arms are the C's, in order.
+     */
+    private _setGroup(group: GtkToggleButton | null): void {
+        // `g_return_if_fail (toggle_button != group)`: a critical, and the list stays as it
+        // was. `console.error` is the browser's channel for "this is wrong, the page
+        // continues"; throwing from an attribute callback is not deliverable to the author.
+        if (group === this) {
+            console.error('<gtk-toggle-button> cannot be its own group; the group is unchanged.');
+            return;
+        }
+        if (group === null) {
+            if (this._groupPrev) this._groupPrev._groupNext = this._groupNext;
+            if (this._groupNext) this._groupNext._groupPrev = this._groupPrev;
+            this._groupNext = null;
+            this._groupPrev = null;
+        } else {
+            // Already directly before it — the one assignment that changes nothing, and
+            // the reason setting the same group twice notifies once.
+            if (this._groupNext === group) return;
+            // NOTE: no unlink from a previous group first, because the C has none
+            // (:542-554). `a.group = b; a.group = c;` leaves `b` linked to `a`, which is
+            // upstream's behaviour and is ported rather than repaired: a list that
+            // silently dropped the old link would make the two renderers disagree about
+            // what the property does.
+            this._groupPrev = null;
+            if (group._groupPrev) {
+                const previous = group._groupPrev;
+                previous._groupNext = this;
+                this._groupPrev = previous;
+            }
+            group._groupPrev = this;
+            this._groupNext = group;
+        }
+        this.dispatchEvent(new CustomEvent('notify::group', { bubbles: true }));
+    }
+
+    /**
+     * Release every OTHER member of the group — `get_group_first()` walked backwards,
+     * then the chain forwards, skipping this one (:426-434).
+     */
+    private _clearGroup(): void {
+        const first = this._groupFirst();
+        for (let iter: GtkToggleButton | null = first; iter !== null; iter = iter._groupNext) {
+            if (iter !== this) iter.active = false;
+        }
+    }
+
+    /**
+     * `get_group_first` (:242-262) — the walk backwards along `group_prev`.
+     *
+     * Written as recursion rather than a loop accumulator so no local ever holds `this`,
+     * which the walk does not need: the C's `g_assert (group_first)` is its proof that the
+     * walk terminates on a member, and the same proof is the `depth` guard here.
+     */
+    private _groupFirst(depth = 0): GtkToggleButton {
+        const previous = this._groupPrev;
+        // A CYCLE is undefined behaviour upstream (:503, "setting up groups in a cycle
+        // leads to undefined behavior") and is left that way — but a cycle must not spin
+        // the page, so the walk stops rather than hanging.
+        if (previous === null || depth > GROUP_WALK_LIMIT) return this;
+        return previous._groupFirst(depth + 1);
+    }
+
+    protected override decorate(button: HTMLButtonElement): void {
+        button.classList.toggle('checked', this.active);
+        button.setAttribute('aria-pressed', String(this.active));
+    }
+}
+
+customElements.define('gtk-toggle-button', GtkToggleButton);
+
+/**
+ * The `group` attribute's value: the partner's id, resolved. A name that is not a
+ * toggle button is refused the way `set_group`'s `Gtk.IS_TOGGLE_BUTTON` precondition is,
+ * because linking to a non-toggle would break every walk in {@link _clearGroup}.
+ */
+function resolveGroupTarget(id: string | null, from: GtkToggleButton): GtkToggleButton | null {
+    if (id === null || id === '') return null;
+    const target = document.getElementById(id);
+    if (target === null) {
+        console.error(`<gtk-toggle-button group="${id}"> names no element; the group is unchanged.`);
+        return null;
+    }
+    // The partner can sit LATER in the document than this button and so not be upgraded
+    // yet — `document.getElementById` finds the element without running its constructor.
+    if (!(target instanceof GtkToggleButton)) customElements.upgrade(target);
+    if (!(target instanceof GtkToggleButton) || target === from) {
+        console.error(`<gtk-toggle-button group="${id}"> names no other toggle button; the group is unchanged.`);
+        return null;
+    }
+    return target;
+}

package/src/elements/gtk-tree-expander.ts

@@ -0,0 +1,243 @@
+// <gtk-tree-expander> — the indent + disclosure arrow a tree row wears in front of its
+// contents, the web counterpart of `Gtk.TreeExpander`.
+//
+// THE `Gtk.TreeListRow` IS THREE NUMBERS HERE (ADR 0089). Upstream the expander WATCHES a
+// row object a `GtkTreeListModel` produced from a create-model callback — a function from
+// an item to its children, called lazily, with the parent chain held by the model.
+// Porting the object would mean porting that model, which is the sorting/filtering/
+// virtualisation half ADR 0046 § 7 refused for the same reason. What the expander
+// actually READS off the row is its depth, whether it can expand and whether it is
+// expanded, so those three are the attributes — `depth`, `expandable`, `expanded` — and
+// `list-row` has no attribute at all.
+//
+// WHAT THAT COSTS, stated rather than absorbed: upstream an expander exists BEFORE a row
+// is assigned, and `gtk_tree_expander_update_for_list_row` has a whole branch for it that
+// unparents every ornament. Here the row IS the attributes, so an expander carrying none
+// of them is a root leaf — which is the common authored case — and there is no rowless
+// state for that branch to be. `TREE_EXPANDER_LAYOUT_VECTORS` carries the row anyway,
+// because the core function still answers it, and the element's own suite says which row
+// it therefore cannot drive.
+//
+// THE NODE ARITHMETIC IS CORE'S (ADR 0004). `treeExpanderLayout` is
+// `gtk_tree_expander_update_for_list_row` (gtktreeexpander.c:166-265), including the part
+// that is easy to get wrong: with no expander drawn, `indent-for-icon` adds ONE to the
+// depth so a leaf lines up with its expandable siblings' content, and the accessible
+// level is computed AFTER that increment. `treeExpanderAction` is the shortcut table from
+// the same file.
+//
+// THE CHILD STAYS IN THE LIGHT DOM, so a `.blp`'s `child` property, a slot assignment and
+// plain markup are all the same thing: the indents and the expander are INSERTED BEFORE
+// it, exactly as `gtk_widget_insert_before (…, self->child)` does, and are removed again
+// when the row says they are not needed.
+//
+// Attributes:
+//   hide-expander     — boolean; `Gtk.TreeExpander:hide-expander`.
+//   indent-for-depth  — the GIR default is TRUE, so this is the OFF switch: the attribute
+//                       is read as `indent-for-depth="false"`, not as a bare flag.
+//   indent-for-icon   — the same, and the same default.
+//   depth             — the row's depth, 0 at the root (`gtk_tree_list_row_get_depth`).
+//   expandable        — boolean; `gtk_tree_list_row_is_expandable`.
+//   expanded          — boolean; `Gtk.TreeListRow:expanded`.
+// Properties: hideExpander, indentForDepth, indentForIcon, depth, expandable, expanded.
+// Events: `notify::expanded` (CustomEvent, bubbles, detail = { expanded }) — every change,
+//   programmatic included, which is what `Gtk.TreeListRow` notifies.
+// A11Y: `role="button"` with `aria-expanded` and `aria-level`, which is what GTK has used
+//   since 4.12 (gtktreeexpander.c:246-266); before that it was `group`.
+//
+// Reference: refs/gtk/gtk/gtktreeexpander.c:166-265 (the node arithmetic)
+// Reference: refs/gtk/gtk/gtktreeexpander.c:654-691 (the shortcuts), :709-734 (drag-hover)
+// Reference: refs/libadwaita/src/stylesheet/widgets/_expanders.scss:1-10 (the expander node)
+// Reference: refs/libadwaita/src/stylesheet/widgets/_column-view.scss:128-130 (border-spacing)
+// Copyright (c) GNOME contributors (GTK/libadwaita). LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+import {
+    treeExpanderAction,
+    treeExpanderExpanded,
+    treeExpanderLayout,
+    type AdwTreeExpanderLayout,
+} from '@gjsify/adwaita-core';
+
+import { createGtkImage } from './gtk-image.js';
+
+/** `TIMEOUT_EXPAND` — how long a drag hovers before the row opens (gtktreeexpander.c:717). */
+const TIMEOUT_EXPAND = 500;
+
+export class GtkTreeExpander extends HTMLElement {
+    private _ornaments: HTMLElement[] = [];
+    private _expandTimer: ReturnType<typeof setTimeout> | null = null;
+    private _initialized = false;
+
+    static get observedAttributes() {
+        return ['hide-expander', 'indent-for-depth', 'indent-for-icon', 'depth', 'expandable', 'expanded'];
+    }
+
+    get hideExpander(): boolean {
+        return this.hasAttribute('hide-expander');
+    }
+
+    set hideExpander(value: boolean) {
+        this.toggleAttribute('hide-expander', !!value);
+    }
+
+    /** Default TRUE (gtktreeexpander.c:750), so only the literal `false` turns it off. */
+    get indentForDepth(): boolean {
+        return this.getAttribute('indent-for-depth') !== 'false';
+    }
+
+    set indentForDepth(value: boolean) {
+        this.setAttribute('indent-for-depth', String(!!value));
+    }
+
+    /** Default TRUE (gtktreeexpander.c:749), read the same way as `indent-for-depth`. */
+    get indentForIcon(): boolean {
+        return this.getAttribute('indent-for-icon') !== 'false';
+    }
+
+    set indentForIcon(value: boolean) {
+        this.setAttribute('indent-for-icon', String(!!value));
+    }
+
+    /** The row's depth — 0 at the root, as `gtk_tree_list_row_get_depth` reports it. */
+    get depth(): number {
+        const parsed = Number.parseInt(this.getAttribute('depth') ?? '', 10);
+        return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+    }
+
+    set depth(value: number) {
+        this.setAttribute('depth', String(value));
+    }
+
+    get expandable(): boolean {
+        return this.hasAttribute('expandable');
+    }
+
+    set expandable(value: boolean) {
+        this.toggleAttribute('expandable', !!value);
+    }
+
+    get expanded(): boolean {
+        return this.hasAttribute('expanded');
+    }
+
+    set expanded(value: boolean) {
+        this.toggleAttribute('expanded', !!value);
+    }
+
+    /** What this expander draws, as counts — `treeExpanderLayout`'s answer for it. */
+    get layout(): AdwTreeExpanderLayout {
+        return treeExpanderLayout(
+            { depth: this.depth, expandable: this.expandable, expanded: this.expanded },
+            {
+                hideExpander: this.hideExpander,
+                indentForDepth: this.indentForDepth,
+                indentForIcon: this.indentForIcon,
+            },
+        );
+    }
+
+    connectedCallback() {
+        if (!this._initialized) {
+            this._initialized = true;
+            if (!this.hasAttribute('tabindex')) this.tabIndex = 0;
+            this._wire();
+        }
+        this.setAttribute('role', 'button');
+        this._render();
+    }
+
+    /** The listeners, installed once — they sit on the element, so a re-parent keeps them. */
+    private _wire(): void {
+        this.addEventListener('keydown', (event) => {
+            const action = treeExpanderAction(event.key, {
+                ctrlKey: event.ctrlKey,
+                shiftKey: event.shiftKey,
+                rtl: globalThis.getComputedStyle(this).direction === 'rtl',
+            });
+            if (action === 'none') return;
+            event.preventDefault();
+            this.expanded = treeExpanderExpanded(this.expanded, action);
+        });
+
+        // A drag that rests over a collapsed row opens it, so a drop can reach a child
+        // the tree has not shown yet (gtktreeexpander.c:719-745).
+        this.addEventListener('dragenter', () => {
+            if (this.expanded || this._expandTimer !== null) return;
+            this._expandTimer = setTimeout(() => {
+                this._expandTimer = null;
+                this.expanded = true;
+            }, TIMEOUT_EXPAND);
+        });
+        for (const name of ['dragleave', 'drop']) {
+            this.addEventListener(name, () => this._cancelExpandTimer());
+        }
+    }
+
+    disconnectedCallback() {
+        // Cleanup beside creation: `gtk_tree_expander_dispose` clears the same timer, and
+        // a pending one here would expand a row that is no longer in the document.
+        this._cancelExpandTimer();
+    }
+
+    attributeChangedCallback(name?: string) {
+        if (!this._initialized) return;
+        this._render();
+        if (name === 'expanded') {
+            this.dispatchEvent(
+                new CustomEvent('notify::expanded', { bubbles: true, detail: { expanded: this.expanded } }),
+            );
+        }
+    }
+
+    private _cancelExpandTimer(): void {
+        if (this._expandTimer === null) return;
+        clearTimeout(this._expandTimer);
+        this._expandTimer = null;
+    }
+
+    /**
+     * Rebuild the indents and the expander in front of the child.
+     *
+     * Every ornament is dropped and rebuilt rather than diffed: there are at most
+     * depth + 1 of them, they hold no state and no focus, and a diff over two kinds of
+     * node is where the leaf/expandable transition would go wrong.
+     */
+    private _render(): void {
+        for (const ornament of this._ornaments) ornament.remove();
+        this._ornaments = [];
+
+        const layout = this.layout;
+        const before = this.firstChild;
+        for (let i = 0; i < layout.indents; i++) {
+            const indent = document.createElement('span');
+            indent.className = 'adw-tree-expander-indent';
+            indent.setAttribute('aria-hidden', 'true');
+            this.insertBefore(indent, before);
+            this._ornaments.push(indent);
+        }
+
+        if (layout.expander === 'none') {
+            this.removeAttribute('aria-expanded');
+        } else {
+            // libadwaita's `expander` node is `pan-end-symbolic`, turning to
+            // `pan-down-symbolic` when `:checked` (_expanders.scss:1-10). This package's
+            // icon subset carries `go-next`, and `.expanded` rotates it a quarter turn —
+            // the substitution `<adw-expander-row>` already makes for its chevron.
+            const icon = createGtkImage('go-next', 'adw-tree-expander-icon');
+            icon.classList.toggle('expanded', layout.expander === 'expanded');
+            icon.addEventListener('click', (event) => {
+                // The gesture is on the ICON upstream, not on the whole widget: the rest
+                // of the row belongs to the list view's own click.
+                event.stopPropagation();
+                this.expanded = !this.expanded;
+            });
+            this.insertBefore(icon, before);
+            this._ornaments.push(icon);
+            this.setAttribute('aria-expanded', String(layout.expander === 'expanded'));
+        }
+
+        this.setAttribute('aria-level', String(layout.level));
+    }
+}
+
+customElements.define('gtk-tree-expander', GtkTreeExpander);