@gtkx/codegen 1.2.0 → 1.2.1

package/src/gir/class.ts

@@ -11,6 +11,12 @@ type GirVirtualMethod = GirCallable & {
     invoker: string | undefined;
 };
 
+/** A `<glib:signal>` on a class or interface. */
+type GirSignal = GirCallable & {
+    /** Whether the signal takes a `::detail` suffix, so `changed::key` reaches only that detail. */
+    isDetailed: boolean;
+};
+
 /** A `<class>` or `<interface>` declared by a GIR namespace. */
 type GirClass = {
     /** Name GIR gives the type, without its namespace prefix. */
@@ -54,7 +60,7 @@ type GirClass = {
     /** GObject properties the type declares. */
     properties: GirProperty[];
     /** GObject signals the type declares. */
-    signals: GirCallable[];
+    signals: GirSignal[];
     /** Virtual methods the type declares, carrying the documentation their vtable slots are generated from. */
     vfuncs: GirVirtualMethod[];
 };
@@ -88,8 +94,11 @@ const classFromNode = (node: RawNode, isInterface: boolean, context: ParseContex
     constructors: getChildren(node, GIR_CONSTRUCTOR_TAG).map((ctor) => functionFromNode(ctor, context)),
     functions: getChildren(node, "function").map((fn) => functionFromNode(fn, context)),
     properties: getChildren(node, "property").map((property) => propertyFromNode(property, context)),
-    signals: getChildren(node, "glib:signal").map((signal) => parseCallable(signal, context)),
+    signals: getChildren(node, "glib:signal").map((signal) => ({
+        ...parseCallable(signal, context),
+        isDetailed: isAttrTrue(signal, "detailed"),
+    })),
     vfuncs: virtualMethodsFromNode(node, context),
 });
 
-export { classFromNode, type GirClass, type GirVirtualMethod };
+export { classFromNode, type GirClass, type GirSignal, type GirVirtualMethod };

package/src/store/gi/callables.ts

@@ -7,7 +7,7 @@ import { renderBlock } from "../../writer/emit.js";
 import { matchAsyncFinish } from "./async.js";
 import { callableDoc, callableSpec } from "./callable-doc.js";
 import { renderFnExpression } from "./function.js";
-import { gtypeMemberDeclaration } from "./gtype-binding.js";
+import { gtypeMemberDeclaration, gtypeStaticMember } from "./gtype-binding.js";
 import {
     finishCallExpression,
     memberName,
@@ -66,7 +66,7 @@ type PlainTypeMembersOptions = {
     context: ModuleContext;
     className: string;
     callables: Callables;
-    hasGtype: boolean;
+    gtypeExpr: string | undefined;
 };
 
 const RUNTIME_OWNED_LIFETIME_METHODS: Set<string> = new Set([
@@ -514,11 +514,11 @@ const renderPlainInstanceMethods = (
 const renderPlainTypeMembers = (
     options: PlainTypeMembersOptions,
 ): { members: string[]; claimedNames: Set<string> } => {
-    const { context, className, callables, hasGtype } = options;
+    const { context, className, callables, gtypeExpr } = options;
     const claimedNames: Set<string> = new Set();
 
     const members: string[] = [
-        ...(hasGtype ? [gtypeMemberDeclaration(context)] : []),
+        ...(gtypeExpr === undefined ? [] : [gtypeMemberDeclaration(context), gtypeStaticMember(context)]),
         ...renderStaticHead(context, callables, className),
         ...renderPlainInstanceMethods(context, callables.methods, claimedNames),
     ];

package/src/store/gi/class.ts

@@ -34,7 +34,7 @@ import {
 } from "./callables.js";
 import { renderClassConstructor, renderConstructorPropsInterface } from "./constructor-props.js";
 import { getDoc } from "./doc-spec.js";
-import { gtypeMemberDeclaration, renderSourceGtype } from "./gtype-binding.js";
+import { gtypeMemberDeclaration, gtypeStaticMember, renderSourceGtype } from "./gtype-binding.js";
 import { methodExportName } from "./method.js";
 import { renderPropertyDeclarations } from "./properties.js";
 import { renderResolvedPropertyAccessor, resolveAccessor, type ResolvedAccessor } from "./property-accessor.js";
@@ -60,6 +60,14 @@ type MemberDeclarationsOptions = {
 
 type ClassMembers = { members: string[]; accessors: ResolvedAccessor[] };
 
+type ClassMembersOptions = {
+    context: ModuleContext;
+    klass: GirClass;
+    callables: Callables;
+    gtypeExpr: string | undefined;
+    hasParent: boolean;
+};
+
 type ImplementedRefOptions = {
     context: ModuleContext;
     klass: GirClass;
@@ -97,7 +105,16 @@ const generateClass = (context: ModuleContext, klass: GirClass): void => {
     const implemented = resolveImplementedRefs(context, klass);
     const typeRefs = implemented.map((ref) => omittedTypeRef(ref.typeRef, ref.conflicts));
     const implementsClause = typeRefs.length === 0 ? "" : ` implements ${typeRefs.join(", ")}`;
-    const { members, accessors } = renderClassMembers(context, klass, callables, parentExpression !== undefined);
+    const gtypeExpr = renderSourceGtype(context, klass);
+
+    const { members, accessors } = renderClassMembers({
+        context,
+        klass,
+        callables,
+        gtypeExpr,
+        hasParent: parentExpression !== undefined,
+    });
+
     const body = indentMembers(members);
     const doc = getDoc(klass);
     const modifier = klass.isAbstract ? "abstract " : "";
@@ -115,7 +132,7 @@ const generateClass = (context: ModuleContext, klass: GirClass): void => {
 
     appendMemberDeclarations({ context, klass, className, accessors, implemented });
     appendInstallMixins(context, className, implemented);
-    appendClassRegistrations(context, klass, className);
+    appendClassRegistrations(context, klass, className, gtypeExpr);
 };
 
 const appendMemberDeclarations = (options: MemberDeclarationsOptions): void => {
@@ -150,15 +167,14 @@ const appendInterfaceMerge = (
     });
 };
 
-const renderClassMembers = (
-    context: ModuleContext,
-    klass: GirClass,
-    callables: Callables,
-    hasParent: boolean,
-): ClassMembers => {
+const renderClassMembers = (options: ClassMembersOptions): ClassMembers => {
+    const { context, klass, callables, gtypeExpr } = options;
     const className = sanitizeTypeIdentifier(klass.name);
-    const members: string[] = [gtypeMemberDeclaration(context)];
-    const constructorBlock = renderClassConstructor(context, klass, className, hasParent);
+
+    const members: string[] =
+        gtypeExpr === undefined ? [] : [gtypeMemberDeclaration(context), gtypeStaticMember(context)];
+
+    const constructorBlock = renderClassConstructor(context, klass, className, options.hasParent);
 
     if (constructorBlock !== undefined) {
         members.push(constructorBlock);
@@ -239,9 +255,12 @@ const appendInstallMixins = (context: ModuleContext, className: string, implemen
     ]);
 };
 
-const appendClassRegistrations = (context: ModuleContext, klass: GirClass, className: string): void => {
-    const gtypeExpr = renderSourceGtype(context, klass);
-
+const appendClassRegistrations = (
+    context: ModuleContext,
+    klass: GirClass,
+    className: string,
+    gtypeExpr: string | undefined,
+): void => {
     appendWrapperClassRegistration(context, {
         className,
         gtypeExpr,

package/src/store/gi/gtype-binding.ts

@@ -1,17 +1,32 @@
 import { sourceStringLiteral } from "@gtkx/utils";
 import type { ModuleContext } from "../../writer/context.js";
 import { PRIMITIVE_TS_TYPE } from "../../gir/primitives.js";
+import { renderJsDoc } from "../../writer/doc.js";
+import { renderBlock } from "../../writer/emit.js";
 
 type TypeSource = {
     glibGetType: string | undefined;
     glibTypeName: string | undefined;
 };
 
+const GTYPE_NOTE = [
+    "The GType this class is registered under, read off the class it is accessed on rather than",
+    "inherited, so a subclass `registerClass` created reports its own type and one that never went",
+    "through `registerClass` reports the invalid type.",
+].join("\n");
+
 const gtypeTsType = (context: ModuleContext): string =>
     context.namespace.name === "GObject" ? "Type" : PRIMITIVE_TS_TYPE.gtype;
 
 const gtypeMemberDeclaration = (context: ModuleContext): string => `declare __type__: ${gtypeTsType(context)};`;
 
+const gtypeStaticMember = (context: ModuleContext): string => {
+    context.addRuntimeImport("getClassType");
+    const block = renderBlock(`static get __gtype__(): ${gtypeTsType(context)}`, "return getClassType(this);");
+
+    return `${renderJsDoc(undefined, GTYPE_NOTE)}${block}`;
+};
+
 const renderInternGtype = (context: ModuleContext, typeName: string | undefined): string | undefined => {
     if (typeName === undefined) {
         return undefined;
@@ -48,4 +63,4 @@ const renderSourceGtype = (context: ModuleContext, source: TypeSource): string |
         ? undefined
         : renderGtypeExpression(context, source.glibGetType, source.glibTypeName);
 
-export { gtypeTsType, gtypeMemberDeclaration, renderSourceGtype };
+export { gtypeTsType, gtypeMemberDeclaration, gtypeStaticMember, renderSourceGtype };

package/src/store/gi/interface.ts

@@ -21,7 +21,7 @@ import {
     renderStaticHead,
 } from "./callables.js";
 import { annotationSpec, getDoc } from "./doc-spec.js";
-import { renderSourceGtype } from "./gtype-binding.js";
+import { gtypeStaticMember, renderSourceGtype } from "./gtype-binding.js";
 import { methodExportName } from "./method.js";
 import {
     type PropertyAccessorArgs,
@@ -378,7 +378,7 @@ const renderInterfaceClass = (context: ModuleContext, options: InterfaceClassOpt
     const members: string[] = [];
 
     if (gtypeExpr !== undefined) {
-        members.push(renderInterfaceHasInstance(context, className, gtypeExpr));
+        members.push(renderInterfaceHasInstance(context, className, gtypeExpr), gtypeStaticMember(context));
     }
 
     members.push(...renderStaticHead(context, callables, className), renderInterfaceBrand(context, implRef));

package/src/store/gi/record-constructor.ts

@@ -11,7 +11,7 @@ import { renderBlock, renderBracedOrEmpty } from "../../writer/emit.js";
 import { type Callables, staticMembers } from "./callables.js";
 import { getDoc } from "./doc-spec.js";
 import { renderSourceGtype } from "./gtype-binding.js";
-import { emitFieldWrite, isEmittableField, isInlineField } from "./record-field-accessor.js";
+import { emitFieldWrite, isEmittableField, isInlineField, isStorableFieldType } from "./record-field-accessor.js";
 import { computeRecordFieldSlots, type RecordFieldSlot } from "./record-layout.js";
 import { isConstructibleRecord } from "./value-marshalable.js";
 
@@ -25,7 +25,9 @@ type RecordConstructorSpec = {
 };
 
 const isWritableFieldSlot = (context: ModuleContext, entry: RecordFieldSlot): entry is WritableFieldSlot =>
-    entry.field.writable && isEmittableField(context, entry.field);
+    entry.field.writable &&
+    isEmittableField(context, entry.field) &&
+    isStorableFieldType(context, entry.field.type);
 
 const renderRecordConstructorPropsInterface = (
     context: ModuleContext,

package/src/store/gi/record-field-accessor.ts

@@ -9,6 +9,7 @@ import type { ModuleContext } from "../../writer/context.js";
 import { isInlineCallbackRef, renderDescriptor } from "../../analysis/descriptor-render.js";
 import { tStruct } from "../../analysis/descriptor.js";
 import { renderTsType } from "../../analysis/ts-type.js";
+import { isUnboundedArray } from "../../analysis/type-shape.js";
 import { indent, renderBlock } from "../../writer/emit.js";
 import { getDoc } from "./doc-spec.js";
 import { bitMask, computeRecordFieldSlots, mergeBitfield, type RecordFieldSlot } from "./record-layout.js";
@@ -27,6 +28,10 @@ type AdmittedField = {
     jsName: string;
 };
 
+type AccessibleField = AdmittedField & {
+    isSettable: boolean;
+};
+
 type RecordFieldEntry = {
     jsName: string;
     tsType: string;
@@ -167,12 +172,49 @@ const admitField = (
     return { field, jsName };
 };
 
+const isNullTerminatedArrayField = (context: ModuleContext, ref: TypeId): boolean => {
+    const type = context.library.typeFor(ref);
+
+    return type?.kind === "carray" && isUnboundedArray(type) && type.elementCType?.endsWith("*") === true;
+};
+
+const isAccessibleFieldType = (context: ModuleContext, ref: TypeId): boolean =>
+    isAccessorEligibleType(context, ref) || isNullTerminatedArrayField(context, ref);
+
+const isStorableFieldType = (context: ModuleContext, ref: TypeId): boolean => {
+    const kind = context.library.typeFor(ref)?.kind;
+
+    return kind !== "carray" && kind !== "list" && kind !== "hashtable";
+};
+
+const admitAccessibleField = (
+    context: ModuleContext,
+    slot: RecordFieldSlot,
+    claimedNames: Set<string>,
+    siblingFields: GirField[],
+): AccessibleField | undefined => {
+    const admitted = admitField(context, slot, claimedNames);
+
+    if (admitted === undefined) {
+        return undefined;
+    }
+
+    const { field, jsName } = admitted;
+    const target: StructArrayTarget = { field, jsName, slot: slot.slot, siblingFields };
+    const hasStructArray = resolveStructArray(context, target) !== undefined;
+    const hasAccessor = hasStructArray || isAccessibleFieldType(context, field.type);
+    const isSettable = field.writable && (hasStructArray || isStorableFieldType(context, field.type));
+
+    return hasAccessor ? { ...admitted, isSettable } : undefined;
+};
+
 const resolveRecordFieldEntry = (
     context: ModuleContext,
     slot: RecordFieldSlot,
     claimedNames: Set<string>,
+    siblingFields: GirField[],
 ): RecordFieldEntry | undefined => {
-    const admitted = admitField(context, slot, claimedNames);
+    const admitted = admitAccessibleField(context, slot, claimedNames, siblingFields);
 
     if (admitted === undefined) {
         return undefined;
@@ -181,7 +223,7 @@ const resolveRecordFieldEntry = (
     return {
         jsName: admitted.jsName,
         tsType: renderTsType(context, admitted.field.type, false),
-        isWritable: admitted.field.writable,
+        isWritable: admitted.isSettable,
         doc: admitted.field.doc,
         annotations: admitted.field.annotations,
     };
@@ -193,7 +235,7 @@ const renderRecordFieldAccessor = (
     claimedNames: Set<string>,
     siblingFields: GirField[],
 ): string | undefined => {
-    const admitted = admitField(context, slot, claimedNames);
+    const admitted = admitAccessibleField(context, slot, claimedNames, siblingFields);
 
     if (admitted === undefined) {
         return undefined;
@@ -207,12 +249,6 @@ const renderRecordFieldAccessor = (
         return `${doc}${structArray}`;
     }
 
-    if (!isAccessorEligibleType(context, field.type)) {
-        const tsType = renderTsType(context, field.type, false);
-
-        return `${doc}declare ${jsName}: ${tsType};`;
-    }
-
     const descriptor = context.hoistDescriptor(
         renderDescriptor(context, field.type, "none", { isInline: isInlineField(context, field) }),
     );
@@ -230,7 +266,7 @@ const renderRecordFieldAccessor = (
 
     const blocks: string[] = [getterBlock(accessorOptions)];
 
-    if (field.writable) {
+    if (admitted.isSettable) {
         blocks.push(setterBlock(accessorOptions));
     }
 
@@ -654,6 +690,7 @@ const setterBlock = (options: AccessorOptions): string =>
 export {
     isEmittableField,
     isInlineField,
+    isStorableFieldType,
     emitFieldWrite,
     resolveRecordFieldEntry,
     renderRecordFieldAccessor,

package/src/store/gi/record.ts

@@ -12,6 +12,14 @@ import { computeRecordFieldSlots } from "./record-layout.js";
 import { appendWrapperClassRegistration } from "./registration.js";
 import { isConstructibleRecord } from "./value-marshalable.js";
 
+type RecordMembersOptions = {
+    context: ModuleContext;
+    record: GirRecord;
+    className: string;
+    callables: Callables;
+    gtypeExpr: string | undefined;
+};
+
 const isGErrorRecord = (context: ModuleContext, record: GirRecord): boolean =>
     context.namespace.name === "GLib" && record.glibGetType === "g_error_get_type";
 
@@ -30,7 +38,8 @@ const generateRecord = (context: ModuleContext, record: GirRecord): void => {
     };
 
     generateBindings(context, callables);
-    const members = renderRecordMembers(context, record, className, callables);
+    const gtypeExpr = renderSourceGtype(context, record);
+    const members = renderRecordMembers({ context, record, className, callables, gtypeExpr });
     const body = indentMembers(members);
     const heritage = isErrorSubclass ? " extends globalThis.Error" : "";
     const doc = getDoc(record);
@@ -50,29 +59,16 @@ const generateRecord = (context: ModuleContext, record: GirRecord): void => {
         });
     }
 
-    const gtypeExpr = renderSourceGtype(context, record);
-
     appendWrapperClassRegistration(context, {
         className,
         gtypeExpr,
     });
 };
 
-const renderRecordMembers = (
-    context: ModuleContext,
-    record: GirRecord,
-    className: string,
-    callables: Callables,
-): string[] => {
+const renderRecordMembers = (options: RecordMembersOptions): string[] => {
+    const { context, record, className, callables, gtypeExpr } = options;
     const isErrorSubclass = isGErrorRecord(context, record);
-
-    const { members, claimedNames } = renderPlainTypeMembers({
-        context,
-        className,
-        callables,
-        hasGtype: record.glibGetType !== undefined,
-    });
-
+    const { members, claimedNames } = renderPlainTypeMembers({ context, className, callables, gtypeExpr });
     members.unshift(renderRecordConstructor(context, { record, className, callables, isErrorSubclass }));
     const { slots } = computeRecordFieldSlots(context, record.fields, record.isUnion);
 

package/src/store/gi/signal.ts

@@ -1,5 +1,5 @@
 import { camelCase, sourceStringLiteral } from "@gtkx/utils";
-import type { GirClass } from "../../gir/class.js";
+import type { GirClass, GirSignal } from "../../gir/class.js";
 import type { GirCallable, GirParameter, GirReturnValue } from "../../gir/parameter.js";
 import type { GirProperty } from "../../gir/property.js";
 import type { ModuleContext } from "../../writer/context.js";
@@ -139,16 +139,20 @@ const renderSignalMap = (spec: SignalMapSpec): string => {
     const { context, klass, className, isParentlessObjectSubclass, suffix, renderEntry } = spec;
     const extendsRefs = signalMapParentRefs(context, klass, isParentlessObjectSubclass, suffix);
     const extendsClause = extendsRefs.length === 0 ? "" : ` extends ${extendsRefs.join(", ")}`;
+    const signals = collectClassSignals(context, klass);
 
-    const signalEntries = collectClassSignals(context, klass).map(
-        (signal) => `${signalDoc(signal)}${sourceStringLiteral(signal.name)}: ${renderEntry(context, signal)};`,
-    );
+    const signalEntries = signals.flatMap((signal) => {
+        const value = renderEntry(context, signal);
+        const entry = `${signalDoc(signal)}${sourceStringLiteral(signal.name)}: ${value};`;
 
-    const entries = [
-        ...signalEntries,
-        ...renderNotifyDetailEntries(context, klass, suffix),
-        ...renderCustomNotifyEntry(context, klass, suffix),
-    ];
+        if (!signal.isDetailed) {
+            return [entry];
+        }
+
+        return [entry, `[detail: \`${signal.name}::\${string}\`]: ${value};`];
+    });
+
+    const entries = [...signalEntries, ...renderNotifyDetailEntries(context, klass, suffix)];
 
     return renderBracedOrEmpty(`export interface ${className}${suffix}${extendsClause}`, entries.join("\n"));
 };
@@ -156,14 +160,6 @@ const renderSignalMap = (spec: SignalMapSpec): string => {
 const signalDoc = (signal: GirCallable): string =>
     renderJsDoc(signal.doc, undefined, handlerSpec(signal, signal.parameters));
 
-const renderCustomNotifyEntry = (context: ModuleContext, klass: GirClass, suffix: string): string[] => {
-    if (context.namespace.name !== "GObject" || klass.name !== "Object") {
-        return [];
-    }
-
-    return [`[detail: \`notify::\${string}\`]: ${gobjectObjectMapRef(context, suffix)}["notify"];`];
-};
-
 const renderNotifyDetailEntries = (context: ModuleContext, klass: GirClass, suffix: string): string[] => {
     const notifyValue = `${gobjectObjectMapRef(context, suffix)}["notify"]`;
 
@@ -219,10 +215,11 @@ const renderSignalConnectInterface = (className: string, isRootObject: boolean):
         `__signals__?: ${map};`,
         `connect<K extends keyof ${map}>(signal: K, handler: ${map}[K], isAfter?: boolean): number;`,
         `emit<K extends keyof ${emitMap}>(sigName: K, ...args: ${emitMap}[K]["args"]): ${emitMap}[K]["result"];`,
-        "emit(sigName: string, ...args: unknown[]): unknown;",
     ];
 
-    if (!isRootObject) {
+    if (isRootObject) {
+        lines.push("emit(sigName: string, ...args: unknown[]): unknown;");
+    } else {
         const chainable = (methods: string[], trailing: string): void => {
             for (const method of methods) {
                 lines.push(
@@ -382,7 +379,7 @@ const renderCallback = (context: ModuleContext, signal: GirCallable): string =>
 const forEachInterfaceSignal = (
     context: ModuleContext,
     klass: GirClass,
-    consider: (signal: GirCallable) => void,
+    consider: (signal: GirSignal) => void,
 ): void => {
     for (const iface of resolveInterfaces(context.library, context.namespace.name, klass.implements)) {
         for (const signal of iface.klass.signals) {
@@ -391,12 +388,12 @@ const forEachInterfaceSignal = (
     }
 };
 
-const collectClassSignals = (context: ModuleContext, klass: GirClass): GirCallable[] => {
+const collectClassSignals = (context: ModuleContext, klass: GirClass): GirSignal[] => {
     const inheritedNames = collectInheritedSignalNames(context, klass);
     const seen: Set<string> = new Set();
-    const result: GirCallable[] = [];
+    const result: GirSignal[] = [];
 
-    const consider = (signal: GirCallable): void => {
+    const consider = (signal: GirSignal): void => {
         const name = camelCase(signal.name);
 
         if (!signal.introspectable || inheritedNames.has(name) || seen.has(name)) {

package/src/store/resolve-store.ts

@@ -28,6 +28,7 @@ const STORE_CONSUMERS: string[] = [
     "@gtkx/components",
     "@gtkx/css",
     "@gtkx/react",
+    "@gtkx/runtime",
     "@gtkx/testing",
 ];