docs: update API documentation

Author: mrholek

packages/docs/build/api.mjs

@@ -3,129 +3,321 @@
 'use strict'
 
 import { globby } from 'globby'
-import { writeFile } from 'node:fs/promises'
+import { writeFile, mkdir } from 'node:fs/promises'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { parse } from 'react-docgen-typescript'
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url))
+/**
+ * Derive __dirname in ESM
+ */
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
 
-const GLOB = [
+/**
+ * Glob patterns to locate .tsx files for documentation.
+ * Adjust these patterns based on your project structure.
+ */
+const GLOB_PATTERNS = [
   '**/src/**/*.tsx',
   '../node_modules/@coreui/icons-react/src/**/*.tsx',
   '../node_modules/@coreui/react-chartjs/src/**/*.tsx',
 ]
+
+/**
+ * Options for globby to control file matching behavior.
+ */
 const GLOBBY_OPTIONS = {
   absolute: true,
   cwd: path.join(__dirname, '..', '..'),
   gitignore: false,
   ignore: ['**/docs/**', '**/__tests__/**'],
 }
-const EXCLUDED_FILES = []
 
-const options = {
+/**
+ * Excluded files list (currently unused).
+ * Can be utilized for additional exclusion patterns if needed.
+ */
+const EXCLUDED_FILES = [] // Currently unused, but can be utilized if needed
+
+/**
+ * Options for react-docgen-typescript parser.
+ */
+const DOCGEN_OPTIONS = {
   savePropValueAsString: true,
   shouldIncludePropTagMap: true,
 }
 
-const PRO_COMPONENTS = []
+/**
+ * List of pro components that require special handling.
+ */
+const PRO_COMPONENTS = [
+  'CDatePicker',
+  'CDateRangePicker',
+  'CFormMask',
+  'CLoadingButton',
+  'CMultiSelect',
+  'CRating',
+  'CSmartPagination',
+  'CSmartTable',
+  'CTimePicker',
+  'CVirtualScroller',
+]
+
+/**
+ * Escapes special characters in text to prevent Markdown rendering issues.
+ *
+ * @param {string} text - The text to escape.
+ * @returns {string} - The escaped text.
+ */
+function escapeMarkdown(text) {
+  if (typeof text !== 'string') return text
+  return (
+    text
+      .replaceAll(/(<)/g, String.raw`\$1`)
+      // .replaceAll(/<C(.*)\/>/g, '`<C$1/>`')
+      .replaceAll('\n', '<br/>')
+      .replaceAll(/`([^`]+)`/g, '<code>{`$1`}</code>')
+  )
+}
 
-const replace = (text) =>
-  text
-    .replaceAll('(<', '(\\<')
-    .replace(/<C(.*)\/>/g, '`<C$1/>`')
-    .replaceAll('\n', '<br/>')
+/**
+ * Generates the relative filename based on the file path.
+ *
+ * @param {string} file - The absolute file path.
+ * @returns {string} - The relative filename.
+ */
+function getRelativeFilename(file) {
+  let relativePath
+  relativePath = file.includes('node_modules')
+    ? path.relative(path.join(__dirname, '..', '..'), file).replace('coreui-', '')
+    : path.relative(GLOBBY_OPTIONS.cwd, file).replace('coreui-', '')
 
-async function createMdx(file, filename, name, props) {
-  if (typeof props === 'undefined') {
-    return
+  // Remove '-pro' from the filename if not a pro component
+  const isPro = PRO_COMPONENTS.some((component) => file.includes(component))
+  if (!isPro) {
+    relativePath = relativePath.replace('-pro', '')
   }
 
-  const pro = PRO_COMPONENTS.some((v) => file.includes(v))
-  let relativeFilename
-  if (file.includes('node_modules')) {
-    relativeFilename = file.replace(path.join(file, '..', '..', '..'), '').replace('coreui-', '')
-  } else {
-    relativeFilename = file.replace(GLOBBY_OPTIONS.cwd, '').replace('coreui-', '')
+  return relativePath
+}
+
+/**
+ * Splits the input string by the '|' character, but only when the '|' is outside of any curly braces {} and parentheses ().
+ *
+ * @param {string} input - The string to be split.
+ * @returns {string[]} An array of split parts, trimmed of whitespace.
+ * @throws {Error} Throws an error if there are unmatched braces or parentheses in the input.
+ */
+function splitOutsideBracesAndParentheses(input) {
+  const parts = []
+  let currentPart = ''
+  let braceDepth = 0 // Tracks depth of curly braces {}
+  let parenthesisDepth = 0 // Tracks depth of parentheses ()
+
+  for (const char of input) {
+    switch (char) {
+      case '{': {
+        braceDepth++
+        break
+      }
+      case '}': {
+        braceDepth--
+        if (braceDepth < 0) {
+          throw new Error('Unmatched closing curly brace detected.')
+        }
+        break
+      }
+      case '(': {
+        parenthesisDepth++
+        break
+      }
+      case ')': {
+        parenthesisDepth--
+        if (parenthesisDepth < 0) {
+          throw new Error('Unmatched closing parenthesis detected.')
+        }
+        break
+      }
+      case '|': {
+        // Split only if not inside any braces or parentheses
+        if (braceDepth === 0 && parenthesisDepth === 0 && currentPart.trim()) {
+          parts.push(currentPart.trim())
+          currentPart = ''
+          continue // Skip adding the '|' to currentPart
+        }
+        break
+      }
+      default: {
+        // No action needed for other characters
+        break
+      }
+    }
+    currentPart += char
+  }
+
+  // After processing all characters, check for unmatched opening braces or parentheses
+  if (braceDepth !== 0) {
+    throw new Error('Unmatched opening curly brace detected.')
+  }
+  if (parenthesisDepth !== 0) {
+    throw new Error('Unmatched opening parenthesis detected.')
   }
 
-  if (!pro) {
-    relativeFilename = relativeFilename.replace('-pro', '')
+  // Add the last accumulated part if it's not empty
+  if (currentPart.trim()) {
+    parts.push(currentPart.trim())
   }
 
-  let content = `\n`
-  content += `\`\`\`jsx\n`
-  content += `import { ${name} } from '@coreui/${relativeFilename.split('/')[1]}'\n`
+  return parts
+}
+
+/**
+ * Creates an MDX file with the component's API documentation.
+ *
+ * @param {string} file - The absolute path to the component file.
+ * @param {object} component - The component information extracted by react-docgen-typescript.
+ */
+async function createMdx(file, component) {
+  if (!component) {
+    return
+  }
+
+  const filename = path.basename(file, '.tsx')
+  const relativeFilename = getRelativeFilename(file)
+
+  // Construct import statements
+  let content = `\n\`\`\`jsx\n`
+  const importPathParts = relativeFilename.split('/')
+  if (importPathParts.length > 1) {
+    content += `import { ${component.displayName} } from '@coreui/${importPathParts[1]}'\n`
+  }
   content += `// or\n`
-  content += `import ${name} from '@coreui${relativeFilename.replace('.tsx', '')}'\n`
+  content += `import ${component.displayName} from '@coreui${relativeFilename.replace('.tsx', '')}'\n`
   content += `\`\`\`\n\n`
 
-  let index = 0
-  for (const [key, value] of Object.entries(props).sort()) {
+  const sortedProps = Object.entries(component.props).sort(([a], [b]) => a.localeCompare(b))
+
+  // Initialize table headers
+  for (const [index, [propName, propInfo]] of sortedProps.entries()) {
+    const isLast = index === sortedProps.length - 1
+    if (index === 0) {
+      content += `<div className="table-responsive table-api border rounded mb-3">\n`
+      content += `  <table className="table">\n`
+      content += `    <thead>\n`
+      content += `      <tr>\n`
+      content += `        <th>Property</th>\n`
+      content += `        <th>Default</th>\n`
+      content += `        <th>Type</th>\n`
+      content += `      </tr>\n`
+      content += `    </thead>\n`
+      content += `    <tbody>\n`
+    }
+
+    // Skip props from React's type definitions
     if (
-      value.parent.fileName.includes('@types/react/index.d.ts') ||
-      value.parent.fileName.includes('@types/react/ts5.0/index.d.ts')
+      propInfo.parent?.fileName?.includes('@types/react/index.d.ts') ||
+      propInfo.parent?.fileName?.includes('@types/react/ts5.0/index.d.ts')
     ) {
+      if (isLast) {
+        content += `    </tbody>\n`
+        content += `  </table>\n`
+        content += `</div>\n`
+      }
+
       continue
     }
 
-    if (value.tags.ignore === '') {
+    // Skip props marked to be ignored
+    if (propInfo.tags?.ignore === '') {
       continue
     }
 
-    if (index === 0) {
-      content += `| Property | Description | Type | Default |\n`
-      content += `| --- | --- | --- | --- |\n`
-    }
-    let name = value.name || ''
-    const since = value.tags.since ? ` **_${value.tags.since}+_**` : ''
-    const deprecated = value.tags.deprecated ? ` **_Deprecated ${value.tags.deprecated}+_**` : ''
-    const description = value.description || '-'
-    const type = value.type
-      ? value.type.name.includes('ReactElement')
+    const displayName = propInfo.name || ''
+    const since = propInfo.tags?.since
+      ? `<span className="badge bg-success">${propInfo.tags.since}+</span>`
+      : ''
+    const deprecated = propInfo.tags?.deprecated
+      ? `<span className="badge bg-success">Deprecated ${propInfo.tags.since}</span>`
+      : ''
+    const description = propInfo.description || '-'
+
+    const type = propInfo.type
+      ? propInfo.type.name.includes('ReactElement')
         ? 'ReactElement'
-        : value.type.name
+        : propInfo.type.name
       : ''
-    const defaultValue = value.defaultValue
-      ? value.defaultValue.value.replace('undefined', '-')
-      : '-'
-    const types = []
-    type.split(' | ').map((element) => {
-      types.push(`\`${element.replace(/"/g, "'")}\``)
-    })
-
-    content += `| **${name}**${since}${deprecated} | ${replace(description)} | ${types.join(
-      ' \\| ',
-    )} | ${replace(defaultValue)} |\n`
-    index++
+    const defaultValue = propInfo.defaultValue ? `\`${propInfo.defaultValue.value}\`` : `undefined`
+
+    // Format types as inline code
+    const types = splitOutsideBracesAndParentheses(type)
+      .map((_type) => `\`${_type.trim()}\``)
+      .join(', ')
+
+    const id = `${component.displayName.toLowerCase()}-${propName}`
+    const anchor = `<a href="#${id}" aria-label="${component.displayName} ${displayName} permalink" className="anchor-link after">#</a>`
+
+    content += `      <tr id="${id}">\n`
+    content += `        <td className="text-primary fw-semibold">${displayName}${anchor}${since}${deprecated}</td>\n`
+    content += `        <td>${escapeMarkdown(defaultValue)}</td>\n`
+    content += `        <td>${escapeMarkdown(types)}</td>\n`
+    content += `      </tr>\n`
+    content += `      <tr>\n`
+    content += `        <td colSpan="3">${escapeMarkdown(description)}${propInfo.tags?.example ? `<br /><JSXDocs code={\`${propInfo.tags.example}\`} />` : ''}</td>\n`
+    content += `      </tr>\n`
+
+    if (isLast) {
+      content += `    </tbody>\n`
+      content += `  </table>\n`
+      content += `</div>\n`
+    }
   }
 
-  await writeFile(`content/api/${filename}.api.mdx`, content, {
-    encoding: 'utf8',
-  }).then(() => {
+  // Define the output directory and ensure it exists
+  const outputDir = path.join('content', 'api')
+  const outputPath = path.join(outputDir, `${filename}.api.mdx`)
+
+  // Create the directory if it doesn't exist
+  try {
+    await mkdir(outputDir, { recursive: true })
+    await writeFile(outputPath, content, { encoding: 'utf8' })
     console.log(`File created: ${filename}.api.mdx`)
-  })
+  } catch (error) {
+    console.error(`Failed to write file ${outputPath}:`, error)
+  }
 }
 
+/**
+ * Main function to execute the script.
+ */
 async function main() {
   try {
-    const files = await globby(GLOB, GLOBBY_OPTIONS, EXCLUDED_FILES)
+    // Retrieve all matching files based on the glob patterns
+    const files = await globby(GLOB_PATTERNS, GLOBBY_OPTIONS)
 
+    // Process each file concurrently
     await Promise.all(
-      files.map((file) => {
-        console.log(file)
-        // const props = docgen.parse(file, options)
-        const props = parse(file, options)
-        if (props && typeof props[0] !== 'undefined') {
-          const filename = path.basename(file, '.tsx')
-          createMdx(file, filename, props[0].displayName, props[0].props)
+      files.map(async (file) => {
+        console.log(`Processing file: ${file}`)
+        let components
+
+        try {
+          components = parse(file, DOCGEN_OPTIONS)
+        } catch (parseError) {
+          console.error(`Failed to parse ${file}:`, parseError)
+          return
+        }
+
+        if (components && components.length > 0) {
+          await Promise.all(components.map((component) => createMdx(file, component)))
         }
       }),
     )
   } catch (error) {
-    console.error(error)
+    console.error('An error occurred:', error)
     process.exit(1)
   }
 }
 
+// Execute the main function
 main()