1#!/usr/bin/env npx tsx
2/**
3 * Generates nuxt-ui component docs from Nuxt UI repo (cloned to /tmp)
4 * Run: npx tsx skills/nuxt-ui/scripts/generate-components.ts
5 *
6 * Creates:
7 *   - references/components.md (index with version column for Other category)
8 *   - components/<name>.md (per-component details)
9 */
10 
11import { execSync } from 'node:child_process'
12import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
13import { tmpdir } from 'node:os'
14import { basename, dirname, join } from 'node:path'
15import { fileURLToPath } from 'node:url'
16 
17const TMP_DIR = join(tmpdir(), 'nuxt-ui-docs-gen')
18const REPO_URL = 'https://github.com/nuxt/ui.git'
19const DOCS_PATH = 'docs/content/docs/2.components'
20 
21interface ComponentMeta {
22  name: string
23  description: string
24  category: string
25  rekaLink?: string
26  version?: string
27}
28 
29// Category groupings for better organization
30const CATEGORIES: Record<string, string> = {
31  element: 'Element',
32  form: 'Form',
33  data: 'Data',
34  navigation: 'Navigation',
35  overlay: 'Overlay',
36  layout: 'Layout',
37}
38 
39// Version mapping for components introduced after v4.0
40const VERSION_MAP: Record<string, string> = {
41  'empty': 'v4.1+',
42  'scroll-area': 'v4.3+',
43  'input-date': 'v4.2+',
44  'input-time': 'v4.2+',
45  'editor': 'v4.3+',
46  'editor-drag-handle': 'v4.3+',
47  'editor-emoji-menu': 'v4.3+',
48  'editor-mention-menu': 'v4.3+',
49  'editor-suggestion-menu': 'v4.3+',
50  'editor-toolbar': 'v4.3+',
51}
52 
53function parseYamlFrontmatter(content: string): { frontmatter: Record<string, any>, body: string } {
54  const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/)
55  if (!match)
56    return { frontmatter: {}, body: content }
57 
58  const frontmatter: Record<string, any> = {}
59  const yamlContent = match[1]
60 
61  // Simple YAML parsing for our needs
62  for (const line of yamlContent.split('\n')) {
63    const colonIdx = line.indexOf(':')
64    if (colonIdx > 0 && !line.startsWith(' ') && !line.startsWith('-')) {
65      const key = line.slice(0, colonIdx).trim()
66      const value = line.slice(colonIdx + 1).trim()
67      frontmatter[key] = value.replace(/^['"]|['"]$/g, '')
68    }
69  }
70 
71  // Parse links for Reka UI reference
72  if (yamlContent.includes('reka-ui.com')) {
73    const rekaMatch = yamlContent.match(/to:\s*(https:\/\/reka-ui\.com[^\n]+)/)
74    if (rekaMatch)
75      frontmatter.rekaLink = rekaMatch[1]
76  }
77 
78  return { frontmatter, body: match[2] }
79}
80 
81function generateComponentFile(name: string, meta: ComponentMeta, body: string): string {
82  const lines: string[] = []
83  const displayName = name.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join('')
84 
85  lines.push(`# ${displayName}`)
86  lines.push('')
87  lines.push(meta.description)
88  lines.push('')
89 
90  if (meta.rekaLink) {
91    lines.push(`> Based on [Reka UI ${displayName}](${meta.rekaLink})`)
92    lines.push('')
93  }
94 
95  // Extract key props from body text
96  const propMentions = body.match(/Use the `(\w+)` prop/g)
97  if (propMentions && propMentions.length > 0) {
98    lines.push('## Key Props')
99    lines.push('')
100    const uniqueProps = [...new Set(propMentions.map(m => m.match(/`(\w+)`/)?.[1]).filter(Boolean))]
101    for (const prop of uniqueProps.slice(0, 10)) {
102      // Find the description after the prop mention
103      const propRegex = new RegExp(`Use the \`${prop}\` prop ([^.]+\\.?)`)
104      const desc = body.match(propRegex)?.[1] || ''
105      lines.push(`- \`${prop}\`: ${desc.replace(/to\s+$/, '').trim()}`)
106    }
107    lines.push('')
108  }
109 
110  // Add basic usage
111  lines.push('## Usage')
112  lines.push('')
113  lines.push('```vue')
114  lines.push(`<U${displayName}`)
115  lines.push(`  <!-- props here -->`)
116  lines.push(`/>`)
117  lines.push('```')
118  lines.push('')
119 
120  // Add slot info if present - look for slot mentions in text
121  const slotPattern = /`#(\w+)`\{?/g
122  const slotMatches = [...body.matchAll(slotPattern)]
123  if (slotMatches.length > 0) {
124    const validSlots = ['default', 'content', 'header', 'body', 'footer', 'title', 'description', 'leading', 'trailing', 'icon', 'label', 'close', 'trigger', 'actions', 'item', 'empty']
125    const uniqueSlots = [...new Set(slotMatches.map(m => m[1]))]
126      .filter(s => validSlots.includes(s))
127    if (uniqueSlots.length > 0) {
128      lines.push('## Slots')
129      lines.push('')
130      for (const slot of uniqueSlots.slice(0, 8)) {
131        lines.push(`- \`#${slot}\``)
132      }
133      lines.push('')
134    }
135  }
136 
137  return lines.join('\n')
138}
139 
140async function main() {
141  const __dirname = dirname(fileURLToPath(import.meta.url))
142  const baseDir = join(__dirname, '..')
143  const componentsDir = join(baseDir, 'components')
144 
145  // Clean previous run and clone fresh
146  rmSync(TMP_DIR, { recursive: true, force: true })
147  console.log('Cloning nuxt/ui (sparse checkout)...')
148  try {
149    execSync(`git clone --depth 1 --filter=blob:none --sparse ${REPO_URL} ${TMP_DIR}`, { stdio: 'inherit' })
150    execSync(`git sparse-checkout set ${DOCS_PATH}`, { cwd: TMP_DIR, stdio: 'inherit' })
151  }
152  catch {
153    console.error(`\nFailed to clone ${REPO_URL}. Check network/GitHub status.`)
154    process.exit(1)
155  }
156 
157  const NUXT_UI_DOCS = join(TMP_DIR, DOCS_PATH)
158 
159  mkdirSync(componentsDir, { recursive: true })
160 
161  console.log('Generating Nuxt UI component docs...')
162 
163  const files = readdirSync(NUXT_UI_DOCS).filter(f => f.endsWith('.md') && f !== '0.index.md')
164  const components: ComponentMeta[] = []
165 
166  for (const file of files) {
167    const name = basename(file, '.md')
168    const content = readFileSync(join(NUXT_UI_DOCS, file), 'utf-8')
169    const { frontmatter, body } = parseYamlFrontmatter(content)
170 
171    const meta: ComponentMeta = {
172      name,
173      description: frontmatter.description || '',
174      category: frontmatter.category || 'other',
175      rekaLink: frontmatter.rekaLink,
176      version: VERSION_MAP[name],
177    }
178    components.push(meta)
179 
180    // Generate component file
181    const componentContent = generateComponentFile(name, meta, body)
182    writeFileSync(join(componentsDir, `${name}.md`), componentContent)
183    console.log(`✓ Generated components/${name}.md`)
184  }
185 
186  // Generate index
187  const index: string[] = []
188  index.push('# Components')
189  index.push('')
190  index.push('> Auto-generated from Nuxt UI docs. Run `npx tsx skills/nuxt-ui/scripts/generate-components.ts` to update.')
191  index.push('')
192  index.push('> **For headless primitives (API, accessibility):** see `reka-ui` skill')
193  index.push('')
194 
195  // Group by category
196  const byCategory: Record<string, ComponentMeta[]> = {}
197  for (const comp of components) {
198    const cat = CATEGORIES[comp.category] || 'Other'
199    if (!byCategory[cat])
200      byCategory[cat] = []
201    byCategory[cat].push(comp)
202  }
203 
204  // Calculate column widths for alignment
205  function getMaxLengths(comps: ComponentMeta[], hasVersionCol: boolean) {
206    let maxComp = 'Component'.length
207    let maxDesc = 'Description'.length
208    for (const comp of comps) {
209      const displayName = comp.name.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join('')
210      const link = `[${displayName}](components/${comp.name}.md)`
211      if (link.length > maxComp)
212        maxComp = link.length
213      const desc = hasVersionCol ? comp.description : (comp.version ? `${comp.description} (${comp.version})` : comp.description)
214      if (desc.length > maxDesc)
215        maxDesc = desc.length
216    }
217    return { maxComp, maxDesc }
218  }
219 
220  for (const [cat, comps] of Object.entries(byCategory).sort((a, b) => a[0].localeCompare(b[0]))) {
221    index.push(`## ${cat}`)
222    index.push('')
223    const hasVersionCol = cat === 'Other'
224    const { maxComp, maxDesc } = getMaxLengths(comps, hasVersionCol)
225 
226    if (hasVersionCol) {
227      index.push(`| ${'Component'.padEnd(maxComp)} | ${'Description'.padEnd(maxDesc)} | Version |`)
228      index.push(`| ${'-'.repeat(maxComp)} | ${'-'.repeat(maxDesc)} | ------- |`)
229    }
230    else {
231      index.push(`| ${'Component'.padEnd(maxComp)} | ${'Description'.padEnd(maxDesc)} |`)
232      index.push(`| ${'-'.repeat(maxComp)} | ${'-'.repeat(maxDesc)} |`)
233    }
234 
235    for (const comp of comps.sort((a, b) => a.name.localeCompare(b.name))) {
236      const displayName = comp.name.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join('')
237      const link = `[${displayName}](components/${comp.name}.md)`
238      if (hasVersionCol) {
239        const desc = comp.version ? `${comp.description} (${comp.version})` : comp.description
240        index.push(`| ${link.padEnd(maxComp)} | ${desc.padEnd(maxDesc)} | ${(comp.version || '').padEnd(7)} |`)
241      }
242      else {
243        const desc = comp.version ? `${comp.description} (${comp.version})` : comp.description
244        index.push(`| ${link.padEnd(maxComp)} | ${desc.padEnd(maxDesc)} |`)
245      }
246    }
247    index.push('')
248  }
249 
250  writeFileSync(join(baseDir, 'references', 'components.md'), index.join('\n'))
251  console.log('✓ Generated references/components.md (index)')
252 
253  console.log(`\nDone! Generated ${components.length + 1} files.`)
254}
255 
256main().catch(console.error)
257