Core/template docs (#1285)

* move narrow template theme styles * add build assets rush command * wip * add place holder * add reverse template and JS note * fix seal url in template * add doc * remove toolbar in story * fix links * add link to template doc from usage doc * add code template * Update packages/core/stories/styles/index.scss * Update packages/core/stories/styles/index.scss
massgov · Dec 3, 2020 · 59537ef · 59537ef
1 parent 946ef7f
commit 59537ef
Show file tree

Hide file tree

Showing 9 changed files with 199 additions and 3 deletions.
diff --git a/common/config/rush/command-line.json b/common/config/rush/command-line.json
@@ -11,6 +11,14 @@
    * "rush my-global-command --help".
    */
   "commands": [
+    {
+      "commandKind": "global",
+      "name": "build:assets",
+      "summary": "Runs 'rushx build' for the assets package.",
+      "safeForSimultaneousRushProcesses": true,
+      "allowWarningsInSuccessfulBuild": true,
+      "shellCommand": "cd packages/assets && rushx build"
+    },
     {
       "commandKind": "global",
       "name": "start:react",

diff --git a/packages/assets/scss/01-atoms/_place-holder.scss b/packages/assets/scss/01-atoms/_place-holder.scss
@@ -0,0 +1,8 @@
+.ma__placeholder {
+  color:#bbb;
+  min-height:200px;
+  border:4px dashed #ddd;
+  font-size:2rem;
+  line-height:200px;
+  text-align:center;
+}
diff --git a/packages/core/stories/about/Usage.stories.mdx b/packages/core/stories/about/Usage.stories.mdx
@@ -1,4 +1,8 @@
 import { Meta } from '@storybook/addon-docs/blocks';
+import { linkTo } from '@storybook/addon-links';
+import {
+  Button
+} from '@massds/mayflower-react';
 
 import generateTitle from '../util/generateTitle';
 const { STORYBOOK_CDN_PATH, STORYBOOK_CDN, STORYBOOK_PKG } = process.env;
@@ -105,9 +109,22 @@ For examples:
   </tr>
 </table>
 
+<br />
+
 ## Build with Mayflower
 
-To import fonts and get started with basic Mayflower layout CSS, import `scss/global.scss` (`@use scss/global.scss`) or link to the compiled `static/fonts/css/global.css` (or the minified version, global.min.css). To use a Mayflower branding component on your site, go to the documentation of the component and copy and paste the html and link to the CDN version of CSS and JS files in the head of your HTML. You can also host the CSS and JS downloaded from mayflower assets package.
+To start building with Mayflower in HTML, start by importing the global styles and then incrementally add the styles and JS for each Mayflower component:
+
+- To import fonts and get started with basic Mayflower styles, link to the compiled `css/global.css` (or the minified version, `css/global.min.css`) from the @massds/mayflower-assets package or the assets CDN.
+
+- To include basic page layout styles from Mayflower, link to the compiled `css/layout.css` (or the minified version, `css/layout.min.css`) from the @massds/mayflower-assets package or the assets CDN.
+
+- To use a Mayflower branding component on your site, go to the documentation of the component and copy and paste the HTML code snippet and link to the CDN version of CSS and JS files in the head of your HTML. You can also host the CSS and JS downloaded from mayflower assets package.
+
+To kickstart a web page with Mayflower Header, Footer, basic layout and styles:
+<Button theme="c-primary-alt" onClick={linkTo(generateTitle('Template'))}>Start From a Template</Button>
+
+<div className="sp--bottom"/>
 
 ## Configure Your Theme
 

diff --git a/packages/core/stories/components/Header/Header.stories.js b/packages/core/stories/components/Header/Header.stories.js
@@ -302,7 +302,7 @@ const notesHeaderSlim = `
 
 const notesHeader = `
   // Link to CSS: <link rel="stylesheet" href="${STORYBOOK_CDN_PATH}/css/header.css">
-  // Link to JS: <script type="text/javascript" src="${STORYBOOK_CDN_PATH}/js/heading.js" />
+  // Link to JS: <script type="text/javascript" src="${STORYBOOK_CDN_PATH}/js/header.js" />
 `
 
 export const headerExample = () => headerBasic;

diff --git a/packages/core/stories/components/Template/Template.stories.js b/packages/core/stories/components/Template/Template.stories.js
@@ -0,0 +1,100 @@
+import { Meta, Story, Canvas } from '@storybook/addon-docs/blocks';
+
+import generateTitle from '../../util/generateTitle';
+import * as headerStories from '../Header/Header.stories.js';
+import * as footerStories from '../Footer/Footer.stories.js';
+
+const { STORYBOOK_CDN_PATH } = process.env;
+
+import { attachHTML } from '../../util/renderCode';
+
+export const template = ({renderHeader, renderFooter, reversed}) => {
+  return(
+    <div id="body-wrapper">
+      {renderHeader}
+      <main id="main-content">
+        <div className="pre-content sp--bottom">
+          <div className="ma__placeholder">
+            Pre Content
+          </div>
+        </div>
+        <div className="main-content ma__container">
+          <div className="ma__placeholder">
+            Main Content
+          </div>
+        </div>
+        <div className={`main-content main-content--two ${reversed ? 'main-content--reversed' : ''}`}>
+          { reversed && (
+            <aside className="sidebar">
+              <div className="ma__placeholder">
+                Left Rail
+              </div>
+            </aside>
+            )
+          }
+          <div className="page-content">
+            <div className="ma__placeholder">
+              Main Content
+            </div>
+          </div>
+          { !reversed && (
+            <aside className="sidebar">
+              <div className="ma__placeholder">
+                Right Rail
+              </div>
+            </aside>
+            )
+          }
+        </div>
+      </main>
+      <div className="ma__placeholder">
+        Post Content
+      </div>
+      {renderFooter}
+    </div>
+  )
+}
+
+const templateSlim = template({renderHeader: headerStories.headerSlimmest(), renderFooter: footerStories.footerSlim()})
+
+const templateFullNav = template({renderHeader: headerStories.headerFullNav(), renderFooter: footerStories.footerFullNav(), reversed: true})
+
+const notesTemplateSlim = `
+  // Link to CSS:
+  <link rel="stylesheet" href="${STORYBOOK_CDN_PATH}/css/general.css">
+  <link rel="stylesheet" href="${STORYBOOK_CDN_PATH}/css/layout.css">
+  <link rel="stylesheet" href="${STORYBOOK_CDN_PATH}/css/header-slim.css">
+  <link rel="stylesheet" href="${STORYBOOK_CDN_PATH}/css/footer-slim.css">
+`
+
+const notesTemplate = `
+  // Link to CSS:
+  <link rel="stylesheet" href="${STORYBOOK_CDN_PATH}/css/general.css">
+  <link rel="stylesheet" href="${STORYBOOK_CDN_PATH}/css/layout.css">
+  <link rel="stylesheet" href="${STORYBOOK_CDN_PATH}/css/header.css">
+  <link rel="stylesheet" href="${STORYBOOK_CDN_PATH}/css/footer.css">
+
+  // Link to JS:
+  <script type="text/javascript" src="${STORYBOOK_CDN_PATH}/js/header.js" />
+`
+
+export const notesTemplateCSS = `
+<head>
+  <!-- Mayflower fonts and other basic styles -->
+  <link rel="stylesheet" href="${STORYBOOK_CDN_PATH}/css/general.css">
+  <!-- Mayflower page layout styles -->
+  <link rel="stylesheet" href="${STORYBOOK_CDN_PATH}/css/layout.css">
+  <!-- Add Mayflower Header and Footer specific styles -->
+</head>
+`
+
+export const notesTemplateJS = `
+  <!-- Add Header JS (if any)-->
+`
+
+export const templateBasic = () => templateSlim;
+attachHTML(templateBasic, templateSlim, notesTemplateSlim)
+
+
+export const templateFull = () => templateFullNav;
+attachHTML(templateFull, templateFullNav, notesTemplate)
diff --git a/packages/core/stories/components/Template/Template.stories.mdx b/packages/core/stories/components/Template/Template.stories.mdx
@@ -0,0 +1,56 @@
+import { Meta, Story, Canvas, Source } from '@storybook/addon-docs/blocks';
+import { linkTo } from '@storybook/addon-links';
+
+import generateTitle from '../../util/generateTitle';
+import * as stories from './Template.stories.js';
+import { renderReactMarkup } from '../../util/renderCode';
+
+<Meta
+  title={generateTitle('Template')}
+  parameters={{
+    viewMode: 'docs'
+  }}
+/>
+
+# Template
+
+The templates demostrates how to assemble a page with a Mayflower Header, Footer and a basic page layout.
+
+> Refer to <button onClick={linkTo(generateTitle('Header'))}>Header</button> and <button onClick={linkTo(generateTitle('Footer'))}>Footer</button>, copy and paste the Header and Footert HTML, CSS and JS (if any) into the template snippet.
+
+<Source code={
+  `
+  ${stories.notesTemplateCSS}
+<body>
+  ${renderReactMarkup(stories.template({renderHeader: '// Insert Header HTML here', renderFooter: '// Insert Footer HTML here'}))}
+  ${stories.notesTemplateJS}
+</body>
+  `
+} />
+
+
+## Usage
+To kick-start a page in HTML:
+1. Copy the code above or jump to an example below and click on "Show code" to copy the HTML snippet from the example
+4. Add the links to CSS and JS at the appropriate places
+    - **CSS**: Link to CSS inside the `<head>`
+    - **JS**: Link to JS before the closing body tag `</body>`
+5. Replace the `.ma__placeholder` divs with real content
+
+
+
+## Examples
+
+### Header and Footer (Slim)
+A demo page with the Slim Header, Slim Footer, and a layout of a full-width block, and two-column block with a right-rail.
+
+<Canvas>
+    <Story story={stories.templateBasic} />
+</Canvas>
+
+### Header and Footer (With Full Navigation)
+A demo page with the Full Nav Header, Full Nav Footer, and a layout of a full-width block, and two-column block with a left-rail.
+
+<Canvas>
+    <Story story={stories.templateFull} />
+</Canvas>
diff --git a/packages/core/stories/meta.json b/packages/core/stories/meta.json
@@ -66,5 +66,9 @@
   "Footer": {
     "group": "Brand Components",
     "title": "Footer"
+  },
+  "Template": {
+    "group": "Brand Components",
+    "title": "Template"
   }
 }
diff --git a/packages/core/stories/styles/index.scss b/packages/core/stories/styles/index.scss
@@ -39,6 +39,9 @@
 @use '@massds/mayflower-assets/scss/02-molecules/footer-links';
 @use '@massds/mayflower-assets/scss/02-molecules/social-links';
 
+@use '@massds/mayflower-assets/scss/00-base/layout';
+@use '@massds/mayflower-assets/scss/01-atoms/place-holder';
+
 // Global
 .sp {
   &--top {

diff --git a/packages/core/stories/util/renderCode.js b/packages/core/stories/util/renderCode.js
@@ -20,7 +20,7 @@ export const renderReactMarkup = (component, notes) => {
     plugins: [parserHtml]
   });
   // Replaces the path to the state seal with the latest assets CDN.
-  return prettyMarkup.replace(/static\/media\/stateseal?([a-z|\-]*)\.(.*)\.png/, `${STORYBOOK_CDN_PATH}/static/images/logo/stateseal$1.png`);
+  return prettyMarkup.replace(/static\/media\/stateseal?([a-z|\-]*)\.(.*)\.png/g, `${STORYBOOK_CDN_PATH}/static/images/logo/stateseal$1.png`);
 }
 
 // can't pass DocsContext from .mdx