Update: Document and Remove experimental mark from URLPopover.LinkVie…

…wer and URLPopover.LinkEditor. (#16566)
WordPress · Jul 29, 2019 · 442ff9d · 442ff9d
1 parent f598210
commit 442ff9d
Show file tree

Hide file tree

Showing 6 changed files with 185 additions and 82 deletions.
diff --git a/packages/block-editor/src/components/url-popover/README.md b/packages/block-editor/src/components/url-popover/README.md
@@ -111,3 +111,80 @@ drawer.
 
 - Type: `Function`
 - Required: No
+
+
+## Useful UI pieces
+
+The URLPopover exposes two components that may be used as child components to make the UI creation process easier.
+Although in the editor these components are used inside URLPopover and they were built with URLPopover use cases in mind, it maybe is possible and perfectly fine to use them standalone if they fit a use-case.
+
+### LinkViewer
+
+LinkViewer provides a simple UI that allows users to see a link and may also offer a button to switch to a mode that will enable editing that link.
+The component accepts the following props. Any other props are passed through to the underlying `div` container.
+
+### className
+
+A class that together with "block-editor-url-popover__link-viewer" is used as a class of the wrapper div.
+If no className is passed only "block-editor-url-popover__link-viewer" is used.
+
+- Type: `String`
+- Required: No
+
+### linkClassName
+
+A class that will be used in the component that renders the link. 
+
+- Type: `String`
+- Required: No
+
+### url
+
+The current URL to view.
+
+- Type: `String`
+- Required: Yes
+
+### urlLabel
+
+The URL label, if not passed a label is automatically generated from the `url`.
+
+- Type: `String`
+- Required: No
+
+### onEditLinkClick
+
+A function called when the user presses the button that allows editing a link. If not passed the link-edit button is not rendered.
+
+- Type: `function`
+- Required: No
+
+
+### LinkEditor
+
+LinkEditor provides a simple UI that allows users to edit link.
+The component accepts the following props. Any other props are passed through to the underlying `form` container.
+
+### value
+
+This property should be set to the attribute (or component state) property used to store the URL.
+This property is directly passed to  `URLInput` component ([refer to its documentation](/packages/components/src/url-input/README.md)) to read additional details.
+
+- Type: `String`
+- Required: Yes
+
+### onChange
+
+Called when the value changes. The second parameter is `null` unless the user selects a post from the suggestions dropdown.
+More
+This property is directly passed to component `URLInput` ([refer to its documentation](/packages/components/src/url-input/README.md)) to read additional details.
+
+- Type: `function`
+- Required: Yes
+
+### autocompleteRef
+
+Reference passed to the auto complete element of the ([URLInput component](/packages/components/src/url-input/README.md)).
+
+- Type: `Object`
+- Required: no
diff --git a/packages/block-editor/src/components/url-popover/index.js b/packages/block-editor/src/components/url-popover/index.js
@@ -1,24 +1,18 @@
-/**
- * External dependencies
- */
-import classnames from 'classnames';
-
 /**
  * WordPress dependencies
  */
 import { __ } from '@wordpress/i18n';
 import { Component } from '@wordpress/element';
 import {
-	ExternalLink,
 	IconButton,
 	Popover,
 } from '@wordpress/components';
-import { safeDecodeURI, filterURLForDisplay } from '@wordpress/url';
 
 /**
  * Internal dependencies
  */
-import URLInput from '../url-input';
+import LinkViewer from './link-viewer';
+import LinkEditor from './link-editor';
 
 class URLPopover extends Component {
 	constructor() {
@@ -91,75 +85,9 @@ class URLPopover extends Component {
 	}
 }
 
-const LinkEditor = ( {
-	autocompleteRef,
-	className,
-	onChangeInputValue,
-	value,
-	...props
-} ) => (
-	<form
-		className={ classnames(
-			'block-editor-url-popover__link-editor',
-			className
-		) }
-		{ ...props }
-	>
-		<URLInput
-			value={ value }
-			onChange={ onChangeInputValue }
-			autocompleteRef={ autocompleteRef }
-		/>
-		<IconButton icon="editor-break" label={ __( 'Apply' ) } type="submit" />
-
-	</form>
-);
-
-URLPopover.__experimentalLinkEditor = LinkEditor;
-
-const LinkViewerUrl = ( { url, urlLabel, className } ) => {
-	const linkClassName = classnames(
-		className,
-		'block-editor-url-popover__link-viewer-url'
-	);
-
-	if ( ! url ) {
-		return <span className={ linkClassName }></span>;
-	}
-
-	return (
-		<ExternalLink
-			className={ linkClassName }
-			href={ url }
-		>
-			{ urlLabel || filterURLForDisplay( safeDecodeURI( url ) ) }
-		</ExternalLink>
-	);
-};
-
-const LinkViewer = ( {
-	className,
-	url,
-	urlLabel,
-	editLink,
-	linkClassName,
-	...props
-} ) => {
-	return (
-		<div
-			className={ classnames(
-				'block-editor-url-popover__link-viewer',
-				className
-			) }
-			{ ...props }
-		>
-			<LinkViewerUrl url={ url } urlLabel={ urlLabel } className={ linkClassName } />
-			<IconButton icon="edit" label={ __( 'Edit' ) } onClick={ editLink } />
-		</div>
-	);
-};
+URLPopover.LinkEditor = LinkEditor;
 
-URLPopover.__experimentalLinkViewer = LinkViewer;
+URLPopover.LinkViewer = LinkViewer;
 
 /**
  * @see https://github.com/WordPress/gutenberg/blob/master/packages/block-editor/src/components/url-popover/README.md

diff --git a/packages/block-editor/src/components/url-popover/link-editor.js b/packages/block-editor/src/components/url-popover/link-editor.js
@@ -0,0 +1,42 @@
+/**
+ * External dependencies
+ */
+import classnames from 'classnames';
+
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+import {
+	IconButton,
+} from '@wordpress/components';
+
+/**
+ * Internal dependencies
+ */
+import URLInput from '../url-input';
+
+export default function LinkEditor( {
+	autocompleteRef,
+	className,
+	onChangeInputValue,
+	value,
+	...props
+} ) {
+	return (
+		<form
+			className={ classnames(
+				'block-editor-url-popover__link-editor',
+				className
+			) }
+			{ ...props }
+		>
+			<URLInput
+				value={ value }
+				onChange={ onChangeInputValue }
+				autocompleteRef={ autocompleteRef }
+			/>
+			<IconButton icon="editor-break" label={ __( 'Apply' ) } type="submit" />
+		</form>
+	);
+}
diff --git a/packages/block-editor/src/components/url-popover/link-viewer.js b/packages/block-editor/src/components/url-popover/link-viewer.js
@@ -0,0 +1,56 @@
+/**
+ * External dependencies
+ */
+import classnames from 'classnames';
+
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+import {
+	ExternalLink,
+	IconButton,
+} from '@wordpress/components';
+import { safeDecodeURI, filterURLForDisplay } from '@wordpress/url';
+
+function LinkViewerUrl( { url, urlLabel, className } ) {
+	const linkClassName = classnames(
+		className,
+		'block-editor-url-popover__link-viewer-url'
+	);
+
+	if ( ! url ) {
+		return <span className={ linkClassName }></span>;
+	}
+
+	return (
+		<ExternalLink
+			className={ linkClassName }
+			href={ url }
+		>
+			{ urlLabel || filterURLForDisplay( safeDecodeURI( url ) ) }
+		</ExternalLink>
+	);
+}
+
+export default function LinkViewer( {
+	className,
+	linkClassName,
+	onEditLinkClick,
+	url,
+	urlLabel,
+	...props
+} ) {
+	return (
+		<div
+			className={ classnames(
+				'block-editor-url-popover__link-viewer',
+				className
+			) }
+			{ ...props }
+		>
+			<LinkViewerUrl url={ url } urlLabel={ urlLabel } className={ linkClassName } />
+			{ onEditLinkClick && <IconButton icon="edit" label={ __( 'Edit' ) } onClick={ onEditLinkClick } /> }
+		</div>
+	);
+}
diff --git a/packages/block-library/src/image/edit.js b/packages/block-library/src/image/edit.js
@@ -229,7 +229,7 @@ const ImageURLInputUI = ( {
 					) }
 				>
 					{ ( ! url || isEditingLink ) && (
-						<URLPopover.__experimentalLinkEditor
+						<URLPopover.LinkEditor
 							className="editor-format-toolbar__link-container-content block-editor-format-toolbar__link-container-content"
 							value={ linkEditorValue }
 							onChangeInputValue={ setUrlInput }
@@ -241,11 +241,11 @@ const ImageURLInputUI = ( {
 					) }
 					{ ( url && ! isEditingLink ) && (
 						<>
-							<URLPopover.__experimentalLinkViewer
+							<URLPopover.LinkViewer
 								className="editor-format-toolbar__link-container-content block-editor-format-toolbar__link-container-content"
 								onKeyPress={ stopPropagation }
 								url={ url }
-								editLink={ startEditLink }
+								onEditLinkClick={ startEditLink }
 								urlLabel={ urlLabel }
 							/>
 							<IconButton

diff --git a/packages/format-library/src/link/inline.js b/packages/format-library/src/link/inline.js
@@ -210,7 +210,7 @@ class InlineLinkUI extends Component {
 				) }
 			>
 				{ showInput ? (
-					<URLPopover.__experimentalLinkEditor
+					<URLPopover.LinkEditor
 						className="editor-format-toolbar__link-container-content block-editor-format-toolbar__link-container-content"
 						value={ inputValue }
 						onChangeInputValue={ this.onChangeInputValue }
@@ -220,11 +220,11 @@ class InlineLinkUI extends Component {
 						autocompleteRef={ this.autocompleteRef }
 					/>
 				) : (
-					<URLPopover.__experimentalLinkViewer
+					<URLPopover.LinkViewer
 						className="editor-format-toolbar__link-container-content block-editor-format-toolbar__link-container-content"
 						onKeyPress={ stopKeyPropagation }
 						url={ url }
-						editLink={ this.editLink }
+						onEditLinkClick={ this.editLink }
 						linkClassName={ isValidHref( prependHTTP( url ) ) ? undefined : 'has-invalid-link' }
 					/>
 				) }