@patternfly/documentation-framework 2.0.0-alpha.42 → 2.0.0-alpha.43

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 2.0.0-alpha.43 (2023-05-25)
+
+
+### Features
+
+* **labels:** add deprecated/demo/beta labels to headers + nav items ([#3547](https://github.com/patternfly/patternfly-org/issues/3547)) ([010a0e0](https://github.com/patternfly/patternfly-org/commit/010a0e05baea661964660d2a733569a34abbf243))
+
+
+
+
+
 # 2.0.0-alpha.42 (2023-05-18)
 
 **Note:** Version bump only for package @patternfly/documentation-framework

package/components/autoLinkHeader/autoLinkHeader.js

@@ -1,5 +1,5 @@
 import React from 'react';
-import { Title } from '@patternfly/react-core';
+import { Title, Flex, FlexItem } 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';
@@ -25,17 +25,22 @@ export const AutoLinkHeader = ({
   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>
+    <Flex alignItems={{ default: 'alignItemsCenter'}} spaceItems={{ default: 'spaceItemsNone' }}>
+      <FlexItem>
+        <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}
+        </Title>
+      </FlexItem>
+      <FlexItem>  {metaText}</FlexItem>
+    </Flex>
   )
 };

package/components/cssVariables/cssVariables.js

@@ -8,6 +8,7 @@ import {
   Tbody,
   Td
 } from "@patternfly/react-table";
+import { AutoLinkHeader } from "../autoLinkHeader/autoLinkHeader";
 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";
@@ -59,12 +60,9 @@ const flattenList = files => {
 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 prefixToken = props.prefix.replace("pf-v5-", "").replace(/-+/g, "_");
     const applicableFiles = Object.entries(tokensModule)
-      .filter(([key, val]) => prefixTokens.includes(key))
+      .filter(([key, val]) => prefixToken === key)
       .sort(([key1], [key2]) => key1.localeCompare(key2))
       .map(([key, val]) => {
         if (props.selector) {
@@ -170,10 +168,11 @@ export class CSSVariables extends React.Component {
   render() {
     return (
       <React.Fragment>
+        {this.props.autoLinkHeader && <AutoLinkHeader size="h3" className="pf-v5-u-mt-lg pf-v5-u-mb-md">{`Prefixed with '${this.props.prefix}'`}</AutoLinkHeader>}
         <CSSSearch getDebouncedFilteredRows={this.getDebouncedFilteredRows} />
         <Table
           variant="compact"
-          aria-label={`CSS Variables for prefixes ${this.prefix.join(" ")}`}
+          aria-label={`CSS Variables prefixed with ${this.props.prefix}`}
         >
           <Thead>
             <Tr>

package/components/example/example.js

@@ -1,6 +1,6 @@
 import React from 'react';
 import { useLocation } from '@reach/router';
-import { Badge, CodeBlock, CodeBlockCode, debounce, Switch } from '@patternfly/react-core';
+import { Button, CodeBlock, CodeBlockCode, debounce, Label, Switch, Tooltip } from '@patternfly/react-core';
 import * as reactCoreModule from '@patternfly/react-core';
 import * as reactCoreNextModule from '@patternfly/react-core/next';
 import * as reactCoreDeprecatedModule from '@patternfly/react-core/deprecated';
@@ -71,7 +71,11 @@ export const Example = ({
   // The image src thumbnail for the example
   thumbnail = missingThumbnail,
   // Whether the example shows demo capability
+  isDemo,
+  // Whether the example is open to further evolution
   isBeta,
+  // Whether the example is deprecated
+  isDeprecated,
   // Slugified source + title
   id,
   // Section in frontmatter of MD file (components, demos, etc)
@@ -173,12 +177,36 @@ export const Example = ({
     + (loc.pathname.endsWith(source) ? '' : `/${source}`)
     + '/'
     + slugger(title);
-    
+
   return (
     <div className="ws-example">
       <div className="ws-example-header">
         <AutoLinkHeader
-          metaText={isBeta && <Badge className="ws-beta-badge pf-v5-u-ml-xs">Beta</Badge>}
+          metaText={
+            <React.Fragment>
+              {isBeta && (
+                <Tooltip content="This beta component is currently under review and is still open for further evolution.">
+                  <Button variant="plain">
+                    <Label isCompact color="blue">Beta</Label>
+                  </Button>
+                </Tooltip>
+              )}
+              {isDemo && (
+                <Tooltip content="Demos show how multiple components can be used in a single design.">
+                  <Button variant="plain">
+                    <Label isCompact color="purple">Demo</Label>
+                  </Button>
+                </Tooltip>
+              )}
+              {isDeprecated && (
+                <Tooltip content="Deprecated components are available for use but are no longer being maintained or enhanced.">
+                  <Button variant="plain">
+                    <Label isCompact color="grey">Deprecated</Label>
+                  </Button>
+                </Tooltip>
+              )}
+            </React.Fragment>
+          }
           size="h4"
           headingLevel="h3"
           className="ws-example-heading"

package/components/sideNav/sideNav.js

@@ -1,6 +1,6 @@
 import React from 'react';
 import { Link } from '../link/link';
-import { Nav, NavList, NavExpandable, PageContextConsumer, capitalize } from '@patternfly/react-core';
+import { Label, Nav, NavList, NavExpandable, PageContextConsumer, capitalize, Flex, FlexItem } from '@patternfly/react-core';
 import { css } from '@patternfly/react-styles';
 import { Location } from '@reach/router';
 import { makeSlug } from '../../helpers';
@@ -14,7 +14,7 @@ const getIsActive = (location, section, subsection = null) => {
 
 const defaultValue = 50;
 
-const NavItem = ({ text, href }) => {
+const NavItem = ({ text, href, isDeprecated, isBeta, isDemo }) => {
   const isMobileView = window.innerWidth < Number.parseInt(globalBreakpointXl.value, 10);
   return (
     <PageContextConsumer key={href + text}>
@@ -33,7 +33,18 @@ const NavItem = ({ text, href }) => {
               }
               tabIndex={isNavOpen ? undefined : -1}
             >
-              {text}
+              <Flex spaceItems={{ default: 'spaceItemsSm'}}>
+                <FlexItem>{text}</FlexItem>
+                {(isBeta || isDemo || isDeprecated) && (
+                  <FlexItem>
+                    {isBeta && (<Label color="blue" isCompact>Beta</Label>)}
+                    {!isBeta && isDemo && (<Label color="purple" isCompact>Demo</Label>)}
+                    {!isBeta && !isDemo && isDeprecated && (<Label color="grey" isCompact>Deprecated</Label>)}
+                  </FlexItem>
+                )}
+              </Flex>
+
+
             </Link>
           </li>
       )}
@@ -70,7 +81,7 @@ const ExpandableNav = ({groupedRoutes, location, section, subsection = null}) =>
     >
       {Object.entries(routes || {})
         .filter(([id, navObj]) => !Boolean(navObj.hideNavItem) && (Object.entries(navObj).length > 0))
-        .map(([id, { slug, isSubsection = false, sortValue = defaultValue, subsectionSortValue = defaultValue }]) => ({ text: id, href: slug, isSubsection, sortValue: (isSubsection ? subsectionSortValue : sortValue) }))
+        .map(([id, { slug, isSubsection = false, sortValue = defaultValue, subsectionSortValue = defaultValue, sources }]) => ({ text: id, href: slug, isSubsection, sortValue: (isSubsection ? subsectionSortValue : sortValue), sources }))
         .sort(({text: text1, sortValue: sortValue1}, {text: text2, sortValue: sortValue2}) => {
           if (sortValue1 === sortValue2) {
             return text1.localeCompare(text2);
@@ -78,10 +89,14 @@ const ExpandableNav = ({groupedRoutes, location, section, subsection = null}) =>
           return sortValue1 > sortValue2 ? 1 : -1;
         })
         .map(navObj => navObj.isSubsection
-          ? ExpandableNav({groupedRoutes, location, section, subsection: navObj.text})
-          : NavItem(navObj)
-        )
-      }
+            ? ExpandableNav({groupedRoutes, location, section, subsection: navObj.text})
+            : NavItem({
+              ...navObj,
+              isDeprecated: navObj.href?.includes('components') && navObj.sources.some(source => source.source === "react-deprecated") && !navObj.sources.some(source => source.source === "react"),
+              isBeta: navObj.sources.some(source => source.beta),
+              isDemo: navObj.sources.some(source => source.source === "react-demos" || source.source === "html-demos") && !navObj.sources.some(source => source.source === "react" || source.source === "html")
+            })
+        )}
     </NavExpandable>
   );
 }
@@ -101,7 +116,7 @@ export const SideNav = ({ groupedRoutes = {}, navItems = [] }) => {
       lastElement.scrollIntoView({ block: 'center' });
     }
   }, []);
-  
+
   return (
     <Nav aria-label="Side Nav" theme="light">
       <NavList className="ws-side-nav-list">

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@patternfly/documentation-framework",
   "description": "A framework to build documentation for PatternFly.",
-  "version": "2.0.0-alpha.42",
+  "version": "2.0.0-alpha.43",
   "author": "Red Hat",
   "license": "MIT",
   "private": false,
@@ -84,12 +84,12 @@
     "webpack-merge": "5.8.0"
   },
   "peerDependencies": {
-    "@patternfly/patternfly": "^5.0.0-alpha.46",
-    "@patternfly/react-code-editor": "^5.0.0-alpha.92",
-    "@patternfly/react-core": "^5.0.0-alpha.91",
-    "@patternfly/react-table": "^5.0.0-alpha.93",
+    "@patternfly/patternfly": "^5.0.0-alpha.64",
+    "@patternfly/react-code-editor": "^5.0.0-alpha.116",
+    "@patternfly/react-core": "^5.0.0-alpha.115",
+    "@patternfly/react-table": "^5.0.0-alpha.117",
     "react": "^17.0.0 || ^18.0.0",
     "react-dom": "^17.0.0 || ^18.0.0"
   },
-  "gitHead": "7eded2969b48b703c735b3848daa36707b692571"
+  "gitHead": "0292205a8574246ff10efc08997d4950bcddf1b0"
 }

package/routes.js

@@ -78,10 +78,8 @@ const groupedRoutes = Object.entries(routes)
 const sourceOrder = {
   react: 1,
   'react-next': 1.1,
-  'react-composable': 1.2,
-  'react-deprecated': 1.3,
-  'react-legacy': 1.4,
   'react-demos': 2,
+  'react-deprecated': 2.1,
   html: 3,
   'html-demos': 4,
   'design-guidelines': 99,

package/scripts/md/parseMD.js

@@ -104,6 +104,10 @@ function toReactComponent(mdFilePath, source, buildMode) {
         id: frontmatter.id,
         section: frontmatter.section || '',
         subsection: frontmatter.subsection || '',
+        deprecated: frontmatter.deprecated || false,
+        beta: frontmatter.beta || false,
+        demo: frontmatter.demo || false,
+        newImplementationLink: frontmatter.newImplementationLink || false,
         source,
         tabName: frontmatter.tabName || null,
         slug,
@@ -133,9 +137,6 @@ function toReactComponent(mdFilePath, source, buildMode) {
       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
@@ -293,6 +294,8 @@ function sourceMDFile(file, source, buildMode) {
       tabName: pageData.tabName,
       ...(pageData.hideNavItem && { hideNavItem: pageData.hideNavItem }),
       ...(pageData.beta && { beta: pageData.beta }),
+      ...(pageData.deprecated && { deprecated: pageData.deprecated }),
+      ...(pageData.demo && { demo: pageData.demo }),
       ...(pageData.sortValue && { sortValue: pageData.sortValue }),
       ...(pageData.subsectionSortValue && { subsectionSortValue: pageData.subsectionSortValue })
     };

package/templates/mdx.js

@@ -1,5 +1,5 @@
 import React from 'react';
-import { PageSection, Title, PageSectionVariants, BackToTop, PageGroup, Page, Text, TextContent } from '@patternfly/react-core';
+import { PageSection, Title, Tooltip, PageSectionVariants, Button, BackToTop, Flex, FlexItem, PageGroup, Page, Text, TextContent, Label } from '@patternfly/react-core';
 import { css } from '@patternfly/react-styles';
 import ExternalLinkAltIcon from '@patternfly/react-icons/dist/esm/icons/external-link-alt-icon';
 import { Router, useLocation } from '@reach/router';
@@ -22,6 +22,8 @@ const MDXChildTemplate = ({
     cssPrefix = [],
     optIn,
     beta,
+    deprecated,
+    newImplementationLink,
     functionDocumentation = []
   } = Component.getPageData();
   const cssVarsTitle = cssPrefix.length > 0 && 'CSS variables';
@@ -32,6 +34,9 @@ const MDXChildTemplate = ({
   }
   if (cssVarsTitle && !toc.find(item => item.text === cssVarsTitle)) {
     toc.push({ text: cssVarsTitle });
+    if (cssPrefix.length > 1) {
+      toc.push(cssPrefix.map(cssPrefix => ({ text: `Prefixed with '${cssPrefix}'` })));
+    }
   }
   // We don't add `id`s in anchor-header.js for items where id === slugger(text)
   // in order to save ~10KB bandwidth.
@@ -55,14 +60,22 @@ const MDXChildTemplate = ({
       )}
       {beta && (
         <InlineAlert title="Beta feature">
-          This beta component is currently under review and is still open for further evolution. It is available for use in product.
-          Beta components are considered for promotion on a quarterly basis. Please join in and give us your feedback or submit any questions on the <a href="https://forum.patternfly.org/">PatternFly forum</a> or via <a href="//slack.patternfly.org/" target="_blank" rel="noopener noreferrer">Slack</a>.
-          To learn more about the process, visit our <Link to="/get-started/about#beta-components">about page</Link> or our <a href="https://github.com/patternfly/patternfly-org/tree/main/beta-component-promotion">Beta components</a> page on GitHub.
+          This beta component is currently under review and is still open for further evolution. It is available for use in product. Beta components are considered for promotion on a quarterly basis. Please join in and give us your feedback or submit any questions on the <a href="https://forum.patternfly.org/">PatternFly forum</a> or via <a href="//slack.patternfly.org/" target="_blank" rel="noopener noreferrer">Slack</a>. To learn more about the process, visit our <Link to="/get-started/about#beta-components">about page</Link> or our <a href="https://github.com/patternfly/patternfly-org/tree/main/beta-component-promotion">Beta components</a> page on GitHub.
+        </InlineAlert>
+      )}
+      {(deprecated || source === 'react-deprecated') && (
+        <InlineAlert title="Deprecated feature" variant="warning">
+          This implementation has been deprecated in favor of a newer implementation, and is no longer getting maintained or enhanced.
+          {newImplementationLink && (
+            <React.Fragment>
+              You can find the <Link to={newImplementationLink}>updated implementation here</Link>.
+            </React.Fragment>
+          )}
+          {' '}To learn more about the process, visit our <Link to="/get-started/about#major-release-cadence">about page</Link>.
         </InlineAlert>
       )}
     </React.Fragment>
   );
-  console.log(id);
   // Create dynamic component for @reach/router
   const ChildComponent = () => (
     <div className="pf-v5-u-display-flex ws-mdx-child-template">
@@ -97,12 +110,14 @@ const MDXChildTemplate = ({
               ))}
             </React.Fragment>
           )}
-          {cssVarsTitle && (
+          {cssPrefix.length > 0 && (
             <React.Fragment>
               <AutoLinkHeader size="h2" className="ws-h2" id="css-variables">
                 {cssVarsTitle}
               </AutoLinkHeader>
-              <CSSVariables prefix={cssPrefix} />
+              {cssPrefix.map(prefix => (
+                <CSSVariables autoLinkHeader={cssPrefix.length > 1} prefix={prefix} />
+              ))}
             </React.Fragment>
           )}
           {sourceLink && (
@@ -126,6 +141,9 @@ export const MDXTemplate = ({
   id,
   componentsData
 }) => {
+  const isDeprecated = sources.some(source => source.source === "react-deprecated") && !sources.some(source => source.source === "react");
+  const isBeta = sources.some(source => source.beta)
+  const isDemo = sources.some(source => source.source === "react-demos" || source.source === "html-demos") && !sources.some(source => source.source === "react" || source.source === "html");
   // Build obj mapping source names to text displayed on tabs
   const tabNames = sources.reduce((acc, curSrc) => {
     const { source, tabName } = curSrc;
@@ -137,7 +155,7 @@ export const MDXTemplate = ({
   const sourceKeys = Object.keys(tabNames);
   const isSinglePage = sourceKeys.length === 1;
 
-  let isDevResources, isComponent, isExtension, isChart, isDemo, isLayout, isUtility;
+  let isDevResources, isComponent, isExtension, isChart, isPattern, isLayout, isUtility;
 
   const getSection = () => {
     return sources.some((source) => {
@@ -154,8 +172,8 @@ export const MDXTemplate = ({
         case "charts":
           isChart = true;
           return;
-        case "demos":
-          isDemo = true;
+        case "patterns":
+          isPattern = true;
           return;
         case "layouts":
           isLayout = true;
@@ -198,7 +216,7 @@ export const MDXTemplate = ({
         return "pf-m-light-100";
       }
       return "pf-m-light";
-    } else if (isUtility || isDemo || isLayout || isComponent) {
+    } else if (isUtility || isPattern || isLayout || isComponent) {
       return "pf-m-light";
     }
     return "pf-m-light-100";
@@ -208,10 +226,9 @@ export const MDXTemplate = ({
     (!isSinglePage && !hideTabName) ||
     isComponent ||
     isUtility ||
-    isDemo
+    isPattern
   );
 
-  console.log(id);
   return (
     <React.Fragment>
       <PageGroup>
@@ -221,7 +238,44 @@ export const MDXTemplate = ({
           isWidthLimited
         >
           <TextContent>
-            <Title headingLevel='h1' size='4xl' id="ws-page-title">{title}</Title>
+            <Flex alignItems={{ default: 'alignItemsCenter'}}>
+              <FlexItem>
+                <Title headingLevel='h1' size='4xl' id="ws-page-title">
+                  {title}
+                </Title>
+              </FlexItem>
+              <FlexItem>
+                <Flex display={{ default: 'inlineFlex' }}>
+                  {isDeprecated && (
+                    <FlexItem spacer={{ default: 'spacerSm' }}>
+                      <Tooltip content="Deprecated components are available for use but are no longer being maintained or enhanced.">
+                        <Button isInline component="span" variant="link">
+                          <Label color="grey">Deprecated</Label>
+                        </Button>
+                      </Tooltip>
+                    </FlexItem>
+                  )}
+                  {isDemo && (
+                    <FlexItem spacer={{ default: 'spacerSm' }}>
+                      <Tooltip content="Demos show how multiple components can be used in a single design.">
+                        <Button isInline component="span" variant="link">
+                          <Label color="purple">Demo</Label>
+                        </Button>
+                      </Tooltip>
+                    </FlexItem>
+                  )}
+                  {isBeta && (
+                    <FlexItem spacer={{ default: 'spacerSm' }}>
+                      <Tooltip content="This beta component is currently under review and is still open for further evolution.">
+                        <Button isInline component="span" variant="link">
+                          <Label color="blue">Beta</Label>
+                        </Button>
+                      </Tooltip>
+                    </FlexItem>
+                  )}
+                </Flex>
+              </FlexItem>
+            </Flex>
             {isComponent && summary && (<SummaryComponent />)}
           </TextContent>
         </PageSection>