feat(docs-ai): add react props type table tool rendering

Author: junghyeonsu

docs/components/ai-panel/tool-result-renderer.tsx

@@ -3,6 +3,7 @@
 import { ComponentPreview } from "@/components/component-preview";
 import Link from "next/link";
 import { DynamicCodeBlock } from "fumadocs-ui/components/dynamic-codeblock";
+import { TypeTable } from "fumadocs-ui/components/type-table";
 import { Tab, Tabs } from "fumadocs-ui/components/tabs";
 import { m } from "motion/react";
 import type { ReactNode } from "react";
@@ -21,6 +22,14 @@ interface RelatedLink {
   href: string;
 }
 
+interface ReactTypeTableRow {
+  name: string;
+  type: string;
+  required: boolean;
+  description: string;
+  defaultValue: string | null;
+}
+
 const INSTALL_COMMANDS = [
   { manager: "npm", commandPrefix: "npx" },
   { manager: "yarn", commandPrefix: "yarn dlx" },
@@ -95,6 +104,43 @@ function getToolOutputCode(output: unknown): { code: string; language: string }
   };
 }
 
+function getReactTypeTableRows(output: unknown): ReactTypeTableRow[] {
+  if (!output || typeof output !== "object") return [];
+
+  const rows = (output as { rows?: unknown }).rows;
+  if (!Array.isArray(rows)) return [];
+
+  return rows
+    .map((row) => {
+      if (!row || typeof row !== "object") return null;
+
+      const safeRow = row as {
+        name?: unknown;
+        type?: unknown;
+        required?: unknown;
+        description?: unknown;
+        defaultValue?: unknown;
+      };
+
+      if (
+        typeof safeRow.name !== "string" ||
+        typeof safeRow.type !== "string" ||
+        typeof safeRow.required !== "boolean"
+      ) {
+        return null;
+      }
+
+      return {
+        name: safeRow.name,
+        type: safeRow.type,
+        required: safeRow.required,
+        description: typeof safeRow.description === "string" ? safeRow.description : "",
+        defaultValue: typeof safeRow.defaultValue === "string" ? safeRow.defaultValue : null,
+      };
+    })
+    .filter((row): row is ReactTypeTableRow => row !== null);
+}
+
 export function ToolResultRenderer({ toolName, input, state, output }: ToolResultRendererProps) {
   // 아직 입력이 완전하지 않으면 로딩 표시
   if (state === "input-streaming") {
@@ -195,6 +241,54 @@ export function ToolResultRenderer({ toolName, input, state, output }: ToolResul
         </ToolFadeIn>
       );
 
+    case "showReactTypeTable": {
+      if (state === "input-available") {
+        return (
+          <ToolFadeIn>
+            <ToolLoading label="Props 타입 테이블 생성 중..." />
+          </ToolFadeIn>
+        );
+      }
+
+      const rows = getReactTypeTableRows(output);
+      if (rows.length === 0) {
+        const error =
+          output &&
+          typeof output === "object" &&
+          typeof (output as { error?: unknown }).error === "string"
+            ? ((output as { error: string }).error ?? "")
+            : "";
+
+        return (
+          <ToolFadeIn>
+            <div className="my-1 text-xs text-fd-muted-foreground">
+              {error || "Props 타입 테이블을 찾지 못했어요."}
+            </div>
+          </ToolFadeIn>
+        );
+      }
+
+      const type = Object.fromEntries(
+        rows.map((row) => [
+          row.name,
+          {
+            type: row.type,
+            required: row.required,
+            ...(row.description ? { description: row.description } : {}),
+            ...(row.defaultValue ? { default: row.defaultValue } : {}),
+          },
+        ]),
+      );
+
+      return (
+        <ToolFadeIn>
+          <div className="my-2">
+            <TypeTable type={type} />
+          </div>
+        </ToolFadeIn>
+      );
+    }
+
     case "findRelatedLinks": {
       if (state === "input-available") {
         return (

docs/lib/ai/system-prompt.ts

@@ -12,16 +12,22 @@ SEED Design is the design system for Karrot (당근), a Korean secondhand market
 - showComponentExample: Display an interactive component preview and example code in the chat
 - showInstallation: Show CLI installation command for a component
 - showCodeBlock: Display a syntax-highlighted code snippet
+- showReactTypeTable: Render React props/type table from source (e.g., ActionButtonProps)
 - findRelatedLinks: Find related documentation links from https://seed-design.io/sitemap.xml (include both docs and react when relevant)
 
 ## Guidelines
 - Always search documentation before answering technical questions
 - Use showComponentExample when users ask to see how a component looks
 - Use showInstallation when users ask how to install or set up a component
 - Use showCodeBlock for code snippets and usage examples instead of writing raw fenced code blocks in plain text
+- Use showReactTypeTable when users ask for props/types/interfaces of a React component
 - Before finalizing a technical answer, call findRelatedLinks with the user's query and attach relevant links when available
 - If a tool already rendered preview/install/code/related-links, do not repeat the same content in plain text
-- Keep plain text complementary to tool output only (short context, no duplicated commands/snippets/links)
+- Keep plain text complementary to tool output only (short context, no duplicated commands/snippets/links/props lists)
+- Prefer structured, tool-first responses:
+  1) call tools for preview/install/code/props/related-links
+  2) then provide only a short connective explanation
+- Do not leave placeholder headings or empty sections such as "### 설치", "### 사용 예시", "관련 링크" when a tool already rendered that section
 - Respond in the same language as the user's message (default: Korean)
 - Be concise but thorough
 - When referencing components, use their official names (e.g., ActionButton, Checkbox, Tabs)

docs/lib/ai/tools.ts

@@ -2,13 +2,44 @@ import { tool } from "ai";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
+import { typeTableGenerator } from "../../components/type-table/generator";
+import { getReactTypeTableOutput } from "../../components/type-table/get-react-type-table";
 import { findRelatedLinks as searchRelatedLinks } from "./sitemap-links";
 
 const SITEMAP_URL = "https://seed-design.io/sitemap.xml";
 
-async function findExamplesDir(): Promise<string | null> {
+async function findDocsRoot(): Promise<string | null> {
   const cwd = process.cwd();
-  const candidates = [path.join(cwd, "examples"), path.join(cwd, "docs", "examples")];
+  const candidates = [path.join(cwd, "docs"), cwd];
+
+  for (const candidate of candidates) {
+    try {
+      const [hasRegistry, hasComponents] = await Promise.all([
+        fs
+          .stat(path.join(candidate, "registry"))
+          .then((stat) => stat.isDirectory())
+          .catch(() => false),
+        fs
+          .stat(path.join(candidate, "components"))
+          .then((stat) => stat.isDirectory())
+          .catch(() => false),
+      ]);
+
+      if (hasRegistry && hasComponents) {
+        return candidate;
+      }
+    } catch {
+      // ignore and try next candidate
+    }
+  }
+
+  return null;
+}
+
+async function findExamplesDir(): Promise<string | null> {
+  const docsRoot = await findDocsRoot();
+  if (!docsRoot) return null;
+  const candidates = [path.join(docsRoot, "examples")];
 
   for (const candidate of candidates) {
     try {
@@ -40,6 +71,123 @@ async function loadExampleCode(name: string): Promise<string | null> {
   }
 }
 
+function toPascalCase(kebabCase: string): string {
+  return kebabCase
+    .split("-")
+    .filter(Boolean)
+    .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+    .join("");
+}
+
+function resolveDocsRelativePath(docsRoot: string, docsRelativePath: string): string | null {
+  const normalizedPath = path.normalize(docsRelativePath);
+  const withoutDotPrefix = normalizedPath.startsWith("./")
+    ? normalizedPath.slice(2)
+    : normalizedPath;
+
+  if (withoutDotPrefix.startsWith("..")) return null;
+
+  const resolvedPath = path.resolve(docsRoot, withoutDotPrefix);
+  const rootPath = path.resolve(docsRoot);
+  if (!resolvedPath.startsWith(`${rootPath}${path.sep}`)) return null;
+
+  return resolvedPath;
+}
+
+async function loadReactTypeTable(input: {
+  component?: string;
+  path?: string;
+  name?: string;
+}): Promise<{
+  shown: boolean;
+  typeName: string;
+  sourcePath: string;
+  rows: Array<{
+    name: string;
+    type: string;
+    required: boolean;
+    description: string;
+    defaultValue: string | null;
+  }>;
+  error?: string;
+}> {
+  const docsRoot = await findDocsRoot();
+  if (!docsRoot) {
+    return {
+      shown: false,
+      typeName: input.name ?? "",
+      sourcePath: input.path ?? "",
+      rows: [],
+      error: "docs 루트를 찾지 못했어요.",
+    };
+  }
+
+  const componentName = input.component?.trim();
+  const sourcePath =
+    input.path?.trim() ||
+    (componentName ? `./registry/ui/${componentName}.tsx` : "./registry/ui/action-button.tsx");
+  const typeName =
+    input.name?.trim() || (componentName ? `${toPascalCase(componentName)}Props` : "");
+
+  if (!typeName) {
+    return {
+      shown: false,
+      typeName: "",
+      sourcePath,
+      rows: [],
+      error: "타입 이름(name)이 비어 있습니다.",
+    };
+  }
+
+  const resolvedPath = resolveDocsRelativePath(docsRoot, sourcePath);
+  if (!resolvedPath) {
+    return {
+      shown: false,
+      typeName,
+      sourcePath,
+      rows: [],
+      error: "유효하지 않은 타입 경로입니다.",
+    };
+  }
+
+  try {
+    const output = await getReactTypeTableOutput({
+      generator: typeTableGenerator,
+      path: resolvedPath,
+      name: typeName,
+    });
+
+    const table = output.find((item) => item.name === typeName) ?? output[0];
+    const rows =
+      table?.entries.map((entry) => ({
+        name: entry.name,
+        type: entry.type,
+        required: entry.required,
+        description: entry.description,
+        defaultValue:
+          entry.tags.find((tag) => tag.name === "default" || tag.name === "defaultValue")?.text ??
+          null,
+      })) ?? [];
+
+    return {
+      shown: rows.length > 0,
+      typeName: table?.name ?? typeName,
+      sourcePath,
+      rows,
+      ...(rows.length === 0 ? { error: "타입 테이블 항목을 찾지 못했어요." } : {}),
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "타입 테이블 로딩에 실패했습니다.";
+    return {
+      shown: false,
+      typeName,
+      sourcePath,
+      rows: [],
+      error: message,
+    };
+  }
+}
+
 /**
  * 채팅 UI 렌더링용 도구.
  * 서버에서도 execute를 제공해 tool result가 누락되지 않도록 한다.
@@ -101,6 +249,46 @@ export const clientTools = {
     }),
   }),
 
+  showReactTypeTable: tool({
+    description:
+      "Show React props type table. Use when users ask for props/types of a React component. Prefer component input like 'action-button'.",
+    inputSchema: z
+      .object({
+        component: z
+          .string()
+          .min(1)
+          .max(64)
+          .regex(
+            /^[a-z0-9]+(?:-[a-z0-9]+)*$/,
+            "Expected kebab-case component name (lowercase letters, numbers, hyphen)",
+          )
+          .optional()
+          .describe("React component name in kebab-case, e.g., action-button"),
+        path: z
+          .string()
+          .min(1)
+          .max(200)
+          .optional()
+          .describe("Path to source file from docs root, e.g., ./registry/ui/action-button.tsx"),
+        name: z
+          .string()
+          .min(1)
+          .max(120)
+          .optional()
+          .describe("Type name to extract, e.g., ActionButtonProps"),
+      })
+      .refine((value) => Boolean(value.component || value.path), {
+        message: "Either component or path is required",
+      }),
+    execute: async ({ component, path: sourcePath, name }) => {
+      return await loadReactTypeTable({
+        component,
+        path: sourcePath,
+        name,
+      });
+    },
+  }),
+
   findRelatedLinks: tool({
     description:
       "Find related documentation URLs from the SEED Design sitemap. Use this before final response and attach related links when available. Prefer a mix of docs and react links when relevant.",