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

package/src/codegen/report.ts

@@ -2,19 +2,27 @@ import type { RunCodegenResult } from "./run-codegen.js";
 
 const PREFIX = "codegen: ";
 
-export const formatCodegenResult = (result: RunCodegenResult, totalMs: number): string[] => {
+const formatCodegenResult = (result: RunCodegenResult, totalMs: number): string[] => {
     const details: string[] = [];
+
     if (result.configFile) {
         details.push(`config=${result.configFile}`);
     }
+
     if (result.libraries) {
         details.push(`libraries=${result.libraries.join(", ")}`);
     }
+
     if (result.girPath) {
         details.push(`girPath=${result.girPath.join(":")}`);
     }
+
     details.push(
-        `${result.namespaces} namespaces, ${result.intrinsicElements} intrinsic elements in ${result.duration}ms (total ${totalMs}ms)`,
+        `${String(result.namespaces)} namespaces, ${String(result.intrinsicElements)} intrinsic elements ` +
+        `in ${String(result.duration)}ms (total ${String(totalMs)}ms)`,
     );
+
     return details.map((detail) => PREFIX + detail);
 };
+
+export { formatCodegenResult };

package/src/codegen/run-codegen.ts

@@ -1,14 +1,15 @@
-import { rmSync } from "node:fs";
-import { resolve } from "node:path";
 import { runCodegen as runCodegenCore } from "@gtkx/codegen";
-import { type Config, type ElementProp, loadConfig } from "@gtkx/config";
+import { type Config, loadConfig } from "@gtkx/config";
+import { resolveLazyElements } from "@gtkx/config/internal";
 import { info } from "@gtkx/utils";
+import { rmSync } from "node:fs";
+import { resolve } from "node:path";
 import { resolveDataDir } from "../internal/data-dir.js";
 import { emitSchemaEnv } from "../settings/schema.js";
 import { type CodegenInputs, isCodegenStale, resolveCodegenInputs } from "./freshness.js";
 import { type CodegenStore, resolveCodegenContext } from "./store-resolver.js";
 
-export type RunCodegenOptions = {
+type RunCodegenOptions = {
     cwd?: string;
     mode?: string | undefined;
     force?: boolean;
@@ -21,7 +22,7 @@ type LoadedConfig = {
     configFile: string | undefined;
 };
 
-export type RunCodegenResult = {
+type RunCodegenResult = {
     regenerated: boolean;
     namespaces: number;
     intrinsicElements: number;
@@ -31,6 +32,27 @@ export type RunCodegenResult = {
     libraries?: string[] | undefined;
 };
 
+type CodegenOptionsInput = {
+    store: CodegenStore;
+    libraries: string[];
+    girPath: string[];
+    elements: Config["elements"];
+};
+
+type PreparedCodegen = CodegenInputs & { force: boolean };
+
+type RunOptionsInput = {
+    root: string;
+    mode: string | undefined;
+    inputs: CodegenInputs | null;
+    resolved: LoadedConfig;
+};
+
+const GIR_PATH_MISSING_MESSAGE =
+    "No GIR search paths available. Install gobject-introspection " +
+    "(Linux: `sudo dnf install gobject-introspection-devel` or `sudo apt install libgirepository1.0-dev`), " +
+    "or set `girPath` in gtkx.config.ts.";
+
 const removeSharedStoreShadow = (cwd: string): void => {
     for (const path of [
         resolve(cwd, "node_modules/.gtkx/gi"),
@@ -42,67 +64,89 @@ const removeSharedStoreShadow = (cwd: string): void => {
     }
 };
 
-type CodegenOptionsInput = {
-    store: CodegenStore;
-    libraries: string[];
-    girPath: string[];
-    elementProps: Record<string, ElementProp[]>;
-};
+const userModuleExports = (
+    elements: Config["elements"],
+    key: "component" | "props",
+): Record<string, { module: string; export: string }> =>
+    Object.fromEntries(
+        Object.entries(elements?.config ?? {}).flatMap(([type, entry]) => {
+            const ref = entry[key];
+
+            return ref === undefined ? [] : [[type, ref] as const];
+        }),
+    );
 
-const codegenOptions = ({ store, libraries, girPath, elementProps }: CodegenOptionsInput) => ({
+const codegenOptions = ({ store, libraries, girPath, elements }: CodegenOptionsInput) => ({
     libraries,
     girPath,
-    elementProps,
     gi: {
         storeDir: store.giStoreDir,
         linkDir: store.giLinkDir,
         version: store.runtimeVersion,
     },
     jsx:
-        store.react !== null
-            ? {
-                  storeDir: store.jsxStoreDir,
-                  linkDir: store.jsxLinkDir,
-                  version: store.react.version,
-              }
-            : undefined,
+        store.react === null
+            ? undefined
+            : {
+                    storeDir: store.jsxStoreDir,
+                    linkDir: store.jsxLinkDir,
+                    version: store.react.version,
+                },
+    reactSubexports: store.react?.subexports ?? [],
+    userComponents: userModuleExports(elements, "component"),
+    userProps: userModuleExports(elements, "props"),
+    userLazyElements: resolveLazyElements(elements),
 });
 
-export const runCodegen = async (options: RunCodegenOptions = {}): Promise<RunCodegenResult> => {
-    const cwd = options.cwd ?? process.cwd();
-
-    const { config, configFile } = options.resolved ?? (await loadConfig(cwd, { mode: options.mode }));
+const disabledCodegenResult = (configFile: string | undefined): RunCodegenResult => ({
+    regenerated: false,
+    namespaces: 0,
+    intrinsicElements: 0,
+    duration: 0,
+    girPath: [],
+    configFile,
+    libraries: [],
+});
 
-    if (config.codegen === false) {
-        removeSharedStoreShadow(cwd);
-        return {
-            regenerated: false,
-            namespaces: 0,
-            intrinsicElements: 0,
-            duration: 0,
-            girPath: [],
-            configFile,
-            libraries: [],
-        };
+const clearGeneratedStores = (store: CodegenStore): void => {
+    for (const path of [store.giStoreDir, store.giLinkDir, store.jsxStoreDir, store.jsxLinkDir]) {
+        rmSync(path, { recursive: true, force: true });
     }
+};
+
+const resolveLoadedConfig = async (options: RunCodegenOptions, cwd: string): Promise<LoadedConfig> =>
+    options.resolved ?? (await loadConfig(cwd, { mode: options.mode }));
 
-    const { girPath, libraries, elementProps, store } = options.inputs ?? resolveCodegenInputs(cwd, config);
+const prepareCodegen = (options: RunCodegenOptions, cwd: string, config: Config): PreparedCodegen => {
+    const { girPath, libraries, store } = options.inputs ?? resolveCodegenInputs(cwd, config);
 
     if (girPath.length === 0) {
-        throw new Error(
-            "No GIR search paths available. Install gobject-introspection (Linux: `sudo dnf install gobject-introspection-devel` or `sudo apt install libgirepository1.0-dev`), or set `girPath` in gtkx.config.ts.",
-        );
+        throw new Error(GIR_PATH_MISSING_MESSAGE);
     }
 
-    const force = options.force === true || isCodegenStale({ girPath, libraries, elementProps, store });
+    const isForce = options.force === true || isCodegenStale({ girPath, libraries, store });
+
+    return { girPath, libraries, store, force: isForce };
+};
+
+const runCodegen = async (options: RunCodegenOptions = {}): Promise<RunCodegenResult> => {
+    const cwd = options.cwd ?? process.cwd();
+    const { config, configFile } = await resolveLoadedConfig(options, cwd);
+
+    if (config.codegen === false) {
+        removeSharedStoreShadow(cwd);
+
+        return disabledCodegenResult(configFile);
+    }
+
+    const { girPath, libraries, store, force } = prepareCodegen(options, cwd, config);
+
     if (options.force) {
-        for (const path of [store.giStoreDir, store.giLinkDir, store.jsxStoreDir, store.jsxLinkDir]) {
-            rmSync(path, { recursive: true, force: true });
-        }
+        clearGeneratedStores(store);
     }
 
     const result = await runCodegenCore({
-        ...codegenOptions({ store, libraries, girPath, elementProps }),
+        ...codegenOptions({ store, libraries, girPath, elements: config.elements }),
         force,
     });
 
@@ -117,19 +161,18 @@ export const runCodegen = async (options: RunCodegenOptions = {}): Promise<RunCo
     };
 };
 
-export const isCodegenDisabled = async (cwd: string, mode?: string): Promise<boolean> => {
+const isCodegenDisabled = async (cwd: string, mode?: string): Promise<boolean> => {
     try {
         const { config } = await loadConfig(cwd, { mode });
+
         return config.codegen === false;
     } catch {
         return false;
     }
 };
 
-export const syncSchemaEnv = (cwd: string): void => {
-    const dataDir = resolveDataDir(cwd);
-    if (dataDir === null) return;
-    emitSchemaEnv(cwd, dataDir);
+const syncSchemaEnv = (cwd: string): void => {
+    emitSchemaEnv(cwd, resolveDataDir(cwd));
 };
 
 const resolveInputsOrNull = (cwd: string, config: Config): CodegenInputs | null => {
@@ -140,7 +183,25 @@ const resolveInputsOrNull = (cwd: string, config: Config): CodegenInputs | null
     }
 };
 
-export const ensureGenerated = async (
+const maybeAnnounceStale = (announce: boolean | undefined, inputs: CodegenInputs | null): void => {
+    if (!announce) {
+        return;
+    }
+
+    if (inputs === null || isCodegenStale(inputs)) {
+        info("generated bindings missing; running codegen...");
+    }
+};
+
+const getRunOptions = ({ root, mode, inputs, resolved }: RunOptionsInput): RunCodegenOptions => {
+    if (inputs === null) {
+        return { cwd: root, mode, resolved };
+    }
+
+    return { cwd: root, mode, inputs, resolved };
+};
+
+const ensureGenerated = async (
     cwd: string,
     options: { announce?: boolean; mode?: string } = {},
 ): Promise<boolean> => {
@@ -149,33 +210,37 @@ export const ensureGenerated = async (
     }
 
     const context = await resolveCodegenContext(cwd, options.mode);
+
     if (!context) {
         return false;
     }
+
     syncSchemaEnv(cwd);
+
     if (context.config.codegen === false) {
         removeSharedStoreShadow(context.root);
+
         return false;
     }
+
     const inputs = resolveInputsOrNull(context.root, context.config);
-    if (options.announce && (inputs === null || isCodegenStale(inputs))) {
-        info("generated bindings missing; running codegen...");
-    }
+    maybeAnnounceStale(options.announce, inputs);
     const resolved = { config: context.config, configFile: context.configFile };
-    const result = await runCodegen(
-        inputs === null
-            ? { cwd: context.root, mode: options.mode, resolved }
-            : { cwd: context.root, mode: options.mode, inputs, resolved },
-    );
+    const result = await runCodegen(getRunOptions({ root: context.root, mode: options.mode, inputs, resolved }));
+
     return result.regenerated;
 };
 
-export const resolveConfigWatch = async (
+const resolveConfigWatch = async (
     cwd: string,
     mode?: string,
 ): Promise<{ paths: string[]; regenerate: () => Promise<void> } | undefined> => {
     const { configFile, root } = await loadConfig(cwd, { mode });
-    if (configFile === undefined) return undefined;
+
+    if (configFile === undefined) {
+        return undefined;
+    }
+
     return {
         paths: [resolve(root, configFile)],
         regenerate: async () => {
@@ -183,3 +248,13 @@ export const resolveConfigWatch = async (
         },
     };
 };
+
+export {
+    runCodegen,
+    isCodegenDisabled,
+    syncSchemaEnv,
+    ensureGenerated,
+    resolveConfigWatch,
+    type RunCodegenOptions,
+    type RunCodegenResult,
+};

package/src/codegen/store-resolver.ts

@@ -1,10 +1,10 @@
+import { type Config, loadConfig } from "@gtkx/config";
 import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { pathToFileURL } from "node:url";
-import { type Config, loadConfig } from "@gtkx/config";
 
-export type CodegenStore = {
+type CodegenStore = {
     giStoreDir: string;
     giLinkDir: string;
     jsxStoreDir: string;
@@ -15,61 +15,102 @@ export type CodegenStore = {
 
 type CodegenReactPackage = {
     version: string;
+    subexports: string[];
 };
 
 type ResolvedPackage = { dir: string; version: string };
 
+type CodegenContext = {
+    root: string;
+    config: Config;
+    configFile: string | undefined;
+};
+
 const readVersion = (packageJsonPath: string): string => {
     const parsed = JSON.parse(readFileSync(packageJsonPath, "utf8")) as { version?: string };
+
     return parsed.version ?? "0.0.0";
 };
 
+const readSubexports = (packageDir: string): string[] => {
+    const parsed = JSON.parse(readFileSync(join(packageDir, "package.json"), "utf8")) as {
+        exports?: Record<string, unknown>;
+    };
+
+    return Object.keys(parsed.exports ?? {})
+        .filter((key) => key.startsWith("./") && key !== "./package.json")
+        .map((key) => key.slice(2));
+};
+
+/** Resolves the `@gtkx/react` subexport names for a project without requiring runtime/native to be installed. */
+const resolveReactSubexports = (dir: string): string[] => {
+    const require = createRequire(pathToFileURL(join(dir, "__gtkx_resolver__.js")).href);
+    const react = resolvePackage(require, dir, "@gtkx/react");
+
+    return react === null ? [] : readSubexports(react.dir);
+};
+
 const resolvePackage = (require: NodeJS.Require, dir: string, packageName: string): ResolvedPackage | null => {
     try {
         const real = realpathSync(require.resolve(`${packageName}/package.json`));
+
         return { dir: dirname(real), version: readVersion(real) };
     } catch {
         const unscoped = packageName.replace(/^@[^/]+\//, "");
         const workspacePkg = join(dir, "packages", unscoped, "package.json");
-        if (!existsSync(workspacePkg)) return null;
+
+        if (!existsSync(workspacePkg)) {
+            return null;
+        }
+
         const real = realpathSync(workspacePkg);
+
         return { dir: dirname(real), version: readVersion(real) };
     }
 };
 
-export const resolveCodegenStore = (dir: string): CodegenStore => {
+const resolveCodegenStore = (dir: string): CodegenStore => {
     const require = createRequire(pathToFileURL(join(dir, "__gtkx_resolver__.js")).href);
-
     const runtime = resolvePackage(require, dir, "@gtkx/runtime");
+
     if (runtime === null) {
         throw new Error("Cannot resolve @gtkx/runtime from the project; is it installed?");
     }
+
     const native = resolvePackage(require, dir, "@gtkx/native");
+
     if (native === null) {
         throw new Error("Cannot resolve @gtkx/native from the project; is it installed?");
     }
+
     const react = resolvePackage(require, dir, "@gtkx/react");
     const reactRuntime = resolvePackage(require, dir, "react");
-
     const nodeModules = join(dir, "node_modules");
+
     return {
         giStoreDir: join(nodeModules, ".gtkx", "gi"),
         giLinkDir: join(nodeModules, "@gtkx", "gi"),
         jsxStoreDir: join(nodeModules, ".gtkx", "jsx"),
         jsxLinkDir: join(nodeModules, "@gtkx", "jsx"),
         runtimeVersion: runtime.version,
-        react: react !== null && reactRuntime !== null ? { version: react.version } : null,
+        react:
+            react !== null && reactRuntime !== null
+                ? {
+                        version: react.version,
+                        subexports: readSubexports(react.dir),
+                    }
+                : null,
     };
 };
 
-export type CodegenContext = {
-    root: string;
-    config: Config;
-    configFile: string | undefined;
-};
-
-export const resolveCodegenContext = async (cwd: string, mode?: string): Promise<CodegenContext | null> => {
+const resolveCodegenContext = async (cwd: string, mode?: string): Promise<CodegenContext | null> => {
     const { config, configFile } = await loadConfig(cwd, { mode });
-    if (configFile === undefined) return null;
+
+    if (configFile === undefined) {
+        return null;
+    }
+
     return { root: cwd, config, configFile };
 };
+
+export { resolveReactSubexports, resolveCodegenStore, resolveCodegenContext, type CodegenStore, type CodegenContext };

package/src/commands/build.ts

@@ -6,7 +6,7 @@ import { entryArg, resolveEntry } from "../internal/entry-arg.js";
 
 const BUILD_MODE = "production";
 
-export const build = defineCommand({
+const build = defineCommand({
     meta: {
         name: "build",
         description: "Build application for production",
@@ -21,7 +21,6 @@ export const build = defineCommand({
     async run({ args }) {
         const { cwd, entry } = resolveEntry(args);
         info(`Building ${entry}`);
-
         await ensureGenerated(cwd, { announce: true, mode: BUILD_MODE });
 
         await buildApp({
@@ -35,3 +34,5 @@ export const build = defineCommand({
         info("Build complete: dist/bundle.js");
     },
 });
+
+export { build };

package/src/commands/codegen.ts

@@ -4,7 +4,7 @@ import { formatCodegenResult } from "../codegen/report.js";
 import { ensureGenerated, isCodegenDisabled, runCodegen, syncSchemaEnv } from "../codegen/run-codegen.js";
 import { cwdArg, resolveCwd } from "../internal/entry-arg.js";
 
-export const codegen = defineCommand({
+const codegen = defineCommand({
     meta: {
         name: "codegen",
         description: "Generate TypeScript bindings for the GIR libraries declared in gtkx.config.ts",
@@ -24,21 +24,26 @@ export const codegen = defineCommand({
             await runCodegen({ cwd });
             syncSchemaEnv(cwd);
             info("codegen: disabled for this project; reusing an installed binding store");
+
             return;
         }
 
         if (!args.force) {
-            const ran = await ensureGenerated(cwd);
-            info(ran ? "codegen: regenerated stale bindings" : "codegen: bindings up to date");
+            const isRan = await ensureGenerated(cwd);
+            info(isRan ? "codegen: regenerated stale bindings" : "codegen: bindings up to date");
+
             return;
         }
 
         const startedAt = Date.now();
         const result = await runCodegen({ cwd, force: true });
         syncSchemaEnv(cwd);
+        const lines = formatCodegenResult(result, Date.now() - startedAt);
 
-        for (const line of formatCodegenResult(result, Date.now() - startedAt)) {
+        for (const line of lines) {
             info(line);
         }
     },
 });
+
+export { codegen };

package/src/commands/dev.ts

@@ -5,7 +5,7 @@ import { entryArg, resolveEntry } from "../internal/entry-arg.js";
 
 const DEV_MODE = "development";
 
-export const dev = defineCommand({
+const dev = defineCommand({
     meta: {
         name: "dev",
         description: "Start development server with HMR",
@@ -15,11 +15,10 @@ export const dev = defineCommand({
     },
     async run({ args }) {
         const { cwd, entry: entryPath } = resolveEntry(args);
-
         await ensureGenerated(cwd, { announce: true, mode: DEV_MODE });
-
         const watch: DevWatch | undefined = await resolveConfigWatch(cwd, DEV_MODE);
-
         await runDevSupervisor(entryPath, cwd, watch);
     },
 });
+
+export { dev };

package/src/commands/docs.ts

@@ -1,11 +1,13 @@
-import { resolve } from "node:path";
-import { resolveGirPath, resolveLibraries, writeDocs } from "@gtkx/codegen";
+import { type ElementProps, readBuiltinElements, resolveGirPath, resolveLibraries, writeDocs } from "@gtkx/codegen";
 import { loadConfig } from "@gtkx/config";
 import { info } from "@gtkx/utils";
 import { defineCommand } from "citty";
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { resolveReactSubexports } from "../codegen/store-resolver.js";
 import { cwdArg, resolveCwd } from "../internal/entry-arg.js";
 
-export const docs = defineCommand({
+const docs = defineCommand({
     meta: {
         name: "docs",
         description:
@@ -32,35 +34,62 @@ export const docs = defineCommand({
     async run({ args }) {
         const cwd = resolveCwd(args);
         const { config } = await loadConfig(cwd);
+
         if (config.codegen === false) {
             throw new Error(
-                "codegen is disabled for this project, so there are no GIR libraries to document. Remove `codegen: false` from gtkx.config.ts to use `gtkx docs`.",
+                "codegen is disabled for this project, so there are no GIR libraries to document. " +
+                "Remove `codegen: false` from gtkx.config.ts to use `gtkx docs`.",
             );
         }
+
         const girPath = resolveGirPath(config.girPath);
+
         if (girPath.length === 0) {
             throw new Error(
-                "No GIR search paths available. Install gobject-introspection (Linux: `sudo dnf install gobject-introspection-devel` or `sudo apt install libgirepository1.0-dev`), or set `girPath` in gtkx.config.ts.",
+                "No GIR search paths available. Install gobject-introspection " +
+                "(Linux: `sudo dnf install gobject-introspection-devel` or " +
+                "`sudo apt install libgirepository1.0-dev`), or set `girPath` in gtkx.config.ts.",
             );
         }
+
         const libraries = resolveLibraries(config.libraries, girPath);
         const startedAt = Date.now();
         const outDir = resolve(cwd, args.out);
+
         const { regenerated, namespaces } = writeDocs({
             libraries,
             girPath,
             outDir,
             basePath: args["base-path"],
-            elementProps: config.elementProps ?? {},
+            props: await resolveDocsProps(cwd),
             force: args.force,
         });
+
         if (!regenerated) {
             info(`docs: pages in ${outDir} are up to date`);
+
             return;
         }
+
         const count = namespaces.reduce((total, namespace) => total + namespace.elements.length, 0);
+
         info(
-            `docs: wrote ${count} element pages across ${namespaces.length} namespaces to ${outDir} in ${Date.now() - startedAt}ms`,
+            `docs: wrote ${String(count)} element pages across ${String(namespaces.length)} namespaces ` +
+            `to ${outDir} in ${String(Date.now() - startedAt)}ms`,
         );
     },
 });
+
+const resolveDocsProps = async (cwd: string): Promise<ElementProps> => {
+    const giStoreDir = join(cwd, "node_modules", ".gtkx", "gi");
+
+    if (!existsSync(giStoreDir)) {
+        return {};
+    }
+
+    const { props } = await readBuiltinElements(resolveReactSubexports(cwd), giStoreDir);
+
+    return props;
+};
+
+export { docs };

package/src/dev/icon-dir.ts

@@ -2,10 +2,20 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { prependXdgDataDir } from "../internal/xdg-data-dirs.js";
 
-export const prepareDevIconDir = (root: string, dataDir: string | null): string | null => {
-    if (dataDir === null) return null;
+const prepareDevIconDir = (root: string, dataDir: string | null): string | null => {
+    if (dataDir === null) {
+        return null;
+    }
+
     const shareDir = join(root, dataDir);
-    if (!existsSync(join(shareDir, "icons"))) return null;
+
+    if (!existsSync(join(shareDir, "icons"))) {
+        return null;
+    }
+
     process.env.XDG_DATA_DIRS = prependXdgDataDir(shareDir, process.env.XDG_DATA_DIRS);
+
     return shareDir;
 };
+
+export { prepareDevIconDir };

package/src/dev/refresh-tracker.ts

@@ -1,21 +1,25 @@
-export type RefreshTracker = {
-    performRefresh(): void;
-    isRefreshing(): boolean;
+type RefreshTracker = {
+    performRefresh: () => void;
+    isRefreshing: () => boolean;
 };
 
-export const createRefreshTracker = (performRefresh: () => void): RefreshTracker => {
-    let refreshing = false;
+const createRefreshTracker = (performRefresh: () => void): RefreshTracker => {
+    let isRefreshing = false;
+
     return {
         performRefresh: () => {
-            refreshing = true;
+            isRefreshing = true;
+
             try {
                 performRefresh();
             } finally {
                 setTimeout(() => {
-                    refreshing = false;
+                    isRefreshing = false;
                 }, 0);
             }
         },
-        isRefreshing: () => refreshing,
+        isRefreshing: () => isRefreshing,
     };
 };
+
+export { createRefreshTracker, type RefreshTracker };