@coreui/astro-docs-api-generator 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 creativeLabs Łukasz Holeczek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# @coreui/astro-docs-api-generator
+
+Generates API documentation JSON for [@coreui/astro-docs](https://www.npmjs.com/package/@coreui/astro-docs).
+It reads your component sources with `react-docgen-typescript` (React) or
+`vue-docgen-api` (Vue) and emits one `<Name>.api.json` per component in a
+consistent `ApiData` shape, consumed by the docs engine's `<Api>` component.
+
+## Installation
+
+```sh
+npm install --save-dev @coreui/astro-docs-api-generator
+```
+
+## Usage
+
+Point the CLI at a config module (defaults to `api.config.mjs` in the current
+directory):
+
+```sh
+coreui-docs-api [path/to/api.config.mjs]
+```
+
+`api.config.mjs` lists the framework and the components to document:
+
+```js
+export default {
+  framework: 'react',            // 'react' | 'vue'
+  outDir: 'src/api',             // where the *.api.json files are written
+  importPackage: '@coreui/react', // shown in the generated import snippet
+  components: {
+    CButton: '../coreui-react/src/components/button/CButton.tsx',
+    CAlert: '../coreui-react/src/components/alert/CAlert.tsx',
+  },
+}
+```
+
+Paths are resolved relative to the config file. The React extractor loads
+eagerly; the Vue one lazily, so a React-only run never pulls in `vue-docgen-api`.
+
+## License
+
+[MIT](./LICENSE) © [CoreUI](https://coreui.io)

package/bin/coreui-docs-api.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.mjs'
+
+run(process.argv[2]).catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@coreui/astro-docs-api-generator",
+  "version": "0.1.0-beta.0",
+  "description": "API documentation JSON generator for @coreui/astro-docs (React + Vue), emitting a consistent ApiData shape.",
+  "type": "module",
+  "license": "MIT",
+  "author": "The CoreUI Team (https://github.com/orgs/coreui/people)",
+  "homepage": "https://coreui.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/coreui/astro-docs.git",
+    "directory": "packages/api-generator"
+  },
+  "bugs": {
+    "url": "https://github.com/coreui/astro-docs/issues"
+  },
+  "keywords": [
+    "coreui",
+    "docs",
+    "api",
+    "react-docgen",
+    "vue-docgen"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "coreui-docs-api": "bin/coreui-docs-api.mjs"
+  },
+  "exports": {
+    ".": "./src/cli.mjs",
+    "./react": "./src/react.mjs",
+    "./vue": "./src/vue.mjs"
+  },
+  "files": [
+    "src",
+    "bin"
+  ],
+  "dependencies": {
+    "react-docgen-typescript": "^2.4.0",
+    "vue-docgen-api": "^4.79.2"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,71 @@
+// Config-driven API generator. The consumer points it at a config module listing
+// components -> source files plus the framework + import paths; this runs the
+// matching extractor and writes one `<Name>.api.json` (the shared ApiData shape)
+// per component. The React extractor is loaded eagerly; the Vue one lazily, so a
+// React-only consumer doesn't pay for vue-docgen-api.
+import { writeFileSync, mkdirSync } from 'node:fs'
+import { resolve, dirname } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { extractReact } from './react.mjs'
+
+function importSnippet({ name, rel, importPackage, importSrcBase }) {
+  if (!importPackage) return undefined
+  const lines = [`import { ${name} } from '${importPackage}'`]
+  // The deep source import (`…/src/components/…`) is opt-in via `importSrcBase`; most
+  // docs only need the package import (ESM tree-shakes it anyway).
+  if (importSrcBase) {
+    const srcPath = rel.replace(/^.*\/src\//, '').replace(/\.(tsx?|jsx?|vue)$/, '')
+    lines.push('// or', `import ${name} from '${importSrcBase}/${srcPath}'`)
+  }
+  return lines.join('\n')
+}
+
+export async function run(configPath = 'api.config.mjs') {
+  const configFile = resolve(process.cwd(), configPath)
+  const config = (await import(pathToFileURL(configFile).href)).default
+  const baseDir = dirname(configFile)
+  const outDir = resolve(baseDir, config.outDir ?? 'src/api')
+  mkdirSync(outDir, { recursive: true })
+
+  const extract =
+    config.framework === 'vue'
+      ? (await import('./vue.mjs')).extractVue
+      : extractReact
+
+  let failed = 0
+  for (const [name, rel] of Object.entries(config.components)) {
+    const file = resolve(baseDir, rel)
+    let data
+    try {
+      data = await extract({ name, file })
+    } catch (error) {
+      // One unparseable component (e.g. an old-style `<Type>value` cast that the docgen
+      // parser rejects) must not abort the whole run — log it and keep going.
+      console.error(`Skipped ${name}: ${error.message} (${file})`)
+      failed += 1
+      continue
+    }
+    if (!data) {
+      console.error(`No component found: ${name} (${file})`)
+      continue
+    }
+
+    const imports = importSnippet({
+      name,
+      rel,
+      importPackage: config.importPackage,
+      importSrcBase: config.importSrcBase,
+    })
+    if (imports) data.imports = imports
+
+    writeFileSync(resolve(outDir, `${name}.api.json`), JSON.stringify(data, null, 2))
+    const counts = [
+      `${data.props.length} props`,
+      data.events?.length ? `${data.events.length} events` : null,
+      data.slots?.length ? `${data.slots.length} slots` : null,
+    ]
+      .filter(Boolean)
+      .join(', ')
+    console.log(`generated ${name}.api.json (${counts})`)
+  }
+}

package/src/react.mjs

@@ -0,0 +1,27 @@
+// React API extractor: react-docgen-typescript -> the shared ApiData shape.
+// React documents everything as props, so there are no events/slots.
+import { parse } from 'react-docgen-typescript'
+
+export function extractReact({ name, file }) {
+  const components = parse(file, { shouldIncludePropTagMap: true })
+  const component = components.find((c) => c.displayName === name) || components[0]
+  if (!component) return null
+
+  const props = Object.entries(component.props)
+    .filter(([, info]) => {
+      const parentFile = info.parent?.fileName
+      return !parentFile || !parentFile.includes('@types/react')
+    })
+    .filter(([, info]) => info.tags?.ignore !== '')
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([propName, info]) => ({
+      name: propName,
+      type: info.type?.name?.includes('ReactElement') ? 'ReactElement' : info.type?.name || '',
+      default: info.defaultValue?.value ?? null,
+      description: info.description || '',
+      since: info.tags?.since || null,
+      deprecated: info.tags?.deprecated || null,
+    }))
+
+  return { name: component.displayName, props }
+}

package/src/vue.mjs

@@ -0,0 +1,56 @@
+// Vue API extractor: vue-docgen-api -> the shared ApiData shape. Vue exports props,
+// events and slots separately (events carry `properties`, slots carry `bindings`),
+// all normalized here to the same shape React props use, so the engine's <Api>
+// renders them uniformly.
+import { parse } from 'vue-docgen-api'
+
+const firstTag = (tags, key) => {
+  const entry = tags?.[key]
+  if (!entry) return null
+  return Array.isArray(entry) ? entry[0]?.description || entry[0]?.name || null : entry
+}
+
+const typeName = (type) => {
+  if (!type) return ''
+  if (type.names) return type.names.join(', ')
+  if (type.name === 'union' && type.elements) return type.elements.map((e) => e.name).join(', ')
+  return type.name || ''
+}
+
+export async function extractVue({ name, file }) {
+  // CoreUI Vue components are render-function `.ts` (no JSX), and some use the old
+  // angle-bracket cast `<Type>value` which the JSX-enabled babel parser rejects. Disable
+  // JSX so those `.ts` files parse.
+  const doc = await parse(file, { jsx: false })
+
+  const props = (doc.props || []).map((prop) => ({
+    name: prop.name,
+    type: typeName(prop.type),
+    default: prop.defaultValue?.value ?? null,
+    description: prop.description || '',
+    since: firstTag(prop.tags, 'since'),
+    deprecated: firstTag(prop.tags, 'deprecated'),
+  }))
+
+  const events = (doc.events || []).map((event) => ({
+    name: event.name,
+    description: event.description || '',
+    properties: (event.properties || []).map((property) => ({
+      name: property.name,
+      type: typeName(property.type),
+      description: property.description || '',
+    })),
+  }))
+
+  const slots = (doc.slots || []).map((slot) => ({
+    name: slot.name,
+    description: slot.description || '',
+    bindings: (slot.bindings || []).map((binding) => ({
+      name: binding.name,
+      type: typeName(binding.type),
+      description: binding.description || '',
+    })),
+  }))
+
+  return { name: name || doc.displayName, props, events, slots }
+}