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

package/src/khronos/render.ts

@@ -1,10 +1,30 @@
 import { lowerFirst, sourceStringLiteral, toCamelIdentifier } from "@gtkx/utils";
+import type { CommandPlan, GlScalar, ReturnPlan } from "./plan.js";
 import { tBind, tInlineStruct, tRef, tString, tUint8, tVoid } from "../analysis/descriptor.js";
 import { type OutArg, planArgs, scalarAliasOrGroup, scalarPrefixArgs, trackInto } from "./args.js";
 import { commandJsDoc, inParamDocLine, singularJsDoc } from "./jsdoc.js";
-import type { CommandPlan, ReturnPlan } from "./plan.js";
+
+type RenderedCommand = {
+    exportName: string;
+    binding?: string;
+    declaration: string;
+};
+
+type EmittedReturn = {
+    tsType: string;
+    descriptor: string;
+    expr?: (call: string) => string;
+};
+
+type GenSingularShape = {
+    countScalar: GlScalar;
+    outScalar: GlScalar;
+    objectClass: string;
+};
 
 const GL_LIB_EXPRESSION = "LIB";
+const GEN_FAMILY = /^gl(Gen|Create)[A-Z][A-Za-z]*s$/;
+const DELETE_FAMILY = /^glDelete[A-Z][A-Za-z]*s$/;
 
 const glBind = (name: string, argList: string, returnType: string): string =>
     tBind({
@@ -23,68 +43,80 @@ const singularize = (plural: string): string =>
 const renderDescriptorList = (descriptors: string[]): string =>
     descriptors.length === 0 ? "[]" : `[${descriptors.join(", ")}]`;
 
-export type RenderedCommand = {
-    exportName: string;
-    binding?: string;
-    declaration: string;
-};
-
-type EmittedReturn = {
-    tsType: string;
-    descriptor: string;
-    expr?: (call: string) => string;
-};
-
 const buildEmittedReturn = (
     plan: ReturnPlan,
     returnGroup: string | undefined,
     usedTypes: Set<string>,
 ): EmittedReturn => {
     const track = trackInto(usedTypes);
+
     switch (plan.kind) {
-        case "void":
+        case "void": {
             return { tsType: "void", descriptor: tVoid };
+        }
         case "scalar": {
             const alias = track(scalarAliasOrGroup(plan.scalar, returnGroup));
+
             return { tsType: alias, descriptor: plan.scalar.descriptor, expr: (call) => `${call} as ${alias}` };
         }
-        case "boolean":
+        case "boolean": {
             return { tsType: "boolean", descriptor: tUint8, expr: (call) => `(${call} as number) !== 0` };
-        case "string":
+        }
+        case "string": {
             return { tsType: "string", descriptor: tString("borrowed"), expr: (call) => `${call} as string` };
-        case "sync":
+        }
+        case "sync": {
             return { tsType: track("GLsync"), descriptor: tInlineStruct(), expr: (call) => `${call} as GLsync` };
-        case "opaque-pointer":
+        }
+        case "opaque-pointer": {
             return {
                 tsType: track("GLpointer"),
                 descriptor: tInlineStruct(),
                 expr: (call) => `${call} as GLpointer`,
             };
+        }
     }
 };
 
 const returnTsType = (returned: EmittedReturn, outs: OutArg[]): string => {
-    if (outs.length === 0) return returned.tsType;
+    if (outs.length === 0) {
+        return returned.tsType;
+    }
+
     const outTypes = outs.map((out) => out.tsType);
+
     if (returned.expr === undefined) {
         return outTypes.length === 1 && outTypes[0] !== undefined ? outTypes[0] : `[${outTypes.join(", ")}]`;
     }
+
     return `[${returned.tsType}, ${outTypes.join(", ")}]`;
 };
 
+const returnNoOut = (call: string, returned: EmittedReturn): string[] =>
+    returned.expr === undefined ? [`${call};`] : [`return ${returned.expr(call)};`];
+
 const returnStatements = (call: string, returned: EmittedReturn, outs: OutArg[]): string[] => {
     if (outs.length === 0) {
-        return returned.expr === undefined ? [`${call};`] : [`return ${returned.expr(call)};`];
+        return returnNoOut(call, returned);
     }
+
     const outValues = outs.map((out) => `${out.cellName}.value`);
+
     if (returned.expr === undefined) {
-        const tail = outValues.length === 1 ? `return ${outValues[0]};` : `return [${outValues.join(", ")}];`;
+        const [single] = outValues;
+
+        const tail =
+            single !== undefined && outValues.length === 1
+                ? `return ${single};`
+                : `return [${outValues.join(", ")}];`;
+
         return [`${call};`, tail];
     }
+
     return [`const result = ${call};`, `return [${returned.expr("result")}, ${outValues.join(", ")}];`];
 };
 
-export const renderCommand = (
+const renderCommand = (
     plan: CommandPlan & { ok: true },
     feature: string,
     usedTypes: Set<string>,
@@ -100,94 +132,199 @@ export const renderCommand = (
     const jsDoc = commandJsDoc({ command, feature, ins, outs, returnPlan: plan.returnPlan });
     const seeds = outs.map((out) => out.seed);
     const bindExpression = glBind(command.name, descriptors, returned.descriptor);
-    const inline = plan.params.some((paramPlan) => paramPlan.kind === "string-out");
-    const bindingName = inline ? "binding" : toCamelIdentifier(command.name);
+    const isInline = plan.params.some((paramPlan) => paramPlan.kind === "string-out");
+    const bindingName = isInline ? "binding" : toCamelIdentifier(command.name);
+
     const body = [
         ...seeds,
-        ...(inline ? [`const ${bindingName} = ${bindExpression};`] : []),
+        ...(isInline ? [`const ${bindingName} = ${bindExpression};`] : []),
         ...returnStatements(`${bindingName}(${argNames})`, returned, outs),
     ]
         .map((line) => `    ${line}`)
         .join("\n");
+
     return {
         exportName,
-        ...(inline ? {} : { binding: `const ${bindingName} = ${bindExpression};` }),
+        ...(!isInline && { binding: `const ${bindingName} = ${bindExpression};` }),
         declaration: `${jsDoc}\nexport function ${exportName}(${signature}): ${tsReturn} {\n${body}\n}`,
     };
 };
 
-const GEN_FAMILY = /^gl(Gen|Create)[A-Z][A-Za-z]*s$/;
-const DELETE_FAMILY = /^glDelete[A-Z][A-Za-z]*s$/;
+const singularCommandJsDoc = (
+    plan: CommandPlan & { ok: true },
+    feature: string,
+    summary: string,
+    body: string[],
+): string => singularJsDoc({ commandName: plan.command.name, feature, summary, body });
 
-export const deriveGenSingular = (
+const genSingularScalars = (
+    plan: CommandPlan & { ok: true },
+): { countScalar: GlScalar; outScalar: GlScalar; lenParamName: string } | undefined => {
+    const countPlan = plan.params.at(-2);
+
+    if (countPlan?.kind !== "scalar") {
+        return undefined;
+    }
+
+    const outPlan = plan.params.at(-1);
+
+    if (outPlan?.kind !== "ref-array-out") {
+        return undefined;
+    }
+
+    return { countScalar: countPlan.scalar, outScalar: outPlan.scalar, lenParamName: outPlan.lenParamName };
+};
+
+const genSingularObjectClass = (plan: CommandPlan & { ok: true }, lenParamName: string): string | undefined => {
+    const countParam = plan.command.params[plan.params.length - 2];
+    const outParam = plan.command.params[plan.params.length - 1];
+
+    if (countParam === undefined || outParam === undefined) {
+        return undefined;
+    }
+
+    if (lenParamName !== countParam.name) {
+        return undefined;
+    }
+
+    return outParam.objectClass;
+};
+
+const genSingularShape = (plan: CommandPlan & { ok: true }): GenSingularShape | undefined => {
+    const scalars = genSingularScalars(plan);
+
+    if (scalars === undefined) {
+        return undefined;
+    }
+
+    const objectClass = genSingularObjectClass(plan, scalars.lenParamName);
+
+    if (objectClass === undefined) {
+        return undefined;
+    }
+
+    return { countScalar: scalars.countScalar, outScalar: scalars.outScalar, objectClass };
+};
+
+const deriveGenSingular = (
     plan: CommandPlan & { ok: true },
     feature: string,
     usedTypes: Set<string>,
 ): RenderedCommand | undefined => {
-    if (!GEN_FAMILY.test(plan.command.name)) return undefined;
-    const countIndex = plan.params.length - 2;
-    const outIndex = plan.params.length - 1;
-    const countPlan = plan.params[countIndex];
-    const outPlan = plan.params[outIndex];
-    const countParam = plan.command.params[countIndex];
-    const outParam = plan.command.params[outIndex];
-    if (countPlan?.kind !== "scalar" || outPlan?.kind !== "ref-array-out") return undefined;
-    if (countParam === undefined || outParam === undefined) return undefined;
-    if (outPlan.lenParamName !== countParam.name || outParam.objectClass === undefined) return undefined;
+    if (!GEN_FAMILY.test(plan.command.name)) {
+        return undefined;
+    }
+
+    const shape = genSingularShape(plan);
+
+    if (shape === undefined) {
+        return undefined;
+    }
+
     const prefix = scalarPrefixArgs(plan, usedTypes);
-    if (prefix === undefined) return undefined;
+
+    if (prefix === undefined) {
+        return undefined;
+    }
+
+    const { countScalar, outScalar, objectClass } = shape;
     const exportName = singularize(commandExportName(plan.command.name));
     const bindingName = `${plan.command.name}Single`;
-    const descriptors = [
-        ...prefix.map((arg) => arg.descriptor),
-        countPlan.scalar.descriptor,
-        tRef(outPlan.scalar.descriptor),
-    ];
-    usedTypes.add(outPlan.scalar.tsAlias);
+    const descriptors = [...prefix.map((arg) => arg.descriptor), countScalar.descriptor, tRef(outScalar.descriptor)];
+    usedTypes.add(outScalar.tsAlias);
     const signature = prefix.map((arg) => `${arg.name}: ${arg.tsType}`).join(", ");
     const callArgs = [...prefix.map((arg) => arg.name), "1", "out"].join(", ");
-    const jsDoc = singularJsDoc({
-        commandName: plan.command.name,
+
+    const jsDoc = singularCommandJsDoc(
+        plan,
         feature,
-        summary: `Returns one ${outParam.objectClass} object name via \`${plan.command.name}(${prefix.length > 0 ? "..., " : ""}1, ...)\`.`,
-        body: [
-            ...prefix.map((arg) => inParamDocLine(plan.command, arg)),
-            ` * @returns The new ${outParam.objectClass} object name`,
-        ],
-    });
-    const body = [`    const out = { value: 0 };`, `    ${bindingName}(${callArgs});`, "    return out.value;"].join(
+        `Returns one ${objectClass} object name via ` +
+        `\`${plan.command.name}(${prefix.length > 0 ? "..., " : ""}1, ...)\`.`,
+        [...prefix.map((arg) => inParamDocLine(plan.command, arg)), ` * @returns The new ${objectClass} object name`],
+    );
+
+    const body = ["    const out = { value: 0 };", `    ${bindingName}(${callArgs});`, "    return out.value;"].join(
         "\n",
     );
+
     const binding = glBind(plan.command.name, renderDescriptorList(descriptors), tVoid);
+
     return {
         exportName,
         binding: `const ${bindingName} = ${binding};`,
-        declaration: `${jsDoc}\nexport function ${exportName}(${signature}): ${outPlan.scalar.tsAlias} {\n${body}\n}`,
+        declaration: `${jsDoc}\nexport function ${exportName}(${signature}): ${outScalar.tsAlias} {\n${body}\n}`,
     };
 };
 
-export const deriveDeleteSingular = (
+const deleteSingularAlias = (plan: CommandPlan & { ok: true }): string | undefined => {
+    if (plan.params.length !== 2) {
+        return undefined;
+    }
+
+    const [countPlan, arrayPlan] = plan.params;
+
+    if (countPlan?.kind !== "scalar") {
+        return undefined;
+    }
+
+    if (arrayPlan?.kind !== "array-in") {
+        return undefined;
+    }
+
+    return arrayPlan.scalar.tsAlias;
+};
+
+const deleteSingularObjectClass = (plan: CommandPlan & { ok: true }): string | undefined => {
+    const [countParam, arrayParam] = plan.command.params;
+
+    if (countParam === undefined || arrayParam === undefined) {
+        return undefined;
+    }
+
+    if (arrayParam.len !== countParam.name) {
+        return undefined;
+    }
+
+    return arrayParam.objectClass;
+};
+
+const deriveDeleteSingular = (
     plan: CommandPlan & { ok: true },
     feature: string,
     usedTypes: Set<string>,
 ): RenderedCommand | undefined => {
-    if (!DELETE_FAMILY.test(plan.command.name)) return undefined;
-    if (plan.params.length !== 2) return undefined;
-    const [countPlan, arrayPlan] = plan.params;
-    const [countParam, arrayParam] = plan.command.params;
-    if (countPlan?.kind !== "scalar" || arrayPlan?.kind !== "array-in") return undefined;
-    if (countParam === undefined || arrayParam === undefined) return undefined;
-    if (arrayParam.len !== countParam.name || arrayParam.objectClass === undefined) return undefined;
+    if (!DELETE_FAMILY.test(plan.command.name)) {
+        return undefined;
+    }
+
+    const scalarAlias = deleteSingularAlias(plan);
+
+    if (scalarAlias === undefined) {
+        return undefined;
+    }
+
+    const objectClass = deleteSingularObjectClass(plan);
+
+    if (objectClass === undefined) {
+        return undefined;
+    }
+
+    usedTypes.add(scalarAlias);
     const exportName = singularize(commandExportName(plan.command.name));
-    usedTypes.add(arrayPlan.scalar.tsAlias);
-    const jsDoc = singularJsDoc({
-        commandName: plan.command.name,
+
+    const jsDoc = singularCommandJsDoc(
+        plan,
         feature,
-        summary: `Deletes one ${arrayParam.objectClass} object name via \`${plan.command.name}(1, ...)\`.`,
-        body: [` * @param name - The ${arrayParam.objectClass} object name to delete`],
-    });
+        `Deletes one ${objectClass} object name via \`${plan.command.name}(1, ...)\`.`,
+        [` * @param name - The ${objectClass} object name to delete`],
+    );
+
     return {
         exportName,
-        declaration: `${jsDoc}\nexport function ${exportName}(name: ${arrayPlan.scalar.tsAlias}): void {\n    ${plan.command.name}(1, [name]);\n}`,
+        declaration:
+            `${jsDoc}\nexport function ${exportName}(name: ${scalarAlias}): void {\n` +
+            `    ${plan.command.name}(1, [name]);\n}`,
     };
 };
+
+export { renderCommand, deriveGenSingular, deriveDeleteSingular, type RenderedCommand };

package/src/khronos/select.ts

@@ -2,7 +2,7 @@ import type { GlEnum, GlFeature, GlInterfaceBlock, GlRegistry } from "./model.js
 
 type GlProfile = "core";
 
-export type GlSelection = {
+type GlSelection = {
     api: string;
     version: number;
     profile: GlProfile;
@@ -13,9 +13,17 @@ type GlSubset = {
     enums: Map<string, string>;
 };
 
-const blockApplies = (block: GlInterfaceBlock, selection: GlSelection): boolean =>
+const isBlockApplicable = (block: GlInterfaceBlock, selection: GlSelection): boolean =>
     block.profile === undefined || block.profile === selection.profile;
 
+const addMissing = (target: Map<string, string>, names: string[], value: string): void => {
+    for (const name of names) {
+        if (!target.has(name)) {
+            target.set(name, value);
+        }
+    }
+};
+
 const applyRequires = (
     feature: GlFeature,
     selection: GlSelection,
@@ -23,13 +31,22 @@ const applyRequires = (
     enums: Map<string, string>,
 ): void => {
     for (const block of feature.requires) {
-        if (!blockApplies(block, selection)) continue;
-        for (const name of block.commands) {
-            if (!commands.has(name)) commands.set(name, feature.name);
-        }
-        for (const name of block.enums) {
-            if (!enums.has(name)) enums.set(name, feature.name);
+        if (!isBlockApplicable(block, selection)) {
+            continue;
         }
+
+        addMissing(commands, block.commands, feature.name);
+        addMissing(enums, block.enums, feature.name);
+    }
+};
+
+const removeBlock = (block: GlInterfaceBlock, commands: Map<string, string>, enums: Map<string, string>): void => {
+    for (const name of block.commands) {
+        commands.delete(name);
+    }
+
+    for (const name of block.enums) {
+        enums.delete(name);
     }
 };
 
@@ -40,28 +57,41 @@ const applyRemoves = (
     enums: Map<string, string>,
 ): void => {
     for (const block of feature.removes) {
-        if (!blockApplies(block, selection)) continue;
-        for (const name of block.commands) commands.delete(name);
-        for (const name of block.enums) enums.delete(name);
+        if (!isBlockApplicable(block, selection)) {
+            continue;
+        }
+
+        removeBlock(block, commands, enums);
     }
 };
 
-export const selectSubset = (registry: GlRegistry, selection: GlSelection): GlSubset => {
+const selectSubset = (registry: GlRegistry, selection: GlSelection): GlSubset => {
     const features = registry.features
         .filter((feature) => feature.api === selection.api && feature.number <= selection.version)
-        .sort((a, b) => a.number - b.number);
+        .toSorted((a, b) => a.number - b.number);
+
+    const commands: Map<string, string> = new Map();
+    const enums: Map<string, string> = new Map();
+
+    for (const feature of features) {
+        applyRequires(feature, selection, commands, enums);
+    }
+
+    for (const feature of features) {
+        applyRemoves(feature, selection, commands, enums);
+    }
 
-    const commands = new Map<string, string>();
-    const enums = new Map<string, string>();
-    for (const feature of features) applyRequires(feature, selection, commands, enums);
-    for (const feature of features) applyRemoves(feature, selection, commands, enums);
     return { commands, enums };
 };
 
-export const resolveEnum = (registry: GlRegistry, name: string): GlEnum => {
+const resolveEnum = (registry: GlRegistry, name: string): GlEnum => {
     const found = registry.enums.find((candidate) => candidate.name === name);
+
     if (found === undefined) {
         throw new Error(`Enum token ${name} has no definition in the registry`);
     }
+
     return found;
 };
+
+export { selectSubset, resolveEnum, type GlSelection };

package/src/react/element-config.ts

@@ -0,0 +1,97 @@
+import type { ModuleExport } from "@gtkx/react/config";
+import { readdirSync } from "node:fs";
+import type { OmittedProps } from "../store/jsx/omitted-props.js";
+
+/** The codegen-relevant subset of a React element config; behaviors are ignored at codegen time. */
+type BuiltinElement = { component?: ModuleExport; lazy?: boolean; props?: ModuleExport; omitProps?: string[] };
+
+/** The framework's built-in element config, split into the maps codegen consumes. */
+type BuiltinElements = {
+    components: Record<string, ModuleExport>;
+    lazyElements: string[];
+    props: Record<string, ModuleExport>;
+    omitProps: OmittedProps;
+};
+
+const CONFIG_ENTRYPOINT = "config";
+const CONFIG_SUFFIX = `/${CONFIG_ENTRYPOINT}`;
+
+const presentNamespaceDirs = (giStoreDir: string): Set<string> => {
+    const dirs: Set<string> = new Set();
+    const entries = readdirSync(giStoreDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            dirs.add(entry.name);
+        }
+    }
+
+    return dirs;
+};
+
+/**
+ * The clean, reconciler-free `@gtkx/react` config entrypoints to import: the base `config` entry plus
+ * each namespace's `<ns>/config` entry whose GIR namespace is present in the gi store.
+ */
+const configEntrypoints = (reactSubexports: string[], present: Set<string>): string[] =>
+    reactSubexports.filter((sub) => {
+        if (sub === CONFIG_ENTRYPOINT) {
+            return true;
+        }
+
+        return sub.endsWith(CONFIG_SUFFIX) && present.has(sub.slice(0, sub.length - CONFIG_SUFFIX.length));
+    });
+
+const importBuiltinElements = async (entrypoint: string): Promise<Record<string, BuiltinElement>> => {
+    const specifier = `@gtkx/react/${entrypoint}`;
+
+    const imported = (await import(/* @vite-ignore */ specifier)) as {
+        BUILTIN_ELEMENTS?: Record<string, BuiltinElement>;
+    };
+
+    return imported.BUILTIN_ELEMENTS ?? {};
+};
+
+const applyBuiltinElement = (target: BuiltinElements, type: string, config: BuiltinElement): void => {
+    if (config.component !== undefined) {
+        target.components[type] = config.component;
+    }
+
+    if (config.props !== undefined) {
+        target.props[type] = config.props;
+    }
+
+    if (config.omitProps !== undefined) {
+        target.omitProps[type] = [...(target.omitProps[type] ?? []), ...config.omitProps];
+    }
+
+    if (config.lazy === true) {
+        target.lazyElements.push(type);
+    }
+};
+
+/**
+ * Reads the framework's built-in element config by importing the freshly linked `@gtkx/react` config
+ * entrypoints. These are reconciler-free, so importing them resolves `@gtkx/gi` but never `virtual:gtkx-config`;
+ * it must run only after the gi store has been linked.
+ */
+const collectBuiltinElements = (target: BuiltinElements, elements: Record<string, BuiltinElement>): void => {
+    for (const [type, config] of Object.entries(elements)) {
+        applyBuiltinElement(target, type, config);
+    }
+};
+
+const readBuiltinElements = async (reactSubexports: string[], giStoreDir: string): Promise<BuiltinElements> => {
+    const present = presentNamespaceDirs(giStoreDir);
+    const entrypoints = configEntrypoints(reactSubexports, present);
+    const result: BuiltinElements = { components: {}, lazyElements: [], props: {}, omitProps: {} };
+
+    for (const entrypoint of entrypoints) {
+        collectBuiltinElements(result, await importBuiltinElements(entrypoint));
+    }
+
+    return result;
+};
+
+export { type ModuleExport } from "@gtkx/react/config";
+export { readBuiltinElements, type BuiltinElement, type BuiltinElements };