Make the useDisabled hook stable (#40890)

WordPress · May 9, 2022 · 2c5b236 · 2c5b236
1 parent 3065308
commit 2c5b236
Show file tree

Hide file tree

Showing 10 changed files with 46 additions and 18 deletions.
diff --git a/packages/block-editor/src/components/block-list/use-block-props/index.js b/packages/block-editor/src/components/block-list/use-block-props/index.js
@@ -12,10 +12,7 @@ import {
 	__unstableGetBlockProps as getBlockProps,
 	getBlockType,
 } from '@wordpress/blocks';
-import {
-	useMergeRefs,
-	__experimentalUseDisabled as useIsDisabled,
-} from '@wordpress/compose';
+import { useMergeRefs, useDisabled } from '@wordpress/compose';
 import { useSelect } from '@wordpress/data';
 import warning from '@wordpress/warning';
 
@@ -132,7 +129,7 @@ export function useBlockProps(
 			enableAnimation,
 			triggerAnimationOnChange: index,
 		} ),
-		useIsDisabled( { isDisabled: ! __unstableIsDisabled } ),
+		useDisabled( { isDisabled: ! __unstableIsDisabled } ),
 	] );
 
 	const blockEditContext = useBlockEditContext();

diff --git a/packages/block-editor/src/components/block-preview/index.js b/packages/block-editor/src/components/block-preview/index.js
@@ -7,10 +7,7 @@ import classnames from 'classnames';
 /**
  * WordPress dependencies
  */
-import {
-	__experimentalUseDisabled as useDisabled,
-	useMergeRefs,
-} from '@wordpress/compose';
+import { useDisabled, useMergeRefs } from '@wordpress/compose';
 import { useSelect } from '@wordpress/data';
 import { memo, useMemo } from '@wordpress/element';
 

diff --git a/packages/block-library/src/post-comments-form/form.js b/packages/block-library/src/post-comments-form/form.js
@@ -2,10 +2,7 @@
  * WordPress dependencies
  */
 import { __ } from '@wordpress/i18n';
-import {
-	__experimentalUseDisabled as useDisabled,
-	useInstanceId,
-} from '@wordpress/compose';
+import { useDisabled, useInstanceId } from '@wordpress/compose';
 
 const CommentsForm = () => {
 	const disabledFormRef = useDisabled();

diff --git a/packages/block-library/src/post-comments/edit.js b/packages/block-library/src/post-comments/edit.js
@@ -16,7 +16,7 @@ import {
 import { __, sprintf } from '@wordpress/i18n';
 import { useSelect } from '@wordpress/data';
 import { useEntityProp, store as coreStore } from '@wordpress/core-data';
-import { __experimentalUseDisabled as useDisabled } from '@wordpress/compose';
+import { useDisabled } from '@wordpress/compose';
 import { createInterpolateElement } from '@wordpress/element';
 
 /**

diff --git a/packages/block-library/src/table-of-contents/edit.js b/packages/block-library/src/table-of-contents/edit.js
@@ -21,7 +21,7 @@ import {
 	ToolbarButton,
 	ToolbarGroup,
 } from '@wordpress/components';
-import { __experimentalUseDisabled as useDisabled } from '@wordpress/compose';
+import { useDisabled } from '@wordpress/compose';
 import { useDispatch, useSelect } from '@wordpress/data';
 import { __unstableStripHTML as stripHTML } from '@wordpress/dom';
 import { renderToString, useEffect } from '@wordpress/element';

diff --git a/packages/components/src/disabled/index.js b/packages/components/src/disabled/index.js
@@ -6,7 +6,7 @@ import classnames from 'classnames';
 /**
  * WordPress dependencies
  */
-import { __experimentalUseDisabled as useDisabled } from '@wordpress/compose';
+import { useDisabled } from '@wordpress/compose';
 import { createContext } from '@wordpress/element';
 
 /**

diff --git a/packages/compose/CHANGELOG.md b/packages/compose/CHANGELOG.md
@@ -6,6 +6,10 @@
 
 -   `useRefEffect`: Allow `void` as a valid callback return type ([#40798](https://github.com/WordPress/gutenberg/pull/40798)).
 
+### New Features
+
+-   Add `useDisabled` hook.
+
 ## 5.6.0 (2022-05-04)
 
 ## 5.5.0 (2022-04-21)

diff --git a/packages/compose/README.md b/packages/compose/README.md
@@ -205,6 +205,39 @@ _Returns_
 
 -   `import('lodash').DebouncedFunc<TFunc>`: Debounced function.
 
+### useDisabled
+
+In some circumstances, such as block previews, all focusable DOM elements
+(input fields, links, buttons, etc.) need to be disabled. This hook adds the
+behavior to disable nested DOM elements to the returned ref.
+
+_Usage_
+
+```js
+import { useDisabled } from '@wordpress/compose';
+const DisabledExample = () => {
+	const disabledRef = useDisabled();
+	return (
+		<div ref={ disabledRef }>
+			<a href="#">This link will have tabindex set to -1</a>
+			<input
+				placeholder="This input will have the disabled attribute added to it."
+				type="text"
+			/>
+		</div>
+	);
+};
+```
+
+_Parameters_
+
+-   _config_ `Object`: Configuration object.
+-   _config.isDisabled_ `boolean=`: Whether the element should be disabled.
+
+_Returns_
+
+-   `import('react').RefCallback<HTMLElement>`: Element Ref.
+
 ### useFocusableIframe
 
 Dispatches a bubbling focus event when the iframe receives focus. Use

diff --git a/packages/compose/src/hooks/use-disabled/index.js b/packages/compose/src/hooks/use-disabled/index.js
@@ -43,7 +43,7 @@ const DISABLED_ELIGIBLE_NODE_NAMES = [
  *
  * @example
  * ```js
- * import { __experimentalUseDisabled as useDisabled } from '@wordpress/compose';
+ * import { useDisabled } from '@wordpress/compose';
  * const DisabledExample = () => {
  * 	const disabledRef = useDisabled();
  *	return (

diff --git a/packages/compose/src/index.js b/packages/compose/src/index.js
@@ -17,7 +17,7 @@ export { default as useConstrainedTabbing } from './hooks/use-constrained-tabbin
 export { default as useCopyOnClick } from './hooks/use-copy-on-click';
 export { default as useCopyToClipboard } from './hooks/use-copy-to-clipboard';
 export { default as __experimentalUseDialog } from './hooks/use-dialog';
-export { default as __experimentalUseDisabled } from './hooks/use-disabled';
+export { default as useDisabled } from './hooks/use-disabled';
 export { default as __experimentalUseDragging } from './hooks/use-dragging';
 export { default as useFocusOnMount } from './hooks/use-focus-on-mount';
 export { default as __experimentalUseFocusOutside } from './hooks/use-focus-outside';