@gjsify/adwaita-nativescript 0.51.1 → 0.52.0

package/lib/types/testing/ns-core.d.mts

@@ -0,0 +1,340 @@
+/** Payload shape for `Observable.notify` and every event listener. */
+export interface EventData {
+    eventName: string;
+    object: Observable;
+    [key: string]: unknown;
+}
+type Listener = (data: EventData) => void;
+export declare class Observable {
+    addEventListener(eventName: string, callback: Listener): void;
+    removeEventListener(eventName: string, callback?: Listener): void;
+    notify<T extends EventData>(data: T): void;
+    notifyPropertyChange(name: string, value: unknown, oldValue?: unknown): void;
+    _emit(eventName: string): void;
+    set(name: string, value: unknown): void;
+    get(name: string): unknown;
+}
+/** An `(x, y)` pair — a translate/scale animation target. */
+export interface Pair {
+    x: number;
+    y: number;
+}
+/** An async operation that can be cancelled mid-flight. */
+export interface Cancelable {
+    cancel(): void;
+}
+/** A running animation: a `Promise` that is also {@link Cancelable}. */
+export type AnimationPromise = Promise<void> & Cancelable;
+/** The slice of NativeScript's animation definition the Adwaita widgets use. */
+export interface AnimationDefinition {
+    target?: View;
+    opacity?: number;
+    backgroundColor?: string;
+    translate?: Pair;
+    scale?: Pair;
+    width?: number | string;
+    height?: number | string;
+    rotate?: number;
+    duration?: number;
+    delay?: number;
+    iterations?: number;
+    curve?: string;
+}
+/** The payload of the `'touch'` gesture. */
+export interface TouchGestureEventData extends EventData {
+    action: 'down' | 'up' | 'move' | 'cancel';
+    getX(): number;
+    getY(): number;
+}
+export declare class View extends Observable {
+    /**
+     * UNSET, NOT EMPTY — a view nobody has written a class onto reads `undefined`.
+     *
+     * This field held `''` and the setter coerced `value ?? ''`, which made the suite
+     * STRUCTURALLY BLIND to the whole class of defect that reads a `className` as if it
+     * were always a string: on a device `Adw.Clamp` with a classless child dies at
+     * startup with `TypeError: … reading 'split'`, and every test here passed because the
+     * double answered `''` to the one question a device answers `undefined`.
+     *
+     * The real semantics, measured against `@nativescript/core` 9.1.2 by registering
+     * `classNameProperty`'s own options on a bare class: the property carries no
+     * `defaultValue`, its getter is `key in this ? this[key] : defaultValue`, so it reads
+     * `undefined` until written; `undefined` is not `unsetValue`, so writing it stores
+     * `undefined` rather than resetting; and `valueChanged` feeds `cssClasses` only from
+     * `typeof newValue === 'string' && newValue !== ''`.
+     *
+     * A DOUBLE THAT SMOOTHS AN EDGE OFF THE PLATFORM CANNOT REPORT THAT EDGE. It is the
+     * only reason this file may differ from a convenient JS object at all.
+     */
+    private _className;
+    /**
+     * The live class set the CSS engine matches against, rebuilt from `className` on every
+     * write. Reproduced because it is a name a port widget must NOT take: ADR 0049 first
+     * spelled the style-class list `cssClasses`, and the shadowing accessor left the Set
+     * missing so the first `className` write died inside a constructor.
+     */
+    readonly cssClasses: Set<string>;
+    width: number | string;
+    height: number | string;
+    horizontalAlignment: string;
+    verticalAlignment: string;
+    /**
+     * UNSET like {@link View.className}, and for the same measured reason: the `Property`
+     * behind it carries no `defaultValue`, so NativeScript answers `undefined` until
+     * something writes one. Every member of this double that models such a property is
+     * declared without an initialiser, and
+     * `scripts/check-nativescript-ns-defaults.mjs` holds the list against
+     * `status/nativescript-undefined-defaults.json`.
+     */
+    backgroundColor: string | undefined;
+    /** Unset like {@link View.className}: `idProperty` carries no `defaultValue` either. */
+    id: string | undefined;
+    opacity: number;
+    paddingTop: number;
+    paddingBottom: number;
+    paddingLeft: number;
+    paddingRight: number;
+    marginTop: number;
+    marginBottom: number;
+    marginLeft: number;
+    marginRight: number;
+    /** `'visible' | 'hidden' | 'collapse'` — NativeScript's own default is `'visible'`. */
+    visibility: string;
+    isUserInteractionEnabled: boolean;
+    translateX: number;
+    translateY: number;
+    /** Never loaded here: nothing mounts a view into a page without a platform. */
+    readonly isLoaded: boolean;
+    androidOverflowEdge: string;
+    accessibilityRole: string | undefined;
+    accessibilityState: string | undefined;
+    accessibilityLabel: string | undefined;
+    accessibilityHint: string | undefined;
+    readonly style: {
+        direction?: 'ltr' | 'rtl' | null;
+    };
+    /** The pseudo-classes `attachRowPressFeedback` toggles — observable, not styled. */
+    readonly pseudoClasses: Set<string>;
+    get className(): string | undefined;
+    set className(value: string | undefined);
+    get parent(): View | null;
+    /** No page exists without a platform, and nothing in the corpus asks for one. */
+    get page(): View | null;
+    /**
+     * Resolves immediately and animates nothing.
+     *
+     * There is no clock and no compositor here, so the honest answer is that the END STATE
+     * is reached at once — which is what the widgets that animate a reveal already fall back
+     * to when the CSS subset cannot express one.
+     */
+    animate(_options: AnimationDefinition): AnimationPromise;
+    /** No layout pass ran, so there is no size to report. */
+    getActualSize(): {
+        width: number;
+        height: number;
+    };
+    /** Upstream's `eachChildView`: a leaf has none. Return `false` from the callback to stop. */
+    eachChildView(_callback: (child: View) => boolean): void;
+    /**
+     * `getViewById` as `ui/core/view-base/index.ts:134` walks it: this view first, then its
+     * descendants depth first through `eachChildView`, the first match wins.
+     */
+    getViewById<T extends View = View>(id: string): T | undefined;
+    addPseudoClass(name: string): void;
+    deletePseudoClass(name: string): void;
+}
+/** One screen. Declared because the ambient slice declares it; nothing here builds one. */
+export declare class Page extends View {
+}
+export declare class LayoutBase extends View {
+    #private;
+    addChild(view: View): void;
+    insertChild(view: View, atIndex: number): void;
+    /** `_removeView` refuses a view that is not this parent's; a silent no-op would hide it. */
+    removeChild(view: View): void;
+    removeChildren(): void;
+    getChildAt(index: number): View;
+    getChildrenCount(): number;
+    eachChildView(callback: (child: View) => boolean): void;
+    /**
+     * THE INHERITED XML-CHILD DOOR, and the reason this class is worth doubling at all.
+     *
+     * `LayoutBaseCommon._addChildFromBuilder(name, view)` IGNORES `name` and calls
+     * `addChild` — which drops a template's child into the composed widget's first cell
+     * instead of into the slot it asked for. Every placement rule in this package is an
+     * override of exactly this method (`widgets/builder-slots.ts`), so a double that
+     * quietly did something smarter here would test the driver's manners rather than the
+     * port's.
+     *
+     * ONE DELIBERATE DIVERGENCE, so it is not read later as an oversight. Upstream guards
+     * `if (value instanceof View)` and DROPS anything else, silently; here the non-view
+     * reaches `#adopt` and throws. Stricter than the platform on purpose: a child door
+     * handed a non-view is a port defect either way, and this surface's whole problem is
+     * that its two doors fail without saying anything.
+     */
+    _addChildFromBuilder(_name: string, view: View): void;
+}
+export declare class StackLayout extends LayoutBase {
+    orientation: 'horizontal' | 'vertical';
+}
+export type GridUnitType = 'auto' | 'star' | 'pixel';
+export declare class ItemSpec {
+    readonly value: number;
+    readonly gridUnitType: GridUnitType;
+    constructor(value: number, gridUnitType: GridUnitType);
+}
+export declare class GridLayout extends LayoutBase {
+    protected _rows: ItemSpec[];
+    protected _columns: ItemSpec[];
+    addColumn(itemSpec: ItemSpec): void;
+    addRow(itemSpec: ItemSpec): void;
+    removeRow(itemSpec: ItemSpec): void;
+    removeColumns(): void;
+    removeRows(): void;
+    /** Where a child was placed — the read-back the `set*` statics have on a device. */
+    static placementOf(view: View): {
+        row: number;
+        column: number;
+        rowSpan: number;
+        columnSpan: number;
+    };
+    static setColumn(view: View, value: number): void;
+    static setRow(view: View, value: number): void;
+    static setColumnSpan(view: View, value: number): void;
+    static setRowSpan(view: View, value: number): void;
+}
+export declare class Label extends View {
+    text: string;
+    textWrap: boolean;
+    textAlignment: string;
+    textOverflow: string;
+    /**
+     * Unset like {@link View.className}, and for the same measured reason: `maxLinesProperty`
+     * (`ui/text-base/text-base-common.ts`) carries no `defaultValue`.
+     * `scripts/check-nativescript-ns-defaults.mjs` holds this against
+     * `status/nativescript-undefined-defaults.json`.
+     */
+    maxLines: number | undefined;
+}
+export declare class Switch extends View {
+    private _checked;
+    get checked(): boolean;
+    /**
+     * A write fires `checkedChange`, as the platform's own property does for a
+     * PROGRAMMATIC write and not only for a drag — which is the re-entry `AdwSwitchRow`'s
+     * single funnel exists to stop. A double that only fired on a gesture would leave that
+     * funnel untested and the row green by absence.
+     */
+    set checked(value: boolean);
+}
+export declare class Slider extends View {
+    value: number;
+    minValue: number;
+    maxValue: number;
+}
+export declare class TextField extends View {
+    private _text;
+    hint: string;
+    secure: boolean;
+    editable: boolean;
+    get text(): string;
+    /** `textChange` for a programmatic write too — same reasoning as `Switch.checked`. */
+    set text(value: string);
+}
+export declare class Button extends View {
+    text: string;
+}
+export declare class ScrollView extends View {
+    orientation: 'horizontal' | 'vertical';
+    content: View;
+    readonly horizontalOffset: number;
+    readonly verticalOffset: number;
+    scrollToHorizontalOffset(_value: number, _animated: boolean): void;
+    scrollToVerticalOffset(_value: number, _animated: boolean): void;
+    eachChildView(callback: (child: View) => boolean): void;
+}
+export declare class ContentView extends LayoutBase {
+    content: View;
+}
+export declare class WrapLayout extends LayoutBase {
+    orientation: 'horizontal' | 'vertical';
+    itemWidth: number;
+    itemHeight: number;
+}
+export declare class FlexboxLayout extends LayoutBase {
+    flexDirection: 'row' | 'row-reverse' | 'column' | 'column-reverse';
+    flexWrap: 'nowrap' | 'wrap' | 'wrap-reverse';
+    justifyContent: 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around';
+    alignItems: 'flex-start' | 'flex-end' | 'center' | 'baseline' | 'stretch';
+    alignContent: 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'stretch';
+    static setFlexGrow(view: View, grow: number): void;
+    static setFlexShrink(view: View, shrink: number): void;
+}
+export declare class AbsoluteLayout extends LayoutBase {
+    private static readonly _left;
+    private static readonly _top;
+    static setLeft(view: View, value: number): void;
+    static setTop(view: View, value: number): void;
+    static getLeft(view: View): number;
+    static getTop(view: View): number;
+}
+export declare class ActivityIndicator extends View {
+    busy: boolean;
+}
+/**
+ * A decoded native image.
+ *
+ * Constructible and inert: the only producer on this surface is `renderSymbolicIcon`, whose
+ * platform-neutral module already returns `null` off a device, so nothing here ever holds a
+ * bitmap. Its dimensions are zero for the same reason `getActualSize` reports zero.
+ */
+export declare class ImageSource {
+    readonly nativeSource?: unknown;
+    readonly width: number;
+    readonly height: number;
+    constructor(nativeSource?: unknown);
+}
+export declare class Image extends View {
+    src: string | ImageSource | undefined;
+    imageSource: ImageSource | undefined;
+    stretch: string;
+}
+export declare class SegmentedBarItem extends Observable {
+    title: string;
+}
+export declare class SegmentedBar extends View {
+    items: SegmentedBarItem[] | undefined;
+    selectedIndex: number;
+}
+export declare enum GestureTypes {
+    tap = 1
+}
+export interface ConfirmOptions {
+    title?: string;
+    message?: string;
+    okButtonText?: string;
+    cancelButtonText?: string;
+    neutralButtonText?: string;
+    cancelable?: boolean;
+}
+export interface ActionOptions {
+    title?: string;
+    message?: string;
+    cancelButtonText?: string;
+    actions: string[];
+    cancelable?: boolean;
+}
+export declare function confirm(_options: ConfirmOptions): Promise<boolean | undefined>;
+export declare function action(_options: ActionOptions): Promise<string>;
+export declare namespace Application {
+    function addCss(cssText: string, _attributeScoped?: boolean): void;
+    /** What the accent layer appended — the read-back a device gives through the engine. */
+    function appliedCss(): readonly string[];
+    function on(event: string, callback: (args: unknown) => void): void;
+    function off(event: string, callback: (args: unknown) => void): void;
+    /** Absent, as on every platform that is not Android — and this is not Android. */
+    const android: undefined;
+    /** Absent, as on every platform that is not iOS — and this is not iOS. */
+    const ios: undefined;
+}
+export {};

package/lib/types/value-lists.spec.d.ts

@@ -0,0 +1 @@
+export declare const AdwValueListsNsTest: () => Promise<void>;

package/lib/types/values/sidebar.d.ts

@@ -0,0 +1,46 @@
+import type { AdwSidebarItemSpec, AdwSidebarSectionSpec } from '@gjsify/adwaita-core';
+/** What `new Adw.SidebarItem({ … })` takes. */
+export interface AdwSidebarItemProps {
+    title?: string | null;
+    subtitle?: string | null;
+    iconName?: string | null;
+    visible?: boolean | string;
+    enabled?: boolean | string;
+}
+export declare class AdwSidebarItem implements AdwSidebarItemSpec {
+    /** `Adw.SidebarItem:title`. */
+    title: string;
+    /** `Adw.SidebarItem:subtitle`. */
+    subtitle: string;
+    /** `Adw.SidebarItem:icon-name` — `''` for none. */
+    iconName: string;
+    /** `Adw.SidebarItem:visible` — bound to the row's `visible`. Default `true`. */
+    visible: boolean;
+    /** `Adw.SidebarItem:enabled` — bound to the row's `sensitive`. Default `true`. */
+    enabled: boolean;
+    constructor(props?: AdwSidebarItemProps | null);
+}
+/** What `new Adw.SidebarSection({ … })` takes. */
+export interface AdwSidebarSectionProps {
+    title?: string | null;
+}
+export declare class AdwSidebarSection implements AdwSidebarSectionSpec {
+    /** `Adw.SidebarSection:title` — `''` draws a separator instead of a heading. */
+    title: string;
+    /** The section's items, in the order they were appended. */
+    readonly items: AdwSidebarItem[];
+    /** The sidebar showing this section, told when an item arrives — see {@link _bindOwner}. */
+    private _owner;
+    constructor(props?: AdwSidebarSectionProps | null);
+    /** `adw_sidebar_section_append`. A sidebar already showing the section redraws. */
+    append(item: AdwSidebarItem): void;
+    /**
+     * Called by the sidebar that takes this section. NativeScript's XML builder hands a
+     * `<adw:SidebarSection>` to the sidebar at its START tag, before its items are read, so
+     * the items reach a section the sidebar already drew — as `adw_sidebar_section_append` on
+     * a section in a sidebar does in C, which the sidebar follows through `items-changed`.
+     */
+    _bindOwner(owner: () => void): void;
+    /** XML inflation: every child is an item, appended in document order. */
+    _addChildFromBuilder(_name: string, child: object): void;
+}

package/lib/types/values/tab-page.d.ts

@@ -0,0 +1,16 @@
+import type { View } from '@nativescript/core';
+/** What `new Adw.TabPage({ … })` takes. */
+export interface AdwTabPageProps {
+    title?: string | null;
+}
+export declare class AdwTabPage {
+    /** `Adw.TabPage:child` is the one destination, so it is the fallback too. */
+    static readonly builderSlots: readonly string[];
+    /** `Adw.TabPage:title` — the tab's label. */
+    title: string;
+    /** `Adw.TabPage:child` — the content the page shows, or `null` before one is set. */
+    child: View | null;
+    constructor(props?: AdwTabPageProps | null);
+    /** XML inflation: `child: …` (or a bare child) is the page's content. */
+    _addChildFromBuilder(_name: string, view: View): void;
+}

package/lib/types/view-switcher-stack.spec.d.ts

@@ -0,0 +1 @@
+export declare const AdwViewSwitcherStackNsTest: () => Promise<void>;

package/lib/types/widgets/adw-about-dialog.d.ts

@@ -5,6 +5,18 @@ export declare const CLOSED = "closed";
 declare const AdwAboutDialog_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-action-row.d.ts

@@ -7,6 +7,18 @@ export declare const ACTIVATED = "activated";
 declare const AdwActionRow_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;
@@ -16,6 +28,8 @@ declare const AdwActionRow_base: (abstract new (...args: any[]) => {
     get(name: string): unknown;
 }) & typeof GridLayout;
 export declare class AdwActionRow extends AdwActionRow_base {
+    /** The names this widget's `_addChildFromBuilder` honours — see `./builder-slots.ts`. */
+    static readonly builderSlots: readonly string[];
     /**
      * Whether libadwaita would answer `ADW_IS_ACTION_ROW` for this row, which decides
      * whether the preferences SEARCH consults its subtitle.
@@ -44,6 +58,14 @@ export declare class AdwActionRow extends AdwActionRow_base {
      * cardinality is the declared remainder — the method ledger in
      * `scripts/check-vocabulary-alignment.mjs` compares names, and ADR 0034 § Amendment 14
      * names this as the divergence a name cannot carry. `remove()` clears the slot.
+     *
+     * INSERTED FIRST, NOT APPENDED, and on a `GridLayout` that is about the COMPOSED TREE
+     * rather than the layout: the column decides where it draws either way, so appending
+     * looked free — until an authored tree put a prefix on a row and the port realised it
+     * AFTER the disclosure's own rows, where `gtk_widget_get_first_child` and
+     * `<div class="adw-entry-row-prefixes">` both put it first. `adwaita-web`'s own slot
+     * binding already records the rule ("`addPrefix` PREPENDS, mirroring `gtk_box_prepend`");
+     * this is the third renderer joining it.
      */
     add_prefix(view: View): void;
     get prefix(): View | null;

package/lib/types/widgets/adw-alert-dialog.d.ts

@@ -14,6 +14,18 @@ export interface NotifyResponseEventData extends EventData {
 declare const AdwAlertDialog_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;
@@ -25,7 +37,12 @@ declare const AdwAlertDialog_base: (abstract new (...args: any[]) => {
 export declare class AdwAlertDialog extends AdwAlertDialog_base {
     /** The headless response registry + ordering + resolution (ADR 0004). */
     private readonly _responses;
-    constructor(heading?: string, body?: string, props?: ConstructProps<AdwAlertDialog>);
+    /**
+     * `adw_alert_dialog_new(heading, body)`'s positional pair, or GJS's construct bag
+     * `new Adw.AlertDialog({ heading, body })` as the only argument — the form a GJS author
+     * writes and the one the shared-tree builder hands every value object it builds.
+     */
+    constructor(headingOrProps?: string | ConstructProps<AdwAlertDialog>, body?: string, props?: ConstructProps<AdwAlertDialog>);
     /** The dialog heading (title). */
     get heading(): string;
     set heading(value: string);

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

@@ -10,6 +10,18 @@ export { AVATAR_DEFAULT_ICON };
 declare const AdwAvatar_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/adw-banner.d.ts

@@ -6,6 +6,18 @@ export declare const BUTTON_CLICKED = "buttonClicked";
 declare const AdwBanner_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;