From 1528d05ed9efa0704978297ffed9759d20108da1 Mon Sep 17 00:00:00 2001 From: Scott Weber Date: Wed, 9 Dec 2020 10:10:52 -0500 Subject: [PATCH] [WNMGDS-532] Add CMSDS core link for child design systems (#890) * add cmsds flag to documentation * Update doc site header to add cmsds link flag * Add status badges to all component pages * Update maturity colors * Update comment in KSS process file * Updates to generate and unique pages * add CMSDS URL to components and patterns only * remove ready staus from pages * remove ready status badges * remove CMSDS flag from guides * Update _List.docs.scss * Update _MonthPicker.docs.scss * Update _VerticalNav.docs.scss * Update generate pages PR feedback * Update page header links * content feedback * Updates to page header * header update * Update page header - PR feedback * Update page header for uswds link only option * Remove cmsds flag option * Update comments - PR feedback * Clean up file - PR feedback * simplify page header * PR feedback * remove cmsds from content flags * Removing extra space Co-authored-by: Bernard --- .../pages/guidelines/component-maturity.md | 4 +- .../src/scripts/components/PageHeader.jsx | 58 +++++++++++-------- .../gulp/docs/generatePages/generatePages.js | 42 ++++++++++---- .../gulp/docs/generatePages/uniquePages.js | 5 +- 4 files changed, 72 insertions(+), 37 deletions(-) diff --git a/packages/design-system-docs/src/pages/guidelines/component-maturity.md b/packages/design-system-docs/src/pages/guidelines/component-maturity.md index c8ae8b36cf..a48f4ce9b2 100644 --- a/packages/design-system-docs/src/pages/guidelines/component-maturity.md +++ b/packages/design-system-docs/src/pages/guidelines/component-maturity.md @@ -11,13 +11,13 @@ Each component in the design system is tested and validated before deciding on t - Coding guidelines are met - Testing and validation is complete -##    Draft +##    Draft - **Do not implement** - Documentation and guidance is incomplete - Testing and validation is incomplete - Could be buggy or have accessibility issues -##    Deprecated +##    Deprecated - **Do not use** diff --git a/packages/design-system-docs/src/scripts/components/PageHeader.jsx b/packages/design-system-docs/src/scripts/components/PageHeader.jsx index 88421a2493..dfd5008fe9 100644 --- a/packages/design-system-docs/src/scripts/components/PageHeader.jsx +++ b/packages/design-system-docs/src/scripts/components/PageHeader.jsx @@ -3,21 +3,13 @@ import React from 'react'; import classNames from 'classnames'; class PageHeader extends React.PureComponent { - uswdsLink() { - if (this.props.uswds) { - return View related U.S. Web Design Standard; - } - } - statusBadge() { if (this.props.status) { - const classes = classNames( - 'ds-c-badge ds-u-margin-right--1 ds-u-text-transform--capitalize', - { - 'ds-c-badge--success': this.props.status === 'Ready', - 'ds-c-badge--alert': this.props.status === 'Draft', - } - ); + const classes = classNames('ds-c-badge ds-u-margin-left--1 ds-u-text-transform--capitalize', { + 'ds-c-badge--success': this.props.status === 'Ready', + 'ds-c-badge--warn': this.props.status === 'Draft', + 'ds-c-badge--error': this.props.status === 'Deprecated', + }); return {this.props.status}; } @@ -33,22 +25,39 @@ class PageHeader extends React.PureComponent { } } + designSystemLinks() { + const cmsdsLink = this.props.cmsds && CMS Design System; + const uswdsLink = this.props.uswds && U.S. Web Design System; + + if (this.props.cmsds && this.props.uswds) { + return ( + + View related guidance in the {cmsdsLink} and {uswdsLink} + + ); + } else if (this.props.cmsds) { + return View related guidance in the {cmsdsLink}; + } else if (this.props.uswds) { + return View related guidance in the {uswdsLink}; + } else { + } + } + render() { return (
-

-
-
+
+

{this.statusBadge()} - +

+
{this.guidanceLink()} - - {this.uswdsLink()} + {this.designSystemLinks()}

); @@ -56,6 +65,7 @@ class PageHeader extends React.PureComponent { } PageHeader.propTypes = { + cmsds: PropTypes.string, header: PropTypes.string.isRequired, reference: PropTypes.string, status: PropTypes.string, diff --git a/packages/design-system-scripts/gulp/docs/generatePages/generatePages.js b/packages/design-system-scripts/gulp/docs/generatePages/generatePages.js index e2f9d8e0b4..56d9cfb784 100644 --- a/packages/design-system-scripts/gulp/docs/generatePages/generatePages.js +++ b/packages/design-system-scripts/gulp/docs/generatePages/generatePages.js @@ -116,6 +116,18 @@ function changedFilter(page, changedPath) { return true; } +// Add a `cmsds` property to component and pattern page sections originating from the `@cmsgov/design-system-docs` NPM package. +// This automatically populates a link to the CMSDS for child design system components and patterns. +function addCmsdsLink(page) { + if ( + page.source.path.includes('node_modules/@cmsgov/design-system-docs/src/pages/components') || + page.source.path.includes('node_modules/@cmsgov/design-system-docs/src/pages/patterns') + ) { + page.cmsds = `https://design.cms.gov/${page.referenceURI}`; + } + return page; +} + /** * Loop through the nested array of pages and create an HTML file for each one. * These HTML pages are what get published as the public documentation website. @@ -200,29 +212,39 @@ module.exports = async function generatePages(sourceDir, docsDir, options, chang processKssSection(kssSection, options) ) ); + // Combine KSS and Markdown page sections and add cmsds links to for child design systems + const pageSections = markdownSections.concat(kssSections).map((section) => addCmsdsLink(section)); - // Merge both sets of page sections into a single array. // Remove pages with the same URL (so child design systems can override existing pages) // Hide sections and pages with the `hide-section` flag - const pages = uniquePages(markdownSections.concat(kssSections)).filter( - (page) => !page.hideSection - ); + const uniquePageSections = uniquePages(pageSections).filter((page) => !page.hideSection); // Add react prop and example data to page sections - await addReactData(pages); + await addReactData(uniquePageSections); - // Add top-level pages and connect the page sections to their parent pages - const nestedPages = await addTopLevelPages(pages).then(nestSections); + // Add missing top-level pages and connect the page parts to their parent pages + // TODO: remove need to nest pages, or generate from unnested pages + const nestedPageSections = await addTopLevelPages(uniquePageSections).then(nestSections); - // Create HTML files for example and doc pages const docsPath = path.join(docsDir, 'dist'); - const examplePages = await generateExamplePages(pages, docsPath, sourceDir, options, changedPath); + + // Create HTML files for example pages + const examplePages = await generateExamplePages( + uniquePageSections, + docsPath, + sourceDir, + options, + changedPath + ); + if (changedPath && examplePages > 0) { logTask('📝 ', `Example page updated from ${changedPath}`); } else if (!changedPath) { logTask('📝  ' + examplePages, `Example pages added to ${docsDir}`); } - const docPages = await generateDocPages(nestedPages, docsPath, options, changedPath); + + // Create HTML files for doc pages + const docPages = await generateDocPages(nestedPageSections, docsPath, options, changedPath); if (changedPath && docPages > 0) { logTask('📝 ', `Doc page updated from ${changedPath}`); } else if (!changedPath) { diff --git a/packages/design-system-scripts/gulp/docs/generatePages/uniquePages.js b/packages/design-system-scripts/gulp/docs/generatePages/uniquePages.js index 2b7ef9734a..561e41e33a 100644 --- a/packages/design-system-scripts/gulp/docs/generatePages/uniquePages.js +++ b/packages/design-system-scripts/gulp/docs/generatePages/uniquePages.js @@ -11,8 +11,11 @@ function uniquePages(pages) { pages.forEach((page) => { if (routes[page.reference]) { if (routes[page.reference].source.path.match(/node_modules/)) { - // We override pages that come from `node_modules` + // We override pages that come from node_modules with pages from the child design system logTask('🖊 ', `Overriding ${page.reference || 'index'} page with ${page.source.path}`); + // Preserves the `cmsds` property created by `addCmsdsLink()` when overriding + // Even when a page is overridden by a child design system, we want to show the CMSDS link + page.cmsds = routes[page.reference].cmsds; routes[page.reference] = page; } else { logTask(