@gtkx/codegen 1.2.2 → 1.3.0

package/src/store/gi/vtable.ts

@@ -11,6 +11,7 @@ import type { JsDocSpec } from "../../writer/doc.js";
 import {
     isInlineCallbackRef,
     isScalarRef,
+    renderCallbackType,
     renderDescriptor,
     renderParamDescriptor,
 } from "../../analysis/descriptor-render.js";
@@ -19,7 +20,6 @@ import {
     handlerParameters,
     parameterIdentifier,
     renamesWithInstance,
-    renderHandlerParameters,
     renderHandlerResultType,
 } from "../../analysis/param-structure.js";
 import { renderTsType } from "../../analysis/ts-type.js";
@@ -74,6 +74,12 @@ type Vtable = {
     slots: VtableSlot[];
 };
 
+type SlotParamPlan = {
+    parameters: GirParameter[];
+    argIndexMap: Map<number, number>;
+    decoded: Set<GirParameter>;
+};
+
 const PADDING_FIELD_NAME = /^(?:reserved|padding)\d*$/i;
 
 const UNCALLABLE_SLOT_KEYS: Set<string> = new Set([
@@ -86,6 +92,7 @@ const UNCALLABLE_SLOT_KEYS: Set<string> = new Set([
 const VTABLE_CACHE: WeakMap<GirClass, Vtable> = new WeakMap();
 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 OPAQUE_CALLBACK_NOTE = "Received as the raw address of the C function pointer.";
 
 const vfuncMemberName = (fieldName: string): string => `vfunc${pascalCase(fieldName)}`;
 
@@ -125,6 +132,79 @@ const vtableCallbackType = (context: ModuleContext, field: GirField): GirCallbac
     return type.value;
 };
 
+const isCallbackParam = (context: ModuleContext, parameter: GirParameter): boolean =>
+    parameter.type !== undefined && context.library.typeFor(parameter.type)?.kind === "callback";
+
+const isDecodedCallbackParam = (context: ModuleContext, parameter: GirParameter, index: number): boolean =>
+    isCallbackParam(context, parameter) &&
+    parameter.closureIndex === index + 1 &&
+    parameter.destroyIndex === undefined;
+
+const decodedSlotParams = (context: ModuleContext, callback: GirCallback): Set<GirParameter> => {
+    const decoded: Set<GirParameter> = new Set();
+
+    for (const [index, parameter] of callback.parameters.entries()) {
+        if (isDecodedCallbackParam(context, parameter, index)) {
+            decoded.add(parameter);
+        }
+    }
+
+    return decoded;
+};
+
+const companionIndices = (decoded: Set<GirParameter>): Set<number> => {
+    const companions: Set<number> = new Set();
+
+    for (const parameter of decoded) {
+        if (parameter.closureIndex !== undefined) {
+            companions.add(parameter.closureIndex);
+        }
+    }
+
+    return companions;
+};
+
+const slotParamPlan = (context: ModuleContext, callback: GirCallback): SlotParamPlan => {
+    const decoded = decodedSlotParams(context, callback);
+    const companions = companionIndices(decoded);
+    const parameters: GirParameter[] = [];
+    const argIndexMap: Map<number, number> = new Map();
+
+    for (const [index, parameter] of callback.parameters.entries()) {
+        if (companions.has(index)) {
+            continue;
+        }
+
+        argIndexMap.set(index, parameters.length);
+        parameters.push(parameter);
+    }
+
+    return { parameters, argIndexMap, decoded };
+};
+
+const isOpaqueCallbackParam = (context: ModuleContext, plan: SlotParamPlan, parameter: GirParameter): boolean =>
+    isCallbackParam(context, parameter) && !plan.decoded.has(parameter);
+
+const renderSlotParamDescriptor = (context: ModuleContext, parameter: GirParameter, plan: SlotParamPlan): string => {
+    if (plan.decoded.has(parameter)) {
+        const callbackDescriptor = renderCallbackType(context, parameter.type, parameter);
+
+        if (callbackDescriptor !== undefined) {
+            return callbackDescriptor;
+        }
+    }
+
+    return renderParamDescriptor(context, parameter, parameter.type, { argIndexMap: plan.argIndexMap });
+};
+
+const renderSlotParamTsType = (context: ModuleContext, plan: SlotParamPlan, parameter: GirParameter): string => {
+    if (isOpaqueCallbackParam(context, plan, parameter)) {
+        return parameter.nullable ? "bigint | null" : "bigint";
+    }
+
+    return renderTsType(context, parameter.type, parameter.nullable);
+};
+
 const vtableSlotEntry = (
     context: ModuleContext,
     field: GirField,
@@ -387,15 +467,35 @@ const hasCallableVfuncSlots = (context: ModuleContext, namespaceName: string, kl
 
 const slotDoc = (slot: VtableSlot): string | undefined => slot.vfunc?.doc ?? slot.field.doc ?? slot.callback.doc;
 
-const slotDocParameters = (slot: VtableSlot): GirParameter[] => {
+const slotParamDoc = (
+    context: ModuleContext,
+    plan: SlotParamPlan,
+    parameter: GirParameter,
+    doc: string | undefined,
+): string | undefined => {
+    if (!isOpaqueCallbackParam(context, plan, parameter)) {
+        return doc;
+    }
+
+    return doc === undefined ? OPAQUE_CALLBACK_NOTE : `${doc} ${OPAQUE_CALLBACK_NOTE}`;
+};
+
+const slotDocParameters = (context: ModuleContext, slot: VtableSlot): GirParameter[] => {
+    const plan = slotParamPlan(context, slot.callback);
     const [, ...parameters] = slot.callback.parameters;
     const vfuncParameters = slot.vfunc?.parameters ?? [];
 
-    return parameters.map((parameter, index) => ({ ...parameter, doc: vfuncParameters[index]?.doc ?? parameter.doc }));
+    return parameters
+        .map((parameter, index) => ({ parameter, index }))
+        .filter(({ index }) => plan.argIndexMap.has(index + 1))
+        .map(({ parameter, index }) => ({
+            ...parameter,
+            doc: slotParamDoc(context, plan, parameter, vfuncParameters[index]?.doc ?? parameter.doc),
+        }));
 };
 
-const slotDocSpec = (slot: VtableSlot): JsDocSpec => {
-    const parameters = slotDocParameters(slot);
+const slotDocSpec = (context: ModuleContext, slot: VtableSlot): JsDocSpec => {
+    const parameters = slotDocParameters(context, slot);
     const source = slot.vfunc ?? slot.callback;
 
     return {
@@ -446,12 +546,18 @@ 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 plan = slotParamPlan(context, slot.callback);
+    const [, ...parameters] = plan.parameters;
 
     const renderType = (ref: TypeId | undefined, isNullable: boolean): string =>
         renderTsType(context, ref, isNullable);
 
-    const signature = renderHandlerParameters(parameters, renderType).join(", ");
+    const signature = handlerParameters(parameters)
+        .map(
+            (parameter, index) =>
+                `${parameterIdentifier(parameter, index)}: ${renderSlotParamTsType(context, plan, parameter)}`)
+        .join(", ");
+
     const folded = foldedLengthParameters(context.library, slot.callback);
 
     const returnType = renderHandlerResultType({
@@ -470,13 +576,13 @@ 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));
+    const doc = renderJsDoc(slotDoc(slot), vfuncMemberNote(options), slotDocSpec(context, slot));
 
     if (mode !== "implementation") {
         return `${doc}${declaration};`;
     }
 
-    const [, ...parameters] = slot.callback.parameters;
+    const [, ...parameters] = slotParamPlan(context, slot.callback).parameters;
 
     const inputs = handlerParameters(parameters).map((parameter, index) =>
         parameterIdentifier(parameter, index));
@@ -511,9 +617,10 @@ const isVtableSlotEligible = (context: ModuleContext, callback: GirCallback): bo
 
 const renderVtableSlotDescriptor = (context: ModuleContext, vtable: Vtable, slot: VtableSlot): string => {
     const { key, field, callback, byteOffset } = slot;
+    const plan = slotParamPlan(context, callback);
 
-    const argDescriptors = callback.parameters
-        .map((param) => renderParamDescriptor(context, param, param.type))
+    const argDescriptors = plan.parameters
+        .map((param) => renderSlotParamDescriptor(context, param, plan))
         .join(", ");
 
     const returnDescriptor = renderDescriptor(

package/src/store/gi-store.ts

@@ -1,3 +1,4 @@
+import { sortStrings } from "@gtkx/utils";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -11,6 +12,12 @@ type GiNamespaceInput = {
     girFile: string;
 };
 
+type GiExternalNamespaceInput = {
+    directory: string;
+    packageName: string;
+    girFile: string;
+};
+
 const OVERRIDES_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "overrides");
 
 const overrideFiles = (directory: string): SourceModule[] => {
@@ -42,8 +49,17 @@ const barrelFile = (directory: string, girFile: string): SourceModule => {
     return overrideModule(barrel.fileName, overrideIndex);
 };
 
+const externalShimModule = ({ directory, packageName, girFile }: GiExternalNamespaceInput): SourceModule => ({
+    fileName: `${directory}/index.ts`,
+    source:
+        `/** @deprecated Import from "${packageName}" instead; this alias is removed in GTKX 2.0. */\n` +
+        `export * from "${packageName}";\n`,
+    origin: girFile,
+});
+
 const collectStoreSources = (
     namespaces: GiNamespaceInput[],
+    externalNamespaces: GiExternalNamespaceInput[],
 ): { collected: SourceModule[]; exportsMap: Record<string, unknown> } => {
     const exportsMap: Record<string, unknown> = {};
     const collected: SourceModule[] = [];
@@ -58,15 +74,29 @@ const collectStoreSources = (
         exportsMap[`./${directory}`] = subpathExport(`${directory}/index`);
     }
 
+    for (const external of externalNamespaces) {
+        collected.push(externalShimModule(external));
+        exportsMap[`./${external.directory}`] = subpathExport(`${external.directory}/index`);
+    }
+
     return { collected, exportsMap };
 };
 
+const storePeerDependencies = (externalNamespaces: GiExternalNamespaceInput[]): Record<string, string> =>
+    Object.fromEntries(
+        sortStrings(["@gtkx/runtime", ...externalNamespaces.map((entry) => entry.packageName)]).map((name) => [
+            name,
+            "*",
+        ]),
+    );
+
 const writeGiStore = (
     options: StoreOptions,
     namespaces: GiNamespaceInput[],
+    externalNamespaces: GiExternalNamespaceInput[],
     fingerprint: GiFingerprint,
 ): void => {
-    const { collected, exportsMap } = collectStoreSources(namespaces);
+    const { collected, exportsMap } = collectStoreSources(namespaces, externalNamespaces);
 
     writeStore({
         storeDir: options.storeDir,
@@ -76,10 +106,10 @@ const writeGiStore = (
             name: "@gtkx/gi",
             version: options.version,
             exports: exportsMap,
-            peerDependencies: { "@gtkx/runtime": "*" },
+            peerDependencies: storePeerDependencies(externalNamespaces),
         }),
         rawFiles: [{ relativePath: FINGERPRINT_FILENAME, content: `${JSON.stringify(fingerprint, null, 2)}\n` }],
     });
 };
 
-export { writeGiStore, type GiNamespaceInput };
+export { writeGiStore, type GiExternalNamespaceInput, type GiNamespaceInput };

package/src/store/jsx/jsx.ts

@@ -3,6 +3,7 @@ import type { GirClass } from "../../gir/class.js";
 import type { Library } from "../../gir/library.js";
 import type { GirNamespace } from "../../gir/namespace.js";
 import type { ImportsBuilder } from "../../writer/imports.js";
+import { externalPackageFor } from "../../gir/external-namespaces.js";
 import { renderBlock } from "../../writer/emit.js";
 import { getDoc } from "../gi/doc-spec.js";
 import { elementPropTypeFor } from "./element-prop-imports.js";
@@ -48,7 +49,8 @@ const addGiNamespace = (imports: ImportsBuilder, namespaceName: string, alias: s
         return;
     }
 
-    imports.addNamespace(`@gtkx/gi/${namespaceName.toLowerCase()}`, alias, true);
+    const specifier = externalPackageFor(namespaceName) ?? `@gtkx/gi/${namespaceName.toLowerCase()}`;
+    imports.addNamespace(specifier, alias, true);
 };
 
 const addReactBuiltin = (imports: ImportsBuilder, name: string): void => {

package/src/store/jsx-store.ts

@@ -1,24 +1,40 @@
+import { sortStrings } from "@gtkx/utils";
 import type { JsxNamespaceFile } from "./jsx/pipeline.js";
 import type { RawFile } from "./store-fs.js";
 import { buildManifest, namespaceBarrel, type StoreOptions, subpathExport, writeStore } from "./store-fs.js";
 
-const writeJsxStore = (
-    options: StoreOptions,
-    namespaces: JsxNamespaceFile[],
-    metadata: string,
-    rawFiles: RawFile[],
-): void => {
+type WriteJsxStoreParams = {
+    options: StoreOptions;
+    namespaces: JsxNamespaceFile[];
+    metadata: string;
+    externalPackages: string[];
+    rawFiles: RawFile[];
+};
+
+const jsxPeerDependencies = (externalPackages: string[]): Record<string, string> =>
+    Object.fromEntries(
+        sortStrings(["@gtkx/gi", "@gtkx/react", "react", ...externalPackages]).map((name) => [name, "*"]),
+    );
+
+const writeJsxStore = (params: WriteJsxStoreParams): void => {
+    const { options, namespaces, metadata, externalPackages, rawFiles } = params;
+
     const exportsMap: Record<string, unknown> = {
+        ".": subpathExport("index"),
         "./metadata": subpathExport("metadata"),
     };
 
     const files = [{ fileName: "metadata.ts", source: metadata }];
+    const indexExports: string[] = [];
 
     for (const { directory, source } of namespaces) {
         files.push({ fileName: `${directory}/${directory}.tsx`, source }, namespaceBarrel(directory));
         exportsMap[`./${directory}`] = subpathExport(`${directory}/index`);
+        indexExports.push(`export * from "./${directory}/index.js";`);
     }
 
+    files.push({ fileName: "index.ts", source: `${indexExports.join("\n")}\n` });
+
     writeStore({
         storeDir: options.storeDir,
         linkDir: options.linkDir,
@@ -27,7 +43,7 @@ const writeJsxStore = (
             name: "@gtkx/jsx",
             version: options.version,
             exports: exportsMap,
-            peerDependencies: { "@gtkx/gi": "*", "@gtkx/react": "*", react: "*" },
+            peerDependencies: jsxPeerDependencies(externalPackages),
         }),
         rawFiles,
     });

package/src/store/resolve-store.ts

@@ -24,6 +24,7 @@ const SCOPE = "@gtkx";
 const STORE_NAMES: string[] = ["gi", "jsx"];
 
 const STORE_CONSUMERS: string[] = [
+    "@gtkx/animated",
     "@gtkx/cli",
     "@gtkx/components",
     "@gtkx/css",
@@ -213,4 +214,4 @@ const resolveStore = (projectRoot: string): ResolvedStore => {
     };
 };
 
-export { getShadowingStorePaths, resolveStore, sweepProjectStaging, type ResolvedStore };
+export { getShadowingStorePaths, nodeModulesChain, resolveStore, sweepProjectStaging, type ResolvedStore };

package/src/store/store-fs.ts

@@ -13,6 +13,7 @@ import { dirname, join, relative } from "node:path";
 import { keepFailedProject, type SourceModule } from "../compile.js";
 import { createStagingDir } from "../staging.js";
 import { compileStore } from "./compile-store.js";
+import { ensureExternalPackageLinks, resetExternalPackageLinks } from "./external-package-links.js";
 
 /** Where one generated store is written and how it is reached. */
 type StoreOptions = {
@@ -88,6 +89,7 @@ const writeStore = (params: WriteStoreParams): void => {
     try {
         buildTempStore(tmp, params);
         swapStore(tmp, params.storeDir);
+        resetExternalPackageLinks(params.storeDir);
         ensureStoreLink(params);
     } catch (error) {
         throw keepFailedProject({ projectDir: tmp, keepAt, error });
@@ -148,11 +150,15 @@ const isStoreLinked = (link: StoreLink): boolean => {
 };
 
 const ensureStoreLink = (link: StoreLink): void => {
-    if (!existsSync(join(link.storeDir, "package.json")) || isStoreLinked(link)) {
+    if (!existsSync(join(link.storeDir, "package.json"))) {
         return;
     }
 
-    symlinkRelative(link.linkDir, link.storeDir);
+    if (!isStoreLinked(link)) {
+        symlinkRelative(link.linkDir, link.storeDir);
+    }
+
+    ensureExternalPackageLinks(link);
 };
 
 const storeWriteMessage = (storeDir: string, error: unknown): string =>
@@ -176,7 +182,9 @@ export {
     buildManifest,
     ensureStoreLink,
     namespaceBarrel,
+    symlinkRelative,
     writeStore,
+    type StoreLink,
     type StoreOptions,
     type RawFile,
 };

package/src/writer/context.ts

@@ -1,5 +1,6 @@
 import type { Library } from "../gir/library.js";
 import type { GirNamespace } from "../gir/namespace.js";
+import { externalPackageFor } from "../gir/external-namespaces.js";
 import { type Declaration, ModuleBuilder } from "./module.js";
 
 class ModuleContext {
@@ -34,6 +35,7 @@ class ModuleContext {
         }
 
         this.module.imports.addSideEffect("../gobject/overrides/object.js");
+        this.module.imports.addSideEffect("../gobject/overrides/param-spec-getters.js");
         this.module.imports.addSideEffect("../gobject/overrides/value.js");
     }
 
@@ -42,6 +44,15 @@ class ModuleContext {
             return namespaceName;
         }
 
+        const packageName = externalPackageFor(namespaceName);
+
+        if (packageName !== undefined) {
+            this.module.imports.addSideEffect(packageName);
+            this.module.imports.addNamespace(packageName, namespaceName);
+
+            return namespaceName;
+        }
+
         const directory = namespaceName.toLowerCase();
         const isFoundational = directory === "gobject" || directory === "glib";
         const path = isFoundational ? `../${directory}/${directory}.js` : `../${directory}/index.js`;

package/src/writer/gtk-doc.ts

@@ -1,6 +1,14 @@
-import { camelCase } from "@gtkx/utils";
+import { camelCase, kebabCase } from "@gtkx/utils";
+import { HIDDEN_SYMBOLS } from "../gir/hidden-symbols.js";
 
 const CONSTANT_MAP: Record<string, string> = { TRUE: "true", FALSE: "false", NULL: "null" };
+
+const HIDDEN_LINK_PREFIXES: Map<string, string> = new Map([
+    ["GLib", "g"],
+    ["GObject", "g"],
+    ["Gio", "g"],
+]);
+
 const CALLABLE_LINK_KINDS: Set<string> = new Set(["method", "func", "ctor", "vfunc", "id"]);
 const SENTINEL = String.fromCodePoint(0xE0_00);
 const CODE_BLOCK_OPEN = "|[";
@@ -27,8 +35,37 @@ const DOCBOOK_LIST_PATTERN = /<\/?itemizedlist>\s*/g;
 const DOCBOOK_PARA_PATTERN = /<\/?para>\s*/g;
 const BLANK_LINE_RUN_PATTERN = /\n{3,}/g;
 
+const cSymbolSegment = (segment: string): string => kebabCase(segment).replaceAll("-", "_");
+
+const hiddenLinkCandidate = (segments: string[]): string | undefined => {
+    const [namespace, ...rest] = segments;
+    const prefix = namespace === undefined ? undefined : HIDDEN_LINK_PREFIXES.get(namespace);
+
+    if (prefix === undefined || rest.length === 0) {
+        return undefined;
+    }
+
+    return [prefix, ...rest.map((segment) => cSymbolSegment(segment))].join("_");
+};
+
+const hiddenCIdentifier = (kind: string, target: string, segments: string[]): string | undefined => {
+    if (!CALLABLE_LINK_KINDS.has(kind)) {
+        return undefined;
+    }
+
+    const candidate = kind === "id" ? target : hiddenLinkCandidate(segments);
+
+    return candidate !== undefined && HIDDEN_SYMBOLS.has(candidate) ? candidate : undefined;
+};
+
 const renderLink = (kind: string, target: string): string => {
     const segments = target.split(/::|[.:]/);
+    const hidden = hiddenCIdentifier(kind, target, segments);
+
+    if (hidden !== undefined) {
+        return `\`${hidden}()\``;
+    }
+
     const lastIndex = segments.length - 1;
 
     if (kind === "property" || CALLABLE_LINK_KINDS.has(kind)) {