Add new placeholder component (#31859)

Co-authored-by: XhmikosR <xhmikosr@gmail.com>
Co-authored-by: Jaume Sala <jaumesala@gmail.com>
Co-authored-by: Mark Otto <markdotto@gmail.com>
Co-authored-by: Patrick H. Lauke <redux@splintered.co.uk>

diff --git a/scss/_placeholders.scss b/scss/_placeholders.scss
new file mode 100644 (file)
index 0000000..2f647cc
--- /dev/null
+++ b/scss/_placeholders.scss
@@ -0,0 +1,51 @@
+.placeholder {
+  display: inline-block;
+  min-height: 1em;
+  vertical-align: middle;
+  cursor: wait;
+  background-color: currentColor;
+  opacity: $placeholder-opacity-max;
+
+  &.btn::before {
+    display: inline-block;
+    content: "";
+  }
+}
+
+// Sizing
+.placeholder-xs {
+  min-height: .6em;
+}
+
+.placeholder-sm {
+  min-height: .8em;
+}
+
+.placeholder-lg {
+  min-height: 1.2em;
+}
+
+// Animation
+.placeholder-glow {
+  .placeholder {
+    animation: placeholder-glow 2s ease-in-out infinite;
+  }
+}
+
+@keyframes placeholder-glow {
+  50% {
+    opacity: $placeholder-opacity-min;
+  }
+}
+
+.placeholder-wave {
+  mask-image: linear-gradient(130deg, $black 55%, rgba(0, 0, 0, (1 - $placeholder-opacity-min)) 75%, $black 95%);
+  mask-size: 200% 100%;
+  animation: placeholder-wave 2s linear infinite;
+}
+
+@keyframes placeholder-wave {
+  100% {
+    mask-position: -200% 0%;
+  }
+}

diff --git a/scss/_variables.scss b/scss/_variables.scss
index b6aa1b1e951d539e1498563331742c020e0f2d6a..9e921c07efca2d83179fa6786667f6699e03796f 100644 (file)
--- a/scss/_variables.scss
+++ b/scss/_variables.scss
@@ -1203,6 +1203,13 @@ $pagination-border-radius-lg:       $border-radius-lg !default;
 // scss-docs-end pagination-variables
 
 
+// Placeholders
+
+// scss-docs-start placeholders
+$placeholder-opacity-max:           .5 !default;
+$placeholder-opacity-min:           .2 !default;
+// scss-docs-end placeholders
+
 // Cards
 
 // scss-docs-start card-variables

diff --git a/scss/bootstrap.scss b/scss/bootstrap.scss
index eb047a3f2968c5c9ae333c29105803a75413ac84..f051c59a993eb6d39d62bc3ea2b6834dd811ec62 100644 (file)
--- a/scss/bootstrap.scss
+++ b/scss/bootstrap.scss
@@ -43,6 +43,7 @@
 @import "carousel";
 @import "spinners";
 @import "offcanvas";
+@import "placeholders";
 
 // Helpers
 @import "helpers";

diff --git a/site/assets/scss/_component-examples.scss b/site/assets/scss/_component-examples.scss
index 8fbfc06c5cda398a5a8ba292b9f89d0546ff1bb9..f93f1ee989136d2a705c5450c75d0790f6af837a 100644 (file)
--- a/site/assets/scss/_component-examples.scss
+++ b/site/assets/scss/_component-examples.scss
@@ -292,6 +292,17 @@
   }
 }
 
+// Placeholders
+.bd-example-placeholder-cards {
+  &::after {
+    display: none;
+  }
+
+  .card {
+    width: 18rem;
+  }
+}
+
 // Toasts
 .bd-example-toasts {
   min-height: 240px;

diff --git a/site/content/docs/5.0/components/placeholders.md b/site/content/docs/5.0/components/placeholders.md
new file mode 100644 (file)
index 0000000..f2be669
--- /dev/null
+++ b/site/content/docs/5.0/components/placeholders.md
@@ -0,0 +1,144 @@
+---
+layout: docs
+title: Placeholders
+description: Use loading placeholders for your components or pages to indicate something may still be loading.
+group: components
+toc: true
+---
+
+## About
+
+Placeholders can be used to enhance the experience of your application. They're built only with HTML and CSS, meaning you don't need any JavaScript to create them. You will, however, need some custom JavaScript to toggle their visibility. Their appearance, color, and sizing can be easily customized with our utility classes.
+
+## Example
+
+In the example below, we take a typical card component and recreate it with placeholders applied to create a "loading card". Size and proportions are the same between the two.
+
+<div class="bd-example bd-example-placeholder-cards d-flex justify-content-around">
+<div class="card">
+  {{< placeholder width="100%" height="180" class="card-img-top" text="false" background="#20c997" >}}
+  <div class="card-body">
+    <h5 class="card-title">Card title</h5>
+    <p class="card-text">Some quick example text to build on the card title and make up the bulk of the card's content.</p>
+    <a href="#" class="btn btn-primary">Go somewhere</a>
+  </div>
+</div>
+
+<div class="card" aria-hidden="true">
+  {{< placeholder width="100%" height="180" class="card-img-top" text="false" >}}
+  <div class="card-body">
+    <div class="h5 card-title placeholder-glow">
+      <span class="placeholder col-6"></span>
+    </div>
+    <p class="card-text placeholder-glow">
+      <span class="placeholder col-7"></span>
+      <span class="placeholder col-4"></span>
+      <span class="placeholder col-4"></span>
+      <span class="placeholder col-6"></span>
+      <span class="placeholder col-8"></span>
+    </p>
+    <a href="#" tabindex="-1" class="btn btn-primary disabled placeholder col-6"></a>
+  </div>
+</div>
+</div>
+
+```html
+<div class="card">
+  <img src="..." class="card-img-top" alt="...">
+
+  <div class="card-body">
+    <h5 class="card-title">Card title</h5>
+    <p class="card-text">Some quick example text to build on the card title and make up the bulk of the card's content.</p>
+    <a href="#" class="btn btn-primary">Go somewhere</a>
+  </div>
+</div>
+
+<div class="card" aria-hidden="true">
+  <img src="..." class="card-img-top" alt="...">
+  <div class="card-body">
+    <h5 class="card-title placeholder-glow">
+      <span class="placeholder col-6"></span>
+    </h5>
+    <p class="card-text placeholder-glow">
+      <span class="placeholder col-7"></span>
+      <span class="placeholder col-4"></span>
+      <span class="placeholder col-4"></span>
+      <span class="placeholder col-6"></span>
+      <span class="placeholder col-8"></span>
+    </p>
+    <a href="#" tabindex="-1" class="btn btn-primary disabled placeholder col-6"></a>
+  </div>
+</div>
+```
+
+## How it works
+
+Create placeholders with the `.placeholder` class and a grid column class (e.g., `.col-6`) to set the `width`. They can replace the text inside an element or as be added as a modifier class to an existing component.
+
+We apply additional styling to `.btn`s via `::before` to ensure the `height` is respected. You may extend this pattern for other situations as needed, or add a `&nbsp;` within the element to reflect the height when actual text is rendered in its place.
+
+{{< example >}}
+<p aria-hidden="true">
+  <span class="placeholder col-6"></span>
+</p>
+
+<a href="#" class="btn btn-primary disabled placeholder col-4" aria-hidden="true"></a>
+{{< /example >}}
+
+{{< callout info >}}
+The use of `aria-hidden="true"` only indicates that the element should be hidden to screen readers. The *loading* behaviour of the placeholder depends on how authors will actually use the placeholder styles, how they plan to update things, etc. Some JavasSript code may be needed to *swap* the state of the placeholder and inform AT users of the update.
+{{< /callout >}}
+
+### Width
+
+You can change the `width` through grid column classes, width utilities, or inline styles.
+
+{{< example >}}
+<span class="placeholder col-6"></span>
+<span class="placeholder w-75"></span>
+<span class="placeholder" style="width: 25%;"></span>
+{{< /example >}}
+
+### Color
+
+By default, the `placeholder` uses `currentColor`. This can be overriden with a custom color or utility class.
+
+{{< example >}}
+<span class="placeholder col-12"></span>
+{{< placeholders.inline >}}
+{{- range (index $.Site.Data "theme-colors") }}
+<span class="placeholder col-12 bg-{{ .name }}"></span>
+{{- end -}}
+{{< /placeholders.inline >}}
+{{< /example >}}
+
+### Sizing
+
+The size of `.placeholder`s are based on the typographic style of the parent element. Customize them with sizing modifiers: `.placeholder-lg`, `.placeholder-sm`, or `.placeholder-xs`.
+
+{{< example >}}
+<span class="placeholder col-12 placeholder-lg"></span>
+<span class="placeholder col-12"></span>
+<span class="placeholder col-12 placeholder-sm"></span>
+<span class="placeholder col-12 placeholder-xs"></span>
+{{< /example >}}
+
+### Animation
+
+Animate placehodlers with `.placeholder-glow` or `.placeholder-wave` to better convey the perception of something being _actively_ loaded.
+
+{{< example >}}
+<p class="placeholder-glow">
+  <span class="placeholder col-12"></span>
+</p>
+
+<p class="placeholder-wave">
+  <span class="placeholder col-12"></span>
+</p>
+{{< /example >}}
+
+## Sass
+
+### Variables
+
+{{< scss-docs name="placeholders" file="scss/_variables.scss" >}}

diff --git a/site/data/sidebar.yml b/site/data/sidebar.yml
index 4bfdcc0ab461e462a31021c49760c6a09bd463f8..df95692afa3894b4404a427b98da4d4b1d04219e 100644 (file)
--- a/site/data/sidebar.yml
+++ b/site/data/sidebar.yml
@@ -75,6 +75,7 @@
     - title: Navbar
     - title: Offcanvas
     - title: Pagination
+    - title: Placeholders
     - title: Popovers
     - title: Progress
     - title: Scrollspy