@cloudflare/kumo 1.0.0

package/scripts/component-registry/props-filter.ts

@@ -0,0 +1,310 @@
+/**
+ * Props filtering for component registry generation.
+ *
+ * Filters out inherited DOM/React props to keep documentation focused
+ * on component-specific props.
+ */
+
+import * as ts from "typescript";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { CLIFlags } from "./types.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const rootDir = join(__dirname, "../..");
+
+// =============================================================================
+// Props Filter Constants
+// =============================================================================
+
+/**
+ * Props to always skip - these are internal React props or rarely useful for LLMs
+ */
+export const ALWAYS_SKIP_PROPS = new Set([
+  "key",
+  "ref",
+  "style",
+  "dangerouslySetInnerHTML",
+]);
+
+/**
+ * Prefixes for props that should be skipped (DOM event handlers, ARIA, data attributes)
+ */
+export const SKIP_PROP_PREFIXES = [
+  "aria-",
+  "data-",
+  "on", // Event handlers: onClick, onMouseDown, onKeyUp, etc.
+];
+
+/**
+ * Props that should be kept even if they appear in inherited HTML types.
+ * These are commonly used and meaningful for component APIs.
+ */
+export const KEEP_PROPS = new Set([
+  "children",
+  "className",
+  "disabled",
+  "name",
+  "value",
+  "checked",
+  "required",
+  "placeholder",
+  "readOnly",
+  "type",
+  "label", // Common form field prop
+  "href", // Common link prop for navigation components
+  "lang", // Code component uses lang for syntax highlighting
+]);
+
+/**
+ * React interface names that define inherited HTML props.
+ * Props from these interfaces are filtered out to keep docs focused on component-specific props.
+ */
+export const REACT_HTML_INTERFACES = [
+  "HTMLAttributes",
+  "InputHTMLAttributes",
+  "ButtonHTMLAttributes",
+  "AnchorHTMLAttributes",
+  "FormHTMLAttributes",
+  "TextareaHTMLAttributes",
+  "SelectHTMLAttributes",
+];
+
+/**
+ * Minimal static list of common HTML props to skip (when --inherited-props is not set).
+ * This replaces the expensive deriveInheritedHtmlProps() by default.
+ */
+export const MINIMAL_SKIP_PROPS = new Set([
+  // Common HTML attributes we don't want to document
+  "accessKey",
+  "autoCapitalize",
+  "autoFocus",
+  "contentEditable",
+  "dir",
+  "draggable",
+  "hidden",
+  "spellCheck",
+  "tabIndex",
+  "translate",
+  // Form-specific attributes
+  "autocomplete",
+  "autofocus",
+  "form",
+  "formAction",
+  "formEncType",
+  "formMethod",
+  "formNoValidate",
+  "formTarget",
+  "max",
+  "maxLength",
+  "min",
+  "minLength",
+  "multiple",
+  "pattern",
+  "step",
+  // Media attributes
+  "accept",
+  "capture",
+  "crossOrigin",
+  "loop",
+  "muted",
+  "preload",
+  "poster",
+  "src",
+  "srcSet",
+  // React internal props
+  "suppressContentEditableWarning",
+  "suppressHydrationWarning",
+  "defaultChecked",
+  "defaultValue",
+  // RDFa attributes (semantic web metadata - not useful for component docs)
+  "about",
+  "content",
+  "datatype",
+  "inlist",
+  "prefix",
+  "property",
+  "rel",
+  "resource",
+  "rev",
+  "typeof",
+  "vocab",
+  // Microdata attributes (HTML5 semantic markup - not useful for component docs)
+  "itemID",
+  "itemProp",
+  "itemRef",
+  "itemScope",
+  "itemType",
+  // Deprecated/obscure HTML attributes
+  "autoCorrect",
+  "autoSave",
+  "color",
+  "results",
+  "security",
+  "unselectable",
+  // Popover API attributes (rarely used directly)
+  "popover",
+  "popoverTarget",
+  "popoverTargetAction",
+  // Web Components attributes
+  "is",
+  "slot",
+  "part",
+  "exportparts",
+  // Other rarely-used HTML attributes
+  "contextMenu",
+  "enterKeyHint",
+  "inputMode",
+  "inert",
+  "nonce",
+  "radioGroup",
+  "role",
+]);
+
+// =============================================================================
+// Inherited Props Derivation (expensive, only used with --inherited-props)
+// =============================================================================
+
+// Lazily computed inherited HTML props (derived from React types at runtime)
+let _inheritedHtmlProps: Set<string> | null = null;
+
+/**
+ * OPTIMIZATION: Derive inherited HTML props from React's type definitions.
+ * This is EXPENSIVE (~15s / 47% of total time) and NOT NEEDED for most use cases.
+ * Only enabled with --inherited-props CLI flag.
+ *
+ * Extracts property names from HTMLAttributes, InputHTMLAttributes, ButtonHTMLAttributes, etc.
+ * These are filtered out to keep component docs focused on component-specific props.
+ */
+export function deriveInheritedHtmlProps(): Set<string> {
+  const inheritedProps = new Set<string>();
+
+  try {
+    // Read tsconfig to get compiler options
+    const configPath = join(rootDir, "tsconfig.json");
+    const configFile = ts.readConfigFile(configPath, ts.sys.readFile);
+    const parsedConfig = ts.parseJsonConfigFileContent(
+      configFile.config,
+      ts.sys,
+      rootDir,
+    );
+
+    // Create a program to access React's type definitions
+    const program = ts.createProgram({
+      rootNames: parsedConfig.fileNames,
+      options: parsedConfig.options,
+    });
+
+    // Find React's type definition file
+    const reactDts = program
+      .getSourceFiles()
+      .find((sf) =>
+        sf.fileName.includes("node_modules/@types/react/index.d.ts"),
+      );
+
+    if (!reactDts) {
+      throw new Error("Could not find React type definitions");
+    }
+
+    // Walk the AST to find the HTML attribute interfaces
+    ts.forEachChild(reactDts, function visit(node) {
+      if (ts.isInterfaceDeclaration(node)) {
+        const name = node.name.text;
+        if (REACT_HTML_INTERFACES.includes(name)) {
+          // Extract property names from this interface
+          for (const member of node.members) {
+            if (ts.isPropertySignature(member) && member.name) {
+              const propName = member.name.getText(reactDts);
+              inheritedProps.add(propName);
+            }
+          }
+        }
+      }
+      ts.forEachChild(node, visit);
+    });
+
+    console.log(
+      `Derived ${inheritedProps.size} inherited HTML props from React types`,
+    );
+  } catch (error) {
+    console.warn(
+      "Warning: Could not derive HTML props from React types, using fallback list",
+    );
+    console.warn(error instanceof Error ? error.message : error);
+
+    // Fallback to a minimal set if derivation fails
+    const fallbackProps = [
+      "accessKey",
+      "autoCapitalize",
+      "autoFocus",
+      "contentEditable",
+      "dir",
+      "draggable",
+      "hidden",
+      "lang",
+      "spellCheck",
+      "tabIndex",
+      "title",
+      "translate",
+      "className",
+      "id",
+      "style",
+      "children",
+    ];
+    for (const prop of fallbackProps) {
+      inheritedProps.add(prop);
+    }
+  }
+
+  return inheritedProps;
+}
+
+/**
+ * Get the set of inherited HTML props to skip.
+ * Uses minimal static list by default, or derives from React types with --inherited-props flag.
+ */
+export function getInheritedHtmlProps(cliFlags: CLIFlags): Set<string> {
+  if (!cliFlags.includeInheritedProps) {
+    // Use minimal static list instead of expensive derivation
+    return MINIMAL_SKIP_PROPS;
+  }
+
+  if (!_inheritedHtmlProps) {
+    _inheritedHtmlProps = deriveInheritedHtmlProps();
+  }
+  return _inheritedHtmlProps;
+}
+
+// =============================================================================
+// Main Filter Function
+// =============================================================================
+
+/**
+ * Determine if a prop should be skipped from the generated documentation.
+ * Filters out inherited DOM props, event handlers, and internal React props.
+ */
+export function shouldSkipProp(propName: string, cliFlags: CLIFlags): boolean {
+  // Never skip props in the keep list
+  if (KEEP_PROPS.has(propName)) {
+    return false;
+  }
+
+  // Always skip certain props
+  if (ALWAYS_SKIP_PROPS.has(propName)) {
+    return true;
+  }
+
+  // Skip props with certain prefixes
+  for (const prefix of SKIP_PROP_PREFIXES) {
+    if (propName.startsWith(prefix)) {
+      return true;
+    }
+  }
+
+  // Skip inherited HTML attributes (derived from React types)
+  if (getInheritedHtmlProps(cliFlags).has(propName)) {
+    return true;
+  }
+
+  return false;
+}

package/scripts/component-registry/schema-generator.ts

@@ -0,0 +1,326 @@
+/**
+ * Zod Schema Generator for Kumo Component Registry
+ *
+ * Generates TypeScript file with Zod schemas from component-registry.json.
+ * This enables runtime validation of AI-generated UI trees.
+ *
+ * Output: catalog/schemas.ts
+ */
+
+import type {
+  ComponentRegistry,
+  ComponentSchema,
+  PropSchema,
+} from "./types.js";
+
+/**
+ * Convert a PropSchema type to its Zod equivalent
+ */
+function propTypeToZod(prop: PropSchema): string {
+  const { type, values, required, optional } = prop;
+
+  let zodType: string;
+
+  // Handle enum types with explicit values
+  if (type === "enum" && values && values.length > 0) {
+    const enumValues = values.map((v) => `"${v}"`).join(", ");
+    zodType = `z.enum([${enumValues}])`;
+  }
+  // Handle common types
+  else if (type === "string") {
+    zodType = "z.string()";
+  } else if (type === "number") {
+    zodType = "z.number()";
+  } else if (type === "boolean") {
+    zodType = "z.boolean()";
+  } else if (type === "ReactNode") {
+    // ReactNode can be string, number, boolean, null, or a dynamic path reference
+    zodType =
+      "z.union([z.string(), z.number(), z.boolean(), z.null(), DynamicValueSchema])";
+  } else if (type.endsWith("[]")) {
+    // Array types
+    const itemType = type.slice(0, -2);
+    const itemZod = itemType === "string" ? "z.string()" : "z.unknown()";
+    zodType = `z.array(${itemZod})`;
+  } else if (type.includes("|")) {
+    // Union types - simplified handling
+    zodType = "z.unknown()";
+  } else {
+    // Fallback for complex types
+    zodType = "z.unknown()";
+  }
+
+  // Make optional if not required
+  if (optional || !required) {
+    zodType = `${zodType}.optional()`;
+  }
+
+  return zodType;
+}
+
+/**
+ * Generate Zod schema for a single component's props
+ */
+function generateComponentPropsSchema(
+  componentName: string,
+  schema: ComponentSchema,
+): string {
+  const propsEntries = Object.entries(schema.props);
+
+  if (propsEntries.length === 0) {
+    return `export const ${componentName}PropsSchema = z.object({});`;
+  }
+
+  const propsLines = propsEntries.map(([propName, propSchema]) => {
+    const zodType = propTypeToZod(propSchema);
+    // Replace newlines with spaces to keep comments on a single line
+    const sanitizedDescription = propSchema.description
+      ?.replace(/\n+/g, " ")
+      .trim();
+    const comment = sanitizedDescription ? ` // ${sanitizedDescription}` : "";
+    return `  ${propName}: ${zodType},${comment}`;
+  });
+
+  return `export const ${componentName}PropsSchema = z.object({
+${propsLines.join("\n")}
+});`;
+}
+
+/**
+ * Generate the complete schemas.ts file content
+ */
+export function generateSchemasFile(registry: ComponentRegistry): string {
+  const componentNames = Object.keys(registry.components).sort();
+
+  const lines: string[] = [
+    "/**",
+    " * Auto-generated Zod schemas for Kumo components",
+    " * DO NOT EDIT - Generated by scripts/component-registry/index.ts",
+    " *",
+    " * These schemas enable runtime validation of AI-generated UI trees.",
+    " */",
+    "",
+    'import { z } from "zod";',
+    "",
+    "// =============================================================================",
+    "// Dynamic Value Schema (for data binding)",
+    "// =============================================================================",
+    "",
+    "/**",
+    " * A value that can either be a literal or a reference to the data model.",
+    ' * Example: "Hello" or { path: "/user/name" }',
+    " */",
+    "export const DynamicValueSchema = z.union([",
+    "  z.string(),",
+    "  z.number(),",
+    "  z.boolean(),",
+    "  z.null(),",
+    "  z.object({ path: z.string() }),",
+    "]);",
+    "",
+    "export type DynamicValue<T = unknown> = T | { path: string };",
+    "",
+    "// =============================================================================",
+    "// Visibility Condition Schemas",
+    "// =============================================================================",
+    "",
+    "/**",
+    " * Visibility conditions for conditional rendering.",
+    " * Components can be shown/hidden based on data, auth, or logic expressions.",
+    " */",
+    "",
+    "// Forward declaration for recursive types",
+    "// Note: Numeric comparisons use DynamicValue (not DynamicValue<number>) for Zod compatibility",
+    "export type LogicExpression =",
+    "  | { and: LogicExpression[] }",
+    "  | { or: LogicExpression[] }",
+    "  | { not: LogicExpression }",
+    "  | { path: string }",
+    "  | { eq: [DynamicValue, DynamicValue] }",
+    "  | { neq: [DynamicValue, DynamicValue] }",
+    "  | { gt: [DynamicValue, DynamicValue] }",
+    "  | { gte: [DynamicValue, DynamicValue] }",
+    "  | { lt: [DynamicValue, DynamicValue] }",
+    "  | { lte: [DynamicValue, DynamicValue] };",
+    "",
+    "// Lazy schema for recursive logic expressions",
+    "const LogicExpressionSchema: z.ZodType<LogicExpression> = z.lazy(() =>",
+    "  z.union([",
+    "    z.object({ and: z.array(LogicExpressionSchema) }),",
+    "    z.object({ or: z.array(LogicExpressionSchema) }),",
+    "    z.object({ not: LogicExpressionSchema }),",
+    "    z.object({ path: z.string() }),",
+    "    z.object({ eq: z.tuple([DynamicValueSchema, DynamicValueSchema]) }),",
+    "    z.object({ neq: z.tuple([DynamicValueSchema, DynamicValueSchema]) }),",
+    "    z.object({ gt: z.tuple([DynamicValueSchema, DynamicValueSchema]) }),",
+    "    z.object({ gte: z.tuple([DynamicValueSchema, DynamicValueSchema]) }),",
+    "    z.object({ lt: z.tuple([DynamicValueSchema, DynamicValueSchema]) }),",
+    "    z.object({ lte: z.tuple([DynamicValueSchema, DynamicValueSchema]) }),",
+    "  ])",
+    ");",
+    "",
+    "export const VisibilityConditionSchema = z.union([",
+    "  z.boolean(),",
+    "  z.object({ path: z.string() }),",
+    '  z.object({ auth: z.enum(["signedIn", "signedOut"]) }),',
+    "  LogicExpressionSchema,",
+    "]);",
+    "",
+    "export type VisibilityCondition = z.infer<typeof VisibilityConditionSchema>;",
+    "",
+    "// =============================================================================",
+    "// Action Schemas",
+    "// =============================================================================",
+    "",
+    "/**",
+    " * Action confirmation dialog configuration",
+    " */",
+    "export const ActionConfirmSchema = z.object({",
+    "  title: z.string(),",
+    "  message: z.string(),",
+    '  variant: z.enum(["default", "danger"]).optional(),',
+    "  confirmLabel: z.string().optional(),",
+    "  cancelLabel: z.string().optional(),",
+    "});",
+    "",
+    "/**",
+    " * Action definition that AI can declare",
+    " */",
+    "export const ActionSchema = z.object({",
+    "  name: z.string(),",
+    "  params: z.record(z.string(), DynamicValueSchema).optional(),",
+    "  confirm: ActionConfirmSchema.optional(),",
+    "  onSuccess: z.object({ set: z.record(z.string(), DynamicValueSchema) }).optional(),",
+    "  onError: z.object({ set: z.record(z.string(), DynamicValueSchema) }).optional(),",
+    "});",
+    "",
+    "export type Action = z.infer<typeof ActionSchema>;",
+    "",
+    "// =============================================================================",
+    "// Component Props Schemas",
+    "// =============================================================================",
+    "",
+  ];
+
+  // Generate schema for each component
+  for (const name of componentNames) {
+    const schema = registry.components[name];
+    lines.push(generateComponentPropsSchema(name, schema));
+    lines.push("");
+  }
+
+  // Generate the component type union
+  lines.push(
+    "// =============================================================================",
+  );
+  lines.push("// Component Type Union");
+  lines.push(
+    "// =============================================================================",
+  );
+  lines.push("");
+  lines.push("/**");
+  lines.push(" * All valid component type names");
+  lines.push(" */");
+  const typeUnion = componentNames.map((n) => `"${n}"`).join(" | ");
+  lines.push(`export type KumoComponentType = ${typeUnion};`);
+  lines.push("");
+  lines.push("export const KumoComponentTypeSchema = z.enum([");
+  for (const name of componentNames) {
+    lines.push(`  "${name}",`);
+  }
+  lines.push("]);");
+  lines.push("");
+
+  // Generate props schema map
+  lines.push("/**");
+  lines.push(" * Map of component type to its props schema");
+  lines.push(" */");
+  lines.push("export const ComponentPropsSchemas = {");
+  for (const name of componentNames) {
+    lines.push(`  ${name}: ${name}PropsSchema,`);
+  }
+  lines.push("} as const;");
+  lines.push("");
+
+  // Generate UIElement schema
+  lines.push(
+    "// =============================================================================",
+  );
+  lines.push("// UI Element & Tree Schemas");
+  lines.push(
+    "// =============================================================================",
+  );
+  lines.push("");
+  lines.push("/**");
+  lines.push(" * Base UI element structure");
+  lines.push(" */");
+  lines.push("export const UIElementBaseSchema = z.object({");
+  lines.push("  key: z.string(),");
+  lines.push("  type: KumoComponentTypeSchema,");
+  lines.push("  props: z.record(z.string(), z.unknown()),");
+  lines.push("  children: z.array(z.string()).optional(),");
+  lines.push("  parentKey: z.string().nullable().optional(),");
+  lines.push("  visible: VisibilityConditionSchema.optional(),");
+  lines.push("  action: ActionSchema.optional(),");
+  lines.push("});");
+  lines.push("");
+  lines.push("export type UIElement = z.infer<typeof UIElementBaseSchema>;");
+  lines.push("");
+  lines.push("/**");
+  lines.push(" * Flat UI tree structure (optimized for LLM generation)");
+  lines.push(" */");
+  lines.push("export const UITreeSchema = z.object({");
+  lines.push("  root: z.string(),");
+  lines.push("  elements: z.record(z.string(), UIElementBaseSchema),");
+  lines.push("});");
+  lines.push("");
+  lines.push("export type UITree = z.infer<typeof UITreeSchema>;");
+  lines.push("");
+
+  // Generate validation helpers
+  lines.push(
+    "// =============================================================================",
+  );
+  lines.push("// Validation Helpers");
+  lines.push(
+    "// =============================================================================",
+  );
+  lines.push("");
+  lines.push("/**");
+  lines.push(" * Validate an element's props against its component schema");
+  lines.push(" */");
+  lines.push(
+    "export function validateElementProps(element: UIElement): z.SafeParseReturnType<unknown, unknown> {",
+  );
+  lines.push(
+    "  const schema = ComponentPropsSchemas[element.type as keyof typeof ComponentPropsSchemas];",
+  );
+  lines.push("  if (!schema) {");
+  lines.push(
+    "    return { success: false, error: new z.ZodError([{ code: 'custom', message: `Unknown component type: ${element.type}`, path: ['type'] }]) };",
+  );
+  lines.push("  }");
+  lines.push("  return schema.safeParse(element.props);");
+  lines.push("}");
+  lines.push("");
+  lines.push("/**");
+  lines.push(" * Validate a complete UI tree");
+  lines.push(" */");
+  lines.push(
+    "export function validateUITree(tree: unknown): z.SafeParseReturnType<unknown, UITree> {",
+  );
+  lines.push("  return UITreeSchema.safeParse(tree);");
+  lines.push("}");
+  lines.push("");
+
+  // Export component names for catalog generation
+  lines.push("/**");
+  lines.push(" * List of all component names (for catalog generation)");
+  lines.push(" */");
+  lines.push(
+    `export const KUMO_COMPONENT_NAMES = [${componentNames.map((n) => `"${n}"`).join(", ")}] as const;`,
+  );
+  lines.push("");
+
+  return lines.join("\n");
+}