From 64c72e2fe0ad5fb008b0c5706b6ac09314eccdab Mon Sep 17 00:00:00 2001
From: Marcelo Serpa <boss@fullofcaffeine.com>
Date: Wed, 22 May 2024 17:05:10 -0600
Subject: [PATCH] Keep an unconstrained width by default, while allowing
 consumers to override it with CSS

---
 .../components/src/progress-bar/README.md     | 46 ++++++++++++++++--
 .../components/src/progress-bar/index.tsx     | 47 +++++++++++++++++++
 .../src/progress-bar/stories/index.story.tsx  | 32 +++++++++++--
 .../components/src/progress-bar/styles.ts     |  1 -
 .../src/components/canvas-loader/index.js     |  7 ++-
 .../src/components/canvas-loader/style.scss   |  4 ++
 .../font-library-modal/font-collection.js     |  2 +-
 .../font-library-modal/installed-fonts.js     |  6 ++-
 .../font-library-modal/style.scss             |  4 ++
 .../font-library-modal/upload-fonts.js        |  2 +-
 10 files changed, 138 insertions(+), 13 deletions(-)

diff --git a/packages/components/src/progress-bar/README.md b/packages/components/src/progress-bar/README.md
index ad69ab54b098a..017d5bffe0ae9 100644
--- a/packages/components/src/progress-bar/README.md
+++ b/packages/components/src/progress-bar/README.md
@@ -1,13 +1,51 @@
 # ProgressBar
 
-<div class="callout callout-alert">
-This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
-</div>
-
 A simple horizontal progress bar component.
 
 Supports two modes: determinate and indeterminate. A progress bar is determinate when a specific progress value has been specified (from 0 to 100), and indeterminate when a value hasn't been specified.
 
+## Usage
+
+```jsx
+import { ProgressBar } from '@wordpress/components';
+
+const MyLoadingComponent = () => {
+  return <ProgressBar />
+}
+```
+
+The ProgressBar will expand to take all the available horizontal space of its immediate parent container element. To control its width, you can:
+
+Pass a custom CSS `className` that takes care of setting the `width`:
+
+```css
+.my-css-class {
+  width: 160px;
+}
+```
+
+```jsx
+import { ProgressBar } from '@wordpress/components';
+
+const MyLoadingComponent = () => {
+  return <ProgressBar className="my-css-class" />;
+};
+```
+
+Wrap it in a container element (e.g `<div>`) that has a `width` specified:
+
+```jsx
+import { ProgressBar } from '@wordpress/components';
+
+const MyLoadingComponent = ( props ) => {
+  return (
+		<div style={ { width: '160px' } }>
+			<ProgressBar />
+		</div>
+	);
+};
+```
+
 ### Props
 
 The component accepts the following props:
diff --git a/packages/components/src/progress-bar/index.tsx b/packages/components/src/progress-bar/index.tsx
index ed13c036e9916..523d521315a5d 100644
--- a/packages/components/src/progress-bar/index.tsx
+++ b/packages/components/src/progress-bar/index.tsx
@@ -46,6 +46,53 @@ function UnforwardedProgressBar(
 	);
 }
 
+/**
+ * A simple horizontal progress bar component.
+ *
+ * Supports two modes: determinate and indeterminate. A progress bar is determinate when a specific progress value has been specified (from 0 to 100), and indeterminate when a value hasn't been specified.
+ *
+ * ## Usage
+ *
+ * ```jsx
+ * import { ProgressBar } from '@wordpress/components';
+ *
+ * const MyLoadingComponent = () => {
+ *   return <ProgressBar />
+ * }
+ * ```
+ *
+ * The ProgressBar will expand to take all the available horizontal space of its immediate parent container element. To control its width, you can:
+ *
+ * Pass a custom CSS `className` that takes care of setting the `width`:
+ *
+ * ```css
+ * .my-css-class {
+ *   width: 160px;
+ * }
+ * ```
+ *
+ * ```jsx
+ * import { ProgressBar } from '@wordpress/components';
+ *
+ * const MyLoadingComponent = () => {
+ *   return <ProgressBar className="my-css-class" />;
+ * };
+ * ```
+ *
+ * Wrap it in a container element (e.g `<div>`) that has a `width` specified:
+ *
+ * ```jsx
+ * import { ProgressBar } from '@wordpress/components';
+ *
+ * const MyLoadingComponent = ( props ) => {
+ *   return (
+ *     <div style={ { width: '160px' } }>
+ *       <ProgressBar />
+ *     </div>
+ *   );
+ * };
+ * ```
+ */
 export const ProgressBar = forwardRef( UnforwardedProgressBar );
 
 export default ProgressBar;
diff --git a/packages/components/src/progress-bar/stories/index.story.tsx b/packages/components/src/progress-bar/stories/index.story.tsx
index 944da75339f07..7e4e66ce52277 100644
--- a/packages/components/src/progress-bar/stories/index.story.tsx
+++ b/packages/components/src/progress-bar/stories/index.story.tsx
@@ -24,9 +24,35 @@ const meta: Meta< typeof ProgressBar > = {
 };
 export default meta;
 
-const Template: StoryFn< typeof ProgressBar > = ( { ...args } ) => {
-	return <ProgressBar { ...args } />;
-};
+const Template: StoryFn< typeof ProgressBar > = ( { ...args } ) => (
+	<ProgressBar { ...args } />
+);
 
 export const Default: StoryFn< typeof ProgressBar > = Template.bind( {} );
 Default.args = {};
+
+export const WithDefaultSuggestedWidth: StoryFn = ( {
+	className,
+	...args
+} ) => (
+	<>
+		<style>
+			{ `
+				.progressbar-story-custom-width {
+					width: 160px;
+				}
+			` }
+		</style>
+		<ProgressBar { ...args } className={ className } />
+	</>
+);
+WithDefaultSuggestedWidth.args = {
+	className: 'progressbar-story-custom-width',
+};
+WithDefaultSuggestedWidth.parameters = {
+	docs: {
+		description: {
+			story: 'For most screens with a wide-enough viewport, we recommend a maximum width of 160px. You can set a custom width by passing a CSS class via the `className` prop (depicted below) or by setting the width of the parent container.',
+		},
+	},
+};
diff --git a/packages/components/src/progress-bar/styles.ts b/packages/components/src/progress-bar/styles.ts
index f04002f458c0a..29c251c97fb6d 100644
--- a/packages/components/src/progress-bar/styles.ts
+++ b/packages/components/src/progress-bar/styles.ts
@@ -25,7 +25,6 @@ export const Track = styled.div`
 	position: relative;
 	overflow: hidden;
 	width: 100%;
-	max-width: 160px;
 	height: ${ CONFIG.borderWidthFocus };
 	/* Text color at 10% opacity */
 	background-color: color-mix(
diff --git a/packages/edit-site/src/components/canvas-loader/index.js b/packages/edit-site/src/components/canvas-loader/index.js
index 99d83c3ad69b3..f34801a3bee2b 100644
--- a/packages/edit-site/src/components/canvas-loader/index.js
+++ b/packages/edit-site/src/components/canvas-loader/index.js
@@ -34,7 +34,12 @@ export default function CanvasLoader( { id } ) {
 	return (
 		<div className="edit-site-canvas-loader">
 			<Theme accent={ indicatorColor } background={ backgroundColor }>
-				<ProgressBar id={ id } max={ total } value={ elapsed } />
+				<ProgressBar
+					id={ id }
+					max={ total }
+					value={ elapsed }
+					className="edit-site-canvas-loader__progressbar"
+				/>
 			</Theme>
 		</div>
 	);
diff --git a/packages/edit-site/src/components/canvas-loader/style.scss b/packages/edit-site/src/components/canvas-loader/style.scss
index 3d74d408aeced..3b9f091b1ca51 100644
--- a/packages/edit-site/src/components/canvas-loader/style.scss
+++ b/packages/edit-site/src/components/canvas-loader/style.scss
@@ -16,6 +16,10 @@
 	& > div {
 		width: 160px;
 	}
+
+	& > .edit-site-canvas-loader__progressbar {
+		width: 160px;
+	}
 }
 
 @keyframes edit-site-canvas-loader__fade-in-animation {
diff --git a/packages/edit-site/src/components/global-styles/font-library-modal/font-collection.js b/packages/edit-site/src/components/global-styles/font-library-modal/font-collection.js
index 7d89a92cb44ba..98b07a324c1b1 100644
--- a/packages/edit-site/src/components/global-styles/font-library-modal/font-collection.js
+++ b/packages/edit-site/src/components/global-styles/font-library-modal/font-collection.js
@@ -266,7 +266,7 @@ function FontCollection( { slug } ) {
 		<div className="font-library-modal__tabpanel-layout">
 			{ isLoading && (
 				<div className="font-library-modal__loading">
-					<ProgressBar />
+					<ProgressBar className="font-library-modal__progressbar" />
 				</div>
 			) }
 
diff --git a/packages/edit-site/src/components/global-styles/font-library-modal/installed-fonts.js b/packages/edit-site/src/components/global-styles/font-library-modal/installed-fonts.js
index cdc81aa09b737..b13072c1e5773 100644
--- a/packages/edit-site/src/components/global-styles/font-library-modal/installed-fonts.js
+++ b/packages/edit-site/src/components/global-styles/font-library-modal/installed-fonts.js
@@ -114,7 +114,7 @@ function InstalledFonts() {
 		<div className="font-library-modal__tabpanel-layout">
 			{ isResolvingLibrary && (
 				<div className="font-library-modal__loading">
-					<ProgressBar />
+					<ProgressBar className="font-library-modal__progressbar" />
 				</div>
 			) }
 
@@ -283,7 +283,9 @@ function InstalledFonts() {
 						justify="flex-end"
 						className="font-library-modal__tabpanel-layout__footer"
 					>
-						{ isInstalling && <ProgressBar /> }
+						{ isInstalling && (
+							<ProgressBar className="font-library-modal__progressbar" />
+						) }
 						{ shouldDisplayDeleteButton && (
 							<Button
 								isDestructive
diff --git a/packages/edit-site/src/components/global-styles/font-library-modal/style.scss b/packages/edit-site/src/components/global-styles/font-library-modal/style.scss
index fb87f6fae505a..0776fbd3bf94d 100644
--- a/packages/edit-site/src/components/global-styles/font-library-modal/style.scss
+++ b/packages/edit-site/src/components/global-styles/font-library-modal/style.scss
@@ -48,6 +48,10 @@ $footer-height: 70px;
 		// Push down so that the progress bar is centered vertically.
 		// It should be 120px (72px modal header height + 48px tab height)
 		padding-top: $header-height + $grid-unit-15 + $grid-unit-60;
+
+		& > .font-library-modal__progressbar {
+			width: 160px;
+		}
 	}
 
 	.font-library-modal__tabpanel-layout__footer {
diff --git a/packages/edit-site/src/components/global-styles/font-library-modal/upload-fonts.js b/packages/edit-site/src/components/global-styles/font-library-modal/upload-fonts.js
index c8710c9111100..de256e725af82 100644
--- a/packages/edit-site/src/components/global-styles/font-library-modal/upload-fonts.js
+++ b/packages/edit-site/src/components/global-styles/font-library-modal/upload-fonts.js
@@ -220,7 +220,7 @@ function UploadFonts() {
 				{ isUploading && (
 					<FlexItem>
 						<div className="font-library-modal__upload-area">
-							<ProgressBar />
+							<ProgressBar className="font-library-modal__progressbar" />
 						</div>
 					</FlexItem>
 				) }