@wordpress/components 19.10.0 → 19.13.0

package/src/checkbox-control/README.md

@@ -77,37 +77,39 @@ const MyCheckboxControl = () => {
 The set of props accepted by the component will be specified below.
 Props not included in this set will be applied to the input element.
 
-#### label
+#### `label`: `string`
 
 A label for the input field, that appears at the side of the checkbox.
 The prop will be rendered as content a label element.
 If no prop is passed an empty label is rendered.
 
--   Type: `String`
 -   Required: No
 
-#### help
+#### `help`: `string|WPElement`
 
 If this property is added, a help text will be generated using help property as the content.
 
--   Type: `String|WPElement`
 -   Required: No
 
-#### checked
+#### `checked`: `boolean`
 
 If checked is true the checkbox will be checked. If checked is false the checkbox will be unchecked.
 If no value is passed the checkbox will be unchecked.
 
--   Type: `Boolean`
 -   Required: No
 
-#### onChange
+#### `onChange`: `function`
 
 A function that receives the checked state (boolean) as input.
 
--   Type: `function`
 -   Required: Yes
 
+#### `indeterminate`: `boolean`
+
+If indeterminate is true the state of the checkbox will be indeterminate.
+
+-   Required: No
+
 ## Related components
 
 -   To select one option from a set, and you want to show all the available options at once, use the `RadioControl` component.

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

@@ -2,6 +2,7 @@
  * External dependencies
  */
 import classnames from 'classnames';
+import type { ChangeEvent } from 'react';
 
 /**
  * WordPress dependencies
@@ -15,17 +16,48 @@ import { Icon, check, reset } from '@wordpress/icons';
  * Internal dependencies
  */
 import BaseControl from '../base-control';
+import type { CheckboxControlProps } from './types';
+import type { WordPressComponentProps } from '../ui/context';
+
+/**
+ * Checkboxes allow the user to select one or more items from a set.
+ *
+ * ```jsx
+ * import { CheckboxControl } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
+ *
+ * const MyCheckboxControl = () => {
+ *   const [ isChecked, setChecked ] = useState( true );
+ *   return (
+ *     <CheckboxControl
+ *       label="Is author"
+ *       help="Is the user a author or not?"
+ *       checked={ isChecked }
+ *       onChange={ setChecked }
+ *     />
+ *   );
+ * };
+ * ```
+ */
+export function CheckboxControl(
+	// ref is omitted until we have `WordPressComponentPropsWithoutRef` or add
+	// ref forwarding to CheckboxControl.
+	props: Omit<
+		WordPressComponentProps< CheckboxControlProps, 'input', false >,
+		'ref'
+	>
+) {
+	const {
+		label,
+		className,
+		heading,
+		checked,
+		indeterminate,
+		help,
+		onChange,
+		...additionalProps
+	} = props;
 
-export default function CheckboxControl( {
-	label,
-	className,
-	heading,
-	checked,
-	indeterminate,
-	help,
-	onChange,
-	...props
-} ) {
 	if ( heading ) {
 		deprecated( '`heading` prop in `CheckboxControl`', {
 			alternative: 'a separate element to implement a heading',
@@ -34,13 +66,12 @@ export default function CheckboxControl( {
 	}
 
 	const [ showCheckedIcon, setShowCheckedIcon ] = useState( false );
-	const [ showIndeterminateIcon, setShowIndeterminateIcon ] = useState(
-		false
-	);
+	const [ showIndeterminateIcon, setShowIndeterminateIcon ] =
+		useState( false );
 
-	// Run the following callback everytime the `ref` (and the additional
+	// Run the following callback every time the `ref` (and the additional
 	// dependencies) change.
-	const ref = useRefEffect(
+	const ref = useRefEffect< HTMLInputElement >(
 		( node ) => {
 			if ( ! node ) {
 				return;
@@ -56,7 +87,8 @@ export default function CheckboxControl( {
 	);
 	const instanceId = useInstanceId( CheckboxControl );
 	const id = `inspector-checkbox-control-${ instanceId }`;
-	const onChangeValue = ( event ) => onChange( event.target.checked );
+	const onChangeValue = ( event: ChangeEvent< HTMLInputElement > ) =>
+		onChange( event.target.checked );
 
 	return (
 		<BaseControl
@@ -75,7 +107,7 @@ export default function CheckboxControl( {
 					onChange={ onChangeValue }
 					checked={ checked }
 					aria-describedby={ !! help ? id + '__help' : undefined }
-					{ ...props }
+					{ ...additionalProps }
 				/>
 				{ showIndeterminateIcon ? (
 					<Icon
@@ -101,3 +133,5 @@ export default function CheckboxControl( {
 		</BaseControl>
 	);
 }
+
+export default CheckboxControl;

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

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import { text } from '@storybook/addon-knobs';
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
 
 /**
  * WordPress dependencies
@@ -11,42 +11,59 @@ import { useState } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import CheckboxControl from '../';
+import CheckboxControl from '..';
 
-export default {
-	title: 'Components/CheckboxControl',
+const meta: ComponentMeta< typeof CheckboxControl > = {
 	component: CheckboxControl,
+	title: 'Components/CheckboxControl',
+	argTypes: {
+		onChange: {
+			action: 'onChange',
+		},
+		checked: {
+			control: { type: null },
+		},
+		help: { control: { type: 'text' } },
+	},
 	parameters: {
-		knobs: { disable: false },
+		controls: {
+			expanded: true,
+			exclude: [ 'heading' ],
+		},
+		docs: { source: { state: 'open' } },
 	},
 };
+export default meta;
 
-const CheckboxControlWithState = ( { checked, ...props } ) => {
-	const [ isChecked, setChecked ] = useState( checked );
+const DefaultTemplate: ComponentStory< typeof CheckboxControl > = ( {
+	onChange,
+	...args
+} ) => {
+	const [ isChecked, setChecked ] = useState( true );
 
 	return (
 		<CheckboxControl
-			{ ...props }
+			{ ...args }
 			checked={ isChecked }
-			onChange={ setChecked }
+			onChange={ ( v ) => {
+				setChecked( v );
+				onChange( v );
+			} }
 		/>
 	);
 };
 
-export const _default = () => {
-	const label = text( 'Label', 'Is author' );
-
-	return <CheckboxControlWithState label={ label } checked />;
+export const Default: ComponentStory< typeof CheckboxControl > =
+	DefaultTemplate.bind( {} );
+Default.args = {
+	label: 'Is author',
+	help: 'Is the user an author or not?',
 };
 
-export const all = () => {
-	const label = text( 'Label', 'Is author' );
-	const help = text( 'Help', 'Is the user an author or not?' );
-
-	return <CheckboxControlWithState label={ label } help={ help } checked />;
-};
-
-export const Indeterminate = () => {
+export const Indeterminate: ComponentStory< typeof CheckboxControl > = ( {
+	onChange,
+	...args
+} ) => {
 	const [ fruits, setFruits ] = useState( { apple: false, orange: false } );
 
 	const isAllChecked = Object.values( fruits ).every( Boolean );
@@ -56,15 +73,16 @@ export const Indeterminate = () => {
 	return (
 		<>
 			<CheckboxControl
-				label="Select All"
+				{ ...args }
 				checked={ isAllChecked }
 				indeterminate={ isIndeterminate }
-				onChange={ ( newValue ) =>
+				onChange={ ( v ) => {
 					setFruits( {
-						apple: newValue,
-						orange: newValue,
-					} )
-				}
+						apple: v,
+						orange: v,
+					} );
+					onChange( v );
+				} }
 			/>
 			<CheckboxControl
 				label="Apple"
@@ -89,3 +107,6 @@ export const Indeterminate = () => {
 		</>
 	);
 };
+Indeterminate.args = {
+	label: 'Select all',
+};

package/src/checkbox-control/test/__snapshots__/index.tsx.snap

@@ -0,0 +1,42 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`CheckboxControl Basic rendering should render the indeterminate icon when in the indeterminate state 1`] = `
+Snapshot Diff:
+- First value
++ Second value
+
+@@ -8,17 +8,31 @@
+        <span
+          class="components-checkbox-control__input-container"
+        >
+          <input
+            class="components-checkbox-control__input"
+-           id="inspector-checkbox-control-5"
++           id="inspector-checkbox-control-6"
+            type="checkbox"
+            value="1"
++         />
++         <svg
++           aria-hidden="true"
++           class="components-checkbox-control__indeterminate"
++           focusable="false"
++           height="24"
++           role="presentation"
++           viewBox="0 0 24 24"
++           width="24"
++           xmlns="http://www.w3.org/2000/svg"
++         >
++           <path
++             d="M7 11.5h10V13H7z"
+            />
++         </svg>
+        </span>
+        <label
+          class="components-checkbox-control__label"
+-         for="inspector-checkbox-control-5"
++         for="inspector-checkbox-control-6"
+        />
+      </div>
+    </div>
+  </div>
+`;

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

@@ -0,0 +1,110 @@
+/**
+ * External dependencies
+ */
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import BaseCheckboxControl from '..';
+import type { CheckboxControlProps } from '../types';
+
+const noop = () => {};
+
+const getInput = () => screen.getByRole( 'checkbox' ) as HTMLInputElement;
+
+const CheckboxControl = ( props: Omit< CheckboxControlProps, 'onChange' > ) => {
+	return <BaseCheckboxControl onChange={ noop } { ...props } />;
+};
+
+const ControlledCheckboxControl = ( { onChange }: CheckboxControlProps ) => {
+	const [ isChecked, setChecked ] = useState( false );
+	return (
+		<BaseCheckboxControl
+			checked={ isChecked }
+			onChange={ ( value ) => {
+				setChecked( value );
+				onChange( value );
+			} }
+		/>
+	);
+};
+
+describe( 'CheckboxControl', () => {
+	describe( 'Basic rendering', () => {
+		it( 'should render', () => {
+			render( <CheckboxControl /> );
+			expect( getInput() ).not.toBeNull();
+		} );
+
+		it( 'should render an unchecked `checkbox` by default', () => {
+			render( <CheckboxControl /> );
+			expect( getInput() ).toHaveProperty( 'checked', false );
+		} );
+
+		it( 'should render an checked `checkbox` when `checked={ true }`', () => {
+			render( <CheckboxControl checked /> );
+			expect( getInput() ).toHaveProperty( 'checked', true );
+		} );
+
+		it( 'should render label', () => {
+			render( <CheckboxControl label="Hello" /> );
+
+			const label = screen.getByText( 'Hello' );
+			expect( label ).toBeInTheDocument();
+		} );
+
+		it( 'should render a checkbox in an indeterminate state', () => {
+			render( <CheckboxControl indeterminate /> );
+			expect( getInput() ).toHaveProperty( 'indeterminate', true );
+		} );
+
+		it( 'should render the indeterminate icon when in the indeterminate state', () => {
+			const { container: containerDefault } = render(
+				<CheckboxControl />
+			);
+
+			const { container: containerIndeterminate } = render(
+				<CheckboxControl indeterminate />
+			);
+
+			// Expect the diff snapshot to be mostly about the indeterminate icon
+			expect( containerDefault ).toMatchDiffSnapshot(
+				containerIndeterminate
+			);
+		} );
+	} );
+
+	describe( 'Value', () => {
+		it( 'should flip the checked property when clicked', async () => {
+			const user = userEvent.setup( {
+				advanceTimers: jest.advanceTimersByTime,
+			} );
+
+			let state = false;
+			const setState = jest.fn(
+				( nextState: boolean ) => ( state = nextState )
+			);
+
+			render( <ControlledCheckboxControl onChange={ setState } /> );
+
+			const input = getInput();
+
+			await user.click( input );
+			expect( input ).toHaveProperty( 'checked', true );
+			expect( state ).toBe( true );
+
+			await user.click( input );
+			expect( input ).toHaveProperty( 'checked', false );
+			expect( state ).toBe( false );
+
+			expect( setState ).toHaveBeenCalledTimes( 2 );
+		} );
+	} );
+} );

package/src/checkbox-control/types.ts

@@ -0,0 +1,36 @@
+/**
+ * External dependencies
+ */
+import type { ReactNode } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import type { BaseControlProps } from '../base-control/types';
+
+export type CheckboxControlProps = Pick< BaseControlProps, 'help' > & {
+	/**
+	 * A function that receives the checked state (boolean) as input.
+	 */
+	onChange: ( value: boolean ) => void;
+	/**
+	 * A label for the input field, that appears at the side of the checkbox.
+	 * The prop will be rendered as content a label element. If no prop is
+	 * passed an empty label is rendered.
+	 */
+	label?: string;
+	/**
+	 * If checked is true the checkbox will be checked. If checked is false the
+	 * checkbox will be unchecked. If no value is passed the checkbox will be
+	 * unchecked.
+	 */
+	checked?: boolean;
+	/**
+	 * If indeterminate is true the state of the checkbox will be indeterminate.
+	 */
+	indeterminate?: boolean;
+	/**
+	 * @deprecated
+	 */
+	heading?: ReactNode;
+};

package/src/circular-option-picker/style.scss

@@ -99,6 +99,7 @@ $color-palette-circle-spacing: 12px;
 		box-shadow: inset 0 0 0 1px rgba(0, 0, 0, 0.2);
 		// Show a thin circular outline in Windows high contrast mode, otherwise the button is invisible.
 		border: 1px solid transparent;
+		box-sizing: inherit;
 	}
 
 	&:focus {

package/src/color-palette/index.js

@@ -6,7 +6,6 @@ import { map } from 'lodash';
 import { colord, extend } from 'colord';
 import namesPlugin from 'colord/plugins/names';
 import a11yPlugin from 'colord/plugins/a11y';
-import classnames from 'classnames';
 
 /**
  * WordPress dependencies
@@ -116,18 +115,18 @@ function MultiplePalettes( {
 export function CustomColorPickerDropdown( { isRenderedInSidebar, ...props } ) {
 	return (
 		<Dropdown
-			contentClassName={ classnames(
-				'components-color-palette__custom-color-dropdown-content',
-				{
-					'is-rendered-in-sidebar': isRenderedInSidebar,
-				}
-			) }
+			contentClassName="components-color-palette__custom-color-dropdown-content"
+			popoverProps={
+				isRenderedInSidebar
+					? { placement: 'left-start', offset: 20 }
+					: undefined
+			}
 			{ ...props }
 		/>
 	);
 }
 
-const extractColorNameFromCurrentValue = (
+export const extractColorNameFromCurrentValue = (
 	currentValue,
 	colors = [],
 	showMultiplePalettes = false
@@ -136,13 +135,20 @@ const extractColorNameFromCurrentValue = (
 		return '';
 	}
 
+	const currentValueIsCssVariable = /^var\(/.test( currentValue );
+	const normalizedCurrentValue = currentValueIsCssVariable
+		? currentValue
+		: colord( currentValue ).toHex();
+
 	// Normalize format of `colors` to simplify the following loop
 	const colorPalettes = showMultiplePalettes ? colors : [ { colors } ];
 	for ( const { colors: paletteColors } of colorPalettes ) {
 		for ( const { name: colorName, color: colorValue } of paletteColors ) {
-			if (
-				colord( currentValue ).toHex() === colord( colorValue ).toHex()
-			) {
+			const normalizedColorValue = currentValueIsCssVariable
+				? colorValue
+				: colord( colorValue ).toHex();
+
+			if ( normalizedCurrentValue === normalizedColorValue ) {
 				return colorName;
 			}
 		}
@@ -176,11 +182,6 @@ export default function ColorPalette( {
 		/>
 	);
 
-	let dropdownPosition;
-	if ( __experimentalIsRenderedInSidebar ) {
-		dropdownPosition = 'bottom left';
-	}
-
 	const colordColor = colord( value );
 
 	const valueWithoutLeadingHash = value?.startsWith( '#' )
@@ -211,7 +212,6 @@ export default function ColorPalette( {
 		<VStack spacing={ 3 } className={ className }>
 			{ ! disableCustomColors && (
 				<CustomColorPickerDropdown
-					position={ dropdownPosition }
 					isRenderedInSidebar={ __experimentalIsRenderedInSidebar }
 					renderContent={ renderCustomColorPicker }
 					renderToggle={ ( { isOpen, onToggle } ) => (

package/src/color-palette/index.native.js

@@ -92,6 +92,9 @@ function ColorPalette( {
 				scrollViewRef.current.scrollTo( { x: 0, y: 0 } );
 			}
 		}
+		// Temporarily disabling exhuastive-deps until the component can be refactored and updated safely.
+		// Please see https://github.com/WordPress/gutenberg/pull/41253 for discussion and details.
+		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, [ currentSegment ] );
 
 	function isSelectedCustom() {

package/src/color-palette/stories/index.js

@@ -43,7 +43,10 @@ const meta = {
 export default meta;
 
 const Template = ( args ) => {
-	const [ color, setColor ] = useState( '#f00' );
+	const firstColor =
+		args.colors[ 0 ].color || args.colors[ 0 ].colors[ 0 ].color;
+	const [ color, setColor ] = useState( firstColor );
+
 	return (
 		<SlotFillProvider>
 			<ColorPalette { ...args } value={ color } onChange={ setColor } />
@@ -88,3 +91,24 @@ MultipleOrigins.args = {
 		},
 	],
 };
+
+export const CSSVariables = ( args ) => {
+	return (
+		<div
+			style={ {
+				'--red': '#f00',
+				'--yellow': '#ff0',
+				'--blue': '#00f',
+			} }
+		>
+			<Template { ...args } />
+		</div>
+	);
+};
+CSSVariables.args = {
+	colors: [
+		{ name: 'Red', color: 'var(--red)' },
+		{ name: 'Yellow', color: 'var(--yellow)' },
+		{ name: 'Blue', color: 'var(--blue)' },
+	],
+};

package/src/color-palette/style.scss

@@ -30,31 +30,16 @@
 	overflow: visible;
 	box-shadow: 0 4px 4px rgba(0, 0, 0, 0.05);
 	border: none;
+	outline: none;
 	border-radius: $radius-block-ui;
-	max-height: fit-content !important;
-	& > div {
-		padding: 0;
-	}
+	padding: 0;
+
 	.react-colorful__saturation {
 		border-top-right-radius: $radius-block-ui;
 		border-top-left-radius: $radius-block-ui;
 	}
 }
 
-@include break-medium() {
-	.components-dropdown__content.components-color-palette__custom-color-dropdown-content.is-rendered-in-sidebar {
-		.components-popover__content.components-popover__content {
-			margin-right: #{ math.div($sidebar-width, 2) + $grid-unit-20 };
-		}
-		&.is-from-top .components-popover__content {
-			margin-top: #{ -($grid-unit-60 + $grid-unit-15) };
-		}
-		&.is-from-bottom .components-popover__content {
-			margin-bottom: #{ -($grid-unit-60 + $grid-unit-15) };
-		}
-	}
-}
-
 .components-color-palette__custom-color-name {
 	text-align: left;
 }

package/src/color-palette/test/utils.ts

@@ -0,0 +1,24 @@
+/**
+ * Internal dependencies
+ */
+import { extractColorNameFromCurrentValue } from '../';
+
+describe( 'ColorPalette: Utils', () => {
+	describe( 'extractColorNameFromCurrentValue', () => {
+		test( 'should support hex values', () => {
+			const result = extractColorNameFromCurrentValue( '#00f', [
+				{ name: 'Red', color: '#f00' },
+				{ name: 'Blue', color: '#00f' },
+			] );
+			expect( result ).toBe( 'Blue' );
+		} );
+
+		test( 'should support CSS variables', () => {
+			const result = extractColorNameFromCurrentValue( 'var(--blue)', [
+				{ name: 'Red', color: 'var(--red)' },
+				{ name: 'Blue', color: 'var(--blue)' },
+			] );
+			expect( result ).toBe( 'Blue' );
+		} );
+	} );
+} );