@patternfly/patternfly-doc-core 1.2.1 → 1.4.0

package/.astro/collections/textContent.schema.json

@@ -16,6 +16,12 @@
         "title": {
           "type": "string"
         },
+        "propComponents": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
         "tab": {
           "type": "string"
         },

package/README.md

@@ -37,13 +37,14 @@ To define the markdown schema this project uses a typescript based schema known
 
 All commands are run from the root of the project, from a terminal:
 
-| Command                   | Action                                           |
-| :------------------------ | :----------------------------------------------- |
-| `npm install`             | Installs dependencies                            |
-| `npm run dev`             | Starts local dev server at `localhost:4321`      |
-| `npm run build`           | Build your production site to `./dist/`          |
-| `npm run preview`         | Preview your build locally, before deploying     |
-| `npm run astro ...`       | Run CLI commands like `astro add`, `astro check` |
-| `npm run astro -- --help` | Get help using the Astro CLI                     |
-| `npm run build:cli`       | Create a JS build of the documentation core CLI  |
-| `npm run build:cli:watch` | Run the CLI builder in watch mode                |
+| Command                   | Action                                                            |
+| :------------------------ | :-----------------------------------------------------------------|
+| `npm install`             | Installs dependencies                                             |
+| `npm run dev`             | Starts local dev server at `localhost:4321`                       |
+| `npm run build`           | Build your production site to `./dist/`                           |
+| `npm run preview`         | Preview your build locally, before deploying                      |
+| `npm run astro ...`       | Run CLI commands like `astro add`, `astro check`                  |
+| `npm run astro -- --help` | Get help using the Astro CLI                                      |
+| `npm run build:cli`       | Create a JS build of the documentation core CLI                   |
+| `npm run build:cli:watch` | Run the CLI builder in watch mode                                 |
+| `npm run build:props`     | Create a json file of your TsDoc compatible in code documentation |

package/astro.config.mjs

@@ -2,9 +2,12 @@
 import { defineConfig } from 'astro/config';
 import react from '@astrojs/react';
 
+import node from '@astrojs/node';
+
 // https://astro.build/config
 export default defineConfig({
   integrations: [react()],
+
   vite: {
     ssr: {
       noExternal: ["@patternfly/*", "react-dropzone"],
@@ -14,5 +17,9 @@ export default defineConfig({
         allow: ['./']
       }
     }
-  }
+  },
+
+  adapter: node({
+    mode: 'standalone'
+  })
 });

package/cli/buildPropsData.ts

@@ -0,0 +1,113 @@
+/* eslint-disable no-console */
+
+import { glob } from 'glob'
+import { writeFile } from 'fs/promises'
+import { join } from 'path'
+
+import { tsDocgen } from './tsDocGen.js'
+import { getConfig, PropsGlobs } from './getConfig.js'
+
+interface Prop {
+  name: string
+  type: string
+  description?: string
+  required?: boolean
+  defaultValue?: string
+  hide?: boolean
+}
+interface TsDoc {
+  name: string
+  description: string
+  props: Prop[]
+}
+interface PropsData {
+  [key: string]: TsDoc
+}
+
+// Build unique names for components with a "variant" extension
+type TsDocVariants = 'next' | 'deprecated' | undefined
+function getTsDocName(name: string, variant: TsDocVariants) {
+  return `${name}${variant ? `-${variant}` : ''}`
+}
+
+function getTsDocNameVariant(source: string) {
+  if (source.includes('next')) {
+    return 'next'
+  }
+
+  if (source.includes('deprecated')) {
+    return 'deprecated'
+  }
+}
+
+async function getFiles(root: string, globs: PropsGlobs[]) {
+  const files = await Promise.all(
+    globs.map(async ({ include, exclude }) => {
+      const files = await glob(include, { cwd: root, ignore: exclude })
+      return files
+    }),
+  )
+  return files.flat()
+}
+
+async function getPropsData(files: string[], verbose: boolean) {
+  const perFilePropsData = await Promise.all(
+    files.map(async (file) => {
+      if (verbose) {
+        console.log(`Parsing props from ${file}`)
+      }
+
+      const props = (await tsDocgen(file)) as TsDoc[]
+
+      const tsDocs = props.reduce((acc, { name, description, props }) => {
+        const key = getTsDocName(name, getTsDocNameVariant(file))
+        return { ...acc, [key]: { name, description, props } }
+      }, {} as PropsData)
+
+      return tsDocs
+    }),
+  )
+
+  const combinedPropsData = perFilePropsData.reduce((acc, props) => {
+    Object.keys(props).forEach((key) => {
+      const propsData = props[key]
+      if (acc[key]) {
+        acc[key].props = [...acc[key].props, ...propsData.props]
+      } else {
+        acc[key] = propsData
+      }
+    })
+    return acc
+  }, {})
+
+  return combinedPropsData
+}
+
+export async function buildPropsData(
+  rootDir: string,
+  astroRoot: string,
+  configFile: string,
+  verbose: boolean,
+) {
+  const config = await getConfig(configFile)
+  if (!config) {
+    return
+  }
+
+  const { propsGlobs } = config
+  if (!propsGlobs) {
+    console.error('No props data found in config')
+    return
+  }
+
+  const files = await getFiles(rootDir, propsGlobs)
+  if (verbose) {
+    console.log(`Found ${files.length} files to parse`)
+  }
+
+  const propsData = await getPropsData(files, verbose)
+
+  const propsFile = join(astroRoot, 'dist', 'props.json')
+
+  await writeFile(propsFile, JSON.stringify(propsData))
+}

package/cli/cli.ts

@@ -8,6 +8,9 @@ import { setFsRootDir } from './setFsRootDir.js'
 import { createConfigFile } from './createConfigFile.js'
 import { updatePackageFile } from './updatePackageFile.js'
 import { getConfig } from './getConfig.js'
+import { symLinkConfig } from './symLinkConfig.js'
+import { buildPropsData } from './buildPropsData.js'
+import { hasFile } from './hasFile.js'
 
 function updateContent(program: Command) {
   const { verbose } = program.opts()
@@ -23,16 +26,47 @@ function updateContent(program: Command) {
   )
 }
 
-const astroRoot = import.meta
-  .resolve('@patternfly/patternfly-doc-core')
-  .replace('dist/cli/cli.js', '')
-  .replace('file://', '')
+async function generateProps(program: Command, forceProps: boolean = false) {
+  const { verbose, props } = program.opts()
+
+  if (!props && !forceProps) {
+    return
+  }
+
+  if (verbose) {
+    console.log('Verbose mode enabled')
+  }
+
+  buildPropsData(
+    currentDir,
+    astroRoot,
+    `${currentDir}/pf-docs.config.mjs`,
+    verbose,
+  )
+}
+
+let astroRoot = ''
+
+try {
+  astroRoot = import.meta
+    .resolve('@patternfly/patternfly-doc-core')
+    .replace('dist/cli/cli.js', '')
+    .replace('file://', '')
+} catch (e: any) {
+  if (e.code === 'ERR_MODULE_NOT_FOUND') {
+    astroRoot = process.cwd()
+  } else {
+    console.error('Error resolving astroRoot', e)
+  }
+}
+
 const currentDir = process.cwd()
 
 const program = new Command()
 program.name('pf-doc-core')
 
 program.option('--verbose', 'verbose mode', false)
+program.option('--props', 'generate props data', false)
 
 program.command('setup').action(async () => {
   await Promise.all([
@@ -47,6 +81,7 @@ program.command('setup').action(async () => {
 
 program.command('init').action(async () => {
   await setFsRootDir(astroRoot, currentDir)
+  await symLinkConfig(astroRoot, currentDir)
   console.log(
     '\nInitialization complete, next update your pf-docs.config.mjs file and then run the `start` script to start the dev server',
   )
@@ -54,11 +89,17 @@ program.command('init').action(async () => {
 
 program.command('start').action(async () => {
   updateContent(program)
+  
+  // if a props file hasn't been generated yet, but the consumer has propsData, it will cause a runtime error so to
+  // prevent that we're just creating a props file regardless of what they say if one doesn't exist yet
+  const hasPropsFile = await hasFile(join(astroRoot, 'dist', 'props.json'))
+  await generateProps(program, !hasPropsFile)
   dev({ mode: 'development', root: astroRoot })
 })
 
 program.command('build').action(async () => {
   updateContent(program)
+  await generateProps(program, true)
   const config = await getConfig(`${currentDir}/pf-docs.config.mjs`)
   if (!config) {
     console.error(
@@ -68,13 +109,20 @@ program.command('build').action(async () => {
   }
 
   if (!config.outputDir) {
-    console.error("No outputDir found in config file, an output directory must be defined in your config file e.g. 'dist'")
+    console.error(
+      "No outputDir found in config file, an output directory must be defined in your config file e.g. 'dist'",
+    )
     return
   }
-    
+
   build({ root: astroRoot, outDir: join(currentDir, config.outputDir) })
 })
 
+program.command('generate-props').action(async () => {
+  await generateProps(program, true)
+  console.log('\nProps data generated')
+})
+
 program.command('serve').action(async () => {
   updateContent(program)
   preview({ root: astroRoot })

package/cli/getConfig.ts

@@ -6,9 +6,15 @@ export interface CollectionDefinition {
   name: string
 }
 
+export interface PropsGlobs {
+  include: string[]
+  exclude: string[]
+}
+
 export interface DocsConfig {
   content: CollectionDefinition[];
   outputDir: string;
+  propsGlobs: PropsGlobs[];
 }
 
 export async function getConfig(fileLocation: string): Promise<DocsConfig | undefined> {

package/cli/hasFile.ts

@@ -0,0 +1,5 @@
+import { readFile } from "fs/promises";
+
+export async function hasFile(path: string) {
+  return readFile(path).then(() => true, () => false)
+}

package/cli/symLinkConfig.ts

@@ -0,0 +1,21 @@
+/* eslint-disable no-console */
+import { symlink } from 'fs/promises'
+
+export async function symLinkConfig(
+  astroRootDir: string,
+  consumerRootDir: string,
+) {
+  const configFileName = '/pf-docs.config.mjs'
+  const docsConfigFile = consumerRootDir + configFileName
+
+  try {
+    await symlink(docsConfigFile, astroRootDir + configFileName)
+  } catch (e: any) {
+    console.error(
+      `Error creating symlink to ${docsConfigFile} in ${astroRootDir}`,
+      e,
+    )
+  } finally {
+    console.log(`Symlink to ${docsConfigFile} in ${astroRootDir} created`)
+  }
+}

package/cli/templates/pf-docs.config.mjs

@@ -16,5 +16,17 @@ export const config = {
     //   name: "react-component-docs",
     // },
   ],
-  outputDir: "./dist/docs"
-};
+  navSectionOrder: ["get-started", "design-foundations"],
+  outputDir: './dist/docs',
+  propsGlobs: [
+    // {
+    //   include: ['*/@patternfly/react-core/src/**/*.tsx'],
+    //   exclude: [
+    //     '/**/examples/**',
+    //     '/**/__mocks__/**',
+    //     '/**/__tests__/**',
+    //     '/**/*.test.tsx',
+    //   ],
+    // },
+  ],
+}

package/cli/tsDocGen.js

@@ -0,0 +1,199 @@
+import { readFile } from 'fs/promises'
+import { parse } from 'react-docgen'
+import ts from 'typescript'
+
+const annotations = [
+  {
+    regex: /@deprecated/,
+    name: 'deprecated',
+    type: 'Boolean',
+  },
+  {
+    regex: /@hide/,
+    name: 'hide',
+    type: 'Boolean',
+  },
+  {
+    regex: /@beta/,
+    name: 'beta',
+    type: 'Boolean',
+  },
+  {
+    regex: /@propType\s+(.*)/,
+    name: 'type',
+    type: 'String',
+  },
+]
+
+function addAnnotations(prop) {
+  if (prop.description) {
+    annotations.forEach(({ regex, name }) => {
+      const match = prop.description.match(regex)
+      if (match) {
+        prop.description = prop.description.replace(regex, '').trim()
+        if (name) {
+          prop[name] = match[2] || match[1] || true
+        }
+      }
+    })
+  }
+
+  return prop
+}
+
+function getComponentMetadata(filename, sourceText) {
+  let parsedComponents = null
+  try {
+    parsedComponents = parse(sourceText, { filename })
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  } catch (_err) {
+    // eslint-disable-next-line no-console
+    // console.warn(`No component found in ${filename}:`, err);
+  }
+
+  return (parsedComponents || []).filter(
+    (parsed) => parsed && parsed.displayName,
+  )
+}
+
+const getNodeText = (node, sourceText) => {
+  if (!node || !node.pos || !node.end) {
+    return undefined
+  }
+
+  return sourceText.substring(node.pos, node.end).trim()
+}
+
+const buildJsDocProps = (nodes, sourceText) =>
+  nodes?.reduce((acc, member) => {
+    const name =
+      (member.name && member.name.escapedText) ||
+      (member.parameters &&
+        `[${getNodeText(member.parameters[0], sourceText)}]`) ||
+      'Unknown'
+    acc[name] = {
+      description: member.jsDoc
+        ? member.jsDoc.map((doc) => doc.comment).join('\n')
+        : null,
+      required: member.questionToken === undefined,
+      type: {
+        raw: getNodeText(member.type, sourceText).trim(),
+      },
+    }
+    return acc
+  }, {})
+
+const getSourceFileStatements = (filename, sourceText) => {
+  const { statements } = ts.createSourceFile(
+    filename,
+    sourceText,
+    ts.ScriptTarget.Latest, // languageVersion
+  )
+
+  return statements
+}
+
+const getInterfaceMetadata = (filename, sourceText) =>
+  getSourceFileStatements(filename, sourceText).reduce(
+    (metaDataAcc, statement) => {
+      if (statement.kind === ts.SyntaxKind.InterfaceDeclaration) {
+        const _statement = statement
+        metaDataAcc.push({
+          displayName: _statement.name.escapedText,
+          description: _statement.jsDoc?.map((doc) => doc.comment).join('\n'),
+          props: buildJsDocProps(_statement.members, sourceText),
+        })
+      }
+
+      return metaDataAcc
+    },
+    [],
+  )
+
+const getTypeAliasMetadata = (filename, sourceText) =>
+  getSourceFileStatements(filename, sourceText).reduce(
+    (metaDataAcc, statement) => {
+      if (statement.kind === ts.SyntaxKind.TypeAliasDeclaration) {
+        const _statement = statement
+        const props = _statement.type.types?.reduce((propAcc, type) => {
+          if (type.members) {
+            propAcc.push(buildJsDocProps(type.members, sourceText))
+          }
+
+          return propAcc
+        }, [])
+
+        metaDataAcc.push({
+          props,
+          displayName: _statement.name.escapedText,
+          description: _statement.jsDoc?.map((doc) => doc.comment).join('\n'),
+        })
+      }
+
+      return metaDataAcc
+    },
+    [],
+  )
+
+function normalizeProp([
+  name,
+  { required, annotatedType, type, tsType, description, defaultValue },
+]) {
+  const res = {
+    name,
+    type:
+      annotatedType ||
+      (type && type.name) ||
+      (type && (type.raw || type.name)) ||
+      (tsType && (tsType.raw || tsType.name)) ||
+      'No type info',
+    description,
+  }
+  if (required) {
+    res.required = true
+  }
+  if (defaultValue && defaultValue.value) {
+    res.defaultValue = defaultValue.value
+  }
+
+  return res
+}
+
+export async function tsDocgen(file) {
+  const sourceText = await readFile(file, 'utf8')
+  const componentMeta = getComponentMetadata(file, sourceText) // Array of components with props
+  const interfaceMeta = getInterfaceMetadata(file, sourceText) // Array of interfaces with props
+  const typeAliasMeta = getTypeAliasMetadata(file, sourceText) // Array of type aliases with props
+  const propsMetaMap = [...interfaceMeta, ...typeAliasMeta].reduce(function (
+    target,
+    interfaceOrTypeAlias,
+  ) {
+    target[interfaceOrTypeAlias.displayName] = interfaceOrTypeAlias
+    return target
+  }, {})
+
+  // Go through each component and check if they have an interface or type alias with a jsDoc description
+  // If so copy it over (fix for https://github.com/patternfly/patternfly-react/issues/7612)
+  componentMeta.forEach((c) => {
+    if (c.description) {
+      return c
+    }
+
+    const propsName = `${c.displayName}Props`
+    if (propsMetaMap[propsName]?.description) {
+      c.description = propsMetaMap[propsName].description
+    }
+  })
+
+  return [...componentMeta, ...interfaceMeta, ...typeAliasMeta].map(
+    (parsed) => ({
+      name: parsed.displayName,
+      description: parsed.description || '',
+      props: Object.entries(parsed.props || {})
+        .map(normalizeProp)
+        .map(addAnnotations)
+        .filter((prop) => !prop.hide)
+        .sort((p1, p2) => p1.name.localeCompare(p2.name)),
+    }),
+  )
+}

package/dist/cli/buildPropsData.js

@@ -0,0 +1,68 @@
+/* eslint-disable no-console */
+import { glob } from 'glob';
+import { writeFile } from 'fs/promises';
+import { join } from 'path';
+import { tsDocgen } from './tsDocGen.js';
+import { getConfig } from './getConfig.js';
+function getTsDocName(name, variant) {
+    return `${name}${variant ? `-${variant}` : ''}`;
+}
+function getTsDocNameVariant(source) {
+    if (source.includes('next')) {
+        return 'next';
+    }
+    if (source.includes('deprecated')) {
+        return 'deprecated';
+    }
+}
+async function getFiles(root, globs) {
+    const files = await Promise.all(globs.map(async ({ include, exclude }) => {
+        const files = await glob(include, { cwd: root, ignore: exclude });
+        return files;
+    }));
+    return files.flat();
+}
+async function getPropsData(files, verbose) {
+    const perFilePropsData = await Promise.all(files.map(async (file) => {
+        if (verbose) {
+            console.log(`Parsing props from ${file}`);
+        }
+        const props = (await tsDocgen(file));
+        const tsDocs = props.reduce((acc, { name, description, props }) => {
+            const key = getTsDocName(name, getTsDocNameVariant(file));
+            return { ...acc, [key]: { name, description, props } };
+        }, {});
+        return tsDocs;
+    }));
+    const combinedPropsData = perFilePropsData.reduce((acc, props) => {
+        Object.keys(props).forEach((key) => {
+            const propsData = props[key];
+            if (acc[key]) {
+                acc[key].props = [...acc[key].props, ...propsData.props];
+            }
+            else {
+                acc[key] = propsData;
+            }
+        });
+        return acc;
+    }, {});
+    return combinedPropsData;
+}
+export async function buildPropsData(rootDir, astroRoot, configFile, verbose) {
+    const config = await getConfig(configFile);
+    if (!config) {
+        return;
+    }
+    const { propsGlobs } = config;
+    if (!propsGlobs) {
+        console.error('No props data found in config');
+        return;
+    }
+    const files = await getFiles(rootDir, propsGlobs);
+    if (verbose) {
+        console.log(`Found ${files.length} files to parse`);
+    }
+    const propsData = await getPropsData(files, verbose);
+    const propsFile = join(astroRoot, 'dist', 'props.json');
+    await writeFile(propsFile, JSON.stringify(propsData));
+}