@patternfly/documentation-framework 2.0.0-alpha.6 → 2.0.0-alpha.60

package/routes.js

@@ -9,6 +9,8 @@ const routes = {
   ...generatedRoutes
 };
 
+const defaultOrder = 50;
+
 for (let route in routes) {
   const pageData = routes[route];
   if (pageData.SyncComponent) {
@@ -28,7 +30,7 @@ const isNull = o => o === null || o === undefined;
 const groupedRoutes = Object.entries(routes)
   .filter(([_slug, { id, section }]) => !isNull(id) && !isNull(section))
   .reduce((accum, [slug, pageData]) => {
-    const { section, subsection = null, id, title, source, katacodaLayout, hideNavItem, relPath } = pageData;
+    const { section, subsection = null, id, title, source, hideNavItem, relPath, sortValue = null, subsectionSortValue = null } = pageData;
     pageData.slug = slug;
     // add section to groupedRoutes obj if not yet created
     accum[section] = accum[section] || {};
@@ -40,9 +42,10 @@ const groupedRoutes = Object.entries(routes)
       title,
       slug: makeSlug(source, section, id, true, subsection),
       sources: [],
-      katacodaLayout,
       hideNavItem,
-      relPath
+      relPath,
+      ...(sortValue && { sortValue }),
+      ...(subsectionSortValue && { subsectionSortValue })
     }
     // add page to groupedRoutes obj section or subsection
     if (subsection) {
@@ -52,10 +55,21 @@ const groupedRoutes = Object.entries(routes)
       // add page to subsection
       accum[section][subsection][id] = accum[section][subsection][id] || data;
       accum[section][subsection][id].sources.push(pageData);
+      // nav item ordering
+      if (sortValue) {
+        accum[section][subsection].sortValue = sortValue;
+      }
+      if (subsectionSortValue) {
+        accum[section][subsection].subsectionSortValue = subsectionSortValue;
+      }
     } else {
       // add page to section
       accum[section][id] = accum[section][id] || data;
       accum[section][id].sources.push(pageData);
+      // nav item ordering
+      if (sortValue) {
+        accum[section][id].sortValue = sortValue;
+      }
     }
 
     return accum;
@@ -64,16 +78,13 @@ const groupedRoutes = Object.entries(routes)
 const sourceOrder = {
   react: 1,
   'react-next': 1.1,
-  'react-composable': 1.2,
-  'react-deprecated': 1.3,
-  'react-legacy': 1.4,
   'react-demos': 2,
+  'react-deprecated': 2.1,
   html: 3,
   'html-demos': 4,
   'design-guidelines': 99,
   'accessibility': 100
 };
-const defaultOrder = 50;
 
 const sortSources = ({ source: s1 }, { source: s2 }) => {
   const s1Index = sourceOrder[s1] || defaultOrder;
@@ -108,7 +119,8 @@ Object.entries(groupedRoutes)
       // Loop through each page in expandable subsection
       if (pageData.isSubsection) {
         Object.entries(pageData).map(([section, ids]) => {
-          if (section !== 'isSubsection') {
+          // only push nested page objects
+          if (ids && ids?.id) {
             pageDataArr.push(ids);
           }
         })

package/scripts/cli/build.js

@@ -50,6 +50,11 @@ async function execFile(file, args) {
     const child_execArgv = [
       '--max-old-space-size=4096'
     ];
+
+    if (args.legacySSL) {
+      child_execArgv.push('--openssl-legacy-provider')
+    }
+
     const child = fork(path.join(__dirname, file), child_argv, { execArgv: child_execArgv });
     function errorHandler(err) {
       console.error(err);
@@ -78,6 +83,7 @@ async function build(cmd, options) {
   const config = getConfig(options);
   config.analyze = options.analyze;
   config.output = options.output;
+  config.legacySSL = options.legacySSL
 
   // These get passed to `fork`ed builds
   process.env.pathPrefix = config.pathPrefix;

package/scripts/cli/cli.js

@@ -26,6 +26,7 @@ program
   .command('build <server|client|all>')
   .option('-a, --analyze', 'use webpack-bundle-analyzer', false)
   .option('-o, --output <folder>', 'output folder', 'public')
+  .option('--legacySSL', 'use legacy version of openssl, needed to support Node 18 until we upgrade webpack to v5', false)
   .description('generates source files and runs webpack')
   .action((cmd, options) => {
     const { build } = require('./build');
@@ -44,6 +45,7 @@ program
 program
   .command('screenshots')
   .option('-u, --urlPrefix <prefix>', 'where fullscreen pages are hosted', 'http://localhost:5000/v4')
+  .option('-a, --allRoutes', 'true if screenshots of all examples - not just full screen', false)
   .description('updates screenshots for generated components')
   .action(options => {
     const { writeScreenshots } = require('../writeScreenshots');

package/scripts/cli/generate.js

@@ -1,5 +1,5 @@
 const path = require('path');
-const { sourceMD, sourceProps, writeIndex } = require('../md/parseMD');
+const { sourceMD, sourceProps, sourceFunctionDocs, writeIndex } = require('../md/parseMD');
 
 function getSource(options) {
   return require(path.join(process.cwd(), options.parent.source));
@@ -9,7 +9,7 @@ function generate(options) {
   const start = new Date();
   console.log('write source files to patternfly-docs/generated');
   const sourceMDWithOptions = (glob, source, ignore) => sourceMD(glob, source, ignore, options._name);
-  getSource(options)(sourceMDWithOptions, sourceProps);
+  getSource(options)(sourceMDWithOptions, sourceProps, sourceFunctionDocs);
   const exitCode = writeIndex();
   if (exitCode !== 0) {
     process.exit(exitCode);

package/scripts/cli/start.js

@@ -6,17 +6,15 @@ const { getConfig } = require('./helpers');
 const { watchMD } = require('../md/parseMD');
 
 function startWebpackDevServer(webpackConfig) {
-  webpackConfig.devServer.filename = webpackConfig.output.filename;
-  webpackConfig.devServer.publicPath = webpackConfig.output.publicPath;
+  webpackConfig.devServer.static = false;
   const { port } = webpackConfig.devServer;
   const compiler = webpack(webpackConfig);
-  const server = new WebpackDevServer(compiler, webpackConfig.devServer);
+  const server = new WebpackDevServer(webpackConfig.devServer, compiler);
 
-  server.listen(port, 'localhost', err => {
-    if (err) {
-      console.log(err);
-    }
-  });
+  (async () => {
+    await server.start();
+    console.log(`Dev server is listening on port ${port}`);
+  })();
 }
 
 async function start(options) {

package/scripts/md/parseMD.js

@@ -12,10 +12,12 @@ const { typecheck } = require('./typecheck');
 const { makeSlug } = require('../../helpers/slugger');
 const { liveCodeTypes } = require('../../helpers/liveCodeTypes');
 const { tsDocgen } = require('../tsDocgen');
+const { getPackageFunctionDocumentation } = require("../typeDocGen");
 
 let exitCode = 0;
 const outputBase = path.join(process.cwd(), `patternfly-docs/generated`);
 const tsDocs = {};
+let functionDocs = {};
 const routes = {};
 const globs = {
   props: [],
@@ -75,6 +77,24 @@ function toReactComponent(mdFilePath, source, buildMode) {
         return acc;
       }, []);
 
+      const functionDocumentation = Object.keys(
+        frontmatter.functions || {}
+      ).reduce((acc, fileName) => {
+        const functionNames = frontmatter.functions[fileName];
+
+        functionNames.forEach((functionName) => {
+          if (functionDocs[fileName] && functionDocs[fileName][functionName]) {
+            const functionDescriptionWithName = { functionName, ...functionDocs[fileName][functionName]}
+            acc.push(functionDescriptionWithName);
+          } else {
+            file.message(
+              `function documentation for ${functionName} is missing from function docs generation`
+            );
+          }
+        });
+        return acc;
+      }, []);
+
       const normalizedPath = relPath
         .replace('node_modules/@patternfly/patternfly/docs', 'src/patternfly')
         .replace(/node_modules\/@patternfly\/react-([\w-])/, (_, match) => `packages/react-${match}`)
@@ -84,7 +104,12 @@ function toReactComponent(mdFilePath, source, buildMode) {
         id: frontmatter.id,
         section: frontmatter.section || '',
         subsection: frontmatter.subsection || '',
+        deprecated: frontmatter.deprecated || false,
+        beta: frontmatter.beta || false,
+        demo: frontmatter.demo || false,
+        newImplementationLink: frontmatter.newImplementationLink || false,
         source,
+        tabName: frontmatter.tabName || null,
         slug,
         sourceLink: frontmatter.sourceLink || `https://github.com/patternfly/${
           sourceRepo}/blob/main/${
@@ -106,26 +131,26 @@ function toReactComponent(mdFilePath, source, buildMode) {
       if (propComponents.length > 0) {
         pageData.propComponents = propComponents;
       }
+      if (functionDocumentation.length > 0) {
+        pageData.functionDocumentation = functionDocumentation;
+      }
       if (frontmatter.optIn) {
         pageData.optIn = frontmatter.optIn;
       }
-      if (frontmatter.beta) {
-        pageData.beta = frontmatter.beta;
-      }
       if (frontmatter.cssPrefix) {
         pageData.cssPrefix = Array.isArray(frontmatter.cssPrefix)
           ? frontmatter.cssPrefix
           : [frontmatter.cssPrefix];
       }
-      if (frontmatter.katacodaBroken) {
-        pageData.katacodaBroken = frontmatter.katacodaBroken;
-      }
-      if (frontmatter.katacodaLayout) {
-        pageData.katacodaLayout = frontmatter.katacodaLayout;
-      }
       if (frontmatter.hideNavItem) {
         pageData.hideNavItem = frontmatter.hideNavItem;
       }
+      if (frontmatter.sortValue) {
+        pageData.sortValue = frontmatter.sortValue;
+      }
+      if (frontmatter.subsectionSortValue) {
+        pageData.subsectionSortValue = frontmatter.subsectionSortValue;
+      }
     })
     // Delete HTML comments
     .use(require('./remove-comments'))
@@ -266,12 +291,21 @@ function sourceMDFile(file, source, buildMode) {
       section: pageData.section,
       subsection: pageData.subsection,
       source: pageData.source,
-      ...(pageData.katacodaLayout && { katacodaLayout: pageData.katacodaLayout }),
-      ...(pageData.hideNavItem && { hideNavItem: pageData.hideNavItem })
+      tabName: pageData.tabName,
+      ...(pageData.hideNavItem && { hideNavItem: pageData.hideNavItem }),
+      ...(pageData.beta && { beta: pageData.beta }),
+      ...(pageData.deprecated && { deprecated: pageData.deprecated }),
+      ...(pageData.demo && { demo: pageData.demo }),
+      ...(pageData.sortValue && { sortValue: pageData.sortValue }),
+      ...(pageData.subsectionSortValue && { subsectionSortValue: pageData.subsectionSortValue })
     };
   }
 }
 
+function sourceFunctionDocs(packageName) {
+  functionDocs = getPackageFunctionDocumentation(packageName);
+}
+
 function writeIndex() {
   const stringifyRoute = ([route, pageData]) => `'${route}': {\n    ${Object.entries(pageData)
     .map(([key, val]) => `${key}: ${JSON.stringify(val)}`)
@@ -310,6 +344,7 @@ module.exports = {
     globs.md.push({ glob, source, ignore });
     sync(glob, { ignore }).forEach(file => sourceMDFile(file, source, buildMode));
   },
+  sourceFunctionDocs,
   writeIndex,
   watchMD() {
     globs.props.forEach(({ glob, ignore }) => {

package/scripts/md/styled-tags.js

@@ -24,22 +24,23 @@ function styledTags() {
         node.properties.className = node.properties.className || '';
         node.properties.className += node.properties.className ? ' ' : '';
         node.properties.className += `ws-${node.tagName}`;
-        // Match pf-c-table implementation
+        // Match pf-v5-c-table implementation
         // https://pf4.patternfly.org/components/table/html/basic-table/
         if (node.tagName === 'table') {
-          node.properties.className += ' pf-c-table pf-m-grid-lg pf-m-compact';
+          node.properties.className += ' pf-v5-c-table pf-m-grid-lg pf-m-compact';
           node.properties.role = 'grid';
           let columnHeaders = [];
           for (let child of node.children) {
             if (child.tagName === 'thead') {
+              child.properties.className = 'pf-v5-c-table__thead';
               // Find column headers
               const tr = child.children.find(child => child.tagName === 'tr');
               tr.properties.role = 'row';
+              tr.properties.className = 'pf-v5-c-table__tr';
               tr.children
                 .filter(child => child.tagName === 'th')
                 .forEach(th => {
-                  th.properties.className = th.properties.className || '';
-                  th.properties.className += ' pf-m-wrap';
+                  th.properties.className = `${th.properties.className} pf-v5-c-table__th pf-m-wrap`;
                   th.properties.role = 'columnheader';
                   th.properties.scope = 'col';
                   let colName = '';
@@ -56,14 +57,17 @@ function styledTags() {
             }
             else if (child.tagName === 'tbody') {
               child.properties.role = 'rowgroup';
+              child.properties.className = 'pf-v5-c-table__tbody';
               child.children
                 .filter(tr => tr.tagName === 'tr')
                 .forEach(tr => {
                   tr.properties.role = 'row';
+                  tr.properties.className = 'pf-v5-c-table__tr';
                   tr.children
                     .filter(td => td.tagName === 'td')
                     .forEach((td, i) => {
                       td.properties.role = 'cell';
+                      td.properties.className = 'pf-v5-c-table__td';
                       if (columnHeaders[i]) {
                         td.properties['data-label'] = columnHeaders[i];
                       }

package/scripts/tsDocgen.js

@@ -1,28 +1,28 @@
-const fs = require('fs');
-const reactDocgen = require('react-docgen');
-const ts = require('typescript');
+const fs = require("fs");
+const reactDocgen = require("react-docgen");
+const ts = require("typescript");
 
 const annotations = [
   {
     regex: /@deprecated/,
-    name: 'deprecated',
-    type: 'Boolean'
+    name: "deprecated",
+    type: "Boolean",
   },
   {
     regex: /@hide/,
-    name: 'hide',
-    type: 'Boolean'
+    name: "hide",
+    type: "Boolean",
   },
   {
     regex: /@beta/,
-    name: 'beta',
-    type: 'Boolean'
+    name: "beta",
+    type: "Boolean",
   },
   {
     regex: /@propType\s+(.*)/,
-    name: 'type',
-    type: 'String'
-  }
+    name: "type",
+    type: "String",
+  },
 ];
 
 function addAnnotations(prop) {
@@ -30,12 +30,12 @@ function addAnnotations(prop) {
     annotations.forEach(({ regex, name }) => {
       const match = prop.description.match(regex);
       if (match) {
-        prop.description = prop.description.replace(regex, '').trim();
+        prop.description = prop.description.replace(regex, "").trim();
         if (name) {
           prop[name] = match[2] || match[1] || true;
         }
       }
-    })
+    });
   }
 
   return prop;
@@ -55,74 +55,101 @@ function getComponentMetadata(filename, sourceText) {
     // console.warn(`No component found in ${filename}:`, err);
   }
 
-  return (parsedComponents || []).filter(parsed => parsed && parsed.displayName);
+  return (parsedComponents || []).filter(
+    (parsed) => parsed && parsed.displayName
+  );
 }
 
-function getInterfaceMetadata(filename, sourceText) {
-  const ast = ts.createSourceFile(
+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
   );
-  
-  function getText(node) {
-    if (!node || !node.pos || !node.end) {
-      return undefined;
-    }
-    return sourceText.substring(node.pos, node.end).trim();
-  }
 
-  const interfaces = [];
-  
-  ast.statements
-    .filter(statement => statement.kind === ts.SyntaxKind.InterfaceDeclaration)
-    .forEach(statement => {
-      const props = statement.members.reduce((acc, member) => {
-        const name = (member.name && member.name.escapedText)
-          || (member.parameters && `[${getText(member.parameters[0])}]`)
-          || 'Unknown';
-        acc[name] = {
-          description: member.jsDoc
-            ? member.jsDoc.map(doc => doc.comment).join('\n')
-            : null,
-          required: member.questionToken === undefined,
-          type: {
-            raw: getText(member.type).trim()
+  return statements;
+};
+
+const getInterfaceMetadata = (filename, sourceText) =>
+  getSourceFileStatements(filename, sourceText).reduce(
+    (metaDataAcc, statement) => {
+      if (statement.kind === ts.SyntaxKind.InterfaceDeclaration) {
+        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 props = statement.type.types?.reduce((propAcc, type) => {
+          if (type.members) {
+            propAcc.push(buildJsDocProps(type.members, sourceText));
           }
-        };
-        return acc;
-      }, {});
-
-      interfaces.push({
-        displayName: statement.name.escapedText,
-        description: statement.jsDoc
-            ? statement.jsDoc.map(doc => doc.comment).join('\n')
-            : null,
-        props
-      });
-    });
-  return interfaces;
-}
+
+          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
-  }
+  { 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
+    type:
+      annotatedType ||
+      (type && type.name) ||
+      (type && (type.raw || type.name)) ||
+      (tsType && (tsType.raw || tsType.name)) ||
+      "No type info",
+    description,
   };
   if (required) {
     res.required = true;
@@ -134,45 +161,46 @@ function normalizeProp([
   return res;
 }
 
-function getDescription(parsed, ) {
-
-}
-
 function tsDocgen(file) {
-  const sourceText = fs.readFileSync(file, 'utf8');
+  const sourceText = fs.readFileSync(file, "utf8");
   const componentMeta = getComponentMetadata(file, sourceText); // Array of components with props
   const interfaceMeta = getInterfaceMetadata(file, sourceText); // Array of interfaces with props
-  const interfaceMetaMap = interfaceMeta.reduce(function(target, interface) {
-    target[interface.displayName] = interface;
+  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 with a jsDoc description
+  // 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 => {
+  componentMeta.forEach((c) => {
     if (c.description) {
       return c;
     }
-    const interface = `${c.displayName}Props`;
-    if (interfaceMetaMap[interface] && interfaceMetaMap[interface].description) {
-      c.description = interfaceMetaMap[interface].description;
+
+    const propsName = `${c.displayName}Props`;
+    if (propsMetaMap[propsName]?.description) {
+      c.description = propsMetaMap[propsName].description;
     }
-  })
+  });
 
-  return componentMeta
-    .concat(interfaceMeta)
-    .map(parsed => ({
+  return [...componentMeta, ...interfaceMeta, ...typeAliasMeta].map(
+    (parsed) => ({
       name: parsed.displayName,
-      description: parsed.description || '',
+      description: parsed.description || "",
       props: Object.entries(parsed.props || {})
         .map(normalizeProp)
         .map(addAnnotations)
-        .filter(prop => !prop.hide)
-        .sort((p1, p2) => p1.name.localeCompare(p2.name))
-    }));
+        .filter((prop) => !prop.hide)
+        .sort((p1, p2) => p1.name.localeCompare(p2.name)),
+    })
+  );
 }
 
 module.exports = {
-  tsDocgen
+  tsDocgen,
 };
-