chore: add autogenerated docs for component adapters

Author: serikjensen

build/componentDocsEmitter.cjs

@@ -0,0 +1,371 @@
+// This script generates UI component prop documentation using ts-morph (CommonJS version).
+// It will flatten all props, including those picked from React types, and output markdown in the same format as component-inventory.md.
+
+const { Project } = require('ts-morph')
+const { writeFile, mkdir } = require('fs').promises
+const { join } = require('path')
+
+const UI_DIR = join(__dirname, '../src/components/Common/UI')
+const OUTPUT_DIR = join(__dirname, '../docs/06/01')
+const OUTPUT_FILE = join(OUTPUT_DIR, 'component-inventory.md')
+const OMIT = [
+  'BaseListProps',
+  'SharedFieldLayoutProps',
+  'FieldLayoutProps',
+  'InternalFieldLayoutProps',
+  'SharedHorizontalFieldLayoutProps',
+  'HorizontalFieldLayoutProps',
+  'InputProps',
+]
+
+function getAllPropsFlattened(interfaceOrAlias) {
+  return interfaceOrAlias.getType().getApparentProperties()
+}
+
+function formatType(type) {
+  if (!type) return '-'
+  const typeText = type.getText()
+  if (typeText === 'ReactNode' || typeText === 'React.ReactNode') {
+    return typeText
+  }
+
+  if (typeText.includes('ReactNode')) {
+    return typeText.includes('React.ReactNode') ? 'React.ReactNode' : 'ReactNode'
+  }
+
+  if (type.isArray()) {
+    return formatType(type.getArrayElementType()) + '[]'
+  }
+
+  if (type.isUnion()) {
+    const unionTypes = type.getUnionTypes().filter(t => t.getText() !== 'undefined')
+    // Special-case React Ref<T> union: null | function | RefObject<T>
+    const hasNull = unionTypes.some(t => t.getText() === 'null')
+    const refObjType = unionTypes.find(t => {
+      const symbol = t.getSymbol && t.getSymbol()
+      return symbol && symbol.getName() === 'RefObject'
+    })
+
+    const fnType = unionTypes.find(t => t.getCallSignatures && t.getCallSignatures().length === 1)
+    if (hasNull && refObjType && fnType && unionTypes.length === 3) {
+      // Try to get the type argument from RefObject<T>
+      const typeArgs = refObjType.getTypeArguments && refObjType.getTypeArguments()
+      if (typeArgs && typeArgs.length) {
+        // Render type argument as plain text, not a link
+        const argType = typeArgs[0]
+        const argName = argType.getSymbol()?.getName() || argType.getText()
+        return `Ref<${argName}>`
+      }
+      return 'Ref<any>'
+    }
+
+    if (
+      unionTypes.length === 2 &&
+      ((unionTypes[0].getText() === 'false' && unionTypes[1].getText() === 'true') ||
+        (unionTypes[0].getText() === 'true' && unionTypes[1].getText() === 'false'))
+    ) {
+      return 'boolean'
+    }
+
+    if (unionTypes.length === 1) {
+      return formatType(unionTypes[0])
+    }
+
+    return unionTypes.map(formatType).join(' | ')
+  }
+
+  if (type.isIntersection()) {
+    return type.getIntersectionTypes().map(formatType).join(' & ')
+  }
+
+  // Special-case RefObject and Ref
+  const symbol = type.getSymbol && type.getSymbol()
+  if (symbol) {
+    const name = symbol.getName()
+    if (name === 'RefObject' || name === 'Ref') {
+      const typeArgs = type.getTypeArguments()
+      if (typeArgs.length) {
+        // Render type argument as plain text, not a link
+        const argType = typeArgs[0]
+        const argName = argType.getSymbol()?.getName() || argType.getText()
+        return `${name}<${argName}>`
+      }
+      return name
+    }
+  }
+
+  if (symbol && symbol.getDeclarations().length) {
+    const decl = symbol.getDeclarations()[0]
+    if (
+      decl.getKindName() === 'InterfaceDeclaration' ||
+      decl.getKindName() === 'TypeAliasDeclaration'
+    ) {
+      const name = symbol.getName()
+
+      if (name === 'RefObject') {
+        return name
+      }
+
+      return `[${name}](#${name.toLowerCase()})`
+    }
+  }
+  return typeText
+}
+
+function escapePipes(str) {
+  return str.replace(/\|/g, '\\|')
+}
+
+function getDefaultValue(prop, decl) {
+  if (decl && decl.getKindName() === 'PropertySignature') {
+    const initializer = decl.getInitializer && decl.getInitializer()
+    if (initializer) return initializer.getText()
+  }
+  return '-'
+}
+
+function getDescription(prop, decl) {
+  if (!decl) return '-'
+  const jsDocs = decl.getJsDocs && decl.getJsDocs()
+  if (jsDocs && jsDocs.length > 0) {
+    return (
+      jsDocs
+        .map(doc => doc.getComment() || '')
+        .join(' ')
+        .trim() || '-'
+    )
+  }
+  return '-'
+}
+
+function findReferencedNames(type, allNames) {
+  if (type.isArray()) {
+    return findReferencedNames(type.getArrayElementType(), allNames)
+  }
+
+  if (type.isUnion()) {
+    return type.getUnionTypes().flatMap(t => findReferencedNames(t, allNames))
+  }
+
+  if (type.isIntersection()) {
+    return type.getIntersectionTypes().flatMap(t => findReferencedNames(t, allNames))
+  }
+
+  const symbol = type.getSymbol && type.getSymbol()
+  if (symbol && allNames.has(symbol.getName())) {
+    return [symbol.getName()]
+  }
+
+  return []
+}
+
+async function main() {
+  const project = new Project({
+    tsConfigFilePath: join(__dirname, '../tsconfig.json'),
+    skipAddingFilesFromTsConfig: false,
+  })
+
+  // Add all *Types.ts files in UI_DIR
+  project.addSourceFilesAtPaths(join(UI_DIR, '**/*Types.ts'))
+  // Add React types for prop flattening
+  project.addSourceFilesAtPaths(join(__dirname, '../node_modules/@types/react/index.d.ts'))
+
+  // Get all interfaces and type aliases in the UI directory
+  const sourceFiles = project.getSourceFiles(join(UI_DIR, '**/*Types.ts'))
+  const interfaces = sourceFiles
+    .flatMap(sourceFile => sourceFile.getInterfaces())
+    .filter(interfaceDecl => !OMIT.includes(interfaceDecl.getName()))
+
+  // --- Add type aliases that resolve to object types ---
+  const typeAliases = sourceFiles
+    .flatMap(sourceFile => sourceFile.getTypeAliases())
+    .filter(typeAlias => {
+      const type = typeAlias.getType()
+      // Type literal or intersection of object types
+      if (type.isObject() && type.getProperties().length > 0) {
+        return true
+      }
+
+      if (type.isIntersection()) {
+        return type.getIntersectionTypes().some(t => t.isObject() && t.getProperties().length > 0)
+      }
+
+      return false
+    })
+    .filter(typeAlias => !OMIT.includes(typeAlias.getName()))
+
+  // Wrap type aliases in a similar interface-like object for unified handling
+  const pseudoInterfaces = typeAliases.map(typeAlias => ({
+    getName: () => typeAlias.getName(),
+    getType: () => typeAlias.getType(),
+    getDeclarations: () => [typeAlias],
+  }))
+
+  // Combine interfaces and pseudo-interfaces
+  const allInterfaces = [...interfaces, ...pseudoInterfaces].sort((a, b) =>
+    a.getName().localeCompare(b.getName()),
+  )
+
+  // --- Infer parent-child relationships ---
+  const interfaceMap = new Map(allInterfaces.map(intf => [intf.getName(), intf]))
+  const allNames = new Set(allInterfaces.map(intf => intf.getName()))
+  const parentToChildren = new Map()
+  const childToParent = new Map()
+
+  for (const parentIntf of allInterfaces) {
+    const props = getAllPropsFlattened(parentIntf)
+    for (const prop of props) {
+      const referencedNames = findReferencedNames(prop.getTypeAtLocation(parentIntf), allNames)
+      for (const typeName of referencedNames) {
+        if (!parentToChildren.has(parentIntf.getName())) {
+          parentToChildren.set(parentIntf.getName(), [])
+        }
+
+        if (!parentToChildren.get(parentIntf.getName()).includes(typeName)) {
+          parentToChildren.get(parentIntf.getName()).push(typeName)
+        }
+
+        childToParent.set(typeName, parentIntf.getName())
+      }
+    }
+  }
+
+  // --- Prepare output order ---
+  // Only top-level parents (not children) go in the top-level list
+  const topLevelInterfaces = allInterfaces.filter(intf => !childToParent.has(intf.getName()))
+
+  // --- Topological sort for logical order ---
+  // Build dependency graph: parent -> [children]
+  const dependencyGraph = new Map()
+  allInterfaces.forEach(intf => {
+    dependencyGraph.set(intf.getName(), parentToChildren.get(intf.getName()) || [])
+  })
+
+  // Topological sort
+  const visited = new Set()
+  const sortedNames = []
+
+  function visit(name) {
+    if (visited.has(name)) {
+      return
+    }
+
+    visited.add(name)
+    const children = dependencyGraph.get(name) || []
+    for (const child of children) {
+      visit(child)
+    }
+    sortedNames.push(name)
+  }
+
+  // Visit all interfaces (in original order for stability)
+  allInterfaces.forEach(intf => visit(intf.getName()))
+
+  // --- Compute heading levels ---
+  // Start at level 2 for top-level, children are one deeper than their parent
+  const headingLevels = {}
+  function setHeadingLevel(name, level) {
+    headingLevels[name] = level
+    const children = dependencyGraph.get(name) || []
+    for (const child of children) {
+      setHeadingLevel(child, level + 1)
+    }
+  }
+
+  topLevelInterfaces.forEach(intf => setHeadingLevel(intf.getName(), 2))
+
+  // --- Generate index (nested) ---
+  function indexEntry(intf, level = 0, indexed = new Set()) {
+    if (indexed.has(intf.getName())) {
+      return ''
+    }
+
+    indexed.add(intf.getName())
+
+    const indent = '  '.repeat(level)
+    let entry = `${indent}- [${intf.getName()}](#${intf.getName().toLowerCase()})`
+    const children = parentToChildren.get(intf.getName()) || []
+    for (const childName of children) {
+      const childIntf = interfaceMap.get(childName)
+      if (childIntf) {
+        const childEntry = indexEntry(childIntf, level + 1, indexed)
+        if (childEntry) {
+          entry += `\n${childEntry}`
+        }
+      }
+    }
+    return entry
+  }
+  const indexSet = new Set()
+  const index = topLevelInterfaces
+    .map(intf => indexEntry(intf, 0, indexSet))
+    .filter(Boolean)
+    .join('\n')
+
+  // --- Output sections in parent-before-children order ---
+  const outputted = new Set()
+  function sectionForInterfaceParentFirst(intf, level = 2) {
+    if (outputted.has(intf.getName())) {
+      return ''
+    }
+
+    const heading = `${'#'.repeat(level)} ${intf.getName()}`
+    const props = getAllPropsFlattened(intf)
+    // Remove duplicates by name
+    const seen = new Set()
+    const uniqueProps = props.filter(p => {
+      if (seen.has(p.getName())) return false
+      seen.add(p.getName())
+      return true
+    })
+    const rows = uniqueProps.map(prop => {
+      const name = prop.getName()
+
+      let type = formatType(prop.getTypeAtLocation(intf))
+      type = type.replace(/\n/g, ' ').replace(/\r/g, ' ')
+      const decl = prop.getDeclarations()[0]
+
+      const required =
+        decl && typeof decl.hasQuestionToken === 'function'
+          ? decl.hasQuestionToken()
+            ? 'No'
+            : 'Yes'
+          : '-'
+
+      const defaultValue = getDefaultValue(prop, decl)
+      const description = getDescription(prop, decl)
+      const isMarkdownLink = type.startsWith('[') && type.includes('](')
+      const typeCell = isMarkdownLink ? escapePipes(type) : `\`${escapePipes(type)}\``
+
+      return `| **${name}** | ${typeCell} | ${required} | ${defaultValue} | ${description} |`
+    })
+    const header =
+      '| Prop | Type | Required | Default | Description |\n|------|------|----------|---------|-------------|'
+    outputted.add(intf.getName())
+    let section = `${heading}\n\n${header}\n${rows.join('\n')}`
+    // Output children after parent
+    const children = parentToChildren.get(intf.getName()) || []
+    for (const childName of children) {
+      const childIntf = interfaceMap.get(childName)
+      if (childIntf) {
+        const childSection = sectionForInterfaceParentFirst(childIntf, level + 1)
+        if (childSection) {
+          section += '\n\n' + childSection
+        }
+      }
+    }
+    return section
+  }
+  const sections = topLevelInterfaces
+    .map(intf => sectionForInterfaceParentFirst(intf))
+    .filter(Boolean)
+    .join('\n\n')
+
+  const markdown = `# Component Inventory\n\n${index}\n\n${sections}`
+
+  await mkdir(OUTPUT_DIR, { recursive: true })
+  await writeFile(OUTPUT_FILE, markdown)
+  console.log(`Documentation written to ${OUTPUT_FILE}`)
+}
+
+main().catch(console.error)