@gjsify/adwaita-web 0.55.0 → 0.57.0

package/src/elements/gtk-popover-menu.ts

@@ -81,6 +81,7 @@ import {
     normalizeMenuModel,
     parseMenuModel,
 } from '@gjsify/adwaita-core';
+import { activateElementMenuItem, menuActionsOfElement } from '../application.js';
 import type { AdwMenuActions, AdwMenuInput, AdwMenuModel, AdwMenuPath } from '@gjsify/adwaita-core';
 
 import { GtkPopover } from './gtk-popover.js';
@@ -187,8 +188,11 @@ export class GtkPopoverMenu extends GtkPopover {
         // with `gtk_popover_menu_set_open_submenu (widget, NULL)` (gtkpopovermenu.c:573-579):
         // a menu that reopens three levels deep is one the reader cannot get out of.
         this.subscribe((open) => {
-            if (open) this._menuView.focusableRows[0]?.focus();
-            else this._menuView.reset();
+            if (open) {
+                this._menuView.setActions(this._actions ?? menuActionsOfElement(this, this._model));
+                this._menuView.render();
+                this._menuView.focusableRows[0]?.focus();
+            } else this._menuView.reset();
         });
     }
 
@@ -308,6 +312,7 @@ export class GtkPopoverMenu extends GtkPopover {
         this.popdown();
         this.anchor?.focus();
         if (target === null) return;
+        activateElementMenuItem(this, target);
         this.dispatchEvent(
             new CustomEvent('menu-item-activated', {
                 bubbles: true,

package/src/elements/gtk-scrolled-window.ts

@@ -86,12 +86,13 @@
 // Copyright (c) The GTK Team. LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
+import { GtkAdjustment } from '@gjsify/adwaita-core';
 import type { AdwAdjustment } from '@gjsify/adwaita-core';
 
 import { AdwScrollShading } from '../scroll-shading.js';
 import { bindSlottedChildren } from '../slotted-children.js';
 import type { GtkScrollType } from './gtk-scrollbar.js';
-import { GtkViewport } from './gtk-viewport.js';
+import type { GtkViewport } from './gtk-viewport.js';
 
 /**
  * `INDICATOR_FADE_OUT_DELAY` — how long an indicator waits, after the last scroll, before
@@ -112,6 +113,8 @@ export type GtkPositionType = 'left' | 'right' | 'top' | 'bottom';
 export type GtkDirectionType = 'forward' | 'backward';
 
 const POLICIES: readonly GtkPolicyType[] = ['always', 'never', 'automatic', 'external'];
+/** The nicks in `Gtk.PolicyType`'s numeric order, which is not the order above. */
+const POLICY_BY_VALUE: readonly GtkPolicyType[] = ['always', 'automatic', 'never', 'external'];
 const CORNERS: readonly GtkCornerType[] = ['top-left', 'top-right', 'bottom-left', 'bottom-right'];
 
 /** An unknown nick is the pspec's default, which is what GtkBuilder's rejection leaves behind. */
@@ -198,11 +201,16 @@ function resolveScrollKey(event: KeyboardEvent): { scroll: GtkScrollType; horizo
 export class GtkScrolledWindow extends HTMLElement {
     private _viewport!: GtkViewport;
     private _bars: Record<'horizontal' | 'vertical', HTMLElement> | null = null;
+    /** The size clamps `_writeSize` last wrote, which are the only ones it may clear. */
+    private readonly _wroteSizes = new Set<string>();
     private _shading: AdwScrollShading | null = null;
     private _observer: ResizeObserver | null = null;
     private _hoverable: MediaQueryList | null = null;
     private _fadeTimer: ReturnType<typeof setTimeout> | null = null;
     private _built = false;
+    /** What an unbuilt window answers before it has a viewport to read. */
+    private readonly _standIn: { hadjustment?: AdwAdjustment; vadjustment?: AdwAdjustment } = {};
+    private readonly _adopted: { hadjustment?: AdwAdjustment; vadjustment?: AdwAdjustment } = {};
 
     static get observedAttributes() {
         return [
@@ -238,6 +246,58 @@ export class GtkScrolledWindow extends HTMLElement {
         this.setAttribute('vscrollbar-policy', value);
     }
 
+    /** `gtk_scrolled_window_get_policy`: `[hscrollbar, vscrollbar]` as `Gtk.PolicyType` constants. */
+    get_policy(): [number, number] {
+        return [POLICY_BY_VALUE.indexOf(this.hscrollbarPolicy), POLICY_BY_VALUE.indexOf(this.vscrollbarPolicy)];
+    }
+
+    /** `gtk_scrolled_window_set_policy`; a value that is not a `Gtk.PolicyType` throws, as GJS's enum marshalling does. */
+    set_policy(hscrollbar_policy: number, vscrollbar_policy: number): void {
+        const nick = (value: number, name: string): GtkPolicyType => {
+            const found = Number.isInteger(value) ? POLICY_BY_VALUE[value] : undefined;
+            if (found === undefined) throw new TypeError(`${value} is not a valid value for enum argument ${name}`);
+            return found;
+        };
+        const h = nick(hscrollbar_policy, 'hscrollbar_policy');
+        const v = nick(vscrollbar_policy, 'vscrollbar_policy');
+        this.hscrollbarPolicy = h;
+        this.vscrollbarPolicy = v;
+    }
+
+    /** `GtkScrollable:hadjustment` as the window reports it: the one it was given, else the viewport's. */
+    get hadjustment(): AdwAdjustment {
+        return (
+            this._adopted.hadjustment ??
+            (this._viewport as GtkViewport | undefined)?.hadjustment ??
+            (this._standIn.hadjustment ??= new GtkAdjustment())
+        );
+    }
+
+    get vadjustment(): AdwAdjustment {
+        return (
+            this._adopted.vadjustment ??
+            (this._viewport as GtkViewport | undefined)?.vadjustment ??
+            (this._standIn.vadjustment ??= new GtkAdjustment())
+        );
+    }
+
+    get_hadjustment(): AdwAdjustment {
+        return this.hadjustment;
+    }
+
+    get_vadjustment(): AdwAdjustment {
+        return this.vadjustment;
+    }
+
+    /** Adopts `adjustment` as what `get_hadjustment` answers; the scroll position keeps following the viewport. */
+    set_hadjustment(adjustment: AdwAdjustment): void {
+        this._adopted.hadjustment = adjustment;
+    }
+
+    set_vadjustment(adjustment: AdwAdjustment): void {
+        this._adopted.vadjustment = adjustment;
+    }
+
     /** `GtkScrolledWindow:window-placement` — where the contents sit against the bars. */
     get windowPlacement(): GtkCornerType {
         return normalizeCorner(this.getAttribute('window-placement'));
@@ -447,10 +507,10 @@ export class GtkScrolledWindow extends HTMLElement {
         this.classList.toggle('overlay-scrolling', indicators);
         // `gtk_scrolled_window_measure`'s four clamps, as the four CSS size requests they
         // are: an unwritten one (-1) sets nothing at all.
-        this.style.minWidth = this._size('min-content-width');
-        this.style.minHeight = this._size('min-content-height');
-        this.style.maxWidth = this._size('max-content-width');
-        this.style.maxHeight = this._size('max-content-height');
+        this._writeSize('min-width', 'min-content-width');
+        this._writeSize('min-height', 'min-content-height');
+        this._writeSize('max-width', 'max-content-width');
+        this._writeSize('max-height', 'max-content-height');
         for (const axis of AXES) {
             const bar = bars[axis.bar];
             const policy = normalizePolicy(this.getAttribute(axis.policy));
@@ -481,9 +541,18 @@ export class GtkScrolledWindow extends HTMLElement {
         if (!indicators) this._clearFade();
     }
 
-    private _size(attribute: string): string {
+    /**
+     * One of the four clamps as inline style. An unwritten clamp clears only what THIS element
+     * wrote: `min-width` / `min-height` are also where a tree's `width-request` /
+     * `height-request` land (`GTK_WIDGET_SIZE_CSS`), and assigning '' unconditionally erased it.
+     * Where both are set the content clamp wins, which is the one the widget measures itself.
+     */
+    private _writeSize(property: string, attribute: string): void {
         const size = sizeRequest(this.getAttribute(attribute));
-        return size === null ? '' : `${size}px`;
+        if (size !== null) this.style.setProperty(property, `${size}px`);
+        else if (this._wroteSizes.has(property)) this.style.removeProperty(property);
+        if (size !== null) this._wroteSizes.add(property);
+        else this._wroteSizes.delete(property);
     }
 
     /** The viewport's adjustment for one axis, which is where GTK reads the scrollbar's. */

package/src/elements/gtk-stack.ts

@@ -91,6 +91,8 @@
 // Copyright (c) The GTK Team. LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
+import type { DispatchedSignals } from '../signals.js';
+
 /** `GtkStackTransitionType`, spelled as the GIR's enum nicks (gtkstack.c:95-121). */
 export type StackTransitionType =
     | 'none'
@@ -224,6 +226,12 @@ export interface GtkStackPageInfo {
 const PAGE_ATTRIBUTES = ['name', 'title', 'icon-name', 'use-underline', 'needs-attention'];
 
 export class GtkStack extends HTMLElement {
+    /** The GTK signals this element dispatches, each with the DOM event it arrives as (ADR 0093). */
+    static readonly signals: DispatchedSignals = {
+        'notify::visible-child': 'notify::visible-child',
+        'notify::visible-child-name': 'notify::visible-child-name',
+    };
+
     /** The child that is visible, or `null` — C's `priv->visible_child`. */
     private _visible: HTMLElement | null = null;
     /** C's `priv->last_visible_child`: the page being animated away. */

package/src/elements/gtk-switch.ts

@@ -39,7 +39,15 @@
 // Copyright (c) 2025 csm (adwaita-web). MIT License.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
+import type { DispatchedSignals } from '../signals.js';
+
 export class GtkSwitch extends HTMLElement {
+    /** The GTK signals this element dispatches, each with the DOM event it arrives as (ADR 0093). */
+    static readonly signals: DispatchedSignals = {
+        'notify::active': 'notify::active',
+        'notify::state': 'notify::state',
+    };
+
     private _input!: HTMLInputElement;
     private _slider!: HTMLSpanElement;
     private _initialized = false;

package/src/elements/gtk-window.ts

@@ -106,9 +106,15 @@ export class GtkWindow extends HTMLElement {
         ];
     }
 
-    /** `Gtk.Window:title` — the window's title. */
-    get title(): string | null {
-        return this.getAttribute('title');
+    /**
+     * `Gtk.Window:title` — the window's title.
+     *
+     * The getter answers `''` for no title, not `null`: a `string | null` getter is not assignable to
+     * `HTMLElement.title`, and the emitted `.d.ts` then fails every consumer that does not set
+     * `skipLibCheck`. The setter still takes `null` to clear it, as GTK does.
+     */
+    get title(): string {
+        return this.getAttribute('title') ?? '';
     }
 
     set title(value: string | null) {

package/src/glib.spec.ts

@@ -0,0 +1,34 @@
+// The GLib timers door of adwaita-web, held to the shared vectors (real GJS is their oracle, in
+// adwaita-core's `glib-timers.gjs.spec.ts`). The door is the namespace module itself, so a member
+// that stops being exported fails here.
+
+import { GLIB_TIMER_VECTORS, driveGLibTimerVectors, type GLibTimersLike } from '@gjsify/adwaita-core/conformance';
+import { describe, expect, it } from '@gjsify/unit';
+
+import * as GLib from './namespace/glib.js';
+
+export const GLibTest = async () => {
+    await driveGLibTimerVectors(
+        {
+            name: 'adwaita-web',
+            isOracle: false,
+            GLib: GLib as unknown as GLibTimersLike,
+            settle: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+            quiet: async (body) => {
+                const original = console.error;
+                console.error = () => {};
+                try {
+                    await body();
+                } finally {
+                    console.error = original;
+                }
+            },
+        },
+        { describe, it, expect },
+    );
+    await describe('adwaita-web: GLib door', async () => {
+        await it('has a vector row for every vector', () => {
+            expect(GLIB_TIMER_VECTORS.length > 0).toBe(true);
+        });
+    });
+};

package/src/gobject-door.spec.ts

@@ -0,0 +1,119 @@
+// ADR 0096: the web door of the GObject subset, against the shared vectors and end to end.
+import { parseBlueprint, projectToSharedNode } from '@gjsify/blueprint';
+import { GOBJECT_VECTORS, driveGObjectVectors, type GObjectSubject } from '@gjsify/adwaita-core/conformance';
+import { describe, expect, it } from '@gjsify/unit';
+
+import { Adw, GObject } from './index.js';
+import { tagForTypeName } from './gobject-door.js';
+import type { SharedTreeNode } from '@gjsify/adwaita-core/conformance';
+import { bindProperties } from '@gjsify/adwaita-core';
+
+function tree(body: string): SharedTreeNode {
+    const { node, lost } = projectToSharedNode(
+        parseBlueprint(`using Gtk 4.0;\nusing Adw 1;\n\n${body}\n`, 'gobject-door.spec.blp'),
+    );
+    if (lost.length > 0) throw new Error(`the projection dropped ${lost.map((loss) => loss.kind).join(', ')}`);
+    return node as SharedTreeNode;
+}
+
+const subject: GObjectSubject = {
+    name: 'adwaita-web',
+    isOracle: false,
+    GObject: GObject as unknown as GObjectSubject['GObject'],
+    Widget: Adw.Bin as unknown as GObjectSubject['Widget'],
+    template: (source) => source.tree,
+    bind: (source, sourceProperty, target, targetProperty, flags) => {
+        bindProperties(source, sourceProperty, target, targetProperty, flags);
+    },
+};
+
+const Template = tree(`template $GoWebHexdump : Adw.Bin {
+    child: Gtk.Box {
+        Gtk.Switch sw { active: bind template.enabled bidirectional; }
+        Gtk.Button btn { clicked => $onClicked(); }
+    };
+}`);
+
+class GoWebHexdump extends Adw.Bin {
+    declare _sw: HTMLElement & { active: boolean };
+    declare _btn: HTMLElement;
+    declare enabled: boolean;
+    clicks = 0;
+    seenInConstructor = false;
+    constructor(params?: Record<string, unknown>) {
+        // @ts-expect-error the element's own constructor takes none; the registered class's takes the params
+        super(params);
+        this.seenInConstructor = this._btn !== undefined;
+        (this._btn as unknown as { connect(s: string, h: () => void): number }).connect('clicked', () => {
+            this.clicks += 10;
+        });
+    }
+    onClicked(): void {
+        this.clicks++;
+    }
+}
+GObject.registerClass(
+    {
+        GTypeName: 'GoWebHexdump',
+        Template,
+        InternalChildren: ['sw', 'btn'],
+        Properties: { enabled: GObject.ParamSpec.boolean('enabled', '', '', GObject.ParamFlags.READWRITE, false) },
+    },
+    GoWebHexdump as never,
+);
+
+export const GObjectDoorTest = async () => {
+    await driveGObjectVectors(subject, { describe, it, expect }, GOBJECT_VECTORS);
+    await describe('adwaita-web: GObject.registerClass end to end (ADR 0096)', async () => {
+        await it('derives the tag from the GTypeName', () => {
+            expect(tagForTypeName('Hexdump')).toBe('gjsify-hexdump');
+            expect(customElements.get('gjsify-go-web-hexdump')).toBe(GoWebHexdump);
+        });
+        await it('refuses a second class under the same tag', () => {
+            expect(() =>
+                GObject.registerClass({ GTypeName: 'GoWebHexdump' }, class extends Adw.Bin {} as never),
+            ).toThrow('already defines');
+        });
+        await it('MEASURED: a bare element dispatches no notify before its first connect, a connected-through-the-door one does', () => {
+            const bare = document.createElement('gtk-switch') as HTMLElement & { active: boolean };
+            let heard = 0;
+            bare.addEventListener('notify::active', () => heard++);
+            bare.active = true;
+            expect(heard).toBe(0);
+            const el = new GoWebHexdump();
+            let viaDoor = 0;
+            (el._sw as unknown as { connect(s: string, h: () => void): number }).connect(
+                'notify::active',
+                () => viaDoor++,
+            );
+            el._sw.active = true;
+            expect(viaDoor).toBe(1);
+        });
+        for (const how of ['new', 'createElement'] as const) {
+            await it(`built with ${how}: this._x after super, children after connect, bind and handler work`, () => {
+                const el = (
+                    how === 'new' ? new GoWebHexdump() : document.createElement('gjsify-go-web-hexdump')
+                ) as GoWebHexdump;
+                expect(el._sw !== undefined).toBe(true);
+                expect(el.children.length).toBe(0);
+                expect(el.seenInConstructor).toBe(true);
+                // notify on a not-yet-connected element reaches the binding (ADR 0096 UNVERIFIED point)
+                el._sw.active = true;
+                expect(el.enabled).toBe(true);
+                el.enabled = false;
+                expect(el._sw.active).toBe(false);
+                document.body.append(el);
+                try {
+                    expect(el.querySelector('gtk-switch') !== null).toBe(true);
+                    expect(el.contains(el._btn)).toBe(true);
+                    el._btn.dispatchEvent(new Event('click'));
+                    expect(el.clicks).toBe(11);
+                    el._sw.active = true;
+                    expect(el.enabled).toBe(true);
+                } finally {
+                    el.remove();
+                }
+            });
+        }
+    });
+};

package/src/gobject-door.ts

@@ -0,0 +1,137 @@
+// The web door of the GObject subset (ADR 0096 § 1): how custom elements dispatch and listen for a
+// named event, build a template, and take the built children.
+//
+// A registered class is a custom element. `registerClass` defines it under a tag derived from
+// its `GTypeName`, and the instance is built in the order of GJS's `Gtk.Widget._init` by a class
+// inserted between the class and its widget base, because the base is an element that knows
+// nothing of GObject and `super(params)` is the only place a subclass hands control down.
+//
+// CHILDREN ARE ATTACHED AT THE FIRST `connectedCallback`, never in the constructor: the custom
+// element rules forbid a constructor to give the element children or attributes when
+// `createElement` or the parser creates it. They are created, and wired to their handlers and
+// binds, from the constructor on, so `this._x.connect(…)` in a subclass constructor works.
+
+import {
+    constructRegistered,
+    type BuiltTemplate,
+    type ClassLike,
+    type GObjectDoor,
+    type RegisteredClass,
+    type TemplateScope,
+} from '@gjsify/adwaita-core';
+import { propertyOf } from '@gjsify/adwaita-core/tags';
+
+import { dispatchElement, listenElement } from './gobject-elements.js';
+import { buildTemplateTree, type BuiltTemplateTree } from './shared-tree-builder.js';
+import { registerTemplateClass } from './template-classes.js';
+
+type Ctor = new (...args: never[]) => HTMLElement;
+
+const PENDING = new WeakMap<HTMLElement, BuiltTemplateTree[]>();
+const CONSTRUCTED = new WeakSet<HTMLElement>();
+const DEFINED_FOR = new Map<string, string>();
+
+/** `Hexdump` → `gjsify-hexdump`, `GoVecNotify` → `gjsify-go-vec-notify`. */
+export function tagForTypeName(typeName: string): string {
+    const kebab = typeName
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return `gjsify-${kebab}`;
+}
+
+function isElementClass(klass: ClassLike): boolean {
+    return (klass as { prototype: object }).prototype instanceof HTMLElement;
+}
+
+/** The signals a registered element declares: its widget base's, one `notify::` per property, its own. */
+function declareSignals(klass: ClassLike, info: RegisteredClass): void {
+    const inherited = (klass as unknown as { signals?: Record<string, string> }).signals ?? {};
+    const signals: Record<string, string> = { ...inherited };
+    for (const spec of info.properties) signals[`notify::${spec.name}`] = `notify::${spec.name}`;
+    for (const name of Object.keys(info.signals)) signals[name] = name;
+    Object.defineProperty(klass, 'signals', { value: signals, configurable: true, writable: true });
+}
+
+function attachPending(host: HTMLElement): void {
+    const pending = PENDING.get(host);
+    if (pending === undefined) return;
+    PENDING.delete(host);
+    for (const built of pending) {
+        built.finish();
+        host.append(...built.children);
+    }
+}
+
+export const webDoor: GObjectDoor = {
+    name: 'adwaita-web',
+
+    dispatch(target, event, args) {
+        if (!(target instanceof HTMLElement)) throw new Error(`No signal '${event}' on object '${String(target)}'`);
+        dispatchElement(target, event, args);
+    },
+
+    listen(target, event, handler) {
+        if (!(target instanceof HTMLElement)) throw new Error(`No signal '${event}' on object '${String(target)}'`);
+        return listenElement(target, event, handler as never);
+    },
+
+    createFromTree(tree, scope: TemplateScope, host): BuiltTemplate {
+        return buildTemplateTree(tree, scope, host as HTMLElement);
+    },
+
+    attach(host, built) {
+        const pending = PENDING.get(host as HTMLElement) ?? [];
+        pending.push(built as BuiltTemplateTree);
+        PENDING.set(host as HTMLElement, pending);
+    },
+
+    register(klass, info) {
+        // A class with no widget model beneath it is built by `GObject.Object`, which is the core's.
+        if (!isElementClass(klass)) return;
+        const tag = tagForTypeName(info.typeName);
+        const known = DEFINED_FOR.get(tag) ?? (customElements.get(tag) === undefined ? undefined : 'another class');
+        if (known !== undefined) {
+            throw new Error(
+                `GObject.registerClass: ${info.typeName} would be <${tag}>, which ${known} already defines. ` +
+                    'Give the class a distinct GTypeName.',
+            );
+        }
+
+        const Parent = Object.getPrototypeOf(klass) as Ctor;
+        class Constructing extends Parent {
+            constructor(params?: Record<string, unknown>) {
+                super();
+                // A registered base ran the whole chain already, for the most derived class.
+                if (CONSTRUCTED.has(this)) return;
+                CONSTRUCTED.add(this);
+                const rest = constructRegistered(this, params);
+                for (const [key, value] of Object.entries(rest)) {
+                    const member = propertyOf(key);
+                    if (!(member in this)) throw new Error(`No property ${key} on <${tag}>`);
+                    (this as unknown as Record<string, unknown>)[member] = value;
+                }
+            }
+        }
+        Object.setPrototypeOf(klass, Constructing);
+        Object.setPrototypeOf((klass as { prototype: object }).prototype, Constructing.prototype);
+
+        const proto = (klass as { prototype: Record<string, unknown> }).prototype;
+        const inherited = proto.connectedCallback as (() => void) | undefined;
+        Object.defineProperty(proto, 'connectedCallback', {
+            configurable: true,
+            writable: true,
+            value(this: HTMLElement) {
+                attachPending(this);
+                inherited?.call(this);
+            },
+        });
+
+        declareSignals(klass, info);
+        customElements.define(tag, klass as unknown as CustomElementConstructor);
+        DEFINED_FOR.set(tag, info.typeName);
+        registerTemplateClass(info.typeName, tag);
+    },
+};