1#!/usr/bin/env npx tsx
2/**
3 * Generates reka-ui component docs from GitHub meta files
4 * Run: npx tsx skills/reka-ui/scripts/generate-components.ts
5 *
6 * Creates:
7 *   - components.md (index)
8 *   - components/<group>.md (per-group details)
9 */
10 
11import { mkdirSync, writeFileSync } from 'node:fs'
12import { dirname, join } from 'node:path'
13import { fileURLToPath } from 'node:url'
14 
15const REPO = 'unovue/reka-ui'
16const BRANCH = 'main'
17const BASE_URL = `https://raw.githubusercontent.com/${REPO}/${BRANCH}`
18 
19interface PropMeta { name: string, description: string, type: string, required: boolean, default?: string }
20interface EmitMeta { name: string, description: string, type: string }
21interface SlotMeta { name: string, description: string, type: string }
22 
23const COMPONENT_GROUPS: Record<string, { category: string, description: string, components: string[] }> = {
24  checkbox: { category: 'Form', description: 'Selection control with indeterminate state', components: ['CheckboxGroupRoot', 'CheckboxRoot', 'CheckboxIndicator'] },
25  combobox: { category: 'Form', description: 'Searchable dropdown with filtering', components: ['ComboboxRoot', 'ComboboxInput', 'ComboboxAnchor', 'ComboboxTrigger', 'ComboboxContent', 'ComboboxViewport', 'ComboboxItem', 'ComboboxItemIndicator', 'ComboboxGroup', 'ComboboxLabel', 'ComboboxEmpty', 'ComboboxSeparator', 'ComboboxArrow', 'ComboboxPortal', 'ComboboxCancel', 'ComboboxVirtualizer'] },
26  editable: { category: 'Form', description: 'Inline text editing with preview/edit modes', components: ['EditableRoot', 'EditableArea', 'EditableInput', 'EditablePreview', 'EditableSubmitTrigger', 'EditableCancelTrigger', 'EditableEditTrigger'] },
27  label: { category: 'Form', description: 'Accessible form label', components: ['Label'] },
28  listbox: { category: 'Form', description: 'Accessible list selection', components: ['ListboxRoot', 'ListboxContent', 'ListboxFilter', 'ListboxItem', 'ListboxItemIndicator', 'ListboxGroup', 'ListboxGroupLabel', 'ListboxVirtualizer'] },
29  numberField: { category: 'Form', description: 'Numeric input with increment/decrement', components: ['NumberFieldRoot', 'NumberFieldInput', 'NumberFieldIncrement', 'NumberFieldDecrement'] },
30  pinInput: { category: 'Form', description: 'Multi-character code entry (OTP)', components: ['PinInputRoot', 'PinInputInput'] },
31  radioGroup: { category: 'Form', description: 'Mutually exclusive selection', components: ['RadioGroupRoot', 'RadioGroupItem', 'RadioGroupIndicator'] },
32  select: { category: 'Form', description: 'Dropdown selection with grouping', components: ['SelectRoot', 'SelectTrigger', 'SelectPortal', 'SelectContent', 'SelectViewport', 'SelectItem', 'SelectItemText', 'SelectItemIndicator', 'SelectGroup', 'SelectLabel', 'SelectSeparator', 'SelectArrow', 'SelectScrollUpButton', 'SelectScrollDownButton', 'SelectValue', 'SelectIcon'] },
33  slider: { category: 'Form', description: 'Range input control', components: ['SliderRoot', 'SliderTrack', 'SliderRange', 'SliderThumb'] },
34  switch: { category: 'Form', description: 'Toggle between two states', components: ['SwitchRoot', 'SwitchThumb'] },
35  tagsInput: { category: 'Form', description: 'Multiple tag entry and management', components: ['TagsInputRoot', 'TagsInputInput', 'TagsInputItem', 'TagsInputItemText', 'TagsInputItemDelete', 'TagsInputClear'] },
36  toggle: { category: 'Form', description: 'Single state button toggle', components: ['Toggle'] },
37  toggleGroup: { category: 'Form', description: 'Multiple toggles with group behavior', components: ['ToggleGroupRoot', 'ToggleGroupItem'] },
38 
39  calendar: { category: 'Date', description: 'Date selection grid (alpha)', components: ['CalendarRoot', 'CalendarHeader', 'CalendarHeading', 'CalendarGrid', 'CalendarGridHead', 'CalendarGridBody', 'CalendarGridRow', 'CalendarCell', 'CalendarCellTrigger', 'CalendarHeadCell', 'CalendarNext', 'CalendarPrev'] },
40  dateField: { category: 'Date', description: 'Date input field (alpha)', components: ['DateFieldRoot', 'DateFieldInput'] },
41  datePicker: { category: 'Date', description: 'Date picker with calendar (alpha)', components: ['DatePickerRoot', 'DatePickerField', 'DatePickerInput', 'DatePickerTrigger', 'DatePickerContent', 'DatePickerCalendar', 'DatePickerHeader', 'DatePickerHeading', 'DatePickerGrid', 'DatePickerCell', 'DatePickerCellTrigger', 'DatePickerNext', 'DatePickerPrev', 'DatePickerAnchor', 'DatePickerArrow', 'DatePickerClose'] },
42  dateRangeField: { category: 'Date', description: 'Date range input (alpha)', components: ['DateRangeFieldRoot', 'DateRangeFieldInput'] },
43  dateRangePicker: { category: 'Date', description: 'Date range picker (alpha)', components: ['DateRangePickerRoot', 'DateRangePickerField', 'DateRangePickerInput', 'DateRangePickerTrigger', 'DateRangePickerContent', 'DateRangePickerCalendar', 'DateRangePickerHeader', 'DateRangePickerHeading', 'DateRangePickerGrid', 'DateRangePickerCell', 'DateRangePickerCellTrigger', 'DateRangePickerNext', 'DateRangePickerPrev'] },
44  rangeCalendar: { category: 'Date', description: 'Calendar for date ranges (alpha)', components: ['RangeCalendarRoot', 'RangeCalendarHeader', 'RangeCalendarHeading', 'RangeCalendarGrid', 'RangeCalendarCell', 'RangeCalendarCellTrigger', 'RangeCalendarNext', 'RangeCalendarPrev'] },
45  timeField: { category: 'Date', description: 'Time input field (alpha)', components: ['TimeFieldRoot', 'TimeFieldInput'] },
46 
47  accordion: { category: 'Disclosure', description: 'Collapsible content sections', components: ['AccordionRoot', 'AccordionItem', 'AccordionHeader', 'AccordionTrigger', 'AccordionContent'] },
48  collapsible: { category: 'Disclosure', description: 'Single collapsible panel', components: ['CollapsibleRoot', 'CollapsibleTrigger', 'CollapsibleContent'] },
49 
50  alertDialog: { category: 'Overlay', description: 'Modal dialog requiring action', components: ['AlertDialogRoot', 'AlertDialogTrigger', 'AlertDialogPortal', 'AlertDialogOverlay', 'AlertDialogContent', 'AlertDialogTitle', 'AlertDialogDescription', 'AlertDialogCancel', 'AlertDialogAction'] },
51  dialog: { category: 'Overlay', description: 'Modal dialog', components: ['DialogRoot', 'DialogTrigger', 'DialogPortal', 'DialogOverlay', 'DialogContent', 'DialogTitle', 'DialogDescription', 'DialogClose'] },
52  hoverCard: { category: 'Overlay', description: 'Card shown on hover', components: ['HoverCardRoot', 'HoverCardTrigger', 'HoverCardPortal', 'HoverCardContent', 'HoverCardArrow'] },
53  popover: { category: 'Overlay', description: 'Floating content panel', components: ['PopoverRoot', 'PopoverTrigger', 'PopoverPortal', 'PopoverContent', 'PopoverArrow', 'PopoverClose', 'PopoverAnchor'] },
54  tooltip: { category: 'Overlay', description: 'Informational hover tip', components: ['TooltipProvider', 'TooltipRoot', 'TooltipTrigger', 'TooltipPortal', 'TooltipContent', 'TooltipArrow'] },
55  toast: { category: 'Overlay', description: 'Temporary notifications', components: ['ToastProvider', 'ToastRoot', 'ToastViewport', 'ToastTitle', 'ToastDescription', 'ToastAction', 'ToastClose', 'ToastPortal'] },
56 
57  contextMenu: { category: 'Menu', description: 'Right-click context menu', components: ['ContextMenuRoot', 'ContextMenuTrigger', 'ContextMenuPortal', 'ContextMenuContent', 'ContextMenuItem', 'ContextMenuCheckboxItem', 'ContextMenuRadioGroup', 'ContextMenuRadioItem', 'ContextMenuItemIndicator', 'ContextMenuLabel', 'ContextMenuGroup', 'ContextMenuSeparator', 'ContextMenuSub', 'ContextMenuSubTrigger', 'ContextMenuSubContent', 'ContextMenuArrow'] },
58  dropdownMenu: { category: 'Menu', description: 'Dropdown action menu', components: ['DropdownMenuRoot', 'DropdownMenuTrigger', 'DropdownMenuPortal', 'DropdownMenuContent', 'DropdownMenuItem', 'DropdownMenuCheckboxItem', 'DropdownMenuRadioGroup', 'DropdownMenuRadioItem', 'DropdownMenuItemIndicator', 'DropdownMenuLabel', 'DropdownMenuGroup', 'DropdownMenuSeparator', 'DropdownMenuSub', 'DropdownMenuSubTrigger', 'DropdownMenuSubContent', 'DropdownMenuArrow'] },
59  menubar: { category: 'Menu', description: 'Horizontal menu bar', components: ['MenubarRoot', 'MenubarMenu', 'MenubarTrigger', 'MenubarPortal', 'MenubarContent', 'MenubarItem', 'MenubarCheckboxItem', 'MenubarRadioGroup', 'MenubarRadioItem', 'MenubarItemIndicator', 'MenubarLabel', 'MenubarGroup', 'MenubarSeparator', 'MenubarSub', 'MenubarSubTrigger', 'MenubarSubContent', 'MenubarArrow'] },
60  navigationMenu: { category: 'Menu', description: 'Site navigation menu', components: ['NavigationMenuRoot', 'NavigationMenuList', 'NavigationMenuItem', 'NavigationMenuTrigger', 'NavigationMenuContent', 'NavigationMenuLink', 'NavigationMenuIndicator', 'NavigationMenuViewport', 'NavigationMenuSub'] },
61 
62  avatar: { category: 'Data', description: 'User image with fallback', components: ['AvatarRoot', 'AvatarImage', 'AvatarFallback'] },
63  pagination: { category: 'Data', description: 'Page navigation', components: ['PaginationRoot', 'PaginationList', 'PaginationListItem', 'PaginationFirst', 'PaginationPrev', 'PaginationNext', 'PaginationLast', 'PaginationEllipsis'] },
64  progress: { category: 'Data', description: 'Progress indicator', components: ['ProgressRoot', 'ProgressIndicator'] },
65  scrollArea: { category: 'Data', description: 'Custom scrollbar container', components: ['ScrollAreaRoot', 'ScrollAreaViewport', 'ScrollAreaScrollbar', 'ScrollAreaThumb', 'ScrollAreaCorner'] },
66  separator: { category: 'Data', description: 'Visual divider', components: ['Separator'] },
67  splitter: { category: 'Data', description: 'Resizable split panels', components: ['SplitterGroup', 'SplitterPanel', 'SplitterResizeHandle'] },
68  stepper: { category: 'Data', description: 'Multi-step progress indicator', components: ['StepperRoot', 'StepperItem', 'StepperTrigger', 'StepperTitle', 'StepperDescription', 'StepperIndicator', 'StepperSeparator'] },
69  tabs: { category: 'Data', description: 'Tabbed content panels', components: ['TabsRoot', 'TabsList', 'TabsTrigger', 'TabsContent', 'TabsIndicator'] },
70  tree: { category: 'Data', description: 'Hierarchical tree view', components: ['TreeRoot', 'TreeItem', 'TreeVirtualizer'] },
71 
72  aspectRatio: { category: 'Layout', description: 'Maintain aspect ratio', components: ['AspectRatio'] },
73  toolbar: { category: 'Layout', description: 'Toolbar with buttons/toggles', components: ['ToolbarRoot', 'ToolbarButton', 'ToolbarLink', 'ToolbarToggleGroup', 'ToolbarToggleItem', 'ToolbarSeparator'] },
74  configProvider: { category: 'Utility', description: 'Global config context', components: ['ConfigProvider'] },
75  focusScope: { category: 'Utility', description: 'Focus trap container', components: ['FocusScope'] },
76  presence: { category: 'Utility', description: 'Animation presence control', components: ['Presence'] },
77  primitive: { category: 'Utility', description: 'Base element wrapper', components: ['Primitive', 'Slot'] },
78  visuallyHidden: { category: 'Utility', description: 'Screen reader only content', components: ['VisuallyHidden'] },
79}
80 
81const COMPOSABLES = [
82  { name: 'useEmitAsProps', description: 'Convert emit functions to props for passing to child components' },
83  { name: 'useFilter', description: 'Filter items based on search query with customizable matching' },
84  { name: 'useForwardProps', description: 'Forward props to child components while filtering out handled ones' },
85  { name: 'useForwardPropsEmits', description: 'Combine useForwardProps and useEmitAsProps' },
86  { name: 'useForwardExpose', description: 'Forward exposed methods/refs from child components' },
87  { name: 'useId', description: 'Generate unique IDs for accessibility attributes' },
88  { name: 'useDateFormatter', description: 'Format dates with locale support' },
89  { name: 'useDirection', description: 'Get/set text direction (ltr/rtl)' },
90  { name: 'useLocale', description: 'Get/set locale for internationalization' },
91]
92 
93async function fetchMeta(componentName: string): Promise<{ props: PropMeta[], emits: EmitMeta[], slots: SlotMeta[] }> {
94  const url = `${BASE_URL}/docs/content/meta/${componentName}.md`
95  try {
96    const res = await fetch(url)
97    if (!res.ok)
98      return { props: [], emits: [], slots: [] }
99    const text = await res.text()
100    return parseMeta(text)
101  }
102  catch { return { props: [], emits: [], slots: [] } }
103}
104 
105function parseMeta(content: string): { props: PropMeta[], emits: EmitMeta[], slots: SlotMeta[] } {
106  const props: PropMeta[] = []
107  const emits: EmitMeta[] = []
108  const slots: SlotMeta[] = []
109  const propsMatch = content.match(/<PropsTable\s+:data="(\[[\s\S]*?\])"\s*\/>/)
110  const emitsMatch = content.match(/<EmitsTable\s+:data="(\[[\s\S]*?\])"\s*\/>/)
111  const slotsMatch = content.match(/<SlotsTable\s+:data="(\[[\s\S]*?\])"\s*\/>/)
112  if (propsMatch) {
113    try {
114      props.push(...JSON.parse(propsMatch[1].replace(/'/g, '"')))
115    }
116    catch {}
117  }
118  if (emitsMatch) {
119    try {
120      emits.push(...JSON.parse(emitsMatch[1].replace(/'/g, '"')))
121    }
122    catch {}
123  }
124  if (slotsMatch) {
125    try {
126      slots.push(...JSON.parse(slotsMatch[1].replace(/'/g, '"')))
127    }
128    catch {}
129  }
130  return { props, emits, slots }
131}
132 
133const escapeMarkdown = (str: string) => str.replace(/\|/g, '\\|').replace(/\n/g, ' ')
134 
135function truncateType(type: string, max = 50) {
136  const c = type.replace(/\s+/g, ' ').trim()
137  return c.length > max ? `${c.slice(0, max - 3)}...` : c
138}
139const toKebab = (str: string) => str.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase()
140 
141async function generateGroupFile(groupName: string, group: { category: string, description: string, components: string[] }): Promise<string> {
142  const lines: string[] = []
143  const title = groupName.charAt(0).toUpperCase() + groupName.slice(1).replace(/([A-Z])/g, ' $1').trim()
144  lines.push(`# ${title}`)
145  lines.push('')
146  lines.push(group.description)
147  lines.push('')
148  lines.push(`**Parts:** ${group.components.map(c => `\`${c}\``).join(', ')}`)
149  lines.push('')
150 
151  for (const comp of group.components) {
152    const meta = await fetchMeta(comp)
153    if (meta.props.length === 0 && meta.emits.length === 0 && meta.slots.length === 0)
154      continue
155 
156    lines.push(`## ${comp}`)
157    lines.push('')
158 
159    if (meta.props.length > 0) {
160      lines.push('### Props')
161      lines.push('| Prop | Type | Default |')
162      lines.push('|------|------|---------|')
163      for (const p of meta.props) {
164        const type = escapeMarkdown(truncateType(p.type))
165        const def = p.default ? `\`${escapeMarkdown(p.default)}\`` : '-'
166        lines.push(`| \`${p.name}\`${p.required ? '*' : ''} | \`${type}\` | ${def} |`)
167      }
168      lines.push('')
169    }
170 
171    if (meta.emits.length > 0) {
172      lines.push('### Emits')
173      lines.push('| Event | Payload |')
174      lines.push('|-------|---------|')
175      for (const e of meta.emits) {
176        lines.push(`| \`${e.name}\` | \`${escapeMarkdown(truncateType(e.type))}\` |`)
177      }
178      lines.push('')
179    }
180 
181    if (meta.slots.length > 0) {
182      lines.push('### Slots')
183      lines.push('| Slot | Type |')
184      lines.push('|------|------|')
185      for (const s of meta.slots) {
186        lines.push(`| \`${s.name}\` | \`${escapeMarkdown(truncateType(s.type))}\` |`)
187      }
188      lines.push('')
189    }
190  }
191  return lines.join('\n')
192}
193 
194async function main() {
195  const __dirname = dirname(fileURLToPath(import.meta.url))
196  const baseDir = join(__dirname, '..')
197  const componentsDir = join(baseDir, 'components')
198  mkdirSync(componentsDir, { recursive: true })
199 
200  console.log('Generating Reka UI component docs...')
201 
202  // Generate index
203  const index: string[] = []
204  index.push('# Components')
205  index.push('')
206  index.push('> Auto-generated. Run `npx tsx skills/reka-ui/scripts/generate-components.ts` to update.')
207  index.push('')
208 
209  const categories: Record<string, string[]> = {}
210  for (const [name, group] of Object.entries(COMPONENT_GROUPS)) {
211    if (!categories[group.category])
212      categories[group.category] = []
213    categories[group.category].push(name)
214  }
215 
216  for (const [cat, groupNames] of Object.entries(categories)) {
217    index.push(`## ${cat}`)
218    index.push('')
219    index.push('| Component | Description | File |')
220    index.push('|-----------|-------------|------|')
221    for (const name of groupNames) {
222      const g = COMPONENT_GROUPS[name]
223      const file = `components/${toKebab(name)}.md`
224      index.push(`| **${name}** | ${g.description} | \`${file}\` |`)
225    }
226    index.push('')
227  }
228 
229  index.push('## Composables')
230  index.push('')
231  index.push('| Composable | Description |')
232  index.push('|------------|-------------|')
233  for (const c of COMPOSABLES) {
234    index.push(`| \`${c.name}\` | ${c.description} |`)
235  }
236  index.push('')
237 
238  writeFileSync(join(baseDir, 'components.md'), index.join('\n'))
239  console.log('✓ Generated components.md (index)')
240 
241  // Generate per-group files
242  for (const [name, group] of Object.entries(COMPONENT_GROUPS)) {
243    const content = await generateGroupFile(name, group)
244    const filename = `${toKebab(name)}.md`
245    writeFileSync(join(componentsDir, filename), content)
246    console.log(`✓ Generated components/${filename}`)
247  }
248 
249  console.log(`\nDone! Generated ${Object.keys(COMPONENT_GROUPS).length + 1} files.`)
250}
251 
252main().catch(console.error)
253