docs(progress-bar): documentation updates

.changeset/easy-jobs-brush.md

@@ -0,0 +1,5 @@
+---
+'@spectrum-web-components/progress-bar': patch
+---
+
+**Added**: Deprecation warning for the over-background attribute.

packages/progress-bar/README.md

@@ -1,30 +1,46 @@
-## Description
+## Overview
 
-An `<sp-progress-bar>` shows the progression of a system operation such as downloading, uploading, processing, etc. in a visual way. It can represent determinate or indeterminate progress.
+An `<sp-progress-bar>` is used to visually show the progression of a system operation such as downloading, uploading, processing, etc. By default, progress bars have a blue fill that shows the progress.
 
 ### Usage
 
 [![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/progress-bar?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/progress-bar)
 [![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/progress-bar?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/progress-bar)
 [![Try it on Stackblitz](https://img.shields.io/badge/Try%20it%20on-Stackblitz-blue?style=for-the-badge)](https://stackblitz.com/edit/vitejs-vite-evntgrmn)
 
-```
+```zsh
 yarn add @spectrum-web-components/progress-bar
 ```
 
 Import the side effectful registration of `<sp-progress-bar>` via:
 
-```
+```ts
 import '@spectrum-web-components/progress-bar/sp-progress-bar.js';
 ```
 
 When looking to leverage the `ProgressBar` base class as a type and/or for extension purposes, do so via:
 
-```
+```ts
 import { ProgressBar } from '@spectrum-web-components/progress-bar';
 ```
 
-## Sizes
+### Anatomy
+
+Progress bars have the following parts:
+
+- **Label:** Progress bars should have a label that gives context about the operation being performed. Use an ellipsis at the end of the label text to communicate that the process is in progress.
+- **Value label:** Progress bars can have a value label that gives detailed information about the progress. This value label works alongside the label and should not be displayed if the label itself is not displayed. The value label is always placed above the track. Use the `progress` attribute to set the value label.
+
+```html
+<sp-progress-bar
+        label="Generating images..."
+        progress="58"
+    ></sp-progress-bar>
+```
+
+### Options
+
+#### Sizes
 
 <sp-tabs selected="m" auto label="Size Attribute Options">
 <sp-tab value="s">Small</sp-tab>
@@ -93,25 +109,30 @@ import { ProgressBar } from '@spectrum-web-components/progress-bar';
 </sp-tab-panel>
 </sp-tabs>
 
-## Variants
 
-### Over background
+#### Variants
 
-When a progress bar needs to be placed on top of a colored background, use the over background progres bar as signified by `[over-background]`. This progress bar uses a white opaque color no matter the background. Make sure the background offers enough contrast for the loader to be legible.
+<sp-tabs selected="static-white" auto label="Variants">
+<sp-tab value="static-white">Static white</sp-tab>
+<sp-tab-panel value="static-white">
+
+When a progress bar needs to be placed on top of a colored background, use the static white progress bar as signified by `[static-color="white"]`. This progress bar uses a white opaque color no matter the background. Make sure the background offers enough contrast for the loader to be legible.
 
 ```html
 <div
-    style="width: 240px; height: 160px; display: flex; flex-direction: column; align-items: center; justify-content: space-around; background-color: var(--spectrum-transparent-black-400);"
+    style="width: 240px; height: 160px; display: flex; flex-direction: column; align-items: center; justify-content: space-around; background-color: var(--spectrum-seafoam-900);"
 >
     <sp-progress-bar
         label="Loaded a large amount"
         progress="77"
-        over-background
+        static-color="white"
     ></sp-progress-bar>
 </div>
 ```
 
-### Indeterminate
+</sp-tab-panel>
+<sp-tab value="indeterminate">Indeterminate</sp-tab>
+<sp-tab-panel value="indeterminate">
 
 A progress bar can be either determinate or indeterminate as signified by `[indeterminate]`. By default, loaders are determinate. Use a determinate loader when progress can be calculated against a specific goal (e.g., downloading a file of a known size). Use an indeterminate loader when progress is happening but the time or effort to completion can’t be determined (e.g., attempting to reconnect to a server).
 
@@ -128,7 +149,9 @@ A progress bar can be either determinate or indeterminate as signified by `[inde
 
 The above `sp-progress-bar` also leverages the `aria-label` attribute in place of the `label` attribute in ensure that the element is labelled correctly without that label appearing visibly in the UI.
 
-### Side Label
+</sp-tab-panel>
+<sp-tab value="side-label">Side label</sp-tab>
+<sp-tab-panel value="side-label">
 
 A progress bar can be delivered with its labeling displayed above its visual indicator or to either side. Use the boolean `[side-label]` attribute to define where this content should appear.
 
@@ -138,12 +161,21 @@ A progress bar can be delivered with its labeling displayed above its visual ind
 >
     <sp-progress-bar
         side-label
-        indeterminate
         label="Label Beside"
+        progress="23"
     ></sp-progress-bar>
 </div>
 ```
 
-## Accessibility
+</sp-tab-panel>
+</sp-tabs>
+
+### Accessibility
+
+An `sp-progress-bar` element will register itself as a `role="progressbar"` element in the accessibility tree. Any value applied to the `label` attribute will be used both to visibly label the element and to set the `aria-label` attribute on the host.
+
+#### Include a label
+
+Progress bars should have a label that gives context about the operation being performed. Use an ellipsis at the end of the label text to communicate that the process is in progress. 
 
-An `sp-progress-bar` element will register itself as a `role="progressbar"` element in the accessibility tree. Any value applied to the `label` attribute will be used both to visibly label the element and to set the `aria-label` attribute on the host. In cases where a visible label is not desired, be sure to include an `aria-label` attribute manually to ensure that the `sp-progress-bar` correctly fulfills its responsibilities to visitors of you site of all abilities.
+ In rare cases where a visible label is not desired, context is sufficient and an accessibility expert has reviewed the design, be sure to include an `aria-label` attribute or an `aria-labelledby` attribute to manually to ensure that the `sp-progress-bar` correctly fulfills its responsibilities to visitors of your site of all abilities.

packages/progress-bar/package.json

@@ -71,6 +71,7 @@
     },
     "types": "./src/index.d.ts",
     "customElements": "custom-elements.json",
+    "deprecationNotice": "The over-background attribute has been deprecated and will be removed in a future release. Use static-color='white' instead.",
     "sideEffects": [
         "./sp-*.js",
         "./**/*.dev.js"

packages/progress-bar/src/ProgressBar.ts

@@ -51,8 +51,28 @@ export class ProgressBar extends SizedMixin(
 
     private languageResolver = new LanguageResolutionController(this);
 
-    @property({ type: Boolean, reflect: true, attribute: 'over-background' })
-    public overBackground = false;
+    @property({ type: Boolean, attribute: 'over-background' })
+    public get overBackground(): string {
+        return this._overBackground ? 'over-background' : '';
+    }
+    public set overBackground(overBackground: boolean) {
+        if (overBackground === true) {
+            this.removeAttribute('over-background');
+            this.staticColor = 'white';
+
+            if (window.__swc.DEBUG) {
+                window.__swc.warn(
+                    this,
+                    `The "over-background" attribute on <${this.localName}> has been deprecated and will be removed in a future release. Use "static-color='white'" instead.`,
+                    'https://opensource.adobe.com/spectrum-web-components/components/progress-bar/#variants',
+                    {
+                        level: 'deprecation',
+                    }
+                );
+            }
+        }
+    }
+    private _overBackground: boolean = false;
 
     @property({ type: Boolean, reflect: true, attribute: 'side-label' })
     public sideLabel = false;

packages/progress-bar/test/progress-bar.test.ts

@@ -169,7 +169,6 @@ describe('ProgressBar', () => {
 
             await elementUpdated(el);
 
-            expect(consoleWarnStub.called).to.be.true;
             const spyCall = consoleWarnStub.getCall(0);
             expect(
                 (spyCall.args.at(0) as string).includes('accessible'),
@@ -250,5 +249,54 @@ describe('ProgressBar', () => {
             expect(el.hasAttribute('aria-label')).to.be.true;
             expect(el.getAttribute('aria-label')).to.equal('Loading');
         });
+        it('warns in devMode for deprecated usage of over-background', async () => {
+            const el = await fixture<ProgressBar>(html`
+                <sp-progress-bar
+                    progress="50"
+                    over-background
+                    label="Loading"
+                ></sp-progress-bar>
+            `);
+
+            await elementUpdated(el);
+            expect(
+                consoleWarnStub.called,
+                'confirm deprecated over-background warning'
+            ).to.be.true;
+
+            const spyCall = consoleWarnStub.getCall(0);
+            expect(
+                (spyCall.args.at(0) as string).includes('deprecated'),
+                'confirm deprecated over-background warning'
+            ).to.be.true;
+            expect(spyCall.args.at(-1), 'confirm `data` shape').to.deep.equal({
+                data: {
+                    localName: 'sp-progress-bar',
+                    type: 'api',
+                    level: 'deprecation',
+                },
+            });
+        });
+        it('warns in Dev Mode when accessible attributes are not leveraged', async () => {
+            const el = await fixture<ProgressBar>(html`
+                <sp-progress-bar progress="50"></sp-progress-bar>
+            `);
+
+            await elementUpdated(el);
+
+            expect(consoleWarnStub.called).to.be.true;
+            const spyCall = consoleWarnStub.getCall(0);
+            expect(
+                (spyCall.args.at(0) as string).includes('accessible'),
+                'confirm accessibility-centric message'
+            ).to.be.true;
+            expect(spyCall.args.at(-1), 'confirm `data` shape').to.deep.equal({
+                data: {
+                    localName: 'sp-progress-bar',
+                    type: 'accessibility',
+                    level: 'default',
+                },
+            });
+        });
     });
 });