@patternfly/documentation-framework 1.0.0

package/scripts/md/parseMD.js

@@ -0,0 +1,308 @@
+const path = require('path');
+const fs = require('fs-extra');
+const unified = require('unified');
+const remove = require('unist-util-remove');
+const visit = require('unist-util-visit');
+const toVfile = require('to-vfile'); // https://github.com/vfile/vfile
+const vfileReport = require('vfile-reporter');
+const yaml = require('js-yaml'); // https://github.com/nodeca/js-yaml
+const chokidar = require('chokidar');
+const { sync } = require('glob');
+const { typecheck } = require('./typecheck');
+const { makeSlug } = require('../../helpers/slugger');
+const { liveCodeTypes } = require('../../helpers/liveCodeTypes');
+const { tsDocgen } = require('../tsDocgen');
+
+let exitCode = 0;
+const outputBase = path.join(process.cwd(), `patternfly-docs/generated`);
+const tsDocs = {};
+const routes = {};
+const globs = {
+  props: [],
+  md: [],
+};
+
+function toReactComponent(mdFilePath, source, buildMode) {
+  // vfiles allow for nicer error messages and have native `unified` support
+  const vfile = toVfile.readSync(mdFilePath);
+
+  const relPath = path.relative(path.join(process.cwd(), '../..'), vfile.path).split(path.sep).join(path.posix.sep);
+
+  let jsx;
+  let outPath;
+  let pageData = {};
+  let frontmatter = {};
+
+  unified()
+    .use(require('remark-parse'))
+    .use(require('remark-frontmatter'), ['yaml'])
+    // Extract frontmatter
+    .use(() => (tree, file) => {
+      const yamlNode = tree.children.shift();
+      if (!yamlNode) {
+        return file.info('no frontmatter, skipping');
+      }
+      frontmatter = yaml.safeLoad(yamlNode.value);
+
+      // Fail early
+      if (!frontmatter.id) {
+        file.fail('id attribute is required in frontmatter for PatternFly docs');
+      }
+      source = frontmatter.source || source;
+      const slug = makeSlug(source, frontmatter.section, frontmatter.id);
+      outPath = path.join(outputBase, `${slug}.js`);
+
+      let sourceRepo = 'patternfly-org';
+      if (source.includes('html')) {
+        sourceRepo = 'patternfly';
+      }
+      else if (source.includes('react')) {
+        sourceRepo = 'patternfly-react';
+      }
+
+      const propComponents = [...new Set(frontmatter.propComponents || [])]
+        .filter(propComponent => {
+          if (tsDocs[propComponent]) {
+            return true;
+          }
+          file.message(`Prop component ${propComponent} missing from tsDocgen`);
+          return false;
+        })
+        .map(propComponent => tsDocs[propComponent])
+
+      const normalizedPath = relPath
+        .replace('node_modules/@patternfly/patternfly/docs', 'src/patternfly')
+        .replace(/node_modules\/@patternfly\/react-([\w-])/, (_, match) => `packages/react-${match}`)
+        .replace(/\.\.\//g, '');
+
+      pageData = {
+        id: frontmatter.id,
+        section: frontmatter.section || '',
+        source,
+        slug,
+        sourceLink: `https://github.com/patternfly/${
+          sourceRepo}/blob/main/${
+          normalizedPath}`,
+        hideTOC: frontmatter.hideTOC || false
+      };
+      // Temporarily override section for Demo tabs until we port this upstream
+      if (frontmatter.section === 'demos' && routes[slug.replace('demos', 'components')]) {
+        // Temporarily override section until https://github.com/patternfly/patternfly-react/pull/4862 is in react-docs
+        pageData.section = 'components';
+        pageData.source = `${source}-demos`;
+        pageData.slug = makeSlug(pageData.source, pageData.section, pageData.id);
+        outPath = path.join(outputBase, `${pageData.slug}.js`);
+      }
+      if (frontmatter.title) {
+        pageData.title = frontmatter.title;
+      }
+      if (propComponents.length > 0) {
+        pageData.propComponents = propComponents;
+      }
+      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;
+      }
+    })
+    // Delete HTML comments
+    .use(require('./remove-comments'))
+    // remark-mdx removes auto-link support
+    // this adds it back ONLY for links which are easily differentiable from JSX 
+    .use(require('./auto-link-url'))
+    // Support for JSX in MD
+    .use(require('remark-mdx'))
+    // remark-mdx leaves paragraphs as normal MD, but inside MDX we expect it not to.
+    .use(() => tree => {
+      visit(tree, 'mdxBlockElement', node => {
+        if (node.children[0] && node.children[0].type === 'paragraph') {
+          const newChildren = node.children[0].children;
+          node.children.shift();
+          node.children = newChildren.concat(node.children);
+        }
+      });
+    })
+    // Support for import/exports in MD
+    .use(require('remark-mdxjs'))
+    // Insert footnotes
+    .use(require('remark-footnotes'))
+    // Remove whitespace
+    .use(require('remark-squeeze-paragraphs'))
+    // Support example captions
+    .use(require('./example-captions'))
+    // .use(require('remark-rehype'))
+    // .use(require('rehype-react'), { createElement: require('react').createElement })
+    // Transform AST to JSX elements. Includes special code block parsing
+    .use(require('./mdx-ast-to-mdx-hast'), { 
+      watchExternal(file) {
+        if (buildMode === 'start') {
+          const watcher = chokidar.watch(file, { ignoreInitial: true });
+          watcher.on('change', () => {
+            sourceMDFile(mdFilePath, source, buildMode);
+            writeIndex();
+          });
+        }
+      }
+    })
+    // Don't allow exports
+    .use(() => tree => remove(tree, 'export'))
+    // Comments aren't very useful in generated files no one wants to look at
+    .use(() => tree => remove(tree, 'comment'))
+    // Extract examples to create fullscreen page routes
+    // Needs to be run after mdx-ast-to-mdx-hast which parses meta properties
+    .use(() => (tree, file) => {
+      const isExample = node =>
+        node.type === 'element'
+        && node.tagName === 'Example'
+        && liveCodeTypes.includes(node.properties.lang)
+        && !node.properties.noLive;
+      visit(tree, isExample, node => {
+        if (node.properties.isFullscreen) {
+          pageData.fullscreenExamples = pageData.fullscreenExamples || [];
+          pageData.fullscreenExamples.push(node.title);
+        }
+        else {
+          pageData.examples = pageData.examples || [];
+          pageData.examples.push(node.title);
+        }
+        // Typecheck TS examples
+        if (node.properties.lang === 'ts') {
+          const typerrors = typecheck(
+            path.join(pageData.id, node.title + '.tsx'), // Needs to be unique per-example
+            node.properties.code
+          );
+          typerrors.forEach(({ line, character, message }) => {
+            line = node.position.start.line + line + 1;
+            const column = character;
+            if (buildMode === 'start') {
+              // Don't fail to start over types
+              file.message(`\u001b[31m THIS WILL FAIL THE BUILD\u001b[0m\n  ${message}`, { line, column });
+            } else {
+              console.log('\u001b[31m');
+              file.fail(`\n  ${message}\n`, { line, column });
+              console.log('\u001b[0m');
+            }
+          });
+        }
+      });
+    })
+    // Add custom PatternFly doc design things
+    .use(require('./anchor-header'), toc => {
+      if (!pageData.hideTOC && toc.length > 0) {
+        pageData.toc = toc;
+      }
+      delete pageData.hideTOC;
+    })
+    .use(require('./styled-tags'))
+    // Transform HAST object to JSX string
+    .use(require('./mdx-hast-to-jsx'), {
+      getOutPath: () => outPath,
+      getRelPath: () => path.relative(path.dirname(outPath), vfile.dirname).split(path.sep).join(path.posix.sep), // for imports
+      getPageData: () => pageData // For @reach/router routing
+    })
+    .process(vfile, (err, file) => {
+      if (err) {
+        console.error(vfileReport(err));
+        exitCode = 2;
+      } else {
+        // console.log(relPath, '->', path.relative(process.cwd(), outPath));
+        if (file.messages.length > 0) {
+          console.log(vfileReport(file));
+        }
+        jsx = file.contents;
+      }
+    });
+
+  return {
+    jsx,
+    pageData,
+    outPath
+  };
+}
+
+function sourcePropsFile(file) {
+  tsDocgen(file)
+    .filter(({ hide }) => !hide)
+    .forEach(({ name, description, props }) => {
+      tsDocs[name] = { name, description, props };
+    });
+}
+
+function sourceMDFile(file, source, buildMode) {
+  if (path.basename(file).startsWith('_')) {
+    return;
+  }
+  const { jsx, pageData, outPath } = toReactComponent(file, source, buildMode);
+
+  if (jsx) {
+    fs.outputFileSync(outPath, jsx);
+    routes[pageData.slug] = {
+      id: pageData.id,
+      title: pageData.title || pageData.id,
+      toc: pageData.toc || [],
+      ...(pageData.examples && { examples: pageData.examples }),
+      ...(pageData.fullscreenExamples && { fullscreenExamples: pageData.fullscreenExamples }),
+      section: pageData.section,
+      source: pageData.source,
+      ...(pageData.katacodaLayout && { katacodaLayout: pageData.katacodaLayout }),
+      ...(pageData.hideNavItem && { hideNavItem: pageData.hideNavItem })
+    };
+  }
+}
+
+function writeIndex() {
+  const stringifyRoute = ([route, pageData]) => `'${route}': {\n    ${Object.entries(pageData)
+    .map(([key, val]) => `${key}: ${JSON.stringify(val)}`)
+    .concat(`Component: () => import(/* webpackChunkName: "${route.substr(1)}/index" */ '.${route}')`)
+    .join(',\n    ')}\n  }`;
+
+  const indexContent = `module.exports = {\n  ${Object.entries(routes)
+    .map(stringifyRoute)
+    .join(',\n  ')}\n};`;
+  fs.outputFileSync(path.join(outputBase, 'index.js'), indexContent);
+
+  return exitCode;
+}
+
+module.exports = {
+  sourceProps(glob, ignore) {
+    globs.props.push({ glob, ignore });
+    sync(glob, { ignore }).forEach(sourcePropsFile);
+  },
+  sourceMD(glob, source, ignore, buildMode) {
+    globs.md.push({ glob, source, ignore });
+    sync(glob, { ignore }).forEach(file => sourceMDFile(file, source, buildMode));
+  },
+  writeIndex,
+  watchMD() {
+    globs.props.forEach(({ glob, ignore }) => {
+      const propWatcher = chokidar.watch(glob, { ignored: ignore, ignoreInitial: true });
+      propWatcher.on('add', sourcePropsFile);
+      propWatcher.on('change', sourcePropsFile);
+    });
+    globs.md.forEach(({ glob, source, ignore }) => {
+      const mdWatcher = chokidar.watch(glob, { ignored: ignore, ignoreInitial: true });
+      function onMDFileChange(file) {
+        sourceMDFile(file, source, 'start');
+        writeIndex();
+      }
+      mdWatcher.on('add', onMDFileChange);
+      mdWatcher.on('change', onMDFileChange);
+    });
+  }
+};

package/scripts/md/remove-comments.js

@@ -0,0 +1,21 @@
+// https://github.com/remarkjs/remark/tree/main/packages/remark-parse#processoruseparse-options
+
+function plugin({ beginMarker = '<!--', endMarker = '-->' } = {}) {
+  const Parser = this.Parser
+  const tokenizers = Parser.prototype.blockTokenizers
+  const methods = Parser.prototype.blockMethods
+
+  tokenizers.comments = function tokenizeComment(eat, value) {
+    const trimmed = value.trimRight();
+    const endIndex = trimmed.indexOf(endMarker);
+    if (trimmed.startsWith(beginMarker) && endIndex >= 1) {
+      eat(value.substr(0, endIndex + endMarker.length));
+    }
+    return true;
+  }
+
+  // Run it just before `html`.
+  methods.splice(methods.indexOf('html'), 0, 'comments')
+}
+
+module.exports = plugin;

package/scripts/md/styled-tags.js

@@ -0,0 +1,87 @@
+const visit = require('unist-util-visit');
+
+const styledMdTags = [
+  'p',
+  'ul',
+  'ul',
+  'ul',
+  'ol',
+  'li',
+  'dl',
+  'blockquote',
+  'small',
+  'hr',
+  'dt',
+  'code',
+  'table',
+  'img'
+];
+
+function styledTags() {
+  return tree => {
+    visit(tree, 'element', node => {
+      if (styledMdTags.includes(node.tagName)) {
+        node.properties.className = node.properties.className || '';
+        node.properties.className += node.properties.className ? ' ' : '';
+        node.properties.className += `ws-${node.tagName}`;
+        // Match pf-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.role = 'grid';
+          let columnHeaders = [];
+          for (let child of node.children) {
+            if (child.tagName === 'thead') {
+              // Find column headers
+              const tr = child.children.find(child => child.tagName === 'tr');
+              tr.properties.role = 'row';
+              tr.children
+                .filter(child => child.tagName === 'th')
+                .forEach(th => {
+                  th.properties.className = th.properties.className || '';
+                  th.properties.className += ' pf-m-wrap';
+                  th.properties.role = 'columnheader';
+                  th.properties.scope = 'col';
+                  let colName = '';
+                  visit(th, 'text', node2 => colName += node2.value);
+                  columnHeaders.push(colName);
+                  // Need to wrap in div for css-grid stuffs
+                  th.children = [{
+                    type: 'element',
+                    tagName: 'div',
+                    properties: {},
+                    children: th.children
+                  }];
+                });
+            }
+            else if (child.tagName === 'tbody') {
+              child.properties.role = 'rowgroup';
+              child.children
+                .filter(tr => tr.tagName === 'tr')
+                .forEach(tr => {
+                  tr.properties.role = 'row';
+                  tr.children
+                    .filter(td => td.tagName === 'td')
+                    .forEach((td, i) => {
+                      td.properties.role = 'cell';
+                      if (columnHeaders[i]) {
+                        td.properties['data-label'] = columnHeaders[i];
+                      }
+                      // Need to wrap in div for css-grid stuffs
+                      td.children = [{
+                        type: 'element',
+                        tagName: 'div',
+                        properties: {},
+                        children: td.children
+                      }];
+                    });
+                });
+            }
+          }
+        }
+      }
+    });
+  }
+}
+
+module.exports = styledTags;

package/scripts/md/typecheck.js

@@ -0,0 +1,133 @@
+const path = require('path');
+const glob = require('glob');
+const ts = require('typescript');
+const versions = require('../../versions.json');
+
+// matches webpack.base.config.js
+const defaultDeclarations = `
+declare module '\\*.png' {
+  const content: string;
+  export default content;
+}
+declare module '\\*.jpg' {
+  const content: string;
+  export default content;
+}
+declare module '\\*.jpeg' {
+  const content: string;
+  export default content;
+}
+declare module '\\*.webp' {
+  const content: string;
+  export default content;
+}
+declare module '\\*.gif' {
+  const content: string;
+  export default content;
+}
+declare module '\\*.svg' {
+  const content: string;
+  export default content;
+}
+`;
+
+const reactStylesDir = path.join(require.resolve('@patternfly/react-styles/package.json'), '../');
+const reactStyles = glob.sync(path.join(reactStylesDir, 'css/**/*.d.ts'))
+  .map(f => f.replace(reactStylesDir, '@patternfly/react-styles/').replace(/\.d.ts$/, ''));
+const files = {
+  'imports.ts': ['react', '@reach/router']
+      .concat(Object.keys(versions.Releases[0].versions))
+      .concat(reactStyles)
+      .filter(p => p !== '@patternfly/patternfly')
+      .map(p => `import '${p}';`)
+      .join('\n'),
+  'declarations.d.ts': defaultDeclarations
+};
+
+const compilerOptions = {
+  target: 'ES2017',
+  noEmit: true,
+  skipLibCheck: true,
+  jsx: 'react',
+  esModuleInterop: true
+};
+const pfPackageRegex = /@patternfly\/([^\/]+)\/dist\/.*/;
+
+const compilerHost = ts.createCompilerHost(compilerOptions);
+compilerHost.readFile = fname => {
+  if (files[fname]) {
+    // console.log('readFile', fname, files[fname].text);
+    return files[fname];
+  }
+  return ts.sys.readFile(fname);
+};
+compilerHost.useCaseSensitiveFileNames = () => false; // saves 200ms on startup
+
+const program = ts.createProgram(
+  Object.keys(files),
+  compilerOptions,
+  compilerHost
+);
+const defaultImportsFile = program.getSourceFile('imports.ts');
+const typechecker = ts.createTypeChecker(program, true);
+
+let fileCounter = 0;
+function typecheck(fname, text) {
+  fname += fileCounter++; // Needs a new fname to bust diagnostics cache per-file :(
+  files[fname] = text;
+  const sourceFile = ts.createSourceFile(
+    fname,
+    text,
+    ts.ScriptTarget.ES2017,
+    true,
+    ts.ScriptKind.TSX
+  );
+  sourceFile.resolvedModules = defaultImportsFile.resolvedModules;
+  // Fix @patternfly/react-* imports so types resolve
+  sourceFile.statements
+    .filter(s => s.moduleSpecifier && s.moduleSpecifier.text.match(pfPackageRegex))
+    .forEach(s => {
+      s.moduleSpecifier.text = s.moduleSpecifier.text.replace(pfPackageRegex, (_, m) => `@patternfly/${m}`);
+      // Copied from a test file with `import { CogIcon } from '@patternfly/react-icons';`
+      if (!s.importClause.namedBindings) {
+        s.importClause.namedBindings = {
+          flags: 0,
+          modifierFlagsCache: 0,
+          kind: 265,
+          transformFlags: 0,
+          elements: [{
+            flags: 0,
+            modifierFlagsCache: 0,
+            kind: 266,
+            transformFlags: 0,
+            propertyName: undefined,
+            name: s.importClause.name
+          }]
+        };
+        s.importClause.name = undefined;
+      }
+    });
+  ts.bindSourceFile(sourceFile, compilerOptions);
+
+  const allDiagnostics = [...typechecker.getDiagnostics(sourceFile)];
+  return allDiagnostics.map(diagnostic => {
+    if (diagnostic.file) {
+      let { line, character } = ts.getLineAndCharacterOfPosition(diagnostic.file, diagnostic.start);
+      let message = ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n");
+      return {
+        line,
+        character: character + 1,
+        message
+      };
+    } else {
+      return {
+        message: ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n")
+      };
+    }
+  });
+}
+
+module.exports = {
+  typecheck
+};
+

package/scripts/tsDocgen.js

@@ -0,0 +1,155 @@
+const fs = require('fs');
+const reactDocgen = require('react-docgen');
+const ts = require('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 = reactDocgen.parse(
+      sourceText,
+      reactDocgen.resolver.findAllExportedComponentDefinitions,
+      null,
+      { filename }
+    );
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    // console.warn(`No component found in ${filename}:`, err);
+  }
+
+  return (parsedComponents || []).filter(parsed => parsed && parsed.displayName);
+}
+
+function getInterfaceMetadata(filename, sourceText) {
+  const ast = 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 acc;
+      }, {});
+
+      interfaces.push({
+        displayName: statement.name.escapedText,
+        props
+      });
+    });
+  return interfaces;
+}
+
+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;
+}
+
+function tsDocgen(file) {
+  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
+
+  return componentMeta
+    .concat(interfaceMeta)
+    .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))
+    }));
+}
+
+module.exports = {
+  tsDocgen
+};
+