feat(core): Add SCSS support (fixes #2201) (#2221)

.browserslistrc

@@ -0,0 +1,13 @@
+# https://github.com/browserslist/browserslist#readme
+
+>= 1%
+last 1 major version
+not dead
+Chrome >= 45
+Firefox >= 38
+Edge >= 12
+Explorer >= 11
+iOS >= 9
+Safari >= 9
+Android >= 4.4
+Opera >= 30

.eslintignore

@@ -1,2 +1,3 @@
 sw.js
 play.js
+/nuxt/plugin.template.js

.eslintrc.js

@@ -1,27 +1,19 @@
 module.exports = {
-    env: {
-        browser: true,
-        commonjs: true,
-        es6: true,
-        'jest/globals': true
-    },
-    extends: [
-        'standard',
-        'plugin:vue/recommended'
-    ],
-    plugins: [
-        'jest'
-    ],
-    parserOptions: {
-        ecmaVersion: 8,
-        sourceType: "module"
-    },
-    globals: {
-        Tether: true,
-        Promise: true,
-        Vue: true
+  extends: ['standard', 'plugin:vue/recommended'],
+  plugins: ['jest'],
+  parserOptions: {
+    ecmaVersion: 8,
+    sourceType: 'module'
+  },
+  env: {
+    browser: true,
+    es6: true,
+    'jest/globals': true
+  },
+  globals: {
+    Vue: true
   },
   rules: {
-    "vue/attributes-order": 0
+    'vue/attributes-order': 'off'
   }
 }

babel.config.js

@@ -0,0 +1,9 @@
+module.exports = {
+  presets: [['@babel/env', { useBuiltIns: 'entry' }]],
+  plugins: ['@babel/proposal-object-rest-spread', '@babel/transform-runtime'],
+  env: {
+    test: {
+      presets: [['@babel/env', { targets: { node: 8 } }]]
+    }
+  }
+}

docs/markdown/intro/README.md

@@ -21,16 +21,30 @@ import BootstrapVue from 'bootstrap-vue'
 Vue.use(BootstrapVue);
 ```
 
-And import Bootstrap and Bootstrap-Vue css files:
+And import Bootstrap and Bootstrap-Vue *css* files:
 
 ```js
 import 'bootstrap/dist/css/bootstrap.css'
 import 'bootstrap-vue/dist/bootstrap-vue.css'
 ```
+Or import Bootstrap and Bootstrap-Vue *scss* files via a custom SCSS file:
+```css
+// custom.scss
+@import "node_modules/bootstrap/scss/bootstrap";
+@import "node_modules/bootstrap-vue/src/index.scss";
+```
+```js
+// App entry point
+import 'custom.scss'
+```
+Be sure to include your custom variables before bootstrap.scss and include boostrap-vue
+SCSS _after_ bootstrap SCSS to ensure variables are set up correctly
 
-**Note**: _requires webpack configuration to load css files ([official guide](https://webpack.js.org/guides/asset-management/#loading-css))_
+**Note**: _requires webpack configuration to load css/scss files
+([official guide](https://webpack.js.org/guides/asset-management/#loading-css))_
 
-## Nuxt.js
+
+## Nuxt.js plugin module
 Install dependencies:
 
 ```bash
@@ -43,18 +57,52 @@ yarn add bootstrap-vue
 
 Add `bootstrap-vue/nuxt` to modules section of **nuxt.config.js**
 
+This will include both `boostrap.css` and `bootstrap-vue.css` default CSS
+
 ```js
 {
-  modules: [
-    'bootstrap-vue/nuxt',
+  modules: [ 'bootstrap-vue/nuxt' ]
+}
+```
+
+If you are using custom bootstrap SCSS, you can disable automatic inclusion of Bootstrap
+and Bootstrap-Vue pre-compiled CSS files by setting the folliwing option(s) to `false`:
 
-    // Or if you have custom bootstrap CSS...
-    ['bootstrap-vue/nuxt', { css: false }],
+```js
+{
+  modules: [
+    ['bootstrap-vue/nuxt', { bootstrapCss: false, bootstrapVueCss: false }],
   ]
 }
+
 ```
 
-## vue-cli
+Bootstrap-Vue's custom CSS relies on some Boostrap SCSS variables. You can include Bootstrap
+and Bootstrap-Vue SCSS in your project's custom SCSS file:
+
+**custom.css file:**
+```scss
+// custom overrides go first
+$grid-breakpoints: (
+  xs: 0,
+  sm: 576px,
+  md: 768px,
+  lg: 992px,
+  xl: 1200px
+  foo: 1999px
+);
+
+// then include the following
+@include "bootstrap/scss/bootstrap"
+@include "bootstrap-vue/src/index.scss"
+```
+and in your app main entry point include the single custom scss file (wen using nodes-sass/sass-loader):
+```js
+import 'custom.scss'
+```
+
+
+## vue-cli V2
 
 Bootstrap-Vue has two vue-cli templates available:
 
@@ -77,8 +125,12 @@ npm run dev
 You can repeat the commands above replacing `bootstrap-vue/webpack-simple` with
 `bootstrap-vue/webpack` for the webpack template.
 
-## Individual components and directives
+## vue-cli V3
+
+Coming soon!
+
 
+## Individual components and directives
 If you would like to only pull in a specific component or set of components, you can do
 this by directly importing those components.
 
@@ -114,11 +166,14 @@ Vue and ES2015 allow for various syntaxes here, so feel free to utilize kebab-ca
 camel-casing, pascal-casing, and/or object property shorthand.
 
 ### Component groups and Directives as Vue plugins
-
 You can also import component groups and directives as Vue plugins by importing
 the component group or directive directory:
 
 ```js
+// This imports all the layout components such as <b-container>, <b-row>, <b-col>:
+import { Layout } from 'bootstrap-vue/es/components';
+Vue.use(Layout);
+
 // This imports <b-modal> as well as the v-b-modal directive as a plugin:
 import { Modal } from 'bootstrap-vue/es/components';
 Vue.use(Modal);
@@ -134,12 +189,12 @@ Vue.use(Scrollspy);
 
 When importing as plugins, all subcomponents and related directives are imported in most cases.
 i.e. When importing `<b-nav>`, all the `<nav-*>` sub components are also included, as well all
-dropdown sub components.
+dropdown sub components. Component shorthand aliases (if any) are also included in the plugin.
 
 Refer to the component and directive documentation for details.
 
-### Webpack + Babel
 
+### Webpack + Babel
 When importing components/directives individually, you must configure your app to properly
 build the bootstrap-vue library source code. This commonly involves white-listing the node
 module for your babel loader rule in webpack.
@@ -169,28 +224,31 @@ module.exports = {
 }
 ```
 
-## Browser
 
+## Browser
 ```html
 <!-- Add this to <head> -->
 <link type="text/css" rel="stylesheet" href="//unpkg.com/bootstrap/dist/css/bootstrap.min.css"/>
-<link type="text/css" rel="stylesheet" href="//unpkg.com/bootstrap-vue@latest/dist/bootstrap-vue.css"/>
+<link type="text/css" rel="stylesheet" href="//unpkg.com/bootstrap-vue@latest/dist/bootstrap-vue.min.css"/>
 
 <!-- Add this after vue.js -->
 <script src="//unpkg.com/babel-polyfill@latest/dist/polyfill.min.js"></script>
-<script src="//unpkg.com/bootstrap-vue@latest/dist/bootstrap-vue.js"></script>
+<script src="//unpkg.com/bootstrap-vue@latest/dist/bootstrap-vue.min.js"></script>
 ```
 
+
 ## Build variants
 
 Choosing the best variant for your build environment / packager helps less bundle sizes.
 If your bundler supports es modules, it will automatically prefer it over commonjs.
 
 | Variant        | Environments         | Package path
-| -------------- | -------------------- | -----------------------------------
-| **ES Module**  | Webpack 2 / Rollup   | `dist/bootstrap-vue.esm.js`
-| commonjs2      | Webpack 1 / ...      | `dist/bootstrap-vue.common.js`
-| UMD            | Browser              | `dist/bootstrap-vue.js`
+| -------------- | -------------------- | -------------------------------------------------------------
+| **ES Module**  | Webpack 2 / Rollup   | `es/index.js`
+| **ESM Module** | Webpack 2 / Rollup   | `dist/bootstrap-vue.esm.js` _or_ `dist/bootstrap-vue.esm.min.js`
+| commonjs2      | Webpack 1 / ...      | `dist/bootstrap-vue.common.js` _or_ `dist/bootstrap-vue.common.min.js`
+| UMD            | Browser              | `dist/bootstrap-vue.js` _or_ `dist/bootstrap-vue.min.js`
+
 
 ## Migrating a project already using Bootstrap
 
@@ -200,31 +258,29 @@ If you've already been using Bootstrap 4, there are a couple adjustments you may
 - If Bootstrap is the only thing relying on jQuery, you can safely remove it — BootstrapVue **does not** depend on jQuery
 - Convert your native bootstrap HTML markup into the simplified Bootstrap-Vue custom component markup
 
+
 ## Browsers Support
 
 ### CSS
-
 BootstrapVue is to be used with Bootstrap 4 CSS.
 Please see [Browsers and devices](https://getbootstrap.com/docs/4.0/getting-started/browsers-devices)
 for more information about browsers currently supported by Bootstrap 4.
 
 ### JS
-
 BootstrapVue is written in Vue! So this is up to your project and bundler which browsers are supported.
 If you want to support older IE, Android and IOS devices, you may want to use
 [Babel Polyfill](https://babeljs.io/docs/usage/polyfill)
 
 ### IE 11
-
 You'll need babel-polyfill for BootstrapVue to work properly. In order to support this browser:
 
 - `npm install babel-polyfill`
 - Import it in your app main entry point with `import 'babel-polyfill'`
 
+
 ## Tooling Support
 
 ### vscode + vetur
-
 If you are using [vscode](https://code.visualstudio.com/) as your text editor, bootstrap-vue
 has intellisense autocompletion for component attributes available when using the
 [vetur extension](https://marketplace.visualstudio.com/items?itemName=octref.vetur).

docs/markdown/reference/theming/README.md

@@ -1,19 +1,24 @@
-# Theming Bootstrap
+# Theming Bootstrap & Bootstrap-Vue
 
 Theming is accomplished by Sass variables, Sass maps, and custom CSS. There’s no dedicated
 theme stylesheet; instead, you can enable the built-in theme to add gradients, shadows, and more.
 
+While Bootstrap-Vue uses Bootstrap's CSS, cetain features of Bootstrap-Vue uses custom CSS (i.e.
+stacked tables, etc). Our custom CSS relies on variables defined the Bootstrap V4.x SCSS. The
+`bootstrap-vue.css` is compiled using the default Bootstrap V4.x variables. Using the
+Bootstrap-Vue source SCSS, you can have your variable overrides (such as breakpoints, etc) adjust
+the custom Bootstrap-Vue css.
 
 ## Custom SCSS
 To use your own theme and colors in `bootstrap-vue`, you will need to create a
-`_custom.scss` file in your project, which you can include in your main app:
+`custom.scss` file in your project, which you can include in your main app:
 
+**Via template:**
 ```html
 <style lang="scss">
-
-  @import "assets/_custom.scss";
+  @import "assets/custom.scss";
   @import "~bootstrap/scss/bootstrap.scss";
-  @import '~bootstrap-vue/dist/bootstrap-vue.css';
+  @import '~bootstrap-vue/src/index.scss';
 
   body {
     margin: 0;
@@ -22,6 +27,32 @@ To use your own theme and colors in `bootstrap-vue`, you will need to create a
 </style>
 ```
 
+**Via app main entry point:**
+
+Create an SCSS file such as `custom.scss`
+```css
+// Define your variable overrides here
+$enable-shadows: true;
+$enable-gradients: true;
+$grid-breakpoints: (
+    xs: 0,
+    sm: 428px,
+    md: 799px,
+    lg: 899px,
+    xl: 1234px
+    xxl: 1600px
+);
+
+// include Bootstrap and Bootstrap-Vue SCSS files
+@import "~bootstrap/scss/bootstrap.scss";
+@import '~bootstrap-vue/src/index.scss';
+```
+and then import that single SCSS file into your app code entry point:
+```js
+// app.js
+import "custom.scss";
+```
+
 The `_custom.scss` file, which needs to be loaded before Bootstrap's scss, will include your
 Bootstrap V4 variable overrides (i.e. colors, shadows, font sizes, breakpoints, etc).
 You can find all of the possible variables in `node_modules/bootstrap/scss/_variables.scss`.
@@ -32,6 +63,8 @@ Do not forget to include `node-sass` and `sass-loader` to use `scss` in Vue:
 npm install --save-dev node-sass sass-loader
 ```
 
+**Note:** You may need to adjust the SCSS import paths based on your build environment.
+
 
 ## See also
 For more details on theming Bootstrap's CSS, refer to the

docs/nuxt.config.js

@@ -92,6 +92,12 @@ module.exports = {
     }
   },
 
+  head: {
+    script: [
+      { type: 'javascript', src: '//unpkg.com/babel-polyfill@latest/dist/polyfill.min.js' }
+    ]
+  },
+
   css: [
     'bootstrap/dist/css/bootstrap.css',
     'highlightjs/styles/atom-one-light.css',