@gjsify/adwaita-web 0.31.0 → 0.33.0

package/lib/types/elements/adw-drop-down.d.ts

@@ -1,34 +1,32 @@
-/** A dropdown option — `value` is the stable id, `label` the shown text. */
-export interface AdwDropDownOption {
-    value: string;
-    label: string;
-}
-type RawOption = string | {
-    value?: unknown;
-    label?: unknown;
-};
+import './adw-popover.js';
+import type { AdwComboOption, AdwComboOptionInput } from '@gjsify/adwaita-core';
+/**
+ * A dropdown option — `value` is the stable id, `label` the shown text.
+ *
+ * An alias of core's {@link AdwComboOption}: the drop-down and the combo row are
+ * the same selection model behind two chromes, and they had two names for one
+ * descriptor. Kept exported so the published type name does not break.
+ */
+export type AdwDropDownOption = AdwComboOption;
 export declare class AdwDropDown extends HTMLElement {
     private _buttonEl;
     private _labelEl;
     private _popoverEl;
     private _listEl;
     private _searchEl;
-    private _options;
     private _itemButtons;
-    private _selected;
-    private _active;
+    /** The headless options list + selectedIndex↔selectedValue machine (ADR 0004). */
+    private readonly _state;
     private _initialized;
     private _typeAheadBuffer;
     private _typeAheadTimer;
-    private _onDocumentPointerDown;
-    private _onDocumentKeyDown;
     static get observedAttributes(): string[];
     /** The options list. Setting it rebuilds the popover and clamps the selection. */
     get options(): AdwDropDownOption[];
-    set options(value: ReadonlyArray<RawOption>);
+    set options(value: ReadonlyArray<AdwComboOptionInput>);
     /** Alias of `options` (Gtk.DropDown's model is often called "items"). */
     get items(): AdwDropDownOption[];
-    set items(value: ReadonlyArray<RawOption>);
+    set items(value: ReadonlyArray<AdwComboOptionInput>);
     /** The selected index. Out-of-range values are ignored (Gtk.DropDown:selected). */
     get selected(): number;
     set selected(value: number);
@@ -43,13 +41,13 @@ export declare class AdwDropDown extends HTMLElement {
     /** Whether the popover is currently open. */
     get active(): boolean;
     connectedCallback(): void;
-    disconnectedCallback(): void;
     attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
     private _parseOptionsAttr;
     private _selectIndex;
-    private _setActive;
+    private _onPopoverToggled;
     private _onButtonKeyDown;
-    private _onPopoverKeyDown;
+    /** Printable keys inside an OPEN popover, when there is no search entry to type into. */
+    private _onPopoverTypeAhead;
     /** Type-ahead: accumulate keys, focus/select the next matching option. */
     private _typeAhead;
     /** Filter the visible items by a search query (case-insensitive substring). */
@@ -60,4 +58,3 @@ export declare class AdwDropDown extends HTMLElement {
     private _updateSelectedStates;
     private _renderPopover;
 }
-export {};

package/lib/types/elements/adw-entry-row.d.ts

@@ -1,10 +1,100 @@
+import { EntryRowState, type EntryRowRenderState } from '@gjsify/adwaita-core';
+import { type AdwIcon } from './adw-icon.js';
 export declare class AdwEntryRow extends HTMLElement {
-    private _input;
-    private _titleEl;
-    private _initialized;
+    /** The headless `update_empty` derivation + apply latch (ADR 0004). */
+    protected readonly _state: EntryRowState;
+    protected _input: HTMLInputElement;
+    /** The large placeholder title (`empty_title` in adw-entry-row.ui). */
+    protected _emptyTitle: HTMLSpanElement;
+    /** The small label above the value (`title` in adw-entry-row.ui). */
+    protected _title: HTMLSpanElement;
+    /** The `editable-area` gizmo: both titles plus the input. */
+    protected _area: HTMLDivElement;
+    protected _editIcon: AdwIcon;
+    protected _indicator: HTMLSpanElement;
+    protected _applyButton: HTMLButtonElement;
+    protected _prefixes: HTMLDivElement;
+    protected _suffixes: HTMLDivElement;
+    protected _initialized: boolean;
+    /** Light-DOM children captured at build time, adopted after `_onConnected`. */
+    private _authored;
+    private _lastText;
+    private _lastLength;
     static get observedAttributes(): string[];
+    /**
+     * Class-name prefix for this row's parts. `<adw-password-entry-row>`
+     * overrides it so `_password_entry_row.scss` keeps matching its own parts —
+     * the two SCSS partials are near-identical but each scopes to its own tag.
+     */
+    protected get _classPrefix(): string;
+    /** The editable text. */
     get text(): string;
     set text(value: string);
+    /** `Adw.EntryRow:text-length` — the number of CHARACTERS, not UTF-16 units. */
+    get textLength(): number;
+    /** `Adw.EntryRow:max-length` — maximum number of characters, `0` = unlimited. */
+    get maxLength(): number;
+    set maxLength(value: number);
+    /** Whether the entry accepts edits (`GtkEditable:editable`). */
+    get editable(): boolean;
+    set editable(value: boolean);
+    /** `Adw.EntryRow:show-apply-button` — typing reveals an apply button. */
+    get showApplyButton(): boolean;
+    set showApplyButton(value: boolean);
+    /** `Adw.EntryRow:activates-default` — Enter may submit the surrounding form. */
+    get activatesDefault(): boolean;
+    set activatesDefault(value: boolean);
+    /** Whether the embedded entry currently has focus. */
+    get editing(): boolean;
     connectedCallback(): void;
     attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+    /**
+     * Add a widget after the editable area — `adw_entry_row_add_suffix`
+     * (adw-entry-row.c:885-899), which APPENDS into a box, so several suffixes
+     * coexist and the password row's own peek toggle survives a consumer's.
+     */
+    addSuffix(node: Node): void;
+    /**
+     * Add a widget before the editable area — `adw_entry_row_add_prefix`
+     * (C:864-880). PREPENDS, like the `gtk_box_prepend` it mirrors, so several
+     * prefixes stack in reverse call order exactly as they do in GTK.
+     */
+    addPrefix(node: Node): void;
+    /**
+     * Drive the trailing indicator — `adw_entry_row_set_show_indicator`
+     * (adw-entry-row-private.h, C:1281-1296). Private-to-the-library upstream,
+     * public here because `<adw-password-entry-row>` is a separate custom element
+     * rather than a C subclass with access to the private header.
+     */
+    setShowIndicator(show: boolean): void;
+    /** `adw_entry_row_set_indicator_icon_name` (C:1263-1273). */
+    setIndicatorIconName(iconName: string): void;
+    /** `adw_entry_row_set_indicator_tooltip` (C:1275-1279). */
+    setIndicatorTooltip(tooltip: string): void;
+    /** Apply the pending edit — the apply button click (C:229-241). */
+    apply(): void;
+    /** Focus the entry without selecting — `adw_entry_row_grab_focus_without_selecting` (C:1379-1389). */
+    grabFocusWithoutSelecting(): boolean;
+    /** Subclass hook: runs after the DOM exists and the state is seeded, before the first render. */
+    protected _onConnected(): void;
+    private _build;
+    /**
+     * Re-home the children the author wrote. libadwaita's buildable maps an
+     * untyped `<child>` to a suffix (C:796-812); `slot="prefix"` is the web
+     * spelling of its `type="prefix"`.
+     */
+    private _adoptAuthored;
+    /**
+     * `pressed_cb` (C:201-227): a click landing on the row, the editable area,
+     * the indicator or either affordance box grabs focus; anything else (a suffix
+     * control, the apply button) is left alone. The pencil is `can-target=False`
+     * in the .ui, so a click on it picks the editable area — hence it focuses too.
+     */
+    private _maybeFocus;
+    /** `text_activated_cb` (C:243-266) — exactly one of the two signals. */
+    private _activate;
+    private _renderTitle;
+    /** Paint one render snapshot. Overridden (via `super`) by the password row. */
+    protected _render(state: EntryRowRenderState): void;
+    private _onStateChanged;
 }

package/lib/types/elements/adw-expander-row.d.ts

@@ -1,9 +1,9 @@
+import './adw-switch.js';
 export declare class AdwExpanderRow extends HTMLElement {
     private _headerEl;
     private _titleEl;
     private _subtitleEl;
     private _enableSwitch;
-    private _enableLabel;
     private _chevronEl;
     private _contentEl;
     private _prefixEl;
@@ -11,6 +11,12 @@ export declare class AdwExpanderRow extends HTMLElement {
     /** The headless expanded/collapsed disclosure state machine (ADR 0004). */
     private readonly _state;
     private _initialized;
+    /**
+     * Guards the enable switch's `notify::active` while WE are the ones writing
+     * it. Only a user toggle publishes `notify::enable-expansion`; a programmatic
+     * `enableExpansion = …` re-syncs the control silently, as it always has.
+     */
+    private _reflectingEnable;
     constructor();
     static get observedAttributes(): string[];
     get expanded(): boolean;

package/lib/types/elements/adw-header-bar.d.ts

@@ -3,6 +3,13 @@ export declare class AdwHeaderBar extends HTMLElement {
     private _startEl;
     private _centerEl;
     private _endEl;
+    /**
+     * The generated title span, or `null` when a `slot="center"` title-widget
+     * took the centre. `Adw.HeaderBar` has the same either/or: setting
+     * `title-widget` replaces the derived `AdwWindowTitle` outright.
+     */
+    private _titleEl;
+    static get observedAttributes(): string[];
     /** The start (left) section container — append buttons/widgets here. */
     get startSection(): HTMLDivElement | null;
     /** The center (title) section — holds the `title` text or any `slot="center"`
@@ -11,4 +18,12 @@ export declare class AdwHeaderBar extends HTMLElement {
     /** The end (right) section container — append buttons/widgets here. */
     get endSection(): HTMLDivElement | null;
     connectedCallback(): void;
+    /**
+     * `title` used to be read ONCE, in `connectedCallback`, so every later write
+     * was a silent no-op — a header bar whose title tracked the open document
+     * kept whatever it was created with. `Adw.HeaderBar`'s derived title widget
+     * is bound to the property and re-renders on every change.
+     */
+    attributeChangedCallback(name: string): void;
+    private _renderTitle;
 }

package/lib/types/elements/adw-icon.d.ts

@@ -0,0 +1,25 @@
+export declare class AdwIcon extends HTMLElement {
+    static get observedAttributes(): string[];
+    /** The declared symbolic name, `-symbolic` suffix optional. */
+    get iconName(): string;
+    set iconName(value: string | null);
+    /**
+     * The name that actually reached the mask class — `''` when the icon-name is
+     * absent, empty, or not usable as one CSS token. Consumers that need to know
+     * whether an icon is being drawn ask this, not the raw attribute.
+     */
+    get resolvedIconName(): string;
+    /** The rendered edge length in px, or `null` when the stylesheet decides. */
+    get size(): number | null;
+    set size(value: number | null);
+    connectedCallback(): void;
+    attributeChangedCallback(): void;
+    private _render;
+}
+/**
+ * Build one icon node: the three lines every caller would otherwise write.
+ *
+ * `extraClasses` are the caller's own positioning/context classes, added
+ * alongside the managed `.adw-icon` + mask class rather than replacing them.
+ */
+export declare function createAdwIcon(iconName: string | null, ...extraClasses: string[]): AdwIcon;

package/lib/types/elements/adw-inline-view-switcher.d.ts

@@ -1,30 +1,92 @@
-/** The three display modes, mirroring AdwInlineViewSwitcherDisplayMode. */
-declare const DISPLAY_MODES: readonly ["labels", "icons", "both"];
-type DisplayMode = (typeof DISPLAY_MODES)[number];
+import type { ViewSwitcherScheduler } from '@gjsify/adwaita-core';
+import type { AdwInlineViewSwitcherDisplayMode, AdwViewSwitcherPage } from '@gjsify/adwaita-core';
 /** A single page. Children of <adw-inline-view-switcher>; consumed at connect time. */
 export declare class AdwViewStackPage extends HTMLElement {
     static get observedAttributes(): string[];
 }
 export declare class AdwInlineViewSwitcher extends HTMLElement {
+    /**
+     * The dwell timer, injectable.
+     *
+     * It used to be `new ViewSwitcherState({ scheduler: domViewSwitcherScheduler })`
+     * inline, which left NOWHERE to hand a clock in — so
+     * `VIEW_SWITCHER_DRAG_VECTORS` was driven by the core suite alone, and the
+     * conformance header claimed all three suites drove it. `scheduler` is a
+     * property so a test can replace it before the element connects; the DOM one
+     * is the default, exactly as before.
+     */
+    scheduler: ViewSwitcherScheduler;
+    private _stateInstance;
+    /** Built on first access, so a `scheduler` set before connect is the one used. */
+    private get _state();
     private _groupEl;
     private _pagesEl;
+    private _panels;
     private _toggles;
-    private _pages;
-    private _active;
     private _displayMode;
     private _initialized;
+    /** The page ELEMENTS, kept because this element detaches them from the tree. */
+    private _declared;
+    private _pageObserver;
     static get observedAttributes(): string[];
-    /** Zero-based index of the visible page. */
+    constructor();
+    /** Zero-based index of the visible PAGE, `-1` when nothing is selected. */
     get active(): number;
     set active(value: number);
+    /**
+     * Index of the ACTIVE TOGGLE, `-1` when the visible page has none because it
+     * is hidden — the port-safe `GTK_INVALID_LIST_POSITION`
+     * (adw-inline-view-switcher.c:441-446).
+     */
+    get activeToggle(): number;
     /** What the toggles display: 'labels', 'icons' or 'both'. */
-    get displayMode(): DisplayMode;
-    set displayMode(value: DisplayMode);
+    get displayMode(): AdwInlineViewSwitcherDisplayMode;
+    set displayMode(value: AdwInlineViewSwitcherDisplayMode);
+    /** Name of the visible page, `''` when nothing is selected. */
+    get visibleChildName(): string;
+    set visibleChildName(name: string | null | undefined);
+    /** The resolved page records. */
+    get pages(): readonly AdwViewSwitcherPage[];
+    /**
+     * Show or hide a page. Returns whether the SELECTION moved. Rebuilds the
+     * toggle row, because a hidden page has no toggle at all — C reacts to a
+     * page's `notify::visible` with `recreate_toggles`
+     * (adw-inline-view-switcher.c:425, :471-477).
+     */
+    setPageVisible(name: string, visible: boolean): boolean;
     connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * Re-read every declared page and push it into the state.
+     *
+     * Driven by {@link _watchPages}, which is what makes a runtime
+     * `badge-number` or `icon-name` change reach the toggle — C rebinds on every
+     * page `notify` (adw-view-switcher.c:184-193) and this element did not.
+     */
+    refreshPages(): void;
+    /**
+     * Watch the declared pages for attribute changes — the DOM's `notify::` on
+     * `AdwViewStackPage`, which C binds per page (adw-view-switcher.c:184-193).
+     *
+     * A `MutationObserver` rather than an `attributeChangedCallback`: this
+     * element consumes the page elements at connect and `replaceChildren`s them
+     * out of the tree, so a detached page cannot find its owner. It delivers on
+     * a MICROTASK where GTK's notify is synchronous — invisible to a user, and
+     * nothing here reads the toggle back inside the setter.
+     */
+    private _watchPages;
     attributeChangedCallback(name: string): void;
-    private _readActiveAttr;
     private _readDisplayModeAttr;
-    private _selectIndex;
+    /**
+     * Rebuild the toggle row from the derived models. One node per VISIBLE page,
+     * in compacted order — the structural half of `recreate_toggles`. Selection
+     * alone never lands here: `selection_changed_cb` only sets the active toggle
+     * (adw-inline-view-switcher.c:434-453), and rebuilding mid-drag would drop
+     * the dwell the drag has already armed.
+     */
+    private _rebuildToggles;
+    private _onStateChange;
     private _render;
+    private _applyStyleClasses;
+    private _reflectActive;
 }
-export {};

package/lib/types/elements/adw-menu-button.d.ts

@@ -1,3 +1,5 @@
+import type { SplitButtonDirection } from '@gjsify/adwaita-core';
+import './adw-popover.js';
 /** A menu entry. `id` defaults to `label` on activation; `icon` is optional. */
 export interface AdwMenuItem {
     id?: string;
@@ -9,11 +11,8 @@ export declare class AdwMenuButton extends HTMLElement {
     private _popoverEl;
     private _items;
     private _menuTitle;
-    private _active;
     private _initialized;
     private _itemButtons;
-    private _onDocumentPointerDown;
-    private _onDocumentKeyDown;
     static get observedAttributes(): string[];
     /** Whether the popover menu is currently open. */
     get active(): boolean;
@@ -23,12 +22,13 @@ export declare class AdwMenuButton extends HTMLElement {
     /** The optional popover heading. */
     get menuTitle(): string;
     set menuTitle(value: string);
+    /** Where the popover opens, and (via core) which way `none` folds. */
+    get direction(): SplitButtonDirection;
+    set direction(value: SplitButtonDirection);
     connectedCallback(): void;
-    disconnectedCallback(): void;
     attributeChangedCallback(name: string): void;
     private _parseMenuAttr;
-    private _setActive;
-    private _onMenuKeyDown;
+    private _onPopoverToggled;
     private _render;
     private _renderMenu;
 }

package/lib/types/elements/adw-navigation-split-view.d.ts

@@ -1,15 +1,63 @@
+import { type AdwPackType, type NavigationActionResult } from '@gjsify/adwaita-core';
+/** Detail of the `navigation-push` / `navigation-pop` delegation event. */
+export interface NavigationDelegateDetail {
+    /** The tag a `push` names; absent for a `pop`. */
+    tag?: string;
+    /** Set by an ancestor that handled it — the `return TRUE` of the C's routing. */
+    handled: boolean;
+}
 export declare class AdwNavigationSplitView extends HTMLElement {
     private _sidebarEl;
     private _contentEl;
     private _initialized;
+    private _disposeBreakpoint;
+    /** The ordering table, the tag guard and the action routing (ADR 0004). */
+    private _state;
+    /** Re-entrancy guard for the `show-content` reflection. */
+    private _reflecting;
     static get observedAttributes(): string[];
     get collapsed(): boolean;
     set collapsed(v: boolean);
     /** When collapsed, whether the content pane (true) or sidebar (false) shows. */
     get showContent(): boolean;
     set showContent(v: boolean);
+    /** Which side the sidebar is packed on — `start` (default) or `end`. */
+    get sidebarPosition(): AdwPackType;
+    set sidebarPosition(value: AdwPackType);
+    /** The sidebar page's tag of record, or `null`. */
+    get sidebarTag(): string | null;
+    /** The content page's tag of record, or `null`. */
+    get contentTag(): string | null;
+    /**
+     * `navigation.push` with `tag` — `navigation_push_cb` (:644-685).
+     *
+     * An unmatched tag DELEGATES to the parent before it may become a critical,
+     * which is how nested split views forward a push outwards; on this port that
+     * is a bubbling `navigation-push` event whose `detail.handled` an ancestor
+     * sets. Returns what the routing decided.
+     */
+    push(tag: string): NavigationActionResult;
+    /** `navigation.pop` — `navigation_pop_cb` (:687-702). */
+    pop(): NavigationActionResult;
     connectedCallback(): void;
+    /** `Adw.NavigationPage:tag` off the slotted pane, or `null` when untagged. */
+    private _tagOf;
+    /**
+     * Mirror the state's `showContent` onto the attribute, so the DOM keeps
+     * telling the truth after a `navigation.push` moved it.
+     *
+     * Guarded the way the overlay view's reflection is: writing the attribute
+     * re-enters `attributeChangedCallback`, which without the flag is a loop.
+     */
+    private _reflectShowContent;
+    disconnectedCallback(): void;
     attributeChangedCallback(name: string): void;
     private _syncWidth;
+    /** A pixel attribute, falling back to the widget's own default. */
+    private _widthAttr;
+    /** The reading direction `start` / `end` resolve against (`get_start_or_end`, :220-227). */
+    private get _direction();
     private _syncClasses;
+    /** (Re)bind the `breakpoint` condition to `collapsed`. */
+    private _syncBreakpoint;
 }

package/lib/types/elements/adw-navigation-view.d.ts

@@ -1,65 +1,108 @@
 /** A single navigation page. Children of <adw-navigation-view>. */
 export declare class AdwNavigationPage extends HTMLElement {
+    /** Set while the owning view writes an attribute back, so the sync cannot recurse. */
+    private _syncing;
     static get observedAttributes(): string[];
     get title(): string;
     set title(value: string);
     get tag(): string | null;
     set tag(value: string | null);
-    /** Whether the page can be popped (and thus shows a back button). */
+    /** Whether the page can be popped by a shortcut or the back button. */
     get canPop(): boolean;
     set canPop(value: boolean);
+    attributeChangedCallback(name: string, previous: string | null): void;
+    /** Put an attribute back the way it was, without re-entering the sync. */
+    revertAttribute(name: string, value: string | null): void;
 }
 export declare class AdwNavigationView extends HTMLElement {
     private _pagesEl;
-    private _pages;
-    private _stack;
-    private _dynamic;
-    private _backButtons;
+    private readonly _backButtons;
     private _initialized;
+    private readonly _diagnose;
+    private readonly _state;
     static get observedAttributes(): string[];
     /** Whether push/pop transitions are animated. */
     get animateTransitions(): boolean;
     set animateTransitions(value: boolean);
+    /** Whether pressing Escape pops the visible page (Adw.NavigationView:pop-on-escape). */
+    get popOnEscape(): boolean;
+    set popOnEscape(value: boolean);
     /** The currently-visible page (top of the stack), or null when empty. */
     get visiblePage(): AdwNavigationPage | null;
     /** The tag of the visible page, or null. */
     get visiblePageTag(): string | null;
+    /** The number of pages on the navigation stack. */
+    get depth(): number;
+    /** The navigation stack, bottom-first (Adw.NavigationView:navigation-stack). */
+    get navigationStack(): readonly AdwNavigationPage[];
+    /** Every page this view knows — static and dynamically pushed. */
+    get pages(): readonly AdwNavigationPage[];
+    /** Whether the automatic back button is shown (AdwBackButton's visibility rule). */
+    get canGoBack(): boolean;
+    /** The back button's tooltip — the previous page's title, or null when there is no button. */
+    get backButtonTooltip(): string | null;
     connectedCallback(): void;
-    attributeChangedCallback(): void;
+    attributeChangedCallback(name: string): void;
+    /**
+     * Push a page property change into the core. Called by
+     * {@link AdwNavigationPage.attributeChangedCallback}; a rename the core rejects
+     * (the tag is taken) is rolled back, because the attribute must not disagree
+     * with the tag index `push-by-tag` resolves against.
+     */
+    syncPageProperty(page: AdwNavigationPage, name: string, previous: string | null): void;
     /**
      * Add a static page without pushing it (mirrors AdwNavigationView.add). The
      * view keeps a reference; the page becomes reachable via push-by-tag. Named
      * `addPage` rather than `add` to avoid clashing with any DOM method.
      */
-    addPage(page: AdwNavigationPage): void;
+    addPage(page: AdwNavigationPage): boolean;
     /**
-     * Remove a static page (mirrors AdwNavigationView.remove). Named `removePage`
-     * to avoid overriding HTMLElement.remove() (which takes no arguments).
+     * Remove a page (mirrors AdwNavigationView.remove). A page that is on the
+     * stack is removed once it is POPPED, not now. Named `removePage` to avoid
+     * overriding HTMLElement.remove() (which takes no arguments).
      */
-    removePage(page: AdwNavigationPage): void;
+    removePage(page: AdwNavigationPage): boolean;
     /**
      * Push a page onto the navigation stack (mirrors AdwNavigationView.push).
      * Accepts a page element or, when given a string, the tag of a known page
-     * (push-by-tag, mirrors AdwNavigationView.push_by_tag). A page that is not
-     * already known is added dynamically and destroyed when it is popped.
+     * (push-by-tag). A page that is not already known is added dynamically and
+     * destroyed when it is popped.
      */
-    push(pageOrTag: AdwNavigationPage | string): void;
+    push(pageOrTag: AdwNavigationPage | string): boolean;
+    /** Push the page carrying `tag` (mirrors AdwNavigationView.push_by_tag). */
+    pushByTag(tag: string): boolean;
     /**
      * Pop the visible page off the stack (mirrors AdwNavigationView.pop).
-     * Returns true when a page was popped. A dynamically-pushed page is removed
-     * from the DOM. The root page cannot be popped.
+     * Returns true when a page was popped. The root page cannot be popped.
+     * `can-pop` does NOT gate this — it gates the shortcuts and the back button.
      */
     pop(): boolean;
-    /** Pop every page down to (and including pushing) the given tag's page. */
+    /** Pop until `page` is visible, in ONE transition (mirrors AdwNavigationView.pop_to_page). */
+    popToPage(page: AdwNavigationPage): boolean;
+    /** Pop until the page carrying `tag` is visible (mirrors AdwNavigationView.pop_to_tag). */
     popToTag(tag: string): boolean;
     /**
-     * Replace the whole navigation stack with the given pages (mirrors
-     * AdwNavigationView.replace). The last page becomes visible.
+     * Replace the whole navigation stack (mirrors AdwNavigationView.replace). The
+     * last page becomes visible; the transition is never animated.
+     *
+     * String entries are resolved BEFORE anything is mutated — the C does the same
+     * in replace_with_tags:3136-3147, and resolving late is what used to lose a
+     * dynamically-pushed page and blank the view.
      */
-    replace(pages: Array<AdwNavigationPage | string>): void;
-    private _resolvePage;
+    replace(pages: ReadonlyArray<AdwNavigationPage | string | null>): void;
+    /** Replace the stack with the pages carrying `tags` (mirrors AdwNavigationView.replace_with_tags). */
+    replaceWithTags(tags: readonly string[]): void;
+    /** The page with this tag, or null (mirrors AdwNavigationView.find_page). */
+    findPage(tag: string): AdwNavigationPage | null;
+    /** The page popping `page` would reveal (mirrors AdwNavigationView.get_previous_page). */
+    getPreviousPage(page: AdwNavigationPage): AdwNavigationPage | null;
+    private _onChange;
+    private _dispatch;
+    private readonly _onKeyDown;
     private _syncClasses;
     private _render;
+    private _attach;
+    private _detach;
     /** Inject (or remove) the automatic back button on the visible page. */
     private _syncBackButton;
     private _removeBackButton;