Unit control Utils: update JS Docs and add basic test coverage

packages/components/src/unit-control/test/utils.js

@@ -0,0 +1,63 @@
+/**
+ * Internal dependencies
+ */
+import { filterUnitsWithSettings, useCustomUnits } from '../utils';
+
+describe( 'UnitControl utils', () => {
+	describe( 'useCustomUnits', () => {
+		it( 'should return filtered css units', () => {
+			const cssUnits = [ { value: 'px' }, { value: '%' } ];
+			const units = useCustomUnits( {
+				availableUnits: [ 'em', 'px' ],
+				units: cssUnits,
+			} );
+
+			expect( units ).toEqual( [ { value: 'px' } ] );
+		} );
+
+		it( 'should add default values to available units', () => {
+			const cssUnits = [ { value: 'px' }, { value: '%' } ];
+			const units = useCustomUnits( {
+				availableUnits: [ '%', 'px' ],
+				defaultValues: { '%': 10, px: 10 },
+				units: cssUnits,
+			} );
+
+			expect( units ).toEqual( [
+				{ value: 'px', default: 10 },
+				{ value: '%', default: 10 },
+			] );
+		} );
+
+		it( 'should return `false` where availableUnits match no preferred css units', () => {
+			const cssUnits = [ { value: 'em' }, { value: 'vh' } ];
+			const units = useCustomUnits( {
+				availableUnits: [ '%', 'px' ],
+				defaultValues: { '%': 10, px: 10 },
+				units: cssUnits,
+			} );
+
+			expect( units ).toBe( false );
+		} );
+	} );
+
+	describe( 'filterUnitsWithSettings', () => {
+		it( 'should return filtered units array', () => {
+			const preferredUnits = [ '%', 'px' ];
+			const availableUnits = [ { value: 'px' }, { value: 'em' } ];
+
+			expect(
+				filterUnitsWithSettings( preferredUnits, availableUnits )
+			).toEqual( [ { value: 'px' } ] );
+		} );
+
+		it( 'should return empty array where preferred units match no available css unit', () => {
+			const preferredUnits = [ '%', 'px' ];
+			const availableUnits = [ { value: 'em' } ];
+
+			expect(
+				filterUnitsWithSettings( preferredUnits, availableUnits )
+			).toEqual( [] );
+		} );
+	} );
+} );

packages/components/src/unit-control/utils.js

@@ -249,7 +249,7 @@ export function parseA11yLabelForUnit( unit ) {
  *
  * @return {Array} Filtered units based on settings.
  */
-function filterUnitsWithSettings( settings = [], units = [] ) {
+export function filterUnitsWithSettings( settings = [], units = [] ) {
 	return units.filter( ( unit ) => {
 		return settings.includes( unit.value );
 	} );
@@ -260,12 +260,12 @@ function filterUnitsWithSettings( settings = [], units = [] ) {
  * TODO: ideally this hook shouldn't be needed
  * https://github.com/WordPress/gutenberg/pull/31822#discussion_r633280823
  *
- * @param {Object} args                An object containing units, settingPath & defaultUnits.
- * @param {Object} args.units          Collection of available units.
- * @param {string} args.availableUnits The setting path. Defaults to 'spacing.units'.
- * @param {Object} args.defaultValues  Collection of default values for defined units. Example: { px: '350', em: '15' }.
+ * @param {Object} args                                  An object containing units, settingPath & defaultUnits.
+ * @param {Array<Object>|undefined} args.units           Collection of available units.
+ * @param {Array<string>|undefined} args.availableUnits  The setting path. Defaults to 'spacing.units'.
+ * @param {Object|undefined}        args.defaultValues   Collection of default values for defined units. Example: { px: '350', em: '15' }.
  *
- * @return {Array} Filtered units based on settings.
+ * @return {Array|boolean} Filtered units based on settings.
  */
 export const useCustomUnits = ( { units, availableUnits, defaultValues } ) => {
 	units = units || ALL_CSS_UNITS;