@gjsify/adwaita-web 0.54.0 → 0.56.0

package/lib/types/elements/gtk-stack.d.ts

@@ -0,0 +1,154 @@
+/** `GtkStackTransitionType`, spelled as the GIR's enum nicks (gtkstack.c:95-121). */
+export type StackTransitionType = 'none' | 'crossfade' | 'slide-right' | 'slide-left' | 'slide-up' | 'slide-down' | 'slide-left-right' | 'slide-up-down' | 'over-up' | 'over-down' | 'over-left' | 'over-right' | 'under-up' | 'under-down' | 'under-left' | 'under-right' | 'over-up-down' | 'over-down-up' | 'over-left-right' | 'over-right-left' | 'rotate-left' | 'rotate-right' | 'rotate-left-right';
+/** The browser's page descriptor — the stand-in for the `GtkStackPage` GObject. */
+export interface GtkStackPageInfo {
+    /** `GtkStackPage:name`, `''` for a page with no `name` attribute. */
+    name: string;
+    /** `GtkStackPage:title` — `null` when absent, which is C's NULL and means NO label. */
+    title: string | null;
+    /** `GtkStackPage:icon-name` — `null` when absent. */
+    iconName: string | null;
+    /** `GtkStackPage:needs-attention`. */
+    needsAttention: boolean;
+    /** `GtkStackPage:use-underline`. */
+    useUnderline: boolean;
+    /** `GtkStackPage:visible` AND `GtkWidget:visible` — the child's `hidden` attribute. */
+    visible: boolean;
+    /** `GtkStackPage:child`: the page's own node. */
+    child: HTMLElement;
+}
+export declare class GtkStack extends HTMLElement {
+    /** The child that is visible, or `null` — C's `priv->visible_child`. */
+    private _visible;
+    /** C's `priv->last_visible_child`: the page being animated away. */
+    private _lastVisible;
+    private _initialized;
+    private _initializedChildren;
+    private _observer;
+    private _timer;
+    private _running;
+    static get observedAttributes(): string[];
+    /** `Gtk.Stack:visible-child-name` — the name of the visible child. */
+    get visibleChildName(): string | null;
+    set visibleChildName(v: string | null);
+    /**
+     * `Gtk.Stack:visible-child` as the browser can spell it: the visible child ELEMENT
+     * (the C property takes a `Gtk.Widget`, which no attribute can carry). Writes go
+     * through the child's own `name`, so it is `visible-child-name` that is read back.
+     */
+    get visibleChild(): HTMLElement | null;
+    set visibleChild(child: HTMLElement | null);
+    /** `Gtk.Stack:transition-type`. An unknown nick reads as `none`, the GIR default. */
+    get transitionType(): StackTransitionType;
+    set transitionType(v: StackTransitionType);
+    /** `Gtk.Stack:transition-duration` in milliseconds. `0` disables the animation. */
+    get transitionDuration(): number;
+    set transitionDuration(v: number);
+    /**
+     * `Gtk.Stack:hhomogeneous` — the same width for every child. Defaults to TRUE
+     * (gtkstack.c:981-987), which is why this one is NOT a boolean attribute: an absent
+     * attribute already means true, so the spelling has to be able to say false.
+     */
+    get hhomogeneous(): boolean;
+    set hhomogeneous(v: boolean);
+    /** `Gtk.Stack:vhomogeneous` — the same height for every child. Defaults to TRUE. */
+    get vhomogeneous(): boolean;
+    set vhomogeneous(v: boolean);
+    /** `Gtk.Stack:interpolate-size` — let the size change smoothly too. */
+    get interpolateSize(): boolean;
+    set interpolateSize(v: boolean);
+    /** `Gtk.Stack:transition-running` — READ-ONLY; reflected for the stylesheet. */
+    get transitionRunning(): boolean;
+    /**
+     * `Gtk.Stack:pages` — the page descriptors in child order, the browser half of the
+     * `GtkStackPages` selection model (gtkstack.c:698-745).
+     */
+    get pages(): GtkStackPageInfo[];
+    /** `gtk_stack_get_child_by_name` (gtkstack.c:1889-1916), `null` when not found. */
+    getChildByName(name: string): HTMLElement | null;
+    /** `gtk_stack_get_page` (gtkstack.c:1870-1887) as a descriptor, `null` when absent. */
+    getPage(child: HTMLElement): GtkStackPageInfo | null;
+    /** `gtk_stack_pages_is_selected` (gtkstack.c:647-666) for the model this element is. */
+    isSelected(child: HTMLElement): boolean;
+    /** `gtk_stack_add_titled` (gtkstack.c:1644-1663) — append a named, titled child. */
+    addTitled(child: HTMLElement, name: string | null, title?: string | null): HTMLElement;
+    /** `gtk_stack_add_named` (gtkstack.c:1687-1696). */
+    addNamed(child: HTMLElement, name: string | null): HTMLElement;
+    /** `gtk_stack_add_child` (gtkstack.c:1665-1685) — the unnamed form. */
+    addChild(child: HTMLElement): HTMLElement;
+    /**
+     * `gtk_stack_remove` (gtkstack.c:1834-1868), named `removePage` because
+     * `HTMLElement.remove()` already occupies the short spelling — the same rename
+     * `Adw.ViewStack.remove` took in `adw-view-stack.ts`.
+     */
+    removePage(child: HTMLElement): void;
+    /**
+     * `gtk_stack_set_visible_child` (gtkstack.c:2244-2281), with `gtk_stack_set_visible_
+     * child_full`'s per-call transition (gtkstack.c:2306-2334). A child that is not in
+     * this stack, or whose page is not visible, changes nothing — C warns and returns.
+     */
+    setVisibleChild(child: HTMLElement | null, transitionType?: StackTransitionType): boolean;
+    /** `gtk_stack_set_visible_child_name` (gtkstack.c:2283-2304). */
+    setVisibleChildName(name: string | null): boolean;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string): void;
+    /**
+     * The `notify::` detail for `name`: the PROPERTY, parsed, not the raw attribute —
+     * `transition-type` in particular reads as `none` for an unknown nick.
+     */
+    private _property;
+    private _notify;
+    private _write;
+    /** A boolean property that DEFAULTS TO TRUE: absent means true, like C's spec. */
+    private _flag;
+    /**
+     * `Gtk.Stack:transition-duration`, the `g_param_spec_uint` default of 200
+     * (gtkstack.c:1024). An unparseable or negative value is the uint clamp to 0 that
+     * the property's own range produces (gtkstack.c:1051-1060), and 0 is what stops the
+     * transition from starting at all (gtkstack.c:1402-1403).
+     */
+    private _duration;
+    /** The pages, in child order — `priv->children`, never the shadow root. */
+    private _children;
+    /** The page descriptor of one child (gtkstack.c:499-573). */
+    private _page;
+    /** `set_visible_child`'s "pick first visible" scan (gtkstack.c:1437-1450). */
+    private _firstVisible;
+    private _initChild;
+    private _onChildMutations;
+    /** C's NULL page name is an ABSENT attribute, not the empty string (gtkstack.c:2216). */
+    private _nameOrNull;
+    /**
+     * `set_visible_child` (gtkstack.c:1428-1586) reduced to what a browser can decide,
+     * with the guards kept in C's order. Returns whether the visible child changed.
+     */
+    private _show;
+    /**
+     * `gtk_stack_start_transition` (gtkstack.c:1389-1426) with
+     * `get_effective_transition_type` (gtkstack.c:1320-1390) and, for a two-way type,
+     * `get_simple_transition_type` on the page ORDER (gtkstack.c:1539-1561,
+     * :1162-1200). The result is always a SIMPLE type, which is what the stylesheet
+     * keys on — C resolves the two-way pair into one of the one-directional types
+     * before the animation starts, and so does this.
+     */
+    private _startTransition;
+    /**
+     * `i_first` (gtkstack.c:1548-1557): whether the incoming page was ADDED EARLIER than
+     * the outgoing one. C walks the children from the start and breaks on whichever it
+     * meets first, so the answer is a comparison of positions.
+     */
+    private _newChildFirst;
+    /** `get_effective_transition_type` (gtkstack.c:1320-1390): reduced motion, then RTL. */
+    private _effectiveType;
+    /** `gtk_widget_get_settings`'s `gtk-interface-reduced-motion`, read from the media query. */
+    private _reducedMotion;
+    /**
+     * The render pass: which page is visible, which is animating out, and the two
+     * `aria-hidden` states GTK raises on the PAGES (gtkstack.c:1526-1532, :1543-1547,
+     * :1610-1613). `hidden` is never written — it is the author's own
+     * `GtkStackPage:visible`, and overwriting it would destroy the distinction C keeps
+     * between the page flag and the widget's own visibility.
+     */
+    private _render;
+}

package/lib/types/elements/gtk-switch.d.ts

@@ -13,9 +13,12 @@ export declare class GtkSwitch extends HTMLElement {
      */
     get unfocusable(): boolean;
     set unfocusable(value: boolean);
-    /** Whether the switch is on. */
+    /** Whether the user put the switch ON. Drives the knob. */
     get active(): boolean;
     set active(value: boolean);
+    /** `Gtk.Switch:state` — what the switched thing currently is. Drives the trough. */
+    get state(): boolean;
+    set state(value: boolean);
     /** Whether the switch is inert. */
     get disabled(): boolean;
     set disabled(value: boolean);

package/lib/types/elements/gtk-text-view.d.ts

@@ -0,0 +1,62 @@
+import { type LabelJustification } from '@gjsify/adwaita-core';
+/** `Gtk.WrapMode`'s four nicks, in enum order — Pango's enum, and the DEFAULT is `none`. */
+declare const WRAP_MODES: readonly ["none", "char", "word", "word-char"];
+type TextViewWrapMode = (typeof WRAP_MODES)[number];
+export declare class GtkTextView extends HTMLElement {
+    private _area;
+    private _initialized;
+    static get observedAttributes(): string[];
+    /** The buffer's text — the light-DOM text of the element, then whatever is typed. */
+    get text(): string;
+    set text(value: string);
+    /** `Gtk.TextView:editable` — defaults TRUE, so the attribute carries a VALUE. */
+    get editable(): boolean;
+    set editable(value: boolean);
+    /** `Gtk.TextView:wrap-mode` — where a line may break. Defaults to `none`, no wrapping. */
+    get wrapMode(): TextViewWrapMode;
+    set wrapMode(value: TextViewWrapMode);
+    /** `Gtk.TextView:justification` — how the lines align with each other. Defaults `left`. */
+    get justification(): LabelJustification;
+    set justification(value: LabelJustification);
+    /** `Gtk.TextView:monospace` — whether the text is drawn in a monospace font. */
+    get monospace(): boolean;
+    set monospace(value: boolean);
+    /** `Gtk.TextView:accepts-tab` — whether Tab inserts a tab character. Defaults TRUE. */
+    get acceptsTab(): boolean;
+    set acceptsTab(value: boolean);
+    /** `Gtk.TextView:cursor-visible` — whether the insertion cursor is drawn. Defaults TRUE. */
+    get cursorVisible(): boolean;
+    set cursorVisible(value: boolean);
+    /** `Gtk.TextView:top-margin` — pixels of blank space above the text, in `padding`. */
+    get topMargin(): number;
+    set topMargin(value: number);
+    /** `Gtk.TextView:bottom-margin` — pixels of blank space below the text. */
+    get bottomMargin(): number;
+    set bottomMargin(value: number);
+    /** `Gtk.TextView:left-margin` — pixels of blank space to the left of the text. */
+    get leftMargin(): number;
+    set leftMargin(value: number);
+    /** `Gtk.TextView:right-margin` — pixels of blank space to the right of the text. */
+    get rightMargin(): number;
+    set rightMargin(value: number);
+    /** The inner native textarea, for focus and selection. */
+    get textarea(): HTMLTextAreaElement;
+    connectedCallback(): void;
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+    private _render;
+    /** The buffer's text before the inner control exists: the light-DOM text, or the attribute. */
+    private _seedText;
+    /**
+     * `Gtk.TextBuffer:changed`, the signal a text view's edits travel on. The buffer is a
+     * separate GObject here (its text is the element's), so its `changed` is the one event
+     * this widget has to re-emit.
+     */
+    private _emitChanged;
+    /** A boolean pspec read the way its default decides an attribute can spell it. */
+    private _bool;
+    /** {@link _bool}'s writer: the pspec default is left unwritten, anything else is written. */
+    private _setBool;
+    /** A pixel margin, floored at 0 like every `g_param_spec_int` with a zero minimum. */
+    private _margin;
+}
+export {};

package/lib/types/elements/gtk-text.d.ts

@@ -0,0 +1,45 @@
+export declare class GtkText extends HTMLElement {
+    private _input;
+    private _initialized;
+    private _maxLength;
+    static get observedAttributes(): string[];
+    /** `Gtk.Editable:text` — the buffer's contents, which is what the field shows. */
+    get text(): string;
+    set text(value: string);
+    /** `Gtk.Editable:editable` — defaults TRUE, so the attribute carries a VALUE. */
+    get editable(): boolean;
+    set editable(value: boolean);
+    /** `Gtk.Text:placeholder-text` — shown while the field is empty and unfocused. */
+    get placeholderText(): string;
+    set placeholderText(value: string);
+    /** `Gtk.Text:max-length` — 0 means unlimited. Counted in CODE POINTS. */
+    get maxLength(): number;
+    set maxLength(value: number);
+    /** `Gtk.Text:visibility` — FALSE masks the contents (the "password mode"). Defaults TRUE. */
+    get visibility(): boolean;
+    set visibility(value: boolean);
+    /**
+     * `Gtk.Text:propagate-text-width` — whether the widget grows and shrinks with its
+     * content. GTK re-measures the Pango layout on every insertion and deletion while it
+     * is set (gtktext.c:2588-2600,3605-3607,3639-3640); a native input has the same
+     * mechanism, its `size`, which is why this is a real mapping and not a measurement.
+     */
+    get propagateTextWidth(): boolean;
+    set propagateTextWidth(value: boolean);
+    /** `gtk_text_get_text_length` — code points, not UTF-16 units. */
+    get textLength(): number;
+    /** The inner native input, for focus and selection. */
+    get input(): HTMLInputElement;
+    connectedCallback(): void;
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+    private _render;
+    /**
+     * `text[.read-only]` (gtktext.c:155-167) is the node class a read-only text carries,
+     * and libadwaita never styles it — it is a selector hook. GTK's own `set_editable`
+     * adds the class on the way TO editable (gtktext.c:5762-5767), which is the inverse of
+     * what the node documentation above it describes; the DOCUMENTED rule is what a node
+     * author can rely on, so that is the one applied here.
+     */
+    private _reflectReadOnly;
+    private _resizeToText;
+}

package/lib/types/elements/gtk-toggle-button.d.ts

@@ -0,0 +1,45 @@
+import type { DispatchedSignals } from '../signals.js';
+import { GtkButton } from './gtk-button.js';
+export declare class GtkToggleButton extends GtkButton {
+    static readonly signals: DispatchedSignals;
+    private _wired;
+    /** The other end of the group link, both halves of `GtkToggleButtonPrivate`. */
+    private _groupNext;
+    private _groupPrev;
+    /** Guards the `group` property ↔ attribute loop, as `gtk-popover` guards its `open`. */
+    private _reflectingGroup;
+    static get observedAttributes(): string[];
+    /** Whether the button is pressed in. */
+    get active(): boolean;
+    set active(value: boolean);
+    /**
+     * `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);
+    /** Whether this button has at least one group link — `group_prev || group_next`. */
+    private get _grouped();
+    connectedCallback(): void;
+    attributeChangedCallback(name?: string): void;
+    /**
+     * `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;
+    /**
+     * Release every OTHER member of the group — `get_group_first()` walked backwards,
+     * then the chain forwards, skipping this one (:426-434).
+     */
+    private _clearGroup;
+    /**
+     * `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;
+    protected decorate(button: HTMLButtonElement): void;
+}

package/lib/types/elements/gtk-tree-expander.d.ts

@@ -0,0 +1,38 @@
+import { type AdwTreeExpanderLayout } from '@gjsify/adwaita-core';
+export declare class GtkTreeExpander extends HTMLElement {
+    private _ornaments;
+    private _expandTimer;
+    private _initialized;
+    static get observedAttributes(): string[];
+    get hideExpander(): boolean;
+    set hideExpander(value: boolean);
+    /** Default TRUE (gtktreeexpander.c:750), so only the literal `false` turns it off. */
+    get indentForDepth(): boolean;
+    set indentForDepth(value: boolean);
+    /** Default TRUE (gtktreeexpander.c:749), read the same way as `indent-for-depth`. */
+    get indentForIcon(): boolean;
+    set indentForIcon(value: boolean);
+    /** The row's depth — 0 at the root, as `gtk_tree_list_row_get_depth` reports it. */
+    get depth(): number;
+    set depth(value: number);
+    get expandable(): boolean;
+    set expandable(value: boolean);
+    get expanded(): boolean;
+    set expanded(value: boolean);
+    /** What this expander draws, as counts — `treeExpanderLayout`'s answer for it. */
+    get layout(): AdwTreeExpanderLayout;
+    connectedCallback(): void;
+    /** The listeners, installed once — they sit on the element, so a re-parent keeps them. */
+    private _wire;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name?: string): void;
+    private _cancelExpandTimer;
+    /**
+     * 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;
+}

package/lib/types/elements/gtk-video.d.ts

@@ -0,0 +1,97 @@
+/** The four overlay glyphs, in the order `update_overlay_icon` tests them (gtkvideo.c:626-646). */
+export type VideoOverlayIcon = 'media-eject-symbolic' | 'dialog-error-symbolic' | 'media-playlist-repeat-symbolic' | 'media-playback-start-symbolic';
+/**
+ * The glyph a video with NO stream draws — the FIRST arm of the four-way choice
+ * (gtkvideo.c:629), because "there is nothing here to play" is the state every GtkVideo
+ * starts in.
+ */
+export declare const NO_STREAM_ICON = "media-eject-symbolic";
+/** The glyph a stream that FAILED draws (gtkvideo.c:633) — tested before `ended`. */
+export declare const ERROR_ICON = "dialog-error-symbolic";
+/** The glyph a stream that has ENDED draws (gtkvideo.c:638-639). */
+export declare const ENDED_ICON = "media-playlist-repeat-symbolic";
+/** The glyph a READY stream draws (gtkvideo.c:645) — the arm everything else falls through to. */
+export declare const READY_ICON = "media-playback-start-symbolic";
+/** `gtk_video_reveal_controls`' timeout: 3 s (gtkvideo.c:130). */
+export declare const CONTROLS_HIDE_MS = 3000;
+export declare class GtkVideo extends HTMLElement {
+    private _initialized;
+    private _overlayIcon;
+    private _controlsRevealer;
+    private _media;
+    /** The listeners currently bound on `_media`, so `_detachMedia` removes the SAME ones. */
+    private mediaListeners;
+    private _hideTimer;
+    /** What the media element last told us, in the four fields the overlay choice reads. */
+    private _hasStream;
+    private _error;
+    private _ended;
+    private _playing;
+    static get observedAttributes(): string[];
+    /**
+     * `GtkVideo:autoplay` (gtkvideo.c:407-414). Defaults to FALSE. The C plays on the
+     * stream's `prepared` notification and not on this write — see the header — so this
+     * setter records the flag and lets the media's own readiness decide.
+     */
+    get autoplay(): boolean;
+    set autoplay(value: boolean);
+    /** `GtkVideo:loop` (gtkvideo.c:432-439). Defaults to FALSE. A plain `<video loop>`. */
+    get loop(): boolean;
+    set loop(value: boolean);
+    /**
+     * `GtkVideo:graphics-offload` (gtkvideo.c:400-406, :1010-1023). Defaults to FALSE — the
+     * template ships `<property name="enabled">disabled</property>` (ui/gtkvideo.ui), so the
+     * C starts with the offload OFF and an application has to ask for it.
+     *
+     * Stored, readable and class-flagged, and NOTHING ELSE HAPPENS: CSS has no way to move a
+     * subtree into a shared GPU texture, which is what `GtkGraphicsOffload` is. The class is
+     * `graphics-offload` so a page can still target it, and `KNOWN_GAPS` in
+     * `check-adwaita-element-properties.mjs` does not list it because the PROPERTY is
+     * observed — what it does not buy is a faster composite.
+     */
+    get graphicsOffload(): boolean;
+    set graphicsOffload(value: boolean);
+    /** The `<video>` this element drives — the browser's answer to a `GtkMediaStream`. */
+    get media(): HTMLVideoElement | null;
+    /** Whether the media reports itself playing — `GtkVideo:playing` (`gtk_video_get_playing`). */
+    get playing(): boolean;
+    /** The current position in SECONDS — the C's `timestamp`, in microseconds × 1000. */
+    get timestamp(): number;
+    /** The media's duration in SECONDS — the C's `duration`; 0 while it is unknown. */
+    get duration(): number;
+    /** Whether the overlay controls bar is currently revealed. */
+    get controlsRevealed(): boolean;
+    private _write;
+    connectedCallback(): void;
+    /**
+     * `ui/gtkvideo.ui` keeps the author's `<video>` as the MAIN child of the overlay and adds
+     * the two overlay children around it. Wrapping in place rather than re-creating is what
+     * lets the light DOM stay the API: a page writes `<gtk-video><video src=…></video></gtk-video>`
+     * and the element never has to be told where the media is.
+     */
+    private _wrap;
+    private _adoptMedia;
+    private _detachMedia;
+    /** `autoplay` and `loop` are declared PROPERTIES of the widget, so they are applied to
+     * the media rather than left to the author's markup — `ui/gtkvideo.ui` does the same by
+     * binding them on the template. */
+    private _syncMedia;
+    private _overlayClicked;
+    /**
+     * `gtk_video_reveal_controls` (gtkvideo.c:125-133): reveal, then arm a 3 s timeout that
+     * hides it again. Re-arming on every call is what makes it a "three seconds after the
+     * LAST movement" rather than a "three seconds after the first".
+     */
+    revealControls(): void;
+    private _hideControls;
+    /** `gtk_video_motion` (ui/gtkvideo.ui) — the motion controller's only job. */
+    private _onPointerMove;
+    attributeChangedCallback(name: string): void;
+    /** The `notify::` detail for `name`: the PROPERTY, parsed, not the raw attribute. */
+    private _property;
+    /** `gtk_video_update_playing` (gtkvideo.c:658-666) — VISIBILITY, not an icon swap. */
+    private _updatePlaying;
+    /** `gtk_video_update_overlay_icon` (gtkvideo.c:626-646), arm by arm. */
+    private _updateOverlayIcon;
+    disconnectedCallback(): void;
+}

package/lib/types/elements/gtk-viewport.d.ts

@@ -0,0 +1,84 @@
+import { type AdwAdjustment } from '@gjsify/adwaita-core';
+/** The two axes a scrollport reports numbers for, in the order GTK declares them. */
+declare const AXES: readonly ["horizontal", "vertical"];
+type Axis = (typeof AXES)[number];
+export declare class GtkViewport extends HTMLElement {
+    private _observer;
+    private _watch;
+    static get observedAttributes(): string[];
+    /**
+     * `GtkScrollable:hadjustment` — the horizontal position, as the portable value.
+     *
+     * Computed on read rather than stored: `viewport_set_adjustment_values` reconfigures both
+     * axes on every allocation, so there is no state to cache and nothing an author can write.
+     */
+    get hadjustment(): AdwAdjustment;
+    /** `GtkScrollable:vadjustment` — the vertical position, as the portable value. */
+    get vadjustment(): AdwAdjustment;
+    /**
+     * `GtkViewport:scroll-to-focus` — whether the viewport keeps the focus widget in view.
+     * TRUE in the pspec (gtkviewport.c:338-340), and an unknown value is the DEFAULT rather
+     * than "off": only the literal `false` turns it off, which is what FALSE in a construct
+     * bag means and what a boolean attribute has to spell out to be read at all.
+     */
+    get scrollToFocus(): boolean;
+    set scrollToFocus(value: boolean);
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * Announce whenever a number the adjustments are made of has changed.
+     *
+     * GTK reconfigures both axes on every allocation — `viewport_set_adjustment_values` runs
+     * out of `size_allocate`, and `gtk_adjustment_configure` compresses the notifications into
+     * one. A browser reports the same event as the scrollport's own box changing (this
+     * element) and its CONTENT changing (the children), and neither is the other's: a child
+     * that grows leaves the viewport's box exactly where it was, which is why BOTH are watched.
+     * The content watcher is what makes a scrolled window's bars appear the moment content
+     * lands in it, and it is `gtk_widget_queue_resize` on the child propagating upward.
+     */
+    private _observe;
+    attributeChangedCallback(name: string): void;
+    /**
+     * `gtk_adjustment_set_value` on one of the viewport's OWN adjustments — the half of a
+     * scrolled window's job that moves content rather than deciding whether to.
+     *
+     * The value is clamped first, which is `set_value`'s documented behaviour ("The value is
+     * clamped to lie between lower and upper") and the reason a bar may ask for a position its
+     * own range has just outgrown.
+     */
+    scrollAxis(axis: Axis, value: number): void;
+    /**
+     * `gtk_viewport_scroll_to` — move the position so `descendant` is inside the window.
+     * `null` asks only for the position to be CLAMPED, which is what a content that shrank
+     * needs from a value that was legal a moment ago.
+     *
+     * GTK animates the move (`gtk_adjustment_animate_to_value`, gtkviewport.c:757-758) for
+     * `ANIMATION_DURATION` unless the widget should not animate — the browser's spelling of
+     * that setting is `prefers-reduced-motion`, and `scrollIntoView`'s own `behavior` is where
+     * the choice belongs.
+     *
+     * `scrollTo` IS a platform method with an options form, so both are here and the KIND of
+     * the argument decides: a node is GTK's `scroll_to(descendant)` and anything else is the
+     * scrollport's own `scrollTo(options)`, which this element is (one element for the two
+     * GTK nodes is the port's own decision, see the header).
+     */
+    scrollTo(descendant: Element | null): void;
+    scrollTo(options?: ScrollToOptions): void;
+    scrollTo(x: number, y: number): void;
+    /** The adjustments of both axes, as the detail of the `value-changed` event. */
+    get adjustments(): {
+        hadjustment: AdwAdjustment;
+        vadjustment: AdwAdjustment;
+    };
+    /**
+     * One event for both adjustments: a browser scroll moves them together, and the C's
+     * `GtkAdjustment::value-changed` is a signal of the ADJUSTMENT rather than of the viewport
+     * that reads it. Bubbling, so `<gtk-scrolled-window>` hears it without holding a reference
+     * to anything in here.
+     */
+    private _announce;
+    /** `setup_focus_change_handler` / `clear_focus_change_handler`, on one event instead of a root signal. */
+    private _bindFocus;
+    private _onFocusIn;
+}
+export {};

package/lib/types/elements/gtk-window-controls.d.ts

@@ -0,0 +1,80 @@
+/** `Gtk.PackType`, spelled as the GIR's enum nicks (gtkwindowcontrols.c:68). */
+type PackSide = 'start' | 'end';
+/** What a press asks for: the `GtkActionable` action name minus its `window.` prefix. */
+export type WindowAction = 'minimize' | 'toggle-maximized' | 'close';
+export declare class GtkWindowControls extends HTMLElement {
+    private _initialized;
+    private _empty;
+    /** The frame this controls answers to, or `null` outside one (`:257-263`). */
+    private _window;
+    private _windowObserver;
+    static get observedAttributes(): string[];
+    /** `Gtk.WindowControls:side` — which half of the decoration layout to build. */
+    get side(): PackSide;
+    set side(value: PackSide);
+    /** `Gtk.WindowControls:use-native-controls` — a macOS-only branch; see KNOWN_GAPS. */
+    get useNativeControls(): boolean;
+    /**
+     * `Gtk.WindowControls:empty` (read-only in GIR). TRUE — the GIR default (:618) — until a
+     * render finds a button, which is what happens outside a window.
+     */
+    get empty(): boolean;
+    /** `setAttribute` for a write that changes nothing; every GObject setter here returns early. */
+    private _write;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string): void;
+    private _property;
+    /**
+     * Bind to the frame above, the way `gtk_window_controls_root` binds to the settings and
+     * to `notify` on the window (:443-462) — then run the build, which is that handler's
+     * first act. Re-established on every connect: a bar moved into another window has a new
+     * ancestor, which is why C does it in `root` and drops it in `unroot`.
+     */
+    private _followWindow;
+    /** `is_sovereign_window` (gtkwindowcontrols.c:272-273): neither modal nor transient. */
+    private _isSovereign;
+    /**
+     * The window property, in ITS polarity. `resizable` and `deletable` default TRUE
+     * (gtkwindow.c:893, :1024) and `maximized` defaults FALSE (:1044), so one helper reading
+     * them alike would put a maximize button on a window that cannot be maximized — and a
+     * restore glyph on every window there is.
+     */
+    private _windowFlag;
+    /**
+     * `get_layout` (gtkwindowcontrols.c:120-176), reduced to what a page can answer: this
+     * widget's own value, then the frame's, then GNOME's default. The first ':' splits the
+     * layout in two, and a layout with no ':' is the same half on both sides.
+     */
+    private _layoutHalf;
+    /** `update_window_buttons` (gtkwindowcontrols.c:247-426), token for token. */
+    private _render;
+    /** Every render writes the class, whether the VALUE moved or not — see {@link _setEmpty}. */
+    private _applyEmptyClass;
+    /** The one child a token builds, or `null` for the tokens that build nothing here. */
+    private _buttonFor;
+    /**
+     * `update_window_icon` (gtkwindowcontrols.c:187-210): the icon node is `presentation` to
+     * an accessibility tree, and it is dropped when the window has no icon — which for a
+     * frame means no `icon-name`, the analogue of a window with no `GdkPaintable`.
+     */
+    private _windowIcon;
+    /**
+     * One `GtkButton` with its `GtkImage` child. A plain `<button>` rather than
+     * `<gtk-button>`: libadwaita's own rules select `windowcontrols > button > image`
+     * (refs/libadwaita/src/stylesheet/widgets/_header-bar.scss:178-202), so the button IS
+     * the widget node here, and `<gtk-button>` would wrap a second one inside it.
+     */
+    private _controlButton;
+    /**
+     * `set_empty` (gtkwindowcontrols.c:216-230): a style class, and a notify of its own.
+     *
+     * The early return is about the NOTIFY, and it is the whole of C's `if (empty ==
+     * self->empty) return;`. The CLASS is not part of that comparison here: `empty` starts
+     * TRUE, so the first render outside a window is a no-op against C and the widget was
+     * left wearing nothing at all — a property whose style class only appears once it has
+     * been wrong and then right again.
+     */
+    private _setEmpty;
+}
+export {};

package/lib/types/elements/gtk-window-handle.d.ts

@@ -0,0 +1,39 @@
+/** `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';
+export declare class GtkWindowHandle extends HTMLElement {
+    /** The gesture in progress, as `priv->drag_start_x` / `_y` are in the C. */
+    private _drag;
+    /**
+     * 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(): string[];
+    /** The action one gesture is set to, as the settings are read in C. */
+    actionFor(gesture: GtkTitlebarGesture): GtkTitlebarAction;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * `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;
+    private _onClick;
+    private _onPointerDown;
+    /**
+     * `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;
+}