@gjsify/adwaita-nativescript 0.31.0 → 0.33.0

package/lib/types/widgets/navigation-stack.d.ts

@@ -0,0 +1,153 @@
+import type { AdwNavigationPageProps, NavigationDiagnosticListener, NavigationShortcutResult } from '@gjsify/adwaita-core';
+import type { View } 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";
+/** Emitted after a page has been pushed. Mirrors `AdwNavigationView::pushed`. */
+export declare const PUSHED = "pushed";
+/** Emitted after a page has been popped — once per popped page, top-first. Mirrors `AdwNavigationView::popped`. */
+export declare const POPPED = "popped";
+/** Emitted after the whole stack has been replaced. Mirrors `AdwNavigationView::replaced`. */
+export declare const REPLACED = "replaced";
+/** The NS visibility values a navigation page is toggled between. */
+export type NsPageVisibility = 'visible' | 'collapse';
+/** The CSS class every managed page carries, so `_navigation-view.scss` applies. */
+export declare const NS_NAVIGATION_PAGE_CLASS = "adw-navigation-page";
+/** Append the navigation-page class to a view's existing class list. */
+export declare function navigationPageClassName(existing: string | null | undefined): string;
+/** One signal the widget must re-emit, already reduced to its payload. */
+export interface NsNavigationEvent {
+    /** {@link PUSHED}, {@link POPPED}, {@link REPLACED} or {@link NOTIFY_VISIBLE_PAGE}. */
+    name: string;
+    /** The page the signal is about — `null` for `replaced` and for an emptied view. */
+    page: View | null;
+    /**
+     * That page's tag, or `null`. A page destroyed by the SAME mutation has already
+     * left the registry, so its tag reads `null` — the page handle is the reliable
+     * identity in an event payload.
+     */
+    tag: string | null;
+    /** The stack depth after the change. */
+    depth: number;
+}
+/** The NativeScript side of the adapter: child management + signal emission. */
+export interface NsNavigationHost {
+    /** Add `view` as an overlaying child of the navigation grid. */
+    attachPage(view: View): void;
+    /** Remove `view` from the grid — the page has been destroyed. */
+    detachPage(view: View): void;
+    /** Show or hide a page. Instant: the NS CSS subset has no transition. */
+    setPageVisibility(view: View, visibility: NsPageVisibility): void;
+    /** Re-emit a GObject-style signal on the widget. */
+    emit(event: NsNavigationEvent): void;
+}
+/** Construction seams. */
+export interface NsNavigationStackOptions {
+    /** Where rejected mutations go — the widget logs them; a test collects them. */
+    onDiagnostic?: NavigationDiagnosticListener;
+}
+/**
+ * `Adw.NavigationView` bound to a NativeScript view tree.
+ *
+ * Holds a `NavigationViewState` and keeps the grid's children in step with its
+ * registry: a page enters the tree when it is registered and leaves when it is
+ * destroyed, and the top of the stack is the only visible one. The widget keeps
+ * ZERO navigation state.
+ */
+export declare class NsNavigationStack {
+    private readonly _state;
+    private readonly _host;
+    /** The views currently in the grid — the mirror of the core's registry. */
+    private readonly _attached;
+    private readonly _onDiagnostic;
+    private _pending;
+    constructor(host: NsNavigationHost, options?: NsNavigationStackOptions);
+    /** 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 stack(): readonly View[];
+    /** Every registered page — static and dynamically pushed. */
+    get pages(): readonly View[];
+    /**
+     * `Adw.NavigationView:animate-transitions`. Stored and honoured by the shared
+     * change payload, but NativeScript paints the swap instantly either way — the
+     * CSS subset has no transition, so a real app animates with `View.animate()`.
+     */
+    get animateTransitions(): boolean;
+    /** `Adw.NavigationView:pop-on-escape` — consulted by {@link popFromEscape}. */
+    get popOnEscape(): boolean;
+    /** Whether `view` is known to this navigation view. */
+    isRegistered(view: View): boolean;
+    /** `view`'s tag, or `null`. */
+    tagOf(view: View): string | null;
+    /** `view`'s title (`''` when untitled). */
+    titleOf(view: View): string;
+    /** Whether `view` may be popped by a shortcut or a back button. */
+    canPopOf(view: View): boolean;
+    /** 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;
+    /** Whether a back button belongs on the visible page. */
+    canGoBack(): boolean;
+    /** The back button's tooltip — the previous page's title, or `null` when there is no button. */
+    backButtonTooltip(fallback?: string): string | null;
+    /**
+     * 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.
+     */
+    add(view: View, tag?: string | null, options?: Omit<AdwNavigationPageProps, 'tag'>): boolean;
+    /** Remove a page. One that is on the stack is removed when it is POPPED. */
+    remove(view: View): boolean;
+    /** Push a page (a previously-registered tag, or a fresh view) onto the stack. */
+    push(viewOrTag: View | string, options?: AdwNavigationPageProps): boolean;
+    /** Push the page carrying `tag`. */
+    pushByTag(tag: string): boolean;
+    /** Pop the top page. `can-pop` does NOT gate this — it gates the shortcuts. */
+    pop(): boolean;
+    /** 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. String entries are resolved BEFORE anything is
+     * mutated, so replacing the stack with the tag of a dynamically-pushed page
+     * keeps that page (replace_with_tags:3136-3147).
+     */
+    replace(entries: ReadonlyArray<View | string | null>, props?: (view: View) => AdwNavigationPageProps | undefined): void;
+    /** Replace the stack with the pages carrying `tags`. */
+    replaceWithTags(tags: readonly string[]): void;
+    /** Set a page's tag. Rejected when another page already owns it. */
+    setTag(view: View, tag: string | null): boolean;
+    /** Set a page's title — the NEXT page's back-button tooltip. */
+    setTitle(view: View, title: string): boolean;
+    /** Set a page's `can-pop`: gates the shortcuts and a back button, not `pop()`. */
+    setCanPop(view: View, canPop: boolean): boolean;
+    /** Set `animate-transitions`. */
+    setAnimateTransitions(value: boolean): boolean;
+    /** Set `pop-on-escape`. */
+    setPopOnEscape(value: boolean): boolean;
+    /** The `can-pop`-aware pop behind a hardware back button or Alt+Left. */
+    popFromShortcut(): NavigationShortcutResult;
+    /** Escape-to-pop, gated on `pop-on-escape`. */
+    popFromEscape(): NavigationShortcutResult;
+    /**
+     * Settle the transition (a no-op here beyond what {@link _flush} already did):
+     * NativeScript never defers, so this exists only so the widget exposes the
+     * whole `Adw.NavigationView` surface.
+     */
+    finishTransition(): readonly View[];
+    /**
+     * Apply the change the last mutation produced: bring the view tree in step,
+     * then re-emit the signals. The tree is synced FIRST so a listener reading
+     * `visiblePage` from the event sees a mounted page.
+     */
+    private _flush;
+    private _emit;
+    private _notify;
+    /** Mirror the core's registry into the grid, then raise the top of the stack. */
+    private _sync;
+}

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

@@ -0,0 +1,52 @@
+import type { PreferencesGroupHeaderState } from '@gjsify/adwaita-core';
+/** The two `View.visibility` values a preferences group ever assigns. */
+export type NsVisibility = 'visible' | 'collapse';
+/** The header box's base style class. */
+export declare const PREFERENCES_GROUP_HEADER_CLASS = "adw-preferences-group-header";
+/**
+ * The style class libadwaita toggles for a one-line header. Not cosmetic: the
+ * stylesheet gives `.single-line` a `min-height` and everything else a bottom
+ * margin, so a header without it is laid out as if it had two lines.
+ */
+export declare const PREFERENCES_GROUP_SINGLE_LINE_CLASS = "single-line";
+/** What a group knows about itself when it re-derives its visuals. */
+export interface NsPreferencesGroupInput {
+    /** `AdwPreferencesGroup:title`. */
+    title?: string | null;
+    /** `AdwPreferencesGroup:description`. */
+    description?: string | null;
+    /** Whether a `header-suffix` view is set. */
+    hasHeaderSuffix?: boolean;
+    /** How many children the boxed list holds. */
+    rowCount?: number;
+}
+/** The NativeScript form of {@link PreferencesGroupHeaderState}. */
+export interface NsPreferencesGroupVisuals {
+    /** `visibility` for the title label. */
+    titleVisibility: NsVisibility;
+    /** `visibility` for the description label. */
+    descriptionVisibility: NsVisibility;
+    /** `visibility` for the whole header box. */
+    headerVisibility: NsVisibility;
+    /** `className` for the header box, carrying `single-line` when it applies. */
+    headerClassName: string;
+    /** `visibility` for the `.boxed-list` container. */
+    listboxVisibility: NsVisibility;
+}
+/**
+ * The five derived states for a group.
+ *
+ * `useMarkup: false` is deliberate and is the same choice the browser renderer
+ * makes: an NS `Label` shows the string verbatim (it has no Pango markup), so
+ * visibility must be judged on the string that is actually painted. Rendering
+ * markup is a separate, still-open gap; closing it flips this one flag.
+ */
+export declare function preferencesGroupHeaderState(input: NsPreferencesGroupInput): PreferencesGroupHeaderState;
+/**
+ * `visibility` / `className` a group must apply for the given inputs.
+ *
+ * `'collapse'` rather than `'hidden'`: a hidden NS view still occupies its
+ * space, which would leave the header's padding behind on a group that has no
+ * header — the very thing `update_header_visibility` exists to avoid.
+ */
+export declare function preferencesGroupVisuals(input: NsPreferencesGroupInput): NsPreferencesGroupVisuals;

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,7 @@
 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';
+import type { AdwTextDirection } from '@gjsify/adwaita-core';
 /** 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 +11,54 @@ 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;
+    /**
+     * Publish which visual side the pane is on, so the theme can put the divider
+     * there — the CSS counterpart to `_sidebars.scss`'s `:dir()` x `.end`
+     * product. A fixed `border-right` drew it on the wrong edge for an `end`
+     * sidebar and for every RTL layout.
+     */
+    protected _syncSidebarSide(view?: View | null): void;
+    /**
+     * The reading direction `start` / `end` resolve against.
+     *
+     * `direction` is an INHERITED CSS property on NativeScript's `Style`, so a
+     * `direction: rtl` on the Page reaches every split view under it — the same
+     * way GTK's text direction reaches a widget from its window. It defaults to
+     * unset, which is `ltr`.
+     */
+    get textDirection(): AdwTextDirection;
+    /** 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 +87,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`. */