@gjsify/gtk-host 0.41.0 → 0.44.0

package/lib/types/attrs.d.ts

@@ -0,0 +1,102 @@
+import type GObject from '@girs/gobject-2.0';
+import type { HostNode } from './types.js';
+/**
+ * A `notify::` handler.
+ *
+ * The host strips the emitting object (`next(...args.slice(1))` in `signals.ts`),
+ * so what reaches the callback is the ParamSpec alone. Declared HERE rather than in
+ * the generated file because it is the same for every property in GTK — and because
+ * a generator that emitted it would have to import GObject for a type that has
+ * nothing to do with the GIR it read.
+ */
+export type NotifyHandler = (pspec: GObject.ParamSpec) => void;
+declare const outParam: unique symbol;
+/**
+ * A signal parameter GIR declares `out`/`inout` with `caller-allocates="0"`.
+ *
+ * GJS still passes an argument in that position, and what it holds is whatever
+ * was in the memory the marshaller allocated: measured on gjs 1.88.1 / GTK
+ * 4.22.4, a handler on `Gtk.SpinButton::input` receives `new_value` as
+ * `6.9526682391035e-310`, and one on `Gtk.Editable::insert-text` receives
+ * `position` as `1711500784`. Both arrive as ordinary numbers. Nothing warns.
+ *
+ * So the slot is DECLARED — dropping it would silently shift every parameter
+ * after it — and given a type nothing can be read out of, and nothing but
+ * itself assigns to. Annotating the parameter `number` is then a compile error
+ * naming the position, which is the only place a reader would have looked.
+ *
+ * `caller-allocates="1"` is a different thing and keeps its real type: there the
+ * callee is handed a live object to FILL, as `Gtk.Overlay::get-child-position`
+ * is handed a `Gdk.Rectangle`.
+ */
+export type OutParam = {
+    readonly [outParam]: never;
+};
+/**
+ * What may appear as a child, mirroring Solid's own `JSX.Element`.
+ *
+ * The shape is copied from `solid-js/types/jsx.d.ts` because a renderer's element
+ * union is not a free choice: a string, a number and a boolean are all legal
+ * children there, an array of children is legal recursively, and a FUNCTION is
+ * not. Substituting our host node for the DOM's `Node` is the only change.
+ */
+export type ElementChild = HostNode | ElementChildren | string | number | boolean | null | undefined;
+export interface ElementChildren extends Array<ElementChild> {
+}
+/**
+ * Add the `.once` spelling of every event prop, without generating 2× the members.
+ *
+ * `signals.ts` accepts `onClickedOnce` for every `onClicked`, including every
+ * `onNotifyFooOnce`, which would be another ~1000 generated members. A mapped type
+ * derives them from the interface instead — including the ones a consumer adds by
+ * declaration merging.
+ */
+export type WithOnce<T> = T & {
+    [K in keyof T & string as K extends `on${string}` ? `${K}Once` : never]?: T[K];
+};
+/** Which of a container's slots this child goes into. Read by `setSlot()`. */
+export interface SlotAttribute {
+    slot?: string | null;
+}
+/**
+ * The `on:<raw-signal-name>` escape hatch, typed.
+ *
+ * `parseEventProp` takes `on:` + a signal name verbatim, which is how a signal
+ * whose name resists the camelCase derivation gets bound at all. The handler type
+ * is deliberately the widest one that is not `any`: parameters of `never` accept
+ * a handler declared with any parameters, so nothing a consumer writes is refused.
+ * An inline arrow's parameter arrives as `never` here, which is the price of an
+ * escape hatch that carries no signal-specific knowledge.
+ */
+export interface RawSignalAttributes {
+    [key: `on:${string}`]: ((...args: never[]) => unknown) | undefined;
+}
+/**
+ * Per-element attributes a JSX dialect needs on top of the GObject properties.
+ *
+ * `ref` and `children` MUST be real members of the element's own props. Measured:
+ * TypeScript unions `JSX.IntrinsicAttributes` into the attributes of a COMPONENT
+ * and not of an intrinsic element, so a `ref` that is not declared here is
+ * rejected outright (TS2322) — and `children` that is not declared makes every
+ * nested element an error (TS2559). `children` must also be OPTIONAL: a required
+ * one makes `<gtk-box/>` an error (TS2741).
+ *
+ * `T` is the widget's own instance type, so `ref={(el) => …}` infers `el` as
+ * `Gtk.Box` rather than the `unknown` a DOM renderer settles for.
+ */
+export interface JsxAttributes<T> extends SlotAttribute, RawSignalAttributes {
+    children?: ElementChild;
+    ref?: T | ((el: T) => void) | undefined;
+}
+/**
+ * Per-element attributes for Vue.
+ *
+ * Deliberately NOT `JsxAttributes`: Vue supplies `ref` and `key` itself through
+ * `VNodeProps`, which every registered component's props are intersected with.
+ * Declaring our own `ref` would intersect two different `ref` types and could
+ * leave the property unusable, so the Vue surface adds only what Vue does not —
+ * and `children` is a SLOT in Vue, never a prop.
+ */
+export interface VueAttributes extends SlotAttribute, RawSignalAttributes {
+}
+export {};

package/lib/types/buildable.spec.d.ts

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

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

@@ -1,10 +1,20 @@
 export interface DiagnosticsGate {
-    /** Warning-or-worse messages seen since the last `reset()`. */
+    /** Warning-or-worse messages ABOUT THE TREE, seen since the last `reset()`. */
     readonly seen: readonly string[];
+    /**
+     * Warning-or-worse messages about the HOST's graphics stack, kept apart.
+     *
+     * Recorded rather than dropped: `assertQuiet` names the count so a run is
+     * never quietly forgiven, and a caller that genuinely wants to assert on the
+     * environment can read them.
+     */
+    readonly environment: readonly string[];
     reset(): void;
-    /** Throw if anything was recorded, naming every message. */
+    /** Throw if anything about the tree was recorded, naming every message. */
     assertQuiet(context?: string): void;
 }
+/** Whether `message` describes the host's graphics stack rather than the tree. */
+export declare function isEnvironmentDiagnostic(message: string): boolean;
 /**
  * Install the writer func once per process and return the gate.
  *
@@ -14,4 +24,18 @@ export interface DiagnosticsGate {
  * what GLib's default writer does with `G_MESSAGES_DEBUG` unset: message-and-above
  * is printed, info/debug is not.
  */
+/**
+ * What a log record SAYS — and never the empty string.
+ *
+ * `MESSAGE` is a structured field like any other, and a record is allowed to
+ * arrive without one. The first version answered `String(raw ?? '')`, so such a
+ * record was counted and then described as nothing: a CI run failed with
+ * `GTK reported 1 diagnostic(s) that would have passed at exit 0:` followed by a
+ * BLANK LIST, over a test that had just constructed 164 widgets. A gate that can
+ * count a failure but not name it sends the reader back to guessing, which is the
+ * state this whole module exists to end.
+ *
+ * So a record with no `MESSAGE` is rendered from the fields it does carry.
+ */
+export declare function describeLogRecord(fields: unknown, decoder?: TextDecoder): string;
 export declare function installDiagnosticsGate(): DiagnosticsGate;

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

@@ -1,4 +1,4 @@
-export { installDiagnosticsGate, type DiagnosticsGate } from './diagnostics.js';
+export { describeLogRecord, installDiagnosticsGate, isEnvironmentDiagnostic, type DiagnosticsGate, } from './diagnostics.js';
 import type Gtk from '@girs/gtk-4.0';
 import type { ChildPolicy, HostElement, WidgetDescriptor } from '../types.js';
 /** Every method name a policy names, so the check does not have to know the shapes. */
@@ -22,5 +22,28 @@ export declare function gtkChildren(widget: Gtk.Widget): Gtk.Widget[];
 export declare const gtkChildTypes: (widget: Gtk.Widget) => string[];
 /** The addresses a host element's element-children occupy, in shadow order. */
 export declare function addressesOf(el: HostElement): Gtk.Widget[];
+/**
+ * First STRICT descendant matching `pred`, breadth-first over the REAL GTK tree.
+ *
+ * Both showcase probes wrote this, identically. It excludes the root on purpose:
+ * every caller is asking "what did the renderer put INSIDE this", and a root that
+ * matches its own predicate answers a different question.
+ *
+ * Breadth-first is not incidental either — `findDescendant(root, w => w instanceof
+ * Gtk.Box)` on an Adwaita window finds an INTERNAL box of the header bar before
+ * anything the author wrote, which is why a probe that needs a specific widget
+ * reaches it through a landmark (a button's `get_parent()`) rather than by type.
+ * Measured: with a search-by-type version, authoring `orientation="horizontal"`
+ * still printed PROBE: PASS with byte-identical output.
+ */
+export declare function findDescendant(root: Gtk.Widget, pred: (widget: Gtk.Widget) => boolean): Gtk.Widget | null;
+/**
+ * Every widget in a subtree, ROOT FIRST and depth-first — GTK's own document order.
+ *
+ * Depth-first and not breadth-first, because the callers that collect (rather than
+ * search) are asserting on ORDER: "the rows land before the counter row" is only a
+ * claim about the tree if the walk visits it the way the tree reads.
+ */
+export declare function descendants(root: Gtk.Widget): Gtk.Widget[];
 /** Recursive GType dump — what a devtools tree walk would show. */
 export declare function dumpTree(widget: Gtk.Widget, depth?: number): string;

package/lib/types/conformance/vectors.d.mts

@@ -0,0 +1,34 @@
+import Gtk from 'gi://Gtk?version=4.0';
+import type { DiagnosticsGate } from './diagnostics.js';
+/** A tree in the one shape all three adapters can build: tag, props, children. */
+export interface VectorElement {
+    readonly tag: string;
+    readonly props?: Record<string, unknown>;
+    /** A string child is a TEXT NODE — never a bulk `setElementText` write. */
+    readonly children?: readonly VectorNode[];
+}
+export type VectorNode = string | VectorElement;
+/** `h('GtkBox', { spacing: 6 }, h('GtkLabel', null, 'hi'))`. */
+export declare const h: (tag: string, props?: Record<string, unknown> | null, ...children: VectorNode[]) => VectorElement;
+export interface VectorMount {
+    /**
+     * Re-render the SAME tree shape with new props and new text, flushed — Vue's
+     * `nextTick`, React's `flushSync`, Solid's synchronous effects.
+     */
+    patch(tree: VectorElement): Promise<void>;
+    unmount(): void;
+}
+export interface VectorHarness {
+    /** Names the describe block, so a failure says which adapter. */
+    readonly framework: string;
+    /** Mount `tree` into a container the application owns, flushed on return. */
+    mount(container: Gtk.Widget, tree: VectorElement): Promise<VectorMount>;
+}
+/**
+ * Every vector, against one adapter.
+ *
+ * `gated` rather than a bare `describe`: `@gjsify/unit` keeps ONE
+ * `beforeEach`/`afterEach` slot per module and nulls both when a describe returns,
+ * so hooks registered outside the block cover exactly one sibling.
+ */
+export declare function runAdapterVectors(harness: VectorHarness, gate: DiagnosticsGate): Promise<void>;

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

@@ -1,5 +1,56 @@
+import type { GeneratedWidget, WidgetDescriptor } from '../types.js';
 export { GTK_DESCRIPTORS } from './gtk.js';
 export { ADW_DESCRIPTORS } from './adw.js';
-export declare const BUILTIN_DESCRIPTORS: import("../types.js").WidgetDescriptor[];
+export { GENERATED_PROVENANCE, GENERATED_WIDGETS } from '../generated/widgets.js';
+/**
+ * The hand-measured table: every widget whose PLACEMENT RULE is known.
+ *
+ * Kept separate from `BUILTIN_DESCRIPTORS` because the generator's gates take it
+ * as their input. Merging first and then checking would make G1 ("every curated
+ * gtype is in the GIR") and G3 ("every method a policy names exists") trivially
+ * true — the generated rows come from the GIR by construction and name no method,
+ * so a gate fed the merged table would pass while checking nothing.
+ */
+export declare const CURATED_DESCRIPTORS: readonly WidgetDescriptor[];
+/**
+ * Construct-only properties a GType ABORTS the process without.
+ *
+ * Not an exception: `adw_layout_slot_constructed` calls `g_error()`, which is
+ * fatal by contract — no catch, no diagnostic, SIGABRT and a core dump. A table
+ * that merely LISTS such a tag hands a renderer a way to kill the process, and
+ * `descriptorProblems()` cannot see it because it never instantiates anything.
+ *
+ * MEASURED bare-constructing all 164 generated rows on gjs 1.88.1 / GTK 4.22.4 /
+ * libadwaita 1.9.3, resuming past each abort: **163 construct, one does not**, and not a
+ * single row throws. So this map is one entry rather than a policy — and
+ * `constructsEveryDescriptor` in `generated.spec.ts` is what keeps it one entry.
+ *
+ * CURATED, like every other placement fact: the GIR says `id` is construct-only
+ * and nullable, which is exactly what it says about properties that construct
+ * fine. Only running it tells them apart (ADR 0028 § 1).
+ */
+export declare const REQUIRED_CONSTRUCT_PROPS: Readonly<Record<string, readonly string[]>>;
+export declare function mergeGenerated(curated: readonly WidgetDescriptor[], generated: readonly GeneratedWidget[]): WidgetDescriptor[];
+/**
+ * Curated placement rules, plus a tag for every other widget in the GIR.
+ *
+ * The direction is one-way and enforced by shape rather than by review: a
+ * `GeneratedWidget` carries no `children`, no `textSink` and no `eventAliases`, so
+ * the generator CANNOT contradict a curated descriptor — it can only add a gtype
+ * that was not there. A generated-only row gets `children: { kind: 'uncurated' }`,
+ * which means the widget can be created, given properties and given handlers,
+ * while inserting a child into it raises an error naming the tag that needs a
+ * curated policy. Guessing an adder is the one thing not on offer: `add`, `append`
+ * and `set_child` all exist somewhere in GTK, and calling the wrong one is a
+ * warning at exit 0.
+ */
+export declare const BUILTIN_DESCRIPTORS: readonly WidgetDescriptor[];
 /** Install the built-in table. Idempotent — registration is keyed on the GType name. */
 export declare function registerBuiltinWidgets(): void;
+/** What the shipped table is made of, for a diagnostic or an about box. */
+export declare const tableProvenance: () => {
+    gir: "Gtk-4.0 Adw-1";
+    curated: number;
+    generated: number;
+    total: number;
+};

package/lib/types/errors.d.ts

@@ -16,11 +16,26 @@ export declare class GtkHostError extends Error {
 }
 export declare const err: {
     unknownTag: (tag: string) => GtkHostError;
+    missingConstructProp: (tag: string, prop: string) => GtkHostError;
     unknownProp: (tag: string, prop: string) => GtkHostError;
     readOnlyProp: (tag: string, prop: string) => GtkHostError;
     badEnum: (tag: string, prop: string, nick: string, gtypeName: string) => GtkHostError;
     unknownSignal: (tag: string, prop: string, signal: string) => GtkHostError;
     signalTaken: (tag: string, prop: string, other: string, signal: string) => GtkHostError;
+    /**
+     * A DOM event-phase modifier has no GObject translation, so it is named, not guessed.
+     *
+     * `capture` selects a phase of DOM tree propagation and a GObject signal does not
+     * propagate through a tree at all — it is emitted on ONE object. `passive` is a
+     * promise not to call `preventDefault`, which no GObject signal has. Kebabing
+     * either into the signal name produced `emits no signal "clicked-capture"`, i.e.
+     * this host blaming the user's spelling for a concept it simply does not carry.
+     *
+     * It lived in `signals.ts` as a bare `new GtkHostError` for its whole life, which
+     * made this file's claim to BE the list false: the code existed, and the only
+     * place that enumerates the codes did not know it.
+     */
+    eventModifier: (prop: string, modifier: string) => GtkHostError;
     badString: (tag: string, prop: string, got: string) => GtkHostError;
     badBoolean: (tag: string, prop: string, value: string) => GtkHostError;
     badFlags: (tag: string, prop: string, value: string, gtypeName: string) => GtkHostError;
@@ -29,5 +44,11 @@ export declare const err: {
     unclaimedChild: (parentTag: string, childTag: string) => GtkHostError;
     unknownSlot: (parentTag: string, slot: string, known: string[]) => GtkHostError;
     rejectedChild: (parentTag: string, childTag: string, reason: string) => GtkHostError;
+    uncuratedPlacement: (parentTag: string, childTag: string) => GtkHostError;
+    siblingCycle: (parentTag: string) => GtkHostError;
     notAWidget: (tag: string) => GtkHostError;
+    occupiedSlot: (parentTag: string, childTag: string, setter: string) => GtkHostError;
+    notAnElement: (kind: string) => GtkHostError;
+    destroyedNode: (tag: string) => GtkHostError;
+    notAHostParent: (got: string) => GtkHostError;
 };