@gjsify/adwaita-web 0.53.0 → 0.55.0

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

@@ -0,0 +1,221 @@
+// <gtk-window-handle> — the titlebar strip: a widget that lets the window manager move the
+// window when it is dragged, and turns the right-click, double-click and middle-click a
+// titlebar is expected to turn into.
+//
+// WHAT IS LEFT OF IT IN GTK 4.24. The widget has ONE property (`child`), a `GtkBinLayout`, a
+// `windowhandle` CSS node and the generic a11y role (gtkwindowhandle.c:529-556); everything
+// else it once was is gone. The titlebar behaviour is three cases in
+// `perform_titlebar_action` (gtkwindowhandle.c:335-367):
+//
+//   · a PRIMARY double-click, a MIDDLE click or a SECONDARY click asks the COMPOSITOR first
+//     (`gdk_toplevel_titlebar_gesture`), and where there is no answer the settings
+//     `gtk-titlebar-double-click`, `-middle-click` and `-right-click` decide — their
+//     documented values are `toggle-maximize`, `lower`, `minimize`, `menu` and `none`
+//     (`perform_titlebar_action_fallback`, gtkwindowhandle.c:282-333);
+//   · a drag past the threshold begins a window MOVE (`gdk_toplevel_begin_move`,
+//     gtkwindowhandle.c:423-467);
+//   · `menu` opens the window menu, falling back to GTK's OWN Restore / Minimize / Maximize /
+//     Close popover (`do_popup_fallback`, gtkwindowhandle.c:160-262).
+//
+// WHAT A PAGE CANNOT DO, AND WHAT IT DOES INSTEAD. `gdk_toplevel_begin_move` and
+// `gdk_toplevel_show_window_menu` are OPERATIONS ON THE COMPOSITOR'S SURFACE: a document is
+// not allowed to move or unmaximize the window it is rendered in, and no web API asks it to.
+// So the port emits the SAME action names GTK's fallback activates — `window.toggle-maximized`
+// and `window.minimize` are the strings `gtk_widget_activate_action` is handed
+// (gtkwindowhandle.c:313-321), and `window.lower` / `window.menu` are the compositor calls it
+// makes instead (gtkwindowhandle.c:84-91, 264-280) — as a `titlebar-action` CustomEvent
+// (bubbles, detail `{ action, gesture, windowAction, x, y }`), and a second event NAMED for the
+// action, which is what the C's `gdk_surface_...` call amounts to from a consumer's side. The
+// settings that choose the action are attributes of the same three names minus the `gtk-`
+// prefix, so a consumer writes `double-click-action="toggle-maximize"` and gets GTK's
+// precedence without a settings object it cannot have.
+//
+// `child` is a SLOT, as everywhere in this package: an attribute cannot carry a widget, and a
+// handle needs no routing of its own because it contributes no box — `display: contents` IS
+// `GtkBinLayout`'s "the child takes the whole allocation", so the strip can go anywhere a
+// header bar goes without moving the layout around it.
+//
+// A11y: `role="generic"`, which GTK 4.12 gave the widget in place of the `group` it used to
+// report (gtkwindowhandle.c:55-59, 555). The gestures are POINTER ones on the child's own
+// box, so everything inside the titlebar — its buttons, its title — stays operable by
+// keyboard.
+//
+// Reference: refs/gtk/gtk/gtkwindowhandle.c (class_init, click_gesture_pressed_cb,
+//   perform_titlebar_action, perform_titlebar_action_fallback, drag_gesture_update_cb,
+//   do_popup_fallback)
+// Copyright (c) The GTK Team. LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+/** `GtkTitlebarGesture`'s three gestures, as `perform_titlebar_action` decides them. */
+export type GtkTitlebarGesture = 'double-click' | 'middle-click' | 'right-click';
+
+/** The settings' own vocabulary, `none` included: "the compositor declined" is one. */
+export type GtkTitlebarAction = 'toggle-maximize' | 'lower' | 'minimize' | 'menu' | 'none';
+
+/**
+ * Each gesture, the ATTRIBUTE its setting is authored under, and the value read when the
+ * attribute is absent.
+ *
+ * The three defaults are the pspecs' own and they are NOT all the same
+ * (gtksettings.c:868-896): `gtk-titlebar-double-click` is `toggle-maximize`,
+ * `gtk-titlebar-middle-click` is `none` — a middle click on a titlebar does nothing unless
+ * something asked for it — and `gtk-titlebar-right-click` is `menu`. Reading all three as
+ * `menu` would open a window menu on a middle click nobody asked for.
+ */
+const GESTURES = {
+    'double-click': { attribute: 'double-click-action', fallback: 'toggle-maximize' },
+    'middle-click': { attribute: 'middle-click-action', fallback: 'none' },
+    'right-click': { attribute: 'right-click-action', fallback: 'menu' },
+} as const satisfies Record<GtkTitlebarGesture, { attribute: string; fallback: GtkTitlebarAction }>;
+
+/**
+ * The GObject action names `gtk_widget_activate_action` is handed (gtkwindowhandle.c:313-321).
+ *
+ * TWO of the four are real `GtkWindow` actions — `window.toggle-maximized` and
+ * `window.minimize` are installed in `gtk_window_class_init` (gtkwindow.c:1319-1328), which is
+ * what makes them the right names to raise. The other two are compositor OPERATIONS in GTK:
+ * `lower` calls `gdk_toplevel_lower` and `menu` calls `gdk_toplevel_show_window_menu`
+ * (gtkwindowhandle.c:84-91, 264-280), and `window.lower` / `window.menu` are the names a
+ * window host binds those two to.
+ */
+const WINDOW_ACTIONS: Readonly<Record<Exclude<GtkTitlebarAction, 'none'>, string>> = {
+    'toggle-maximize': 'window.toggle-maximized',
+    lower: 'window.lower',
+    minimize: 'window.minimize',
+    menu: 'window.menu',
+};
+
+/** Every action the settings document, which is also the set a typo has to be refused against. */
+const ACTIONS = new Set<string>(['none', 'toggle-maximize', 'lower', 'minimize', 'menu']);
+
+/** `gestureOf`'s switch — which button and press count is which gesture. */
+function gestureOf(button: number, presses: number): GtkTitlebarGesture | null {
+    switch (button) {
+        case 0:
+            return presses > 1 ? 'double-click' : null;
+        case 1:
+            return 'middle-click';
+        case 2:
+            return 'right-click';
+        default:
+            return null;
+    }
+}
+
+/**
+ * The distance a pointer travels before a drag counts.
+ *
+ * `drag_gesture_update_cb` asks `gtk_drag_check_threshold_double (self, 0, 0, dx, dy)`,
+ * which is the theme's drag threshold or `gdk_drag_get_threshold ()` where the toolkit has
+ * none (gtkwindowhandle.c:429). A titlebar has to tell a tap from a drag on a touchscreen as
+ * much as on a mouse, so it is one device pixel.
+ */
+const DRAG_THRESHOLD = 1;
+
+export class GtkWindowHandle extends HTMLElement {
+    /** The gesture in progress, as `priv->drag_start_x` / `_y` are in the C. */
+    private _drag: { pointerId: number; x: number; y: number } | null = null;
+
+    /**
+     * The three gesture SETTINGS, spelled out.
+     *
+     * `GESTURES` above names the same three, and the list is written rather than computed
+     * from it because `scripts/adwaita-elements.mjs` reads `observedAttributes` as an array
+     * LITERAL: a `.map()` over a table reads as an unreadable element there, which is
+     * reported as "this reader cannot tell" rather than as the three attributes it is.
+     */
+    static get observedAttributes() {
+        return ['double-click-action', 'middle-click-action', 'right-click-action'];
+    }
+
+    /** The action one gesture is set to, as the settings are read in C. */
+    actionFor(gesture: GtkTitlebarGesture): GtkTitlebarAction {
+        const { attribute, fallback } = GESTURES[gesture];
+        const written = this.getAttribute(attribute);
+        // An absent attribute is the setting's own value, and each of the three is its own
+        // (gtksettings.c:868-896) — a middle click does nothing by default.
+        if (written === null) return fallback;
+        // `perform_titlebar_action_fallback` matches `toggle-maximize` by PREFIX, "treat all
+        // maximization variants the same" (gtkwindowhandle.c:311-315), so a variant a window
+        // manager invents maximizes rather than being refused.
+        if (written.startsWith('toggle-maximize')) return 'toggle-maximize';
+        // Anything else it does not know takes the C's own refusal branch: `g_warning
+        // ("Unsupported titlebar action %s")` and `retval = FALSE` (gtkwindowhandle.c:324-328),
+        // which is what `none` means here — a typo must not minimize a window.
+        return ACTIONS.has(written) ? (written as GtkTitlebarAction) : 'none';
+    }
+
+    connectedCallback() {
+        this.setAttribute('role', 'generic');
+        this.addEventListener('click', this._onClick);
+        this.addEventListener('pointerdown', this._onPointerDown);
+        this.addEventListener('pointermove', this._onPointerMove);
+    }
+
+    disconnectedCallback() {
+        this.removeEventListener('click', this._onClick);
+        this.removeEventListener('pointerdown', this._onPointerDown);
+        this.removeEventListener('pointermove', this._onPointerMove);
+        this._drag = null;
+    }
+
+    /**
+     * `perform_titlebar_action_fallback`: raise the action GTK would have activated, and
+     * then the event NAMED for it.
+     *
+     * Both fire for every gesture, `none` included: the first is what a consumer reads to
+     * know a titlebar was clicked at all — the C's `retval = FALSE`, where the compositor
+     * declined, is a fact worth reporting — and the second is what a window host binds to.
+     */
+    private _perform(gesture: GtkTitlebarGesture, x: number, y: number): void {
+        const action = this.actionFor(gesture);
+        const windowAction = action === 'none' ? null : WINDOW_ACTIONS[action];
+        const detail = { action, gesture, windowAction, x, y };
+        this.dispatchEvent(new CustomEvent('titlebar-action', { bubbles: true, detail }));
+        if (windowAction === null) return;
+        this.dispatchEvent(new CustomEvent(windowAction, { bubbles: true, detail }));
+    }
+
+    private _onClick = (event: MouseEvent): void => {
+        // The click gesture CLAIMED the sequence, which is what `gtk_event_controller_reset`
+        // on both gestures does upstream for every click it acts on — including the second
+        // press of a double click, whose drag was denied at press time
+        // (gtkwindowhandle.c:408-409, 464-465). A press count the browser knows and a
+        // pointerdown does not is why the reset happens HERE.
+        this._drag = null;
+        const gesture = gestureOf(event.button, event.detail);
+        if (gesture === null) return;
+        // `do_popup_fallback` places the menu with `gtk_popover_set_pointing_to` at the event's
+        // own position, which is the click's.
+        this._perform(gesture, event.clientX, event.clientY);
+    };
+
+    private _onPointerDown = (event: PointerEvent): void => {
+        // A second press of a multi-click sequence DENIES the drag, which is what
+        // `click_gesture_pressed_cb` does with `n_press > 1` (gtkwindowhandle.c:382-383):
+        // a double-click is a click, and a drag that began on its second press is not one.
+        if (event.detail > 1) return;
+        this._drag = { pointerId: event.pointerId, x: event.clientX, y: event.clientY };
+    };
+
+    /**
+     * `drag_gesture_update_cb`: past the threshold the WINDOW moves, and the sequence is
+     * reset so the gesture does not repeat. The move is a compositor operation, so what is
+     * emitted is the INTENT, with the pointer's position where GTK hands `begin_move` its
+     * own surface coordinates.
+     */
+    private _onPointerMove = (event: PointerEvent): void => {
+        const drag = this._drag;
+        if (drag === null || drag.pointerId !== event.pointerId) return;
+        const travelled = Math.abs(event.clientX - drag.x) + Math.abs(event.clientY - drag.y);
+        // STRICTLY past the threshold, which is what `gtk_drag_check_threshold_double` asks:
+        // movement up to it is not a drag.
+        if (travelled <= DRAG_THRESHOLD) return;
+        this._drag = null;
+        this.dispatchEvent(
+            new CustomEvent('window-move', { bubbles: true, detail: { x: event.clientX, y: event.clientY } }),
+        );
+    };
+}
+
+customElements.define('gtk-window-handle', GtkWindowHandle);

package/src/elements/gtk-window.ts

@@ -0,0 +1,366 @@
+// <gtk-window> — a window, IN PAGE. This is a FRAME, not a toplevel: a rounded, shadowed box
+// with a titlebar strip at the top, the window's content below it, and the same window
+// properties `<gtk-window-controls>` reads to decide which frame buttons to draw.
+//
+// SAYING THAT PLAINLY, because the element's name promises something the page cannot be. A
+// browser document has no `GtkWindow`, no `GdkToplevel`, no window manager and no place to
+// map one; what a page can draw is the DECORATION of a window and honour the properties that
+// decide what that decoration shows. So: no `move()`, no `resize()`, no real `is-active`, and
+// a close button that hides or detaches a box rather than a surface the compositor owns.
+// Everything else below is ported from `gtkwindow.c`.
+//
+// THE TREE. `Gtk.Window` is a `GtkBin` with a `child` and, since 4.6, a `titlebar`
+// (gtkwindow.c:1128, :1138), and libadwaita paints `window { &.csd { … } }` around it
+// (refs/libadwaita/src/stylesheet/widgets/_window.scss:1-31). This element therefore builds
+//
+//   <gtk-window>
+//     ├── div.adw-gtk-window-titlebar   — the `titlebar`, or the server-side decoration
+//     │                                 a `Gtk.Window` without one would get from the WM
+//     └── div.adw-gtk-window-content    — everything else, in document order
+//
+// and `decorated="false"` drops the first, which is what `gtk_window_set_decorated` means
+// (:1014). A `titlebar` SLOT is how the property is written in markup; with none, the strip
+// holds the two `<gtk-window-controls>` and the window's own title — GTK's SSD shape, which
+// is exactly the thing a page has to draw for itself.
+//
+// WHAT THE FRAME PROPERTIES DO, EACH AT ITS OWN SOURCE LINE:
+//   `title`          — read by a header bar's `update_title` (gtkheaderbar.c:250-271) and
+//                      written into the strip's title when there is no titlebar (:873).
+//   `deletable`      — no close button when false (:1024); `gtk_window_close` (:1274).
+//   `resizable`      — no maximize button when false (:893).
+//   `maximized`      — the restore glyph instead of the maximize one, and the square-cornered
+//                      `&.maximized` frame libadwaita draws (_window.scss:66-72, :1044).
+//   `fullscreened`   — the same square corners from the other side (_window.scss:67, :1060).
+//   `modal` / `transient-for` — the sovereignty test: neither means the window owns an icon
+//                      and a minimize button (gtkwindowcontrols.c:272-273, :299, :318).
+//   `icon-name`      — the icon at the head of the start controls (:982).
+//   `hide-on-close`  — the two branches of the close button's default handler (:945,
+//                      `gtk_window_close` :1274-1287): hide, or destroy. `close-request` is
+//                      emitted first and is CANCELLED by a handler that takes over (:1200-1224).
+//   `default-width` / `default-height` — the size a window opens at (:913-930).
+//
+// THE CLOSE BUTTON. GTK's window controls activate the `window.close` action, which
+// `Gtk.Window` answers with `gtk_window_close` (:1274-1287): emit `close-request`, and if
+// nothing handled it, HIDE the window when `hide-on-close` is set and DESTROY it otherwise.
+// That is the whole of the default, and it is what this element does — except that "destroy"
+// detaches the frame from the page rather than unref'ing a toplevel, which is the one
+// difference a reader of the DOM can see.
+//
+// NOT PORTED, and why — these are the KNOWN_GAPS of this element:
+//   `application`, `child`, `default-widget`, `display`, `focus-widget` — WIDGET- or
+//     DISPLAY-typed, so a slot or an id here rather than an attribute; `child` and
+//     `titlebar` ARE slots and `transient-for` only has to be PRESENT.
+//   `destroy-with-parent` — a DOM node has no destroy, and a page has no parent to destroy.
+//   `focus-visible`, `mnemonics-visible` — GTK maintains both from user input and the GIR
+//     says an application must not set them (:969, :956).
+//   `gravity` — which point stays fixed while the window is resized PROGRAMMATICALLY (:1163);
+//     a browser box is laid out, never resized that way.
+//   `handle-menubar-accel` — F10 activating a menubar, which is `<gtk-application-window>`'s
+//     business and needs the `Gio.MenuModel` it is built from (:1150).
+//   `startup-id` — write-only, and written by the launcher that started the application (:883).
+//
+// Events: `notify::<prop>` (CustomEvent, bubbles, detail `{ <prop>: value }`) on every real
+// change, and `close-request` (CustomEvent, bubbles, CANCELLED, no detail), which is
+// `Gtk.Window::close-request`.
+//
+// Reference: refs/gtk/gtk/gtkwindow.c
+// Reference: refs/libadwaita/src/stylesheet/widgets/_window.scss (GtkWindow)
+// Copyright (c) The GTK Team. LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+import { bindSlottedChildren, type AdwSlot } from '../slotted-children.js';
+
+// Registers <gtk-window-controls>: a frame with no titlebar of its own draws the two of them
+// a server-side decoration would have, so importing the window alone must define them.
+import './gtk-window-controls.js';
+import type { WindowAction } from './gtk-window-controls.js';
+
+export class GtkWindow extends HTMLElement {
+    private _initialized = false;
+    /** The `titlebar` strip — `protected` so a subclass can place its own strips around it. */
+    protected _titlebar!: HTMLDivElement;
+    /** Every child the window has no slot name for. */
+    protected _content!: HTMLDivElement;
+    /** The SSD controls the strip draws when the window has no titlebar of its own. */
+    private _startControls: HTMLElement | null = null;
+    private _endControls: HTMLElement | null = null;
+    /** The window's own title in the strip, or `null` when a titlebar holds it. */
+    private _titleLabel: HTMLElement | null = null;
+    /** Watches the strip for an author's titlebar arriving after the build. */
+    private _titlebarObserver: MutationObserver | null = null;
+
+    static get observedAttributes() {
+        return [
+            'decorated',
+            'default-width',
+            'default-height',
+            'deletable',
+            'fullscreened',
+            'hide-on-close',
+            'icon-name',
+            'maximized',
+            'modal',
+            'resizable',
+            'title',
+            'transient-for',
+        ];
+    }
+
+    /** `Gtk.Window:title` — the window's title. */
+    get title(): string | null {
+        return this.getAttribute('title');
+    }
+
+    set title(value: string | null) {
+        this._write('title', value);
+    }
+
+    /** `Gtk.Window:decorated` — whether the frame and its titlebar strip are drawn at all. */
+    get decorated(): boolean {
+        return this._onByDefault('decorated');
+    }
+
+    set decorated(value: boolean) {
+        this._write('decorated', String(value));
+    }
+
+    /** `Gtk.Window:maximized` — square corners and the restore glyph. */
+    get maximized(): boolean {
+        return this._offByDefault('maximized');
+    }
+
+    set maximized(value: boolean) {
+        this._write('maximized', String(value));
+    }
+
+    /** `Gtk.Window:resizable` — whether the maximize button may appear. */
+    get resizable(): boolean {
+        return this._onByDefault('resizable');
+    }
+
+    set resizable(value: boolean) {
+        this._write('resizable', String(value));
+    }
+
+    /** `Gtk.Window:deletable` — whether the close button may appear. */
+    get deletable(): boolean {
+        return this._onByDefault('deletable');
+    }
+
+    set deletable(value: boolean) {
+        this._write('deletable', String(value));
+    }
+
+    /**
+     * `setAttribute` for a write that changes nothing. Every GObject setter here returns
+     * early when the value is already right (gtkwindow.c:1015-1017, :1045-1046, :894-895),
+     * and a boolean property whose value did not move must not notify.
+     */
+    protected _write(name: string, value: string | null): void {
+        if (value === null) this.removeAttribute(name);
+        else if (this.getAttribute(name) !== value) this.setAttribute(name, value);
+    }
+
+    /**
+     * The two default polarities, because one of them is wrong for half of this widget.
+     *
+     * `decorated`, `resizable` and `deletable` default TRUE (gtkwindow.c:1014, :893, :1024)
+     * and `maximized`, `fullscreened`, `modal` and `hide-on-close` default FALSE (:1044,
+     * :1060, :903, :945). Reading them all through one helper is how a bare `<gtk-window>`
+     * ended up wearing `.maximized` and `.fullscreen` — square corners and no shadow, on a
+     * window that had never been maximized.
+     */
+    private _onByDefault(name: string): boolean {
+        return this.getAttribute(name) !== 'false';
+    }
+
+    private _offByDefault(name: string): boolean {
+        return this.hasAttribute(name);
+    }
+
+    connectedCallback() {
+        if (this._initialized) {
+            this._watchTitlebar();
+            this._render();
+            return;
+        }
+        this._initialized = true;
+
+        this._titlebar = document.createElement('div');
+        this._titlebar.className = 'adw-gtk-window-titlebar';
+        this._content = document.createElement('div');
+        this._content.className = 'adw-gtk-window-content';
+
+        bindSlottedChildren(this, [
+            { name: 'titlebar', into: this._titlebar },
+            ...this.extraSlots(),
+            { into: this._content },
+        ]).install(...this.strips());
+
+        // The `window.close` action the frame controls activate, answered by the window
+        // itself — `gtk_window_close` (gtkwindow.c:1274-1287). Left armed for the life of the
+        // element: it is a listener ON this, not a binding reaching outside it, so a move
+        // between parents costs nothing and nothing has to be re-armed.
+        this.addEventListener('window-action', (event) => this._onWindowAction(event));
+
+        this._watchTitlebar();
+        this._render();
+    }
+
+    disconnectedCallback() {
+        this._titlebarObserver?.disconnect();
+        this._titlebarObserver = null;
+    }
+
+    /**
+     * A `slot="titlebar"` child adopted AFTER the build has to take the strip over from the
+     * server-side decoration, and `_render` is the one that notices — nothing else here runs
+     * when a child lands. Observed on `_titlebar`, which is where the adopted child goes,
+     * because `bindSlottedChildren` already watches the host for it.
+     *
+     * Re-established on every connect, so a window moved between parents keeps it.
+     */
+    private _watchTitlebar(): void {
+        this._titlebarObserver?.disconnect();
+        this._titlebarObserver = new MutationObserver(() => this._render());
+        this._titlebarObserver.observe(this._titlebar, { childList: true });
+    }
+
+    /**
+     * The strips the frame is built from, in order. A subclass with a strip of its own —
+     * `<gtk-application-window>`'s menubar — adds it here, which is the only reason this pair
+     * exists: `install()` takes the structure and the slots at once, and the ORDER is that
+     * call's invariant (see `slotted-children.ts`).
+     */
+    protected strips(): Node[] {
+        return [this._titlebar, this._content];
+    }
+
+    /** The slots a subclass adds beside `titlebar`; none by default. */
+    protected extraSlots(): AdwSlot[] {
+        return [];
+    }
+
+    attributeChangedCallback(name: string) {
+        if (!this._initialized) return;
+        this._render();
+        this.dispatchEvent(
+            new CustomEvent(`notify::${name}`, { bubbles: true, detail: { [name]: this._property(name) } }),
+        );
+    }
+
+    private _property(name: string): boolean | number | string | null {
+        if (name === 'default-width' || name === 'default-height') {
+            const raw = Number.parseFloat(this.getAttribute(name) ?? '');
+            return Number.isFinite(raw) ? raw : null;
+        }
+        if (name === 'title' || name === 'icon-name' || name === 'transient-for') return this.getAttribute(name);
+        if (name === 'decorated' || name === 'resizable' || name === 'deletable') return this._onByDefault(name);
+        return this._offByDefault(name);
+    }
+
+    private _render(): void {
+        // `gtk_window_set_decorated` (gtkwindow.c:1014): no frame, no titlebar strip, and so
+        // nothing for the frame controls to hang in — a bar alone would still draw them.
+        this._titlebar.hidden = !this.decorated;
+        // `_window.scss:66-72` — maximized and fullscreen are the two states that square the
+        // frame off and drop its shadow.
+        this.classList.toggle('maximized', this.decorated && this.maximized);
+        this.classList.toggle('fullscreen', this.decorated && this._offByDefault('fullscreened'));
+
+        const width = Number.parseFloat(this.getAttribute('default-width') ?? '');
+        const height = Number.parseFloat(this.getAttribute('default-height') ?? '');
+        for (const [axis, value] of [
+            ['width', width],
+            ['height', height],
+        ] as const) {
+            if (Number.isFinite(value) && value > 0) this.style.setProperty(axis, `${value}px`);
+            else this.style.removeProperty(axis);
+        }
+
+        const title = this.getAttribute('title');
+        if (title === null) this.removeAttribute('aria-label');
+        else this.setAttribute('aria-label', title);
+        this._renderTitlebar();
+    }
+
+    /**
+     * The strip, in the two shapes a window can be in. With a `titlebar` child the strip
+     * holds exactly that — GTK hands the whole titlebar to the bar, decorations and all. With
+     * none it holds the two `<gtk-window-controls>` and the window's title, which is the
+     * server-side decoration GTK would otherwise have asked the window manager to draw and
+     * which a page has to draw for itself.
+     */
+    private _renderTitlebar(): void {
+        // The strip's OWN nodes do not count as an authored titlebar. `connectedCallback`
+        // re-runs `_render()` on every connect, and a check on `childElementCount` alone
+        // read the three SSD children this method had just built as somebody else's titlebar
+        // and removed them — so a window that had been moved between parents came back with an
+        // empty titlebar while a freshly built one kept its frame buttons.
+        const authored = [...this._titlebar.children].some(
+            (child) => child !== this._startControls && child !== this._endControls && child !== this._titleLabel,
+        );
+        if (authored) {
+            for (const own of [this._startControls, this._endControls, this._titleLabel]) own?.remove();
+            this._startControls = null;
+            this._endControls = null;
+            this._titleLabel = null;
+            return;
+        }
+        if (!this.decorated) return;
+
+        if (this._startControls === null) {
+            this._startControls = document.createElement('gtk-window-controls');
+            this._startControls.setAttribute('side', 'start');
+            this._endControls = document.createElement('gtk-window-controls');
+            this._endControls.setAttribute('side', 'end');
+            this._titleLabel = document.createElement('span');
+            this._titleLabel.className = 'adw-gtk-window-title';
+            this._titlebar.append(this._startControls, this._titleLabel, this._endControls);
+        }
+        const title = this.getAttribute('title');
+        if (title === null) this._titleLabel?.removeAttribute('title');
+        else this._titleLabel?.setAttribute('title', title ?? '');
+    }
+
+    /** The frame controls' `GtkActionable` names, answered here — gtkwindow.c:1274-1287. */
+    private _onWindowAction(event: Event): void {
+        const action = (event as CustomEvent<{ action: WindowAction }>).detail?.action;
+        if (action === 'toggle-maximized') {
+            this._write('maximized', String(!this._offByDefault('maximized')));
+            return;
+        }
+        if (action === 'close') this.close();
+    }
+
+    /**
+     * `gtk_window_close` (gtkwindow.c:1274-1287): emit `close-request` and, if nothing handled
+     * it, hide the window when `hide-on-close` is set and DESTROY it otherwise. "Destroy" is
+     * the one word this port cannot mean — a page has no unref — so the default detaches the
+     * frame, which is the same observable outcome for everything above it.
+     */
+    close(): boolean {
+        const request = new CustomEvent('close-request', { bubbles: true, cancelable: true });
+        this.dispatchEvent(request);
+        if (request.defaultPrevented) return false;
+        if (this._offByDefault('hide-on-close')) this.hidden = true;
+        else this.remove();
+        return true;
+    }
+
+    /**
+     * `gtk_window_maximize`. ASYNCHRONOUS in GTK — the GIR says so at gtkwindow.c:1044 — so
+     * the property is the thing a caller watches, and this writes it directly rather than
+     * pretending to round-trip a compositor.
+     */
+    maximize(): void {
+        this._write('maximized', 'true');
+    }
+
+    /** `gtk_window_unmaximize`, with the same caveat as {@link maximize}. */
+    unmaximize(): void {
+        this._write('maximized', 'false');
+    }
+}
+
+customElements.define('gtk-window', GtkWindow);

package/src/elements/justification.ts

@@ -0,0 +1,24 @@
+// Pango's justification switch, as a CSS `text-align` — the one place this package spells
+// it, because TWO widgets show justified text: `<gtk-label>` (through `Gtk.Label:justify`)
+// and `<gtk-text-view>` (through `Gtk.TextView:justification`). The enum is Pango's, not
+// either widget's: `gtk_text_view_set_justification` writes the same
+// `layout->default_style->justification` (gtktextview.c:3560-3573) that `gtk_label_set_justify`
+// writes, so the two properties take the same four nicks through the same layout field.
+//
+// LEFT and RIGHT are START and END of the TEXT DIRECTION, which is what the C means: a
+// justified label reads `Gtk.Justification.LEFT` in either direction and lands on the leading
+// edge. FILL is start-aligned lines with the spaces between words stretched, which is CSS
+// `justify`.
+//
+// `normalizeLabelJustify` (`@gjsify/adwaita-core`) is the reader of the nick, and it reads it
+// the same way for both widgets — which is what makes a shared table the right shape here
+// rather than a second switch.
+
+import type { LabelJustification } from '@gjsify/adwaita-core';
+
+export const JUSTIFY_TEXT_ALIGN: Record<LabelJustification, string> = {
+    left: 'start',
+    right: 'end',
+    center: 'center',
+    fill: 'justify',
+};

package/src/elements/popover-menu.ts

@@ -123,6 +123,30 @@ export class PopoverMenuView {
         return this._rows;
     }
 
+    /**
+     * The path of the page showing; `[]` is the root.
+     *
+     * Public because `GtkPopoverMenu:visible-submenu` IS this: GTK's value is the
+     * `GtkStack` child's name (gtkpopovermenu.c:755-757), and the stack child's identity
+     * here is the path that leads to it. Reading it is how the element answers the
+     * property without keeping a second copy of the open page beside this one.
+     */
+    get page(): AdwMenuPath {
+        return this._page;
+    }
+
+    /**
+     * Point the view at `path` without rendering — {@link render} does that, and doing it
+     * here as well would rebuild the rows twice per change.
+     *
+     * Distinct from {@link reset} because it NAMES the destination: a popover menu can be
+     * opened straight into a submenu, and a caller that had to open the parent first and
+     * then click into it would be reporting the reader's journey as the widget's state.
+     */
+    showPage(path: AdwMenuPath): void {
+        this._page = [...path];
+    }
+
     /**
      * The rows a key can actually REACH, which is the only list worth focusing into.
      *