@gtkx/codegen 1.0.0-rc.1 → 1.0.0-rc.2

package/src/store/gi/vtable.ts

@@ -1,99 +1,175 @@
-import { sourceStringLiteral, toCamelIdentifier, toPascalCase } from "@gtkx/utils";
+import { pascalCase, sourceStringLiteral, toCamelIdentifier } from "@gtkx/utils";
+import type { GirCallback } from "../../gir/callback.js";
+import type { GirClass } from "../../gir/class.js";
+import type { GirField } from "../../gir/field.js";
+import type { GirParameter } from "../../gir/parameter.js";
+import type { ModuleContext } from "../../writer/context.js";
 import {
     isInlineCallbackRef,
     isScalarRef,
     renderDescriptor,
     renderParamDescriptor,
 } from "../../analysis/descriptor-render.js";
-import type { GirCallback } from "../../gir/callback.js";
-import type { GirClass } from "../../gir/class.js";
-import type { GirField } from "../../gir/field.js";
-import type { ModuleContext } from "../../writer/context.js";
 import { renderBraced } from "../../writer/emit.js";
 import { computeRecordFieldSlots } from "./record-layout.js";
 
 type VtableKind = "class" | "interface";
 
-export const renderVfuncMetadata = (context: ModuleContext, klass: GirClass): string | undefined => {
-    if (klass.glibTypeStruct === undefined) return undefined;
-    const structName = toPascalCase(klass.glibTypeStruct);
+type RenderVtableSlotDescriptorOptions = {
+    key: string;
+    structName: string;
+    kind: VtableKind;
+    field: GirField;
+    callback: GirCallback;
+    byteOffset: number;
+    vtableSize: number;
+};
+
+const renderVfuncMetadata = (context: ModuleContext, klass: GirClass): string | undefined => {
+    if (klass.glibTypeStruct === undefined) {
+        return undefined;
+    }
+
+    const structName = pascalCase(klass.glibTypeStruct);
     const kind: VtableKind = klass.isInterface ? "interface" : "class";
     const entries = vtableEntries(context, structName, kind, klass.glibTypeStruct);
-    if (entries.length === 0) return undefined;
+
+    if (entries.length === 0) {
+        return undefined;
+    }
+
     return renderBraced(entries.join("\n"));
 };
 
+const vtableCallbackType = (context: ModuleContext, field: GirField): GirCallback | undefined => {
+    if (field.type === undefined) {
+        return undefined;
+    }
+
+    const type = context.library.typeFor(field.type);
+
+    if (type?.kind !== "callback" || context.library.nameFor(field.type) !== undefined) {
+        return undefined;
+    }
+
+    return type.value;
+};
+
+const vtableSlotEntry = (
+    context: ModuleContext,
+    field: GirField,
+    claimedNames: Set<string>,
+): { key: string; callback: GirCallback } | undefined => {
+    const callback = vtableCallbackType(context, field);
+
+    if (callback === undefined) {
+        return undefined;
+    }
+
+    const key = toCamelIdentifier(field.name);
+
+    if (key === "constructor" || claimedNames.has(key)) {
+        return undefined;
+    }
+
+    if (!isVtableSlotEligible(context, callback)) {
+        return undefined;
+    }
+
+    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 === undefined || resolved.kind !== "record") return [];
-    const { slots } = computeRecordFieldSlots(context, resolved.value.fields, resolved.value.isUnion);
+
+    if (resolved?.kind !== "record") {
+        return [];
+    }
+
+    const { slots, size } = computeRecordFieldSlots(context, resolved.value.fields, resolved.value.isUnion);
     const entries: string[] = [];
-    const claimedNames = new Set<string>();
+    const claimedNames: Set<string> = new Set();
+
     for (const { field, slot } of slots) {
-        if (field.type === undefined) continue;
-        const type = context.library.typeOf(field.type);
-        if (type?.kind !== "callback" || context.library.nameOf(field.type) !== undefined) continue;
-        const key = toCamelIdentifier(field.name);
-        if (key === "constructor" || claimedNames.has(key)) continue;
-        const callback = type.value;
-        if (!isVtableSlotEligible(context, callback)) continue;
-        claimedNames.add(key);
+        const entry = vtableSlotEntry(context, field, claimedNames);
+
+        if (entry === undefined) {
+            continue;
+        }
+
+        claimedNames.add(entry.key);
+
         entries.push(
             renderVtableSlotDescriptor(context, {
-                key,
+                key: entry.key,
                 structName,
                 kind,
                 field,
-                callback,
+                callback: entry.callback,
                 byteOffset: slot.byteOffset,
+                vtableSize: size,
             }),
         );
     }
+
     return entries;
 };
 
+const isUnsupportedOutParam = (context: ModuleContext, param: GirParameter): boolean =>
+    (param.direction === "out" || param.direction === "inout") &&
+    !param.callerAllocates &&
+    !isScalarRef(context.library, param.type);
+
+const isEligibleVtableParam = (context: ModuleContext, param: GirParameter): boolean => {
+    if (param.isVarargs) {
+        return false;
+    }
+
+    if (isUnsupportedOutParam(context, param)) {
+        return false;
+    }
+
+    return !isInlineCallbackRef(context.library, param.type);
+};
+
 const isVtableSlotEligible = (context: ModuleContext, callback: GirCallback): boolean => {
-    if (!callback.introspectable) return false;
+    if (!callback.introspectable) {
+        return false;
+    }
+
     for (const param of callback.parameters) {
-        if (param.isVarargs) return false;
-        if (
-            (param.direction === "out" || param.direction === "inout") &&
-            !param.callerAllocates &&
-            !isScalarRef(context.library, param.type)
-        ) {
+        if (!isEligibleVtableParam(context, param)) {
             return false;
         }
-        if (isInlineCallbackRef(context.library, param.type)) return false;
     }
-    return !isInlineCallbackRef(context.library, callback.returnValue.type);
-};
 
-type RenderVtableSlotDescriptorOptions = {
-    key: string;
-    structName: string;
-    kind: VtableKind;
-    field: GirField;
-    callback: GirCallback;
-    byteOffset: number;
+    return !isInlineCallbackRef(context.library, callback.returnValue.type);
 };
 
 const renderVtableSlotDescriptor = (context: ModuleContext, options: RenderVtableSlotDescriptorOptions): string => {
-    const { key, structName, kind, field, callback, byteOffset } = options;
+    const { key, structName, kind, field, callback, byteOffset, vtableSize } = options;
+
     const argDescriptors = callback.parameters
         .map((param) => renderParamDescriptor(context, param, param.type))
         .join(", ");
+
     const returnDescriptor = renderDescriptor(
         context,
         callback.returnValue.type,
         callback.returnValue.transferOwnership,
     );
+
     const lines = [
         `kind: ${sourceStringLiteral(kind)} as const,`,
         `className: ${sourceStringLiteral(structName)},`,
         `vfuncName: ${sourceStringLiteral(field.name)},`,
-        `byteOffset: ${byteOffset},`,
+        `byteOffset: ${String(byteOffset)},`,
+        `vtableSize: ${String(vtableSize)},`,
         `argDescriptors: [${argDescriptors}],`,
         `returnDescriptor: ${returnDescriptor},`,
     ];
+
     return `${key}: ${renderBraced(lines.join("\n"))},`;
 };
+
+export { renderVfuncMetadata };

package/src/store/gi-store.ts

@@ -1,35 +1,41 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { type CodegenFingerprint, FINGERPRINT_FILENAME } from "../fingerprint.js";
+import { FINGERPRINT_FILENAME, type GiFingerprint } from "../fingerprint.js";
 import { buildManifest, type StoreOptions, subpathExport, writeStore } from "./store-fs.js";
 
-const OVERRIDES_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "overrides");
-
-export type GiStoreOptions = StoreOptions;
+type GiStoreOptions = StoreOptions;
 
-export type GiNamespaceInput = {
+type GiNamespaceInput = {
     directory: string;
     rawSource: string;
 };
 
+type CollectedFile = {
+    fileName: string;
+    source: string;
+};
+
+const OVERRIDES_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "overrides");
+
 const overrideFiles = (directory: string): string[] => {
     const dir = join(OVERRIDES_ROOT, directory);
-    if (!existsSync(dir)) return [];
+
+    if (!existsSync(dir)) {
+        return [];
+    }
+
     return readdirSync(dir).filter((name) => name.endsWith(".ejs") && name !== "index.ts.ejs");
 };
 
 const barrelSource = (directory: string): string => {
     const overrideIndex = join(OVERRIDES_ROOT, directory, "index.ts.ejs");
+
     if (!existsSync(overrideIndex)) {
         return `export * from "./${directory}.js";\n`;
     }
-    return readFileSync(overrideIndex, "utf8");
-};
 
-type CollectedFile = {
-    fileName: string;
-    source: string;
+    return readFileSync(overrideIndex, "utf8");
 };
 
 const collectStoreSources = (
@@ -37,30 +43,35 @@ const collectStoreSources = (
 ): { collected: CollectedFile[]; exportsMap: Record<string, unknown> } => {
     const exportsMap: Record<string, unknown> = {};
     const collected: CollectedFile[] = [];
+
     for (const { directory, rawSource } of namespaces) {
         collected.push({
             fileName: `${directory}/${directory}.ts`,
             source: rawSource,
         });
+
         for (const file of overrideFiles(directory)) {
             collected.push({
                 fileName: `${directory}/overrides/${file.replace(/\.ejs$/, "")}`,
                 source: readFileSync(join(OVERRIDES_ROOT, directory, file), "utf8"),
             });
         }
+
         collected.push({
             fileName: `${directory}/index.ts`,
             source: barrelSource(directory),
         });
+
         exportsMap[`./${directory}`] = subpathExport(`${directory}/index`);
     }
+
     return { collected, exportsMap };
 };
 
-export const writeGiStore = (
+const writeGiStore = (
     options: GiStoreOptions,
     namespaces: GiNamespaceInput[],
-    fingerprint: CodegenFingerprint,
+    fingerprint: GiFingerprint,
 ): void => {
     const { collected, exportsMap } = collectStoreSources(namespaces);
 
@@ -77,3 +88,5 @@ export const writeGiStore = (
         rawFiles: [{ relativePath: FINGERPRINT_FILENAME, content: `${JSON.stringify(fingerprint, null, 2)}\n` }],
     });
 };
+
+export { writeGiStore, type GiStoreOptions, type GiNamespaceInput };

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

@@ -0,0 +1,152 @@
+import { sourceStringLiteral } from "@gtkx/utils";
+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 { 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 = {
+    imports: ImportsBuilder;
+    exportedNames: Set<string>;
+    exportLines: string[];
+};
+
+type CandidateExportOptions = {
+    targetNamespace: GirNamespace;
+    library: Library;
+    virtualNames: Set<string>;
+    intrinsicElements: GlibNamedClass[];
+    components: Record<string, ElementComponent>;
+};
+
+const generateElementComponentsSection = (
+    targetNamespace: GirNamespace,
+    library: Library,
+    options: {
+        imports: ImportsBuilder;
+        lazyElements: LazyElementSpec[];
+        intrinsicElements: GlibNamedClass[];
+        components: ElementComponentOverrides;
+    },
+): { source: string; exportedNames: Set<string> } => {
+    const collector: ExportCollector = { imports: options.imports, exportedNames: new Set(), exportLines: [] };
+    const lazyElements = options.lazyElements;
+    const virtualNames = new Set(lazyElements.map((entry) => entry.element));
+
+    collectCandidateExports(collector, {
+        targetNamespace,
+        library,
+        virtualNames,
+        intrinsicElements: options.intrinsicElements,
+        components: options.components,
+    });
+
+    collectLazyElementExports(collector, lazyElements);
+    const source = collector.exportLines.join("\n\n");
+
+    return { source, exportedNames: collector.exportedNames };
+};
+
+const appendCandidateExport = (
+    collector: ExportCollector,
+    candidate: GlibNamedClass,
+    options: CandidateExportOptions,
+): void => {
+    const { targetNamespace, library, virtualNames, components } = options;
+
+    if (candidate.namespace.name !== targetNamespace.name) {
+        return;
+    }
+
+    if (virtualNames.has(candidate.glibName)) {
+        return;
+    }
+
+    const line = renderCandidateExport(candidate, library, collector.imports, components);
+    collector.exportLines.push(line);
+    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) {
+            continue;
+        }
+
+        appendCandidateExport(collector, candidate, options);
+    }
+};
+
+const collectLazyElementExports = (collector: ExportCollector, lazyElements: LazyElementSpec[]): void => {
+    for (const spec of lazyElements) {
+        collector.imports.addNamed("@gtkx/react/internal", "createElementComponent", false);
+        collector.imports.addNamed("react", "ReactNode", true);
+        collector.exportLines.push(renderLazyElementExport(spec));
+        collector.exportedNames.add(spec.element);
+    }
+};
+
+const renderLazyElementExport = (spec: LazyElementSpec): string => {
+    const factory = `createElementComponent(${sourceStringLiteral(spec.element)})`;
+    const component = `export const ${spec.element}: (props: ${spec.typeName}) => ReactNode = ${factory};`;
+
+    return `${spec.typeSource}\n\n${component}`;
+};
+
+const renderCandidateExport = (
+    candidate: GlibNamedClass,
+    library: Library,
+    imports: ImportsBuilder,
+    components: Record<string, ElementComponent>,
+): string => {
+    const { glibName, klass, namespace } = candidate;
+    const ancestry = ancestorGlibNames(klass, namespace, library);
+    const component = resolveElementComponent(ancestry, components);
+    imports.addNamed("@gtkx/react/internal", "createElementComponent", false);
+    imports.addNamed("react", "ReactNode", true);
+
+    if (component !== undefined) {
+        imports.addNamed(component.module, component.export, false);
+    }
+
+    return `${renderJsDoc(klass.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>,
+): ElementComponent | undefined => {
+    for (const name of ancestry) {
+        const found = components[name];
+
+        if (found !== undefined) {
+            return found;
+        }
+    }
+
+    return undefined;
+};
+
+const renderElementComponentExport = (glibName: string, component: ElementComponent | undefined): string => {
+    const propsType = `${glibName}Props`;
+    const annotation = `(props: ${propsType}) => ReactNode`;
+    const factoryCall = `createElementComponent(${sourceStringLiteral(glibName)})`;
+
+    if (component === undefined) {
+        return `export const ${glibName}: ${annotation} = ${factoryCall};`;
+    }
+
+    return `export const ${glibName}: ${annotation} = ${component.export}(${factoryCall});`;
+};
+
+export { generateElementComponentsSection, type ElementComponent, type ElementComponentOverrides };

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

@@ -0,0 +1,24 @@
+/** 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 }>;
+
+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();
+
+    for (const [glibName, ref] of Object.entries(props)) {
+        elementProps.set(glibName, ref);
+    }
+};
+
+/** 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 };

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

@@ -0,0 +1,59 @@
+import { toCamelIdentifier } from "@gtkx/utils";
+import type { GirClass } from "../../gir/class.js";
+import { getChain, type GirIndex, type GirTypeEntry } from "./gir-index.js";
+import { getGlibName } from "./intrinsic-elements.js";
+
+type LazyElementSpec = {
+    element: string;
+    typeName: string;
+    typeSource: string;
+};
+
+const appendConstructOnlyNames = (klass: GirClass, names: string[]): void => {
+    for (const property of klass.properties) {
+        if (property.constructOnly) {
+            names.push(toCamelIdentifier(property.name));
+        }
+    }
+};
+
+const constructOnlyNames = (context: GirIndex, entry: GirTypeEntry): string[] => {
+    const names: string[] = [];
+
+    for (const klass of getChain(context, entry)) {
+        appendConstructOnlyNames(klass, names);
+    }
+
+    return names;
+};
+
+const createLazyElementSpec = (context: GirIndex, element: string, entry: GirTypeEntry): LazyElementSpec => {
+    const typeName = `${element}ElementProps`;
+    const baseName = getGlibName(entry.klass) ?? element;
+    const omitted = constructOnlyNames(context, entry);
+    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 };` };
+};
+
+/** 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();
+
+    for (const element of lazyElements) {
+        const entry = context.index.get(element);
+
+        if (entry === undefined) {
+            continue;
+        }
+
+        const list = specs.get(entry.namespace.name) ?? [];
+        list.push(createLazyElementSpec(context, element, entry));
+        specs.set(entry.namespace.name, list);
+    }
+
+    return specs;
+};
+
+export { lazyElementSpecs, type LazyElementSpec };

package/src/store/jsx/gir-index.ts

@@ -0,0 +1,62 @@
+import type { GirClass } from "../../gir/class.js";
+import type { Library } from "../../gir/library.js";
+import type { GirNamespace } from "../../gir/namespace.js";
+import { ancestorChain } from "../../gir/ancestry.js";
+import { getGlibName, implementedInterfaces } from "./intrinsic-elements.js";
+
+type GirTypeEntry = {
+    klass: GirClass;
+    namespace: GirNamespace;
+    isInterface: boolean;
+};
+
+type GirIndex = {
+    library: Library;
+    index: Map<string, GirTypeEntry>;
+};
+
+const indexClasses = (
+    index: Map<string, GirTypeEntry>,
+    classes: Iterable<GirClass>,
+    namespace: GirNamespace,
+    isInterface: boolean,
+): void => {
+    for (const klass of classes) {
+        const glibName = getGlibName(klass);
+
+        if (glibName !== undefined && !index.has(glibName)) {
+            index.set(glibName, { klass, namespace, isInterface });
+        }
+    }
+};
+
+const buildGirIndex = (library: Library): GirIndex => {
+    const index: Map<string, GirTypeEntry> = new Map();
+
+    for (const namespace of library.namespaces.values()) {
+        indexClasses(index, namespace.classes, namespace, false);
+        indexClasses(index, namespace.interfaces, namespace, true);
+    }
+
+    return { library, index };
+};
+
+const getChain = (context: GirIndex, entry: GirTypeEntry): GirClass[] => {
+    if (entry.isInterface) {
+        return [entry.klass];
+    }
+
+    const chain: GirClass[] = [];
+
+    for (const { klass } of ancestorChain(context.library, entry.klass, entry.namespace.name)) {
+        chain.push(klass);
+    }
+
+    for (const iface of implementedInterfaces(entry.klass, entry.namespace, context.library)) {
+        chain.push(iface.klass);
+    }
+
+    return chain;
+};
+
+export { buildGirIndex, getChain, type GirTypeEntry, type GirIndex };