Add @example tags to the customize-widgets package (#52141)

* Add example for setIsInserterOpen. * Add example for isInserterOpened selector. * Update examples to use store export based on #52189
WordPress · Jul 4, 2023 · eb8209e · eb8209e · github-actions · Jul 4, 2023
1 parent 926ba17
commit eb8209e
Show file tree

Hide file tree

Showing 3 changed files with 88 additions and 0 deletions.
diff --git a/docs/reference-guides/data/data-core-customize-widgets.md b/docs/reference-guides/data/data-core-customize-widgets.md
@@ -10,6 +10,25 @@ Namespace: `core/customize-widgets`.
 
 Returns true if the inserter is opened.
 
+_Usage_
+
+```js
+import { store as customizeWidgetsStore } from '@wordpress/customize-widgets';
+import { __ } from '@wordpress/i18n';
+import { useSelect } from '@wordpress/data';
+
+const ExampleComponent = () => {
+	const { isInserterOpened } = useSelect(
+		( select ) => select( customizeWidgetsStore ),
+		[]
+	);
+
+	return isInserterOpened()
+		? __( 'Inserter is open' )
+		: __( 'Inserter is closed.' );
+};
+```
+
 _Parameters_
 
 -   _state_ `Object`: Global application state.
@@ -28,6 +47,32 @@ _Returns_
 
 Returns an action object used to open/close the inserter.
 
+_Usage_
+
+```js
+import { store as customizeWidgetsStore } from '@wordpress/customize-widgets';
+import { __ } from '@wordpress/i18n';
+import { useDispatch } from '@wordpress/data';
+import { Button } from '@wordpress/components';
+import { useState } from '@wordpress/element';
+
+const ExampleComponent = () => {
+	const { setIsInserterOpened } = useDispatch( customizeWidgetsStore );
+	const [ isOpen, setIsOpen ] = useState( false );
+
+	return (
+		<Button
+			onClick={ () => {
+				setIsInserterOpened( ! isOpen );
+				setIsOpen( ! isOpen );
+			} }
+		>
+			{ __( 'Open/close inserter' ) }
+		</Button>
+	);
+};
+```
+
 _Parameters_
 
 -   _value_ `boolean|Object`: Whether the inserter should be opened (true) or closed (false). To specify an insertion point, use an object.

diff --git a/packages/customize-widgets/src/store/actions.js b/packages/customize-widgets/src/store/actions.js
@@ -8,6 +8,31 @@
  * @param {string}         value.rootClientId   The root client ID to insert at.
  * @param {number}         value.insertionIndex The index to insert at.
  *
+ * @example
+ * ```js
+ * import { store as customizeWidgetsStore } from '@wordpress/customize-widgets';
+ * import { __ } from '@wordpress/i18n';
+ * import { useDispatch } from '@wordpress/data';
+ * import { Button } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
+ *
+ * const ExampleComponent = () => {
+ *   const { setIsInserterOpened } = useDispatch( customizeWidgetsStore );
+ *   const [ isOpen, setIsOpen ] = useState( false );
+ *
+ *    return (
+ *        <Button
+ *            onClick={ () => {
+ *                setIsInserterOpened( ! isOpen );
+ *                setIsOpen( ! isOpen );
+ *            } }
+ *        >
+ *            { __( 'Open/close inserter' ) }
+ *        </Button>
+ *    );
+ * };
+ * ```
+ *
  * @return {Object} Action object.
  */
 export function setIsInserterOpened( value ) {

diff --git a/packages/customize-widgets/src/store/selectors.js b/packages/customize-widgets/src/store/selectors.js
@@ -3,6 +3,24 @@
  *
  * @param {Object} state Global application state.
  *
+ * @example
+ * ```js
+ * import { store as customizeWidgetsStore } from '@wordpress/customize-widgets';
+ * import { __ } from '@wordpress/i18n';
+ * import { useSelect } from '@wordpress/data';
+ *
+ * const ExampleComponent = () => {
+ *    const { isInserterOpened } = useSelect(
+ *        ( select ) => select( customizeWidgetsStore ),
+ *        []
+ *    );
+ *
+ *    return isInserterOpened()
+ *        ? __( 'Inserter is open' )
+ *        : __( 'Inserter is closed.' );
+ * };
+ * ```
+ *
  * @return {boolean} Whether the inserter is opened.
  */
 export function isInserterOpened( state ) {