Merge branch 'vue_shared-storybook' into 'master'

[RUN ALL RSPEC] [RUN AS-IF-FOSS] Add Storybook for Vue components

See merge request gitlab-org/gitlab!63592

.eslintrc.yml

@@ -107,3 +107,7 @@ overrides:
       import/no-nodejs-modules: off
       filenames/match-regex: off
       no-console: off
+  - files:
+      - '*.stories.js'
+    rules:
+      filenames/match-regex: off

.gitlab/ci/frontend.gitlab-ci.yml

@@ -2,6 +2,10 @@
   - source scripts/utils.sh
   - run_timed_command "retry yarn install --frozen-lockfile"
 
+.storybook-yarn-install: &storybook-yarn-install
+  - source scripts/utils.sh
+  - run_timed_command "retry yarn run storybook:install --frozen-lockfile"
+
 .compile-assets-base:
   extends:
     - .default-retry
@@ -80,6 +84,15 @@ update-yarn-cache:
   script:
     - *yarn-install
 
+update-storybook-yarn-cache:
+  extends:
+    - .default-retry
+    - .storybook-yarn-cache-push
+    - .shared:rules:update-cache
+  stage: prepare
+  script:
+    - *storybook-yarn-install
+
 .frontend-fixtures-base:
   extends:
     - .default-retry
@@ -344,3 +357,29 @@ startup-css-check as-if-foss:
   needs:
     - job: "compile-test-assets as-if-foss"
     - job: "rspec frontend_fixture as-if-foss"
+
+.compile-storybook-base:
+  extends:
+    - .frontend-test-base
+    - .storybook-yarn-cache
+  script:
+    - *yarn-install  # storybook depends on the global webpack config, so we must install global deps.
+    - *storybook-yarn-install
+    - yarn run storybook:build
+
+compile-storybook:
+  extends:
+    - .compile-storybook-base
+    - .frontend:rules:default-frontend-jobs
+  artifacts:
+    name: storybook
+    expire_in: 31d
+    when: always
+    paths:
+      - storybook/public
+
+compile-storybook as-if-foss:
+  extends:
+    - .compile-storybook-base
+    - .as-if-foss
+    - .frontend:rules:default-frontend-jobs-as-if-foss

.gitlab/ci/global.gitlab-ci.yml

@@ -88,6 +88,16 @@
   <<: *assets-cache
   policy: push  # We want to rebuild the cache from scratch to ensure stale dependencies are cleaned up.
 
+.storybook-node-modules-cache: &storybook-node-modules-cache
+  key: "storybook-node-modules-${NODE_ENV}-v1"
+  paths:
+    - storybook/node_modules/
+  policy: pull
+
+.storybook-node-modules-cache-push: &storybook-node-modules-cache-push
+  <<: *storybook-node-modules-cache
+  policy: push  # We want to rebuild the cache from scratch to ensure stale dependencies are cleaned up.
+
 .rubocop-cache: &rubocop-cache
   key: "rubocop-v1"
   paths:
@@ -181,6 +191,14 @@
     - *node-modules-cache-push
     - *assets-cache-push
 
+.storybook-yarn-cache:
+  cache:
+    - *storybook-node-modules-cache
+
+.storybook-yarn-cache-push:
+  cache:
+    - *storybook-node-modules-cache-push
+
 .use-pg11:
   image: "registry.gitlab.com/gitlab-org/gitlab-build-images:ruby-2.7.2.patched-golang-1.16-git-2.31-lfs-2.9-chrome-89-node-14.15-yarn-1.22-postgresql-11-graphicsmagick-1.3.36"
   services:

.gitlab/ci/pages.gitlab-ci.yml

@@ -8,12 +8,14 @@ pages:
     - coverage-frontend
     - karma
     - compile-production-assets
+    - compile-storybook
   script:
     - mv public/ .public/
     - mkdir public/
     - mv coverage/ public/coverage-ruby/ || true
     - mv coverage-frontend/ public/coverage-frontend/ || true
     - mv coverage-javascript/ public/coverage-javascript/ || true
+    - mv storybook/public public/storybook || true
     - cp .public/assets/application-*.css public/application.css || true
     - cp .public/assets/application-*.css.gz public/application.css.gz || true
   artifacts:

app/assets/javascripts/vue_shared/components/todo_button.stories.js

+/* eslint-disable @gitlab/require-i18n-strings */
+
+import TodoButton from './todo_button.vue';
+
+export default {
+  component: TodoButton,
+  title: 'vue_shared/components/todo_button',
+};
+
+const Template = (args, { argTypes }) => ({
+  components: { TodoButton },
+  props: Object.keys(argTypes),
+  template: '<todo-button v-bind="$props" v-on="$props" />',
+});
+
+export const Default = Template.bind({});
+Default.argTypes = {
+  isTodo: {
+    description: 'True if to-do is unresolved (i.e. not "done")',
+    control: { type: 'boolean' },
+  },
+  click: { action: 'clicked' },
+};

doc/development/fe_guide/storybook.md

+---
+stage: none
+group: unassigned
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
+---
+
+# Storybook
+
+The Storybook for the `gitlab-org/gitlab` project is available on our [GitLab Pages site](https://gitlab-org.gitlab.io/gitlab/storybook).
+
+## Storybook in local development
+
+Storybook dependencies and configuration are located under the `storybook/` directory.
+
+To build and launch Storybook locally, in the root directory of the `gitlab` project:
+
+1. Install Storybook dependencies:
+
+    ```shell
+    yarn storybook:install
+    ```
+
+1. Build the Storybook site:
+
+    ```shell
+    yarn storybook:start
+    ```
+
+## Adding components to Storybook
+
+Stories can be added for any Vue component in the `gitlab` repository.
+
+To add a story:
+
+1. Create a new `.stories.js` file in the same directory as the Vue component.
+   The file name should have the same prefix as the Vue component.
+
+    ```txt
+    vue_shared/
+    ├─ components/
+    │  ├─ todo_button.vue
+    │  ├─ todo_button.stories.js
+    ```
+
+1. Write the story as per the [official Storybook instructions](https://storybook.js.org/docs/vue/writing-stories/introduction)
+   
+   Notes:
+   - Specify the `title` field of the story as the component's file path from the `javascripts/` directory,
+     e.g. if the component is located at `app/assets/javascripts/vue_shared/components/todo_button.vue`, specify the `title` as
+     `vue_shared/components/To-do Button`. This will ensure the Storybook navigation maps closely to our internal directory structure.

doc/development/pipelines.md

@@ -560,7 +560,7 @@ request, be sure to start the `dont-interrupt-me` job before pushing.
    - `.yarn-cache`
    - `.assets-compile-cache` (the key includes `${NODE_ENV}` so it's actually two different caches).
 1. These cache definitions are composed of [multiple atomic caches](../ci/caching/index.md#use-multiple-caches).
-1. Only 6 specific jobs, running in 2-hourly scheduled pipelines, are pushing (i.e. updating) to the caches:
+1. Only the following jobs, running in 2-hourly scheduled pipelines, are pushing (i.e. updating) to the caches:
    - `update-setup-test-env-cache`, defined in [`.gitlab/ci/rails.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/rails.gitlab-ci.yml).
    - `update-gitaly-binaries-cache`, defined in [`.gitlab/ci/rails.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/rails.gitlab-ci.yml).
    - `update-static-analysis-cache`, defined in [`.gitlab/ci/rails.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/rails.gitlab-ci.yml).
@@ -568,6 +568,7 @@ request, be sure to start the `dont-interrupt-me` job before pushing.
    - `update-assets-compile-production-cache`, defined in [`.gitlab/ci/frontend.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/frontend.gitlab-ci.yml).
    - `update-assets-compile-test-cache`, defined in [`.gitlab/ci/frontend.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/frontend.gitlab-ci.yml).
    - `update-yarn-cache`, defined in [`.gitlab/ci/frontend.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/frontend.gitlab-ci.yml).
+   - `update-storybook-yarn-cache`, defined in [`.gitlab/ci/frontend.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/frontend.gitlab-ci.yml).
 1. These jobs can also be forced to run in merge requests whose title include `UPDATE CACHE` (this can be useful to warm the caches in a MR that updates the cache keys).
 
 ### Artifacts strategy

package.json

@@ -40,6 +40,9 @@
     "markdownlint:no-trailing-spaces": "markdownlint --config doc/.markdownlint/markdownlint-no-trailing-spaces.yml",
     "markdownlint:no-trailing-spaces:fix": "yarn run markdownlint:no-trailing-spaces --fix",
     "postinstall": "node ./scripts/frontend/postinstall.js",
+    "storybook:install": "yarn --cwd ./storybook install",
+    "storybook:build": "yarn --cwd ./storybook build",
+    "storybook:start": "yarn --cwd ./storybook start",
     "stylelint-create-utility-map": "node scripts/frontend/stylelint/stylelint-utility-map.js",
     "webpack": "NODE_OPTIONS=\"--max-old-space-size=3584\" webpack --config config/webpack.config.js",
     "webpack-vendor": "NODE_OPTIONS=\"--max-old-space-size=3584\" webpack --config config/webpack.vendor.config.js",

storybook/.gitignore

+node_modules/
+public/
\ No newline at end of file

storybook/config/main.js

+/* eslint-disable import/no-commonjs */
+const IS_EE = require('../../config/helpers/is_ee_env');
+
+module.exports = {
+  stories: [
+    '../../app/assets/javascripts/**/*.stories.js',
+    IS_EE && '../../ee/app/assets/javascripts/**/*.stories.js',
+  ].filter(Boolean),
+  addons: ['@storybook/addon-essentials', '@storybook/addon-a11y'],
+};

storybook/config/preview.js

+const stylesheetsRequireCtx = require.context(
+  '../../app/assets/stylesheets',
+  true,
+  /application\.scss$/,
+);
+
+stylesheetsRequireCtx('./application.scss');

storybook/config/webpack.config.js

+/* eslint-disable no-param-reassign */
+
+const { statSync } = require('fs');
+const path = require('path');
+const sass = require('node-sass'); // eslint-disable-line import/no-unresolved
+const { buildIncludePaths, resolveGlobUrl } = require('node-sass-magic-importer/dist/toolbox'); // eslint-disable-line import/no-unresolved
+const webpack = require('webpack');
+const gitlabWebpackConfig = require('../../config/webpack.config.js');
+
+const ROOT = path.resolve(__dirname, '../../');
+const TRANSPARENT_1X1_PNG =
+  'url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==)';
+const SASS_INCLUDE_PATHS = [
+  'app/assets/stylesheets',
+  'app/assets/stylesheets/_ee',
+  'ee/app/assets/stylesheets',
+  'ee/app/assets/stylesheets/_ee',
+  'node_modules',
+].map((p) => path.resolve(ROOT, p));
+
+/**
+ * Custom importer for node-sass, used when LibSass encounters the `@import` directive.
+ * Doc source: https://github.com/sass/node-sass#importer--v200---experimental
+ * @param {*} url the path in import as-is, which LibSass encountered.
+ * @param {*} prev the previously resolved path.
+ * @returns {Object | null} the new import string.
+ */
+function sassSmartImporter(url, prev) {
+  const nodeSassOptions = this.options;
+  const includePaths = buildIncludePaths(nodeSassOptions.includePaths, prev).filter(
+    (includePath) => !includePath.includes('node_modules'),
+  );
+
+  // GitLab extensively uses glob-style import paths, but
+  // Sass doesn't support glob-style URLs out of the box.
+  // Here, we try and resolve the glob URL.
+  // If it resolves, we update the @import statement with the resolved path.
+  const filePaths = resolveGlobUrl(url, includePaths);
+  if (filePaths) {
+    const contents = filePaths
+      .filter((file) => statSync(file).isFile())
+      .map((x) => `@import '${x}';`)
+      .join(`\n`);
+
+    return { contents };
+  }
+
+  return null;
+}
+
+const sassLoaderOptions = {
+  functions: {
+    'image-url($url)': function sassImageUrlStub() {
+      return new sass.types.String(TRANSPARENT_1X1_PNG);
+    },
+    'asset_path($url)': function sassAssetPathStub() {
+      return new sass.types.String(TRANSPARENT_1X1_PNG);
+    },
+    'asset_url($url)': function sassAssetUrlStub() {
+      return new sass.types.String(TRANSPARENT_1X1_PNG);
+    },
+    'url($url)': function sassUrlStub() {
+      return new sass.types.String(TRANSPARENT_1X1_PNG);
+    },
+  },
+  includePaths: SASS_INCLUDE_PATHS,
+  importer: sassSmartImporter,
+};
+
+module.exports = function storybookWebpackConfig({ config }) {
+  // Add any missing extensions from the main GitLab webpack config
+  config.resolve.extensions = Array.from(
+    new Set([...config.resolve.extensions, ...gitlabWebpackConfig.resolve.extensions]),
+  );
+
+  // Replace any Storybook-defined CSS loaders with our custom one.
+  config.module.rules = [
+    ...config.module.rules.filter((r) => !r.test.test('.css')),
+    {
+      test: /\.s?css$/,
+      exclude: /typescale\/\w+_demo\.scss$/, // skip typescale demo stylesheets
+      loaders: [
+        'style-loader',
+        'css-loader',
+        {
+          loader: 'sass-loader',
+          options: sassLoaderOptions,
+        },
+      ],
+    },
+  ];
+
+  // Silence webpack warnings about moment/pikaday not being able to resolve.
+  config.plugins.push(new webpack.IgnorePlugin(/moment/, /pikaday/));
+
+  // Add any missing aliases from the main GitLab webpack config
+  Object.assign(config.resolve.alias, gitlabWebpackConfig.resolve.alias);
+  // The main GitLab project aliases this `icons.svg` file to app/assets/javascripts/lib/utils/icons_path.js,
+  // which depends on the existence of a global `gon` variable.
+  // By deleting the alias, imports of this path will resolve as expected.
+  delete config.resolve.alias['@gitlab/svgs/dist/icons.svg'];
+
+  return config;
+};

storybook/package.json

+{
+  "private": true,
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "start": "start-storybook -p 9002 -c config",
+    "build": "build-storybook -c config -o public"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@storybook/addon-a11y": "^6.2.9",
+    "@storybook/addon-actions": "^6.2.9",
+    "@storybook/addon-controls": "^6.2.9",
+    "@storybook/addon-essentials": "^6.2.9",
+    "@storybook/vue": "6.2.9",
+    "node-sass": "^4.14.1",
+    "node-sass-magic-importer": "^5.3.2",
+    "postcss-loader": "3.0.0",
+    "sass-loader": "^7.1.0"
+  }
+}