@patternfly/documentation-framework 2.0.0-alpha.3 → 2.0.0-alpha.31

package/layouts/sideNavLayout/sideNavLayout.js

@@ -3,17 +3,19 @@ import {
   Button,
   Page,
   PageSidebar,
+  PageSidebarBody,
   Brand,
   Dropdown,
-  DropdownToggle,
   DropdownItem,
   DropdownGroup,
+  DropdownList,
   Divider,
   Masthead,
   MastheadToggle,
   MastheadMain,
   MastheadContent,
   MastheadBrand,
+  MenuToggle,
   PageToggleButton,
   Toolbar,
   ToolbarGroup,
@@ -23,7 +25,6 @@ import {
   Switch,
   SearchInput
 } from '@patternfly/react-core';
-import ExternalLinkAltIcon from '@patternfly/react-icons/dist/esm/icons/external-link-alt-icon';
 import BarsIcon from '@patternfly/react-icons/dist/esm/icons/bars-icon';
 import GithubIcon from '@patternfly/react-icons/dist/esm/icons/github-icon';
 import { SideNav, TopNav, GdprBanner } from '../../components';
@@ -48,14 +49,9 @@ const HeaderTools = ({
   const [isSearchExpanded, setIsSearchExpanded] = React.useState(false);
 
   const getDropdownItem = (version, isLatest = false) => (
-    <DropdownItem
-      key={version.name}
-      component={
-        <a href={isLatest ? '/' : `/${version.name}`}>
-          {`Release ${version.name}`}
-        </a>
-      }
-    />
+    <DropdownItem itemId={version.name} key={version.name} to={isLatest ? '/' : `/${version.name}`}>
+      {`Release ${version.name}`}
+    </DropdownItem>
   );
 
   const onChange = (_evt, value) => {
@@ -82,7 +78,7 @@ const HeaderTools = ({
           </ToolbarItem>
         )}
         <ToolbarGroup
-          alignment={{ default: 'alignRight' }}
+          align={{ default: 'alignRight' }}
           spaceItems={{ default: 'spacerNone', md: 'spacerMd' }}
         >
           {hasDarkThemeSwitcher && (
@@ -117,42 +113,60 @@ const HeaderTools = ({
           {hasVersionSwitcher && (
             <ToolbarItem>
               <Dropdown
-                isFullHeight
                 onSelect={() => setDropdownOpen(!isDropdownOpen)}
+                onOpenChange={(isOpen) => setDropdownOpen(isOpen)}
                 isOpen={isDropdownOpen}
-                toggle={(
-                  <DropdownToggle
-                    onToggle={() => setDropdownOpen(!isDropdownOpen)}
+                toggle={(toggleRef) => (
+                  <MenuToggle
+                    isFullHeight
+                    ref={toggleRef}
+                    onClick={() => setDropdownOpen(!isDropdownOpen)}
+                    isExpanded={isDropdownOpen}
                   >
                     Release {initialVersion.name}
-                  </DropdownToggle>
+                  </MenuToggle>
                 )}
-                dropdownItems={[
-                  <DropdownGroup key="latest" label="Latest">
+              >
+                <DropdownGroup key="Latest" label="Latest">
+                  <DropdownList>
                     {getDropdownItem(latestVersion, true)}
-                  </DropdownGroup>,
-                  <DropdownGroup key="Previous" label="Previous releases">
+                  </DropdownList>
+                </DropdownGroup>
+                <DropdownGroup key="Previous releases" label="Previous releases">
+                  <DropdownList>
                     {Object.values(versions.Releases)
                       .filter(version => !version.hidden && !version.latest)
                       .slice(0,3)
                       .map(version => getDropdownItem(version))}
-                  </DropdownGroup>,
-                  <Divider key="divider" className="ws-switcher-divider"/>,
-                  <DropdownItem
-                    key="PatternFly 3"
-                    className="ws-patternfly-3"
-                    target="_blank"
-                    href="https://pf3.patternfly.org/"
-                  >
-                    PatternFly 3
-                    <ExternalLinkAltIcon />
-                  </DropdownItem>
-                ]}
-              />
+                  </DropdownList>
+                </DropdownGroup>
+                <Divider key="divider" className="ws-switcher-divider"/>
+                <DropdownGroup key="Previous versions" label="Previous versions">
+                  <DropdownList>
+                    <DropdownItem
+                      key="PatternFly 4"
+                      className="ws-patternfly-3"
+                      isExternalLink
+                      to="http://v4-archive.patternfly.org/v4/"
+                      itemId="patternfly-4"
+                    >
+                      PatternFly 4
+                    </DropdownItem>
+                    <DropdownItem
+                      key="PatternFly 3"
+                      className="ws-patternfly-3"
+                      isExternalLink
+                      to="https://pf3.patternfly.org/"
+                      itemId="patternfly-3"
+                    >
+                      PatternFly 3
+                    </DropdownItem>
+                  </DropdownList>
+                </DropdownGroup>
+              </Dropdown>
             </ToolbarItem>
           )}
-        </ToolbarGroup>
-      </ToolbarContent>
+        </ToolbarGroup></ToolbarContent>
     </Toolbar>
   );
 }
@@ -205,8 +219,11 @@ export const SideNavLayout = ({ children, groupedRoutes, navOpen: navOpenProp })
     <PageSidebar
       className="ws-page-sidebar"
       theme="light"
-      nav={<SideNav navItems={sideNavItems} groupedRoutes={groupedRoutes} />}
-    />
+    >
+      <PageSidebarBody>
+        <SideNav navItems={sideNavItems} groupedRoutes={groupedRoutes} />
+      </PageSidebarBody>
+    </PageSidebar>
   );
 
   const Header = (

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@patternfly/documentation-framework",
   "description": "A framework to build documentation for PatternFly.",
-  "version": "2.0.0-alpha.3",
+  "version": "2.0.0-alpha.31",
   "author": "Red Hat",
   "license": "MIT",
   "private": false,
@@ -22,19 +22,19 @@
     "@babel/preset-env": "7.18.2",
     "@mdx-js/util": "1.6.16",
     "@patternfly/ast-helpers": "^0.4.57",
-    "@reach/router": "1.3.4",
+    "@reach/router": "npm:@gatsbyjs/reach-router@1.3.9",
     "autoprefixer": "9.8.6",
-    "babel-loader": "8.2.5",
+    "babel-loader": "9.1.2",
     "camelcase-css": "2.0.1",
     "chokidar": "3.5.3",
-    "clean-webpack-plugin": "3.0.0",
+    "clean-webpack-plugin": "4.0.0",
     "codesandbox": "2.2.0",
     "commander": "4.1.1",
-    "copy-webpack-plugin": "6.1.0",
-    "css-loader": "4.3.0",
+    "copy-webpack-plugin": "11.0.0",
+    "css-loader": "6.7.3",
     "detab": "2.0.3",
     "express": "4.18.1",
-    "file-loader": "6.1.0",
+    "file-loader": "6.2.0",
     "file-saver": "1.3.8",
     "fs-extra": "9.0.1",
     "glob": "8.0.3",
@@ -42,51 +42,54 @@
     "hast-to-hyperscript": "9.0.0",
     "hast-util-to-text": "2.0.0",
     "html-formatter": "0.1.9",
-    "html-webpack-plugin": "4.4.1",
+    "html-webpack-plugin": "5.5.0",
     "js-yaml": "3.14.0",
     "mdast-util-to-hast": "9.1.1",
     "mdurl": "1.0.1",
-    "mini-css-extract-plugin": "1.3.9",
-    "monaco-editor": "0.21.3",
-    "monaco-editor-webpack-plugin": "2.1.0",
-    "null-loader": "4.0.0",
+    "mini-css-extract-plugin": "2.7.5",
+    "monaco-editor": "0.34.1",
+    "monaco-editor-webpack-plugin": "7.0.1",
+    "null-loader": "4.0.1",
     "parse-entities": "2.0.0",
+    "path-browserify": "1.0.1",
     "postcss": "7.0.32",
-    "postcss-loader": "4.2.0",
+    "postcss-loader": "7.1.0",
+    "process": "^0.11.10",
     "puppeteer": "14.3.0",
     "puppeteer-cluster": "0.23.0",
     "react-docgen": "5.3.1",
-    "react-monaco-editor": "0.48.0",
-    "react-ssr-prepass": "1.2.1",
+    "react-monaco-editor": "^0.51.0",
+    "react-ssr-prepass": "1.5.0",
     "remark-footnotes": "1.0.0",
     "remark-frontmatter": "2.0.0",
     "remark-mdx": "2.0.0-next.8",
     "remark-mdxjs": "2.0.0-next.8",
     "remark-parse": "8.0.3",
     "remark-squeeze-paragraphs": "4.0.0",
-    "responsive-loader": "2.1.1",
+    "responsive-loader": "3.1.2",
     "sharp": "0.30.6",
     "style-to-object": "0.3.0",
     "to-vfile": "6.1.0",
+    "typedoc": "0.22.X",
     "typescript": "4.3.5",
     "unified": "9.1.0",
     "unist-util-remove": "2.0.0",
     "unist-util-visit": "2.0.3",
     "url-loader": "4.1.0",
     "vfile-reporter": "6.0.1",
-    "webpack": "4.44.1",
-    "webpack-bundle-analyzer": "3.8.0",
-    "webpack-cli": "3.3.12",
-    "webpack-dev-server": "3.11.0",
+    "webpack": "5.76.3",
+    "webpack-bundle-analyzer": "4.8.0",
+    "webpack-cli": "5.0.1",
+    "webpack-dev-server": "4.13.1",
     "webpack-merge": "5.8.0"
   },
   "peerDependencies": {
-    "@patternfly/patternfly": "^5.0.0-alpha.13",
-    "@patternfly/react-code-editor": "^5.0.0-alpha.7",
-    "@patternfly/react-core": "^5.0.0-alpha.7",
-    "@patternfly/react-table": "^5.0.0-alpha.7",
+    "@patternfly/patternfly": "^5.0.0-alpha.37",
+    "@patternfly/react-code-editor": "^5.0.0-alpha.84",
+    "@patternfly/react-core": "^5.0.0-alpha.83",
+    "@patternfly/react-table": "^5.0.0-alpha.85",
     "react": "^17.0.0 || ^18.0.0",
     "react-dom": "^17.0.0 || ^18.0.0"
   },
-  "gitHead": "c1a9c0434ef5569eb7772d9221d4f9c5a506df59"
+  "gitHead": "46db0c1c334e7304290b8cc024bfdd40c887013b"
 }

package/pages/404/index.js

@@ -6,7 +6,7 @@ import {
   CardTitle,
   CardBody,
   CardFooter,
-  CardHeaderMain,
+  CardHeader,
   EmptyState,
   EmptyStateBody,
   EmptyStateIcon,
@@ -36,9 +36,9 @@ const Card404 = ({
 }) => (
   <GridItem xl={3} md={6} xs={12}>
     <Card style={{ height: '340px' }}>
-      <CardHeaderMain className="ws-404-card-header">
+      <CardHeader className="ws-404-card-header">
         <img src={img} alt={alt} width="64px" />
-      </CardHeaderMain>
+      </CardHeader>
       <CardTitle>
         {title}
       </CardTitle>

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;
@@ -73,7 +87,6 @@ const sourceOrder = {
   'design-guidelines': 99,
   'accessibility': 100
 };
-const defaultOrder = 50;
 
 const sortSources = ({ source: s1 }, { source: s2 }) => {
   const s1Index = sourceOrder[s1] || defaultOrder;
@@ -108,7 +121,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}`)
@@ -85,6 +105,7 @@ function toReactComponent(mdFilePath, source, buildMode) {
         section: frontmatter.section || '',
         subsection: frontmatter.subsection || '',
         source,
+        tabName: frontmatter.tabName || null,
         slug,
         sourceLink: frontmatter.sourceLink || `https://github.com/patternfly/${
           sourceRepo}/blob/main/${
@@ -106,6 +127,9 @@ 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;
       }
@@ -117,15 +141,15 @@ function toReactComponent(mdFilePath, source, buildMode) {
           ? 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 +290,19 @@ 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.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 +341,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 }) => {