@gjsify/gtk-host 0.51.1 → 0.52.0

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

@@ -1,5 +1,7 @@
 export { describeLogRecord, installDiagnosticsGate, isEnvironmentDiagnostic, type DiagnosticsGate, } from './diagnostics.js';
 export { windowChromeCensus, windowChromeProblems, type WindowChromeCensus } from './window-chrome.js';
+export { buildSharedTree } from './shared-tree-builder.js';
+export { installAccessibilityBackend, withAtContext } from './at-context.js';
 import type Gtk from '@girs/gtk-4.0';
 import type { ChildPolicy, HostElement, NodePlacement, WidgetDescriptor } from '../types.js';
 /** Every method name a policy names, so the check does not have to know the shapes. */

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

@@ -0,0 +1,26 @@
+/** What GObject must end up holding, or the refusal that must reach the caller. */
+export type NickOutcome = {
+    readonly holds: number;
+} | {
+    readonly refuses: string;
+};
+export interface NickVector {
+    /** What this row is about — a failing row prints it. */
+    readonly what: string;
+    readonly tag: string;
+    /** Kebab, as GObject knows the property. */
+    readonly prop: string;
+    /** What a template, a JSX file or a renderer writes. */
+    readonly authored: string | number;
+    readonly outcome: NickOutcome;
+}
+/**
+ * Every edge of nick resolution, against four bitfields and three enums.
+ *
+ * MORE THAN ONE BITFIELD TYPE ON PURPOSE. `GtkInputHints` alone would prove the
+ * parser and nothing about the JOIN that finds it: the type surface reaches a
+ * bitfield through `PROP_ENUMS`, keyed by the DECLARING type, so a property inherited
+ * from an interface (`GtkEditable`) and one declared on the class itself take
+ * different routes to the same answer.
+ */
+export declare const NICK_VECTORS: readonly NickVector[];

package/lib/types/conformance/shared-tree-builder.d.ts

@@ -0,0 +1,26 @@
+import type { SharedTreeNode } from '@gjsify/adwaita-core/conformance';
+import type { HostElement } from '../types.js';
+/**
+ * A `SharedTreeNode`, realised: a tag, its authored properties, its placement, its children,
+ * in that order.
+ *
+ * Recursive and total — no tag list, no property list, no per-block case. The authored
+ * property NAMES go to `setProp` verbatim (through `createElement`), which is the point:
+ * `buttonLabel` reaching `button-label` is the host's own coercion, and a caller spelling the
+ * GObject name itself would be testing its own translation table instead of this one's.
+ *
+ * `built` COLLECTS THE ELEMENTS THIS CALL CREATED, in authored order, for a caller that has to
+ * tell them from the widgets libadwaita built AROUND them. Filtering a realised tree by CLASS
+ * cannot: the moment a corpus block authored a `GtkButton`, `AdwEntryRow`'s own apply button
+ * answered to the same name and the walk read one node too many. Identity is the only filter
+ * that stays right as the corpus grows, and only the builder knows it.
+ *
+ * THE SLOT GOES THROUGH THE SAME DOOR, and it is not a table here either. `setProp(el,
+ * 'slot', …)` is `setSlot`, and every framework adapter in this package already writes a
+ * `slot=` attribute through it; placement is then the parent descriptor's `ChildPolicy`,
+ * which refuses a name the parent has no destination for BY NAME. This builder read `tag`,
+ * `props` and `children` and dropped `slot` silently until a real `.blp` authored one — a
+ * `[top]` header bar landed in the content and the window title was then discarded by the
+ * bar's own construction, at exit 0.
+ */
+export declare function buildSharedTree(node: SharedTreeNode, built?: HostElement[]): HostElement;

package/lib/types/errors.d.ts

@@ -35,6 +35,38 @@ export declare const err: {
      */
     listModelMismatch: (tag: string, prop: string, gtypeName: string) => GtkHostError;
     badAdjustment: (tag: string, prop: string, got: string) => GtkHostError;
+    /**
+     * The `accessibility` prop given something that is not an object of ARIA names.
+     *
+     * One grouped prop, so the shape of the value is the first thing that can be wrong —
+     * and a string or an array would reach `Object.entries` and produce refusals about
+     * index names rather than about the prop.
+     */
+    badAccessibility: (tag: string, got: string) => GtkHostError;
+    unknownAria: (tag: string, name: string) => GtkHostError;
+    /**
+     * An ARIA name the SHIPPED table has and the INSTALLED GTK does not.
+     *
+     * The same version-gap question the generated widget table answers with `SINCE`, on the
+     * one axis where GTK's own failure is worst: `update_property` with an out-of-range
+     * member emits `gtk_accessible_value_collect_for_property_value: assertion failed`, then
+     * `gtk_accessible_attribute_set_remove: assertion failed`, and exits 0 (measured).
+     */
+    ariaNotInstalled: (tag: string, name: string, table: string) => GtkHostError;
+    badAriaValue: (tag: string, name: string, wants: string, got: string) => GtkHostError;
+    badAriaEnum: (tag: string, name: string, nick: string, gtypeName: string) => GtkHostError;
+    /**
+     * A relation whose value is another widget — the one part of GTK's ARIA surface this
+     * host cannot express, named rather than half-built.
+     *
+     * `Gtk.AccessibleList.new_from_list([widget])` builds exactly the value GTK wants, so
+     * the MARSHALLING is not what is missing: the ADDRESSING is. This host has no `id` prop,
+     * and `ref` is resolved by each framework AFTER the props of the element that names it
+     * are applied — so a ref read at this point is null on the render that authored it, and
+     * GTK takes a null reference at exit 0.
+     */
+    ariaReference: (tag: string, name: string) => GtkHostError;
+    notAccessible: (tag: 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;
@@ -54,10 +86,38 @@ export declare const err: {
     eventModifier: (prop: string, modifier: string) => GtkHostError;
     badString: (tag: string, prop: string, got: string) => GtkHostError;
     badBoolean: (tag: string, prop: string, value: string) => GtkHostError;
+    /**
+     * A MEMBER of a flags value that names nothing — not the value as a whole.
+     *
+     * This used to refuse every string on a flags property, because resolving a nick
+     * set was nothing GObject exposed. GTK's `.ui` parser does resolve one, so what is
+     * left to refuse is the typo inside a set that otherwise reads fine, and the
+     * message has to name the SET as well as the type: `"spellcheck|lowecase"` fails
+     * on one member, and reporting only the type sends a reader looking at the wrong
+     * half of their own string.
+     */
     badFlags: (tag: string, prop: string, value: string, gtypeName: string) => GtkHostError;
-    unresolvableEnum: (gtypeName: string) => GtkHostError;
+    /**
+     * The one flags input GTK's own parser answers SILENTLY, so this host does not.
+     *
+     * Measured on GTK 4.22.4: `""` and `" "` both parse to `[true, 0]`, and a leading
+     * empty member is dropped without a word. Zero is a legal flags value, so the
+     * caller gets every flag cleared, no diagnostic and exit 0 — while `"a||b"` and
+     * `"a|"` do raise. Refusing all of them by one name keeps the stray separator a
+     * spelling mistake rather than a value.
+     */
+    blankFlags: (tag: string, prop: string, value: string, gtypeName: string) => GtkHostError;
     textNotAccepted: (tag: string, text: string) => GtkHostError;
     unclaimedChild: (parentTag: string, childTag: string) => GtkHostError;
+    /**
+     * A placement the parent has no destination for.
+     *
+     * The EMPTY case is the common one and it used to print `Known slots: .` — `ordered`,
+     * `indexed` and `none` parents declare no slot names at all, and those are exactly the
+     * parents a stray `slot=` lands on. A reader needs "this parent has none" to act; a
+     * trailing full stop after nothing reads like the message was cut off. Both other
+     * renderers already spell it out, so this is also what makes the three agree.
+     */
     unknownSlot: (parentTag: string, slot: string, known: string[]) => GtkHostError;
     /**
      * An adder-backed slot with nothing that takes the child back out.

package/lib/types/font-dir.d.ts

@@ -54,9 +54,11 @@ export declare function resolveFontSources(options?: ResolveFontSourcesOptions):
  * which is the only party that knows whether the payload became `/usr`, a `--prefix` tree, `/app`,
  * a bundle's `Contents/Resources` or a Windows program directory.
  *
- * There is NO system fallback, and that is the one place this parts company with
- * `resolveLocaleDir`, whose `/usr/share/locale` default is both correct and free. The analogous
- * `/usr/share/fonts` is neither: fontconfig has already scanned it, so walking it again would add
+ * There is NO system fallback, on ANY platform — where `resolveLocaleDir` keeps one for Linux,
+ * whose `/usr/share/locale` default is there both correct and free (it has none for darwin or
+ * win32, which have no such directory). The analogous
+ * `/usr/share/fonts` is correct on no platform: fontconfig has already scanned it, so walking it
+ * again would add
  * hundreds of `add_font_file` calls to every startup to arrive at families the font map holds
  * anyway. `undefined` therefore means "this application ships no faces of its own" — the ordinary
  * case, and a quiet one, because the launcher exports the variable only when it staged a face.

package/lib/types/fonts.d.ts

@@ -150,9 +150,12 @@ export interface InitFontsResult {
  * Keyed on the ERROR rather than on `process.platform`, which is the difference between a
  * capability test and a guess about who is asking. It costs no `gjsify.os` declaration (this
  * package makes no OS decision, and ADR 0018's candidate set is derived from the code that reads
- * the host), it stays right if a fontconfig-backed Pango is ever selected on darwin — the backend
- * is chosen by what is compiled in, not per platform, and `PANGOCAIRO_BACKEND=fc` selects one — and
- * it stays right for any other map that declines. The OS name was never the thing being asked.
+ * the host), and it stays right for any other map that declines. The OS name was never the thing
+ * being asked — which stopped being hypothetical: the backend is whichever one is selected rather
+ * than one per platform, and `@gjsify/node-gi`'s loader selects `PANGOCAIRO_BACKEND=fc` on the
+ * bundled windowing runtime (ADR 0038 § Amendment 3), so a darwin process on it reaches this
+ * arm's other side and REGISTERS the faces. A `process.platform` branch would have had to be
+ * found and reversed instead.
  */
 export declare function isUnsupportedByFontMap(error: unknown): boolean;
 /**

package/lib/types/generated/accessibility.d.ts

@@ -0,0 +1,208 @@
+import type Gtk from '@girs/gtk-4.0';
+import type { AriaSlot } from '../types.js';
+import type { GtkAccessibleAutocompleteNick, GtkAccessibleInvalidStateNick, GtkAccessibleSortNick, GtkAccessibleTristateNick, GtkOrientationNick } from './props.js';
+/**
+ * ARIA name -> the table it belongs to and the kind of value GTK collects for it.
+ *
+ * Keyed by the NAME alone: across the three tables of this GTK the names are distinct,
+ * and `girs-vocabulary.mts` fails the generation rather than emit a map that silently
+ * kept one of two. The table name is what the runtime derives its GTK call from.
+ */
+export declare const ARIA_SLOTS: Readonly<Record<string, AriaSlot>>;
+/**
+ * What `accessibility={{ … }}` accepts.
+ *
+ * ONE OBJECT PROP, NOT 53 FLAT ONES, and the decision is measured rather than
+ * stylistic. Measured in this repo's own type surface: TypeScript exempts every
+ * hyphen-containing JSX attribute from excess-property checking, so a flat `aria-labell`
+ * would be accepted in silence, while a key inside a FRESH object literal is checked —
+ * `accessibility={{ labell: 'x' }}` is TS2561, naming the key and suggesting `label`. A grouped
+ * prop is also the spelling the other surface over this same vocabulary has: a `.blp` author
+ * writes `accessibility { label: "…"; }`, and ADR 0034 exists so two surfaces over one
+ * vocabulary do not invent two spellings for one name.
+ *
+ * KEBAB, THE SPELLING GTK ITSELF USES. A second camelCase spelling would double the
+ * surface for nothing: unlike a JSX attribute, a quoted key in an object literal IS
+ * excess-property checked, so the one spelling already catches the typo.
+ *
+ * `null` clears a slot, as it does for every property on this host — `gtk_accessible_reset_*`
+ * is what GTK offers and what the host calls.
+ */
+export interface AccessibilityAttributes {
+    /**
+     * `GtkAccessibleRelation.active-descendant` — a REFERENCE to another widget, and this host has no way
+     * to name one. There is no `id` prop and `ref` is resolved by the framework after the
+     * props are applied, so the value would be `null` on the render that authors it. Declared
+     * and unwritable rather than absent: GTK has this name, the gap is ours.
+     */
+    'active-descendant'?: never;
+    /** `GtkAccessibleProperty.autocomplete` — a GtkAccessibleAutocomplete, which GTK collects as an int: the nick or the constant. */
+    autocomplete?: GtkAccessibleAutocompleteNick | Gtk.AccessibleAutocomplete | null;
+    /** `GtkAccessibleState.busy` — GTK collects it as a boolean. */
+    busy?: boolean | null;
+    /** `GtkAccessibleState.checked` — a GtkAccessibleTristate, which GTK collects as an int: the nick or the constant. */
+    checked?: GtkAccessibleTristateNick | Gtk.AccessibleTristate | null;
+    /** `GtkAccessibleRelation.col-count` — GTK collects it as an integer. */
+    'col-count'?: number | null;
+    /** `GtkAccessibleRelation.col-index` — GTK collects it as an integer. */
+    'col-index'?: number | null;
+    /** `GtkAccessibleRelation.col-index-text` — GTK collects it as a string. */
+    'col-index-text'?: string | null;
+    /** `GtkAccessibleRelation.col-span` — GTK collects it as an integer. */
+    'col-span'?: number | null;
+    /**
+     * `GtkAccessibleRelation.controlled-by` — a REFERENCE to another widget, and this host has no way
+     * to name one. There is no `id` prop and `ref` is resolved by the framework after the
+     * props are applied, so the value would be `null` on the render that authors it. Declared
+     * and unwritable rather than absent: GTK has this name, the gap is ours.
+     */
+    'controlled-by'?: never;
+    /**
+     * `GtkAccessibleRelation.controls` — a REFERENCE to another widget, and this host has no way
+     * to name one. There is no `id` prop and `ref` is resolved by the framework after the
+     * props are applied, so the value would be `null` on the render that authors it. Declared
+     * and unwritable rather than absent: GTK has this name, the gap is ours.
+     */
+    controls?: never;
+    /**
+     * `GtkAccessibleRelation.described-by` — a REFERENCE to another widget, and this host has no way
+     * to name one. There is no `id` prop and `ref` is resolved by the framework after the
+     * props are applied, so the value would be `null` on the render that authors it. Declared
+     * and unwritable rather than absent: GTK has this name, the gap is ours.
+     */
+    'described-by'?: never;
+    /** `GtkAccessibleProperty.description` — GTK collects it as a string. */
+    description?: string | null;
+    /**
+     * `GtkAccessibleRelation.description-for` — a REFERENCE to another widget, and this host has no way
+     * to name one. There is no `id` prop and `ref` is resolved by the framework after the
+     * props are applied, so the value would be `null` on the render that authors it. Declared
+     * and unwritable rather than absent: GTK has this name, the gap is ours.
+     */
+    'description-for'?: never;
+    /**
+     * `GtkAccessibleRelation.details` — a REFERENCE to another widget, and this host has no way
+     * to name one. There is no `id` prop and `ref` is resolved by the framework after the
+     * props are applied, so the value would be `null` on the render that authors it. Declared
+     * and unwritable rather than absent: GTK has this name, the gap is ours.
+     */
+    details?: never;
+    /**
+     * `GtkAccessibleRelation.details-for` — a REFERENCE to another widget, and this host has no way
+     * to name one. There is no `id` prop and `ref` is resolved by the framework after the
+     * props are applied, so the value would be `null` on the render that authors it. Declared
+     * and unwritable rather than absent: GTK has this name, the gap is ours.
+     */
+    'details-for'?: never;
+    /** `GtkAccessibleState.disabled` — GTK collects it as a boolean. */
+    disabled?: boolean | null;
+    /**
+     * `GtkAccessibleRelation.error-message` — a REFERENCE to another widget, and this host has no way
+     * to name one. There is no `id` prop and `ref` is resolved by the framework after the
+     * props are applied, so the value would be `null` on the render that authors it. Declared
+     * and unwritable rather than absent: GTK has this name, the gap is ours.
+     */
+    'error-message'?: never;
+    /**
+     * `GtkAccessibleRelation.error-message-for` — a REFERENCE to another widget, and this host has no way
+     * to name one. There is no `id` prop and `ref` is resolved by the framework after the
+     * props are applied, so the value would be `null` on the render that authors it. Declared
+     * and unwritable rather than absent: GTK has this name, the gap is ours.
+     */
+    'error-message-for'?: never;
+    /** `GtkAccessibleState.expanded` — GTK collects it as a boolean. */
+    expanded?: boolean | null;
+    /**
+     * `GtkAccessibleRelation.flow-from` — a REFERENCE to another widget, and this host has no way
+     * to name one. There is no `id` prop and `ref` is resolved by the framework after the
+     * props are applied, so the value would be `null` on the render that authors it. Declared
+     * and unwritable rather than absent: GTK has this name, the gap is ours.
+     */
+    'flow-from'?: never;
+    /**
+     * `GtkAccessibleRelation.flow-to` — a REFERENCE to another widget, and this host has no way
+     * to name one. There is no `id` prop and `ref` is resolved by the framework after the
+     * props are applied, so the value would be `null` on the render that authors it. Declared
+     * and unwritable rather than absent: GTK has this name, the gap is ours.
+     */
+    'flow-to'?: never;
+    /** `GtkAccessibleProperty.has-popup` — GTK collects it as a boolean. */
+    'has-popup'?: boolean | null;
+    /** `GtkAccessibleProperty.help-text` — GTK collects it as a string. */
+    'help-text'?: string | null;
+    /** `GtkAccessibleState.hidden` — GTK collects it as a boolean. */
+    hidden?: boolean | null;
+    /** `GtkAccessibleState.invalid` — a GtkAccessibleInvalidState, which GTK collects as an int: the nick or the constant. */
+    invalid?: GtkAccessibleInvalidStateNick | Gtk.AccessibleInvalidState | null;
+    /** `GtkAccessibleProperty.key-shortcuts` — GTK collects it as a string. */
+    'key-shortcuts'?: string | null;
+    /** `GtkAccessibleProperty.label` — GTK collects it as a string. */
+    label?: string | null;
+    /**
+     * `GtkAccessibleRelation.label-for` — a REFERENCE to another widget, and this host has no way
+     * to name one. There is no `id` prop and `ref` is resolved by the framework after the
+     * props are applied, so the value would be `null` on the render that authors it. Declared
+     * and unwritable rather than absent: GTK has this name, the gap is ours.
+     */
+    'label-for'?: never;
+    /**
+     * `GtkAccessibleRelation.labelled-by` — a REFERENCE to another widget, and this host has no way
+     * to name one. There is no `id` prop and `ref` is resolved by the framework after the
+     * props are applied, so the value would be `null` on the render that authors it. Declared
+     * and unwritable rather than absent: GTK has this name, the gap is ours.
+     */
+    'labelled-by'?: never;
+    /** `GtkAccessibleProperty.level` — GTK collects it as an integer. */
+    level?: number | null;
+    /** `GtkAccessibleProperty.modal` — GTK collects it as a boolean. */
+    modal?: boolean | null;
+    /** `GtkAccessibleProperty.multi-line` — GTK collects it as a boolean. */
+    'multi-line'?: boolean | null;
+    /** `GtkAccessibleProperty.multi-selectable` — GTK collects it as a boolean. */
+    'multi-selectable'?: boolean | null;
+    /** `GtkAccessibleProperty.orientation` — a GtkOrientation, which GTK collects as an int: the nick or the constant. */
+    orientation?: GtkOrientationNick | Gtk.Orientation | null;
+    /**
+     * `GtkAccessibleRelation.owns` — a REFERENCE to another widget, and this host has no way
+     * to name one. There is no `id` prop and `ref` is resolved by the framework after the
+     * props are applied, so the value would be `null` on the render that authors it. Declared
+     * and unwritable rather than absent: GTK has this name, the gap is ours.
+     */
+    owns?: never;
+    /** `GtkAccessibleProperty.placeholder` — GTK collects it as a string. */
+    placeholder?: string | null;
+    /** `GtkAccessibleRelation.pos-in-set` — GTK collects it as an integer. */
+    'pos-in-set'?: number | null;
+    /** `GtkAccessibleState.pressed` — a GtkAccessibleTristate, which GTK collects as an int: the nick or the constant. */
+    pressed?: GtkAccessibleTristateNick | Gtk.AccessibleTristate | null;
+    /** `GtkAccessibleProperty.read-only` — GTK collects it as a boolean. */
+    'read-only'?: boolean | null;
+    /** `GtkAccessibleProperty.required` — GTK collects it as a boolean. */
+    required?: boolean | null;
+    /** `GtkAccessibleProperty.role-description` — GTK collects it as a string. */
+    'role-description'?: string | null;
+    /** `GtkAccessibleRelation.row-count` — GTK collects it as an integer. */
+    'row-count'?: number | null;
+    /** `GtkAccessibleRelation.row-index` — GTK collects it as an integer. */
+    'row-index'?: number | null;
+    /** `GtkAccessibleRelation.row-index-text` — GTK collects it as a string. */
+    'row-index-text'?: string | null;
+    /** `GtkAccessibleRelation.row-span` — GTK collects it as an integer. */
+    'row-span'?: number | null;
+    /** `GtkAccessibleState.selected` — GTK collects it as a boolean. */
+    selected?: boolean | null;
+    /** `GtkAccessibleRelation.set-size` — GTK collects it as an integer. */
+    'set-size'?: number | null;
+    /** `GtkAccessibleProperty.sort` — a GtkAccessibleSort, which GTK collects as an int: the nick or the constant. */
+    sort?: GtkAccessibleSortNick | Gtk.AccessibleSort | null;
+    /** `GtkAccessibleProperty.value-max` — GTK collects it as a double. */
+    'value-max'?: number | null;
+    /** `GtkAccessibleProperty.value-min` — GTK collects it as a double. */
+    'value-min'?: number | null;
+    /** `GtkAccessibleProperty.value-now` — GTK collects it as a double. */
+    'value-now'?: number | null;
+    /** `GtkAccessibleProperty.value-text` — GTK collects it as a string. */
+    'value-text'?: string | null;
+    /** `GtkAccessibleState.visited` — GTK collects it as a boolean. */
+    visited?: boolean | null;
+}

package/lib/types/generated/enum-values.d.mts

@@ -5,7 +5,7 @@
  * A value, not only a header comment: `generated.spec.ts` compares it with the
  * running library to decide whether a disagreement is a defect or a version gap.
  */
-export declare const VALUES_PROVENANCE = "Adw-1/1.9.3 Gtk-4.0/4.22.4 Pango-1.0/1.57.1";
+export declare const VALUES_PROVENANCE = "Adw-1/1.9.3 Gio-2.0 Gtk-4.0/4.22.4 Pango-1.0/1.57.1";
 /** `<enum GType>.<nick>` -> the integer the library registers for it. */
 export declare const ENUM_VALUES: Readonly<Record<string, number>>;
 /**