feat(b-skeleton): add skeleton components (closes #5413) (#5575)

* init * Update * Apply basic border-radius to type `text` * update skeleton-image.js * update component references * Add icon loader * Add BSkeletonIcon to package.json * Update _variables.scss * Update styles.scss * Update _skeleton.scss * Update README.md * Update skeleton.js * Update skeleton-icon.js * Update skeleton-image.js * Update skeleton-table.js * Update skeleton-wrapper.js * Adjust BundleWatch limits * Rename `<b-skeleton-image>` to `<b-skeleton-img>` and improve docs * Update README.md * Update .bundlewatch.config.json * Update build.yml * update skeleton-table.js * update package.json * update _skeleton.scss * Add tests * update skeleton-wrapper.spec.js * update _variables.scss * update readme.md * update package.json * Un-mark all other components as "New" * Update _variables.scss * Update README.md * Update package.json * Update README.md * Update README.md * Update README.md Co-authored-by: Jacob Müller <jacob.mueller.elz@gmail.com>
bootstrap-vue · Aug 21, 2020 · 31c06b5 · 31c06b5
1 parent 43806dc
commit 31c06b5
Show file tree

Hide file tree

Showing 29 changed files with 1,343 additions and 8 deletions.
diff --git a/docs/assets/scss/styles.scss b/docs/assets/scss/styles.scss
@@ -36,7 +36,7 @@
   -webkit-font-smoothing: antialiased;
   -moz-osx-font-smoothing: grayscale;
 
-  &:after {
+  &::after {
     content: "#";
   }
 }

diff --git a/src/_variables.scss b/src/_variables.scss
@@ -152,3 +152,11 @@ $bv-enable-popover-variants: true !default;
 $b-popover-bg-level: $alert-bg-level !default;
 $b-popover-border-level: $alert-border-level !default;
 $b-popover-color-level: $alert-color-level !default;
+
+// --- Skeleton ---
+
+$b-skeleton-background-color: rgba(0, 0, 0, 0.12) !default;
+$b-skeleton-loading-cursor: wait !default;
+$b-skeleton-animation-duration: 1.75s !default;
+$b-skeleton-text-spacing: map-get($spacers, 1) !default;
+$b-skeleton-btn-width: 75px !default;
diff --git a/src/components/aspect/package.json b/src/components/aspect/package.json
@@ -3,7 +3,6 @@
   "version": "1.0.0",
   "meta": {
     "title": "Aspect",
-    "new": true,
     "version": "2.9.0",
     "description": "The `<b-aspect>` component can be used to maintain a minimum responsive aspect ratio for content.",
     "components": [

diff --git a/src/components/avatar/package.json b/src/components/avatar/package.json
@@ -3,7 +3,6 @@
   "version": "1.0.0",
   "meta": {
     "title": "Avatar",
-    "new": true,
     "version": "2.8.0",
     "description": "Avatars are typically used to display a user profile as a picture, an icon, or short text.",
     "components": [

diff --git a/src/components/form-rating/package.json b/src/components/form-rating/package.json
@@ -4,7 +4,6 @@
   "meta": {
     "title": "Form Rating",
     "version": "2.12.0",
-    "new": true,
     "description": "BootstrapVue custom star rating form control for ratings entry or aggregated display",
     "components": [
       {

diff --git a/src/components/index.d.ts b/src/components/index.d.ts
@@ -47,6 +47,7 @@ export * from './pagination-nav'
 export * from './popover'
 export * from './progress'
 export * from './sidebar'
+export * from './skeleton'
 export * from './spinner'
 export * from './table'
 export * from './tabs'

diff --git a/src/components/index.js b/src/components/index.js
@@ -44,6 +44,7 @@ import { PaginationNavPlugin } from './pagination-nav'
 import { PopoverPlugin } from './popover'
 import { ProgressPlugin } from './progress'
 import { SidebarPlugin } from './sidebar'
+import { SkeletonPlugin } from './skeleton'
 import { SpinnerPlugin } from './spinner'
 // Table plugin includes TableLitePlugin and TableSimplePlugin
 import { TablePlugin } from './table'
@@ -98,6 +99,7 @@ export const componentsPlugin = /*#__PURE__*/ pluginFactory({
     PopoverPlugin,
     ProgressPlugin,
     SidebarPlugin,
+    SkeletonPlugin,
     SpinnerPlugin,
     TablePlugin,
     TabsPlugin,

diff --git a/src/components/index.scss b/src/components/index.scss
@@ -16,6 +16,7 @@
 @import "pagination/index";
 @import "pagination-nav/index";
 @import "popover/index";
+@import "skeleton/index";
 @import "sidebar/index";
 @import "table/index";
 @import "time/index";

diff --git a/src/components/sidebar/README.md b/src/components/sidebar/README.md
@@ -328,9 +328,9 @@ elements outside of the sidebar.
 
 ### `v-b-toggle` directive
 
-Using the [`v-b-toggle` directive](/docs/directive/toggle) is the preferred method for _opening_ the
-sidebar, as it automatically handles applying the `aria-controls` and `aria-expanded` accessibility
-attributes on the trigger element.
+Using the [`v-b-toggle` directive](/docs/directives/toggle) is the preferred method for _opening_
+the sidebar, as it automatically handles applying the `aria-controls` and `aria-expanded`
+accessibility attributes on the trigger element.
 
 The majority of examples on this page use the `v-b-toggle` directive.
 

diff --git a/src/components/sidebar/package.json b/src/components/sidebar/package.json
@@ -3,7 +3,6 @@
   "version": "1.0.0",
   "meta": {
     "title": "Sidebar",
-    "new": true,
     "version": "2.10.0",
     "description": "The `<b-sidebar>` component creates a fixed viewport, left or right, sliding popout drawer.",
     "plugins": [

diff --git a/src/components/skeleton/README.md b/src/components/skeleton/README.md
@@ -0,0 +1,275 @@
+# Skeleton
+
+> `<b-skeleton>` is a BootstrapVue custom component, that allows you to display a loading state for
+> several component types while your data is being fetched or computed.
+
+**Example: Basic usage**
+
+```html
+<template>
+  <div>
+    <div class="d-flex align-items-center mb-3">
+      <b-progress class="w-100" :max="maxLoadingTime" height="1.5rem">
+        <b-progress-bar :value="loadingTime" :label="`${((loadingTime / maxLoadingTime) * 100).toFixed(2)}%`"></b-progress-bar>
+      </b-progress>
+
+      <b-button class="ml-3" @click="startLoading()">Reload</b-button>
+    </div>
+
+    <b-skeleton-wrapper :loading="loading">
+      <template v-slot:loading>
+        <b-card>
+          <b-skeleton width="85%"></b-skeleton>
+          <b-skeleton width="55%"></b-skeleton>
+          <b-skeleton width="70%"></b-skeleton>
+        </b-card>
+      </template>
+
+      <b-card>
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas viverra nunc sapien,
+        non rhoncus elit tincidunt vitae. Vestibulum maximus, ligula eu feugiat molestie,
+        massa diam imperdiet odio, vitae viverra ligula est id nisi. Aliquam ut molestie est.
+        Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac
+        turpis egestas. Phasellus at consequat dui. Aenean tristique sagittis quam,
+        sit amet sollicitudin neque sodales in.
+      </b-card>
+    </b-skeleton-wrapper>
+  </div>
+</template>
+
+<script>
+  export default {
+    data() {
+      return {
+        loading: false,
+        loadingTime: 0,
+        maxLoadingTime: 3
+      }
+    },
+    watch: {
+      loading(newVal, oldValue) {
+        if (newVal !== oldValue) {
+          this.clearLoadingTimeInterval()
+
+          if (newVal) {
+            this.$_loadingTimeInterval = setInterval(() => {
+              this.loadingTime++
+            }, 1000)
+          }
+        }
+      },
+      loadingTime(newVal, oldValue) {
+        if (newVal !== oldValue) {
+          if (newVal === this.maxLoadingTime) {
+            this.loading = false
+          }
+        }
+      }
+    },
+    created() {
+      this.$_loadingTimeInterval = null
+    },
+    mounted() {
+      this.startLoading()
+    },
+    methods: {
+      clearLoadingTimeInterval() {
+        clearInterval(this.$_loadingTimeInterval)
+        this.$_loadingTimeInterval = null
+      },
+      startLoading() {
+        this.loading = true
+        this.loadingTime = 0
+      }
+    }
+  }
+</script>
+
+<!-- b-skeleton.vue -->
+```
+
+## Types
+
+`<b-skeleton>` supports various basic types, to represent various components in your project.
+
+```html
+<h5>Text (default)</h5>
+<b-skeleton></b-skeleton>
+
+<h5 class="mt-3">Avatar</h5>
+<b-skeleton type="avatar"></b-skeleton>
+
+<h5 class="mt-3">Input</h5>
+<b-skeleton type="input"></b-skeleton>
+
+<h5 class="mt-3">Button</h5>
+<b-skeleton type="button"></b-skeleton>
+
+<!-- b-skeleton-types.vue -->
+```
+
+## Skeleton animations
+
+`<b-skeleton>` supports different animations. You can set them per component or change it globally
+in the [settings](/docs/reference/settings).
+
+```html
+<h5>Wave (default)</h5>
+<b-card>
+  <b-skeleton animation="wave" width="85%"></b-skeleton>
+  <b-skeleton animation="wave" width="55%"></b-skeleton>
+  <b-skeleton animation="wave" width="70%"></b-skeleton>
+</b-card>
+
+<h5 class="mt-3">Fade</h5>
+<b-card>
+  <b-skeleton animation="fade" width="85%"></b-skeleton>
+  <b-skeleton animation="fade" width="55%"></b-skeleton>
+  <b-skeleton animation="fade" width="70%"></b-skeleton>
+</b-card>
+
+<h5 class="mt-3">Throb</h5>
+<b-card>
+  <b-skeleton animation="throb" width="85%"></b-skeleton>
+  <b-skeleton animation="throb" width="55%"></b-skeleton>
+  <b-skeleton animation="throb" width="70%"></b-skeleton>
+</b-card>
+
+<h5 class="mt-3">None</h5>
+<b-card>
+  <b-skeleton animation width="85%"></b-skeleton>
+  <b-skeleton animation width="55%"></b-skeleton>
+  <b-skeleton animation width="70%"></b-skeleton>
+</b-card>
+
+<!-- b-skeleton-animations.vue -->
+```
+
+## Helper components
+
+Utilize `<b-skeleton>` helper components to quickly scaffold existing components.
+
+### Table
+
+`<b-skeleton-table>` allows you to scaffold a basic table structure by utilizing the `rows` and
+`columns` props to define the size of the table. You can pass props directly to the table via the
+`table-props` property, which supports the same props as `<b-table-simple>`. Refer to the
+`<b-table-simple>` [documentation](/docs/components/table#comp-ref-b-table-simple) for a complete
+list.
+
+```html
+<b-skeleton-table
+  :rows="5"
+  :columns="4"
+  :table-props="{ bordered: true, striped: true }"
+></b-skeleton-table>
+
+<!-- b-skeleton-helper-table.vue -->
+```
+
+### Image
+
+Utilize `<b-skeleton-img>` to represent images. It utilizes a 16:9 aspect ratio by default, for a
+responsive sizing. You can overwrite this by applying `no-aspect` and utilize the `height` and
+`width` props to set your own sizing.
+
+```html
+<b-row>
+  <b-col>
+    <b-skeleton-img></b-skeleton-img>
+  </b-col>
+  <b-col>
+    <b-skeleton-img></b-skeleton-img>
+  </b-col>
+  <b-col cols="12" class="mt-3">
+    <b-skeleton-img no-aspect height="150px"></b-skeleton-img>
+  </b-col>
+</b-row>
+
+<!-- b-skeleton-helper-img.vue -->
+```
+
+#### Card Image
+
+Use `<b-skeleton-img>` to represent images in `<b-card>`. Remember to set the `card-img` prop to the
+position of the image. This will apply the proper border-radius.
+
+```html
+<b-row>
+  <b-col cols="12" md="6">
+    <h5>Image top</h5>
+    <b-card no-body img-top>
+      <b-skeleton-img card-img="top" aspect="3:1"></b-skeleton-img>
+      <b-card-body>
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas viverra nunc sapien,
+        non rhoncus elit tincidunt vitae.
+      </b-card-body>
+    </b-card>
+  </b-col>
+  <b-col cols="12" md="6">
+    <h5>Image bottom</h5>
+    <b-card no-body img-bottom>
+      <b-card-body>
+        Vestibulum maximus, ligula eu feugiat molestie, massa diam imperdiet odio, vitae viverra
+        ligula est id nisi. Aliquam ut molestie est.
+      </b-card-body>
+      <b-skeleton-img card-img="bottom" aspect="3:1"></b-skeleton-img>
+    </b-card>
+  </b-col>
+</b-row>
+
+<b-row class="mt-md-3">
+  <b-col cols="12" md="6">
+    <h5>Image left</h5>
+    <b-card no-body img-left>
+      <b-skeleton-img card-img="left" width="225px"></b-skeleton-img>
+      <b-card-body>
+        Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis
+        egestas. Phasellus at consequat dui.
+      </b-card-body>
+    </b-card>
+  </b-col>
+  <b-col cols="12" md="6">
+    <h5>Image right</h5>
+    <b-card no-body img-right>
+      <b-skeleton-img card-img="right" width="225px"></b-skeleton-img>
+      <b-card-body>
+        Aenean tristique sagittis quam, sit amet sollicitudin neque sodales in.
+      </b-card-body>
+    </b-card>
+  </b-col>
+</b-row>
+
+<!-- b-skeleton-helper-card-img.vue -->
+```
+
+## Icons
+
+`<b-skeleton-icon>` can also be used as placeholder for icons. If you need to use any icon props,
+you can pass them via the `icon-props` property.
+
+```html
+<b-skeleton-icon
+  icon="person"
+  :icon-props="{ fontScale: 2 }"
+></b-skeleton-icon>
+
+<b-skeleton-icon
+  icon="person-fill"
+  :icon-props="{ fontScale: 2, variant: 'dark' }"
+></b-skeleton-icon>
+
+<!-- b-skeleton-helper-card-icon.vue -->
+```
+
+**Note:** The `throb` animation does not work with `b-skeleton-icon`.
+
+## Styling and customization
+
+The `<b-skeleton>` component and helper components utilizes Bootstrap SCSS variables, as much as
+possible to best match the styling and sizing of the native components. This means if you've
+customized Bootstrap SCSS, the skeleton components should adapt to fit your custom theming.
+
+We've also provided a few custom SCSS variables, that can be used to further customize the styling
+of the various `<b-skeleton>` components. You can read more about how to change these variables in
+the [theming section](/docs/reference/theming#bootstrapvue-sass-variables).