bootstrap-vue · jacobmllr95 · Apr 9, 2019 · Apr 9, 2019 · Apr 9, 2019 · Apr 9, 2019
diff --git a/docs/markdown/intro/README.md b/docs/markdown/intro/README.md
@@ -37,7 +37,7 @@ import 'bootstrap/dist/css/bootstrap.css'
 import 'bootstrap-vue/dist/bootstrap-vue.css'
 ```
 
-Or import Bootstrap and BootstrapVue `scss` files via a custom SCSS file:
+Or import Bootstrap and BootstrapVue `scss` files via a single custom SCSS file:
 
 ```scss
 // custom.scss
@@ -50,12 +50,20 @@ Or import Bootstrap and BootstrapVue `scss` files via a custom SCSS file:
 import 'custom.scss'
 ```
 
-Be sure to include your custom variables before `bootstrap.scss` and include BootstrapVue SCSS
-_after_ Bootstrap SCSS to ensure variables are set up correctly.
+Be sure to `@import` or define your custom variable values _before_ including Bootstrap SCSS
+(`bootstrap.scss`), and include BootstrapVue SCSS (`bootstrap-vue.scss`) _after that_ to ensure
+variables are set up correctly.
+
+Make sure you place all the SCSS `@import`s into a single SCSS file, and import that single file
+into your project. Importing individual SCSS files into your project will **not** share variable
+values and functions between files by default.
 
 **Note**: _Requires webpack configuration to load CSS/SCSS files
 ([official guide](https://webpack.js.org/guides/asset-management/#loading-css))_.
 
+For information on theming Bootstrap, check out the [Theming](/docs/reference/theming) reference
+section.
+
 ## Nuxt.js Module
 
 [Nuxt.js](https://nuxtjs.org) version {{ nuxtVersion }} (or greater) is recommended.

diff --git a/docs/nuxt.config.js b/docs/nuxt.config.js
@@ -161,7 +161,7 @@ module.exports = {
     'highlightjs/styles/atom-one-light.css',
     'codemirror/lib/codemirror.css',
     'bootstrap/dist/css/bootstrap.css',
-    '../src/index.scss', // BootstrapVue SCSS
+    '../scripts/build.scss', // BootstrapVue SCSS
     '@assets/css/docs.min.css',
     '@assets/scss/styles.scss'
   ]

diff --git a/scripts/build.scss b/scripts/build.scss
@@ -0,0 +1,11 @@
+/*!
+ * BootstrapVue Custom CSS (https://bootstrap-vue.js.org)
+ */
+
+// Include Bootstrap functions, variables, and mixins
+@import "node_modules/bootstrap/scss/functions";
+@import "node_modules/bootstrap/scss/variables";
+@import "node_modules/bootstrap/scss/mixins";
+
+// Import BootstrapVue custom SCSS
+@import "../src/index.scss";
diff --git a/scripts/build.sh b/scripts/build.sh
@@ -44,7 +44,7 @@ node-sass --output-style expanded \
           --source-map true \
           --source-map-contents true \
           --precision 6 \
-          src/index.scss \
+          scripts/build.scss \
           dist/bootstrap-vue.css
 postcss --config scripts/postcss.config.js \
         --replace dist/bootstrap-vue.css

diff --git a/src/_utilities.scss b/src/_utilities.scss
@@ -1,12 +1,12 @@
-// Bootstrap Vue Utility classes
+// --- BootstrapVue Utility Classes ---
 
 $bv-utility-classes-defined: false !default;
 
+// Make sure to include these style definitions only once
 @if $bv-utility-classes-defined == false {
-  // This test will only include these style definitions once
   $bv-utility-classes-defined: true;
 
-  // Create .bv-d-<bp>-down-none helper classes
+  // Create `.bv-d-<bp>-down-none` helper classes
   @each $breakpoint in map-keys($grid-breakpoints) {
     @include media-breakpoint-down($breakpoint) {
       .bv-d-#{$breakpoint}-down-none {

diff --git a/src/_variables.scss b/src/_variables.scss
@@ -1,7 +1,5 @@
-// Alerts
-
+// --- Alerts ---
 $bv-alert-transition: $transition-fade !default;
 
-// Tables
-
+// --- Tables ---
 $b-table-busy-opacity: 0.55 !default;
diff --git a/src/components/button/package.json b/src/components/button/package.json
@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "meta": {
     "title": "Button",
-    "description": "Use Bootstrap Vue’s <b-button> component for actions in forms, dialogs, and more. Includes support for a handful of contextual variations, sizes, states, and more.",
+    "description": "Use BootstrapVue’s <b-button> component for actions in forms, dialogs, and more. Includes support for a handful of contextual variations, sizes, states, and more.",
     "components": [
       {
         "component": "BButton",

diff --git a/src/components/dropdown/_dropdown-form.scss b/src/components/dropdown/_dropdown-form.scss
@@ -4,8 +4,8 @@ $bv-dropdown-form-defined: false !default;
   // This test will only include these style definitions once
   $bv-dropdown-form-defined: true;
 
-  // Custom styles for b-dropdown-form
-  // Based on class .dropdown-item
+  // Custom styles for <b-dropdown-form>
+  // Based on class `.dropdown-item`
   .b-dropdown-form {
     display: inline-block;
     padding: $dropdown-item-padding-y $dropdown-item-padding-x;

diff --git a/src/components/dropdown/_dropdown-text.scss b/src/components/dropdown/_dropdown-text.scss
@@ -4,8 +4,8 @@ $bv-dropdown-text-defined: false !default;
   // This test will only include these style definitions once
   $bv-dropdown-text-defined: true;
 
-  // Custom styles for b-dropdown-text
-  // Based on class .dropdown-item
+  // Custom styles for <b-dropdown-text>
+  // Based on class `.dropdown-item`
   .b-dropdown-text {
     display: inline-block;
     padding: $dropdown-item-padding-y $dropdown-item-padding-x;

diff --git a/src/components/dropdown/_dropdown.scss b/src/components/dropdown/_dropdown.scss
@@ -1,10 +1,10 @@
 $bv-dropdown-defined: false !default;
 
+// Make sure to include these style definitions only once
 @if $bv-dropdown-defined == false {
-  // This test will only include these style definitions once
   $bv-dropdown-defined: true;
 
-  // Hide the caret for no-caret setting
+  // Hide the caret for `no-caret` setting
   // See: https://github.com/bootstrap-vue/bootstrap-vue/issues/1473
   // See: https://github.com/twbs/bootstrap/issues/23724
   .dropdown {

diff --git a/src/components/form-input/_form-input.scss b/src/components/form-input/_form-input.scss
@@ -1,6 +1,6 @@
 // Temporary fix for cssnano bug: https://github.com/cssnano/cssnano/issues/712
-// By moving center to last value in background-position property
-// Bug will/may affect Nuxt.js users and docs site https://github.com/bootstrap-vue/bootstrap-vue/issues/2599
+// By moving center to last value in `background-position` property
+// See: https://github.com/bootstrap-vue/bootstrap-vue/issues/2599
 @if $enable-validation-icons {
   .form-control {
     .was-validated &:invalid,
@@ -39,7 +39,7 @@ input[type="color"].form-control:disabled {
   opacity: $btn-disabled-opacity;
 }
 
-/* Base .input-group > .custom-range styling (no PR yet on BS V4) */
+// --- Base `.input-group > .custom-range` styling (no PR yet on BS V4) ---
 .input-group {
   > .custom-range {
     position: relative;
@@ -116,8 +116,8 @@ input[type="color"].form-control:disabled {
   @include border-radius($input-border-radius-sm);
 }
 
-/* b-form-input: custom-range validation styling - valid (no PR yet for BS V4.2) */
-// Mixin for generating .input-group .custom-range validation styling
+// --- <b-form-input>: custom-range validation styling - valid (no PR yet for BS V4.2) ---
+// Mixin for generating `.input-group .custom-range` validation styling
 @mixin bv-custom-range-validation-state($state, $color) {
   .input-group .custom-range {
     .was-validated &:#{$state},
@@ -134,7 +134,7 @@ input[type="color"].form-control:disabled {
   .custom-range {
     .was-validated &:#{$state},
     &.is-#{$state} {
-      // Pseudo-elements must be split across multiple rulesets to have an affect.
+      // Pseudo-elements must be split across multiple rulesets to have an affect
       &:focus {
         &::-webkit-slider-thumb {
           box-shadow: 0 0 0 1px $body-bg, 0 0 0 $input-btn-focus-width lighten($color, 35%);
@@ -174,8 +174,6 @@ input[type="color"].form-control:disabled {
       &::-moz-range-track {
         background: rgba($color, 0.35);
       }
-      &::-moz-range-thumb {
-      }
 
       ~ .#{$state}-feedback,
       ~ .#{$state}-tooltip {

diff --git a/src/components/input-group/_input-group.scss b/src/components/input-group/_input-group.scss
@@ -1,12 +1,12 @@
 $bv-input-group-dropdown-patched: false !default;
 
+// Make sure to include these style definitions only once
 @if $bv-input-group-dropdown-patched == false {
-  // Only include this style patch once in final CSS
   $bv-input-group-dropdown-patched: true;
 
-  /* workaround for https://github.com/bootstrap-vue/bootstrap-vue/issues/1560 */
-  /* workaround for https://github.com/bootstrap-vue/bootstrap-vue/issues/2114 */
-  /* based on: bootstrap/scss/_input-group.scss */
+  // Workaround for https://github.com/bootstrap-vue/bootstrap-vue/issues/1560
+  // Workaround for https://github.com/bootstrap-vue/bootstrap-vue/issues/2114 */
+  // Based on: `~bootstrap/scss/_input-group.scss`
   .input-group {
     > .input-group-prepend > .btn-group,
     > .input-group-append:not(:last-child) > .btn-group,

diff --git a/src/components/jumbotron/README.md b/src/components/jumbotron/README.md
@@ -12,7 +12,7 @@ Anything else between the opening and closing tags will be rendered at the botto
 
 ```html
 <div>
-  <b-jumbotron header="Bootstrap Vue" lead="Bootstrap 4 Components for Vue.js 2">
+  <b-jumbotron header="BootstrapVue" lead="Bootstrap 4 Components for Vue.js 2">
     <p>For more information visit website</p>
     <b-button variant="primary" href="#">More Info</b-button>
   </b-jumbotron>
@@ -26,7 +26,7 @@ Anything else between the opening and closing tags will be rendered at the botto
 ```html
 <div>
   <b-jumbotron>
-    <template slot="header">Bootstrap Vue</template>
+    <template slot="header">BootstrapVue</template>
 
     <template slot="lead">
       This is a simple hero unit, a simple jumbotron-style component for calling extra attention to
@@ -87,7 +87,7 @@ jumbotron to use the default styling.
 ```html
 <div>
   <b-jumbotron bg-variant="info" text-variant="white" border-variant="dark">
-    <template slot="header">Bootstrap Vue</template>
+    <template slot="header">BootstrapVue</template>
 
     <template slot="lead">
       This is a simple hero unit, a simple jumbotron-style component for calling extra attention to

diff --git a/src/components/pagination-nav/_pagination-nav.scss b/src/components/pagination-nav/_pagination-nav.scss
@@ -1,3 +1,2 @@
-// Pagination and pagination-nav require the helper utility classes
-// Note the utilities file will automatically only be included once
+// <pagination> and <pagination-nav> require the helper utility classes
 @import "../../utilities";
diff --git a/src/components/pagination/_pagination.scss b/src/components/pagination/_pagination.scss
@@ -1,3 +1,2 @@
-// Pagination and pagination-nav require the helper utility classes
-// Note the utilities file will automatically only be included once
+// <pagination> and <pagination-nav> require the helper utility classes
 @import "../../utilities";
diff --git a/src/components/table/_table.scss b/src/components/table/_table.scss
@@ -1,8 +1,8 @@
-/* b-table: general styling */
+// --- <b-table>: general styling ---
 .b-table.table {
-  // table fixed header width layout
+  // Table fixed header width layout
   &.b-table-fixed {
-    /* fixed width columns */
+    // Fixed width columns
     table-layout: fixed;
   }
 
@@ -15,7 +15,7 @@
   > tbody > tr.b-table-details > td {
     border-top: none !important;
   }
-  // captioon positioning
+  // Caption positioning
   > caption {
     caption-side: bottom;
 
@@ -24,33 +24,33 @@
     }
   }
 
-  // make cells relatively position for thinks like tooltips, etc
+  // Make cells relatively position for thinks like tooltips, etc.
   > thead,
   > tfoot {
     > tr {
       > th,
       > td {
-        // So dropdowns, tooltips, sorting, etc, will position properly
+        // So dropdowns, tooltips, sorting, etc., will position properly
         position: relative;
       }
     }
   }
 }
 
-/* b-table: header sort styling */
+// --- <b-table>: header sort styling ---
 .b-table.table {
-  // Sort Styling
+  // Sort styling
   > thead,
   > tfoot {
     > tr {
       > th {
         &[aria-sort] {
-          // &.sorting
+          // `&.sorting`
           position: relative;
           padding-right: 1.125em;
           cursor: pointer;
 
-          // Up/Down sort=null indicator
+          // Up/down sort=null indicator
           &::after {
             position: absolute;
             display: block;
@@ -60,32 +60,32 @@
             font-size: inherit;
             line-height: inherit;
             opacity: 0.4;
-            content: "\2195"; // \2195 up-down arrow
+            content: "\2195"; // Up/down arrow
             speak: none;
           }
 
           // Ascending indicator
           &[aria-sort="ascending"]::after {
-            // &.sorting_asc::after.sorting_asc
+            // `&.sorting_asc::after.sorting_asc`
             opacity: 1;
-            content: "\2193"; // down arrow
+            content: "\2193"; // Down arrow
           }
 
           // Descending indicator
           &[aria-sort="descending"]::after {
-            // &.sorting_desc::after
+            // `&.sorting_desc::after`
             opacity: 1;
-            content: "\2191"; // up arrow
+            content: "\2191"; // Up arrow
           }
         }
       }
     }
   }
 }
 
-/* b-table: stackled tables */
+// --- <b-table>: stacked tables ---
 // Generate series of `.table-stacked-*` classes for configuring the screen
-// size of where your table will be stacked.
+// size of where your table will be stacked
 .b-table.table.b-table-stacked {
   @each $breakpoint in map-keys($grid-breakpoints) {
     $next: breakpoint-next($breakpoint, $grid-breakpoints);
@@ -125,7 +125,8 @@
           > tr {
             // Turn cells with labels into micro-grids
             > [data-label] {
-              // convert TD/TH contents to "cells". Caveat: child elements become cells!
+              // Convert <td>/<th> contents to "cells"
+              // Caveat: child elements become cells!
               display: grid;
               grid-template-columns: 40% auto;
               grid-gap: 0.25rem 1rem;
@@ -147,7 +148,7 @@
               display: none;
             }
 
-            // give the top of each "row" a heavy border
+            // Give the top of each "row" a heavy border
             > :first-child {
               border-top-width: (3 * $table-border-width);
             }
@@ -158,7 +159,7 @@
   }
 }
 
-/* b-table: selectable rows */
+// --- <b-table>: selectable rows ---
 .b-table.table.b-table-selectable {
   & > tbody > tr {
     cursor: pointer;

diff --git a/src/index.scss b/src/index.scss
@@ -1,14 +1,11 @@
-/*!
- * BootstrapVue Custom CSS (https://bootstrap-vue.js.org)
- */
-// Bootstrap
+// --- BootstrapVue Custom SCSS ---
 
-@import "node_modules/bootstrap/scss/functions";
-@import "node_modules/bootstrap/scss/variables";
-@import "node_modules/bootstrap/scss/mixins";
-
-// Bootstrap Vue
+// Requires at least the Bootstrap functions, variables and
+// mixins to be imported first
 
+// Include variables and utilities first
 @import "variables";
 @import "utilities";
+
+// Include custom SCSS for components
 @import "components/index";
diff --git a/src/utils/config.js b/src/utils/config.js
@@ -4,7 +4,7 @@ import warn from './warn'
 import { isArray } from './array'
 import { keys, isObject } from './object'
 
-// General Bootstrap Vue configuration
+// General BootstrapVue configuration
 //
 // BREAKPOINT DEFINITIONS
 //