@gjsify/adwaita-nativescript 0.64.12 → 0.64.13

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

@@ -21,6 +21,43 @@ type Declared<P> = P & {
      * here, since a write that resolves to the value already held is not a change.
      */
     readonly normalize?: (value: unknown, self: object) => unknown;
+    /**
+     * Replaces the equal-write check for this property: `written` is the value as the caller
+     * spelled it, `next` what {@link Declared.normalize} made of it, `held` what the store holds
+     * — and the answer decides whether the write notifies at all.
+     *
+     * WHY. A C setter guards on `g_strcmp0 (value, adw_…_get_…(self))`, against the GETTER
+     * READBACK rather than the stored field. Where storage normalises, the two differ and the
+     * guard can never fire: `GtkImage` turns an empty icon name into "no icon", so writing `''`
+     * to a button that already reads back `null` notifies EVERY time (measured on GJS 1.88.1 /
+     * libadwaita 1.9.4). Comparing the held value says the opposite, and only the property whose
+     * `normalize` collapses distinct writes onto one held value can tell the difference.
+     *
+     * RUNS ON BOTH LEGS. It used to run on the pure one alone, on the reasoning that "there the
+     * guard IS the C one" — which holds for a widget wrapping a real C object and not for a
+     * foreign-parent class, which has no C setter at all. On route D node-gi's generated setter
+     * is an identity guard and nothing more (`installForeignPropertyAccessors` in `gi.js`), so a
+     * property that left this to the real leg got the identity answer there and the measured one
+     * off-device — the per-leg difference this seam exists to close.
+     */
+    readonly changed?: (next: unknown, held: unknown, written: unknown, self: object) => boolean;
+    /**
+     * The rest of the C setter: runs once this property's own `notify::<name>` is out, so a
+     * setter that also drives OTHER properties emits in the order C does. For a property with
+     * {@link ForeignScalarProperty.explicitNotify} it runs INSTEAD of that notify, and owes every
+     * emission the write makes, its own included.
+     *
+     * WHY IT IS NOT `normalize`. A normalizer runs AHEAD of the store, so a cross-write made
+     * there notifies before the property that caused it. `Adw.SplitButton` measures the other way
+     * round — `label = 'Open'` on an icon button emits `label` first and the slots it clears
+     * after — and the two cannot both be one hook. The SHAPE of a value still belongs to
+     * `normalize`; what the write does to its siblings belongs here.
+     *
+     * RUNS ON BOTH LEGS, for the reason {@link Declared.changed} states: the foreign-parent class
+     * route D registers has no C setter to do this instead. `adw-split-button`'s label/icon-name
+     * mutual clear is the one that was silently missing on Android because of it.
+     */
+    readonly afterNotify?: (self: object) => void;
 };
 /** A declared property of any kind, with its optional {@link Declared.normalize}. */
 export type DeclaredProperty = Declared<ForeignScalarProperty> | Declared<ForeignObjectProperty>;
@@ -194,4 +231,21 @@ export declare function withProperties<TBase extends ObservableConstructor>(Base
     /** Only what this class ADDS; `emittedSignalsOf` merges it with the base's. */
     readonly emittedSignals: readonly string[];
 }) & TBase;
+/**
+ * Write a declared property's held value WITHOUT notifying, and without running `normalize`,
+ * `changed` or `afterNotify` — the PUSH half of a property whose widget owns the emission.
+ *
+ * WHY A WIDGET NEEDS IT. A property whose value also moves from UNDERNEATH — the selection of an
+ * `Adw.ComboRow` when its model is replaced, or when the held model splices — cannot be kept in
+ * sync by writing it, because the write is the thing that emits and the emission order is
+ * measured and is not the order a write would produce. `model = null` is the sharpest case:
+ * `selected` goes to the sentinel and `selected-item` to null with NO notify at all, and `model`
+ * alone notifies. So the widget pushes the new value in here and emits what it owes with
+ * `notify('<name>')`, in the order it measured.
+ *
+ * Only a {@link isSeamOwned} property may be pushed, and a name that is not one THROWS rather
+ * than writing a store route D would never read back: there the value lives in the GObject, and
+ * a silent push would be correct off-device and invisible on the device.
+ */
+export declare function pushDeclared(self: object, name: string, value: unknown): void;
 export {};

package/lib/types/widgets/single-child-base.d.ts

@@ -5,6 +5,8 @@ export declare abstract class AdwSingleChildBase extends AdwStyledLayoutBase {
     constructor();
     private _columnIsStar;
     onLoaded(): void;
+    onUnloaded(): void;
+    private _onWidthChangeSyncColumn;
     private _syncColumnToAlignment;
     /** The child, or `null`. */
     get child(): View | null;

package/lib/types/widgets/single-child-cell.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Whether the single cell of a one-child container is `star` rather than `auto`.
+ *
+ * `star` when the container's width is settled — either because it stretches to its parent,
+ * or because a definite `width` was written on it. `auto` otherwise, so the container can
+ * still report its child's natural width and be placed by its alignment.
+ */
+export declare function singleChildCellIsStar(horizontalAlignment: unknown, width: unknown): boolean;

package/lib/types/widgets/xml-values.d.ts

@@ -6,6 +6,18 @@
  * caller can keep validating a RANGE without also having to re-check the type.
  */
 export declare function xmlNumber(value: unknown, fallback: number): number;
+/**
+ * The integer GtkBuilder reads out of an enum property's value, or `undefined` when the
+ * value is a nick or name.
+ *
+ * `_gtk_builder_enum_from_string` (gtk/gtkbuilder.c) tries the number FIRST
+ * (`g_ascii_strtoull (string, &endptr, 0)`, so base 0: decimal, `0x` hex, leading-`0` octal)
+ * and only then the nick and the name — which is why `halign="1"` and `halign="start"` are
+ * the same attribute in a `.ui` file. A JS number is the same reading, already parsed.
+ * GTK also accepts a numeric PREFIX (`"2abc"` is 2); the whole string must be a number here,
+ * so a nick that merely starts with a digit stays a nick.
+ */
+export declare function gtkBuilderInteger(value: unknown): number | undefined;
 /**
  * An attribute as a boolean.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-nativescript",
-    "version": "0.64.12",
+    "version": "0.64.13",
     "description": "Native Adwaita widgets for the NativeScript runtime — real NativeScript components (StackLayout/GridLayout/Switch/Label) styled like Libadwaita, not a webview",
     "type": "module",
     "module": "lib/esm/index.js",
@@ -73,15 +73,15 @@
         "design-system"
     ],
     "dependencies": {
-        "@gjsify/adwaita-core": "^0.64.12",
-        "@gjsify/adwaita-fonts": "^0.64.12",
-        "@gjsify/adwaita-icons": "^0.64.12",
-        "@gjsify/canvas2d-core": "^0.64.12",
-        "@gjsify/native-platform": "^0.64.12"
+        "@gjsify/adwaita-core": "^0.64.13",
+        "@gjsify/adwaita-fonts": "^0.64.13",
+        "@gjsify/adwaita-icons": "^0.64.13",
+        "@gjsify/canvas2d-core": "^0.64.13",
+        "@gjsify/native-platform": "^0.64.13"
     },
     "peerDependencies": {
         "@nativescript/core": "*",
-        "@gjsify/app-settings": "^0.64.12"
+        "@gjsify/app-settings": "^0.64.13"
     },
     "peerDependenciesMeta": {
         "@nativescript/core": {
@@ -92,11 +92,11 @@
         }
     },
     "devDependencies": {
-        "@gjsify/app-settings": "^0.64.12",
-        "@gjsify/blueprint": "^0.64.12",
-        "@gjsify/cli": "^0.64.12",
-        "@gjsify/unit": "^0.64.12",
-        "@gjsify/vite-plugin-blueprint": "^0.64.12",
+        "@gjsify/app-settings": "^0.64.13",
+        "@gjsify/blueprint": "^0.64.13",
+        "@gjsify/cli": "^0.64.13",
+        "@gjsify/unit": "^0.64.13",
+        "@gjsify/vite-plugin-blueprint": "^0.64.13",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },

package/src/testing/ns-core.mts

@@ -173,8 +173,12 @@ function unloadView(view: View): void {
  */
 export class Style extends Observable {
     direction?: 'ltr' | 'rtl' | null = null;
+    /** In DIPs, and unset until written: `fontSizeProperty` carries no `defaultValue`. */
+    fontSize?: number;
     readonly viewRef: WeakRef<View>;
     #visibility = 'visible';
+    #width: number | string = 'auto';
+    #height: number | string = 'auto';
 
     constructor(view: View) {
         super();
@@ -191,6 +195,33 @@ export class Style extends Observable {
         this.#visibility = value;
         this.notify({ eventName: 'visibilityChange', object: this, propertyName: 'visibility', value, oldValue });
     }
+
+    /**
+     * The inline width, in DIPs or as a percentage string, `'auto'` until written — and the
+     * `widthChange` a one-child container listens for. A CSS property notifies on the style
+     * and not on the view, which is the whole reason this pair lives here.
+     */
+    get width(): number | string {
+        return this.#width;
+    }
+
+    set width(value: number | string) {
+        const oldValue = this.#width;
+        if (value === oldValue) return;
+        this.#width = value;
+        this.notify({ eventName: 'widthChange', object: this, propertyName: 'width', value, oldValue });
+    }
+
+    get height(): number | string {
+        return this.#height;
+    }
+
+    set height(value: number | string) {
+        const oldValue = this.#height;
+        if (value === oldValue) return;
+        this.#height = value;
+        this.notify({ eventName: 'heightChange', object: this, propertyName: 'height', value, oldValue });
+    }
 }
 
 export class View extends Observable {
@@ -232,8 +263,32 @@ export class View extends Observable {
      * missing so the first `className` write died inside a constructor.
      */
     readonly cssClasses: Set<string> = new Set();
-    width: number | string = 'auto';
-    height: number | string = 'auto';
+    /**
+     * `'auto'` until written, and HELD ON THE {@link Style} as `widthProperty` /
+     * `heightProperty` are (`ui/styling/style-properties.ts` registers both on `Style`;
+     * `view-common.ts`'s `get width()` is a one-line forward to `this.style.width`).
+     *
+     * This double held them as plain fields on the view, which made it STRUCTURALLY BLIND to
+     * the one thing a reader needs from them: the notification. `AdwSingleChildBase` learns
+     * that a parent settled its width from `widthChange` on the style — on a device the only
+     * place it is emitted — and against a field there is no event at all, so a spec would
+     * have passed while the widget sat waiting for a message that never came.
+     */
+    get width(): number | string {
+        return this._style.width;
+    }
+
+    set width(value: number | string) {
+        this._style.width = value;
+    }
+
+    get height(): number | string {
+        return this._style.height;
+    }
+
+    set height(value: number | string) {
+        this._style.height = value;
+    }
     horizontalAlignment = 'stretch';
     verticalAlignment = 'stretch';
     /**
@@ -663,8 +718,181 @@ export class GridLayout extends LayoutBase {
     }
 }
 
+/**
+ * A `Span`'s style — NOT a {@link View}'s {@link Style}.
+ *
+ * `Span extends ViewBase` upstream, so it has none of `View`'s shortcuts and carries only
+ * what a span can be given. Every member is unset until written, which is what the font
+ * properties answer on a device: `fontSizeProperty` and `fontFamilyProperty` are registered
+ * with no `defaultValue` (`ui/styling/style-properties.ts`).
+ */
+export class SpanStyle extends Observable {
+    fontFamily: string | undefined;
+    fontSize: number | undefined;
+    fontStyle: string | undefined;
+    fontWeight: string | undefined;
+    textDecoration: string | undefined;
+    verticalAlignment: string | undefined;
+}
+
+/**
+ * One styled stretch of a {@link FormattedString}.
+ *
+ * The font and decoration members are ACCESSORS OVER `style`, as `ui/text-base/span.ts`
+ * has them — a double that made them own fields could not report a widget that wrote one
+ * and expected the other to see it.
+ */
+export class Span extends Observable {
+    static readonly linkTapEvent = 'linkTap';
+
+    readonly _style: SpanStyle = new SpanStyle();
+
+    get style(): SpanStyle {
+        return this._style;
+    }
+
+    /** NativeScript unescapes the two whitespace spellings a markup file can carry. */
+    private _text = '';
+
+    get text(): string {
+        return this._text;
+    }
+
+    set text(value: string) {
+        this._text = String(value ?? '')
+            .replace(/\\n/g, '\n')
+            .replace(/\\t/g, '\t');
+    }
+
+    get fontFamily(): string | undefined {
+        return this._style.fontFamily;
+    }
+
+    set fontFamily(value: string | undefined) {
+        this._style.fontFamily = value;
+    }
+
+    get fontSize(): number | undefined {
+        return this._style.fontSize;
+    }
+
+    set fontSize(value: number | undefined) {
+        this._style.fontSize = value;
+    }
+
+    get fontStyle(): string | undefined {
+        return this._style.fontStyle;
+    }
+
+    set fontStyle(value: string | undefined) {
+        this._style.fontStyle = value;
+    }
+
+    get fontWeight(): string | undefined {
+        return this._style.fontWeight;
+    }
+
+    set fontWeight(value: string | undefined) {
+        this._style.fontWeight = value;
+    }
+
+    get textDecoration(): string | undefined {
+        return this._style.textDecoration;
+    }
+
+    set textDecoration(value: string | undefined) {
+        this._style.textDecoration = value;
+    }
+
+    /**
+     * DERIVED, never written — upstream flips it from `addEventListener` /
+     * `removeEventListener` through `_setTappable(this.hasListeners(Span.linkTapEvent))`,
+     * and `setSpanModifiers` attaches the native `ClickableSpan` only for a tappable span.
+     * So subscribing IS what makes a span a link, and this reads the listeners rather than
+     * a flag a caller could set without one.
+     */
+    get tappable(): boolean {
+        return (listenersOf(this).get(Span.linkTapEvent)?.length ?? 0) > 0;
+    }
+}
+
+/**
+ * The `ObservableArray<Span>` behind {@link FormattedString.spans}, as the four members
+ * that collection really offers.
+ *
+ * NOT A PLAIN ARRAY, and a double that used one would be the easier lie: `ObservableArray`
+ * reads by `getItem(pos)` and has no index access at all, so `spans[0]` is `undefined` on a
+ * device. A spec written against an array would pass here and read nothing there.
+ */
+export class SpanList {
+    private readonly _items: Span[] = [];
+
+    get length(): number {
+        return this._items.length;
+    }
+
+    push(span: Span): number {
+        return this._items.push(span);
+    }
+
+    /** A negative `pos` counts from the end, as upstream's does. */
+    getItem(pos: number): Span {
+        return this._items[pos < 0 ? this._items.length + pos : pos]!;
+    }
+
+    *[Symbol.iterator](): Generator<Span, void, unknown> {
+        yield* this._items;
+    }
+}
+
+/** The rich-text value of a {@link Label} — a FLAT list of spans, no nesting. */
+export class FormattedString extends Observable {
+    readonly spans: SpanList = new SpanList();
+
+    /** `formatted-string.ts`: the span texts concatenated, nothing between them. */
+    toString(): string {
+        let text = '';
+        for (const span of this.spans) text += span.text;
+        return text;
+    }
+}
+
 export class Label extends View {
-    text = '';
+    private _text = '';
+    private _formattedText: FormattedString | null | undefined;
+
+    /**
+     * A write is a NO-OP while {@link formattedText} is set, as on a device:
+     * `[textProperty.setNative]` returns early when the label carries rich text
+     * (`ui/text-base/index.android.ts:192-195`), so the spans are what shows and this
+     * property is whatever the spans last said.
+     */
+    get text(): string {
+        return this._text;
+    }
+
+    set text(value: string) {
+        if (this._formattedText === null || this._formattedText === undefined) this._text = value;
+    }
+
+    /**
+     * Unset until something writes it — `formattedTextProperty` carries no `defaultValue`
+     * (`ui/text-base/text-base-common.ts:194`), so a label that was never given rich text
+     * reads `undefined`, not `null`.
+     */
+    get formattedText(): FormattedString | null | undefined {
+        return this._formattedText;
+    }
+
+    set formattedText(value: FormattedString | null | undefined) {
+        this._formattedText = value;
+        // The device re-derives the plain text from the spans on BOTH legs:
+        // `[formattedTextProperty.setNative]` calls
+        // `textProperty.nativeValueChange(this, value?.toString() ?? '')`, which is why a
+        // `text` written BEFORE the clear would be wiped to the empty string.
+        this._text = value?.toString() ?? '';
+    }
+
     textWrap = false;
     textAlignment = 'initial';
     textOverflow = 'initial';