@patternfly/documentation-framework 1.0.0

package/README.md

@@ -0,0 +1,92 @@
+# @patternfly/documentation-framework
+
+## Install
+
+We publish this theme [on npm.](https://www.npmjs.com/package/@patternfly/documentation-framework) Install it as a devDependency with your package manager.
+
+`npm i --save-dev @patternfly/documentation-framework`
+
+`yarn add -D @patternfly/documentation-framework`
+
+## First time setup
+
+### Puppeteer
+
+Puppeteer is used to create screenshots, it requires chromium to be installed on your machine
+
+- install chromium using brew:
+
+  `brew install chromium`
+- check the chromium path, should point to /opt/homebrew/bin/chromium:
+
+  `which chromium`
+- export out the path:
+
+  export PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
+
+  export PUPPETEER_EXECUTABLE_PATH=\`which chromium\`
+
+- So you don't have to retype this in the future, save to your shell rc file like .bashrc or .zshrc:
+
+  echo 'export PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true' >> ~/.zshrc
+
+  echo 'export PUPPETEER_EXECUTABLE_PATH=\`which chromium\`' >> ~/.zshrc 
+
+### Init documentation project
+
+To get started, you can scaffold out a sample extension docs setup:
+
+`npx pf-docs-framework init --name "My extension"`
+
+If you also want to add relevant script targets to package.json, pass in `--scripts` as well:
+
+`npx pf-docs-framework init --name "My extension" --scripts`
+
+## Usage
+
+For all CLI options, run `npx pf-docs-framework --help`
+
+For individual CLI commands, you can also display more information by running `npx pf-docs-framework <COMMAND> --help`
+
+### Develop docs
+
+`yarn docs:develop`
+
+or
+
+`npx pf-docs-framework start`
+
+### Build docs
+
+`yarn docs:build`
+
+or
+
+`npx pf-docs-framework build all --output public`
+
+> NOTE: If you have `sideEffects: false` in your package.json, that will prevent the CSS from loading in the documentation production build. Set it to true or remove it to enable the CSS from being loaded.
+
+### Generate screenshots
+
+You can generate screenshots against development or production builds.
+
+- Development:
+
+  Terminal 1:
+
+  `yarn docs:develop` or `npx pf-docs-framework start` (Take note of the port it started on, you can modify it in patternfly-docs.config)
+
+  Terminal 2:
+
+  `yarn docs:screenshots` or `npx pf-docs-framework screenshots --urlPrefix http://localhost:<PORT>`
+
+- Production:
+
+  Terminal 1:
+  
+  - `yarn docs:build` or `npx pf-docs-framework build all --output public`
+  - `yarn docs:serve` or `npx pf-docs-framework serve public --port 5000`
+
+  Terminal 2:
+
+  `yarn docs:screenshots` or `npx pf-docs-framework screenshots --urlPrefix http://localhost:5000`

package/app.js

@@ -0,0 +1,118 @@
+import React from 'react';
+import ReactDOM from 'react-dom';
+import { Router, useLocation } from '@reach/router';
+import { SideNavLayout } from '@patternfly/documentation-framework/layouts';
+import { Footer } from '@patternfly/documentation-framework/components';
+import { MDXTemplate } from '@patternfly/documentation-framework/templates/mdx';
+import { routes, groupedRoutes, fullscreenRoutes, getAsyncComponent } from './routes';
+import { trackEvent } from './helpers';
+import 'client-styles'; // Webpack replaces this import: patternfly-docs.css.js
+import './components/autoLinkHeader/autoLinkHeader.css';
+import './components/cssVariables/cssVariables.css';
+import './components/tableOfContents/tableOfContents.css';
+import './components/example/example.css';
+import './components/footer/footer.css';
+import './components/sideNav/sideNav.css';
+import './components/topNav/topNav.css';
+import './layouts/sideNavLayout/sideNavLayout.css';
+
+const AppRoute = ({ child, katacodaLayout, title, path }) => {
+  const pathname = useLocation().pathname;
+  if (typeof window !== 'undefined' && window.gtag) {
+    gtag('config', 'UA-47523816-6', {
+      'page_path': pathname,
+      'page_title': (title || pathname)
+    });
+  }
+  // Send 404 event if redirected to 404 page
+  if (path === '/404' && pathname.split('/').pop() !== '404') {
+    trackEvent('404_redirect', 'redirect', pathname);
+  }
+  return (
+    <React.Fragment>
+      {child}
+      {!katacodaLayout && process.env.hasFooter && <Footer />}
+    </React.Fragment>
+  );
+}
+
+const SideNavRouter = () => {
+  const pathname = useLocation().pathname.replace(process.env.pathPrefix, '');
+  const navOpen = !routes[pathname] || !routes[pathname].katacodaLayout;
+  return (
+    <SideNavLayout groupedRoutes={groupedRoutes} navOpen={navOpen} >
+      <Router id="ws-page-content-router">
+        {Object.entries(routes)
+          .map(([path, { Component, title, sources, katacodaLayout }]) => Component
+            ? <AppRoute
+                key={path}
+                path={path}
+                default={path === '/404'}
+                child={<Component />}
+                katacodaLayout={katacodaLayout}
+                title={title}
+              />
+            : <AppRoute
+                key={path}
+                path={path + '/*'}
+                child={
+                  <MDXTemplate
+                    path={path}
+                    title={title}
+                    sources={sources}
+                  />
+                }
+                katacodaLayout={katacodaLayout}
+                title={title}
+              />
+          )
+        }
+      </Router>
+    </SideNavLayout>
+  );
+}
+
+const FullscreenComponent = ({ Component, title }) => {
+  const [isLoaded, setIsLoaded] = React.useState(false);
+  React.useEffect(() => {
+    Component.preload().then(() => setIsLoaded(true));
+  }, []);
+  const { examples = {} } = Component.getPageData();
+  const Example = examples[title];
+  return isLoaded ? <Example isFullscreen={false} isFullscreenPreview /> : <Component />;
+};
+
+// Export for SSR
+export const App = () => (
+  <Router basepath={process.env.pathPrefix} id="ws-router">
+    <SideNavRouter path="/*" />
+    {Object.entries(fullscreenRoutes)
+      .map(([path, { title, Component }]) =>
+        <FullscreenComponent
+          key={path}
+          path={path}
+          Component={Component}
+          title={title}
+        />
+      )
+    }
+  </Router>
+);
+
+const isProd = process.env.NODE_ENV === 'production';
+const isPrerender = process.env.PRERENDER;
+// Don't use ReactDOM in SSR
+if (!isPrerender) {
+  function render() {
+    const renderFn = isProd ? ReactDOM.hydrate : ReactDOM.render;
+    renderFn(<App />, document.getElementById('root'));
+  }
+  // On first load, await promise for the current page to avoid flashing a "Loading..." state
+  const Component = getAsyncComponent(null);
+  if (Component) {
+    Component.preload().then(render);
+  }
+  else {
+    render();
+  }
+}

package/assets/manifest.json

@@ -0,0 +1,29 @@
+{
+  "name": "PatternFly docs",
+  "short_name": "PatternFly docs",
+  "description": "Home of PatternFly Design.",
+  "dir": "auto",
+  "lang": "en-US",
+  "display": "standalone",
+  "orientation": "any",
+  "start_url": "/",
+  "background_color": "#4F5255",
+  "theme_color": "#151515",
+  "icons": [
+    {
+      "src": "/assets/android-chrome-36x36.png",
+      "sizes": "36x36",
+      "type": "image/png"
+    },
+    {
+      "src": "/assets/android-chrome-48x48.png",
+      "sizes": "48x48",
+      "type": "image/png"
+    },
+    {
+      "src": "/assets/android-chrome-96x96.png",
+      "sizes": "96x96",
+      "type": "image/png"
+    }
+  ]
+}

package/components/autoLinkHeader/autoLinkHeader.css

@@ -0,0 +1,22 @@
+.ws-heading {
+  position: relative;
+}
+
+.ws-heading-anchor {
+  color: var(--pf-global--Color--100);
+  transform: translate(calc(-100% - var(--pf-global--spacer--xs)), -50%);
+  opacity: 0;
+  position: absolute;
+  left: 0;
+  top: 50%;
+}
+
+.ws-heading-anchor-icon {
+  height: 0.5em;
+  width: 0.5em;
+}
+
+.ws-heading:hover .ws-heading-anchor,
+.ws-heading-anchor:focus {
+  opacity: 1;
+}

package/components/autoLinkHeader/autoLinkHeader.js

@@ -0,0 +1,41 @@
+import React from 'react';
+import { Title } from '@patternfly/react-core';
+import LinkIcon from '@patternfly/react-icons/dist/esm/icons/link-icon';
+import { Link } from '../link/link';
+import { slugger } from '../../helpers/slugger';
+
+// "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl"
+const sizes = {
+  h1: '3xl',
+  h2: '2xl',
+  h3: 'xl',
+  h4: 'lg',
+  h5: 'md',
+  h6: 'sm'
+}
+
+export const AutoLinkHeader = ({
+  id,
+  size,
+  headingLevel,
+  children,
+  metaText,
+  className
+}) => {
+  const slug = id || slugger(children);
+
+  return (
+    <Title
+      id={slug}
+      size={sizes[size]}
+      headingLevel={headingLevel || size}
+      className={`ws-heading ${className}`}
+      tabIndex={-1}
+    >
+      <Link href={`#${slug}`} className="ws-heading-anchor" tabIndex="-1" aria-hidden>
+        <LinkIcon className="ws-heading-anchor-icon" style={{ verticalAlign: 'middle' }} />
+      </Link>
+      {children} {metaText}
+    </Title>
+  )
+};

package/components/cssVariables/cssSearch.js

@@ -0,0 +1,32 @@
+import React from "react";
+import { TextInput } from "@patternfly/react-core";
+
+export class CSSSearch extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = {
+      filterValue: ""
+    };
+  }
+
+  onFilterChange = (_change, event) => {
+    this.setState(
+      {
+        filterValue: event.target.value
+      },
+      () => this.props.getDebouncedFilteredRows(this.state.filterValue)
+    );
+  };
+
+  render() {
+    return (
+      <TextInput
+        type="text"
+        aria-label="Filter CSS Variables"
+        placeholder="Filter CSS Variables"
+        value={this.state.filterValue}
+        onChange={this.onFilterChange}
+      />
+    );
+  }
+}

package/components/cssVariables/cssVariables.css

@@ -0,0 +1,15 @@
+.ws-color-box {
+  display: inline-block;
+  height: 18px;
+  width: 18px;
+  border: var(--pf-global--BorderWidth--sm) solid var(--pf-global--BorderColor--200);
+  border-radius: var(--pf-global--BorderRadius--lg);
+}
+
+.ws-td-text {
+  font-size: var(--pf-global--FontSize--sm) !important;
+}
+
+.ws-css-property {
+  padding: var(--pf-global--spacer--xs) var(--pf-global--spacer--md);
+}

package/components/cssVariables/cssVariables.js

@@ -0,0 +1,233 @@
+import React from "react";
+import { debounce } from "@patternfly/react-core";
+import {
+  Table,
+  TableHeader,
+  TableBody,
+  sortable,
+  SortByDirection,
+  expandable
+} from "@patternfly/react-table";
+import * as tokensModule from "@patternfly/react-tokens/dist/esm/componentIndex";
+import global_spacer_md from "@patternfly/react-tokens/dist/esm/global_spacer_md";
+import LevelUpAltIcon from "@patternfly/react-icons/dist/esm/icons/level-up-alt-icon";
+import { CSSSearch } from './cssSearch';
+
+const isColorRegex = /^(#|rgb)/;
+
+const mappingAsList = (property, values) => (
+  <div>
+    <div className="ws-css-property">
+      <span>
+        {property}
+      </span>
+    </div>
+    {values.map((entry, index) => (
+      <div
+        key={index}
+        style={{
+          padding: `4px 0 4px calc(${global_spacer_md.value} * ${index + 3})`
+        }}
+      >
+        <LevelUpAltIcon style={{ transform: 'rotate(90deg)' }} />
+        <span style={{ paddingLeft: '16px' }}>
+          {entry}
+        </span>
+      </div>
+    ))}
+  </div>
+);
+
+const flattenList = files => {
+  let list = [];
+  files.forEach(file => {
+    Object.entries(file).forEach(([selector, values]) => {
+      Object.entries(values).forEach(([key, val]) => {
+        list.push({
+          selector,
+          property: val.name,
+          token: key,
+          value: val.value,
+          values: val.values
+        });
+      });
+    });
+  });
+  return list;
+};
+
+export class CSSVariables extends React.Component {
+  constructor(props) {
+    super(props);
+    // Ensure array in case of multiple prefixes
+    this.prefix =
+      typeof props.prefix === "string" ? [props.prefix] : props.prefix;
+    const prefixTokens = this.prefix.map(prefix => prefix.replace("pf-", "").replace(/-+/g, "_"));
+    const applicableFiles = Object.entries(tokensModule)
+      .filter(([key, val]) => prefixTokens.includes(key))
+      .sort(([key1], [key2]) => key1.localeCompare(key2))
+      .map(([key, val]) => {
+        if (props.selector) {
+          return {
+            [props.selector]: val[props.selector]
+          }
+        }
+        return val;
+      });
+
+    this.flatList = flattenList(applicableFiles);
+
+    this.columns = [
+      ...props.hideSelectorColumn ? [] : [{
+         title: "Selector",
+         transforms: [sortable],
+         cellFormatters: [expandable]
+      }],
+      { title: "Variable", transforms: [sortable] },
+      { title: "Value", transforms: [sortable] }
+    ]
+
+    this.state = {
+      searchRE: '',
+      rows: this.getFilteredRows(),
+      sortBy: {
+        index: 0,
+        direction: "asc" // a-z
+      }
+    };
+  }
+
+  getFilteredRows = (searchRE) => {
+    let filteredRows = [];
+    let rowNumber = -1;
+    this.flatList.forEach(row => {
+      const { selector, property, token, value, values} = row;
+      const passes =
+        !searchRE ||
+        searchRE.test(selector) ||
+        searchRE.test(property) ||
+        searchRE.test(value) ||
+        (values && searchRE.test(JSON.stringify(values)));
+      if (passes) {
+        const rowKey = `${selector}_${property}`;
+        const cells = [
+          ...this.props.hideSelectorColumn ? [] : [selector],
+          property,
+          <div key={rowKey}>
+            <div
+              key={`${rowKey}_1`}
+              className="pf-l-flex pf-m-space-items-sm"
+            >
+              {isColorRegex.test(value) && (
+                <div
+                  key={`${rowKey}_2`}
+                  className="pf-l-flex pf-m-column pf-m-align-self-center"
+                >
+                  <span
+                    className="ws-color-box"
+                    style={{ backgroundColor: value }}
+                  />
+                </div>
+              )}
+              <div
+                key={`${rowKey}_3`}
+                className="pf-l-flex pf-m-column pf-m-align-self-center ws-td-text"
+              >
+                {value}
+              </div>
+            </div>
+          </div>
+        ];
+        filteredRows.push({
+          isOpen: values ? false : undefined,
+          cells
+        });
+        rowNumber += 1;
+        if (values) {
+          filteredRows.push({
+            parent: rowNumber,
+            fullWidth: true,
+            cells: [
+              {
+                title: mappingAsList(property, values)
+              }
+            ]
+          });
+          rowNumber += 1;
+        }
+      }
+    });
+    return filteredRows;
+  };
+
+  onCollapse = (event, rowKey, isOpen) => {
+    const { rows } = this.state;
+    const collapseAll = rowKey === undefined;
+    let newRows = Array.from(rows);
+
+    if (collapseAll) {
+      newRows = newRows.map(r => (r.isOpen === undefined ? r : { ...r, isOpen }));
+    } else {
+      newRows[rowKey] = { ...newRows[rowKey], isOpen };
+    }
+    this.setState({
+      rows: newRows,
+    });
+  };
+
+  getDebouncedFilteredRows = debounce(value => {
+    const searchRE = new RegExp(value, "i");
+    this.setState({
+      searchRE,
+      rows: this.getFilteredRows(searchRE)
+    });
+  }, 500);
+
+  onSort = (_event, index, direction) => {
+    this.flatList = this.flatList.sort((a, b) => {
+      const indexToColMap = {
+        '1': 'selector',
+        '2': 'property',
+        '3': 'value'
+      };
+      const column = indexToColMap[index];
+      if (direction === SortByDirection.asc) {
+        return a[column] < b[column] ? -1 : a[column] > b[column] ? 1 : 0;
+      } else {
+        return a[column] > b[column] ? -1 : a[column] < b[column] ? 1 : 0;
+      }
+    });
+    this.setState({
+      sortBy: {
+        index,
+        direction
+      },
+      rows: this.getFilteredRows(this.state.searchRE)
+    });
+  };
+
+  render() {
+    return (
+      <React.Fragment>
+        <CSSSearch getDebouncedFilteredRows={this.getDebouncedFilteredRows} />
+        <Table
+          variant="compact"
+          aria-label={`CSS Variables for prefixes ${this.prefix.join(" ")}`}
+          sortBy={this.state.sortBy}
+          onSort={this.onSort}
+          cells={this.columns}
+          rows={this.state.rows}
+          onCollapse={this.onCollapse}
+          canCollapseAll={true}
+          collapseAllAriaLabel="expand all css variables"
+          gridBreakPoint="grid-lg"
+          contentId="css-variables-content"
+          expandId="css-variables-toggle"
+        >
+          <TableHeader />
+          <TableBody />
+        </Table>
+      </React.Fragment>
+    );
+  }
+}