From 59537efc7b8fda5c58f70fbfbb5ce152400ee1b1 Mon Sep 17 00:00:00 2001
From: Minghua Sun <clairesunstudio@gmail.com>
Date: Thu, 3 Dec 2020 11:56:23 -0500
Subject: [PATCH] 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
---
 common/config/rush/command-line.json          |   8 ++
 .../assets/scss/01-atoms/_place-holder.scss   |   8 ++
 packages/core/stories/about/Usage.stories.mdx |  19 +++-
 .../components/Header/Header.stories.js       |   2 +-
 .../components/Template/Template.stories.js   | 100 ++++++++++++++++++
 .../components/Template/Template.stories.mdx  |  56 ++++++++++
 packages/core/stories/meta.json               |   4 +
 packages/core/stories/styles/index.scss       |   3 +
 packages/core/stories/util/renderCode.js      |   2 +-
 9 files changed, 199 insertions(+), 3 deletions(-)
 create mode 100644 packages/assets/scss/01-atoms/_place-holder.scss
 create mode 100644 packages/core/stories/components/Template/Template.stories.js
 create mode 100644 packages/core/stories/components/Template/Template.stories.mdx

diff --git a/common/config/rush/command-line.json b/common/config/rush/command-line.json
index 0e21c57be6..f098ff505a 100644
--- 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
new file mode 100644
index 0000000000..ec84fd360c
--- /dev/null
+++ 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
index 129a0e72d0..89515fb9b8 100644
--- 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
index 6711d6bc67..01fcdc8ad0 100644
--- 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
new file mode 100644
index 0000000000..ddd2282e93
--- /dev/null
+++ 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
new file mode 100644
index 0000000000..91c7f4122b
--- /dev/null
+++ 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
index ea6f9f23b8..bea5ae39b5 100644
--- 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
index 90e360fa07..80f1501fe6 100644
--- 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
index 03cb365bc2..8aad025abd 100644
--- 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