ToggleGroupControl: Improve stories for Docs view (#43265)

* ToggleGroupControl: Improve stories for Docs view

* Add usage clarification re: TabPanel

* Add changelog

* Mark as non-polymorphic

packages/components/CHANGELOG.md

@@ -8,6 +8,7 @@
 
 ### Enhancements
 
+-   `ToggleGroupControl`: Improve TypeScript documentation ([#43265](https://github.com/WordPress/gutenberg/pull/43265)).
 -   `ComboboxControl`: Normalize hyphen-like characters to an ASCII hyphen ([#42942](https://github.com/WordPress/gutenberg/pull/42942)).
 -   `FormTokenField`: Refactor away from `_.difference()` ([#43224](https://github.com/WordPress/gutenberg/pull/43224/)).
 

packages/components/src/toggle-group-control/stories/index.tsx

@@ -0,0 +1,127 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+import { formatLowercase, formatUppercase } from '@wordpress/icons';
+
+/**
+ * Internal dependencies
+ */
+import {
+	ToggleGroupControl,
+	ToggleGroupControlOption,
+	ToggleGroupControlOptionIcon,
+} from '../index';
+import type {
+	ToggleGroupControlOptionProps,
+	ToggleGroupControlOptionIconProps,
+	ToggleGroupControlProps,
+} from '../types';
+
+const meta: ComponentMeta< typeof ToggleGroupControl > = {
+	component: ToggleGroupControl,
+	title: 'Components (Experimental)/ToggleGroupControl',
+	subcomponents: { ToggleGroupControlOption, ToggleGroupControlOptionIcon },
+	argTypes: {
+		help: { control: { type: 'text' } },
+		onChange: { action: 'onChange' },
+		value: { control: { type: null } },
+	},
+	parameters: {
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof ToggleGroupControl > = ( {
+	onChange,
+	...props
+} ) => {
+	const [ value, setValue ] =
+		useState< ToggleGroupControlProps[ 'value' ] >();
+
+	return (
+		<ToggleGroupControl
+			{ ...props }
+			onChange={ ( ...changeArgs ) => {
+				setValue( ...changeArgs );
+				onChange?.( ...changeArgs );
+			} }
+			value={ value }
+		/>
+	);
+};
+
+const mapPropsToOptionComponent = ( {
+	value,
+	...props
+}: ToggleGroupControlOptionProps ) => (
+	<ToggleGroupControlOption value={ value } key={ value } { ...props } />
+);
+
+const mapPropsToOptionIconComponent = ( {
+	value,
+	...props
+}: ToggleGroupControlOptionIconProps ) => (
+	<ToggleGroupControlOptionIcon value={ value } key={ value } { ...props } />
+);
+
+export const Default: ComponentStory< typeof ToggleGroupControl > =
+	Template.bind( {} );
+Default.args = {
+	children: [
+		{ value: 'left', label: 'Left' },
+		{ value: 'center', label: 'Center' },
+		{ value: 'right', label: 'Right' },
+		{ value: 'justify', label: 'Justify' },
+	].map( mapPropsToOptionComponent ),
+	label: 'Label',
+};
+
+/**
+ * A tooltip can be shown for each option by enabling the `showTooltip` prop.
+ * The `aria-label` will be used in the tooltip if provided. Otherwise, the
+ * `label` will be used.
+ */
+export const WithTooltip: ComponentStory< typeof ToggleGroupControl > =
+	Template.bind( {} );
+WithTooltip.args = {
+	...Default.args,
+	children: [
+		{
+			value: 'asc',
+			label: 'A→Z',
+			'aria-label': 'Ascending',
+			showTooltip: true,
+		},
+		{
+			value: 'desc',
+			label: 'Z→A',
+			'aria-label': 'Descending',
+			showTooltip: true,
+		},
+	].map( mapPropsToOptionComponent ),
+};
+
+/**
+ * The `ToggleGroupControlOptionIcon` component can be used for icon options. A `label` is required
+ * on each option for accessibility, which will be shown in a tooltip.
+ *
+ * When using icon options within `ToggleGroupControl`, the `__experimentalIsIconGroup` style is preferred.
+ */
+export const WithIcons: ComponentStory< typeof ToggleGroupControl > =
+	Template.bind( {} );
+WithIcons.args = {
+	...Default.args,
+	__experimentalIsIconGroup: true,
+	children: [
+		{ value: 'uppercase', label: 'Uppercase', icon: formatUppercase },
+		{ value: 'lowercase', label: 'Lowercase', icon: formatLowercase },
+	].map( mapPropsToOptionIconComponent ),
+};

packages/components/src/toggle-group-control/toggle-group-control/README.md

@@ -6,6 +6,8 @@ This feature is still experimental. “Experimental” means this is an early im
 
 `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.
 
+This component is intended for selecting a single persistent value from a set of options, similar to a how a radio button group would work. If you simply want a toggle to switch between views, use a [`TabPanel`](/packages/components/src/tab-panel/README.md) instead.
+
 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

packages/components/src/toggle-group-control/toggle-group-control/component.tsx

@@ -35,8 +35,8 @@ import * as styles from './styles';
 
 const noop = () => {};
 
-function ToggleGroupControl(
-	props: WordPressComponentProps< ToggleGroupControlProps, 'input' >,
+function UnconnectedToggleGroupControl(
+	props: WordPressComponentProps< ToggleGroupControlProps, 'input', false >,
 	forwardedRef: ForwardedRef< any >
 ) {
 	const {
@@ -135,11 +135,14 @@ function ToggleGroupControl(
  * represented in horizontal segments. To render options for this control use
  * `ToggleGroupControlOption` component.
  *
+ * This component is intended for selecting a single persistent value from a set of options,
+ * similar to a how a radio button group would work. If you simply want a toggle to switch between views,
+ * use a `TabPanel` instead.
+ *
  * 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,
@@ -156,9 +159,9 @@ function ToggleGroupControl(
  * }
  * ```
  */
-const ConnectedToggleGroupControl = contextConnect(
-	ToggleGroupControl,
+export const ToggleGroupControl = contextConnect(
+	UnconnectedToggleGroupControl,
 	'ToggleGroupControl'
 );
 
-export default ConnectedToggleGroupControl;
+export default ToggleGroupControl;