@gtkx/config 2.0.0-beta.10 → 2.0.0-beta.12

package/src/config.ts

@@ -25,14 +25,13 @@ type ResolvedReactCompilerOptions = ReactCompilerOptions & {
 };
 
 /**
- * User-facing configuration for a GTKX project, as authored in `gtkx.config.ts`: the GIR libraries
- * to bind and where to find them, the GApplication id, per-element configuration, the React
- * Compiler, codegen, and user event signal settings, and the `agents` and `mcp` blocks controlling
- * what coding agents are given.
+ * GTKX project configuration authored in `gtkx.config.ts` and validated when loaded.
  */
 type Config = z.infer<typeof configSchema>;
 type ModuleExport = z.infer<typeof moduleExportSchema>;
-type ElementConfigEntry = z.infer<typeof elementConfigSchema>;
+type ElementPropsExport = z.infer<typeof elementPropsSchema>;
+/** Overrides for one GLib type in `elements.config`, keyed by its registered type name. */
+type ElementConfigOptions = z.infer<typeof elementConfigSchema>;
 
 type McpSettings = {
     tools: string[];
@@ -65,8 +64,10 @@ const COMPILATION_MODES = ["infer", "syntax", "annotation", "all"] as const;
 const PANIC_THRESHOLDS = ["none", "critical_errors", "all_errors"] as const;
 const REACT_COMPILER_TARGET = "19";
 
-const librarySchema = girLibrary('must be of the form "Name-Version", such as "Adw-1"')
-    .refine((library) => !IMPLICIT_LIBRARIES.has(library), { error: "is bound implicitly; remove it" });
+const librarySchema = girLibrary('must be of the form "Name-Version", such as "Adw-1"').refine(
+    (library) => !IMPLICIT_LIBRARIES.has(library),
+    { error: "is bound implicitly; remove it" },
+);
 
 const librariesSchema = z
     .array(librarySchema, { error: "must be a non-empty string array or omitted" })
@@ -80,8 +81,10 @@ const applicationIdSchema = z
 
 const reactCompilerSchema = z.union([
     z.boolean(),
-    z.object({
+    z.strictObject({
+        /** Which functions the React Compiler processes. */
         compilationMode: z.enum(COMPILATION_MODES).optional(),
+        /** Which React Compiler diagnostics fail the build. */
         panicThreshold: z.enum(PANIC_THRESHOLDS).optional(),
     }),
 ]);
@@ -97,18 +100,37 @@ const userEventSignalsSchema = z.record(
     { error: "must be a record of GLib type names to signal name arrays" },
 );
 
-const moduleExportSchema = z.object(
+const moduleExportSchema = z.strictObject(
     {
+        /** Module specifier containing the named export. */
         module: z.string({ error: "must be a module specifier" }).min(1, { error: "must be a module specifier" }),
+        /** Name of the export to import from the module. */
         export: z.string({ error: "must be an export name" }).min(1, { error: "must be an export name" }),
     },
     { error: "must be a { module, export } object" },
 );
 
-const elementConfigSchema = z.object({
+const elementPropsSchema = moduleExportSchema.extend({
+    /**
+     * How the exported props are combined: `intersection` is inherited; `factory` applies only to this type.
+     * Defaults to `intersection`.
+     */
+    composition: z.enum(["factory", "intersection"]).optional(),
+    /** Props that can only be set when the element is created; changing them afterward throws. */
+    constructOnly: z.array(z.string()).optional(),
+});
+
+/** Schema for one element override and the source of {@link ElementConfigOptions}. */
+const elementConfigSchema = z.strictObject({
+    /** Component export that wraps the generated element. */
     component: moduleExportSchema.optional(),
-    props: moduleExportSchema.optional(),
+    /** Additional props type to combine with the generated element props. */
+    props: elementPropsSchema.optional(),
+    /** Whether the parent container creates this element's GObject instead of the element constructing its own. */
     isLazy: z.boolean({ error: "must be a boolean" }).optional(),
+    /** Accepted child GLib type names to show in the generated element documentation. */
+    acceptedChildTypes: z.array(z.string()).optional(),
+    /** GObject properties to leave out of generated props, such as properties managed by an element behavior. */
     omittedProps: z
         .array(
             z.string({ error: "must be a non-empty property name" }).min(1, {
@@ -119,25 +141,43 @@ const elementConfigSchema = z.object({
         .optional(),
 });
 
-const elementsSchema = z.object({
+const elementsSchema = z.strictObject({
+    /** Path, relative to the project root, of the module exporting the element behavior map. */
     behaviors: z
         .string({ error: "must be a path to a module exporting element behaviors" })
         .min(1, { error: "must be a path to a module exporting element behaviors" })
         .optional(),
+    /**
+     * Element configuration overrides keyed by GLib type name, such as `GtkWidget`.
+     * @see {@link ElementConfigOptions} for the fields accepted by each entry.
+     */
     config: z.record(z.string(), elementConfigSchema).optional(),
 });
 
-const agentsSchema = z.object({
+const agentsSchema = z.strictObject({
+    /**
+     * Whether codegen maintains the GTKX rules in `AGENTS.md` and creates a missing `CLAUDE.md` import.
+     * Defaults to `true`.
+     */
     rules: z.boolean({ error: "must be a boolean" }).optional(),
+    /** Whether codegen writes the generated element reference to `.gtkx/reference`. Defaults to `true`. */
     reference: z.boolean({ error: "must be a boolean" }).optional(),
 });
 
-const mcpSchema = z.object({
+const mcpSchema = z.strictObject({
+    /**
+     * Tool name patterns applied in order: `*` matches any text and a leading `!` excludes matches.
+     * Omitted, empty, or exclusion-only lists start with all tools; other lists start with none.
+     */
     tools: z
         .array(z.string({ error: "must be a tool name pattern" }).min(1, { error: "must be a tool name pattern" }), {
             error: "must be an array of tool name patterns",
         })
         .optional(),
+    /**
+     * Whether the MCP server exposes only inspection and reference tools, excluding app interactions.
+     * Defaults to `false`.
+     */
     readOnly: z.boolean({ error: "must be a boolean" }).optional(),
 });
 
@@ -153,7 +193,8 @@ const graduatedFutureSchema = z
     })
     .strict();
 
-const deprecationsSchema = z.object({
+const deprecationsSchema = z.strictObject({
+    /** Deprecation identifiers whose warnings are suppressed. There are currently no accepted identifiers. */
     silence: z
         .array(z.never({ error: "does not name a current deprecation" }), {
             error: "must be an array of current deprecation ids",
@@ -162,18 +203,39 @@ const deprecationsSchema = z.object({
 });
 
 /** Schema every `gtkx.config.ts` is validated against, and the source of the {@link Config} type. */
-const configSchema = z.object({
+const configSchema = z.strictObject({
+    /**
+     * Additional GIR libraries to bind, such as `WebKit-6.0`.
+     * Adwaita and GTK are included implicitly and must not be listed.
+     */
     libraries: librariesSchema.optional(),
+    /** Additional GIR search directories. Relative paths are resolved from the project root. */
     girPath: z.array(z.string(), { error: "must be an array of strings if provided" }).optional(),
+    /** Required GApplication identifier, such as `com.example.Tasks`. */
     applicationId: applicationIdSchema,
+    /** Whether to enable the React Compiler, or options passed to it. Enabled by default. */
     reactCompiler: reactCompilerSchema.optional(),
+    /**
+     * Whether GTKX generates project bindings. Set to `false` to reuse an installed binding store.
+     * Defaults to `true`.
+     */
     codegen: z.boolean({ error: "must be a boolean" }).optional(),
+    /**
+     * Additional signals to suppress during React property updates, keyed by GLib type name.
+     * Entries extend the built-in signal lists.
+     */
     userEventSignals: userEventSignalsSchema.optional(),
+    /** Custom element behaviors and overrides for generated components, props, and documentation. */
     elements: elementsSchema.optional(),
+    /** Path to an icon theme directory or a single application icon file, relative to the project root. */
     applicationIcon: text("must be a path to an icon theme directory or a single icon file").optional(),
+    /** Application metadata, bundled runtime settings, and packaging options used by `gtkx deploy`. */
     deploy: deploySchema.optional(),
+    /** Controls the project instructions and reference files generated for coding agents. */
     agents: agentsSchema.optional(),
+    /** Default tool selection and access mode for the project's MCP server. Command-line flags take precedence. */
     mcp: mcpSchema.optional(),
+    /** Controls warnings for deprecated configuration and behavior. */
     deprecations: deprecationsSchema.optional(),
 });
 
@@ -238,7 +300,7 @@ const resolveLazyElements = (elements: Config["elements"]): string[] =>
 
 const elementEntryValues = <T>(
     elements: Config["elements"],
-    pick: (entry: ElementConfigEntry) => T | undefined,
+    pick: (entry: ElementConfigOptions) => T | undefined,
 ): Record<string, T> =>
     Object.fromEntries(
         Object.entries(elements?.config ?? {}).flatMap(([type, entry]) => {
@@ -251,9 +313,12 @@ const elementEntryValues = <T>(
 const resolveElementComponents = (elements: Config["elements"]): Record<string, ModuleExport> =>
     elementEntryValues(elements, (entry) => entry.component);
 
-const resolveElementProps = (elements: Config["elements"]): Record<string, ModuleExport> =>
+const resolveElementProps = (elements: Config["elements"]): Record<string, ElementPropsExport> =>
     elementEntryValues(elements, (entry) => entry.props);
 
+const resolveAcceptedChildTypes = (elements: Config["elements"]): Record<string, string[]> =>
+    elementEntryValues(elements, (entry) => entry.acceptedChildTypes);
+
 const resolveOmittedProps = (elements: Config["elements"]): Record<string, string[]> =>
     elementEntryValues(elements, (entry) => entry.omittedProps);
 
@@ -285,11 +350,15 @@ export {
     resolveLazyElements,
     resolveElementComponents,
     resolveElementProps,
+    resolveAcceptedChildTypes,
     resolveMcpSettings,
     resolveOmittedProps,
     resolveConfig,
     type McpSettings,
     type ResolvedReactCompilerOptions,
     type Config,
+    type ElementConfigOptions,
+    type ElementPropsExport,
+    type ModuleExport,
     type ResolvedConfig,
 };