@wordpress/components 19.12.0 → 19.15.0

package/src/range-control/README.md

@@ -109,75 +109,100 @@ const MyRangeControl = () => {
 };
 ```
 
-### Props
+## Props
 
 The set of props accepted by the component will be specified below.
 Props not included in this set will be applied to the input elements.
 
-#### label
+### `afterIcon`: `string|Function|WPComponent|null`
 
-If this property is added, a label will be generated using label property as the content.
+If this property is added, an [Icon component](/packages/components/src/icon/README.md) will be rendered after the slider with the icon equal to `afterIcon`.
+
+For more information on `IconType` see the [Icon component](/packages/components/src/icon/index.tsx#L23).
+
+-   Required: No
+-   Platform: Web
+
+### `allowReset`: `boolean`
+
+If this property is true, a button to reset the slider is rendered.
 
--   Type: `String`
 -   Required: No
+-   Default: `false`
 -   Platform: Web | Mobile
 
-#### help
+### `beforeIcon`: `string|Function|WPComponent|null`
 
-If this property is added, a help text will be generated using help property as the content.
+If this property is added, an [Icon component](/packages/components/src/icon/README.md) will be rendered before the slider with the icon equal to `beforeIcon`.
+
+For more information on `IconType` see the [Icon component](/packages/components/src/icon/index.tsx#L23).
 
--   Type: `String|WPElement`
 -   Required: No
 -   Platform: Web
 
-#### beforeIcon
+### `color`: `CSSProperties['color']`
 
-If this property is added, a DashIcon component will be rendered before the slider with the icon equal to beforeIcon
+CSS color string for the `RangeControl` wrapper.
 
--   Type: `String`
 -   Required: No
 -   Platform: Web
 
-#### afterIcon
+### `currentInput`: `number`
 
-If this property is added, a DashIcon component will be rendered after the slider with the icon equal to afterIcon
+The current input to use as a fallback if `value` is currently `undefined`.
 
--   Type: `String`
 -   Required: No
 -   Platform: Web
 
-#### allowReset
+### `disabled`: `boolean`
 
-If this property is true, a button to reset the the slider is rendered.
+Disables the `input`, preventing new values from being applied.
 
--   Type: `Boolean`
 -   Required: No
--   Platform: Web | Mobile
+-   Platform: Web
 
-#### disabled
 
-Disables the `input`, preventing new values from being applied.
+### `help`: `string|WPElement`
+
+If this property is added, a help text will be generated using help property as the content.
 
--   Type: `Boolean`
 -   Required: No
 -   Platform: Web
 
-#### initialPosition
+### `hideLabelFromVision`: `boolean`
+
+Provides control over whether the label will only be visible to screen readers.
+
+- Required: No
+
+### `icon`: `string`
+
+An icon to be shown above the slider next to its container title.
+
+-   Required: No
+-   Platform: Mobile
+
+### `initialPosition`: `number`
 
 If no value exists this prop contains the slider starting position.
 
--   Type: `Number`
 -   Required: No
 -   Platform: Web | Mobile
 
-#### isShiftStepEnabled
+### `isShiftStepEnabled`: `boolean`
 
 Passed as a prop to the `NumberControl` component and is only applicable if `withInputField` is true. If true, while the number input has focus, pressing `UP` or `DOWN` along with the `SHIFT` key will change the value by the `shiftStep` value.
 
--   Type: `Boolean`
 -   Required: No
 
-#### marks
+### `label`: `string`
+
+If this property is added, a label will be generated using label property as the content.
+
+-   Required: No
+-   Platform: Web | Mobile
+
+### `marks`: `Array|boolean`
 
 Renders a visual representation of `step` ticks. Custom mark indicators can be provided by an `Array`.
 
@@ -204,49 +229,72 @@ const marks = [
 ];
 
 const MyRangeControl() {
-	return (<RangeControl marks={ marks } min={ 0 } max={ 10 } step={ 1 } />)
+	return ( <RangeControl marks={ marks } min={ 0 } max={ 10 } step={ 1 } /> )
 }
 ```
 
--   Type: `Array|Boolean`
 -   Required: No
 -   Platform: Web
 
-#### onChange
+### `onBlur`: `FocusEventHandler< HTMLInputElement >`
+
+Callback for when `RangeControl` input loses focus.
+
+-   Required: No
+-   Platform: Web
+
+### `onChange`: `( value?: number ) => void`
 
 A function that receives the new value. The value will be less than `max` and more than `min` unless a reset (enabled by `allowReset`) has occurred. In which case the value will be either that of `resetFallbackValue` if it has been specified or otherwise `undefined`.
 
--   Type: `function`
--   Required: Yes
+-   Required: No
 -   Platform: Web | Mobile
 
-#### min
+### `onFocus`: `FocusEventHandler< HTMLInputElement >`
+
+Callback for when `RangeControl` input gains focus.
+
+-   Required: No
+-   Platform: Web
+
+### `onMouseLeave`: `MouseEventHandler< HTMLInputElement >`
+
+Callback for when mouse exits the `RangeControl`.
+
+-   Required: No
+-   Platform: Web
+
+### `onMouseMove`: `MouseEventHandler< HTMLInputElement >`
+
+Callback for when mouse moves within the `RangeControl`.
+
+-   Required: No
+-   Platform: Web
+
+### `min`: `number`
 
 The minimum `value` allowed.
 
--   Type: `Number`
 -   Required: No
 -   Default: 0
 -   Platform: Web | Mobile
 
-#### max
+### `max`: `number`
 
 The maximum `value` allowed.
 
--   Type: `Number`
 -   Required: No
 -   Default: 100
 -   Platform: Web | Mobile
 
-#### railColor
+### `railColor`: `CSSProperties[ 'color' ]`
 
-Customizes the (background) color of the rail element.
+CSS color string to customize the rail element's background.
 
--   Type: `String`
 -   Required: No
 -   Platform: Web
 
-#### renderTooltipContent
+### `renderTooltipContent`: ( value ) => value
 
 A way to customize the rendered UI of the value. Example:
 
@@ -258,89 +306,69 @@ const MyRangeControl() {
 }
 ```
 
--   Type: `Function`
 -   Required: No
 -   Platform: Web
 
-#### resetFallbackValue
+### `resetFallbackValue`: `number`
 
 The value to revert to if the Reset button is clicked (enabled by `allowReset`)
 
--   Type: `Number`
--   Required: No
--   Platform: Web
-
-#### showTooltip
-
-Forcing the Tooltip UI to show or hide. This is overriden to `false` when `step` is set to the special string value `any`.
-
--   Type: `Boolean`
 -   Required: No
 -   Platform: Web
 
-#### step
+### `separatorType`: `'none' | 'fullWidth' | 'topFullWidth'`
 
-The minimum amount by which `value` changes. It is also a factor in validation as `value` must be a multiple of `step` (offset by `min`) to be valid. Accepts the special string value `any` that voids the validation constraint and overrides both `withInputField` and `showTooltip` props to `false`.
+Define if separator line under/above control row should be disabled or full width. By default it is placed below excluding underline the control icon.
 
--   Type: `Number | "any"`
 -   Required: No
--   Platform: Web
+-   Platform: Mobile
 
-#### shiftStep
+### `shiftStep`: `number`
 
 Passed as a prop to the `NumberControl` component and is only applicable if `withInputField` and `isShiftStepEnabled` are both true and while the number input has focus. Acts as a multiplier of `step`.
 
--   Type: `Number`
 -   Required: No
 
-#### trackColor
+### `showTooltip`: `boolean`
 
-Customizes the (background) color of the track element.
+Forcing the Tooltip UI to show or hide. This is overridden to `false` when `step` is set to the special string value `any`.
 
--   Type: `String`
 -   Required: No
 -   Platform: Web
 
-#### value
+### `step`: `number | 'any'`
 
-The current value of the range slider.
-
--   Type: `Number`
--   Required: Yes
--   Platform: Web | Mobile
+The minimum amount by which `value` changes. It is also a factor in validation as `value` must be a multiple of `step` (offset by `min`) to be valid. Accepts the special string value `any` that voids the validation constraint and overrides both `withInputField` and `showTooltip` props to `false`.
 
-#### withInputField
+-   Required: No
+-   Platform: Web
+### `trackColor`: `CSSProperties[ 'color' ]`
 
-Determines if the `input` number field will render next to the RangeControl. This is overriden to `false` when `step` is set to the special string value `any`.
+CSS color string to customize the track element's background.
 
--   Type: `Boolean`
 -   Required: No
 -   Platform: Web
 
-#### icon
+### `type`: `string`
 
-An icon to be shown above the slider next to it's container title.
+Define if the value selection should present a stepper control or a slider control in the bottom sheet on mobile. To use the stepper set the type value as `stepper`. Defaults to slider if no option is provided.
 
--   Type: `String`
 -   Required: No
 -   Platform: Mobile
 
-#### separatorType
+### `value`: `number`
 
-Define if separator line under/above control row should be disabled or full width. By default it is placed below excluding underline the control icon.
+The current value of the range slider.
 
--   Type: `String Enum`
--   Values: `none` | `fullWidth` | `topFullWidth`
 -   Required: No
--   Platform: Mobile
+-   Platform: Web | Mobile
 
-#### type
+### `withInputField`: `boolean`
 
-Define if the value selection should present a stepper control or a slider control in the bottom sheet on mobile. To use the stepper set the type value as `stepper`. Defaults to slider if no option is provided.
+Determines if the `input` number field will render next to the RangeControl. This is overridden to `false` when `step` is set to the special string value `any`.
 
--   Type: `String`
 -   Required: No
--   Platform: Mobile
+-   Platform: Web
 
 ## Related components
 

package/src/range-control/{index.js → index.tsx}

@@ -1,16 +1,15 @@
-// @ts-nocheck
 /**
  * External dependencies
  */
 import classnames from 'classnames';
-import { clamp, isFinite, noop } from 'lodash';
+import type { ChangeEvent, FocusEvent, ForwardedRef } from 'react';
 
 /**
  * WordPress dependencies
  */
 import { __, isRTL } from '@wordpress/i18n';
 import { useRef, useState, forwardRef } from '@wordpress/element';
-import { useInstanceId } from '@wordpress/compose';
+import { useInstanceId, useMergeRefs } from '@wordpress/compose';
 
 /**
  * Internal dependencies
@@ -20,6 +19,7 @@ import Button from '../button';
 import Icon from '../icon';
 import { COLORS } from '../utils';
 import { floatClamp, useControlledRangeValue } from './utils';
+import { clamp } from '../utils/math';
 import InputRange from './input-range';
 import RangeRail from './rail';
 import SimpleTooltip from './tooltip';
@@ -35,69 +35,74 @@ import {
 	Wrapper,
 } from './styles/range-control-styles';
 
-function RangeControl(
-	{
+import type { RangeControlProps } from './types';
+import type { WordPressComponentProps } from '../ui/context';
+
+const noop = () => {};
+
+function UnforwardedRangeControl< IconProps = unknown >(
+	props: WordPressComponentProps<
+		RangeControlProps< IconProps >,
+		'input',
+		false
+	>,
+	forwardedRef: ForwardedRef< HTMLInputElement >
+) {
+	const {
 		afterIcon,
 		allowReset = false,
 		beforeIcon,
 		className,
-		currentInput,
 		color: colorProp = COLORS.ui.theme,
+		currentInput,
 		disabled = false,
 		help,
+		hideLabelFromVision = false,
 		initialPosition,
 		isShiftStepEnabled = true,
 		label,
-		hideLabelFromVision = false,
 		marks = false,
 		max = 100,
 		min = 0,
 		onBlur = noop,
 		onChange = noop,
 		onFocus = noop,
-		onMouseMove = noop,
 		onMouseLeave = noop,
+		onMouseMove = noop,
 		railColor,
-		resetFallbackValue,
 		renderTooltipContent = ( v ) => v,
-		showTooltip: showTooltipProp,
+		resetFallbackValue,
 		shiftStep = 10,
+		showTooltip: showTooltipProp,
 		step = 1,
 		trackColor,
 		value: valueProp,
 		withInputField = true,
-		...props
-	},
-	ref
-) {
+		...otherProps
+	} = props;
+
 	const [ value, setValue ] = useControlledRangeValue( {
 		min,
 		max,
-		value: valueProp,
+		value: valueProp ?? null,
 		initial: initialPosition,
 	} );
 	const isResetPendent = useRef( false );
 
+	let hasTooltip = showTooltipProp;
+	let hasInputField = withInputField;
+
 	if ( step === 'any' ) {
 		// The tooltip and number input field are hidden when the step is "any"
 		// because the decimals get too lengthy to fit well.
-		showTooltipProp = false;
-		withInputField = false;
+		hasTooltip = false;
+		hasInputField = false;
 	}
 
-	const [ showTooltip, setShowTooltip ] = useState( showTooltipProp );
+	const [ showTooltip, setShowTooltip ] = useState( hasTooltip );
 	const [ isFocused, setIsFocused ] = useState( false );
 
-	const inputRef = useRef();
-
-	const setRef = ( nodeRef ) => {
-		inputRef.current = nodeRef;
-
-		if ( ref ) {
-			ref( nodeRef );
-		}
-	};
-
+	const inputRef = useRef< HTMLInputElement >();
 	const isCurrentlyFocused = inputRef.current?.matches( ':focus' );
 	const isThumbFocused = ! disabled && isFocused;
 
@@ -105,11 +110,11 @@ function RangeControl(
 	const currentValue = value !== undefined ? value : currentInput;
 
 	const inputSliderValue = isValueReset ? '' : currentValue;
-
 	const rangeFillValue = isValueReset ? ( max - min ) / 2 + min : value;
 
-	const calculatedFillValue = ( ( value - min ) / ( max - min ) ) * 100;
-	const fillValue = isValueReset ? 50 : calculatedFillValue;
+	const fillValue = isValueReset
+		? 50
+		: ( ( value - min ) / ( max - min ) ) * 100;
 	const fillValueOffset = `${ clamp( fillValue, 0, 100 ) }%`;
 
 	const classes = classnames( 'components-range-control', className );
@@ -119,27 +124,32 @@ function RangeControl(
 		!! marks && 'is-marked'
 	);
 
-	const id = useInstanceId( RangeControl, 'inspector-range-control' );
+	const id = useInstanceId(
+		UnforwardedRangeControl,
+		'inspector-range-control'
+	);
 	const describedBy = !! help ? `${ id }__help` : undefined;
-	const enableTooltip = showTooltipProp !== false && isFinite( value );
+	const enableTooltip = hasTooltip !== false && Number.isFinite( value );
 
-	const handleOnRangeChange = ( event ) => {
+	const handleOnRangeChange = ( event: ChangeEvent< HTMLInputElement > ) => {
 		const nextValue = parseFloat( event.target.value );
 		setValue( nextValue );
 		onChange( nextValue );
 	};
 
-	const handleOnChange = ( nextValue ) => {
-		nextValue = parseFloat( nextValue );
+	const handleOnChange = ( next: string ) => {
+		let nextValue = parseFloat( next );
 		setValue( nextValue );
+
 		/*
 		 * Calls onChange only when nextValue is numeric
 		 * otherwise may queue a reset for the blur event.
 		 */
 		if ( ! isNaN( nextValue ) ) {
 			if ( nextValue < min || nextValue > max ) {
-				nextValue = floatClamp( nextValue, min, max );
+				nextValue = floatClamp( nextValue, min, max ) as number;
 			}
+
 			onChange( nextValue );
 			isResetPendent.current = false;
 		} else if ( allowReset ) {
@@ -155,8 +165,8 @@ function RangeControl(
 	};
 
 	const handleOnReset = () => {
-		let resetValue = parseFloat( resetFallbackValue );
-		let onChangeResetValue = resetValue;
+		let resetValue: number | null = parseFloat( `${ resetFallbackValue }` );
+		let onChangeResetValue: number | undefined = resetValue;
 
 		if ( isNaN( resetValue ) ) {
 			resetValue = null;
@@ -184,13 +194,13 @@ function RangeControl(
 	const handleShowTooltip = () => setShowTooltip( true );
 	const handleHideTooltip = () => setShowTooltip( false );
 
-	const handleOnBlur = ( event ) => {
+	const handleOnBlur = ( event: FocusEvent< HTMLInputElement > ) => {
 		onBlur( event );
 		setIsFocused( false );
 		handleHideTooltip();
 	};
 
-	const handleOnFocus = ( event ) => {
+	const handleOnFocus = ( event: FocusEvent< HTMLInputElement > ) => {
 		onFocus( event );
 		setIsFocused( true );
 		handleShowTooltip();
@@ -205,7 +215,7 @@ function RangeControl(
 			className={ classes }
 			label={ label }
 			hideLabelFromVision={ hideLabelFromVision }
-			id={ id }
+			id={ `${ id }` }
 			help={ help }
 		>
 			<Root className="components-range-control__root">
@@ -220,11 +230,11 @@ function RangeControl(
 					marks={ !! marks }
 				>
 					<InputRange
-						{ ...props }
+						{ ...otherProps }
 						className="components-range-control__slider"
 						describedBy={ describedBy }
 						disabled={ disabled }
-						id={ id }
+						id={ `${ id }` }
 						label={ label }
 						max={ max }
 						min={ min }
@@ -233,9 +243,9 @@ function RangeControl(
 						onFocus={ handleOnFocus }
 						onMouseMove={ onMouseMove }
 						onMouseLeave={ onMouseLeave }
-						ref={ setRef }
+						ref={ useMergeRefs( [ inputRef, forwardedRef ] ) }
 						step={ step }
-						value={ inputSliderValue }
+						value={ inputSliderValue ?? undefined }
 					/>
 					<RangeRail
 						aria-hidden={ true }
@@ -278,7 +288,7 @@ function RangeControl(
 						<Icon icon={ afterIcon } />
 					</AfterIconWrapper>
 				) }
-				{ withInputField && (
+				{ hasInputField && (
 					<InputNumber
 						aria-label={ label }
 						className="components-range-control__number"
@@ -312,6 +322,28 @@ function RangeControl(
 	);
 }
 
-const ForwardedComponent = forwardRef( RangeControl );
+/**
+ * RangeControls are used to make selections from a range of incremental values.
+ *
+ * ```jsx
+ * import { RangeControl } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
+ *
+ * const MyRangeControl = () => {
+ *   const [ isChecked, setChecked ] = useState( true );
+ *   return (
+ *     <RangeControl
+ *       help="Please select how transparent you would like this."
+ *       initialPosition={50}
+ *       label="Opacity"
+ *       max={100}
+ *       min={0}
+ *       onChange={() => {}}
+ *     />
+ *   );
+ * };
+ * ```
+ */
+export const RangeControl = forwardRef( UnforwardedRangeControl );
 
-export default ForwardedComponent;
+export default RangeControl;

package/src/range-control/{input-range.js → input-range.tsx}

@@ -1,9 +1,3 @@
-// @ts-nocheck
-/**
- * External dependencies
- */
-import { noop } from 'lodash';
-
 /**
  * WordPress dependencies
  */
@@ -15,8 +9,16 @@ import { forwardRef } from '@wordpress/element';
 import { InputRange as BaseInputRange } from './styles/range-control-styles';
 import { useDebouncedHoverInteraction } from './utils';
 
+import type { InputRangeProps } from './types';
+import type { WordPressComponentProps } from '../ui/context';
+
+const noop = () => {};
+
 function InputRange(
-	{
+	props: WordPressComponentProps< InputRangeProps, 'input' >,
+	ref: React.ForwardedRef< HTMLInputElement >
+) {
+	const {
 		describedBy,
 		label,
 		onHideTooltip = noop,
@@ -24,10 +26,9 @@ function InputRange(
 		onMouseMove = noop,
 		onShowTooltip = noop,
 		value,
-		...props
-	},
-	ref
-) {
+		...otherProps
+	} = props;
+
 	const hoverInteractions = useDebouncedHoverInteraction( {
 		onHide: onHideTooltip,
 		onMouseLeave,
@@ -37,7 +38,7 @@ function InputRange(
 
 	return (
 		<BaseInputRange
-			{ ...props }
+			{ ...otherProps }
 			{ ...hoverInteractions }
 			aria-describedby={ describedBy }
 			aria-label={ label }

package/src/range-control/{mark.js → mark.tsx}

@@ -1,4 +1,3 @@
-// @ts-nocheck
 /**
  * External dependencies
  */
@@ -9,13 +8,20 @@ import classnames from 'classnames';
  */
 import { Mark, MarkLabel } from './styles/range-control-styles';
 
-export default function RangeMark( {
-	className,
-	isFilled = false,
-	label,
-	style = {},
-	...props
-} ) {
+import type { RangeMarkProps } from './types';
+import type { WordPressComponentProps } from '../ui/context';
+
+export default function RangeMark(
+	props: WordPressComponentProps< RangeMarkProps, 'span' >
+) {
+	const {
+		className,
+		isFilled = false,
+		label,
+		style = {},
+		...otherProps
+	} = props;
+
 	const classes = classnames(
 		'components-range-control__mark',
 		isFilled && 'is-filled',
@@ -29,7 +35,7 @@ export default function RangeMark( {
 	return (
 		<>
 			<Mark
-				{ ...props }
+				{ ...otherProps }
 				aria-hidden="true"
 				className={ classes }
 				isFilled={ isFilled }