Add types to style mixins

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": "7.0.2",
 		"@types/webpack": "4.41.16",
 		"@types/webpack-sources": "0.1.7",

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} [initial] The initial state.
+ * @property {T} [fallback] The state to use when no state is defined.
+ */
+
+/** @type {Options<any>} */
 const defaultOptions = {
 	initial: undefined,
 	/**
@@ -33,10 +41,9 @@ 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] Additional options for the hook.
  *
  * @return {[*, Function]} The controlled value and the value setter.
  */
@@ -60,7 +67,10 @@ function useControlledState( currentState, options = defaultOptions ) {
 		fallback
 	);
 
-	const setState = ( nextState ) => {
+	const setState = (
+		/** @type {any} */
+		nextState
+	) => {
 		if ( ! hasCurrentState ) {
 			setInternalState( nextState );
 		}

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

@@ -29,7 +29,10 @@ function useJumpStep( {
 	const [ isShiftKey, setIsShiftKey ] = useState( false );
 
 	useEffect( () => {
-		const handleShiftKeyToggle = ( event ) => {
+		const handleShiftKeyToggle = (
+			/** @type {KeyboardEvent} */
+			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 The effect to run.
+ * @param {import('react').DependencyList} [deps] The dependencies of the effect.
  */
 function useUpdateEffect( effect, deps ) {
 	const mounted = useRef( false );

packages/components/src/utils/math.js

@@ -19,24 +19,23 @@ export function getNumber( value ) {
 /**
  * Safely adds 2 values.
  *
- * @param {number|string} args Values to add together.
+ * @param {(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.map( getNumber ).reduce( ( sum, arg ) => sum + arg, 0 );
 }
 
 /**
  * Safely subtracts 2 values.
  *
- * @param {number|string} args Values to subtract together.
+ * @param {(number|string)[]} args Values to subtract together.
  *
  * @return {number} The difference of the 2 values.
  */
 export function subtract( ...args ) {
-	return args.reduce( ( diff, arg, index ) => {
-		const value = getNumber( arg );
+	return args.map( getNumber ).reduce( ( diff, value, index ) => {
 		return index === 0 ? value : diff - value;
 	} );
 }
@@ -56,10 +55,10 @@ function getPrecision( value ) {
 /**
  * Clamps a value based on a min/max range with rounding
  *
- * @param {number} value The value.
- * @param {number} min The minimum range.
- * @param {number} max The maximum range.
- * @param {number} step A multiplier for the value.
+ * @param {number} [value=0] The value.
+ * @param {number} [min=Infinity] The minimum range.
+ * @param {number} [max=Infinity] The maximum range.
+ * @param {number} [step=1] A multiplier for the value.
  *
  * @return {number} The rounded and clamped value.
  */
@@ -84,11 +83,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<roundClamp>} args Arguments for roundClamp().
  *
  * @return {string} The rounded and clamped value.
  */

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 {Record<string, string>} ltrStyles
  *
- * @return {Object} Converted ltr -> rtl styles
+ * @return {Record<string, string>} Converted ltr -> rtl styles
  */
 export const convertLTRToRTL = ( ltrStyles = {} ) => {
 	return mapKeys( ltrStyles, ( _value, key ) => getConvertedKey( key ) );
@@ -76,10 +76,10 @@ 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 {Record<string, string>} [ltrStyles={}] Ltr styles. Converts and renders from ltr -> rtl styles, if applicable.
+ * @param {Record<string, string>} [rtlStyles] Rtl styles. Renders if provided.
  *
- * @return {Function} A function to output CSS styles for Emotion's renderer
+ * @return {() => ReturnType<css>} A function to output CSS styles for Emotion's renderer
  */
 export function rtl( ltrStyles = {}, rtlStyles ) {
 	return () => {

packages/components/tsconfig.json

@@ -5,5 +5,5 @@
 		"declarationDir": "build-types"
 	},
 	"references": [ { "path": "../primitives" } ],
-	"include": [ "src/dashicon/*", "src/tip/*" ]
+	"include": [ "src/dashicon/*", "src/tip/*", "src/utils/**/*" ]
 }