@gjsify/adwaita-web 0.53.0 → 0.55.0

package/src/elements/gtk-grid-view.ts

@@ -0,0 +1,168 @@
+// <gtk-grid-view> — the same model and factory as `<gtk-list-view>`, reflowed into
+// columns: the web counterpart of `Gtk.GridView`.
+//
+// `GtkGridView` IS a `GtkListBase`, exactly as `GtkListView` is — same model, same
+// factory, same selection function, same rubberband — and the only thing it adds is HOW
+// MANY COLUMNS fit. So this element extends `<gtk-list-view>` and adds that one
+// derivation, rather than restating a second copy of the item machinery. GTK's own CSS
+// node names say the same thing from the other side: a list view's children are `row`,
+// a grid view's are `child`, and nothing else in the node tree differs.
+//
+// THE COLUMN COUNT IS MEASURED, NOT GUESSED. `gridViewColumns` in `@gjsify/adwaita-core`
+// is `gtk_grid_view_compute_n_columns` (gtkgridview.c:619-641) — integer division of the
+// available size by the item size, both sides carrying the spacing, then
+// `CLAMP (n, min-columns, max-columns)`. A `ResizeObserver` feeds it the view's own width
+// and the first child's, which is the browser's equivalent of the size negotiation GTK
+// runs; the result is written as `repeat(n, 1fr)` so the tracks stay equal, as GTK's do.
+//
+// A pure CSS `repeat(auto-fill, minmax(…))` was the alternative and was rejected: it
+// cannot express `max-columns` at all (the cap is on the COUNT, not on a width), and
+// `min-columns` only by a container width an author would have to compute — so the
+// property pair GTK documents would have become two properties the port silently drops.
+//
+// Attributes: model, selection-mode, single-click-activate, enable-rubberband,
+//   tab-behavior, orientation (all `<gtk-list-view>`'s), plus `min-columns` and
+//   `max-columns`, which are `GtkGridView`'s own.
+// Properties: everything `<gtk-list-view>` publishes, plus minColumns / maxColumns.
+// Events: `activate`, `notify::selected` — the base element's.
+// A11Y: `listbox` / `option`, inherited. GTK declares `GRID`/`GRID_CELL`
+//   (gtkgridview.c:88-91), and the ARIA `grid` pattern needs a `row` layer between the
+//   two that this widget has no concept of — its items are addressed by POSITION, never
+//   by row and column — so announcing a grid would promise a navigation that is not there.
+//
+// Reference: refs/gtk/gtk/gtkgridview.c:44-92 (the widget, its CSS nodes and its role)
+// Reference: refs/gtk/gtk/gtkgridview.c:619-641, 1147-1167 (the count and its two bounds)
+// Reference: refs/libadwaita/src/stylesheet/widgets/_views.scss:52-91 (gridview > child)
+// Copyright (c) GNOME contributors (GTK/libadwaita). LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+import { ADW_GRID_VIEW_MAX_COLUMNS, ADW_GRID_VIEW_MIN_COLUMNS, gridViewColumns } from '@gjsify/adwaita-core';
+
+import { GtkListView } from './gtk-list-view.js';
+
+/** The gap between cells — what `_grid_view.scss` sets, and the answer with no stylesheet. */
+const GRID_SPACING = 6;
+
+/** What `_grid_view.scss` floors a cell at, and the answer with no stylesheet. */
+const GRID_ITEM_MIN_WIDTH = 120;
+
+/**
+ * A computed length in px, or `fallback` where CSS answered a keyword.
+ *
+ * Both lengths this element reads have a keyword for "unset" — `min-width: auto` on a grid
+ * item, `column-gap: normal` — and both are numbers the stylesheet owns, so the fallback is
+ * only reached when no stylesheet is loaded at all. A declared `0px` is NOT a fallback: the
+ * column arithmetic has its own answer for a zero-sized item and must get to give it.
+ */
+function cssPixels(value: string, fallback: number): number {
+    const parsed = Number.parseFloat(value);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+export class GtkGridView extends GtkListView {
+    private _observer: ResizeObserver | null = null;
+
+    static get observedAttributes() {
+        return [
+            'model',
+            'selection-mode',
+            'single-click-activate',
+            'enable-rubberband',
+            'tab-behavior',
+            'orientation',
+            'min-columns',
+            'max-columns',
+        ];
+    }
+
+    /** `GtkGridView:min-columns` — at least one, as the ParamSpec's range says. */
+    get minColumns(): number {
+        return this._columnBound('min-columns', ADW_GRID_VIEW_MIN_COLUMNS);
+    }
+
+    set minColumns(value: number) {
+        this.setAttribute('min-columns', String(value));
+    }
+
+    /** `GtkGridView:max-columns` — `DEFAULT_MAX_COLUMNS` is 7 (gtkgridview.c:42). */
+    get maxColumns(): number {
+        return this._columnBound('max-columns', ADW_GRID_VIEW_MAX_COLUMNS);
+    }
+
+    set maxColumns(value: number) {
+        this.setAttribute('max-columns', String(value));
+    }
+
+    connectedCallback() {
+        super.connectedCallback();
+        if (this._observer !== null) return;
+        // The view's width AND the first cell's: the count is a ratio of the two, and a
+        // factory that lays out late changes the second without changing the first.
+        this._observer = new ResizeObserver(() => this._applyColumns());
+        this._observer.observe(this);
+        this._applyColumns();
+    }
+
+    disconnectedCallback() {
+        // Cleanup beside creation: an observer outliving its element keeps the whole
+        // subtree alive and keeps measuring a box nothing draws.
+        this._observer?.disconnect();
+        this._observer = null;
+    }
+
+    attributeChangedCallback(name?: string) {
+        super.attributeChangedCallback(name);
+        this._applyColumns();
+    }
+
+    protected override get _viewClass(): string {
+        return 'adw-grid-view';
+    }
+
+    protected override get _rowClass(): string {
+        // `gridview > child`, where a list view has `listview > row`.
+        return 'adw-grid-view-child';
+    }
+
+    protected override _renderRows(): void {
+        super._renderRows();
+        this._applyColumns();
+    }
+
+    /** An attribute that is not a positive integer is the property's default, not NaN. */
+    private _columnBound(attribute: string, fallback: number): number {
+        const parsed = Number.parseInt(this.getAttribute(attribute) ?? '', 10);
+        return Number.isFinite(parsed) && parsed >= 1 ? parsed : fallback;
+    }
+
+    /**
+     * Measure, count, and write the tracks.
+     *
+     * THE ITEM SIZE IS THE CELL'S `min-width`, NOT ITS RENDERED WIDTH, and the difference
+     * is the whole reason this is three lines rather than one. The tracks are written as
+     * `1fr`, so a rendered cell is as wide as the count made it: feeding that back in
+     * would measure the answer and converge on whatever the first frame happened to do.
+     * `min-width` is a fact about the CONTENT instead, declared by the stylesheet and
+     * overridable per cell — and it is the branch GTK itself takes under
+     * `GTK_SCROLL_MINIMUM` (gtkgridview.c:628-630). The natural-size branch needs a
+     * measurement a browser can only take by first undoing the layout the answer feeds.
+     *
+     * The gap is read the same way, off the container's own `column-gap`, so the two
+     * numbers the arithmetic takes come from ONE place — the stylesheet — and an author
+     * who widens the gap does not get a column count computed against the old one.
+     *
+     * An empty view keeps the tracks it had: there is nothing to measure, and no cell for
+     * the answer to be wrong about.
+     */
+    private _applyColumns(): void {
+        const first = this._rows[0];
+        if (first === undefined) return;
+        const itemSize = cssPixels(globalThis.getComputedStyle(first).minWidth, GRID_ITEM_MIN_WIDTH);
+        const spacing = cssPixels(globalThis.getComputedStyle(this._listEl).columnGap, GRID_SPACING);
+        const forSize = Math.round(this.getBoundingClientRect().width);
+        const columns = gridViewColumns(forSize, itemSize, spacing, this.minColumns, this.maxColumns);
+        this._listEl.style.gridTemplateColumns = `repeat(${columns}, 1fr)`;
+    }
+}
+
+customElements.define('gtk-grid-view', GtkGridView);

package/src/elements/gtk-grid.ts

@@ -0,0 +1,127 @@
+// <gtk-grid> — Gtk.Grid: a table of cells, each the size of its own content unless the
+// grid is asked to make them equal.
+//
+// FOUR SCALAR PROPERTIES, and CSS Grid already has every one of them.
+//
+//   `row-spacing` / `column-spacing`  the gap between two consecutive rows / columns
+//       (gtkgrid.c:429-447: an int, minimum 0, default 0 — the same pspec as `Gtk.Box`'s
+//       `spacing`, so `normalizeBoxSpacing` is the same reader for both).
+//   `row-homogeneous` / `column-homogeneous`  every row the same height / every column the
+//       same width (gtkgrid.c:449-470, both default FALSE).
+//   `orientation` (GtkOrientable, gtkgrid.c:198-211, :481-484) which way a child with no
+//       position of its own is attached: along the columns, or down the rows.
+//
+// PLACEMENT IS SOURCE ORDER, which is what GtkBuilder itself does: a child written without
+// a position is attached at the first free cell ALONG THE ORIENTATION (gtkgrid.c:493-507,
+// `find_attach_position`), which searches the CROSS range that starts at 0 and takes the
+// maximum position along the orientation one — so the child lands at row 0, column N for a
+// horizontal grid, and never wraps. That is `grid-auto-flow: column` here (the implicit
+// grid has no rows, so every item takes the single row and opens a new column), and the
+// vertical case is the mirror. `gtk_grid_attach()` for a named cell is the imperative route
+// and has no markup form here — the gallery trees carry no layout data either, because
+// `SharedTreeNode` has no field for it.
+//
+// WHAT `1fr` IS NOT. GTK sets every line's minimum AND natural to the maximum over all
+// lines (gtkgridlayout.c:703-732), so a homogeneous column is as wide as the WIDEST cell
+// whatever it holds. A `1fr` track instead takes an equal share of the space the grid is
+// given, which is the same answer whenever the grid fills its parent — the shape every
+// block here has, and the shape a `Gtk.Grid` in a window has — and a different one for a
+// shrink-wrapped grid. For ROWS the two only meet when the grid is given a definite height,
+// because an auto-height grid has no free space to share; that is the whole of the
+// divergence and it is declared rather than measured away.
+//
+// A11Y: `role="generic"`, GtkGrid's own accessible role (gtkgrid.c:488).
+//
+// Reference: refs/gtk/gtk/gtkgrid.c:198-211, :429-488, :493-507
+// Reference: refs/gtk/gtk/gtkgridlayout.c:703-732
+// Copyright (c) The GTK Team. LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+import { normalizeBoxOrientation, normalizeBoxSpacing, type BoxOrientation } from '@gjsify/adwaita-core';
+
+export class GtkGrid extends HTMLElement {
+    static get observedAttributes() {
+        return ['column-spacing', 'row-spacing', 'column-homogeneous', 'row-homogeneous', 'orientation'];
+    }
+
+    /** `Gtk.Grid:column-spacing` — the gap between two consecutive columns. Defaults to 0. */
+    get columnSpacing(): number {
+        return normalizeBoxSpacing(this.getAttribute('column-spacing'));
+    }
+
+    set columnSpacing(value: number) {
+        this.setAttribute('column-spacing', String(value));
+    }
+
+    /** `Gtk.Grid:row-spacing` — the gap between two consecutive rows. Defaults to 0. */
+    get rowSpacing(): number {
+        return normalizeBoxSpacing(this.getAttribute('row-spacing'));
+    }
+
+    set rowSpacing(value: number) {
+        this.setAttribute('row-spacing', String(value));
+    }
+
+    /** `Gtk.Grid:column-homogeneous` — whether every column gets the same width. */
+    get columnHomogeneous(): boolean {
+        return this.hasAttribute('column-homogeneous');
+    }
+
+    set columnHomogeneous(value: boolean) {
+        this.toggleAttribute('column-homogeneous', !!value);
+    }
+
+    /** `Gtk.Grid:row-homogeneous` — whether every row gets the same height. */
+    get rowHomogeneous(): boolean {
+        return this.hasAttribute('row-homogeneous');
+    }
+
+    set rowHomogeneous(value: boolean) {
+        this.toggleAttribute('row-homogeneous', !!value);
+    }
+
+    /**
+     * `GtkOrientable:orientation` — the axis a child with no position of its own is
+     * attached along. `horizontal` (the default) appends each one to ROW 0 at the next
+     * free column, `vertical` to COLUMN 0 at the next free row.
+     */
+    get orientation(): BoxOrientation {
+        return normalizeBoxOrientation(this.getAttribute('orientation'));
+    }
+
+    set orientation(value: BoxOrientation) {
+        this.setAttribute('orientation', value);
+    }
+
+    connectedCallback() {
+        this.setAttribute('role', 'generic');
+        this._sync();
+    }
+
+    attributeChangedCallback(name: string, old: string | null, value: string | null) {
+        this._sync();
+        if (!this.isConnected) return;
+        const next = this._normalized(name, value);
+        if (next === this._normalized(name, old)) return;
+        this.dispatchEvent(new CustomEvent(`notify::${name}`, { bubbles: true, detail: { [name]: next } }));
+    }
+
+    private _normalized(name: string, raw: string | null): number | boolean | string {
+        if (name === 'column-spacing' || name === 'row-spacing') return normalizeBoxSpacing(raw);
+        if (name === 'orientation') return normalizeBoxOrientation(raw);
+        return raw !== null;
+    }
+
+    private _sync(): void {
+        // `gap` takes the ROW axis first, which is the reverse of the pair's alphabetical
+        // order here; writing the two longhands keeps the mapping to the two properties
+        // visible instead of hiding it in one shorthand.
+        this.style.rowGap = `${this.rowSpacing}px`;
+        this.style.columnGap = `${this.columnSpacing}px`;
+        this.style.gridAutoRows = this.rowHomogeneous ? '1fr' : '';
+        this.style.gridAutoColumns = this.columnHomogeneous ? '1fr' : '';
+        this.style.gridAutoFlow = this.orientation === 'vertical' ? 'row' : 'column';
+    }
+}
+
+customElements.define('gtk-grid', GtkGrid);

package/src/elements/gtk-header-bar.ts

@@ -0,0 +1,273 @@
+// <gtk-header-bar> — GTK's titlebar widget: a horizontal bar that packs children at the
+// start and at the end and shows the window's title in the middle, with the window-frame
+// buttons GTK would otherwise ask the window manager for.
+//
+// THE CSS TREE, PORTED VERBATIM (gtkheaderbar.c:99-116, `gtk_header_bar_init` :649-675):
+//
+//   headerbar
+//   ╰── windowhandle
+//       ╰── box
+//           ├── box.start ── [windowcontrols.start] ── [other children]
+//           ├── [Title Widget]
+//           ╰── box.end ──── [other children] ──────── [windowcontrols.end]
+//
+// The centre is the `GtkCenterBox`'s centre child, so the title is centred on the WHOLE bar
+// rather than on the space the two ends leave — which is why `_box` lays out as a flex row
+// with `order` on the three children and the title's own box is `flex: 1`.
+//
+// THE THREE WAYS A CHILD GETS THERE (gtkheaderbar.c:678-701, `gtk_header_bar_pack` :843-861):
+//   `start` packs from the start — an APPEND; `end` packs from the end — a PREPEND, so the
+//   first `[end]` child sits nearest the edge and each later one lands in front of it; a
+//   child with NO type packs from the start. There is no `center` slot: the centre is
+//   `title-widget`, and the buildable's `"title"` is the DEPRECATED spelling of it
+//   (gtkheaderbar.c:683-686), so both spellings are accepted here as well.
+//
+// THE DERIVED TITLE IS A LABEL, NOT A WINDOW TITLE. `construct_title_label` (gtkheaderbar.c:274-290)
+// builds a plain `GtkLabel` — `title` style class, `valign=center`, no wrap,
+// `single-line-mode`, `ellipsize=END`, `width-chars=5` (MIN_TITLE_CHARS, :117) — and
+// `Gtk.HeaderBar` has no `title` property at all. `update_title` (:250-271) fills it from
+// the ROOT window's title, and failing that from `g_get_application_name()`, and failing
+// THAT from `g_get_prgname()`. This element reproduces the first step against the nearest
+// `<gtk-window>`/`<adw-window>` ancestor; for the two GLib fallbacks — a PROCESS name, which
+// is what those two are — the page's own `<title>` is the only thing a browser has, and it is
+// the same fact one level up. An app that wants something richer sets a `slot="title"`
+// child, which is the whole of `Gtk.HeaderBar:title-widget`.
+//
+// THE EITHER/OR, IN BOTH DIRECTIONS. `gtk_header_bar_set_title_widget` empties the centre
+// bin before installing (:319-341) and rebuilds the derived label when the widget goes back
+// to NULL (:332-336) — so a centre widget takes the title away and GIVING IT BACK restores
+// it, which is the asymmetry `<adw-header-bar>` documents as its own missing half.
+//
+// `show-title-buttons` (default TRUE, :657) is what CREATES the two controls and what
+// REMOVES them again (:798-826): `create_window_controls` builds a `GTK_PACK_START` one,
+// PREPENDS it into the start box and binds `decoration-layout` and `use-native-controls` to
+// it, then builds a `GTK_PACK_END` one, APPENDS it into the end box and binds the same two
+// properties. The `empty`↔`visible` binding beside them (:238, :247) is why a bar with no
+// buttons for its side shows nothing at all. `Gtk.WindowControls` draws those buttons from
+// the FRAME it sits in, so a bar outside a window shows none either way.
+//
+// `default-decoration` — the 37px variant libadwaita draws at `_header-bar.scss:53-75` — is
+// NOT derived here. It is set by `update_default_decoration` (:205-236), and only a
+// `GtkWindow` that installs an EMPTY header bar for itself ever asks for it, through the
+// internal `_gtk_header_bar_track_default_decoration` (:242-248). A bar that has children is
+// never in that mode, and one the page wrote is never empty.
+//
+// A11Y: `role="group"`, GtkHeaderBar's own accessible role (:644).
+//
+// Reference: refs/gtk/gtk/gtkheaderbar.c
+// Reference: refs/libadwaita/src/stylesheet/widgets/_header-bar.scss (GtkHeaderBar)
+// Copyright (c) The GTK Team. LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+import { bindSlottedChildren } from '../slotted-children.js';
+
+// Registers <gtk-window-controls>: `show-title-buttons` builds two of them, so importing
+// the bar alone must still define them.
+import './gtk-window-controls.js';
+
+export class GtkHeaderBar extends HTMLElement {
+    private _initialized = false;
+    private _handle!: HTMLDivElement;
+    private _box!: HTMLDivElement;
+    private _startBox!: HTMLDivElement;
+    private _endBox!: HTMLDivElement;
+    /** The two `GtkWindowControls`, present only while `show-title-buttons` is true (:798-826). */
+    private _startControls: HTMLElement | null = null;
+    private _endControls: HTMLElement | null = null;
+    /** The derived `GtkLabel`, or `null` while a `title-widget` holds the centre. */
+    private _titleLabel: HTMLElement | null = null;
+    /** The child that took the centre — read back out of `_box`, never stored as truth. */
+    private _centre: HTMLElement | null = null;
+    private _centreObserver: MutationObserver | null = null;
+
+    static get observedAttributes() {
+        return ['decoration-layout', 'show-title-buttons'];
+    }
+
+    /** `Gtk.HeaderBar:decoration-layout` — bound to both controls (:231-236, :240-245). */
+    get decorationLayout(): string | null {
+        return this.getAttribute('decoration-layout');
+    }
+
+    set decorationLayout(value: string | null) {
+        if (value === null) this.removeAttribute('decoration-layout');
+        else this._write('decoration-layout', value);
+    }
+
+    /** `Gtk.HeaderBar:show-title-buttons` — whether the standard frame controls are built. */
+    get showTitleButtons(): boolean {
+        return this.getAttribute('show-title-buttons') !== 'false';
+    }
+
+    set showTitleButtons(value: boolean) {
+        this._write('show-title-buttons', String(value));
+    }
+
+    /** `Gtk.HeaderBar:title-widget`, read as the element that holds the centre — or `null`. */
+    get titleWidget(): HTMLElement | null {
+        return this._centre;
+    }
+
+    /** `setAttribute` for a write that changes nothing; every GObject setter here returns early. */
+    private _write(name: string, value: string): void {
+        if (this.getAttribute(name) !== value) this.setAttribute(name, value);
+    }
+
+    connectedCallback() {
+        if (this._initialized) {
+            this._followCentre();
+            return;
+        }
+        this._initialized = true;
+
+        this.setAttribute('role', 'group');
+
+        this._startBox = document.createElement('div');
+        this._startBox.className = 'adw-gtk-header-bar-start';
+        this._endBox = document.createElement('div');
+        this._endBox.className = 'adw-gtk-header-bar-end';
+        this._box = document.createElement('div');
+        this._box.className = 'adw-gtk-header-bar-box';
+        this._box.append(this._startBox, this._endBox);
+        this._handle = document.createElement('div');
+        this._handle.className = 'adw-gtk-header-bar-handle';
+        this._handle.appendChild(this._box);
+
+        this._renderTitleButtons();
+
+        bindSlottedChildren(this, [
+            { name: 'start', into: this._startBox },
+            { name: 'title', into: this._box },
+            // The DEPRECATED buildable spelling of the same slot (:683-686), kept because a
+            // tree authored at the property position writes it.
+            { name: 'title-widget', into: this._box },
+            // `end` is a CONSUME, not an `into` slot: `gtk_header_bar_pack_end` is a PREPEND
+            // (gtkheaderbar.c:847-858) and a slot with an `into` is routed with `appendChild`
+            // whichever `consume` it also carries, so the two together quietly packed the end
+            // in the wrong order.
+            { name: 'end', consume: (node) => this._endBox.prepend(node) },
+            // An untyped `<child>` packs from the start (:698).
+            { into: this._startBox },
+        ]).install(this._handle);
+
+        this._followCentre();
+    }
+
+    disconnectedCallback() {
+        this._centreObserver?.disconnect();
+        this._centreObserver = null;
+    }
+
+    attributeChangedCallback(name: string) {
+        if (!this._initialized) return;
+        if (name === 'show-title-buttons') this._renderTitleButtons();
+        else this._bindDecorationLayout();
+        this.dispatchEvent(
+            new CustomEvent(`notify::${name}`, { bubbles: true, detail: { [name]: this._property(name) } }),
+        );
+    }
+
+    private _property(name: string): boolean | string | null {
+        return name === 'show-title-buttons' ? this.showTitleButtons : this.decorationLayout;
+    }
+
+    /**
+     * `create_window_controls` and its inverse, `gtk_header_bar_set_show_title_buttons`
+     * (gtkheaderbar.c:198-249, :798-826): the start controls are PREPENDED into the start
+     * box, the end controls APPENDED into the end box, and setting the property false
+     * REMOVES both — which is why a bar with the property off has no controls at all rather
+     * than hidden ones.
+     */
+    private _renderTitleButtons(): void {
+        if (!this.showTitleButtons) {
+            this._startControls?.remove();
+            this._endControls?.remove();
+            this._startControls = null;
+            this._endControls = null;
+            return;
+        }
+        if (this._startControls === null) {
+            this._startControls = document.createElement('gtk-window-controls');
+            this._startControls.setAttribute('side', 'start');
+            this._startBox.prepend(this._startControls);
+            this._endControls = document.createElement('gtk-window-controls');
+            this._endControls.setAttribute('side', 'end');
+            this._endBox.appendChild(this._endControls);
+        }
+        this._bindDecorationLayout();
+    }
+
+    /** The two `G_BINDING_SYNC_CREATE` bindings onto the controls (:229-247). */
+    private _bindDecorationLayout(): void {
+        for (const controls of [this._startControls, this._endControls]) {
+            if (controls === null) continue;
+            const layout = this.decorationLayout;
+            if (layout === null) controls.removeAttribute('decoration-layout');
+            else controls.setAttribute('decoration-layout', layout);
+        }
+    }
+
+    /**
+     * The two things `gtk_header_bar_root` connects to (gtkheaderbar.c:362-376): the centre
+     * either/or, which changes what belongs in the middle in BOTH directions — `set_title_widget`
+     * empties the bin before installing and rebuilds the derived label when it is handed back
+     * to NULL (:319-341) — and `notify::title` on the ROOT, which re-runs `update_title`.
+     */
+    private _followCentre(): void {
+        this._centreObserver?.disconnect();
+        this._centreObserver = new MutationObserver(() => this._syncCentre());
+        // `_box`'s only other children are the two side boxes and the derived label itself.
+        this._centreObserver.observe(this._box, { childList: true });
+        const root = this.closest('gtk-window, adw-window');
+        if (root !== null) {
+            this._centreObserver.observe(root, { attributes: true, attributeFilter: ['title'] });
+        }
+        this._syncCentre();
+    }
+
+    /** The child of `_box` that is neither a side box nor the derived label. */
+    private _centreChild(): HTMLElement | null {
+        for (const child of this._box.children) {
+            if (child === this._startBox || child === this._endBox || child === this._titleLabel) continue;
+            if (child instanceof HTMLElement) return child;
+        }
+        return null;
+    }
+
+    private _syncCentre(): void {
+        this._centre = this._centreChild();
+        if (this._centre !== null) this._dropTitleLabel();
+        else if (this._titleLabel === null) this._constructTitleLabel();
+        else this._updateTitle();
+    }
+
+    /** `construct_title_label` (gtkheaderbar.c:274-290), with `width-chars=5` as CSS. */
+    private _constructTitleLabel(): void {
+        const label = document.createElement('gtk-label');
+        label.className = 'title adw-gtk-header-bar-title';
+        this._titleLabel = label;
+        this._box.appendChild(label);
+        this._updateTitle();
+    }
+
+    /** `gtk_header_bar_set_title_widget`'s first act: the centre bin goes empty (:323). */
+    private _dropTitleLabel(): void {
+        this._titleLabel?.remove();
+        this._titleLabel = null;
+    }
+
+    /**
+     * `update_title` (gtkheaderbar.c:250-271): the root window's title, then the two GLib
+     * process-name fallbacks — which is what the page's own `<title>` stands in for here.
+     */
+    private _updateTitle(): void {
+        const label = this._titleLabel;
+        if (label === null) return;
+        const root = this.closest('gtk-window, adw-window');
+        const title = root?.getAttribute('title') ?? document.title;
+        if (title === '') label.removeAttribute('label');
+        else label.setAttribute('label', title);
+    }
+}
+
+customElements.define('gtk-header-bar', GtkHeaderBar);