@gjsify/gtk-host 0.51.1 → 0.52.0

package/lib/types/generated/surface-data.d.mts

@@ -6,6 +6,16 @@ export declare const OWN_SIGNALS: Readonly<Record<string, readonly string[]>>;
 export declare const DECLS: Readonly<Record<string, readonly string[]>>;
 /** Enum GType -> the nicks the surface offers. */
 export declare const ENUM_NICKS: Readonly<Record<string, readonly string[]>>;
+/**
+ * Bitfield GType -> the member nicks the surface offers, for the bitfields a property
+ * of this surface carries.
+ *
+ * Derived from `FLAG_VALUES`' KEYS rather than from a nick list, because `@girs`
+ * publishes none for a bitfield — GObject resolves no nick SET, so the vocabulary says
+ * nothing about sets and the members keep their names in the value table. Held against
+ * the installed library the same way `ENUM_NICKS` is.
+ */
+export declare const FLAG_NICKS: Readonly<Record<string, readonly string[]>>;
 /** Widget GType -> its kebab tag. */
 export declare const TAGS: Readonly<Record<string, string>>;
 /**

package/lib/types/generated/value-types.d.mts

@@ -0,0 +1,28 @@
+/**
+ * The libraries these rows were read from, in the same provenance grammar
+ * `methods.mts` uses so one parser reads both lines.
+ */
+export declare const VALUE_TYPES_PROVENANCE = "Adw-1/1.9.3 Gio-2.0 Gtk-4.0/4.22.5";
+/**
+ * `<Namespace>.<Member>` -> what the typelib says that type is.
+ *
+ * One row per entry of `CONSTRUCTIBLE_VALUES` in `scripts/value-types.mjs`: the ledger is
+ * the INPUT, this is the answer. `gtype` is the GType the class registers; `widget` is
+ * whether its declared parent chain reaches `GtkWidget`, and a `true` here is the
+ * finding the whole ledger is guarded for — a widget excused as a value would be the
+ * second place a widget is declared.
+ */
+export declare const VALUE_TYPES: Readonly<Record<string, {
+    gtype: string;
+    widget: boolean;
+}>>;
+/**
+ * `<Namespace>.<Member>` -> the loaded typelib that declares no such GObject.
+ *
+ * The declared remainder, so "every ledger entry has an answer" can be a rule rather than
+ * a hope: a member in NEITHER table is a ledger the artifact predates, and the gate says
+ * so instead of passing over it. An entry here is a ledger entry that is simply wrong —
+ * unlike the sibling artifacts' remainders, it cannot be a version gap, because nothing
+ * in this repository may excuse a member whose type the installed GIR has never heard of.
+ */
+export declare const VALUE_TYPES_UNDECLARED: Readonly<Record<string, string>>;

package/lib/types/generator/emit-types.d.mts

@@ -40,6 +40,28 @@ export interface EmittedFile {
     readonly text: string;
 }
 export declare function emitProps(model: SurfaceModel, provenance: string): EmittedFile;
+/**
+ * Emit GTK's ARIA surface: the slot table the runtime reads, and the props interface.
+ *
+ * WHY THIS FILE EXISTS AND `props.ts` COULD NOT CARRY IT. Every other name a renderer can
+ * write on a widget is a GObject property, and the host resolves those through the
+ * ParamSpec of the INSTALLED class — the table travels with the package, the coercion
+ * travels with the user's GTK. An ARIA slot has no ParamSpec. `GtkAccessible` installs
+ * exactly one property, `accessible-role`; the other 53 names live in three ENUMS and are
+ * written through three calls, and the value type of each is stated only in that enum
+ * member's GIR DOCUMENTATION. So the type has to SHIP, and this is the one generated file
+ * whose data the runtime cannot re-derive from the object in front of it.
+ *
+ * WHY THE TABLE AND THE INTERFACE ARE IN ONE FILE. They are the two halves of one answer
+ * and they are keyed identically; split, the day a GTK release adds a name is the day the
+ * type surface and the runtime refusal disagree about whether it exists.
+ *
+ * THE FLOOR IS THE LOAD-BEARING GATE, as it is in `emit.mts`: a reader that silently
+ * yields three rows and a generator reporting success over it look identical, and here
+ * an under-read does not fail loudly downstream — it emits a smaller vocabulary, and
+ * every name it dropped becomes `unknown-aria` at a user's call site.
+ */
+export declare function emitAccessibility(model: SurfaceModel, provenance: string, floor?: number): EmittedFile;
 /**
  * Emit the data the runtime cross-check reads.
  *

package/lib/types/generator/model.d.mts

@@ -14,6 +14,7 @@
  * of that format instead of two. Only the shape survived, which is why the file is
  * `model.mts` and no longer `surface.mts`: `surface` now names the `@girs` subpath.
  */
+import type { AriaSlot } from '../types.js';
 import type { WidgetRow } from './emit.mjs';
 export interface PropMember {
     readonly kebab: string;
@@ -75,9 +76,28 @@ export interface SurfaceModel {
     readonly closure: ReadonlyMap<string, readonly string[]>;
     /** Enum GType -> nicks, for the emitted aliases and for the runtime nick check. */
     readonly enumNicks: ReadonlyMap<string, readonly string[]>;
+    /**
+     * Bitfield GType -> member nicks, for the bitfields this surface's properties carry.
+     *
+     * Separate from `enumNicks`, because the two answer different questions and one map
+     * would hide it: an enum property takes ONE nick, so the union IS the type, while a
+     * bitfield property takes a `|`-joined SET and the union is only its members.
+     * `emit-types.mts` renders each kind accordingly.
+     */
+    readonly flagNicks: ReadonlyMap<string, readonly string[]>;
     readonly namespacesUsed: ReadonlySet<string>;
     /** Namespace -> the `@girs` package that types it, so the emitter needs no second source. */
     readonly packages: Readonly<Record<string, string>>;
+    /**
+     * ARIA name -> its table, value kind and enum, merged over every vocabulary read.
+     *
+     * Keyed by the NAME alone, not by `<table>.<name>` the way `@girs` keys it, and that
+     * is a measured property rather than a convenience: across the three tables of gtk4
+     * 4.23.3 the 53 names are distinct, so one authored key can only ever mean one slot.
+     * `girs-vocabulary.mts` re-checks it on every run, because the day GTK adds a name a
+     * second table already carries, a map would silently keep one of the two.
+     */
+    readonly aria: ReadonlyMap<string, AriaSlot>;
     /**
      * Base -> members it must not contribute, because a nearer declaration disagrees.
      *

package/lib/types/host.d.ts

@@ -21,6 +21,32 @@ export declare const isText: (node: HostNode) => node is HostText;
 export declare function materialize(el: HostElement): GObject.Object;
 export declare function setProp(el: HostElement, key: string, next: unknown, _prev?: unknown): void;
 export declare function setEventHandler(el: HostElement, prop: string, next: ((...args: unknown[]) => unknown) | null): void;
+/**
+ * The ARIA object, diffed against the one it replaces.
+ *
+ * ONE GROUPED PROP RATHER THAN 53 FLAT `aria*` ONES, and the reasons are measured rather
+ * than aesthetic. (1) TypeScript exempts every hyphen-containing JSX attribute from
+ * excess-property checking — the measurement `emit-types.mts` already records for the
+ * kebab property spellings — so a flat `aria-labell` would be accepted in silence, while a
+ * key inside a fresh object literal IS checked. (2) The ARIA names are not the widget's
+ * properties and collide with them: `label`, `orientation`, `checked`, `expanded` and
+ * `selected` are all both, and `orientation` is settable on a `GtkLabel` that implements no
+ * `GtkOrientable` at all — one object keeps the two vocabularies apart by construction
+ * instead of by prefix. (3) The other surface over this same vocabulary already spells it
+ * this way: a `.blp` author writes `accessibility { label: "…"; }` (ADR 0034). (4) `setProp`
+ * already has this shape for `layout` — a structured, non-ParamSpec prop routed to its own
+ * mechanism — so this adds one reserved key to the host, not 53.
+ *
+ * REFUSED ON THE CLASS, not on the widget: every framework builds bottom-up, so props are
+ * authored long before materialisation, and asking the instance would report
+ * `<gtk-string-list accessibility={…}>` from inside a later `materialize` rather than at the
+ * call that wrote it.
+ *
+ * The plan is built BEFORE anything is recorded, for the reason the property path states:
+ * `el.accessibility` is replayed verbatim by `replayInto`, so a refused value kept there
+ * would poison the next rebuild.
+ */
+export declare function setAccessibility(el: HostElement, next: unknown): void;
 export declare function setSlot(el: HostElement, slot: string | null): void;
 export declare function setText(node: HostText | HostAnchor, data: string): void;
 /** Vue's bulk path and React's `shouldSetTextContent`: drop children, set the sink. */

package/lib/types/index.d.ts

@@ -6,6 +6,6 @@ export { toSignalName, isEventProp } from './signals.js';
 export { constructOnlyNames, isConstructOnly, isWritable, lookupEnumNick, paramSpecs, toPropertyName, } from './props.js';
 export { assertInjective, tagOf } from './tags.js';
 export { blankReason, checkRendered, probeEnabled, runHostProbe, runHostProbeApp, shotEvidence, type CaptureWidget, type HostProbe, type HostProbeApp, type ProbeCheck, type ShotEvidence, } from './probe.js';
-export type { ElementChild, ElementChildren, JsxAttributes, RawSignalAttributes, SlotAttribute, VueAttributes, WithOnce, } from './attrs.js';
+export type { AccessibilityAttribute, ElementChild, ElementChildren, JsxAttributes, RawSignalAttributes, SlotAttribute, VueAttributes, WithOnce, } from './attrs.js';
 export { clearRegistry, hasWidget, lookupWidget, nearestRegistered, registerWidget, registerWidgets, registeredTags, } from './registry.js';
 export { ADW_DESCRIPTORS, BUILTIN_DESCRIPTORS, CURATED_DESCRIPTORS, GENERATED_PROVENANCE, GENERATED_WIDGETS, GTK_DESCRIPTORS, mergeGenerated, registerBuiltinWidgets, tableProvenance, } from './descriptors/index.js';

package/lib/types/policies.d.ts

@@ -3,6 +3,63 @@ import Gtk from 'gi://Gtk?version=4.0';
 import type { ChildPolicy, HostElement, NodePlacement, WidgetDescriptor } from './types.js';
 /** The object the PARENT addresses: a wrapper row when the policy demands one. */
 export declare function addressOf(el: HostElement): Gtk.Widget;
+/**
+ * The property a one-child slot method writes — `set_title_widget` -> `title-widget`.
+ *
+ * GTK SPELLS ONE PLACEMENT TWICE and both spellings reach the same widget:
+ * `adw_header_bar_buildable_add_child`'s `<child type="title">` branch calls
+ * `adw_header_bar_set_title_widget`, i.e. writes the `title-widget` property. An authored
+ * tree carries whichever spelling its SOURCE had — a Blueprint `[title]` bracket is the
+ * first, a `title-widget:` property-valued child the second — and `SharedTreeNode.slot`
+ * conflates the two by construction (the projection's own header records that, and that it
+ * cannot be inverted). A descriptor declaring only the buildable type would therefore refuse
+ * a placement GTK itself accepts.
+ *
+ * A CASE RULE OVER THE SETTER'S OWN NAME, never a table: an ADDER (`pack_start`,
+ * `add_top_bar`, `add_prefix`) writes no property, so such a slot answers to its buildable
+ * type alone — which is why `[start]` has no second spelling to admit.
+ */
+export declare function slotPropertyOf(method: string): string | null;
+/**
+ * Every name a policy answers to — what a refusal lists.
+ *
+ * Each declared key is followed by the property spelling it also answers to, so the order is
+ * `['start', 'title', 'title-widget', 'end']` and not the keys first. That is deliberate: a
+ * reader matching their own `slot="title-widget"` against the list finds it beside the key it
+ * resolves to, rather than in a second group they have to pair up themselves.
+ */
+export declare function slotNames(policy: ChildPolicy): string[];
+/**
+ * The DECLARED slot key an authored name asks for, or the default when it asks for nothing.
+ *
+ * EVERY read of `child.slot` in this file goes through here, so the property spelling
+ * {@link slotPropertyOf} admits is canonical everywhere at once: a placement resolved
+ * through `title-widget` and a detach resolved through `title` would otherwise be two
+ * different keys to `policy.slots[…]`, and the child would leak at unmount.
+ *
+ * THE DEFAULT IS CHECKED LIKE ANY OTHER NAME, and it is the one that has no author to
+ * blame. `defaultSlot` and `slots` are two fields of a descriptor, and an application
+ * registers descriptors of its own — nothing else in this package holds the two together.
+ * An unchecked default reaches `policy.slots[slot]` as `undefined` and the caller calls it:
+ * `TypeError: host[undefined] is not a function`, which is exactly the shape
+ * {@link errors.unknownSlot} exists to replace. Returning only keys that are IN `slots` is
+ * what makes the lookup at every call site total.
+ */
+export declare function slottedSlot(policy: Extract<ChildPolicy, {
+    kind: 'slotted';
+}>, authored: string | null | undefined, gtype: string): string;
+/**
+ * A slot the parent cannot honour is refused BY NAME, whatever its policy kind.
+ *
+ * `slotted` already refused an unknown slot; every OTHER kind read `child.slot` as nothing
+ * at all, so a name it has no destination for put the widget in the one place it does have
+ * and said nothing. That is the defect measured on a real `.blp`: an authored placement
+ * dropped, the widget on screen in the wrong container, exit 0. A `single` parent accepts
+ * the property its own setter writes (`AdwApplicationWindow` + `set_content` accepts
+ * `content`) and nothing else; `keyed` reads the slot as its page NAME, which is a
+ * destination, so it is left alone.
+ */
+export declare function refuseUnknownSlot(parent: HostElement, child: HostElement): void;
 /**
  * `Gtk.ListBox` and `Gtk.FlowBox` wrap arbitrary children; the wrap is the host's job.
  *
@@ -17,7 +74,7 @@ export declare function addressOf(el: HostElement): Gtk.Widget;
  * is that `gtk_list_box_remove` does not unwrap, so without this the child leaks behind
  * one `Gtk-WARNING` at unmount.
  */
-export declare function makeWrapper(policy: ChildPolicy, child: Gtk.Widget, slot: string | null): Gtk.Widget | null;
+export declare function makeWrapper(descriptor: WidgetDescriptor, child: Gtk.Widget, slot: string | null): Gtk.Widget | null;
 /**
  * A container the host owns that no window shows — the DOM's detached `<div>`.
  *

package/lib/types/props.d.ts

@@ -24,23 +24,28 @@ export declare const isConstructOnly: (spec: GObject.ParamSpec) => boolean;
 /** Construct-only property names of a class, in declaration order. */
 export declare function constructOnlyNames(klass: GObject.ObjectClass, gtypeName: string): string[];
 /**
- * The value a nick names on an enum GType, or undefined if it names none.
+ * The value a nick names on an enum or bitfield GType, or undefined if it names none.
  *
  * Exported for the generated surface's own check: the type surface offers a union
  * of nicks per enum, and a nick this host cannot resolve would type-check and then
  * be refused at runtime. `generated.spec.ts` resolves every emitted nick through
  * this function, so the GIR-member-to-nick spelling is measured rather than
  * assumed. Also the primitive a renderer needs for a "did you mean" diagnostic.
+ *
+ * The NAME is kept in the signature although a GType would need no lookup, because
+ * every caller has the name and not the type — the check reads it off a generated
+ * table, a renderer off `GObject.type_name(spec.value_type)`.
  */
 export declare const lookupEnumNick: (gtypeName: string, nick: string) => number | undefined;
 /**
- * The member names an installed enum registers, or `undefined` if this host has none.
+ * The member names an installed enum or bitfield registers, or `undefined` if this
+ * host has none.
  *
  * The INVERSE of {@link lookupEnumNick}, and it exists for the one question that
  * function cannot answer: a nick the vocabulary never emitted is absent from every
- * list a check could iterate, so only the host's own members can reveal it. Read off
- * the same `ENUM_NAMESPACES` table, so the two cannot disagree about where an enum
- * lives — a second copy of that list is what made `Pango` missing once already.
+ * list a check could iterate, so only the host's own members can reveal it. GJS
+ * offers no route to a `GEnumClass`, so the members come off the namespace object —
+ * which is the whole remaining reason {@link GI_NAMESPACES} exists.
  *
  * `$gtype` and anything non-numeric are not members; GJS puts both on the same object.
  */

package/lib/types/react-jsx-runtime.d.ts

@@ -33,7 +33,7 @@
  */
 import type { Key, ReactElement, ReactNode, Ref } from 'react';
 import type { WidgetClassByTag, WidgetPropsByTag } from './generated/props.js';
-import type { RawSignalAttributes, SlotAttribute, WithOnce, WithPortableValues } from './attrs.js';
+import type { AccessibilityAttribute, RawSignalAttributes, SlotAttribute, WithOnce, WithPortableValues } from './attrs.js';
 export { Fragment } from 'react/jsx-runtime';
 /**
  * React's own factories, RE-TYPED over this package's element list.
@@ -67,7 +67,7 @@ type GtkJsxDevFactory = (type: GtkElementType, props: unknown, key: Key | undefi
  * element TS2559. `children` must also be optional, or a self-closing tag is
  * TS2741.
  */
-export interface ReactWidgetAttributes<T> extends SlotAttribute, RawSignalAttributes {
+export interface ReactWidgetAttributes<T> extends AccessibilityAttribute, SlotAttribute, RawSignalAttributes {
     children?: ReactNode;
     ref?: Ref<T> | undefined;
     key?: Key | null | undefined;

package/lib/types/types.d.ts

@@ -1,5 +1,6 @@
 import type GObject from '@girs/gobject-2.0';
 import type Gtk from '@girs/gtk-4.0';
+import type { AriaValueType } from '@girs/gtk-4.0/vocabulary';
 export type NodeKind = 'element' | 'text' | 'anchor';
 export interface HostNodeBase {
     readonly kind: NodeKind;
@@ -50,6 +51,15 @@ export interface HostElement extends HostNodeBase {
     listeners: Map<string, (...args: unknown[]) => unknown>;
     /** Positional data for `coords` parents (`Gtk.Grid`), read off the child. */
     layout: Record<string, unknown> | null;
+    /**
+     * The authored ARIA object, or null — the accessibility GTK holds for this widget.
+     *
+     * A field of its own and NOT a key in `props`, for the reason `layout` is one: `props`
+     * is replayed into `g_object_new` by `materialize`, and none of these names is a
+     * construct property. It is the LAST authored value, so a patch can compute which
+     * slots the new object no longer sets and reset exactly those.
+     */
+    accessibility: Record<string, unknown> | null;
     /** True once text CHILDREN wrote the sink, so removing the last one clears it
      *  instead of leaving the stale string an authored prop never set. */
     textFromChildren: boolean;
@@ -452,3 +462,45 @@ export interface WidgetDescriptor {
      */
     readonly requiresProps?: readonly string[];
 }
+/**
+ * The three enums whose MEMBERS are GTK's ARIA names.
+ *
+ * `GtkAccessibleProperty`, `GtkAccessibleState` and `GtkAccessibleRelation` are three
+ * tables and three calls — `update_property`, `update_state`, `update_relation` — and
+ * which name belongs to which is GTK's answer, never ours. The runtime derives the call
+ * from this string, which is why a fourth table is refused at generation time rather
+ * than emitted: a call that does not exist is a `TypeError` inside a render.
+ */
+export type AriaTable = 'GtkAccessibleProperty' | 'GtkAccessibleRelation' | 'GtkAccessibleState';
+/**
+ * One ARIA slot: the table it lives in, and the kind of value GTK collects for it.
+ *
+ * WHY THIS EXISTS AT ALL, and why it is not a ParamSpec. An ARIA slot is not a GObject
+ * property and never can be: `gtk_accessible_update_property()` takes a `GValue` the
+ * CALLER builds, and GTK reads it back with a fixed `g_value_get_*` per slot. There is
+ * nothing on the object to interrogate — so the type this table carries is the only
+ * thing standing between an authored value and the measured failure below.
+ *
+ * MEASURED on gjs 1.88.1 / GTK 4.22.5, one process per line. GJS guesses a GValue type
+ * from the JS value, and the guess is made on the value's INTEGRALITY:
+ *
+ *     update_property([VALUE_NOW], [3])       g_value_get_double: G_VALUE_HOLDS_DOUBLE failed
+ *     update_property([LEVEL], [3.5])         g_value_get_int:    G_VALUE_HOLDS_INT failed
+ *     update_property([SORT], ['ascending'])  g_value_get_int:    G_VALUE_HOLDS_INT failed
+ *     update_state([CHECKED], [true])         g_value_get_int:    G_VALUE_HOLDS_INT failed
+ *
+ * Every one of those is a CRITICAL at exit 0 with the slot left unset — the silent
+ * mis-store this package exists to refuse — and the last is the one a DOM author writes
+ * first, because `checked` is a `GtkAccessibleTristate` and not a boolean.
+ */
+export interface AriaSlot {
+    /**
+     * The table this name lives in. The NAME itself is the key the slot is stored under —
+     * kebab, as GTK spells the enum nick (`has-popup`, `row-index`) — and is deliberately
+     * not repeated in the row: a second copy of a map key is a second thing to keep in step.
+     */
+    readonly table: AriaTable;
+    readonly kind: AriaValueType;
+    /** `kind: 'enum'` only — the GType whose nicks the value takes. */
+    readonly enumGType?: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/gtk-host",
-    "version": "0.51.1",
+    "version": "0.52.0",
     "description": "Framework-agnostic GTK4/Adwaita host: the element model UI-framework renderers bind to",
     "type": "module",
     "module": "lib/esm/index.js",
@@ -82,7 +82,8 @@
         "test:gjs-on-node": "gjsify run build:gjsify && gjsify run build:test:node && node dist/test.node.mjs",
         "generate": "gjsify build src/generator/main.mts --app gjs --outfile tmp/generate.gjs.mjs && gjsify run tmp/generate.gjs.mjs -- --out src/generated && gjsify format src/generated",
         "generate:enum-values": "gjs -m ../../../scripts/generate-enum-values.mjs",
-        "generate:methods": "gjs -m ../../../scripts/generate-widget-methods.mjs"
+        "generate:methods": "gjs -m ../../../scripts/generate-widget-methods.mjs",
+        "generate:value-types": "gjs -m ../../../scripts/generate-value-types.mjs"
     },
     "keywords": [
         "gjs",
@@ -92,16 +93,16 @@
         "host"
     ],
     "dependencies": {
-        "@girs/adw-1": "5.0.0",
-        "@girs/gdk-4.0": "5.0.0",
-        "@girs/gio-2.0": "5.0.0",
-        "@girs/gjs": "5.0.0",
-        "@girs/glib-2.0": "5.0.0",
-        "@girs/gobject-2.0": "5.0.0",
-        "@girs/gtk-4.0": "5.0.0",
-        "@girs/pango-1.0": "5.0.0",
-        "@girs/pangocairo-1.0": "5.0.0",
-        "@gjsify/adwaita-core": "^0.51.1"
+        "@girs/adw-1": "5.4.0",
+        "@girs/gdk-4.0": "5.4.0",
+        "@girs/gio-2.0": "5.4.0",
+        "@girs/gjs": "5.4.0",
+        "@girs/glib-2.0": "5.4.0",
+        "@girs/gobject-2.0": "5.4.0",
+        "@girs/gtk-4.0": "5.4.0",
+        "@girs/pango-1.0": "5.4.0",
+        "@girs/pangocairo-1.0": "5.4.0",
+        "@gjsify/adwaita-core": "^0.52.0"
     },
     "peerDependencies": {
         "@vue/runtime-core": "^3.5.0",
@@ -124,10 +125,10 @@
         }
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.51.1",
+        "@gjsify/cli": "^0.52.0",
         "@vue/runtime-core": "^3.5.0",
         "solid-js": "^1.9.0",
-        "@gjsify/unit": "^0.51.1",
+        "@gjsify/unit": "^0.52.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3",
         "@gjsify/node-gi": "file:../../node-gi/node-gi",
@@ -136,7 +137,8 @@
         "react": "^19.2.0",
         "react-reconciler": "^0.33.0",
         "@types/react": "^19.2.2",
-        "@types/react-reconciler": "^0.33.0"
+        "@types/react-reconciler": "^0.33.0",
+        "@girs/girepository-3.0": "5.4.0"
     },
     "gjsify": {
         "runtimes": {