diff --git a/packages/a11y/README.md b/packages/a11y/README.md index 9ce27b254d5c98..b4f3f0018158db 100644 --- a/packages/a11y/README.md +++ b/packages/a11y/README.md @@ -16,20 +16,16 @@ _This package assumes that your code will run in an **ES2015+** environment. If -### setup - -[src/index.js#L16-L26](src/index.js#L16-L26) +# **setup** [\<>](src/index.js#L16-L26) Create the live regions. -### speak - -[src/index.js#L52-L66](src/index.js#L52-L66) +# **speak** [\<>](src/index.js#L52-L66) Allows you to easily announce dynamic interface updates to screen readers using ARIA live regions. This module is inspired by the `speak` function in wp-a11y.js -**Usage** +_Usage_ ```js import { speak } from '@wordpress/a11y'; @@ -41,10 +37,10 @@ speak( 'The message you want to send to the ARIA live region' ); speak( 'The message you want to send to the ARIA live region', 'assertive' ); ``` -**Parameters** +_Parameters_ -- **message** `string`: The message to be announced by Assistive Technologies. -- **ariaLive** `string`: Optional. The politeness level for aria-live. Possible values: polite or assertive. Default polite. +- _message_ `string`: The message to be announced by Assistive Technologies. +- _ariaLive_ `string`: Optional. The politeness level for aria-live. Possible values: polite or assertive. Default polite. diff --git a/packages/autop/README.md b/packages/autop/README.md index ffb9168b63f208..3288ccf9eb5f0c 100644 --- a/packages/autop/README.md +++ b/packages/autop/README.md @@ -16,9 +16,7 @@ _This package assumes that your code will run in an **ES2015+** environment. If -#### autop - -[src/index.js#L129-L285](src/index.js#L129-L285) +# **autop** [\<>](src/index.js#L129-L285) Replaces double line-breaks with paragraph elements. @@ -26,45 +24,43 @@ A group of regex replaces used to identify text formatted with newlines and replace double line-breaks with HTML paragraph tags. The remaining line- breaks after conversion become `
` tags, unless br is set to 'false'. -**Usage** +_Usage_ ```js import { autop } from '@wordpress/autop'; autop( 'my text' ); // "

my text

" ``` -**Parameters** - -- **text** `string`: The text which has to be formatted. -- **br** `boolean`: Optional. If set, will convert all remaining line- breaks after paragraphing. Default true. +_Parameters_ -**Returns** +- _text_ `string`: The text which has to be formatted. +- _br_ `boolean`: Optional. If set, will convert all remaining line- breaks after paragraphing. Default true. -`string`: Text which has been converted into paragraph tags. +_Returns_ -#### removep +- `string`: Text which has been converted into paragraph tags. -[src/index.js#L303-L426](src/index.js#L303-L426) +# **removep** [\<>](src/index.js#L303-L426) Replaces `

` tags with two line breaks. "Opposite" of autop(). Replaces `

` tags with two line breaks except where the `

` has attributes. Unifies whitespace. Indents `

  • `, `
    ` and `
    ` for better readability. -**Usage** +_Usage_ ```js import { removep } from '@wordpress/autop'; removep( '

    my text

    ' ); // "my text" ``` -**Parameters** +_Parameters_ -- **html** `string`: The content from the editor. +- _html_ `string`: The content from the editor. -**Returns** +_Returns_ -`string`: The content with stripped paragraph tags. +- `string`: The content with stripped paragraph tags. diff --git a/packages/blob/README.md b/packages/blob/README.md index c0aed95f3b17b9..4d94b85d8d14ee 100644 --- a/packages/blob/README.md +++ b/packages/blob/README.md @@ -14,59 +14,51 @@ npm install @wordpress/blob --save -### createBlobURL - -[src/index.js#L15-L21](src/index.js#L15-L21) +# **createBlobURL** [\<>](src/index.js#L15-L21) Create a blob URL from a file. -**Parameters** - -- **file** `File`: The file to create a blob URL for. +_Parameters_ -**Returns** +- _file_ `File`: The file to create a blob URL for. -`string`: The blob URL. +_Returns_ -### getBlobByURL +- `string`: The blob URL. -[src/index.js#L32-L34](src/index.js#L32-L34) +# **getBlobByURL** [\<>](src/index.js#L32-L34) Retrieve a file based on a blob URL. The file must have been created by `createBlobURL` and not removed by `revokeBlobURL`, otherwise it will return `undefined`. -**Parameters** +_Parameters_ -- **url** `string`: The blob URL. +- _url_ `string`: The blob URL. -**Returns** +_Returns_ -`?File`: The file for the blob URL. +- `?File`: The file for the blob URL. -### isBlobURL - -[src/index.js#L56-L61](src/index.js#L56-L61) +# **isBlobURL** [\<>](src/index.js#L56-L61) Check whether a url is a blob url. -**Parameters** - -- **url** `string`: The URL. +_Parameters_ -**Returns** +- _url_ `string`: The URL. -`boolean`: Is the url a blob url? +_Returns_ -### revokeBlobURL +- `boolean`: Is the url a blob url? -[src/index.js#L41-L47](src/index.js#L41-L47) +# **revokeBlobURL** [\<>](src/index.js#L41-L47) Remove the resource and file cache from memory. -**Parameters** +_Parameters_ -- **url** `string`: The blob URL. +- _url_ `string`: The blob URL. diff --git a/packages/block-editor/README.md b/packages/block-editor/README.md index b30502aaf65405..4722cfa49e448f 100644 --- a/packages/block-editor/README.md +++ b/packages/block-editor/README.md @@ -68,142 +68,98 @@ registerCoreBlockTypes(); -### AlignmentToolbar - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **AlignmentToolbar** [\<>](src/index.js#L15-L15) Undocumented declaration. -### Autocomplete - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **Autocomplete** [\<>](src/index.js#L15-L15) Undocumented declaration. -### BlockAlignmentToolbar - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **BlockAlignmentToolbar** [\<>](src/index.js#L15-L15) Undocumented declaration. -### BlockControls - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **BlockControls** [\<>](src/index.js#L15-L15) Undocumented declaration. -### BlockEdit - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **BlockEdit** [\<>](src/index.js#L15-L15) Undocumented declaration. -### BlockEditorKeyboardShortcuts - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **BlockEditorKeyboardShortcuts** [\<>](src/index.js#L15-L15) Undocumented declaration. -### BlockEditorProvider - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **BlockEditorProvider** [\<>](src/index.js#L15-L15) Undocumented declaration. -### BlockFormatControls - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **BlockFormatControls** [\<>](src/index.js#L15-L15) Undocumented declaration. -### BlockIcon - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **BlockIcon** [\<>](src/index.js#L15-L15) Undocumented declaration. -### BlockInspector - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **BlockInspector** [\<>](src/index.js#L15-L15) Undocumented declaration. -### BlockList - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **BlockList** [\<>](src/index.js#L15-L15) Undocumented declaration. -### BlockMover - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **BlockMover** [\<>](src/index.js#L15-L15) Undocumented declaration. -### BlockNavigationDropdown - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **BlockNavigationDropdown** [\<>](src/index.js#L15-L15) Undocumented declaration. -### BlockSelectionClearer - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **BlockSelectionClearer** [\<>](src/index.js#L15-L15) Undocumented declaration. -### BlockSettingsMenu - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **BlockSettingsMenu** [\<>](src/index.js#L15-L15) Undocumented declaration. -### BlockTitle - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **BlockTitle** [\<>](src/index.js#L15-L15) Undocumented declaration. -### BlockToolbar - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **BlockToolbar** [\<>](src/index.js#L15-L15) Undocumented declaration. -### BlockVerticalAlignmentToolbar - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **BlockVerticalAlignmentToolbar** [\<>](src/index.js#L15-L15) Undocumented declaration. -### ColorPalette - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **ColorPalette** [\<>](src/index.js#L15-L15) Undocumented declaration. -### ContrastChecker - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **ContrastChecker** [\<>](src/index.js#L15-L15) Undocumented declaration. -### CopyHandler - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **CopyHandler** [\<>](src/index.js#L15-L15) Undocumented declaration. -### createCustomColorsHOC - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **createCustomColorsHOC** [\<>](src/index.js#L15-L15) A higher-order component factory for creating a 'withCustomColors' HOC, which handles color logic for class generation color value, retrieval and color attribute setting. Use this higher-order component to work with a custom set of colors. -**Usage** +_Usage_ ```jsx const CUSTOM_COLORS = [ { name: 'Red', slug: 'red', color: '#ff0000' }, { name: 'Blue', slug: 'blue', color: '#0000ff' } ]; @@ -215,209 +171,159 @@ export default compose( ); ``` -**Parameters** - -- **colorsArray** `Array`: The array of color objects (name, slug, color, etc... ). +_Parameters_ -**Returns** +- _colorsArray_ `Array`: The array of color objects (name, slug, color, etc... ). -`Function`: Higher-order component. +_Returns_ -### DefaultBlockAppender +- `Function`: Higher-order component. -[src/index.js#L15-L15](src/index.js#L15-L15) +# **DefaultBlockAppender** [\<>](src/index.js#L15-L15) Undocumented declaration. -### FontSizePicker - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **FontSizePicker** [\<>](src/index.js#L15-L15) Undocumented declaration. -### getColorClassName - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **getColorClassName** [\<>](src/index.js#L15-L15) Returns a class based on the context a color is being used and its slug. -**Parameters** +_Parameters_ -- **colorContextName** `string`: Context/place where color is being used e.g: background, text etc... -- **colorSlug** `string`: Slug of the color. +- _colorContextName_ `string`: Context/place where color is being used e.g: background, text etc... +- _colorSlug_ `string`: Slug of the color. -**Returns** +_Returns_ -`string`: String with the class corresponding to the color in the provided context. +- `string`: String with the class corresponding to the color in the provided context. -### getColorObjectByAttributeValues - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **getColorObjectByAttributeValues** [\<>](src/index.js#L15-L15) Provided an array of color objects as set by the theme or by the editor defaults, and the values of the defined color or custom color returns a color object describing the color. -**Parameters** - -- **colors** `Array`: Array of color objects as set by the theme or by the editor defaults. -- **definedColor** `?string`: A string containing the color slug. -- **customColor** `?string`: A string containing the customColor value. +_Parameters_ -**Returns** +- _colors_ `Array`: Array of color objects as set by the theme or by the editor defaults. +- _definedColor_ `?string`: A string containing the color slug. +- _customColor_ `?string`: A string containing the customColor value. -`?string`: If definedColor is passed and the name is found in colors, the color object exactly as set by the theme or editor defaults is returned. Otherwise, an object that just sets the color is defined. +_Returns_ -### getColorObjectByColorValue +- `?string`: If definedColor is passed and the name is found in colors, the color object exactly as set by the theme or editor defaults is returned. Otherwise, an object that just sets the color is defined. -[src/index.js#L15-L15](src/index.js#L15-L15) +# **getColorObjectByColorValue** [\<>](src/index.js#L15-L15) Provided an array of color objects as set by the theme or by the editor defaults, and a color value returns the color object matching that value or undefined. -**Parameters** - -- **colors** `Array`: Array of color objects as set by the theme or by the editor defaults. -- **colorValue** `?string`: A string containing the color value. +_Parameters_ -**Returns** +- _colors_ `Array`: Array of color objects as set by the theme or by the editor defaults. +- _colorValue_ `?string`: A string containing the color value. -`?string`: Returns the color object included in the colors array whose color property equals colorValue. Returns undefined if no color object matches this requirement. +_Returns_ -### getFontSize +- `?string`: Returns the color object included in the colors array whose color property equals colorValue. Returns undefined if no color object matches this requirement. -[src/index.js#L15-L15](src/index.js#L15-L15) +# **getFontSize** [\<>](src/index.js#L15-L15) Returns the font size object based on an array of named font sizes and the namedFontSize and customFontSize values. If namedFontSize is undefined or not found in fontSizes an object with just the size value based on customFontSize is returned. -**Parameters** +_Parameters_ -- **fontSizes** `Array`: Array of font size objects containing at least the "name" and "size" values as properties. -- **fontSizeAttribute** `?string`: Content of the font size attribute (slug). -- **customFontSizeAttribute** `?number`: Contents of the custom font size attribute (value). +- _fontSizes_ `Array`: Array of font size objects containing at least the "name" and "size" values as properties. +- _fontSizeAttribute_ `?string`: Content of the font size attribute (slug). +- _customFontSizeAttribute_ `?number`: Contents of the custom font size attribute (value). -**Returns** +_Returns_ -`?string`: If fontSizeAttribute is set and an equal slug is found in fontSizes it returns the font size object for that slug. Otherwise, an object with just the size value based on customFontSize is returned. +- `?string`: If fontSizeAttribute is set and an equal slug is found in fontSizes it returns the font size object for that slug. Otherwise, an object with just the size value based on customFontSize is returned. -### getFontSizeClass - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **getFontSizeClass** [\<>](src/index.js#L15-L15) Returns a class based on fontSizeName. -**Parameters** - -- **fontSizeSlug** `string`: Slug of the fontSize. +_Parameters_ -**Returns** +- _fontSizeSlug_ `string`: Slug of the fontSize. -`string`: String with the class corresponding to the fontSize passed. The class is generated by appending 'has-' followed by fontSizeSlug in kebabCase and ending with '-font-size'. +_Returns_ -### InnerBlocks +- `string`: String with the class corresponding to the fontSize passed. The class is generated by appending 'has-' followed by fontSizeSlug in kebabCase and ending with '-font-size'. -[src/index.js#L15-L15](src/index.js#L15-L15) +# **InnerBlocks** [\<>](src/index.js#L15-L15) Undocumented declaration. -### Inserter - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **Inserter** [\<>](src/index.js#L15-L15) Undocumented declaration. -### InspectorAdvancedControls - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **InspectorAdvancedControls** [\<>](src/index.js#L15-L15) Undocumented declaration. -### InspectorControls - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **InspectorControls** [\<>](src/index.js#L15-L15) Undocumented declaration. -### MediaPlaceholder - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **MediaPlaceholder** [\<>](src/index.js#L15-L15) Undocumented declaration. -### MediaUpload - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **MediaUpload** [\<>](src/index.js#L15-L15) Undocumented declaration. -### MediaUploadCheck - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **MediaUploadCheck** [\<>](src/index.js#L15-L15) Undocumented declaration. -### MultiBlocksSwitcher - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **MultiBlocksSwitcher** [\<>](src/index.js#L15-L15) Undocumented declaration. -### MultiSelectScrollIntoView - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **MultiSelectScrollIntoView** [\<>](src/index.js#L15-L15) Undocumented declaration. -### NavigableToolbar - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **NavigableToolbar** [\<>](src/index.js#L15-L15) Undocumented declaration. -### ObserveTyping - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **ObserveTyping** [\<>](src/index.js#L15-L15) Undocumented declaration. -### PanelColorSettings - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **PanelColorSettings** [\<>](src/index.js#L15-L15) Undocumented declaration. -### PlainText - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **PlainText** [\<>](src/index.js#L15-L15) Undocumented declaration. -### PreserveScrollInReorder - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **PreserveScrollInReorder** [\<>](src/index.js#L15-L15) Undocumented declaration. -### RichText - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **RichText** [\<>](src/index.js#L15-L15) Undocumented declaration. -### RichTextShortcut - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **RichTextShortcut** [\<>](src/index.js#L15-L15) Undocumented declaration. -### RichTextToolbarButton - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **RichTextToolbarButton** [\<>](src/index.js#L15-L15) Undocumented declaration. -### SETTINGS_DEFAULTS - -[src/index.js#L17-L17](src/index.js#L17-L17) +# **SETTINGS_DEFAULTS** [\<>](src/index.js#L17-L17) The default editor settings @@ -438,51 +344,37 @@ The default editor settings bodyPlaceholder string Empty post placeholder titlePlaceholder string Empty title placeholder -### SkipToSelectedBlock - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **SkipToSelectedBlock** [\<>](src/index.js#L15-L15) Undocumented declaration. -### URLInput - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **URLInput** [\<>](src/index.js#L15-L15) Undocumented declaration. -### URLInputButton - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **URLInputButton** [\<>](src/index.js#L15-L15) Undocumented declaration. -### URLPopover - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **URLPopover** [\<>](src/index.js#L15-L15) Undocumented declaration. -### Warning - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **Warning** [\<>](src/index.js#L15-L15) Undocumented declaration. -### withColorContext - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **withColorContext** [\<>](src/index.js#L15-L15) Undocumented declaration. -### withColors - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **withColors** [\<>](src/index.js#L15-L15) A higher-order component, which handles color logic for class generation color value, retrieval and color attribute setting. For use with the default editor/theme color palette. -**Usage** +_Usage_ ```jsx export default compose( @@ -491,32 +383,28 @@ export default compose( ); ``` -**Parameters** - -- **colorTypes** `...(object|string)`: The arguments can be strings or objects. If the argument is an object, it should contain the color attribute name as key and the color context as value. If the argument is a string the value should be the color attribute name, the color context is computed by applying a kebab case transform to the value. Color context represents the context/place where the color is going to be used. The class name of the color is generated using 'has' followed by the color name and ending with the color context all in kebab case e.g: has-green-background-color. +_Parameters_ -**Returns** +- _colorTypes_ `...(object|string)`: The arguments can be strings or objects. If the argument is an object, it should contain the color attribute name as key and the color context as value. If the argument is a string the value should be the color attribute name, the color context is computed by applying a kebab case transform to the value. Color context represents the context/place where the color is going to be used. The class name of the color is generated using 'has' followed by the color name and ending with the color context all in kebab case e.g: has-green-background-color. -`Function`: Higher-order component. +_Returns_ -### withFontSizes +- `Function`: Higher-order component. -[src/index.js#L15-L15](src/index.js#L15-L15) +# **withFontSizes** [\<>](src/index.js#L15-L15) Higher-order component, which handles font size logic for class generation, font size value retrieval, and font size change handling. -**Parameters** - -- **args** `...(object|string)`: The arguments should all be strings Each string contains the font size attribute name e.g: 'fontSize'. +_Parameters_ -**Returns** +- _args_ `...(object|string)`: The arguments should all be strings Each string contains the font size attribute name e.g: 'fontSize'. -`Function`: Higher-order component. +_Returns_ -### WritingFlow +- `Function`: Higher-order component. -[src/index.js#L15-L15](src/index.js#L15-L15) +# **WritingFlow** [\<>](src/index.js#L15-L15) Undocumented declaration. diff --git a/packages/block-library/README.md b/packages/block-library/README.md index 78573bbf753e7d..1a87ac2572622c 100644 --- a/packages/block-library/README.md +++ b/packages/block-library/README.md @@ -16,13 +16,11 @@ _This package assumes that your code will run in an **ES2015+** environment. If -### registerCoreBlocks - -[src/index.js#L70-L132](src/index.js#L70-L132) +# **registerCoreBlocks** [\<>](src/index.js#L70-L132) Function to register core blocks provided by the block editor. -**Usage** +_Usage_ ```js import { registerCoreBlocks } from '@wordpress/block-library'; diff --git a/packages/block-serialization-default-parser/README.md b/packages/block-serialization-default-parser/README.md index d64533b36b341b..f0f7e0c7913e93 100644 --- a/packages/block-serialization-default-parser/README.md +++ b/packages/block-serialization-default-parser/README.md @@ -16,13 +16,11 @@ _This package assumes that your code will run in an **ES2015+** environment. If -### parse - -[src/index.js#L150-L162](src/index.js#L150-L162) +# **parse** [\<>](src/index.js#L150-L162) Parser function, that converts input HTML into a block based structure. -**Usage** +_Usage_ Input post: @@ -96,13 +94,13 @@ parse( post ) === [ ]; ``` -**Parameters** +_Parameters_ -- **doc** `string`: The HTML document to parse. +- _doc_ `string`: The HTML document to parse. -**Returns** +_Returns_ -`Array`: A block-based representation of the input HTML. +- `Array`: A block-based representation of the input HTML. diff --git a/packages/blocks/README.md b/packages/blocks/README.md index 960edae9da7737..116a4dd19711c4 100644 --- a/packages/blocks/README.md +++ b/packages/blocks/README.md @@ -176,63 +176,53 @@ In the random image block above, we've given the `alt` attribute of the image a -### children - -[src/index.js#L16-L16](src/index.js#L16-L16) +# **children** [\<>](src/index.js#L16-L16) Undocumented declaration. -### cloneBlock - -[src/index.js#L16-L16](src/index.js#L16-L16) +# **cloneBlock** [\<>](src/index.js#L16-L16) Given a block object, returns a copy of the block object, optionally merging new attributes and/or replacing its inner blocks. -**Parameters** - -- **block** `Object`: Block instance. -- **mergeAttributes** `Object`: Block attributes. -- **newInnerBlocks** `?Array`: Nested blocks. +_Parameters_ -**Returns** +- _block_ `Object`: Block instance. +- _mergeAttributes_ `Object`: Block attributes. +- _newInnerBlocks_ `?Array`: Nested blocks. -`Object`: A cloned block. +_Returns_ -### createBlock +- `Object`: A cloned block. -[src/index.js#L16-L16](src/index.js#L16-L16) +# **createBlock** [\<>](src/index.js#L16-L16) Returns a block object given its type and attributes. -**Parameters** +_Parameters_ -- **name** `string`: Block name. -- **attributes** `Object`: Block attributes. -- **innerBlocks** `?Array`: Nested blocks. +- _name_ `string`: Block name. +- _attributes_ `Object`: Block attributes. +- _innerBlocks_ `?Array`: Nested blocks. -**Returns** +_Returns_ -`Object`: Block object. +- `Object`: Block object. -### doBlocksMatchTemplate - -[src/index.js#L16-L16](src/index.js#L16-L16) +# **doBlocksMatchTemplate** [\<>](src/index.js#L16-L16) Checks whether a list of blocks matches a template by comparing the block names. -**Parameters** - -- **blocks** `Array`: Block list. -- **template** `Array`: Block template. +_Parameters_ -**Returns** +- _blocks_ `Array`: Block list. +- _template_ `Array`: Block template. -`boolean`: Whether the list of blocks matches a templates +_Returns_ -### findTransform +- `boolean`: Whether the list of blocks matches a templates -[src/index.js#L16-L16](src/index.js#L16-L16) +# **findTransform** [\<>](src/index.js#L16-L16) Given an array of transforms, returns the highest-priority transform where the predicate function returns a truthy value. A higher-priority transform @@ -240,329 +230,283 @@ is one with a lower priority value (i.e. first in priority order). Returns null if the transforms set is empty or the predicate function returns a falsey value for all entries. -**Parameters** - -- **transforms** `Array`: Transforms to search. -- **predicate** `Function`: Function returning true on matching transform. +_Parameters_ -**Returns** +- _transforms_ `Array`: Transforms to search. +- _predicate_ `Function`: Function returning true on matching transform. -`?Object`: Highest-priority transform candidate. +_Returns_ -### getBlockAttributes +- `?Object`: Highest-priority transform candidate. -[src/index.js#L16-L16](src/index.js#L16-L16) +# **getBlockAttributes** [\<>](src/index.js#L16-L16) Returns the block attributes of a registered block node given its type. -**Parameters** +_Parameters_ -- **blockTypeOrName** `(string|Object)`: Block type or name. -- **innerHTML** `string`: Raw block content. -- **attributes** `?Object`: Known block attributes (from delimiters). +- _blockTypeOrName_ `(string|Object)`: Block type or name. +- _innerHTML_ `string`: Raw block content. +- _attributes_ `?Object`: Known block attributes (from delimiters). -**Returns** +_Returns_ -`Object`: All block attributes. +- `Object`: All block attributes. -### getBlockContent - -[src/index.js#L16-L16](src/index.js#L16-L16) +# **getBlockContent** [\<>](src/index.js#L16-L16) Given a block object, returns the Block's Inner HTML markup. -**Parameters** - -- **block** `Object`: Block instance. +_Parameters_ -**Returns** +- _block_ `Object`: Block instance. -`string`: HTML. +_Returns_ -### getBlockDefaultClassName +- `string`: HTML. -[src/index.js#L16-L16](src/index.js#L16-L16) +# **getBlockDefaultClassName** [\<>](src/index.js#L16-L16) Returns the block's default classname from its name. -**Parameters** - -- **blockName** `string`: The block name. +_Parameters_ -**Returns** +- _blockName_ `string`: The block name. -`string`: The block's default class. +_Returns_ -### getBlockMenuDefaultClassName +- `string`: The block's default class. -[src/index.js#L16-L16](src/index.js#L16-L16) +# **getBlockMenuDefaultClassName** [\<>](src/index.js#L16-L16) Returns the block's default menu item classname from its name. -**Parameters** +_Parameters_ -- **blockName** `string`: The block name. +- _blockName_ `string`: The block name. -**Returns** +_Returns_ -`string`: The block's default menu item class. +- `string`: The block's default menu item class. -### getBlockSupport - -[src/index.js#L16-L16](src/index.js#L16-L16) +# **getBlockSupport** [\<>](src/index.js#L16-L16) Returns the block support value for a feature, if defined. -**Parameters** - -- **nameOrType** `(string|Object)`: Block name or type object -- **feature** `string`: Feature to retrieve -- **defaultSupports** `*`: Default value to return if not explicitly defined +_Parameters_ -**Returns** +- _nameOrType_ `(string|Object)`: Block name or type object +- _feature_ `string`: Feature to retrieve +- _defaultSupports_ `*`: Default value to return if not explicitly defined -`?*`: Block support value +_Returns_ -### getBlockTransforms +- `?*`: Block support value -[src/index.js#L16-L16](src/index.js#L16-L16) +# **getBlockTransforms** [\<>](src/index.js#L16-L16) Returns normal block transforms for a given transform direction, optionally for a specific block by name, or an empty array if there are no transforms. If no block name is provided, returns transforms for all blocks. A normal transform object includes `blockName` as a property. -**Parameters** - -- **direction** `string`: Transform direction ("to", "from"). -- **blockTypeOrName** `(string|Object)`: Block type or name. +_Parameters_ -**Returns** +- _direction_ `string`: Transform direction ("to", "from"). +- _blockTypeOrName_ `(string|Object)`: Block type or name. -`Array`: Block transforms for direction. +_Returns_ -### getBlockType +- `Array`: Block transforms for direction. -[src/index.js#L16-L16](src/index.js#L16-L16) +# **getBlockType** [\<>](src/index.js#L16-L16) Returns a registered block type. -**Parameters** +_Parameters_ -- **name** `string`: Block name. +- _name_ `string`: Block name. -**Returns** +_Returns_ -`?Object`: Block type. +- `?Object`: Block type. -### getBlockTypes - -[src/index.js#L16-L16](src/index.js#L16-L16) +# **getBlockTypes** [\<>](src/index.js#L16-L16) Returns all registered blocks. -**Returns** - -`Array`: Block settings. +_Returns_ -### getCategories +- `Array`: Block settings. -[src/index.js#L16-L16](src/index.js#L16-L16) +# **getCategories** [\<>](src/index.js#L16-L16) Returns all the block categories. -**Returns** - -`Array`: Block categories. +_Returns_ -### getChildBlockNames +- `Array`: Block categories. -[src/index.js#L16-L16](src/index.js#L16-L16) +# **getChildBlockNames** [\<>](src/index.js#L16-L16) Returns an array with the child blocks of a given block. -**Parameters** +_Parameters_ -- **blockName** `string`: Name of block (example: “latest-posts”). +- _blockName_ `string`: Name of block (example: “latest-posts”). -**Returns** +_Returns_ -`Array`: Array of child block names. +- `Array`: Array of child block names. -### getDefaultBlockName - -[src/index.js#L16-L16](src/index.js#L16-L16) +# **getDefaultBlockName** [\<>](src/index.js#L16-L16) Retrieves the default block name. -**Returns** - -`?string`: Block name. +_Returns_ -### getFreeformContentHandlerName +- `?string`: Block name. -[src/index.js#L16-L16](src/index.js#L16-L16) +# **getFreeformContentHandlerName** [\<>](src/index.js#L16-L16) Retrieves name of block handling non-block content, or undefined if no handler has been defined. -**Returns** - -`?string`: Blog name. +_Returns_ -### getPhrasingContentSchema +- `?string`: Blog name. -[src/index.js#L16-L16](src/index.js#L16-L16) +# **getPhrasingContentSchema** [\<>](src/index.js#L16-L16) Get schema of possible paths for phrasing content. -**Related** +_Related_ - -**Returns** +_Returns_ -`Object`: Schema. +- `Object`: Schema. -### getPossibleBlockTransformations - -[src/index.js#L16-L16](src/index.js#L16-L16) +# **getPossibleBlockTransformations** [\<>](src/index.js#L16-L16) Returns an array of block types that the set of blocks received as argument can be transformed into. -**Parameters** - -- **blocks** `Array`: Blocks array. +_Parameters_ -**Returns** +- _blocks_ `Array`: Blocks array. -`Array`: Block types that the blocks argument can be transformed to. +_Returns_ -### getSaveContent +- `Array`: Block types that the blocks argument can be transformed to. -[src/index.js#L16-L16](src/index.js#L16-L16) +# **getSaveContent** [\<>](src/index.js#L16-L16) Given a block type containing a save render implementation and attributes, returns the static markup to be saved. -**Parameters** - -- **blockTypeOrName** `(string|Object)`: Block type or name. -- **attributes** `Object`: Block attributes. -- **innerBlocks** `?Array`: Nested blocks. +_Parameters_ -**Returns** +- _blockTypeOrName_ `(string|Object)`: Block type or name. +- _attributes_ `Object`: Block attributes. +- _innerBlocks_ `?Array`: Nested blocks. -`string`: Save content. +_Returns_ -### getSaveElement +- `string`: Save content. -[src/index.js#L16-L16](src/index.js#L16-L16) +# **getSaveElement** [\<>](src/index.js#L16-L16) Given a block type containing a save render implementation and attributes, returns the enhanced element to be saved or string when raw HTML expected. -**Parameters** +_Parameters_ -- **blockTypeOrName** `(string|Object)`: Block type or name. -- **attributes** `Object`: Block attributes. -- **innerBlocks** `?Array`: Nested blocks. +- _blockTypeOrName_ `(string|Object)`: Block type or name. +- _attributes_ `Object`: Block attributes. +- _innerBlocks_ `?Array`: Nested blocks. -**Returns** +_Returns_ -`(Object|string)`: Save element or raw HTML string. +- `(Object|string)`: Save element or raw HTML string. -### getUnregisteredTypeHandlerName - -[src/index.js#L16-L16](src/index.js#L16-L16) +# **getUnregisteredTypeHandlerName** [\<>](src/index.js#L16-L16) Retrieves name of block handling unregistered block types, or undefined if no handler has been defined. -**Returns** - -`?string`: Blog name. +_Returns_ -### hasBlockSupport +- `?string`: Blog name. -[src/index.js#L16-L16](src/index.js#L16-L16) +# **hasBlockSupport** [\<>](src/index.js#L16-L16) Returns true if the block defines support for a feature, or false otherwise. -**Parameters** - -- **nameOrType** `(string|Object)`: Block name or type object. -- **feature** `string`: Feature to test. -- **defaultSupports** `boolean`: Whether feature is supported by default if not explicitly defined. +_Parameters_ -**Returns** +- _nameOrType_ `(string|Object)`: Block name or type object. +- _feature_ `string`: Feature to test. +- _defaultSupports_ `boolean`: Whether feature is supported by default if not explicitly defined. -`boolean`: Whether block supports feature. +_Returns_ -### hasChildBlocks +- `boolean`: Whether block supports feature. -[src/index.js#L16-L16](src/index.js#L16-L16) +# **hasChildBlocks** [\<>](src/index.js#L16-L16) Returns a boolean indicating if a block has child blocks or not. -**Parameters** +_Parameters_ -- **blockName** `string`: Name of block (example: “latest-posts”). +- _blockName_ `string`: Name of block (example: “latest-posts”). -**Returns** +_Returns_ -`boolean`: True if a block contains child blocks and false otherwise. +- `boolean`: True if a block contains child blocks and false otherwise. -### hasChildBlocksWithInserterSupport - -[src/index.js#L16-L16](src/index.js#L16-L16) +# **hasChildBlocksWithInserterSupport** [\<>](src/index.js#L16-L16) Returns a boolean indicating if a block has at least one child block with inserter support. -**Parameters** - -- **blockName** `string`: Block type name. +_Parameters_ -**Returns** +- _blockName_ `string`: Block type name. -`boolean`: True if a block contains at least one child blocks with inserter support and false otherwise. +_Returns_ -### isReusableBlock +- `boolean`: True if a block contains at least one child blocks with inserter support and false otherwise. -[src/index.js#L16-L16](src/index.js#L16-L16) +# **isReusableBlock** [\<>](src/index.js#L16-L16) Determines whether or not the given block is a reusable block. This is a special block type that is used to point to a global block stored via the API. -**Parameters** - -- **blockOrType** `Object`: Block or Block Type to test. +_Parameters_ -**Returns** +- _blockOrType_ `Object`: Block or Block Type to test. -`boolean`: Whether the given block is a reusable block. +_Returns_ -### isUnmodifiedDefaultBlock +- `boolean`: Whether the given block is a reusable block. -[src/index.js#L16-L16](src/index.js#L16-L16) +# **isUnmodifiedDefaultBlock** [\<>](src/index.js#L16-L16) Determines whether the block is a default block and its attributes are equal to the default attributes which means the block is unmodified. -**Parameters** +_Parameters_ -- **block** `WPBlock`: Block Object +- _block_ `WPBlock`: Block Object -**Returns** +_Returns_ -`boolean`: Whether the block is an unmodified default block +- `boolean`: Whether the block is an unmodified default block -### isValidBlockContent - -[src/index.js#L16-L16](src/index.js#L16-L16) +# **isValidBlockContent** [\<>](src/index.js#L16-L16) Returns true if the parsed block is valid given the input content. A block is considered valid if, when serialized with assumed attributes, the content @@ -570,214 +514,182 @@ matches the original value. Logs to console in development environments when invalid. -**Parameters** - -- **blockTypeOrName** `(string|Object)`: Block type. -- **attributes** `Object`: Parsed block attributes. -- **originalBlockContent** `string`: Original block content. +_Parameters_ -**Returns** +- _blockTypeOrName_ `(string|Object)`: Block type. +- _attributes_ `Object`: Parsed block attributes. +- _originalBlockContent_ `string`: Original block content. -`boolean`: Whether block is valid. +_Returns_ -### isValidIcon +- `boolean`: Whether block is valid. -[src/index.js#L16-L16](src/index.js#L16-L16) +# **isValidIcon** [\<>](src/index.js#L16-L16) Function that checks if the parameter is a valid icon. -**Parameters** - -- **icon** `*`: Parameter to be checked. +_Parameters_ -**Returns** +- _icon_ `*`: Parameter to be checked. -`boolean`: True if the parameter is a valid icon and false otherwise. +_Returns_ -### node +- `boolean`: True if the parameter is a valid icon and false otherwise. -[src/index.js#L16-L16](src/index.js#L16-L16) +# **node** [\<>](src/index.js#L16-L16) Undocumented declaration. -### normalizeIconObject - -[src/index.js#L16-L16](src/index.js#L16-L16) +# **normalizeIconObject** [\<>](src/index.js#L16-L16) Function that receives an icon as set by the blocks during the registration and returns a new icon object that is normalized so we can rely on just on possible icon structure in the codebase. -**Parameters** - -- **icon** `(Object|string|WPElement)`: Slug of the Dashicon to be shown as the icon for the block in the inserter, or element or an object describing the icon. +_Parameters_ -**Returns** +- _icon_ `(Object|string|WPElement)`: Slug of the Dashicon to be shown as the icon for the block in the inserter, or element or an object describing the icon. -`Object`: Object describing the icon. +_Returns_ -### parse +- `Object`: Object describing the icon. -[src/index.js#L16-L16](src/index.js#L16-L16) +# **parse** [\<>](src/index.js#L16-L16) Parses the post content with a PegJS grammar and returns a list of blocks. -**Parameters** - -- **content** `string`: The post content. +_Parameters_ -**Returns** +- _content_ `string`: The post content. -`Array`: Block list. +_Returns_ -### parseWithAttributeSchema +- `Array`: Block list. -[src/index.js#L16-L16](src/index.js#L16-L16) +# **parseWithAttributeSchema** [\<>](src/index.js#L16-L16) Given a block's raw content and an attribute's schema returns the attribute's value depending on its source. -**Parameters** +_Parameters_ -- **innerHTML** `string`: Block's raw content. -- **attributeSchema** `Object`: Attribute's schema. +- _innerHTML_ `string`: Block's raw content. +- _attributeSchema_ `Object`: Attribute's schema. -**Returns** +_Returns_ -`*`: Attribute value. +- `*`: Attribute value. -### pasteHandler - -[src/index.js#L16-L16](src/index.js#L16-L16) +# **pasteHandler** [\<>](src/index.js#L16-L16) Converts an HTML string to known blocks. Strips everything else. -**Parameters** - -- **options.HTML** `[string]`: The HTML to convert. -- **options.plainText** `[string]`: Plain text version. -- **options.mode** `[string]`: Handle content as blocks or inline content. _ 'AUTO': Decide based on the content passed. _ 'INLINE': Always handle as inline content, and return string. \* 'BLOCKS': Always handle as blocks, and return array of blocks. -- **options.tagName** `[Array]`: The tag into which content will be inserted. -- **options.canUserUseUnfilteredHTML** `[boolean]`: Whether or not the user can use unfiltered HTML. +_Parameters_ -**Returns** +- _options.HTML_ `[string]`: The HTML to convert. +- _options.plainText_ `[string]`: Plain text version. +- _options.mode_ `[string]`: Handle content as blocks or inline content. _ 'AUTO': Decide based on the content passed. _ 'INLINE': Always handle as inline content, and return string. \* 'BLOCKS': Always handle as blocks, and return array of blocks. +- _options.tagName_ `[Array]`: The tag into which content will be inserted. +- _options.canUserUseUnfilteredHTML_ `[boolean]`: Whether or not the user can use unfiltered HTML. -`(Array|string)`: A list of blocks or a string, depending on `handlerMode`. +_Returns_ -### rawHandler +- `(Array|string)`: A list of blocks or a string, depending on `handlerMode`. -[src/index.js#L16-L16](src/index.js#L16-L16) +# **rawHandler** [\<>](src/index.js#L16-L16) Converts an HTML string to known blocks. -**Parameters** - -- **$1.HTML** `string`: The HTML to convert. +_Parameters_ -**Returns** +- _$1.HTML_ `string`: The HTML to convert. -`Array`: A list of blocks. +_Returns_ -### registerBlockStyle +- `Array`: A list of blocks. -[src/index.js#L16-L16](src/index.js#L16-L16) +# **registerBlockStyle** [\<>](src/index.js#L16-L16) Registers a new block style variation for the given block. -**Parameters** +_Parameters_ -- **blockName** `string`: Name of block (example: “core/latest-posts”). -- **styleVariation** `Object`: Object containing `name` which is the class name applied to the block and `label` which identifies the variation to the user. +- _blockName_ `string`: Name of block (example: “core/latest-posts”). +- _styleVariation_ `Object`: Object containing `name` which is the class name applied to the block and `label` which identifies the variation to the user. -### registerBlockType - -[src/index.js#L16-L16](src/index.js#L16-L16) +# **registerBlockType** [\<>](src/index.js#L16-L16) Registers a new block provided a unique name and an object defining its behavior. Once registered, the block is made available as an option to any editor interface where blocks are implemented. -**Parameters** - -- **name** `string`: Block name. -- **settings** `Object`: Block settings. +_Parameters_ -**Returns** +- _name_ `string`: Block name. +- _settings_ `Object`: Block settings. -`?WPBlock`: The block, if it has been successfully registered; otherwise `undefined`. +_Returns_ -### serialize +- `?WPBlock`: The block, if it has been successfully registered; otherwise `undefined`. -[src/index.js#L16-L16](src/index.js#L16-L16) +# **serialize** [\<>](src/index.js#L16-L16) Takes a block or set of blocks and returns the serialized post content. -**Parameters** - -- **blocks** `Array`: Block(s) to serialize. +_Parameters_ -**Returns** +- _blocks_ `Array`: Block(s) to serialize. -`string`: The post content. +_Returns_ -### setCategories +- `string`: The post content. -[src/index.js#L16-L16](src/index.js#L16-L16) +# **setCategories** [\<>](src/index.js#L16-L16) Sets the block categories. -**Parameters** +_Parameters_ -- **categories** `Array`: Block categories. +- _categories_ `Array`: Block categories. -### setDefaultBlockName - -[src/index.js#L16-L16](src/index.js#L16-L16) +# **setDefaultBlockName** [\<>](src/index.js#L16-L16) Assigns the default block name. -**Parameters** - -- **name** `string`: Block name. +_Parameters_ -### setFreeformContentHandlerName +- _name_ `string`: Block name. -[src/index.js#L16-L16](src/index.js#L16-L16) +# **setFreeformContentHandlerName** [\<>](src/index.js#L16-L16) Assigns name of block for handling non-block content. -**Parameters** - -- **blockName** `string`: Block name. +_Parameters_ -### setUnregisteredTypeHandlerName +- _blockName_ `string`: Block name. -[src/index.js#L16-L16](src/index.js#L16-L16) +# **setUnregisteredTypeHandlerName** [\<>](src/index.js#L16-L16) Assigns name of block handling unregistered block types. -**Parameters** +_Parameters_ -- **blockName** `string`: Block name. +- _blockName_ `string`: Block name. -### switchToBlockType - -[src/index.js#L16-L16](src/index.js#L16-L16) +# **switchToBlockType** [\<>](src/index.js#L16-L16) Switch one or more blocks into one or more blocks of the new block type. -**Parameters** - -- **blocks** `(Array|Object)`: Blocks array or block object. -- **name** `string`: Block name. +_Parameters_ -**Returns** +- _blocks_ `(Array|Object)`: Blocks array or block object. +- _name_ `string`: Block name. -`Array`: Array of blocks. +_Returns_ -### synchronizeBlocksWithTemplate +- `Array`: Array of blocks. -[src/index.js#L16-L16](src/index.js#L16-L16) +# **synchronizeBlocksWithTemplate** [\<>](src/index.js#L16-L16) Synchronize a block list with a block template. @@ -786,61 +698,53 @@ keep the block as is if it matches the block at the same position in the templat (If it has the same name) and if doesn't match, we create a new block based on the template. Extra blocks not present in the template are removed. -**Parameters** - -- **blocks** `Array`: Block list. -- **template** `Array`: Block template. +_Parameters_ -**Returns** +- _blocks_ `Array`: Block list. +- _template_ `Array`: Block template. -`Array`: Updated Block list. +_Returns_ -### unregisterBlockStyle +- `Array`: Updated Block list. -[src/index.js#L16-L16](src/index.js#L16-L16) +# **unregisterBlockStyle** [\<>](src/index.js#L16-L16) Unregisters a block style variation for the given block. -**Parameters** +_Parameters_ -- **blockName** `string`: Name of block (example: “core/latest-posts”). -- **styleVariationName** `string`: Name of class applied to the block. +- _blockName_ `string`: Name of block (example: “core/latest-posts”). +- _styleVariationName_ `string`: Name of class applied to the block. -### unregisterBlockType - -[src/index.js#L16-L16](src/index.js#L16-L16) +# **unregisterBlockType** [\<>](src/index.js#L16-L16) Unregisters a block. -**Parameters** - -- **name** `string`: Block name. +_Parameters_ -**Returns** +- _name_ `string`: Block name. -`?WPBlock`: The previous block value, if it has been successfully unregistered; otherwise `undefined`. +_Returns_ -### updateCategory +- `?WPBlock`: The previous block value, if it has been successfully unregistered; otherwise `undefined`. -[src/index.js#L16-L16](src/index.js#L16-L16) +# **updateCategory** [\<>](src/index.js#L16-L16) Updates a category. -**Parameters** - -- **slug** `string`: Block category slug. -- **category** `Object`: Object containing the category properties that should be updated. +_Parameters_ -### withBlockContentContext +- _slug_ `string`: Block category slug. +- _category_ `Object`: Object containing the category properties that should be updated. -[src/index.js#L17-L17](src/index.js#L17-L17) +# **withBlockContentContext** [\<>](src/index.js#L17-L17) A Higher Order Component used to inject BlockContent using context to the wrapped component. -**Returns** +_Returns_ -`Component`: Enhanced component with injected BlockContent as prop. +- `Component`: Enhanced component with injected BlockContent as prop. diff --git a/packages/compose/README.md b/packages/compose/README.md index cbb4be0f20642a..00dfc8e98f34dd 100644 --- a/packages/compose/README.md +++ b/packages/compose/README.md @@ -65,118 +65,102 @@ For more details, you can refer to each Higher Order Component's README file. [A -### compose - -[src/index.js#L22-L22](src/index.js#L22-L22) +# **compose** [\<>](src/index.js#L22-L22) Composes multiple higher-order components into a single higher-order component. Performs right-to-left function composition, where each successive invocation is supplied the return value of the previous. -**Parameters** - -- **hocs** `...Function`: The HOC functions to invoke. +_Parameters_ -**Returns** +- _hocs_ `...Function`: The HOC functions to invoke. -`Function`: Returns the new composite function. +_Returns_ -### createHigherOrderComponent +- `Function`: Returns the new composite function. -[src/index.js#L6-L6](src/index.js#L6-L6) +# **createHigherOrderComponent** [\<>](src/index.js#L6-L6) Given a function mapping a component to an enhanced component and modifier name, returns the enhanced component augmented with a generated displayName. -**Parameters** +_Parameters_ -- **mapComponentToEnhancedComponent** `Function`: Function mapping component to enhanced component. -- **modifierName** `string`: Seed name from which to generated display name. +- _mapComponentToEnhancedComponent_ `Function`: Function mapping component to enhanced component. +- _modifierName_ `string`: Seed name from which to generated display name. -**Returns** +_Returns_ -`WPComponent`: Component class with generated display name assigned. +- `WPComponent`: Component class with generated display name assigned. -### ifCondition - -[src/index.js#L7-L7](src/index.js#L7-L7) +# **ifCondition** [\<>](src/index.js#L7-L7) Higher-order component creator, creating a new component which renders if the given condition is satisfied or with the given optional prop name. -**Parameters** - -- **predicate** `Function`: Function to test condition. +_Parameters_ -**Returns** +- _predicate_ `Function`: Function to test condition. -`Function`: Higher-order component. +_Returns_ -### pure +- `Function`: Higher-order component. -[src/index.js#L8-L8](src/index.js#L8-L8) +# **pure** [\<>](src/index.js#L8-L8) Given a component returns the enhanced component augmented with a component only rerendering when its props/state change -**Parameters** +_Parameters_ -- **mapComponentToEnhancedComponent** `Function`: Function mapping component to enhanced component. -- **modifierName** `string`: Seed name from which to generated display name. +- _mapComponentToEnhancedComponent_ `Function`: Function mapping component to enhanced component. +- _modifierName_ `string`: Seed name from which to generated display name. -**Returns** +_Returns_ -`WPComponent`: Component class with generated display name assigned. +- `WPComponent`: Component class with generated display name assigned. -### withGlobalEvents - -[src/index.js#L9-L9](src/index.js#L9-L9) +# **withGlobalEvents** [\<>](src/index.js#L9-L9) Undocumented declaration. -### withInstanceId - -[src/index.js#L10-L10](src/index.js#L10-L10) +# **withInstanceId** [\<>](src/index.js#L10-L10) A Higher Order Component used to be provide a unique instance ID by component. -**Parameters** +_Parameters_ -- **WrappedComponent** `WPElement`: The wrapped component. +- _WrappedComponent_ `WPElement`: The wrapped component. -**Returns** +_Returns_ -`Component`: Component with an instanceId prop. +- `Component`: Component with an instanceId prop. -### withSafeTimeout - -[src/index.js#L11-L11](src/index.js#L11-L11) +# **withSafeTimeout** [\<>](src/index.js#L11-L11) A higher-order component used to provide and manage delayed function calls that ought to be bound to a component's lifecycle. -**Parameters** - -- **OriginalComponent** `Component`: Component requiring setTimeout +_Parameters_ -**Returns** +- _OriginalComponent_ `Component`: Component requiring setTimeout -`Component`: Wrapped component. +_Returns_ -### withState +- `Component`: Wrapped component. -[src/index.js#L12-L12](src/index.js#L12-L12) +# **withState** [\<>](src/index.js#L12-L12) A Higher Order Component used to provide and manage internal component state via props. -**Parameters** +_Parameters_ -- **initialState** `?Object`: Optional initial state of the component. +- _initialState_ `?Object`: Optional initial state of the component. -**Returns** +_Returns_ -`Component`: Wrapped component. +- `Component`: Wrapped component. diff --git a/packages/data/README.md b/packages/data/README.md index 98a3f2bc03d08f..e40efa3ab1a0b9 100644 --- a/packages/data/README.md +++ b/packages/data/README.md @@ -248,14 +248,12 @@ Specific implementation differences from Redux and React Redux: -### combineReducers - -[src/index.js#L58-L58](src/index.js#L58-L58) +# **combineReducers** [\<>](src/index.js#L58-L58) The combineReducers helper function turns an object whose values are different reducing functions into a single reducing function you can pass to registerReducer. -**Usage** +_Usage_ ```js const { combineReducers, registerStore } = wp.data; @@ -283,65 +281,57 @@ registerStore( 'my-shop', { } ); ``` -**Parameters** - -- **reducers** `Object`: An object whose values correspond to different reducing functions that need to be combined into one. +_Parameters_ -**Returns** +- _reducers_ `Object`: An object whose values correspond to different reducing functions that need to be combined into one. -`Function`: A reducer that invokes every reducer inside the reducers object, and constructs a state object with the same shape. +_Returns_ -### createRegistry +- `Function`: A reducer that invokes every reducer inside the reducers object, and constructs a state object with the same shape. -[src/index.js#L17-L17](src/index.js#L17-L17) +# **createRegistry** [\<>](src/index.js#L17-L17) Creates a new store registry, given an optional object of initial store configurations. -**Parameters** +_Parameters_ -- **storeConfigs** `Object`: Initial store configurations. +- _storeConfigs_ `Object`: Initial store configurations. -**Returns** +_Returns_ -`WPDataRegistry`: Data registry. +- `WPDataRegistry`: Data registry. -### createRegistryControl - -[src/index.js#L19-L19](src/index.js#L19-L19) +# **createRegistryControl** [\<>](src/index.js#L19-L19) Mark a control as a registry control. -**Parameters** - -- **registryControl** `function`: Function receiving a registry object and returning a control. +_Parameters_ -**Returns** +- _registryControl_ `function`: Function receiving a registry object and returning a control. -`function`: marked registry control. +_Returns_ -### createRegistrySelector +- `function`: marked registry control. -[src/index.js#L19-L19](src/index.js#L19-L19) +# **createRegistrySelector** [\<>](src/index.js#L19-L19) Mark a selector as a registry selector. -**Parameters** +_Parameters_ -- **registrySelector** `function`: Function receiving a registry object and returning a state selector. +- _registrySelector_ `function`: Function receiving a registry object and returning a state selector. -**Returns** +_Returns_ -`function`: marked registry selector. +- `function`: marked registry selector. -### dispatch - -[src/index.js#L92-L92](src/index.js#L92-L92) +# **dispatch** [\<>](src/index.js#L92-L92) Given the name of a registered store, returns an object of the store's action creators. Calling an action creator will cause it to be dispatched, updating the state value accordingly. -**Usage** +_Usage_ ```js const { dispatch } = wp.data; @@ -349,67 +339,55 @@ const { dispatch } = wp.data; dispatch( 'my-shop' ).setPrice( 'hammer', 9.75 ); ``` -**Parameters** - -- **name** `string`: Store name +_Parameters_ -**Returns** +- _name_ `string`: Store name -`Object`: Object containing the action creators. +_Returns_ -### plugins +- `Object`: Object containing the action creators. -[src/index.js#L18-L18](src/index.js#L18-L18) +# **plugins** [\<>](src/index.js#L18-L18) Undocumented declaration. -### registerGenericStore - -[src/index.js#L122-L122](src/index.js#L122-L122) +# **registerGenericStore** [\<>](src/index.js#L122-L122) Registers a generic store. -**Parameters** - -- **key** `string`: Store registry key. -- **config** `Object`: Configuration (getSelectors, getActions, subscribe). +_Parameters_ -### registerStore +- _key_ `string`: Store registry key. +- _config_ `Object`: Configuration (getSelectors, getActions, subscribe). -[src/index.js#L132-L132](src/index.js#L132-L132) +# **registerStore** [\<>](src/index.js#L132-L132) Registers a standard `@wordpress/data` store. -**Parameters** +_Parameters_ -- **reducerKey** `string`: Reducer key. -- **options** `Object`: Store description (reducer, actions, selectors, resolvers). +- _reducerKey_ `string`: Reducer key. +- _options_ `Object`: Store description (reducer, actions, selectors, resolvers). -**Returns** +_Returns_ -`Object`: Registered store object. +- `Object`: Registered store object. -### RegistryConsumer - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **RegistryConsumer** [\<>](src/index.js#L15-L15) Undocumented declaration. -### RegistryProvider - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **RegistryProvider** [\<>](src/index.js#L15-L15) Undocumented declaration. -### select - -[src/index.js#L76-L76](src/index.js#L76-L76) +# **select** [\<>](src/index.js#L76-L76) Given the name of a registered store, returns an object of the store's selectors. The selector functions are been pre-bound to pass the current state automatically. As a consumer, you need only pass arguments of the selector, if applicable. -**Usage** +_Usage_ ```js const { select } = wp.data; @@ -417,23 +395,21 @@ const { select } = wp.data; select( 'my-shop' ).getPrice( 'hammer' ); ``` -**Parameters** - -- **name** `string`: Store name +_Parameters_ -**Returns** +- _name_ `string`: Store name -`Object`: Object containing the store's selectors. +_Returns_ -### subscribe +- `Object`: Object containing the store's selectors. -[src/index.js#L114-L114](src/index.js#L114-L114) +# **subscribe** [\<>](src/index.js#L114-L114) Given a listener function, the function will be called any time the state value of one of the registered stores has changed. This function returns a `unsubscribe` function used to stop the subscription. -**Usage** +_Usage_ ```js const { subscribe } = wp.data; @@ -447,23 +423,19 @@ const unsubscribe = subscribe( () => { unsubscribe(); ``` -**Parameters** +_Parameters_ -- **listener** `Function`: Callback function. +- _listener_ `Function`: Callback function. -### use - -[src/index.js#L133-L133](src/index.js#L133-L133) +# **use** [\<>](src/index.js#L133-L133) Undocumented declaration. -### withDispatch - -[src/index.js#L13-L13](src/index.js#L13-L13) +# **withDispatch** [\<>](src/index.js#L13-L13) Higher-order component used to add dispatch props using registered action creators. -**Usage** +_Usage_ ```jsx function Button( { onClick, children } ) { @@ -517,37 +489,33 @@ const SaleButton = withDispatch( ( dispatch, ownProps, { select } ) => { _Note:_ It is important that the `mapDispatchToProps` function always returns an object with the same keys. For example, it should not contain conditions under which a different value would be returned. -**Parameters** +_Parameters_ -- **mapDispatchToProps** `Object`: Object of prop names where value is a dispatch-bound action creator, or a function to be called with with the component's props and returning an action creator. +- _mapDispatchToProps_ `Object`: Object of prop names where value is a dispatch-bound action creator, or a function to be called with with the component's props and returning an action creator. -**Returns** +_Returns_ -`Component`: Enhanced component with merged dispatcher props. +- `Component`: Enhanced component with merged dispatcher props. -### withRegistry - -[src/index.js#L14-L14](src/index.js#L14-L14) +# **withRegistry** [\<>](src/index.js#L14-L14) Higher-order component which renders the original component with the current registry context passed as its `registry` prop. -**Parameters** - -- **OriginalComponent** `WPComponent`: Original component. +_Parameters_ -**Returns** +- _OriginalComponent_ `WPComponent`: Original component. -`WPComponent`: Enhanced component. +_Returns_ -### withSelect +- `WPComponent`: Enhanced component. -[src/index.js#L12-L12](src/index.js#L12-L12) +# **withSelect** [\<>](src/index.js#L12-L12) Higher-order component used to inject state-derived props using registered selectors. -**Usage** +_Usage_ ```js function PriceDisplay( { price, currency } ) { @@ -575,13 +543,13 @@ const HammerPriceDisplay = withSelect( ( select, ownProps ) => { In the above example, when `HammerPriceDisplay` is rendered into an application, it will pass the price into the underlying `PriceDisplay` component and update automatically if the price of a hammer ever changes in the store. -**Parameters** +_Parameters_ -- **mapSelectToProps** `Function`: Function called on every state change, expected to return object of props to merge with the component's own props. +- _mapSelectToProps_ `Function`: Function called on every state change, expected to return object of props to merge with the component's own props. -**Returns** +_Returns_ -`Component`: Enhanced component with merged state data props. +- `Component`: Enhanced component with merged state data props. diff --git a/packages/date/README.md b/packages/date/README.md index fb201db6395cb3..8e26a27e82ff7c 100644 --- a/packages/date/README.md +++ b/packages/date/README.md @@ -16,104 +16,90 @@ _This package assumes that your code will run in an **ES2015+** environment. If -### date - -[src/index.js#L323-L327](src/index.js#L323-L327) +# **date** [\<>](src/index.js#L323-L327) Formats a date (like `date()` in PHP), in the site's timezone. -**Parameters** - -- **dateFormat** `string`: PHP-style formatting string. See php.net/date. -- **dateValue** `(Date|string|moment|null)`: Date object or string, parsable by moment.js. +_Parameters_ -**Returns** +- _dateFormat_ `string`: PHP-style formatting string. See php.net/date. +- _dateValue_ `(Date|string|moment|null)`: Date object or string, parsable by moment.js. -`string`: Formatted date. +_Returns_ -### dateI18n +- `string`: Formatted date. -[src/index.js#L356-L366](src/index.js#L356-L366) +# **dateI18n** [\<>](src/index.js#L356-L366) Formats a date (like `dateI18n()` in PHP). -**Parameters** +_Parameters_ -- **dateFormat** `string`: PHP-style formatting string. See php.net/date. -- **dateValue** `(Date|string|moment|null)`: Date object or string, parsable by moment.js. -- **gmt** `boolean`: True for GMT/UTC, false for site's timezone. +- _dateFormat_ `string`: PHP-style formatting string. See php.net/date. +- _dateValue_ `(Date|string|moment|null)`: Date object or string, parsable by moment.js. +- _gmt_ `boolean`: True for GMT/UTC, false for site's timezone. -**Returns** +_Returns_ -`string`: Formatted date. +- `string`: Formatted date. -### format - -[src/index.js#L282-L311](src/index.js#L282-L311) +# **format** [\<>](src/index.js#L282-L311) Formats a date. Does not alter the date's timezone. -**Parameters** - -- **dateFormat** `string`: PHP-style formatting string. See php.net/date. -- **dateValue** `(Date|string|moment|null)`: Date object or string, parsable by moment.js. +_Parameters_ -**Returns** +- _dateFormat_ `string`: PHP-style formatting string. See php.net/date. +- _dateValue_ `(Date|string|moment|null)`: Date object or string, parsable by moment.js. -`string`: Formatted date. +_Returns_ -### getDate +- `string`: Formatted date. -[src/index.js#L389-L395](src/index.js#L389-L395) +# **getDate** [\<>](src/index.js#L389-L395) Create and return a JavaScript Date Object from a date string in the WP timezone. -**Parameters** +_Parameters_ -- **dateString** `?string`: Date formatted in the WP timezone. +- _dateString_ `?string`: Date formatted in the WP timezone. -**Returns** +_Returns_ -`Date`: Date +- `Date`: Date -### gmdate - -[src/index.js#L339-L342](src/index.js#L339-L342) +# **gmdate** [\<>](src/index.js#L339-L342) Formats a date (like `date()` in PHP), in the UTC timezone. -**Parameters** - -- **dateFormat** `string`: PHP-style formatting string. See php.net/date. -- **dateValue** `(Date|string|moment|null)`: Date object or string, parsable by moment.js. +_Parameters_ -**Returns** +- _dateFormat_ `string`: PHP-style formatting string. See php.net/date. +- _dateValue_ `(Date|string|moment|null)`: Date object or string, parsable by moment.js. -`string`: Formatted date. +_Returns_ -### isInTheFuture +- `string`: Formatted date. -[src/index.js#L375-L380](src/index.js#L375-L380) +# **isInTheFuture** [\<>](src/index.js#L375-L380) Check whether a date is considered in the future according to the WordPress settings. -**Parameters** - -- **dateValue** `string`: Date String or Date object in the Defined WP Timezone. +_Parameters_ -**Returns** +- _dateValue_ `string`: Date String or Date object in the Defined WP Timezone. -`boolean`: Is in the future. +_Returns_ -### setSettings +- `boolean`: Is in the future. -[src/index.js#L36-L83](src/index.js#L36-L83) +# **setSettings** [\<>](src/index.js#L36-L83) Adds a locale to moment, using the format supplied by `wp_localize_script()`. -**Parameters** +_Parameters_ -- **dateSettings** `Object`: Settings, including locale data. +- _dateSettings_ `Object`: Settings, including locale data. diff --git a/packages/deprecated/README.md b/packages/deprecated/README.md index 8f03c2ec0b3cd1..b1eeec998ff556 100644 --- a/packages/deprecated/README.md +++ b/packages/deprecated/README.md @@ -32,13 +32,11 @@ addAction( 'deprecated', 'my-plugin/add-deprecation-alert', addDeprecationAlert -### default - -[src/index.js#L39-L78](src/index.js#L39-L78) +# **default** [\<>](src/index.js#L39-L78) Logs a message to notify developers about a deprecated feature. -**Usage** +_Usage_ ```js import deprecated from '@wordpress/deprecated'; @@ -53,26 +51,24 @@ deprecated( 'Eating meat', { // Logs: 'Eating meat is deprecated and will be removed from the earth in the future. Please use vegetables instead. Note: You may find it beneficial to transition gradually.' ``` -**Parameters** - -- **feature** `string`: Name of the deprecated feature. -- **options** `?Object`: Personalisation options -- **options.version** `?string`: Version in which the feature will be removed. -- **options.alternative** `?string`: Feature to use instead -- **options.plugin** `?string`: Plugin name if it's a plugin feature -- **options.link** `?string`: Link to documentation -- **options.hint** `?string`: Additional message to help transition away from the deprecated feature. +_Parameters_ -### logged +- _feature_ `string`: Name of the deprecated feature. +- _options_ `?Object`: Personalisation options +- _options.version_ `?string`: Version in which the feature will be removed. +- _options.alternative_ `?string`: Feature to use instead +- _options.plugin_ `?string`: Plugin name if it's a plugin feature +- _options.link_ `?string`: Link to documentation +- _options.hint_ `?string`: Additional message to help transition away from the deprecated feature. -[src/index.js#L12-L12](src/index.js#L12-L12) +# **logged** [\<>](src/index.js#L12-L12) Object map tracking messages which have been logged, for use in ensuring a message is only logged once. -**Type** +_Type_ -`Object` +- `Object` diff --git a/packages/docgen/src/markdown/formatter.js b/packages/docgen/src/markdown/formatter.js index 84b09a1b441f5c..df74712155afa1 100644 --- a/packages/docgen/src/markdown/formatter.js +++ b/packages/docgen/src/markdown/formatter.js @@ -19,7 +19,7 @@ const formatTag = ( title, tags, formatter, docs ) => { if ( tags && tags.length > 0 ) { docs.push( '\n' ); docs.push( '\n' ); - docs.push( `**${ title }**` ); + docs.push( `*${ title }*` ); docs.push( '\n' ); docs.push( ...tags.map( formatter ) ); } @@ -29,7 +29,7 @@ const formatExamples = ( tags, docs ) => { if ( tags && tags.length > 0 ) { docs.push( '\n' ); docs.push( '\n' ); - docs.push( '**Usage**' ); + docs.push( '*Usage*' ); docs.push( '\n' ); docs.push( '\n' ); docs.push( ...tags.map( @@ -57,6 +57,10 @@ const getHeading = ( index, text ) => { return '#'.repeat( index ) + ' ' + text; }; +const getSymbolHeading = ( text, source ) => { + return `# **${ text }** ${ `[<>](${ source })` }`; +}; + module.exports = function( rootDir, docPath, symbols, headingTitle, headingStartIndex ) { const docs = [ ]; let headingIndex = headingStartIndex || 1; @@ -87,8 +91,7 @@ module.exports = function( rootDir, docPath, symbols, headingTitle, headingStart path.basename( symbol.path ), ); const symbolPathWithLines = `${ symbolPath }#L${ symbol.lineStart }-L${ symbol.lineEnd }`; - docs.push( getHeading( headingIndex, `${ symbol.name }` ) ); - docs.push( `\n\n[${ symbolPathWithLines }](${ symbolPathWithLines })` ); + docs.push( getSymbolHeading( symbol.name, symbolPathWithLines ) ); formatDeprecated( getTagsByName( symbol.tags, 'deprecated' ), docs ); formatDescription( symbol.description, docs ); formatTag( @@ -101,19 +104,19 @@ module.exports = function( rootDir, docPath, symbols, headingTitle, headingStart formatTag( 'Type', getTagsByName( symbol.tags, 'type' ), - ( tag ) => `\n\`${ tag.type }\` ${ cleanSpaces( tag.description ) }`, + ( tag ) => `\n- \`${ tag.type }\` ${ cleanSpaces( tag.description ) }`, docs ); formatTag( 'Parameters', getTagsByName( symbol.tags, 'param' ), - ( tag ) => `\n- **${ tag.name }** \`${ tag.type }\`: ${ cleanSpaces( tag.description ) }`, + ( tag ) => `\n- *${ tag.name }* \`${ tag.type }\`: ${ cleanSpaces( tag.description ) }`, docs ); formatTag( 'Returns', getTagsByName( symbol.tags, 'return' ), - ( tag ) => `\n\`${ tag.type }\`: ${ cleanSpaces( tag.description ) }`, + ( tag ) => `\n- \`${ tag.type }\`: ${ cleanSpaces( tag.description ) }`, docs ); docs.push( '\n' ); diff --git a/packages/docgen/src/test/formatter-markdown.js b/packages/docgen/src/test/formatter-markdown.js index 953768eb5c604b..b3115519279193 100644 --- a/packages/docgen/src/test/formatter-markdown.js +++ b/packages/docgen/src/test/formatter-markdown.js @@ -28,7 +28,7 @@ describe( 'Formatter', () => { lineEnd: 2, } ], 'API docs' ); expect( docs ).toBe( - '# API docs\n\n## myDeclaration\n\n[home/my-path/docs-code.js#L1-L2](home/my-path/docs-code.js#L1-L2)\n\nMy declaration example.\n\n**Parameters**\n\n- **firstParam** `number`: First declaration parameter.\n\n**Returns**\n\n`number`: The result of the declaration.\n' + '# API docs\n\n# **myDeclaration** [<>](home/my-path/docs-code.js#L1-L2)\n\nMy declaration example.\n\n*Parameters*\n\n- *firstParam* `number`: First declaration parameter.\n\n*Returns*\n\n- `number`: The result of the declaration.\n' ); } ); } ); diff --git a/packages/dom-ready/README.md b/packages/dom-ready/README.md index 0c8515e57f3b17..7c6aa2c4333013 100644 --- a/packages/dom-ready/README.md +++ b/packages/dom-ready/README.md @@ -16,13 +16,11 @@ _This package assumes that your code will run in an **ES2015+** environment. If -### default - -[src/index.js#L29-L29](src/index.js#L29-L29) +# **default** [\<>](src/index.js#L29-L29) Specify a function to execute when the DOM is fully loaded. -**Usage** +_Usage_ ```js import domReady from '@wordpress/dom-ready'; @@ -32,13 +30,13 @@ domReady( function() { } ); ``` -**Parameters** +_Parameters_ -- **callback** `Function`: A function to execute after the DOM is ready. +- _callback_ `Function`: A function to execute after the DOM is ready. -**Returns** +_Returns_ -`void`: +- `void`: diff --git a/packages/dom/README.md b/packages/dom/README.md index bf572a4741b508..13f56014940971 100644 --- a/packages/dom/README.md +++ b/packages/dom/README.md @@ -14,256 +14,220 @@ npm install @wordpress/dom --save -### computeCaretRect - -[src/index.js#L13-L13](src/index.js#L13-L13) +# **computeCaretRect** [\<>](src/index.js#L13-L13) Get the rectangle for the selection in a container. -**Parameters** - -- **container** `Element`: Editable container. +_Parameters_ -**Returns** +- _container_ `Element`: Editable container. -`?DOMRect`: The rectangle. +_Returns_ -### documentHasSelection +- `?DOMRect`: The rectangle. -[src/index.js#L13-L13](src/index.js#L13-L13) +# **documentHasSelection** [\<>](src/index.js#L13-L13) Check wether the current document has a selection. This checks both for focus in an input field and general text selection. -**Returns** - -`boolean`: True if there is selection, false if not. +_Returns_ -### focus +- `boolean`: True if there is selection, false if not. -[src/index.js#L11-L11](src/index.js#L11-L11) +# **focus** [\<>](src/index.js#L11-L11) Object grouping `focusable` and `tabbable` utils under the keys with the same name. -### getOffsetParent - -[src/index.js#L13-L13](src/index.js#L13-L13) +# **getOffsetParent** [\<>](src/index.js#L13-L13) Returns the closest positioned element, or null under any of the conditions of the offsetParent specification. Unlike offsetParent, this function is not limited to HTMLElement and accepts any Node (e.g. Node.TEXT_NODE). -**Related** +_Related_ - -**Parameters** - -- **node** `Node`: Node from which to find offset parent. +_Parameters_ -**Returns** +- _node_ `Node`: Node from which to find offset parent. -`?Node`: Offset parent. +_Returns_ -### getRectangleFromRange +- `?Node`: Offset parent. -[src/index.js#L13-L13](src/index.js#L13-L13) +# **getRectangleFromRange** [\<>](src/index.js#L13-L13) Get the rectangle of a given Range. -**Parameters** +_Parameters_ -- **range** `Range`: The range. +- _range_ `Range`: The range. -**Returns** +_Returns_ -`DOMRect`: The rectangle. +- `DOMRect`: The rectangle. -### getScrollContainer - -[src/index.js#L13-L13](src/index.js#L13-L13) +# **getScrollContainer** [\<>](src/index.js#L13-L13) Given a DOM node, finds the closest scrollable container node. -**Parameters** - -- **node** `Element`: Node from which to start. +_Parameters_ -**Returns** +- _node_ `Element`: Node from which to start. -`?Element`: Scrollable container node, if found. +_Returns_ -### insertAfter +- `?Element`: Scrollable container node, if found. -[src/index.js#L13-L13](src/index.js#L13-L13) +# **insertAfter** [\<>](src/index.js#L13-L13) Given two DOM nodes, inserts the former in the DOM as the next sibling of the latter. -**Parameters** +_Parameters_ -- **newNode** `Element`: Node to be inserted. -- **referenceNode** `Element`: Node after which to perform the insertion. +- _newNode_ `Element`: Node to be inserted. +- _referenceNode_ `Element`: Node after which to perform the insertion. -**Returns** +_Returns_ -`void`: +- `void`: -### isEntirelySelected - -[src/index.js#L13-L13](src/index.js#L13-L13) +# **isEntirelySelected** [\<>](src/index.js#L13-L13) Check whether the contents of the element have been entirely selected. Returns true if there is no possibility of selection. -**Parameters** - -- **element** `Element`: The element to check. +_Parameters_ -**Returns** +- _element_ `Element`: The element to check. -`boolean`: True if entirely selected, false if not. +_Returns_ -### isHorizontalEdge +- `boolean`: True if entirely selected, false if not. -[src/index.js#L13-L13](src/index.js#L13-L13) +# **isHorizontalEdge** [\<>](src/index.js#L13-L13) Check whether the selection is horizontally at the edge of the container. -**Parameters** +_Parameters_ -- **container** `Element`: Focusable element. -- **isReverse** `boolean`: Set to true to check left, false for right. +- _container_ `Element`: Focusable element. +- _isReverse_ `boolean`: Set to true to check left, false for right. -**Returns** +_Returns_ -`boolean`: True if at the horizontal edge, false if not. +- `boolean`: True if at the horizontal edge, false if not. -### isTextField - -[src/index.js#L13-L13](src/index.js#L13-L13) +# **isTextField** [\<>](src/index.js#L13-L13) Check whether the given element is a text field, where text field is defined by the ability to select within the input, or that it is contenteditable. See: -**Parameters** - -- **element** `HTMLElement`: The HTML element. +_Parameters_ -**Returns** +- _element_ `HTMLElement`: The HTML element. -`boolean`: True if the element is an text field, false if not. +_Returns_ -### isVerticalEdge +- `boolean`: True if the element is an text field, false if not. -[src/index.js#L13-L13](src/index.js#L13-L13) +# **isVerticalEdge** [\<>](src/index.js#L13-L13) Check whether the selection is vertically at the edge of the container. -**Parameters** - -- **container** `Element`: Focusable element. -- **isReverse** `boolean`: Set to true to check top, false for bottom. +_Parameters_ -**Returns** +- _container_ `Element`: Focusable element. +- _isReverse_ `boolean`: Set to true to check top, false for bottom. -`boolean`: True if at the edge, false if not. +_Returns_ -### placeCaretAtHorizontalEdge +- `boolean`: True if at the edge, false if not. -[src/index.js#L13-L13](src/index.js#L13-L13) +# **placeCaretAtHorizontalEdge** [\<>](src/index.js#L13-L13) Places the caret at start or end of a given element. -**Parameters** +_Parameters_ -- **container** `Element`: Focusable element. -- **isReverse** `boolean`: True for end, false for start. +- _container_ `Element`: Focusable element. +- _isReverse_ `boolean`: True for end, false for start. -### placeCaretAtVerticalEdge - -[src/index.js#L13-L13](src/index.js#L13-L13) +# **placeCaretAtVerticalEdge** [\<>](src/index.js#L13-L13) Places the caret at the top or bottom of a given element. -**Parameters** - -- **container** `Element`: Focusable element. -- **isReverse** `boolean`: True for bottom, false for top. -- **rect** `[DOMRect]`: The rectangle to position the caret with. -- **mayUseScroll** `[boolean]`: True to allow scrolling, false to disallow. +_Parameters_ -### remove +- _container_ `Element`: Focusable element. +- _isReverse_ `boolean`: True for bottom, false for top. +- _rect_ `[DOMRect]`: The rectangle to position the caret with. +- _mayUseScroll_ `[boolean]`: True to allow scrolling, false to disallow. -[src/index.js#L13-L13](src/index.js#L13-L13) +# **remove** [\<>](src/index.js#L13-L13) Given a DOM node, removes it from the DOM. -**Parameters** +_Parameters_ -- **node** `Element`: Node to be removed. +- _node_ `Element`: Node to be removed. -**Returns** +_Returns_ -`void`: +- `void`: -### replace - -[src/index.js#L13-L13](src/index.js#L13-L13) +# **replace** [\<>](src/index.js#L13-L13) Given two DOM nodes, replaces the former with the latter in the DOM. -**Parameters** - -- **processedNode** `Element`: Node to be removed. -- **newNode** `Element`: Node to be inserted in its place. +_Parameters_ -**Returns** +- _processedNode_ `Element`: Node to be removed. +- _newNode_ `Element`: Node to be inserted in its place. -`void`: +_Returns_ -### replaceTag +- `void`: -[src/index.js#L13-L13](src/index.js#L13-L13) +# **replaceTag** [\<>](src/index.js#L13-L13) Replaces the given node with a new node with the given tag name. -**Parameters** +_Parameters_ -- **node** `Element`: The node to replace -- **tagName** `string`: The new tag name. +- _node_ `Element`: The node to replace +- _tagName_ `string`: The new tag name. -**Returns** +_Returns_ -`Element`: The new node. +- `Element`: The new node. -### unwrap - -[src/index.js#L13-L13](src/index.js#L13-L13) +# **unwrap** [\<>](src/index.js#L13-L13) Unwrap the given node. This means any child nodes are moved to the parent. -**Parameters** - -- **node** `Node`: The node to unwrap. +_Parameters_ -**Returns** +- _node_ `Node`: The node to unwrap. -`void`: +_Returns_ -### wrap +- `void`: -[src/index.js#L13-L13](src/index.js#L13-L13) +# **wrap** [\<>](src/index.js#L13-L13) Wraps the given node with a new node with the given tag name. -**Parameters** +_Parameters_ -- **newNode** `Element`: The node to insert. -- **referenceNode** `Element`: The node to wrap. +- _newNode_ `Element`: The node to insert. +- _referenceNode_ `Element`: The node to wrap. diff --git a/packages/e2e-test-utils/README.md b/packages/e2e-test-utils/README.md index 3f08ca78766cff..da4138a9376d16 100644 --- a/packages/e2e-test-utils/README.md +++ b/packages/e2e-test-utils/README.md @@ -14,499 +14,405 @@ npm install @wordpress/e2e-test-utils --save-dev -### activatePlugin - -[src/index.js#L1-L1](src/index.js#L1-L1) +# **activatePlugin** [\<>](src/index.js#L1-L1) Activates an installed plugin. -**Parameters** - -- **slug** `string`: Plugin slug. +_Parameters_ -### arePrePublishChecksEnabled +- _slug_ `string`: Plugin slug. -[src/index.js#L2-L2](src/index.js#L2-L2) +# **arePrePublishChecksEnabled** [\<>](src/index.js#L2-L2) Verifies if publish checks are enabled. -**Returns** +_Returns_ -`boolean`: Boolean which represents the state of prepublish checks. +- `boolean`: Boolean which represents the state of prepublish checks. -### clearLocalStorage - -[src/index.js#L3-L3](src/index.js#L3-L3) +# **clearLocalStorage** [\<>](src/index.js#L3-L3) Clears the local storage. -### clickBlockAppender - -[src/index.js#L4-L4](src/index.js#L4-L4) +# **clickBlockAppender** [\<>](src/index.js#L4-L4) Clicks the default block appender. -### clickBlockToolbarButton - -[src/index.js#L5-L5](src/index.js#L5-L5) +# **clickBlockToolbarButton** [\<>](src/index.js#L5-L5) Clicks a block toolbar button. -**Parameters** - -- **buttonAriaLabel** `string`: The aria label of the button to click. +_Parameters_ -### clickButton +- _buttonAriaLabel_ `string`: The aria label of the button to click. -[src/index.js#L6-L6](src/index.js#L6-L6) +# **clickButton** [\<>](src/index.js#L6-L6) Clicks a button based on the text on the button. -**Parameters** - -- **buttonText** `string`: The text that appears on the button to click. +_Parameters_ -### clickOnCloseModalButton +- _buttonText_ `string`: The text that appears on the button to click. -[src/index.js#L7-L7](src/index.js#L7-L7) +# **clickOnCloseModalButton** [\<>](src/index.js#L7-L7) Click on the close button of an open modal. -**Parameters** +_Parameters_ -- **modalClassName** `?string`: Class name for the modal to close +- _modalClassName_ `?string`: Class name for the modal to close -### clickOnMoreMenuItem - -[src/index.js#L8-L8](src/index.js#L8-L8) +# **clickOnMoreMenuItem** [\<>](src/index.js#L8-L8) Clicks on More Menu item, searches for the button with the text provided and clicks it. -**Parameters** - -- **buttonLabel** `string`: The label to search the button for. +_Parameters_ -### createEmbeddingMatcher +- _buttonLabel_ `string`: The label to search the button for. -[src/index.js#L52-L52](src/index.js#L52-L52) +# **createEmbeddingMatcher** [\<>](src/index.js#L52-L52) Creates a function to determine if a request is embedding a certain URL. -**Parameters** +_Parameters_ -- **url** `string`: The URL to check against a request. +- _url_ `string`: The URL to check against a request. -**Returns** +_Returns_ -`function`: Function that determines if a request is for the embed API, embedding a specific URL. +- `function`: Function that determines if a request is for the embed API, embedding a specific URL. -### createJSONResponse - -[src/index.js#L52-L52](src/index.js#L52-L52) +# **createJSONResponse** [\<>](src/index.js#L52-L52) Respond to a request with a JSON response. -**Parameters** - -- **mockResponse** `string`: The mock object to wrap in a JSON response. +_Parameters_ -**Returns** +- _mockResponse_ `string`: The mock object to wrap in a JSON response. -`Promise`: Promise that responds to a request with the mock JSON response. +_Returns_ -### createNewPost +- `Promise`: Promise that responds to a request with the mock JSON response. -[src/index.js#L9-L9](src/index.js#L9-L9) +# **createNewPost** [\<>](src/index.js#L9-L9) Creates new post. -**Parameters** +_Parameters_ -- **obj** `Object`: Object to create new post, along with tips enabling option. +- _obj_ `Object`: Object to create new post, along with tips enabling option. -### createURL - -[src/index.js#L10-L10](src/index.js#L10-L10) +# **createURL** [\<>](src/index.js#L10-L10) Creates new URL by parsing base URL, WPPath and query string. -**Parameters** - -- **WPPath** `string`: String to be serialized as pathname. -- **query** `?string`: String to be serialized as query portion of URL. +_Parameters_ -**Returns** +- _WPPath_ `string`: String to be serialized as pathname. +- _query_ `?string`: String to be serialized as query portion of URL. -`string`: String which represents full URL. +_Returns_ -### createURLMatcher +- `string`: String which represents full URL. -[src/index.js#L52-L52](src/index.js#L52-L52) +# **createURLMatcher** [\<>](src/index.js#L52-L52) Creates a function to determine if a request is calling a URL with the substring present. -**Parameters** - -- **substring** `string`: The substring to check for. +_Parameters_ -**Returns** +- _substring_ `string`: The substring to check for. -`function`: Function that determines if a request's URL contains substring. +_Returns_ -### deactivatePlugin +- `function`: Function that determines if a request's URL contains substring. -[src/index.js#L11-L11](src/index.js#L11-L11) +# **deactivatePlugin** [\<>](src/index.js#L11-L11) Deactivates an active plugin. -**Parameters** +_Parameters_ -- **slug** `string`: Plugin slug. +- _slug_ `string`: Plugin slug. -### disablePrePublishChecks - -[src/index.js#L12-L12](src/index.js#L12-L12) +# **disablePrePublishChecks** [\<>](src/index.js#L12-L12) Disables Pre-publish checks. -### enablePageDialogAccept - -[src/index.js#L13-L13](src/index.js#L13-L13) +# **enablePageDialogAccept** [\<>](src/index.js#L13-L13) Enables even listener which accepts a page dialog which may appear when navigating away from Gutenberg. -### enablePrePublishChecks - -[src/index.js#L14-L14](src/index.js#L14-L14) +# **enablePrePublishChecks** [\<>](src/index.js#L14-L14) Enables Pre-publish checks. -### ensureSidebarOpened - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **ensureSidebarOpened** [\<>](src/index.js#L15-L15) Verifies that the edit post sidebar is opened, and if it is not, opens it. -**Returns** +_Returns_ -`Promise`: Promise resolving once the edit post sidebar is opened. +- `Promise`: Promise resolving once the edit post sidebar is opened. -### findSidebarPanelToggleButtonWithTitle - -[src/index.js#L16-L16](src/index.js#L16-L16) +# **findSidebarPanelToggleButtonWithTitle** [\<>](src/index.js#L16-L16) Finds a sidebar panel with the provided title. -**Parameters** - -- **panelTitle** `string`: The name of sidebar panel. +_Parameters_ -**Returns** +- _panelTitle_ `string`: The name of sidebar panel. -`?ElementHandle`: Object that represents an in-page DOM element. +_Returns_ -### findSidebarPanelWithTitle +- `?ElementHandle`: Object that represents an in-page DOM element. -[src/index.js#L17-L17](src/index.js#L17-L17) +# **findSidebarPanelWithTitle** [\<>](src/index.js#L17-L17) Finds the button responsible for toggling the sidebar panel with the provided title. -**Parameters** - -- **panelTitle** `string`: The name of sidebar panel. +_Parameters_ -**Returns** +- _panelTitle_ `string`: The name of sidebar panel. -`?ElementHandle`: Object that represents an in-page DOM element. +_Returns_ -### getAllBlockInserterItemTitles +- `?ElementHandle`: Object that represents an in-page DOM element. -[src/index.js#L18-L18](src/index.js#L18-L18) +# **getAllBlockInserterItemTitles** [\<>](src/index.js#L18-L18) Returns an array of strings with all inserter item titles. -**Returns** +_Returns_ -`Promise`: Promise resolving with an array containing all inserter item titles. +- `Promise`: Promise resolving with an array containing all inserter item titles. -### getAllBlocks - -[src/index.js#L19-L19](src/index.js#L19-L19) +# **getAllBlocks** [\<>](src/index.js#L19-L19) Returns an array with all blocks; Equivalent to calling wp.data.select( 'core/editor' ).getBlocks(); -**Returns** - -`Promise`: Promise resolving with an array containing all blocks in the document. +_Returns_ -### getAvailableBlockTransforms +- `Promise`: Promise resolving with an array containing all blocks in the document. -[src/index.js#L20-L20](src/index.js#L20-L20) +# **getAvailableBlockTransforms** [\<>](src/index.js#L20-L20) Returns an array of strings with all block titles, that the current selected block can be transformed into. -**Returns** +_Returns_ -`Promise`: Promise resolving with an array containing all possible block transforms +- `Promise`: Promise resolving with an array containing all possible block transforms -### getBlockSetting - -[src/index.js#L21-L21](src/index.js#L21-L21) +# **getBlockSetting** [\<>](src/index.js#L21-L21) Returns a string containing the block title associated with the provided block name. -**Parameters** - -- **blockName** `string`: Block name. -- **setting** `string`: Block setting e.g: title, attributes.... +_Parameters_ -**Returns** +- _blockName_ `string`: Block name. +- _setting_ `string`: Block setting e.g: title, attributes.... -`Promise`: Promise resolving with a string containing the block title. +_Returns_ -### getEditedPostContent +- `Promise`: Promise resolving with a string containing the block title. -[src/index.js#L22-L22](src/index.js#L22-L22) +# **getEditedPostContent** [\<>](src/index.js#L22-L22) Returns a promise which resolves with the edited post content (HTML string). -**Returns** +_Returns_ -`Promise`: Promise resolving with post content markup. +- `Promise`: Promise resolving with post content markup. -### hasBlockSwitcher - -[src/index.js#L23-L23](src/index.js#L23-L23) +# **hasBlockSwitcher** [\<>](src/index.js#L23-L23) Returns a boolean indicating if the current selected block has a block switcher or not. -**Returns** - -`Promise`: Promise resolving with a boolean. +_Returns_ -### insertBlock +- `Promise`: Promise resolving with a boolean. -[src/index.js#L24-L24](src/index.js#L24-L24) +# **insertBlock** [\<>](src/index.js#L24-L24) Opens the inserter, searches for the given term, then selects the first result that appears. -**Parameters** - -- **searchTerm** `string`: The text to search the inserter for. -- **panelName** `string`: The inserter panel to open (if it's closed by default). +_Parameters_ -### installPlugin +- _searchTerm_ `string`: The text to search the inserter for. +- _panelName_ `string`: The inserter panel to open (if it's closed by default). -[src/index.js#L25-L25](src/index.js#L25-L25) +# **installPlugin** [\<>](src/index.js#L25-L25) Installs a plugin from the WP.org repository. -**Parameters** +_Parameters_ -- **slug** `string`: Plugin slug. -- **searchTerm** `?string`: If the plugin is not findable by its slug use an alternative term to search. +- _slug_ `string`: Plugin slug. +- _searchTerm_ `?string`: If the plugin is not findable by its slug use an alternative term to search. -### isCurrentURL - -[src/index.js#L26-L26](src/index.js#L26-L26) +# **isCurrentURL** [\<>](src/index.js#L26-L26) Checks if current URL is a WordPress path. -**Parameters** - -- **WPPath** `string`: String to be serialized as pathname. -- **query** `?string`: String to be serialized as query portion of URL. +_Parameters_ -**Returns** +- _WPPath_ `string`: String to be serialized as pathname. +- _query_ `?string`: String to be serialized as query portion of URL. -`boolean`: Boolean represents whether current URL is or not a WordPress path. +_Returns_ -### isInDefaultBlock +- `boolean`: Boolean represents whether current URL is or not a WordPress path. -[src/index.js#L27-L27](src/index.js#L27-L27) +# **isInDefaultBlock** [\<>](src/index.js#L27-L27) Checks if the block that is focused is the default block. -**Returns** +_Returns_ -`Promise`: Promise resolving with a boolean indicating if the focused block is the default block. +- `Promise`: Promise resolving with a boolean indicating if the focused block is the default block. -### loginUser - -[src/index.js#L28-L28](src/index.js#L28-L28) +# **loginUser** [\<>](src/index.js#L28-L28) Performs log in with specified username and password. -**Parameters** - -- **username** `?string`: String to be used as user credential. -- **password** `?string`: String to be used as user credential. +_Parameters_ -### mockOrTransform +- _username_ `?string`: String to be used as user credential. +- _password_ `?string`: String to be used as user credential. -[src/index.js#L52-L52](src/index.js#L52-L52) +# **mockOrTransform** [\<>](src/index.js#L52-L52) Mocks a request with the supplied mock object, or allows it to run with an optional transform, based on the deserialised JSON response for the request. -**Parameters** +_Parameters_ -- **mockCheck** `function`: function that returns true if the request should be mocked. -- **mock** `Object`: A mock object to wrap in a JSON response, if the request should be mocked. -- **responseObjectTransform** `(function|undefined)`: An optional function that transforms the response's object before the response is used. +- _mockCheck_ `function`: function that returns true if the request should be mocked. +- _mock_ `Object`: A mock object to wrap in a JSON response, if the request should be mocked. +- _responseObjectTransform_ `(function|undefined)`: An optional function that transforms the response's object before the response is used. -**Returns** +_Returns_ -`Promise`: Promise that uses `mockCheck` to see if a request should be mocked with `mock`, and optionally transforms the response with `responseObjectTransform`. +- `Promise`: Promise that uses `mockCheck` to see if a request should be mocked with `mock`, and optionally transforms the response with `responseObjectTransform`. -### observeFocusLoss - -[src/index.js#L29-L29](src/index.js#L29-L29) +# **observeFocusLoss** [\<>](src/index.js#L29-L29) Binds to the document on page load which throws an error if a `focusout` event occurs without a related target (i.e. focus loss). -### openAllBlockInserterCategories - -[src/index.js#L30-L30](src/index.js#L30-L30) +# **openAllBlockInserterCategories** [\<>](src/index.js#L30-L30) Opens all block inserter categories. -### openDocumentSettingsSidebar - -[src/index.js#L31-L31](src/index.js#L31-L31) +# **openDocumentSettingsSidebar** [\<>](src/index.js#L31-L31) Clicks on the button in the header which opens Document Settings sidebar when it is closed. -### openGlobalBlockInserter - -[src/index.js#L32-L32](src/index.js#L32-L32) +# **openGlobalBlockInserter** [\<>](src/index.js#L32-L32) Opens the global block inserter. -### openPublishPanel - -[src/index.js#L33-L33](src/index.js#L33-L33) +# **openPublishPanel** [\<>](src/index.js#L33-L33) Opens the publish panel. -### pressKeyTimes - -[src/index.js#L34-L34](src/index.js#L34-L34) +# **pressKeyTimes** [\<>](src/index.js#L34-L34) Presses the given keyboard key a number of times in sequence. -**Parameters** - -- **key** `string`: Key to press. -- **count** `number`: Number of times to press. +_Parameters_ -**Returns** +- _key_ `string`: Key to press. +- _count_ `number`: Number of times to press. -`Promise`: Promise resolving when key presses complete. +_Returns_ -### pressKeyWithModifier +- `Promise`: Promise resolving when key presses complete. -[src/index.js#L35-L35](src/index.js#L35-L35) +# **pressKeyWithModifier** [\<>](src/index.js#L35-L35) Performs a key press with modifier (Shift, Control, Meta, Alt), where each modifier is normalized to platform-specific modifier. -**Parameters** +_Parameters_ -- **modifier** `string`: Modifier key. -- **key** `string`: Key to press while modifier held. +- _modifier_ `string`: Modifier key. +- _key_ `string`: Key to press while modifier held. -### publishPost - -[src/index.js#L36-L36](src/index.js#L36-L36) +# **publishPost** [\<>](src/index.js#L36-L36) Publishes the post, resolving once the request is complete (once a notice is displayed). -**Returns** - -`Promise`: Promise resolving when publish is complete. +_Returns_ -### publishPostWithPrePublishChecksDisabled +- `Promise`: Promise resolving when publish is complete. -[src/index.js#L37-L37](src/index.js#L37-L37) +# **publishPostWithPrePublishChecksDisabled** [\<>](src/index.js#L37-L37) Publishes the post without the pre-publish checks, resolving once the request is complete (once a notice is displayed). -**Returns** - -`Promise`: Promise resolving when publish is complete. +_Returns_ -### saveDraft +- `Promise`: Promise resolving when publish is complete. -[src/index.js#L38-L38](src/index.js#L38-L38) +# **saveDraft** [\<>](src/index.js#L38-L38) Saves the post as a draft, resolving once the request is complete (once the "Saved" indicator is displayed). -**Returns** +_Returns_ -`Promise`: Promise resolving when draft save is complete. +- `Promise`: Promise resolving when draft save is complete. -### searchForBlock - -[src/index.js#L39-L39](src/index.js#L39-L39) +# **searchForBlock** [\<>](src/index.js#L39-L39) Search for block in the global inserter -**Parameters** - -- **searchTerm** `string`: The text to search the inserter for. +_Parameters_ -### selectBlockByClientId +- _searchTerm_ `string`: The text to search the inserter for. -[src/index.js#L40-L40](src/index.js#L40-L40) +# **selectBlockByClientId** [\<>](src/index.js#L40-L40) Given the clientId of a block, selects the block on the editor. -**Parameters** +_Parameters_ -- **clientId** `string`: Identified of the block. +- _clientId_ `string`: Identified of the block. -### setBrowserViewport - -[src/index.js#L41-L41](src/index.js#L41-L41) +# **setBrowserViewport** [\<>](src/index.js#L41-L41) Sets browser viewport to specified type. -**Parameters** - -- **type** `string`: String to represent dimensions type; can be either small or large. +_Parameters_ -### setPostContent +- _type_ `string`: String to represent dimensions type; can be either small or large. -[src/index.js#L42-L42](src/index.js#L42-L42) +# **setPostContent** [\<>](src/index.js#L42-L42) Sets code editor content -**Parameters** +_Parameters_ -- **content** `string`: New code editor content. +- _content_ `string`: New code editor content. -**Returns** +_Returns_ -`Promise`: Promise resolving with an array containing all blocks in the document. +- `Promise`: Promise resolving with an array containing all blocks in the document. -### setUpResponseMocking - -[src/index.js#L52-L52](src/index.js#L52-L52) +# **setUpResponseMocking** [\<>](src/index.js#L52-L52) Sets up mock checks and responses. Accepts a list of mock settings with the following properties: - `match`: function to check if a request should be mocked. - `onRequestMatch`: async function to respond to the request. -**Usage** +_Usage_ ```js const MOCK_RESPONSES = [ @@ -524,89 +430,73 @@ setUpResponseMocking( MOCK_RESPONSES ); If none of the mock settings match the request, the request is allowed to continue. -**Parameters** - -- **mocks** `Array`: Array of mock settings. +_Parameters_ -### switchEditorModeTo +- _mocks_ `Array`: Array of mock settings. -[src/index.js#L43-L43](src/index.js#L43-L43) +# **switchEditorModeTo** [\<>](src/index.js#L43-L43) Switches editor mode. -**Parameters** - -- **mode** `string`: String editor mode. +_Parameters_ -### switchUserToAdmin +- _mode_ `string`: String editor mode. -[src/index.js#L44-L44](src/index.js#L44-L44) +# **switchUserToAdmin** [\<>](src/index.js#L44-L44) Switches the current user to the admin user (if the user running the test is not already the admin user). -### switchUserToTest - -[src/index.js#L45-L45](src/index.js#L45-L45) +# **switchUserToTest** [\<>](src/index.js#L45-L45) Switches the current user to whichever user we should be running the tests as (if we're not already that user). -### toggleScreenOption - -[src/index.js#L46-L46](src/index.js#L46-L46) +# **toggleScreenOption** [\<>](src/index.js#L46-L46) Toggles the screen option with the given label. -**Parameters** - -- **label** `string`: The label of the screen option, e.g. 'Show Tips'. -- **shouldBeChecked** `?boolean`: If true, turns the option on. If false, off. If undefined, the option will be toggled. +_Parameters_ -### transformBlockTo +- _label_ `string`: The label of the screen option, e.g. 'Show Tips'. +- _shouldBeChecked_ `?boolean`: If true, turns the option on. If false, off. If undefined, the option will be toggled. -[src/index.js#L47-L47](src/index.js#L47-L47) +# **transformBlockTo** [\<>](src/index.js#L47-L47) Converts editor's block type. -**Parameters** +_Parameters_ -- **name** `string`: Block name. +- _name_ `string`: Block name. -### uninstallPlugin - -[src/index.js#L48-L48](src/index.js#L48-L48) +# **uninstallPlugin** [\<>](src/index.js#L48-L48) Uninstalls a plugin. -**Parameters** - -- **slug** `string`: Plugin slug. +_Parameters_ -### visitAdminPage +- _slug_ `string`: Plugin slug. -[src/index.js#L49-L49](src/index.js#L49-L49) +# **visitAdminPage** [\<>](src/index.js#L49-L49) Visits admin page; if user is not logged in then it logging in it first, then visits admin page. -**Parameters** - -- **adminPath** `string`: String to be serialized as pathname. -- **query** `string`: String to be serialized as query portion of URL. +_Parameters_ -### waitForWindowDimensions +- _adminPath_ `string`: String to be serialized as pathname. +- _query_ `string`: String to be serialized as query portion of URL. -[src/index.js#L50-L50](src/index.js#L50-L50) +# **waitForWindowDimensions** [\<>](src/index.js#L50-L50) Function that waits until the page viewport has the required dimensions. It is being used to address a problem where after using setViewport the execution may continue, without the new dimensions being applied. -**Parameters** +_Parameters_ -- **width** `number`: Width of the window. -- **height** `height`: Height of the window. +- _width_ `number`: Width of the window. +- _height_ `height`: Height of the window. diff --git a/packages/edit-post/README.md b/packages/edit-post/README.md index 0c8eb1326e8846..2192cc6dbcf421 100644 --- a/packages/edit-post/README.md +++ b/packages/edit-post/README.md @@ -27,30 +27,26 @@ They can be found in the global variable `wp.editPost` when defining `wp-edit-po -### initializeEditor - -[src/index.js#L66-L96](src/index.js#L66-L96) +# **initializeEditor** [\<>](src/index.js#L66-L96) Initializes and returns an instance of Editor. The return value of this function is not necessary if we change where we call initializeEditor(). This is due to metaBox timing. -**Parameters** - -- **id** `string`: Unique identifier for editor instance. -- **postType** `Object`: Post type of the post to edit. -- **postId** `Object`: ID of the post to edit. -- **settings** `?Object`: Editor settings object. -- **initialEdits** `Object`: Programmatic edits to apply initially, to be considered as non-user-initiated (bypass for unsaved changes prompt). +_Parameters_ -### PluginBlockSettingsMenuItem +- _id_ `string`: Unique identifier for editor instance. +- _postType_ `Object`: Post type of the post to edit. +- _postId_ `Object`: ID of the post to edit. +- _settings_ `?Object`: Editor settings object. +- _initialEdits_ `Object`: Programmatic edits to apply initially, to be considered as non-user-initiated (bypass for unsaved changes prompt). -[src/index.js#L98-L98](src/index.js#L98-L98) +# **PluginBlockSettingsMenuItem** [\<>](src/index.js#L98-L98) Renders a new item in the block settings menu. -**Usage** +_Usage_ ```js // Using ES5 syntax @@ -92,26 +88,24 @@ const MyPluginBlockSettingsMenuItem = () => ( ); ``` -**Parameters** - -- **props** `Object`: Component props. -- **props.allowedBlockNames** `[Array]`: An array containing a list of block names for which the item should be shown. If not present, it'll be rendered for any block. If multiple blocks are selected, it'll be shown if and only if all of them are in the whitelist. -- **props.icon** `[(string|Element)]`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element. -- **props.label** `string`: The menu item text. -- **props.onClick** `Function`: Callback function to be executed when the user click the menu item. +_Parameters_ -**Returns** +- _props_ `Object`: Component props. +- _props.allowedBlockNames_ `[Array]`: An array containing a list of block names for which the item should be shown. If not present, it'll be rendered for any block. If multiple blocks are selected, it'll be shown if and only if all of them are in the whitelist. +- _props.icon_ `[(string|Element)]`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element. +- _props.label_ `string`: The menu item text. +- _props.onClick_ `Function`: Callback function to be executed when the user click the menu item. -`WPElement`: The WPElement to be rendered. +_Returns_ -### PluginMoreMenuItem +- `WPElement`: The WPElement to be rendered. -[src/index.js#L99-L99](src/index.js#L99-L99) +# **PluginMoreMenuItem** [\<>](src/index.js#L99-L99) Renders a menu item in `Plugins` group in `More Menu` drop down, and can be used to as a button or link depending on the props provided. The text within the component appears as the menu item label. -**Usage** +_Usage_ ```js // Using ES5 syntax @@ -153,26 +147,24 @@ const MyButtonMoreMenuItem = () => ( ); ``` -**Parameters** +_Parameters_ -- **props** `Object`: Component properties. -- **props.href** `[string]`: When `href` is provided then the menu item is represented as an anchor rather than button. It corresponds to the `href` attribute of the anchor. -- **props.icon** `[(string|Element)]`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered to the left of the menu item label. -- **props.onClick** `[Function]`: The callback function to be executed when the user clicks the menu item. -- **props.other** `[...*]`: Any additional props are passed through to the underlying [MenuItem](/packages/components/src/menu-item/README.md) component. +- _props_ `Object`: Component properties. +- _props.href_ `[string]`: When `href` is provided then the menu item is represented as an anchor rather than button. It corresponds to the `href` attribute of the anchor. +- _props.icon_ `[(string|Element)]`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered to the left of the menu item label. +- _props.onClick_ `[Function]`: The callback function to be executed when the user clicks the menu item. +- _props.other_ `[...*]`: Any additional props are passed through to the underlying [MenuItem](/packages/components/src/menu-item/README.md) component. -**Returns** +_Returns_ -`WPElement`: The element to be rendered. +- `WPElement`: The element to be rendered. -### PluginPostPublishPanel - -[src/index.js#L100-L100](src/index.js#L100-L100) +# **PluginPostPublishPanel** [\<>](src/index.js#L100-L100) Renders provided content to the post-publish panel in the publish flow (side panel that opens after a user publishes the post). -**Usage** +_Usage_ ```js // Using ES5 syntax @@ -208,26 +200,24 @@ const MyPluginPostPublishPanel = () => ( ); ``` -**Parameters** - -- **props** `Object`: Component properties. -- **props.className** `[string]`: An optional class name added to the panel. -- **props.title** `[string]`: Title displayed at the top of the panel. -- **props.initialOpen** `[boolean]`: Whether to have the panel initially opened. When no title is provided it is always opened. +_Parameters_ -**Returns** +- _props_ `Object`: Component properties. +- _props.className_ `[string]`: An optional class name added to the panel. +- _props.title_ `[string]`: Title displayed at the top of the panel. +- _props.initialOpen_ `[boolean]`: Whether to have the panel initially opened. When no title is provided it is always opened. -`WPElement`: The WPElement to be rendered. +_Returns_ -### PluginPostStatusInfo +- `WPElement`: The WPElement to be rendered. -[src/index.js#L101-L101](src/index.js#L101-L101) +# **PluginPostStatusInfo** [\<>](src/index.js#L101-L101) Renders a row in the Status & Visibility panel of the Document sidebar. It should be noted that this is named and implemented around the function it serves and not its location, which may change in future iterations. -**Usage** +_Usage_ ```js // Using ES5 syntax @@ -259,23 +249,21 @@ const MyPluginPostStatusInfo = () => ( ); ``` -**Parameters** +_Parameters_ -- **props** `Object`: Component properties. -- **props.className** `[string]`: An optional class name added to the row. +- _props_ `Object`: Component properties. +- _props.className_ `[string]`: An optional class name added to the row. -**Returns** +_Returns_ -`WPElement`: The WPElement to be rendered. +- `WPElement`: The WPElement to be rendered. -### PluginPrePublishPanel - -[src/index.js#L102-L102](src/index.js#L102-L102) +# **PluginPrePublishPanel** [\<>](src/index.js#L102-L102) Renders provided content to the pre-publish side panel in the publish flow (side panel that opens when a user first pushes "Publish" from the main editor). -**Usage** +_Usage_ ```js // Using ES5 syntax @@ -311,20 +299,18 @@ const MyPluginPrePublishPanel = () => ( ); ``` -**Parameters** - -- **props** `Object`: Component props. -- **props.className** `[string]`: An optional class name added to the panel. -- **props.title** `[string]`: Title displayed at the top of the panel. -- **props.initialOpen** `[boolean]`: Whether to have the panel initially opened. When no title is provided it is always opened. +_Parameters_ -**Returns** +- _props_ `Object`: Component props. +- _props.className_ `[string]`: An optional class name added to the panel. +- _props.title_ `[string]`: Title displayed at the top of the panel. +- _props.initialOpen_ `[boolean]`: Whether to have the panel initially opened. When no title is provided it is always opened. -`WPElement`: The WPElement to be rendered. +_Returns_ -### PluginSidebar +- `WPElement`: The WPElement to be rendered. -[src/index.js#L103-L103](src/index.js#L103-L103) +# **PluginSidebar** [\<>](src/index.js#L103-L103) Renders a sidebar when activated. The contents within the `PluginSidebar` will appear as content within the sidebar. If you wish to display the sidebar, you can with use the `PluginSidebarMoreMenuItem` component or the `wp.data.dispatch` API: @@ -333,11 +319,11 @@ If you wish to display the sidebar, you can with use the `PluginSidebarMoreMenuI wp.data.dispatch( 'core/edit-post' ).openGeneralSidebar( 'plugin-name/sidebar-name' ); ``` -**Related** +_Related_ - PluginSidebarMoreMenuItem -**Usage** +_Usage_ ```js // Using ES5 syntax @@ -382,28 +368,26 @@ const MyPluginSidebar = () => ( ); ``` -**Parameters** +_Parameters_ -- **props** `Object`: Element props. -- **props.name** `string`: A string identifying the sidebar. Must be unique for every sidebar registered within the scope of your plugin. -- **props.className** `[string]`: An optional class name added to the sidebar body. -- **props.title** `string`: Title displayed at the top of the sidebar. -- **props.isPinnable** `[boolean]`: Whether to allow to pin sidebar to toolbar. -- **props.icon** `[(string|Element)]`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. +- _props_ `Object`: Element props. +- _props.name_ `string`: A string identifying the sidebar. Must be unique for every sidebar registered within the scope of your plugin. +- _props.className_ `[string]`: An optional class name added to the sidebar body. +- _props.title_ `string`: Title displayed at the top of the sidebar. +- _props.isPinnable_ `[boolean]`: Whether to allow to pin sidebar to toolbar. +- _props.icon_ `[(string|Element)]`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. -**Returns** +_Returns_ -`WPElement`: Plugin sidebar component. +- `WPElement`: Plugin sidebar component. -### PluginSidebarMoreMenuItem - -[src/index.js#L104-L104](src/index.js#L104-L104) +# **PluginSidebarMoreMenuItem** [\<>](src/index.js#L104-L104) Renders a menu item in `Plugins` group in `More Menu` drop down, and can be used to activate the corresponding `PluginSidebar` component. The text within the component appears as the menu item label. -**Usage** +_Usage_ ```js // Using ES5 syntax @@ -437,31 +421,29 @@ const MySidebarMoreMenuItem = () => ( ); ``` -**Parameters** - -- **props** `Object`: Component props. -- **props.target** `string`: A string identifying the target sidebar you wish to be activated by this menu item. Must be the same as the `name` prop you have given to that sidebar. -- **props.icon** `[(string|Element)]`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered to the left of the menu item label. +_Parameters_ -**Returns** +- _props_ `Object`: Component props. +- _props.target_ `string`: A string identifying the target sidebar you wish to be activated by this menu item. Must be the same as the `name` prop you have given to that sidebar. +- _props.icon_ `[(string|Element)]`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered to the left of the menu item label. -`WPElement`: The element to be rendered. +_Returns_ -### reinitializeEditor +- `WPElement`: The element to be rendered. -[src/index.js#L35-L50](src/index.js#L35-L50) +# **reinitializeEditor** [\<>](src/index.js#L35-L50) Reinitializes the editor after the user chooses to reboot the editor after an unhandled error occurs, replacing previously mounted editor element using an initial state from prior to the crash. -**Parameters** +_Parameters_ -- **postType** `Object`: Post type of the post to edit. -- **postId** `Object`: ID of the post to edit. -- **target** `Element`: DOM node in which editor is rendered. -- **settings** `?Object`: Editor settings object. -- **initialEdits** `Object`: Programmatic edits to apply initially, to be considered as non-user-initiated (bypass for unsaved changes prompt). +- _postType_ `Object`: Post type of the post to edit. +- _postId_ `Object`: ID of the post to edit. +- _target_ `Element`: DOM node in which editor is rendered. +- _settings_ `?Object`: Editor settings object. +- _initialEdits_ `Object`: Programmatic edits to apply initially, to be considered as non-user-initiated (bypass for unsaved changes prompt). diff --git a/packages/element/README.md b/packages/element/README.md index 44ae7e16ba2f42..2e23c82aa54700 100755 --- a/packages/element/README.md +++ b/packages/element/README.md @@ -78,335 +78,273 @@ This assumes that you will import the `createElement` function in any file where -### Children - -[src/index.js#L1-L1](src/index.js#L1-L1) +# **Children** [\<>](src/index.js#L1-L1) Object that provides utilities for dealing with React children. -### cloneElement - -[src/index.js#L1-L1](src/index.js#L1-L1) +# **cloneElement** [\<>](src/index.js#L1-L1) Creates a copy of an element with extended props. -**Parameters** +_Parameters_ -- **element** `WPElement`: Element -- **props** `?Object`: Props to apply to cloned element +- _element_ `WPElement`: Element +- _props_ `?Object`: Props to apply to cloned element -**Returns** +_Returns_ -`WPElement`: Cloned element. +- `WPElement`: Cloned element. -### Component - -[src/index.js#L1-L1](src/index.js#L1-L1) +# **Component** [\<>](src/index.js#L1-L1) A base class to create WordPress Components (Refs, state and lifecycle hooks) -### concatChildren - -[src/index.js#L1-L1](src/index.js#L1-L1) +# **concatChildren** [\<>](src/index.js#L1-L1) Concatenate two or more React children objects. -**Parameters** +_Parameters_ -- **childrenArguments** `...?Object`: Array of children arguments (array of arrays/strings/objects) to concatenate. +- _childrenArguments_ `...?Object`: Array of children arguments (array of arrays/strings/objects) to concatenate. -**Returns** +_Returns_ -`Array`: The concatenated value. +- `Array`: The concatenated value. -### createContext - -[src/index.js#L1-L1](src/index.js#L1-L1) +# **createContext** [\<>](src/index.js#L1-L1) Creates a context object containing two components: a provider and consumer. -**Parameters** - -- **defaultValue** `Object`: A default data stored in the context. +_Parameters_ -**Returns** +- _defaultValue_ `Object`: A default data stored in the context. -`Object`: Context object. +_Returns_ -### createElement +- `Object`: Context object. -[src/index.js#L1-L1](src/index.js#L1-L1) +# **createElement** [\<>](src/index.js#L1-L1) Returns a new element of given type. Type can be either a string tag name or another function which itself returns an element. -**Parameters** +_Parameters_ -- **type** `?(string|Function)`: Tag name or element creator -- **props** `Object`: Element properties, either attribute set to apply to DOM node or values to pass through to element creator -- **children** `...WPElement`: Descendant elements +- _type_ `?(string|Function)`: Tag name or element creator +- _props_ `Object`: Element properties, either attribute set to apply to DOM node or values to pass through to element creator +- _children_ `...WPElement`: Descendant elements -**Returns** +_Returns_ -`WPElement`: Element. +- `WPElement`: Element. -### createPortal - -[src/index.js#L2-L2](src/index.js#L2-L2) +# **createPortal** [\<>](src/index.js#L2-L2) Creates a portal into which a component can be rendered. -**Related** +_Related_ - -**Parameters** - -- **component** `Component`: Component -- **target** `Element`: DOM node into which element should be rendered +_Parameters_ -### createRef +- _component_ `Component`: Component +- _target_ `Element`: DOM node into which element should be rendered -[src/index.js#L1-L1](src/index.js#L1-L1) +# **createRef** [\<>](src/index.js#L1-L1) Returns an object tracking a reference to a rendered element via its `current` property as either a DOMElement or Element, dependent upon the type of element rendered with the ref attribute. -**Returns** +_Returns_ -`Object`: Ref object. +- `Object`: Ref object. -### findDOMNode - -[src/index.js#L2-L2](src/index.js#L2-L2) +# **findDOMNode** [\<>](src/index.js#L2-L2) Finds the dom node of a React component -**Parameters** - -- **component** `Component`: component's instance -- **target** `Element`: DOM node into which element should be rendered +_Parameters_ -### forwardRef +- _component_ `Component`: component's instance +- _target_ `Element`: DOM node into which element should be rendered -[src/index.js#L1-L1](src/index.js#L1-L1) +# **forwardRef** [\<>](src/index.js#L1-L1) Component enhancer used to enable passing a ref to its wrapped component. Pass a function argument which receives `props` and `ref` as its arguments, returning an element using the forwarded ref. The return value is a new component which forwards its ref. -**Parameters** +_Parameters_ -- **forwarder** `Function`: Function passed `props` and `ref`, expected to return an element. +- _forwarder_ `Function`: Function passed `props` and `ref`, expected to return an element. -**Returns** +_Returns_ -`WPComponent`: Enhanced component. +- `WPComponent`: Enhanced component. -### Fragment - -[src/index.js#L1-L1](src/index.js#L1-L1) +# **Fragment** [\<>](src/index.js#L1-L1) A component which renders its children without any wrapping element. -### isEmptyElement - -[src/index.js#L3-L3](src/index.js#L3-L3) +# **isEmptyElement** [\<>](src/index.js#L3-L3) Checks if the provided WP element is empty. -**Parameters** +_Parameters_ -- **element** `*`: WP element to check. +- _element_ `*`: WP element to check. -**Returns** +_Returns_ -`boolean`: True when an element is considered empty. +- `boolean`: True when an element is considered empty. -### isValidElement - -[src/index.js#L1-L1](src/index.js#L1-L1) +# **isValidElement** [\<>](src/index.js#L1-L1) Checks if an object is a valid WPElement -**Parameters** - -- **objectToCheck** `Object`: The object to be checked. +_Parameters_ -**Returns** +- _objectToCheck_ `Object`: The object to be checked. -`boolean`: true if objectToTest is a valid WPElement and false otherwise. +_Returns_ -### lazy +- `boolean`: true if objectToTest is a valid WPElement and false otherwise. -[src/index.js#L1-L1](src/index.js#L1-L1) +# **lazy** [\<>](src/index.js#L1-L1) -**Related** +_Related_ - -### RawHTML - -[src/index.js#L5-L5](src/index.js#L5-L5) +# **RawHTML** [\<>](src/index.js#L5-L5) Component used as equivalent of Fragment with unescaped HTML, in cases where it is desirable to render dangerous HTML without needing a wrapper element. To preserve additional props, a `div` wrapper _will_ be created if any props aside from `children` are passed. -**Parameters** - -- **props.children** `string`: HTML to render. +_Parameters_ -**Returns** +- _props.children_ `string`: HTML to render. -`WPElement`: Dangerously-rendering element. +_Returns_ -### render +- `WPElement`: Dangerously-rendering element. -[src/index.js#L2-L2](src/index.js#L2-L2) +# **render** [\<>](src/index.js#L2-L2) Renders a given element into the target DOM node. -**Parameters** +_Parameters_ -- **element** `WPElement`: Element to render -- **target** `Element`: DOM node into which element should be rendered +- _element_ `WPElement`: Element to render +- _target_ `Element`: DOM node into which element should be rendered -### renderToString - -[src/index.js#L4-L4](src/index.js#L4-L4) +# **renderToString** [\<>](src/index.js#L4-L4) Serializes a React element to string. -**Parameters** - -- **element** `WPElement`: Element to serialize. -- **context** `?Object`: Context object. -- **legacyContext** `?Object`: Legacy context object. +_Parameters_ -**Returns** +- _element_ `WPElement`: Element to serialize. +- _context_ `?Object`: Context object. +- _legacyContext_ `?Object`: Legacy context object. -`string`: Serialized element. +_Returns_ -### StrictMode +- `string`: Serialized element. -[src/index.js#L1-L1](src/index.js#L1-L1) +# **StrictMode** [\<>](src/index.js#L1-L1) Component that activates additional checks and warnings for its descendants. -### Suspense +# **Suspense** [\<>](src/index.js#L1-L1) -[src/index.js#L1-L1](src/index.js#L1-L1) - -**Related** +_Related_ - -### switchChildrenNodeName - -[src/index.js#L1-L1](src/index.js#L1-L1) +# **switchChildrenNodeName** [\<>](src/index.js#L1-L1) Switches the nodeName of all the elements in the children object. -**Parameters** +_Parameters_ -- **children** `?Object`: Children object. -- **nodeName** `string`: Node name. +- _children_ `?Object`: Children object. +- _nodeName_ `string`: Node name. -**Returns** +_Returns_ -`?Object`: The updated children object. +- `?Object`: The updated children object. -### unmountComponentAtNode - -[src/index.js#L2-L2](src/index.js#L2-L2) +# **unmountComponentAtNode** [\<>](src/index.js#L2-L2) Removes any mounted element from the target DOM node. -**Parameters** - -- **target** `Element`: DOM node in which element is to be removed +_Parameters_ -### useCallback +- _target_ `Element`: DOM node in which element is to be removed -[src/index.js#L1-L1](src/index.js#L1-L1) +# **useCallback** [\<>](src/index.js#L1-L1) -**Related** +_Related_ - -### useContext +# **useContext** [\<>](src/index.js#L1-L1) -[src/index.js#L1-L1](src/index.js#L1-L1) - -**Related** +_Related_ - -### useDebugValue - -[src/index.js#L1-L1](src/index.js#L1-L1) +# **useDebugValue** [\<>](src/index.js#L1-L1) -**Related** +_Related_ - -### useEffect +# **useEffect** [\<>](src/index.js#L1-L1) -[src/index.js#L1-L1](src/index.js#L1-L1) - -**Related** +_Related_ - -### useImperativeHandle - -[src/index.js#L1-L1](src/index.js#L1-L1) +# **useImperativeHandle** [\<>](src/index.js#L1-L1) -**Related** +_Related_ - -### useLayoutEffect +# **useLayoutEffect** [\<>](src/index.js#L1-L1) -[src/index.js#L1-L1](src/index.js#L1-L1) - -**Related** +_Related_ - -### useMemo - -[src/index.js#L1-L1](src/index.js#L1-L1) +# **useMemo** [\<>](src/index.js#L1-L1) -**Related** +_Related_ - -### useReducer +# **useReducer** [\<>](src/index.js#L1-L1) -[src/index.js#L1-L1](src/index.js#L1-L1) - -**Related** +_Related_ - -### useRef - -[src/index.js#L1-L1](src/index.js#L1-L1) +# **useRef** [\<>](src/index.js#L1-L1) -**Related** +_Related_ - -### useState - -[src/index.js#L1-L1](src/index.js#L1-L1) +# **useState** [\<>](src/index.js#L1-L1) -**Related** +_Related_ - diff --git a/packages/escape-html/README.md b/packages/escape-html/README.md index eafa8cf0673b71..c6f4769c298e79 100644 --- a/packages/escape-html/README.md +++ b/packages/escape-html/README.md @@ -16,36 +16,32 @@ _This package assumes that your code will run in an **ES2015+** environment. If -### escapeAmpersand - -[src/index.js#L33-L35](src/index.js#L33-L35) +# **escapeAmpersand** [\<>](src/index.js#L33-L35) Returns a string with ampersands escaped. Note that this is an imperfect implementation, where only ampersands which do not appear as a pattern of named, decimal, or hexadecimal character references are escaped. Invalid named references (i.e. ambiguous ampersand) are are still permitted. -**Related** +_Related_ - - - -**Parameters** - -- **value** `string`: Original string. +_Parameters_ -**Returns** +- _value_ `string`: Original string. -`string`: Escaped string. +_Returns_ -### escapeAttribute +- `string`: Escaped string. -[src/index.js#L79-L81](src/index.js#L79-L81) +# **escapeAttribute** [\<>](src/index.js#L79-L81) Returns an escaped attribute value. -**Related** +_Related_ - @@ -60,76 +56,68 @@ necessary for `__unstableEscapeGreaterThan` to be used. See: -**Parameters** - -- **value** `string`: Attribute value. +_Parameters_ -**Returns** +- _value_ `string`: Attribute value. -`string`: Escaped attribute value. +_Returns_ -### escapeHTML +- `string`: Escaped attribute value. -[src/index.js#L95-L97](src/index.js#L95-L97) +# **escapeHTML** [\<>](src/index.js#L95-L97) Returns an escaped HTML element value. -**Related** +_Related_ - "the text must not contain the character U+003C LESS-THAN SIGN (\<) or an ambiguous ampersand." -**Parameters** +_Parameters_ -- **value** `string`: Element value. +- _value_ `string`: Element value. -**Returns** +_Returns_ -`string`: Escaped HTML element value. +- `string`: Escaped HTML element value. -### escapeLessThan - -[src/index.js#L55-L57](src/index.js#L55-L57) +# **escapeLessThan** [\<>](src/index.js#L55-L57) Returns a string with less-than sign replaced. -**Parameters** - -- **value** `string`: Original string. +_Parameters_ -**Returns** +- _value_ `string`: Original string. -`string`: Escaped string. +_Returns_ -### escapeQuotationMark +- `string`: Escaped string. -[src/index.js#L44-L46](src/index.js#L44-L46) +# **escapeQuotationMark** [\<>](src/index.js#L44-L46) Returns a string with quotation marks replaced. -**Parameters** - -- **value** `string`: Original string. +_Parameters_ -**Returns** +- _value_ `string`: Original string. -`string`: Escaped string. +_Returns_ -### isValidAttributeName +- `string`: Escaped string. -[src/index.js#L106-L108](src/index.js#L106-L108) +# **isValidAttributeName** [\<>](src/index.js#L106-L108) Returns true if the given attribute name is valid, or false otherwise. -**Parameters** +_Parameters_ -- **name** `string`: Attribute name to test. +- _name_ `string`: Attribute name to test. -**Returns** +_Returns_ -`boolean`: Whether attribute is valid. +- `boolean`: Whether attribute is valid. diff --git a/packages/html-entities/README.md b/packages/html-entities/README.md index 2d13431fa13b4d..3f5f4ec7256d2a 100644 --- a/packages/html-entities/README.md +++ b/packages/html-entities/README.md @@ -16,26 +16,24 @@ _This package assumes that your code will run in an **ES2015+** environment. If -### decodeEntities - -[src/index.js#L16-L35](src/index.js#L16-L35) +# **decodeEntities** [\<>](src/index.js#L16-L35) Decodes the HTML entities from a given string. -**Usage** +_Usage_ ```js const result = decodeEntities( 'á' ); console.log( result ); // result will be "á" ``` -**Parameters** +_Parameters_ -- **html** `string`: String that contain HTML entities. +- _html_ `string`: String that contain HTML entities. -**Returns** +_Returns_ -`string`: The decoded string. +- `string`: The decoded string. diff --git a/packages/i18n/README.md b/packages/i18n/README.md index 373ba5849db731..83a3337eb2b16b 100644 --- a/packages/i18n/README.md +++ b/packages/i18n/README.md @@ -27,125 +27,113 @@ For a complete example, see the [Internationalization section of the Gutenberg H -### setLocaleData - -[src/index.js#L45-L58](src/index.js#L45-L58) +# **setLocaleData** [\<>](src/index.js#L45-L58) Merges locale data into the Tannin instance by domain. Accepts data in a Jed-formatted JSON object shape. -**Related** +_Related_ - -**Parameters** - -- **data** `?Object`: Locale data configuration. -- **domain** `?string`: Domain for which configuration applies. +_Parameters_ -### sprintf +- _data_ `?Object`: Locale data configuration. +- _domain_ `?string`: Domain for which configuration applies. -[src/index.js#L159-L167](src/index.js#L159-L167) +# **sprintf** [\<>](src/index.js#L159-L167) Returns a formatted string. If an error occurs in applying the format, the original format string is returned. -**Related** +_Related_ - -**Parameters** - -- **format** `string`: The format of the string to generate. -- **args** `...string`: Arguments to apply to the format. +_Parameters_ -**Returns** +- _format_ `string`: The format of the string to generate. +- _args_ `...string`: Arguments to apply to the format. -`string`: The formatted string. +_Returns_ -### \_n +- `string`: The formatted string. -[src/index.js#L125-L127](src/index.js#L125-L127) +# **\_n** [\<>](src/index.js#L125-L127) Translates and retrieves the singular or plural form based on the supplied number. -**Related** +_Related_ - -**Parameters** +_Parameters_ -- **single** `string`: The text to be used if the number is singular. -- **plural** `string`: The text to be used if the number is plural. -- **number** `number`: The number to compare against to use either the singular or plural form. -- **domain** `?string`: Domain to retrieve the translated text. +- _single_ `string`: The text to be used if the number is singular. +- _plural_ `string`: The text to be used if the number is plural. +- _number_ `number`: The number to compare against to use either the singular or plural form. +- _domain_ `?string`: Domain to retrieve the translated text. -**Returns** +_Returns_ -`string`: The translated singular or plural form. +- `string`: The translated singular or plural form. -### \_nx - -[src/index.js#L144-L146](src/index.js#L144-L146) +# **\_nx** [\<>](src/index.js#L144-L146) Translates and retrieves the singular or plural form based on the supplied number, with gettext context. -**Related** +_Related_ - -**Parameters** - -- **single** `string`: The text to be used if the number is singular. -- **plural** `string`: The text to be used if the number is plural. -- **number** `number`: The number to compare against to use either the singular or plural form. -- **context** `string`: Context information for the translators. -- **domain** `?string`: Domain to retrieve the translated text. +_Parameters_ -**Returns** +- _single_ `string`: The text to be used if the number is singular. +- _plural_ `string`: The text to be used if the number is plural. +- _number_ `number`: The number to compare against to use either the singular or plural form. +- _context_ `string`: Context information for the translators. +- _domain_ `?string`: Domain to retrieve the translated text. -`string`: The translated singular or plural form. +_Returns_ -### \_x +- `string`: The translated singular or plural form. -[src/index.js#L107-L109](src/index.js#L107-L109) +# **\_x** [\<>](src/index.js#L107-L109) Retrieve translated string with gettext context. -**Related** +_Related_ - -**Parameters** - -- **text** `string`: Text to translate. -- **context** `string`: Context information for the translators. -- **domain** `?string`: Domain to retrieve the translated text. +_Parameters_ -**Returns** +- _text_ `string`: Text to translate. +- _context_ `string`: Context information for the translators. +- _domain_ `?string`: Domain to retrieve the translated text. -`string`: Translated context string without pipe. +_Returns_ -### \_\_ +- `string`: Translated context string without pipe. -[src/index.js#L92-L94](src/index.js#L92-L94) +# **\_\_** [\<>](src/index.js#L92-L94) Retrieve the translation of text. -**Related** +_Related_ - -**Parameters** +_Parameters_ -- **text** `string`: Text to translate. -- **domain** `?string`: Domain to retrieve the translated text. +- _text_ `string`: Text to translate. +- _domain_ `?string`: Domain to retrieve the translated text. -**Returns** +_Returns_ -`string`: Translated text. +- `string`: Translated text. diff --git a/packages/keycodes/README.md b/packages/keycodes/README.md index d99081ed5823c2..99501bfc78865e 100644 --- a/packages/keycodes/README.md +++ b/packages/keycodes/README.md @@ -38,104 +38,76 @@ onKeyDown( event ) { -### ALT - -[src/index.js#L74-L74](src/index.js#L74-L74) +# **ALT** [\<>](src/index.js#L74-L74) Keycode for ALT key. -### BACKSPACE - -[src/index.js#L30-L30](src/index.js#L30-L30) +# **BACKSPACE** [\<>](src/index.js#L30-L30) Keycode for BACKSPACE key. -### COMMAND - -[src/index.js#L82-L82](src/index.js#L82-L82) +# **COMMAND** [\<>](src/index.js#L82-L82) Keycode for COMMAND/META key. -### CTRL - -[src/index.js#L78-L78](src/index.js#L78-L78) +# **CTRL** [\<>](src/index.js#L78-L78) Keycode for CTRL key. -### DELETE - -[src/index.js#L66-L66](src/index.js#L66-L66) +# **DELETE** [\<>](src/index.js#L66-L66) Keycode for DELETE key. -### displayShortcut - -[src/index.js#L166-L168](src/index.js#L166-L168) +# **displayShortcut** [\<>](src/index.js#L166-L168) An object that contains functions to display shortcuts. E.g. displayShortcut.primary( 'm' ) will return '⌘M' on Mac. -**Type** +_Type_ -`Object` Keyed map of functions to display shortcuts. +- `Object` Keyed map of functions to display shortcuts. -### displayShortcutList - -[src/index.js#L135-L158](src/index.js#L135-L158) +# **displayShortcutList** [\<>](src/index.js#L135-L158) Return an array of the parts of a keyboard shortcut chord for display E.g displayShortcutList.primary( 'm' ) will return [ '⌘', 'M' ] on Mac. -**Type** - -`Object` keyed map of functions to shortcut sequences +_Type_ -### DOWN +- `Object` keyed map of functions to shortcut sequences -[src/index.js#L62-L62](src/index.js#L62-L62) +# **DOWN** [\<>](src/index.js#L62-L62) Keycode for DOWN key. -### ENTER - -[src/index.js#L38-L38](src/index.js#L38-L38) +# **ENTER** [\<>](src/index.js#L38-L38) Keycode for ENTER key. -### ESCAPE - -[src/index.js#L42-L42](src/index.js#L42-L42) +# **ESCAPE** [\<>](src/index.js#L42-L42) Keycode for ESCAPE key. -### F10 - -[src/index.js#L70-L70](src/index.js#L70-L70) +# **F10** [\<>](src/index.js#L70-L70) Keycode for F10 key. -### isKeyboardEvent - -[src/index.js#L204-L218](src/index.js#L204-L218) +# **isKeyboardEvent** [\<>](src/index.js#L204-L218) An object that contains functions to check if a keyboard event matches a predefined shortcut combination. E.g. isKeyboardEvent.primary( event, 'm' ) will return true if the event signals pressing ⌘M. -**Type** - -`Object` Keyed map of functions to match events. +_Type_ -### LEFT +- `Object` Keyed map of functions to match events. -[src/index.js#L50-L50](src/index.js#L50-L50) +# **LEFT** [\<>](src/index.js#L50-L50) Keycode for LEFT key. -### modifiers - -[src/index.js#L103-L114](src/index.js#L103-L114) +# **modifiers** [\<>](src/index.js#L103-L114) Object that contains functions that return the available modifier depending on platform. @@ -151,52 +123,38 @@ depending on platform. - `shift` - `shiftAlt` -### rawShortcut - -[src/index.js#L123-L127](src/index.js#L123-L127) +# **rawShortcut** [\<>](src/index.js#L123-L127) An object that contains functions to get raw shortcuts. E.g. rawShortcut.primary( 'm' ) will return 'meta+m' on Mac. These are intended for user with the KeyboardShortcuts component or TinyMCE. -**Type** - -`Object` Keyed map of functions to raw shortcuts. +_Type_ -### RIGHT +- `Object` Keyed map of functions to raw shortcuts. -[src/index.js#L58-L58](src/index.js#L58-L58) +# **RIGHT** [\<>](src/index.js#L58-L58) Keycode for RIGHT key. -### SHIFT - -[src/index.js#L86-L86](src/index.js#L86-L86) +# **SHIFT** [\<>](src/index.js#L86-L86) Keycode for SHIFT key. -### shortcutAriaLabel - -[src/index.js#L174-L194](src/index.js#L174-L194) +# **shortcutAriaLabel** [\<>](src/index.js#L174-L194) An object that contains functions to return an aria label for a keyboard shortcut. E.g. shortcutAriaLabel.primary( '.' ) will return 'Command + Period' on Mac. -### SPACE - -[src/index.js#L46-L46](src/index.js#L46-L46) +# **SPACE** [\<>](src/index.js#L46-L46) Keycode for SPACE key. -### TAB - -[src/index.js#L34-L34](src/index.js#L34-L34) +# **TAB** [\<>](src/index.js#L34-L34) Keycode for TAB key. -### UP - -[src/index.js#L54-L54](src/index.js#L54-L54) +# **UP** [\<>](src/index.js#L54-L54) Keycode for UP key. diff --git a/packages/plugins/README.md b/packages/plugins/README.md index 1dfa17b3fed222..31588557221e89 100644 --- a/packages/plugins/README.md +++ b/packages/plugins/README.md @@ -16,37 +16,31 @@ _This package assumes that your code will run in an **ES2015+** environment. If -#### getPlugin - -[src/index.js#L2-L2](src/index.js#L2-L2) +# **getPlugin** [\<>](src/index.js#L2-L2) Returns a registered plugin settings. -**Parameters** - -- **name** `string`: Plugin name. +_Parameters_ -**Returns** +- _name_ `string`: Plugin name. -`?Object`: Plugin setting. +_Returns_ -#### getPlugins +- `?Object`: Plugin setting. -[src/index.js#L2-L2](src/index.js#L2-L2) +# **getPlugins** [\<>](src/index.js#L2-L2) Returns all registered plugins. -**Returns** - -`Array`: Plugin settings. +_Returns_ -#### PluginArea +- `Array`: Plugin settings. -[src/index.js#L1-L1](src/index.js#L1-L1) +# **PluginArea** [\<>](src/index.js#L1-L1) A component that renders all plugin fills in a hidden div. -**Usage** +_Usage_ ```js // Using ES5 syntax @@ -75,17 +69,15 @@ const Layout = () => ( ); ``` -**Returns** +_Returns_ -`WPElement`: Plugin area. +- `WPElement`: Plugin area. -#### registerPlugin - -[src/index.js#L2-L2](src/index.js#L2-L2) +# **registerPlugin** [\<>](src/index.js#L2-L2) Registers a plugin to the editor. -**Usage** +_Usage_ ```js // Using ES5 syntax @@ -150,24 +142,22 @@ registerPlugin( 'plugin-name', { } ); ``` -**Parameters** - -- **name** `string`: A string identifying the plugin. Must be unique across all registered plugins. -- **settings** `Object`: The settings for this plugin. -- **settings.icon** `(string|WPElement|Function)`: An icon to be shown in the UI. It can be a slug of the Dashicon, or an element (or function returning an element) if you choose to render your own SVG. -- **settings.render** `Function`: A component containing the UI elements to be rendered. +_Parameters_ -**Returns** +- _name_ `string`: A string identifying the plugin. Must be unique across all registered plugins. +- _settings_ `Object`: The settings for this plugin. +- _settings.icon_ `(string|WPElement|Function)`: An icon to be shown in the UI. It can be a slug of the Dashicon, or an element (or function returning an element) if you choose to render your own SVG. +- _settings.render_ `Function`: A component containing the UI elements to be rendered. -`Object`: The final plugin settings object. +_Returns_ -#### unregisterPlugin +- `Object`: The final plugin settings object. -[src/index.js#L2-L2](src/index.js#L2-L2) +# **unregisterPlugin** [\<>](src/index.js#L2-L2) Unregisters a plugin by name. -**Usage** +_Usage_ ```js // Using ES5 syntax @@ -183,28 +173,26 @@ const { unregisterPlugin } = wp.plugins; unregisterPlugin( 'plugin-name' ); ``` -**Parameters** - -- **name** `string`: Plugin name. +_Parameters_ -**Returns** +- _name_ `string`: Plugin name. -`?WPPlugin`: The previous plugin settings object, if it has been successfully unregistered; otherwise `undefined`. +_Returns_ -#### withPluginContext +- `?WPPlugin`: The previous plugin settings object, if it has been successfully unregistered; otherwise `undefined`. -[src/index.js#L1-L1](src/index.js#L1-L1) +# **withPluginContext** [\<>](src/index.js#L1-L1) A Higher Order Component used to inject Plugin context to the wrapped component. -**Parameters** +_Parameters_ -- **mapContextToProps** `Function`: Function called on every context change, expected to return object of props to merge with the component's own props. +- _mapContextToProps_ `Function`: Function called on every context change, expected to return object of props to merge with the component's own props. -**Returns** +_Returns_ -`Component`: Enhanced component with injected context as props. +- `Component`: Enhanced component with injected context as props. diff --git a/packages/priority-queue/README.md b/packages/priority-queue/README.md index d9f34770344362..60923ef28aa28a 100644 --- a/packages/priority-queue/README.md +++ b/packages/priority-queue/README.md @@ -16,14 +16,12 @@ _This package assumes that your code will run in an **ES2015+** environment. If -### createQueue - -[src/index.js#L25-L72](src/index.js#L25-L72) +# **createQueue** [\<>](src/index.js#L25-L72) Creates a context-aware queue that only executes the last task of a given context. -**Usage** +_Usage_ ```js import { createQueue } from '@wordpress/priority-queue'; @@ -40,9 +38,9 @@ queue.add( ctx2, () => console.log( 'This won\'t be printed' ) ); queue.add( ctx2, () => console.log( 'This will be printed second' ) ); ``` -**Returns** +_Returns_ -`Object`: Queue object with `add` and `flush` methods. +- `Object`: Queue object with `add` and `flush` methods. diff --git a/packages/redux-routine/README.md b/packages/redux-routine/README.md index 46c9b299b31040..5eb35117ee2d40 100644 --- a/packages/redux-routine/README.md +++ b/packages/redux-routine/README.md @@ -59,9 +59,7 @@ request has completed does the action creator procede to return the `SET_TEMPERA -### default - -[src/index.js#L19-L30](src/index.js#L19-L30) +# **default** [\<>](src/index.js#L19-L30) Creates a Redux middleware, given an object of controls where each key is an action type for which to act upon, the value a function which returns either @@ -70,13 +68,13 @@ or a value. The value or resolved promise value is assigned on the return value of the yield assignment. If the control handler returns undefined, the execution is not continued. -**Parameters** +_Parameters_ -- **controls** `Object`: Object of control handlers. +- _controls_ `Object`: Object of control handlers. -**Returns** +_Returns_ -`Function`: Co-routine runtime +- `Function`: Co-routine runtime diff --git a/packages/rich-text/README.md b/packages/rich-text/README.md index 90fe67367ddc8c..06d9506d47576d 100644 --- a/packages/rich-text/README.md +++ b/packages/rich-text/README.md @@ -16,43 +16,37 @@ _This package assumes that your code will run in an **ES2015+** environment. If -### applyFormat - -[src/index.js#L6-L6](src/index.js#L6-L6) +# **applyFormat** [\<>](src/index.js#L6-L6) Apply a format object to a Rich Text value from the given `startIndex` to the given `endIndex`. Indices are retrieved from the selection if none are provided. -**Parameters** - -- **value** `Object`: Value to modify. -- **format** `Object`: Format to apply. -- **startIndex** `[number]`: Start index. -- **endIndex** `[number]`: End index. +_Parameters_ -**Returns** +- _value_ `Object`: Value to modify. +- _format_ `Object`: Format to apply. +- _startIndex_ `[number]`: Start index. +- _endIndex_ `[number]`: End index. -`Object`: A new value with the format applied. +_Returns_ -### concat +- `Object`: A new value with the format applied. -[src/index.js#L8-L8](src/index.js#L8-L8) +# **concat** [\<>](src/index.js#L8-L8) Combine all Rich Text values into one. This is similar to `String.prototype.concat`. -**Parameters** - -- **values** `...Object`: Objects to combine. +_Parameters_ -**Returns** +- _values_ `...Object`: Objects to combine. -`Object`: A new value combining all given records. +_Returns_ -### create +- `Object`: A new value combining all given records. -[src/index.js#L9-L9](src/index.js#L9-L9) +# **create** [\<>](src/index.js#L9-L9) Create a RichText value from an `Element` tree (DOM), an HTML string or a plain text string, with optionally a `Range` object to set the selection. If @@ -81,309 +75,275 @@ holds information about the formatting at the relevant text indices. Finally `start` and `end` state which text indices are selected. They are only provided if a `Range` was given. -**Parameters** +_Parameters_ -- **$1** `[Object]`: Optional named arguments. -- **$1.element** `[Element]`: Element to create value from. -- **$1.text** `[string]`: Text to create value from. -- **$1.html** `[string]`: HTML to create value from. -- **$1.range** `[Range]`: Range to create value from. -- **$1.multilineTag** `[string]`: Multiline tag if the structure is multiline. -- **$1.multilineWrapperTags** `[Array]`: Tags where lines can be found if nesting is possible. +- _$1_ `[Object]`: Optional named arguments. +- _$1.element_ `[Element]`: Element to create value from. +- _$1.text_ `[string]`: Text to create value from. +- _$1.html_ `[string]`: HTML to create value from. +- _$1.range_ `[Range]`: Range to create value from. +- _$1.multilineTag_ `[string]`: Multiline tag if the structure is multiline. +- _$1.multilineWrapperTags_ `[Array]`: Tags where lines can be found if nesting is possible. -**Returns** +_Returns_ -`Object`: A rich text value. +- `Object`: A rich text value. -### getActiveFormat - -[src/index.js#L10-L10](src/index.js#L10-L10) +# **getActiveFormat** [\<>](src/index.js#L10-L10) Gets the format object by type at the start of the selection. This can be used to get e.g. the URL of a link format at the current selection, but also to check if a format is active at the selection. Returns undefined if there is no format at the selection. -**Parameters** - -- **value** `Object`: Value to inspect. -- **formatType** `string`: Format type to look for. +_Parameters_ -**Returns** +- _value_ `Object`: Value to inspect. +- _formatType_ `string`: Format type to look for. -`(Object|undefined)`: Active format object of the specified type, or undefined. +_Returns_ -### getActiveObject +- `(Object|undefined)`: Active format object of the specified type, or undefined. -[src/index.js#L11-L11](src/index.js#L11-L11) +# **getActiveObject** [\<>](src/index.js#L11-L11) Gets the active object, if there is any. -**Parameters** +_Parameters_ -- **value** `Object`: Value to inspect. +- _value_ `Object`: Value to inspect. -**Returns** +_Returns_ -`?Object`: Active object, or undefined. +- `?Object`: Active object, or undefined. -### getTextContent - -[src/index.js#L14-L14](src/index.js#L14-L14) +# **getTextContent** [\<>](src/index.js#L14-L14) Get the textual content of a Rich Text value. This is similar to `Element.textContent`. -**Parameters** - -- **value** `Object`: Value to use. +_Parameters_ -**Returns** +- _value_ `Object`: Value to use. -`string`: The text content. +_Returns_ -### insert +- `string`: The text content. -[src/index.js#L22-L22](src/index.js#L22-L22) +# **insert** [\<>](src/index.js#L22-L22) Insert a Rich Text value, an HTML string, or a plain text string, into a Rich Text value at the given `startIndex`. Any content between `startIndex` and `endIndex` will be removed. Indices are retrieved from the selection if none are provided. -**Parameters** - -- **value** `Object`: Value to modify. -- **valueToInsert** `(Object|string)`: Value to insert. -- **startIndex** `[number]`: Start index. -- **endIndex** `[number]`: End index. +_Parameters_ -**Returns** +- _value_ `Object`: Value to modify. +- _valueToInsert_ `(Object|string)`: Value to insert. +- _startIndex_ `[number]`: Start index. +- _endIndex_ `[number]`: End index. -`Object`: A new value with the value inserted. +_Returns_ -### insertObject +- `Object`: A new value with the value inserted. -[src/index.js#L25-L25](src/index.js#L25-L25) +# **insertObject** [\<>](src/index.js#L25-L25) Insert a format as an object into a Rich Text value at the given `startIndex`. Any content between `startIndex` and `endIndex` will be removed. Indices are retrieved from the selection if none are provided. -**Parameters** +_Parameters_ -- **value** `Object`: Value to modify. -- **formatToInsert** `Object`: Format to insert as object. -- **startIndex** `[number]`: Start index. -- **endIndex** `[number]`: End index. +- _value_ `Object`: Value to modify. +- _formatToInsert_ `Object`: Format to insert as object. +- _startIndex_ `[number]`: Start index. +- _endIndex_ `[number]`: End index. -**Returns** +_Returns_ -`Object`: A new value with the object inserted. +- `Object`: A new value with the object inserted. -### isCollapsed - -[src/index.js#L15-L15](src/index.js#L15-L15) +# **isCollapsed** [\<>](src/index.js#L15-L15) Check if the selection of a Rich Text value is collapsed or not. Collapsed means that no characters are selected, but there is a caret present. If there is no selection, `undefined` will be returned. This is similar to `window.getSelection().isCollapsed()`. -**Parameters** - -- **value** `Object`: The rich text value to check. +_Parameters_ -**Returns** +- _value_ `Object`: The rich text value to check. -`(boolean|undefined)`: True if the selection is collapsed, false if not, undefined if there is no selection. +_Returns_ -### isEmpty +- `(boolean|undefined)`: True if the selection is collapsed, false if not, undefined if there is no selection. -[src/index.js#L16-L16](src/index.js#L16-L16) +# **isEmpty** [\<>](src/index.js#L16-L16) Check if a Rich Text value is Empty, meaning it contains no text or any objects (such as images). -**Parameters** +_Parameters_ -- **value** `Object`: Value to use. +- _value_ `Object`: Value to use. -**Returns** +_Returns_ -`boolean`: True if the value is empty, false if not. +- `boolean`: True if the value is empty, false if not. -### join - -[src/index.js#L17-L17](src/index.js#L17-L17) +# **join** [\<>](src/index.js#L17-L17) Combine an array of Rich Text values into one, optionally separated by `separator`, which can be a Rich Text value, HTML string, or plain text string. This is similar to `Array.prototype.join`. -**Parameters** - -- **values** `Array`: An array of values to join. -- **separator** `[(string|Object)]`: Separator string or value. +_Parameters_ -**Returns** +- _values_ `Array`: An array of values to join. +- _separator_ `[(string|Object)]`: Separator string or value. -`Object`: A new combined value. +_Returns_ -### registerFormatType +- `Object`: A new combined value. -[src/index.js#L18-L18](src/index.js#L18-L18) +# **registerFormatType** [\<>](src/index.js#L18-L18) Registers a new format provided a unique name and an object defining its behavior. -**Parameters** - -- **name** `string`: Format name. -- **settings** `Object`: Format settings. -- **settings.tagName** `string`: The HTML tag this format will wrap the selection with. -- **settings.className** `[string]`: A class to match the format. -- **settings.title** `string`: Name of the format. -- **settings.edit** `Function`: Should return a component for the user to interact with the new registered format. +_Parameters_ -**Returns** +- _name_ `string`: Format name. +- _settings_ `Object`: Format settings. +- _settings.tagName_ `string`: The HTML tag this format will wrap the selection with. +- _settings.className_ `[string]`: A class to match the format. +- _settings.title_ `string`: Name of the format. +- _settings.edit_ `Function`: Should return a component for the user to interact with the new registered format. -`(WPFormat|undefined)`: The format, if it has been successfully registered; otherwise `undefined`. +_Returns_ -### remove +- `(WPFormat|undefined)`: The format, if it has been successfully registered; otherwise `undefined`. -[src/index.js#L20-L20](src/index.js#L20-L20) +# **remove** [\<>](src/index.js#L20-L20) Remove content from a Rich Text value between the given `startIndex` and `endIndex`. Indices are retrieved from the selection if none are provided. -**Parameters** +_Parameters_ -- **value** `Object`: Value to modify. -- **startIndex** `[number]`: Start index. -- **endIndex** `[number]`: End index. +- _value_ `Object`: Value to modify. +- _startIndex_ `[number]`: Start index. +- _endIndex_ `[number]`: End index. -**Returns** +_Returns_ -`Object`: A new value with the content removed. +- `Object`: A new value with the content removed. -### removeFormat - -[src/index.js#L19-L19](src/index.js#L19-L19) +# **removeFormat** [\<>](src/index.js#L19-L19) Remove any format object from a Rich Text value by type from the given `startIndex` to the given `endIndex`. Indices are retrieved from the selection if none are provided. -**Parameters** - -- **value** `Object`: Value to modify. -- **formatType** `string`: Format type to remove. -- **startIndex** `[number]`: Start index. -- **endIndex** `[number]`: End index. +_Parameters_ -**Returns** +- _value_ `Object`: Value to modify. +- _formatType_ `string`: Format type to remove. +- _startIndex_ `[number]`: Start index. +- _endIndex_ `[number]`: End index. -`Object`: A new value with the format applied. +_Returns_ -### replace +- `Object`: A new value with the format applied. -[src/index.js#L21-L21](src/index.js#L21-L21) +# **replace** [\<>](src/index.js#L21-L21) Search a Rich Text value and replace the match(es) with `replacement`. This is similar to `String.prototype.replace`. -**Parameters** +_Parameters_ -- **value** `Object`: The value to modify. -- **pattern** `(RegExp|string)`: A RegExp object or literal. Can also be a string. It is treated as a verbatim string and is not interpreted as a regular expression. Only the first occurrence will be replaced. -- **replacement** `(Function|string)`: The match or matches are replaced with the specified or the value returned by the specified function. +- _value_ `Object`: The value to modify. +- _pattern_ `(RegExp|string)`: A RegExp object or literal. Can also be a string. It is treated as a verbatim string and is not interpreted as a regular expression. Only the first occurrence will be replaced. +- _replacement_ `(Function|string)`: The match or matches are replaced with the specified or the value returned by the specified function. -**Returns** +_Returns_ -`Object`: A new value with replacements applied. +- `Object`: A new value with replacements applied. -### slice - -[src/index.js#L26-L26](src/index.js#L26-L26) +# **slice** [\<>](src/index.js#L26-L26) Slice a Rich Text value from `startIndex` to `endIndex`. Indices are retrieved from the selection if none are provided. This is similar to `String.prototype.slice`. -**Parameters** - -- **value** `Object`: Value to modify. -- **startIndex** `[number]`: Start index. -- **endIndex** `[number]`: End index. +_Parameters_ -**Returns** +- _value_ `Object`: Value to modify. +- _startIndex_ `[number]`: Start index. +- _endIndex_ `[number]`: End index. -`Object`: A new extracted value. +_Returns_ -### split +- `Object`: A new extracted value. -[src/index.js#L27-L27](src/index.js#L27-L27) +# **split** [\<>](src/index.js#L27-L27) Split a Rich Text value in two at the given `startIndex` and `endIndex`, or split at the given separator. This is similar to `String.prototype.split`. Indices are retrieved from the selection if none are provided. -**Parameters** - -- **value** `Object`: Value to modify. -- **string** `[(number|string)]`: Start index, or string at which to split. -- **endStr** `[number]`: End index. +_Parameters_ -**Returns** +- _value_ `Object`: Value to modify. +- _string_ `[(number|string)]`: Start index, or string at which to split. +- _endStr_ `[number]`: End index. -`Array`: An array of new values. +_Returns_ -### toggleFormat +- `Array`: An array of new values. -[src/index.js#L30-L30](src/index.js#L30-L30) +# **toggleFormat** [\<>](src/index.js#L30-L30) Toggles a format object to a Rich Text value at the current selection. -**Parameters** +_Parameters_ -- **value** `Object`: Value to modify. -- **format** `Object`: Format to apply or remove. +- _value_ `Object`: Value to modify. +- _format_ `Object`: Format to apply or remove. -**Returns** +_Returns_ -`Object`: A new value with the format applied or removed. +- `Object`: A new value with the format applied or removed. -### toHTMLString - -[src/index.js#L29-L29](src/index.js#L29-L29) +# **toHTMLString** [\<>](src/index.js#L29-L29) Create an HTML string from a Rich Text value. If a `multilineTag` is provided, text separated by a line separator will be wrapped in it. -**Parameters** - -- **$1** `Object`: Named argements. -- **$1.value** `Object`: Rich text value. -- **$1.multilineTag** `[string]`: Multiline tag. +_Parameters_ -**Returns** +- _$1_ `Object`: Named argements. +- _$1.value_ `Object`: Rich text value. +- _$1.multilineTag_ `[string]`: Multiline tag. -`string`: HTML string. +_Returns_ -### unregisterFormatType +- `string`: HTML string. -[src/index.js#L32-L32](src/index.js#L32-L32) +# **unregisterFormatType** [\<>](src/index.js#L32-L32) Unregisters a format. -**Parameters** +_Parameters_ -- **name** `string`: Format name. +- _name_ `string`: Format name. -**Returns** +_Returns_ -`(WPFormat|undefined)`: The previous format value, if it has been successfully unregistered; otherwise `undefined`. +- `(WPFormat|undefined)`: The previous format value, if it has been successfully unregistered; otherwise `undefined`. diff --git a/packages/shortcode/README.md b/packages/shortcode/README.md index 4fc494b224206b..d848919f39ae48 100644 --- a/packages/shortcode/README.md +++ b/packages/shortcode/README.md @@ -16,9 +16,7 @@ _This package assumes that your code will run in an **ES2015+** environment. If -### attrs - -[src/index.js#L167-L210](src/index.js#L167-L210) +# **attrs** [\<>](src/index.js#L167-L210) Parse shortcode attributes. @@ -32,17 +30,15 @@ Named attributes can be formatted as either `name="value"`, `name='value'`, or `name=value`. Numeric attributes can be formatted as `"value"` or just `value`. -**Parameters** - -- **text** `string`: Serialised shortcode attributes. +_Parameters_ -**Returns** +- _text_ `string`: Serialised shortcode attributes. -`WPShortcodeAttrs`: Parsed shortcode attributes. +_Returns_ -### default +- `WPShortcodeAttrs`: Parsed shortcode attributes. -[src/index.js#L363-L363](src/index.js#L363-L363) +# **default** [\<>](src/index.js#L363-L363) Creates a shortcode instance. @@ -51,17 +47,15 @@ containing a `tag` string, a string or object of `attrs`, a string indicating the `type` of the shortcode ('single', 'self-closing', or 'closed'), and a `content` string. -**Parameters** +_Parameters_ -- **options** `Object`: Options as described. +- _options_ `Object`: Options as described. -**Returns** +_Returns_ -`WPShortcode`: Shortcode instance. +- `WPShortcode`: Shortcode instance. -### fromMatch - -[src/index.js#L223-L240](src/index.js#L223-L240) +# **fromMatch** [\<>](src/index.js#L223-L240) Generate a Shortcode Object from a RegExp match. @@ -69,33 +63,29 @@ Accepts a `match` object from calling `regexp.exec()` on a `RegExp` generated by `regexp()`. `match` can also be set to the `arguments` from a callback passed to `regexp.replace()`. -**Parameters** - -- **match** `Array`: Match array. +_Parameters_ -**Returns** +- _match_ `Array`: Match array. -`WPShortcode`: Shortcode instance. +_Returns_ -### next +- `WPShortcode`: Shortcode instance. -[src/index.js#L45-L80](src/index.js#L45-L80) +# **next** [\<>](src/index.js#L45-L80) Find the next matching shortcode. -**Parameters** +_Parameters_ -- **tag** `string`: Shortcode tag. -- **text** `string`: Text to search. -- **index** `number`: Index to start search from. +- _tag_ `string`: Shortcode tag. +- _text_ `string`: Text to search. +- _index_ `number`: Index to start search from. -**Returns** +_Returns_ -`?WPShortcodeMatch`: Matched information. +- `?WPShortcodeMatch`: Matched information. -### regexp - -[src/index.js#L146-L148](src/index.js#L146-L148) +# **regexp** [\<>](src/index.js#L146-L148) Generate a RegExp to identify a shortcode. @@ -112,33 +102,29 @@ Capture groups: 6. The closing tag. 7. An extra `]` to allow for escaping shortcodes with double `[[]]` -**Parameters** - -- **tag** `string`: Shortcode tag. +_Parameters_ -**Returns** +- _tag_ `string`: Shortcode tag. -`RegExp`: Shortcode RegExp. +_Returns_ -### replace +- `RegExp`: Shortcode RegExp. -[src/index.js#L92-L107](src/index.js#L92-L107) +# **replace** [\<>](src/index.js#L92-L107) Replace matching shortcodes in a block of text. -**Parameters** - -- **tag** `string`: Shortcode tag. -- **text** `string`: Text to search. -- **callback** `Function`: Function to process the match and return replacement string. +_Parameters_ -**Returns** +- _tag_ `string`: Shortcode tag. +- _text_ `string`: Text to search. +- _callback_ `Function`: Function to process the match and return replacement string. -`string`: Text with shortcodes replaced. +_Returns_ -### string +- `string`: Text with shortcodes replaced. -[src/index.js#L122-L124](src/index.js#L122-L124) +# **string** [\<>](src/index.js#L122-L124) Generate a string from shortcode parameters. @@ -148,13 +134,13 @@ Accepts the same `options` as the `shortcode()` constructor, containing a `tag` string, a string or object of `attrs`, a boolean indicating whether to format the shortcode using a `single` tag, and a `content` string. -**Parameters** +_Parameters_ -- **options** `Object`: +- _options_ `Object`: -**Returns** +_Returns_ -`string`: String representation of the shortcode. +- `string`: String representation of the shortcode. diff --git a/packages/url/README.md b/packages/url/README.md index 611efcddfc3f3b..fc9f9bdb06ee81 100644 --- a/packages/url/README.md +++ b/packages/url/README.md @@ -16,397 +16,359 @@ _This package assumes that your code will run in an **ES2015+** environment. If -### addQueryArgs - -[src/index.js#L242-L264](src/index.js#L242-L264) +# **addQueryArgs** [\<>](src/index.js#L242-L264) Appends arguments as querystring to the provided URL. If the URL already includes query arguments, the arguments are merged with (and take precedent over) the existing set. -**Usage** +_Usage_ ```js const newURL = addQueryArgs( 'https://google.com', { q: 'test' } ); // https://google.com/?q=test ``` -**Parameters** - -- **url** `?string`: URL to which arguments should be appended. If omitted, only the resulting querystring is returned. -- **args** `Object`: Query arguments to apply to URL. +_Parameters_ -**Returns** +- _url_ `?string`: URL to which arguments should be appended. If omitted, only the resulting querystring is returned. +- _args_ `Object`: Query arguments to apply to URL. -`string`: URL with arguments applied. +_Returns_ -### filterURLForDisplay +- `string`: URL with arguments applied. -[src/index.js#L379-L389](src/index.js#L379-L389) +# **filterURLForDisplay** [\<>](src/index.js#L379-L389) Returns a URL for display. -**Usage** +_Usage_ ```js const displayUrl = filterURLForDisplay( 'https://www.wordpress.org/gutenberg/' ); // wordpress.org/gutenberg ``` -**Parameters** - -- **url** `string`: Original URL. +_Parameters_ -**Returns** +- _url_ `string`: Original URL. -`string`: Displayed URL. +_Returns_ -### getAuthority +- `string`: Displayed URL. -[src/index.js#L79-L84](src/index.js#L79-L84) +# **getAuthority** [\<>](src/index.js#L79-L84) Returns the authority part of the URL. -**Usage** +_Usage_ ```js const authority1 = getAuthority( 'https://wordpress.org/help/' ); // 'wordpress.org' const authority2 = getAuthority( 'https://localhost:8080/test/' ); // 'localhost:8080' ``` -**Parameters** +_Parameters_ -- **url** `string`: The full URL. +- _url_ `string`: The full URL. -**Returns** +_Returns_ -`?string`: The authority part of the URL. +- `?string`: The authority part of the URL. -### getFragment - -[src/index.js#L199-L204](src/index.js#L199-L204) +# **getFragment** [\<>](src/index.js#L199-L204) Returns the fragment part of the URL. -**Usage** +_Usage_ ```js const fragment1 = getFragment( 'http://localhost:8080/this/is/a/test?query=true#fragment' ); // '#fragment' const fragment2 = getFragment( 'https://wordpress.org#another-fragment?query=true' ); // '#another-fragment' ``` -**Parameters** - -- **url** `string`: The full URL +_Parameters_ -**Returns** +- _url_ `string`: The full URL -`?string`: The fragment part of the URL. +_Returns_ -### getPath +- `?string`: The fragment part of the URL. -[src/index.js#L119-L124](src/index.js#L119-L124) +# **getPath** [\<>](src/index.js#L119-L124) Returns the path part of the URL. -**Usage** +_Usage_ ```js const path1 = getPath( 'http://localhost:8080/this/is/a/test?query=true' ); // 'this/is/a/test' const path2 = getPath( 'https://wordpress.org/help/faq/' ); // 'help/faq' ``` -**Parameters** +_Parameters_ -- **url** `string`: The full URL. +- _url_ `string`: The full URL. -**Returns** +_Returns_ -`?string`: The path part of the URL. +- `?string`: The path part of the URL. -### getProtocol - -[src/index.js#L39-L44](src/index.js#L39-L44) +# **getProtocol** [\<>](src/index.js#L39-L44) Returns the protocol part of the URL. -**Usage** +_Usage_ ```js const protocol1 = getProtocol( 'tel:012345678' ); // 'tel:' const protocol2 = getProtocol( 'https://wordpress.org' ); // 'https:' ``` -**Parameters** - -- **url** `string`: The full URL. +_Parameters_ -**Returns** +- _url_ `string`: The full URL. -`?string`: The protocol part of the URL. +_Returns_ -### getQueryArg +- `?string`: The protocol part of the URL. -[src/index.js#L279-L284](src/index.js#L279-L284) +# **getQueryArg** [\<>](src/index.js#L279-L284) Returns a single query argument of the url -**Usage** +_Usage_ ```js const foo = getQueryArg( 'https://wordpress.org?foo=bar&bar=baz', 'foo' ); // bar ``` -**Parameters** - -- **url** `string`: URL -- **arg** `string`: Query arg name +_Parameters_ -**Returns** +- _url_ `string`: URL +- _arg_ `string`: Query arg name -`(Array|string)`: Query arg value. +_Returns_ -### getQueryString +- `(Array|string)`: Query arg value. -[src/index.js#L159-L164](src/index.js#L159-L164) +# **getQueryString** [\<>](src/index.js#L159-L164) Returns the query string part of the URL. -**Usage** +_Usage_ ```js const queryString1 = getQueryString( 'http://localhost:8080/this/is/a/test?query=true#fragment' ); // 'query=true' const queryString2 = getQueryString( 'https://wordpress.org#fragment?query=false&search=hello' ); // 'query=false&search=hello' ``` -**Parameters** +_Parameters_ -- **url** `string`: The full URL. +- _url_ `string`: The full URL. -**Returns** +_Returns_ -`?string`: The query string part of the URL. +- `?string`: The query string part of the URL. -### hasQueryArg - -[src/index.js#L299-L301](src/index.js#L299-L301) +# **hasQueryArg** [\<>](src/index.js#L299-L301) Determines whether the URL contains a given query arg. -**Usage** +_Usage_ ```js const hasBar = hasQueryArg( 'https://wordpress.org?foo=bar&bar=baz', 'bar' ); // true ``` -**Parameters** - -- **url** `string`: URL -- **arg** `string`: Query arg name +_Parameters_ -**Returns** +- _url_ `string`: URL +- _arg_ `string`: Query arg name -`boolean`: Whether or not the URL contains the query arg. +_Returns_ -### isURL +- `boolean`: Whether or not the URL contains the query arg. -[src/index.js#L22-L24](src/index.js#L22-L24) +# **isURL** [\<>](src/index.js#L22-L24) Determines whether the given string looks like a URL. -**Usage** +_Usage_ ```js const isURL = isURL( 'https://wordpress.org' ); // true ``` -**Parameters** +_Parameters_ -- **url** `string`: The string to scrutinise. +- _url_ `string`: The string to scrutinise. -**Returns** +_Returns_ -`boolean`: Whether or not it looks like a URL. +- `boolean`: Whether or not it looks like a URL. -### isValidAuthority - -[src/index.js#L99-L104](src/index.js#L99-L104) +# **isValidAuthority** [\<>](src/index.js#L99-L104) Checks for invalid characters within the provided authority. -**Usage** +_Usage_ ```js const isValid = isValidAuthority( 'wordpress.org' ); // true const isNotValid = isValidAuthority( 'wordpress#org' ); // false ``` -**Parameters** - -- **authority** `string`: A string containing the URL authority. +_Parameters_ -**Returns** +- _authority_ `string`: A string containing the URL authority. -`boolean`: True if the argument contains a valid authority. +_Returns_ -### isValidFragment +- `boolean`: True if the argument contains a valid authority. -[src/index.js#L219-L224](src/index.js#L219-L224) +# **isValidFragment** [\<>](src/index.js#L219-L224) Checks for invalid characters within the provided fragment. -**Usage** +_Usage_ ```js const isValid = isValidFragment( '#valid-fragment' ); // true const isNotValid = isValidFragment( '#invalid-#fragment' ); // false ``` -**Parameters** - -- **fragment** `string`: The url fragment. +_Parameters_ -**Returns** +- _fragment_ `string`: The url fragment. -`boolean`: True if the argument contains a valid fragment. +_Returns_ -### isValidPath +- `boolean`: True if the argument contains a valid fragment. -[src/index.js#L139-L144](src/index.js#L139-L144) +# **isValidPath** [\<>](src/index.js#L139-L144) Checks for invalid characters within the provided path. -**Usage** +_Usage_ ```js const isValid = isValidPath( 'test/path/' ); // true const isNotValid = isValidPath( '/invalid?test/path/' ); // false ``` -**Parameters** +_Parameters_ -- **path** `string`: The URL path. +- _path_ `string`: The URL path. -**Returns** +_Returns_ -`boolean`: True if the argument contains a valid path +- `boolean`: True if the argument contains a valid path -### isValidProtocol - -[src/index.js#L59-L64](src/index.js#L59-L64) +# **isValidProtocol** [\<>](src/index.js#L59-L64) Tests if a url protocol is valid. -**Usage** +_Usage_ ```js const isValid = isValidProtocol( 'https:' ); // true const isNotValid = isValidProtocol( 'https :' ); // false ``` -**Parameters** - -- **protocol** `string`: The url protocol. +_Parameters_ -**Returns** +- _protocol_ `string`: The url protocol. -`boolean`: True if the argument is a valid protocol (e.g. http\:, tel:). +_Returns_ -### isValidQueryString +- `boolean`: True if the argument is a valid protocol (e.g. http\:, tel:). -[src/index.js#L179-L184](src/index.js#L179-L184) +# **isValidQueryString** [\<>](src/index.js#L179-L184) Checks for invalid characters within the provided query string. -**Usage** +_Usage_ ```js const isValid = isValidQueryString( 'query=true&another=false' ); // true const isNotValid = isValidQueryString( 'query=true?another=false' ); // false ``` -**Parameters** +_Parameters_ -- **queryString** `string`: The query string. +- _queryString_ `string`: The query string. -**Returns** +_Returns_ -`boolean`: True if the argument contains a valid query string. +- `boolean`: True if the argument contains a valid query string. -### prependHTTP - -[src/index.js#L338-L344](src/index.js#L338-L344) +# **prependHTTP** [\<>](src/index.js#L338-L344) Prepends "http\://" to a url, if it looks like something that is meant to be a TLD. -**Usage** +_Usage_ ```js const actualURL = prependHTTP( 'wordpress.org' ); // http://wordpress.org ``` -**Parameters** - -- **url** `string`: The URL to test +_Parameters_ -**Returns** +- _url_ `string`: The URL to test -`string`: The updated URL +_Returns_ -### removeQueryArgs +- `string`: The updated URL -[src/index.js#L316-L324](src/index.js#L316-L324) +# **removeQueryArgs** [\<>](src/index.js#L316-L324) Removes arguments from the query string of the url -**Usage** +_Usage_ ```js const newUrl = removeQueryArgs( 'https://wordpress.org?foo=bar&bar=baz&baz=foobar', 'foo', 'bar' ); // https://wordpress.org?baz=foobar ``` -**Parameters** +_Parameters_ -- **url** `string`: URL -- **args** `...string`: Query Args +- _url_ `string`: URL +- _args_ `...string`: Query Args -**Returns** +_Returns_ -`string`: Updated URL +- `string`: Updated URL -### safeDecodeURI - -[src/index.js#L359-L365](src/index.js#L359-L365) +# **safeDecodeURI** [\<>](src/index.js#L359-L365) Safely decodes a URI with `decodeURI`. Returns the URI unmodified if `decodeURI` throws an error. -**Usage** +_Usage_ ```js const badUri = safeDecodeURI( '%z' ); // does not throw an Error, simply returns '%z' ``` -**Parameters** - -- **uri** `string`: URI to decode. +_Parameters_ -**Returns** +- _uri_ `string`: URI to decode. -`string`: Decoded URI if possible. +_Returns_ -### safeDecodeURIComponent +- `string`: Decoded URI if possible. -[src/index.js#L399-L405](src/index.js#L399-L405) +# **safeDecodeURIComponent** [\<>](src/index.js#L399-L405) Safely decodes a URI component with `decodeURIComponent`. Returns the URI component unmodified if `decodeURIComponent` throws an error. -**Parameters** +_Parameters_ -- **uriComponent** `string`: URI component to decode. +- _uriComponent_ `string`: URI component to decode. -**Returns** +_Returns_ -`string`: Decoded URI component if possible. +- `string`: Decoded URI component if possible. diff --git a/packages/viewport/README.md b/packages/viewport/README.md index c11fd9172d10dc..cd1ed4d2d02b37 100644 --- a/packages/viewport/README.md +++ b/packages/viewport/README.md @@ -49,18 +49,16 @@ This package provides a set of HOCs to author components whose behavior should v -#### ifViewportMatches - -[src/index.js#L16-L16](src/index.js#L16-L16) +# **ifViewportMatches** [\<>](src/index.js#L16-L16) Higher-order component creator, creating a new component which renders if the viewport query is satisfied. -**Related** +_Related_ - withViewportMatches -**Usage** +_Usage_ ```jsx function MyMobileComponent() { @@ -70,27 +68,25 @@ function MyMobileComponent() { MyMobileComponent = ifViewportMatches( '< small' )( MyMobileComponent ); ``` -**Parameters** - -- **query** `string`: Viewport query. +_Parameters_ -**Returns** +- _query_ `string`: Viewport query. -`Function`: Higher-order component. +_Returns_ -#### withViewportMatch +- `Function`: Higher-order component. -[src/index.js#L17-L17](src/index.js#L17-L17) +# **withViewportMatch** [\<>](src/index.js#L17-L17) Higher-order component creator, creating a new component which renders with the given prop names, where the value passed to the underlying component is the result of the query assigned as the object's value. -**Related** +_Related_ - isViewportMatch -**Usage** +_Usage_ ```jsx function MyComponent( { isMobile } ) { @@ -102,13 +98,13 @@ function MyComponent( { isMobile } ) { MyComponent = withViewportMatch( { isMobile: '< small' } )( MyComponent ); ``` -**Parameters** +_Parameters_ -- **queries** `Object`: Object of prop name to viewport query. +- _queries_ `Object`: Object of prop name to viewport query. -**Returns** +_Returns_ -`Function`: Higher-order component. +- `Function`: Higher-order component. diff --git a/packages/wordcount/README.md b/packages/wordcount/README.md index ecd1de4a1ed810..76599096ef5a26 100644 --- a/packages/wordcount/README.md +++ b/packages/wordcount/README.md @@ -16,28 +16,26 @@ _This package assumes that your code will run in an **ES2015+** environment. If -### count - -[src/index.js#L107-L121](src/index.js#L107-L121) +# **count** [\<>](src/index.js#L107-L121) Count some words. -**Usage** +_Usage_ ```js import { count } from '@wordpress/wordcount'; const numberOfWords = count( 'Words to count', 'words', {} ) ``` -**Parameters** +_Parameters_ -- **text** `String`: The text being processed -- **type** `String`: The type of count. Accepts ;words', 'characters_excluding_spaces', or 'characters_including_spaces'. -- **userSettings** `Object`: Custom settings object. +- _text_ `String`: The text being processed +- _type_ `String`: The type of count. Accepts ;words', 'characters_excluding_spaces', or 'characters_including_spaces'. +- _userSettings_ `Object`: Custom settings object. -**Returns** +_Returns_ -`Number`: The word or character count. +- `Number`: The word or character count.