@wordpress/block-editor 14.10.1 → 14.12.0

package/src/components/spacing-sizes-control/test/utils.js

@@ -3,20 +3,15 @@
  */
 import {
 	ALL_SIDES,
-	getAllRawValue,
 	getCustomValueFromPreset,
 	getInitialView,
 	getPresetValueFromCustomValue,
 	getSliderValueFromPreset,
 	getSpacingPresetCssVar,
 	getSpacingPresetSlug,
-	getSupportedMenuItems,
 	hasAxisSupport,
 	hasBalancedSidesSupport,
-	isValuesDefined,
-	isValuesMixed,
 	isValueSpacingPreset,
-	LABELS,
 	VIEWS,
 } from '../utils';
 
@@ -114,88 +109,6 @@ describe( 'getSliderValueFromPreset', () => {
 	} );
 } );
 
-describe( 'getAllRawValue', () => {
-	const customValues = {
-		top: '5px',
-		bottom: '5px',
-		left: '6px',
-		right: '2px',
-	};
-	it( 'should return the most common custom value from the values object', () => {
-		expect( getAllRawValue( customValues ) ).toBe( '5px' );
-	} );
-	const presetValues = {
-		top: 'var:preset|spacing|30',
-		bottom: 'var:preset|spacing|20',
-		left: 'var:preset|spacing|10',
-		right: 'var:preset|spacing|30',
-	};
-	it( 'should return the most common preset value from the values object', () => {
-		expect( getAllRawValue( presetValues ) ).toBe(
-			'var:preset|spacing|30'
-		);
-	} );
-} );
-
-describe( 'isValuesMixed', () => {
-	const unmixedValues = {
-		top: '5px',
-		bottom: '5px',
-		left: '5px',
-		right: '5px',
-	};
-	it( 'should return false if all values are the same', () => {
-		expect( isValuesMixed( unmixedValues ) ).toBe( false );
-	} );
-	const mixedValues = {
-		top: 'var:preset|spacing|30',
-		bottom: 'var:preset|spacing|20',
-		left: 'var:preset|spacing|10',
-		right: 'var:preset|spacing|30',
-	};
-	it( 'should return true if all the values are not the same', () => {
-		expect( isValuesMixed( mixedValues ) ).toBe( true );
-	} );
-	const singleValue = {
-		top: 'var:preset|spacing|30',
-	};
-	it( 'should return true if only one side set', () => {
-		expect( isValuesMixed( singleValue ) ).toBe( true );
-	} );
-	const incompleteValues = {
-		top: 'var:preset|spacing|30',
-		bottom: 'var:preset|spacing|30',
-		left: 'var:preset|spacing|30',
-	};
-	it( 'should return true if all sides not set', () => {
-		expect( isValuesMixed( incompleteValues ) ).toBe( true );
-	} );
-} );
-
-describe( 'isValuesDefined', () => {
-	const undefinedValues = {
-		top: undefined,
-		bottom: undefined,
-		left: undefined,
-		right: undefined,
-	};
-	it( 'should return false if values are not defined', () => {
-		expect( isValuesDefined( undefinedValues ) ).toBe( false );
-	} );
-	it( 'should return false if values is passed in as null', () => {
-		expect( isValuesDefined( null ) ).toBe( false );
-	} );
-	const definedValues = {
-		top: 'var:preset|spacing|30',
-		bottom: 'var:preset|spacing|20',
-		left: 'var:preset|spacing|10',
-		right: 'var:preset|spacing|30',
-	};
-	it( 'should return true if all the values are not the same', () => {
-		expect( isValuesDefined( definedValues ) ).toBe( true );
-	} );
-} );
-
 describe( 'hasAxisSupport', () => {
 	it( 'should return true for horizontal support if it is in sides', () => {
 		expect( hasAxisSupport( [ 'horizontal' ], 'horizontal' ) ).toBe( true );
@@ -228,70 +141,6 @@ describe( 'hasAxisSupport', () => {
 	} );
 } );
 
-describe( 'getSupportedMenuItems', () => {
-	it( 'returns no items when sides are not configured', () => {
-		expect( getSupportedMenuItems( [] ) ).toEqual( {} );
-		expect( getSupportedMenuItems() ).toEqual( {} );
-	} );
-
-	const sideConfigs = [
-		[ LABELS.axial, [ 'horizontal', 'vertical' ] ],
-		[ LABELS.axial, [ 'top', 'right', 'bottom', 'left' ] ],
-		[ LABELS.horizontal, [ 'horizontal' ] ],
-		[ LABELS.horizontal, [ 'left', 'right' ] ],
-		[ LABELS.vertical, [ 'vertical' ] ],
-		[ LABELS.vertical, [ 'top', 'bottom' ] ],
-		[ LABELS.horizontal, [ 'horizontal' ] ],
-	];
-
-	test.each( sideConfigs )(
-		'should include %s axial menu with %s sides',
-		( label, sides ) => {
-			expect( getSupportedMenuItems( sides ) ).toHaveProperty(
-				'axial.label',
-				label
-			);
-		}
-	);
-
-	it( 'returns no axial item when not not supported', () => {
-		expect( getSupportedMenuItems( [ 'left', 'top' ] ) ).not.toHaveProperty(
-			'axial'
-		);
-	} );
-
-	it( 'should include the correct individual side options', () => {
-		expect( getSupportedMenuItems( [ 'top' ] ) ).toHaveProperty(
-			'top.label',
-			LABELS.top
-		);
-		expect( getSupportedMenuItems( [ 'right' ] ) ).toHaveProperty(
-			'right.label',
-			LABELS.right
-		);
-		expect( getSupportedMenuItems( [ 'bottom' ] ) ).toHaveProperty(
-			'bottom.label',
-			LABELS.bottom
-		);
-		expect( getSupportedMenuItems( [ 'left' ] ) ).toHaveProperty(
-			'left.label',
-			LABELS.left
-		);
-	} );
-	it( 'should include the custom option only when applicable', () => {
-		expect( getSupportedMenuItems( [ 'top', 'left' ] ) ).toHaveProperty(
-			'custom.label',
-			LABELS.custom
-		);
-		expect( getSupportedMenuItems( [ 'top' ] ) ).not.toHaveProperty(
-			'custom'
-		);
-		expect(
-			getSupportedMenuItems( [ 'horizontal', 'vertical' ] )
-		).not.toHaveProperty( 'custom.label' );
-	} );
-} );
-
 describe( 'hasBalancedSidesSupport', () => {
 	it( 'should determine balanced sides', () => {
 		expect( hasBalancedSidesSupport( ALL_SIDES ) ).toBe( true );

package/src/components/spacing-sizes-control/utils.js

@@ -184,64 +184,6 @@ export function getSliderValueFromPreset( presetValue, spacingSizes ) {
 	return sliderValue !== -1 ? sliderValue : NaN;
 }
 
-/**
- * Gets an items with the most occurrence within an array
- * https://stackoverflow.com/a/20762713
- *
- * @param {Array<any>} arr Array of items to check.
- * @return {any} The item with the most occurrences.
- */
-function mode( arr ) {
-	return arr
-		.sort(
-			( a, b ) =>
-				arr.filter( ( v ) => v === a ).length -
-				arr.filter( ( v ) => v === b ).length
-		)
-		.pop();
-}
-
-/**
- * Gets the 'all' input value from values data.
- *
- * @param {Object} values Box spacing values
- *
- * @return {string} The most common value from all sides of box.
- */
-export function getAllRawValue( values = {} ) {
-	return mode( Object.values( values ) );
-}
-
-/**
- * Checks to determine if values are mixed.
- *
- * @param {Object} values Box values.
- * @param {Array}  sides  Sides that values relate to.
- *
- * @return {boolean} Whether values are mixed.
- */
-export function isValuesMixed( values = {}, sides = ALL_SIDES ) {
-	return (
-		( Object.values( values ).length >= 1 &&
-			Object.values( values ).length < sides.length ) ||
-		new Set( Object.values( values ) ).size > 1
-	);
-}
-
-/**
- * Checks to determine if values are defined.
- *
- * @param {Object} values Box values.
- *
- * @return {boolean} Whether values are defined.
- */
-export function isValuesDefined( values ) {
-	if ( values === undefined || values === null ) {
-		return false;
-	}
-	return Object.values( values ).filter( ( value ) => !! value ).length > 0;
-}
-
 /**
  * Determines whether a particular axis has support. If no axis is
  * specified, this function checks if either axis is supported.
@@ -275,54 +217,6 @@ export function hasAxisSupport( sides, axis ) {
 	return hasHorizontalSupport || hasVerticalSupport;
 }
 
-/**
- * Determines which menu options should be included in the SidePicker.
- *
- * @param {Array} sides Supported sides.
- *
- * @return {Object} Menu options with each option containing label & icon.
- */
-export function getSupportedMenuItems( sides ) {
-	if ( ! sides || ! sides.length ) {
-		return {};
-	}
-
-	const menuItems = {};
-
-	// Determine the primary "side" menu options.
-	const hasHorizontalSupport = hasAxisSupport( sides, 'horizontal' );
-	const hasVerticalSupport = hasAxisSupport( sides, 'vertical' );
-
-	if ( hasHorizontalSupport && hasVerticalSupport ) {
-		menuItems.axial = { label: LABELS.axial, icon: ICONS.axial };
-	} else if ( hasHorizontalSupport ) {
-		menuItems.axial = { label: LABELS.horizontal, icon: ICONS.horizontal };
-	} else if ( hasVerticalSupport ) {
-		menuItems.axial = { label: LABELS.vertical, icon: ICONS.vertical };
-	}
-
-	// Track whether we have any individual sides so we can omit the custom
-	// option if required.
-	let numberOfIndividualSides = 0;
-
-	ALL_SIDES.forEach( ( side ) => {
-		if ( sides.includes( side ) ) {
-			numberOfIndividualSides += 1;
-			menuItems[ side ] = {
-				label: LABELS[ side ],
-				icon: ICONS[ side ],
-			};
-		}
-	} );
-
-	// Add custom item if there are enough sides to warrant a separated view.
-	if ( numberOfIndividualSides > 1 ) {
-		menuItems.custom = { label: LABELS.custom, icon: ICONS.custom };
-	}
-
-	return menuItems;
-}
-
 /**
  * Checks if the supported sides are balanced for each axis.
  * - Horizontal - both left and right sides are supported.

package/src/components/tabbed-sidebar/README.md

@@ -1,21 +1,19 @@
-# Tabbed Panel
+# TabbedSidebar
 
-The `TabbedPanel` component is used to create the secondary panels in the editor.
+The `TabbedSidebar` component is used to create secondary panels in the editor with tabbed navigation.
 
 ## Development guidelines
 
-This acts as a wrapper for the `Tabs` component, but adding conventions that can be shared between all secondary panels, for example:
+This acts as a wrapper for the `Tabs` component, adding conventions that can be shared between all secondary panels, including:
 
 -   A close button
 -   Tabs that fill the panel
--   Custom scollbars
+-   Custom scrollbars
 
 ### Usage
 
-Renders a block alignment toolbar with alignments options.
-
 ```jsx
-import { TabbedSidebar } from '@wordpress/components';
+import { TabbedSidebar } from '@wordpress/block-editor';
 
 const MyTabbedSidebar = () => (
 	<TabbedSidebar
@@ -23,7 +21,7 @@ const MyTabbedSidebar = () => (
 			{
 				name: 'slug-1',
 				title: _x( 'Title 1', 'context' ),
-				panel: <PanelContents>,
+				panel: <PanelContents />,
 				panelRef: useRef('an-optional-ref'),
 			},
 			{
@@ -35,6 +33,8 @@ const MyTabbedSidebar = () => (
 		onClose={ onClickCloseButton }
 		onSelect={ onSelectTab }
 		defaultTabId="slug-1"
+		selectedTab="slug-1"
+		closeButtonLabel="Close sidebar"
 		ref={ tabsRef }
 	/>
 );
@@ -47,30 +47,41 @@ const MyTabbedSidebar = () => (
 -   **Type:** `String`
 -   **Default:** `undefined`
 
-This is passed to the `Tabs` component so it can handle the tab to select by default when it component renders.
+The ID of the tab to be selected by default when the component renders.
 
 ### `onClose`
 
 -   **Type:** `Function`
 
-The function that is called when the close button is clicked.
+Function called when the close button is clicked.
 
 ### `onSelect`
 
 -   **Type:** `Function`
 
-This is passed to the `Tabs` component - it will be called when a tab has been selected. It is passed the selected tab's ID as an argument.
+Function called when a tab is selected. Receives the selected tab's ID as an argument.
 
 ### `selectedTab`
 
 -   **Type:** `String`
 -   **Default:** `undefined`
 
-This is passed to the `Tabs` component - it will display this tab as selected.
+The ID of the currently selected tab.
 
 ### `tabs`
 
 -   **Type:** `Array`
 -   **Default:** `undefined`
 
-An array of tabs which will be rendered as `TabList` and `TabPanel` components.
+Array of tab objects. Each tab should have:
+
+- `name` (string): Unique identifier for the tab
+- `title` (string): Display title for the tab
+- `panel` (React.Node): Content to display in the tab panel
+- `panelRef` (React.Ref, optional): Reference to the tab panel element
+
+#### `closeButtonLabel`
+
+-   **Type:** `String`
+
+Accessibility label for the close button.

package/src/components/tabbed-sidebar/index.js

@@ -15,6 +15,44 @@ import { unlock } from '../../lock-unlock';
 
 const { Tabs } = unlock( componentsPrivateApis );
 
+/**
+ * A component that creates a tabbed sidebar with a close button.
+ *
+ * @see https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/tabbed-sidebar/README.md
+ *
+ * @example
+ * ```jsx
+ * function MyTabbedSidebar() {
+ *   return (
+ *     <TabbedSidebar
+ *       tabs={ [
+ *         {
+ *           name: 'tab1',
+ *           title: 'Settings',
+ *           panel: <PanelContents />,
+ *         }
+ *       ] }
+ *       onClose={ () => {} }
+ *       onSelect={ () => {} }
+ *       defaultTabId="tab1"
+ *       selectedTab="tab1"
+ *       closeButtonLabel="Close sidebar"
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @param {Object}   props                  Component props.
+ * @param {string}   [props.defaultTabId]   The ID of the tab to be selected by default when the component renders.
+ * @param {Function} props.onClose          Function called when the close button is clicked.
+ * @param {Function} props.onSelect         Function called when a tab is selected. Receives the selected tab's ID as an argument.
+ * @param {string}   props.selectedTab      The ID of the currently selected tab.
+ * @param {Array}    props.tabs             Array of tab objects. Each tab should have: name (string), title (string),
+ *                                          panel (React.Node), and optionally panelRef (React.Ref).
+ * @param {string}   props.closeButtonLabel Accessibility label for the close button.
+ * @param {Object}   ref                    Forward ref to the tabs list element.
+ * @return {Element} The tabbed sidebar component.
+ */
 function TabbedSidebar(
 	{ defaultTabId, onClose, onSelect, selectedTab, tabs, closeButtonLabel },
 	ref

package/src/components/tabbed-sidebar/stories/index.story.js

@@ -0,0 +1,104 @@
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import TabbedSidebar from '../';
+
+const meta = {
+	title: 'BlockEditor/TabbedSidebar',
+	component: TabbedSidebar,
+	tags: [ 'status-private' ],
+	parameters: {
+		docs: {
+			canvas: { sourceState: 'shown' },
+			description: {
+				component:
+					'A component that creates a tabbed sidebar with a close button.',
+			},
+		},
+	},
+	argTypes: {
+		defaultTabId: {
+			control: { type: null },
+			table: {
+				type: { summary: 'string' },
+			},
+			description:
+				'The ID of the tab to be selected by default when the component renders.',
+		},
+		onClose: {
+			action: 'onClose',
+			control: { type: null },
+			table: {
+				type: { summary: 'function' },
+			},
+			description: 'Function called when the close button is clicked.',
+		},
+		onSelect: {
+			action: 'onSelect',
+			control: { type: null },
+			table: {
+				type: { summary: 'function' },
+			},
+			description:
+				"Function called when a tab is selected. Receives the selected tab's ID as an argument.",
+		},
+		selectedTab: {
+			control: { type: null },
+			table: {
+				type: { summary: 'string' },
+			},
+			description: 'The ID of the currently selected tab.',
+		},
+		tabs: {
+			control: { type: 'array' },
+			table: {
+				type: { summary: 'array' },
+			},
+			description:
+				'Array of tab objects. Each tab should have: name (string), title (string), panel (React.Node), and optionally panelRef (React.Ref).',
+		},
+		closeButtonLabel: {
+			control: { type: 'text' },
+			table: {
+				type: { summary: 'string' },
+			},
+			description: 'Accessibility label for the close button.',
+		},
+	},
+};
+
+export default meta;
+
+const DEMO_TABS = [
+	{ name: 'tab1', title: 'Settings' },
+	{ name: 'tab2', title: 'Styles' },
+	{ name: 'tab3', title: 'Advanced' },
+];
+
+export const Default = {
+	render: function Template( { onSelect, onClose, ...args } ) {
+		const [ selectedTab, setSelectedTab ] = useState();
+
+		return (
+			<TabbedSidebar
+				{ ...args }
+				selectedTab={ selectedTab }
+				onSelect={ ( ...changeArgs ) => {
+					onSelect( ...changeArgs );
+					setSelectedTab( ...changeArgs );
+				} }
+				onClose={ onClose }
+			/>
+		);
+	},
+	args: {
+		tabs: DEMO_TABS,
+		defaultTabId: 'tab1',
+		closeButtonLabel: 'Close Sidebar',
+	},
+};

package/src/components/typewriter/index.js

@@ -193,7 +193,7 @@ export function useTypewriter() {
 			}
 
 			/**
-			 * Checks if the current situation is elegible for scroll:
+			 * Checks if the current situation is eligible for scroll:
 			 * - There should be one and only one block selected.
 			 * - The component must contain the selection.
 			 * - The active element must be contenteditable.

package/src/components/unit-control/README.md

@@ -34,7 +34,7 @@ const Example = () => {
 
 ### Props
 
-#### disabledUnits
+#### disableUnits
 
 If true, the unit `<select>` is hidden.
 

package/src/components/unit-control/stories/index.story.js

@@ -0,0 +1,124 @@
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import UnitControl from '../';
+
+const meta = {
+	title: 'BlockEditor/UnitControl',
+	component: UnitControl,
+	parameters: {
+		docs: {
+			canvas: { sourceState: 'shown' },
+			description: {
+				component:
+					'UnitControl allows the user to set a numeric quantity as well as a unit.',
+			},
+		},
+	},
+	argTypes: {
+		onChange: {
+			action: 'onChange',
+			description: 'Callback function when the value changes.',
+			table: {
+				type: { summary: 'function' },
+			},
+		},
+		onUnitChange: {
+			action: 'onUnitChange',
+			description: 'Callback function when the unit changes.',
+			table: {
+				type: { summary: 'function' },
+			},
+		},
+		labelPosition: {
+			control: 'radio',
+			options: [ 'top', 'side', 'bottom', 'edge' ],
+			description: 'The position of the label.',
+			table: {
+				type: { summary: 'string' },
+			},
+		},
+		label: {
+			control: 'text',
+			description: 'The label for the control.',
+			table: {
+				type: { summary: 'string' },
+			},
+		},
+		value: {
+			control: { type: null },
+			description: 'The value of the control.',
+			table: {
+				type: { summary: 'string' },
+			},
+		},
+		size: {
+			control: 'radio',
+			options: [ 'default', 'small' ],
+			description: 'The size of the control.',
+			table: {
+				type: { summary: 'string' },
+				defaultValue: { summary: 'default' },
+			},
+		},
+		disabled: {
+			control: 'boolean',
+			description: 'Whether the control is disabled.',
+			table: {
+				type: { summary: 'boolean' },
+				defaultValue: { summary: false },
+			},
+		},
+		disableUnits: {
+			control: 'boolean',
+			description: 'If true, the unit select is hidden.',
+			table: {
+				type: { summary: 'boolean' },
+				defaultValue: { summary: false },
+			},
+		},
+		isPressEnterToChange: {
+			control: 'boolean',
+			description:
+				'If true, the ENTER key press is required to trigger onChange. Change is also triggered on blur.',
+			table: {
+				type: { summary: 'boolean' },
+				defaultValue: { summary: false },
+			},
+		},
+		isUnitSelectTabbable: {
+			control: 'boolean',
+			description: 'Determines if the unit select is tabbable.',
+			table: {
+				type: { summary: 'boolean' },
+				defaultValue: { summary: true },
+			},
+		},
+	},
+};
+
+export default meta;
+
+export const Default = {
+	render: function Template( { onChange, ...args } ) {
+		const [ value, setValue ] = useState();
+		return (
+			<UnitControl
+				{ ...args }
+				value={ value }
+				onChange={ ( ...changeArgs ) => {
+					onChange( ...changeArgs );
+					setValue( ...changeArgs );
+				} }
+			/>
+		);
+	},
+	args: {
+		label: 'Label',
+	},
+};