DP-18263: Adds new assets package. (#1037) (#1039)

* DP-18263: Adds new assets package. (#1037) * DP-18263: Adds new assets package. * DP-18263: Removes stylelint ignore for dist directory. * DP-18263: Updates package name. * DP-18263: Updates circleci scripts for assets. * DP-18263: Fixes stylelint bug. * DP-18263: Updates lockfile to reflect package name change, fixes test script. * DP-18263: Moving static assets to static directory. (#1042) * DP-18263: Assets integration Branch: package version bump. (#1046) * DP-18263: Bumping mayflower-assets version. * Update assets/package.json Co-authored-by: Minghua Sun <[email protected]> Co-authored-by: Minghua Sun <[email protected]> * Assets integration: Remove Bourbon requirement from assets package. (#1051) * DP-18263: Removes the dependency on bourbon. * Updates README, version bump. * Assets Integration Branch: React Support with Mayflower Assets Package (#1047) * DP-18263: Adds support for assets package with react. * DP-18263: Updates react package to use latest mayflower-assets package, removes debugging in storybook config. * Update react/.storybook/main.js * DP-18263: Adds .env file for react. * DP-18263: Fixes bugs related to fonts, layouts. Removes bourbon and bourbon neat dependencies. * DP-18263: Fixes stylelint errors for mayflower-assets. * DP-18263: Updates mayflower-assets package. * DP-18263: Fixes visual regression on HeaderSearch component. * Assets Integration: Patternlab (#1052) * DP-18263: Adds support for mayflower-assets package to patternlab. * DP-18263: Fixes bug caused by not waiting for files to copy before processing them for building patternlab. * DP-18263: Removes bourbon and bourbon neat from patternlab. * DP-18740: Integrates React/Storybook with Assets Package (#1064) * 18740: Integrates react package with new assets package. * DP-18740: Removes build css / watch css steps. * DP-18740: Updates files to be symlink. * DP-18740: Removes babel config from nwb, combines rules for storybook babel processing. * DP-18740: Removes css, style, sass loaders in package. * DP-18740: Updates react_test job to copy docs directory into image. * DP-18740: Fixes bug with backstop custom script failing to find symlink. * Assets integration: Remove style imports from react components. (#1073) * Adds component styles to styles directory. * Removes direct importing of styles in react components. * Updated gatsby site to support new mayflower-react. * Removes react style files from component directories. * Adds back missing ContactGroup import. * Adds missing styles for form component. * WIP. * Updated react components to document required styles. * Switches build to use gulp instead of NWB. * Removes NWB, react-scripts/CRA. * Cleans up npm scripts. * Updating mayflower-react version to 10, fixes bug with gatsby site related to package version. * Fixes eslint bug caused by babel-eslint plugins. * Removing babel-eslint to fix broken builds. * Reverting update of babel-eslint to fix bugs. * Fixes gatsby site to handle new dist/ directory from react. * Adds missing mayflower-react path to sass, adds auto eslint fixes. * Adds changelog file, updates gatsby site layout styles to remove duplicates. * Updated changelog text. * Cleans up code in storybook main file. * format changelog * format changelog Co-authored-by: Minghua Sun <[email protected]> * Fixes remaining lint errors. (#1083) * Fixes bad pathing from merge conflicts. * Fixes regression on DecorativeLink. * Adding gulpfile to eslint ignore list. * Assets integration update backstop final (#1087) * Adds updated react backstop reference images. * approve patternlab screenshots * Removing files to fix conflicts with merge. * Puts back conflicitng files using assets-integration-branch as source. Co-authored-by: Minghua Sun <[email protected]> * Assets integration: Upgrades React, Patternlab, Gatsby to node 12. (#1085) * Upgrades node to v12 for react, gatsby site. * Updates node version to 12 for react circleci test. * Updates patternlab to node v12. * Assets integration: Fix React ES6 Exports (#1098) * Fixes ES Module exports to add file extensions. * WIP fix for react exports. * Revert "WIP fix for react exports." This reverts commit 57c0b64. * fix site missing styles (#1100) * Removes package exports and switches main to commonjs version. (#1101) * update mayflower-assets * Updating react circleci cache. * approve screenshots vertical spacing due to clearfix * approve react backstop screenshots * publish mayflower-react 10.0.0-alpha Co-authored-by: Minghua Sun <[email protected]>
massgov · Jun 26, 2020 · d19a838 · d19a838
1 parent 4a6065e
commit d19a838
Show file tree

Hide file tree

Showing 798 changed files with 22,123 additions and 32,176 deletions.
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -12,8 +12,7 @@ references:
 react_defaults: &react_defaults
   working_directory: ~/repo
   docker:
-    - image: circleci/node:10.15.1
-
+    - image: circleci/node:12.18.0
 patternlab_defaults: &patternlab_defaults
   working_directory: /var/www/code
   docker:
@@ -165,12 +164,12 @@ jobs:
       - checkout
       - restore_cache:
           keys:
-            - mfr-dependencies-{{ checksum "react/package.json" }}
+            - mfr-dependencies-{{ checksum "react/package.json" }}-0
       - run: cd react && npm install
       - save_cache:
           paths:
             - react/node_modules
-          key: mfr-dependencies-{{ checksum "react/package.json" }}
+          key: mfr-dependencies-{{ checksum "react/package.json" }}-0
       - run:
           name: Mayflower React Build
           command: cd react && npm run build
@@ -194,6 +193,7 @@ jobs:
           docker-compose up --no-start web backstop
           docker cp ./ $(docker-compose ps -q backstop):/src/
           docker cp ../assets $(docker-compose ps -q backstop):/src/assets
+          docker cp ../docs $(docker-compose ps -q backstop):/src/docs
           docker cp ./storybook-static/. $(docker-compose ps -q web):/usr/share/nginx/html
       - run: |
           cd react
@@ -288,9 +288,6 @@ jobs:
       - run:
           name: Mayflower Style Linter
           command: cd assets && npm run stylelint
-      - run:
-          name: Validate Package Build
-          command: cd assets && npm run build
 
   assets_deploy_tag:
     <<: *react_defaults
@@ -305,13 +302,12 @@ jobs:
           paths:
             - assets/node_modules
           key: assets-dependencies-{{ checksum "assets/package.json" }}
-      - run: cd assets && npm run build
       - run:
-          name: 'Publish mayflower-tokens NPM package'
+          name: 'Publish mayflower-assets NPM package'
           command: |
             cd assets
             npm version --no-git-tag-version "$CIRCLE_TAG"
-            if test -z "$(npm show @massds/mayflower-tokens@$CIRCLE_TAG)"; then
+            if test -z "$(npm show @massds/mayflower-assets@$CIRCLE_TAG)"; then
               npm publish
             else
               echo "Skipping NPM publish - $CIRCLE_TAG already exists"

diff --git a/.gitignore b/.gitignore
@@ -5,6 +5,6 @@
 node_modules
 
 .env
-
+!react/.env
 # Distribution folder
 dist
diff --git a/assets/.nvmrc b/assets/.nvmrc
@@ -0,0 +1 @@
+v12.16.0
diff --git a/assets/.stylelintignore b/assets/.stylelintignore
@@ -1 +1 @@
-node_modules
+node_modules
diff --git a/assets/README.md b/assets/README.md
@@ -1,58 +1,158 @@
-# Mayflower-Tokens
-[![npm package][npm-badge]][npm]
-
-Mayflower-tokens provides a bundled up library of design tokens and assets that you will need for theming your front end framework to look and feel like [Mass.gov](https://mass.gov) and other Commonwealth web properties that are in Mayflower ecosystem. Mayflower-tokens includes color token SCSS variables, fonts, icons and other imagery from Mayflower — the [enterprise design system for the Commonwealth of Massachusetts][mayflower-doc].
-```
-├── dist   
-    ├── fonts                 Texta web fonts      
-    ├── images             
-    │   ├── svg-icons         SVG icon files
-    │   ├── stateseal         stateseal png
-    │   ├── stateseal-color   stateseal png in color grayscale
-    ├── scss        
-    │   ├── _colors.scss      Color tokens
-    │   ├── _fonts.scss       Texta font imports (needs to set $assets-path)
-    │   ├── _index.scss       Default SCSS export
-```
-
-- **Codebase:** [Mayflower monorepo][mayflower-github] `assets` subdirectory
-  >[Mayflower monorepo][mayflower-github] comprised of [Mayflower documentation][mayflower-doc], two component libraries — [Mayflower React][react-storybook] and [Mayflower PatternLab][patternLab], and their [shared assets][shared-assets].
-  > Refer to [Mayflower PatternLab Static Site][patternlab] for the set of UI components consumed in Mass.gov.
-- **Live demo:** [mayflower-react storybook][react-storybook]
-
-## Using Mayflower-Tokens in Your Project
-1. Install mayflower-tokens into your project as a dependency.
-`npm i @massds/mayflower-tokens --save`
-2. Import color tokens into your SASS/SCSS file
-`@import '[path to node_modules]/@massds/mayflower-tokens/colors/mayflower-color_tokens';`
-3. Refer to variables in `@massds/mayflower-tokens/colors/_mayflower-color_tokens.scss` or a [live demo for the colors](https://mayflower.digital.mass.gov/react/?path=/story/brand-colors--colors) to map the Mayflower color tokens in your theming SCSS.
-4. You can also find the web fonts Texta that are used in Mayflower (please)
-To import into your styles, refer to [mayflower Texta font imports](https://github.com/massgov/mayflower/blob/develop/assets/scss/00-base/_fonts.scss).
+# Mayflower Assets
+The styles provided by this package require compiling with a tool that supports the [npm sass package](https://www.npmjs.com/package/sass). 
 
 ## License
 Please note that the fonts and the svg-icons are licensed only for the usage on websites that are **owned by the Commonwealth of Massachusetts**. Mayflower is currently using a licensed web font Texta and purchased [Smashing Icons](https://smashicons.com/) for some icons.
 
-### Texta License
+## Texta License
 Fontspring grants Licensee a perpetual, worldwide, non-exclusive and non-transferrable license to install the Texta as webfont on Websites that are owned by the Commonwealth of Massachusetts using the @font-face selector in CSS files. For other usage, you may have to acquire an additional license through Fontsprint.
 For more details about Texta's terms of use, please refer to our [web font license](https://www.fontspring.com/lic/htswufoczd).
 
-## Publish Package
+## Publishing Instructions
+>To publish the package, you will have to be a collaborator or have access to the [@massds/mayflower-assets npm package](https://www.npmjs.com/package/@massds/mayflower-assets).
 
-1. `npm login` — Login to the npm account.
->To publish the package, you will have to be a collaborator or have access to the [@massds/mayflower-tokens npm package](https://www.npmjs.com/package/@massds/mayflower-tokens).
+1. Once you're done making changes and ready to publish, run `npm login` to login to the npm account.
+2. Update `version` in package.json and run `npm publish`. Wait a few minutes and check [@massds/mayflower-assets](https://www.npmjs.com/package/@massds/mayflower-assets) on the npm registry.
 
-1. `npm run build` — Build the distribution folder `dist`.
 
-1. Update `version` in package.json.
-1. `npm publish` — Publish `@massds/mayflower-tokens` to npm registry.å
-1. Wait a few minutes and check [@massds/mayflower-tokens][npm] on the registry.
 
+## Setup and Usage (fonts/images)
+If you're using this package only for its fonts and images, you can skip installing bourbon and sass. Assets can be found under `fonts` and `images`.
 
-[npm-badge]: https://img.shields.io/npm/v/@massds/mayflower-react.png?style=flat-square
-[npm]: https://www.npmjs.com/package/@massds/mayflower-tokens
-[mayflower-github]: https://github.com/massgov/mayflower
-[mayflower-doc]: https://www.mass.gov/mayflower
-[react-storybook]: https://mayflower.digital.mass.gov/react
-[react-starter]: https://github.com/massgov/mayflower-react-starter
-[patternlab]: https://mayflower.digital.mass.gov/patternlab
-[shared-assets]: https://github.com/massgov/mayflower/tree/develop/assets
+## Setup and Usage (Sass)
+When using this package for the .scss files, you should set the sass package's include paths to include bourbon's include paths as well as this package's own. This package's include paths are:
+```
+scss
+scss/00-base
+scss/00-base/mixins
+scss/01-atoms
+scss/03-organisms
+scss/04-templates
+scss/05-dataviz
+scss/08-print
+```
+These include paths allow you to include files with paths like `00-base/name-of-file` in your code.
+
+You can also set up your include paths by using an `.env` file at the root of your project. Sass can use the node environment variable `SASS_PATH` for setting your include paths:
+```
+// .env file
+SASS_PATH=./node_modules/@massds/mayflower-assets/scss:./node_modules/@massds/mayflower-assets/scss/00-base:./node_modules/@massds/mayflower-assets/scss/00-base/mixins:./node_modules/@massds/mayflower-assets/scss/01-atoms:./node_modules/@massds/mayflower-assets/scss/02-molecules:./node_modules/@massds/mayflower-assets/scss/03-organisms:./node_modules/@massds/mayflower-assets/scss/04-templates/./node_modules/@massds/mayflower-assets/scss/05-dataviz:./node_modules/@massds/mayflower-assets/scss/08-print
+```
+
+Many of the components require the file `00-base/_layout.scss` to be included at least once before their use. It's recommended for your project to create a single .scss file that includes all the shared files for your needs. This file should use `@forward` to forward sass modules that your other files need:
+```
+// example.scss
+
+// Assuming 'node_modules' is your include paths here...
+// forwards the normalize-scss library's normalize styling.
+@forward "normalize-scss/sass/normalize";
+@forward "00-base/layout";
+// Let all your scss files have access to colors without having to remember that.
+@forward "00-base/colors";
+// Grab the fonts from this package for inclusion:
+@forward "00-base/fonts";
+```
+```
+// some-other-file.scss
+
+// This path depends on what's in your include paths...
+@use "path/to/example.scss" as *;
+// You can also scope it:
+@use "path/to/example.scss";
+.elementClass {
+  ... rules go here ...
+}
+```
+Creating a shared file is NOT required. You can also just ensure that you include the box-sizing styling:
+```
+// some-other-file.scss
+@use "00-base/layout";
+.elementClass {
+  ... rules go here ...
+}
+```
+## Including SCSS Files
+To include a `.scss` file, please do NOT use `@import`. All previous uses of `@import` have been replaced by `@use` for [Sass Modules](https://sass-lang.com/documentation/at-rules/use) support:
+```
+// Scoped inclusion of variables. All variables will now
+// be under the variables scope.
+@use "00-base/variables";
+$my-new-var: variables.$column;
+// Or you can do this to place all variables
+// in the global scope for the file:
+@use "00-base/variables" as *;
+$my-new-var: $column;
+```
+## Variable Overrides
+All provided variables of this package allow for overrides by the user:
+```
+// You can define your overrides before the @use call.
+// Doing so will ensure the file you're calling with @use uses the overrides.
+$column: 60px;
+@use "00-base/variables";
+// You can also just pass the override to the file you're calling @use on:
+@use "00-base/variables" with (
+  $column: 60px;
+);
+```
+## Recommended Fonts
+Some reccomended fonts you can use can be found under `00-base/fonts`.
+## Example Compilation of Styles
+
+The following example uses gulp to compile all .scss files under src (with exceptions to those .scss files under `00-base/`). The script will place the compiled files under `dist/` within the same directories they originated.
+```
+// gulpfile.js
+const { src, dest, series } = require('gulp');
+const sass = require('gulp-sass');
+const rename = require('gulp-rename');
+const flatmap = require('gulp-flatmap');
+const del = require('del');
+const bourbon = require('bourbon');
+const path = require('path');
+// Replaces node_sass with sass.
+sass.compiler = require('sass');
+
+const compileSass = () => {
+  return src([
+    // Compile all scss files
+    './src/scss/**/*.scss',
+    // But skip over base directory files.
+    '!./src/scss/00-base/**'
+  ])
+  .pipe(rename(function(assetPath) {
+    // Sass will not compile files that start with an underscore,
+    // so rename them to remove it.
+    assetPath.basename = assetPath.basename.replace('_', '');
+    return assetPath;
+  }))
+  // Loops over all files in the stream with flatmap.
+  .pipe(flatmap((stream, file) => {
+    // Normally you should require/import the index file
+    // to get the includePaths used but that points to 
+    // the dist/ directory. Here we mimic that by just replacing
+    // dist/ with src/.
+    return stream
+    
+    .pipe(sass({
+      includePaths: [
+        path.join(__dirname, 'src'),
+        path.join(__dirname, 'src/scss'),
+        path.join(__dirname, 'src/scss/00-base'),
+        path.join(__dirname, 'src/scss/00-base/mixins'),
+        path.join(__dirname, 'src/scss/01-atoms'),
+        path.join(__dirname, 'src/scss/03-organisms'),
+        path.join(__dirname, 'src/scss/04-templates'),
+        path.join(__dirname, 'src/scss/05-dataviz'),
+        path.join(__dirname, 'src/scss/08-print'),
+        'node_modules',
+      ],
+    }).on('error', sass.logError))
+    .on('error', (err) => console.log(err))
+  }))
+  .pipe(dest('./dist/css'));
+};
+exports.default = series(compileSass);
+
+```
+## Development with Assets Package
+When working on changing styling, you can use `npm link` with another project so that changes made to `.scss` files show up live time. First, run `npm link` under the mayflower repo's assets directory. Next, in your other project's root directory run `npm link @massds/mayflower-assets`. This will make it so that under node_modules for your project, this package is symlinked (from @massds/mayflower-assets) to the mayflower repo's assets directory.
diff --git a/assets/index.js b/assets/index.js
@@ -0,0 +1,14 @@
+var path = require("path");
+
+module.exports = {
+  includePaths: [
+    path.join(__dirname, 'scss'),
+    path.join(__dirname, 'scss/00-base'),
+    path.join(__dirname, 'scss/00-base/mixins'),
+    path.join(__dirname, 'scss/01-atoms'),
+    path.join(__dirname, 'scss/03-organisms'),
+    path.join(__dirname, 'scss/04-templates'),
+    path.join(__dirname, 'scss/05-dataviz'),
+    path.join(__dirname, 'scss/08-print'),
+  ]
+};