diff --git a/bin/update-readmes.js b/bin/update-readmes.js index 6f1efc62ff5a8..fb1be92aa4a34 100755 --- a/bin/update-readmes.js +++ b/bin/update-readmes.js @@ -27,21 +27,35 @@ const packages = [ //'plugins', //'priority-queue', //'redux-routine', - //'rich-text', + 'rich-text', //'shortcode', //'url', //'viewport', //'wordcount', ]; +const getArgsForPackage = ( packageName ) => { + switch ( packageName ) { + case 'rich-text': + return [ + `packages/${ packageName }/src/index.js`, + `--output packages/${ packageName }/README.md`, + '--to-token', + '--ignore "unstable|experimental|^apply$|^changeListType$|^charAt$|^getSelectionStart$|^getSelectionEnd$|^indentListItems$|^insertLineBreak$|^insertLineSeparator$|^isEmptyLine$|^LINE_SEPARATOR$|^outdentListItems$"', + ]; + default: + return [ + `packages/${ packageName }/src/index.js`, + `--output packages/${ packageName }/README.md`, + '--to-token', + '--ignore "unstable|experimental"', + ]; + } +}; + let aggregatedExitCode = 0; packages.forEach( ( packageName ) => { - const args = [ - `packages/${ packageName }/src/index.js`, - `--output packages/${ packageName }/README.md`, - '--to-token', - '--ignore "unstable|experimental"', - ]; + const args = getArgsForPackage( packageName ); const pathToDocGen = path.join( __dirname, '..', 'node_modules', '.bin', 'docgen' ); const { status, stderr } = childProcess.spawnSync( pathToDocGen, diff --git a/packages/rich-text/README.md b/packages/rich-text/README.md index be3d703b2678f..0ac85d85b640d 100644 --- a/packages/rich-text/README.md +++ b/packages/rich-text/README.md @@ -12,171 +12,347 @@ npm install @wordpress/rich-text _This package assumes that your code will run in an **ES2015+** environment. If you're using an environment that has limited or no support for ES2015+ such as lower versions of IE then using [core-js](https://github.com/zloirock/core-js) or [@babel/polyfill](https://babeljs.io/docs/en/next/babel-polyfill) will add support for these methods. Learn more about it in [Babel docs](https://babeljs.io/docs/en/next/caveats)._ -## Usage +## API + + + +### applyFormat + +[src/index.js#L6-L6](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. + +**Returns** + +`Object`: A new value with the format applied. + +### concat + +[src/index.js#L8-L8](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. + +**Returns** + +`Object`: A new value combining all given records. ### create -```js -create( { - ?element: Element, - ?text: string, - ?html: string, - ?range: Range, - ?multilineTag: string, - ?multilineWrapperTags: Array, -} ): Object -``` +[src/index.js#L9-L9](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 called without any arguments, an empty value will be created. If `multilineTag` is provided, any content of direct children whose type matches `multilineTag` will be separated by a line separator. +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 +called without any input, an empty value will be created. If +`multilineTag` is provided, any content of direct children whose type matches +`multilineTag` will be separated by two newlines. The optional functions can +be used to filter out content. -### toHTMLString +**Parameters** -```js -toHTMLString( { - value: Object, - ?multilineTag: string, - ?multilineWrapperTags: Array, -} ): string -``` +- **$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. -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. +**Returns** -### apply +`Object`: A rich text value. -```js -apply( { - value: Object, - current: Element, - ?multilineTag: string - ?multilineWrapperTags: Array, -} ): void -``` +### getActiveFormat + +[src/index.js#L10-L10](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. + +**Returns** + +`(Object|undefined)`: Active format object of the specified type, or undefined. + +### getTextContent + +[src/index.js#L13-L13](src/index.js#L13-L13) -Create an `Element` tree from a Rich Text value and applies the difference to the `Element` tree contained by `current`. If a `multilineTag` is provided, text separated by two new lines will be wrapped in an `Element` of that type. +Get the textual content of a Rich Text value. This is similar to +`Element.textContent`. + +**Parameters** + +- **value** `Object`: Value to use. + +**Returns** + +`string`: The text content. + +### insert + +[src/index.js#L21-L21](src/index.js#L21-L21) + +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. + +**Returns** + +`Object`: A new value with the value inserted. + +### insertObject + +[src/index.js#L24-L24](src/index.js#L24-L24) + +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** + +- **value** `Object`: Value to modify. +- **formatToInsert** `Object`: Format to insert as object. +- **startIndex** `[number]`: Start index. +- **endIndex** `[number]`: End index. + +**Returns** + +`Object`: A new value with the object inserted. ### isCollapsed -```js -isCollapsed( value: Object ): ?boolean -``` +[src/index.js#L14-L14](src/index.js#L14-L14) + +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. + +**Returns** -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()`. +`(boolean|undefined)`: True if the selection is collapsed, false if not, undefined if there is no selection. ### isEmpty -```js -isEmpty( value: Object ): boolean -``` +[src/index.js#L15-L15](src/index.js#L15-L15) -Check if a Rich Text value is Empty, meaning it contains no text or any objects (such as images). +Check if a Rich Text value is Empty, meaning it contains no text or any +objects (such as images). -### applyFormat +**Parameters** -```js -applyFormat( value: Object, format: Object, ?startIndex: number, ?endIndex: number ): Object -``` +- **value** `Object`: Value to use. -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. +**Returns** -### removeFormat +`boolean`: True if the value is empty, false if not. -```js -removeFormat( value: Object, formatType: string, ?startIndex: number, ?endIndex: number ): Object -``` +### join -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. +[src/index.js#L16-L16](src/index.js#L16-L16) -### toggleFormat +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`. -```js -toggleFormat( value: Object, format: Object ): Object -``` +**Parameters** -Toggles a format object to a Rich Text value at the current selection, and returns a new value with the format applied or removed. +- **values** `Array`: An array of values to join. +- **separator** `[(string|Object)]`: Separator string or value. -### getActiveFormat +**Returns** -```js -getActiveFormat( value: Object, formatType: string ): ?Object -``` +`Object`: A new combined value. -Get any 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. +### registerFormatType -### getTextContent +[src/index.js#L17-L17](src/index.js#L17-L17) -```js -getTextContent( value: Object ): string -``` +Registers a new format provided a unique name and an object defining its +behavior. -Get the textual content of a Rich Text value. This is similar to `Element.textContent`. +**Parameters** -### slice +- **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. -```js -slice( value: Object, ?startIndex: number, ?endIndex: number ): Object -``` +**Returns** + +`(WPFormat|undefined)`: The format, if it has been successfully registered; otherwise `undefined`. + +### remove + +[src/index.js#L19-L19](src/index.js#L19-L19) + +Remove content from a Rich Text value between the given `startIndex` and +`endIndex`. Indices are retrieved from the selection if none are provided. + +**Parameters** + +- **value** `Object`: Value to modify. +- **startIndex** `[number]`: Start index. +- **endIndex** `[number]`: End index. + +**Returns** -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`. +`Object`: A new value with the content removed. + +### removeFormat + +[src/index.js#L18-L18](src/index.js#L18-L18) + +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. + +**Returns** + +`Object`: A new value with the format applied. ### replace -```js -replace( value: Object, pattern: RegExp, replacement: Object | string ): Object -``` +[src/index.js#L20-L20](src/index.js#L20-L20) -Search a Rich Text value and replace the match(es) with `replacement`. This is similar to `String.prototype.replace`. +Search a Rich Text value and replace the match(es) with `replacement`. This +is similar to `String.prototype.replace`. -### insert +**Parameters** -```js -insert( value: Object, valueToInsert: Object | string, ?startIndex: number, ?endIndex: number ): Object -``` +- **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. -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. +**Returns** -### registerFormatType +`Object`: A new value with replacements applied. -```js -registerFormatType( name: String, settings: Object ): ?WPformat -``` +### slice -Registers a new format provided a unique name and an object defining its behavior. Settings object: +[src/index.js#L25-L25](src/index.js#L25-L25) -- `tagName`: String. The HTML tag this format will wrap the selection with. -- `className`: String || null. A class to match the format. -- `title`: String. Name of the format. -- `edit`: function. Should return a component for the user to interact with the new registered format. +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`. -### remove +**Parameters** -```js -remove( value: Object, ?startIndex: number, ?endIndex: number ): Object -``` +- **value** `Object`: Value to modify. +- **startIndex** `[number]`: Start index. +- **endIndex** `[number]`: End index. + +**Returns** -Remove content from a Rich Text value between the given `startIndex` and `endIndex`. Indices are retrieved from the selection if none are provided. +`Object`: A new extracted value. ### split -```js -split( value: Object, ?startIndex: number | string | RegExp, ?endIndex: number ): Array -``` +[src/index.js#L26-L26](src/index.js#L26-L26) -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. +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. -### join +**Parameters** -```js -join( values: Array, ?separator: Object | string ): Object -``` +- **value** `Object`: Value to modify. +- **string** `[(number|string)]`: Start index, or string at which to split. +- **endStr** `[number]`: End index. -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`. +**Returns** -### concat +`Array`: An array of new values. + +### toggleFormat + +[src/index.js#L29-L29](src/index.js#L29-L29) + +Toggles a format object to a Rich Text value at the current selection. + +**Parameters** + +- **value** `Object`: Value to modify. +- **format** `Object`: Format to apply or remove. + +**Returns** + +`Object`: A new value with the format applied or removed. + +### toHTMLString + +[src/index.js#L28-L28](src/index.js#L28-L28) + +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. +- **$1.multilineWrapperTags** `[Array]`: Tags where lines can be found if nesting is possible. + +**Returns** + +`string`: HTML string. + +### unregisterFormatType + +[src/index.js#L31-L31](src/index.js#L31-L31) + +Unregisters a format. + +**Parameters** + +- **name** `string`: Format name. + +**Returns** + +`(WPFormat|undefined)`: The previous format value, if it has been successfully unregistered; otherwise `undefined`. -```js -concat( ...values: Array ): Object -``` -Combine all Rich Text values into one. This is similar to `String.prototype.concat`. +

Code is Poetry.

diff --git a/packages/rich-text/src/apply-format.js b/packages/rich-text/src/apply-format.js index 271be1176931d..8134cd8d742a9 100644 --- a/packages/rich-text/src/apply-format.js +++ b/packages/rich-text/src/apply-format.js @@ -15,10 +15,10 @@ import { normaliseFormats } from './normalise-formats'; * given `endIndex`. Indices are retrieved from the selection if none are * provided. * - * @param {Object} value Value to modify. - * @param {Object} format Format to apply. - * @param {number} startIndex Start index. - * @param {number} endIndex End index. + * @param {Object} value Value to modify. + * @param {Object} format Format to apply. + * @param {number} [startIndex] Start index. + * @param {number} [endIndex] End index. * * @return {Object} A new value with the format applied. */ diff --git a/packages/rich-text/src/char-at.js b/packages/rich-text/src/char-at.js index 6f04c2e2ac1aa..e68d3b6a5a5ac 100644 --- a/packages/rich-text/src/char-at.js +++ b/packages/rich-text/src/char-at.js @@ -5,7 +5,7 @@ * @param {Object} value Value to get the character from. * @param {string} index Index to use. * - * @return {?string} A one character long string, or undefined. + * @return {string|undefined} A one character long string, or undefined. */ export function charAt( { text }, index ) { return text[ index ]; diff --git a/packages/rich-text/src/create.js b/packages/rich-text/src/create.js index 82348bbd4fa8a..9fa677828209d 100644 --- a/packages/rich-text/src/create.js +++ b/packages/rich-text/src/create.js @@ -89,14 +89,14 @@ function toFormat( { type, attributes } ) { * `multilineTag` will be separated by two newlines. The optional functions can * be used to filter out content. * - * @param {?Object} $1 Optional named argements. - * @param {?Element} $1.element Element to create value from. - * @param {?string} $1.text Text to create value from. - * @param {?string} $1.html HTML to create value from. - * @param {?Range} $1.range Range to create value from. - * @param {?string} $1.multilineTag Multiline tag if the structure is + * @param {Object} [$1] Optional named arguments. + * @param {Element} [$1.element] Element to create value from. + * @param {string} [$1.text] Text to create value from. + * @param {string} [$1.html] HTML to create value from. + * @param {Range} [$1.range] Range to create value from. + * @param {string} [$1.multilineTag] Multiline tag if the structure is * multiline. - * @param {?Array} $1.multilineWrapperTags Tags where lines can be found if + * @param {Array} [$1.multilineWrapperTags] Tags where lines can be found if * nesting is possible. * * @return {Object} A rich text value. diff --git a/packages/rich-text/src/get-active-format.js b/packages/rich-text/src/get-active-format.js index 89fcb5fc7711c..fd658bf6adc27 100644 --- a/packages/rich-text/src/get-active-format.js +++ b/packages/rich-text/src/get-active-format.js @@ -19,7 +19,7 @@ import { getActiveFormats } from './get-active-formats'; * @param {Object} value Value to inspect. * @param {string} formatType Format type to look for. * - * @return {?Object} Active format object of the specified type, or undefined. + * @return {Object|undefined} Active format object of the specified type, or undefined. */ export function getActiveFormat( value, formatType ) { return find( getActiveFormats( value ), { type: formatType } ); diff --git a/packages/rich-text/src/get-selection-end.js b/packages/rich-text/src/get-selection-end.js index 90dee341391c1..8154a48b451fb 100644 --- a/packages/rich-text/src/get-selection-end.js +++ b/packages/rich-text/src/get-selection-end.js @@ -5,7 +5,7 @@ * * @param {Object} value Value to get the selection from. * - * @return {?number} Index where the selection ends. + * @return {number|undefined} Index where the selection ends. */ export function getSelectionEnd( { end } ) { return end; diff --git a/packages/rich-text/src/get-selection-start.js b/packages/rich-text/src/get-selection-start.js index 948d380052314..442d84d308691 100644 --- a/packages/rich-text/src/get-selection-start.js +++ b/packages/rich-text/src/get-selection-start.js @@ -5,7 +5,7 @@ * * @param {Object} value Value to get the selection from. * - * @return {?number} Index where the selection starts. + * @return {number|undefined} Index where the selection starts. */ export function getSelectionStart( { start } ) { return start; diff --git a/packages/rich-text/src/indent-list-items.js b/packages/rich-text/src/indent-list-items.js index 516b3c85f96ea..1a61bd7db1536 100644 --- a/packages/rich-text/src/indent-list-items.js +++ b/packages/rich-text/src/indent-list-items.js @@ -40,7 +40,7 @@ function getTargetLevelLineIndex( { text, formats }, lineIndex ) { * Indents any selected list items if possible. * * @param {Object} value Value to change. - * @param {Object} rootFormat + * @param {Object} rootFormat Root format. * * @return {Object} The changed value. */ diff --git a/packages/rich-text/src/insert-line-separator.js b/packages/rich-text/src/insert-line-separator.js index 24174668d25cb..e273c9eea9ac4 100644 --- a/packages/rich-text/src/insert-line-separator.js +++ b/packages/rich-text/src/insert-line-separator.js @@ -11,9 +11,9 @@ import { LINE_SEPARATOR } from './special-characters'; * `startIndex`. Any content between `startIndex` and `endIndex` will be * removed. Indices are retrieved from the selection if none are provided. * - * @param {Object} value Value to modify. - * @param {number} startIndex Start index. - * @param {number} endIndex End index. + * @param {Object} value Value to modify. + * @param {number} [startIndex] Start index. + * @param {number} [endIndex] End index. * * @return {Object} A new value with the value inserted. */ diff --git a/packages/rich-text/src/insert-object.js b/packages/rich-text/src/insert-object.js index bf67ac3913b73..fcdfc6f897c2d 100644 --- a/packages/rich-text/src/insert-object.js +++ b/packages/rich-text/src/insert-object.js @@ -13,8 +13,8 @@ const OBJECT_REPLACEMENT_CHARACTER = '\ufffc'; * * @param {Object} value Value to modify. * @param {Object} formatToInsert Format to insert as object. - * @param {number} startIndex Start index. - * @param {number} endIndex End index. + * @param {number} [startIndex] Start index. + * @param {number} [endIndex] End index. * * @return {Object} A new value with the object inserted. */ diff --git a/packages/rich-text/src/insert.js b/packages/rich-text/src/insert.js index 10c2ec0e9621a..cf46305240fb7 100644 --- a/packages/rich-text/src/insert.js +++ b/packages/rich-text/src/insert.js @@ -11,10 +11,10 @@ import { normaliseFormats } from './normalise-formats'; * and `endIndex` will be removed. Indices are retrieved from the selection if * none are provided. * - * @param {Object} value Value to modify. - * @param {string} valueToInsert Value to insert. - * @param {number} startIndex Start index. - * @param {number} endIndex End index. + * @param {Object} value Value to modify. + * @param {Object|string} valueToInsert Value to insert. + * @param {number} [startIndex] Start index. + * @param {number} [endIndex] End index. * * @return {Object} A new value with the value inserted. */ diff --git a/packages/rich-text/src/is-collapsed.js b/packages/rich-text/src/is-collapsed.js index 7c1e49b5a7cd4..7014d510377c2 100644 --- a/packages/rich-text/src/is-collapsed.js +++ b/packages/rich-text/src/is-collapsed.js @@ -6,8 +6,8 @@ * * @param {Object} value The rich text value to check. * - * @return {?boolean} True if the selection is collapsed, false if not, - * undefined if there is no selection. + * @return {boolean|undefined} True if the selection is collapsed, false if not, + * undefined if there is no selection. */ export function isCollapsed( { start, end } ) { if ( start === undefined || end === undefined ) { diff --git a/packages/rich-text/src/join.js b/packages/rich-text/src/join.js index c2e3c103b0674..7784b5962ca53 100644 --- a/packages/rich-text/src/join.js +++ b/packages/rich-text/src/join.js @@ -10,8 +10,8 @@ import { normaliseFormats } from './normalise-formats'; * `separator`, which can be a Rich Text value, HTML string, or plain text * string. This is similar to `Array.prototype.join`. * - * @param {Array} values An array of values to join. - * @param {string|Object} separator Separator string or value. + * @param {Array} values An array of values to join. + * @param {string|Object} [separator] Separator string or value. * * @return {Object} A new combined value. */ diff --git a/packages/rich-text/src/register-format-type.js b/packages/rich-text/src/register-format-type.js index 262812a22b248..8b07559541984 100644 --- a/packages/rich-text/src/register-format-type.js +++ b/packages/rich-text/src/register-format-type.js @@ -26,11 +26,15 @@ const EMPTY_ARRAY = []; * Registers a new format provided a unique name and an object defining its * behavior. * - * @param {string} name Format name. - * @param {Object} settings Format settings. + * @param {string} name Format name. + * @param {Object} settings Format settings. + * @param {string} settings.tagName The HTML tag this format will wrap the selection with. + * @param {string} [settings.className] A class to match the format. + * @param {string} settings.title Name of the format. + * @param {Function} settings.edit Should return a component for the user to interact with the new registered format. * - * @return {?WPFormat} The format, if it has been successfully registered; - * otherwise `undefined`. + * @return {WPFormat|undefined} The format, if it has been successfully registered; + * otherwise `undefined`. */ export function registerFormatType( name, settings ) { settings = { diff --git a/packages/rich-text/src/remove-format.js b/packages/rich-text/src/remove-format.js index d6f2890f3afaf..be1c92ace7fd4 100644 --- a/packages/rich-text/src/remove-format.js +++ b/packages/rich-text/src/remove-format.js @@ -15,10 +15,10 @@ import { normaliseFormats } from './normalise-formats'; * `startIndex` to the given `endIndex`. Indices are retrieved from the * selection if none are provided. * - * @param {Object} value Value to modify. - * @param {string} formatType Format type to remove. - * @param {number} startIndex Start index. - * @param {number} endIndex End index. + * @param {Object} value Value to modify. + * @param {string} formatType Format type to remove. + * @param {number} [startIndex] Start index. + * @param {number} [endIndex] End index. * * @return {Object} A new value with the format applied. */ diff --git a/packages/rich-text/src/remove.js b/packages/rich-text/src/remove.js index de4241ad301e6..c3af472167baa 100644 --- a/packages/rich-text/src/remove.js +++ b/packages/rich-text/src/remove.js @@ -9,9 +9,9 @@ import { create } from './create'; * Remove content from a Rich Text value between the given `startIndex` and * `endIndex`. Indices are retrieved from the selection if none are provided. * - * @param {Object} value Value to modify. - * @param {number} startIndex Start index. - * @param {number} endIndex End index. + * @param {Object} value Value to modify. + * @param {number} [startIndex] Start index. + * @param {number} [endIndex] End index. * * @return {Object} A new value with the content removed. */ diff --git a/packages/rich-text/src/slice.js b/packages/rich-text/src/slice.js index 3a54642b98cc7..bb4313dd61309 100644 --- a/packages/rich-text/src/slice.js +++ b/packages/rich-text/src/slice.js @@ -3,9 +3,9 @@ * retrieved from the selection if none are provided. This is similar to * `String.prototype.slice`. * - * @param {Object} value Value to modify. - * @param {number} startIndex Start index. - * @param {number} endIndex End index. + * @param {Object} value Value to modify. + * @param {number} [startIndex] Start index. + * @param {number} [endIndex] End index. * * @return {Object} A new extracted value. */ diff --git a/packages/rich-text/src/special-characters.js b/packages/rich-text/src/special-characters.js index 611869f8dbe56..5695c40c745b9 100644 --- a/packages/rich-text/src/special-characters.js +++ b/packages/rich-text/src/special-characters.js @@ -1,2 +1,5 @@ +/** + * Line separator character. + */ export const LINE_SEPARATOR = '\u2028'; export const OBJECT_REPLACEMENT_CHARACTER = '\ufffc'; diff --git a/packages/rich-text/src/split.js b/packages/rich-text/src/split.js index d8b40b5aafb75..a300c3ccbcca4 100644 --- a/packages/rich-text/src/split.js +++ b/packages/rich-text/src/split.js @@ -9,9 +9,9 @@ import { replace } from './replace'; * split at the given separator. This is similar to `String.prototype.split`. * Indices are retrieved from the selection if none are provided. * - * @param {Object} value Value to modify. - * @param {number|string} string Start index, or string at which to split. - * @param {number} end End index. + * @param {Object} value Value to modify. + * @param {number|string} [string] Start index, or string at which to split. + * @param {number} [endStr] End index. * * @return {Array} An array of new values. */ diff --git a/packages/rich-text/src/to-dom.js b/packages/rich-text/src/to-dom.js index 987849172bf5f..b81c518468444 100644 --- a/packages/rich-text/src/to-dom.js +++ b/packages/rich-text/src/to-dom.js @@ -164,10 +164,11 @@ export function toDom( { * the `Element` tree contained by `current`. If a `multilineTag` is provided, * text separated by two new lines will be wrapped in an `Element` of that type. * - * @param {Object} value Value to apply. - * @param {HTMLElement} current The live root node to apply the element - * tree to. - * @param {string} multilineTag Multiline tag. + * @param {Object} $1 Named arguments. + * @param {Object} $1.value Value to apply. + * @param {HTMLElement} $1.current The live root node to apply the element tree to. + * @param {string} [$1.multilineTag] Multiline tag. + * @param {Array} [$1.multilineWrapperTags] Tags where lines can be found if nesting is possible. */ export function apply( { value, diff --git a/packages/rich-text/src/to-html-string.js b/packages/rich-text/src/to-html-string.js index 324dd2d65d287..0ba36e62510a3 100644 --- a/packages/rich-text/src/to-html-string.js +++ b/packages/rich-text/src/to-html-string.js @@ -18,11 +18,11 @@ import { toTree } from './to-tree'; * 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. * - * @param {Object} $1 Named argements. - * @param {Object} $1.value Rich text value. - * @param {string} $1.multilineTag Multiline tag. - * @param {Array} $1.multilineWrapperTags Tags where lines can be found if - * nesting is possible. + * @param {Object} $1 Named argements. + * @param {Object} $1.value Rich text value. + * @param {string} [$1.multilineTag] Multiline tag. + * @param {Array} [$1.multilineWrapperTags] Tags where lines can be found if + * nesting is possible. * * @return {string} HTML string. */ diff --git a/packages/rich-text/src/toggle-format.js b/packages/rich-text/src/toggle-format.js index 147d9524df246..6e7854dcaa662 100644 --- a/packages/rich-text/src/toggle-format.js +++ b/packages/rich-text/src/toggle-format.js @@ -9,8 +9,8 @@ import { applyFormat } from './apply-format'; /** * Toggles a format object to a Rich Text value at the current selection. * - * @param {Object} value Value to modify. - * @param {Object} format Format to apply or remove. + * @param {Object} value Value to modify. + * @param {Object} format Format to apply or remove. * * @return {Object} A new value with the format applied or removed. */ diff --git a/packages/rich-text/src/unregister-format-type.js b/packages/rich-text/src/unregister-format-type.js index cffaa3d025b94..6f6741183ee16 100644 --- a/packages/rich-text/src/unregister-format-type.js +++ b/packages/rich-text/src/unregister-format-type.js @@ -9,8 +9,8 @@ import { removeFilter } from '@wordpress/hooks'; * * @param {string} name Format name. * - * @return {?WPFormat} The previous format value, if it has been successfully - * unregistered; otherwise `undefined`. + * @return {WPFormat|undefined} The previous format value, if it has been successfully + * unregistered; otherwise `undefined`. */ export function unregisterFormatType( name ) { const oldFormat = select( 'core/rich-text' ).getFormatType( name );