From 19b918e6b866f96923c7782f937c1168b8a96e02 Mon Sep 17 00:00:00 2001 From: Andrew Duthie Date: Thu, 23 Jan 2020 19:58:02 -0500 Subject: [PATCH 1/3] Block Editor: LinkControl: Resolve error when undefined value, "view" state --- .../src/components/link-control/README.md | 30 +++++- .../src/components/link-control/index.js | 100 ++++++++++++++---- 2 files changed, 105 insertions(+), 25 deletions(-) diff --git a/packages/block-editor/src/components/link-control/README.md b/packages/block-editor/src/components/link-control/README.md index 158ef9d4c95ea..2fa39f52d221d 100644 --- a/packages/block-editor/src/components/link-control/README.md +++ b/packages/block-editor/src/components/link-control/README.md @@ -1,5 +1,9 @@ # Link Control +Renders a link control. A link control is a controlled input which maintains +a value associated with a link (HTML anchor element) and relevant settings +for how that link is expected to behave. + ## Props ### value @@ -7,6 +11,18 @@ - Type: `Object` - Required: No +Current link value. + +A link value contains is composed as a union of the default properties and any custom settings values. + +Default properties include: + +- id (`string|number`): Unique identifier of link. +- url (`string`): Link URL. +- title (`string`): Link title. +- type (`string`): Type of link entity. +- subtype (`string`): Subtype of link entity. + ### settings - Type: `Array` @@ -33,14 +49,20 @@ An array of settings objects. Each object will used to render a `ToggleControl` - Type: `Function` - Required: No -Use this callback to take an action after a user set or updated a link. -The function callback will receive the selected item. +Value change handler, called with the updated value if the user selects a new link or updates settings. ```jsx { - console.log( `The item selected has the ${ item.id } id.` ); + onChange={ ( nextValue ) => { + console.log( `The item selected has the ${ nextValue.id } id.` ); } /> ``` +### showInitialSuggestions + +- Type: `boolean` +- Required: No +- Default: `false` + +Whether to present initial suggestions immediately. diff --git a/packages/block-editor/src/components/link-control/index.js b/packages/block-editor/src/components/link-control/index.js index 38fec35f6ab6b..ab25b65e92350 100644 --- a/packages/block-editor/src/components/link-control/index.js +++ b/packages/block-editor/src/components/link-control/index.js @@ -27,6 +27,66 @@ import LinkControlSettingsDrawer from './settings-drawer'; import LinkControlSearchItem from './search-item'; import LinkControlSearchInput from './search-input'; +/** + * Default properties associated with a link control value. + * + * @typedef WPLinkControlDefaultValue + * + * @property {string|number} id Unique identifier of link. + * @property {string} url Link URL. + * @property {string} title Link title. + * @property {string} type Type of link entity. + * @property {string} subtype Subtype of link entity. + * @property {boolean} [opensInNewTab] Whether link should open in a new + * browser tab. This value is only + * assigned if not providing a custom + * settings array. + */ + +/** + * Custom settings values associated with a link. + * + * @typedef {{[setting:string]:any}} WPLinkControlSettingsValue + */ + +/** + * Custom settings values associated with a link. + * + * @typedef WPLinkControlSetting + * + * @property {string} id Identifier to use as property for setting value. + * @property {string} title Human-readable label to show in user interface. + */ + +/** + * Properties associated with a link control value, composed as a union of the + * default properties and any custom settings values. + * + * @typedef {WPLinkControlDefaultValue&WPLinkControlSettingsValue} WPLinkControlValue + */ + +/** @typedef {(nextValue:WPLinkControlValue)=>void} WPLinkControlOnChangeProp */ + +/** + * @typedef WPLinkControlProps + * + * @property {(WPLinkControlSetting[])=} settings An array of settings objects. Each object will used to + * render a `ToggleControl` for that setting. + * @property {(search:string)=>Promise=} fetchSearchSuggestions Fetches suggestions for a given search term, + * returning a promise resolving once fetch is complete. + * @property {WPLinkControlValue=} value Current link value. + * @property {WPLinkControlOnChangeProp=} onChange Value change handler, called with the updated value if + * the user selects a new link or updates settings. + * @property {boolean=} showInitialSuggestions Whether to present initial suggestions immediately. + */ + +/** + * Renders a link control. A link control is a controlled input which maintains + * a value associated with a link (HTML anchor element) and relevant settings + * for how that link is expected to behave. + * + * @param {WPLinkControlProps} props Component props. + */ function LinkControl( { value, settings, @@ -157,7 +217,19 @@ function LinkControl( { return (
- { ( ! isEditingLink ) && ( + { isEditingLink || ! value ? + { + setIsEditingLink( false ); + onChange( { ...value, ...suggestion } ); + } } + renderSuggestions={ renderSearchResults } + fetchSuggestions={ getSearchHandler } + onReset={ resetInput } + showInitialSuggestions={ showInitialSuggestions } + /> :

{ __( 'Currently selected' ) }: @@ -191,27 +263,13 @@ function LinkControl( { { __( 'Edit' ) }

+ - ) } - - { isEditingLink && ( - { - setIsEditingLink( false ); - onChange( { ...value, ...suggestion } ); - } } - renderSuggestions={ renderSearchResults } - fetchSuggestions={ getSearchHandler } - onReset={ resetInput } - showInitialSuggestions={ showInitialSuggestions } - /> - ) } - - { ! isEditingLink && ( - - ) } + } ); } From bc5e69688fd6c9f66c7236666a0e4536c5be63d5 Mon Sep 17 00:00:00 2001 From: Andrew Duthie Date: Tue, 28 Jan 2020 11:28:25 -0500 Subject: [PATCH 2/3] Block Editor: LinkControl: Document only url, title, opensInNewTab value properties --- .../src/components/link-control/README.md | 8 +++----- .../src/components/link-control/index.js | 14 +++++--------- 2 files changed, 8 insertions(+), 14 deletions(-) diff --git a/packages/block-editor/src/components/link-control/README.md b/packages/block-editor/src/components/link-control/README.md index 2fa39f52d221d..98d49e9b49dea 100644 --- a/packages/block-editor/src/components/link-control/README.md +++ b/packages/block-editor/src/components/link-control/README.md @@ -17,11 +17,9 @@ A link value contains is composed as a union of the default properties and any c Default properties include: -- id (`string|number`): Unique identifier of link. -- url (`string`): Link URL. -- title (`string`): Link title. -- type (`string`): Type of link entity. -- subtype (`string`): Subtype of link entity. +- `url` (`string`): Link URL. +- `title` (`string`, optional): Link title. +- `opensInNewTab` (`boolean`, optional): Whether link should open in a new browser tab.This value is only assigned if not providing a custom `settings` prop. ### settings diff --git a/packages/block-editor/src/components/link-control/index.js b/packages/block-editor/src/components/link-control/index.js index ab25b65e92350..d8e6fa4284fdc 100644 --- a/packages/block-editor/src/components/link-control/index.js +++ b/packages/block-editor/src/components/link-control/index.js @@ -32,15 +32,11 @@ import LinkControlSearchInput from './search-input'; * * @typedef WPLinkControlDefaultValue * - * @property {string|number} id Unique identifier of link. - * @property {string} url Link URL. - * @property {string} title Link title. - * @property {string} type Type of link entity. - * @property {string} subtype Subtype of link entity. - * @property {boolean} [opensInNewTab] Whether link should open in a new - * browser tab. This value is only - * assigned if not providing a custom - * settings array. + * @property {string} url Link URL. + * @property {string=} title Link title. + * @property {boolean=} opensInNewTab Whether link should open in a new browser + * tab. This value is only assigned if not + * providing a custom `settings` prop. */ /** From 1e55842183b6c072ba08306a3e2ccf2c28c167ce Mon Sep 17 00:00:00 2001 From: Andrew Duthie Date: Tue, 28 Jan 2020 12:13:37 -0500 Subject: [PATCH 3/3] Block Editor: LinkControl: Change documented example to reference known value property --- packages/block-editor/src/components/link-control/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/block-editor/src/components/link-control/README.md b/packages/block-editor/src/components/link-control/README.md index 98d49e9b49dea..64bde7b5658ce 100644 --- a/packages/block-editor/src/components/link-control/README.md +++ b/packages/block-editor/src/components/link-control/README.md @@ -52,7 +52,7 @@ Value change handler, called with the updated value if the user selects a new li ```jsx { - console.log( `The item selected has the ${ nextValue.id } id.` ); + console.log( `The selected item URL: ${ nextValue.url }.` ); } /> ```