From b3bfb37bdb37885b1e4c6cea6f7ccd1c75fccee8 Mon Sep 17 00:00:00 2001 From: Sainath Poojary Date: Wed, 27 Nov 2024 14:21:17 +0530 Subject: [PATCH 1/5] Storybook: Add PlainText Storybook stories - Add Default, LongText, and WithClassName stories - Configure meta for PlainText component --- .../plain-text/stories/index.story.js | 86 +++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 packages/block-editor/src/components/plain-text/stories/index.story.js diff --git a/packages/block-editor/src/components/plain-text/stories/index.story.js b/packages/block-editor/src/components/plain-text/stories/index.story.js new file mode 100644 index 00000000000000..33c0ebfda431c3 --- /dev/null +++ b/packages/block-editor/src/components/plain-text/stories/index.story.js @@ -0,0 +1,86 @@ +/** + * Internal dependencies + */ +import PlainText from '..'; + +/** + * WordPress dependencies + */ +import { useEffect, useState } from '@wordpress/element'; + +/** + * Render an auto-growing textarea allow users to fill any textual content. + */ +const meta = { + title: 'BlockEditor/PlainText', + component: PlainText, + argTypes: { + value: { + control: 'text', + description: 'The current text value of the PlainText', + }, + onChange: { + action: 'onChange', + control: { + type: null, + }, + description: 'Function called when the text value changes', + }, + className: { + control: 'text', + description: 'Additional class name for the PlainText', + }, + }, + render: function Render( args ) { + const [ value, setValue ] = useState( '' ); + + const { value: argValue, className, onChange } = args; + + useEffect( () => { + setValue( argValue ); + }, [ argValue ] ); + + const handleOnChange = ( newValue ) => { + setValue( newValue ); + if ( onChange ) { + onChange( newValue ); + } + }; + + return ( + + ); + }, +}; + +export default meta; + +export const Default = { + args: { + className: 'bold', + value: 'Type some text here...', + }, +}; + +/** + * PlainText component with a long text value to test auto-grow. + */ +export const LongText = { + args: { + value: 'Type a long piece of text to see auto-grow in action...', + }, +}; + +/** + * PlainText component with a custom class name. + */ +export const WithClassName = { + args: { + className: 'my-custom-class', + value: 'Type some text here...', + }, +}; From cab66de457e789e181be54ab4053655582dce62c Mon Sep 17 00:00:00 2001 From: Sainath Poojary <spoojary614@gmail.com> Date: Fri, 6 Dec 2024 16:01:36 +0530 Subject: [PATCH 2/5] Refactor: `PlainText` stories and removed useEffect --- .../plain-text/stories/index.story.js | 76 +++++++++---------- 1 file changed, 36 insertions(+), 40 deletions(-) diff --git a/packages/block-editor/src/components/plain-text/stories/index.story.js b/packages/block-editor/src/components/plain-text/stories/index.story.js index 33c0ebfda431c3..4f92523c788c90 100644 --- a/packages/block-editor/src/components/plain-text/stories/index.story.js +++ b/packages/block-editor/src/components/plain-text/stories/index.story.js @@ -6,17 +6,33 @@ import PlainText from '..'; /** * WordPress dependencies */ -import { useEffect, useState } from '@wordpress/element'; +import { useState } from '@wordpress/element'; /** - * Render an auto-growing textarea allow users to fill any textual content. + * Render an auto-growing textarea for user input. */ const meta = { title: 'BlockEditor/PlainText', component: PlainText, + parameters: { + docs: { + canvas: { sourceState: 'shown' }, + }, + description: { + component: + 'PlainText renders an auto-growing textarea that allows users to enter any textual content.', + }, + }, argTypes: { value: { - control: 'text', + control: { + type: null, + }, + table: { + type: { + summary: 'string', + }, + }, description: 'The current text value of the PlainText', }, onChange: { @@ -24,34 +40,33 @@ const meta = { control: { type: null, }, + table: { + type: { + summary: 'function', + }, + }, description: 'Function called when the text value changes', }, className: { control: 'text', + table: { + type: { + summary: 'string', + }, + }, description: 'Additional class name for the PlainText', }, }, - render: function Render( args ) { - const [ value, setValue ] = useState( '' ); - - const { value: argValue, className, onChange } = args; - - useEffect( () => { - setValue( argValue ); - }, [ argValue ] ); - - const handleOnChange = ( newValue ) => { - setValue( newValue ); - if ( onChange ) { - onChange( newValue ); - } - }; - + render: function Template( { onChange, ...args } ) { + const [ value, setValue ] = useState( args.value ); return ( <PlainText + { ...args } + onChange={ ( ...changeArgs ) => { + onChange( ...changeArgs ); + setValue( ...changeArgs ); + } } value={ value } - onChange={ handleOnChange } - className={ className } /> ); }, @@ -65,22 +80,3 @@ export const Default = { value: 'Type some text here...', }, }; - -/** - * PlainText component with a long text value to test auto-grow. - */ -export const LongText = { - args: { - value: 'Type a long piece of text to see auto-grow in action...', - }, -}; - -/** - * PlainText component with a custom class name. - */ -export const WithClassName = { - args: { - className: 'my-custom-class', - value: 'Type some text here...', - }, -}; From 109c17fc936bb0f2650b828309c798808f5a8bef Mon Sep 17 00:00:00 2001 From: Sainath Poojary <spoojary614@gmail.com> Date: Thu, 12 Dec 2024 16:00:01 +0530 Subject: [PATCH 3/5] Refactor: Remove comment from story --- .../plain-text/stories/index.story.js | 25 +++++++------------ 1 file changed, 9 insertions(+), 16 deletions(-) diff --git a/packages/block-editor/src/components/plain-text/stories/index.story.js b/packages/block-editor/src/components/plain-text/stories/index.story.js index 4f92523c788c90..0c2f2f4c594eb1 100644 --- a/packages/block-editor/src/components/plain-text/stories/index.story.js +++ b/packages/block-editor/src/components/plain-text/stories/index.story.js @@ -8,19 +8,16 @@ import PlainText from '..'; */ import { useState } from '@wordpress/element'; -/** - * Render an auto-growing textarea for user input. - */ const meta = { title: 'BlockEditor/PlainText', component: PlainText, parameters: { docs: { canvas: { sourceState: 'shown' }, - }, - description: { - component: - 'PlainText renders an auto-growing textarea that allows users to enter any textual content.', + description: { + component: + 'PlainText renders an auto-growing textarea that allows users to enter any textual content.', + }, }, }, argTypes: { @@ -57,6 +54,11 @@ const meta = { description: 'Additional class name for the PlainText', }, }, +}; + +export default meta; + +export const Default = { render: function Template( { onChange, ...args } ) { const [ value, setValue ] = useState( args.value ); return ( @@ -71,12 +73,3 @@ const meta = { ); }, }; - -export default meta; - -export const Default = { - args: { - className: 'bold', - value: 'Type some text here...', - }, -}; From c524163e82001b1b8251835e9efa4539837d5fa5 Mon Sep 17 00:00:00 2001 From: Sainath Poojary <spoojary614@gmail.com> Date: Tue, 17 Dec 2024 13:19:25 +0530 Subject: [PATCH 4/5] Storybook: improve `PlainText` JSDoc and storybook descriptions - Enhance prop descriptions - Fix import order in storybook. --- packages/block-editor/README.md | 40 +++++++++++++++++++ .../src/components/plain-text/index.js | 34 ++++++++++++++++ .../plain-text/stories/index.story.js | 16 ++++---- 3 files changed, 82 insertions(+), 8 deletions(-) diff --git a/packages/block-editor/README.md b/packages/block-editor/README.md index a0f75683914408..fa9bed3ec462c4 100644 --- a/packages/block-editor/README.md +++ b/packages/block-editor/README.md @@ -705,10 +705,50 @@ Undocumented declaration. ### PlainText +Render an auto-growing textarea allow users to fill any textual content. + _Related_ - <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/plain-text/README.md> +_Usage_ + +```jsx +import { registerBlockType } from '@wordpress/blocks'; +import { PlainText } from '@wordpress/block-editor'; + +registerBlockType( 'my-plugin/example-block', { + // ... + + attributes: { + content: { + type: 'string', + }, + }, + + edit( { className, attributes, setAttributes } ) { + return ( + <PlainText + className={ className } + value={ attributes.content } + onChange={ ( content ) => setAttributes( { content } ) } + /> + ); + }, +} ); +``` + +_Parameters_ + +- _props_ `Object`: Component props. +- _props.value_ `string`: String value of the textarea +- _props.onChange_ `Function`: Called when the value changes +- _props.ref_ `[Object]`: The component forwards the `ref` property to the `TextareaAutosize` component. + +_Returns_ + +- `Element`: Plain text component + ### privateApis Private @wordpress/block-editor APIs. diff --git a/packages/block-editor/src/components/plain-text/index.js b/packages/block-editor/src/components/plain-text/index.js index 4bd6681f4eb079..e054a6016c23d9 100644 --- a/packages/block-editor/src/components/plain-text/index.js +++ b/packages/block-editor/src/components/plain-text/index.js @@ -15,7 +15,41 @@ import { forwardRef } from '@wordpress/element'; import EditableText from '../editable-text'; /** + * Render an auto-growing textarea allow users to fill any textual content. + * * @see https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/plain-text/README.md + * + * @example + * ```jsx + * import { registerBlockType } from '@wordpress/blocks'; + * import { PlainText } from '@wordpress/block-editor'; + * + * registerBlockType( 'my-plugin/example-block', { + * // ... + * + * attributes: { + * content: { + * type: 'string', + * }, + * }, + * + * edit( { className, attributes, setAttributes } ) { + * return ( + * <PlainText + * className={ className } + * value={ attributes.content } + * onChange={ ( content ) => setAttributes( { content } ) } + * /> + * ); + * }, + * } ); + * ```` + * + * @param {Object} props Component props. + * @param {string} props.value String value of the textarea + * @param {Function} props.onChange Called when the value changes + * @param {Object} [props.ref] The component forwards the `ref` property to the `TextareaAutosize` component. + * @return {Element} Plain text component */ const PlainText = forwardRef( ( { __experimentalVersion, ...props }, ref ) => { if ( __experimentalVersion === 2 ) { diff --git a/packages/block-editor/src/components/plain-text/stories/index.story.js b/packages/block-editor/src/components/plain-text/stories/index.story.js index 0c2f2f4c594eb1..3eda17b6d73bb9 100644 --- a/packages/block-editor/src/components/plain-text/stories/index.story.js +++ b/packages/block-editor/src/components/plain-text/stories/index.story.js @@ -1,12 +1,12 @@ /** - * Internal dependencies + * WordPress dependencies */ -import PlainText from '..'; +import { useState } from '@wordpress/element'; /** - * WordPress dependencies + * Internal dependencies */ -import { useState } from '@wordpress/element'; +import PlainText from '..'; const meta = { title: 'BlockEditor/PlainText', @@ -30,7 +30,7 @@ const meta = { summary: 'string', }, }, - description: 'The current text value of the PlainText', + description: 'The current text value of the PlainText.', }, onChange: { action: 'onChange', @@ -42,7 +42,7 @@ const meta = { summary: 'function', }, }, - description: 'Function called when the text value changes', + description: 'Function called when the text value changes.', }, className: { control: 'text', @@ -51,7 +51,7 @@ const meta = { summary: 'string', }, }, - description: 'Additional class name for the PlainText', + description: 'Additional class name for the PlainText.', }, }, }; @@ -60,7 +60,7 @@ export default meta; export const Default = { render: function Template( { onChange, ...args } ) { - const [ value, setValue ] = useState( args.value ); + const [ value, setValue ] = useState(); return ( <PlainText { ...args } From 93f3680fb301195794d14344b490edeea8112847 Mon Sep 17 00:00:00 2001 From: Sainath Poojary <spoojary614@gmail.com> Date: Fri, 20 Dec 2024 00:05:04 +0530 Subject: [PATCH 5/5] Storybook: Unify value and onChange prop descriptions --- packages/block-editor/README.md | 4 ++-- packages/block-editor/src/components/plain-text/README.md | 4 ++-- packages/block-editor/src/components/plain-text/index.js | 4 ++-- .../src/components/plain-text/stories/index.story.js | 2 +- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/packages/block-editor/README.md b/packages/block-editor/README.md index fa9bed3ec462c4..f4bdc3783aef2f 100644 --- a/packages/block-editor/README.md +++ b/packages/block-editor/README.md @@ -741,8 +741,8 @@ registerBlockType( 'my-plugin/example-block', { _Parameters_ - _props_ `Object`: Component props. -- _props.value_ `string`: String value of the textarea -- _props.onChange_ `Function`: Called when the value changes +- _props.value_ `string`: String value of the textarea. +- _props.onChange_ `Function`: Function called when the text value changes. - _props.ref_ `[Object]`: The component forwards the `ref` property to the `TextareaAutosize` component. _Returns_ diff --git a/packages/block-editor/src/components/plain-text/README.md b/packages/block-editor/src/components/plain-text/README.md index aa15758118afdc..1e0a7888ed1e4d 100644 --- a/packages/block-editor/src/components/plain-text/README.md +++ b/packages/block-editor/src/components/plain-text/README.md @@ -6,11 +6,11 @@ Render an auto-growing textarea allow users to fill any textual content. ### `value: string` -_Required._ String value of the textarea +_Required._ String value of the textarea. ### `onChange( value: string ): Function` -_Required._ Called when the value changes. +_Required._ Function called when the text value changes. You can also pass any extra prop to the textarea rendered by this component. diff --git a/packages/block-editor/src/components/plain-text/index.js b/packages/block-editor/src/components/plain-text/index.js index e054a6016c23d9..d28aabebf7a140 100644 --- a/packages/block-editor/src/components/plain-text/index.js +++ b/packages/block-editor/src/components/plain-text/index.js @@ -46,8 +46,8 @@ import EditableText from '../editable-text'; * ```` * * @param {Object} props Component props. - * @param {string} props.value String value of the textarea - * @param {Function} props.onChange Called when the value changes + * @param {string} props.value String value of the textarea. + * @param {Function} props.onChange Function called when the text value changes. * @param {Object} [props.ref] The component forwards the `ref` property to the `TextareaAutosize` component. * @return {Element} Plain text component */ diff --git a/packages/block-editor/src/components/plain-text/stories/index.story.js b/packages/block-editor/src/components/plain-text/stories/index.story.js index 3eda17b6d73bb9..d1a6253c0870a7 100644 --- a/packages/block-editor/src/components/plain-text/stories/index.story.js +++ b/packages/block-editor/src/components/plain-text/stories/index.story.js @@ -30,7 +30,7 @@ const meta = { summary: 'string', }, }, - description: 'The current text value of the PlainText.', + description: 'String value of the textarea.', }, onChange: { action: 'onChange',