@gjsify/adwaita-web 0.53.0 → 0.55.0

package/lib/types/elements/gtk-page-setup-unix-dialog.d.ts

@@ -0,0 +1,87 @@
+import { type PageSetup, type PageUnit } from '../page-setup.js';
+import { AdwDialog } from './adw-dialog.js';
+/** One row of the "Format for:" drop down. */
+export interface PrinterInfo {
+    /** `gtk_printer_get_name` — what `format-for-printer` is compared against. */
+    readonly name: string;
+    /** `gtk_printer_get_location`, the dimmed second line of the row. */
+    readonly location?: string;
+}
+/** The one `GtkPrintSettings` key this dialog reads or writes. */
+export interface PrintSettingsData {
+    /** `format-for-printer` — the printer name the settings belong to. */
+    readonly 'format-for-printer'?: string;
+}
+export declare class GtkPageSetupUnixDialog extends AdwDialog {
+    private _built;
+    static get observedAttributes(): string[];
+    private _printerEl;
+    private _paperEl;
+    private _sizeLabelEl;
+    private _radios;
+    private _printers;
+    /** The setups in the drop-down, in the order the C appends them. */
+    private _setups;
+    /** `last_setup` — the size the drop down is put back to when a row is not a size. */
+    private _lastSetup;
+    private _printSettings;
+    private _unit;
+    /** The unit the two labels speak — `_gtk_print_get_default_user_units` is mm here. */
+    get unit(): PageUnit;
+    set unit(value: PageUnit);
+    /**
+     * The printer list GTK discovers through a print backend. A browser has no CUPS, so
+     * this is an INPUT; the row every dialog starts with is added by the element itself.
+     */
+    get printers(): PrinterInfo[];
+    set printers(value: readonly PrinterInfo[]);
+    /**
+     * The current page setup — `gtk_page_setup_unix_dialog_get_page_setup`, which returns
+     * the SELECTED setup with the orientation the radios hold.
+     */
+    get pageSetup(): PageSetup;
+    /**
+     * `gtk_page_setup_unix_dialog_set_page_setup`: select the matching row, appending the
+     * setup when no row matches (`set_paper_size` with `add_item` TRUE), then set the
+     * orientation radios.
+     */
+    set pageSetup(value: PageSetup);
+    /** `gtk_page_setup_unix_dialog_get_print_settings` — the object, not a copy of it. */
+    get printSettings(): PrintSettingsData | null;
+    /** Selects the printer named by `format-for-printer`, as the setter does. */
+    set printSettings(value: PrintSettingsData | null);
+    connectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    private _build;
+    /** A `GtkDropDown` with its label as the accessible name, `column-span 3`. */
+    private _dropDown;
+    /** A grid label — right-aligned, `use-underline` in the `.ui`, no keyvals here. */
+    private _label;
+    /**
+     * The `.dialog-action-area` row: `_Cancel` (GTK_RESPONSE_CANCEL) and `_Apply`
+     * (GTK_RESPONSE_OK), which is the label `gtk_dialog_add_buttons` gives the OK response
+     * in this dialog. Escape is the close action the base class already binds.
+     */
+    private _actions;
+    private _respond;
+    /** The drop-down's rows: the pseudo printer first, then the caller's. */
+    private _printerRows;
+    /**
+     * `fill_paper_sizes_from_printer` (:470-491): with no printer — which includes the
+     * "Any Printer" row, because `printer_changed_callback` clears it before the call
+     * (:576-580) — the list is the twelve common sizes. A REAL printer would bring its
+     * own `gtk_printer_list_papers`, which needs the backend this port has not.
+     */
+    private _fillPaperSizes;
+    /** The selected setup, before the radios' orientation is folded in. */
+    private _current;
+    private _orientation;
+    private _setOrientation;
+    private _renderSetup;
+    /** `printer_changed_callback` (:557-609): the paper list follows the printer. */
+    private _printerChanged;
+    /** `paper_size_changed` (:635-758). */
+    private _paperChanged;
+    /** The radios' side of `get_orientation` — the label follows them. */
+    private _orientationChanged;
+}

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

@@ -0,0 +1,121 @@
+import { type BoxOrientation } from '@gjsify/adwaita-core';
+/** The inputs of `gtk_paned_compute_position`, one per field it reads. */
+export interface PanedPositionInput {
+    /** The paned's own allocation along the axis, minus the handle — its `allocation`. */
+    allocation: number;
+    /** The start child's size REQUEST along the axis. */
+    startRequest: number;
+    /** The end child's size REQUEST along the axis. */
+    endRequest: number;
+    resizeStart: boolean;
+    resizeEnd: boolean;
+    shrinkStart: boolean;
+    shrinkEnd: boolean;
+    /** `position_set` — whether the app or the user has placed the divider. */
+    positionSet: boolean;
+    /** `start_child_size` — the divider as last allocated or set; `0` when unset. */
+    startChildSize: number;
+    /** `last_allocation` — what `startChildSize` was measured against. */
+    lastAllocation: number;
+}
+/** What `gtk_paned_compute_position` writes back through its three out-parameters. */
+export interface PanedPosition {
+    min: number;
+    max: number;
+    position: number;
+}
+/**
+ * `gtk_paned_compute_position` (gtkpaned.c:1092-1146), statement for statement.
+ *
+ * Exported so a spec can pin the arithmetic without a layout. The branch keyed on
+ * `lastAllocation` is the one a browser cannot reach on its own — there is no "position was
+ * set before the first allocation" moment in a flex layout — so it is the piece only a table
+ * of inputs can hold.
+ */
+export declare function computePanedPosition(input: PanedPositionInput): PanedPosition;
+export declare class GtkPaned extends HTMLElement {
+    private _startEl;
+    private _handleEl;
+    private _endEl;
+    private _initialized;
+    /** `start_child_size` — the divider. `-1` is GTK's "unset". */
+    private _position;
+    /** `position_set` — GTK's read-only flag; see the header. */
+    private _positionSet;
+    /** What `gtk_paned_compute_position` last produced for `min_position`. */
+    private _minPosition;
+    /** …and for `max_position`. */
+    private _maxPosition;
+    /** `last_allocation` — the allocation the current position was computed against. */
+    private _lastAllocation;
+    /** `drag_pos` — where inside the handle the gesture began (gtkpaned.c:930-940). */
+    private _dragPos;
+    private _dragging;
+    private _resize;
+    static get observedAttributes(): string[];
+    /** `GtkOrientable:orientation` — which way the divider runs. */
+    get orientation(): BoxOrientation;
+    set orientation(value: BoxOrientation);
+    /** `Gtk.Paned:position` — the divider in pixels; `-1` puts it back to derived. */
+    get position(): number;
+    set position(value: number);
+    /** `Gtk.Paned:position-set` — read-only in GTK; only `position` moves it. */
+    get positionSet(): boolean;
+    /** `Gtk.AccessibleRange:min-position` as the last computation left it. */
+    get minPosition(): number;
+    /** `Gtk.AccessibleRange:max-position` as the last computation left it. */
+    get maxPosition(): number;
+    /** `Gtk.Paned:wide-handle` — the stronger visual separation. */
+    get wideHandle(): boolean;
+    set wideHandle(value: boolean);
+    /** `Gtk.Paned:start-child` — the light-DOM node in the leading pane. */
+    get startChild(): Element | null;
+    /** `Gtk.Paned:end-child` — the light-DOM node in the trailing pane. */
+    get endChild(): Element | null;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string): void;
+    private _property;
+    private _observe;
+    /** `gtk_paned_set_position` (gtkpaned.c:1874-1910), with its two notifications. */
+    private setPosition;
+    /** `gtk_paned_calc_position` (gtkpaned.c:1021-1053): compute, place, notify, remember. */
+    private _layout;
+    /**
+     * A child's SIZE REQUEST — what `gtk_widget_measure` answers with.
+     *
+     * `flex: none` pins the item to its content size, which is exactly a GTK size request,
+     * and the read is one forced reflow. It has to be a separate pass: the laid-out size of a
+     * pane that is currently `flex-grow: 1` is its ALLOCATION, and feeding that back as a
+     * request is how a paned ends up re-deriving its own divisor.
+     */
+    private _sizeRequest;
+    /**
+     * `shrink-*` is "can this child be made smaller than its requisition", which in CSS is
+     * whether the AUTOMATIC minimum applies — `min-width: auto` is the flex automatic
+     * minimum, so `min-width: 0` is the permission and leaving the longhand alone is the
+     * prohibition.
+     */
+    private _applyMinimum;
+    /**
+     * `notify::<property>`, with the DETAIL keyed by the JS property name — the spelling
+     * `<adw-expander-row>`, `<adw-entry-row>` and `<gtk-switch>` use, and the one a caller
+     * destructures. `notify::position-set` therefore carries `{ positionSet }`.
+     */
+    private _notify;
+    /** `is_rtl` (gtkpaned.c:1533-1536): only a horizontal paned mirrors. */
+    private get _isRtl();
+    /** `gesture_drag_begin_cb` (gtkpaned.c:915-955) — the capture and `drag_pos`. */
+    private readonly _onPointerDown;
+    /** `update_drag` (gtkpaned.c:1538-1573), from the capture phase. */
+    private readonly _onPointerMove;
+    private readonly _onPointerUp;
+    /**
+     * `gtk_paned_move_handle` (gtkpaned.c:2286-2353) over `add_move_binding`'s key list
+     * (gtkpaned.c:768-785). `Escape` and `Return`/Space are `cancel-position` /
+     * `accept-position`, which GTK binds to no handler of its own — they are the signals an
+     * embedding application listens for — so they are dispatched as events and left to
+     * bubble rather than swallowed here.
+     */
+    private readonly _onKeyDown;
+}

package/lib/types/elements/gtk-password-entry.d.ts

@@ -0,0 +1,27 @@
+import { GtkEntry } from './gtk-entry.js';
+export declare class GtkPasswordEntry extends GtkEntry {
+    /** The headless peek + caps-lock derivation, composing the entry's own state. */
+    private readonly _entry;
+    private readonly _password;
+    private _toggle;
+    private _peekIcon;
+    private _capsLock;
+    static get observedAttributes(): string[];
+    /** Whether the contents are shown in clear text (`GtkText:visibility`). */
+    get revealed(): boolean;
+    set revealed(value: boolean);
+    /** Whether Caps Lock is engaged, as last observed from a keyboard event. */
+    get capsLockOn(): boolean;
+    /**
+     * Feed the platform's Caps Lock state in — GDK reads it off the keyboard device
+     * (`gdk_device_get_caps_lock_state`), which a browser exposes only on keyboard events.
+     * Public so a host that knows better (a virtual keyboard, a test) can drive it directly.
+     */
+    setCapsLockOn(on: boolean): void;
+    connectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, value: string | null): void;
+    /** A focus change re-derives, because the warning's visibility is `editing && …`. */
+    private _passwordChanged;
+    /** `notify_visibility_cb`, applied to the DOM. */
+    private _applyPassword;
+}

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

@@ -0,0 +1,66 @@
+/** `GtkContentFit`, in enum order — the four nicks the GIR and CSS share. */
+export declare const PICTURE_CONTENT_FIT_MODES: readonly ["fill", "contain", "cover", "scale-down"];
+export type PictureContentFit = (typeof PICTURE_CONTENT_FIT_MODES)[number];
+/** `GTK_CONTENT_FIT_CONTAIN`, the default the C installs (gtkpicture.c:530, :555). */
+export declare const DEFAULT_PICTURE_CONTENT_FIT: PictureContentFit;
+/**
+ * `GtkPicture:content-fit` from its nick, with the C's own guard: an unknown nick is left
+ * to the default rather than coerced to `fill`, which is the one value that would silently
+ * distort every picture a page writes.
+ */
+export declare function normalizePictureContentFit(value: unknown): PictureContentFit;
+export declare class GtkPicture extends HTMLElement {
+    private _initialized;
+    static get observedAttributes(): string[];
+    /**
+     * `GtkPicture:alternative-text` (gtkpicture.c:474-483) — the accessible NAME of the
+     * picture. It is NOT `alt`: the GIR property is `alternative-text`, and the element
+     * carries that spelling so the attribute and the property are one write.
+     */
+    get alternativeText(): string;
+    set alternativeText(value: string);
+    /** `GtkPicture:can-shrink` (gtkpicture.c:486-497). Defaults to TRUE (gtkpicture.c:554). */
+    get canShrink(): boolean;
+    set canShrink(value: boolean);
+    /** `GtkPicture:content-fit` (gtkpicture.c:520-531). Defaults to CONTAIN. */
+    get contentFit(): PictureContentFit;
+    set contentFit(value: PictureContentFit);
+    /**
+     * `GtkPicture:isolate-contents` (gtkpicture.c:538-549). Defaults to TRUE
+     * (gtkpicture.c:555) — the same absent-is-true rule {@link canShrink} follows, and for
+     * the same reason: the C installs the value in `init`, before any attribute is read.
+     */
+    get isolateContents(): boolean;
+    set isolateContents(value: boolean);
+    /**
+     * `GtkPicture:keep-aspect-ratio` — DEPRECATED in 4.8, and implemented rather than
+     * dropped, because the C did not drop it (gtkpicture.c:1006-1040).
+     *
+     * The setter is a MAPPING, not a stored boolean (gtkpicture.c:1017-1021): TRUE sets
+     * `content-fit` to CONTAIN, FALSE sets it to FILL. The getter is the INVERSE test over
+     * the live `content-fit` (gtkpicture.c:1040), so a picture authored as `cover` or
+     * `scale-down` reads `true` back — those two preserve the ratio, exactly as CONTAIN
+     * does, and returning `false` for them would contradict the property's own definition.
+     */
+    get keepAspectRatio(): boolean;
+    set keepAspectRatio(value: boolean);
+    /**
+     * `setAttribute` runs the custom-element reaction for a write that changes nothing,
+     * while every GObject setter here returns early when the value is already right
+     * (gtkpicture.c:1111-1112). This is the guard that makes "notify only on a real
+     * change" true.
+     */
+    private _write;
+    /**
+     * A boolean whose GIR default is TRUE needs three states, not two: absent means TRUE
+     * (the default the C installs in `init`), `=""` means TRUE, and `="false"` means FALSE.
+     * `toggleAttribute` alone would make absent and empty the same state, which is right for
+     * a FALSE-defaulted property and wrong for every one of these three.
+     */
+    private _toggle;
+    connectedCallback(): void;
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+    /** The `notify::` detail for `name`: the PROPERTY, parsed, not the raw attribute. */
+    private _property;
+    private _render;
+}

package/lib/types/elements/gtk-popover-bin.d.ts

@@ -0,0 +1,82 @@
+import type { AdwMenuActions, AdwMenuInput, AdwMenuModel } from '@gjsify/adwaita-core';
+import './gtk-popover-menu.js';
+import type { GtkPopoverMenu } from './gtk-popover-menu.js';
+export declare class GtkPopoverBin extends HTMLElement {
+    private _model;
+    private _popover;
+    private _actions;
+    private _initialized;
+    private _longPressTimer;
+    static get observedAttributes(): string[];
+    /** The menu model, normalised (ADR 0042). */
+    get menuModel(): AdwMenuModel;
+    /**
+     * The model the popover is built from — ONE slot with `popover`, because GTK's two
+     * setters clear each other (gtkpopoverbin.c:474-500, :543-551). A model REPLACES the
+     * popover; a popover DROPS the model, and both notify for both properties.
+     */
+    set menuModel(value: AdwMenuInput | AdwMenuModel);
+    /**
+     * The popover this bin presents, or `null`.
+     *
+     * NOT `popover`, which is `GtkPopoverBin`'s GObject name and also `HTMLElement`'s: the
+     * DOM's Popover API spells a string attribute `popover`, and shadowing it with a widget
+     * would make the element disagree with the platform it sits on. The `Element` suffix is
+     * what this package already uses where a GIR name is taken (`childElement` below, and
+     * `Adw.NavigationPage`'s own `navigationPage`).
+     */
+    get popoverElement(): GtkPopoverMenu | null;
+    set popoverElement(value: GtkPopoverMenu | null);
+    /** Whether a right click or a long press opens the popover. GTK's default is FALSE. */
+    get handleInput(): boolean;
+    set handleInput(value: boolean);
+    /** What the action group publishes about the actions the menu names (ADR 0042). */
+    get actions(): AdwMenuActions | null;
+    set actions(value: AdwMenuActions | null);
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name?: string): void;
+    /** The `menu.popup` action — present the popover. */
+    popup(): void;
+    /** Dismiss the popover. */
+    popdown(): void;
+    /** The widget whose `.has-open-popup` follows the popover, when the bin has one. */
+    get childElement(): HTMLElement | null;
+    private _wireGestures;
+    private _cancelLongPress;
+    private _onContextMenu;
+    /**
+     * `popup_at_position` WITH the pointer's coordinates, which is the branch that sets
+     * `pointing-to` to `(x, y)` (gtkpopoverbin.c:141-145). `<gtk-popover>` has no
+     * `pointing-to` to set — placement is the `position`/`align` pair, the same gap the
+     * element's own KNOWN_GAPS records — so the call is the plain `popup()` and what the
+     * reader sees is GTK's: the menu under the child.
+     */
+    private _popupAt;
+    /**
+     * The Menu key, which is the shortcut GTK installs next to the gestures
+     * (`gtk_shortcut_trigger_create_for_menu`, gtkpopoverbin.c:643-649). GTK builds the
+     * trigger in the platform's canonical form, which a keydown cannot carry, so the
+     * un-modified key beside Shift is the whole binding here.
+     */
+    private _onKeyDown;
+    private _buildPopover;
+    /**
+     * `set_popover` (gtkpopoverbin.c:543-587): hide and unparent the old one, parent the
+     * new one, and wire the map/unmap handlers that carry `.has-open-popup` on the child.
+     */
+    private _adoptPopover;
+    /**
+     * `g_object_notify_by_pspec` is called for `:popover` AND `:menu-model` by BOTH setters
+     * (gtkpopoverbin.c:502, :586-587), because the two are one slot. One event carrying
+     * both is the faithful reading, and the second notify GTK sends separately has no state
+     * of its own to report.
+     */
+    private _notifyModel;
+    /**
+     * The `menu-model` ATTRIBUTE through the core parser, refusing a `custom` item the way
+     * every menu-bearing surface here does: markup is parsed by the browser, so a throw from
+     * `connectedCallback` would reach nobody and the menu would be silently empty.
+     */
+    private _parseMenuAttr;
+}

package/lib/types/elements/gtk-popover-menu-bar.d.ts

@@ -0,0 +1,66 @@
+import type { AdwMenuActions, AdwMenuInput, AdwMenuModel } from '@gjsify/adwaita-core';
+import './gtk-popover-menu.js';
+export declare class GtkPopoverMenuBar extends HTMLElement {
+    private _model;
+    private _actions;
+    private _items;
+    private _active;
+    private _initialized;
+    static get observedAttributes(): string[];
+    /** The menu model, normalised (ADR 0042). */
+    get menuModel(): AdwMenuModel;
+    set menuModel(value: AdwMenuInput);
+    /** What the action group publishes about the actions these menus name (ADR 0042). */
+    get actions(): AdwMenuActions | null;
+    set actions(value: AdwMenuActions | null);
+    /** The active item's button, or `null` — GTK's `active_item`, as a widget. */
+    get activeItem(): HTMLElement | null;
+    connectedCallback(): void;
+    attributeChangedCallback(name?: string): void;
+    /** `gtk_popover_menu_bar_select_first` — activate and OPEN the first item. */
+    selectFirst(): void;
+    /** What the bar's `menu.popup` action does, which is the same thing. */
+    popup(): void;
+    /**
+     * `set_active_item` (gtkpopovermenubar.c:126-163), variable names and all.
+     *
+     * `changed` and `was_popup` decide three DIFFERENT outcomes — close the old one, open
+     * the new one, or move focus onto it — and collapsing them is how a hover would come to
+     * open menus, which is the single behaviour that separates a menubar from a row of menu
+     * buttons.
+     */
+    private _setActive;
+    private _onKeyDown;
+    /**
+     * The sibling in `step`'s direction, WRAPPING at either end
+     * (gtkpopovermenubar.c:232-252): with no active item there is no sibling, so the first
+     * move goes to the first child for RIGHT and to the LAST for LEFT.
+     */
+    private _move;
+    private _rebuild;
+    /**
+     * Focus the first row a key can reach in a menu that has just opened.
+     *
+     * This is what `autohide` does in GTK: `gtk_popover_show` calls
+     * `gtk_widget_child_focus (widget, GTK_DIR_TAB_FORWARD)` when the property holds
+     * (gtkpopover.c:1188-1192), and a browser popup takes no focus until it is told to —
+     * which is why the item whose menu opened is what does it here.
+     */
+    private _focusFirstRow;
+    /**
+     * One `menubar > item > popover` (the node tree in gtkpopovermenubar.c:38-46).
+     *
+     * A toplevel node that is not a submenu is refused by `_parseMenuAttr` with GTK's own
+     * wording rather than drawn: `tracker_insert` builds nothing for it
+     * (gtkpopovermenubar.c:466), and a row that opens nothing is the same lie in another
+     * shape.
+     */
+    private _buildItem;
+    /**
+     * Activating a row inside one of the popovers closes THAT popover and hands focus back
+     * to its item, which is what `gtk_popover_menu_set_active_item` does when the active
+     * row is not the row that opened a submenu (gtkpopovermenu.c:257-259).
+     */
+    private _activate;
+    private _parseMenuAttr;
+}

package/lib/types/elements/gtk-popover-menu.d.ts

@@ -0,0 +1,83 @@
+import type { AdwMenuActions, AdwMenuInput, AdwMenuModel } from '@gjsify/adwaita-core';
+import { GtkPopover } from './gtk-popover.js';
+export declare class GtkPopoverMenu extends GtkPopover {
+    private _model;
+    private _actions;
+    private _menuView;
+    /** Named apart from `GtkPopover`'s own: two `private` fields of one name are two fields. */
+    private _menuInitialized;
+    static get observedAttributes(): string[];
+    /** The menu, normalised (ADR 0042). */
+    get menuModel(): AdwMenuModel;
+    /**
+     * Set the menu from anything the portable model accepts, refusing a `custom` item
+     * HERE — at the assignment, where it is a call the caller can catch. An ATTRIBUTE is
+     * markup the browser parses, so the attribute path refuses the whole menu instead and
+     * says why on `console.error`, exactly as `<gtk-menu-button>` does.
+     *
+     * `AdwMenuModel` is in the union because a menu bar hands over a submenu's own `items`
+     * untouched, and `normalizeMenuModel` is documented to be IDEMPOTENT over an
+     * already-normalised node — that is what lets a renderer hand a model it is holding
+     * straight back. The one cast is where the core's parameter type (`AdwMenuInput`, whose
+     * entries are the AUTHORED shapes) is narrower than the behaviour it documents.
+     */
+    set menuModel(value: AdwMenuInput | AdwMenuModel);
+    /** What the action group publishes about the actions this menu names (ADR 0042). */
+    get actions(): AdwMenuActions | null;
+    set actions(value: AdwMenuActions | null);
+    /** The optional heading. GTK spells one as a labelled SECTION; this is the shorthand. */
+    get menuTitle(): string;
+    set menuTitle(value: string);
+    /**
+     * The name of the open page — `'main'` for the root, a submenu's label for a submenu.
+     *
+     * GTK's value is the stack child's NAME, which `GtkMenuTracker` gives a submenu page
+     * from the node it links; with no name given that is the submenu's label, so the label
+     * is what this element answers with. `gtk_popover_menu_open_submenu` (gtkpopovermenu.c
+     * :755-757) is the only way in, so setting it navigates rather than describing.
+     */
+    get visibleSubmenu(): string;
+    set visibleSubmenu(value: string);
+    connectedCallback(): void;
+    attributeChangedCallback(name?: string, previous?: string | null, value?: string | null): void;
+    /** `gtk_popover_menu_open_submenu` — switch to the named page. */
+    openSubmenu(name: string): void;
+    /**
+     * The ONE way the open page changes, from the property and from the attribute alike.
+     *
+     * The notify belongs HERE rather than beside the attribute write: a page can change
+     * without the attribute's text changing (`openSubmenu('More')` when it is already
+     * `More` after a dismissal, or an attribute set to the page already showing), and
+     * `GObject` notifies on the state, not on the spelling.
+     */
+    private _navigate;
+    /**
+     * Point the page stack at the named page and rebuild it. `false` when the name is not
+     * one of the stack's children, which is what `gtk_stack_set_visible_child_name` leaves
+     * alone — the current page keeps showing rather than the surface blanking.
+     */
+    private _showPage;
+    /**
+     * `gtk_popover_menu_close_submenus` — leave the open submenu, ONE level
+     * (gtkpopovermenu.c:223-233), which is what the back row does.
+     */
+    closeSubmenus(): void;
+    private _openPageLabel;
+    private _findSubmenu;
+    /**
+     * Write the open page back to the attribute, ONCE, and only when the spelling differs.
+     *
+     * Reading the attribute instead of the state is the whole loop guard: navigating sets
+     * this, the attribute change calls back into `_navigate`, and a comparison against the
+     * current value stops the second turn.
+     */
+    private _reflectSubmenu;
+    /**
+     * Activating an item closes the popover and returns focus to the anchor — the
+     * behaviour every menu-bearing surface here has, and the reason a menu cannot be left
+     * open by choosing from it.
+     */
+    private _activate;
+    private _renderMenu;
+    private _parseMenuAttr;
+}

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

@@ -2,8 +2,15 @@
 export type GtkPopoverPosition = 'bottom' | 'top' | 'start' | 'end';
 /** Which edge of the anchor the surface lines up with. */
 export type GtkPopoverAlign = 'start' | 'end';
-/** The ARIA role of the surface — it decides the row role consumers give their items. */
-export type GtkPopoverRole = 'menu' | 'listbox';
+/**
+ * The ARIA role of the surface — it decides the row role consumers give their items.
+ *
+ * `dialog` is the one role that is not a container of ROWS: it is for a surface holding
+ * content, so nothing derives an item role from it. Upstream splits the same way —
+ * `GtkPopoverMenu` declares itself a menu (`refs/gtk/gtk/gtkpopovermenu.c:676`), a bare
+ * `GtkPopover` declares nothing.
+ */
+export type GtkPopoverRole = 'menu' | 'listbox' | 'dialog';
 export declare class GtkPopover extends HTMLElement {
     private readonly _state;
     private _anchor;
@@ -15,6 +22,17 @@ export declare class GtkPopover extends HTMLElement {
     static get observedAttributes(): string[];
     get open(): boolean;
     set open(value: boolean);
+    /**
+     * Whether an outside click (or an Escape) dismisses the popover — GTK's grab.
+     *
+     * `autohide` defaults to TRUE in C (`priv->autohide = TRUE`, gtkpopover.c:1046) and
+     * that default is what every existing consumer in this package relies on, so it is
+     * the ABSENCE of the attribute rather than its presence, exactly as GTK spells it.
+     * Turning it off is entry completion's shape, which is the usecase the property
+     * documents: the entry keeps the caret and the list follows the typing.
+     */
+    get autohide(): boolean;
+    set autohide(value: boolean);
     /**
      * The element the surface is positioned against and hands focus back to. Defaults to
      * `parentElement`: the popover is normally the last child of the widget that owns it.
@@ -25,6 +43,7 @@ export declare class GtkPopover extends HTMLElement {
     set position(value: GtkPopoverPosition);
     get align(): GtkPopoverAlign;
     set align(value: GtkPopoverAlign);
+    /** The ARIA role of the surface; an unknown value reads as the `menu` default. */
     get popoverRole(): GtkPopoverRole;
     /**
      * The navigable rows, in DOM order.
@@ -50,7 +69,13 @@ export declare class GtkPopover extends HTMLElement {
     connectedCallback(): void;
     private _buildOnce;
     disconnectedCallback(): void;
-    attributeChangedCallback(name: string, _previous: string | null, value: string | null): void;
+    /**
+     * Every parameter is optional, and that is FOR `<gtk-popover-menu>`, which subclasses
+     * this element: an override may not demand a parameter the base signature does not pass,
+     * and the platform always passes all three — the `?` is a typescript-visible fact about
+     * the CALLER, not about what arrives.
+     */
+    attributeChangedCallback(name?: string, _previous?: string | null, value?: string | null): void;
     private _onStateChange;
     private _bindDocument;
     private _unbindDocument;