@wordpress/components 23.3.1 → 23.4.0

package/src/tools-panel/tools-panel/hook.ts

@@ -35,12 +35,11 @@ const generateMenuItems = ( {
 	panelItems.forEach( ( { hasValue, isShownByDefault, label } ) => {
 		const group = isShownByDefault ? 'default' : 'optional';
 
-		// If a menu item for this label already exists, do not overwrite its value.
-		// This can cause default controls that have been flagged as customized to
-		// lose their value.
+		// If a menu item for this label has already been flagged as customized
+		// (for default controls), or toggled on (for optional controls), do not
+		// overwrite its value as those controls would lose that state.
 		const existingItemValue = currentMenuItems?.[ group ]?.[ label ];
-		const value =
-			existingItemValue !== undefined ? existingItemValue : hasValue();
+		const value = existingItemValue ? existingItemValue : hasValue();
 
 		menuItems[ group ][ label ] = shouldReset ? false : value;
 	} );
@@ -57,10 +56,11 @@ export function useToolsPanel(
 ) {
 	const {
 		className,
+		headingLevel = 2,
 		resetAll,
 		panelId,
-		hasInnerWrapper,
-		shouldRenderPlaceholderItems,
+		hasInnerWrapper = false,
+		shouldRenderPlaceholderItems = false,
 		__experimentalFirstVisibleItemClass,
 		__experimentalLastVisibleItemClass,
 		...otherProps
@@ -307,6 +307,7 @@ export function useToolsPanel(
 
 	return {
 		...otherProps,
+		headingLevel,
 		panelContext,
 		resetAllItems,
 		toggleItem,

package/src/tools-panel/tools-panel-header/README.md

@@ -18,6 +18,13 @@ This component is generated automatically by its parent
 
 ## Props
 
+### `headingLevel`: `1 | 2 | 3 | 4 | 5 | 6 | '1' | '2' | '3' | '4' | '5' | '6'`
+
+The heading level of the panel's header.
+
+-   Required: No
+-   Default: `2`
+
 ### `label`: `string`
 
 Text to be displayed within the panel header. It is also passed along as the

package/src/tools-panel/tools-panel-header/component.tsx

@@ -156,6 +156,7 @@ const ToolsPanelHeader = (
 		dropdownMenuClassName,
 		hasMenuItems,
 		headingClassName,
+		headingLevel = 2,
 		label: labelText,
 		menuItems,
 		resetAll,
@@ -185,7 +186,7 @@ const ToolsPanelHeader = (
 
 	return (
 		<HStack { ...headerProps } ref={ forwardedRef }>
-			<Heading level={ 2 } className={ headingClassName }>
+			<Heading level={ headingLevel } className={ headingClassName }>
 				{ labelText }
 			</Heading>
 			{ hasMenuItems && (

package/src/tools-panel/tools-panel-header/hook.ts

@@ -15,10 +15,11 @@ import type { ToolsPanelHeaderProps } from '../types';
 export function useToolsPanelHeader(
 	props: WordPressComponentProps< ToolsPanelHeaderProps, 'h2' >
 ) {
-	const { className, ...otherProps } = useContextSystem(
-		props,
-		'ToolsPanelHeader'
-	);
+	const {
+		className,
+		headingLevel = 2,
+		...otherProps
+	} = useContextSystem( props, 'ToolsPanelHeader' );
 
 	const cx = useCx();
 	const classes = useMemo( () => {
@@ -47,6 +48,7 @@ export function useToolsPanelHeader(
 		dropdownMenuClassName,
 		hasMenuItems,
 		headingClassName,
+		headingLevel,
 		menuItems,
 		className: classes,
 	};

package/src/tools-panel/tools-panel-item/README.md

@@ -31,7 +31,8 @@ This prop identifies the current item as being displayed by default. This means
 it will show regardless of whether it has a value set or is toggled on in the
 panel's menu.
 
--   Required: Yes
+-   Required: No
+-   Default: `false`
 
 ### `label`: `string`
 
@@ -58,18 +59,19 @@ A callback to take action when this item is selected in the `ToolsPanel` menu.
 
 -   Required: No
 
-### `panelId`: `string`
+### `panelId`: `string | null`
 
 Panel items will ensure they are only registering with their intended panel by
-comparing the `panelId` props set on both the item and the panel itself. This
+comparing the `panelId` props set on both the item and the panel itself, or if the `panelId` is explicitly `null`. This
 allows items to be injected from a shared source.
 
 -   Required: No
 
-### `resetAllFilter`: `() => void`
+### `resetAllFilter`: `( attributes?: any ) => any`
 
 A `ToolsPanel` will collect each item's `resetAllFilter` and pass an array of
 these functions through to the panel's `resetAll` callback. They can then be
 iterated over to perform additional tasks.
 
 -   Required: No
+-   Default: `() => {}`

package/src/tools-panel/tools-panel-item/component.tsx

@@ -13,7 +13,7 @@ import type { ToolsPanelItemProps } from '../types';
 
 // This wraps controls to be conditionally displayed within a tools panel. It
 // prevents props being applied to HTML elements that would make them invalid.
-const ToolsPanelItem = (
+const UnconnectedToolsPanelItem = (
 	props: WordPressComponentProps< ToolsPanelItemProps, 'div' >,
 	forwardedRef: ForwardedRef< any >
 ) => {
@@ -37,9 +37,9 @@ const ToolsPanelItem = (
 	);
 };
 
-const ConnectedToolsPanelItem = contextConnect(
-	ToolsPanelItem,
+export const ToolsPanelItem = contextConnect(
+	UnconnectedToolsPanelItem,
 	'ToolsPanelItem'
 );
 
-export default ConnectedToolsPanelItem;
+export default ToolsPanelItem;

package/src/tools-panel/tools-panel-item/hook.ts

@@ -13,16 +13,18 @@ import { useContextSystem, WordPressComponentProps } from '../../ui/context';
 import { useCx } from '../../utils/hooks/use-cx';
 import type { ToolsPanelItemProps } from '../types';
 
+const noop = () => {};
+
 export function useToolsPanelItem(
 	props: WordPressComponentProps< ToolsPanelItemProps, 'div' >
 ) {
 	const {
 		className,
 		hasValue,
-		isShownByDefault,
+		isShownByDefault = false,
 		label,
 		panelId,
-		resetAllFilter,
+		resetAllFilter = noop,
 		onDeselect,
 		onSelect,
 		...otherProps
@@ -86,30 +88,40 @@ export function useToolsPanelItem(
 		deregisterPanelItem,
 	] );
 
+	// Note: `label` is used as a key when building menu item state in
+	// `ToolsPanel`.
+	const menuGroup = isShownByDefault ? 'default' : 'optional';
+	const isMenuItemChecked = menuItems?.[ menuGroup ]?.[ label ];
+	const wasMenuItemChecked = usePrevious( isMenuItemChecked );
+	const isRegistered = menuItems?.[ menuGroup ]?.[ label ] !== undefined;
+
 	const isValueSet = hasValue();
 	const wasValueSet = usePrevious( isValueSet );
-
-	// If this item represents a default control it will need to notify the
-	// panel when a custom value has been set.
+	const newValueSet = isValueSet && ! wasValueSet;
+
+	// Notify the panel when an item's value has been set.
+	//
+	// 1. For default controls, this is so "reset" appears beside its menu item.
+	// 2. For optional controls, when the panel ID is `null`, it allows the
+	// panel to ensure the item is toggled on for display in the menu, given the
+	// value has been set external to the control.
 	useEffect( () => {
-		if ( isShownByDefault && isValueSet && ! wasValueSet ) {
-			flagItemCustomization( label );
+		if ( ! newValueSet ) {
+			return;
+		}
+
+		if ( isShownByDefault || currentPanelId === null ) {
+			flagItemCustomization( label, menuGroup );
 		}
 	}, [
-		isValueSet,
-		wasValueSet,
+		currentPanelId,
+		newValueSet,
 		isShownByDefault,
+		menuGroup,
 		label,
 		flagItemCustomization,
 	] );
 
-	// Note: `label` is used as a key when building menu item state in
-	// `ToolsPanel`.
-	const menuGroup = isShownByDefault ? 'default' : 'optional';
-	const isMenuItemChecked = menuItems?.[ menuGroup ]?.[ label ];
-	const wasMenuItemChecked = usePrevious( isMenuItemChecked );
-	const isRegistered = menuItems?.[ menuGroup ]?.[ label ] !== undefined;
-
 	// Determine if the panel item's corresponding menu is being toggled and
 	// trigger appropriate callback if it is.
 	useEffect( () => {

package/src/tools-panel/types.ts

@@ -3,7 +3,12 @@
  */
 import type { ReactNode } from 'react';
 
-type ResetAllFilter = () => void;
+/**
+ * Internal dependencies
+ */
+import type { HeadingSize } from '../heading/types';
+
+type ResetAllFilter = ( attributes?: any ) => any;
 type ResetAll = ( filters?: ResetAllFilter[] ) => void;
 
 export type ToolsPanelProps = {
@@ -14,8 +19,16 @@ export type ToolsPanelProps = {
 	/**
 	 * Flags that the items in this ToolsPanel will be contained within an inner
 	 * wrapper element allowing the panel to lay them out accordingly.
+	 *
+	 * @default false
+	 */
+	hasInnerWrapper?: boolean;
+	/**
+	 * The heading level of the panel's header.
+	 *
+	 * @default 2
 	 */
-	hasInnerWrapper: boolean;
+	headingLevel?: HeadingSize;
 	/**
 	 * Text to be displayed within the panel's header and as the `aria-label`
 	 * for the panel's dropdown menu.
@@ -23,20 +36,24 @@ export type ToolsPanelProps = {
 	label: string;
 	/**
 	 * If a `panelId` is set, it is passed through the `ToolsPanelContext` and
-	 * used to restrict panel items. Only items with a matching `panelId` will
-	 * be able to register themselves with this panel.
+	 * used to restrict panel items. When a `panelId` is set, items can only
+	 * register themselves if the `panelId` is explicitly `null` or the item's
+	 * `panelId` matches exactly.
 	 */
-	panelId: string;
+	panelId?: string | null;
 	/**
-	 * A function to call when the `Reset all` menu option is selected. This is
-	 * passed through to the panel's header component.
+	 * A function to call when the `Reset all` menu option is selected. As an
+	 * argument, it receives an array containing the `resetAllFilter` callbacks
+	 * of all the valid registered `ToolsPanelItems`.
 	 */
 	resetAll: ResetAll;
 	/**
 	 * Advises the `ToolsPanel` that its child `ToolsPanelItem`s should render
 	 * placeholder content instead of null when they are toggled off and hidden.
+	 *
+	 * @default false
 	 */
-	shouldRenderPlaceholderItems: boolean;
+	shouldRenderPlaceholderItems?: boolean;
 	/**
 	 * Experimental prop allowing for a custom CSS class to be applied to the
 	 * first visible `ToolsPanelItem` within the `ToolsPanel`.
@@ -50,6 +67,12 @@ export type ToolsPanelProps = {
 };
 
 export type ToolsPanelHeaderProps = {
+	/**
+	 * The heading level of the panel's header.
+	 *
+	 * @default 2
+	 */
+	headingLevel?: HeadingSize;
 	/**
 	 * Text to be displayed within the panel header. It is also passed along as
 	 * the `label` for the panel header's `DropdownMenu`.
@@ -79,8 +102,10 @@ export type ToolsPanelItem = {
 	 * This prop identifies the current item as being displayed by default. This
 	 * means it will show regardless of whether it has a value set or is toggled
 	 * on in the panel's menu.
+	 *
+	 * @default false
 	 */
-	isShownByDefault: boolean;
+	isShownByDefault?: boolean;
 	/**
 	 * The supplied label is dual purpose. It is used as:
 	 * 1. the human-readable label for the panel's dropdown menu
@@ -91,17 +116,20 @@ export type ToolsPanelItem = {
 	 */
 	label: string;
 	/**
-	 * Panel items will ensure they are only registering with their intended
-	 * panel by comparing the `panelId` props set on both the item and the panel
-	 * itself. This allows items to be injected from a shared source.
+	 * Panel items will ensure they are only registering with their intended panel
+	 * by comparing the `panelId` props set on both the item and the panel itself,
+	 * or if the `panelId` is explicitly `null`. This allows items to be injected
+	 * from a shared source.
 	 */
-	panelId: string;
+	panelId?: string | null;
 	/**
 	 * A `ToolsPanel` will collect each item's `resetAllFilter` and pass an
 	 * array of these functions through to the panel's `resetAll` callback. They
 	 * can then be iterated over to perform additional tasks.
+	 *
+	 * @default noop
 	 */
-	resetAllFilter: ResetAllFilter;
+	resetAllFilter?: ResetAllFilter;
 };
 
 export type ToolsPanelItemProps = ToolsPanelItem & {
@@ -128,7 +156,7 @@ export type ToolsPanelMenuItems = {
 };
 
 export type ToolsPanelContext = {
-	panelId?: string;
+	panelId?: string | null;
 	menuItems: ToolsPanelMenuItems;
 	hasMenuItems: boolean;
 	registerPanelItem: ( item: ToolsPanelItem ) => void;

package/src/tree-grid/README.md

@@ -10,7 +10,7 @@ This feature is still experimental. “Experimental” means this is an early im
 
 ## Development guidelines
 
-`TreeGrid`, `TreeGridRow`, and `TreeGridCell` are components used to create a tree hierarchy. They're not visually styled components, but instead help with adding keyboard navigation and roving tab index behaviors to tree grid structures.
+`TreeGrid`, `TreeGridRow`, and `TreeGridCell` are components used to create a tree hierarchy. They're not visually styled components, but instead help with adding keyboard navigation and roving tabindex behaviors to tree grid structures.
 
 A tree grid is a hierarchical 2 dimensional UI component, for example it could be used to implement a file system browser.
 
@@ -31,69 +31,36 @@ function TreeMenu() {
 			<TreeGridRow level={ 1 } positionInSet={ 1 } setSize={ 2 }>
 				<TreeGridCell>
 					{ ( props ) => (
-						<Button onClick={ onSelect } { ...props }>
-							Select
-						</Button>
+						<Button onClick={ onSelect } { ...props }>Select</Button>
 					) }
 				</TreeGridCell>
 				<TreeGridCell>
 					{ ( props ) => (
-						<Button onClick={ onMoveUp } { ...props }>
-							Move Up
-						</Button>
-					) }
-				</TreeGridCell>
-				<TreeGridCell>
-					{ ( props ) => (
-						<Button onClick={ onMoveDown } { ...props }>
-							Move Down
-						</Button>
+						<Button onClick={ onMove } { ...props }>Move</Button>
 					) }
 				</TreeGridCell>
 			</TreeGridRow>
 			<TreeGridRow level={ 1 } positionInSet={ 2 } setSize={ 2 }>
 				<TreeGridCell>
 					{ ( props ) => (
-						<Button onClick={ onSelect } { ...props }>
-							Select
-						</Button>
-					) }
-				</TreeGridCell>
-				<TreeGridCell>
-					{ ( props ) => (
-						<Button onClick={ onMoveUp } { ...props }>
-							Move Up
-						</Button>
+						<Button onClick={ onSelect } { ...props }>Select</Button>
 					) }
 				</TreeGridCell>
 				<TreeGridCell>
 					{ ( props ) => (
-						<Button onClick={ onMoveDown } { ...props }>
-							Move Down
-						</Button>
+						<Button onClick={ onMove } { ...props }>Move</Button>
 					) }
 				</TreeGridCell>
 			</TreeGridRow>
 			<TreeGridRow level={ 2 } positionInSet={ 1 } setSize={ 1 }>
 				<TreeGridCell>
 					{ ( props ) => (
-						<Button onClick={ onSelect } { ...props }>
-							Select
-						</Button>
-					) }
-				</TreeGridCell>
-				<TreeGridCell>
-					{ ( props ) => (
-						<Button onClick={ onMoveUp } { ...props }>
-							Move Up
-						</Button>
+						<Button onClick={ onSelect } { ...props }>Select</Button>
 					) }
 				</TreeGridCell>
 				<TreeGridCell>
 					{ ( props ) => (
-						<Button onClick={ onMoveDown } { ...props }>
-							Move Down
-						</Button>
+						<Button onClick={ onMove } { ...props }>Move</Button>
 					) }
 				</TreeGridCell>
 			</TreeGridRow>
@@ -112,27 +79,24 @@ Aside from the documented callback functions, any props specified will be passed
 
 `TreeGrid` should always have children.
 
-###### onFocusRow( event: Event, startRow: HTMLElement, destinationRow: HTMLElement )
+###### `onFocusRow`: `( event: KeyboardEvent, startRow: HTMLElement, destinationRow: HTMLElement ) => void`
 
 Callback that fires when focus is shifted from one row to another via the Up and Down keys. Callback is also fired on Home and End keys which move focus from the beginning row to the end row.
 The callback is passed the event, the start row element that the focus was on originally, and
 the destination row element after the focus has moved.
 
--   Type: `Function`
 -   Required: No
 
-###### onCollapseRow( row: HTMLElement )
+###### `onCollapseRow`: `( row: HTMLElement ) => void`
 
 A callback that passes in the row element to be collapsed.
 
--   Type: `Function`
 -   Required: No
 
-###### onExpandRow( row: HTMLElement )
+###### `onExpandRow`: `( row: HTMLElement ) => void`
 
 A callback that passes in the row element to be expanded.
 
--   Type: `Function`
 -   Required: No
 
 #### TreeGridRow
@@ -141,32 +105,28 @@ A callback that passes in the row element to be expanded.
 
 Additional props other than those specified below will be passed to the `tr` element rendered by `TreeGridRow`, so for example, it is possible to also set a `className` on a row.
 
-###### level
+###### `level`: `number`
 
 An integer value designating the level in the hierarchical tree structure. Counting starts at 1. A value of `1` indicates the root level of the structure.
 
--   Type: `Number`
 -   Required: Yes
 
-###### positionInSet
+###### `positionInSet`: `number`
 
 An integer value that represents the position in the set. A set is the count of elements at a specific level. Counting starts at 1.
 
--   Type: `Number`
 -   Required: Yes
 
-###### setSize
+###### `setSize`: `number`
 
-An integer value that represents the total number of items in the set ... that is the total number of items at this specific level of the hierarchy.
+An integer value that represents the total number of items in the set, at this specific level of the hierarchy.
 
--   Type: `Number`
 -   Required: Yes
 
-###### isExpanded
+###### `isExpanded`: `boolean`
 
 An optional value that designates whether a row is expanded or collapsed. Currently this value only sets the correct aria-expanded property on a row, it has no other built-in behavior.
 
--   Type: `Boolean`
 -   Required: No
 
 ### TreeGridCell
@@ -182,14 +142,14 @@ An optional value that designates whether a row is expanded or collapsed. Curren
 ```jsx
 <TreeGridCell>
 	{ ( props ) => (
-		<Button onClick={ onMoveDown } { ...props }>
-			Move Down
+		<Button onClick={ doSomething } { ...props }>
+			Do something
 		</Button>
 	) }
 </TreeGridCell>
 ```
 
-Props passed as an argument to the render prop must be passed to the child focusable component/element within the cell. If a component is used, it must correctly handle the `onFocus`, `tabIndex`, and `ref` props, passing these to the element it renders. These props are used to handle the roving tab index functionality of the tree grid.
+Props passed as an argument to the render prop must be passed to the child focusable component/element within the cell. If a component is used, it must correctly handle the `onFocus`, `tabIndex`, and `ref` props, passing these to the element it renders. These props are used to handle the roving tabindex functionality of the tree grid.
 
 ## Related components
 

package/src/tree-grid/cell.tsx

@@ -0,0 +1,41 @@
+/**
+ * WordPress dependencies
+ */
+import { forwardRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import TreeGridItem from './item';
+import type { WordPressComponentProps } from '../ui/context';
+import type { TreeGridCellProps } from './types';
+
+function UnforwardedTreeGridCell(
+	{
+		children,
+		withoutGridItem = false,
+		...props
+	}: WordPressComponentProps< TreeGridCellProps, 'td', false >,
+	ref: React.ForwardedRef< any >
+) {
+	return (
+		<td { ...props } role="gridcell">
+			{ withoutGridItem ? (
+				<>{ children }</>
+			) : (
+				<TreeGridItem ref={ ref }>{ children }</TreeGridItem>
+			) }
+		</td>
+	);
+}
+
+/**
+ * `TreeGridCell` is used to create a tree hierarchy.
+ * It is not a visually styled component, but instead helps with adding
+ * keyboard navigation and roving tab index behaviors to tree grid structures.
+ *
+ * @see {@link https://www.w3.org/TR/wai-aria-practices/examples/treegrid/treegrid-1.html}
+ */
+export const TreeGridCell = forwardRef( UnforwardedTreeGridCell );
+
+export default TreeGridCell;