diff --git a/packages/block-editor/src/components/link-control/README.md b/packages/block-editor/src/components/link-control/README.md index 158ef9d4c95ea..64bde7b5658ce 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,16 @@ - 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: + +- `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 - Type: `Array` @@ -33,14 +47,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 selected item URL: ${ nextValue.url }.` ); } /> ``` +### 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..d8e6fa4284fdc 100644 --- a/packages/block-editor/src/components/link-control/index.js +++ b/packages/block-editor/src/components/link-control/index.js @@ -27,6 +27,62 @@ 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} 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. + */ + +/** + * 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 +213,19 @@ function LinkControl( { return (
- { ( ! isEditingLink ) && ( + { isEditingLink || ! value ? + { + setIsEditingLink( false ); + onChange( { ...value, ...suggestion } ); + } } + renderSuggestions={ renderSearchResults } + fetchSuggestions={ getSearchHandler } + onReset={ resetInput } + showInitialSuggestions={ showInitialSuggestions } + /> :

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

+ - ) } - - { isEditingLink && ( - { - setIsEditingLink( false ); - onChange( { ...value, ...suggestion } ); - } } - renderSuggestions={ renderSearchResults } - fetchSuggestions={ getSearchHandler } - onReset={ resetInput } - showInitialSuggestions={ showInitialSuggestions } - /> - ) } - - { ! isEditingLink && ( - - ) } + } ); }