@gjsify/adwaita-nativescript 0.31.0 → 0.33.0

package/lib/types/widgets/split-view-state.d.ts

@@ -0,0 +1,228 @@
+import type { AdwPackType, AdwTextDirection, NavigationActionResult, NavigationStackPlan, OverlaySplitViewOptions, SplitViewPane } from '@gjsify/adwaita-core';
+export type { AdwPackType, NavigationStackPlan, SplitViewPane };
+/** Payload of the `notify::show-sidebar` a state change asks the widget to emit. */
+export interface NsShowSidebarNotification {
+    /** Whether the sidebar is meant to be shown. */
+    showSidebar: boolean;
+    /** Whether the view is in its collapsed (narrow) mode. */
+    collapsed: boolean;
+}
+/**
+ * The NativeScript side of a split view: what a state change makes it do.
+ *
+ * Only the changes with real ordering or animation semantics come through here.
+ * Structural mutations (mounting a pane, moving the sidebar to the other side)
+ * stay the widget's own business, because they also have to re-declare the grid
+ * columns — a callback would only be able to run after that anyway.
+ */
+export interface NsSplitViewHost {
+    /** Re-run the structural layout for the SETTLED state. Instant. */
+    applyLayout(): void;
+    /** Run the animated sidebar reveal / master⇄detail swap — a user-driven toggle. */
+    transitionSidebar(): void;
+    /** Re-emit `notify::show-sidebar`. */
+    notifyShowSidebar(event: NsShowSidebarNotification): void;
+}
+/** The `collapsed` + `show-sidebar` surface `AdwSplitViewBase` delegates to. */
+export interface NsSplitViewState {
+    /** Whether the panes are stacked (one at a time) rather than side by side. */
+    readonly collapsed: boolean;
+    /** Whether the sidebar is meant to be shown. */
+    readonly showSidebar: boolean;
+    /** Which side the sidebar is packed on. */
+    readonly sidebarPosition: AdwPackType;
+    /** Attach the widget. Called exactly once, from the base constructor. */
+    bind(host: NsSplitViewHost): void;
+    /** Collapse or expand. Returns whether it changed. */
+    setCollapsed(value: boolean): boolean;
+    /** Show or hide the sidebar. Returns whether it changed. */
+    setShowSidebar(value: boolean): boolean;
+    /** Move the sidebar to the other side. Returns whether it changed. */
+    setSidebarPosition(position: AdwPackType): boolean;
+    /** Record that a pane was mounted or unmounted. Returns whether it changed. */
+    setPaneMounted(pane: SplitViewPane, mounted: boolean): boolean;
+}
+/**
+ * Which of the two grid columns each pane takes.
+ *
+ * `AdwSplitViewBase._syncColumns` makes the SIDEBAR's column the fixed (`'auto'`)
+ * one and the content's the expanding (`'star'`) one, ordered by
+ * `sidebar-position`. So a pane placed in the wrong column is not merely
+ * mirrored — it also swaps its sizing mode, which is what made an
+ * `end`-positioned navigation split view fully inverted: it wrote the sidebar
+ * into column 0 and the content into column 1 unconditionally, while the base had
+ * already made column 0 the star column. libadwaita allocates an `end` sidebar at
+ * `width - sidebar_width` (adw-navigation-split-view.c:306-316).
+ */
+export declare function splitViewColumns(sidebarPosition: AdwPackType, direction?: AdwTextDirection): {
+    sidebar: number;
+    content: number;
+};
+/**
+ * `Adw.OverlaySplitView` bound to a NativeScript widget.
+ *
+ * Holds an `OverlaySplitViewState` and turns its notifications into the two
+ * things NativeScript can do: re-lay the panes out, or animate the reveal. The
+ * widget keeps ZERO split-view state.
+ *
+ * The reveal itself is NOT driven from here. NativeScript animates with a native
+ * `View.animate()` on `translateX`/`opacity`, not by sampling a progress value,
+ * so the core's `SplitViewAnimator` seam stays on its instant default and
+ * `show-progress` settles at 0 or 1 — which is also what a renderer without a
+ * spring gets from `adw_animation_skip`.
+ */
+export declare class NsOverlaySplitViewState implements NsSplitViewState {
+    private readonly _state;
+    private _host;
+    /**
+     * True while {@link setCollapsed} runs. The `show-sidebar` flip it couples is
+     * STRUCTURAL, not a user toggle: `set_collapsed` passes `animate = FALSE`
+     * (adw-overlay-split-view.c:1457-1458) and the `collapsed` notification right
+     * behind it re-lays the whole view out anyway.
+     */
+    private _coupling;
+    constructor(options?: OverlaySplitViewOptions);
+    bind(host: NsSplitViewHost): void;
+    /** Whether the sidebar overlays the content instead of sitting beside it. */
+    get collapsed(): boolean;
+    /** Whether the sidebar is meant to be shown. */
+    get showSidebar(): boolean;
+    /** Whether collapsing/uncollapsing leaves the sidebar's visibility alone. */
+    get pinSidebar(): boolean;
+    /** Which side the sidebar is packed on. */
+    get sidebarPosition(): AdwPackType;
+    /** The reveal progress: 0 hidden, 1 shown. */
+    get showProgress(): number;
+    /** Whether the tap-to-dismiss scrim takes input — `update_shield` (:249-256). */
+    get shieldVisible(): boolean;
+    /**
+     * Whether the SIDEBAR pane may take focus — `gtk_widget_set_can_focus
+     * (sidebar_bin, !collapsed || show_sidebar)` (:330, :1460).
+     *
+     * NativeScript's equivalent is `isUserInteractionEnabled` (the precedent is
+     * the decorative bottom-sheet handle, adw-bottom-sheet.c:1198). Without it the
+     * pane hidden behind the overlay keeps answering taps and stays in the
+     * screen-reader order.
+     */
+    get sidebarFocusable(): boolean;
+    /** Whether the CONTENT pane may take focus — the mirror of {@link sidebarFocusable} (:331, :1461). */
+    get contentFocusable(): boolean;
+    /**
+     * Collapse or expand. Unless the sidebar is pinned this also flips
+     * `show-sidebar` to match, notifying it FIRST — GTK freezes notifications
+     * across the whole setter and thaws them in queue order
+     * (adw-overlay-split-view.c:1449-1483).
+     */
+    setCollapsed(value: boolean): boolean;
+    /** Show or hide the sidebar — the animated, user-driven path. */
+    setShowSidebar(value: boolean): boolean;
+    /** Pin the sidebar so collapsing no longer hides it (`pin-sidebar`, :990-992). */
+    setPinSidebar(value: boolean): boolean;
+    /** Move the sidebar to the other side. The widget re-declares its columns. */
+    setSidebarPosition(position: AdwPackType): boolean;
+    /**
+     * No-op: `Adw.OverlaySplitView` has no navigation stack, so which children
+     * exist changes none of its state. Present so the two adapters share one seam.
+     */
+    setPaneMounted(_pane: SplitViewPane, _mounted: boolean): boolean;
+    /** Tap on the scrim — `released_cb` (:431-439) hides the sidebar unconditionally. */
+    dismissShield(): boolean;
+    private _apply;
+}
+/**
+ * `Adw.NavigationSplitView` bound to a NativeScript widget.
+ *
+ * NativeScript spells the visible pane as `showSidebar`, GTK as `show-content`;
+ * they are each other's negation and the core owns the meaning. What the core
+ * adds is the whole ordering table: which pane is on top for a given
+ * `sidebar-position` × `show-content` × which children exist, and whether
+ * reaching it is a push or a pop.
+ *
+ * Tags and the `navigation.push`/`navigation.pop` actions ARE wired, through an
+ * explicit {@link setTag} rather than by handing the core a `View`: a `View` is
+ * not a `NavigationPageRef`, and reading a `tag` property off one would silently
+ * adopt whatever NativeScript happens to put there. The panes stay tracked by
+ * presence with a marker object, and the tag of record lives in the core — which
+ * is where it lives in the browser port too, because `setTag` CLEARS a colliding
+ * tag and mutating a caller's view to do that would be a surprise.
+ */
+export declare class NsNavigationSplitViewState implements NsSplitViewState {
+    private readonly _state;
+    /** Presence markers — one per pane, so mounting one never looks like the other. */
+    private readonly _markers;
+    private _host;
+    private _plan;
+    constructor(options?: {
+        sidebarPosition?: AdwPackType;
+        collapsed?: boolean;
+        showContent?: boolean;
+        /** Where a `g_critical` goes on this port. */
+        onCritical?: (message: string) => void;
+        /** Offer an unmatched `navigation.*` to the parent — how nesting forwards a push. */
+        onDelegate?: (action: 'push' | 'pop', tag?: string) => boolean;
+    });
+    bind(host: NsSplitViewHost): void;
+    /**
+     * Retag a mounted pane — `check_tags_cb` (adw-navigation-split-view.c:431-460).
+     *
+     * On a collision the pane KEEPS its page and loses the tag, which is a
+     * different failure from mounting a colliding page (that one is refused
+     * outright). Returns whether the tag stuck.
+     */
+    setTag(pane: SplitViewPane, tag: string | null): boolean;
+    /** 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). */
+    push(tag: string): NavigationActionResult;
+    /** `navigation.pop` — `navigation_pop_cb` (:687-702). */
+    pop(): NavigationActionResult;
+    /**
+     * `Adw.NavigationSplitView:show-content` under ITS OWN NAME.
+     *
+     * This port spells the visible pane `showSidebar`, which is the negation —
+     * and that costs every consumer a `!(…)`, including the storybook, which
+     * carries one purely to bind a shared story arg. Both spellings are here now
+     * and neither is derived from a second copy of the flag.
+     */
+    get showContent(): boolean;
+    set showContent(value: boolean);
+    /** Whether the panes are stacked (one at a time) rather than side by side. */
+    get collapsed(): boolean;
+    /** Whether the SIDEBAR is the visible pane — GTK's `show-content`, negated. */
+    get showSidebar(): boolean;
+    /** Which side the sidebar is packed on. */
+    get sidebarPosition(): AdwPackType;
+    /** The settled navigation stack, root first. */
+    get stack(): readonly SplitViewPane[];
+    /**
+     * The pane on top of the stack — what a COLLAPSED view shows.
+     *
+     * Keyed on the stack, not on `showSidebar`: a LONE child stays visible
+     * whatever `show-content` says (adw-navigation-split-view.c:389-401), and
+     * keying on the flag alone is what rendered a sidebar-only split view blank.
+     */
+    get visiblePane(): SplitViewPane | null;
+    /** Whether `pane` is the one a collapsed view shows. */
+    isVisible(pane: SplitViewPane): boolean;
+    /**
+     * How the last `show-content` change reached its stack: `push`, `pop`, or
+     * `replace` for a structural rebuild that NativeScript paints instantly.
+     *
+     * This is the animation DIRECTION, and it is not `showSidebar`: with
+     * `sidebar-position: end` the content is the ROOT page, so showing it is a POP
+     * and hiding it a PUSH — the reverse of `start` (:1414-1428). Taking the
+     * direction from the flag ran an `end`-positioned swap backwards.
+     */
+    get transition(): NavigationStackPlan['transition'];
+    /** Collapse or expand. `Adw.NavigationSplitView` has no `show-content` coupling (:1341-1353). */
+    setCollapsed(value: boolean): boolean;
+    /** Show the sidebar (`true`) or the content (`false`) while collapsed. */
+    setShowSidebar(value: boolean): boolean;
+    /** Move the sidebar to the other side. The widget re-declares its columns. */
+    setSidebarPosition(position: AdwPackType): boolean;
+    /** Record that a pane was mounted or unmounted — it changes the stack. */
+    setPaneMounted(pane: SplitViewPane, mounted: boolean): boolean;
+    private _apply;
+}

package/lib/types/widgets/split-view-width.d.ts

@@ -0,0 +1,76 @@
+import { DEFAULT_MAX_SIDEBAR_WIDTH, DEFAULT_MIN_SIDEBAR_WIDTH, DEFAULT_SIDEBAR_WIDTH_FRACTION } from '@gjsify/adwaita-core';
+export { DEFAULT_MAX_SIDEBAR_WIDTH, DEFAULT_MIN_SIDEBAR_WIDTH, DEFAULT_SIDEBAR_WIDTH_FRACTION };
+/** The three width properties, as a split view holds them. */
+export interface SidebarWidthProps {
+    /** Lower bound in DIPs. Defaults to libadwaita's 180. */
+    minSidebarWidth: number;
+    /** Upper bound in DIPs. Defaults to libadwaita's 280. */
+    maxSidebarWidth: number;
+    /** Share of the container the sidebar asks for. Defaults to 0.25. */
+    sidebarWidthFraction: number;
+}
+/** The property defaults a fresh split view starts with. */
+export declare function defaultSidebarWidthProps(): SidebarWidthProps;
+/** Which split view is asking — the two answer the same input differently. */
+export type SplitViewWidthRule = 'navigation' | 'overlay';
+/** What the renderer knows about the layout the width is being derived for. */
+export interface SplitViewWidthContext {
+    /** The content pane's own minimum width. */
+    contentMin?: number;
+    /** The sidebar child's own minimum width. */
+    sidebarChildMin?: number;
+    /**
+     * Whether the view is collapsed. Overlay only, and not a detail: COLLAPSED
+     * `get_sidebar_width` IGNORES the fraction and clamps the VIEW width instead
+     * (adw-overlay-split-view.c:462-463), so on a 360 DIP phone GTK draws 280
+     * where a fraction would give 180.
+     */
+    collapsed?: boolean;
+}
+/**
+ * The sidebar width for a container of `totalWidth` DIPs.
+ *
+ * The two widgets genuinely differ, and not only in a corner: OVERLAY takes a
+ * final `min(width, totalWidth - contentMin)`, so it never claims more than the
+ * view has left; NAVIGATION folds that same limit into the clamp's UPPER bound,
+ * where the LOWER bound can still win — so it may exceed the view. A 100 DIP
+ * container with no content minimum at all already splits them: navigation
+ * answers 180 (its minimum), overlay answers 100 (all there is).
+ *
+ * `collapsed` only reaches the overlay rule, because only the overlay has a
+ * collapsed sidebar to size — a collapsed NAVIGATION pane fills the view and
+ * takes no derived width at all ({@link appliesDerivedSidebarWidth}).
+ *
+ * `totalWidth <= 0` means the view has not been laid out yet — NativeScript
+ * reports a zero size before the first pass — so the MINIMUM is returned rather
+ * than a fraction of nothing. That is the smallest thing libadwaita would ever
+ * draw, so the first layout can only widen it, never jump down.
+ */
+export declare function sidebarWidthFor(totalWidth: number, props: SidebarWidthProps, rule?: SplitViewWidthRule, context?: SplitViewWidthContext): number;
+/**
+ * Whether the sidebar pane takes a DERIVED width at all, or sizes itself.
+ *
+ * Only one case says no, and it is the one that cost a frame-late regression:
+ * a COLLAPSED navigation split view has no sidebar column. Its visible page
+ * fills the whole view (`gtk_bin_layout_new`,
+ * adw-navigation-split-view.c:538), which NativeScript expresses as
+ * `width = 'auto'` spanning both columns — so writing a number over it, as the
+ * post-layout re-measure did, snapped the full-screen pane back to 180-280 DIP
+ * one frame after the collapse.
+ *
+ * The overlay is deliberately NOT exempt. Its collapsed sidebar really is a
+ * clamped-width overlay drawn above the content
+ * (adw-overlay-split-view.c:462-463), so it still wants a number — a shared
+ * "collapsed means auto" rule would have been wrong for half the callers.
+ */
+export declare function appliesDerivedSidebarWidth(collapsed: boolean, rule: SplitViewWidthRule): boolean;
+/**
+ * Normalise one width property, keeping a nonsense value from reaching layout.
+ *
+ * A non-finite or negative input falls back to the default rather than to zero:
+ * a zero-width sidebar is indistinguishable from a missing one on screen, which
+ * turns a typo into a widget that looks broken instead of one that looks wrong.
+ */
+export declare function normalizeWidthProp(value: number, fallback: number): number;
+/** Clamp the fraction into the `[0, 1]` range its GTK property is declared with. */
+export declare function normalizeWidthFraction(value: number): number;

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

@@ -0,0 +1,23 @@
+/** NativeScript's `visible` / not-in-layout pair, the counterpart of GTK `visible`. */
+export type StatusPageVisibility = 'visible' | 'collapse';
+/**
+ * `string_is_not_empty` (adw-status-page.c:91-96), bound to the `visible` of BOTH
+ * the title and the description labels (adw-status-page.ui:41-46, :57-62).
+ *
+ * It is `string && string[0]` — one byte, no trim. A title of `"   "` is a
+ * VISIBLE title in libadwaita, which is why this takes the raw text and never
+ * trims it: trimming would hide a widget GTK draws.
+ */
+export declare function statusPageLabelVisibility(text: string | null | undefined): StatusPageVisibility;
+/**
+ * `has_image` (adw-status-page.c:83-89), bound to the image's `visible`
+ * (adw-status-page.ui:23-28).
+ *
+ * C is `paintable || (icon_name && icon_name[0])` — two sources, either of which
+ * shows the image. This port has no `paintable` counterpart (the icon is an SVG
+ * string handed to `AdwIcon`), so only the second half applies; it is kept as its
+ * own predicate rather than folded into
+ * {@link statusPageLabelVisibility} because upstream really are two different
+ * closures, and the missing half is a real gap rather than a simplification.
+ */
+export declare function statusPageIconVisibility(icon: string | null | undefined): StatusPageVisibility;

package/lib/types/widgets/svg-path.d.ts

@@ -0,0 +1,28 @@
+/** One absolute drawing command. Every SVG command reduces to these four. */
+export type SvgPathCommand = {
+    type: 'M';
+    x: number;
+    y: number;
+} | {
+    type: 'L';
+    x: number;
+    y: number;
+} | {
+    type: 'C';
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    x: number;
+    y: number;
+} | {
+    type: 'Z';
+};
+/**
+ * Parse SVG path data into absolute `M`/`L`/`C`/`Z` commands.
+ *
+ * Unparsable input yields the commands read so far rather than throwing: a
+ * single malformed icon must not take down the view that renders it, which is
+ * the same call the Android backend makes when `PathParser` rejects a subpath.
+ */
+export declare function parseSvgPath(d: string): SvgPathCommand[];

package/lib/types/widgets/tab-view-state.d.ts

@@ -0,0 +1,74 @@
+import type { View } from '@nativescript/core';
+import { TabViewState } from '@gjsify/adwaita-core';
+import type { AdwTabPageState, TabViewHandlers, TabViewSelectionChange } from '@gjsify/adwaita-core';
+/** One page of an `AdwTabView`, as a renderer reads it. */
+export type AdwTabPage = AdwTabPageState<View>;
+/** The two `View.visibility` values a stacked page or a tab affordance ever takes. */
+export type NsVisibility = 'visible' | 'collapse';
+/** The model an `AdwTabView` delegates to, typed on the NS `View`. */
+export declare function createTabViewState(handlers?: TabViewHandlers<View>): TabViewState<View>;
+/**
+ * The `visibility` each page's content view must carry for the current
+ * selection, in page order. Exactly one entry is `'visible'` — none when nothing
+ * is selected, which is a real state here: closing the last tab EMPTIES the view
+ * (adw-tab-view.c:1912-1913), where the old port refused the close outright.
+ */
+export declare function tabPageVisibilities(state: TabViewState<View>): NsVisibility[];
+/** Push {@link tabPageVisibilities} onto the real content views. */
+export declare function applyTabViewVisibility(state: TabViewState<View>): void;
+/**
+ * The `visibility` each tab's close button must carry, in page order.
+ *
+ * `tabCloseVisible` is `(hovering && fullyVisible) || selected || dragging`, and
+ * never on a pinned tab (adw-tab.c:124, :645-650). Touch has no hover and this
+ * port has no tab drag-and-drop, so `hovering` and `dragging` are constantly
+ * false and the predicate REDUCES to "selected, and not pinned" — which is the
+ * old port's rule plus the pinned gate it was missing. Calling the shared
+ * predicate rather than writing `active` keeps that a derivation instead of a
+ * coincidence, and gives the pinned gate for free.
+ */
+export declare function tabCloseVisibilities(state: TabViewState<View>): NsVisibility[];
+/**
+ * The `visibility` of the whole tab bar — `tabsRevealed` (adw-tab-bar.c:142-164)
+ * projected onto NS. The old port had no autohide at all; the bar was added in
+ * the constructor and never hidden.
+ */
+export declare function tabBarVisibility(state: TabViewState<View>, autohide: boolean): NsVisibility;
+/**
+ * The text a tab's label shows.
+ *
+ * A pinned tab is a single-glyph chip in libadwaita — `adw_tab_constructed`
+ * hides its title outright (adw-tab.c:645-650) — so it renders no label at all
+ * here either. Everything else shows its title, which is already `''` rather
+ * than `undefined` for a page that declared none: the old port assigned
+ * `page.title` straight to `Label.text` with no coercion, so an `AdwViewPage`
+ * literal without a title rendered the string "undefined".
+ */
+export declare function tabLabelText(page: AdwTabPage): string;
+/**
+ * The tooltip text for a tab — `tabTooltip`, i.e. the page's own tooltip when it
+ * has one and its title otherwise (adw-tab.c:137-146).
+ *
+ * NS has no tooltip primitive, so this is exposed for a consumer (and for the
+ * accessibility label) rather than rendered. It is deliberately the TEXT form:
+ * a page-supplied tooltip is Pango markup in C, and NS has no markup sink to
+ * push it through.
+ */
+export declare function tabTooltipText(page: AdwTabPage): string;
+/** The data half of the `notify::selected-page` event (minus NS's `eventName`/`object`). */
+export interface TabViewNotifyPayload {
+    /** Id of the newly-selected page, `null` when the view is empty. */
+    selectedId: string | null;
+    /** Its index, `-1` when the view is empty. */
+    selectedIndex: number;
+    /** The previously-selected id, `null` when there was none. */
+    previousId: string | null;
+    /** `false` for a model-driven pick (auto-select, close successor), `true` otherwise. */
+    interactive: boolean;
+}
+/**
+ * Project a core change onto the event payload. Kept as a function rather than
+ * spreading the change directly so that if the core payload ever grows a live
+ * model object, it does not silently leak into an event a consumer holds on to.
+ */
+export declare function tabViewNotifyPayload(change: TabViewSelectionChange): TabViewNotifyPayload;

package/lib/types/widgets/view-stack-state.d.ts

@@ -0,0 +1,35 @@
+import type { View } from '@nativescript/core';
+import { ViewStackState } from '@gjsify/adwaita-core';
+import type { AdwViewStackPageInfo, ViewStackStateChange } from '@gjsify/adwaita-core';
+/** One page registered with an `AdwViewStack`, as a bound switcher reads it. */
+export type AdwViewStackPage = AdwViewStackPageInfo<View>;
+/** The two `View.visibility` values a stacked page ever takes. */
+export type NsPageVisibility = 'visible' | 'collapse';
+/** The selection machine an `AdwViewStack` delegates to, typed on the NS `View`. */
+export declare function createViewStackState(): ViewStackState<View>;
+/**
+ * The `visibility` each page's content view must carry for the current
+ * selection, in page order. Exactly one entry is `'visible'` — none when nothing
+ * is selected, which is a real state here (an empty stack, every page hidden, or
+ * the visible page removed).
+ */
+export declare function pageVisibilities(state: ViewStackState<View>): NsPageVisibility[];
+/** Push {@link pageVisibilities} onto the real content views. */
+export declare function applyViewStackVisibility(state: ViewStackState<View>): void;
+/** The data half of the `notify::visible-child` event (minus NS's `eventName`/`object`). */
+export interface ViewStackNotifyPayload {
+    /** The newly-visible page's index, `-1` when nothing is selected. */
+    index: number;
+    /** The newly-visible page's name, `''` when nothing is selected. */
+    name: string;
+    /** The newly-visible page's title, `''` when nothing is selected. */
+    title: string;
+    /** `false` for an auto-pick (add / hide / show), `true` for an explicit select. */
+    interactive: boolean;
+}
+/**
+ * Project a core change onto the event payload. Kept as a function rather than
+ * spreading the change directly so the `page` descriptor — a live model object —
+ * never leaks into an event a consumer might hold on to.
+ */
+export declare function viewStackNotifyPayload(change: ViewStackStateChange<View>): ViewStackNotifyPayload;

package/lib/types/widgets/view-switcher-base.d.ts

@@ -1,21 +1,15 @@
-import { GridLayout, StackLayout, View, type EventData } from '@nativescript/core';
+import { GridLayout, type EventData } from '@nativescript/core';
+import type { AdwInlineViewSwitcherDisplayMode, AdwViewSwitcherPolicy, ViewSwitcherState } from '@gjsify/adwaita-core';
+import { type AdwViewPage, type ViewSwitcherKind, type ViewSwitcherNotifyPayload } from './view-switcher-model.js';
+export type { AdwViewPage };
 /** Event name emitted when the selected view changes. Mirrors GObject `notify::selected`. */
 export declare const NOTIFY_SELECTED = "notify::selected";
-/** Payload of the `notify::selected` event. */
-export interface NotifyViewSelectedEventData extends EventData {
-    /** The newly-selected view index. */
-    selected: number;
-    /** The newly-selected view's title. */
-    title: string;
-}
-/** One page registered with a {@link AdwViewSwitcherBase}. */
-export interface AdwViewPage {
-    /** The switcher button label. */
-    title: string;
-    /** The page content view, shown when this page is selected. */
-    content: View;
-    /** Optional Adwaita symbolic SVG shown left of the label in the switcher button. */
-    icon?: string;
+/**
+ * Payload of the `notify::selected` event. `selected` is `-1` and `name`/`title`
+ * are `''` when nothing is selected — the state an empty switcher and a
+ * fully-hidden one both land in.
+ */
+export interface NotifyViewSelectedEventData extends EventData, ViewSwitcherNotifyPayload {
 }
 /**
  * Shared base: a switcher bar (row 0) + a content area (row 1), one page visible.
@@ -23,40 +17,88 @@ export interface AdwViewPage {
  */
 export declare abstract class AdwViewSwitcherBase extends GridLayout {
     /** The horizontal switcher bar holding the buttons. */
-    protected readonly _bar: StackLayout;
+    protected readonly _bar: GridLayout;
+    /** `Adw.ViewSwitcher:policy`, default NARROW (adw-view-switcher.c:447-451). */
+    private _policy;
     /** The content area where the selected page is shown. */
     protected readonly _contentArea: GridLayout;
+    /** The registered pages, in bar order. */
     protected readonly _pages: AdwViewPage[];
-    /** The tappable button containers (one per page), in bar order. */
-    protected readonly _buttons: StackLayout[];
-    protected _selected: number;
+    /** The headless selection + page model every derivation reads. */
+    protected readonly _state: ViewSwitcherState;
+    private _nodes;
     /** CSS class applied to the switcher bar — subclass-specific. */
     protected abstract get barClass(): string;
     /** CSS class applied to each switcher button — subclass-specific. */
     protected abstract get buttonClass(): string;
+    /**
+     * `AdwViewSwitcher:policy`, which decides the button orientation
+     * (adw-view-switcher.c:534-537).
+     *
+     * It used to be a HARD-CODED `'wide'` with a note saying there was no policy
+     * property on NS — so a consumer could not follow a breakpoint, and the
+     * default was the opposite of C's, which is `ADW_VIEW_SWITCHER_POLICY_NARROW`
+     * (adw-view-switcher.c:447-451). It is a real property now, defaulting to
+     * `narrow`; a subclass may still pin it.
+     */
+    protected get policy(): AdwViewSwitcherPolicy;
+    /**
+     * `Adw.ViewSwitcher:policy` — settable, defaulting to NARROW as in C
+     * (adw-view-switcher.c:447-451).
+     *
+     * A hard-coded `'wide'` meant an NS consumer could not follow a breakpoint
+     * at all, and the value it was pinned to was not even the default.
+     */
+    get switcherPolicy(): AdwViewSwitcherPolicy;
+    set switcherPolicy(value: AdwViewSwitcherPolicy);
+    /**
+     * What the buttons show. `'both'` for the classic switcher, whose buttons
+     * "always have an icon and a label" (adw-view-switcher.c class docs);
+     * `AdwInlineViewSwitcher` overrides it with the real
+     * `AdwInlineViewSwitcherDisplayMode`.
+     */
+    protected get buttonDisplayMode(): AdwInlineViewSwitcherDisplayMode;
     constructor(rootClass: string);
     /** Initialise the bar class after the subclass fields are ready. */
     protected _initClasses(): void;
-    /** Register the view pages. Rebuilds the switcher bar + content stack. */
-    setViews(pages: AdwViewPage[]): void;
-    /** Show only the selected page; mark its button active. */
-    protected _applySelection(): void;
     /**
-     * Hook: append extra chrome to a freshly-built button (after icon + label).
-     * Default no-op. Subclasses (e.g. {@link AdwTabView}) override to add a close
-     * button. The button is the tappable `StackLayout` container.
+     * Register the view pages. Rebuilds the switcher bar + content stack.
+     *
+     * The SELECTED PAGE survives the rebuild whenever a page of the same name
+     * does — libadwaita's selection is a page pointer, not an index
+     * (adw-view-stack.c:660-672) — and falls back to the first VISIBLE page
+     * otherwise (:1149-1151).
      */
-    protected _buildButtonExtras(_button: StackLayout, _page: AdwViewPage, _index: number): void;
+    setViews(pages: AdwViewPage[]): void;
+    /** Build one button's NS nodes. Painted by {@link _applySelection}. */
+    private _buildButton;
     /**
-     * Hook: react to a button's active/inactive state on every selection change.
-     * Default no-op. Subclasses override to e.g. show the close button only on the
-     * active tab.
+     * Which visibility rule this switcher follows — see
+     * {@link switcherButtonVisible}, which holds the rule itself so a spec can
+     * reach it.
      */
-    protected _applyButtonState(_button: StackLayout, _index: number, _active: boolean): void;
+    protected get switcherKind(): ViewSwitcherKind;
+    /** Paint the derived models: show only the selected page, mark its button active. */
+    protected _applySelection(): void;
     /** The registered view pages. */
     get views(): AdwViewPage[];
     set views(pages: AdwViewPage[]);
-    /** The selected view index. Swaps the visible page + emits `notify::selected`. */
+    /**
+     * The selected view index, `-1` when nothing is selected. Swaps the visible
+     * page + emits `notify::selected`.
+     *
+     * Out-of-range, negative, fractional and hidden-page indices are all silent
+     * NO-OPS — refused, never clamped, exactly as
+     * `adw_view_stack_pages_select_item` refuses (adw-view-stack.c:682-684).
+     */
     get selected(): number;
     set selected(value: number);
+    /** Name of the selected page, `''` when nothing is selected. */
+    get selectedName(): string;
+    /**
+     * Show or hide a page by name. Returns whether the SELECTION moved: hiding
+     * the selected page falls back to the first still-visible one
+     * (`update_child_visible`, adw-view-stack.c:1061-1082).
+     */
+    setPageVisible(name: string, visible: boolean): boolean;
 }