@wordpress/components 18.0.0 → 19.0.3

package/src/toggle-group-control/stories/index.js

@@ -13,25 +13,29 @@ import { useState } from '@wordpress/element';
  */
 import { ToggleGroupControl, ToggleGroupControlOption } from '../index';
 import { View } from '../../view';
+import Button from '../../button';
 
 export default {
 	component: ToggleGroupControl,
 	title: 'Components/ToggleGroupControl',
+	parameters: {
+		knobs: { disabled: false },
+	},
 };
 
-const aligns = [ 'Left', 'Center', 'Right', 'Justify' ];
 const KNOBS_GROUPS = {
 	ToggleGroupControl: 'ToggleGroupControl',
 	ToggleGroupControlOption: 'ToggleGroupControlOption',
 };
 
-export const _default = () => {
-	const [ alignState, setAlignState ] = useState( aligns[ 0 ] );
+const _default = ( { options } ) => {
+	const [ value, setValue ] = useState( options[ 0 ].value );
 	const label = text(
 		`${ KNOBS_GROUPS.ToggleGroupControl }: label`,
 		'Toggle Group Control',
 		KNOBS_GROUPS.ToggleGroupControl
 	);
+
 	const hideLabelFromVision = boolean(
 		`${ KNOBS_GROUPS.ToggleGroupControl }: hideLabelFromVision`,
 		false,
@@ -53,13 +57,18 @@ export const _default = () => {
 		KNOBS_GROUPS.ToggleGroupControl
 	);
 
-	const alignOptions = aligns.map( ( key, index ) => (
+	const controlOptions = options.map( ( opt, index ) => (
 		<ToggleGroupControlOption
-			key={ key }
-			value={ key }
+			key={ opt.value }
+			value={ opt.value }
 			label={ text(
 				`${ KNOBS_GROUPS.ToggleGroupControlOption }: label`,
-				key,
+				opt.label,
+				`${ KNOBS_GROUPS.ToggleGroupControlOption }-${ index + 1 }`
+			) }
+			aria-label={ text(
+				`${ KNOBS_GROUPS.ToggleGroupControlOption }: aria-label`,
+				opt[ 'aria-label' ],
 				`${ KNOBS_GROUPS.ToggleGroupControlOption }-${ index + 1 }`
 			) }
 		/>
@@ -68,16 +77,66 @@ export const _default = () => {
 	return (
 		<View>
 			<ToggleGroupControl
-				onChange={ setAlignState }
-				value={ alignState }
+				onChange={ setValue }
+				value={ value }
 				label={ label }
 				hideLabelFromVision={ hideLabelFromVision }
 				help={ help }
 				isBlock={ isBlock }
 				isAdaptiveWidth={ isAdaptiveWidth }
+			>
+				{ controlOptions }
+			</ToggleGroupControl>
+		</View>
+	);
+};
+
+export const Default = _default.bind( {} );
+Default.args = {
+	options: [
+		{ value: 'left', label: 'Left' },
+		{ value: 'center', label: 'Center' },
+		{ value: 'right', label: 'Right' },
+		{ value: 'justify', label: 'Justify' },
+	],
+};
+
+export const WithAriaLabel = _default.bind( {} );
+WithAriaLabel.args = {
+	...Default.args,
+	options: [
+		{ value: 'asc', label: 'A→Z', 'aria-label': 'Ascending' },
+		{ value: 'desc', label: 'Z→A', 'aria-label': 'Descending' },
+	],
+};
+
+export const WithReset = () => {
+	const [ alignState, setAlignState ] = useState();
+	const aligns = [ 'Left', 'Center', 'Right' ];
+	const alignOptions = aligns.map( ( key, index ) => (
+		<ToggleGroupControlOption
+			key={ key }
+			value={ key }
+			label={ text(
+				`${ KNOBS_GROUPS.ToggleGroupControlOption }: label`,
+				key,
+				`${ KNOBS_GROUPS.ToggleGroupControlOption }-${ index + 1 }`
+			) }
+		/>
+	) );
+	return (
+		<View>
+			<ToggleGroupControl
+				onChange={ setAlignState }
+				value={ alignState }
+				label={ 'Toggle Group Control' }
+				hideLabelFromVision
 			>
 				{ alignOptions }
 			</ToggleGroupControl>
+			<Button onClick={ () => setAlignState( undefined ) } isTertiary>
+				Reset
+			</Button>
 		</View>
 	);
 };

package/src/toggle-group-control/test/__snapshots__/index.js.snap

@@ -49,25 +49,6 @@ exports[`ToggleGroupControl should render correctly 1`] = `
 }
 
 .emotion-6 {
-  background: #1e1e1e;
-  border-radius: 2px;
-  box-shadow: transparent;
-  left: 0;
-  position: absolute;
-  top: 2px;
-  bottom: 2px;
-  -webkit-transition: -webkit-transform 160ms ease;
-  transition: transform 160ms ease;
-  z-index: 1;
-}
-
-@media ( prefers-reduced-motion: reduce ) {
-  .emotion-6 {
-    transition-duration: 0ms;
-  }
-}
-
-.emotion-8 {
   display: -webkit-inline-box;
   display: -webkit-inline-flex;
   display: -ms-inline-flexbox;
@@ -80,7 +61,7 @@ exports[`ToggleGroupControl should render correctly 1`] = `
   flex: 1;
 }
 
-.emotion-10 {
+.emotion-8 {
   -webkit-align-items: center;
   -webkit-box-align: center;
   -ms-flex-align: center;
@@ -119,20 +100,20 @@ exports[`ToggleGroupControl should render correctly 1`] = `
 }
 
 @media ( prefers-reduced-motion: reduce ) {
-  .emotion-10 {
+  .emotion-8 {
     transition-duration: 0ms;
   }
 }
 
-.emotion-10::-moz-focus-inner {
+.emotion-8::-moz-focus-inner {
   border: 0;
 }
 
-.emotion-10:active {
+.emotion-8:active {
   background: #fff;
 }
 
-.emotion-11 {
+.emotion-9 {
   font-size: 13px;
   line-height: 1;
   position: absolute;
@@ -144,7 +125,7 @@ exports[`ToggleGroupControl should render correctly 1`] = `
   transform: translate( -50%, -50% );
 }
 
-.emotion-13 {
+.emotion-11 {
   font-size: 13px;
   font-weight: bold;
   height: 0;
@@ -152,24 +133,6 @@ exports[`ToggleGroupControl should render correctly 1`] = `
   visibility: hidden;
 }
 
-.emotion-15 {
-  background: rgba(0, 0, 0, 0.1);
-  height: calc( 100% - 4px - 4px );
-  position: absolute;
-  right: 0;
-  top: 4px;
-  -webkit-transition: background 200ms linear;
-  transition: background 200ms linear;
-  width: 1px;
-  background: transparent;
-}
-
-@media ( prefers-reduced-motion: reduce ) {
-  .emotion-15 {
-    transition-duration: 0ms;
-  }
-}
-
 <div
   class="components-base-control emotion-0 emotion-1"
 >
@@ -200,17 +163,12 @@ exports[`ToggleGroupControl should render correctly 1`] = `
       />
       <div
         class="emotion-6 emotion-7"
-        role="presentation"
-        style="transform: translateX(0px); transition: none; width: 0px;"
-      />
-      <div
-        class="emotion-8 emotion-9"
         data-active="false"
       >
         <button
           aria-checked="false"
           aria-label="R"
-          class="emotion-10 components-toggle-group-control-option"
+          class="emotion-8 components-toggle-group-control-option"
           data-value="rigas"
           data-wp-c16t="true"
           data-wp-component="ToggleGroupControlOption"
@@ -219,30 +177,26 @@ exports[`ToggleGroupControl should render correctly 1`] = `
           tabindex="0"
         >
           <div
-            class="emotion-11 emotion-12"
+            class="emotion-9 emotion-10"
           >
             R
           </div>
           <div
             aria-hidden="true"
-            class="emotion-13 emotion-14"
+            class="emotion-11 emotion-12"
           >
             R
           </div>
         </button>
-        <div
-          aria-hidden="true"
-          class="emotion-15 emotion-16"
-        />
       </div>
       <div
-        class="emotion-8 emotion-9"
+        class="emotion-6 emotion-7"
         data-active="false"
       >
         <button
           aria-checked="false"
           aria-label="J"
-          class="emotion-10 components-toggle-group-control-option"
+          class="emotion-8 components-toggle-group-control-option"
           data-value="jack"
           data-wp-c16t="true"
           data-wp-component="ToggleGroupControlOption"
@@ -251,21 +205,17 @@ exports[`ToggleGroupControl should render correctly 1`] = `
           tabindex="-1"
         >
           <div
-            class="emotion-11 emotion-12"
+            class="emotion-9 emotion-10"
           >
             J
           </div>
           <div
             aria-hidden="true"
-            class="emotion-13 emotion-14"
+            class="emotion-11 emotion-12"
           >
             J
           </div>
         </button>
-        <div
-          aria-hidden="true"
-          class="emotion-15 emotion-16"
-        />
       </div>
     </div>
   </div>

package/src/toggle-group-control/test/index.js

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import { render, fireEvent } from '@testing-library/react';
+import { render, fireEvent, screen } from '@testing-library/react';
 
 /**
  * Internal dependencies
@@ -25,7 +25,7 @@ describe( 'ToggleGroupControl', () => {
 	} );
 	it( 'should call onChange with proper value', () => {
 		const mockOnChange = jest.fn();
-		const { getByLabelText } = render(
+		render(
 			<ToggleGroupControl
 				value="jack"
 				onChange={ mockOnChange }
@@ -34,8 +34,8 @@ describe( 'ToggleGroupControl', () => {
 				{ options }
 			</ToggleGroupControl>
 		);
-		const firstButton = getByLabelText( 'R' );
-		fireEvent.click( firstButton );
+		const firstRadio = screen.getByRole( 'radio', { name: 'R' } );
+		fireEvent.click( firstRadio );
 		expect( mockOnChange ).toHaveBeenCalledWith( 'rigas' );
 	} );
 } );

package/src/toggle-group-control/{README.md → toggle-group-control/README.md}

@@ -1,10 +1,12 @@
-# ToggleGroupControl
+# `ToggleGroupControl`
 
 <div class="callout callout-alert">
 This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
 </div>
 
-`ToggleGroupControl` is a form component that lets users choose options represented in horizontal segments. To render options for this control use `ToggleGroupControlOption` component.
+`ToggleGroupControl` is a form component that lets users choose options represented in horizontal segments. To render options for this control use [`ToggleGroupControlOption`](/packages/components/src/toggle-group-control/toggle-group-control-option/README.md) component.
+
+Only use this control when you know for sure the labels of items inside won't wrap. For items with longer labels, you can consider a [`SelectControl`](/packages/components/src/select-control/README.md) or a [`CustomSelectControl`](/packages/components/src/custom-select-control/README.md) component instead.
 
 ## Usage
 
@@ -26,53 +28,49 @@ function Example() {
 
 ## Props
 
-### `label`
+### `help`: `ReactNode`
 
--   Type: `string`
+If this property is added, a help text will be generated using help property as the content.
 
-Label for the form element.
+-   Required: No
+
+### `hideLabelFromVision`: `boolean`
 
-### `hideLabelFromVision`
+If true, the label will only be visible to screen readers.
 
--   Type: `boolean`
 -   Required: No
 -   Default: `false`
 
-If true, the label will only be visible to screen readers.
+### `isAdaptiveWidth`: `boolean`
 
-### `isAdaptiveWidth`
+Determines if segments should be rendered with equal widths.
 
--   Type: `boolean`
 -   Required: No
 -   Default: `false`
 
-Determines if segments should be rendered with equal widths.
+### `isBlock`: `boolean`
 
-### `isBlock`
+Renders `ToggleGroupControl` as a (CSS) block element.
 
--   Type: `boolean`
 -   Required: No
 -   Default: `false`
 
-Renders `ToggleGroupControl` as a (CSS) block element.
+### `label`: `string`
 
-### `onChange`
+Label for the form element.
 
--   Type: `boolean`
--   Required: No
--   Default: `false`
+-   Required: Yes
+
+### `onChange`: `( value?: string | number ) => void`
 
 Callback when a segment is selected.
 
-### `value`
+-   Required: No
+-   Default: `() => {}`
 
--   Type: `string | number`
 
-The value of the `ToggleGroupControl`.
+### `value`: `string | number`
 
-### `help`
+The value of the `ToggleGroupControl`.
 
--   Type: `ReactNode`
 -   Required: No
-
-If this property is added, a help text will be generated using help property as the content.

package/src/toggle-group-control/{component.tsx → toggle-group-control/component.tsx}

@@ -2,6 +2,8 @@
  * External dependencies
  */
 // eslint-disable-next-line no-restricted-imports
+import type { Ref } from 'react';
+// eslint-disable-next-line no-restricted-imports
 import { RadioGroup, useRadioState } from 'reakit';
 import useResizeAware from 'react-resize-aware';
 
@@ -19,20 +21,20 @@ import {
 	contextConnect,
 	useContextSystem,
 	WordPressComponentProps,
-} from '../ui/context';
-import { useUpdateEffect, useCx } from '../utils/hooks';
-import { View } from '../view';
-import BaseControl from '../base-control';
+} from '../../ui/context';
+import { useUpdateEffect, useCx } from '../../utils/hooks';
+import { View } from '../../view';
+import BaseControl from '../../base-control';
 import ToggleGroupControlBackdrop from './toggle-group-control-backdrop';
-import type { ToggleGroupControlProps } from './types';
-import ToggleGroupControlContext from './toggle-group-control-context';
+import type { ToggleGroupControlProps } from '../types';
+import ToggleGroupControlContext from '../context';
 import * as styles from './styles';
 
 const noop = () => {};
 
 function ToggleGroupControl(
 	props: WordPressComponentProps< ToggleGroupControlProps, 'input' >,
-	forwardedRef: import('react').Ref< any >
+	forwardedRef: Ref< any >
 ) {
 	const {
 		className,
@@ -114,4 +116,35 @@ function ToggleGroupControl(
 	);
 }
 
-export default contextConnect( ToggleGroupControl, 'ToggleGroupControl' );
+/**
+ * `ToggleGroupControl` is a form component that lets users choose options
+ * represented in horizontal segments. To render options for this control use
+ * `ToggleGroupControlOption` component.
+ *
+ * Only use this control when you know for sure the labels of items inside won't
+ * wrap. For items with longer labels, you can consider a `SelectControl` or a
+ * `CustomSelectControl` component instead.
+ *
+ * @example
+ * ```jsx
+ * import {
+ *   __experimentalToggleGroupControl as ToggleGroupControl,
+ *   __experimentalToggleGroupControlOption as ToggleGroupControlOption,
+ * } from '@wordpress/components';
+ *
+ * function Example() {
+ *   return (
+ *     <ToggleGroupControl label="my label" value="vertical" isBlock>
+ *       <ToggleGroupControlOption value="horizontal" label="Horizontal" />
+ *       <ToggleGroupControlOption value="vertical" label="Vertical" />
+ *     </ToggleGroupControl>
+ *   );
+ * }
+ * ```
+ */
+const ConnectedToggleGroupControl = contextConnect(
+	ToggleGroupControl,
+	'ToggleGroupControl'
+);
+
+export default ConnectedToggleGroupControl;

package/src/toggle-group-control/toggle-group-control/index.ts

@@ -0,0 +1 @@
+export { default as ToggleGroupControl } from './component';

package/src/toggle-group-control/toggle-group-control/styles.ts

@@ -0,0 +1,52 @@
+/**
+ * External dependencies
+ */
+import { css } from '@emotion/react';
+import styled from '@emotion/styled';
+
+/**
+ * Internal dependencies
+ */
+import { CONFIG, COLORS, reduceMotion } from '../../utils';
+
+export const ToggleGroupControl = css`
+	background: ${ COLORS.ui.background };
+	border: 1px solid;
+	border-color: ${ COLORS.ui.border };
+	border-radius: ${ CONFIG.controlBorderRadius };
+	display: inline-flex;
+	min-height: ${ CONFIG.controlHeight };
+	min-width: 0;
+	padding: 2px;
+	position: relative;
+	transition: transform ${ CONFIG.transitionDurationFastest } linear;
+	${ reduceMotion( 'transition' ) }
+	&:hover {
+		border-color: ${ COLORS.ui.borderHover };
+	}
+
+	&:focus-within {
+		border-color: ${ COLORS.ui.borderFocus };
+		box-shadow: ${ CONFIG.controlBoxShadowFocus };
+		outline: none;
+		z-index: 1;
+	}
+`;
+
+export const block = css`
+	display: flex;
+	width: 100%;
+`;
+
+export const BackdropView = styled.div`
+	background: ${ COLORS.gray[ 900 ] };
+	border-radius: ${ CONFIG.controlBorderRadius };
+	box-shadow: ${ CONFIG.toggleGroupControlBackdropBoxShadow };
+	left: 0;
+	position: absolute;
+	top: 2px;
+	bottom: 2px;
+	transition: transform ${ CONFIG.transitionDurationFast } ease;
+	${ reduceMotion( 'transition' ) }
+	z-index: 1;
+`;

package/src/toggle-group-control/{toggle-group-control-backdrop.tsx → toggle-group-control/toggle-group-control-backdrop.tsx}

@@ -6,7 +6,7 @@ import { useState, useEffect, memo } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import type { ToggleGroupControlBackdropProps } from './types';
+import type { ToggleGroupControlBackdropProps } from '../types';
 import { BackdropView } from './styles';
 
 function ToggleGroupControlBackdrop( {
@@ -18,6 +18,7 @@ function ToggleGroupControlBackdrop( {
 	const [ left, setLeft ] = useState( 0 );
 	const [ width, setWidth ] = useState( 0 );
 	const [ canAnimate, setCanAnimate ] = useState( false );
+	const [ renderBackdrop, setRenderBackdrop ] = useState( false );
 
 	useEffect( () => {
 		const containerNode = containerRef?.current;
@@ -29,7 +30,10 @@ function ToggleGroupControlBackdrop( {
 		const targetNode = containerNode.querySelector(
 			`[data-value="${ state }"]`
 		);
-		if ( ! targetNode ) return;
+		setRenderBackdrop( !! targetNode );
+		if ( ! targetNode ) {
+			return;
+		}
 
 		const { x: parentX } = containerNode.getBoundingClientRect();
 		const { width: offsetWidth, x } = targetNode.getBoundingClientRect();
@@ -48,6 +52,10 @@ function ToggleGroupControlBackdrop( {
 		return () => window.cancelAnimationFrame( requestId );
 	}, [ canAnimate, containerRef, containerWidth, state, isAdaptiveWidth ] );
 
+	if ( ! renderBackdrop ) {
+		return null;
+	}
+
 	return (
 		<BackdropView
 			role="presentation"

package/src/toggle-group-control/toggle-group-control-option/README.md

@@ -0,0 +1,40 @@
+# `ToggleGroupControlOption`
+
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
+`ToggleGroupControlOption` is a form component and is meant to be used as a child of [`ToggleGroupControl`]((/packages/components/src/toggle-group-control/toggle-group-control/README.md)).
+
+
+## Usage
+
+```js
+import {
+	__experimentalToggleGroupControl as ToggleGroupControl,
+	__experimentalToggleGroupControlOption as ToggleGroupControlOption,
+} from '@wordpress/components';
+
+function Example() {
+	return (
+		<ToggleGroupControl label="my label" value="vertical" isBlock>
+			<ToggleGroupControlOption value="horizontal" label="Horizontal" />
+			<ToggleGroupControlOption value="vertical" label="Vertical" />
+		</ToggleGroupControl>
+	);
+}
+```
+
+## Props
+
+### `label`: `string`
+
+Label for the option. If needed, the `aria-label` prop can be used in addition to specify a different label for assistive technologies.
+
+- Required: Yes
+
+### `value`: `string | number`
+
+The value of the `ToggleGroupControlOption`.
+
+- Required: Yes