Components: Make the ProgressBar public (#61062)

* Remove "experimental" designation for `ProgressBar` * Add optional width prop to override/set the progress bar track container * Revert "Add optional width prop to override/set the progress bar track container" This reverts commit b1fe7cd. * Keep an unconstrained width by default, while allowing consumers to override it with CSS * Revert "Keep an unconstrained width by default, while allowing consumers to override it with CSS" This reverts commit 64c72e2. * Make the component public * Update consumers to import the public component * Expose docs for the now public ProgressBar component * Update CHANGELOG * Run docs:build after docs/manifest.js change * Remove remaining private usage of ProgressBar * Small formatting fix in the changelog * Add basic docs to the README * Add jsdoc * Formatting fix in README jsx block Co-authored-by: Marin Atanasov <8436925+tyxla@users.noreply.github.com> * Another formatting fix in README jsx block Co-authored-by: Marin Atanasov <8436925+tyxla@users.noreply.github.com> * YAFF (yet another formatting fix) in the README jsx Co-authored-by: Marin Atanasov <8436925+tyxla@users.noreply.github.com> * Improve wording in descripton of the `value` prop in the README Co-authored-by: Marin Atanasov <8436925+tyxla@users.noreply.github.com> * YAFF: Missing semicolon in README jsx Co-authored-by: Marin Atanasov <8436925+tyxla@users.noreply.github.com> * YAFF: missing semicolon in jsx block in README Co-authored-by: Marin Atanasov <8436925+tyxla@users.noreply.github.com> * YAFF: missing semicolon in jsx block in README Co-authored-by: Marin Atanasov <8436925+tyxla@users.noreply.github.com> * YAFF: use tab instead of spaces in jsx code block in README Co-authored-by: Marin Atanasov <8436925+tyxla@users.noreply.github.com> * Move export out of the HOC export section * Fix CHANGELOG: Move entry to the existing enhacements section * Spacing fix Co-authored-by: Marin Atanasov <8436925+tyxla@users.noreply.github.com> * Sort import alphabetically * Simplify CHANGELOG entry Co-authored-by: Marin Atanasov <8436925+tyxla@users.noreply.github.com> * Re-export as default for visual consistency * Improve jsdoc comment: make it fit within ~80chars of char lenght and fix comment opening --------- Co-authored-by: Marin Atanasov <8436925+tyxla@users.noreply.github.com>
WordPress · May 29, 2024 · 4119044 · 4119044
1 parent c4e00ff
commit 4119044
Show file tree

Hide file tree

Showing 13 changed files with 66 additions and 21 deletions.
diff --git a/docs/manifest.json b/docs/manifest.json
@@ -1121,6 +1121,12 @@
 		"markdown_source": "../packages/components/src/popover/README.md",
 		"parent": "components"
 	},
+	{
+		"title": "ProgressBar",
+		"slug": "progress-bar",
+		"markdown_source": "../packages/components/src/progress-bar/README.md",
+		"parent": "components"
+	},
 	{
 		"title": "QueryControls",
 		"slug": "query-controls",

diff --git a/docs/tool/manifest.js b/docs/tool/manifest.js
@@ -16,7 +16,6 @@ const componentPaths = glob( 'packages/components/src/*/**/README.md', {
 		'packages/components/src/theme/README.md',
 		'packages/components/src/view/README.md',
 		'packages/components/src/dropdown-menu-v2/README.md',
-		'packages/components/src/progress-bar/README.md',
 		'packages/components/src/tabs/README.md',
 		'packages/components/src/custom-select-control-v2/README.md',
 	],

diff --git a/packages/components/CHANGELOG.md b/packages/components/CHANGELOG.md
@@ -11,6 +11,7 @@
 
 -   `Tabs`: Animate indicator ([#60560](https://github.com/WordPress/gutenberg/pull/60560)).
 -   `ComboboxControl`: Introduce Combobox expandOnFocus prop ([#61705](https://github.com/WordPress/gutenberg/pull/61705)).
+-   `ProgressBar`: Expose as public API ([#61062](https://github.com/WordPress/gutenberg/pull/61062)).
 
 ### Bug Fixes
 

diff --git a/packages/components/src/index.ts b/packages/components/src/index.ts
@@ -132,6 +132,7 @@ export { default as PanelHeader } from './panel/header';
 export { default as PanelRow } from './panel/row';
 export { default as Placeholder } from './placeholder';
 export { default as Popover } from './popover';
+export { default as ProgressBar } from './progress-bar';
 export { default as QueryControls } from './query-controls';
 export { default as __experimentalRadio } from './radio-group/radio';
 export { default as __experimentalRadioGroup } from './radio-group';

diff --git a/packages/components/src/private-apis.ts b/packages/components/src/private-apis.ts
@@ -15,7 +15,6 @@ import {
 } from './composite/v2';
 import { default as CustomSelectControl } from './custom-select-control';
 import { positionToPlacement as __experimentalPopoverLegacyPositionToPlacement } from './popover/utils';
-import { default as ProgressBar } from './progress-bar';
 import { createPrivateSlotFill } from './slot-fill';
 import {
 	DropdownMenu as DropdownMenuV2,
@@ -44,7 +43,6 @@ lock( privateApis, {
 	__experimentalPopoverLegacyPositionToPlacement,
 	createPrivateSlotFill,
 	ComponentsContext,
-	ProgressBar,
 	Tabs,
 	Theme,
 	DropdownMenuV2,

diff --git a/packages/components/src/progress-bar/README.md b/packages/components/src/progress-bar/README.md
@@ -1,13 +1,42 @@
 # 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
+
+Basic usage:
+
+```jsx
+import { ProgressBar } from '@wordpress/components';
+
+const MyLoadingComponent = () => {
+	return <ProgressBar />;
+};
+```
+
+You can also make it determinate by passing a `value` (from 0 to 100) representing the progress:
+
+```jsx
+import { ProgressBar } from '@wordpress/components';
+
+const MyLoadingComponent = ( { progress } ) => {
+	return <ProgressBar value={ progress } />;
+};
+```
+
+You can customize its appearance by passing a custom CSS class name to `className`:
+
+
+```jsx
+import { ProgressBar } from '@wordpress/components';
+
+const MyLoadingComponent = () => {
+	return <ProgressBar className="my-custom-css-class" />;
+};
+```
+
 ### 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
@@ -44,6 +44,21 @@ 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.
+ *
+ * ```jsx
+ * import { ProgressBar } from '@wordpress/components';
+ *
+ * const MyLoadingComponent = () => {
+ * 	return <ProgressBar />;
+ * };
+ * ```
+ */
 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
@@ -10,11 +10,10 @@ import { ProgressBar } from '..';
 
 const meta: Meta< typeof ProgressBar > = {
 	component: ProgressBar,
-	title: 'Components (Experimental)/ProgressBar',
+	title: 'Components/ProgressBar',
 	argTypes: {
 		value: { control: { type: 'number', min: 0, max: 100, step: 1 } },
 	},
-	tags: [ 'status-private' ],
 	parameters: {
 		controls: {
 			expanded: true,

diff --git a/packages/edit-site/src/components/canvas-loader/index.js b/packages/edit-site/src/components/canvas-loader/index.js
@@ -2,7 +2,10 @@
  * WordPress dependencies
  */
 import { privateApis as blockEditorPrivateApis } from '@wordpress/block-editor';
-import { privateApis as componentsPrivateApis } from '@wordpress/components';
+import {
+	privateApis as componentsPrivateApis,
+	ProgressBar,
+} from '@wordpress/components';
 import { store as coreStore } from '@wordpress/core-data';
 import { useSelect } from '@wordpress/data';
 
@@ -12,7 +15,7 @@ import { useSelect } from '@wordpress/data';
 import { unlock } from '../../lock-unlock';
 import { useStylesPreviewColors } from '../global-styles/hooks';
 
-const { ProgressBar, Theme } = unlock( componentsPrivateApis );
+const { Theme } = unlock( componentsPrivateApis );
 const { useGlobalStyle } = unlock( blockEditorPrivateApis );
 
 export default function CanvasLoader( { id } ) {

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
@@ -24,7 +24,7 @@ import {
 	Button,
 	DropdownMenu,
 	SearchControl,
-	privateApis as componentsPrivateApis,
+	ProgressBar,
 } from '@wordpress/components';
 import { debounce } from '@wordpress/compose';
 import { sprintf, __, _x } from '@wordpress/i18n';
@@ -45,8 +45,6 @@ import GoogleFontsConfirmDialog from './google-fonts-confirm-dialog';
 import { downloadFontFaceAssets } from './utils';
 import { sortFontFaces } from './utils/sort-font-faces';
 import CollectionFontVariant from './collection-font-variant';
-import { unlock } from '../../../lock-unlock';
-const { ProgressBar } = unlock( componentsPrivateApis );
 
 const DEFAULT_CATEGORY = {
 	slug: 'all',

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
@@ -15,7 +15,7 @@ import {
 	__experimentalVStack as VStack,
 	Flex,
 	Notice,
-	privateApis as componentsPrivateApis,
+	ProgressBar,
 } from '@wordpress/components';
 import { store as coreStore } from '@wordpress/core-data';
 import { useSelect } from '@wordpress/data';
@@ -26,12 +26,10 @@ import { chevronLeft } from '@wordpress/icons';
 /**
  * Internal dependencies
  */
-import { unlock } from '../../../lock-unlock';
 import { FontLibraryContext } from './context';
 import FontCard from './font-card';
 import LibraryFontVariant from './library-font-variant';
 import { sortFontFaces } from './utils/sort-font-faces';
-const { ProgressBar } = unlock( componentsPrivateApis );
 
 function InstalledFonts() {
 	const {

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
@@ -11,7 +11,7 @@ import {
 	Notice,
 	FormFileUpload,
 	FlexItem,
-	privateApis as componentsPrivateApis,
+	ProgressBar,
 } from '@wordpress/components';
 import { useContext, useState } from '@wordpress/element';
 
@@ -23,9 +23,6 @@ import { FontLibraryContext } from './context';
 import { Font } from '../../../../lib/lib-font.browser';
 import makeFamiliesFromFaces from './utils/make-families-from-faces';
 import { loadFontFaceInBrowser } from './utils';
-import { unlock } from '../../../lock-unlock';
-
-const { ProgressBar } = unlock( componentsPrivateApis );
 
 function UploadFonts() {
 	const { installFonts, notice, setNotice } =

diff --git a/storybook/manager-head.html b/storybook/manager-head.html
@@ -4,6 +4,7 @@
 			'navigation',
 			'customselectcontrol-v2',
 			'theme',
+			'progressbar',
 		];
 		const REDIRECTS = [
 			{