Start Storybook and react components additions

.eslintignore

@@ -1 +1,3 @@
 node_modules
+storybook-static/**/*.js
+

.eslintrc.base.js

@@ -7,10 +7,16 @@ module.exports = {
   extends: [
     'airbnb-base',
     'plugin:jest/recommended',
+    'plugin:react/recommended',
   ],
   parserOptions: {
     ecmaVersion: 12,
   },
+  settings: {
+    react: {
+      version: 'detect',
+    },
+  },
   plugins: ['jest'],
   rules: {
     'import/extensions': [

.gitignore

@@ -3,6 +3,7 @@ node_modules
 .sass-cache
 .DS_STORE
 *.log
+storybook-static
 
 # local env files
 .env.local

.storybook/coopTheme.js

@@ -0,0 +1,8 @@
+import { create } from '@storybook/theming/create';
+import Logo from './coop-logo.svg';
+
+export default create({
+  base: 'light',
+  brandTitle: 'Coop UI',
+  brandImage: Logo,
+});

.storybook/main.js

@@ -0,0 +1,26 @@
+module.exports = {
+  "stories": [
+    "../packages/**/**/*.stories.mdx",
+  ],
+  "addons": [
+    {
+      name: '@storybook/addon-docs',
+      options: {
+        configureJSX: true,
+      },
+    },
+    "@storybook/addon-links",
+    "@storybook/addon-essentials",
+    '@storybook/addon-storysource',
+    '@storybook/addon-a11y',
+    '@whitespace/storybook-addon-html',
+    'storybook-addon-designs/register',
+  ],
+  webpackFinal: async (config) => {
+    config.module.rules.push({
+      test: /\.pcss$/,
+      use: [{ loader: 'style-loader' }, { loader: 'css-loader' }],
+    });
+    return config;
+  },
+}

.storybook/manager.js

@@ -0,0 +1,6 @@
+import { addons } from '@storybook/addons';
+import coopTheme from './coopTheme';
+
+addons.setConfig({
+  theme: coopTheme,
+});

.storybook/preview-body.html

@@ -0,0 +1,7 @@
+<!-- .storybook/preview-body.html -->
+
+<style>
+  body {
+    font-size: 1.2499999rem;
+  }
+</style>

.storybook/preview.js

@@ -0,0 +1,28 @@
+import "@coopdigital/foundations-vars";
+import "@coopdigital/foundations-typography";
+import "@coopdigital/foundations-global";
+
+export const parameters = {
+  options: {
+    showRoots: true,
+    storySort: {
+      order: ['Docs', ['Intro'], 'Foundations', 'Elements', 'Components', 'Patterns', 'Layout'],
+    },
+  },
+  actions: { argTypesRegex: "^on[A-Z].*" },
+  dependencies: {
+    // display only dependencies/dependents that have a story in storybook
+    // by default this is false
+    withStoriesOnly: true,
+
+    // completely hide a dependency/dependents block if it has no elements
+    // by default this is false
+    hideEmpty: true,
+  },
+  html: {
+    prettier: {
+      tabWidth: 4,
+      useTabs: false,
+    },
+  },
+}

README.md

@@ -2,11 +2,10 @@
 A mono-repository containing the design system website and foundations and component packages needed for designing and building digital services for the Co‑op. All packages can be found in the [packages](./packages) directory.
 
 ## Co-op Design system
-The [design system](http://coop.co.uk/designsystem) is a sub folder of this repo and can be run locally and deployed to Heroku independently of the foundations and component packages. 
+The [design system](http://coop.co.uk/designsystem) is a sub folder of this repo and can be run locally and deployed to Heroku independently of the foundations and component packages.
 
 [How to install, run and deploy the design system](https://github.com/coopdigital/coop-frontend/blob/master/design-system/README.md)
 
-
 ## Developing foundation and component packages for the design system
 This repository uses [lerna](https://github.com/lerna/lerna) to automatically manage versioning of all the different packages. These are published as separate packages to [Co-op digital's NPM organisation](https://www.npmjs.com/org/coopdigital). These packages can be installed by digital teams as required as dependencies of their project.
 
@@ -16,3 +15,43 @@ This repository uses [lerna](https://github.com/lerna/lerna) to automatically ma
 If you publish a new or amended component - create a release for the coop-frontend repo adding release notes to let everyone know what changes you have made and why.
 
 The Slack github integration will let everyone on the #frontend and #designsystem channels know that there has been an update.
+
+## Storybook react UI library
+Storybook allows you to create and update react components within the `./packages` directory, using existing css and utility packages.
+### **How to install, run and deploy the Co-op react storybook**
+To run storybook locally, run the following commands:
+- `npm ci`
+- `npm run storybook`
+
+Storybook should now be available at `http://localhost:6006`
+
+### **Add components and stories to Storybook**
+The two most common ways you will create components for react are, adding a react component to an existing package, or creating a brand new package.
+#### **If you are creating a react compoennt for an existing package:**
+- From the `./packages/component-template` directory, copy the `index.mjs`, `Component.jsx` and `Component.stories.mdx` files, and the `__test__` directory from the package
+- Paste these into component directory you are working on and rename the component accordingly.
+- Add your tests to `__test__/<Yourcomponent>.test.jsx`;
+- Stories are added to `<Yourcomponent>.stories.mdx` files.  Review the `Component.stories.mdx` example file and its comments for help with creating stories,
+#### **If you are creating a new react component, follow these steps:**
+- Make a copy of the `./component-template` directory in the `./packages` directory
+- Rename the copied directory and its contained files, to your component name.
+- Start adding tests and creating the component
+
+### Info and useful links for Storybook and react
+In storybook there are addons allowing you to view your component stories as raw html, have basic accessibility checks, link to the relevant designs within Figma, and more.
+
+<!-- Co-op Storybook stories are broken into the following groups:
+- Foundations - for foundation packages
+- Elements - for element react/html packages
+- Components - for component packages, (can be made from one or more element packages) -->
+<!-- - (tbc) Patterns -->
+
+#### Useful links
+- [Storybook react docs](https://storybook.js.org/docs/react/get-started/introduction)
+- [Component Story Format](https://storybook.js.org/docs/react/api/csf)
+- [Storybook react mdx docs](https://storybook.js.org/docs/react/writing-docs/mdx)
+- [Storybook react mdx api docs](https://storybook.js.org/docs/react/api/mdx)
+- [MDX - Official site and docs](https://mdxjs.com/)
+- [React - Getting Started](https://reactjs.org/docs/getting-started.html)
+- [Jest docs](https://jestjs.io/docs/en/getting-started)
+<!-- - [React testing library](https://testing-library.com/docs/react-testing-library/intro/) -->

__mocks__/styleMock.js

@@ -0,0 +1,2 @@
+
+module.exports = {};

babel.config.js

@@ -1,4 +1,38 @@
+function isBabelCli(caller) {
+  return !!(caller && caller.name === "@babel/cli");
+}
+
+/** remove pcss to stop storybook build breaking */
+const moduleExtensions = ['module-extension', {
+  cjs: '',
+  mjs: '',
+  jsx: '',
+}];
+
+/**  when using the transform on pcss,
+ *   it breaks our storybook build due to src component
+ *  not being able to find .css extensions.
+ * Only add this extension transform on cli build  */
+const moduleExtensionsWithPcss = ['module-extension', {
+  cjs: '',
+  mjs: '',
+  jsx: '',
+  pcss: 'css',
+}];
+
 module.exports = (api) => {
+  const plugins = [
+    '@babel/plugin-transform-runtime',
+    '@babel/plugin-proposal-optional-chaining',
+    '@babel/plugin-proposal-object-rest-spread',
+  ];
+
+  if (api.caller(isBabelCli) === true) {
+    plugins.push(moduleExtensionsWithPcss);
+  } else {
+    plugins.push(moduleExtensions);
+  }
+
   api.cache(true);
 
   const presets = [
@@ -9,19 +43,15 @@ module.exports = (api) => {
       shippedProposals: true,
       useBuiltIns: 'usage',
     }],
+    '@babel/preset-react',
+    '@babel/preset-typescript',
   ];
 
-  const plugins = [
-    '@babel/plugin-transform-runtime',
-    '@babel/plugin-proposal-optional-chaining',
-    ['module-extension', {
-      cjs: '',
-      mjs: '',
-    }],
-  ];
+  const ignore = ['**/*.stories.(js|mdx)'];
 
   return {
     presets,
     plugins,
+    ignore,
   };
 };

design-system/package.json

@@ -57,30 +57,30 @@
     "prismjs": "^1.23.0"
   },
   "devDependencies": {
-    "@babel/core": "^7.13.1",
-    "@babel/plugin-transform-runtime": "^7.13.7",
-    "@babel/preset-env": "^7.13.5",
+    "@babel/core": "^7.13.8",
+    "@babel/plugin-transform-runtime": "^7.13.9",
+    "@babel/preset-env": "^7.13.9",
     "@babel/runtime": "^7.13.7",
-    "autoprefixer": "^10.2.4",
+    "autoprefixer": "^9.8.6",
     "babel-plugin-module-extension": "^0.1.3",
     "babelify": "^10.0.0",
     "browserify": "^17.0.0",
-    "core-js": "^3.9.0",
+    "core-js": "^3.8.3",
     "cssnano": "^4.1.10",
     "gulp": "^4.0.2",
     "gulp-buffer": "0.0.2",
     "gulp-changed": "^4.0.2",
     "gulp-connect": "^5.7.0",
-    "gulp-postcss": "^9.0.0",
+    "gulp-postcss": "^8.0.0",
     "gulp-rename": "^2.0.0",
     "gulp-sourcemaps": "^3.0.0",
     "gulp-tap": "^2.0.0",
     "gulp-terser": "^2.0.1",
-    "postcss": "^8.2.6",
-    "postcss-calc": "^8.0.0",
-    "postcss-custom-media": "^8.0.0",
-    "postcss-custom-properties": "^11.0.0",
-    "postcss-import": "^14.0.0",
+    "postcss": "^7.0.35",
+    "postcss-calc": "^7.0.4",
+    "postcss-custom-media": "^7.0.8",
+    "postcss-custom-properties": "^9.2.0",
+    "postcss-import": "^12.0.1",
     "postcss-nesting": "^7.0.1"
   },
   "scripts": {

jest.config.mjs

@@ -7,6 +7,9 @@ export default {
   modulePathIgnorePatterns: [
     './node_modules/',
   ],
+  moduleNameMapper: {
+    '\\.(css|pcss)$': '<rootDir>/__mocks__/styleMock.js',
+  },
   roots: [
     './packages',
   ],