Components: Type BaseControl and VisuallyHidden (#26078)

* Type VisuallyHidden

* Type BaseControl

* Better, alphabetized includes

* Remove debugging code

* Revert stylistic changes

* Improve and fixup documentation

* Add tinycolor2 types

* Type utils

* Type cleanup

* Properly ignore stories

* Exclude stories and tests

* Update snapshot

* Use EffectCallback type

package.json

@@ -106,6 +106,7 @@
 		"@types/requestidlecallback": "0.3.1",
 		"@types/semver": "7.2.0",
 		"@types/sprintf-js": "1.1.2",
+		"@types/tinycolor2": "1.4.2",
 		"@types/uuid": "8.3.0",
 		"@types/webpack": "4.41.16",
 		"@types/webpack-sources": "0.1.7",

packages/block-editor/src/components/responsive-block-control/test/__snapshots__/index.js.snap

@@ -1,3 +1,3 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
-exports[`Basic rendering should render with required props 1`] = `"<fieldset class=\\"block-editor-responsive-block-control\\"><legend class=\\"block-editor-responsive-block-control__title\\">Padding</legend><div class=\\"block-editor-responsive-block-control__inner\\"><div class=\\"components-base-control components-toggle-control block-editor-responsive-block-control__toggle css-wdf2ti-Wrapper e1puf3u0\\"><div class=\\"components-base-control__field css-11vcxb9-StyledField e1puf3u1\\"><span class=\\"components-form-toggle is-checked\\"><input class=\\"components-form-toggle__input\\" id=\\"inspector-toggle-control-0\\" type=\\"checkbox\\" aria-describedby=\\"inspector-toggle-control-0__help\\" checked=\\"\\"><span class=\\"components-form-toggle__track\\"></span><span class=\\"components-form-toggle__thumb\\"></span></span><label for=\\"inspector-toggle-control-0\\" class=\\"components-toggle-control__label\\">Use the same padding on all screensizes.</label></div><p id=\\"inspector-toggle-control-0__help\\" class=\\"components-base-control__help css-1wm1a55-StyledHelp e1puf3u3\\">Toggle between using the same value for all screen sizes or using a unique value per screen size.</p></div><div class=\\"block-editor-responsive-block-control__group\\"><div class=\\"components-base-control css-wdf2ti-Wrapper e1puf3u0\\"><div class=\\"components-base-control__field css-11vcxb9-StyledField e1puf3u1\\"><div class=\\"components-flex components-select-control e1cr7zh10 css-xnuudl-Flex-Root eboqfv50\\"><div class=\\"components-flex__item e1cr7zh14 css-d373l0-Item-LabelWrapper eboqfv51\\"><label for=\\"inspector-select-control-0\\" class=\\"components-input-control__label css-za86g6-Text-BaseLabel e1cr7zh13\\"><span aria-describedby=\\"rbc-desc-0\\">All</span><span class=\\"components-visually-hidden\\" id=\\"rbc-desc-0\\">Controls the padding property for All viewports.</span></label></div><div class=\\"components-input-control__container css-nj8rmx-Container e1cr7zh11\\"><select class=\\"components-select-control__input css-hwcz8s-Select e12x0a390\\" id=\\"inspector-select-control-0\\"><option value=\\"\\">Please select</option><option value=\\"small\\">Small</option><option value=\\"medium\\">Medium</option><option value=\\"large\\">Large</option></select><span class=\\"components-input-control__suffix css-1lym30p-Suffix e1cr7zh17\\"><div class=\\"css-s55r1c-DownArrowWrapper e12x0a391\\"><svg viewBox=\\"0 0 24 24\\" xmlns=\\"http://www.w3.org/2000/svg\\" width=\\"18\\" height=\\"18\\" role=\\"img\\" aria-hidden=\\"true\\" focusable=\\"false\\"><path d=\\"M17.5 11.6L12 16l-5.5-4.4.9-1.2L12 14l4.5-3.6 1 1.2z\\"></path></svg></div></span><div aria-hidden=\\"true\\" class=\\"components-input-control__backdrop css-1s1n1to-BackdropUI e1cr7zh15\\"></div></div></div></div></div><p id=\\"all\\">All is used here for testing purposes to ensure we have access to details about the device.</p></div></div></fieldset>"`;
+exports[`Basic rendering should render with required props 1`] = `"<fieldset class=\\"block-editor-responsive-block-control\\"><legend class=\\"block-editor-responsive-block-control__title\\">Padding</legend><div class=\\"block-editor-responsive-block-control__inner\\"><div class=\\"components-base-control components-toggle-control block-editor-responsive-block-control__toggle css-wdf2ti-Wrapper e1puf3u0\\"><div class=\\"components-base-control__field css-11vcxb9-StyledField e1puf3u1\\"><span class=\\"components-form-toggle is-checked\\"><input class=\\"components-form-toggle__input\\" id=\\"inspector-toggle-control-0\\" type=\\"checkbox\\" aria-describedby=\\"inspector-toggle-control-0__help\\" checked=\\"\\"><span class=\\"components-form-toggle__track\\"></span><span class=\\"components-form-toggle__thumb\\"></span></span><label for=\\"inspector-toggle-control-0\\" class=\\"components-toggle-control__label\\">Use the same padding on all screensizes.</label></div><p id=\\"inspector-toggle-control-0__help\\" class=\\"components-base-control__help css-1wm1a55-StyledHelp e1puf3u3\\">Toggle between using the same value for all screen sizes or using a unique value per screen size.</p></div><div class=\\"block-editor-responsive-block-control__group\\"><div class=\\"components-base-control css-wdf2ti-Wrapper e1puf3u0\\"><div class=\\"components-base-control__field css-11vcxb9-StyledField e1puf3u1\\"><div class=\\"components-flex components-select-control e1cr7zh10 css-xnuudl-Flex-Root eboqfv50\\"><div class=\\"components-flex__item e1cr7zh14 css-d373l0-Item-LabelWrapper eboqfv51\\"><label for=\\"inspector-select-control-0\\" class=\\"components-input-control__label css-za86g6-Text-BaseLabel e1cr7zh13\\"><span aria-describedby=\\"rbc-desc-0\\">All</span><span class=\\"components-visually-hidden\\" id=\\"rbc-desc-0\\">Controls the padding property for All viewports.</span></label></div><div class=\\"components-input-control__container css-nj8rmx-Container e1cr7zh11\\"><select class=\\"components-select-control__input css-owzv2l-Select e12x0a390\\" id=\\"inspector-select-control-0\\"><option value=\\"\\">Please select</option><option value=\\"small\\">Small</option><option value=\\"medium\\">Medium</option><option value=\\"large\\">Large</option></select><span class=\\"components-input-control__suffix css-1lym30p-Suffix e1cr7zh17\\"><div class=\\"css-s55r1c-DownArrowWrapper e12x0a391\\"><svg viewBox=\\"0 0 24 24\\" xmlns=\\"http://www.w3.org/2000/svg\\" width=\\"18\\" height=\\"18\\" role=\\"img\\" aria-hidden=\\"true\\" focusable=\\"false\\"><path d=\\"M17.5 11.6L12 16l-5.5-4.4.9-1.2L12 14l4.5-3.6 1 1.2z\\"></path></svg></div></span><div aria-hidden=\\"true\\" class=\\"components-input-control__backdrop css-1o1vxqx-BackdropUI e1cr7zh15\\"></div></div></div></div></div><p id=\\"all\\">All is used here for testing purposes to ensure we have access to details about the device.</p></div></div></fieldset>"`;

packages/components/src/base-control/index.js

@@ -14,6 +14,26 @@ import {
 	StyledHelp,
 } from './styles/base-control-styles';
 
+/**
+ * @typedef Props
+ * @property {string} id The id of the element to which labels and help text are being generated.
+ *                       That element should be passed as a child.
+ * @property {import('react').ReactNode} help If this property is added, a help text will be
+ *                                            generated using help property as the content.
+ * @property {import('react').ReactNode} label If this property is added, a label will be generated
+ *                                             using label property as the content.
+ * @property {boolean} [hideLabelFromVision] If true, the label will only be visible to screen readers.
+ * @property {string} [className] The class that will be added with "components-base-control" to the
+ *                                classes of the wrapper div. If no className is passed only
+ *                                components-base-control is used.
+ * @property {import('react').ReactNode} [children] The content to be displayed within
+ *                                                  the BaseControl.
+ */
+
+/**
+ * @param {Props} props
+ * @return {JSX.Element} Element
+ */
 function BaseControl( {
 	id,
 	label,
@@ -64,6 +84,16 @@ function BaseControl( {
 	);
 }
 
+/**
+ * @typedef VisualLabelProps
+ * @property {string} [className] Class name
+ * @property {import('react').ReactNode} [children] Children
+ */
+
+/**
+ * @param {VisualLabelProps} Props
+ * @return {JSX.Element} Element
+ */
 BaseControl.VisualLabel = ( { className, children } ) => {
 	className = classnames( 'components-base-control__label', className );
 	return <span className={ className }>{ children }</span>;

packages/components/src/utils/colors.js

@@ -28,7 +28,7 @@ export function rgba( hexValue = '', alpha = 1 ) {
 /**
  * Retrieves a color from the color palette.
  *
- * @param {string} value The value to retrieve.
+ * @param {import('lodash').PropertyPath} value The value to retrieve.
  * @return {string} The color (or fallback, if not found).
  *
  * @example

packages/components/src/utils/hooks/use-controlled-state.js

@@ -8,6 +8,14 @@ import { useEffect, useState } from '@wordpress/element';
  */
 import { isValueDefined, getDefinedValue } from '../values';
 
+/**
+ * @template T
+ * @typedef Options
+ * @property {T | undefined} initial  Initial value
+ * @property {T | ""}        fallback Fallback value
+ */
+
+/** @type {Readonly<{ initial: undefined, fallback: '' }>} */
 const defaultOptions = {
 	initial: undefined,
 	/**
@@ -33,12 +41,12 @@ const defaultOptions = {
  * Unlike the basic useState hook, useControlledState's state can
  * be updated if a new incoming prop value is changed.
  *
- * @param {any} currentState The current value.
- * @param {Object} options Additional options for the hook.
- * @param {any} options.initial The initial state.
- * @param {any} options.fallback The state to use when no state is defined.
+ * @template T
+ *
+ * @param {T | undefined} currentState The current value.
+ * @param {Options<T>} [options=defaultOptions] Additional options for the hook.
  *
- * @return {[*, Function]} The controlled value and the value setter.
+ * @return {[T | "", (nextState: T) => void]} The controlled value and the value setter.
  */
 function useControlledState( currentState, options = defaultOptions ) {
 	const { initial, fallback } = { ...defaultOptions, ...options };
@@ -60,11 +68,14 @@ function useControlledState( currentState, options = defaultOptions ) {
 		fallback
 	);
 
+	/* eslint-disable jsdoc/no-undefined-types */
+	/** @type {(nextState: T) => void} */
 	const setState = ( nextState ) => {
 		if ( ! hasCurrentState ) {
 			setInternalState( nextState );
 		}
 	};
+	/* eslint-enable jsdoc/no-undefined-types */
 
 	return [ state, setState ];
 }

packages/components/src/utils/hooks/use-jump-step.js

@@ -29,6 +29,7 @@ function useJumpStep( {
 	const [ isShiftKey, setIsShiftKey ] = useState( false );
 
 	useEffect( () => {
+		/** @type {(event: KeyboardEvent)=>void} */
 		const handleShiftKeyToggle = ( event ) => {
 			setIsShiftKey( event.shiftKey );
 		};

packages/components/src/utils/hooks/use-update-effect.js

@@ -3,10 +3,13 @@
  */
 import { useRef, useEffect } from '@wordpress/element';
 
-/*
+/**
  * A `React.useEffect` that will not run on the first render.
  * Source:
  * https://github.com/reakit/reakit/blob/master/packages/reakit-utils/src/useUpdateEffect.ts
+ *
+ * @param {import('react').EffectCallback} effect
+ * @param {import('react').DependencyList} deps
  */
 function useUpdateEffect( effect, deps ) {
 	const mounted = useRef( false );

packages/components/src/utils/math.js

@@ -6,7 +6,7 @@ import { clamp } from 'lodash';
 /**
  * Parses and retrieves a number value.
  *
- * @param {any} value The incoming value.
+ * @param {unknown} value The incoming value.
  *
  * @return {number} The parsed number value.
  */
@@ -19,26 +19,34 @@ export function getNumber( value ) {
 /**
  * Safely adds 2 values.
  *
- * @param {number|string} args Values to add together.
+ * @param {Array<number|string>} args Values to add together.
  *
  * @return {number} The sum of values.
  */
 export function add( ...args ) {
-	return args.reduce( ( sum, arg ) => sum + getNumber( arg ), 0 );
+	return args.reduce(
+		/** @type {(sum:number, arg: number|string) => number} */
+		( sum, arg ) => sum + getNumber( arg ),
+		0
+	);
 }
 
 /**
  * Safely subtracts 2 values.
  *
- * @param {number|string} args Values to subtract together.
+ * @param {Array<number|string>} args Values to subtract together.
  *
- * @return {number} The difference of the 2 values.
+ * @return {number} The difference of the values.
  */
 export function subtract( ...args ) {
-	return args.reduce( ( diff, arg, index ) => {
-		const value = getNumber( arg );
-		return index === 0 ? value : diff - value;
-	} );
+	return args.reduce(
+		/** @type {(diff:number, arg: number|string, index:number) => number} */
+		( diff, arg, index ) => {
+			const value = getNumber( arg );
+			return index === 0 ? value : diff - value;
+		},
+		0
+	);
 }
 
 /**
@@ -84,12 +92,7 @@ export function roundClamp(
  * Clamps a value based on a min/max range with rounding.
  * Returns a string.
  *
- * @param {any} args Arguments for roundClamp().
- * @property {number} value The value.
- * @property {number} min The minimum range.
- * @property {number} max The maximum range.
- * @property {number} step A multiplier for the value.
- *
+ * @param {Parameters<typeof roundClamp>} args Arguments for roundClamp().
  * @return {string} The rounded and clamped value.
  */
 export function roundClampString( ...args ) {

packages/components/src/utils/rtl.js

@@ -65,9 +65,9 @@ function getConvertedKey( key ) {
 /**
  * An incredibly basic ltr -> rtl converter for style properties
  *
- * @param {Object} ltrStyles
+ * @param {import('react').CSSProperties} ltrStyles
  *
- * @return {Object} Converted ltr -> rtl styles
+ * @return {import('react').CSSProperties} Converted ltr -> rtl styles
  */
 export const convertLTRToRTL = ( ltrStyles = {} ) => {
 	return mapKeys( ltrStyles, ( _value, key ) => getConvertedKey( key ) );
@@ -76,8 +76,8 @@ export const convertLTRToRTL = ( ltrStyles = {} ) => {
 /**
  * A higher-order function that create an incredibly basic ltr -> rtl style converter for CSS objects.
  *
- * @param {Object} ltrStyles Ltr styles. Converts and renders from ltr -> rtl styles, if applicable.
- * @param {null|Object} rtlStyles Rtl styles. Renders if provided.
+ * @param {import('react').CSSProperties} ltrStyles   Ltr styles. Converts and renders from ltr -> rtl styles, if applicable.
+ * @param {import('react').CSSProperties} [rtlStyles] Rtl styles. Renders if provided.
  *
  * @return {Function} A function to output CSS styles for Emotion's renderer
  */
@@ -86,9 +86,11 @@ export function rtl( ltrStyles = {}, rtlStyles ) {
 		const isRTL = getRTL();
 
 		if ( rtlStyles ) {
+			// @ts-ignore: `css` types are wrong, it can accept an object: https://emotion.sh/docs/object-styles#with-css
 			return isRTL ? css( rtlStyles ) : css( ltrStyles );
 		}
 
+		// @ts-ignore: `css` types are wrong, it can accept an object: https://emotion.sh/docs/object-styles#with-css
 		return isRTL ? css( convertLTRToRTL( ltrStyles ) ) : css( ltrStyles );
 	};
 }

packages/components/src/utils/space.js

@@ -3,7 +3,7 @@ const SPACE_GRID_BASE = 8;
 /**
  * Creates a spacing CSS value (px) based on grid system values.
  *
- * @param {number} value Multiplier against the grid base value (8)
+ * @param {number} [value=1] Multiplier against the grid base value (8)
  * @return {string} The spacing value (px).
  */
 export function space( value = 1 ) {

packages/components/src/utils/values.js

@@ -1,31 +1,41 @@
+/* eslint-disable jsdoc/valid-types */
 /**
  * Determines if a value is null or undefined.
  *
- * @param {any} value The value to check.
- * @return {boolean} Whether value is null or undefined.
+ * @template T
+ *
+ * @param {T | null | undefined} value The value to check.
+ * @return {value is T} Whether value is not null or undefined.
  */
 export function isValueDefined( value ) {
 	return value !== undefined && value !== null;
 }
+/* eslint-enable jsdoc/valid-types */
 
+/* eslint-disable jsdoc/valid-types */
 /**
  * Determines if a value is empty, null, or undefined.
  *
- * @param {any} value The value to check.
- * @return {boolean} Whether value is empty.
+ * @template T
+ *
+ * @param {T | "" | null | undefined} value The value to check.
+ * @return {value is T} Whether value is empty.
  */
 export function isValueEmpty( value ) {
 	const isEmptyString = value === '';
 
 	return ! isValueDefined( value ) || isEmptyString;
 }
+/* eslint-enable jsdoc/valid-types */
 
 /**
- * Attempts to get a defined/non-null value from a collection of arguments.
+ * Get the first defined/non-null value from an array.
+ *
+ * @template T
  *
- * @param {Array<any>} values Values to derive from.
- * @param {any} fallbackValue Fallback value if there are no defined values.
- * @return {any} A defined value or the fallback value.
+ * @param {Array<T | null | undefined>} values Values to derive from.
+ * @param {T} fallbackValue Fallback value if there are no defined values.
+ * @return {T} A defined value or the fallback value.
  */
 export function getDefinedValue( values = [], fallbackValue ) {
 	return values.find( isValueDefined ) ?? fallbackValue;

packages/components/src/visually-hidden/index.js

@@ -8,13 +8,25 @@ import classnames from 'classnames';
  */
 import { renderAsRenderProps } from './utils';
 
+/**
+ * @template {keyof JSX.IntrinsicElements | import('react').JSXElementConstructor<any>} T
+ * @typedef OwnProps
+ * @property {T} [as='div'] Component to render, e.g. `"div"` or `MyComponent`.
+ */
+
+/**
+ * @template {keyof JSX.IntrinsicElements | import('react').JSXElementConstructor<any>} T
+ * @typedef {OwnProps<T> & import('react').ComponentProps<T>} Props
+ */
+
 /**
  * VisuallyHidden component to render text out non-visually
  * for use in devices such as a screen reader.
  *
- * @param {Object}             props             Component props.
- * @param {string|WPComponent} [props.as="div"]  A tag or component to render.
- * @param {string}             [props.className] Class to set on the container.
+ * @template {keyof JSX.IntrinsicElements | import('react').JSXElementConstructor<any>} T
+ *
+ * @param {Props<T>} props
+ * @return {JSX.Element} Element
  */
 function VisuallyHidden( { as = 'div', className, ...props } ) {
 	return renderAsRenderProps( {

packages/components/src/visually-hidden/utils.js

@@ -1,5 +1,13 @@
 /**
- * Utility Functions
+ * @template {keyof JSX.IntrinsicElements | import('react').JSXElementConstructor<any>} T
+ * @typedef OwnProps
+ * @property {T} [as='div'] Component to render
+ * @property {import('react').ReactNode | ((props: import('react').ComponentProps<T>) => JSX.Element) } [children] Children or render props function
+ */
+
+/**
+ * @template {keyof JSX.IntrinsicElements | import('react').JSXElementConstructor<any>} T
+ * @typedef {OwnProps<T> & import('react').ComponentProps<T>} Props
  */
 
 /**
@@ -9,8 +17,9 @@
  *
  * See VisuallyHidden hidden for example.
  *
- * @param {string|WPComponent} as A tag or component to render.
- * @return {WPComponent} The rendered component.
+ * @template {keyof JSX.IntrinsicElements | import('react').JSXElementConstructor<any>} T
+ * @param {Props<T>} props
+ * @return {JSX.Element} The rendered element.
  */
 function renderAsRenderProps( { as: Component = 'div', ...props } ) {
 	if ( typeof props.children === 'function' ) {

packages/components/tsconfig.json

@@ -5,5 +5,19 @@
 		"declarationDir": "build-types"
 	},
 	"references": [ { "path": "../primitives" } ],
-	"include": [ "src/dashicon/*", "src/tip/*" ]
+	"include": [
+		"src/base-control/**/*",
+		"src/dashicon/**/*",
+		"src/tip/**/*",
+		"src/utils/**/*",
+		"src/visually-hidden/**/*"
+	],
+	"exclude": [
+		"src/**/*.android.js",
+		"src/**/*.ios.js",
+		"src/**/*.native.js",
+		"src/**/react-native-*",
+		"src/**/stories",
+		"src/**/test"
+	]
 }