@gtkx/codegen 1.0.0-rc.3 → 1.0.0

package/src/store/gi/vtable.ts

@@ -1,46 +1,112 @@
-import { pascalCase, sourceStringLiteral, toCamelIdentifier } from "@gtkx/utils";
+import { pascalCase, sourceStringLiteral } from "@gtkx/utils";
 import type { GirCallback } from "../../gir/callback.js";
-import type { GirClass } from "../../gir/class.js";
+import type { GirClass, GirVirtualMethod } from "../../gir/class.js";
 import type { GirField } from "../../gir/field.js";
 import type { GirParameter } from "../../gir/parameter.js";
+import type { GirRecord } from "../../gir/record.js";
+import type { TypeId } from "../../gir/type-id.js";
 import type { ModuleContext } from "../../writer/context.js";
+import type { JsDocSpec } from "../../writer/doc.js";
 import {
     isInlineCallbackRef,
     isScalarRef,
     renderDescriptor,
     renderParamDescriptor,
 } from "../../analysis/descriptor-render.js";
-import { renderBraced } from "../../writer/emit.js";
+import {
+    foldedLengthParameters,
+    handlerParameters,
+    parameterIdentifier,
+    renamesWithInstance,
+    renderHandlerParameters,
+    renderHandlerResultType,
+} from "../../analysis/param-structure.js";
+import { renderTsType } from "../../analysis/ts-type.js";
+import { ancestorChain, type ResolvedAncestor, resolveInterfaces } from "../../gir/ancestry.js";
+import { renderJsDoc } from "../../writer/doc.js";
+import { renderBlock, renderBraced } from "../../writer/emit.js";
+import { handlerSpec, THROWS_TEXT } from "./doc-spec.js";
 import { computeRecordFieldSlots } from "./record-layout.js";
 
 type VtableKind = "class" | "interface";
+type VfuncMemberMode = "implementation" | "requirement" | "signature";
 
-type RenderVtableSlotDescriptorOptions = {
+type VtableSlot = {
     key: string;
-    structName: string;
-    kind: VtableKind;
     field: GirField;
     callback: GirCallback;
+    vfunc: GirVirtualMethod | undefined;
     byteOffset: number;
-    vtableSize: number;
 };
 
-const renderVfuncMetadata = (context: ModuleContext, klass: GirClass): string | undefined => {
-    if (klass.glibTypeStruct === undefined) {
-        return undefined;
-    }
+type VfuncMemberOptions = {
+    context: ModuleContext;
+    ownerRef: string;
+    slot: VtableSlot;
+    mode: VfuncMemberMode;
+    isProtected: boolean;
+};
+
+type VfuncMembersOptions = {
+    context: ModuleContext;
+    klass: GirClass;
+    mode: VfuncMemberMode;
+};
 
-    const structName = pascalCase(klass.glibTypeStruct);
-    const kind: VtableKind = klass.isInterface ? "interface" : "class";
-    const entries = vtableEntries(context, structName, kind, klass.glibTypeStruct);
+type VfuncSignature = {
+    header: string;
+    returnType: string;
+};
 
-    if (entries.length === 0) {
-        return undefined;
-    }
+type VfuncEntry = {
+    name: string;
+    signature: string;
+    doc: string | undefined;
+};
 
-    return renderBraced(entries.join("\n"));
+type Vtable = {
+    structName: string;
+    kind: VtableKind;
+    vtableSize: number;
+    slots: VtableSlot[];
 };
 
+const PADDING_FIELD_NAME = /^(?:reserved|padding)\d*$/i;
+
+const UNCALLABLE_SLOT_KEYS: Set<string> = new Set([
+    "vfuncDispose",
+    "vfuncFinalize",
+    "vfuncGetProperty",
+    "vfuncSetProperty",
+]);
+
+const PROTECTED_SLOT_NOTE = "It is `protected`, so only a subclass chaining up reaches it.";
+const PUBLIC_SLOT_NOTE = "Calling it from anywhere else re-enters the slot on a live instance.";
+
+const vfuncMemberName = (fieldName: string): string => `vfunc${pascalCase(fieldName)}`;
+
+const vfuncOverrideNote = (slot: VtableSlot, isProtected: boolean): string =>
+    [
+        `Invokes the \`${slot.field.name}\` vtable slot. Override it on a class passed to \`registerClass\``,
+        `and chain up with \`super.${slot.key}()\`.`,
+        isProtected ? PROTECTED_SLOT_NOTE : PUBLIC_SLOT_NOTE,
+    ].join("\n");
+
+const vfuncRequirementNote = (slot: VtableSlot, ownerRef: string): string =>
+    [
+        `Fills the \`${slot.field.name}\` vtable slot. Declare it on a class passed to \`registerClass\``,
+        `with \`${ownerRef}\` in \`implements\`, which installs it in the interface vtable. Leaving it out`,
+        "keeps whatever the interface installs by default, the way it does for a C implementer.",
+    ].join("\n");
+
+const vfuncMemberNote = (options: VfuncMemberOptions): string =>
+    options.mode === "requirement"
+        ? vfuncRequirementNote(options.slot, options.ownerRef)
+        : vfuncOverrideNote(options.slot, options.isProtected);
+
+const isPaddingField = (field: GirField): boolean =>
+    field.name.startsWith("_") || PADDING_FIELD_NAME.test(field.name);
+
 const vtableCallbackType = (context: ModuleContext, field: GirField): GirCallback | undefined => {
     if (field.type === undefined) {
         return undefined;
@@ -60,15 +126,19 @@ const vtableSlotEntry = (
     field: GirField,
     claimedNames: Set<string>,
 ): { key: string; callback: GirCallback } | undefined => {
+    if (field.name === "constructor" || isPaddingField(field)) {
+        return undefined;
+    }
+
     const callback = vtableCallbackType(context, field);
 
     if (callback === undefined) {
         return undefined;
     }
 
-    const key = toCamelIdentifier(field.name);
+    const key = vfuncMemberName(field.name);
 
-    if (key === "constructor" || claimedNames.has(key)) {
+    if (claimedNames.has(key)) {
         return undefined;
     }
 
@@ -79,53 +149,271 @@ const vtableSlotEntry = (
     return { key, callback };
 };
 
-const vtableEntries = (context: ModuleContext, structName: string, kind: VtableKind, typeStruct: string): string[] => {
-    const resolved = context.library.resolveType(context.namespace.name, typeStruct);
-
-    if (resolved?.kind !== "record") {
-        return [];
-    }
-
-    const { slots, size } = computeRecordFieldSlots(context, resolved.value.fields, resolved.value.isUnion);
-    const entries: string[] = [];
+const collectVtableSlots = (
+    context: ModuleContext,
+    fields: GirField[],
+    isUnion: boolean,
+): { slots: VtableSlot[]; vtableSize: number } => {
+    const { slots, size } = computeRecordFieldSlots(context, fields, isUnion);
+    const entries: VtableSlot[] = [];
     const claimedNames: Set<string> = new Set();
 
     for (const { field, slot } of slots) {
         const entry = vtableSlotEntry(context, field, claimedNames);
 
-        if (entry === undefined) {
-            continue;
+        if (entry !== undefined) {
+            claimedNames.add(entry.key);
+            entries.push({ ...entry, field, vfunc: undefined, byteOffset: slot.byteOffset });
         }
+    }
+
+    return { slots: entries, vtableSize: size };
+};
 
-        claimedNames.add(entry.key);
+const resolveVtableRecord = (
+    context: ModuleContext,
+    namespaceName: string,
+    klass: GirClass,
+): { typeStruct: string; record: GirRecord } | undefined => {
+    const typeStruct = klass.glibTypeStruct;
+    const resolved = typeStruct === undefined ? undefined : context.library.resolveType(namespaceName, typeStruct);
 
-        entries.push(
-            renderVtableSlotDescriptor(context, {
-                key: entry.key,
-                structName,
-                kind,
-                field,
-                callback: entry.callback,
-                byteOffset: slot.byteOffset,
-                vtableSize: size,
-            }),
-        );
+    if (typeStruct === undefined || resolved?.kind !== "record" || resolved.value.fields.length === 0) {
+        return undefined;
     }
 
-    return entries;
+    return { typeStruct, record: resolved.value };
 };
 
-const isUnsupportedOutParam = (context: ModuleContext, param: GirParameter): boolean =>
-    (param.direction === "out" || param.direction === "inout") &&
-    !param.callerAllocates &&
-    !isScalarRef(context.library, param.type);
+const attachVirtualMethods = (slots: VtableSlot[], klass: GirClass): VtableSlot[] => {
+    const byKey: Map<string, GirVirtualMethod> = new Map(
+        klass.vfuncs.map((vfunc) => [vfuncMemberName(vfunc.name), vfunc]),
+    );
 
-const isEligibleVtableParam = (context: ModuleContext, param: GirParameter): boolean => {
-    if (param.isVarargs) {
-        return false;
+    return slots.map((slot) => ({ ...slot, vfunc: byKey.get(slot.key) }));
+};
+
+const collectVtable = (context: ModuleContext, namespaceName: string, klass: GirClass): Vtable | undefined => {
+    const resolved = resolveVtableRecord(context, namespaceName, klass);
+
+    if (resolved === undefined) {
+        return undefined;
+    }
+
+    const { slots, vtableSize } = collectVtableSlots(context, resolved.record.fields, resolved.record.isUnion);
+
+    if (slots.length === 0) {
+        return undefined;
+    }
+
+    return {
+        structName: pascalCase(resolved.typeStruct),
+        kind: klass.isInterface ? "interface" : "class",
+        vtableSize,
+        slots: attachVirtualMethods(slots, klass),
+    };
+};
+
+const vfuncMemberNames = (context: ModuleContext, namespaceName: string, klass: GirClass): string[] =>
+    collectVtable(context, namespaceName, klass)?.slots.map((slot) => slot.key) ?? [];
+
+const renderVfuncMetadata = (context: ModuleContext, klass: GirClass): string | undefined => {
+    const vtable = collectVtable(context, context.namespace.name, klass);
+
+    if (vtable === undefined) {
+        return undefined;
+    }
+
+    const entries = vtable.slots.map((slot) => renderVtableSlotDescriptor(context, vtable, slot));
+
+    return renderBraced(entries.join("\n"));
+};
+
+const slotIdentity = (slot: VtableSlot): string => `${slot.key}:${String(slot.byteOffset)}`;
+
+const inheritedSlotIdentities = (context: ModuleContext, namespaceName: string, klass: GirClass): Set<string> => {
+    const identities: Set<string> = new Set();
+    const [, ...ancestors] = [...ancestorChain(context.library, klass, namespaceName)];
+
+    for (const ancestor of ancestors) {
+        const vtable = collectVtable(context, ancestor.namespaceName, ancestor.klass);
+        const slots = vtable?.slots ?? [];
+
+        for (const slot of slots) {
+            identities.add(slotIdentity(slot));
+        }
+    }
+
+    return identities;
+};
+
+const addInterfaceSlotKeys = (
+    context: ModuleContext,
+    iface: ResolvedAncestor,
+    keys: Set<string>,
+    seen: Set<string>,
+): void => {
+    const identity = `${iface.namespaceName}.${iface.klass.name}`;
+
+    if (seen.has(identity)) {
+        return;
+    }
+
+    seen.add(identity);
+
+    for (const key of vfuncMemberNames(context, iface.namespaceName, iface.klass)) {
+        keys.add(key);
+    }
+
+    for (const ref of resolveInterfaces(context.library, iface.namespaceName, iface.klass.prerequisites)) {
+        addInterfaceSlotKeys(context, ref, keys, seen);
+    }
+};
+
+const implementedSlotKeys = (context: ModuleContext, namespaceName: string, klass: GirClass): Set<string> => {
+    const keys: Set<string> = new Set();
+    const seen: Set<string> = new Set();
+
+    for (const ancestor of ancestorChain(context.library, klass, namespaceName)) {
+        for (const ref of resolveInterfaces(context.library, ancestor.namespaceName, ancestor.klass.implements)) {
+            addInterfaceSlotKeys(context, ref, keys, seen);
+        }
+    }
+
+    return keys;
+};
+
+const protectedSlotKeys = (options: VfuncMembersOptions, slots: VtableSlot[]): Set<string> => {
+    const { context, klass } = options;
+
+    if (klass.isInterface) {
+        return new Set();
+    }
+
+    const shared = implementedSlotKeys(context, context.namespace.name, klass);
+
+    return new Set(slots.map((slot) => slot.key).filter((key) => !shared.has(key)));
+};
+
+const callableVfuncSlots = (context: ModuleContext, namespaceName: string, klass: GirClass): VtableSlot[] => {
+    const vtable = collectVtable(context, namespaceName, klass);
+
+    if (vtable === undefined) {
+        return [];
+    }
+
+    const inherited = inheritedSlotIdentities(context, namespaceName, klass);
+
+    return vtable.slots.filter((slot) => isCallableSlot(context, slot) && !inherited.has(slotIdentity(slot)));
+};
+
+const hasCallableVfuncSlots = (context: ModuleContext, namespaceName: string, klass: GirClass): boolean =>
+    callableVfuncSlots(context, namespaceName, klass).length > 0;
+
+const slotDoc = (slot: VtableSlot): string | undefined => slot.vfunc?.doc ?? slot.field.doc ?? slot.callback.doc;
+
+const slotDocParameters = (slot: VtableSlot): GirParameter[] => {
+    const [, ...parameters] = slot.callback.parameters;
+    const vfuncParameters = slot.vfunc?.parameters ?? [];
+
+    return parameters.map((parameter, index) => ({ ...parameter, doc: vfuncParameters[index]?.doc ?? parameter.doc }));
+};
+
+const slotDocSpec = (slot: VtableSlot): JsDocSpec => {
+    const parameters = slotDocParameters(slot);
+    const source = slot.vfunc ?? slot.callback;
+
+    return {
+        ...handlerSpec(source, parameters, renamesWithInstance(parameters, slot.callback.parameters[0])),
+        returns: slot.vfunc?.returnValue.doc ?? slot.callback.returnValue.doc,
+        throws: slot.callback.throws ? THROWS_TEXT : undefined,
+    };
+};
+
+const vfuncEntries = (context: ModuleContext, namespaceName: string, klass: GirClass): VfuncEntry[] =>
+    callableVfuncSlots(context, namespaceName, klass).map((slot) => ({
+        name: slot.key,
+        signature: vfuncSlotSignature(context, slot).header,
+        doc: slotDoc(slot),
+    }));
+
+const renderVfuncMembers = (options: VfuncMembersOptions): string[] => {
+    const { context, klass, mode } = options;
+    const ownerRef = pascalCase(klass.name);
+    const slots = callableVfuncSlots(context, context.namespace.name, klass);
+
+    if (slots.length === 0) {
+        return [];
+    }
+
+    if (mode === "implementation") {
+        context.addRuntimeImport("callVfunc");
+    }
+
+    const protectedKeys = protectedSlotKeys(options, slots);
+
+    return slots.map((slot) =>
+        renderVfuncMember({ context, ownerRef, slot, mode, isProtected: protectedKeys.has(slot.key) }));
+};
+
+const hasUnannotatedPointerParam = (context: ModuleContext, slot: VtableSlot): boolean => {
+    const [, ...parameters] = slot.callback.parameters;
+
+    return parameters.some(
+        (parameter) =>
+            parameter.direction === "in" &&
+            parameter.cType?.endsWith("*") === true &&
+            isScalarRef(context.library, parameter.type),
+    );
+};
+
+const isCallableSlot = (context: ModuleContext, slot: VtableSlot): boolean =>
+    !UNCALLABLE_SLOT_KEYS.has(slot.key) && !hasUnannotatedPointerParam(context, slot);
+
+const vfuncSlotSignature = (context: ModuleContext, slot: VtableSlot, isOptional = false): VfuncSignature => {
+    const [, ...parameters] = slot.callback.parameters;
+
+    const renderType = (ref: TypeId | undefined, isNullable: boolean): string =>
+        renderTsType(context, ref, isNullable);
+
+    const signature = renderHandlerParameters(parameters, renderType).join(", ");
+    const folded = foldedLengthParameters(context.library, slot.callback);
+
+    const returnType = renderHandlerResultType({
+        library: context.library,
+        signal: { ...slot.callback, parameters },
+        renderType,
+        shouldIncludeCallerAllocated: true,
+        isOptOut: false,
+        shouldExcludeOut: (parameter) => folded.has(parameter),
+    });
+
+    return { header: `${slot.key}${isOptional ? "?" : ""}(${signature}): ${returnType}`, returnType };
+};
+
+const renderVfuncMember = (options: VfuncMemberOptions): string => {
+    const { context, ownerRef, slot, mode, isProtected } = options;
+    const { header, returnType } = vfuncSlotSignature(context, slot, mode === "requirement");
+    const declaration = `${isProtected ? "protected " : ""}${header}`;
+    const doc = renderJsDoc(slotDoc(slot), vfuncMemberNote(options), slotDocSpec(slot));
+
+    if (mode !== "implementation") {
+        return `${doc}${declaration};`;
     }
 
-    if (isUnsupportedOutParam(context, param)) {
+    const [, ...parameters] = slot.callback.parameters;
+
+    const inputs = handlerParameters(parameters).map((parameter, index) =>
+        parameterIdentifier(parameter, index));
+
+    const call = `callVfunc(${ownerRef}, ${sourceStringLiteral(slot.key)}, this, [${inputs.join(", ")}])`;
+    const body = returnType === "void" ? `${call};` : `return ${call} as ${returnType};`;
+
+    return `${doc}${renderBlock(declaration, body)}`;
+};
+
+const isEligibleVtableParam = (context: ModuleContext, param: GirParameter): boolean => {
+    if (param.isVarargs) {
         return false;
     }
 
@@ -146,8 +434,8 @@ const isVtableSlotEligible = (context: ModuleContext, callback: GirCallback): bo
     return !isInlineCallbackRef(context.library, callback.returnValue.type);
 };
 
-const renderVtableSlotDescriptor = (context: ModuleContext, options: RenderVtableSlotDescriptorOptions): string => {
-    const { key, structName, kind, field, callback, byteOffset, vtableSize } = options;
+const renderVtableSlotDescriptor = (context: ModuleContext, vtable: Vtable, slot: VtableSlot): string => {
+    const { key, field, callback, byteOffset } = slot;
 
     const argDescriptors = callback.parameters
         .map((param) => renderParamDescriptor(context, param, param.type))
@@ -160,16 +448,29 @@ const renderVtableSlotDescriptor = (context: ModuleContext, options: RenderVtabl
     );
 
     const lines = [
-        `kind: ${sourceStringLiteral(kind)} as const,`,
-        `className: ${sourceStringLiteral(structName)},`,
+        `className: ${sourceStringLiteral(vtable.structName)},`,
         `vfuncName: ${sourceStringLiteral(field.name)},`,
         `byteOffset: ${String(byteOffset)},`,
-        `vtableSize: ${String(vtableSize)},`,
-        `argDescriptors: [${argDescriptors}],`,
-        `returnDescriptor: ${returnDescriptor},`,
     ];
 
+    if (vtable.kind === "interface") {
+        lines.push(`vtableSize: ${String(vtable.vtableSize)},`);
+    }
+
+    lines.push(`argDescriptors: [${argDescriptors}],`, `returnDescriptor: ${returnDescriptor},`);
+
+    if (callback.throws) {
+        lines.push("canThrow: true,");
+    }
+
     return `${key}: ${renderBraced(lines.join("\n"))},`;
 };
 
-export { renderVfuncMetadata };
+export {
+    hasCallableVfuncSlots,
+    renderVfuncMembers,
+    renderVfuncMetadata,
+    vfuncEntries,
+    vfuncMemberNames,
+    type VfuncMemberMode,
+};

package/src/store/gi-store.ts

@@ -4,8 +4,6 @@ import { fileURLToPath } from "node:url";
 import { FINGERPRINT_FILENAME, type GiFingerprint } from "../fingerprint.js";
 import { buildManifest, type StoreOptions, subpathExport, writeStore } from "./store-fs.js";
 
-type GiStoreOptions = StoreOptions;
-
 type GiNamespaceInput = {
     directory: string;
     rawSource: string;
@@ -69,7 +67,7 @@ const collectStoreSources = (
 };
 
 const writeGiStore = (
-    options: GiStoreOptions,
+    options: StoreOptions,
     namespaces: GiNamespaceInput[],
     fingerprint: GiFingerprint,
 ): void => {
@@ -89,4 +87,4 @@ const writeGiStore = (
     });
 };
 
-export { writeGiStore, type GiStoreOptions, type GiNamespaceInput };
+export { writeGiStore, type GiNamespaceInput };

package/src/store/jsx/element-components.ts

@@ -3,12 +3,10 @@ import type { Library } from "../../gir/library.js";
 import type { GirNamespace } from "../../gir/namespace.js";
 import type { ImportsBuilder } from "../../writer/imports.js";
 import type { LazyElementSpec } from "./element-prop-types.js";
-import { renderJsDoc } from "../../writer/doc.js";
+import { getDoc } from "../gi/doc-spec.js";
 import { ancestorGlibNames, type GlibNamedClass } from "./intrinsic-elements.js";
 
-/** A component that wraps a generated element, keyed by GLib type name (built-in or user-provided). */
 type ElementComponent = { module: string; export: string };
-/** Component wrappers keyed by GLib type name; the framework's built-ins merged with the project's own. */
 type ElementComponentOverrides = Record<string, ElementComponent>;
 
 type ExportCollector = {
@@ -73,9 +71,6 @@ const appendCandidateExport = (
     collector.exportedNames.add(candidate.glibName);
 };
 
-// An abstract GType cannot be instantiated: `g_object_new` on one is a fatal GObject error rather
-// than a NULL return. Its props interface and metadata still have to be emitted, since every
-// concrete subclass extends them, so only the constructible component export is withheld.
 const collectCandidateExports = (collector: ExportCollector, options: CandidateExportOptions): void => {
     for (const candidate of options.intrinsicElements) {
         if (candidate.klass.isAbstract) {
@@ -96,10 +91,11 @@ const collectLazyElementExports = (collector: ExportCollector, lazyElements: Laz
 };
 
 const renderLazyElementExport = (spec: LazyElementSpec): string => {
+    const doc = getDoc(spec);
     const factory = `createElementComponent(${sourceStringLiteral(spec.element)})`;
-    const component = `export const ${spec.element}: (props: ${spec.typeName}) => ReactNode = ${factory};`;
+    const component = `${doc}export const ${spec.element}: (props: ${spec.typeName}) => ReactNode = ${factory};`;
 
-    return `${spec.typeSource}\n\n${component}`;
+    return `${doc}${spec.typeSource}\n\n${component}`;
 };
 
 const renderCandidateExport = (
@@ -118,10 +114,11 @@ const renderCandidateExport = (
         imports.addNamed(component.module, component.export, false);
     }
 
-    return `${renderJsDoc(klass.doc)}${renderElementComponentExport(glibName, component)}`;
+    const doc = getDoc(klass);
+
+    return `${doc}${renderElementComponentExport(glibName, component)}`;
 };
 
-/** The component for the nearest ancestry match, most-derived first; user overrides win on their exact type. */
 const resolveElementComponent = (
     ancestry: string[],
     components: Record<string, ElementComponent>,
@@ -149,4 +146,4 @@ const renderElementComponentExport = (glibName: string, component: ElementCompon
     return `export const ${glibName}: ${annotation} = ${component.export}(${factoryCall});`;
 };
 
-export { generateElementComponentsSection, type ElementComponent, type ElementComponentOverrides };
+export { generateElementComponentsSection, type ElementComponentOverrides };

package/src/store/jsx/element-prop-imports.ts

@@ -1,11 +1,13 @@
-/** Props interface a generated element's props extend, declared by hand in `@gtkx/react`. */
 type ElementPropTypeRef = { type: string; module: string; export: string };
+
 /** Base props interface each element extends, keyed by GLib type name (the module exports it). */
-type ElementProps = Record<string, { module: string; export: string }>;
+type ElementProps = Record<string, {
+    module: string;
+    export: string;
+}>;
 
 const elementProps: Map<string, { module: string; export: string }> = new Map();
 
-/** Installs the base props each element extends (GLib type name → `{ module, export }`); set once per run. */
 const setElementProps = (props: ElementProps): void => {
     elementProps.clear();
 
@@ -14,11 +16,10 @@ const setElementProps = (props: ElementProps): void => {
     }
 };
 
-/** The base props interface an element extends, when its element config declares one. */
 const elementPropTypeFor = (glibName: string): ElementPropTypeRef | undefined => {
     const ref = elementProps.get(glibName);
 
     return ref === undefined ? undefined : { type: glibName, module: ref.module, export: ref.export };
 };
 
-export { setElementProps, elementPropTypeFor, type ElementPropTypeRef, type ElementProps };
+export { setElementProps, elementPropTypeFor, type ElementProps };

package/src/store/jsx/element-prop-types.ts

@@ -1,4 +1,5 @@
 import { toCamelIdentifier } from "@gtkx/utils";
+import type { GirAnnotations } from "../../gir/annotations.js";
 import type { GirClass } from "../../gir/class.js";
 import { getChain, type GirIndex, type GirTypeEntry } from "./gir-index.js";
 import { getGlibName } from "./intrinsic-elements.js";
@@ -7,6 +8,8 @@ type LazyElementSpec = {
     element: string;
     typeName: string;
     typeSource: string;
+    doc: string | undefined;
+    annotations: GirAnnotations;
 };
 
 const appendConstructOnlyNames = (klass: GirClass, names: string[]): void => {
@@ -34,10 +37,15 @@ const createLazyElementSpec = (context: GirIndex, element: string, entry: GirTyp
     const omitUnion = omitted.map((name) => JSON.stringify(name)).join(" | ");
     const base = omitted.length === 0 ? `${baseName}Props` : `Omit<${baseName}Props, ${omitUnion}>`;
 
-    return { element, typeName, typeSource: `export type ${typeName} = ${base} & { children?: ReactNode };` };
+    return {
+        element,
+        typeName,
+        typeSource: `export type ${typeName} = ${base} & { children?: ReactNode };`,
+        doc: entry.klass.doc,
+        annotations: entry.klass.annotations,
+    };
 };
 
-/** Lazy element prop types to emit, grouped by the namespace declaring each element. */
 const lazyElementSpecs = (context: GirIndex, lazyElements: string[]): Map<string, LazyElementSpec[]> => {
     const specs: Map<string, LazyElementSpec[]> = new Map();