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

package/scripts/typeDocGen.js

@@ -0,0 +1,209 @@
+const TypeDoc = require("typedoc");
+const path = require("path");
+
+/** Compiles variable types if a type is generic. */
+function getVariableType(typeArguments) {
+  if (!typeArguments || typeArguments.length === 0) {
+    return "";
+  }
+
+  const typeArgs = typeArguments.map((type) => getType(type));
+
+  return (
+    typeArgs.reduce((acc, type) => acc + type + ", ", "<").slice(0, -2) + ">"
+  );
+}
+
+/** compiles key/value pairs of a Type or Interface. */
+function getPropertyTypes(properties) {
+  const formattedProperties = properties.reduce((acc, property) => {
+    const { flags, name, type } = property;
+    const formattedName = flags.isOptional ? name + "?" : name;
+    return `${acc}${formattedName}: ${getType(type)}; `;
+  }, "");
+
+  return `{ ${formattedProperties} }`;
+}
+
+/** Compiles the subtypes of a tuple. */
+function getTupleTypes(tupleElements) {
+  const [firstType, secondType] = tupleElements.map((element) =>
+    getType(element)
+  );
+  return `[${firstType}, ${secondType}]`;
+}
+
+/** Compiles the different subtypes of a union or intersection. */
+function getJoinedTypes(types, joinChar) {
+  const joinedTypes = types.map((type) => getType(type));
+  return joinedTypes
+    .reduce((acc, type) => `${acc} ${joinChar} ${type}`, "")
+    .slice(2);
+}
+
+/** Return the type of a reflection.
+ * For anything that has, or can have, multiple subtypes (i.e. variable types in a generic, properties in an interface,
+ * several types in a union, callbacks, etc.) it will recursively navigate the parsed type info as needed to resolve
+ * all relevant subtypes.
+ */
+function getType(reflection) {
+  switch (reflection.type) {
+    case "intrinsic":
+    case "reference":
+      return reflection.name + getVariableType(reflection.typeArguments);
+    case "union":
+      return getJoinedTypes(reflection.types, "|");
+    case "reflection":
+      const { signatures, children } = reflection.declaration;
+      if (signatures) {
+        return getFunctionDocumentation(signatures[0]).type;
+      } else if (children) {
+        return getPropertyTypes(children);
+      } else {
+        return "Props";
+      }
+    case "array":
+      return reflection.elementType.name + "[]";
+    case "tuple":
+      return getTupleTypes(reflection.elements);
+    case "intersection":
+      return getJoinedTypes(reflection.types, "&");
+    case "literal":
+      return reflection.value;
+  }
+}
+
+/** Compiles information about the parameters of a function.
+ * Includes the name, default value, type, and whether it is optional.
+ */
+function getParamInfo(parameters = []) {
+  return parameters.map((parameter) => {
+    const { name, defaultValue, type, flags } = parameter;
+    return {
+      name,
+      default: defaultValue,
+      type: getType(type),
+      optional: flags.isOptional,
+    };
+  });
+}
+
+/** Formats call signature for a function. */
+function formatFunctionType(parameters, returnType) {
+  const annotatedParams = parameters.map((parameter) => {
+    const { name, type, optional } = parameter;
+
+    return [optional ? name + "?" : name, type];
+  });
+
+  const formattedParams = annotatedParams
+    .reduce((acc, param) => `${acc}, ${param[0]}: ${param[1]}`, "")
+    .slice(2);
+
+  return `(${formattedParams}) => ${returnType}`;
+}
+
+/** Primary entry point for gathering type information from a typedoc function reflection. */
+function getFunctionDocumentation(callSignatureReflection) {
+  const { type, parameters, comment } = callSignatureReflection;
+  const params = getParamInfo(parameters);
+
+  const returnType = type?.name || getType(type);
+
+  return {
+    params,
+    returnType,
+    type: formatFunctionType(params, returnType),
+    description: comment?.shortText,
+  };
+}
+
+/** Parses the source for a package using TypeDoc. */
+function typeDocGen(entryPoint, tsconfigLocation) {
+  const app = new TypeDoc.Application();
+  app.options.addReader(new TypeDoc.TSConfigReader());
+  app.bootstrap({
+    // typedoc options here
+    entryPointStrategy: "expand",
+    entryPoints: [entryPoint],
+    tsconfig: tsconfigLocation,
+  });
+
+  // this non-standard reflection creation allows us to ignore any type errors in a package
+  const project = app.converter.convert(app.getEntryPoints() ?? []);
+
+  // if something caused project conversion to fail log an error
+  if (project) {
+    return project;
+  } else {
+    console.error("Something went wrong during typedoc project conversion");
+    return {};
+  }
+}
+
+/** Takes package information and returns an object with all tsdoc standard format info about the functions in it.
+ * 
+ * The object has file names as keys, with values being an additional object which has the function names in that file
+ * as keys and the information about that function as the value, also in object form.
+ * Information includes the name of the file in which it's defined, the parameters, description, default values and
+ * type information.
+ *
+ * Example structure:
+ * {
+ *   "components/component.tsx": {
+ *     "boolToString": {
+ *       "description": "Converts a boolean to a string",
+ *       "params": [
+ *         {
+ *           "default": false,
+ *           "name": "booleanValue",
+ *           "optional": true,
+ *           "type": "boolean",
+ *         },
+ *       ],
+ *       "returnType": "string",
+ *       "type": "(booleanValue?: boolean) => string",
+ *     },
+ *   },
+ * }
+ */
+function getPackageFunctionDocumentation(
+  packageName,
+  pathToRoot = "dist/js/index.js",
+  srcPath = "src",
+  tsconfigPath = "tsconfig.json"
+) {
+  const packageRoot = require.resolve(packageName).replace(pathToRoot, "");
+  const entry = path.relative(process.cwd(), path.join(packageRoot, srcPath));
+  const configLocation = path.relative(
+    process.cwd(),
+    path.join(packageRoot, tsconfigPath)
+  );
+
+  const packageReflection = typeDocGen(entry, configLocation);
+
+  // 64 corresponds with functions, see all reflection kinds here: https://typedoc.org/api/enums/Models.ReflectionKind-1.html
+  const functionReflections = packageReflection.getReflectionsByKind(64);
+
+  const functionsMap = functionReflections.reduce((acc, functionReflection) => {
+    const { name, sources, signatures } = functionReflection;
+
+    const sourceFile = sources[0].fileName;
+    const shortSourceFile = sourceFile.replace(
+      `${packageName}/${srcPath}/`,
+      ""
+    );
+    const obj = getFunctionDocumentation(signatures[0]);
+
+    if (acc[shortSourceFile]) {
+      acc[shortSourceFile] = { ...acc[shortSourceFile], [name]: obj };
+    } else {
+      acc[shortSourceFile] = { [name]: obj };
+    }
+    return acc;
+  }, {});
+
+  return functionsMap;
+}
+
+module.exports = { getPackageFunctionDocumentation };

package/scripts/webpack/webpack.base.config.js

@@ -8,6 +8,7 @@ module.exports = (_env, argv) => {
   const {
     pathPrefix = '',
     mode,
+    googleAnalyticsID = false,
     algolia = {},
     hasGdprBanner = false,
     hasFooter = false,
@@ -27,7 +28,8 @@ module.exports = (_env, argv) => {
     output: {
       publicPath: isProd ? `${pathPrefix}/` : '/',
       pathinfo: false, // https://webpack.js.org/guides/build-performance/#output-without-path-info,
-      hashDigestLength: 8
+      hashDigestLength: 8,
+      clean: true, // Clean the output directory before emit.
     },
     amd: false, // We don't use any AMD modules, helps performance
     mode: isProd ? 'production' : 'development',
@@ -39,9 +41,12 @@ module.exports = (_env, argv) => {
           include: [
             path.resolve(process.cwd(), 'src'),
             path.resolve(process.cwd(), 'patternfly-docs'),
+            path.resolve(process.cwd(), 'examples'),
             path.resolve(__dirname, '../..'), // Temporarily compile theme using webpack for development
             /react-[\w-]+\/src\/.*\/examples/,
             /react-[\w-]+\\src\\.*\\examples/, // fix for Windows
+            /react-[\w-]+\/patternfly-docs\/.*\/examples/, //fixes for extensions
+            /react-[\w-]+\\patternfly-docs\\.*\\examples/,
           ].concat(includePaths.map(path => new RegExp(path))),
           exclude: [
             path.resolve(__dirname, '../../node_modules'), // Temporarily compile theme using webpack for development
@@ -82,35 +87,28 @@ module.exports = (_env, argv) => {
         },
         {
           test: /\.(gif|svg)$/,
-          use: {
-            loader: 'file-loader',
-            options: {
-              name: '[name].[contenthash].[ext]',
-              outputPath: 'images/'
-            },
+          type: 'asset/resource',
+          dependency: { not: ['url'] },
+          generator: {
+            filename: 'images/[hash][ext][query]'
           }
         },
         {
           test: /\.(pdf)$/,
-          use: {
-            loader: 'file-loader',
-            options: {
-              name: '[name].[contenthash].[ext]',
-            }
+          type: 'asset/resource',
+          dependency: { not: ['url'] },
+          generator: {
+            filename: '[hash][ext][query]'
           }
         },
         {
           test: /.(woff(2)?|ttf|eot)(\?v=\d+\.\d+\.\d+)?$/,
-          use: [
-            {
-              loader: 'file-loader',
-              options: {
-                name: '[name].[ext]',
-                outputPath: 'fonts/'
-              }
-            }
-          ]
-        }
+          type: 'asset/resource',
+          dependency: { not: ['url'] },
+          generator: {
+            filename: 'fonts/[name][ext][query]'
+          }
+        },
       ]
     },
     resolve: {
@@ -118,21 +116,29 @@ module.exports = (_env, argv) => {
       alias: {
         'client-styles': path.resolve(process.cwd(), 'patternfly-docs/patternfly-docs.css.js'),
         './routes-client': path.resolve(process.cwd(), 'patternfly-docs/patternfly-docs.routes.js'),
-        './routes-generated': path.resolve(process.cwd(), 'patternfly-docs/generated/index.js')
+        './routes-generated': path.resolve(process.cwd(), 'patternfly-docs/generated/index.js'),
+        process: "process/browser"
       },
       modules: [
         'node_modules',
         ...module.paths,
-      ]
+      ],
+      fallback: {
+        "path": require.resolve("path-browserify")
+      },
     },
     // Use this module's node_modules first (for use in Core/React workspaces)
     resolveLoader: {
       modules: module.paths,
     },
     plugins: [
+      new webpack.ProvidePlugin({
+        process: 'process/browser',
+      }),
       new webpack.DefinePlugin({
         'process.env.NODE_ENV': JSON.stringify(mode),
         'process.env.pathPrefix': JSON.stringify(isProd ? pathPrefix : ''),
+        'process.env.googleAnalyticsID': JSON.stringify(isProd ? googleAnalyticsID : ''),
         'process.env.algolia': JSON.stringify(algolia),
         'process.env.hasGdprBanner': JSON.stringify(hasGdprBanner),
         'process.env.hasFooter': JSON.stringify(hasFooter),
@@ -143,20 +149,16 @@ module.exports = (_env, argv) => {
         'process.env.sideNavItems': JSON.stringify(sideNavItems),
         'process.env.topNavItems': JSON.stringify(topNavItems),
         'process.env.prnum': JSON.stringify(process.env.CIRCLE_PR_NUMBER || process.env.PR_NUMBER || ''),
-        'process.env.prurl': JSON.stringify(process.env.CIRCLE_PULL_REQUEST || ''),
+        'process.env.prurl': JSON.stringify(process.env.CIRCLE_PULL_REQUEST || '')
       }),
       new CopyWebpackPlugin({
         patterns: [
           { from: path.join(__dirname, '../../assets'), to: 'assets' }
         ]
       }),
-      new MonacoWebpackPlugin(),
-      ...(isProd
-        ? [
-          new CleanWebpackPlugin()
-        ]
-        : []
-      )
+      new MonacoWebpackPlugin({
+        globalAPI: true,
+      })
     ],
     stats: 'minimal'
   };

package/scripts/webpack/webpack.client.config.js

@@ -5,6 +5,7 @@ const BundleAnalyzerPlugin = require('webpack-bundle-analyzer').BundleAnalyzerPl
 const MiniCssExtractPlugin = require('mini-css-extract-plugin');
 const TerserPlugin = require('terser-webpack-plugin');
 const CopyPlugin = require('copy-webpack-plugin');
+const webpack = require('webpack');
 const baseConfig = require('./webpack.base.config');
 const { getHtmlWebpackPlugins } = require('./getHtmlWebpackPlugins');
 
@@ -23,18 +24,20 @@ const reactJSRegex = /react-([^\\/]*)[\\/]dist[\\/].*\.js$/
 
 const clientConfig = async (env, argv) => {
   const isProd = argv.mode === 'production';
-
   return {
     output: {
       path: argv.output ? path.resolve(argv.output) : path.resolve('public'),
-      filename: '[name].[hash].bundle.js'
+      filename: '[name].[contenthash].bundle.js'
     },
     devServer: {
       hot: true,
       historyApiFallback: true,
+      compress: true,
       port: argv.port,
-      clientLogLevel: 'info',
-      stats: 'minimal'
+      client: {
+        logging: 'info',
+      },
+      static: {}
     },
     optimization: {
       splitChunks: {
@@ -71,10 +74,7 @@ const clientConfig = async (env, argv) => {
       },
       minimize: isProd ? true : false,
       minimizer: [
-        new TerserPlugin({
-          cache: path.join(process.cwd(), '.cache/terser'),
-          ...(process.env.CI ? { parallel: 2 } : {})
-        }),
+        new TerserPlugin(),
       ],
       runtimeChunk: 'single',
     },
@@ -113,6 +113,9 @@ const clientConfig = async (env, argv) => {
       ]
     },
     plugins: [
+      new webpack.DefinePlugin({
+        'process.env.PRERENDER': false,
+      }),
       new MiniCssExtractPlugin(!isProd ? {} : {
         filename: '[name].[contenthash].css',
         chunkFilename: '[name].[contenthash].css',

package/scripts/webpack/webpack.server.config.js

@@ -2,8 +2,11 @@ const path = require('path');
 const webpack = require('webpack');
 const { merge } = require('webpack-merge');
 const baseConfig = require('./webpack.base.config');
+const MiniCssExtractPlugin = require('mini-css-extract-plugin');
+const reactCSSRegex = /(react-[\w-]+\/dist|react-styles\/css)\/.*\.css$/;
 
-const serverConfig = () => {
+const serverConfig = async (env, argv) => {
+  const isProd = argv.mode === 'production';
   return {
     output: {
       path: path.resolve('.cache/ssr-build'), // Don't bloat `public` dir
@@ -31,7 +34,7 @@ const serverConfig = () => {
         {
           test: /(novnc-core|@novnc\/novnc)\/.*\.js/,
           use: 'null-loader'
-        }
+        },
       ]
     },
     resolve: {
@@ -41,7 +44,7 @@ const serverConfig = () => {
         // The maintainer will not allow his bundle to be required from a node context
         // https://github.com/xtermjs/xterm.js/pull/3134
         'xterm':  '@patternfly/documentation-framework/helpers/xterm',
-        'xterm-addon-fit':  '@patternfly/documentation-framework/helpers/xterm-addon-fit'
+        'xterm-addon-fit':  '@patternfly/documentation-framework/helpers/xterm-addon-fit',
       },
     },
     // Load in prerender.js instead
@@ -49,7 +52,7 @@ const serverConfig = () => {
   };
 }
 
-module.exports = (env = {}, argv) => merge(
+module.exports = async (env = {}, argv) => merge(
   baseConfig(env, argv),
-  serverConfig(env, argv)
+  await serverConfig(env, argv)
 );

package/scripts/writeScreenshots.js

@@ -11,7 +11,7 @@ sharp.cache(false);
 async function writeScreenshot({ page, data: { url, urlPrefix } }) {
   await page.goto(url);
   await page.addStyleTag({content: '*,*::before,*::after{animation-delay:-1ms !important;animation-duration:1ms !important;animation-iteration-count:1 !important;transition-duration:0s !important;transition-delay:0s !important;}'}); // disable animations/transitions so they don't interfere with screenshot tool
-  await page.waitForSelector('.pf-u-h-100');
+  await page.waitForSelector('.pf-v5-u-h-100');
   const outfile = path.join(
     screenshotBase,
     url.replace(`${urlPrefix}/`, '') + '.png'
@@ -27,7 +27,7 @@ async function writeScreenshot({ page, data: { url, urlPrefix } }) {
   await sharp(buffer).toFile(outfile);
 }
 
-async function writeScreenshots({ urlPrefix }) {
+async function writeScreenshots({ urlPrefix, allRoutes }) {
   const cluster = await Cluster.launch({
     concurrency: Cluster.CONCURRENCY_CONTEXT,
     maxConcurrency: os.cpus().length,
@@ -43,7 +43,7 @@ async function writeScreenshots({ urlPrefix }) {
 
   // Add some pages to queue
   Object.entries(fullscreenRoutes)
-    .filter(([, { isFullscreenOnly }]) => isFullscreenOnly)
+    .filter(([, { isFullscreenOnly }]) => allRoutes || isFullscreenOnly)
     .forEach(([url,]) => cluster.queue({
       url: `${urlPrefix}${url}`,
       urlPrefix

package/templates/html.ejs

@@ -15,10 +15,8 @@
     <meta name="application-name" content="PatternFly docs">
     <%= htmlWebpackPlugin.tags.headTags %>
   </head>
-  <body class="pf-m-redhat-updated-font pf-m-redhatmono-font">
-    <div id="root">
-      <%= prerendering %>
-    </div>
+  <body>
+    <div id="root"><%= prerendering %></div>
     <%= htmlWebpackPlugin.tags.bodyTags %>
     <% if (algolia) { %>
     <script