Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update: Document and Remove experimental mark from URLPopover "subcomponents" #16566

Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 77 additions & 0 deletions packages/block-editor/src/components/url-popover/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
80 changes: 4 additions & 76 deletions packages/block-editor/src/components/url-popover/index.js
Original file line number Diff line number Diff line change
@@ -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() {
Expand Down Expand Up @@ -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
Expand Down
42 changes: 42 additions & 0 deletions packages/block-editor/src/components/url-popover/link-editor.js
Original file line number Diff line number Diff line change
@@ -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>
);
}
56 changes: 56 additions & 0 deletions packages/block-editor/src/components/url-popover/link-viewer.js
Original file line number Diff line number Diff line change
@@ -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 } ) {
Copy link
Member

@aduth aduth Dec 3, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Based on the file name, this probably should have been named LinkViewer. In any case, this specific naming doesn't adhere to capitalization guidelines, and it should at the very least be LinkViewerURL. Thankfully it doesn't seem to be part of the public API?

https://make.wordpress.org/core/handbook/best-practices/coding-standards/javascript/#abbreviations-and-acronyms

Edit: Oh, I see this file contains multiple components. In that case, I might have suggested each component get its own file.

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>
);
}
6 changes: 3 additions & 3 deletions packages/block-library/src/image/edit.js
Original file line number Diff line number Diff line change
Expand Up @@ -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 }
Expand All @@ -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
Expand Down
6 changes: 3 additions & 3 deletions packages/format-library/src/link/inline.js
Original file line number Diff line number Diff line change
Expand Up @@ -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 }
Expand All @@ -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' }
/>
) }
Expand Down