chore: add autogenerated docs for component adapters

Author: serikjensen

build/componentDocsEmitter.cjs

@@ -0,0 +1,291 @@
+// 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')
+
+// --- CONFIG ---
+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(intf) {
+  return intf.getType().getApparentProperties()
+}
+
+function formatType(type) {
+  if (!type) return '-'
+  const text = type.getText()
+  if (text === 'ReactNode' || text === 'React.ReactNode') {
+    return text
+  }
+  if (text.includes('ReactNode')) {
+    // Show as ReactNode or React.ReactNode, not the full union
+    return text.includes('React.ReactNode') ? 'React.ReactNode' : 'ReactNode'
+  }
+  if (type.isArray()) {
+    return escapePipes(formatType(type.getArrayElementType()) + '[]')
+  }
+  if (type.isUnion()) {
+    // Filter out 'undefined' from union types
+    const filtered = type.getUnionTypes().filter(t => t.getText() !== 'undefined')
+    // If the union is exactly 'false | true' or 'true | false', return 'boolean'
+    if (
+      filtered.length === 2 &&
+      ((filtered[0].getText() === 'false' && filtered[1].getText() === 'true') ||
+        (filtered[0].getText() === 'true' && filtered[1].getText() === 'false'))
+    ) {
+      return 'boolean'
+    }
+    if (filtered.length === 1) return escapePipes(formatType(filtered[0]))
+    return escapePipes(filtered.map(formatType).join(' | '))
+  }
+  if (type.isIntersection()) {
+    return escapePipes(type.getIntersectionTypes().map(formatType).join(' & '))
+  }
+  if (type.getSymbol() && type.getSymbol().getDeclarations().length) {
+    const decl = type.getSymbol().getDeclarations()[0]
+    if (
+      decl.getKindName() === 'InterfaceDeclaration' ||
+      decl.getKindName() === 'TypeAliasDeclaration'
+    ) {
+      const name = type.getSymbol().getName()
+      // Don't create links for RefObject
+      if (name === 'RefObject') {
+        return escapePipes(name)
+      }
+      return escapePipes(`[${name}](#${name.toLowerCase()})`)
+    }
+  }
+  return escapePipes(text)
+}
+
+function escapePipes(str) {
+  return str.replace(/\|/g, '\\|')
+}
+
+function getDefaultValue(prop, decl) {
+  if (decl && decl.getKindName() === 'PropertySignature') {
+    const init = decl.getInitializer && decl.getInitializer()
+    if (init) return init.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(sf => sf.getInterfaces())
+    .filter(intf => !OMIT.includes(intf.getName()))
+
+  // --- Add type aliases that resolve to object types ---
+  const typeAliases = sourceFiles
+    .flatMap(sf => sf.getTypeAliases())
+    .filter(ta => {
+      // Only include type aliases that resolve to object types
+      const type = ta.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(ta => !OMIT.includes(ta.getName()))
+
+  // Wrap type aliases in a similar interface-like object for unified handling
+  const pseudoInterfaces = typeAliases.map(ta => ({
+    getName: () => ta.getName(),
+    getType: () => ta.getType(),
+    getDeclarations: () => [ta],
+  }))
+
+  // Combine interfaces and pseudo-interfaces
+  const allIntfs = [...interfaces, ...pseudoInterfaces].sort((a, b) =>
+    a.getName().localeCompare(b.getName()),
+  )
+
+  // --- Infer parent-child relationships ---
+  const interfaceMap = new Map(allIntfs.map(intf => [intf.getName(), intf]))
+  const allNames = new Set(allIntfs.map(intf => intf.getName()))
+  const parentToChildren = new Map()
+  const childToParent = new Map()
+
+  for (const parentIntf of allIntfs) {
+    const props = getAllPropsFlattened(parentIntf)
+    for (const prop of props) {
+      const referenced = findReferencedNames(prop.getTypeAtLocation(parentIntf), allNames)
+      for (const typeName of referenced) {
+        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 = allIntfs.filter(intf => !childToParent.has(intf.getName()))
+
+  // --- Topological sort for logical order ---
+  // Build dependency graph: parent -> [children]
+  const graph = new Map()
+  allIntfs.forEach(intf => {
+    graph.set(intf.getName(), parentToChildren.get(intf.getName()) || [])
+  })
+
+  // Topological sort
+  const visited = new Set()
+  const sorted = []
+  function visit(name) {
+    if (visited.has(name)) return
+    visited.add(name)
+    const children = graph.get(name) || []
+    for (const child of children) {
+      visit(child)
+    }
+    sorted.push(name)
+  }
+  // Visit all interfaces (in original order for stability)
+  allIntfs.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 = graph.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, ' ') // Remove newlines from type
+      const decl = prop.getDeclarations()[0]
+      const required =
+        decl && typeof decl.hasQuestionToken === 'function'
+          ? decl.hasQuestionToken()
+            ? 'No'
+            : 'Yes'
+          : '-'
+      const def = getDefaultValue(prop, decl)
+      const desc = getDescription(prop, decl)
+      const isMarkdownLink = type.startsWith('[') && type.includes('](')
+      const typeCell = isMarkdownLink ? type : `\`${type}\``
+      return `| **${name}** | ${typeCell} | ${required} | ${def} | ${desc} |`
+    })
+    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)

build/typedocMdPrefixPlugin.mjs

@@ -0,0 +1,12 @@
+export function load(app) {
+  app.renderer.markdownHooks.on('page.begin', args => {
+    const name = args.page.model.name
+    const title = name.includes('/') ? name.split('/').pop() : name
+    return `# ${title}`
+  }),
+    app.renderer.markdownHooks.on('index.page.begin', args => {
+      return `# Component Adapter Inventory
+
+The following are a list of types for available component adapters. Follow the links below to view the interfaces.`
+    })
+}