@wordpress/components 19.12.0 → 19.15.0

package/src/range-control/test/index.tsx

@@ -0,0 +1,311 @@
+/**
+ * External dependencies
+ */
+import { fireEvent, render, screen } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import RangeControl from '../';
+
+const getRangeInput = (): HTMLInputElement | null =>
+	screen.getByRole( 'slider' ) as HTMLInputElement;
+const getNumberInput = (): HTMLInputElement | null =>
+	screen.getByRole( 'spinbutton' ) as HTMLInputElement;
+const getResetButton = (): HTMLButtonElement | null =>
+	screen.getByRole( 'button' ) as HTMLButtonElement;
+
+const fireChangeEvent = (
+	input: HTMLInputElement | null,
+	value?: number | string
+) => fireEvent.change( input as Element, { target: { value } } );
+
+describe( 'RangeControl', () => {
+	describe( '#render()', () => {
+		it( 'should trigger change callback with numeric value', () => {
+			const onChange = jest.fn();
+
+			render( <RangeControl onChange={ onChange } /> );
+
+			const rangeInput = getRangeInput();
+			const numberInput = getNumberInput();
+
+			rangeInput?.focus();
+			fireChangeEvent( rangeInput, '5' );
+
+			numberInput?.focus();
+			fireChangeEvent( numberInput, '10' );
+
+			expect( onChange ).toHaveBeenCalledWith( 5 );
+			expect( onChange ).toHaveBeenCalledWith( 10 );
+		} );
+
+		it( 'should render with icons', () => {
+			const { container } = render(
+				<RangeControl
+					beforeIcon="format-image"
+					afterIcon="format-video"
+				/>
+			);
+
+			const beforeIcon = container.querySelector(
+				'.dashicons-format-image'
+			);
+			const afterIcon = container.querySelector(
+				'.dashicons-format-video'
+			);
+
+			expect( beforeIcon ).toBeInTheDocument();
+			expect( afterIcon ).toBeInTheDocument();
+		} );
+	} );
+
+	describe( 'validation', () => {
+		it( 'should not apply if new value is lower than minimum', () => {
+			render( <RangeControl min={ 11 } /> );
+
+			const rangeInput = getRangeInput();
+			const numberInput = getNumberInput();
+
+			fireChangeEvent( numberInput, '10' );
+			fireEvent.blur( numberInput as Element );
+
+			expect( rangeInput?.value ).not.toBe( '10' );
+		} );
+
+		it( 'should not apply if new value is greater than maximum', () => {
+			render( <RangeControl max={ 20 } /> );
+
+			const rangeInput = getRangeInput();
+			const numberInput = getNumberInput();
+
+			fireChangeEvent( numberInput, '21' );
+			fireEvent.blur( numberInput as Element );
+
+			expect( rangeInput?.value ).not.toBe( '21' );
+		} );
+
+		it( 'should not call onChange if new value is invalid', () => {
+			const onChange = jest.fn();
+			render(
+				<RangeControl onChange={ onChange } min={ 10 } max={ 20 } />
+			);
+
+			const numberInput = getNumberInput();
+
+			numberInput?.focus();
+			fireChangeEvent( numberInput, '25e' );
+
+			expect( onChange ).not.toHaveBeenCalled();
+		} );
+
+		it( 'should keep invalid values in number input until loss of focus', () => {
+			const onChange = jest.fn();
+			render(
+				<RangeControl onChange={ onChange } min={ -1 } max={ 1 } />
+			);
+
+			const rangeInput = getRangeInput();
+			const numberInput = getNumberInput();
+
+			numberInput?.focus();
+			fireChangeEvent( numberInput, '-1.1' );
+
+			expect( numberInput?.value ).toBe( '-1.1' );
+			expect( rangeInput?.value ).toBe( '-1' );
+
+			fireEvent.blur( numberInput as Element );
+			expect( onChange ).toHaveBeenCalledWith( -1 );
+			expect( numberInput?.value ).toBe( '-1' );
+		} );
+
+		it( 'should validate when provided a max or min of zero', () => {
+			render( <RangeControl min={ -100 } max={ 0 } /> );
+
+			const rangeInput = getRangeInput();
+			const numberInput = getNumberInput();
+
+			numberInput?.focus();
+			fireChangeEvent( numberInput, '1' );
+			fireEvent.blur( numberInput as Element );
+
+			expect( rangeInput?.value ).toBe( '0' );
+		} );
+
+		it( 'should validate when min and max are negative', () => {
+			render( <RangeControl min={ -100 } max={ -50 } /> );
+
+			const rangeInput = getRangeInput();
+			const numberInput = getNumberInput();
+
+			numberInput?.focus();
+
+			fireChangeEvent( numberInput, '-101' );
+			expect( rangeInput?.value ).toBe( '-100' );
+
+			fireChangeEvent( numberInput, '-49' );
+			expect( rangeInput?.value ).toBe( '-50' );
+
+			fireChangeEvent( numberInput, '-50' );
+			expect( rangeInput?.value ).toBe( '-50' );
+		} );
+
+		it( 'should take into account the step starting from min', () => {
+			const onChange = jest.fn();
+			render(
+				<RangeControl
+					onChange={ onChange }
+					min={ 0.1 }
+					step={ 0.125 }
+				/>
+			);
+
+			const rangeInput = getRangeInput();
+			const numberInput = getNumberInput();
+
+			numberInput?.focus();
+			fireChangeEvent( numberInput, '0.125' );
+
+			expect( onChange ).toHaveBeenCalledWith( 0.125 );
+			expect( rangeInput?.value ).toBe( '0.125' );
+
+			fireChangeEvent( numberInput, '0.225' );
+
+			expect( onChange ).toHaveBeenCalledWith( 0.225 );
+			expect( rangeInput?.value ).toBe( '0.225' );
+		} );
+	} );
+
+	describe( 'initialPosition / value', () => {
+		it( 'should render initial rendered value of 50% of min/max, if no initialPosition or value is defined', () => {
+			render( <RangeControl min={ 0 } max={ 10 } /> );
+
+			const rangeInput = getRangeInput();
+
+			expect( rangeInput?.value ).toBe( '5' );
+		} );
+
+		it( 'should render initialPosition if no value is provided', () => {
+			render( <RangeControl initialPosition={ 50 } /> );
+
+			const rangeInput = getRangeInput();
+
+			expect( rangeInput?.value ).toBe( '50' );
+		} );
+
+		it( 'should render value instead of initialPosition is provided', () => {
+			render( <RangeControl initialPosition={ 50 } value={ 10 } /> );
+
+			const rangeInput = getRangeInput();
+
+			expect( rangeInput?.value ).toBe( '10' );
+		} );
+	} );
+
+	describe( 'input field', () => {
+		it( 'should render an input field by default', () => {
+			render( <RangeControl /> );
+
+			const numberInput = getNumberInput();
+
+			expect( numberInput ).toBeInTheDocument();
+		} );
+
+		it( 'should not render an input field, if disabled', () => {
+			render( <RangeControl withInputField={ false } /> );
+
+			const numberInput = screen.queryByRole( 'spinbutton' );
+
+			expect( numberInput ).not.toBeInTheDocument();
+		} );
+
+		it( 'should render a zero value into input range and field', () => {
+			render( <RangeControl value={ 0 } /> );
+
+			const rangeInput = getRangeInput();
+			const numberInput = getNumberInput();
+
+			expect( rangeInput?.value ).toBe( '0' );
+			expect( numberInput?.value ).toBe( '0' );
+		} );
+
+		it( 'should update both field and range on change', () => {
+			render( <RangeControl /> );
+
+			const rangeInput = getRangeInput();
+			const numberInput = getNumberInput();
+
+			rangeInput?.focus();
+			fireChangeEvent( rangeInput, 13 );
+
+			expect( rangeInput?.value ).toBe( '13' );
+			expect( numberInput?.value ).toBe( '13' );
+
+			numberInput?.focus();
+			fireChangeEvent( numberInput, 7 );
+
+			expect( rangeInput?.value ).toBe( '7' );
+			expect( numberInput?.value ).toBe( '7' );
+		} );
+
+		it( 'should reset input values if next value is removed', () => {
+			render( <RangeControl /> );
+
+			const rangeInput = getRangeInput();
+			const numberInput = getNumberInput();
+
+			fireChangeEvent( numberInput, '' );
+			fireEvent.blur( numberInput as Element );
+
+			// Reset to 50. Median value of min: 0, max: 100.
+			expect( rangeInput?.value ).toBe( '50' );
+			// Input field should be blank.
+			expect( numberInput?.value ).toBe( '' );
+		} );
+	} );
+
+	describe( 'reset', () => {
+		it( 'should reset to a custom fallback value, defined by a parent component', () => {
+			const spy = jest.fn();
+			render(
+				<RangeControl
+					initialPosition={ 10 }
+					allowReset={ true }
+					onChange={ spy }
+					resetFallbackValue={ 33 }
+				/>
+			);
+
+			const resetButton = getResetButton();
+			const rangeInput = getRangeInput();
+			const numberInput = getNumberInput();
+
+			fireEvent.click( resetButton as Element );
+
+			expect( rangeInput?.value ).toBe( '33' );
+			expect( numberInput?.value ).toBe( '33' );
+			expect( spy ).toHaveBeenCalledWith( 33 );
+		} );
+
+		it( 'should reset to a 50% of min/max value, of no initialPosition or value is defined', () => {
+			render(
+				<RangeControl
+					initialPosition={ undefined }
+					min={ 0 }
+					max={ 100 }
+					allowReset={ true }
+					resetFallbackValue={ undefined }
+				/>
+			);
+
+			const resetButton = getResetButton();
+			const rangeInput = getRangeInput();
+			const numberInput = getNumberInput();
+
+			fireEvent.click( resetButton as Element );
+
+			expect( rangeInput?.value ).toBe( '50' );
+			expect( numberInput?.value ).toBe( '' );
+		} );
+	} );
+} );

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

@@ -1,4 +1,3 @@
-// @ts-nocheck
 /**
  * External dependencies
  */
@@ -14,17 +13,23 @@ import { useCallback, useEffect, useState } from '@wordpress/element';
  */
 import { Tooltip } from './styles/range-control-styles';
 
-export default function SimpleTooltip( {
-	className,
-	inputRef,
-	tooltipPosition,
-	show = false,
-	style = {},
-	value = 0,
-	renderTooltipContent = ( v ) => v,
-	zIndex = 100,
-	...restProps
-} ) {
+import type { TooltipProps } from './types';
+import type { WordPressComponentProps } from '../ui/context';
+
+export default function SimpleTooltip(
+	props: WordPressComponentProps< TooltipProps, 'span' >
+) {
+	const {
+		className,
+		inputRef,
+		tooltipPosition,
+		show = false,
+		style = {},
+		value = 0,
+		renderTooltipContent = ( v ) => v,
+		zIndex = 100,
+		...restProps
+	} = props;
 	const position = useTooltipPosition( { inputRef, tooltipPosition } );
 	const classes = classnames( 'components-simple-tooltip', className );
 	const styles = {
@@ -47,8 +52,8 @@ export default function SimpleTooltip( {
 	);
 }
 
-function useTooltipPosition( { inputRef, tooltipPosition } ) {
-	const [ position, setPosition ] = useState();
+function useTooltipPosition( { inputRef, tooltipPosition }: TooltipProps ) {
+	const [ position, setPosition ] = useState< string >();
 
 	const setTooltipPosition = useCallback( () => {
 		if ( inputRef && inputRef.current ) {

package/src/range-control/types.ts

@@ -0,0 +1,326 @@
+/**
+ * External dependencies
+ */
+import type {
+	CSSProperties,
+	FocusEventHandler,
+	MouseEventHandler,
+	MutableRefObject,
+} from 'react';
+
+/**
+ * Internal dependencies
+ */
+import type { BaseControlProps } from '../base-control/types';
+import type { IconType } from '../icon';
+
+export type NumericProps = {
+	/**
+	 * The minimum `value` allowed.
+	 *
+	 * @default 0
+	 */
+	min?: number;
+	/**
+	 * The maximum `value` allowed.
+	 *
+	 * @default 100
+	 */
+	max?: number;
+	/**
+	 * The current value of the range slider.
+	 */
+	value?: number;
+};
+
+export type RangeMark = { value: number; label?: string };
+// An expanded definition of this type is used in MarkProps to improve Storybook
+// generated docs.
+export type RangeMarks = boolean | RangeMark[];
+
+export type MarksProps = NumericProps & {
+	/**
+	 * Disables the `input`, preventing new values from being applied.
+	 *
+	 * @default false
+	 */
+	disabled?: boolean;
+	/**
+	 * Renders a visual representation of `step` ticks. Custom mark indicators
+	 * can be provided by an `Array`.
+	 *
+	 * @default false
+	 */
+	marks?: boolean | { value: number; label?: string }[];
+	/**
+	 * 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`.
+	 *
+	 * @default 1
+	 */
+	step?: number | 'any';
+};
+
+export type RangeMarkProps = {
+	isFilled?: boolean;
+	label?: string;
+	disabled?: boolean;
+	key?: string;
+	style?: CSSProperties;
+};
+
+export type ControlledRangeValue = number | '' | null;
+
+export type RangeControlProps< IconProps = unknown > = Pick<
+	BaseControlProps,
+	'hideLabelFromVision' | 'help'
+> &
+	MarksProps & {
+		/**
+		 * If this property is added, an Icon component 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
+		 */
+		afterIcon?: IconType< IconProps >;
+		/**
+		 * If this property is true, a button to reset the the slider is
+		 * rendered.
+		 *
+		 * @default false
+		 */
+		allowReset?: boolean;
+		/**
+		 * If this property is added, an Icon component 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
+		 */
+		beforeIcon?: IconType< IconProps >;
+		/**
+		 * CSS color string for the `RangeControl` wrapper.
+		 *
+		 * @default COLORS.ui.theme
+		 * @see /packages/components/src/utils/colors-values.js
+		 */
+		color?: CSSProperties[ 'color' ];
+		/**
+		 * The current input to use as a fallback if `value` is currently
+		 * `undefined`.
+		 */
+		currentInput?: number;
+		/**
+		 * An icon to be shown above the slider next to its container title.
+		 */
+		icon?: string;
+		/**
+		 * If no value exists this prop contains the slider starting position.
+		 */
+		initialPosition?: number;
+		/**
+		 * 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.
+		 *
+		 * @default true
+		 */
+		isShiftStepEnabled?: boolean;
+		/**
+		 * If this property is added, a label will be generated using label
+		 * property as the content.
+		 */
+		label?: string;
+		/**
+		 * Callback for when `RangeControl` input loses focus.
+		 *
+		 * @default () => void
+		 */
+		onBlur?: FocusEventHandler< HTMLInputElement >;
+		/**
+		 * 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`.
+		 *
+		 * @default () => void
+		 */
+		onChange?: ( value?: number ) => void;
+		/**
+		 * Callback for when `RangeControl` input gains focus.
+		 *
+		 * @default () => void
+		 */
+		onFocus?: FocusEventHandler< HTMLInputElement >;
+		/**
+		 * Callback for when mouse exits the `RangeControl`.
+		 *
+		 * @default () => void
+		 */
+		onMouseLeave?: MouseEventHandler< HTMLInputElement >;
+		/**
+		 * Callback for when mouse moves within the `RangeControl`.
+		 *
+		 * @default () => void
+		 */
+		onMouseMove?: MouseEventHandler< HTMLInputElement >;
+		/**
+		 * CSS color string to customize the rail element's background.
+		 */
+		railColor?: CSSProperties[ 'color' ];
+		/**
+		 * A way to customize the rendered UI of the value.
+		 *
+		 * @default ( value ) => value
+		 */
+		renderTooltipContent?: (
+			value?: ControlledRangeValue
+		) => string | number | null | undefined;
+		/**
+		 * The value to revert to if the Reset button is clicked (enabled by
+		 * `allowReset`)
+		 */
+		resetFallbackValue?: 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.
+		 */
+		separatorType?: 'none' | 'fullWidth' | 'topFullWidth';
+		/**
+		 * 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`.
+		 *
+		 * @default 10
+		 */
+		shiftStep?: number;
+		/**
+		 * Forcing the Tooltip UI to show or hide. This is overridden to `false`
+		 * when `step` is set to the special string value `any`.
+		 */
+		showTooltip?: boolean;
+		/**
+		 * CSS color string to customize the track element's background.
+		 */
+		trackColor?: CSSProperties[ 'color' ];
+		/**
+		 * 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?: 'stepper';
+		/**
+		 * 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`.
+		 *
+		 * @default true
+		 */
+		withInputField?: boolean;
+	};
+
+export type RailProps = MarksProps & {
+	railColor?: CSSProperties[ 'color' ];
+};
+
+export type InputRangeProps = {
+	describedBy?: string;
+	label?: string;
+	onHideTooltip?: () => void;
+	onMouseLeave?: MouseEventHandler< HTMLInputElement >;
+	onMouseMove?: MouseEventHandler< HTMLInputElement >;
+	onShowTooltip?: () => void;
+	value?: number | '';
+};
+
+export type WrapperProps = {
+	color?: CSSProperties[ 'color' ];
+	marks?: RangeMarks;
+};
+
+export type ThumbProps = {
+	isFocused?: boolean;
+	disabled?: boolean;
+};
+
+export type TooltipProps = {
+	show?: boolean;
+	position?: string;
+	inputRef?: MutableRefObject< HTMLElement | undefined >;
+	tooltipPosition?: string;
+	value?: ControlledRangeValue;
+	renderTooltipContent?: (
+		value?: ControlledRangeValue
+	) => string | number | null | undefined;
+	zIndex?: number;
+};
+
+export type TrackProps = {
+	disabled: boolean;
+	trackColor: CSSProperties[ 'color' ];
+};
+
+export type UseControlledRangeValueArgs = {
+	/**
+	 * The initial value.
+	 */
+	initial?: number;
+	/**
+	 * The maximum value.
+	 */
+	max: number;
+	/**
+	 * The minimum value.
+	 */
+	min: number;
+	/**
+	 * The current value.
+	 */
+	value: number | null;
+};
+
+export type UseDebouncedHoverInteractionArgs = {
+	/**
+	 *  A callback function invoked when the element is hidden.
+	 *
+	 * @default () => {}
+	 */
+	onHide?: () => void;
+	/**
+	 * A callback function invoked when the mouse is moved out of the element.
+	 *
+	 * @default () => {}
+	 */
+	onMouseLeave?: MouseEventHandler< HTMLInputElement >;
+	/**
+	 * A callback function invoked when the mouse is moved.
+	 *
+	 * @default () => {}
+	 */
+	onMouseMove?: MouseEventHandler< HTMLInputElement >;
+	/**
+	 * A callback function invoked when the element is shown.
+	 *
+	 * @default () => {}
+	 */
+	onShow?: () => void;
+	/**
+	 * Timeout before the element is shown or hidden.
+	 *
+	 * @default 300
+	 */
+	timeout?: number;
+};
+
+export type UseMarksArgs = NumericProps & {
+	marks: RangeMarks;
+	step: number;
+};