Storybook: Add stories for the panel-color-settings Component

packages/block-editor/README.md

@@ -709,7 +709,80 @@ _Related_
 
 ### PanelColorSettings
 
-Undocumented declaration.
+`PanelColorSettings` is a React component that renders a UI for managing various color settings. It is essentially a wrapper around the `PanelColorGradientSettings` component, but specifically disables the gradient features.
+
+_Related_
+
+-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/panel-color-settings/README.md>
+
+_Usage_
+
+```jsx
+import { useState } from 'react';
+import { PanelColorSettings } from '@wordpress/block-editor';
+import { __ } from '@wordpress/i18n';
+
+const MyPanelColorSettings = () => {
+	const [ textColor, setTextColor ] = useState( { color: '#000' } );
+	const [ backgroundColor, setBackgroundColor ] = useState( {
+		color: '#fff',
+	} );
+	const [ overlayTextColor, setOverlayTextColor ] = useState( {
+		color: '#000',
+	} );
+	const [ overlayBackgroundColor, setOverlayBackgroundColor ] = useState( {
+		color: '#eee',
+	} );
+
+	return (
+		<PanelColorSettings
+			__experimentalIsRenderedInSidebar
+			title={ __( 'Color' ) }
+			colorSettings={ [
+				{
+					value: textColor.color,
+					onChange: setTextColor,
+					label: __( 'Text' ),
+				},
+				{
+					value: backgroundColor.color,
+					onChange: setBackgroundColor,
+					label: __( 'Background' ),
+				},
+				{
+					value: overlayTextColor.color,
+					onChange: setOverlayTextColor,
+					label: __( 'Submenu & overlay text' ),
+				},
+				{
+					value: overlayBackgroundColor.color,
+					onChange: setOverlayBackgroundColor,
+					label: __( 'Submenu & overlay background' ),
+				},
+			] }
+		/>
+	);
+};
+
+<MyPanelColorSettings />;
+```
+
+_Parameters_
+
+-   _props_ `Object`: Component props.
+-   _props.colorSettings_ `[Array]`: A user-provided array of color settings. Colors settings are provided as an array of objects with the following schema: - `value` (string): The current color of the setting. - `onChange` (Function): Callback on change of the setting. - `label` (string): Label of the setting.
+-   _props.className_ `[string]`: Additional class names added to the underlying `ToolsPanel` instance.
+-   _props.colors_ `[Array]`: An array of predefined colors to be displayed in the color palette.
+-   _props.disableCustomColors_ `[boolean]`: Whether to disable the option for users to add custom colors.
+-   _props.children_ `[JSX.Element]`: Displayed below the underlying `PanelColorGradientSettings` instance.
+-   _props.title_ `[string]`: The title of the underlying `ToolsPanel`.
+-   _props.showTitle_ `[boolean]`: Whether to show the title of the `ToolsPanel`.
+-   _props.\_\_experimentalIsRenderedInSidebar_ `[boolean]`: Whether this is rendered in the sidebar.
+-   _props.enableAlpha_ `[boolean]`: Whether to enable the alpha (opacity) slider in the color picker.
+
+_Returns_
+
+-   `JSX.Element`: The PanelColorSettings component.
 
 ### PlainText
 

packages/block-editor/src/components/panel-color-settings/README.md

@@ -87,16 +87,16 @@ Colors settings are provided as an array of objects with the following schema:
 
 Additionally, the following `PanelColorGradientSettings` props are supported and directly passed down to the underlying `PanelColorGradientSettings` instance:
 
-- `className` - added to the underlying `ToolsPanel` instance.
-- `colors` - array of colors to be used.
+- `className` - additional class names added to the underlying `ToolsPanel` instance.
+- `colors` - an array of predefined colors to be displayed in the color palette.
 - `gradients` - not recommended to be used since `PanelColorSettings` resets it.
-- `disableCustomColors` - whether addition of custom colors is enabled
+- `disableCustomColors` - whether to disable the option for users to add custom colors.
 - `disableCustomGradients` - not recommended to be used since `PanelColorSettings` sets it.
 - `children` - displayed below the underlying `PanelColorGradientSettings` instance.
 - `settings` - not recommended to be used, since `PanelColorSettings` builds it from the `colorSettings` prop.
-- `title` - title of the underlying `ToolsPanel`.
+- `title` - the title of the underlying `ToolsPanel`.
 - `showTitle` - whether to show the title of the `ToolsPanel`.
-- `__experimentalIsRenderedInSidebar`
+- `__experimentalIsRenderedInSidebar` - whether this is rendered in the sidebar.
 - `enableAlpha` - whether to enable setting opacity when specifying a color.
 
 Please refer to the `PanelColorGradientSettings` component for more information.

packages/block-editor/src/components/panel-color-settings/index.js

@@ -3,6 +3,79 @@
  */
 import PanelColorGradientSettings from '../colors-gradients/panel-color-gradient-settings';
 
+/**
+ * `PanelColorSettings` is a React component that renders a UI for managing various color settings.
+ * It is essentially a wrapper around the `PanelColorGradientSettings` component, but specifically
+ * disables the gradient features.
+ *
+ * @see https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/panel-color-settings/README.md
+ *
+ * @example
+ * ```jsx
+ * import { useState } from 'react';
+ * import { PanelColorSettings } from '@wordpress/block-editor';
+ * import { __ } from '@wordpress/i18n';
+ *
+ * const MyPanelColorSettings = () => {
+ *   const [textColor, setTextColor] = useState({ color: '#000' });
+ *   const [backgroundColor, setBackgroundColor] = useState({
+ *     color: '#fff',
+ *   });
+ *   const [overlayTextColor, setOverlayTextColor] = useState({
+ *     color: '#000',
+ *   });
+ *   const [overlayBackgroundColor, setOverlayBackgroundColor] = useState({
+ *     color: '#eee',
+ *   });
+ *
+ *   return (
+ *     <PanelColorSettings
+ *       __experimentalIsRenderedInSidebar
+ *       title={__('Color')}
+ *       colorSettings={[
+ *         {
+ *           value: textColor.color,
+ *           onChange: setTextColor,
+ *           label: __('Text'),
+ *         },
+ *         {
+ *           value: backgroundColor.color,
+ *           onChange: setBackgroundColor,
+ *           label: __('Background'),
+ *         },
+ *         {
+ *           value: overlayTextColor.color,
+ *           onChange: setOverlayTextColor,
+ *           label: __('Submenu & overlay text'),
+ *         },
+ *         {
+ *           value: overlayBackgroundColor.color,
+ *           onChange: setOverlayBackgroundColor,
+ *           label: __('Submenu & overlay background'),
+ *         },
+ *       ]}
+ *     />
+ *   );
+ * };
+ *
+ * <MyPanelColorSettings />;
+ * ```
+ *
+ * @param {Object}      props                                     Component props.
+ * @param {Array}       [props.colorSettings]                     A user-provided array of color settings. Colors settings are provided as an array of objects with the following schema:
+ *                                                                - `value` (string): The current color of the setting.
+ *                                                                - `onChange` (Function): Callback on change of the setting.
+ *                                                                - `label` (string): Label of the setting.
+ * @param {string}      [props.className]                         Additional class names added to the underlying `ToolsPanel` instance.
+ * @param {Array}       [props.colors]                            An array of predefined colors to be displayed in the color palette.
+ * @param {boolean}     [props.disableCustomColors]               Whether to disable the option for users to add custom colors.
+ * @param {JSX.Element} [props.children]                          Displayed below the underlying `PanelColorGradientSettings` instance.
+ * @param {string}      [props.title]                             The title of the underlying `ToolsPanel`.
+ * @param {boolean}     [props.showTitle]                         Whether to show the title of the `ToolsPanel`.
+ * @param {boolean}     [props.__experimentalIsRenderedInSidebar] Whether this is rendered in the sidebar.
+ * @param {boolean}     [props.enableAlpha]                       Whether to enable the alpha (opacity) slider in the color picker.
+ * @return {JSX.Element} The PanelColorSettings component.
+ */
 const PanelColorSettings = ( { colorSettings, ...props } ) => {
 	const settings = colorSettings.map( ( setting ) => {
 		if ( ! setting ) {

packages/block-editor/src/components/panel-color-settings/stories/index.story.js

@@ -0,0 +1,139 @@
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import PanelColorSettings from '../';
+
+const meta = {
+	title: 'BlockEditor/PanelColorSettings',
+	component: PanelColorSettings,
+	parameters: {
+		docs: {
+			canvas: { sourceState: 'shown' },
+			description: {
+				component:
+					'The `PanelColorSettings` component provides a UI for managing color settings. It wraps the `PanelColorGradientSettings` component while specifically disabling gradient features.',
+			},
+		},
+	},
+	argTypes: {
+		colorSettings: {
+			description: 'Array of color setting objects',
+			control: { type: 'object' },
+			table: {
+				type: {
+					summary:
+						'Array<{ value: string, onChange: Function, label: string }>',
+				},
+			},
+		},
+		className: {
+			control: 'text',
+			description:
+				'Additional class names added to the underlying ToolsPanel instance.',
+			table: {
+				type: { summary: 'string' },
+			},
+		},
+		colors: {
+			control: 'object',
+			description:
+				'An array of predefined colors to be displayed in the color palette.',
+			table: {
+				type: { summary: 'Array<{ name: string, color: string }>' },
+			},
+		},
+		disableCustomColors: {
+			control: 'boolean',
+			description:
+				'Whether to disable the option for users to add custom colors.',
+			table: {
+				type: { summary: 'boolean' },
+			},
+		},
+		children: {
+			control: { type: null },
+			description:
+				'Displayed below the underlying PanelColorGradientSettings instance.',
+			table: {
+				type: { summary: 'ReactNode' },
+			},
+		},
+		title: {
+			control: 'text',
+			description: 'The title of the underlying ToolsPanel.',
+			table: {
+				type: { summary: 'string' },
+			},
+		},
+		showTitle: {
+			control: 'boolean',
+			description: 'Whether to show the title of the ToolsPanel.',
+			table: {
+				type: { summary: 'boolean' },
+			},
+		},
+		__experimentalIsRenderedInSidebar: {
+			control: 'boolean',
+			description: 'Whether this is rendered in the sidebar.',
+			table: {
+				type: { summary: 'boolean' },
+			},
+		},
+		enableAlpha: {
+			control: 'boolean',
+			description:
+				'Whether to enable the alpha (opacity) slider in the color picker.',
+			table: {
+				type: { summary: 'boolean' },
+			},
+		},
+	},
+};
+
+export default meta;
+
+export const Default = {
+	args: {
+		colors: [
+			{ name: 'Sapphire Blue', color: '#0F52BA' },
+			{ name: 'Emerald Green', color: '#50C878' },
+			{ name: 'Ruby Red', color: '#E0115F' },
+			{ name: 'Amethyst Purple', color: '#9966CC' },
+			{ name: 'Topaz Yellow', color: '#FFC87C' },
+		],
+		title: 'Color',
+	},
+	render: function Template( args ) {
+		const [ backgroundColor, setbackgroundColor ] = useState( '' );
+		const [ textColor, setTextColor ] = useState( '' );
+		const [ linkColor, setLinkColor ] = useState( '' );
+
+		return (
+			<PanelColorSettings
+				{ ...args }
+				colorSettings={ [
+					{
+						value: backgroundColor,
+						onChange: setbackgroundColor,
+						label: 'Background',
+					},
+					{
+						value: textColor,
+						onChange: setTextColor,
+						label: 'Text',
+					},
+					{
+						value: linkColor,
+						onChange: setLinkColor,
+						label: 'Link',
+					},
+				] }
+			/>
+		);
+	},
+};