@patternfly/documentation-framework 1.0.0

package/pages/red-hat-font.md

@@ -0,0 +1,40 @@
+---
+id: Red Hat font
+section: developer-resources
+---
+
+PR - [https://github.com/patternfly/patternfly/pull/4476](https://github.com/patternfly/patternfly/pull/4476)
+
+Available in [v4.161.0](https://github.com/patternfly/patternfly/releases/tag/prerelease-v4.161.0)
+
+## Overview
+
+PatternFly has created opt-ins for `v4.0.2` of the [RedHatFont](https://github.com/RedHatOfficial/RedHatFont/). This is an update from `v2.x`. There are many new features in this update, including:
+
+- Variable fonts
+- New weights in Red Hat Display and Red Hat Text
+- Tabular figures (monospaced numbers) in Red Hat Display and Red Hat Text
+- Red Hat Mono typeface
+- Dropping support for IE11 (dropped the `.woff` format)
+
+### Available Opt-ins
+
+#### `.pf-m-redhat-updated-font`
+
+Updates the Red Hat Text and Red Hat Display font stacks to `v4.0.2`. This should be a safe, seamless opt-in, with small improvements to glyph shape, kerning, metadata across the entire family of fonts. Potential concerns may be that this will remove support for IE11 by removing the `.woff` format support, and small layout shifts as result of the small improvements.
+
+#### `.pf-m-redhatmono-font`
+
+Updates the monospaced font stack to use the Red Hat Mono font. This opt-in can be combined with `.pf-m-redhat-updated-font`.
+
+#### `.pf-m-redhatVF-font`
+
+Updates the Red Hat Text, Red Hat Display, and Red Hat Mono font stacks to use the variable font files.
+
+#### `.pf-m-tabular-nums`
+
+This is a global class that can be applied to any element to enable monospaced numbers on that element and its children.
+
+### Using opt-in classes
+
+To opt-in to any of the new fonts (`.pf-m-redhat-updated-font`, `.pf-m-redhatmono-font`, and `.pf-m-redhatVF-font`), add the opt-in class to the `<body>` tag of your application. To opt-in to monospaced numbers globally across your application, apply `.pf-m-tabular-nums` to any element that wraps your entire application (eg, `<body>`, `<div id="root">`, `<div class="pf-c-page">`, etc). To opt-in to monospaced numbers on a particular element and its children, add the class to that element itself.

package/routes-client.js

@@ -0,0 +1 @@
+module.exports = require(require('path').join(process.cwd(), 'patternfly-docs/patternfly-docs.routes'));

package/routes-generated.js

@@ -0,0 +1 @@
+module.exports = require(require('path').join(process.cwd(), 'patternfly-docs/generated'));

package/routes.js

@@ -0,0 +1,155 @@
+// This module is shared between NodeJS and babelled ES5
+const { makeSlug, slugger } = require('@patternfly/documentation-framework/helpers/slugger');
+const { asyncComponentFactory } = require('@patternfly/documentation-framework/helpers/asyncComponentFactory');
+const clientRoutes = require('./routes-client'); // Webpack replaces this import: patternfly-docs.routes.js
+const generatedRoutes = require('./routes-generated'); // Webpack replaces this import: patternfly-docs/generated/index.js
+
+const routes = {
+  ...clientRoutes,
+  ...generatedRoutes
+};
+
+for (let route in routes) {
+  const pageData = routes[route];
+  if (pageData.SyncComponent) {
+    pageData.Component = pageData.SyncComponent;
+  }
+  else if (pageData.Component) {
+    pageData.Component = asyncComponentFactory(route, pageData);
+  }
+}
+
+// Save a copy of all routes for path matching on first load
+const allRoutes = Object.assign({}, routes);
+
+// Group routes by section, id
+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, id, title, source, katacodaLayout, hideNavItem } = pageData;
+    accum[section] = accum[section] || {};
+    accum[section][id] = accum[section][id] || {
+      id,
+      section,
+      title,
+      slug: makeSlug(source, section, id, true),
+      sources: [],
+      katacodaLayout,
+      hideNavItem
+    };
+
+    pageData.slug = slug;
+    accum[section][id].sources.push(pageData);
+
+    return accum;
+  }, {});
+
+const sourceOrder = {
+  react: 1,
+  'react-composable': 1.1,
+  'react-legacy': 1.2,
+  'react-demos': 2,
+  html: 3,
+  'html-demos': 4,
+  'design-guidelines': 99,
+  'accessibility': 100
+};
+const defaultOrder = 50;
+
+const sortSources = ({ source: s1 }, { source: s2 }) => {
+  const s1Index = sourceOrder[s1] || defaultOrder;
+  const s2Index = sourceOrder[s2] || defaultOrder;
+  if (s1Index === defaultOrder && s2Index === defaultOrder) {
+    return s1.localeCompare(s2);
+  }
+
+  return s1Index > s2Index ? 1 : -1;
+}
+
+const getDefaultDesignGuidelines = ({ id, section, slug, title }) => {
+  const Component = () => require('@patternfly/documentation-framework/templates/design-guidelines').DesignGuidelineTemplate
+  const pageData = {
+    id,
+    section,
+    slug: `${slug}/design-guidelines`,
+    source: 'design-guidelines',
+    title,
+    Component
+  };
+
+  Component.getPageData = () => pageData;
+
+  return pageData;
+}
+
+Object.entries(groupedRoutes)
+  .forEach(([_section, ids]) => {
+    Object.values(ids).forEach(pageData => {
+      const { slug, section } = pageData;
+      // Remove source routes for `app.js`
+      pageData.sources.forEach(({ slug }) => {
+        delete routes[slug];
+      });
+      // Add design guidelines if doesn't exist
+      if (
+        ['components', 'charts', 'layouts', 'demos'].includes(section) &&
+        !pageData.sources.map(({ source }) => source).includes('design-guidelines') &&
+        process.env.hasDesignGuidelines
+      ) {
+        pageData.sources.push(getDefaultDesignGuidelines(pageData));
+      }
+      // Sort sources for tabs
+      pageData.sources = pageData.sources.sort(sortSources);
+      // Add grouped route
+      routes[slug] = pageData;
+    })
+  });
+
+function getAsyncComponent(url) {
+  if (!url && typeof window !== 'undefined') {
+    url = window.location.pathname.replace(/\/$/, '') || '/';
+  }
+  // Normalize path for matching
+  url = url.replace(process.env.pathPrefix, '');
+  let res;
+
+  if (allRoutes[url]) {
+    res = allRoutes[url].Component;
+  }
+  else if (routes[url]) {
+    res = routes[url].sources[0].Component;
+  }
+
+  if (res && res.preload) {
+    return res;
+  }
+
+  return null;
+}
+
+const fullscreenRoutes = Object.entries(allRoutes)
+  .filter(([, { examples, fullscreenExamples }]) => examples || fullscreenExamples)
+  .reduce((acc, val) => {
+    const [path, { Component, examples = [], fullscreenExamples = [] }] = val;
+    examples
+      .concat(fullscreenExamples)
+      .forEach(title => {
+        const slug = `${path}/${slugger(title)}`;
+        acc[slug] = {
+          title,
+          Component,
+          isFullscreen: true,
+          isFullscreenOnly: fullscreenExamples.includes(title)
+        };
+      });
+    return acc;
+  }, {});
+
+module.exports = {
+  routes,
+  groupedRoutes,
+  fullscreenRoutes,
+  getAsyncComponent
+};

package/scripts/cli/build.js

@@ -0,0 +1,95 @@
+const path = require('path');
+const { fork } = require('child_process');
+const webpack = require('webpack');
+const { generate } = require('./generate');
+const { getConfig } = require('./helpers');
+
+async function buildWebpack(webpackConfig) {
+  let compiler;
+  try {
+    compiler = webpack(webpackConfig);
+  } catch (err) {
+    if (err.name === "WebpackOptionsValidationError") {
+      console.error(err.message);
+      process.exit(1);
+    }
+
+    throw err;
+  }
+
+  return new Promise((res, rej) => 
+    compiler.run((err, stats) => {
+      if (err) {
+        console.error(err.stack || err);
+        if (err.details) {
+          console.error(err.details);
+        }
+        rej();
+      }
+    
+      const info = stats.toJson();
+    
+      if (stats.hasErrors()) {
+        console.error(info.errors);
+        rej();
+      }
+    
+      if (stats.hasWarnings()) {
+        console.warn(info.warnings.join('\n'));
+      }
+
+      res();
+    })
+  );
+}
+
+async function execFile(file, args) {
+  const start = new Date();
+  return new Promise((res, rej) => {
+    const child = fork(path.join(__dirname, file), args);
+    function errorHandler(err) {
+      console.error(err);
+      process.exit(1);
+    };
+    function successHandler(code) {
+      if (code === 0) {
+        const duration = new Date() - start;
+        console.log('%s took %ss', file, duration / 1000);
+        res();
+      }
+      else {
+        process.exit(code);
+      }
+    }
+    child.on('error', errorHandler);
+    child.on('exit', successHandler);
+  });
+}
+
+async function build(cmd, options) {
+  generate(options);
+  const toBuild = cmd === 'all'
+    ? ['server', 'client']
+    : cmd;
+  const config = getConfig(options);
+  config.analyze = options.analyze;
+  config.output = options.output;
+
+  // These get passed to `fork`ed builds
+  process.env.pathPrefix = config.pathPrefix;
+  process.env.hasDesignGuidelines = config.hasDesignGuidelines;
+  // console.log('build', cmd, options.parent.cssconfig);
+  if (toBuild.includes('server')) {
+    // Need to fork since first webpack build puts pressure on GC
+    // Otherwise CircleCI will fail with 4GB RAM
+    await execFile('buildServer.js', [JSON.stringify(config)]);
+  }
+  if (toBuild.includes('client')) {
+    await execFile('buildClient.js', [JSON.stringify(config)]);
+  }
+}
+
+module.exports = {
+  build,
+  buildWebpack
+};

package/scripts/cli/buildClient.js

@@ -0,0 +1,23 @@
+const { buildWebpack } = require('./build');
+const clientConfig = require('../webpack/webpack.client.config');
+
+const options = JSON.parse(process.argv[2]);
+
+async function buildClient() {
+  console.log('load client webpack config');
+  
+  const webpackArgv = {
+    mode: 'production',
+    ...options
+  };
+  const webpackClientConfig = await clientConfig(options.analyze && 'analyze', webpackArgv);
+  console.log('build client');
+  await buildWebpack(webpackClientConfig);
+}
+
+buildClient()
+  .catch(err => {
+    console.error(err);
+    process.exit(3);
+  })
+  .then(() => process.exit(0));

package/scripts/cli/buildServer.js

@@ -0,0 +1,24 @@
+const { buildWebpack } = require('./build');
+const serverConfig = require('../webpack/webpack.server.config');
+
+const options = JSON.parse(process.argv[2]);
+
+async function buildServer() {
+  console.log('load server webpack config');
+
+  const webpackArgv = {
+    mode: 'production',
+    ...options
+  };
+  const webpackServerConfig = await serverConfig(null, webpackArgv);
+  console.log('build server');
+  await buildWebpack(webpackServerConfig);
+}
+
+buildServer()
+  .catch(err => {
+    console.error(err);
+    process.exit(2);
+  })
+  .then(() => process.exit(0));
+

package/scripts/cli/cli.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+const program = require('commander');
+
+program
+  .option('-c, --config <path>', 'set config path', 'patternfly-docs/patternfly-docs.config.js')
+  .option('-css, --cssconfig <path>', 'set css import file path', 'patternfly-docs/patternfly-docs.css.js')
+  .option('-s, --source <path>', 'set source generation file path', 'patternfly-docs/patternfly-docs.source.js');
+
+program
+  .command('generate')
+  .description('generates source files')
+  .action(options => {
+    const { generate } = require('./generate');
+    generate(options);
+  });
+
+program
+  .command('start')
+  .description('generates source files and runs webpack-dev-server')
+  .action(options => {
+    const { start } = require('./start');
+    start(options);
+  });
+
+program
+  .command('build <server|client|all>')
+  .option('-a, --analyze', 'use webpack-bundle-analyzer', false)
+  .option('-o, --output <folder>', 'output folder', 'public')
+  .description('generates source files and runs webpack')
+  .action((cmd, options) => {
+    const { build } = require('./build');
+    build(cmd, options);
+  });
+
+program
+  .command('serve <folder>')
+  .option('-p, --port <port>', 'port to serve on', 5000)
+  .description('serves a directory on a port')
+  .action((cmd, options) => {
+    const { serve } = require('./serve');
+    serve(cmd, options);
+  });
+
+program
+  .command('screenshots')
+  .option('-u, --urlPrefix <prefix>', 'where fullscreen pages are hosted', 'http://localhost:5000/v4')
+  .description('updates screenshots for generated components')
+  .action(options => {
+    const { writeScreenshots } = require('../writeScreenshots');
+    writeScreenshots(options);
+  });
+
+program
+  .command('init')
+  .option('-n, --name <extension>', 'name of the extension', 'extension')
+  .option('-s, --scripts', 'Adds script targets to package.json', false)
+  .description('Initialize patternfly-docs')
+  .action(options => {
+    const { init } = require('./init');
+    init(options);
+  });
+
+program.parse(process.argv);

package/scripts/cli/generate.js

@@ -0,0 +1,23 @@
+const path = require('path');
+const { sourceMD, sourceProps, writeIndex } = require('../md/parseMD');
+
+function getSource(options) {
+  return require(path.join(process.cwd(), options.parent.source));
+}
+
+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);
+  const exitCode = writeIndex();
+  if (exitCode !== 0) {
+    process.exit(exitCode);
+  }
+  const duration = new Date() - start;
+  console.log('generating took %ss', duration / 1000);
+}
+
+module.exports = {
+  generate
+};

package/scripts/cli/helpers.js

@@ -0,0 +1,9 @@
+const path = require('path');
+
+function getConfig(options) {
+  return require(path.join(process.cwd(), options.parent.config));
+}
+
+module.exports = {
+  getConfig
+};

package/scripts/cli/init.js

@@ -0,0 +1,68 @@
+const fs = require("fs");
+const fse = require("fs-extra");
+const path = require("path");
+
+function init({ name, scripts }) {
+  const srcDir = path.join(__dirname, "../../templates/patternfly-docs");
+  const destDir = path.join(process.cwd(), "/patternfly-docs");
+
+  console.log(`Scaffolding patternfly-docs at ${destDir}`);
+
+  // To copy a folder or file
+  fse.copy(srcDir, destDir, function (err) {
+    if (err) {
+      console.error(err);
+    } else {
+      const nameLowerCaseHyphenated = name.toLowerCase().split(" ").join("-");
+      fs.renameSync(
+        path.join(destDir, "/content/extensions/extension"),
+        path.join(destDir, `/content/extensions/${nameLowerCaseHyphenated}`)
+      );
+
+      if (scripts) {
+        console.log(`Adding script targets to package.json`);
+        const packageJson = require(path.join(process.cwd(), "/package.json"));
+        if (!packageJson) {
+          console.error(`No package.json found at ${process.cwd()}`);
+          return;
+        }
+        if (!packageJson.scripts) {
+          packageJson.scripts = {};
+        }
+        packageJson.scripts = {
+          ...packageJson.scripts,
+          "docs:develop": "pf-docs-framework start",
+          "docs:build": "pf-docs-framework build all --output public",
+          "docs:serve": "pf-docs-framework serve public --port 5000",
+          "docs:screenshots":
+            "pf-docs-framework screenshots --urlPrefix http://localhost:5000",
+        };
+        // console.log(packageJson);
+        const jsonString = JSON.stringify(packageJson, null, 2);
+        fs.writeFile("./package.json", jsonString, (err) => {
+          if (err) {
+            console.log("Error writing to package.json", err);
+          }
+        });
+      }
+
+      const filesToReplaceId = [
+        path.join(destDir, `/content/extensions/${nameLowerCaseHyphenated}/design-guidelines/design-guidelines.md`),
+        path.join(destDir, `/content/extensions/${nameLowerCaseHyphenated}/examples/basic.md`)
+      ];
+      filesToReplaceId.forEach(path => {
+        fs.readFile(path, "utf-8", function (err, data) {
+          if (err) throw err;
+          var newValue = data.replace(/id: My extension/, `id: ${name}`);
+          fs.writeFile(path, newValue, "utf-8", function (err, data) {
+            if (err) throw err;
+          });
+        });
+      });
+    }
+  });
+}
+
+module.exports = {
+  init,
+};

package/scripts/cli/serve.js

@@ -0,0 +1,13 @@
+const express = require('express');
+
+function serve(serveDir, { port }) {
+  const app = express();
+
+  app.use(express.static(serveDir));
+
+  app.listen(port, () => console.log(`Serving ${serveDir} at http://localhost:${port}`));
+}
+
+module.exports = {
+  serve
+};

package/scripts/cli/start.js

@@ -0,0 +1,32 @@
+const WebpackDevServer = require('webpack-dev-server');
+const webpack = require('webpack');
+const clientConfig = require('../webpack/webpack.client.config');
+const { generate } = require('./generate');
+const { getConfig } = require('./helpers');
+const { watchMD } = require('../md/parseMD');
+
+function startWebpackDevServer(webpackConfig) {
+  webpackConfig.devServer.filename = webpackConfig.output.filename;
+  webpackConfig.devServer.publicPath = webpackConfig.output.publicPath;
+  const { port } = webpackConfig.devServer;
+  const compiler = webpack(webpackConfig);
+  const server = new WebpackDevServer(compiler, webpackConfig.devServer);
+
+  server.listen(port, 'localhost', err => {
+    if (err) {
+      console.log(err);
+    }
+  });
+}
+
+async function start(options) {
+  generate(options, true);
+  const webpackClientConfig = await clientConfig(null, { mode: 'development', ...getConfig(options) });
+  console.log('start webpack-dev-server');
+  watchMD();
+  startWebpackDevServer(webpackClientConfig);
+}
+
+module.exports = {
+  start
+};

package/scripts/md/anchor-header.js

@@ -0,0 +1,69 @@
+const visit = require('unist-util-visit');
+const toText = require('hast-util-to-text')
+const { slugger } = require('../../helpers/slugger');
+const { liveCodeTypes } = require('../../helpers/liveCodeTypes');
+
+// This transforms headers in markdown to AutoLinkHeader JSX components
+function anchorHeader(tocCallback) {
+  return tree => {
+    const ids = {};
+    const toc = [];
+    const addTOCItem = (tocItem, level) => {
+      if (level === 'h2') {
+        toc.push(tocItem);
+      }
+      else if (level === 'h3') {
+        // Only need to support up to h3s, so this array structure works fine
+        const lastTOC = toc[toc.length - 1];
+        if (Array.isArray(lastTOC)) {
+          lastTOC.push(tocItem);
+        }
+        else {
+          toc.push([tocItem]);
+        }
+      }
+    }
+    visit(tree, 'element', node => {
+      if (node.tagName.match(/h\d/)) {
+        // Add a unique id for auto link headers
+        const text = toText(node);
+        node.properties.id = node.properties.id || slugger(text);
+        const idNum = ids[node.properties.id];
+        const tocItem = { text };
+        if (idNum !== undefined) {
+          ids[node.properties.id] += 1;
+          node.properties.id += `-${idNum}`;
+          // Only add id if its not === `slugger(text)` to save some bandwidth
+          tocItem.id = node.properties.id;
+        }
+        else {
+          ids[node.properties.id] = 0;
+        }
+        // Add to TOC for indexing
+        addTOCItem(tocItem, node.tagName);
+
+        node.properties.size = node.tagName;
+        node.properties.className = node.properties.className || '';
+        node.properties.className += node.properties.className ? ' ' : '';
+        node.properties.className += `ws-title ws-${node.tagName}`;
+        node.tagName = 'AutoLinkHeader';
+      }
+      else if (
+        node.tagName === 'Example'
+        && liveCodeTypes.includes(node.properties.lang)
+        && !node.properties.noLive
+      ) {
+        addTOCItem(
+          {
+            text: node.title
+          },
+          'h3'
+        );
+      }
+    });
+
+    tocCallback(toc);
+  }
+}
+
+module.exports = anchorHeader;

package/scripts/md/auto-link-url.js

@@ -0,0 +1,33 @@
+// https://github.com/remarkjs/remark/tree/main/packages/remark-parse#processoruseparse-options
+// https://github.com/remarkjs/remark/blob/main/packages/remark-parse/lib/tokenize/auto-link.js
+const decode = require('parse-entities');
+
+// Support `<https://google.com>`
+// This is removed in MDX 2: https://github.com/mdx-js/mdx/issues/1049
+function plugin({ beginMarker = '<http', endMarker = '>' } = {}) {
+  const Parser = this.Parser;
+  const tokenizers = Parser.prototype.inlineTokenizers;
+  const methods = Parser.prototype.inlineMethods;
+
+  tokenizers.autoLinkUrl = function autoLinkUrl(eat, value) {
+    if (!value.startsWith(beginMarker)) {
+      return;
+    }
+    const endIndex = value.indexOf(endMarker);
+    if (endIndex >= 1) {
+      const link = value.substr(1, endIndex);
+      return eat(value.substr(0, endIndex))({
+        type: 'link',
+        title: null,
+        url: decode(link, { nonTerminated: false })
+      });
+    }
+    return true;
+  }
+  tokenizers.autoLinkUrl.locator = (value, fromIndex) => value.indexOf(beginMarker, fromIndex);
+
+  // Put before existing `autoLink` which will be deleted in remark-mdx
+  methods.splice(methods.indexOf('autoLink'), 0, 'autoLinkUrl')
+}
+
+module.exports = plugin;