DotTip: Rename id attribute to tipId (#10317)

ramonjd · youknowriad · commit dfbda26c3eed · 2018-10-27T12:14:34.000+01:00
* Resolves #10305 by renaming `id` prop on `<DotTip />` to `tipId` to avoid using common DOM attributes as prop names. Updates prop names where we're using the component, including in README examples and documentation. Updates related unit tests and snapshot. Removes eslint exception. * Add deprecation
diff --git a/.eslintrc.js b/.eslintrc.js
@@ -155,10 +155,7 @@ module.exports = {
 				message: 'Prefer page.waitForSelector instead.',
 			},
 			{
-				// The <DotTip> component uses the `id` prop for something that does not require an
-				// instanceId; maybe we should change its key.
-				// See: https://github.com/WordPress/gutenberg/issues/10305
-				selector: 'JSXOpeningElement[name.name!="DotTip"] JSXAttribute[name.name="id"][value.type="Literal"]',
+				selector: 'JSXAttribute[name.name="id"][value.type="Literal"]',
 				message: 'Do not use string literals for IDs; use withInstanceId instead.',
 			},
 			{
diff --git a/docs/reference/deprecated.md b/docs/reference/deprecated.md
@@ -5,6 +5,7 @@ Gutenberg's deprecation policy is intended to support backwards-compatibility fo
 - `wp.date.getSettings` has been removed. Please use `wp.date.__experimentalGetSettings` instead.
 - `wp.compose.remountOnPropChange` has been removed.
 - The following editor store actions have been removed: `createNotice`, `removeNotice`, `createSuccessNotice`, `createInfoNotice`, `createErrorNotice`, `createWarningNotice`. Use the equivalent actions by the same name from the `@wordpress/notices` module.
+- The id prop of wp.nux.DotTip has been removed. Please use the tipId prop instead.
 
 ## 4.3.0
 
diff --git a/lib/client-assets.php b/lib/client-assets.php
@@ -550,6 +550,7 @@ function gutenberg_register_scripts_and_styles() {
 			'wp-components',
 			'wp-compose',
 			'wp-data',
+			'wp-deprecated',
 			'wp-i18n',
 			'wp-polyfill',
 			'lodash',
diff --git a/package-lock.json b/package-lock.json
diff --git a/packages/edit-post/src/components/header/header-toolbar/index.js b/packages/edit-post/src/components/header/header-toolbar/index.js
@@ -30,7 +30,7 @@ function HeaderToolbar( { hasFixedToolbar, isLargeViewport, mode } ) {
 			<FullscreenModeClose />
 			<div>
 				<Inserter disabled={ mode !== 'visual' } position="bottom right" />
-				<DotTip id="core/editor.inserter">
+				<DotTip tipId="core/editor.inserter">
 					{ __( 'Welcome to the wonderful world of blocks! Click the “+” (“Add block”) button to add a new block. There are blocks available for all kinds of content: you can insert text, headings, images, lists, and lots more!' ) }
 				</DotTip>
 			</div>
diff --git a/packages/edit-post/src/components/header/index.js b/packages/edit-post/src/components/header/index.js
@@ -59,7 +59,7 @@ function Header( {
 							aria-expanded={ isEditorSidebarOpened }
 							shortcut={ shortcuts.toggleSidebar }
 						/>
-						<DotTip id="core/editor.settings">
+						<DotTip tipId="core/editor.settings">
 							{ __( 'You’ll find more settings for your page and blocks in the sidebar. Click “Settings” to open it.' ) }
 						</DotTip>
 					</div>
diff --git a/packages/editor/src/components/post-preview-button/index.js b/packages/editor/src/components/post-preview-button/index.js
@@ -167,7 +167,7 @@ export class PostPreviewButton extends Component {
 				disabled={ ! isSaveable }
 			>
 				{ _x( 'Preview', 'imperative verb' ) }
-				<DotTip id="core/editor.preview">
+				<DotTip tipId="core/editor.preview">
 					{ __( 'Click “Preview” to load a preview of this page, so you can make sure you’re happy with your blocks.' ) }
 				</DotTip>
 			</Button>
diff --git a/packages/editor/src/components/post-preview-button/test/__snapshots__/index.js.snap b/packages/editor/src/components/post-preview-button/test/__snapshots__/index.js.snap
@@ -9,7 +9,7 @@ exports[`PostPreviewButton render() should match the snapshot 1`] = `
 >
   Preview
   <WithSelect(WithDispatch(DotTip))
-    id="core/editor.preview"
+    tipId="core/editor.preview"
   >
     Click “Preview” to load a preview of this page, so you can make sure you’re happy with your blocks.
   </WithSelect(WithDispatch(DotTip))>
diff --git a/packages/editor/src/components/post-publish-panel/toggle.js b/packages/editor/src/components/post-publish-panel/toggle.js
@@ -31,7 +31,7 @@ export function PostPublishPanelToggle( {
 			isBusy={ isSaving && isPublished }
 		>
 			{ isBeingScheduled ? __( 'Schedule…' ) : __( 'Publish…' ) }
-			<DotTip id="core/editor.publish">
+			<DotTip tipId="core/editor.publish">
 				{ __( 'Finished writing? That’s great, let’s get this published right now. Just click “Publish” and you’re good to go.' ) }
 			</DotTip>
 		</Button>
diff --git a/packages/nux/CHANGELOG.md b/packages/nux/CHANGELOG.md
@@ -1,3 +1,9 @@
+## 2.0.7 (Unreleased)
+
+### Deprecations
+
+- The id prop of DotTip has been deprecated. Please use the tipId prop instead.
+
 ## 2.0.6 (2018-10-22)
 
 ## 2.0.5 (2018-10-19)
diff --git a/packages/nux/README.md b/packages/nux/README.md
@@ -18,7 +18,7 @@ _This package assumes that your code will run in an **ES2015+** environment. If
 
 ## DotTip
 
-`DotTip` is a React component that renders a single _tip_ on the screen. The tip will point to the React element that `DotTip` is nested within. Each tip is uniquely identified by a string passed to `id`.
+`DotTip` is a React component that renders a single _tip_ on the screen. The tip will point to the React element that `DotTip` is nested within. Each tip is uniquely identified by a string passed to `tipId`.
 
 See [the component's README][dot-tip-readme] for more information.
 
@@ -27,7 +27,7 @@ See [the component's README][dot-tip-readme] for more information.
 ```jsx
 <button onClick={ ... }>
 	Add to Cart
-	<DotTip id="acme/add-to-cart">
+	<DotTip tipId="acme/add-to-cart">
 		Click here to add the product to your shopping cart.
 	</DotTip>
 </button>
diff --git a/packages/nux/package.json b/packages/nux/package.json
@@ -24,6 +24,7 @@
 		"@wordpress/components": "file:../components",
 		"@wordpress/compose": "file:../compose",
 		"@wordpress/data": "file:../data",
+		"@wordpress/deprecated": "file:../deprecated",
 		"@wordpress/element": "file:../element",
 		"@wordpress/i18n": "file:../i18n",
 		"lodash": "^4.17.10",
diff --git a/packages/nux/src/components/dot-tip/README.md b/packages/nux/src/components/dot-tip/README.md
@@ -1,14 +1,14 @@
 DotTip
 ========
 
-`DotTip` is a React component that renders a single _tip_ on the screen. The tip will point to the React element that `DotTip` is nested within. Each tip is uniquely identified by a string passed to `id`.
+`DotTip` is a React component that renders a single _tip_ on the screen. The tip will point to the React element that `DotTip` is nested within. Each tip is uniquely identified by a string passed to `tipId`.
 
 ## Usage
 
 ```jsx
 <button onClick={ ... }>
 	Add to Cart
-	<DotTip id="acme/add-to-cart">
+	<DotTip tipId="acme/add-to-cart">
 		Click here to add the product to your shopping cart.
 	</DotTip>
 </button>
@@ -19,7 +19,7 @@ DotTip
 
 The component accepts the following props:
 
-### id
+### tipId
 
 A string that uniquely identifies the tip. Identifiers should be prefixed with the name of the plugin, followed by a `/`. For example, `acme/add-to-cart`.
 
diff --git a/packages/nux/src/components/dot-tip/index.js b/packages/nux/src/components/dot-tip/index.js
@@ -5,6 +5,7 @@ import { compose } from '@wordpress/compose';
 import { Popover, Button, IconButton } from '@wordpress/components';
 import { __ } from '@wordpress/i18n';
 import { withSelect, withDispatch } from '@wordpress/data';
+import { deprecated } from '@wordpress/deprecated';
 
 function getAnchorRect( anchor ) {
 	// The default getAnchorRect() excludes an element's top and bottom padding
@@ -58,19 +59,27 @@ export function DotTip( {
 }
 
 export default compose(
-	withSelect( ( select, { id } ) => {
+	withSelect( ( select, { tipId, id } ) => {
+		if ( id ) {
+			tipId = id;
+			deprecated( 'The id prop of wp.nux.DotTip', {
+				plugin: 'Gutenberg',
+				version: '4.4',
+				alternative: 'the tipId prop',
+			} );
+		}
 		const { isTipVisible, getAssociatedGuide } = select( 'core/nux' );
-		const associatedGuide = getAssociatedGuide( id );
+		const associatedGuide = getAssociatedGuide( tipId );
 		return {
-			isVisible: isTipVisible( id ),
+			isVisible: isTipVisible( tipId ),
 			hasNextTip: !! ( associatedGuide && associatedGuide.nextTipId ),
 		};
 	} ),
-	withDispatch( ( dispatch, { id } ) => {
+	withDispatch( ( dispatch, { tipId, id } ) => {
 		const { dismissTip, disableTips } = dispatch( 'core/nux' );
 		return {
 			onDismiss() {
-				dismissTip( id );
+				dismissTip( tipId || id );
 			},
 			onDisable() {
 				disableTips();

Original file line number	Diff line number	Diff line change
`@@ -155,10 +155,7 @@ module.exports = {`
`155`	`155`	`message: 'Prefer page.waitForSelector instead.',`
`156`	`156`	`},`
`157`	`157`	`{`
`158`		- // The <DotTip> component uses the `id` prop for something that does not require an
`159`		`- // instanceId; maybe we should change its key.`
`160`		`- // See: https://github.com/WordPress/gutenberg/issues/10305`
`161`		`- selector: 'JSXOpeningElement[name.name!="DotTip"] JSXAttribute[name.name="id"][value.type="Literal"]',`
	`158`	`+ selector: 'JSXAttribute[name.name="id"][value.type="Literal"]',`
`162`	`159`	`message: 'Do not use string literals for IDs; use withInstanceId instead.',`
`163`	`160`	`},`
`164`	`161`	`{`
Original file line number	Diff line number	Diff line change
`@@ -167,7 +167,7 @@ export class PostPreviewButton extends Component {`
`167`	`167`	`disabled={ ! isSaveable }`
`168`	`168`	`>`
`169`	`169`	`{ _x( 'Preview', 'imperative verb' ) }`
`170`		`- <DotTip id="core/editor.preview">`
	`170`	`+ <DotTip tipId="core/editor.preview">`
`171`	`171`	`{ __( 'Click “Preview” to load a preview of this page, so you can make sure you’re happy with your blocks.' ) }`
`172`	`172`	`</DotTip>`
`173`	`173`	`</Button>`
Original file line number	Diff line number	Diff line change
@@ -9,7 +9,7 @@ exports[`PostPreviewButton render() should match the snapshot 1`] = `
`9`	`9`	`>`
`10`	`10`	`Preview`
`11`	`11`	`<WithSelect(WithDispatch(DotTip))`
`12`		`- id="core/editor.preview"`
	`12`	`+ tipId="core/editor.preview"`
`13`	`13`	`>`
`14`	`14`	`Click “Preview” to load a preview of this page, so you can make sure you’re happy with your blocks.`
`15`	`15`	`</WithSelect(WithDispatch(DotTip))>`
Original file line number	Diff line number	Diff line change
`@@ -31,7 +31,7 @@ export function PostPublishPanelToggle( {`
`31`	`31`	`isBusy={ isSaving && isPublished }`
`32`	`32`	`>`
`33`	`33`	`{ isBeingScheduled ? __( 'Schedule…' ) : __( 'Publish…' ) }`
`34`		`- <DotTip id="core/editor.publish">`
	`34`	`+ <DotTip tipId="core/editor.publish">`
`35`	`35`	`{ __( 'Finished writing? That’s great, let’s get this published right now. Just click “Publish” and you’re good to go.' ) }`
`36`	`36`	`</DotTip>`
`37`	`37`	`</Button>`