@wordpress/components 23.3.2 → 23.4.0

package/src/tree-grid/types.ts

@@ -0,0 +1,116 @@
+export type TreeGridRowProps = {
+	/**
+	 * The children to be rendered in the row.
+	 */
+	children: React.ReactNode;
+	/**
+	 * 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.
+	 */
+	level: NonNullable< React.AriaAttributes[ 'aria-level' ] >;
+	/**
+	 * 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.
+	 */
+	positionInSet: NonNullable< React.AriaAttributes[ 'aria-posinset' ] >;
+	/**
+	 * An integer value that represents the total number of items in the set,
+	 * at this specific level of the hierarchy.
+	 */
+	setSize: NonNullable< React.AriaAttributes[ 'aria-setsize' ] >;
+	/**
+	 * 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.
+	 */
+	isExpanded?: boolean;
+};
+
+type RovingTabIndexItemPassThruProps = {
+	ref: React.ForwardedRef< any >;
+	tabIndex?: number;
+	onFocus: React.FocusEventHandler< any >;
+	[ key: string ]: any;
+};
+
+export type RovingTabIndexItemProps = {
+	/**
+	 * A render function that receives the props necessary to make it participate in the
+	 * roving tabindex. Any extra props will also be passed through to this function.
+	 *
+	 * 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.
+	 *
+	 * ```jsx
+	 * <TreeGridCell>
+	 * 	{ ( props ) => (
+	 * 		<Button onClick={ doSomething } { ...props }>
+	 * 			Do something
+	 * 		</Button>
+	 * 	) }
+	 * </TreeGridCell>
+	 * ```
+	 */
+	children?: ( props: RovingTabIndexItemPassThruProps ) => JSX.Element;
+	/**
+	 * If `children` is not a function, this component will be used instead.
+	 */
+	as?: React.ComponentType< RovingTabIndexItemPassThruProps >;
+	[ key: string ]: any;
+};
+
+export type TreeGridCellProps =
+	| ( {
+			/**
+			 * Render `children` without wrapping it in a `TreeGridItem` component.
+			 * This means that `children` will not participate in the roving tabindex.
+			 *
+			 * @default false
+			 */
+			withoutGridItem?: false;
+	  } & NonNullable< Pick< RovingTabIndexItemProps, 'children' > > )
+	| {
+			children: React.ReactNode;
+			withoutGridItem: true;
+	  };
+
+export type TreeGridProps = {
+	/**
+	 * Label to use for the element with the `application` role.
+	 */
+	applicationAriaLabel?: string;
+	/**
+	 * The children to be rendered in the tree grid.
+	 */
+	children: React.ReactNode;
+	/**
+	 * Callback to fire when row is expanded.
+	 *
+	 * @default noop
+	 */
+	onExpandRow?: ( row: HTMLElement ) => void;
+	/**
+	 * Callback to fire when row is collapsed.
+	 *
+	 * @default noop
+	 */
+	onCollapseRow?: ( row: 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.
+	 *
+	 * @default noop
+	 */
+	onFocusRow?: (
+		event: React.KeyboardEvent< HTMLTableElement >,
+		startRow: HTMLElement,
+		destinationRow: HTMLElement
+	) => void;
+};

package/src/ui/context/context-connect.ts

@@ -29,8 +29,8 @@ type ContextConnectOptions = {
  * Forwards ref (React.ForwardRef) and "Connects" (or registers) a component
  * within the Context system under a specified namespace.
  *
- * @param  Component The component to register into the Context system.
- * @param  namespace The namespace to register the component under.
+ * @param Component The component to register into the Context system.
+ * @param namespace The namespace to register the component under.
  * @return The connected WordPressComponent
  */
 export function contextConnect<
@@ -50,8 +50,8 @@ export function contextConnect<
  * "Connects" (or registers) a component within the Context system under a specified namespace.
  * Does not forward a ref.
  *
- * @param  Component The component to register into the Context system.
- * @param  namespace The namespace to register the component under.
+ * @param Component The component to register into the Context system.
+ * @param namespace The namespace to register the component under.
  * @return The connected WordPressComponent
  */
 export function contextConnectWithoutRef< P >(
@@ -110,7 +110,7 @@ function _contextConnect<
 /**
  * Attempts to retrieve the connected namespace from a component.
  *
- * @param  Component The component to retrieve a namespace from.
+ * @param Component The component to retrieve a namespace from.
  * @return The connected namespaces.
  */
 export function getConnectNamespace(
@@ -138,8 +138,8 @@ export function getConnectNamespace(
 /**
  * Checks to see if a component is connected within the Context system.
  *
- * @param  Component The component to retrieve a namespace from.
- * @param  match     The namespace to check.
+ * @param Component The component to retrieve a namespace from.
+ * @param match     The namespace to check.
  */
 export function hasConnectNamespace(
 	Component: ReactNode,

package/src/ui/context/get-styled-class-name-from-key.ts

@@ -7,7 +7,7 @@ import memoize from 'memize';
 /**
  * Generates the connected component CSS className based on the namespace.
  *
- * @param  namespace The name of the connected component.
+ * @param namespace The name of the connected component.
  * @return The generated CSS className.
  */
 function getStyledClassName( namespace: string ): string {

package/src/ui/utils/get-valid-children.ts

@@ -11,7 +11,7 @@ import { Children, isValidElement } from '@wordpress/element';
 /**
  * Gets a collection of available children elements from a React component's children prop.
  *
- * @param  children
+ * @param children
  *
  * @return An array of available children.
  */

package/src/ui/utils/space.ts

@@ -20,7 +20,7 @@ const GRID_BASE = '4px';
  * When given a unit value or one of the named CSS values like `auto`,
  * it will simply return the value back.
  *
- * @param  value A number, numeric string, or a unit value.
+ * @param value A number, numeric string, or a unit value.
  */
 export function space( value?: SpaceInput ): string | undefined {
 	if ( typeof value === 'undefined' ) {

package/src/unit-control/index.tsx

@@ -203,8 +203,8 @@ function UnforwardedUnitControl(
 	 * This allows us to tap into actions to transform the (next) state for
 	 * InputControl.
 	 *
-	 * @param  state  State from InputControl
-	 * @param  action Action triggering state change
+	 * @param state  State from InputControl
+	 * @param action Action triggering state change
 	 * @return The updated state to apply to InputControl
 	 */
 	const unitControlStateReducer: StateReducer = ( state, action ) => {

package/src/unit-control/utils.ts

@@ -130,9 +130,9 @@ export const DEFAULT_UNIT = allUnits.px;
  * Moving forward, ideally the value should be a string that contains both
  * the value and unit, example: '10px'
  *
- * @param  rawValue     The raw value as a string (may or may not contain the unit)
- * @param  fallbackUnit The unit used as a fallback, if not unit is detected in the `value`
- * @param  allowedUnits Units to derive from.
+ * @param rawValue     The raw value as a string (may or may not contain the unit)
+ * @param fallbackUnit The unit used as a fallback, if not unit is detected in the `value`
+ * @param allowedUnits Units to derive from.
  * @return The extracted quantity and unit. The quantity can be `undefined` in case the raw value
  * could not be parsed to a number correctly. The unit can be `undefined` in case the unit parse
  * from the raw value could not be matched against the list of allowed units.
@@ -152,7 +152,7 @@ export function getParsedQuantityAndUnit(
 /**
  * Checks if units are defined.
  *
- * @param  units List of units.
+ * @param units List of units.
  * @return Whether the list actually contains any units.
  */
 export function hasUnits(
@@ -168,8 +168,8 @@ export function hasUnits(
  * Parses a quantity and unit from a raw string value, given a list of allowed
  * units and otherwise falling back to the default unit.
  *
- * @param  rawValue     The raw value as a string (may or may not contain the unit)
- * @param  allowedUnits Units to derive from.
+ * @param rawValue     The raw value as a string (may or may not contain the unit)
+ * @param allowedUnits Units to derive from.
  * @return The extracted quantity and unit. The quantity can be `undefined` in case the raw value
  * could not be parsed to a number correctly. The unit can be `undefined` in case the unit parsed
  * from the raw value could not be matched against the list of allowed units.
@@ -208,10 +208,10 @@ export function parseQuantityAndUnitFromRawValue(
  * Parses quantity and unit from a raw value. Validates parsed value, using fallback
  * value if invalid.
  *
- * @param  rawValue         The next value.
- * @param  allowedUnits     Units to derive from.
- * @param  fallbackQuantity The fallback quantity, used in case it's not possible to parse a valid quantity from the raw value.
- * @param  fallbackUnit     The fallback unit, used in case it's not possible to parse a valid unit from the raw value.
+ * @param rawValue         The next value.
+ * @param allowedUnits     Units to derive from.
+ * @param fallbackQuantity The fallback quantity, used in case it's not possible to parse a valid quantity from the raw value.
+ * @param fallbackUnit     The fallback unit, used in case it's not possible to parse a valid unit from the raw value.
  * @return The extracted quantity and unit. The quantity can be `undefined` in case the raw value
  * could not be parsed to a number correctly, and the `fallbackQuantity` was also `undefined`. The
  * unit can be `undefined` only if the unit parsed from the raw value could not be matched against
@@ -248,7 +248,7 @@ export function getValidParsedQuantityAndUnit(
  * Takes a unit value and finds the matching accessibility label for the
  * unit abbreviation.
  *
- * @param  unit Unit value (example: `px`)
+ * @param unit Unit value (example: `px`)
  * @return a11y label for the unit abbreviation
  */
 export function getAccessibleLabelForUnit( unit: string ): string | undefined {
@@ -259,8 +259,8 @@ export function getAccessibleLabelForUnit( unit: string ): string | undefined {
 /**
  * Filters available units based on values defined a list of allowed unit values.
  *
- * @param  allowedUnitValues Collection of allowed unit value strings.
- * @param  availableUnits    Collection of available unit objects.
+ * @param allowedUnitValues Collection of allowed unit value strings.
+ * @param availableUnits    Collection of available unit objects.
  * @return Filtered units.
  */
 export function filterUnitsWithSettings(
@@ -282,10 +282,10 @@ export function filterUnitsWithSettings(
  * TODO: ideally this hook shouldn't be needed
  * https://github.com/WordPress/gutenberg/pull/31822#discussion_r633280823
  *
- * @param  args                An object containing units, settingPath & defaultUnits.
- * @param  args.units          Collection of all potentially available units.
- * @param  args.availableUnits Collection of unit value strings for filtering available units.
- * @param  args.defaultValues  Collection of default values for defined units. Example: `{ px: 350, em: 15 }`.
+ * @param args                An object containing units, settingPath & defaultUnits.
+ * @param args.units          Collection of all potentially available units.
+ * @param args.availableUnits Collection of unit value strings for filtering available units.
+ * @param args.defaultValues  Collection of default values for defined units. Example: `{ px: 350, em: 15 }`.
  *
  * @return Filtered list of units, with their default values updated following the `defaultValues`
  * argument's property.
@@ -327,9 +327,9 @@ export const useCustomUnits = ( {
  * accurately displayed in the UI, even if the intention is to hide
  * the availability of that unit.
  *
- * @param  rawValue   Selected value to parse.
- * @param  legacyUnit Legacy unit value, if rawValue needs it appended.
- * @param  units      List of available units.
+ * @param rawValue   Selected value to parse.
+ * @param legacyUnit Legacy unit value, if rawValue needs it appended.
+ * @param units      List of available units.
  *
  * @return A collection of units containing the unit for the current value.
  */

package/src/utils/events.ts

@@ -4,8 +4,8 @@ type EventHandler< T extends Event > = ( event: T ) => void;
  * Merges event handlers together.
  *
  * @template TEvent
- * @param  handler
- * @param  otherHandler
+ * @param    handler
+ * @param    otherHandler
  */
 function mergeEvent< TEvent extends Event >(
 	handler: EventHandler< TEvent >,
@@ -25,8 +25,8 @@ function mergeEvent< TEvent extends Event >(
  * Merges two sets of event handlers together.
  *
  * @template TEvent
- * @param  handlers
- * @param  extraHandlers
+ * @param    handlers
+ * @param    extraHandlers
  */
 export function mergeEventHandlers<
 	TEvent extends Event,

package/src/utils/hooks/use-controlled-state.js

@@ -11,8 +11,8 @@ import { isValueDefined, getDefinedValue } from '../values';
 /**
  * @template T
  * @typedef Options
- * @property {T | undefined} initial  Initial value
- * @property {T | ""}        fallback Fallback value
+ * @property {T}      [initial] Initial value
+ * @property {T | ""} fallback  Fallback value
  */
 
 /** @type {Readonly<{ initial: undefined, fallback: '' }>} */

package/src/utils/hooks/use-controlled-value.ts

@@ -12,10 +12,10 @@ type Props< T > = {
 /**
  * Simplified and improved implementation of useControlledState.
  *
- * @param  props
- * @param  props.defaultValue
- * @param  props.value
- * @param  props.onChange
+ * @param props
+ * @param props.defaultValue
+ * @param props.value
+ * @param props.onChange
  * @return The controlled value and the value setter.
  */
 export function useControlledValue< T >( {

package/src/utils/hooks/use-latest-ref.ts

@@ -15,7 +15,7 @@ import { useIsomorphicLayoutEffect } from '@wordpress/compose';
  *
  * @see https://codesandbox.io/s/uselatestref-mlj3i?file=/src/App.tsx
  *
- * @param  value The value to reference
+ * @param value The value to reference
  * @return The prop reference.
  */
 export function useLatestRef< T >( value: T ): RefObject< T > {

package/src/utils/unit-values.ts

@@ -4,7 +4,7 @@ const UNITED_VALUE_REGEX =
 /**
  * Parses a number and unit from a value.
  *
- * @param  toParse Value to parse
+ * @param toParse Value to parse
  *
  * @return  The extracted number and unit.
  */
@@ -27,8 +27,8 @@ export function parseCSSUnitValue(
 /**
  * Combines a value and a unit into a unit value.
  *
- * @param  value
- * @param  unit
+ * @param value
+ * @param unit
  *
  * @return The unit value.
  */

package/tsconfig.json

@@ -45,10 +45,7 @@
 		"src/**/stories/**/*.js", // only exclude js files, tsx files should be checked
 		"src/**/test/**/*.js", // only exclude js files, ts{x} files should be checked
 		"src/index.js",
-		"src/angle-picker-control",
 		"src/autocomplete",
-		"src/box-control",
-		"src/combobox-control",
 		"src/custom-gradient-picker",
 		"src/dimension-control",
 		"src/duotone-picker",
@@ -59,11 +56,8 @@
 		"src/higher-order/with-filters",
 		"src/higher-order/with-focus-return",
 		"src/higher-order/with-notices",
-		"src/menu-items-choice",
 		"src/navigation",
 		"src/palette-edit",
-		"src/panel",
-		"src/toolbar",
-		"src/tree-grid"
+		"src/panel/body.js"
 	]
 }