@gjsify/gtk-host 0.44.0 → 0.46.0

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

@@ -1,164 +0,0 @@
-/**
- * Read the GIR XML into a plain model.
- *
- * WHY THE XML AND NOT THE TYPELIB. Both carry the structure — measured on gtk
- * 4.22.4, `GIRepository` 3.0 answers class enumeration, abstractness, properties
- * with `CONSTRUCT_ONLY`, signals, methods and property enum types, and its
- * concrete-widget set is IDENTICAL to the XML's. What the typelib does not carry,
- * and offers no API that could, is documentation, default values and
- * since-versions: it strips them by design, which is why gi-docgen reads the GIR.
- * ADR 0028 § 6 makes these surfaces a PUBLISHED artifact whose point is what a
- * consumer's editor shows on hover, so the richer input wins.
- *
- * WHY @gjsify/domparser. Measured on the 6.2 MB `Gtk-4.0.gir`: 232 ms, RSS 53 MB
- * -> 96 MB, and its `application/xml` mode is right where it has to be —
- * selectors are case-SENSITIVE (`CLASS` matches nothing), namespaced tags work
- * (`glib\:signal` -> 352), namespaced attributes work (`[glib\:type-name]` ->
- * 445). No new dependency, and a tier-1 package gets dogfooded against a real
- * 6 MB document.
- *
- * ONE FROZEN WART TO KNOW ABOUT: in XML mode `tagName` is LOWERCASED and
- * `nodeName` UPPERCASED, both wrong by the XML spec and both deliberately frozen
- * (ADR 0026 § Decision 4) because a measured consumer switches on lowercase tag
- * literals at 24 sites. Harmless here — every GIR tag is lowercase already — but
- * a generator for a mixed-case dialect could not use this reader as-is.
- */
-/**
- * A GIR type reference, with the array flag kept SEPARATE.
- *
- * Not a nicety: `<property name="css-classes"><array><type name="utf8"/></array>`
- * is `string[]`, and a reader that asked for a descendant `<type>` would answer
- * `string` — for a property authored as `cssClasses={['card']}` on every second
- * widget. `querySelector` searches descendants, so the array case has to be
- * checked FIRST, on own children only.
- */
-export interface GirType {
-    /** Qualified where GIR wrote a reference (`Gtk.Orientation`), bare for a C scalar (`gboolean`). */
-    readonly name: string;
-    readonly array: boolean;
-}
-export interface GirProperty {
-    readonly name: string;
-    readonly writable: boolean;
-    readonly readable: boolean;
-    readonly constructOnly: boolean;
-    readonly type: GirType;
-    /** GIR carries it, the typelib does not — `GTK_ORIENTATION_HORIZONTAL`. */
-    readonly defaultValue?: string;
-    readonly deprecated: boolean;
-    /** GIR's `version` attribute — the release that introduced this member. */
-    readonly since?: string;
-    readonly doc?: string;
-}
-/**
- * The GObject nick a GIR enum member would get if GIR did not say.
- *
- * GIR writes `baseline_fill`; the nick GObject registered is `baseline-fill`. This
- * is the FALLBACK for a `<member>` with no `glib:nick` — the attribute itself is
- * the answer wherever it exists, because the substitution is right for Gtk and Adw
- * by luck and not by construction: some nicks keep an underscore it would have
- * replaced, and nothing but the attribute knows which one survived.
- *
- * The count that used to sit here is now `ts-for-gir/scripts/check-nick-derivation.mjs`,
- * which owns the corpus this measures over. It also settles what looked like a
- * contradiction: this file said 97 and ts-for-gir said 889 over the SAME 705 GIRs,
- * and both were right — the derivations differ. 889 counts a fallback that also
- * lowercases, which adds the 792 members whose GIR name carries uppercase and whose
- * nick preserves it. This one does not lowercase, so 97 is its number. Quote a
- * derived-nick count without naming its derivation and you get that pair back.
- */
-export declare const nickOf: (member: string) => string;
-export interface GirParam {
-    readonly name: string;
-    readonly type: GirType;
-    /** GIR's `direction`, which defaults to `in` when the attribute is absent. */
-    readonly direction: 'in' | 'out' | 'inout';
-    /**
-     * GIR's `caller-allocates`. It decides whether a non-`in` slot holds anything
-     * at all — see `renderParam` in `surface.mts`, which is the only reader.
-     */
-    readonly callerAllocates: boolean;
-}
-export interface GirSignal {
-    readonly name: string;
-    /**
-     * WITHOUT the emitting object. GIR lists a signal's `<parameters>` free of the
-     * instance (unlike a `<method>`), and the host strips the instance too —
-     * `next(...args.slice(1))` in `signals.ts`. The two line up exactly, which is
-     * why a generated handler signature can be taken from here verbatim.
-     */
-    readonly params: readonly GirParam[];
-    readonly deprecated: boolean;
-    /** GIR's `version` attribute — the release that introduced this signal. */
-    readonly since?: string;
-    readonly doc?: string;
-}
-export interface GirClass {
-    /** The GType name — `GtkBox`. Absent for a class GIR declares without one. */
-    readonly gtype: string;
-    /** GIR-local name — `Box`. */
-    readonly name: string;
-    readonly namespace: string;
-    readonly kind: 'class' | 'interface';
-    readonly abstract: boolean;
-    /** Namespace-qualified parent — `Gtk.Widget` — or null at the root. */
-    readonly parent: string | null;
-    /** Qualified interfaces (`<implements>`), or an interface's `<prerequisite>`s. */
-    readonly implements: readonly string[];
-    readonly methods: readonly string[];
-    readonly signals: readonly GirSignal[];
-    readonly properties: readonly GirProperty[];
-    readonly doc?: string;
-}
-export interface GirEnum {
-    readonly gtype: string;
-    /** Namespace-qualified — `Gtk.Orientation`. */
-    readonly qualified: string;
-    readonly flags: boolean;
-    /** The NICKS, which is what a string-accepting surface needs. */
-    readonly members: readonly string[];
-}
-export interface GirNamespace {
-    readonly name: string;
-    readonly version: string;
-    /** Classes AND interfaces, in one list: `implements` resolves against the same index. */
-    readonly classes: readonly GirClass[];
-    readonly enums: readonly GirEnum[];
-    /** Every other named type GIR declares — records, unions, callbacks, aliases. */
-    readonly otherTypes: readonly string[];
-}
-export declare function readNamespace(xml: string): GirNamespace;
-/** Every class and interface across the namespaces read, keyed the way GIR references them. */
-export declare function indexClasses(namespaces: readonly GirNamespace[]): Map<string, GirClass>;
-/**
- * Walk to the root, or as far as the loaded namespaces reach.
- *
- * A chain that leaves the loaded set is not an error: `Gtk.Widget`'s own parent
- * is `GObject.InitiallyUnowned`, and loading GObject-2.0 to learn that would buy
- * nothing. What matters is whether `Gtk.Widget` is ON the chain.
- */
-export declare function ancestors(cls: GirClass, index: Map<string, GirClass>): GirClass[];
-/**
- * Every declaration a class's members can come from — self, ancestors, interfaces.
- *
- * The interfaces are not optional and the measurement says why: `GtkBox` declares
- * four properties of its own and `orientation` is NOT among them. It lives on
- * `Gtk.Orientable`, an `<implements>` of `GtkBox`, because GObject installs
- * interface properties on the implementor at runtime while GIR keeps them once,
- * on the interface. A class-only reader therefore emits a surface in which
- * `<gtk-box orientation="vertical">` — the most-written GtkBox attribute there is
- * — is a type error.
- *
- * Order is self, then the parent chain, then interfaces of each, so a nearer
- * declaration of the same property name wins.
- */
-export declare function declarations(cls: GirClass, index: Map<string, GirClass>): GirClass[];
-/**
- * Concrete descendants of a root class — the set a renderer can actually create.
- *
- * The root is a PARAMETER so a fixture can exercise this with a five-class GIR of
- * its own. Hard-coding `GtkWidget` would leave the walk, the abstract filter and
- * the namespace-crossing parent chain testable only against the real 6.2 MB file,
- * where an off-by-one is invisible.
- */
-export declare function concreteWidgets(namespaces: readonly GirNamespace[], root?: string): GirClass[];

package/lib/types/generator/mini.fixture.d.mts

@@ -1,30 +0,0 @@
-/**
- * A five-class GIR, so the generator is testable without the 6.2 MB one.
- *
- * Every element here earns its place by exercising a branch the real GIR cannot
- * exercise ON DEMAND:
- *
- *  - `Orientable.label` is a `gint` and `Box.label` a `utf8`, so the two bases of
- *    `MiniBoxProps` disagree and the `Omit` machinery has to fire. Measured, the
- *    real Gtk+Adw hierarchy produces ZERO such conflicts, which left that code
- *    shipped and unexercised — this is what turns it into a tested path.
- *  - `baseline_fill` is a two-word enum member, so the GIR-underscore-to-nick
- *    substitution is visible.
- *  - `css-classes` is an ARRAY of a scalar, the case a descendant `<type>` lookup
- *    gets wrong by answering `string` for `string[]`.
- *  - `locked` is readable and NOT writable, so the writable filter has something to
- *    drop.
- *  - `MiniGLThing` has two adjacent capitals, so `tagOf`'s acronym rule and the
- *    Volar-resolution gap both have a case.
- *  - `Nameless` has no `glib:type-name`, and `NotAWidget` does not descend from the
- *    root — the two reasons a class is skipped.
- *
- * Embedded as a string rather than a file: the test bundle runs under gjs from a
- * path that is not the source tree, and a fixture that cannot be found is a test
- * that silently checks nothing.
- */
-export declare const MINI_GIR = "<?xml version=\"1.0\"?>\n<repository version=\"1.2\"\n            xmlns=\"http://www.gtk.org/introspection/core/1.0\"\n            xmlns:c=\"http://www.gtk.org/introspection/c/1.0\"\n            xmlns:glib=\"http://www.gtk.org/introspection/glib/1.0\">\n  <namespace name=\"Mini\" version=\"1.0\">\n    <enumeration name=\"Align\" glib:type-name=\"MiniAlign\">\n      <member name=\"fill\" value=\"0\"/>\n      <member name=\"baseline_fill\" value=\"1\"/>\n      <!-- A nick GIR CARRIES and the substitution would get wrong. 97 members\n           across this workspace's GIRs are shaped like this. -->\n      <member name=\"two_words\" value=\"2\" glib:nick=\"renamed\"/>\n    </enumeration>\n    <bitfield name=\"StateFlags\" glib:type-name=\"MiniStateFlags\">\n      <member name=\"active\" value=\"1\"/>\n    </bitfield>\n    <record name=\"Rect\" c:type=\"MiniRect\"/>\n    <interface name=\"Orientable\" glib:type-name=\"MiniOrientable\">\n      <doc xml:space=\"preserve\">Anything with an orientation. Second sentence, dropped.</doc>\n      <property name=\"orientation\" writable=\"1\">\n        <doc xml:space=\"preserve\">Which way round it goes.</doc>\n        <type name=\"Align\"/>\n      </property>\n      <property name=\"label\" writable=\"1\">\n        <type name=\"gint\"/>\n      </property>\n    </interface>\n    <class name=\"Widget\" glib:type-name=\"MiniWidget\" abstract=\"1\" parent=\"GObject.Object\">\n      <property name=\"visible\" writable=\"1\"><type name=\"gboolean\"/></property>\n      <property name=\"css-classes\" writable=\"1\"><array><type name=\"utf8\"/></array></property>\n      <property name=\"locked\"><type name=\"gint\"/></property>\n      <property name=\"area\" writable=\"1\"><type name=\"Rect\"/></property>\n      <glib:signal name=\"destroy\"/>\n      <method name=\"show\"/>\n    </class>\n    <class name=\"Box\" glib:type-name=\"MiniBox\" parent=\"Widget\">\n      <implements name=\"Orientable\"/>\n      <property name=\"spacing\" writable=\"1\"><type name=\"gint\"/></property>\n      <property name=\"label\" writable=\"1\"><type name=\"utf8\"/></property>\n      <property name=\"old-thing\" writable=\"1\" deprecated=\"1\"><type name=\"gboolean\"/></property>\n      <glib:signal name=\"row-activated\" version=\"1.2\">\n        <parameters>\n          <parameter name=\"row\"><type name=\"Widget\"/></parameter>\n          <parameter name=\"how\"><type name=\"Align\"/></parameter>\n        </parameters>\n      </glib:signal>\n      <method name=\"append\"/>\n      <method name=\"remove\"/>\n    </class>\n    <class name=\"GLThing\" glib:type-name=\"MiniGLThing\" parent=\"Widget\">\n      <property name=\"mode\" writable=\"1\"><type name=\"Align\"/></property>\n      <property name=\"flags\" writable=\"1\"><type name=\"StateFlags\"/></property>\n    </class>\n    <class name=\"Nameless\" parent=\"Widget\"/>\n    <class name=\"NotAWidget\" glib:type-name=\"MiniNotAWidget\" parent=\"GObject.Object\"/>\n  </namespace>\n</repository>\n";
-/** The fixture's own namespace-to-package map, which the real one has no entry for. */
-export declare const MINI_PACKAGES: {
-    readonly Mini: "@girs/mini-1.0";
-};

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

@@ -1,62 +0,0 @@
-/**
- * Build the declaration graph the type surfaces are emitted from.
- *
- * ONE INTERFACE PER GIR DECLARATION, carrying its OWN members and extending its
- * bases — not one flat interface per widget. The measurement decides it: the 164
- * concrete widgets have 6768 writable property slots between them and only 561
- * distinct property names. Flattening would emit the same `visible?: boolean`
- * 164 times; mirroring GIR's own inheritance emits it once, on `GtkWidgetProps`,
- * and the diff of a GTK update then shows what actually changed.
- *
- * THE CONFLICT MACHINERY IS NOT DEFENSIVE. TypeScript requires a multiply
- * inherited member to be IDENTICAL in every base — `string` and `string | null`
- * are not — and GTK's interfaces do redeclare class properties. So a base that
- * loses a member is emitted as `Omit<Base, 'name'>`, because a local redeclaration
- * does NOT repair incompatible bases (it turns one error into another).
- */
-import { type GirClass, type GirNamespace } from './gir.mjs';
-import { type Universe } from './tsmap.mjs';
-export interface PropMember {
-    readonly kebab: string;
-    readonly camel: string;
-    readonly ts: string;
-    readonly doc?: string;
-    readonly deprecated: boolean;
-    readonly since?: string;
-}
-export interface SignalMember {
-    readonly signal: string;
-    readonly prop: string;
-    /** Already rendered — `(row: Gtk.ListBoxRow) => void`. */
-    readonly ts: string;
-    readonly doc?: string;
-    readonly deprecated: boolean;
-    readonly since?: string;
-}
-export interface Declaration {
-    /** GIR-qualified — `Gtk.Box`. The graph is keyed on this, the way GIR references. */
-    readonly key: string;
-    readonly gtype: string;
-    readonly kind: 'class' | 'interface';
-    /** `GtkBoxProps`. */
-    readonly iface: string;
-    readonly bases: readonly string[];
-    readonly props: readonly PropMember[];
-    readonly signals: readonly SignalMember[];
-    readonly doc?: string;
-}
-export interface SurfaceModel {
-    /** The 164, sorted by GType name. */
-    readonly widgets: readonly GirClass[];
-    readonly declarations: ReadonlyMap<string, Declaration>;
-    /** Widget GType -> the GTypes of every declaration its members come from, self first. */
-    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[]>;
-    readonly namespacesUsed: ReadonlySet<string>;
-    /** Copied from the universe, so the emitter needs no second source for it. */
-    readonly packages: Readonly<Record<string, string>>;
-    /** Base -> members it must not contribute, because a nearer declaration disagrees. */
-    readonly omissions: ReadonlyMap<string, ReadonlyMap<string, readonly string[]>>;
-}
-export declare function buildSurface(widgets: readonly GirClass[], namespaces: readonly GirNamespace[], universe: Universe): SurfaceModel;

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

@@ -1,73 +0,0 @@
-/**
- * GIR type -> TypeScript type, and the two places variance decides the answer.
- *
- * Measured over the real Gtk-4.0 + Adw-1 GIR with the seven referenced namespaces
- * loaded: 6768 writable property slots and 1889 signal parameters, and NOT ONE
- * type name that fails to resolve. So there is no "unknown fallback" branch to
- * hide behind — every type either maps or the generator fails and says which.
- *
- * WHERE PROPERTIES AND PARAMETERS MUST DIFFER, twice, both times because a
- * property is an INPUT and a handler parameter is an OUTPUT:
- *
- *  1. An enum PROPERTY takes the nick (`orientation="vertical"`) — the host
- *     resolves it (`coerce()` in props.ts) precisely because GObject would
- *     silently keep the old value. An enum PARAMETER arrives as a NUMBER: GJS
- *     hands the marshalled value. Offering the nick union in a parameter would
- *     invite `if (mode === 'single')`, which is always false — a silent bug worse
- *     than no typing at all.
- *  2. Nullability widens a property harmlessly and BREAKS a parameter. GIR marks
- *     many parameters `nullable="1"`, but a parameter type is contravariant: with
- *     `(row: Gtk.ListBoxRow | null) => void` declared, the ordinary
- *     `onRowActivated={(row: Gtk.ListBoxRow) => …}` stops compiling. So object
- *     PROPERTIES get `| null` (clearing one is legitimate) and parameters do not,
- *     and this comment is the record that the second was a decision rather than an
- *     oversight.
- *
- * FLAGS ARE `number`, in both positions, and that mirrors the runtime exactly: the
- * host REFUSES a nick string for a flags property by name (`err.badFlags`),
- * because resolving a nick set ("horizontal|vertical") is not something GObject
- * exposes. A union of nicks here would type-check something the host rejects.
- */
-import type { GirClass, GirEnum, GirNamespace, GirType } from './gir.mjs';
-/** GIR namespace -> the `@girs` package that types it. Only these seven are referenced. */
-export declare const GIRS_PACKAGES: Readonly<Record<string, string>>;
-export interface Universe {
-    readonly enums: Map<string, GirEnum>;
-    readonly classes: Map<string, GirClass>;
-    readonly others: Set<string>;
-    /**
-     * GIR namespace -> the `@girs` package that types it.
-     *
-     * Carried here rather than read from the module constant, so a fixture can
-     * supply its own five-class namespace. Without it the type mapper is only ever
-     * exercised against the real GIR, where the branch that refuses an unknown
-     * namespace can never be reached.
-     */
-    readonly packages: Readonly<Record<string, string>>;
-}
-export declare function buildUniverse(namespaces: readonly GirNamespace[], packages?: Readonly<Record<string, string>>): Universe;
-export { nickOf } from './gir.mjs';
-export interface TsType {
-    readonly text: string;
-    /** GIR namespaces whose `@girs` import the emitted text needs. */
-    readonly namespaces: readonly string[];
-    /** Enum GTypes whose nick alias the emitted text references. */
-    readonly enums: readonly string[];
-}
-export declare class TypeMapError extends Error {
-}
-/** A nick union, or `never` for an enum GIR declares with no members. */
-export declare const nickUnion: (e: GirEnum) => string;
-/** The alias name a nick union is emitted under — the GType name, so it is unique. */
-export declare const nickAliasOf: (e: GirEnum) => string;
-/**
- * Map one GIR type.
- *
- * `where` is not decoration: see the header — an enum in a `prop` accepts nicks
- * and in a `param` never does, and an object in a `prop` accepts null.
- */
-export declare function tsTypeOf(type: GirType, u: Universe, where: 'prop' | 'param'): TsType;
-/** `row-activated` -> `onRowActivated`; `notify` handled by the caller. */
-export declare const eventPropOf: (signal: string) => string;
-/** `can-focus` -> `canFocus`. The inverse of the host's `toPropertyName`. */
-export declare const camelOf: (kebab: string) => string;