From a7fbd6e6a939666c630ca86cf73a3b4fb5034db7 Mon Sep 17 00:00:00 2001
From: Riad Benguella
Date: Fri, 7 Feb 2020 14:28:45 +0100
Subject: [PATCH] Prefer @wordpress/icons over dashicons in docs and tests
(#20094)
---
.../block-api/block-registration.md | 173 +++++++++++-------
.../slotfills/plugin-more-menu-item.md | 12 +-
.../plugin-sidebar-more-menu-item.md | 14 +-
.../developers/slotfills/plugin-sidebar.md | 18 +-
.../src/components/block-icon/test/index.js | 9 +-
packages/components/src/button/test/index.js | 33 ++--
packages/components/src/draggable/README.md | 79 ++++----
.../components/src/draggable/stories/index.js | 4 +-
.../components/src/dropdown-menu/README.md | 14 +-
.../components/src/dropdown/stories/index.js | 12 +-
packages/components/src/icon/README.md | 40 ++--
.../test/__snapshots__/index.js.snap | 28 ++-
.../components/src/menu-item/test/index.js | 9 +-
.../src/mobile/stepper-control/README.md | 60 +++---
packages/components/src/panel/README.md | 81 ++++----
packages/components/src/placeholder/README.md | 21 +--
.../components/src/placeholder/test/index.js | 7 +-
packages/edit-post/README.md | 36 ++--
.../header/plugin-more-menu-item/index.js | 14 +-
.../test/__snapshots__/index.js.snap | 6 +-
.../plugin-more-menu-item/test/index.js | 5 +-
.../plugin-sidebar-more-menu-item/index.js | 10 +-
.../sidebar/plugin-sidebar/index.js | 12 +-
packages/plugins/README.md | 10 +-
packages/plugins/src/api/index.js | 10 +-
storybook/test/__snapshots__/index.js.snap | 27 ++-
26 files changed, 415 insertions(+), 329 deletions(-)
diff --git a/docs/designers-developers/developers/block-api/block-registration.md b/docs/designers-developers/developers/block-api/block-registration.md
index f69cc31ee0a984..e31115ea459b87 100644
--- a/docs/designers-developers/developers/block-api/block-registration.md
+++ b/docs/designers-developers/developers/block-api/block-registration.md
@@ -2,13 +2,13 @@
## `registerBlockType`
-* **Type:** `Function`
+- **Type:** `Function`
Every block starts by registering a new block type definition. To register, you use the `registerBlockType` function from the [`wp-blocks` package](/packages/blocks/README.md#registerBlockType). The function takes two arguments, a block `name` and a block configuration object.
### Block Name
-* **Type:** `String`
+- **Type:** `String`
The name for a block is a unique string that identifies a block. Names have to be structured as `namespace/block-name`, where namespace is the name of your plugin or theme.
@@ -17,50 +17,50 @@ The name for a block is a unique string that identifies a block. Names have to b
registerBlockType( 'my-plugin/book', {} );
```
-*Note:* A block name can only contain lowercase alphanumeric characters and dashes, and must begin with a letter.
+_Note:_ A block name can only contain lowercase alphanumeric characters and dashes, and must begin with a letter.
-*Note:* This name is used on the comment delimiters as ``. Those blocks provided by core don't include a namespace when serialized.
+_Note:_ This name is used on the comment delimiters as ``. Those blocks provided by core don't include a namespace when serialized.
### Block Configuration
-* **Type:** `Object` [ `{ key: value }` ]
+- **Type:** `Object` [ `{ key: value }` ]
A block requires a few properties to be specified before it can be registered successfully. These are defined through a configuration object, which includes the following:
#### title
-* **Type:** `String`
+- **Type:** `String`
This is the display title for your block, which can be translated with our translation functions. The block inserter will show this name.
```js
// Our data object
-title: __( 'Book' )
+title: __( 'Book' );
```
#### description (optional)
-* **Type:** `String`
+- **Type:** `String`
This is a short description for your block, which can be translated with our translation functions. This will be shown in the Block Tab in the Settings Sidebar.
```js
-description: __( 'Block showing a Book card.' )
+description: __( 'Block showing a Book card.' );
```
#### category
-* **Type:** `String` [ common | formatting | layout | widgets | embed ]
+- **Type:** `String` [ common | formatting | layout | widgets | embed ]
Blocks are grouped into categories to help users browse and discover them.
The core provided categories are:
-* common
-* formatting
-* layout
-* widgets
-* embed
+- common
+- formatting
+- layout
+- widgets
+- embed
```js
// Assigning to the 'widgets' category
@@ -71,7 +71,7 @@ Plugins and Themes can also register [custom block categories](/docs/designers-d
#### icon (optional)
-* **Type:** `String` | `Object`
+- **Type:** `String` | `Object`
An icon property should be specified to make it easier to identify a block. These can be any of [WordPress' Dashicons](https://developer.wordpress.org/resource/dashicons/), or a custom `svg` element.
@@ -95,14 +95,14 @@ icon: {
background: '#7e70af',
// Specifying a color for the icon (optional: if not set, a readable color will be automatically defined)
foreground: '#fff',
- // Specifying a dashicon for the block
- src: 'book-alt',
+ // Specifying an icon for the block
+ src: ,
} ,
```
#### keywords (optional)
-* **Type:** `Array`
+- **Type:** `Array`
Sometimes a block could have aliases that help users discover it while searching. For example, an `image` block could also want to be discovered by `photo`. You can do so by providing an array of terms (which can be translated).
@@ -114,7 +114,7 @@ keywords: [ __( 'image' ), __( 'photo' ), __( 'pics' ) ],
#### styles (optional)
-* **Type:** `Array`
+- **Type:** `Array`
Block styles can be used to provide alternative styles to block. It works by adding a class name to the block’s wrapper. Using CSS, a theme developer can target the class name for the style variation if it is selected.
@@ -142,7 +142,7 @@ Plugins and Themes can also register [custom block style](/docs/designers-develo
#### attributes (optional)
-* **Type:** `Object`
+- **Type:** `Object`
Attributes provide the structured data needs of a block. They can exist in different forms when they are serialized, but they are declared together under a common interface.
@@ -166,11 +166,11 @@ attributes: {
},
```
-* **See: [Attributes](/docs/designers-developers/developers/block-api/block-attributes.md).**
+- **See: [Attributes](/docs/designers-developers/developers/block-api/block-attributes.md).**
#### example (optional)
-* **Type:** `Object`
+- **Type:** `Object`
Example provides structured example data for the block. This data is used to construct a preview for the block to be shown in the Inspector Help Panel when the user mouses over the block.
@@ -190,7 +190,7 @@ If `example` is not defined, the preview will not be shown. So even if no-attrib
#### transforms (optional)
-* **Type:** `Array`
+- **Type:** `Array`
Transforms provide rules for what a block can be transformed from and what it can be transformed to. A block can be transformed from another block, a shortcode, a regular expression, a file or a raw DOM node.
@@ -198,6 +198,7 @@ For example, a Paragraph block can be transformed into a Heading block. This use
{% codetabs %}
{% ES5 %}
+
```js
transforms: {
from: [
@@ -213,7 +214,9 @@ transforms: {
]
},
```
+
{% ESNext %}
+
```js
transforms: {
from: [
@@ -229,12 +232,14 @@ transforms: {
]
},
```
+
{% end %}
An existing shortcode can be transformed into its block counterpart.
{% codetabs %}
{% ES5 %}
+
```js
transforms: {
from: [
@@ -263,7 +268,9 @@ transforms: {
]
},
```
+
{% ESNext %}
+
```js
transforms: {
from: [
@@ -292,12 +299,14 @@ transforms: {
},
```
+
{% end %}
A block can also be transformed into another block type. For example, a Heading block can be transformed into a Paragraph block.
{% codetabs %}
{% ES5 %}
+
```js
transforms: {
to: [
@@ -313,7 +322,9 @@ transforms: {
],
},
```
+
{% ESNext %}
+
```js
transforms: {
to: [
@@ -329,12 +340,14 @@ transforms: {
],
},
```
+
{% end %}
In addition to accepting an array of known block types, the `blocks` option also accepts a "wildcard" (`"*"`). This allows for transformations which apply to _all_ block types (eg: all blocks can transform into `core/group`):
{% codetabs %}
{% ES5 %}
+
```js
transforms: {
from: [
@@ -348,7 +361,9 @@ transforms: {
],
},
```
+
{% ESNext %}
+
```js
transforms: {
from: [
@@ -362,13 +377,14 @@ transforms: {
],
},
```
-{% end %}
+{% end %}
A block with InnerBlocks can also be transformed from and to another block with InnerBlocks.
{% codetabs %}
{% ES5 %}
+
```js
transforms: {
to: [
@@ -382,7 +398,9 @@ transforms: {
],
},
```
+
{% ESNext %}
+
```js
transforms: {
to: [
@@ -396,12 +414,14 @@ transforms: {
],
},
```
+
{% end %}
An optional `isMatch` function can be specified on a transform object. This provides an opportunity to perform additional checks on whether a transform should be possible. Returning `false` from this function will prevent the transform from being displayed as an option to the user.
{% codetabs %}
{% ES5 %}
+
```js
transforms: {
to: [
@@ -420,7 +440,9 @@ transforms: {
],
},
```
+
{% ESNext %}
+
```js
transforms: {
to: [
@@ -437,25 +459,29 @@ transforms: {
],
},
```
+
{% end %}
In the case of shortcode transforms, `isMatch` receives shortcode attributes per the [Shortcode API](https://codex.wordpress.org/Shortcode_API):
{% codetabs %}
{% ES5 %}
+
```js
isMatch: function( attributes ) {
return attributes.named.id === 'my-id';
},
```
+
{% ESNext %}
+
```js
isMatch( { named: { id } } ) {
return id === 'my-id';
},
```
-{% end %}
+{% end %}
To control the priority with which a transform is applied, define a `priority` numeric property on your transform object, where a lower value will take precedence over higher values. This behaves much like a [WordPress hook](https://codex.wordpress.org/Plugin_API#Hook_to_WordPress). Like hooks, the default priority is `10` when not otherwise set.
@@ -463,12 +489,13 @@ A file can be dropped into the editor and converted into a block with a matching
{% codetabs %}
{% ES5 %}
+
```js
transforms: {
from: [
{
type: 'files',
- isMatch: function ( files ) {
+ isMatch: function( files ) {
return files.length === 1;
},
// We define a lower priority (higher number) than the default of 10. This
@@ -486,10 +513,12 @@ transforms: {
} );
},
},
- ]
+ ];
}
```
+
{% ESNext %}
+
```js
transforms: {
from: [
@@ -511,52 +540,56 @@ transforms: {
} );
},
},
- ]
+ ];
}
```
+
{% end %}
A prefix transform is a transform that will be applied if the user prefixes some text in e.g. the Paragraph block with a given pattern and a trailing space.
{% codetabs %}
{% ES5 %}
+
```js
transforms: {
- from: [
- {
- type: 'prefix',
- prefix: '?',
- transform: function( content ) {
- return createBlock( 'my-plugin/question', {
- content,
- } );
- },
- },
- ]
+ from: [
+ {
+ type: 'prefix',
+ prefix: '?',
+ transform: function( content ) {
+ return createBlock( 'my-plugin/question', {
+ content,
+ } );
+ },
+ },
+ ];
}
```
+
{% ESNext %}
+
```js
transforms: {
- from: [
- {
- type: 'prefix',
- prefix: '?',
- transform( content ) {
- return createBlock( 'my-plugin/question', {
- content,
- } );
- },
- },
- ]
+ from: [
+ {
+ type: 'prefix',
+ prefix: '?',
+ transform( content ) {
+ return createBlock( 'my-plugin/question', {
+ content,
+ } );
+ },
+ },
+ ];
}
```
-{% end %}
+{% end %}
#### parent (optional)
-* **Type:** `Array`
+- **Type:** `Array`
Blocks are able to be inserted into blocks that use [`InnerBlocks`](https://github.com/WordPress/gutenberg/blob/master/packages/block-editor/src/components/inner-blocks/README.md) as nested content. Sometimes it is useful to restrict a block so that it is only available as a nested block. For example, you might want to allow an 'Add to Cart' block to only be available within a 'Product' block.
@@ -569,13 +602,13 @@ parent: [ 'core/columns' ],
#### supports (optional)
-*Some [block supports](#supports-optional) — for example, `anchor` or `className` — apply their attributes by adding additional props on the element returned by `save`. This will work automatically for default HTML tag elements (`div`, etc). However, if the return value of your `save` is a custom component element, you will need to ensure that your custom component handles these props in order for the attributes to be persisted.*
+_Some [block supports](#supports-optional) — for example, `anchor` or `className` — apply their attributes by adding additional props on the element returned by `save`. This will work automatically for default HTML tag elements (`div`, etc). However, if the return value of your `save` is a custom component element, you will need to ensure that your custom component handles these props in order for the attributes to be persisted._
-* **Type:** `Object`
+- **Type:** `Object`
Optional block extended support features. The following options are supported:
-- `align` (default `false`): This property adds block controls which allow to change block's alignment. _Important: It doesn't work with dynamic blocks yet._
+- `align` (default `false`): This property adds block controls which allow to change block's alignment. _Important: It doesn't work with dynamic blocks yet._
```js
// Add the support for block's alignment (left, center, right, wide, full).
@@ -583,9 +616,11 @@ align: true,
// Pick which alignment options to display.
align: [ 'left', 'right', 'full' ],
```
+
When supports align is used the block attributes definition is extended to include an align attribute with a string type.
By default, no alignment is assigned to the block.
The block can apply a default alignment by specifying its own align attribute with a default e.g.:
+
```
attributes: {
...
@@ -597,57 +632,57 @@ attributes: {
}
```
-- `alignWide` (default `true`): This property allows to enable [wide alignment](/docs/designers-developers/developers/themes/theme-support.md#wide-alignment) for your theme. To disable this behavior for a single block, set this flag to `false`.
+- `alignWide` (default `true`): This property allows to enable [wide alignment](/docs/designers-developers/developers/themes/theme-support.md#wide-alignment) for your theme. To disable this behavior for a single block, set this flag to `false`.
```js
// Remove the support for wide alignment.
alignWide: false,
```
-- `anchor` (default `false`): Anchors let you link directly to a specific block on a page. This property adds a field to define an id for the block and a button to copy the direct link.
+- `anchor` (default `false`): Anchors let you link directly to a specific block on a page. This property adds a field to define an id for the block and a button to copy the direct link.
```js
// Add the support for an anchor link.
anchor: true,
```
-- `customClassName` (default `true`): This property adds a field to define a custom className for the block's wrapper.
+- `customClassName` (default `true`): This property adds a field to define a custom className for the block's wrapper.
```js
// Remove the support for the custom className.
customClassName: false,
```
-- `className` (default `true`): By default, the class `.wp-block-your-block-name` is added to the root element of your saved markup. This helps having a consistent mechanism for styling blocks that themes and plugins can rely on. If for whatever reason a class is not desired on the markup, this functionality can be disabled.
+- `className` (default `true`): By default, the class `.wp-block-your-block-name` is added to the root element of your saved markup. This helps having a consistent mechanism for styling blocks that themes and plugins can rely on. If for whatever reason a class is not desired on the markup, this functionality can be disabled.
```js
// Remove the support for the generated className.
className: false,
```
-- `html` (default `true`): By default, a block's markup can be edited individually. To disable this behavior, set `html` to `false`.
+- `html` (default `true`): By default, a block's markup can be edited individually. To disable this behavior, set `html` to `false`.
```js
// Remove support for an HTML mode.
html: false,
```
-- `inserter` (default `true`): By default, all blocks will appear in the inserter. To hide a block so that it can only be inserted programmatically, set `inserter` to `false`.
+- `inserter` (default `true`): By default, all blocks will appear in the inserter. To hide a block so that it can only be inserted programmatically, set `inserter` to `false`.
```js
// Hide this block from the inserter.
inserter: false,
```
-- `multiple` (default `true`): A non-multiple block can be inserted into each post, one time only. For example, the built-in 'More' block cannot be inserted again if it already exists in the post being edited. A non-multiple block's icon is automatically dimmed (unclickable) to prevent multiple instances.
+- `multiple` (default `true`): A non-multiple block can be inserted into each post, one time only. For example, the built-in 'More' block cannot be inserted again if it already exists in the post being edited. A non-multiple block's icon is automatically dimmed (unclickable) to prevent multiple instances.
```js
// Use the block just once per post
multiple: false,
```
-- `reusable` (default `true`): A block may want to disable the ability of being converted into a reusable block.
-By default all blocks can be converted to a reusable block. If supports reusable is set to false, the option to convert the block into a reusable block will not appear.
+- `reusable` (default `true`): A block may want to disable the ability of being converted into a reusable block.
+ By default all blocks can be converted to a reusable block. If supports reusable is set to false, the option to convert the block into a reusable block will not appear.
```js
// Don't allow the block to be converted into a reusable block.
@@ -658,7 +693,7 @@ reusable: false,
## `registerBlockCollection`
-* **Type:** `Function`
+- **Type:** `Function`
Blocks can be added to collections, grouping together all blocks from the same origin
@@ -666,7 +701,7 @@ Blocks can be added to collections, grouping together all blocks from the same o
### Namespace
-* **Type:** `String`
+- **Type:** `String`
This should match the namespace declared in the block name; the name of your plugin or theme.
@@ -674,13 +709,13 @@ This should match the namespace declared in the block name; the name of your plu
#### Title
-* **Type:** `String`
+- **Type:** `String`
This will display in the block inserter section, which will list all blocks in this collection.
#### Icon
-* **Type:** `Object`
+- **Type:** `Object`
(Optional) An icon to display alongside the title in the block inserter.
diff --git a/docs/designers-developers/developers/slotfills/plugin-more-menu-item.md b/docs/designers-developers/developers/slotfills/plugin-more-menu-item.md
index 23efd6a021685c..5625d33f03f6e8 100644
--- a/docs/designers-developers/developers/slotfills/plugin-more-menu-item.md
+++ b/docs/designers-developers/developers/slotfills/plugin-more-menu-item.md
@@ -5,13 +5,16 @@ This slot will add a new item to the More Tools & Options section.
## Example
```js
-const { registerPlugin } = wp.plugins;
-const { PluginMoreMenuItem } = wp.editPost;
+import { registerPlugin } from '@wordpress/plugins';
+import { PluginMoreMenuItem } from '@wordpress/edit-post';
+import { image } from '@wordpress/icons';
const MyButtonMoreMenuItemTest = () => (
{ alert( 'Button Clicked' ) } }
+ icon={ image }
+ onClick={ () => {
+ alert( 'Button Clicked' );
+ } }
>
More Menu Item
@@ -23,4 +26,3 @@ registerPlugin( 'more-menu-item-test', { render: MyButtonMoreMenuItemTest } );
## Location
![Location](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/assets/plugin-more-menu-item.png?raw=true)
-
diff --git a/docs/designers-developers/developers/slotfills/plugin-sidebar-more-menu-item.md b/docs/designers-developers/developers/slotfills/plugin-sidebar-more-menu-item.md
index 5bd43819501e74..40d1e0e22bab54 100644
--- a/docs/designers-developers/developers/slotfills/plugin-sidebar-more-menu-item.md
+++ b/docs/designers-developers/developers/slotfills/plugin-sidebar-more-menu-item.md
@@ -3,30 +3,30 @@
This slot allows the creation of a `` with a menu item that when clicked will expand the sidebar to the appropriate Plugin section.
This is done by setting the `target` on `` to match the `name` on the ``
-
## Example
```js
-const { registerPlugin } = wp.plugins;
-
-const {
+import { registerPlugin } from '@wordpress/plugins';
+import {
PluginSidebar,
PluginSidebarMoreMenuItem
-} = wp.editPost;
+} from '@wordpress/edit-post';
+import { image } from '@wordpress/icons';
const { Fragment } = wp.element;
+const myIcon =
const PluginSidebarMoreMenuItemTest = () => (
Expanded Sidebar - More item
Content of the sidebar
diff --git a/docs/designers-developers/developers/slotfills/plugin-sidebar.md b/docs/designers-developers/developers/slotfills/plugin-sidebar.md
index 66121d8c8941cb..8af1641f6ea1fd 100644
--- a/docs/designers-developers/developers/slotfills/plugin-sidebar.md
+++ b/docs/designers-developers/developers/slotfills/plugin-sidebar.md
@@ -6,22 +6,22 @@ Using this slot will add an icon to the bar that, when clicked, will open a side
## Example
```js
-const { registerPlugin } = wp.plugins;
-const { PluginSidebar } = wp.editPost;
+import { registerPlugin } from '@wordpress/plugins';
+import { PluginSidebar } from '@wordpress/edit-post';
+import { image } from '@wordpress/icons';
const PluginSidebarTest = () => {
- return(
+ return (