From 3b8d33aeab8baa305f91b4592cec51127aa066be Mon Sep 17 00:00:00 2001 From: Sainath Poojary Date: Thu, 19 Dec 2024 15:03:58 +0530 Subject: [PATCH 1/4] Storybook: Add stories for the panel-color-settings component --- .../stories/index.story.js | 81 +++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 packages/block-editor/src/components/panel-color-settings/stories/index.story.js diff --git a/packages/block-editor/src/components/panel-color-settings/stories/index.story.js b/packages/block-editor/src/components/panel-color-settings/stories/index.story.js new file mode 100644 index 00000000000000..4b780ca53eeaa7 --- /dev/null +++ b/packages/block-editor/src/components/panel-color-settings/stories/index.story.js @@ -0,0 +1,81 @@ +/** + * WordPress dependencies + */ +import { __ } from '@wordpress/i18n'; +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 }>', + }, + }, + }, + }, +}; + +export default meta; + +export const Default = { + render: function Template( args ) { + const [ color, setColor ] = useState( '#0F52BA' ); + + return ( + { + setColor( newColor ); + }, + label: __( 'Color' ), + 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' }, + ], + }, + ] } + /> + ); + }, +}; + +export const WithAdditionalProps = { + ...Default, + args: { + title: __( 'Color' ), + showTitle: true, + __experimentalIsRenderedInSidebar: true, + disableCustomColors: false, + disableCustomGradients: false, + disableDefaultColors: false, + disableDefaultGradients: false, + disableGradients: false, + enableAlpha: true, + }, +}; From fa214f3c480b9c92b6a87f402b1bbcde4e219107 Mon Sep 17 00:00:00 2001 From: Sainath Poojary Date: Thu, 19 Dec 2024 18:38:09 +0530 Subject: [PATCH 2/4] Storybook: Enhance PanelColorSettings documentation and comments - Improved prop descriptions in README.md for clarity. - Added JSDoc for PanelColorSettings props --- packages/block-editor/README.md | 75 ++++++++++++++++++- .../components/panel-color-settings/README.md | 10 +-- .../components/panel-color-settings/index.js | 73 ++++++++++++++++++ 3 files changed, 152 insertions(+), 6 deletions(-) diff --git a/packages/block-editor/README.md b/packages/block-editor/README.md index 13dffce114f59a..77c7c30d03b956 100644 --- a/packages/block-editor/README.md +++ b/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_ + +- + +_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 ( + + ); +}; + +; +``` + +_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 diff --git a/packages/block-editor/src/components/panel-color-settings/README.md b/packages/block-editor/src/components/panel-color-settings/README.md index e9f3818fab55c3..4c8e3dc8be1905 100644 --- a/packages/block-editor/src/components/panel-color-settings/README.md +++ b/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. diff --git a/packages/block-editor/src/components/panel-color-settings/index.js b/packages/block-editor/src/components/panel-color-settings/index.js index 29a444def88a20..28a521f4017ba8 100644 --- a/packages/block-editor/src/components/panel-color-settings/index.js +++ b/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 ( + * + * ); + * }; + * + * ; + * ``` + * + * @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 ) { From 7b738623e3a6faa29c6f23b8cb20b82056c9138f Mon Sep 17 00:00:00 2001 From: Sainath Poojary Date: Thu, 19 Dec 2024 19:10:57 +0530 Subject: [PATCH 3/4] Storybook: Update PanelColorSettings stories - Added detailed controls for props with descriptions and types. - Enhanced Default story with examples for Background, Text, and Link colors. --- .../stories/index.story.js | 116 +++++++++++++----- 1 file changed, 87 insertions(+), 29 deletions(-) diff --git a/packages/block-editor/src/components/panel-color-settings/stories/index.story.js b/packages/block-editor/src/components/panel-color-settings/stories/index.story.js index 4b780ca53eeaa7..adadee36c34d1f 100644 --- a/packages/block-editor/src/components/panel-color-settings/stories/index.story.js +++ b/packages/block-editor/src/components/panel-color-settings/stories/index.story.js @@ -1,7 +1,6 @@ /** * WordPress dependencies */ -import { __ } from '@wordpress/i18n'; import { useState } from '@wordpress/element'; /** @@ -32,50 +31,109 @@ const meta = { }, }, }, + 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: 'text', + 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 [ color, setColor ] = useState( '#0F52BA' ); + const [ backgroundColor, setbackgroundColor ] = useState( '' ); + const [ textColor, setTextColor ] = useState( '' ); + const [ linkColor, setLinkColor ] = useState( '' ); return ( { - setColor( newColor ); - }, - label: __( 'Color' ), - 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' }, - ], + value: backgroundColor, + onChange: setbackgroundColor, + label: 'Background', + }, + { + value: textColor, + onChange: setTextColor, + label: 'Text', + }, + { + value: linkColor, + onChange: setLinkColor, + label: 'Link', }, ] } /> ); }, }; - -export const WithAdditionalProps = { - ...Default, - args: { - title: __( 'Color' ), - showTitle: true, - __experimentalIsRenderedInSidebar: true, - disableCustomColors: false, - disableCustomGradients: false, - disableDefaultColors: false, - disableDefaultGradients: false, - disableGradients: false, - enableAlpha: true, - }, -}; From 804bb18cb4b3ca2bb9180afc8238fdfdafe1f1af Mon Sep 17 00:00:00 2001 From: Sainath Poojary Date: Fri, 20 Dec 2024 09:41:00 +0530 Subject: [PATCH 4/4] Storybook: Disable the control for children prop --- .../panel-color-settings/stories/index.story.js | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/packages/block-editor/src/components/panel-color-settings/stories/index.story.js b/packages/block-editor/src/components/panel-color-settings/stories/index.story.js index adadee36c34d1f..e02f724ab49a94 100644 --- a/packages/block-editor/src/components/panel-color-settings/stories/index.story.js +++ b/packages/block-editor/src/components/panel-color-settings/stories/index.story.js @@ -34,7 +34,7 @@ const meta = { className: { control: 'text', description: - 'Additional class names added to the underlying `ToolsPanel` instance.', + 'Additional class names added to the underlying ToolsPanel instance.', table: { type: { summary: 'string' }, }, @@ -56,23 +56,23 @@ const meta = { }, }, children: { - control: 'text', + control: { type: null }, description: - 'Displayed below the underlying `PanelColorGradientSettings` instance.', + 'Displayed below the underlying PanelColorGradientSettings instance.', table: { type: { summary: 'ReactNode' }, }, }, title: { control: 'text', - description: 'The title of the underlying `ToolsPanel`.', + description: 'The title of the underlying ToolsPanel.', table: { type: { summary: 'string' }, }, }, showTitle: { control: 'boolean', - description: 'Whether to show the title of the `ToolsPanel`.', + description: 'Whether to show the title of the ToolsPanel.', table: { type: { summary: 'boolean' }, },