feat: add docs-extractor package for component documentation extraction

apps/website/content/docs/components/avatar.mdx

@@ -1,7 +1,7 @@
 ---
 title: 'Avatar'
 site_name: 'Avatar - Vapor Core'
-description: 'Avatar는 사용자가 설정한 프로필 이미지 혹은 텍스트를 UI상에 나타냅니다.'
+description: 'Avatar는 프로필 이미지 또는 대체 텍스트를 표시합니다.'
 ---
 
 <Demo name="avatar/default-avatar">
@@ -19,7 +19,7 @@ description: 'Avatar는 사용자가 설정한 프로필 이미지 혹은 텍스
 
 ### Size
 
-Avatar의 크기를 설정합니다.
+크기를 지정합니다.
 
 <Demo name="avatar/avatar-size">
 ```json doc-gen:file
@@ -32,7 +32,7 @@ Avatar의 크기를 설정합니다.
 
 ### Shape
 
-Avatar의 모양을 설정합니다.
+모양을 지정합니다.
 
 <Demo name="avatar/avatar-shape">
 ```json doc-gen:file
@@ -49,7 +49,7 @@ Avatar의 모양을 설정합니다.
 
 ### Composition Pattern
 
-Avatar 컴포넌트의 다양한 구성 패턴입니다.
+하위 컴포넌트를 조합하여 이미지와 대체 콘텐츠를 커스터마이징합니다.
 
 <Demo name="avatar/flexible">
 ```json doc-gen:file
@@ -62,7 +62,7 @@ Avatar 컴포넌트의 다양한 구성 패턴입니다.
 
 ### Fallback Only
 
-이미지 없이 대체 텍스트만 표시합니다.
+이미지 없이 대체 콘텐츠만 표시합니다. `delay` prop으로 대체 콘텐츠의 표시 지연 시간을 설정합니다.
 
 <Demo name="avatar/avatar-fallback-only">
 ```json doc-gen:file

apps/website/package.json

@@ -6,6 +6,7 @@
         "build": "next build",
         "clean": "rm -rf node_modules .next .turbo .source",
         "dev": "next dev --turbo",
+        "docs:generate": "docs-extractor --output ./public/references --cwd ../..",
         "format": "prettier --write \"./src/**/*.{ts,tsx,md}\"",
         "format:check": "prettier --check \"./src/**/*.{ts,tsx,md}\"",
         "postinstall": "fumadocs-mdx",
@@ -58,6 +59,7 @@
         "@types/node": "^22.15.4",
         "@types/react": "^18.0.1",
         "@types/react-dom": "^18.0.1",
+        "@vapor-ui/docs-extractor": "workspace:*",
         "eslint": "^9.20.1",
         "postcss": "^8.5.4",
         "shiki": "^3.7.0",

apps/website/public/references/avatar/fallback-primitive.json

@@ -0,0 +1,23 @@
+{
+    "name": "FallbackPrimitive",
+    "displayName": "Avatar.FallbackPrimitive",
+    "description": "",
+    "props": [
+        {
+            "name": "className",
+            "type": ["string", "((state: Avatar.FallbackPrimitive.State) => string)", "undefined"],
+            "required": false,
+            "description": "CSS class applied to the element, or a function that\nreturns a class based on the component’s state."
+        },
+        {
+            "name": "render",
+            "type": [
+                "((props: HTMLProps, state: Avatar.FallbackPrimitive.State) => ReactElement)",
+                "ReactElement",
+                "undefined"
+            ],
+            "required": false,
+            "description": "Allows you to replace the component’s HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+        }
+    ]
+}

apps/website/public/references/avatar/image-primitive.json

@@ -0,0 +1,29 @@
+{
+    "name": "ImagePrimitive",
+    "displayName": "Avatar.ImagePrimitive",
+    "description": "",
+    "props": [
+        {
+            "name": "className",
+            "type": ["string", "((state: Avatar.ImagePrimitive.State) => string)", "undefined"],
+            "required": false,
+            "description": "CSS class applied to the element, or a function that\nreturns a class based on the component’s state."
+        },
+        {
+            "name": "render",
+            "type": [
+                "((props: HTMLProps, state: Avatar.ImagePrimitive.State) => ReactElement)",
+                "ReactElement",
+                "undefined"
+            ],
+            "required": false,
+            "description": "Allows you to replace the component’s HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+        },
+        {
+            "name": "onLoadingStatusChange",
+            "type": ["((status: ImageLoadingStatus) => void)", "undefined"],
+            "required": false,
+            "description": "Callback fired when the loading status changes."
+        }
+    ]
+}

apps/website/public/references/avatar/root.json

@@ -0,0 +1,57 @@
+{
+    "name": "Root",
+    "displayName": "Avatar.Root",
+    "description": "",
+    "props": [
+        {
+            "name": "className",
+            "type": ["string", "((state: Avatar.Root.State) => string)", "undefined"],
+            "required": false,
+            "description": "CSS class applied to the element, or a function that\nreturns a class based on the component’s state."
+        },
+        {
+            "name": "render",
+            "type": [
+                "((props: HTMLProps, state: Avatar.Root.State) => ReactElement)",
+                "ReactElement",
+                "undefined"
+            ],
+            "required": false,
+            "description": "Allows you to replace the component’s HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+        },
+        {
+            "name": "src",
+            "type": ["string", "undefined"],
+            "required": false,
+            "description": ""
+        },
+        {
+            "name": "alt",
+            "type": ["string"],
+            "required": true,
+            "description": ""
+        },
+        {
+            "name": "delay",
+            "type": ["number", "undefined"],
+            "required": false,
+            "description": ""
+        }
+    ],
+    "variants": [
+        {
+            "name": "size",
+            "type": ["sm", "md", "lg", "xl"],
+            "required": false,
+            "defaultValue": "md",
+            "description": "Sizes for the avatar component"
+        },
+        {
+            "name": "shape",
+            "type": ["square", "circle"],
+            "required": false,
+            "defaultValue": "square",
+            "description": "Shapes for the avatar component"
+        }
+    ]
+}

apps/website/src/components/component-props-table/component-props-table.tsx

@@ -6,6 +6,7 @@ import ReactMarkdown from 'react-markdown';
 import { Badge, Flex, HStack, Text, VStack } from '@vapor-ui/core';
 
 import { InfoPopover } from '~/components/info';
+import { parseComponentName } from '~/utils/component-path';
 
 interface PropDefinition {
     name: string;
@@ -15,11 +16,20 @@ interface PropDefinition {
     defaultValue?: string;
 }
 
+interface VariantDefinition {
+    name: string;
+    type: string[];
+    defaultValue?: string;
+    description?: string;
+    required: boolean;
+}
+
 interface ComponentData {
     name: string;
     displayName: string;
     description: string;
     props: PropDefinition[];
+    variants?: VariantDefinition[];
     generatedAt: string;
     sourceFile: string;
 }
@@ -36,7 +46,9 @@ export const ComponentPropsTable = ({ componentName }: ComponentPropsTableProps)
     React.useEffect(() => {
         const loadComponentData = async () => {
             try {
-                const response = await fetch(`/components/generated/${componentName}.json`);
+                const { folder, filename } = parseComponentName(componentName);
+
+                const response = await fetch(`/references/${folder}/${filename}.json`);
                 if (!response.ok) {
                     throw new Error(`Failed to load component data for ${componentName}`);
                 }
@@ -60,12 +72,26 @@ export const ComponentPropsTable = ({ componentName }: ComponentPropsTableProps)
         return <p>Error: {error}</p>;
     }
 
-    if (!componentData || componentData.props.length === 0) {
+    const hasProps = componentData?.props && componentData.props.length > 0;
+    const hasVariants = componentData?.variants && componentData.variants.length > 0;
+
+    if (!componentData || (!hasProps && !hasVariants)) {
         return <p>No props available for this component.</p>;
     }
 
+    // Props와 Variants를 하나의 배열로 통합
+    type TableRow =
+        | { kind: 'prop'; data: PropDefinition }
+        | { kind: 'variant'; data: VariantDefinition };
+
+    const tableRows: TableRow[] = [
+        ...(componentData?.variants ?? []).map(
+            (variant) => ({ kind: 'variant', data: variant }) as TableRow,
+        ),
+        ...(componentData?.props ?? []).map((prop) => ({ kind: 'prop', data: prop }) as TableRow),
+    ];
     return (
-        <VStack className="w-full not-prose" alignItems="flex-start" gap="$200">
+        <VStack className="w-full not-prose" alignItems="flex-start" gap="$400">
             <Text typography="body1" foreground="normal-200">
                 <ReactMarkdown
                     components={{
@@ -88,10 +114,10 @@ export const ComponentPropsTable = ({ componentName }: ComponentPropsTableProps)
                 borderRadius="$300"
             >
                 <table
-                    className="w-full  border-separate border-spacing-0 overflow-hidden border border-[var(--vapor-color-border-normal)] rounded-[var(--vapor-size-borderRadius-300)]"
+                    className="w-full border-separate border-spacing-0 overflow-hidden border border-[var(--vapor-color-border-normal)] rounded-[var(--vapor-size-borderRadius-300)]"
                     style={{ tableLayout: 'auto' }}
                 >
-                    <thead className="w-full items-start self-stretch rounded-[var(--vapor-size-borderRadius-300)]">
+                    <thead className="w-full items-start self-stretch rounded-[var(--vapor-size-borderRadius-300)] bg-v-canvas-200">
                         <tr className="w-full bg-[var(--vapor-color-background-surface-200)] border-b border-b-[var(--vapor-color-border-normal)]">
                             <th className="px-[var(--vapor-size-space-300)] h-[var(--vapor-size-dimension-500)] text-left rounded-tl-[var(--vapor-size-borderRadius-300)] min-w-[140px] w-px">
                                 <Text typography="subtitle1" foreground="normal-100">
@@ -111,69 +137,74 @@ export const ComponentPropsTable = ({ componentName }: ComponentPropsTableProps)
                         </tr>
                     </thead>
                     <tbody>
-                        {componentData.props.map((prop, index) => (
-                            <tr key={prop.name}>
-                                <td
-                                    className={` px-[var(--vapor-size-space-300)] py-[var(--vapor-size-space-200)] border-b border-b-[var(--vapor-color-border-normal)] min-w-[140px] w-px ${index === componentData.props.length - 1 ? 'rounded-bl-[var(--vapor-size-borderRadius-300)] border-b-0' : ''}`}
-                                >
-                                    <HStack alignItems="center" gap="$100" width="fit-content">
-                                        <Text typography="body2" foreground="normal-200">
-                                            <span>
-                                                {prop.name}
-                                                {!prop.required && '?'}
-                                            </span>
-                                        </Text>
-                                        {prop.description && (
-                                            <InfoPopover>
-                                                <ReactMarkdown
-                                                    components={{
-                                                        code: ({ children }) => (
-                                                            <code className="px-1 py-0.5 rounded bg-v-gray-100 text-sm">
-                                                                {children}
-                                                            </code>
-                                                        ),
-                                                    }}
-                                                >
-                                                    {prop.description}
-                                                </ReactMarkdown>
-                                            </InfoPopover>
-                                        )}
-                                    </HStack>
-                                </td>
-                                <td
-                                    className={`px-[var(--vapor-size-space-300)] py-[var(--vapor-size-space-200)] border-b border-b-[var(--vapor-color-border-normal)] min-w-[100px] w-px ${index === componentData.props.length - 1 ? 'border-b-0' : ''}`}
-                                >
-                                    {prop.defaultValue ? (
-                                        <Badge colorPalette="hint" size="md">
-                                            {prop.defaultValue}
-                                        </Badge>
-                                    ) : (
-                                        '-'
-                                    )}
-                                </td>
-                                <td
-                                    className={`px-[var(--vapor-size-space-300)] py-[var(--vapor-size-space-200)] border-b border-b-[var(--vapor-color-border-normal)] ${index === componentData.props.length - 1 ? 'rounded-br-[var(--vapor-size-borderRadius-300)] border-b-0' : ''}`}
-                                >
-                                    <Flex gap="$100" className="flex-wrap">
-                                        {Array.isArray(prop.type) ? (
-                                            prop.type.map((typeValue) => (
-                                                <Badge
-                                                    key={typeValue}
-                                                    colorPalette="hint"
-                                                    size="md"
-                                                >
-                                                    {typeValue}
-                                                </Badge>
-                                            ))
-                                        ) : (
+                        {tableRows.map((row, index) => {
+                            const isLast = index === tableRows.length - 1;
+
+                            const prop = row.data;
+                            return (
+                                <tr key={`prop-${prop.name}`}>
+                                    <td
+                                        className={`px-[var(--vapor-size-space-300)] py-[var(--vapor-size-space-200)] border-b border-b-[var(--vapor-color-border-normal)] min-w-[140px] w-px ${isLast ? 'rounded-bl-[var(--vapor-size-borderRadius-300)] border-b-0' : ''}`}
+                                    >
+                                        <HStack alignItems="center" gap="$100" width="fit-content">
+                                            <Text typography="body2" foreground="normal-200">
+                                                <span>
+                                                    {prop.name}
+                                                    {!prop.required && '?'}
+                                                </span>
+                                            </Text>
+                                            {prop.description && (
+                                                <InfoPopover>
+                                                    <ReactMarkdown
+                                                        components={{
+                                                            code: ({ children }) => (
+                                                                <code className="px-1 py-0.5 rounded bg-v-gray-100 text-sm">
+                                                                    {children}
+                                                                </code>
+                                                            ),
+                                                        }}
+                                                    >
+                                                        {prop.description}
+                                                    </ReactMarkdown>
+                                                </InfoPopover>
+                                            )}
+                                        </HStack>
+                                    </td>
+                                    <td
+                                        className={`px-[var(--vapor-size-space-300)] py-[var(--vapor-size-space-200)] border-b border-b-[var(--vapor-color-border-normal)] min-w-[100px] w-px ${isLast ? 'border-b-0' : ''}`}
+                                    >
+                                        {prop.defaultValue ? (
                                             <Badge colorPalette="hint" size="md">
-                                                {prop.type}
+                                                {prop.defaultValue}
                                             </Badge>
+                                        ) : (
+                                            '-'
                                         )}
-                                    </Flex>
-                                </td>
-                            </tr>
-                        ))}
+                                    </td>
+                                    <td
+                                        className={`px-[var(--vapor-size-space-300)] py-[var(--vapor-size-space-200)] border-b border-b-[var(--vapor-color-border-normal)] ${isLast ? 'rounded-br-[var(--vapor-size-borderRadius-300)] border-b-0' : ''}`}
+                                    >
+                                        <Flex gap="$100" className="flex-wrap">
+                                            {Array.isArray(prop.type) ? (
+                                                prop.type.map((typeValue) => (
+                                                    <Badge
+                                                        key={typeValue}
+                                                        colorPalette="hint"
+                                                        size="md"
+                                                    >
+                                                        {typeValue}
+                                                    </Badge>
+                                                ))
+                                            ) : (
+                                                <Badge colorPalette="hint" size="md">
+                                                    {prop.type}
+                                                </Badge>
+                                            )}
+                                        </Flex>
+                                    </td>
+                                </tr>
+                            );
+                        })}
                     </tbody>
                 </table>
             </VStack>