@gjsify/adwaita-nativescript 0.30.0 → 0.32.0

package/lib/types/widgets/preferences-search.d.ts

@@ -0,0 +1,68 @@
+import type { PreferencesSearchPage, PreferencesSearchResult, SearchPreferencesOptions } from '@gjsify/adwaita-core';
+/**
+ * What the search reads off a row widget.
+ *
+ * `isActionRow` is a declared property rather than an `instanceof` test,
+ * because the NativeScript hierarchy does NOT match the GObject one:
+ * `AdwEntryRow extends AdwActionRow` here so it can reuse the row chrome, while
+ * in C it derives from `AdwPreferencesRow` (adw-entry-row.c:90) and its text is
+ * therefore deliberately NOT searchable. The row classes carry the C answer.
+ */
+export interface NsSearchableRow {
+    /** `AdwPreferencesRow:title`. */
+    readonly title?: string;
+    /** `AdwActionRow:subtitle`; only consulted when `isActionRow`. */
+    readonly subtitle?: string;
+    /** Whether the row derives from `AdwActionRow` in libadwaita. */
+    readonly isActionRow?: boolean;
+    /** NS `View.visibility`. */
+    readonly visibility?: string;
+}
+/** What the search reads off a group widget. */
+export interface NsSearchableGroup {
+    /** `AdwPreferencesGroup:title`. */
+    readonly title?: string;
+    /** NS `View.visibility`. */
+    readonly visibility?: string;
+    /** The group's boxed-list rows, in order. */
+    searchRows(): readonly NsSearchableRow[];
+}
+/** What the search reads off a page widget. */
+export interface NsSearchablePage {
+    /** `AdwPreferencesPage:title`. */
+    readonly title?: string;
+    /** `AdwPreferencesPage:name` — the view-stack child name. */
+    readonly name?: string;
+    /** `AdwPreferencesPage:use-underline`. */
+    readonly useUnderline?: boolean;
+    /** NS `View.visibility`. */
+    readonly visibility?: string;
+    /** The page's groups, in order. */
+    searchGroups(): readonly NsSearchableGroup[];
+}
+/** Any node a search result can point back at. */
+export type NsSearchableNode = NsSearchablePage | NsSearchableGroup | NsSearchableRow;
+/** A described NS preferences tree, ready for `searchPreferences`. */
+export type NsPreferencesSearchPage = PreferencesSearchPage<NsSearchableNode>;
+/** One NS search result, carrying the page and row widgets it came from. */
+export type NsPreferencesSearchResult = PreferencesSearchResult<NsSearchableNode>;
+/**
+ * `gtk_widget_get_visible` for a NativeScript view.
+ *
+ * NS has THREE values where GTK has a boolean, and only `'visible'` counts as
+ * shown: `'collapse'` removes the view from layout and `'hidden'` keeps its
+ * space but paints nothing — neither is something a user can read or reach, so
+ * neither belongs in a search index. An undefined value is a view that never
+ * set the property, i.e. the NS default `'visible'`.
+ */
+export declare function isNsVisible(visibility: string | undefined): boolean;
+/** Describe a list of page widgets as the tree `searchPreferences` indexes. */
+export declare function describeNsPreferencesPages(pages: readonly NsSearchablePage[]): NsPreferencesSearchPage[];
+/**
+ * Search a list of NativeScript preferences pages.
+ *
+ * An empty query returns the WHOLE corpus, which is what C does
+ * (`strstr (title, "")` is non-NULL) and what keeps the results list populated
+ * before the user has typed.
+ */
+export declare function searchNsPreferences(pages: readonly NsSearchablePage[], query: string, options?: SearchPreferencesOptions): NsPreferencesSearchResult[];

package/lib/types/widgets/row-state.d.ts

@@ -0,0 +1,71 @@
+import { ActionRowState, ButtonRowState, SwitchRowState, WindowTitleState } from '@gjsify/adwaita-core';
+import type { AdwRowLabelInput, AdwRowLabels, ButtonRowRenderState } from '@gjsify/adwaita-core';
+import type { View } from '@nativescript/core';
+export { ActionRowState, ButtonRowState, SwitchRowState, WindowTitleState };
+export type { AdwRowLabels, ButtonRowRenderState };
+/** The two `View.visibility` values an Adwaita row ever assigns. */
+export type NsVisibility = 'visible' | 'collapse';
+/**
+ * `visibility` for a shown/hidden view.
+ *
+ * `'collapse'` rather than `'hidden'`: a hidden NS view still occupies its
+ * space, so an empty subtitle would leave its whole line behind — which is the
+ * one thing the binding exists to prevent.
+ */
+export declare function nsVisibility(shown: boolean): NsVisibility;
+/** The NativeScript form of a title/subtitle label pair. */
+export interface NsRowLabelVisuals {
+    /** Text for the title `Label`. */
+    title: string;
+    /** `visibility` for the title `Label`. */
+    titleVisibility: NsVisibility;
+    /** Text for the subtitle `Label`. */
+    subtitle: string;
+    /** `visibility` for the subtitle `Label`. */
+    subtitleVisibility: NsVisibility;
+}
+/** What a row must apply to its two labels for the given title/subtitle. */
+export declare function rowLabelVisuals(input: AdwRowLabelInput): NsRowLabelVisuals;
+/** The same mapping, for a state object that already holds the derivation. */
+export declare function toLabelVisuals(labels: AdwRowLabels): NsRowLabelVisuals;
+/** The NativeScript form of an `Adw.ButtonRow`'s two icons. */
+export interface NsButtonRowIconVisuals {
+    /** Payload for the leading icon. */
+    startIcon: string;
+    /** `visibility` for the leading icon. */
+    startIconVisibility: NsVisibility;
+    /** Payload for the trailing icon. */
+    endIcon: string;
+    /** `visibility` for the trailing icon. */
+    endIconVisibility: NsVisibility;
+}
+/**
+ * What a button row must apply to its two icons.
+ *
+ * The TITLE half of `ButtonRowRenderState` is deliberately not mapped here: the
+ * NativeScript button row reuses the action row's title `Label` and therefore
+ * its title state, so routing the title through a second state object would give
+ * one label two sources of truth — the exact shape this package exists to
+ * remove. {@link rowLabelVisuals} paints it.
+ *
+ * NOTE ON THE ICON PAYLOAD: GTK stores an icon NAME and resolves it through the
+ * icon theme; this port stores the symbolic SVG source itself, because `AdwIcon`
+ * renders SVG rather than looking a name up. `ButtonRowState` is indifferent —
+ * the rule it applies is `string_is_not_empty`, which reads the first byte and
+ * does not care what the string means.
+ */
+export declare function buttonRowIconVisuals(state: ButtonRowRenderState): NsButtonRowIconVisuals;
+/**
+ * Whether a view is "sensitive" in the sense the `activatable-widget` binding
+ * reads (`GtkWidget:sensitive` → `GtkListBoxRow:activatable`,
+ * adw-action-row.c:729-732).
+ *
+ * NativeScript has no `sensitive`; `isUserInteractionEnabled` is the nearest
+ * flag it surfaces (its own docs map it to `gtk_widget_set_can_target`). The two
+ * are not identical in GTK — an insensitive widget is also greyed out, a
+ * can't-target one is not — but `isUserInteractionEnabled` is the only property
+ * a NativeScript view has for "the user cannot operate this", so it is what the
+ * binding reads here. A view that has never been touched reports `true`, which
+ * is also GTK's default.
+ */
+export declare function isViewSensitive(view: Pick<View, 'isUserInteractionEnabled'> | null | undefined): boolean;

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

@@ -0,0 +1,18 @@
+import { SidebarState } from '@gjsify/adwaita-core';
+import type { AdwSidebarItemSpec, AdwSidebarSectionSpec, SidebarItemFilter } from '@gjsify/adwaita-core';
+export { SidebarState };
+export type { AdwSidebarItemSpec, AdwSidebarSectionSpec, SidebarItemFilter };
+/**
+ * The section list a flat `AdwSidebar.setItems(labels)` call means: one untitled
+ * section, which renders no header at all (a first + untitled section's header is
+ * bound to a non-empty title, adw-sidebar.c:1521-1527).
+ */
+export declare function sidebarSectionsFromLabels(labels: readonly string[]): AdwSidebarSectionSpec[];
+/**
+ * The class string one navigation row carries.
+ *
+ * `selectionVisible` is false in page mode, where libadwaita tracks the
+ * selection but never paints it (adw-sidebar.c:2948-2951) — its rows are plain
+ * boxed-list `AdwActionRow`s with no selected state.
+ */
+export declare function sidebarRowClassName(selected: boolean, selectionVisible: boolean): string;

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

@@ -0,0 +1,55 @@
+import type { AdwArrowIcon, AdwMenuEntry, SplitButtonDirection, SplitButtonState } from '@gjsify/adwaita-core';
+export type { AdwMenuEntry, SplitButtonDirection };
+/** Text of the sheet's dismiss button. */
+export declare const MENU_CANCEL_LABEL = "Cancel";
+/**
+ * The libadwaita arrow glyph names mapped to real Adwaita symbolic SVGs.
+ *
+ * Keyed by {@link AdwArrowIcon} and therefore TOTAL: which glyph a direction gets
+ * is decided in core, and a glyph this table has no SVG for is a compile error
+ * rather than a fallback arrow.
+ */
+export declare const ARROW_SVGS: Readonly<Record<AdwArrowIcon, string>>;
+/**
+ * Normalise a menu assigned from XML or app code into entries.
+ *
+ * A bare `string[]` is accepted because that is what `AdwSplitButton.menu` used
+ * to be and what the storybook still passes; it widens to the shared
+ * {@link AdwMenuEntry} without breaking a caller.
+ */
+export declare function toMenuEntries(value: readonly (string | AdwMenuEntry)[] | null | undefined): AdwMenuEntry[];
+/**
+ * The strings handed to `Dialogs.action()`, one per entry and each unique.
+ *
+ * A label that collides with another entry — or with the dismiss button — gets
+ * zero-width spaces appended until it is distinct. Nothing changes on screen;
+ * what changes is that {@link resolveMenuChoice} can now tell the entries apart.
+ */
+export declare function menuSheetActions(entries: readonly AdwMenuEntry[], cancelLabel?: string): string[];
+/**
+ * The position the user chose, or `-1` when the sheet was dismissed.
+ *
+ * Feed it the SAME array {@link menuSheetActions} produced: the strings are
+ * unique there, so the lookup is a position and not a guess.
+ */
+export declare function resolveMenuChoice(sheetActions: readonly string[], chosen: string | null | undefined): number;
+/**
+ * The arrow SVG for a direction, keyed off the SPLIT BUTTON's glyph map — so
+ * `none` is the down caret (_buttons.scss:621-623), not the hamburger this widget
+ * used to render for it.
+ */
+export declare function splitButtonArrowSvg(direction: SplitButtonDirection): string;
+/**
+ * Apply `AdwSplitButton.actionIcon = svg` to the content machine.
+ *
+ * The SVG string IS the icon identity on NativeScript (no icon theme is
+ * resolved), so it goes in where GTK puts the icon NAME. Clearing it is the
+ * mapping worth having in one place: C offers no "unset the icon", only the
+ * side effect of filling another slot (adw-split-button.c:749-771), so an empty
+ * SVG clears the content and lets the label half take over again — which is what
+ * every caller assigning `actionIcon` from a nullable lookup expects.
+ *
+ * Lives here rather than in the widget so it is unit-testable off-device: the
+ * widget module `extends GridLayout` and cannot be imported on GJS/Node.
+ */
+export declare function setActionIcon(state: SplitButtonState, svg: string | null | undefined): void;

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

@@ -1,4 +1,6 @@
 import { type Cancelable, type EventData, GridLayout, type View } from '@nativescript/core';
+import { type SidebarWidthProps, type SplitViewWidthRule } from './split-view-width.js';
+import type { AdwPackType, NsShowSidebarNotification, NsSplitViewState } from './split-view-state.js';
 /** Event name emitted when the sidebar visibility changes. */
 export declare const NOTIFY_SHOW_SIDEBAR = "notify::show-sidebar";
 /** Payload of the `notify::show-sidebar` event. */
@@ -8,24 +10,38 @@ export interface NotifyShowSidebarEventData extends EventData {
     /** Whether the view is in its collapsed (narrow) mode. */
     collapsed: boolean;
 }
-/** Default sidebar width, in DIPs. */
-export declare const DEFAULT_SIDEBAR_WIDTH = 240;
-export declare abstract class AdwSplitViewBase extends GridLayout {
+export declare abstract class AdwSplitViewBase<TState extends NsSplitViewState = NsSplitViewState> extends GridLayout {
+    /** Which widget's width rule applies — they differ once a pane has a minimum. */
+    protected readonly _widthRule: SplitViewWidthRule;
+    /** The headless state machine this widget renders (`split-view-state.ts`). */
+    protected readonly _state: TState;
     protected _sidebar: View | null;
     protected _content: View | null;
-    protected _collapsed: boolean;
-    protected _showSidebar: boolean;
-    protected _sidebarWidth: number;
-    protected _sidebarPosition: 'start' | 'end';
-    constructor(rootClass: string);
+    /** The three width PROPERTIES; the drawn width is derived from them. */
+    protected _widthProps: SidebarWidthProps;
+    /** The container width the sidebar was last sized against, in DIPs. */
+    protected _measuredWidth: number;
+    /** An explicit `sidebarWidth` assignment, which overrides the derivation. */
+    protected _sidebarWidthOverride: number | null;
+    constructor(rootClass: string, 
+    /** Which widget's width rule applies — they differ once a pane has a minimum. */
+    _widthRule: SplitViewWidthRule, 
+    /** The headless state machine this widget renders (`split-view-state.ts`). */
+    _state: TState);
     /**
      * (Re)declare the two columns so the sidebar's column is fixed-width ('auto')
      * and the content's is expanding ('star'), ordered by {@link sidebarPosition}:
      * `start` → [sidebar auto, content star]; `end` → [content star, sidebar auto].
      * Without this an `end` sidebar would land in the expanding column and float
      * away from the right edge (leaving a gap), with the content squeezed.
+     *
+     * `splitViewColumns()` is the other half of the same rule — which column each
+     * PANE is written into. The two must agree, or an `end` sidebar ends up in the
+     * expanding column with the content squeezed into the fixed one.
      */
     protected _syncColumns(): void;
+    /** Re-emit `notify::show-sidebar` for a state change. */
+    protected _emitShowSidebar(event: NsShowSidebarNotification): void;
     /** Subclass-specific layout application for the current collapsed/show state. */
     protected abstract _applyLayout(): void;
     /** Apply a user-initiated show/hide toggle. The default is an instant re-layout;
@@ -54,20 +70,47 @@ export declare abstract class AdwSplitViewBase extends GridLayout {
     showSidebarPane(): void;
     /** Hide the sidebar (relevant in collapsed mode). */
     hideSidebarPane(): void;
-    /** Whether the view is in collapsed (narrow / single-pane) mode. */
+    /**
+     * Whether the view is in collapsed (narrow / single-pane) mode.
+     *
+     * On an OVERLAY split view this is not an independent flag: unless the sidebar
+     * is pinned, collapsing hides it and uncollapsing shows it, emitting
+     * `notify::show-sidebar` first — the state machine owns that, not this setter.
+     */
     get collapsed(): boolean;
     set collapsed(value: boolean);
     /** Whether the sidebar is shown. Toggling emits `notify::show-sidebar`. */
     get showSidebar(): boolean;
     set showSidebar(value: boolean);
-    /** The sidebar pane width, in DIPs. */
+    /**
+     * The sidebar pane width in DIPs, DERIVED from the container size unless a
+     * caller assigned one. `Adw.OverlaySplitView` has no stored width — see
+     * `split-view-width.ts` for why the old fixed 240 could not be right.
+     */
     get sidebarWidth(): number;
     set sidebarWidth(value: number);
+    /** Lower bound in DIPs (`Adw.OverlaySplitView:min-sidebar-width`, default 180). */
+    get minSidebarWidth(): number;
+    set minSidebarWidth(value: number);
+    /** Upper bound in DIPs (`Adw.OverlaySplitView:max-sidebar-width`, default 280). */
+    get maxSidebarWidth(): number;
+    set maxSidebarWidth(value: number);
+    /** Share of the container the sidebar asks for (default 0.25). */
+    get sidebarWidthFraction(): number;
+    set sidebarWidthFraction(value: number);
+    /**
+     * Re-measure the container and re-size the sidebar.
+     *
+     * Called from `layoutChanged`, the same size source `addBreakpoints` uses —
+     * NativeScript has no window-resize signal, so a view's post-layout size is
+     * the closest thing to the window size Adwaita evaluates against.
+     */
+    protected _applySidebarWidth(): void;
     /** Which side the sidebar sits on — `'start'` (leading / left) or `'end'`
      *  (trailing / right). Mirrors `Adw.OverlaySplitView`'s `sidebar-position`
      *  (the storybook controls overlay uses `'end'`). */
-    get sidebarPosition(): 'start' | 'end';
-    set sidebarPosition(value: 'start' | 'end');
+    get sidebarPosition(): AdwPackType;
+    set sidebarPosition(value: AdwPackType);
     /** The sidebar pane, or `null`. */
     get sidebar(): View | null;
     /** The content pane, or `null`. */

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

@@ -0,0 +1,196 @@
+import type { AdwPackType, 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): {
+    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 NOT wired on
+ * NativeScript, so the panes are tracked by presence with a marker object rather
+ * than by handing the core a `View` — a `View` is not a `NavigationPageRef` and
+ * pretending otherwise would silently give a pane whatever `tag` property
+ * NativeScript happens to put on a view.
+ */
+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;
+    });
+    bind(host: NsSplitViewHost): void;
+    /** 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[];