@patternfly/documentation-framework 1.0.0

package/scripts/md/example-captions.js

@@ -0,0 +1,67 @@
+const visit = require('unist-util-visit');
+const remove = require('unist-util-remove');
+const { parseJSXAttributes } = require('./jsxAttributes');
+const { liveCodeTypes } = require('../../helpers/liveCodeTypes');
+
+function isExample(node, file) {
+  if (node.type !== 'code' || !liveCodeTypes.includes(node.lang)) {
+    return false;
+  }
+  if (node.meta) {
+    let properties = {};
+    try {
+      Object.entries(parseJSXAttributes(`<Component ${node.meta} />`))
+        .forEach(([key, val]) => {
+          properties[key] = val;
+        }); 
+    }
+    catch (error) {
+      file.fail(`Error parsing "${node.meta}": ${error}`);
+    }
+    if (properties.noLive) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+function exampleCaptions() {
+  return (tree, file) => {
+    visit(tree, node => isExample(node, file), (node, _index, parent) => {
+      let title = 'Untitled example';
+      let caption = [];
+
+      // Starting from node, look up for h3s
+      let startLooking = false;
+      for(let i = parent.children.length - 1; i > 0; i--) {
+        const child = parent.children[i];
+        if (child === node) {
+          startLooking = true;
+        }
+        else if (startLooking) {
+          if (
+            child.type === 'heading' &&
+            child.depth === 3 &&
+            child.children && 
+            child.children[0].value
+          ) {
+            title = child.children[0].value;
+            child.needsDeletion = true;
+            break;
+          }
+          else {
+            caption.unshift(Object.assign({}, child));
+            child.needsDeletion = true;
+          }
+        }
+      }
+
+      node.title = title;
+      node.children = caption;
+    });
+    remove(tree, node => node.needsDeletion);
+  }
+}
+
+module.exports = exampleCaptions;

package/scripts/md/jsxAttributes.js

@@ -0,0 +1,20 @@
+const { parse } = require('@patternfly/ast-helpers');
+
+module.exports = {
+  parseJSXAttributes: jsx => {
+    // Patch until https://github.com/patternfly/patternfly/pull/3324 is in react-docs
+    jsx = jsx.replace(/=(true|false)/g, (_, match) => `="${match}"`);
+    const properties = {};
+    const jsxAttributes = parse(jsx)
+      .body[0]
+      .expression
+      .openingElement
+      .attributes;
+
+    jsxAttributes.forEach(attr => {
+      properties[attr.name.name] = attr.value ? attr.value.value : true;
+    });
+
+    return properties;
+  }
+}

package/scripts/md/mdx-ast-to-mdx-hast.js

@@ -0,0 +1,210 @@
+const fs = require('fs');
+const path = require('path');
+const toHAST = require('mdast-util-to-hast');
+const detab = require('detab');
+const normalize = require('mdurl/encode');
+const all = require('mdast-util-to-hast/lib/all');
+const styleToObject = require('style-to-object');
+const camelCaseCSS = require('camelcase-css');
+const { parseJSXAttributes } = require('./jsxAttributes');
+const { getExampleDeclaration, prettyExampleCode } = require('../../helpers/codesandbox');
+const { liveCodeTypes } = require('../../helpers/liveCodeTypes');
+
+let srcCounter = 0;
+
+// Adapted from https://github.com/mdx-js/mdx/blob/next/packages/mdx/mdx-ast-to-mdx-hast.js
+function mdxAstToMdxHast({ watchExternal }) {
+  return (tree, file) => {
+    const srcImports = [];
+
+    function imageHandler(h, node) {
+      const { src, ...rest } = node.props || {};
+      const srcImport = `srcImport${srcCounter++}`;
+      const url = (node.url || src).replace(/'/g, "\\'");
+      const props = {
+        src: srcImport,
+        alt: node.alt,
+        title: node.title,
+        isResponsive: /\.(png|jpe?g|webp)$/.test(url),
+        ...rest
+      };
+      // Add import statement
+      srcImports.push({
+        type: 'import',
+        value: `import ${srcImport} from '${url}';`
+      });
+    
+      return h(node, 'img', props);
+    }
+
+    function mdxExpression(h, node) {
+      // Treat JSX <img> tags like commonmark ![]() image tags
+      if (node.name === 'img') {
+        node.props = node.attributes.reduce((acc, attr) => {
+          acc[attr.name] = attr.value;
+          return acc;
+        }, {});
+        if (typeof node.props.src === 'string') {
+          return imageHandler(h, node);
+        }
+      }
+      node.attributes.forEach(attr => {
+        // style="backgroundcolor: black" -> style={{backgroundColor: "black"}}
+        if (attr.name === 'style' && typeof attr.value === 'string') {
+          const styleObject = {};
+          styleToObject(attr.value, (name, value) => styleObject[camelCaseCSS(name)] = value);
+          attr.value = {
+            type: 'mdxValueExpression',
+            value: JSON.stringify(styleObject)
+          };
+        }
+    
+        // class="my-class" -> className="my-class"
+        if (attr.name === 'class') {
+          attr.name = 'className';
+        }
+      });
+
+      return Object.assign({}, node, {children: all(h, node)});
+    }
+
+    const handlers = {
+      // `inlineCode` gets passed as `code` by the HAST transform.
+      // This makes sure it ends up being `inlineCode`
+      inlineCode(h, node) {
+        return Object.assign({}, node, {
+          type: 'element',
+          tagName: 'code',
+          properties: {},
+          children: [
+            {
+              type: 'text',
+              value: node.value
+            }
+          ]
+        });
+      },
+      code(h, node) {
+        const properties = {
+          code: node.value ? detab(node.value + '\n').trim() : '',
+          title: node.title
+        };
+        
+        if (node.lang) {
+          properties.lang = node.lang;
+        }
+
+        if (node.meta) {
+          try {
+            const dirname = path.dirname(file.history[0]);
+            Object.entries(parseJSXAttributes(`<Component ${node.meta} />`))
+              .forEach(([key, val]) => {
+                if (key === 'file') {
+                  const filePath = path.join(dirname, val);
+                  properties.code = fs.readFileSync(filePath, 'utf8');
+                  watchExternal(filePath);
+                } else {
+                  properties[key] = val;
+                }
+              });
+          }
+          catch(error) {
+            file.fail(`Error parsing "${node.meta}": ${error}`);
+          }
+        }
+        if (liveCodeTypes.includes(node.lang) && node.lang !== 'html' && !properties.noLive) {
+          try {
+            const declaration = getExampleDeclaration(properties.code);
+            if (
+              declaration.type === 'ExpressionStatement' &&
+              declaration.expression.type === 'JSXElement'
+            ) {
+              // Lone JSX
+              properties.code = prettyExampleCode(node.title, properties.code, declaration);
+            }
+            else if (
+              !declaration ||
+              // Allow Example = () => {...}
+              declaration.type === 'ExpressionStatement' && !(
+                declaration.expression.type === 'AssignmentExpression' &&
+                declaration.expression.right.body &&
+                declaration.expression.right.body.type === 'BlockStatement'
+              )
+            ) {
+              file.message(`Example "${node.title}" must be a class, named block statement, or plain JSX`, node.position);
+            }
+          }
+          catch (err) {
+            file.message(`Example "${node.title}" has invalid JSX: ${err.toString()}`)
+          }
+        }
+
+        return Object.assign({}, node, {
+          type: 'element',
+          tagName: 'Example',
+          properties,
+          children: all(h, node)
+        });
+      },
+      import(h, node) {
+        return Object.assign({}, node, {
+          type: 'import'
+        });
+      },
+      comment(h, node) {
+        return Object.assign({}, node, {
+          type: 'comment'
+        });
+      },
+      image(h, node) {
+        return imageHandler(h, node);
+      },
+      link(h, node) {
+        const href = normalize(node.href || node.url);
+
+        const properties = {};
+        if (node.title !== null && node.title !== undefined) {
+          properties.title = node.title;
+        }
+  
+        if (href) {
+          properties.to = href;
+          
+          return Object.assign({}, node, {
+            type: 'element',
+            tagName: 'PatternflyThemeLink',
+            properties,
+            children: all(h, node)
+          });
+        }
+  
+        properties.href = href;
+        return h(node, 'a', properties, all(h, node));
+      },
+      mdxBlockElement(h, node) {
+        return mdxExpression(h, node);
+      },
+      mdxSpanElement(h, node) {
+        return mdxExpression(h, node);
+      },
+      mdxBlockExpression(h, node) {
+        return Object.assign({}, node, {
+          type: 'mdxBlockExpression'
+        });
+      },
+      mdxSpanExpression(h, node) {
+        return Object.assign({}, node, {
+          type: 'mdxSpanExpression'
+        });
+      }
+    };
+
+    const hast = toHAST(tree, { handlers });
+
+    hast.children.unshift(...srcImports);
+
+    return hast;
+  }
+}
+
+module.exports = mdxAstToMdxHast

package/scripts/md/mdx-hast-to-jsx.js

@@ -0,0 +1,233 @@
+const path = require('path');
+const fs = require('fs');
+const { serializeTags } = require('remark-mdx/lib/serialize/mdx-element');
+const serializeMdxExpression = require('remark-mdx/lib/serialize/mdx-expression');
+const toH = require('hast-to-hyperscript');
+const { toTemplateLiteral } = require('@mdx-js/util');
+const { parse } = require('@patternfly/ast-helpers');
+const { capitalize } = require('../../helpers/capitalize');
+const { slugger } = require('../../helpers/slugger');
+const { liveCodeTypes } = require('../../helpers/liveCodeTypes');
+
+// Adapted from https://github.com/mdx-js/mdx/blob/next/packages/mdx/mdx-hast-to-jsx.js
+function toJSX(node, parentNode = {}, options = {}) {
+  options.examples = options.examples || {};
+  options.indent = options.indent || 2;
+  if (node.type === 'root') {
+    return serializeRoot(node, options);
+  }
+
+  if (node.type === 'element') {
+    return serializeElement(node, options, parentNode);
+  }
+
+  // Wraps text nodes inside template string, so that we don't run into escaping issues.
+  if (node.type === 'text') {
+    return serializeText(node, options, parentNode);
+  }
+
+  if (node.type === 'mdxBlockExpression' || node.type === 'mdxSpanExpression') {
+    return serializeMdxExpression(node);
+  }
+
+  if (node.type === 'mdxBlockElement' || node.type === 'mdxSpanElement') {
+    return serializeComponent(node, options, parentNode);
+  }
+}
+
+function compile(options = { }) {
+  this.Compiler = function(tree) {
+    return toJSX(tree, {}, options);
+  }
+}
+
+function serializeRoot(node, options) {
+  const { getOutPath, getRelPath, getPageData, examples } = options;
+  const pageData = {...getPageData()};
+  // Save some kb
+  delete pageData.toc;
+  const exportName = pageData.slug.replace(/[\/-](.)?/g, (_, match) => capitalize(match)) + 'Docs';
+  const groups = {
+    import: [],
+    rest: []
+  };
+
+  for (const child of node.children) {
+    let kind = 'rest'
+
+    if (child.type === 'import') {
+      kind = child.type
+    }
+
+    groups[kind].push(child)
+  }
+
+  const thumbnailFolder = path.join(path.dirname(getOutPath()), pageData.source);
+  const thumbnails = fs.existsSync(thumbnailFolder) ? fs.readdirSync(thumbnailFolder) : [];
+  const thumbnailImports = thumbnails.map(img =>
+    `import srcImport${path.basename(img, '.png').replace(/-/g, '')} from './${pageData.source}/${img}';`)
+
+  const importStatements = groups.import
+    .map(node => node.value)
+    .map(imp => imp.replace(/(['"])\./g, (_, match) => `${match}${getRelPath()}${path.posix.sep}\.`))
+    .concat(thumbnailImports)
+    .join('\n')
+
+  // https://astexplorer.net/#/gist/9c531dd372dfc57e194c13c2889d31c3/03f2d6e889db1a733c6a079554e8af7784863739
+  options.importSpecifiers = parse(importStatements).body
+    .map(node => node.specifiers)
+    .flat(1)
+    .map(spec => spec.local ? spec.local.name : null)
+    .filter(Boolean);
+  const liveContext = options.importSpecifiers
+    .filter(localName => !/srcImport.*/.test(localName)) // Images in MD like [!img](./src)
+    .join(',\n  ');
+
+  const childNodes = groups.rest
+    .map(childNode => toJSX(childNode, node, options))
+    .join('');
+
+  let res = `import React from 'react';
+import { AutoLinkHeader, Example, Link as PatternflyThemeLink } from '@patternfly/documentation-framework/components';
+${importStatements}
+const pageData = ${JSON.stringify(pageData, null, 2)};
+`;
+  if (liveContext) {
+    res += `pageData.liveContext = {\n${
+      '  ' + liveContext
+    }\n};\n`
+  }
+  if (examples) {
+    res += `pageData.examples = {\n${
+      '  ' + Object.entries(examples)
+        .map(([key, val]) => `'${key}': ${val}`)
+        .join(',\n  ')
+    }\n};\n`;
+  }
+  res += `\nconst Component = () => (
+  <React.Fragment>${childNodes.replace(/\n\s*\n/g, '\n')}
+  </React.Fragment>
+);
+Component.displayName = '${exportName}';
+Component.pageData = pageData;
+
+export default Component;\n`;
+
+  return res;
+}
+
+function serializeElement(node, options) {
+  const { indent, examples } = options;
+  const { type, props } = toH(
+    fakeReactCreateElement,
+    Object.assign({}, node, {children: []}),
+    {prefix: false}
+  );
+  const content = serializeChildren(node, {...options});
+
+  delete props.key;
+
+  const srcImport = node.properties.src;
+  if (type === 'img') {
+    delete props.src;
+    delete props.isResponsive;
+  }
+  const spread = Object.keys(props).length === 0
+    ? null
+    : JSON.stringify(props);
+
+  const indentText = '  '.repeat(indent);
+  let res = '\n';
+  const isFullscreenExample = type === 'Example'
+    && liveCodeTypes.includes(props.lang)
+    && !props.noLive;
+  res += `${indentText}<${type}`;
+  if (isFullscreenExample) {
+    res += ' {...pageData} {...props}';
+    const thumbnailImport = `srcImport${slugger(props.title).replace(/-/g, '')}`;
+    if (options.importSpecifiers.includes(thumbnailImport)) {
+      res += ` thumbnail={${thumbnailImport}}`;
+    }
+  }
+  else if (type === 'img') {
+    res += ` src={${srcImport}}`;
+    if (node.properties.isResponsive) {
+      if (!props.width) {
+        res += ` width={${srcImport}.width}`;
+        res += ` height={${srcImport}.height}`;
+      }
+      else {
+        props.width = props.width.replace('px', '');
+        res += ` height={${srcImport}.height * ${props.width} / ${srcImport}.width}`;
+      }
+    }
+  }
+  if (spread) {
+    res += ` {...${spread}}`;
+  }
+  res += `>\n${indentText}  ${content}`;
+  res += `\n${indentText}</${type}>`;
+  if (isFullscreenExample) {
+    // Props lets us pass `isFullscreenPreview` to <Example> so it knows to take 100% height
+    examples[props.title] = `props => ${res}`;
+    res = `\n${indentText}{React.createElement(pageData.examples[${
+      JSON.stringify(props.title)
+    }])}`;
+  }
+
+  return res;
+}
+
+function serializeComponent(node, options) {
+  let content = serializeChildren(node, options);
+  const tags = serializeTags(
+    Object.assign({}, node, {children: content ? ['!'] : []})
+  );
+
+  if (node.type === 'mdxBlockElement' && content) {
+    content = '\n' + content + '\n';
+  }
+
+  const indentText = '  '.repeat(options.indent);
+  return `${indentText}${tags.open}${content}${tags.close || ''}`;
+}
+
+function serializeText(node, options, parentNode) {
+  // Don't wrap newlines unless specifically instructed to by the flag,
+  // to avoid issues like React warnings caused by text nodes in tables.
+  const shouldPreserveNewlines = options.preserveNewlines || parentNode.tagName === 'p';
+
+  if (node.value === '\n' && !shouldPreserveNewlines) {
+    return node.value;
+  }
+
+  return toTemplateLiteral(node.value);
+}
+
+function serializeChildren(node, options) {
+  const children = node.children || [];
+  const childOptions = Object.assign({}, options, {
+    // Tell all children inside <pre> tags to preserve newlines as text nodes
+    preserveNewlines: options.preserveNewlines || node.tagName === 'pre',
+    indent: options.indent + 1
+  });
+
+  const indentText = '  '.repeat(options.indent + 1);
+
+  return children
+    .map(childNode => toJSX(childNode, node, childOptions))
+    .join(`\n${indentText}`);
+}
+
+// We only do this for the props, so we’re ignoring children.
+function fakeReactCreateElement(name, props) {
+  return {
+    type: name,
+    props: props,
+    // Needed for `toH` to think this is React.
+    key: null,
+    _owner: null
+  }
+}
+
+module.exports = compile;