diff --git a/.changeset/easy-jobs-brush.md b/.changeset/easy-jobs-brush.md new file mode 100644 index 00000000000..30a09f3cc5f --- /dev/null +++ b/.changeset/easy-jobs-brush.md @@ -0,0 +1,5 @@ +--- +'@spectrum-web-components/progress-bar': patch +--- + +**Added**: Deprecation warning for the over-background attribute. diff --git a/packages/progress-bar/README.md b/packages/progress-bar/README.md index 35cf5c8d722..196ded308f4 100644 --- a/packages/progress-bar/README.md +++ b/packages/progress-bar/README.md @@ -1,6 +1,6 @@ -## Description +## Overview -An `` 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 `` 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 @@ -8,22 +8,29 @@ An `` shows the progression of a system operation such as downl [![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 `` 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'; ``` +### Anatomy + +- **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. + +Labels are set using the `label` slot and values are set using the `progress` slot. + ## Sizes @@ -93,25 +100,31 @@ import { ProgressBar } from '@spectrum-web-components/progress-bar'; -## Variants +### Options + +#### Variants -### Over background + +Static white + -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. +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
``` -### Indeterminate + +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 +141,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 + +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 +153,15 @@ A progress bar can be delivered with its labeling displayed above its visual ind > ``` -## Accessibility + + + +### 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. 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. diff --git a/packages/progress-bar/package.json b/packages/progress-bar/package.json index 9ef3ee57269..62f296dfd0c 100644 --- a/packages/progress-bar/package.json +++ b/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" diff --git a/packages/progress-bar/src/ProgressBar.ts b/packages/progress-bar/src/ProgressBar.ts index b162ca7eadc..bbc283203d8 100644 --- a/packages/progress-bar/src/ProgressBar.ts +++ b/packages/progress-bar/src/ProgressBar.ts @@ -146,6 +146,15 @@ export class ProgressBar extends SizedMixin( } if (window.__swc.DEBUG) { + if (changes.has('over-background')) { + 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' } + ); + } + if ( !this.label && !this.getAttribute('aria-label') && diff --git a/packages/progress-bar/test/progress-bar.test.ts b/packages/progress-bar/test/progress-bar.test.ts index 712dc629892..9580fd08317 100644 --- a/packages/progress-bar/test/progress-bar.test.ts +++ b/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,73 @@ 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(html` + + `); + + await elementUpdated(el); + + const overBackgroundWarning = consoleWarnStub + .getCalls() + .find((call) => + call.args.some( + (arg) => + typeof arg === 'string' && + arg.includes('over-background') + ) + ); + expect(overBackgroundWarning, 'should warn about over-background') + .to.exist; + const hasDeprecationLevel = consoleWarnStub + .getCalls() + .some((call) => + call.args.some( + (arg) => + arg && + typeof arg === 'object' && + arg.level === 'deprecation' + ) + ); + expect(hasDeprecationLevel, 'should have deprecation level').to.be + .true; + }); + it('warns in devMode when missing accessible labeling', async () => { + const el = await fixture(html` + + `); + + await elementUpdated(el); + const accessibilityWarning = consoleWarnStub + .getCalls() + .find((call) => + call.args.some( + (arg) => + typeof arg === 'string' && + arg.includes( + 'need one of the following to be accessible' + ) + ) + ); + expect( + accessibilityWarning, + 'should warn about accessible labeling' + ).to.exist; + const hasAccessibilityType = consoleWarnStub + .getCalls() + .some((call) => + call.args.some( + (arg) => + arg && + typeof arg === 'object' && + arg.type === 'accessibility' + ) + ); + expect(hasAccessibilityType, 'should have accessibility type').to.be + .true; + }); }); }); diff --git a/projects/documentation/content/_includes/partials/deprecation.njk b/projects/documentation/content/_includes/partials/deprecation.njk index 8a010554637..dd5a6cfe1c9 100644 --- a/projects/documentation/content/_includes/partials/deprecation.njk +++ b/projects/documentation/content/_includes/partials/deprecation.njk @@ -1,7 +1,7 @@
-
+
Deprecation Warning diff --git a/projects/documentation/src/components/inline-alert.css b/projects/documentation/src/components/inline-alert.css index 0dbba7065e0..feb680e12d3 100644 --- a/projects/documentation/src/components/inline-alert.css +++ b/projects/documentation/src/components/inline-alert.css @@ -1,128 +1,64 @@ -/** - * Copyright 2025 Adobe. All rights reserved. - * This file is licensed to you under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. You may obtain a copy - * of the License at http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software distributed under - * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS - * OF ANY KIND, either express or implied. See the License for the specific language - * governing permissions and limitations under the License. - */ +/*! +Copyright 2023 Adobe. All rights reserved. +This file is licensed to you under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. You may obtain a copy +of the License at http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software distributed under +the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS +OF ANY KIND, either express or implied. See the License for the specific language +governing permissions and limitations under the License. +*/ .spectrum-InLineAlert { /* Font */ - --spectrum-inlinealert-heading-font-family: var( - --spectrum-sans-font-family-stack - ); - --spectrum-inlinealert-heading-font-weight: var( - --spectrum-heading-sans-serif-font-weight - ); - --spectrum-inlinealert-heading-font-style: var( - --spectrum-heading-sans-serif-font-style - ); + --spectrum-inlinealert-heading-font-family: var(--spectrum-sans-font-family-stack); + --spectrum-inlinealert-heading-font-weight: var(--spectrum-heading-sans-serif-font-weight); + --spectrum-inlinealert-heading-font-style: var(--spectrum-heading-sans-serif-font-style); --spectrum-inlinealert-heading-font-size: var(--spectrum-heading-size-xxs); - --spectrum-inlinealert-heading-line-height: var( - --spectrum-heading-line-height - ); - --spectrum-inlinealert-content-font-family: var( - --spectrum-sans-font-family-stack - ); - --spectrum-inlinealert-content-font-weight: var( - --spectrum-body-sans-serif-font-weight - ); - --spectrum-inlinealert-content-font-style: var( - --spectrum-body-sans-serif-font-style - ); + --spectrum-inlinealert-heading-line-height: var(--spectrum-heading-line-height); + --spectrum-inlinealert-content-font-family: var(--spectrum-sans-font-family-stack); + --spectrum-inlinealert-content-font-weight: var(--spectrum-body-sans-serif-font-weight); + --spectrum-inlinealert-content-font-style: var(--spectrum-body-sans-serif-font-style); --spectrum-inlinealert-content-font-size: var(--spectrum-body-size-s); - --spectrum-inlinealert-content-line-height: var( - --spectrum-body-line-height - ); + --spectrum-inlinealert-content-line-height: var(--spectrum-body-line-height); /* Size */ --spectrum-inlinealert-border-width: var(--spectrum-border-width-200); --spectrum-inlinealert-border-radius: var(--spectrum-corner-radius-100); --spectrum-inlinealert-icon-size: var(--spectrum-workflow-icon-size-100); - --spectrum-inlinealert-min-inline-size: var( - --spectrum-in-line-alert-minimum-width - ); - --spectrum-inlinealert-header-min-block-size: var( - --spectrum-component-height-50 - ); + --spectrum-inlinealert-min-inline-size: var(--spectrum-in-line-alert-minimum-width); + --spectrum-inlinealert-header-min-block-size: var(--spectrum-component-height-50); /* Spacing */ --spectrum-inlinealert-spacing-edge-to-text: var(--spectrum-spacing-400); --spectrum-inlinealert-spacing-header-to-icon: var(--spectrum-spacing-400); - --spectrum-inlinealert-spacing-header-content-button: var( - --spectrum-spacing-300 - ); + --spectrum-inlinealert-spacing-header-content-button: var(--spectrum-spacing-300); /* Color */ - --spectrum-inlinealert-background-color: var( - --spectrum-background-layer-2-color - ); - --spectrum-inlinealert-border-and-icon-color: var( - --spectrum-neutral-visual-color - ); + --spectrum-inlinealert-background-color: var(--spectrum-background-layer-2-color); + --spectrum-inlinealert-border-and-icon-color: var(--spectrum-neutral-visual-color); --spectrum-inlinealert-header-color: var(--spectrum-heading-color); --spectrum-inlinealert-content-color: var(--spectrum-body-color); - --spectrum-inlinealert-border-and-icon-color-info: var( - --spectrum-informative-visual-color - ); - --spectrum-inlinealert-border-and-icon-color-positive: var( - --spectrum-positive-visual-color - ); - --spectrum-inlinealert-border-and-icon-color-notice: var( - --spectrum-notice-visual-color - ); - --spectrum-inlinealert-border-and-icon-color-negative: var( - --spectrum-negative-visual-color - ); + --spectrum-inlinealert-border-and-icon-color-info: var(--spectrum-informative-visual-color); + --spectrum-inlinealert-border-and-icon-color-positive: var(--spectrum-positive-visual-color); + --spectrum-inlinealert-border-and-icon-color-notice: var(--spectrum-notice-visual-color); + --spectrum-inlinealert-border-and-icon-color-negative: var(--spectrum-negative-visual-color); } .spectrum-InLineAlert { position: relative; display: inline-block; box-sizing: border-box; - min-inline-size: var( - --mod-inlinealert-min-inline-size, - var(--spectrum-inlinealert-min-inline-size) - ); - padding-block: var( - --mod-inlinealert-spacing-edge-to-text, - var(--spectrum-inlinealert-spacing-edge-to-text) - ); - padding-inline: var( - --mod-inlinealert-spacing-edge-to-text, - var(--spectrum-inlinealert-spacing-edge-to-text) - ); - border-block-width: var( - --mod-inlinealert-border-width, - var(--spectrum-inlinealert-border-width) - ); - border-inline-width: var( - --mod-inlinealert-border-width, - var(--spectrum-inlinealert-border-width) - ); + min-inline-size: var(--mod-inlinealert-min-inline-size, var(--spectrum-inlinealert-min-inline-size)); + padding-block: var(--mod-inlinealert-spacing-edge-to-text, var(--spectrum-inlinealert-spacing-edge-to-text)); + padding-inline: var(--mod-inlinealert-spacing-edge-to-text, var(--spectrum-inlinealert-spacing-edge-to-text)); + border-block-width: var(--mod-inlinealert-border-width, var(--spectrum-inlinealert-border-width)); + border-inline-width: var(--mod-inlinealert-border-width, var(--spectrum-inlinealert-border-width)); border-style: solid; - border-radius: var( - --mod-inlinealert-border-radius, - var(--spectrum-inlinealert-border-radius) - ); - background-color: var( - --highcontrast-inlinealert-background-color, - var( - --mod-inlinealert-background-color, - var(--spectrum-inlinealert-background-color) - ) - ); - border-color: var( - --highcontrast-inlinealert-border-and-icon-color, - var( - --mod-inlinealert-border-and-icon-color, - var(--spectrum-inlinealert-border-and-icon-color) - ) - ); + border-radius: var(--mod-inlinealert-border-radius, var(--spectrum-inlinealert-border-radius)); + background-color: var(--highcontrast-inlinealert-background-color, var(--mod-inlinealert-background-color, var(--spectrum-inlinealert-background-color))); + border-color: var(--highcontrast-inlinealert-border-and-icon-color, var(--mod-inlinealert-border-and-icon-color, var(--spectrum-inlinealert-border-and-icon-color))); } @media (forced-colors: active) { @@ -140,100 +76,37 @@ justify-content: space-between; /* Minimum space between header and icon */ - gap: var( - --mod-inlinealert-spacing-header-to-icon, - var(--spectrum-inlinealert-spacing-header-to-icon) - ); - font-weight: var( - --mod-inlinealert-heading-font-weight, - var(--spectrum-inlinealert-heading-font-weight) - ); - font-family: var( - --mod-inlinealert-heading-font-family, - var(--spectrum-inlinealert-heading-font-family) - ); - font-style: var( - --mod-inlinealert-heading-font-style, - var(--spectrum-inlinealert-heading-font-style) - ); - font-size: var( - --mod-inlinealert-heading-font-size, - var(--spectrum-inlinealert-heading-font-size) - ); - line-height: var( - --mod-inlinealert-heading-line-height, - var(--spectrum-inlinealert-heading-line-height) - ); + gap: var(--mod-inlinealert-spacing-header-to-icon, var(--spectrum-inlinealert-spacing-header-to-icon)); + font-weight: var(--mod-inlinealert-heading-font-weight, var(--spectrum-inlinealert-heading-font-weight)); + font-family: var(--mod-inlinealert-heading-font-family, var(--spectrum-inlinealert-heading-font-family)); + font-style: var(--mod-inlinealert-heading-font-style, var(--spectrum-inlinealert-heading-font-style)); + font-size: var(--mod-inlinealert-heading-font-size, var(--spectrum-inlinealert-heading-font-size)); + line-height: var(--mod-inlinealert-heading-line-height, var(--spectrum-inlinealert-heading-line-height)); text-transform: none; - min-block-size: var( - --mod-inlinealert-header-min-block-size, - var(--spectrum-inlinealert-header-min-block-size) - ); - color: var( - --highcontrast-inlinealert-header-color, - var( - --mod-inlinealert-header-color, - var(--spectrum-inlinealert-header-color) - ) - ); + min-block-size: var(--mod-inlinealert-header-min-block-size, var(--spectrum-inlinealert-header-min-block-size)); + color: var(--highcontrast-inlinealert-header-color, var(--mod-inlinealert-header-color, var(--spectrum-inlinealert-header-color))); } .spectrum-InLineAlert-content { display: block; - margin-block-start: var( - --mod-inlinealert-spacing-header-content-button, - var(--spectrum-inlinealert-spacing-header-content-button) - ); + margin-block-start: var(--mod-inlinealert-spacing-header-content-button, var(--spectrum-inlinealert-spacing-header-content-button)); margin-block-end: 0; margin-inline-start: 0; margin-inline-end: 0; padding: 0; word-wrap: break-word; - font-weight: var( - --mod-inlinealert-content-font-weight, - var(--spectrum-inlinealert-content-font-weight) - ); - font-family: var( - --mod-inlinealert-content-font-family, - var(--spectrum-inlinealert-content-font-family) - ); - font-style: var( - --mod-inlinealert-content-font-style, - var(--spectrum-inlinealert-content-font-style) - ); - font-size: var( - --mod-inlinealert-content-font-size, - var(--spectrum-inlinealert-content-font-size) - ); - line-height: var( - --mod-inlinealert-content-line-height, - var(--spectrum-inlinealert-content-line-height) - ); - color: var( - --highcontrast-inlinealert-content-color, - var( - --mod-inlinealert-content-color, - var(--spectrum-inlinealert-content-color) - ) - ); + font-weight: var(--mod-inlinealert-content-font-weight, var(--spectrum-inlinealert-content-font-weight)); + font-family: var(--mod-inlinealert-content-font-family, var(--spectrum-inlinealert-content-font-family)); + font-style: var(--mod-inlinealert-content-font-style, var(--spectrum-inlinealert-content-font-style)); + font-size: var(--mod-inlinealert-content-font-size, var(--spectrum-inlinealert-content-font-size)); + line-height: var(--mod-inlinealert-content-line-height, var(--spectrum-inlinealert-content-line-height)); + color: var(--highcontrast-inlinealert-content-color, var(--mod-inlinealert-content-color, var(--spectrum-inlinealert-content-color))); } -.spectrum-InLineAlert--negative { - border-color: var( - --highcontrast-inlinealert-border-and-icon-color, - var( - --mod-inlinealert-border-and-icon-color-negative, - var(--spectrum-inlinealert-border-and-icon-color-negative) - ) - ); +.spectrum-InLineAlert--notice { + border-color: var(--highcontrast-inlinealert-border-and-icon-color, var(--mod-inlinealert-border-and-icon-color-notice, var(--spectrum-inlinealert-border-and-icon-color-notice))); +} - .spectrum-InLineAlert-icon { - color: var( - --highcontrast-inlinealert-border-and-icon-color, - var( - --mod-inlinealert-border-and-icon-color-negative, - var(--spectrum-inlinealert-border-and-icon-color-negative) - ) - ); - } +.spectrum-InLineAlert--notice .spectrum-InLineAlert-icon { + color: var(--highcontrast-inlinealert-border-and-icon-color, var(--mod-inlinealert-border-and-icon-color-notice, var(--spectrum-inlinealert-border-and-icon-color-notice))); }