@gjsify/adwaita-nativescript 0.31.0 → 0.32.0

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

@@ -1,33 +1,88 @@
-import { GridLayout, View, type EventData } from '@nativescript/core';
-/** Event name emitted when the visible page changes. Mirrors GObject `notify::visible-page`. */
-export declare const NOTIFY_VISIBLE_PAGE = "notify::visible-page";
-/** Payload of the `notify::visible-page` event. */
-export interface NotifyVisiblePageEventData extends EventData {
-    /** The newly-visible page's tag, or `null`. */
+import { GridLayout, type EventData, type View } from '@nativescript/core';
+import type { AdwNavigationPageProps, NavigationShortcutResult } from '@gjsify/adwaita-core';
+import { NOTIFY_VISIBLE_PAGE, POPPED, PUSHED, REPLACED } from './navigation-stack.js';
+export { NOTIFY_VISIBLE_PAGE, POPPED, PUSHED, REPLACED };
+/** Payload of every navigation signal — `pushed`, `popped`, `replaced`, `notify::visible-page`. */
+export interface AdwNavigationEventData extends EventData {
+    /** The page the signal is about, or `null` (`replaced`, or an emptied view). */
+    page: View | null;
+    /** That page's tag, or `null`. */
     tag: string | null;
     /** The current navigation stack depth. */
     depth: number;
 }
+/** Payload of the `notify::visible-page` event. */
+export type NotifyVisiblePageEventData = AdwNavigationEventData;
 export declare class AdwNavigationView extends GridLayout {
-    /** All registered pages (by tag), addressable by `push(tag)`. */
-    private readonly _pages;
-    /** The live navigation stack (last entry = visible). */
-    private readonly _stack;
+    private readonly _nav;
     constructor();
     /**
-     * Register a page (optionally with a tag for `push(tag)`). The FIRST page added
-     * is auto-pushed so the view is never empty, matching `Adw.NavigationView`.
+     * Register a page (optionally with a tag for `push(tag)`). A page added while
+     * the stack is EMPTY is pushed automatically, so the view is never blank —
+     * which also re-arms after `replace([])`.
+     */
+    add(view: View, tag?: string | null, options?: Omit<AdwNavigationPageProps, 'tag'>): boolean;
+    /**
+     * Remove a page (`AdwNavigationView.remove`). One that is on the stack is
+     * removed once it is POPPED. Named `removePage` rather than `remove` so the
+     * widget never shadows a member of NativeScript's own `ViewBase`, the same
+     * reason `@gjsify/adwaita-web` avoids `HTMLElement.remove()`.
      */
-    add(view: View, tag?: string | null): void;
+    removePage(view: View): boolean;
     /** Push a page (a previously-registered tag, or a fresh view) onto the stack. */
-    push(pageOrTag: View | string): void;
-    /** Pop the top page. Returns `true` if a page was popped (stack keeps ≥1). */
+    push(viewOrTag: View | string, options?: AdwNavigationPageProps): boolean;
+    /** Push the page carrying `tag`. */
+    pushByTag(tag: string): boolean;
+    /**
+     * Pop the top page. Returns `true` if a page was popped (the stack keeps ≥1).
+     * `can-pop` does NOT gate this — it gates {@link popFromShortcut} and the back
+     * button, exactly as libadwaita documents.
+     */
     pop(): boolean;
-    private _applyVisible;
+    /** Pop until `view` is visible, in ONE transition. */
+    popToPage(view: View): boolean;
+    /** Pop until the page carrying `tag` is visible. */
+    popToTag(tag: string): boolean;
+    /** Replace the whole stack; the last entry becomes visible. Never animates. */
+    replace(entries: ReadonlyArray<View | string | null>): void;
+    /** Replace the stack with the pages carrying `tags`. */
+    replaceWithTags(tags: readonly string[]): void;
+    /** The page with this tag, or `null`. */
+    findPage(tag: string): View | null;
+    /** The page popping `view` would reveal, or `null`. */
+    getPreviousPage(view: View): View | null;
+    /** Set a page's tag. Rejected when another page already owns it. */
+    setPageTag(view: View, tag: string | null): boolean;
+    /** Set a page's title — used as the NEXT page's back-button tooltip. */
+    setPageTitle(view: View, title: string): boolean;
+    /** Set a page's `can-pop`, gating the shortcuts and a back button. */
+    setPageCanPop(view: View, canPop: boolean): boolean;
+    /** Whether a back button belongs on the visible page. */
+    canGoBack(): boolean;
+    /** The back button's label/tooltip — the previous page's title, or `null` when there is none. */
+    backButtonTooltip(fallback?: string): string | null;
+    /** The `can-pop`-aware pop, for a hardware/software back button. */
+    popFromShortcut(): NavigationShortcutResult;
+    /** Escape-to-pop, gated on {@link popOnEscape}. */
+    popFromEscape(): NavigationShortcutResult;
     /** The currently-visible page view, or `null`. */
     get visiblePage(): View | null;
     /** The currently-visible page tag, or `null`. */
     get visiblePageTag(): string | null;
     /** The current navigation stack depth. */
     get depth(): number;
+    /** The navigation stack, bottom-first. */
+    get navigationStack(): readonly View[];
+    /** Every registered page — static and dynamically pushed. */
+    get pages(): readonly View[];
+    /**
+     * `Adw.NavigationView:animate-transitions`. Kept for API parity: the NS CSS
+     * subset has no transition, so the swap is instant either way.
+     */
+    get animateTransitions(): boolean;
+    set animateTransitions(value: boolean);
+    /** `Adw.NavigationView:pop-on-escape` — consulted by {@link popFromEscape}. */
+    get popOnEscape(): boolean;
+    set popOnEscape(value: boolean);
+    private _emit;
 }

package/lib/types/widgets/adw-overlay-split-view.d.ts

@@ -1,12 +1,34 @@
 import { AdwSplitViewBase } from './split-view-base.js';
-export declare class AdwOverlaySplitView extends AdwSplitViewBase {
+import { NsOverlaySplitViewState } from './split-view-state.js';
+export declare class AdwOverlaySplitView extends AdwSplitViewBase<NsOverlaySplitViewState> {
     /** Dimmed backdrop drawn between content and the overlaid sidebar; tapping it
      *  closes the sidebar (Adwaita's click-outside-to-dismiss). Created lazily. */
     private _scrim;
     constructor();
+    /**
+     * `Adw.OverlaySplitView:pin-sidebar` (adw-overlay-split-view.c:990-992,
+     * default FALSE) — whether collapsing leaves the sidebar's visibility alone.
+     */
+    get pinSidebar(): boolean;
+    set pinSidebar(value: boolean);
     protected _applyLayout(): void;
     /** Animate a collapsed show/hide toggle; fall back to instant off-screen/off-device. */
     protected _transitionSidebar(): void;
+    /**
+     * `gtk_widget_set_can_focus (sidebar_bin, !collapsed || show_sidebar)` and its
+     * mirror (:330-331, :1460-1461), as NativeScript spells it.
+     *
+     * Without this the pane hidden UNDER the overlay keeps answering taps and stays
+     * in the screen-reader order — the scrim only shields the area it covers, and a
+     * `translateX`-ed sidebar is not covered at all.
+     *
+     * DEVIATION the C cannot settle: GTK sets `can-focus` on its own `AdwBin`
+     * WRAPPER, leaving the application's child untouched. NativeScript has no such
+     * wrapper — the pane IS the view the consumer handed us — so this writes on
+     * their view, and a pane the app deliberately made non-interactive is made
+     * interactive again the next time it comes on screen.
+     */
+    private _applyPaneFocus;
     /** Lazily create the tap-to-dismiss scrim. */
     private _ensureScrim;
     /** Re-establish paint order: content < scrim < sidebar (NS paints in add order).
@@ -24,5 +46,10 @@ export declare class AdwOverlaySplitView extends AdwSplitViewBase {
     private _animateClose;
     /** Off-screen sidebar offset: slides past the edge it's anchored to. */
     private _hiddenOffset;
-    private _stripOverlay;
+    /**
+     * The sidebar pane's class list for the current mode — the NativeScript
+     * spelling of `update_collapsed`'s css-class swap (:727-738): `overlay-pane`
+     * while collapsed, `sidebar-pane` while docked, never both.
+     */
+    private _paneClassName;
 }

package/lib/types/widgets/adw-password-entry-row.d.ts

@@ -1,12 +1,42 @@
+import type { EventData } from '@nativescript/core';
 import { AdwEntryRow } from './adw-entry-row.js';
 import { AdwImageButton } from './adw-image-button.js';
+export { PasswordEntryRowState } from '@gjsify/adwaita-core';
+export type { PasswordEntryRowRenderState } from '@gjsify/adwaita-core';
+/** Event name emitted when the peek state flips. Mirrors a GObject `notify::`. */
+export declare const NOTIFY_REVEALED = "notify::revealed";
+/** Payload of the `notify::revealed` event. */
+export interface NotifyRevealedEventData extends EventData {
+    /** Whether the contents are now shown in clear text. */
+    revealed: boolean;
+}
 export declare class AdwPasswordEntryRow extends AdwEntryRow {
+    /** The headless peek + caps-lock derivation, composing the parent row's state. */
+    private readonly _password;
     /** The trailing peek (reveal/conceal) toggle button. */
     protected readonly _peekButton: AdwImageButton;
     constructor();
-    /** Toggle the masked/revealed state + swap the eye icon. */
-    private _togglePeek;
-    /** Whether the password is currently revealed (the value is shown). */
+    /** Whether the contents are shown in clear text (`GtkText:visibility`). */
+    get revealed(): boolean;
+    set revealed(value: boolean);
+    /**
+     * Legacy spelling of {@link revealed}. The web port called it `revealed`, this
+     * one called it `peeking`, and neither name is in the C — kept so existing
+     * NativeScript callers keep working while `revealed` is the shared name.
+     */
     get peeking(): boolean;
     set peeking(value: boolean);
+    /** Flip masked↔revealed — `show_text_clicked_cb` (C:90-97). */
+    togglePeek(): boolean;
+    /** Whether Caps Lock is engaged, as last reported by the host. */
+    get capsLockOn(): boolean;
+    /**
+     * Feed the platform's Caps Lock state in — GDK reads it off the keyboard
+     * device (C:111-115). NativeScript surfaces no equivalent, so this is the
+     * host's seam.
+     */
+    setCapsLockOn(on: boolean): void;
+    protected get _baseClassName(): string;
+    /** `notify_visibility_cb` (C:62-81), applied to the NS views. */
+    private _renderPassword;
 }

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

@@ -1,4 +1,6 @@
 import { GridLayout, Label, StackLayout, View } from '@nativescript/core';
+import type { SearchPreferencesOptions } from '@gjsify/adwaita-core';
+import { type NsPreferencesSearchResult, type NsSearchablePage } from './preferences-search.js';
 /** Event name emitted when the dialog is closed. */
 export declare const CLOSED = "closed";
 export declare class AdwPreferencesDialog extends GridLayout {
@@ -14,6 +16,22 @@ export declare class AdwPreferencesDialog extends GridLayout {
     add(view: View): void;
     /** Remove a previously-added page from the body. */
     remove(view: View): void;
+    /**
+     * The pages this dialog searches, in add order.
+     *
+     * Reads the live body children, so a page added or removed after the dialog
+     * was built is indexed without an invalidation step. A plain view dropped
+     * into the body is not a page and contributes nothing.
+     */
+    get searchPages(): readonly NsSearchablePage[];
+    /**
+     * The preferences search (`filter_search_results` +
+     * `create_search_row_subtitle`) over this dialog's live pages.
+     *
+     * An empty query returns the WHOLE corpus, which is what C does and what
+     * keeps a results list populated before the user types.
+     */
+    search(query: string, options?: SearchPreferencesOptions): NsPreferencesSearchResult[];
     /** Reveal the preferences overlay. */
     present(): void;
     /** Hide the preferences overlay and emit `closed`. */

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

@@ -1,23 +1,71 @@
-import { StackLayout, Label, View } from '@nativescript/core';
-export declare class AdwPreferencesGroup extends StackLayout {
-    /** The group header label (created lazily — only in the tree when a title is set). */
+import { GridLayout, Label, StackLayout, View } from '@nativescript/core';
+import type { NsSearchableGroup, NsSearchableRow } from './preferences-search.js';
+export declare class AdwPreferencesGroup extends StackLayout implements NsSearchableGroup {
+    /** The header box: labels on the leading edge, suffix on the trailing one. */
+    protected readonly _header: GridLayout;
+    /** The group header label. */
     protected readonly _titleLabel: Label;
-    private _hasTitle;
+    /** The dimmed description line below the title. */
+    protected readonly _descriptionLabel: Label;
+    /** Host for the optional `header-suffix` view. */
+    protected readonly _suffixHost: StackLayout;
     /** The boxed-list container that actually holds the rows. */
     protected readonly _listbox: StackLayout;
+    private _title;
+    private _description;
+    private _headerSuffix;
     constructor();
     /**
-     * The group title (dim, uppercase header above the boxed list). Setting a
-     * non-empty value inserts the header label above the list; setting empty
-     * removes it — so a titleless group has no blank header, matching
-     * `Adw.PreferencesGroup`.
+     * The group title (dim, uppercase header above the boxed list).
+     *
+     * `null`/`undefined` is the empty string, as
+     * `adw_preferences_group_set_title` normalises it
+     * (adw-preferences-group.c:508).
      */
     get title(): string;
     set title(value: string);
+    /**
+     * The dimmed description line below the title.
+     *
+     * Normalised here even though `adw_preferences_group_set_description` passes
+     * NULL straight through (:555) where its own `set_title` and
+     * `adw_preferences_page_set_title` both normalise — the visibility test
+     * treats NULL and `""` alike, so the inconsistency has no consequence.
+     */
+    get description(): string;
+    set description(value: string);
+    /**
+     * The `header-suffix` view — displayed above the list, next to the title and
+     * description; commonly a button or a spinner for the whole group
+     * (`adw_preferences_group_set_header_suffix`, :597-625).
+     *
+     * A suffix keeps the header alive even with no title AND makes it
+     * single-line, which is why it feeds the derivation rather than only the
+     * tree.
+     */
+    get headerSuffix(): View | null;
+    set headerSuffix(view: View | null);
     /** Append a row (or any view) to the boxed list. */
     addRow(view: View): void;
     /** Remove a previously-added row from the boxed list. */
     removeRow(view: View): void;
+    /**
+     * The rows this group contributes to a preferences search, in listbox order.
+     *
+     * Reads the live children rather than a parallel list, so a consumer that
+     * empties the listbox directly (the storybook's controls panel does) cannot
+     * leave a stale index behind.
+     */
+    searchRows(): readonly NsSearchableRow[];
+    /**
+     * Push the derived header/listbox state onto the views.
+     *
+     * Re-reads the live child count on every call — `update_listbox_visibility`
+     * is wired to the row model's `items-changed`
+     * (adw-preferences-group.c:335-339), so the rule has to hold after every
+     * mutation and not only at construction.
+     */
+    private _applyVisuals;
     /**
      * Mark the FIRST row so it draws no top separator. Adwaita draws hairline
      * separators BETWEEN rows only; the `.boxed-list .adw-row` top-border rule

package/lib/types/widgets/adw-preferences-page.d.ts

@@ -1,12 +1,43 @@
 import { ScrollView, StackLayout, View } from '@nativescript/core';
-export declare class AdwPreferencesPage extends ScrollView {
+import type { NsSearchableGroup, NsSearchablePage } from './preferences-search.js';
+export declare class AdwPreferencesPage extends ScrollView implements NsSearchablePage {
     /** The vertical stack that actually holds the groups. */
     protected readonly _content: StackLayout;
+    private _title;
+    private _name;
+    private _iconName;
+    private _useUnderline;
     constructor();
+    /**
+     * `AdwPreferencesPage:title` — shown by a view switcher and by the search
+     * results, never by the page itself. `null` is the empty string
+     * (`adw_preferences_page_set_title`, adw-preferences-page.c:538).
+     */
+    get title(): string;
+    set title(value: string);
+    /** `AdwPreferencesPage:name` — the view-stack child name. */
+    get name(): string;
+    set name(value: string);
+    /** `AdwPreferencesPage:icon-name` — the symbolic a view switcher shows. */
+    get iconName(): string;
+    set iconName(value: string);
+    /**
+     * `AdwPreferencesPage:use-underline` — the title carries a mnemonic, which
+     * a search-result subtitle strips before showing it (:196-199).
+     */
+    get useUnderline(): boolean;
+    set useUnderline(value: boolean);
     /** Append a preferences group (or any view) to the page. */
     addGroup(view: View): void;
     /** Remove a previously-added group from the page. */
     removeGroup(view: View): void;
+    /**
+     * The groups this page contributes to a preferences search, in order.
+     *
+     * Reads the live children so a group added or removed later is indexed
+     * without an invalidation step.
+     */
+    searchGroups(): readonly NsSearchableGroup[];
     /** The vertical content stack holding the groups. */
     get groups(): StackLayout;
 }

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

@@ -1,27 +1,69 @@
 import { ScrollView, StackLayout, type EventData } from '@nativescript/core';
+import type { AdwSidebarItemSpec, AdwSidebarSectionSpec, SidebarItemFilter } from './sidebar-model.js';
 /** Event name emitted when {@link AdwSidebar.selected} changes. Mirrors GObject `notify::selected`. */
 export declare const NOTIFY_SELECTED = "notify::selected";
+/**
+ * Event name emitted on EVERY row tap, including a re-tap of the selected row.
+ * Mirrors the `AdwSidebar::activated` signal (adw-sidebar.c:1601-1612).
+ */
+export declare const ACTIVATED = "activated";
 /** Payload of the `notify::selected` event. */
 export interface NotifySidebarSelectedEventData extends EventData {
-    /** The newly-selected item index. */
+    /** The newly-selected item index, or -1 for no selection. */
     selected: number;
-    /** The newly-selected item's label. */
+    /** The newly-selected item's label (`''` when nothing is selected). */
+    title: string;
+    /** The index the selection moved away from. */
+    previous: number;
+    /** True for a row tap; false for a programmatic set or a model change. */
+    interactive: boolean;
+}
+/** Payload of the `activated` event. */
+export interface SidebarActivatedEventData extends EventData {
+    /** Flat index of the activated item. */
+    index: number;
+    /** The activated item's label. */
     title: string;
 }
 export declare class AdwSidebar extends ScrollView {
     /** The vertical list container. */
     protected readonly _list: StackLayout;
+    private readonly _state;
     private readonly _rows;
-    private _items;
-    private _selected;
     constructor();
-    /** Set the navigation item labels. Rebuilds the tappable rows. */
+    /** Set the navigation item labels — one untitled section. Rebuilds the tappable rows. */
     setItems(items: string[]): void;
+    /** Set the full section model (titles, subtitles, icons, per-item `visible`/`enabled`). */
+    setSections(sections: readonly AdwSidebarSectionSpec[]): void;
+    private _rebuild;
+    /** Tap handler — the core applies the selection, then `activated` fires. */
+    private _activate;
     private _applySelection;
-    /** The navigation item labels. */
+    /** The navigation item labels, in flat index order. */
     get items(): string[];
     set items(value: string[]);
-    /** The selected item index. Highlights the row + emits `notify::selected`. */
+    /** The section model. */
+    get sections(): readonly AdwSidebarSectionSpec[];
+    set sections(value: readonly AdwSidebarSectionSpec[]);
+    /**
+     * The selected item index, or -1 for no selection. Writing an index that is
+     * not a valid position — out of range, negative, fractional — clears the
+     * selection rather than being ignored (adw-sidebar.c:3028-3029).
+     */
     get selected(): number;
     set selected(value: number);
+    /** The selected item, or undefined — `adw_sidebar_get_selected_item`. */
+    get selectedItem(): AdwSidebarItemSpec | undefined;
+    /**
+     * `Adw.Sidebar:mode`. Only the BEHAVIOURAL half is implemented here: page
+     * mode stops painting the selection (adw-sidebar.c:2948-2951). The boxed-list
+     * look it also switches to needs theme classes this surface does not have.
+     */
+    get mode(): 'sidebar' | 'page';
+    set mode(value: 'sidebar' | 'page');
+    /** `Adw.Sidebar:filter` — decides which rows render, never the selection index space. */
+    get filter(): SidebarItemFilter | null;
+    set filter(value: SidebarItemFilter | null);
+    /** Whether the FILTERED row list is empty — the `.empty` / placeholder state. */
+    get isEmpty(): boolean;
 }

package/lib/types/widgets/adw-spinner.d.ts

@@ -1,6 +1,6 @@
 import { ActivityIndicator } from '@nativescript/core';
-/** Default spinner diameter in DIPs. */
-export declare const DEFAULT_SPINNER_SIZE = 32;
+import { DEFAULT_SPINNER_SIZE } from './chrome.js';
+export { DEFAULT_SPINNER_SIZE };
 export declare class AdwSpinner extends ActivityIndicator {
     private _size;
     constructor();
@@ -8,7 +8,12 @@ export declare class AdwSpinner extends ActivityIndicator {
     /** Whether the spinner is animating. Two-way bound to the indicator's `busy`. */
     get spinning(): boolean;
     set spinning(value: boolean);
-    /** The spinner diameter in DIPs. */
+    /**
+     * The spinner diameter in DIPs — the DRAWN one, so reading it back after
+     * `size = 200` reports 64 and after `size = 8` reports 16. Adwaita's ring is
+     * bounded on both ends, and a getter that echoed the request would be
+     * describing something that is not on screen.
+     */
     get size(): number;
     set size(value: number);
 }

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

@@ -1,4 +1,5 @@
 import { GridLayout, Label, StackLayout, type EventData } from '@nativescript/core';
+import type { AdwMenuEntry, SplitButtonDirection } from '@gjsify/adwaita-core';
 import { AdwIcon } from './adw-icon.js';
 /** Event name emitted when the main action part is tapped. Mirrors `Adw.SplitButton::clicked`. */
 export declare const CLICKED = "clicked";
@@ -8,37 +9,71 @@ export declare const MENU_TAPPED = "menuTapped";
 export interface MenuTappedEventData extends EventData {
     /** The chosen menu item label. */
     item: string;
-    /** The chosen item's index in {@link AdwSplitButton.menu}. */
+    /** The chosen item's index in {@link AdwSplitButton.menu} — its GMenuModel POSITION. */
     index: number;
+    /** The chosen item's detailed action name, when the entry carried one. */
+    action?: string;
 }
 export declare class AdwSplitButton extends GridLayout {
     /** The main action part (column 0). */
     protected readonly _actionPart: StackLayout;
-    /** The action label (shown when no `actionIcon` is set). */
+    /** The action label (shown in label mode). */
     protected readonly _actionLabel: Label;
-    /** The action symbolic icon (shown when an `actionIcon` is set). */
+    /** The action symbolic icon (shown in icon mode). */
     protected readonly _actionIcon: AdwIcon;
     /** The dropdown-arrow part (column 1). */
     protected readonly _dropdownPart: GridLayout;
-    /** The pan-down chevron. */
+    /** The direction arrow. */
     protected readonly _chevron: AdwIcon;
-    private _menu;
-    private _hasActionIcon;
-    private _actionIconSvg;
+    private readonly _state;
+    /** Which of the two action views is currently parented. */
+    private _showingIcon;
+    private _disabled;
     constructor();
+    /**
+     * Present the dropdown menu and dispatch the choice BY POSITION.
+     *
+     * Nothing happens without a menu: "if the menu model is `NULL`, the dropdown
+     * is disabled" (adw-split-button.c:376-378).
+     */
     private _openMenu;
-    /** The main action button's text label (used when no `actionIcon` is set). */
+    /** Repaint both halves from the state machine. */
+    private _render;
+    /**
+     * The main action button's text label, or `''` when the action half shows an
+     * icon or nothing — never the stale value behind a swapped-out view.
+     */
     get label(): string;
     set label(value: string);
     /**
-     * A symbolic SVG for the action part (e.g. `documentSaveSymbolic`). When set,
-     * the icon replaces the text label — matching `Adw.SplitButton`'s icon mode.
+     * A symbolic SVG for the action part (e.g. `documentSaveSymbolic`). Setting
+     * one replaces the label, clearing it returns the action half to its label —
+     * the mutual exclusion `Adw.SplitButton` enforces (adw-split-button.c:749-771).
+     *
+     * The SVG string IS the icon identity here, so it is what the state machine
+     * stores as the icon name; NS resolves no icon theme.
      */
     get actionIcon(): string;
     set actionIcon(svg: string);
-    /** The dropdown menu items (opened as a native `action()` sheet on arrow tap). */
-    get menu(): string[];
-    set menu(value: string[]);
+    /** The dropdown menu entries (opened as a native `action()` sheet on arrow tap). */
+    get menu(): readonly AdwMenuEntry[];
+    set menu(value: readonly (string | AdwMenuEntry)[]);
+    /** The direction the arrow points (and, on GTK, the popup opens). */
+    get direction(): SplitButtonDirection;
+    set direction(value: SplitButtonDirection);
+    /**
+     * The dropdown tooltip as set — `''` while unset. Resolve it through
+     * `resolveDropdownTooltip()` for what should be shown; the NS sheet has no
+     * tooltip surface, so this is carried for parity and for host bindings.
+     */
+    get dropdownTooltip(): string;
+    set dropdownTooltip(value: string);
+    /** Whether an underline in the label marks a mnemonic. */
+    get useUnderline(): boolean;
+    set useUnderline(value: boolean);
+    /** Whether the control is insensitive: dimmed, and emitting neither signal. */
+    get disabled(): boolean;
+    set disabled(value: boolean);
     /** The main action part (for composing a custom content widget). */
     get actionButton(): StackLayout;
 }

package/lib/types/widgets/adw-status-page.d.ts

@@ -9,19 +9,16 @@ export declare class AdwStatusPage extends GridLayout {
     /** The large glyph label (shown when `iconText` is set — the legacy fallback). */
     protected readonly _iconLabel: Label;
     private _iconGlyph;
-    /** The icon node currently in the stack (the AdwIcon or the glyph Label), or null. */
-    private _iconNode;
     /** The bold title label. */
     protected readonly _titleLabel: Label;
-    /** The dim description label (lazily in the tree — only when set). */
+    /** The dim description label. */
     protected readonly _descriptionLabel: Label;
-    private _hasDescription;
     private _child;
     constructor();
     /**
      * A large Adwaita symbolic SVG string shown above the title (e.g.
      * `folderSymbolic`). Setting a non-empty value shows the symbolic icon; empty
-     * removes it. Matches `Adw.StatusPage`'s themed icon. Mutually exclusive with
+     * hides it. Matches `Adw.StatusPage`'s themed icon. Mutually exclusive with
      * {@link iconText} — whichever was set last wins.
      */
     get icon(): string;
@@ -33,17 +30,15 @@ export declare class AdwStatusPage extends GridLayout {
      */
     get iconText(): string;
     set iconText(value: string);
-    /** Swap the icon node at the TOP of the stack (above the title), or clear it. */
-    private _setIconNode;
     /** The icon fill colour (hex). Defaults to a dim grey; light/dark callers may override. */
     get iconColor(): string;
     set iconColor(value: string);
-    /** The page title (bold, centered). */
+    /** The page title (bold, centered). An empty title takes no space. */
     get title(): string;
     set title(value: string);
     /**
-     * The dim description below the title. Setting a non-empty value adds it;
-     * empty removes it — so a descriptionless page has no blank gap.
+     * The dim description below the title. An empty description takes no space,
+     * so a descriptionless page has no blank gap.
      */
     get description(): string;
     set description(value: string);

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

@@ -10,8 +10,28 @@ export interface NotifyActiveEventData extends EventData {
 export declare class AdwSwitchRow extends AdwActionRow {
     /** The suffix Switch control. */
     protected readonly _switch: Switch;
+    /** The headless active flag + its notify rule (ADR 0004). */
+    private readonly _switchState;
     constructor();
-    /** Whether the switch is on. Two-way bound to the suffix `Switch.checked`. */
+    /** Whether the switch is on. */
     get active(): boolean;
     set active(value: boolean);
+    /**
+     * The row was tapped — invert the state, then emit `activated` like any
+     * other action row (adw-switch-row.c:23-27 via the activatable widget).
+     *
+     * UNVERIFIED OFF-DEVICE: this assumes a tap that lands on the `Switch`
+     * itself is consumed by it and does NOT also reach the row's tap gesture. If
+     * a platform were to bubble it, the handle would toggle twice. Both Android
+     * (a clickable native widget consumes the touch) and iOS (a `UISwitch` claims
+     * the gesture) are expected to consume it, but only a device run can confirm
+     * that — `row-press.ts` reasons about the same propagation for its highlight.
+     */
+    activate(): void;
+    /**
+     * Push a state transition out to the Switch and emit `notify::active` — only
+     * when something actually changed, which is the `g_object_notify` gate
+     * libadwaita puts on the same transition (C:224-225 → :76).
+     */
+    private _apply;
 }