From 26a3ef1bcb147d3a3b79610f674298e6fdfb11fe Mon Sep 17 00:00:00 2001 From: "Patrick H. Lauke" Date: Tue, 29 Nov 2022 07:07:48 +0000 Subject: [PATCH] Rework progress bar markup and styles (#36831) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Rework progress bar markup and styles Logically moves the various `role` and `aria-` attributes to the `.progress` element itself, leaving the `.progress-bar` to be used purely for the visual presentation. This fixes the problem #36736 that in certain browser/AT combinations, zero-value/zero-width progress bars are completely ignored and not announced. For multiple/stacked progress bars, this PR introduces a new wrapper and class `.progress-stacked`, to accommodate for the fact that with the more logical structure above, we need full `.progress` elements with child `.progress-bar` elements, and can't get away with the fudge we had before of having a single `.progress` with multiple `.progress-bar`s. Note that the old markup structures still work with this change, so this could be considered a non-breaking change - though one we definitely want to highlight as it's more accessible (as it now guarantees that zero-value/zero-width progress bars, whether on their own or as part of a multi/stacked bar, are actually announced) * Add a note about progress bar change in migration guide * Add notes with old markup examples and explanation * Fix bundlewatch * Update site/content/docs/5.2/components/progress.md Co-authored-by: Julien Déramond * Reintroduce deleted styles Turns out they're needed for correct positioning of text inside progress bar * Move changes in markup to Migrationg guide, link to that from top of progress page, rewrite some content * Fix typo in callout * Clarify "Sizing" section * Remove redundant "now" Co-authored-by: Julien Déramond Co-authored-by: Julien Déramond Co-authored-by: Mark Otto Co-authored-by: Mark Otto --- scss/_progress.scss | 11 +- site/content/docs/5.2/components/progress.md | 127 ++++++++++-------- .../5.2/examples/cheatsheet-rtl/index.html | 30 +++-- .../docs/5.2/examples/cheatsheet/index.html | 30 +++-- site/content/docs/5.2/migration.md | 42 ++++++ site/content/docs/5.2/utilities/position.md | 4 +- 6 files changed, 159 insertions(+), 85 deletions(-) diff --git a/scss/_progress.scss b/scss/_progress.scss index 1bfafb58fa..148c3815e8 100644 --- a/scss/_progress.scss +++ b/scss/_progress.scss @@ -8,7 +8,8 @@ } // scss-docs-end progress-keyframes -.progress { +.progress, +.progress-stacked { // scss-docs-start progress-css-vars --#{$prefix}progress-height: #{$progress-height}; @include rfs($progress-font-size, --#{$prefix}progress-font-size); @@ -46,6 +47,14 @@ background-size: var(--#{$prefix}progress-height) var(--#{$prefix}progress-height); } +.progress-stacked > .progress { + overflow: visible; +} + +.progress-stacked > .progress > .progress-bar { + width: 100%; +} + @if $enable-transitions { .progress-bar-animated { animation: $progress-bar-animation-timing progress-bar-stripes; diff --git a/site/content/docs/5.2/components/progress.md b/site/content/docs/5.2/components/progress.md index a06aafafff..c441f13c85 100644 --- a/site/content/docs/5.2/components/progress.md +++ b/site/content/docs/5.2/components/progress.md @@ -6,40 +6,62 @@ group: components toc: true --- +{{< callout info >}} +**New markup in v5.3.0 —** We've deprecated the previous HTML structure for progress bars and replaced it with a more accessible one. The previous structure will continue to work until v6. [See what's changed in our migration guide.]({{< docsref "/migration#improved-markup-for-progress-bars" >}}) +{{< /callout >}} + ## How it works Progress components are built with two HTML elements, some CSS to set the width, and a few attributes. We don't use [the HTML5 `` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/progress), ensuring you can stack progress bars, animate them, and place text labels over them. - We use the `.progress` as a wrapper to indicate the max value of the progress bar. -- We use the inner `.progress-bar` to indicate the progress so far. -- The `.progress-bar` requires an inline style, utility class, or custom CSS to set their width. -- The `.progress-bar` also requires some `role` and `aria` attributes to make it accessible, including an accessible name (using `aria-label`, `aria-labelledby`, or similar). +- The `.progress` wrapper also requires a `role="progress"` and `aria` attributes to make it accessible, including an accessible name (using `aria-label`, `aria-labelledby`, or similar). +- We use the inner `.progress-bar` purely for the visual bar and label. +- The `.progress-bar` requires an inline style, utility class, or custom CSS to set its width. +- We provide a special `.progress-stacked` class to create multiple/stacked progress bars. Put that all together, and you have the following examples. {{< example >}} -
-
+
+
-
-
+
+
-
-
+
+
-
-
+
+
-
-
+
+
{{< /example >}} -Bootstrap provides a handful of [utilities for setting width]({{< docsref "/utilities/sizing" >}}). Depending on your needs, these may help with quickly configuring progress. +## Bar sizing + +### Width + +Bootstrap provides a handful of [utilities for setting width]({{< docsref "/utilities/sizing" >}}). Depending on your needs, these may help with quickly configuring the width of the `.progress-bar`. {{< example >}} -
-
+
+
+
+{{< /example >}} + +### Height + +You only set a `height` value on the `.progress` container, so if you change that value, the inner `.progress-bar` will automatically resize accordingly. + +{{< example >}} +
+
+
+
+
{{< /example >}} @@ -48,21 +70,8 @@ Bootstrap provides a handful of [utilities for setting width]({{< docsref "/util Add labels to your progress bars by placing text within the `.progress-bar`. {{< example >}} -
-
25%
-
-{{< /example >}} - -## Height - -We only set a `height` value on the `.progress`, so if you change that value the inner `.progress-bar` will automatically resize accordingly. - -{{< example >}} -
-
-
-
-
+
+
25%
{{< /example >}} @@ -71,17 +80,17 @@ We only set a `height` value on the `.progress`, so if you change that value the Use background utility classes to change the appearance of individual progress bars. {{< example >}} -
-
+
+
-
-
+
+
-
-
+
+
-
-
+
+
{{< /example >}} @@ -91,13 +100,19 @@ Use background utility classes to change the appearance of individual progress b ## Multiple bars -Include multiple progress bars in a progress component if you need. +You can include multiple progress components inside a container with `.progress-stacked` to create a single stacked progress bar. Note that in this case, the styling to set the visual width of the progress bar *must* be applied to the `.progress` elements, rather than the `.progress-bar`s. {{< example >}} -
-
-
-
+
+
+
+
+
+
+
+
+
+
{{< /example >}} @@ -106,20 +121,20 @@ Include multiple progress bars in a progress component if you need. Add `.progress-bar-striped` to any `.progress-bar` to apply a stripe via CSS gradient over the progress bar's background color. {{< example >}} -
-
+
+
-
-
+
+
-
-
+
+
-
-
+
+
-
-
+
+
{{< /example >}} @@ -128,8 +143,8 @@ Add `.progress-bar-striped` to any `.progress-bar` to apply a stripe via CSS gra The striped gradient can also be animated. Add `.progress-bar-animated` to `.progress-bar` to animate the stripes right to left via CSS3 animations. {{< example >}} -
-
+
+
{{< /example >}} diff --git a/site/content/docs/5.2/examples/cheatsheet-rtl/index.html b/site/content/docs/5.2/examples/cheatsheet-rtl/index.html index a05799873a..d3d0c6f008 100644 --- a/site/content/docs/5.2/examples/cheatsheet-rtl/index.html +++ b/site/content/docs/5.2/examples/cheatsheet-rtl/index.html @@ -1397,27 +1397,31 @@ direction: rtl
{{< example show_markup="false" >}} -
-
0%
+
+
0%
-
-
25%
+
+
25%
-
-
50%
+
+
50%
-
-
75%
+
+
75%
-
-
100%
+
+
100%
{{< /example >}} {{< example show_markup="false" >}} -
-
-
+
+
+
+
+
+
+
{{< /example >}}
diff --git a/site/content/docs/5.2/examples/cheatsheet/index.html b/site/content/docs/5.2/examples/cheatsheet/index.html index a2285d0ed7..6ee32654d1 100644 --- a/site/content/docs/5.2/examples/cheatsheet/index.html +++ b/site/content/docs/5.2/examples/cheatsheet/index.html @@ -1394,27 +1394,31 @@ body_class: "bg-light"
{{< example show_markup="false" >}} -
-
0%
+
+
0%
-
-
25%
+
+
25%
-
-
50%
+
+
50%
-
-
75%
+
+
75%
-
-
100%
+
+
100%
{{< /example >}} {{< example show_markup="false" >}} -
-
-
+
+
+
+
+
+
+
{{< /example >}}
diff --git a/site/content/docs/5.2/migration.md b/site/content/docs/5.2/migration.md index c7942e5c34..0b71ec3bce 100644 --- a/site/content/docs/5.2/migration.md +++ b/site/content/docs/5.2/migration.md @@ -78,6 +78,48 @@ Learn more by reading the new [color modes documentation]({{< docsref "/customiz - Deprecated The `.navbar-dark` class has been deprecated and replaced with `data-bs-theme="dark"` on the navbar or any parent element. [See the docs for updated examples.]({{< docsref "/components/navbar#color-schemes" >}}) +### Progress bars + +The markup for [progress bars]({{< docsref "/components/progress" >}}) has been updated in v5.3.0. Due to the placement of `role` and various `aria-` attributes on the inner `.progress-bar` element, **some screen readers were not announcing zero value progress bars**. Now, `role="progressbar"` and the relevant `aria-*` attributes are on the outer `.progress` element, leaving the `.progress-bar` purely for the visual presentation of the bar and optional label. + +While we recommend adopting the new markup for improved compatibility with all screen readers, note that the legacy progress bar structure will continue to work as before. + +```html + +
+
+
+ + +
+
+
+``` + +We've also introduced a new `.progress-stacked` class to more logically wrap [multiple progress bars]({{< docsref "/components/progress#multiple-bars" >}}) into a single stacked progress bar. + +```html + +
+
+
+
+
+ + +
+
+
+
+
+
+
+
+
+
+
+``` + ### Forms - `.form-control` is now styled with CSS variables to support color modes. This includes the addition of two new root CSS variables for the default and disabled form control backgrounds. diff --git a/site/content/docs/5.2/utilities/position.md b/site/content/docs/5.2/utilities/position.md index 3b1394263e..0ba0dd7695 100644 --- a/site/content/docs/5.2/utilities/position.md +++ b/site/content/docs/5.2/utilities/position.md @@ -106,8 +106,8 @@ You can use these classes with existing components to create new ones. Remember {{< example class="bd-example-position-examples" >}}
-
-
+
+