@gjsify/adwaita-core 0.64.13-next.283 → 0.64.14

package/lib/types/conformance/menu.d.ts

@@ -1,8 +1,8 @@
-import type { AdwMenuActions, AdwMenuInput, AdwMenuItem, AdwMenuItemState, AdwMenuModel, AdwMenuPath } from '../menu.js';
+import type { AdwMenuActions, AdwMenuInput, AdwMenuItem, AdwMenuItemState, AdwMenuTree, AdwMenuPath } from '../menu.js';
 /** One {@link normalizeMenuModel} expectation. */
 export interface MenuNormalizeVector {
     input: AdwMenuInput;
-    model: AdwMenuModel;
+    tree: AdwMenuTree;
     rule: string;
 }
 /**
@@ -17,7 +17,7 @@ export declare const MENU_NORMALIZE_VECTORS: ReadonlyArray<MenuNormalizeVector>;
 export interface MenuParseVector {
     /** The raw attribute (or `null` when absent). */
     json: string | null;
-    model: AdwMenuModel;
+    tree: AdwMenuTree;
     rule: string;
 }
 /**
@@ -34,7 +34,7 @@ export interface MenuFlatRowVector {
 }
 /** One {@link flattenMenu} expectation. */
 export interface MenuFlattenVector {
-    model: AdwMenuModel;
+    tree: AdwMenuTree;
     rows: readonly MenuFlatRowVector[];
     rule: string;
 }
@@ -103,7 +103,7 @@ export interface MenuItemStateVector {
 export declare const MENU_ITEM_STATE_VECTORS: ReadonlyArray<MenuItemStateVector>;
 /** One {@link menuRefusals} expectation. */
 export interface MenuRefusalVector {
-    model: AdwMenuModel;
+    tree: AdwMenuTree;
     /** The paths that must be refused, in walk order. */
     paths: readonly AdwMenuPath[];
     rule: string;
@@ -131,3 +131,343 @@ export interface MenuLabelTextVector {
  * marker, which `adw_strip_mnemonic` (the core `stripMnemonic`) drops.
  */
 export declare const MENU_LABEL_TEXT_VECTORS: ReadonlyArray<MenuLabelTextVector>;
+/** What a type-surface row asks of the implementation. */
+export type MenuTypeQuery = 
+/** `new Gio.MenuModel()` — the abstract base. */
+'construct-abstract'
+/** `new Gio.Menu().constructor.$gtype.name`. */
+ | 'gtype-name'
+/** `GObject.type_parent(Gio.Menu.$gtype).name`. */
+ | 'parent-gtype-name'
+/** `new Gio.Menu() instanceof Gio.MenuModel`. */
+ | 'instance-of-base'
+/** `GObject.signal_lookup('items-changed', Gio.MenuModel.$gtype) !== 0`. */
+ | 'items-changed-on-base'
+/** `new Gio.Menu().get_n_items()`. */
+ | 'fresh-n-items'
+/** `new Gio.Menu().is_mutable()`. */
+ | 'fresh-is-mutable';
+/** One type-surface fact a `Gio.Menu` twin has to reproduce. */
+export interface MenuModelTypeVector {
+    query: MenuTypeQuery;
+    /** What the query answered, or `undefined` where it threw. */
+    answer?: string | number | boolean;
+    /** The message it threw, where it threw. */
+    throws?: string;
+    rule: string;
+}
+/**
+ * CORE-ONLY: a GType surface has no rendered form — a renderer can only observe it
+ * through the door that reads it, which is MENU_MODEL_DOOR_VECTORS, and both renderers
+ * drive that. Holding the same facts twice would assert the port's registration against
+ * itself in a place no widget can see.
+ *
+ * The GType surface: what a menu IS before anything is in it.
+ *
+ * The row a reader guesses wrong is the first one. `Gio.MenuModel` is an abstract CLASS,
+ * not an interface, so the twin declares it with `registerBaseClass` and has no
+ * `Implements` to answer for. ADR 0122's string list had the opposite shape:
+ * `Gio.ListModel` IS an interface, and the whole `ACCEPTED_INTERFACES` apparatus exists
+ * for it. A port that copied the string list wholesale would have invented an interface
+ * GTK does not have.
+ */
+export declare const MENU_MODEL_TYPE_VECTORS: ReadonlyArray<MenuModelTypeVector>;
+/** A mutator call, as data, so the table can be driven rather than read. */
+export type MenuMutatorCall = {
+    readonly method: 'append' | 'prepend';
+    readonly label: string;
+    readonly action?: string;
+} | {
+    readonly method: 'insert';
+    readonly position: number;
+    readonly label: string;
+    readonly action?: string;
+} | {
+    readonly method: 'append_item' | 'prepend_item';
+    readonly label: string;
+} | {
+    readonly method: 'insert_item';
+    readonly position: number;
+    readonly label: string;
+} | {
+    readonly method: 'append_section' | 'append_submenu' | 'prepend_section' | 'prepend_submenu';
+    readonly label: string | null;
+    readonly children: readonly string[];
+} | {
+    readonly method: 'insert_section' | 'insert_submenu';
+    readonly position: number;
+    readonly label: string | null;
+    readonly children: readonly string[];
+} | {
+    readonly method: 'remove';
+    readonly position: number;
+} | {
+    readonly method: 'remove_all';
+} | {
+    readonly method: 'items_changed';
+    readonly position: number;
+    readonly removed: number;
+    readonly added: number;
+};
+/** One measured `Gio.Menu` mutator and the single `items-changed` it emits. */
+export interface MenuMutatorEmissionVector {
+    /** How many plain items the menu holds before the call. */
+    before: number;
+    call: MenuMutatorCall;
+    /** `items-changed(position, removed, added)` — exactly ONE emission per call. */
+    emission: readonly [number, number, number];
+    /** How many items the menu holds after it. */
+    after: number;
+    rule: string;
+}
+/**
+ * CORE-ONLY: the emission is the CONTRACT a renderer consumes, and what a renderer can
+ * be held to is the reaction, not the triple — which is
+ * MENU_MODEL_NOTIFY_VECTORS and COMBO_ITEMS_CHANGED_VECTORS, both renderer-driven. A
+ * renderer suite asserting the triple would be asserting the model it was handed.
+ *
+ * Every mutator, the triple it emits, and the count it leaves behind.
+ *
+ * ONE emission per call, always: there is no mutator that batches and none that stays
+ * silent. The last two rows are the ones that separate a menu from a list store. A
+ * `remove_all()` on an EMPTY menu STILL emits `(0, 0, 0)` — measured — so the no-op skip
+ * that is right for `Gtk.StringList` (ADR 0122) is wrong here, and `items_changed` is a
+ * PUBLIC emitter that changes nothing, which is how a subclass reports a splice it made
+ * itself.
+ */
+export declare const MENU_MUTATOR_EMISSION_VECTORS: ReadonlyArray<MenuMutatorEmissionVector>;
+/** A GVariant the table hands to `set_attribute_value`, spelled as type + value. */
+export interface MenuAttributeVariant {
+    /** A type string from ADR 0118 § 2's subset — `s`, `i`, `b` or `d`. */
+    readonly type: 's' | 'i' | 'b' | 'd';
+    readonly value: string | number | boolean;
+}
+/** How the attribute under test got onto the item. */
+export type MenuAttributeSet = 
+/** `item.set_detailed_action(detailed)` — writes `action` and maybe `target`. */
+{
+    readonly kind: 'detailed-action';
+    readonly detailed: string;
+}
+/** `item.set_label(label)`. */
+ | {
+    readonly kind: 'label';
+    readonly label: string;
+}
+/** `item.set_attribute_value(name, variant)`. */
+ | {
+    readonly kind: 'attribute';
+    readonly name: string;
+    readonly variant: MenuAttributeVariant;
+}
+/** Nothing was set — the row is about reading what was never written. */
+ | {
+    readonly kind: 'nothing';
+};
+/** One `get_item_attribute_value` read, and the variant type it answers with. */
+export interface MenuAttributeVariantVector {
+    set: MenuAttributeSet;
+    /** The attribute name the read asks for. */
+    read: string;
+    /** `expected_type`, where the row is about passing one. */
+    expectedType?: string;
+    /** The type string the read answers with, or `null` for an empty read. */
+    type: string | null;
+    /** `deepUnpack()` of the answer, where the row is about the VALUE and not only the type. */
+    value?: string | number | boolean;
+    rule: string;
+}
+/**
+ * CORE-ONLY: an attribute's variant TYPE never reaches a rendered surface — what a
+ * renderer draws from it is held by MENU_NORMALIZE_VECTORS and MENU_ITEM_STATE_VECTORS,
+ * which both renderers drive.
+ *
+ * What type each menu attribute comes back as.
+ *
+ * `target` is the row that explains the table: its type is the TARGET's own, not a fixed
+ * `s`. A radio item written `win.zoom(2)` reads `i` and one written `app.view::list`
+ * reads `s`, which is why `resolveMenuItemState` compares the PRINTED target rather than
+ * the unpacked one. The two rows at the end are the empty reads, and neither throws — an
+ * unknown attribute name and a mismatched `expected_type` both answer `null`, so a
+ * surface cannot tell a typo from an absence and must not try.
+ */
+export declare const MENU_ATTRIBUTE_VARIANT_VECTORS: ReadonlyArray<MenuAttributeVariantVector>;
+/** What a link row asks of the implementation, against the scene its docblock describes. */
+export type MenuLinkQuery = 
+/** `menu.get_item_link(0, 'section')` is the very section that was appended. */
+'section-identity'
+/** Two reads of the same link are identity-equal. */
+ | 'repeat-read-identity'
+/** `get_item_link(0, 'submenu')` on a SECTION item. */
+ | 'wrong-link-name'
+/** `get_item_link(0, 'x-no-such-link')`. */
+ | 'unknown-link-name'
+/** The link names `iterate_item_links(0)` yields. */
+ | 'link-iteration'
+/** The attribute names `iterate_item_attributes(0)` yields. */
+ | 'attribute-iteration'
+/** Root emissions counted while the SECTION is appended to. */
+ | 'link-emission-does-not-bubble'
+/** The link's own count after that append. */
+ | 'link-count-after-append';
+/** One link read, or the emission a link does not send. */
+export interface MenuLinkVector {
+    query: MenuLinkQuery;
+    /** What it answered: a boolean, a count, or the names an iterator yielded. */
+    answer: boolean | number | readonly string[] | null;
+    rule: string;
+}
+/**
+ * CORE-ONLY: the non-bubbling emission is the reason `watchMenuModel` exists, and what a
+ * renderer owes is the REDRAW — held by MENU_TREE_VECTORS, which both renderers drive
+ * through their own widgets.
+ *
+ * Links, their identity, and the emission that stays where it was raised.
+ *
+ * THE SCENE every row runs against: a menu holding one `append_section('Edit', sec)` at
+ * position 0, where `sec` holds a single `append('Cut', 'app.cut')`.
+ *
+ * The last two rows are the whole reason `watchMenuModel` exists (ADR 0128 § 6). A
+ * section's own `items-changed` does NOT bubble to the menu holding it, while the link
+ * read reflects the change immediately — so a renderer connected only to the root shows a
+ * stale section for ever. That defect was unreachable while the model was an array,
+ * because every mutation went through a re-parse of the whole tree; it arrives WITH the
+ * real model, which is why the vector arrives with it too.
+ */
+export declare const MENU_LINK_VECTORS: ReadonlyArray<MenuLinkVector>;
+/** The widgets whose `menu-model` property was measured. */
+export type MenuModelHolder = 'Adw.SplitButton' | 'Gtk.MenuButton';
+/** One value in a write sequence: the name of a model, or the empty value. */
+export type MenuModelWrite = 'A' | 'B' | null;
+/** One widget `menu-model` write sequence and the `notify::menu-model` count per write. */
+export interface MenuModelNotifyVector {
+    widget: MenuModelHolder;
+    /** The writes, in order. `A` and `B` are two DISTINCT models; `null` clears. */
+    writes: ReadonlyArray<MenuModelWrite>;
+    /** How many `notify::menu-model` each write produced, in order. */
+    notifies: ReadonlyArray<number>;
+    /** Set where the sequence ends by MUTATING the held model rather than writing one. */
+    mutateHeldModel?: boolean;
+    rule: string;
+}
+/**
+ * The identity guard, which the TWO libraries disagree about.
+ *
+ * Both widgets declare `menu-model` with `value_type=GMenuModel` and both take the same
+ * values, but `Adw.SplitButton` compares by POINTER and skips the notify for a repeat,
+ * while `Gtk.MenuButton` notifies unconditionally — including `null` over `null`.
+ * Measured, both of them, because a port guessing one way is wrong about one widget: a
+ * port that guards both is wrong about `Gtk.MenuButton`, and one that guards neither is
+ * wrong about `Adw.SplitButton`, whose notify rebuilds the popover.
+ *
+ * The last row is the one that puts `JSON.stringify` out of the picture for good. Mutating
+ * a HELD model is not a property change: the content arrives over `items-changed` and
+ * never over `notify`, so a widget keying its popover on a serialisation of the model
+ * (which `split-button.ts` did, as `menuKey`) redraws on writes that changed nothing and
+ * stays still for mutations that changed everything.
+ */
+export declare const MENU_MODEL_NOTIFY_VECTORS: ReadonlyArray<MenuModelNotifyVector>;
+/** One value written to a widget's `menu-model` property, and the door's answer. */
+export interface MenuModelDoorVector {
+    /** What was assigned. */
+    write: 'menu' | 'null' | 'array' | 'plain-object' | 'wrong-gobject' | 'json-string';
+    /** The message the write threw, or `null` where it was accepted. */
+    error: string | null;
+    /**
+     * Where ONE surface answers differently, keyed by `AdwMenuSurface['name']`: `null`
+     * means that surface accepts the write, a string is a FRAGMENT of its refusal (the
+     * full message names the widget class, which belongs to the caller and not here).
+     *
+     * One row needs it, and the asymmetry is deliberate rather than a gap. The browser has
+     * a real `menu-model` ATTRIBUTE, so a JSON string is what markup actually delivers and
+     * the door parses it. NativeScript's XML Builder writes an attribute STRAIGHT onto the
+     * property, so the same string would arrive at the same door a code assignment uses —
+     * and ADR 0042 kept that door shut rather than open an XML seam no probe can prove.
+     * Same write, two answers, each measured against its own platform.
+     */
+    bySurface?: Readonly<Record<string, string | null>>;
+    rule: string;
+}
+/**
+ * What the `menu-model` door accepts, and the words it refuses with.
+ *
+ * The two GJS refusals are reproduced VERBATIM — an array and a plain object are both
+ * rejected by the GObject value check before any menu code sees them, which is what makes
+ * "assign an array to `menu-model`" a type error rather than a convenience the port could
+ * have kept. The `json-string` row is the port's OWN door and not GIO's: an authored
+ * `menu="…"` attribute is a string by the time it reaches a widget, and ADR 0128 § 7
+ * coerces it at the same seam ADR 0122 § 5 coerces a list at, which is the one place a
+ * ParamSpec cannot.
+ */
+export declare const MENU_MODEL_DOOR_VECTORS: ReadonlyArray<MenuModelDoorVector>;
+/** A behaviour the twin has to ANSWER for, named so a spec can drive it. */
+export type MenuDivergenceProbe = 
+/** `get_item_attribute_value(99, 'label', null)` on a one-item menu. */
+'attribute-read-out-of-range'
+/** `get_item_link(99, 'section')` on a one-item menu. */
+ | 'link-read-out-of-range'
+/** `freeze()`, then `append` — `is_mutable()` and the resulting count. */
+ | 'freeze-does-not-lock'
+/** `set_label` on an item ALREADY appended. */
+ | 'item-is-a-snapshot'
+/** `set_attribute_value(name, null)`. */
+ | 'null-attribute-removes'
+/** `set_attribute_value('x', 'str')` — a bare JS string where a Variant belongs. */
+ | 'bare-string-attribute-refused'
+/** The serialised-GIcon `icon` attribute GIO writes and the subset has no type for. */
+ | 'icon-is-a-serialised-gicon'
+/** `get_item_attribute` — the varargs form. */
+ | 'varargs-attribute-getter-absent'
+/** `get_string` / `get_boolean` / `get_int32` on an attribute Variant. */
+ | 'typed-variant-getters-refused'
+/** What `expected_type` is: `get_item_attribute_value(0, 'label', <type>)`. */
+ | 'variant-type-is-a-string';
+/** One place the twin cannot copy GIO, with what each side does. */
+export interface MenuModelDivergenceVector {
+    probe: MenuDivergenceProbe;
+    /** What GIO does, measured. */
+    gio: string;
+    /** What the twin does — the port's declared answer, which the spec drives. */
+    twin: string;
+    rule: string;
+}
+/**
+ * CORE-ONLY: a divergence is between the port and GIO, so there is no third surface to
+ * hold it against — the renderer-visible consequence is the snapshot read, which is
+ * MENU_TREE_VECTORS, and both renderers drive that.
+ *
+ * Where the port cannot copy GIO, and what it does instead.
+ *
+ * The first row is not a style choice. `get_item_attribute_value` past the end trips a C
+ * position assertion and takes the process with it — measured by crashing a probe — so
+ * there is no behaviour to reproduce and the twin has to PICK one. It picks the empty
+ * read, matching every other out-of-range read in this package. `freeze-does-not-lock` is
+ * the opposite of what the name suggests and is measured both ways: the flag flips and the
+ * mutators keep working, so a twin that refused mutation after a freeze would break a
+ * caller GIO lets through. The last three are the edges of ADR 0118 § 2's variant subset
+ * and of GJS's own introspection, and each is a deliberate narrowing rather than a gap
+ * someone forgot.
+ */
+export declare const MENU_MODEL_DIVERGENCE_VECTORS: ReadonlyArray<MenuModelDivergenceVector>;
+/** One `Gio` menu constant the twin has to export with the measured value. */
+export interface MenuConstantVector {
+    /** The name on the `Gio` namespace. */
+    name: string;
+    /** Its value, measured. */
+    value: string | number;
+    rule: string;
+}
+/**
+ * CORE-ONLY: a constant has no rendered form at all. What a renderer does with the names
+ * it stands for is MENU_NORMALIZE_VECTORS, which both renderers drive through their own
+ * split button.
+ *
+ * The constants, because a caller writing `Gio.MENU_ATTRIBUTE_LABEL` instead of `'label'`
+ * has to get the same string from the port as from GJS.
+ *
+ * `MENU_EXPORTER_MAX_SECTION_SIZE` is the odd one out: nothing in the port enforces it and
+ * nothing should, since it is a D-Bus exporter limit. It is here so that a caller reading
+ * it is handed the real number rather than `undefined` — the failure mode of a port that
+ * exports the constants it happens to use.
+ */
+export declare const MENU_CONSTANT_VECTORS: ReadonlyArray<MenuConstantVector>;

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

@@ -1,4 +1,4 @@
-import type { AdwMenuItem, AdwMenuModel, AdwMenuPath } from '../menu.js';
+import type { AdwMenuItem, AdwMenuPath, AdwMenuTree } from '../menu.js';
 import type { AdwArrowIcon, SplitButtonContentMode, SplitButtonDirection, SplitButtonHalfState, SplitButtonProperty, SplitButtonStyleClass } from '../split-button.js';
 /** One mutation in a {@link SplitButtonContentVector} sequence, with its outcome. */
 export interface SplitButtonContentStep {
@@ -129,7 +129,7 @@ export interface SplitButtonRootStateVector {
 export declare const SPLIT_BUTTON_ROOT_STATE_VECTORS: ReadonlyArray<SplitButtonRootStateVector>;
 /** One activate-by-position expectation. */
 export interface SplitButtonMenuActivationVector {
-    model: AdwMenuModel;
+    tree: AdwMenuTree;
     path: AdwMenuPath;
     /** The item that must be dispatched, or `null`. */
     activated: AdwMenuItem | null;
@@ -147,8 +147,11 @@ export declare const SPLIT_BUTTON_MENU_ACTIVATION_VECTORS: ReadonlyArray<SplitBu
  * a row with both also exercises the dissociation.
  */
 export interface SplitButtonDropdownVector {
-    /** The menu model to install (empty = none). */
-    model: AdwMenuModel;
+    /**
+     * The tree to BUILD a menu model from and install, or `null` to install no model at
+     * all. `[]` is a real but EMPTY menu, which is not the same row as `null` (ADR 0128).
+     */
+    tree: AdwMenuTree | null;
     /** Whether a popover is installed before it. */
     popover: boolean;
     /** Whether the dropdown half is live. */
@@ -159,7 +162,8 @@ export interface SplitButtonDropdownVector {
 }
 /**
  * "If the menu model is `NULL`, the dropdown is disabled",
- * and the same for the popover. An empty entry list is the renderers'
- * only spelling of "no menu", so it collapses onto the `NULL` case.
+ * and the same for the popover. `NULL` is the ONLY spelling of "no menu": a present but
+ * empty model leaves the dropdown live, which is why the port needed a real model to say
+ * it at all (ADR 0128).
  */
 export declare const SPLIT_BUTTON_DROPDOWN_VECTORS: ReadonlyArray<SplitButtonDropdownVector>;

package/lib/types/engine.d.ts

@@ -12,6 +12,20 @@ export interface ForeignScalarProperty {
     readonly default?: string | boolean | number | null;
     readonly nick?: string;
     readonly blurb?: string;
+    /**
+     * The property emits `notify` ITSELF, so neither engine emits one for an ordinary write.
+     *
+     * This is `G_PARAM_EXPLICIT_NOTIFY`, and it is a declaration ABOUT THE REAL WIDGET, not a
+     * convenience: `Adw.ComboRow:selected` carries the flag upstream, and a write that moves the
+     * index there emits `selected` AND `selected-item` — an order no store-level "it changed, so
+     * notify" can produce. The widget that sets this owns both emissions, from `afterNotify` or
+     * from whatever state push stands in for the C setter. Measured, GJS 1.88 / libadwaita 1.9.4:
+     * `selected = 2` → `["selected", "selected-item"]`; out of range → nothing at all.
+     *
+     * Leave it off and the engine emits one `notify` per changed property, which is what every
+     * other declared property wants.
+     */
+    readonly explicitNotify?: boolean;
 }
 /**
  * A property holding another GObject, or `null` — `Adw.ComboRow:model` (ADR 0122 § 6).
@@ -33,6 +47,8 @@ export interface ForeignObjectProperty {
     readonly valueType: GType | GInterface;
     readonly nick?: string;
     readonly blurb?: string;
+    /** `G_PARAM_EXPLICIT_NOTIFY` — see {@link ForeignScalarProperty.explicitNotify}. */
+    readonly explicitNotify?: boolean;
 }
 /** One property a widget class declares at its `extends`. */
 export type ForeignProperty = ForeignScalarProperty | ForeignObjectProperty;