@gjsify/adwaita-nativescript 0.36.0 → 0.37.0

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

@@ -2,7 +2,6 @@ import type { AdwPackType, AdwTextDirection, NavigationActionResult, NavigationS
 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;
@@ -10,10 +9,10 @@ export interface NsShowSidebarNotification {
 /**
  * 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.
+ * Only changes with real ordering or animation semantics come through here.
+ * Structural mutations (mounting a pane, moving the sidebar) stay the widget's own
+ * business, because they also have to re-declare the grid columns — a callback
+ * could only run after that anyway.
  */
 export interface NsSplitViewHost {
     /** Re-run the structural layout for the SETTLED state. Instant. */
@@ -27,17 +26,16 @@ export interface NsSplitViewHost {
 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. */
+    /** Returns whether it changed. */
     setCollapsed(value: boolean): boolean;
-    /** Show or hide the sidebar. Returns whether it changed. */
+    /** Returns whether it changed. */
     setShowSidebar(value: boolean): boolean;
-    /** Move the sidebar to the other side. Returns whether it changed. */
+    /** 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;
@@ -47,45 +45,35 @@ export interface NsSplitViewState {
  *
  * `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).
+ * `sidebar-position`. A pane in the wrong column is therefore not merely mirrored,
+ * it also swaps its sizing mode.
  */
 export declare function splitViewColumns(sidebarPosition: AdwPackType, direction?: AdwTextDirection): {
     sidebar: number;
     content: number;
 };
 /**
- * `Adw.OverlaySplitView` bound to a NativeScript widget.
+ * `Adw.OverlaySplitView` bound to a NativeScript widget. The widget keeps ZERO
+ * split-view state.
  *
- * 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`.
+ * The reveal is NOT driven from here: NativeScript animates with a native
+ * `View.animate()` on `translateX`/`opacity` rather than by sampling a progress
+ * value, so the core's `SplitViewAnimator` seam stays on its instant default and
+ * `show-progress` settles at 0 or 1 — what `adw_animation_skip` also yields.
  */
 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.
+     * STRUCTURAL, not a user toggle: `set_collapsed` passes `animate = FALSE` and
+     * the `collapsed` notification 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;
@@ -93,30 +81,26 @@ export declare class NsOverlaySplitViewState implements NsSplitViewState {
     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). */
+    /** Whether the tap-to-dismiss scrim takes input — `update_shield`. */
     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.
+     * Whether the SIDEBAR pane may take focus — GTK's
+     * `can_focus = !collapsed || show_sidebar`. NativeScript's equivalent is
+     * `isUserInteractionEnabled`; 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). */
+    /** The mirror of {@link sidebarFocusable} for the CONTENT pane. */
     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).
+     * across the whole setter and thaws them in queue order.
      */
     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). */
+    /** Pin the sidebar so collapsing no longer hides it (`pin-sidebar`). */
     setPinSidebar(value: boolean): boolean;
     /** Move the sidebar to the other side. The widget re-declares its columns. */
     setSidebarPosition(position: AdwPackType): boolean;
@@ -125,26 +109,24 @@ export declare class NsOverlaySplitViewState implements NsSplitViewState {
      * 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. */
+    /** Tap on the scrim — 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.
+ * This port spells the visible pane `showSidebar`, GTK spells it `show-content`;
+ * they are each other's negation and the core owns the meaning, including the
+ * 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 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.
+ * Tags go 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. Panes stay
+ * tracked by presence with a marker object and the tag of record lives in the
+ * core, 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;
@@ -163,29 +145,20 @@ export declare class NsNavigationSplitViewState implements NsSplitViewState {
     });
     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.
+     * Retag a mounted pane — `check_tags_cb`. 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). */
+    /** `navigation.push` with `tag`. */
     push(tag: string): NavigationActionResult;
-    /** `navigation.pop` — `navigation_pop_cb` (:687-702). */
+    /** `navigation.pop`. */
     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.
-     */
+    /** `Adw.NavigationSplitView:show-content` — the negation of {@link showSidebar}. */
     get showContent(): boolean;
     set showContent(value: boolean);
     /** Whether the panes are stacked (one at a time) rather than side by side. */
@@ -199,24 +172,23 @@ export declare class NsNavigationSplitViewState implements NsSplitViewState {
     /**
      * 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.
+     * Keyed on the stack, not on `showSidebar`: a LONE child stays visible whatever
+     * `show-content` says, and keying on the flag alone renders 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.
+     * `replace` for a structural rebuild 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.
+     * and hiding it a PUSH — the reverse of `start`.
      */
     get transition(): NavigationStackPlan['transition'];
-    /** Collapse or expand. `Adw.NavigationSplitView` has no `show-content` coupling (:1341-1353). */
+    /** Collapse or expand. `Adw.NavigationSplitView` has no `show-content` coupling. */
     setCollapsed(value: boolean): boolean;
     /** Show the sidebar (`true`) or the content (`false`) while collapsed. */
     setShowSidebar(value: boolean): boolean;

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

@@ -20,56 +20,45 @@ export interface SplitViewWidthContext {
     /** 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.
+     * Whether the view is collapsed. Overlay only, and not a detail: a COLLAPSED
+     * `get_sidebar_width` IGNORES the fraction and clamps the VIEW width instead, 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).
+ * The two widgets genuinely differ: OVERLAY takes a final
+ * `min(width, totalWidth - contentMin)` and never claims more than the view has left;
+ * NAVIGATION folds that 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
+ * splits them: navigation answers 180 (its minimum), overlay answers 100.
  *
- * `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}).
+ * `collapsed` only reaches the overlay rule, because only the overlay has a collapsed
+ * sidebar to size ({@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
+ * `totalWidth <= 0` means NativeScript has not laid the view out yet, so the MINIMUM
+ * is returned rather than a fraction of nothing: the smallest thing libadwaita would
  * 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.
+ * Exactly one case says no: a COLLAPSED navigation split view has no sidebar column,
+ * its visible page fills the whole view, and NativeScript expresses that as
+ * `width = 'auto'` spanning both columns. Writing a number over it snaps 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.
+ * The overlay is deliberately NOT exempt: its collapsed sidebar really is a
+ * clamped-width overlay drawn above the content, so it still wants a number.
  */
 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.
+ * Normalise one width property. A non-finite or negative input falls back to the
+ * DEFAULT rather than to zero, because a zero-width sidebar is indistinguishable from
+ * a missing one on screen.
  */
 export declare function normalizeWidthProp(value: number, fallback: number): number;
 /** Clamp the fraction into the `[0, 1]` range its GTK property is declared with. */

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

@@ -1,23 +1,18 @@
 /** 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.
+ * `string_is_not_empty`, bound to the `visible` of BOTH the title and the description
+ * labels. It is `string && string[0]` — one byte, no trim: a title of `"   "` is a
+ * VISIBLE title in libadwaita, so trimming here 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).
+ * `has_image`, bound to the image's `visible`.
  *
- * 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.
+ * C is `paintable || (icon_name && icon_name[0])`; this port has no `paintable`
+ * counterpart (the icon is an SVG string handed to `AdwIcon`), so only the second
+ * half applies. Kept as its own predicate rather than folded into
+ * {@link statusPageLabelVisibility} because upstream really are two 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/tab-view-state.d.ts

@@ -8,10 +8,9 @@ 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.
+ * 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: closing the last tab EMPTIES the view.
  */
 export declare function tabPageVisibilities(state: TabViewState<View>): NsVisibility[];
 /** Push {@link tabPageVisibilities} onto the real content views. */
@@ -19,40 +18,26 @@ 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.
+ * `tabCloseVisible` is `(hovering && fullyVisible) || selected || dragging`, and never
+ * on a pinned tab. Touch has no hover and this port has no tab drag-and-drop, so both
+ * are constantly false and the predicate REDUCES to "selected, and not pinned" —
+ * called rather than written out so it stays a derivation.
  */
 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.
- */
+/** The `visibility` of the whole tab bar — `tabsRevealed` projected onto NS. */
 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".
+ * The text a tab's label shows. A pinned tab is a single-glyph chip in libadwaita —
+ * `adw_tab_constructed` hides its title outright — so it renders no label here either.
+ * Everything else shows its title, which the model has already coerced to `''` for a
+ * page that declared none.
  */
 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.
+ * The tooltip text for a tab — the page's own tooltip when it has one, its title
+ * otherwise. NS has no tooltip primitive, so this is exposed for a consumer (and the
+ * accessibility label) rather than rendered, and in TEXT form: a page-supplied tooltip
+ * is Pango markup in C and NS has no markup sink.
  */
 export declare function tabTooltipText(page: AdwTabPage): string;
 /** The data half of the `notify::selected-page` event (minus NS's `eventName`/`object`). */
@@ -67,8 +52,7 @@ export interface TabViewNotifyPayload {
     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.
+ * Project a core change onto the event payload. A function rather than a spread so a
+ * live model object cannot leak into an event a consumer holds on to.
  */
 export declare function tabViewNotifyPayload(change: TabViewSelectionChange): TabViewNotifyPayload;

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

@@ -18,7 +18,7 @@ export interface NotifyViewSelectedEventData extends EventData, ViewSwitcherNoti
 export declare abstract class AdwViewSwitcherBase extends GridLayout {
     /** The horizontal switcher bar holding the buttons. */
     protected readonly _bar: GridLayout;
-    /** `Adw.ViewSwitcher:policy`, default NARROW (adw-view-switcher.c:447-451). */
+    /** `Adw.ViewSwitcher:policy`, default NARROW as in C. */
     private _policy;
     /** The content area where the selected page is shown. */
     protected readonly _contentArea: GridLayout;
@@ -31,30 +31,14 @@ export declare abstract class AdwViewSwitcherBase extends GridLayout {
     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.
-     */
+    /** `AdwViewSwitcher:policy`, which decides the button orientation. A subclass may 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.
-     */
+    /** `Adw.ViewSwitcher:policy` — settable, so a consumer can drive it from a breakpoint. */
     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
+     * What the buttons show. `'both'` for the classic switcher, whose buttons always
+     * have an icon and a label; `AdwInlineViewSwitcher` overrides it with the real
      * `AdwInlineViewSwitcherDisplayMode`.
      */
     protected get buttonDisplayMode(): AdwInlineViewSwitcherDisplayMode;
@@ -64,10 +48,9 @@ export declare abstract class AdwViewSwitcherBase extends GridLayout {
     /**
      * 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).
+     * The SELECTED PAGE survives the rebuild whenever a page of the same name does —
+     * libadwaita's selection is a page pointer, not an index — and falls back to the
+     * first VISIBLE page otherwise.
      */
     setViews(pages: AdwViewPage[]): void;
     /** Build one button's NS nodes. Painted by {@link _applySelection}. */
@@ -88,17 +71,15 @@ export declare abstract class AdwViewSwitcherBase extends GridLayout {
      * 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).
+     * NO-OPS — refused, never clamped, as `adw_view_stack_pages_select_item` does.
      */
     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).
+     * Show or hide a page by name. Returns whether the SELECTION moved: hiding the
+     * selected page falls back to the first still-visible one.
      */
     setPageVisible(name: string, visible: boolean): boolean;
 }

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

@@ -5,10 +5,8 @@ import type { AdwViewSwitcherPageInit, ViewSwitcherStateChange } from '@gjsify/a
  * One page registered with a view switcher.
  *
  * Mirrors `AdwViewStackPage`'s properties with their C defaults. `title` and
- * `icon` are NULLABLE on purpose: a page with neither renders no button at all
- * (adw-view-switcher.c:178), and once an absent title has been flattened to `''`
- * that rule is no longer expressible — which is why the old shape, with a
- * required `title: string`, could not implement it.
+ * `icon` are NULLABLE on purpose: a page with neither renders no button at all, and
+ * an absent title flattened to `''` makes that rule inexpressible.
  *
  * `icon` is an Adwaita symbolic SVG DOCUMENT here, not a GTK icon name: `AdwIcon`
  * rasterises the path data natively. The core treats the field as an opaque
@@ -16,12 +14,7 @@ import type { AdwViewSwitcherPageInit, ViewSwitcherStateChange } from '@gjsify/a
  * the fallback sentinel it hands back.
  */
 export interface AdwViewPage {
-    /**
-     * The switcher button label. ABSENT means the page has none — which is C's
-     * NULL, and the state the button-visibility rule turns on. Spelled as an
-     * optional `string` rather than `string | null` so the existing consumers
-     * that pass a plain `string` keep type-checking unchanged.
-     */
+    /** The switcher button label. ABSENT is C's NULL — the state button visibility turns on. */
     title?: string;
     /** The page content view, shown when this page is selected. */
     content: View;
@@ -47,9 +40,9 @@ export declare function createViewSwitcherBarState(): ViewSwitcherBarState;
 /**
  * Project one NS page onto the core's page init.
  *
- * A page without an explicit `name` gets its POSITION as the name — the NS API
- * has always been positional (`setViews` takes an array), and a stable id is
- * what the name-preserving rebuild needs to keep the selected page selected.
+ * A page without an explicit `name` gets its POSITION as the name: the NS API is
+ * positional (`setViews` takes an array), and the name-preserving rebuild needs a
+ * stable id to keep the selected page selected.
  */
 export declare function viewSwitcherPageSpec(page: AdwViewPage, index: number): AdwViewSwitcherPageInit;
 /** {@link viewSwitcherPageSpec} over a whole page list. */
@@ -57,11 +50,10 @@ export declare function viewSwitcherPageSpecs(pages: readonly AdwViewPage[]): Ad
 /**
  * Resolve the core's icon slot to something `AdwIcon` can rasterise.
  *
- * The core substitutes the NAME `image-missing` for an absent icon
- * (adw-view-switcher-button.c:405). On the browser side that name becomes a CSS
- * mask class; here it has to become the actual symbolic document, so the
- * sentinel is swapped for the vendored `image-missing-symbolic` SVG. Anything
- * else is already an SVG and passes through.
+ * The core substitutes the NAME `image-missing` for an absent icon. On the browser
+ * side that name becomes a CSS mask class; here it has to become the actual
+ * symbolic document, so the sentinel is swapped for the vendored
+ * `image-missing-symbolic` SVG. Anything else is already an SVG and passes through.
  */
 export declare function nsIconSvg(iconName: string): string;
 /**
@@ -76,24 +68,15 @@ export declare function applyViewSwitcherVisibility(pages: readonly AdwViewPage[
 /** Which switcher is asking — the two apply different visibility rules. */
 export type ViewSwitcherKind = 'switcher' | 'inline';
 /**
- * Whether a page gets a button/toggle at all.
+ * Whether a page gets a button/toggle at all. The two switchers genuinely differ:
  *
- * The two switchers genuinely differ, and the difference is easy to miss because
- * only one of them is documented where you would look:
+ * - `AdwViewSwitcher` needs a title or an icon ON TOP OF `visible`
+ *   (`visible && (title != NULL || icon_name != NULL)`).
+ * - `AdwInlineViewSwitcher` gates on `visible` alone, so a page with neither still
+ *   gets an empty toggle.
  *
- * - `AdwViewSwitcher` needs a title or an icon ON TOP OF `visible` —
- *   `gtk_widget_set_visible (button, visible && (title != NULL || icon_name !=
- *   NULL))` (adw-view-switcher.c:178).
- * - `AdwInlineViewSwitcher` does not. `populate_group` gates on `visible` alone
- *   (adw-inline-view-switcher.c:370-378), so a page with neither still gets an
- *   empty toggle.
- *
- * The inline widget inherited the stricter rule and silently dropped toggles
- * libadwaita draws. `@gjsify/adwaita-core` had spelled this out in
- * `buildInlineToggles`' doc and pinned it in `INLINE_TOGGLE_VECTORS` the whole
- * time — the rule just lived in a class that `extends GridLayout`, which no
- * spec can import, so nothing could reach it to check. That is why it is here
- * and not there.
+ * The rule lives here rather than in the widget because a class that `extends
+ * GridLayout` cannot be imported by a spec.
  */
 export declare function switcherButtonVisible(kind: ViewSwitcherKind, modelVisible: boolean, pageVisible: boolean): boolean;
 /** The data half of the `notify::selected` event (minus NS's `eventName`/`object`). */