json-render/apps/web/app/(main)/docs/api/codegen/page.tsx

import { Code } from "@/components/code";

export const metadata = {
  title: "@json-render/codegen API | json-render",
};

export default function CodegenApiPage() {
  return (
    <article>
      <h1 className="text-3xl font-bold mb-4">@json-render/codegen</h1>
      <p className="text-muted-foreground mb-8">
        Utilities for generating code from UI trees.
      </p>

      <h2 className="text-xl font-semibold mt-12 mb-4">Tree Traversal</h2>

      <h3 className="text-lg font-semibold mt-8 mb-4">traverseSpec</h3>
      <p className="text-sm text-muted-foreground mb-4">
        Walk the UI spec depth-first.
      </p>
      <Code lang="typescript">{`function traverseSpec(
  spec: Spec,
  visitor: SpecVisitor,
  startKey?: string
): void

interface SpecVisitor {
  (element: UIElement, depth: number, parent: UIElement | null): void;
}`}</Code>

      <h3 className="text-lg font-semibold mt-8 mb-4">collectUsedComponents</h3>
      <p className="text-sm text-muted-foreground mb-4">
        Get all unique component types used in a spec.
      </p>
      <Code lang="typescript">{`function collectUsedComponents(spec: Spec): Set<string>

// Example
const components = collectUsedComponents(spec);
// Set { 'Card', 'Metric', 'Chart' }`}</Code>

      <h3 className="text-lg font-semibold mt-8 mb-4">collectDataPaths</h3>
      <p className="text-sm text-muted-foreground mb-4">
        Get all data paths referenced in props (valuePath, dataPath, bindPath,
        etc.).
      </p>
      <Code lang="typescript">{`function collectDataPaths(spec: Spec): Set<string>

// Example
const paths = collectDataPaths(spec);
// Set { 'analytics/revenue', 'analytics/customers' }`}</Code>

      <h3 className="text-lg font-semibold mt-8 mb-4">collectActions</h3>
      <p className="text-sm text-muted-foreground mb-4">
        Get all action names used in the spec.
      </p>
      <Code lang="typescript">{`function collectActions(spec: Spec): Set<string>

// Example
const actions = collectActions(spec);
// Set { 'submit_form', 'refresh_data' }`}</Code>

      <h2 className="text-xl font-semibold mt-12 mb-4">Serialization</h2>

      <h3 className="text-lg font-semibold mt-8 mb-4">serializePropValue</h3>
      <p className="text-sm text-muted-foreground mb-4">
        Serialize a single value to a code string.
      </p>
      <Code lang="typescript">{`function serializePropValue(
  value: unknown,
  options?: SerializeOptions
): { value: string; needsBraces: boolean }

// Examples
serializePropValue("hello")
// { value: '"hello"', needsBraces: false }

serializePropValue(42)
// { value: '42', needsBraces: true }

serializePropValue({ path: 'user/name' })
// { value: '{ path: "user/name" }', needsBraces: true }`}</Code>

      <h3 className="text-lg font-semibold mt-8 mb-4">serializeProps</h3>
      <p className="text-sm text-muted-foreground mb-4">
        Serialize a props object to a JSX attributes string.
      </p>
      <Code lang="typescript">{`function serializeProps(
  props: Record<string, unknown>,
  options?: SerializeOptions
): string

// Example
serializeProps({ title: 'Dashboard', columns: 3, disabled: true })
// 'title="Dashboard" columns={3} disabled'`}</Code>

      <h3 className="text-lg font-semibold mt-8 mb-4">escapeString</h3>
      <p className="text-sm text-muted-foreground mb-4">
        Escape a string for use in code.
      </p>
      <Code lang="typescript">{`function escapeString(
  str: string,
  quotes?: 'single' | 'double'
): string`}</Code>

      <h2 className="text-xl font-semibold mt-12 mb-4">Types</h2>

      <h3 className="text-lg font-semibold mt-8 mb-4">GeneratedFile</h3>
      <Code lang="typescript">{`interface GeneratedFile {
  /** File path relative to project root */
  path: string;
  /** File contents */
  content: string;
}`}</Code>

      <h3 className="text-lg font-semibold mt-8 mb-4">CodeGenerator</h3>
      <Code lang="typescript">{`interface CodeGenerator {
  /** Generate files from a UI spec */
  generate(spec: Spec): GeneratedFile[];
}`}</Code>

      <h3 className="text-lg font-semibold mt-8 mb-4">SerializeOptions</h3>
      <Code lang="typescript">{`interface SerializeOptions {
  /** Quote style for strings */
  quotes?: 'single' | 'double';
  /** Indent for objects/arrays */
  indent?: number;
}`}</Code>
    </article>
  );
}