@gjsify/adwaita-nativescript 0.51.1 → 0.53.0

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

@@ -1,8 +1,9 @@
 import type { View } from '@nativescript/core';
 import { GridLayout, type EventData } from '@nativescript/core';
-import { type AdwViewStackPage, type ViewStackNotifyPayload } from './view-stack-state.js';
+import { type AdwViewStackPageInfo, type ViewStackNotifyPayload } from './view-stack-state.js';
+import { AdwViewStackPage } from './view-stack-page.js';
 import { type ConstructProps } from './construct-props.js';
-export type { AdwViewStackPage };
+export type { AdwViewStackPageInfo };
 /** Event name emitted when the visible child changes. Mirrors GObject `notify::visible-child`. */
 export declare const NOTIFY_VISIBLE_CHILD = "notify::visible-child";
 /**
@@ -15,6 +16,18 @@ export interface NotifyVisibleChildEventData extends EventData, ViewStackNotifyP
 declare const AdwViewStack_base: (abstract new (...args: any[]) => {
     connect(eventName: string, callback: (self: /*elided*/ any, data: EventData) => void): number;
     disconnect(handlerId: number): void;
+    get halign(): string;
+    set halign(value: string | number);
+    get valign(): string;
+    set valign(value: string | number);
+    get hexpand(): boolean;
+    set hexpand(value: boolean | string);
+    get vexpand(): boolean;
+    set vexpand(value: boolean | string);
+    get marginStart(): number;
+    set marginStart(value: number | string);
+    get marginEnd(): number;
+    set marginEnd(value: number | string);
     _emit(eventName: string): void;
     addEventListener(eventName: string, callback: (data: EventData) => void, thisArg?: unknown, once?: boolean): void;
     removeEventListener(eventName: string, callback?: (data: EventData) => void, thisArg?: unknown): void;
@@ -24,6 +37,12 @@ declare const AdwViewStack_base: (abstract new (...args: any[]) => {
     get(name: string): unknown;
 }) & typeof GridLayout;
 export declare class AdwViewStack extends AdwViewStack_base {
+    /**
+     * No named placement: a stack's XML children are its pages, in order, as GtkBuildable's
+     * untyped `<child>` is (`adw_view_stack_buildable_add_child`). An empty list, not an absent
+     * one, so the builder refuses an authored slot by name instead of guessing one.
+     */
+    static readonly builderSlots: readonly string[];
     private readonly _state;
     constructor(props?: ConstructProps<AdwViewStack>);
     /**
@@ -32,16 +51,41 @@ export declare class AdwViewStack extends AdwViewStack_base {
      * initial page without a manual `refresh()` (`add_page`,
      * adw-view-stack.c:1149-1151 → the notify at :1038-1039). Returns the page handle.
      */
-    add(content: View, name: string, title?: string, icon?: string): AdwViewStackPage;
+    add(content: View, name: string, title?: string, icon?: string): AdwViewStackPageInfo;
+    /** Put a page's view into the one cell and let the selection decide what shows. */
+    private _placePage;
+    /**
+     * An XML child — `adw_view_stack_buildable_add_child`: an {@link AdwViewStackPage} record
+     * adds its child under the record's name, title, icon and badge state; any other view is
+     * a page with no name, which is `adw_view_stack_add` (`name` NULL). Before this there was no
+     * child door at all, and `LayoutBase`'s inherited one put every child into the grid
+     * beside the pages, shown whatever the selection said.
+     */
+    _addChildFromBuilder(_name: string, view: View | AdwViewStackPage): void;
     /** Convenience alias matching `Adw.ViewStack.add_titled`. */
-    add_titled(content: View, name: string, title: string): AdwViewStackPage;
+    add_titled(content: View, name: string, title: string): AdwViewStackPageInfo;
     /**
-     * Remove the first page named `name` and detach its content view. Returns
+     * Register a titled page carrying an icon — `Adw.ViewStack.add_titled_with_icon`.
+     *
+     * The same call {@link add} already is, under the name the counterpart gives it. It
+     * exists because the ARGUMENT ORDER is the thing a reader has to get right and this
+     * port had no spelling that matched: `add(child, name, title, icon)` and
+     * `adw_view_stack_add_titled_with_icon (stack, child, name, title, icon_name)` take
+     * the same four values in the same order, so the alias is a rename and cannot drift
+     * from the method it forwards to.
+     */
+    add_titled_with_icon(content: View, name: string, title: string, iconName: string): AdwViewStackPageInfo;
+    /**
+     * Remove a page and detach its content view — `adw_view_stack_remove`. Returns
      * whether anything was removed. When the removed page was the visible one the
      * stack ends up showing NOTHING and emits no event — `stack_remove` clears
      * `visible_child` without re-picking (adw-view-stack.c:1202-1203).
+     *
+     * Takes the CHILD, as the GIR verb does, or the page name the port's headless list
+     * keys on (view-stack-state.ts) — a caller ported off GJS holds the view, and one
+     * that came through {@link visibleChildName} or an XML attribute holds the name.
      */
-    removePage(name: string): boolean;
+    remove(child: View | string): boolean;
     /**
      * Show or hide a page (`AdwViewStackPage:visible`). Returns whether the
      * SELECTION moved: hiding the visible page falls back to the next visible one
@@ -49,8 +93,10 @@ export declare class AdwViewStack extends AdwViewStack_base {
      * (`update_child_visible`, adw-view-stack.c:1061-1082).
      */
     setPageVisible(name: string, visible: boolean): boolean;
+    /** The name of the page holding `child`, or `null` when it is not one of ours. */
+    private _nameOf;
     /** All registered pages, in add order (a bound switcher reads this). */
-    get pages(): readonly AdwViewStackPage[];
+    get pages(): readonly AdwViewStackPageInfo[];
     /**
      * The visible page's position, `-1` when nothing is selected.
      *

package/lib/types/widgets/adw-view-switcher-bar.d.ts

@@ -1,9 +1,22 @@
 import { GridLayout } from '@nativescript/core';
-import type { AdwViewStack } from './adw-view-stack.js';
+import { AdwViewStack } from './adw-view-stack.js';
+import { type ViewId } from './id-reference.js';
 import { type ConstructProps } from './construct-props.js';
 declare const AdwViewSwitcherBar_base: (abstract new (...args: any[]) => {
     connect(eventName: string, callback: (self: /*elided*/ any, data: import("@nativescript/core").EventData) => void): number;
     disconnect(handlerId: number): void;
+    get halign(): string;
+    set halign(value: string | number);
+    get valign(): string;
+    set valign(value: string | number);
+    get hexpand(): boolean;
+    set hexpand(value: boolean | string);
+    get vexpand(): boolean;
+    set vexpand(value: boolean | string);
+    get marginStart(): number;
+    set marginStart(value: number | string);
+    get marginEnd(): number;
+    set marginEnd(value: number | string);
     _emit(eventName: string): void;
     addEventListener(eventName: string, callback: (data: import("@nativescript/core").EventData) => void, thisArg?: unknown, once?: boolean): void;
     removeEventListener(eventName: string, callback?: (data: import("@nativescript/core").EventData) => void, thisArg?: unknown): void;
@@ -13,10 +26,14 @@ declare const AdwViewSwitcherBar_base: (abstract new (...args: any[]) => {
     get(name: string): unknown;
 }) & typeof GridLayout;
 export declare class AdwViewSwitcherBar extends AdwViewSwitcherBar_base {
+    /** `stack` names an `AdwViewStack` of the same tree — see `./builder-slots.ts`. */
+    static readonly builderReferences: readonly string[];
     /** The horizontal (homogeneous) row of buttons. */
     private readonly _bar;
     private _nodes;
     private _stack;
+    /** A `stack` written as an id before the bar was in a loaded tree. */
+    private _stackId;
     private _stackListener;
     private readonly _barState;
     constructor(props?: ConstructProps<AdwViewSwitcherBar>);
@@ -24,7 +41,7 @@ export declare class AdwViewSwitcherBar extends AdwViewSwitcherBar_base {
     set_stack(stack: AdwViewStack | null): void;
     /** The bound stack (`Adw.ViewSwitcherBar.stack`). */
     get stack(): AdwViewStack | null;
-    set stack(value: AdwViewStack | null);
+    set stack(value: AdwViewStack | ViewId | null);
     /**
      * Whether the layout asked for the bar — `Adw.ViewSwitcherBar:reveal`. An
      * adaptive layout sets it `true` on narrow screens and `false` on wide ones,

package/lib/types/widgets/adw-window-title.d.ts

@@ -7,6 +7,18 @@ export declare const NOTIFY_SUBTITLE = "notify::subtitle";
 declare const AdwWindowTitle_base: (abstract new (...args: any[]) => {
     connect(eventName: string, callback: (self: /*elided*/ any, data: EventData) => void): number;
     disconnect(handlerId: number): void;
+    get halign(): string;
+    set halign(value: string | number);
+    get valign(): string;
+    set valign(value: string | number);
+    get hexpand(): boolean;
+    set hexpand(value: boolean | string);
+    get vexpand(): boolean;
+    set vexpand(value: boolean | string);
+    get marginStart(): number;
+    set marginStart(value: number | string);
+    get marginEnd(): number;
+    set marginEnd(value: number | string);
     _emit(eventName: string): void;
     addEventListener(eventName: string, callback: (data: EventData) => void, thisArg?: unknown, once?: boolean): void;
     removeEventListener(eventName: string, callback?: (data: EventData) => void, thisArg?: unknown): void;

package/lib/types/widgets/adw-wrap-box.d.ts

@@ -6,6 +6,18 @@ export type AdwWrapBoxProperty = 'child-spacing' | 'child-spacing-unit' | 'pack-
 declare const AdwWrapBox_base: (abstract new (...args: any[]) => {
     connect(eventName: string, callback: (self: /*elided*/ any, data: import("@nativescript/core").EventData) => void): number;
     disconnect(handlerId: number): void;
+    get halign(): string;
+    set halign(value: string | number);
+    get valign(): string;
+    set valign(value: string | number);
+    get hexpand(): boolean;
+    set hexpand(value: boolean | string);
+    get vexpand(): boolean;
+    set vexpand(value: boolean | string);
+    get marginStart(): number;
+    set marginStart(value: number | string);
+    get marginEnd(): number;
+    set marginEnd(value: number | string);
     _emit(eventName: string): void;
     addEventListener(eventName: string, callback: (data: import("@nativescript/core").EventData) => void, thisArg?: unknown, once?: boolean): void;
     removeEventListener(eventName: string, callback?: (data: import("@nativescript/core").EventData) => void, thisArg?: unknown): void;

package/lib/types/widgets/avatar-view.d.ts

@@ -48,7 +48,7 @@ export interface AvatarViewState extends AvatarVisibilities {
  * unreachable is three assignments; no test here closes that.
  *
  * `hasCustomImage` is hard `false` because the port has no `custom-image` counterpart
- * (status/open-todos.md); when it lands, only this argument changes.
+ * (status/open-todos/README.md); when it lands, only this argument changes.
  */
 export declare function avatarViewState(input: {
     showInitials: boolean;

package/lib/types/widgets/bottom-sheet-state.d.ts

@@ -1,6 +1,6 @@
 import type { EventData, View } from '@nativescript/core';
 import { BottomSheetPresentation } from '@gjsify/adwaita-core';
-import type { BottomSheetCloseOutcome, BottomSheetCloseSource } from '@gjsify/adwaita-core';
+import type { BottomSheetChrome, BottomSheetCloseOutcome, BottomSheetCloseSource } from '@gjsify/adwaita-core';
 /** Event name emitted when the sheet's open state changes. Mirrors GObject `notify::open`. */
 export declare const NOTIFY_OPEN = "notify::open";
 /**
@@ -25,13 +25,46 @@ export type NsSheetVisibility = 'visible' | 'collapse';
 /** The open/can-close model an `AdwBottomSheet` delegates to. */
 export declare function createBottomSheetPresentation(): BottomSheetPresentation;
 /**
- * The `visibility` the sheet panel must carry for the current open state. NS has
- * no transform transition in its CSS subset, so the reveal is instant — the
- * spring animation and its intermediate `progress` are not modelled here.
+ * The `visibility` a sheet pane must carry to be shown or not. NS has no transform
+ * transition in its CSS subset, so every reveal is instant — the spring animation and its
+ * intermediate `progress` are not modelled here.
  */
-export declare function sheetVisibility(open: boolean): NsSheetVisibility;
-/** Push {@link sheetVisibility} onto the real panel view. */
-export declare function applySheetVisibility(panel: View, open: boolean): void;
+export declare function sheetVisibility(shown: boolean): NsSheetVisibility;
+/** Marker class on the bottom-bar bin — the collapsed form the sheet morphs out of. */
+export declare const BOTTOM_BAR_CLASS = "adw-bottom-sheet-bottom-bar";
+/**
+ * Marker class for a bar that refuses to open (`AdwBottomSheet:can-open` off).
+ *
+ * libadwaita spells it `inert` on the bin (adw-bottom-sheet.c:2033-2036) and takes only the
+ * hover/active feedback away with it; the bar stays a live, focusable button. Prefixed here
+ * because every class this port emits is held against `theme/adwaita.css` by name.
+ */
+export declare const INERT_CLASS = "adw-bottom-sheet-inert";
+/** Marker class on the scrim a modal sheet lays over its content while it is open. */
+export declare const DIMMING_CLASS = "adw-bottom-sheet-dimming";
+/** The four views a bottom sheet's chrome is painted onto. */
+export interface BottomSheetPanes {
+    /**
+     * The scrim between the content and the sheet — libadwaita's `dimming` gizmo. Painted
+     * over the content and under the panel, so a tap on the dimmed area lands HERE and never
+     * on the content a modal sheet blocks.
+     */
+    dimming: View;
+    /** The bottom-anchored bin — libadwaita's `sheet_bin`. */
+    panel: View;
+    /** The sheet page inside it: drag handle plus the sheet child. */
+    page: View;
+    /** The bottom-bar bin, the page's sibling in the same slot. */
+    bottomBar: View;
+}
+/**
+ * Paint a {@link BottomSheetChrome} onto the real views.
+ *
+ * The two `visibility` writes are ONE stack in libadwaita (`sheet_stack`), so they are
+ * mutually exclusive by construction here: NS has no stack, and two independently toggled
+ * panes is how a port ends up showing a bar on top of an open sheet.
+ */
+export declare function applyBottomSheetChrome(panes: BottomSheetPanes, chrome: BottomSheetChrome): void;
 /**
  * Which event a gate verdict makes the widget emit, or `null` when it emits
  * nothing.

package/lib/types/widgets/box-layout.d.ts

@@ -1,20 +1,6 @@
-import { resolveWrapBoxChildOrder } from '@gjsify/adwaita-core';
-/**
- * `Gtk.Box:spacing`'s default, in DIPs. `0` in C (`gtkbox.c`, the property's default
- * value), which is also what makes the margin write invisible until a caller asks.
- */
-export declare const DEFAULT_BOX_SPACING = 0;
-/** Which axis a box stacks along — NativeScript's two words, and `Gtk.Orientation`'s nicks. */
-export type BoxOrientation = 'horizontal' | 'vertical';
-/**
- * A spacing value as the box will hold it: a finite, non-negative number of DIPs.
- *
- * `gtk_box_set_spacing` takes an `int` and the property's minimum is 0, so a negative
- * value is clamped rather than refused — the same clamp `normalizeWrapBoxSpacing` applies
- * one widget over, restated here because that one carries the wrap box's UNIT machinery
- * (`Adw.LengthUnit`) and a `Gtk.Box` has no unit to convert from.
- */
-export declare function normalizeBoxSpacing(value: unknown): number;
+import { DEFAULT_BOX_SPACING, normalizeBoxSpacing, resolveWrapBoxChildOrder, type BoxOrientation } from '@gjsify/adwaita-core';
+export { DEFAULT_BOX_SPACING, normalizeBoxSpacing };
+export type { BoxOrientation };
 /** Whether writing `next` over `current` is a change the box must push to its children. */
 export declare function boxSpacingChanges(current: number, next: unknown): boolean;
 /**

package/lib/types/widgets/builder-slots.d.ts

@@ -1,3 +1,31 @@
+/**
+ * Every name a widget's `_addChildFromBuilder` answers to — its own slots and the
+ * fallback, in one list.
+ *
+ * WHY A WIDGET DECLARES THEM AT ALL, when {@link resolveBuilderSlot} already routes:
+ * routing is total by design, so an XML child naming a slot this widget does not have
+ * takes the fallback and lands somewhere plausible, silently — which is exactly right
+ * for a bare `<AdwHeaderBar>` child arriving under its ELEMENT name, and exactly wrong
+ * for a tree that AUTHORED a placement. A builder realising an authored tree has to be
+ * able to ask, before the write, whether the name means anything here; the answer is
+ * the widget's own, so it lives on the widget rather than in a table beside it.
+ *
+ * The fallback is IN the list: it is a name this widget honours — `content` on a
+ * toolbar view, `row` on an expander — and a caller that spells it deliberately gets
+ * the placement it asked for rather than a refusal.
+ */
+export declare function builderSlotsOf<Slot extends string, Fallback extends string>(slots: readonly Slot[], fallback: Fallback): readonly (Slot | Fallback)[];
+/** A widget class that declares {@link builderSlotsOf} — read by the shared-tree builder. */
+export interface BuilderSlotDeclaring {
+    readonly builderSlots: readonly string[];
+}
+/**
+ * The slots a widget CLASS declares, or `null` when it declares none.
+ *
+ * `null` and an empty list are different answers: a class with no declaration cannot be
+ * asked, so the builder refuses every authored slot for it rather than inventing one.
+ */
+export declare function declaredBuilderSlots(ctor: unknown): readonly string[] | null;
 /**
  * The slot an XML child asks for, or `fallback` when it asks for nothing this
  * widget knows.
@@ -14,3 +42,23 @@
  * a widget's own tree.
  */
 export declare function resolveBuilderSlot<Slot extends string, Fallback extends string>(name: unknown, slots: readonly Slot[], fallback: Fallback): Slot | Fallback;
+/**
+ * A widget class that declares which of its properties hold ANOTHER OBJECT of the tree,
+ * named by id — read by the shared-tree builder.
+ *
+ * WHY A DECLARATION, when the builder could look for a string that matches an id: a projected
+ * `.blp` carries `stack: stack` as the prop `stack` holding the STRING `"stack"`, exactly as it
+ * carries `name: "inbox"` — the projection keeps the value and drops the type. GtkBuilder tells
+ * the two apart by the property's `GParamSpec` (an object pspec resolves the id, deferred to
+ * the end of the parse so a reference may point forward), and a runtime without GI has no
+ * pspec to ask. So the widget says which of its properties are object-valued, and the builder
+ * resolves exactly those — never a `name` that happens to equal an id.
+ */
+export interface BuilderReferenceDeclaring {
+    readonly builderReferences: readonly string[];
+}
+/**
+ * The object-valued properties a widget CLASS declares, as the camelCase names its accessors
+ * carry; an empty list when it declares none.
+ */
+export declare function declaredBuilderReferences(ctor: unknown): readonly string[];

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

@@ -1,5 +1,6 @@
 import { BUTTON_CONTENT_STYLE_CLASS, buttonContentEllipsize, buttonContentLabelText, buttonContentLabelVisible } from '@gjsify/adwaita-core';
 import type { ButtonContentEllipsize } from '@gjsify/adwaita-core';
+import { type NsClassName } from './chrome.js';
 export { BUTTON_CONTENT_STYLE_CLASS, buttonContentEllipsize, buttonContentLabelText, buttonContentLabelVisible };
 export type { ButtonContentEllipsize };
 /** The class the content carries while `can-shrink` is set, for the theme to key off. */
@@ -21,14 +22,14 @@ export declare function buttonContentIconIsFallback(icon: string): boolean;
  * of `adw_button_content_root`. Adds rather than rewrites, so a caller's composed
  * classes survive, and is idempotent, so a re-parent cannot double the token.
  */
-export declare function buttonContentRootedParentClassName(current: string): string;
+export declare function buttonContentRootedParentClassName(current: NsClassName): string;
 /**
  * The parent button's `className` with `image-text-button` removed — the unroot half.
  * A button that loses its content must go back to plain-button padding, or the 9px
  * stays on a now text-only button.
  */
-export declare function buttonContentUnrootedParentClassName(current: string): string;
+export declare function buttonContentUnrootedParentClassName(current: NsClassName): string;
 /** The label view's `visibility` — NS's spelling of `gtk_widget_set_visible`. */
 export declare function buttonContentLabelVisibility(label: string): 'visible' | 'collapse';
 /** The content's own `className` for a `can-shrink` value, other tokens untouched. */
-export declare function buttonContentClassName(current: string, canShrink: boolean): string;
+export declare function buttonContentClassName(current: NsClassName, canShrink: boolean): string;

package/lib/types/widgets/carousel-indicator-base.d.ts

@@ -0,0 +1,54 @@
+import { GridLayout, StackLayout } from '@nativescript/core';
+import { AdwCarousel } from './adw-carousel.js';
+import { type ViewId } from './id-reference.js';
+declare const AdwCarouselIndicatorBase_base: (abstract new (...args: any[]) => {
+    connect(eventName: string, callback: (self: /*elided*/ any, data: import("@nativescript/core").EventData) => void): number;
+    disconnect(handlerId: number): void;
+    get halign(): string;
+    set halign(value: string | number);
+    get valign(): string;
+    set valign(value: string | number);
+    get hexpand(): boolean;
+    set hexpand(value: boolean | string);
+    get vexpand(): boolean;
+    set vexpand(value: boolean | string);
+    get marginStart(): number;
+    set marginStart(value: number | string);
+    get marginEnd(): number;
+    set marginEnd(value: number | string);
+    _emit(eventName: string): void;
+    addEventListener(eventName: string, callback: (data: import("@nativescript/core").EventData) => void, thisArg?: unknown, once?: boolean): void;
+    removeEventListener(eventName: string, callback?: (data: import("@nativescript/core").EventData) => void, thisArg?: unknown): void;
+    notify<T extends import("@nativescript/core").EventData>(data: T): void;
+    notifyPropertyChange(name: string, value: unknown, oldValue?: unknown): void;
+    set(name: string, value: unknown): void;
+    get(name: string): unknown;
+}) & typeof GridLayout;
+export declare abstract class AdwCarouselIndicatorBase extends AdwCarouselIndicatorBase_base {
+    /** `carousel` names an `AdwCarousel` of the same tree — see `./builder-slots.ts`. */
+    static readonly builderReferences: readonly string[];
+    /** The marker row, centred in the indicator's cell as the C snapshot centres it. */
+    protected readonly _row: StackLayout;
+    private _carousel;
+    /** A `carousel` written as an id before the indicator was in a loaded tree. */
+    private _carouselId;
+    private readonly _onChange;
+    /** The class every marker carries — `adw-carousel-dot` or `adw-carousel-line`. */
+    protected abstract readonly _markerClass: string;
+    /** What a marker shows; the look is the theme's. */
+    protected abstract readonly _markerText: string;
+    constructor(indicatorClass: string);
+    /** `AdwCarouselIndicator*:carousel` — the carousel whose pages this marks, or `null`. */
+    get carousel(): AdwCarousel | null;
+    set carousel(value: AdwCarousel | ViewId | null);
+    private _resolveCarouselId;
+    /**
+     * `GtkOrientable:orientation` — the axis the markers run along, `horizontal` by default.
+     * The nick, as `Gtk.Box`'s `orientation` takes it; anything else is refused.
+     */
+    get orientation(): string;
+    set orientation(value: string);
+    /** Rebuild the markers when the page count moved, then mark the current page. */
+    private _render;
+}
+export {};

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

@@ -1,4 +1,3 @@
-import type { Label } from '@nativescript/core';
 import { CarouselState } from '@gjsify/adwaita-core';
 import type { CarouselScrollRequest, CarouselStateChange } from '@gjsify/adwaita-core';
 /**
@@ -52,17 +51,21 @@ export declare class CarouselScrollSync {
      */
     apply(state: CarouselState, position: number, epsilon?: number): boolean;
 }
-/** The class string each dot `Label` must carry, in page order. */
-export declare function carouselDotClasses(state: CarouselState): string[];
 /**
- * Push {@link carouselDotClasses} onto the real dot labels.
+ * The class string each marker of a page indicator carries, in page order: `markerClass`,
+ * and `active` on the page the carousel settles on (`current`, `-1` for none).
  *
- * The selected dot comes from `get_page_at_position` (adw-carousel.c:222-239),
- * not from `Math.round`, so a carousel resting half-way between two pages marks
- * the LOWER one — and, unlike the integer compare this replaces, it marks
- * something at all while a swipe is in progress.
+ * The CURRENT page comes from `get_page_at_position` (adw-carousel.c:222-239) — the
+ * carousel's `currentPage` — never from `Math.round(position)`, so a carousel resting
+ * half-way between two pages marks the LOWER one, and a swipe in progress still marks one.
  */
-export declare function applyCarouselDots(state: CarouselState, dots: readonly Label[]): void;
+export declare function indicatorMarkerClasses(markerClass: string, count: number, current: number): string[];
+/** {@link indicatorMarkerClasses} for a dot indicator bound to a carousel in `state`. */
+export declare function carouselDotClasses(state: CarouselState): string[];
+/** Push marker classes onto the real marker views, in page order. */
+export declare function applyMarkerClasses(markers: readonly {
+    className: string;
+}[], classes: readonly string[]): void;
 /** The data half of the `notify::position` event (minus NS's `eventName`/`object`). */
 export interface CarouselNotifyPayload {
     /** The clamped fractional scroll position. */

package/lib/types/widgets/chrome.d.ts

@@ -72,6 +72,22 @@ export interface ToolbarViewClassNames {
     topBar: string;
     bottomBar: string;
 }
+/**
+ * A `className` as READ BACK off a NativeScript view.
+ *
+ * NOT `string`, and the difference is a crash. `classNameProperty` is registered with NO
+ * `defaultValue` (`ui/core/view-base/index.ts:1592`) and `Property`'s getter answers
+ * `key in this ? this[key] : defaultValue` (`ui/core/properties/index.ts:303`), so a view
+ * nobody has written a class onto reads `undefined` — measured against
+ * `@nativescript/core` 9.1.2, not inferred. NativeScript's own `valueChanged` guards
+ * `typeof newValue === 'string'` for exactly this reason.
+ *
+ * A view with no class of its own is ordinary, not exotic: `Gtk.Box` and `Gtk.Label` are
+ * transparent and write no `className` at all, and so does any plain `@nativescript/core`
+ * view a consumer hands a widget. Every function here that takes a class string its
+ * caller did NOT write itself takes this type.
+ */
+export type NsClassName = string | null | undefined;
 /**
  * Swap the classes a widget MANAGES on a NativeScript `className`, leaving every
  * other token in place.
@@ -81,10 +97,20 @@ export interface ToolbarViewClassNames {
  * a fixed base instead would silently drop what a CONSUMER added — the storybook
  * appends `sb-sidebar-pane` to an `AdwToolbarView`, and a re-style would have
  * taken it away again.
+ *
+ * THE ONE FUNNEL, which is why the missing class is answered here and not at a call site.
+ * This took `current: string` and split it unconditionally, and that is how `Adw.Clamp`
+ * killed Learn6502's Android port at startup on a real emulator: `TypeError: … reading
+ * 'split'` on a clamp child carrying no class. THE TYPE IS WHAT HID IT — the ambient
+ * `ns-core.d.ts` promised `string`, so `gjsify tsc` held every call correct, and the
+ * off-device double answered `''` where a device answers `undefined`, leaving nothing in
+ * the package able to see it. Four sibling readers of a class string their caller did not
+ * write — `addMarkerClass`, `removeMarkerClass`, `navigationPageClassName`,
+ * `_paneClassName` — were already tolerant; this family was the one that was not.
  */
-export declare function replaceClasses(current: string, managed: readonly string[], next: readonly string[]): string;
+export declare function replaceClasses(current: NsClassName, managed: readonly string[], next: readonly string[]): string;
 /** The child `className` for a clamp allocation — the size class, and nothing else touched. */
-export declare function clampChildClassName(current: string, sizeClass: AdwClampSizeClass | null): string;
+export declare function clampChildClassName(current: NsClassName, sizeClass: AdwClampSizeClass | null): string;
 /** The five banner properties, as the widget holds them. */
 export type BannerProps = AdwBannerProps;
 /**
@@ -117,7 +143,7 @@ export declare function bannerVisibility(revealed: boolean): 'visible' | 'collap
  * `adw_banner_set_button_style` only ever adds or removes `suggested-action`; it
  * never rewrites the button's class list, and neither does this.
  */
-export declare function bannerButtonClassName(current: string, style: AdwBannerButtonStyle): string;
+export declare function bannerButtonClassName(current: NsClassName, style: AdwBannerButtonStyle): string;
 /**
  * The `className` strings for a toolbar view, given its CURRENT ones, its
  * properties and the measured bar heights.
@@ -127,9 +153,9 @@ export declare function bannerButtonClassName(current: string, style: AdwBannerB
  * that was never given a height fades nothing, so it gets no undershoot.
  */
 export declare function toolbarViewClassNames(current: {
-    view: string;
-    topBar: string;
-    bottomBar: string;
+    view: NsClassName;
+    topBar: NsClassName;
+    bottomBar: NsClassName;
 }, props: ToolbarViewProps, heights: {
     topBarHeight: number;
     bottomBarHeight: number;

package/lib/types/widgets/construct-props.d.ts

@@ -1,9 +1,12 @@
+import type { AdwAdjustmentInput, AdwListModelInput } from '@gjsify/adwaita-core';
 /**
  * The keys a widget's construct-props bag accepts, derived from the widget itself.
  *
  * Methods are dropped; everything else a caller could assign stays, its type read off the
  * GETTER (so `size?: number` even though `set size(value: number | string)` also takes the
- * string XML hands over — the bag is the TypeScript door, the attribute is the string one).
+ * string XML hands over — the bag is the TypeScript door, the attribute is the string one),
+ * except for the two keys {@link ValueProps} widens, where the setter takes a portable VALUE
+ * the getter does not hand back.
  *
  * A read-only accessor survives this type and is refused at RUNTIME instead. The
  * `readonly`-detecting mapped type that would have caught `parent` at compile time was
@@ -12,14 +15,50 @@
  * one that admits two impossible ones and says so when they arrive.
  */
 export type ConstructProps<T> = Partial<{
-    [K in keyof T as T[K] extends (...args: never[]) => unknown ? never : K]: K extends EnumProp ? T[K] | number : T[K];
+    [K in keyof T as T[K] extends (...args: never[]) => unknown ? never : K]: K extends EnumProp ? T[K] | number : K extends ValueProp ? T[K] | ValueProps[K & ValueProp] : T[K];
 }>;
+/**
+ * The two properties whose SETTER takes a portable VALUE the getter does not hand back, and
+ * what each one accepts.
+ *
+ * THE GETTER TYPE IS NOT THE WHOLE DOOR HERE, and the difference is not an XML artifact like
+ * `size`'s `| string`. `set model` takes `AdwListModelInput` — bare strings included, which
+ * is `Gtk.StringList`'s own model and what `Gtk.StringList` itself is — and hands back
+ * normalised `AdwComboOption`s; `set adjustment` takes a PARTIAL and hands back a whole one,
+ * which is what makes `adjustment: { upper: 20 }` move one bound. Read off the getter alone,
+ * the bag refused both — `new Adw.ComboRow({ model: ['Blue', 'Teal'] })` and
+ * `new Adw.SpinRow({ adjustment: { lower: 0, upper: 100 } })` are the spellings the website
+ * gallery has published on every such block, and every one of them was `TS2322` while the
+ * runtime took it: `applyConstructProps` assigns through the setter, so nothing could fail.
+ *
+ * TWO KEY NAMES AND FOUR ACCESSORS: `model` on `AdwComboRow` and `GtkDropDown`, `adjustment`
+ * on `AdwSpinRow` and `AdwSliderRow`, each pair declaring the same input type as the other.
+ * Keyed by NAME like {@link ALIGNMENT_AXES}, because a widget that grows one of these
+ * properties grows it with that meaning or the vocabulary gate refuses the name.
+ *
+ * It is held by `gtk-value-doors.spec.ts`, which writes all four spellings — array, a
+ * `Gtk.StringList`, an object literal and a `Gtk.Adjustment` — through this door and is
+ * type-checked with the rest of the package, so narrowing this table stops that file
+ * compiling.
+ */
+export interface ValueProps {
+    model: AdwListModelInput;
+    adjustment: AdwAdjustmentInput;
+}
+/** The keys {@link ValueProps} declares — {@link ConstructProps} widens exactly these. */
+export type ValueProp = keyof ValueProps;
 /**
  * Every key this bag reads as a GIR ENUM, so `| number` is admitted for exactly those and
  * nowhere else. ADR 0034 § 4's second spelling: a nick is what an XML attribute can carry,
  * and the constant is what a snippet ported off GJS carries.
  */
-export type EnumProp = AlignmentProp | IconSizeProp;
+export type EnumProp = AlignmentProp | GtkAlignProp | IconSizeProp;
+/**
+ * `GtkWidget:halign` / `valign` under GTK's own names (`widget-layout.ts`). Their setters read a
+ * nick or a constant themselves, so unlike {@link AlignmentProp} the bag translates nothing
+ * for them — the widening is the type half alone.
+ */
+export type GtkAlignProp = 'halign' | 'valign';
 /**
  * The NativeScript properties whose value this package reads as a `Gtk.Align`.
  *
@@ -39,8 +78,10 @@ export type EnumProp = AlignmentProp | IconSizeProp;
  * to `stretch`, which is also what the `default:` arm does with it. Nothing here closes the
  * vertical three — the attribute door has no coercer to hang this on and a per-widget
  * `set verticalAlignment` would shadow `View`'s, which is the hazard arm 2 of
- * `check-nativescript-xml-doors.mjs` exists for — so it is a declared divergence and the same
- * § 1 convergence question ADR 0034 § Amendment 12 leaves open for `halign` / `valign`.
+ * `check-nativescript-xml-doors.mjs` exists for — so it stays a declared divergence on
+ * NativeScript's OWN name. The door that agrees everywhere is GTK's: `valign="center"` and
+ * `halign` are accessors on every widget (`widget-layout.ts`), so the attribute, the bag and a
+ * projected `.blp` all translate the same way through them.
  */
 declare const ALIGNMENT_AXES: {
     readonly horizontalAlignment: "horizontal";