Storybook: Add BlockAlignmentMatrixControl Stories and update README (#…

…68007) * Storybook: Add BlockAlignmentMatrixControl Stories and update README * Fix defaultValue summary quotes in BlockAlignmentMatrixControl storie * Add JSDoc for BlockAlignmentMatrixControl * Improve JSDoc block indentation * Update JSDoc block indentation * Improve BlockAlignmentMatrixControl story Co-authored-by: Sukhendu2002 <[email protected]> Co-authored-by: t-hamano <[email protected]>
WordPress · Dec 19, 2024 · 2d974f2 · 2d974f2 · github-actions · Dec 19, 2024
1 parent 030c680
commit 2d974f2
Show file tree

Hide file tree

Showing 3 changed files with 138 additions and 6 deletions.
diff --git a/packages/block-editor/src/components/block-alignment-matrix-control/README.md b/packages/block-editor/src/components/block-alignment-matrix-control/README.md
@@ -41,13 +41,36 @@ const controls = (
       />
     </BlockControls>
   </>
-}
+);
 ```
 
 ### Props
 
-| Name       | Type       | Default                   | Description                                                                                                                              |
-| ---------- | ---------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `label`    | `string`   | `Change matrix alignment` | concise description of tool's functionality.                                                                                             |
-| `onChange` | `function` | `noop`                    | the function to execute upon a user's change of the matrix state                                                                         |
-| `value`    | `string`   | `center`                  | describes the content alignment location and can be `top`, `right`, `bottom`, `left`, `topRight`, `bottomRight`, `bottomLeft`, `topLeft` |
+### `label`
+
+-   **Type:** `string`
+-   **Default:** `'Change matrix alignment'`
+
+Label for the control.
+
+### `onChange`
+
+-   **Type:** `Function`
+-   **Default:** `noop`
+
+Function to execute upon a user's change of the matrix state.
+
+### `value`
+
+-   **Type:** `string`
+-   **Default:** `'center'`
+-   **Options:** `'center'`, `'center center'`, `'center left'`, `'center right'`, `'top center'`, `'top left'`, `'top right'`, `'bottom center'`, `'bottom left'`, `'bottom right'`
+
+Content alignment location.
+
+### `isDisabled`
+
+-   **Type:** `boolean`
+-   **Default:** `false`
+
+Whether the control should be disabled.
diff --git a/packages/block-editor/src/components/block-alignment-matrix-control/index.js b/packages/block-editor/src/components/block-alignment-matrix-control/index.js
@@ -11,6 +11,37 @@ import {
 
 const noop = () => {};
 
+/**
+ * The alignment matrix control allows users to quickly adjust inner block alignment.
+ *
+ * @see https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-alignment-matrix-control/README.md
+ *
+ * @example
+ * ```jsx
+ * function Example() {
+ *   return (
+ *     <BlockControls>
+ *       <BlockAlignmentMatrixControl
+ *         label={ __( 'Change content position' ) }
+ *         value="center"
+ *         onChange={ ( nextPosition ) =>
+ *           setAttributes( { contentPosition: nextPosition } )
+ *         }
+ *       />
+ *     </BlockControls>
+ *   );
+ * }
+ * ```
+ *
+ * @param {Object}   props            Component props.
+ * @param {string}   props.label      Label for the control. Defaults to 'Change matrix alignment'.
+ * @param {Function} props.onChange   Function to execute upon change of matrix state.
+ * @param {string}   props.value      Content alignment location. One of: 'center', 'center center',
+ *                                    'center left', 'center right', 'top center', 'top left',
+ *                                    'top right', 'bottom center', 'bottom left', 'bottom right'.
+ * @param {boolean}  props.isDisabled Whether the control should be disabled.
+ * @return {Element} The BlockAlignmentMatrixControl component.
+ */
 function BlockAlignmentMatrixControl( props ) {
 	const {
 		label = __( 'Change matrix alignment' ),

diff --git a/packages/block-editor/src/components/block-alignment-matrix-control/stories/index.story.js b/packages/block-editor/src/components/block-alignment-matrix-control/stories/index.story.js
@@ -0,0 +1,78 @@
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import BlockAlignmentMatrixControl from '../';
+
+const meta = {
+	title: 'BlockEditor/BlockAlignmentMatrixControl',
+	component: BlockAlignmentMatrixControl,
+	parameters: {
+		docs: {
+			canvas: { sourceState: 'shown' },
+			description: {
+				component:
+					'Renders a control for selecting block alignment using a matrix of alignment options.',
+			},
+		},
+	},
+	argTypes: {
+		label: {
+			control: 'text',
+			table: {
+				type: { summary: 'string' },
+				defaultValue: { summary: "'Change matrix alignment'" },
+			},
+			description: 'Label for the control.',
+		},
+		onChange: {
+			action: 'onChange',
+			control: { type: null },
+			table: {
+				type: { summary: 'function' },
+				defaultValue: { summary: '() => {}' },
+			},
+			description:
+				"Function to execute upon a user's change of the matrix state.",
+		},
+		isDisabled: {
+			control: 'boolean',
+			table: {
+				type: { summary: 'boolean' },
+				defaultValue: { summary: 'false' },
+			},
+			description: 'Whether the control should be disabled.',
+		},
+		value: {
+			control: { type: null },
+			table: {
+				type: { summary: 'string' },
+				defaultValue: { summary: "'center'" },
+			},
+			description: 'Content alignment location.',
+		},
+	},
+};
+
+export default meta;
+
+export const Default = {
+	render: function Template( { onChange, ...args } ) {
+		const [ value, setValue ] = useState();
+
+		return (
+			<BlockAlignmentMatrixControl
+				{ ...args }
+				value={ value }
+				onChange={ ( ...changeArgs ) => {
+					onChange( ...changeArgs );
+					setValue( ...changeArgs );
+				} }
+			/>
+		);
+	},
+};