docs(progressbar): adds missing stories, tests, controls

- adds relevant S2 controls to template
- expands test coverage to include without label and without value label
- adds stories and documentation to docs page
- adds additional migration guide context to CHANGELOG

components/progressbar/CHANGELOG.md

@@ -1320,10 +1320,18 @@ Co-authored-by: Bernhard Schmidt <[email protected]
 
 - use Field label instead of custom classes ([dd9d369](https://github.com/adobe/spectrum-css/commit/dd9d369))
 
+### Label and percentage now use Field Label
+
+Progress bar now uses Field label for its label and percentage. Add the appropriately sized Field label to match the t-shirt size of the Progress bar.
+
 ### ✨ Features
 
 - t-shirt sizing for ProgressBar, update notice classes, closes [#955](https://github.com/adobe/spectrum-css/issues/955) ([440ce85](https://github.com/adobe/spectrum-css/commit/440ce85))
 
+#### T-shirt sizing
+
+Progress bar now supports t-shirt sizing and requires that you specify the size of button by adding a `.spectrum-ProgressBar--size*` class.
+
 ### 🐛 Bug fixes
 
 - allow customizing ProgressBar width, fixes [#1064](https://github.com/adobe/spectrum-css/issues/1064) ([5b39f67](https://github.com/adobe/spectrum-css/commit/5b39f67))
@@ -1335,9 +1343,18 @@ Co-authored-by: Bernhard Schmidt <[email protected]
 ### 🛑 BREAKING CHANGES
 
 - Progress bar now uses Field label
-- .spectrum-ProgressBar--large renamed to .spectrum-ProgressBar--sizeM, .spectrum-ProgressBar--large renamed to .spectrum-ProgressBar--sizeS is required for previous
+- .spectrum-ProgressBar--large renamed to .spectrum-ProgressBar--sizeM, .spectrum-ProgressBar--small renamed to .spectrum-ProgressBar--sizeS is required for previous
 - ProgressBar .is-warning renamed to .is-notice, .is-critical renamed to .is-negative
 
+#### Size classnames changed
+
+Previous size classnames map as follows:
+
+| Previous size classname        | New size classname             |
+| ------------------------------ | ------------------------------ |
+| `.spectrum-ProgressBar--small` | `.spectrum-ProgressBar--sizeS` |
+| `.spectrum-ProgressBar--large` | `.spectrum-ProgressBar--sizeM` |
+
 <a name="1.0.0-beta.2"></a>
 
 ## 1.0.0-beta.2
@@ -1356,6 +1373,12 @@ Co-authored-by: Bernhard Schmidt <[email protected]
 
 - removed more deprecations ([70dd116](https://github.com/adobe/spectrum-css/commit/70dd116))
 
+### 🛑 BREAKING CHANGES
+
+#### Component renamed
+
+Bar loader is now known as Progress bar. Replace all .spectrum-BarLoader* classnames with .spectrum-ProgressBar*.
+
 <a name="3.0.0-beta.2"></a>
 
 ## 3.0.0-beta.2

components/progressbar/stories/progressbar.stories.js

@@ -1,15 +1,33 @@
 import { disableDefaultModes } from "@spectrum-css/preview/modes";
+import { Sizes } from "@spectrum-css/preview/decorators";
 import { isIndeterminate, size, staticColor } from "@spectrum-css/preview/types";
 import { ProgressBarGroup } from "./progressbar.test.js";
+import { IndeterminateGroup, Template } from "./template.js";
 
 /**
  * The progress bar component shows the progression of a system operation such as downloading, uploading, processing, etc. in a visual way.
+ * 
+ * ## Values
+ * The value is the progress of a system operation (e.g., downloading, uploading, processing) within the progress bar’s range, from the min value to max value. By default, the min value starts at 0 and the max value is set to 100. These values are not applicable when a progress bar is indeterminate.
+ * 
+ * Progress bars can have a value label at the end of the track that gives detailed information about the progress (e.g. "60%" or "2 of 8"). This value label works alongside the label and should not be displayed if the label itself is not displayed. It should also not be displayed if the progress is indeterminate. Similar to the label, the value label is always placed above the track.
  */
 export default {
 	title: "Progress bar",
 	component: "ProgressBar",
 	argTypes: {
-		customWidth: { table: { disable: true } },
+		customWidth: {
+			name: "Custom width",
+			defaultValue: 192,
+			description: "Adjust the width of the component between 48px and 768px. 192px is the default width on desktop, while 240px is the default on mobile.",
+			type: { name: "number" },
+			table: {
+				type: { summary: "number" },
+				category: "Component",
+				defaultValue: { summary: 192 },
+			},
+			control: { type: "range", min: 48, max: 768,},
+		},
 		size: size(["s", "m", "l", "xl"]),
 		isIndeterminate,
 		labelPosition: {
@@ -18,6 +36,9 @@ export default {
 			table: {
 				type: { summary: "string" },
 				category: "Component",
+
+				// todo: side labels are not supported according to S1 documentation, but will be in S2. Remove the disable: true once S2 is released
+				disable: true,
 			},
 			options: ["top", "side"],
 			control: "select",
@@ -41,6 +62,17 @@ export default {
 			control: { type: "range", min: 0, max: 100,},
 			if: { arg: "isIndeterminate", truthy: false },
 		},
+		showValueLabel: {
+			name: "Show value label",
+			description: "The value label should not be displayed if the label itself is not displayed.",
+			type: { name: "boolean" },
+			table: {
+				type: { summary: "boolean" },
+				category: "Content",
+			},
+			control: { type: "boolean" },
+			if: { arg: "isIndeterminate", truthy: false },
+		},
 		trackFill: { table: { disable: true }},
 		progressBarFill: { table: { disable: true }},
 		staticColor: {
@@ -51,18 +83,110 @@ export default {
 	args: {
 		rootClass: "spectrum-ProgressBar",
 		size: "m",
+		label: "Loading",
 		labelPosition: "top",
 		value: 0,
 		isIndeterminate: false,
+		showValueLabel: true,
 	},
 };
 
+/**
+ * By default, progress bars are determinate and have a blue fill that shows the progress. This component should have a label at the start of the track that gives context about the operation being performed. In rare cases where context is sufficient and an accessibility expert has reviewed the design, the label could be undefined. These progress bars should still include an “aria-label” or “aria-labelledby” in HTML, depending on the context. The label is always placed above the track.
+ * 
+ * When the label is too long for the available horizontal space, it wraps to form another line. The value is always shown in full and never wraps or truncates.
+ */
 export const Default = ProgressBarGroup.bind({});
 Default.args = {
-	label: "Loading",
 	value: 50,
 };
 
+/**
+ * Progress bars come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option.
+ */
+export const Sizing = (args, context) => Sizes({
+	Template,
+	withBorder: false,
+	withHeading: false,
+	...args, 
+}, context);
+Sizing.args = Default.args;
+Sizing.tags = ["!dev"];
+Sizing.parameters = {
+	chromatic: { disableSnapshot: true },
+};
+
+/**
+ * Progress bars can represent either determinate or indeterminate progress. Use a determinate progress bar when progress can be calculated against a specific goal (e.g., downloading a file of a known size). Use an indeterminate progress bar when progress is happening, but the time or effort to completion can’t be determined (e.g., attempting to reconnect to a server).
+ */
+export const Indeterminate = IndeterminateGroup.bind({});
+Indeterminate.args = {
+	value: 50,
+};
+Indeterminate.tags = ["!dev"];
+Indeterminate.parameters = {
+	chromatic: { disableSnapshot: true },
+};
+
+/**
+ * The minimum width of a progress bar is 48px and the maximum width of a progress bar is 768px, for both desktop and mobile platform scale. Smaller progress bars should only be used in places where it’s not necessary to have a label.
+ */
+export const CustomWidth = Template.bind({});
+CustomWidth.storyName = "Custom width";
+CustomWidth.args = {
+	value: 83,
+	customWidth: 400,
+};
+CustomWidth.tags = ["!dev"];
+CustomWidth.parameters = {
+	chromatic: { disableSnapshot: true },
+};
+
+/**
+ * The example below shows a progress bar without its label. Progress bars typically have a label, but in rare cases where context is sufficient and an accessibility expert has reviewed the design, the label could be undefined.
+ */
+export const WithoutLabel = Template.bind({});
+WithoutLabel.storyName = "Without label";
+WithoutLabel.args = {
+	label: "",
+	value: 50,
+	showValueLabel: false,
+};
+WithoutLabel.tags = ["!dev"];
+WithoutLabel.parameters = {
+	chromatic: { disableSnapshot: true },
+};
+
+/**
+ * The example below shows a progress bar without its value label. This value label works in conjunction with the label, and should not be displayed if the label itself is not displayed.
+ */
+export const WithoutValue = Template.bind({});
+WithoutValue.storyName = "Without value";
+WithoutValue.args = {
+	value: 83,
+	showValueLabel: false,
+};
+WithoutValue.tags = ["!dev"];
+WithoutValue.parameters = {
+	chromatic: {
+		modes: disableDefaultModes
+	},
+};
+
+export const StaticWhiteDocs = Template.bind({});
+StaticWhiteDocs.storyName = "Static white";
+StaticWhiteDocs.args = {
+	staticColor: "white",
+	label: "Loading your fonts, images, and icons",
+	value: 50,
+};
+StaticWhiteDocs.tags = ["!dev"];
+StaticWhiteDocs.parameters = {
+	chromatic: {
+		modes: disableDefaultModes
+	},
+};
+
 // ********* VRT ONLY ********* //
 export const WithForcedColors = ProgressBarGroup.bind({});
 WithForcedColors.args = Default.args;

components/progressbar/stories/progressbar.test.js

@@ -15,6 +15,15 @@ export const ProgressBarGroup = Variants({
 			testHeading: "Text overflow",
 			label: "Storage space remaining for XYZ user"
 		},
+		{
+			testHeading: "Without label",
+			label: undefined,
+			showValueLabel: false,
+		},
+		{
+			testHeading: "Without value label",
+			showValueLabel: false,
+		},
 		/* The gradient story below supports linear-gradients used by Express. For use cases that require a custom 
 		linear-gradient for any --mod-*-{fill} properties, set those custom properties in CSS.
 		*/

components/progressbar/stories/template.js

@@ -1,4 +1,5 @@
 import { Template as FieldLabel } from "@spectrum-css/fieldlabel/stories/template.js";
+import { Container } from "@spectrum-css/preview/decorators";
 import { html } from "lit";
 import { classMap } from "lit/directives/class-map.js";
 import { ifDefined } from "lit/directives/if-defined.js";
@@ -16,6 +17,7 @@ export const Template = ({
 	isIndeterminate = false,
 	label,
 	value,
+	showValueLabel = true,
 	trackFill,
 	progressBarFill,
 	customStyles = {},
@@ -31,7 +33,7 @@ export const Template = ({
 				...customClasses.reduce((a, c) => ({ ...a, [c]: true }), {}),
 			})}
 			style=${styleMap({
-				"width": customWidth,
+				"width": `${customWidth}px`,
 				...customStyles,
 				"--mod-progressbar-track-color": trackFill,
 				"--mod-progressbar-fill-color": progressBarFill,
@@ -49,7 +51,7 @@ export const Template = ({
 			}, context)}
 			${FieldLabel({
 				size,
-				label: isIndeterminate || typeof value === "undefined" ? "" : `${value}%`,
+				label: isIndeterminate || typeof value === "undefined" || !showValueLabel ? "" : `${value}%`,
 				customClasses: [`${rootClass}-percentage`],
 			}, context)}
 
@@ -61,3 +63,22 @@ export const Template = ({
 			</div>
 		</div>
 `;
+
+/* This template shows determinate and indeterminate progress bars  */
+export const IndeterminateGroup = (args, context) => Container({
+	Template,
+	withBorder: false,
+	withHeading: false,
+	content: html`
+		${Container({
+			withBorder: false,
+			heading: "Determinate",
+			content: Template(args, context)
+		})}
+		${Container({
+			withBorder: false,
+			heading: "Indeterminate",
+			content: Template({ ...args, isIndeterminate: true }, context)
+		})}
+	`
+});