@gjsify/adwaita-web 0.31.0 → 0.32.0

package/lib/types/elements/adw-preferences-dialog.d.ts

@@ -1,10 +1,28 @@
+import type { PreferencesSearchResult, SearchPreferencesOptions } from '@gjsify/adwaita-core';
 /**
- * A single preferences page. Child of <adw-preferences-dialog>; consumed at
- * connect time. Carries optional `title` / `icon-name` attributes and any
+ * A single preferences page. Child of <adw-preferences-dialog>. Carries optional
+ * `title` / `icon-name` / `name` / `use-underline` attributes and any
  * <adw-preferences-group> content — mirrors Adw.PreferencesPage.
+ *
+ * The dialog keeps the page ELEMENT rather than hoisting its children out,
+ * because the page's identity is load-bearing: `adw_preferences_dialog_add`
+ * binds title / icon-name / name / use-underline / visible onto the view-stack
+ * page (adw-preferences-dialog.c:707-711), and `create_search_row_subtitle`
+ * needs the title back the moment a second page is visible.
  */
 export declare class AdwPreferencesPage extends HTMLElement {
     static get observedAttributes(): string[];
+    /** `adw_preferences_page_get_name` — the view-stack child name. */
+    get name(): string;
+    set name(value: string);
+    /** `AdwPreferencesPage:icon-name`, shown by a view switcher. */
+    get iconName(): string;
+    set iconName(value: string);
+    /** `AdwPreferencesPage:use-underline` — the title carries a mnemonic. */
+    get useUnderline(): boolean;
+    set useUnderline(value: boolean);
+    /** The page's groups, in document order. */
+    get groups(): HTMLElement[];
 }
 export declare class AdwPreferencesDialog extends HTMLElement {
     private _initialized;
@@ -12,6 +30,7 @@ export declare class AdwPreferencesDialog extends HTMLElement {
     private _dialogEl;
     private _titleEl;
     private _bodyEl;
+    private _pagesEl;
     private _closeBtn;
     static get observedAttributes(): string[];
     /** Whether the dialog is revealed. */
@@ -29,6 +48,42 @@ export declare class AdwPreferencesDialog extends HTMLElement {
     close(): void;
     /** Dismiss the dialog regardless of `can-close` (mirrors Adw.Dialog.force_close). */
     forceClose(): void;
+    /**
+     * `adw_preferences_dialog_add` (adw-preferences-dialog.c:693-716) — add a
+     * page at ANY time.
+     *
+     * Before this the pages were snapshotted once, in `connectedCallback`; a
+     * page appended later stayed a sibling of the scrim and rendered OUTSIDE
+     * the dialog card. GTK and the NativeScript port both accept a page
+     * whenever it arrives.
+     */
+    add(page: AdwPreferencesPage): void;
+    /**
+     * `adw_preferences_dialog_remove` (:723-745). C logs
+     * `ADW_CRITICAL_CANNOT_REMOVE_CHILD` and no-ops for a page it does not own;
+     * returning `false` is the same contract without a console write.
+     *
+     * NOT named `remove`: `ChildNode.remove()` already exists on every element
+     * and takes no arguments, so overriding it with a different signature makes
+     * the class un-assignable to `HTMLElement` — which `customElements.define`
+     * requires.
+     */
+    removePage(page: AdwPreferencesPage): boolean;
+    /** The dialog's pages, in add order. */
+    get pages(): AdwPreferencesPage[];
+    /**
+     * The preferences search (`filter_search_results` +
+     * `create_search_row_subtitle`), over this dialog's live page subtree.
+     *
+     * The whole pipeline is `@gjsify/adwaita-core`'s, so this dialog and the
+     * NativeScript one answer identically for the same tree — including the
+     * three corpus filters (visible page → visible group → titled visible row)
+     * and the case fold that makes `strasse` find `Straße`.
+     *
+     * An empty query returns the WHOLE corpus, which is what C does and what
+     * makes the results list non-empty before the user types.
+     */
+    search(query: string, options?: SearchPreferencesOptions): PreferencesSearchResult<Element>[];
     connectedCallback(): void;
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
     private _attemptClose;

package/lib/types/elements/adw-preferences-group.d.ts

@@ -1,12 +1,43 @@
 export declare class AdwPreferencesGroup extends HTMLElement {
+    private _headerEl;
     private _titleEl;
     private _descriptionEl;
     private _suffixEl;
+    private _listboxEl;
     private _initialized;
+    private _observer;
     static get observedAttributes(): string[];
     get description(): string;
     set description(value: string);
+    /**
+     * `adw_preferences_group_add` (adw-preferences-group.c:396-411): a row goes
+     * into the boxed list, a `header-suffix` child into the header.
+     *
+     * Exposed as a method AND wired to a `MutationObserver` on the host, because
+     * both spellings occur: `group.addRow(row)` in code, `group.append(row)` in
+     * a framework's rendering. Before this, a child appended after connect
+     * stayed a bare child of the host — outside the card, and invisible to the
+     * row count that decides whether the card is painted at all.
+     */
+    addRow(child: Node): void;
+    /**
+     * `adw_preferences_group_remove` (:421-440). C logs
+     * `ADW_CRITICAL_CANNOT_REMOVE_CHILD` and no-ops for a child it does not
+     * own; returning `false` is the same contract without a console write.
+     */
+    removeRow(child: Node): boolean;
     connectedCallback(): void;
+    disconnectedCallback(): void;
     attributeChangedCallback(): void;
+    /**
+     * Adopt children appended to the HOST after the subtree was built, so
+     * `group.append(row)` behaves like `adw_preferences_group_add`.
+     *
+     * C gets this for free — `gtk_widget_observe_children` on the listbox drives
+     * `update_listbox_visibility` through `items-changed`
+     * (adw-preferences-group.c:335-339) — and a DOM element needs the observer
+     * to have the same rule hold over time rather than only at connect.
+     */
+    private _observeHost;
     private _renderHeader;
 }

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

@@ -0,0 +1,38 @@
+export declare class AdwProgressBar extends HTMLElement {
+    private _trough;
+    private _progress;
+    private _text;
+    private _initialized;
+    static get observedAttributes(): string[];
+    /** How much of the bar is filled, 0…1. Always the CLAMPED value. */
+    get fraction(): number;
+    set fraction(value: number);
+    /** Whether the bar is indeterminate. */
+    get pulsing(): boolean;
+    set pulsing(value: boolean);
+    /** Whether the text node is shown. */
+    get showText(): boolean;
+    set showText(value: boolean);
+    /** The shown text. Falls back to the fraction as a percentage. */
+    get text(): string;
+    set text(value: string);
+    /** Whether the bar fills from the far end. */
+    get inverted(): boolean;
+    set inverted(value: boolean);
+    /** Whether the `.osd` hairline variant is used. */
+    get osd(): boolean;
+    set osd(value: boolean);
+    /** Whether the widget is dimmed. */
+    get disabled(): boolean;
+    set disabled(value: boolean);
+    /**
+     * Switch the bar to indeterminate — GtkProgressBar's method name for the
+     * same intent. See the module header: the bouncing block is a CSS animation
+     * here, so this ENTERS the state and repeat calls are no-ops; GTK's
+     * `pulse-step` arithmetic is not verifiable in this tree and is not faked.
+     */
+    pulse(): void;
+    connectedCallback(): void;
+    attributeChangedCallback(): void;
+    private _render;
+}

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

@@ -1,29 +1,61 @@
+import { type AdwSidebarItemSpec, type AdwSidebarSectionSpec, type SidebarItemFilter } from '@gjsify/adwaita-core';
 /** A single sidebar item. Child of <adw-sidebar-section>; consumed at connect time. */
 export declare class AdwSidebarItem extends HTMLElement {
     static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
 }
 /** A titled group of items. Child of <adw-sidebar>; consumed at connect time. */
 export declare class AdwSidebarSection extends HTMLElement {
     static get observedAttributes(): string[];
+    attributeChangedCallback(_name: string, _oldValue: string | null, newValue: string | null): void;
 }
 export declare class AdwSidebar extends HTMLElement {
+    private readonly _state;
     private _listEl;
     private _rows;
-    private _selected;
-    private _mode;
     private _initialized;
+    /** Guards the `selected` attribute write we make ourselves from re-entering. */
+    private _reflecting;
     static get observedAttributes(): string[];
     /** Zero-based flat index of the selected item, or -1 for no selection. */
     get selected(): number;
     set selected(value: number);
+    /** The selected item's spec, or undefined — Adw.Sidebar:selected-item. */
+    get selectedItem(): AdwSidebarItemSpec | undefined;
     /** 'sidebar' (flat navigation list) or 'page' (boxed lists). */
     get mode(): 'sidebar' | 'page';
     set mode(value: 'sidebar' | 'page');
+    /** The section/item model. Assigning replaces it, the way adw_sidebar_remove_all + append would. */
+    get sections(): readonly AdwSidebarSectionSpec[];
+    set sections(value: readonly AdwSidebarSectionSpec[]);
+    /** Adw.Sidebar:filter — decides which rows render, never the selection index space. */
+    get filter(): SidebarItemFilter | null;
+    set filter(value: SidebarItemFilter | null);
     connectedCallback(): void;
     attributeChangedCallback(name: string): void;
+    /**
+     * Re-derive after a declared `<adw-sidebar-item>` / `<adw-sidebar-section>`
+     * attribute changed. The item model keeps its shape, so the selection cannot
+     * move — exactly like the GObject property bindings this stands in for.
+     */
+    refresh(): void;
+    /** Snapshot the declared children into specs, and bind them for live updates. */
+    private _readDeclaredSections;
     private _readModeAttr;
+    /**
+     * `parseFloat`, not `parseInt`: the core rejects a fractional position, and
+     * truncating `"1.5"` to row 1 here would hide that from it. An unparseable
+     * value is NaN, which the core turns into "no selection".
+     */
     private _readSelectedAttr;
-    /** Click handler — selects the row (if changed) and always emits `activated`. */
-    private _activateIndex;
-    private _render;
+    private _reflectSelected;
+    private _onSelectionChanged;
+    /** Click handler — the core applies the selection, then `activated` fires. */
+    private _activate;
+    /** Rebuild the rendered rows + headers from the core's derived model. */
+    private _rebuild;
+    private _createHeader;
+    private _createRow;
+    private _applyMode;
+    private _applySelection;
 }

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

@@ -1,18 +1,64 @@
+import type { AdwMenuEntry, SplitButtonDirection } from '@gjsify/adwaita-core';
+import './adw-popover.js';
 export declare class AdwSplitButton extends HTMLElement {
+    private readonly _state;
     private _actionEl;
     private _dropdownEl;
+    private _arrowEl;
     private _menuEl;
-    private _label;
-    private _active;
+    /** Inline text content, captured before we take over the subtree. */
+    private _inlineLabel;
+    /** Last `open` value reflected as `notify::active`, so the event fires once per flip. */
+    private _openReflected;
     private _initialized;
-    private _onDocumentPointerDown;
     static get observedAttributes(): string[];
     /** Whether the dropdown menu is currently open. */
     get active(): boolean;
+    /** Whether the dropdown half is live (there is a menu to show). */
+    get dropdownEnabled(): boolean;
+    /** The action label, or `null` when the action half shows an icon or nothing. */
+    get label(): string | null;
+    set label(value: string);
+    /** The symbolic icon name, or `null` when the action half shows a label or nothing. */
+    get iconName(): string | null;
+    set iconName(value: string);
+    /** The dropdown menu entries. */
+    get menuItems(): readonly AdwMenuEntry[];
+    set menuItems(value: readonly AdwMenuEntry[]);
+    /** The dropdown tooltip as set — `''` while unset. */
+    get dropdownTooltip(): string;
+    set dropdownTooltip(value: string);
+    /** The direction the popup opens in, and the arrow points. */
+    get direction(): SplitButtonDirection;
+    set direction(value: SplitButtonDirection);
+    /** Whether an underline in the label marks a mnemonic. */
+    get useUnderline(): boolean;
+    set useUnderline(value: boolean);
+    /** Pop the menu up — `adw_split_button_popup()`. */
+    popup(): void;
+    /** Dismiss the menu — `adw_split_button_popdown()`. */
+    popdown(): void;
     connectedCallback(): void;
-    disconnectedCallback(): void;
-    attributeChangedCallback(): void;
-    private _setActive;
-    private _parseMenu;
+    attributeChangedCallback(name: string, _previous: string | null, value: string | null): void;
+    /** Seed label/icon/menu/direction/tooltip from the attributes present at connect time. */
+    private _syncStateFromAttributes;
+    /**
+     * Route a `label` / `icon-name` attribute mutation into the content machine.
+     *
+     * C has no independent "unset" for either slot — clearing one is a side
+     * effect of setting another — so a REMOVED attribute falls back to whichever
+     * sibling is still present, and to the empty child otherwise. That fallback
+     * is what makes `removeAttribute('label')` actually drop the label; it used
+     * to be a silent no-op, so the storybook's icon-only mode rendered the icon
+     * next to a stale "Save".
+     */
+    private _applyContentAttribute;
+    private _onStateChange;
     private _render;
+    /** The action half + the root style classes libadwaita derives from it. */
+    private _renderContent;
+    /** The dropdown half: arrow glyph, tooltip/accessible name, expanded state. */
+    private _renderDropdown;
+    /** The popover contents, one button per menu entry, dispatched BY POSITION. */
+    private _renderMenu;
 }

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

@@ -1,12 +1,21 @@
+import './adw-switch.js';
 export declare class AdwSwitchRow extends HTMLElement {
-    private _checkbox;
+    private _switchEl;
     private _titleEl;
     private _subtitleEl;
+    /** The headless active flag + its notify rule (ADR 0004). */
+    private readonly _state;
     private _initialized;
     static get observedAttributes(): string[];
     get active(): boolean;
     set active(value: boolean);
     connectedCallback(): void;
-    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+    attributeChangedCallback(name: string): void;
+    /**
+     * Push a state transition out to the DOM and emit `notify::active` — but
+     * only when something actually changed, which is the `g_object_notify`
+     * gate libadwaita puts on the same transition (C:224-225 → :76).
+     */
+    private _apply;
     private _renderText;
 }

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

@@ -0,0 +1,15 @@
+export declare class AdwSwitch extends HTMLElement {
+    private _input;
+    private _slider;
+    private _initialized;
+    static get observedAttributes(): string[];
+    /** Whether the switch is on. */
+    get active(): boolean;
+    set active(value: boolean);
+    /** Whether the switch is inert. */
+    get disabled(): boolean;
+    set disabled(value: boolean);
+    connectedCallback(): void;
+    attributeChangedCallback(name: string): void;
+    private _render;
+}

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

@@ -1,19 +1,41 @@
-/** A single page. Children of <adw-tab-view>; consumed at connect time. */
+import type { AdwTabPageSpec, AdwTabPageState } from '@gjsify/adwaita-core';
+/** A page descriptor as `pages` exposes it. */
+export type AdwTabViewPage = AdwTabPageState<HTMLElement>;
+/** The page spec the imperative insertion methods take. */
+export type AdwTabViewPageSpec = AdwTabPageSpec<HTMLElement>;
+/**
+ * A single page. Declared as a child of <adw-tab-view>; the element itself
+ * becomes the page panel, so its attributes keep driving the tab after connect —
+ * the old implementation moved the children out and discarded the element, which
+ * is why its `observedAttributes` declaration had nothing to act on.
+ */
 export declare class AdwTabPage extends HTMLElement {
     static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
 }
 export declare class AdwTabView extends HTMLElement {
-    private _barEl;
-    private _pagesEl;
-    private _tabs;
-    private _pages;
-    private _selected;
+    private readonly _state;
+    private readonly _barEl;
+    private readonly _tabBoxEl;
+    private readonly _pagesEl;
+    /** Tab chips keyed by page id — the bar is edited in place, never rebuilt. */
+    private readonly _tabs;
+    /** Page panels keyed by page id; kept so a DETACHED page's node is still reachable. */
+    private readonly _panels;
+    private readonly _hovered;
     private _initialized;
+    private _generatedIds;
+    /** Guards the `selected` attribute reflection against re-entering the model. */
+    private _reflecting;
     static get observedAttributes(): string[];
-    /** Zero-based index of the visible page. */
+    constructor();
+    /** Zero-based index of the visible page, `-1` when the view is empty. */
     get selected(): number;
     set selected(value: number);
-    /** Whether the tab bar hides itself when only one page remains. */
+    /**
+     * Whether the tab bar hides itself when it has nothing to show —
+     * `tabsRevealed`, which keeps the bar up for a single PINNED tab.
+     */
     get autohide(): boolean;
     set autohide(value: boolean);
     /** Whether tabs stretch to fill the bar evenly (Adw.TabBar `expand-tabs`). */
@@ -23,8 +45,103 @@ export declare class AdwTabView extends HTMLElement {
     get noClose(): boolean;
     set noClose(value: boolean);
     connectedCallback(): void;
-    attributeChangedCallback(name: string): void;
-    private _readSelectedAttr;
-    private _selectIndex;
-    private _render;
+    attributeChangedCallback(name: string, _old: string | null, _value: string | null): void;
+    /**
+     * Push a live `<adw-tab-page>` attribute change into the model. Called by
+     * {@link AdwTabPage.attributeChangedCallback}; not part of the public API.
+     */
+    syncDeclaredPage(pageEl: AdwTabPage, name: string, value: string | null): void;
+    /** All pages in order. */
+    get pages(): readonly AdwTabViewPage[];
+    /** Number of pages. */
+    get nPages(): number;
+    /** Length of the pinned prefix. */
+    get nPinnedPages(): number;
+    /** Id of the selected page, `null` when the view is empty. */
+    get selectedId(): string | null;
+    /** Index of the selected page, `-1` when the view is empty. */
+    get selectedIndex(): number;
+    /** The selected page's panel element, or `null`. */
+    get selectedContent(): HTMLElement | null;
+    isClosing(id: string): boolean;
+    setSelectedPage(id: string | null): boolean;
+    selectNthPage(n: number): boolean;
+    selectPreviousPage(): boolean;
+    selectNextPage(): boolean;
+    selectFirstPage(): boolean;
+    selectLastPage(): boolean;
+    /** Ctrl+Tab — the next page, wrapping to the first. */
+    cycleNextPage(): boolean;
+    /** Ctrl+Shift+Tab — the previous page, wrapping to the last. */
+    cyclePreviousPage(): boolean;
+    /** Add a page opened FROM `parentId`, deriving its position (Adw.TabView.add_page). */
+    addPage(spec: AdwTabViewPageSpec, parentId?: string | null): number;
+    insertPage(spec: AdwTabViewPageSpec, position: number): number;
+    prependPage(spec: AdwTabViewPageSpec): number;
+    appendPage(spec: AdwTabViewPageSpec): number;
+    insertPinnedPage(spec: AdwTabViewPageSpec, position: number): number;
+    prependPinnedPage(spec: AdwTabViewPageSpec): number;
+    appendPinnedPage(spec: AdwTabViewPageSpec): number;
+    /** Pin or unpin a page, re-ordering it in the same step. Returns its new position. */
+    setPagePinned(id: string, pinned: boolean): number;
+    /**
+     * Request a close. Dispatches a CANCELABLE `close-page`; calling
+     * `preventDefault()` on it holds the page open until {@link closePageFinish}.
+     */
+    closePage(id: string): boolean;
+    closePageFinish(id: string, confirm: boolean): boolean;
+    closeOtherPages(id: string): void;
+    closePagesBefore(id: string): void;
+    closePagesAfter(id: string): void;
+    /** Remove a page unconditionally, running the successor rule first. */
+    detachPage(id: string): AdwTabViewPage | null;
+    reorderPage(id: string, position: number): boolean;
+    reorderBackward(id: string): boolean;
+    reorderForward(id: string): boolean;
+    reorderFirst(id: string): boolean;
+    reorderLast(id: string): boolean;
+    setPageTitle(id: string, title: string | null): boolean;
+    setPageTooltip(id: string, tooltip: string | null): boolean;
+    setPageIcon(id: string, icon: string | null): boolean;
+    setPageLoading(id: string, loading: boolean): boolean;
+    setPageNeedsAttention(id: string, needsAttention: boolean): boolean;
+    /** Every precondition the model refused, as C would have warned about it. */
+    get diagnostics(): readonly string[];
+    private _adoptDeclaredPage;
+    /** Give a spec its panel, so `append({ id })` with no content is legal. */
+    private _withPanel;
+    private _nextId;
+    private _onPagesChange;
+    private _insertTab;
+    /** Remove-then-insert, the same shape the model's own reorder has. */
+    private _moveTab;
+    private _refreshTab;
+    /**
+     * `tabCloseVisible` (adw-tab.c:124 + the pinned gate at :645-650). `dragging`
+     * is constantly false — tab drag-and-drop is compositor work and is not
+     * modelled — and `fullyVisible` is measured against the bar's scroll window,
+     * which is exactly what the C term means for a horizontally scrolled bar.
+     */
+    private _refreshCloseVisibility;
+    private _onSelectionChange;
+    private _applyActiveState;
+    private _applyBarVisibility;
+    private _reflectSelected;
+    private _applySelectedAttribute;
+    /**
+     * The `Adw.TabView` shortcut table (`init_shortcuts`, adw-tab-view.c:2192+),
+     * plus the ArrowLeft/ArrowRight movement `role=tablist` promises.
+     *
+     * Ctrl+Tab WRAPS and Ctrl+Page-Up/Down does not — the same `last` flag that
+     * separates them in `select_page_cb` (:2017-2041). Alt+0 is page index 9,
+     * because pages count from 0 (:2149-2150).
+     */
+    private _onKeyDown;
+    /**
+     * The `close-page` seam. A CANCELABLE DOM event is the idiomatic spelling of
+     * the C signal's return value: letting it through takes libadwaita's default
+     * (`!pinned`, adw-tab-view.c:1990-1991), and `preventDefault()` defers the
+     * close until the app calls {@link closePageFinish}.
+     */
+    private _requestClose;
 }

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

@@ -3,6 +3,8 @@ export declare class AdwToolbarView extends HTMLElement {
     private _contentEl;
     private _bottomEl;
     private _initialized;
+    private _resize;
+    static get observedAttributes(): string[];
     /** The top-bar container — append header bars here imperatively. */
     get topBar(): HTMLDivElement;
     /** The scrollable content container. */
@@ -10,4 +12,7 @@ export declare class AdwToolbarView extends HTMLElement {
     /** The bottom-bar container. */
     get bottomBar(): HTMLDivElement;
     connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(): void;
+    private _syncClasses;
 }

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

@@ -1,37 +1,45 @@
+import type { AdwViewStackPageInfo as CorePageInfo } from '@gjsify/adwaita-core';
 /** A page descriptor exposed via `pages` (consumed by a bound switcher bar). */
-export interface AdwViewStackPageInfo {
-    /** Stable id used by visibleChildName + switcher binding. */
-    name: string;
-    /** Human-facing title shown by a bound switcher. */
-    title: string;
-    /** Symbolic icon name (no `-symbolic` suffix), or '' for none. */
-    icon: string;
-    /** The page's content container (the visibility-toggled node). */
-    element: HTMLElement;
-}
+export type AdwViewStackPageInfo = CorePageInfo<HTMLElement>;
 export declare class AdwViewStack extends HTMLElement {
-    private _pages;
-    private _visibleIndex;
+    private readonly _state;
     private _initialized;
     static get observedAttributes(): string[];
+    constructor();
     /** All pages in declaration/add order. A bound switcher reads this. */
     get pages(): readonly AdwViewStackPageInfo[];
-    /** Zero-based index of the visible page. Out-of-range/same values no-op. */
+    /** Zero-based index of the visible page, `-1` when nothing is selected. */
     get visibleChildIndex(): number;
     set visibleChildIndex(value: number);
-    /** Name of the visible page, or '' when the stack is empty. */
+    /** Name of the visible page, or '' when nothing is selected. */
     get visibleChildName(): string;
-    set visibleChildName(name: string);
-    /** The visible page's content element, or null when empty. */
+    set visibleChildName(name: string | null | undefined);
+    /** The visible page's content element, or null when nothing is selected. */
     get visibleChild(): HTMLElement | null;
     connectedCallback(): void;
     attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
     /**
-     * Append a page. The FIRST page added becomes visible automatically; later
-     * pages are added hidden. Mirrors Adw.ViewStack.add()/the NS twin's add().
+     * Append a page. It becomes visible when nothing is selected yet, matching
+     * `Adw.ViewStack.add()` — and, unlike before, that auto-pick NOTIFIES.
      */
     add(content: HTMLElement, name: string, title?: string, icon?: string): AdwViewStackPageInfo;
     /** Convenience alias mirroring Adw.ViewStack.add_titled() (no icon). */
     addTitled(content: HTMLElement, name: string, title: string): AdwViewStackPageInfo;
-    private _apply;
+    /**
+     * Remove the first page named `name` and detach its content. Returns whether
+     * anything was removed. When the removed page was the visible one the stack
+     * ends up showing NOTHING and emits no event — `stack_remove` clears
+     * `visible_child` without re-picking (adw-view-stack.c:1202-1203).
+     */
+    removePage(name: string): boolean;
+    /**
+     * Show or hide a page (`AdwViewStackPage:visible`). Returns whether the
+     * SELECTION moved: hiding the visible page falls back to the next visible
+     * one, and making a page visible while nothing is selected selects it
+     * (`update_child_visible`, adw-view-stack.c:1061-1082).
+     */
+    setPageVisible(name: string, visible: boolean): boolean;
+    private _onStateChange;
+    private _applyVisibility;
+    private _reflectName;
 }

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

@@ -1,27 +1,43 @@
 import type { AdwViewStack } from './adw-view-stack.js';
 export declare class AdwViewSwitcherBar extends HTMLElement {
+    private readonly _barState;
     private _barEl;
-    private _buttons;
+    private _nodes;
     private _stack;
-    private _revealed;
     private _initialized;
-    private _onStackNotify;
+    private readonly _onStackNotify;
     static get observedAttributes(): string[];
+    constructor();
     /** The bound stack element, or null when unbound. */
     get stack(): AdwViewStack | null;
     set stack(value: AdwViewStack | string | null);
-    /** Whether the bar is revealed (shown). Hidden when false. */
+    /** Whether the layout asked for the bar — `Adw.ViewSwitcherBar:reveal`. */
+    get reveal(): boolean;
+    set reveal(value: boolean);
+    /**
+     * Whether the bar is actually shown. READ-ONLY: a one-page stack keeps it
+     * collapsed however loudly the layout asks (adw-view-switcher-bar.c:125).
+     * Write {@link reveal} to make the request.
+     */
     get revealed(): boolean;
-    set revealed(value: boolean);
     connectedCallback(): void;
     disconnectedCallback(): void;
     attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
     /** Bind to a stack element (or null). Unbinds the previous one and rebuilds. */
     setStack(stack: AdwViewStack | null): void;
-    /** Rebuild the buttons — call after adding pages to the bound stack. */
+    /**
+     * Rebuild the buttons — needed after pages were added to the bound stack
+     * WITHOUT changing its selection. A page add that does move the selection
+     * (the first one) notifies and rebuilds on its own. libadwaita rebuilds on
+     * the pages model's `items-changed` (adw-view-switcher.c:258-263), which the
+     * DOM stack has no counterpart for yet.
+     */
     refresh(): void;
+    private _readReveal;
+    private _bindStack;
+    private _unbindStack;
     private _resolveStack;
     private _rebuild;
-    private _syncActive;
+    private _buildButton;
     private _applyRevealed;
 }