@gjsify/adwaita-nativescript 0.44.0 → 0.46.0

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

@@ -1,4 +1,5 @@
-import { GridLayout, Label, StackLayout, View } from '@nativescript/core';
+import type { View } from '@nativescript/core';
+import { GridLayout, Label, StackLayout } from '@nativescript/core';
 import { AdwIcon } from './adw-icon.js';
 export declare class AdwStatusPage extends GridLayout {
     /** The centered vertical stack. */
@@ -21,8 +22,8 @@ export declare class AdwStatusPage extends GridLayout {
      * hides it. Matches `Adw.StatusPage`'s themed icon. Mutually exclusive with
      * {@link iconText} — whichever was set last wins.
      */
-    get icon(): string;
-    set icon(value: string);
+    get iconName(): string;
+    set iconName(value: string);
     /**
      * A large glyph shown above the title (emoji / font glyph — the legacy
      * fallback for callers that have no symbolic SVG). Mutually exclusive with
@@ -46,4 +47,11 @@ export declare class AdwStatusPage extends GridLayout {
     setChild(view: View | null): void;
     /** The currently-installed child, or `null`. */
     get child(): View | null;
+    /**
+     * The one destination an XML child can have: the slot under the description,
+     * where `AdwStatusPage:child` goes. The name is ignored because
+     * `<AdwStatusPage.child>` and a bare child mean the same thing — the shape
+     * `AdwClamp` already has.
+     */
+    _addChildFromBuilder(_name: string, view: View): void;
 }

package/lib/types/widgets/adw-switch-row.d.ts

@@ -15,7 +15,7 @@ export declare class AdwSwitchRow extends AdwActionRow {
     constructor();
     /** Whether the switch is on. */
     get active(): boolean;
-    set active(value: boolean);
+    set active(value: boolean | string);
     /**
      * The row was tapped — invert the state, then emit `activated` like any
      * other action row (adw-switch-row.c:23-27 via the activatable widget).

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

@@ -55,7 +55,7 @@ export declare class AdwTabView extends GridLayout {
     get selectedIndex(): number;
     /** The selected page index. Setting it IGNORES a non-integer or out-of-range value. */
     get selected(): number;
-    set selected(value: number);
+    set selected(raw: number | string);
     isClosing(id: string): boolean;
     setSelectedPage(id: string | null): boolean;
     selectNthPage(n: number): boolean;
@@ -103,7 +103,7 @@ export declare class AdwTabView extends GridLayout {
      * visible before this lift stays visible unless asked otherwise.
      */
     get autohide(): boolean;
-    set autohide(value: boolean);
+    set autohide(raw: boolean | string);
     /** `Adw.TabView:default-icon` — what a PINNED page with no icon of its own shows. */
     get defaultIcon(): string | null;
     set defaultIcon(value: string | null);

package/lib/types/widgets/adw-toast-overlay.d.ts

@@ -1,4 +1,5 @@
-import { Button, GridLayout, Label, View } from '@nativescript/core';
+import type { View } from '@nativescript/core';
+import { Button, GridLayout, Label } from '@nativescript/core';
 import { AdwToast } from '@gjsify/adwaita-core';
 import type { AdwToastOptions } from '@gjsify/adwaita-core';
 export { AdwToast, AdwToastQueue, DEFAULT_TOAST_TIMEOUT } from '@gjsify/adwaita-core';

package/lib/types/widgets/adw-toggle-group.d.ts

@@ -29,8 +29,8 @@ export declare class AdwToggleGroup extends StackLayout {
     /** Mark only the selected segment `.active` (the raised white pill). */
     private _applySelection;
     /** The selected segment index. Swaps the active pill + emits `notify::selected`. */
-    get selected(): number;
-    set selected(value: number);
+    get active(): number;
+    set active(raw: number | string);
     /** The selected segment's label, or `''` when out of range. */
     get selectedValue(): string;
 }

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

@@ -1,4 +1,5 @@
-import { GridLayout, StackLayout, View } from '@nativescript/core';
+import type { View } from '@nativescript/core';
+import { GridLayout, StackLayout } from '@nativescript/core';
 import { type AdwToolbarStyle } from './chrome.js';
 export declare class AdwToolbarView extends GridLayout {
     /** The top-bar slot (row 0) — stack of header bars / toolbars. */
@@ -20,6 +21,16 @@ export declare class AdwToolbarView extends GridLayout {
     addBottomBar(view: View): void;
     /** Set (or replace) the main content view. Pass `null` to clear it. */
     setContent(view: View | null): void;
+    /**
+     * XML inflation — route a template's child through the slot API.
+     *
+     * `<AdwToolbarView.topBar>` / `.bottomBar` / `.content` arrive here as those
+     * names; anything else (a bare child) is the content, which is the one slot a
+     * toolbar view cannot do without. Without this the `GridLayout` default put
+     * every child in row 0: measured on Android, a top bar and the content were
+     * painted ON TOP OF EACH OTHER in the bar row while row 1 stayed empty.
+     */
+    _addChildFromBuilder(name: string, view: View): void;
     /** The currently-installed content view, or `null`. */
     get content(): View | null;
     /** The top-bar slot container. */
@@ -34,10 +45,10 @@ export declare class AdwToolbarView extends GridLayout {
     set bottomBarStyle(value: AdwToolbarStyle);
     /** `Adw.ToolbarView:extend-content-to-top-edge` — draw the top bar OVER the content. */
     get extendContentToTopEdge(): boolean;
-    set extendContentToTopEdge(value: boolean);
+    set extendContentToTopEdge(raw: boolean | string);
     /** `Adw.ToolbarView:extend-content-to-bottom-edge` — draw the bottom bar OVER the content. */
     get extendContentToBottomEdge(): boolean;
-    set extendContentToBottomEdge(value: boolean);
+    set extendContentToBottomEdge(raw: boolean | string);
     /**
      * Put each bar box in its own row, or — when the content extends under it —
      * in the CONTENT row pinned to that edge, which is how an NS `GridLayout`
@@ -54,7 +65,14 @@ export declare class AdwToolbarView extends GridLayout {
      */
     private _restackBars;
     /**
-     * Pay each edge's inset out of the slot that sits on it.
+     * Pay each edge's inset out of the slot that sits on it — the part of it this
+     * widget still owes.
+     *
+     * `insetsOwedBy` drops what the HOST already paid, which on Android is the bottom
+     * edge (the page's `LayoutBase`, because only its branch also folds in the keyboard)
+     * and never the top (`host-insets.android.ts` hands that edge back, because only the
+     * top-bar box paints it in the header colour). Without it the inset was applied
+     * twice: 142 px + 142 px above the header bar on emulator-5554.
      *
      * The assignment is decided by the pure sibling (`toolbarViewInsetPadding`); this
      * only spells it in NativeScript. Where that module says "the content pays", the

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

@@ -1,4 +1,5 @@
-import { GridLayout, View, type EventData } from '@nativescript/core';
+import type { View } from '@nativescript/core';
+import { GridLayout, type EventData } from '@nativescript/core';
 import { type AdwViewStackPage, type ViewStackNotifyPayload } from './view-stack-state.js';
 export type { AdwViewStackPage };
 /** Event name emitted when the visible child changes. Mirrors GObject `notify::visible-child`. */
@@ -40,7 +41,7 @@ export declare class AdwViewStack extends GridLayout {
     get pages(): readonly AdwViewStackPage[];
     /** The visible page index, `-1` when nothing is selected. Swaps the visible page + emits. */
     get visibleChildIndex(): number;
-    set visibleChildIndex(value: number);
+    set visibleChildIndex(raw: number | string);
     /** The visible page name (`Adw.ViewStack.visible-child-name`), `''` for none. */
     get visibleChildName(): string;
     set visibleChildName(name: string | null | undefined);

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

@@ -1,5 +1,5 @@
 import { GridLayout } from '@nativescript/core';
-import { AdwViewStack } from './adw-view-stack.js';
+import type { AdwViewStack } from './adw-view-stack.js';
 export declare class AdwViewSwitcherBar extends GridLayout {
     /** The horizontal (homogeneous) row of buttons. */
     private readonly _bar;
@@ -19,7 +19,7 @@ export declare class AdwViewSwitcherBar extends GridLayout {
      * where a header-bar `AdwViewSwitcher` takes over.
      */
     get reveal(): boolean;
-    set reveal(value: boolean);
+    set reveal(raw: boolean | string);
     /**
      * Whether the bar is actually shown. READ-ONLY: a one-page stack keeps it
      * collapsed however loudly the layout asks (adw-view-switcher-bar.c:125).

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

@@ -47,31 +47,31 @@ export declare class AdwWrapBox extends FlexboxLayout {
     private _applyOrder;
     /** Gap between items in a line, in {@link childSpacingUnit}. Defaults to 0, as in C. */
     get childSpacing(): number;
-    set childSpacing(value: number);
+    set childSpacing(value: number | string);
     /** The unit {@link childSpacing} is written in. Defaults to `px`, as in C. */
     get childSpacingUnit(): AdwLengthUnit;
     set childSpacingUnit(value: AdwLengthUnit);
     /** Gap between wrapped lines, in {@link lineSpacingUnit}. Defaults to 0, as in C. */
     get lineSpacing(): number;
-    set lineSpacing(value: number);
+    set lineSpacing(value: number | string);
     /** The unit {@link lineSpacing} is written in. Defaults to `px`, as in C. */
     get lineSpacingUnit(): AdwLengthUnit;
     set lineSpacingUnit(value: AdwLengthUnit);
     /** Where the children sit ALONG the line (main axis): 0 start, 0.5 middle, 1 end. */
     get align(): number;
-    set align(value: number);
+    set align(raw: number | string);
     /** Whether and how each line is stretched to fill the widget. */
     get justify(): AdwWrapBoxJustify;
     set justify(value: AdwWrapBoxJustify);
     /** Whether the FINAL line is justified too. Default false, as in C. */
     get justifyLastLine(): boolean;
-    set justifyLastLine(value: boolean);
+    set justifyLastLine(raw: boolean | string);
     /** Whether every line takes the same amount of space. */
     get lineHomogeneous(): boolean;
-    set lineHomogeneous(value: boolean);
+    set lineHomogeneous(raw: boolean | string);
     /** Whether lines wrap upwards (horizontal) / towards the start (vertical). */
     get wrapReverse(): boolean;
-    set wrapReverse(value: boolean);
+    set wrapReverse(raw: boolean | string);
     /** Whether an overflowing line squeezes its children or lets them spill. */
     get wrapPolicy(): AdwWrapPolicy;
     set wrapPolicy(value: AdwWrapPolicy);
@@ -88,7 +88,7 @@ export declare class AdwWrapBox extends FlexboxLayout {
      * maximum-size property to cap a line with.
      */
     get naturalLineLength(): number;
-    set naturalLineLength(value: number);
+    set naturalLineLength(raw: number | string);
     /** The unit {@link naturalLineLength} is written in. Defaults to `px`, as in C. */
     get naturalLineLengthUnit(): AdwLengthUnit;
     set naturalLineLengthUnit(value: AdwLengthUnit);

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

@@ -0,0 +1,16 @@
+/**
+ * The slot an XML child asks for, or `fallback` when it asks for nothing this
+ * widget knows.
+ *
+ * `slots` are the widget's own property names, because that is what NativeScript's
+ * complex-property syntax spells: `<AdwToolbarView.topBar>` reaches
+ * `_addChildFromBuilder('topBar', …)`. A bare `<AdwHeaderBar>` child arrives under
+ * its ELEMENT name instead, which is never a slot name and so takes the fallback —
+ * the same shape as GtkBuildable's untyped `<child>`.
+ *
+ * A dotted `name` is reduced to its last segment first. NativeScript already does
+ * that before it calls us, but a caller that does not is the difference between
+ * "no slot" and "the wrong slot", and this returns the answer to a question about
+ * a widget's own tree.
+ */
+export declare function resolveBuilderSlot<Slot extends string, Fallback extends string>(name: unknown, slots: readonly Slot[], fallback: Fallback): Slot | Fallback;

package/lib/types/widgets/entry-row-view.d.ts

@@ -39,7 +39,7 @@ export interface PasswordEntryRowViews {
     };
     /** The peek toggle, whose `icon` takes an Adwaita symbolic SVG string. */
     peekButton: {
-        icon: string;
+        iconName: string;
     };
 }
 /** Base class list of an entry row, before the state classes. */

package/lib/types/widgets/{adw-button.d.ts → gtk-button.d.ts}

@@ -6,14 +6,19 @@ import { Button } from '@nativescript/core';
  * The class list is `@gjsify/adwaita-core`'s, not a local table: this widget's own
  * one was MISSING `circular`, which the browser element had, and neither file could
  * see the other. `circular` is now here because the shared table says it exists.
+ *
+ * STILL `Adw…`, on a class that is not: the variants ARE libadwaita style classes
+ * (`.suggested-action`, `.pill`, `_buttons.scss`), so the prefix names what they are.
+ * ADR 0034 clause 1 renames WIDGETS after the library owning their GType; a style-class
+ * vocabulary is not a widget, and renaming it would have moved a true name to a false one.
  */
 export type AdwButtonVariant = 'default' | AdwButtonStyleClass;
-export declare class AdwButton extends Button {
+export declare class GtkButton extends Button {
     private _variant;
     constructor();
     /**
      * The Adwaita style variant. Setting it swaps the corresponding CSS class
-     * (one of `AdwButton.variantClasses`) onto the button,
+     * (one of `GtkButton.variantClasses`) onto the button,
      * preserving the base `adw-button` class. Note that `pill` is the rounded
      * SHAPE and combines with no other variant here (set the shape OR the accent
      * intent — matching how this CSS subset expresses them as flat classes).

package/lib/types/widgets/{adw-drop-down.d.ts → gtk-drop-down.d.ts}

@@ -1,7 +1,7 @@
 import { Label, StackLayout, type EventData } from '@nativescript/core';
 import type { AdwComboOption } from '@gjsify/adwaita-core';
 import { AdwIcon } from './adw-icon.js';
-/** Event name emitted when {@link AdwDropDown.selected} changes through a pick. Mirrors GObject `notify::selected`. */
+/** Event name emitted when {@link GtkDropDown.selected} changes through a pick. Mirrors GObject `notify::selected`. */
 export declare const NOTIFY_SELECTED = "notify::selected";
 /** Payload of the `notify::selected` event. */
 export interface NotifyDropDownSelectedEventData extends EventData {
@@ -12,7 +12,7 @@ export interface NotifyDropDownSelectedEventData extends EventData {
     /** The newly-selected option's `label` — what the button now shows. */
     label: string;
 }
-export declare class AdwDropDown extends StackLayout {
+export declare class GtkDropDown extends StackLayout {
     /** The button label — the selected option. */
     protected readonly _label: Label;
     /** The down-chevron — a real Adwaita `pan-down-symbolic` icon. */
@@ -29,7 +29,7 @@ export declare class AdwDropDown extends StackLayout {
     set options(value: AdwComboOption[]);
     /** The selected option index (`Gtk.DropDown:selected`). */
     get selected(): number;
-    set selected(value: number);
+    set selected(raw: number | string);
     /** The selected option's `value`, or `''` when out of range. */
     get selectedValue(): string;
     set selectedValue(value: string);
@@ -38,7 +38,7 @@ export declare class AdwDropDown extends StackLayout {
     /**
      * Optional title shown atop the chooser sheet. A SUBSTITUTION affordance:
      * GTK's popover has no title, but a bare native sheet gives no clue what is
-     * being chosen — the same reason `AdwMenuButton` carries `menuTitle`.
+     * being chosen — the same reason `GtkMenuButton` carries `menuTitle`.
      */
     get chooserTitle(): string;
     set chooserTitle(value: string);

package/lib/types/widgets/{adw-entry.d.ts → gtk-entry.d.ts}

@@ -1,5 +1,5 @@
 import { GridLayout, TextField, type EventData } from '@nativescript/core';
-/** Event name emitted when {@link AdwEntry.text} changes. Mirrors GObject `notify::text`. */
+/** Event name emitted when {@link GtkEntry.text} changes. Mirrors GObject `notify::text`. */
 export declare const NOTIFY_TEXT = "notify::text";
 /** Event name emitted when the return key is pressed — `Gtk.Entry::activate`. */
 export declare const ACTIVATE = "activate";
@@ -10,7 +10,7 @@ export interface NotifyEntryTextEventData extends EventData {
     /** The new number of CHARACTERS (not UTF-16 units). */
     textLength: number;
 }
-export declare class AdwEntry extends GridLayout {
+export declare class GtkEntry extends GridLayout {
     /** The real input. Chrome-less: the box around it paints the Adwaita surface. */
     protected readonly _field: TextField;
     private _text;
@@ -31,13 +31,13 @@ export declare class AdwEntry extends GridLayout {
     get textLength(): number;
     /** Maximum number of characters, `0` = unlimited. */
     get maxLength(): number;
-    set maxLength(value: number);
+    set maxLength(raw: number | string);
     /** Placeholder shown while the entry is empty (`Gtk.Entry:placeholder-text`). */
-    get placeholder(): string;
-    set placeholder(value: string);
+    get placeholderText(): string;
+    set placeholderText(value: string);
     /** Whether the entry accepts edits (`GtkEditable:editable`). */
     get editable(): boolean;
-    set editable(value: boolean);
+    set editable(raw: boolean | string);
     /** The inner `TextField` — for focus, selection and host-specific keyboard options. */
     get field(): TextField;
 }

package/lib/types/widgets/{adw-menu-button.d.ts → gtk-menu-button.d.ts}

@@ -4,7 +4,7 @@ import { AdwImageButton } from './adw-image-button.js';
 /** Event name emitted when a menu item is chosen. */
 export declare const MENU_ITEM_ACTIVATED = "menuItemActivated";
 /**
- * One entry in an {@link AdwMenuButton}'s menu — `@gjsify/adwaita-core`'s
+ * One entry in an {@link GtkMenuButton}'s menu — `@gjsify/adwaita-core`'s
  * {@link AdwMenuEntry}, under the name this widget has always used.
  *
  * It used to be a THIRD declaration of the same shape (the browser element had a
@@ -19,10 +19,10 @@ export interface MenuItemActivatedEventData extends EventData {
     id: string;
     /** The chosen item's label. */
     label: string;
-    /** The chosen item's index in {@link AdwMenuButton.menuItems}. */
+    /** The chosen item's index in {@link GtkMenuButton.menuItems}. */
     index: number;
 }
-export declare class AdwMenuButton extends AdwImageButton {
+export declare class GtkMenuButton extends AdwImageButton {
     private _items;
     private _menuTitle;
     constructor();

package/lib/types/widgets/host-insets.android.d.ts

@@ -0,0 +1,4 @@
+import type { View } from '@nativescript/core';
+import { type HostPaidEdges, type WindowInsets } from './window-insets.js';
+/** Settle which window-inset edges `view` still owes. See {@link resolveHostInsets}. */
+export declare function resolveHostInsets(view: View, insets: WindowInsets): HostPaidEdges;

package/lib/types/widgets/host-insets.d.ts

@@ -0,0 +1,13 @@
+import type { View } from '@nativescript/core';
+import { type HostPaidEdges, type WindowInsets } from './window-insets.js';
+/**
+ * Settle which window-inset edges `view` still owes, adjusting the host where the
+ * widget paints an edge better than the host can.
+ *
+ * Takes the READING as well as the view, and is called on every inset application
+ * rather than once at `loaded`, because an Android variant that hands an edge back to
+ * the host must not do so before it holds a reading to pay that edge with. Idempotent:
+ * a page with two toolbar views resolves twice, and a view re-attached to another page
+ * resolves again.
+ */
+export declare function resolveHostInsets(_view: View, _insets: WindowInsets): HostPaidEdges;

package/lib/types/widgets/host-insets.ios.d.ts

@@ -0,0 +1,4 @@
+import type { View } from '@nativescript/core';
+import { type HostPaidEdges, type WindowInsets } from './window-insets.js';
+/** Settle which window-inset edges `view` still owes. See {@link resolveHostInsets}. */
+export declare function resolveHostInsets(_view: View, _insets: WindowInsets): HostPaidEdges;

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

@@ -8,20 +8,74 @@ export interface SymbolicIconOptions {
     /** Fill colour as a hex string (`#RRGGBB` / `#AARRGGBB`). Default = light fg. */
     color?: string;
 }
-/** One fillable path of a symbolic icon: its path data + its own fill opacity. */
+/**
+ * A 2D affine transform in SVG's own `matrix(a b c d e f)` order.
+ *
+ * `[a c e; b d f; 0 0 1]` — the same six numbers `android.graphics.Matrix.setValues`
+ * and `CGAffineTransformMake` take, so neither renderer has to convert anything.
+ */
+export type IconTransform = readonly [number, number, number, number, number, number];
+/** The identity — nothing to apply. */
+export declare const IDENTITY_TRANSFORM: IconTransform;
+/** One fillable path of a symbolic icon. */
 export interface IconPath {
     /** SVG `d` path data (the `androidx` `PathParser` `pathData` grammar). */
     d: string;
     /** Per-path fill opacity in [0, 1] — Adwaita dims accent sub-shapes (e.g. the
      *  filled panel of `sidebar-show`); defaults to 1 when the path has none. */
     opacity: number;
+    /**
+     * This path's own `transform`, composed under every enclosing `<g transform=…>`.
+     *
+     * {@link IDENTITY_TRANSFORM} for the icons that need none. NOT optional: an
+     * optional field is one a renderer forgets to read, and forgetting it is exactly
+     * the defect this exists to fix.
+     */
+    transform: IconTransform;
+    /**
+     * `fill-rule` — `evenodd`, or `nonzero` (SVG's initial value) when unset.
+     *
+     * Neither renderer set one, so both drew the platform default and every icon
+     * declaring `evenodd` filled a hole it should have carved.
+     */
+    fillRule: 'nonzero' | 'evenodd';
+    /**
+     * The path's own `fill`, when it names a colour instead of inheriting one.
+     *
+     * `null` means "use the caller's colour" — the symbolic case, and the common one.
+     * A shipped icon that hardcodes `#ed333b` for a critical battery is NOT symbolic,
+     * and drawing it in one colour is what turned a red battery grey. The icon
+     * generator rewrites the four neutral greys to `currentColor`, so anything still
+     * literal here was meant to be literal.
+     */
+    fill: string | null;
 }
 /**
- * Extract every fillable `<path>` of a symbolic SVG as `{ d, opacity }`. Each path
- * must be drawn SEPARATELY (not concatenated): Adwaita icons frequently pair a
- * solid outline with a dimmed (`fill-opacity`) inner shape, and a single path's
- * subpaths carve holes via the non-zero winding rule — flattening all paths into
- * one fill destroys both. Returns `[]` when the SVG carries no path data.
+ * Parse an SVG `transform` attribute into one affine matrix.
+ *
+ * The whole grammar, not the two functions the shipped icons happen to use
+ * (`translate` 33×, `matrix` 9×): SVG's transform list is exactly matrix / translate /
+ * scale / rotate / skewX / skewY, all affine, and supporting five of six would sit
+ * silently wrong the first time an icon set grows the sixth. Returns `null` for a
+ * string it cannot read, which a caller must treat as a refusal rather than as
+ * identity — quietly dropping a transform is the failure being repaired here.
+ */
+export declare function parseIconTransform(value: string): IconTransform | null;
+/**
+ * Extract every fillable `<path>` of a symbolic SVG.
+ *
+ * Each path must be drawn SEPARATELY (not concatenated): Adwaita icons frequently pair
+ * a solid outline with a dimmed (`fill-opacity`) inner shape, and a single path's
+ * subpaths carve holes via the winding rule — flattening all paths into one fill
+ * destroys both. Returns `[]` when the SVG carries no path data.
+ *
+ * WHY THIS WALKS `<g>` AND NOT JUST `<path>`. It used to be one regex over `<path>`
+ * tags, and the geometry of a grouped icon is authored in the group's coordinate space:
+ * icons whose paths live at x≈684, y≈180 under a `translate(-680,-180)` were extracted
+ * with the translate dropped, scaled by `size/16`, and drawn onto a 16×16 bitmap that
+ * their geometry misses entirely. Measured before this change: 12 shipped icons —
+ * eleven `battery-level-*-charging` and one parental-controls glyph — rendered
+ * COMPLETELY EMPTY on NativeScript, with no diagnostic anywhere.
  */
 export declare function extractIconPaths(svg: string): IconPath[];
 /**
@@ -48,9 +102,20 @@ export interface IconColorComponents {
  * two backends must read the same string the same way.
  *
  * Returns opaque black for anything unparsable, so a typo in a caller's colour
- * yields a visible icon rather than an invisible one.
+ * yields a visible icon rather than an invisible one. Where the caller has a better
+ * fallback than black — a path's own `fill`, which should fall back to the icon
+ * colour rather than to black — use {@link parseHexColorOrNull}.
  */
 export declare function parseHexColor(hex: string): IconColorComponents;
+/**
+ * {@link parseHexColor} without the black fallback: `null` says "not a colour I read".
+ *
+ * Two callers want different answers to the same failure. A caller's own
+ * `options.color` has no better candidate than black — an invisible icon is worse
+ * than a wrong-coloured one. A path's `fill` does: the icon colour the caller passed
+ * in. Folding both into one black default made the second silently draw black.
+ */
+export declare function parseHexColorOrNull(hex: string): IconColorComponents | null;
 /**
  * Space-separate the two single-digit ARC FLAGS (large-arc, sweep) in every
  * elliptical-arc command (`A`/`a`) of an SVG path-data string.

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

@@ -6,23 +6,23 @@ export type { NotifyActiveEventData } from './adw-switch-row.js';
 export { AdwEntryRow, NOTIFY_TEXT } from './adw-entry-row.js';
 export type { NotifyTextEventData } from './adw-entry-row.js';
 export { AdwPasswordEntryRow } from './adw-password-entry-row.js';
-export { AdwEntry, ACTIVATE as ENTRY_ACTIVATE, NOTIFY_TEXT as NOTIFY_ENTRY_TEXT } from './adw-entry.js';
-export type { NotifyEntryTextEventData } from './adw-entry.js';
+export { GtkEntry, ACTIVATE as ENTRY_ACTIVATE, NOTIFY_TEXT as NOTIFY_ENTRY_TEXT } from './gtk-entry.js';
+export type { NotifyEntryTextEventData } from './gtk-entry.js';
 export { AdwComboRow, ComboState, NOTIFY_SELECTED } from './adw-combo-row.js';
 export type { AdwComboOption, ComboStateChange, ComboStateListener, NotifySelectedEventData } from './adw-combo-row.js';
-export { AdwDropDown, NOTIFY_SELECTED as NOTIFY_DROP_DOWN_SELECTED } from './adw-drop-down.js';
-export type { NotifyDropDownSelectedEventData } from './adw-drop-down.js';
+export { GtkDropDown, NOTIFY_SELECTED as NOTIFY_DROP_DOWN_SELECTED } from './gtk-drop-down.js';
+export type { NotifyDropDownSelectedEventData } from './gtk-drop-down.js';
 export { AdwSpinRow, NOTIFY_VALUE, SpinState } from './adw-spin-row.js';
 export type { NotifyValueEventData, SpinStateChange, SpinStateListener } from './adw-spin-row.js';
 export { AdwSliderRow, NOTIFY_SLIDER_VALUE } from './adw-slider-row.js';
 export type { NotifySliderValueEventData } from './adw-slider-row.js';
 export { AdwExpanderRow, ExpanderState, NOTIFY_EXPANDED } from './adw-expander-row.js';
 export type { ExpanderStateListener, NotifyExpandedEventData } from './adw-expander-row.js';
-export { AdwButton } from './adw-button.js';
-export type { AdwButtonVariant } from './adw-button.js';
+export { GtkButton } from './gtk-button.js';
+export type { AdwButtonVariant } from './gtk-button.js';
 export { AdwImageButton, DEFAULT_ICON_BUTTON_ICON_SIZE } from './adw-image-button.js';
-export { AdwMenuButton, MENU_ITEM_ACTIVATED } from './adw-menu-button.js';
-export type { AdwMenuItem, MenuItemActivatedEventData } from './adw-menu-button.js';
+export { GtkMenuButton, MENU_ITEM_ACTIVATED } from './gtk-menu-button.js';
+export type { AdwMenuItem, MenuItemActivatedEventData } from './gtk-menu-button.js';
 export { AdwIcon, DEFAULT_ADW_ICON_SIZE } from './adw-icon.js';
 export { AdwBanner, BUTTON_CLICKED } from './adw-banner.js';
 export { AdwAvatar, DEFAULT_AVATAR_SIZE, avatarInitials } from './adw-avatar.js';
@@ -90,12 +90,19 @@ export type { AdwColorScheme } from './color-scheme.js';
 export { AdwBreakpoint, addBreakpoints, evaluateBreakpointCondition, parseBreakpointCondition } from './breakpoint.js';
 export type { AdwBreakpointHandlers, BreakpointBound, BreakpointConditionGroup, BreakpointConditionLeaf, BreakpointConditionNode, BreakpointDimension, BreakpointSize, } from './breakpoint.js';
 /**
- * Register all Adwaita widgets as NativeScript XML elements (idempotent).
+ * Register all Adwaita widgets as UNPREFIXED NativeScript XML elements, where a
+ * framework integration provides the `registerElement` global (idempotent).
  *
- * After calling this once at app bootstrap, markup like
- * `<AdwSwitchRow title="Dark mode" />` resolves to the corresponding class.
- * No-op (returns silently) when the `registerElement` runtime global is absent
- * — i.e. off NativeScript, or when the bundler context has not injected it yet —
- * so the call is safe to make unconditionally.
+ * That global is NOT part of NativeScript itself: `@nativescript/core` 9.1 does
+ * not contain the identifier at all, and it is `undefined` in a plain app built
+ * with `@nativescript/vite` — measured on an Android emulator, 2026-08-28, where
+ * this function therefore returned silently and `<AdwSwitchRow>` resolved to
+ * nothing. It comes from `@nativescript/angular` / `nativescript-vue`, which is
+ * where this call earns its keep; a plain XML app uses the `xmlns` barrel above
+ * instead and needs no registration at all.
+ *
+ * The no-op is the safe branch of that split, not a fallback: it is why the call
+ * can be made unconditionally, and why it must never be the only thing an app
+ * does before writing `<AdwSwitchRow>` in markup.
  */
 export declare function registerAdwaitaElements(): void;

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

@@ -28,11 +28,11 @@ export declare function resolveMenuChoice(sheetActions: readonly string[], chose
 /** The arrow SVG for a direction; the split button's `none` is the down caret, not a hamburger. */
 export declare function splitButtonArrowSvg(direction: SplitButtonDirection): string;
 /**
- * Apply `AdwSplitButton.actionIcon = svg` to the content machine. The SVG string IS
+ * Apply `AdwSplitButton.iconName = svg` to the content machine. The SVG string IS
  * the icon identity on NativeScript, so it goes where GTK puts the icon NAME.
  *
  * C offers no "unset the icon", only the side effect of filling another slot, so an
  * empty SVG clears the content and lets the label half take over again — what a
- * caller assigning `actionIcon` from a nullable lookup expects.
+ * caller assigning `iconName` from a nullable lookup expects.
  */
 export declare function setActionIcon(state: SplitButtonState, svg: string | null | undefined): void;

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

@@ -78,6 +78,15 @@ export declare abstract class AdwSplitViewBase<TState extends NsSplitViewState =
     setSidebar(view: View | null): void;
     /** Set (or replace) the content pane. */
     setContent(view: View | null): void;
+    /**
+     * An XML child asks for `sidebar` or `content`, and a bare one is CONTENT.
+     *
+     * The fallback follows the widget's own collapsed behaviour: a lone child stays
+     * visible whatever `show-content` says, so the pane a template gives without
+     * naming one is the one a reader will see. Without this override, `LayoutBase`'s
+     * default drops both panes into column 0 of the grid, stacked.
+     */
+    _addChildFromBuilder(name: string, view: View): void;
     /** Show the sidebar (relevant in collapsed mode). */
     showSidebarPane(): void;
     /** Hide the sidebar (relevant in collapsed mode). */
@@ -90,26 +99,26 @@ export declare abstract class AdwSplitViewBase<TState extends NsSplitViewState =
      * `notify::show-sidebar` first — the state machine owns that, not this setter.
      */
     get collapsed(): boolean;
-    set collapsed(value: boolean);
+    set collapsed(raw: boolean | string);
     /** Whether the sidebar is shown. Toggling emits `notify::show-sidebar`. */
     get showSidebar(): boolean;
-    set showSidebar(value: boolean);
+    set showSidebar(raw: boolean | string);
     /**
      * The sidebar pane width in DIPs, DERIVED from the container size unless a caller
      * assigned one — `Adw.OverlaySplitView` stores no width; see
      * `split-view-width.ts` for the rule.
      */
     get sidebarWidth(): number;
-    set sidebarWidth(value: number);
+    set sidebarWidth(raw: number | string);
     /** Lower bound in DIPs (`Adw.OverlaySplitView:min-sidebar-width`, default 180). */
     get minSidebarWidth(): number;
-    set minSidebarWidth(value: number);
+    set minSidebarWidth(raw: number | string);
     /** Upper bound in DIPs (`Adw.OverlaySplitView:max-sidebar-width`, default 280). */
     get maxSidebarWidth(): number;
-    set maxSidebarWidth(value: number);
+    set maxSidebarWidth(raw: number | string);
     /** Share of the container the sidebar asks for (default 0.25). */
     get sidebarWidthFraction(): number;
-    set sidebarWidthFraction(value: number);
+    set sidebarWidthFraction(raw: number | string);
     /**
      * Re-measure the container and re-size the sidebar.
      *

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

@@ -74,7 +74,7 @@ export declare abstract class AdwViewSwitcherBase extends GridLayout {
      * NO-OPS — refused, never clamped, as `adw_view_stack_pages_select_item` does.
      */
     get selected(): number;
-    set selected(value: number);
+    set selected(raw: number | string);
     /** Name of the selected page, `''` when nothing is selected. */
     get selectedName(): string;
     /**