PHPXRef 0.7.1 : WordPress Trunk (Updated Daily) : Detail view of rich-text.js

Class: RichTextData - X-Ref

The RichTextData class is used to instantiate a wrapper around rich text
values, with methods that can be used to transform or manipulate the data.

- Create an empty instance: `new RichTextData()`.
- Create one from an HTML string: `RichTextData.fromHTMLString(
'<em>hello</em>' )`.
- Create one from a wrapper HTMLElement: `RichTextData.fromHTMLElement(
document.querySelector( 'p' ) )`.
- Create one from plain text: `RichTextData.fromPlainText( '1\n2' )`.
- Create one from a rich text value: `new RichTextData( { text: '...',
formats: [ ... ] } )`.

create({element,text,html,range,__unstableIsEditableTree: isEditableTree} = {}) X-Ref

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. The optional
functions can be used to filter out content.

A value will have the following shape, which you are strongly encouraged not
to modify without the use of helper functions:

```js
{
text: string,
formats: Array,
replacements: Array,
?start: number,
?end: number,
}
```

As you can see, text and formatting are separated. `text` holds the text,
including any replacement characters for objects and lines. `formats`,
`objects` and `lines` are all sparse arrays of the same length as `text`. It
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.

return: {RichTextValue} A rich text value.
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: {boolean} [$1.__unstableIsEditableTree]

accumulateSelection(accumulator, node, range, value) X-Ref

Helper to accumulate the value's selection start and end from the current
node and range.

param: {Object} accumulator Object to accumulate into.
param: {Node}   node        Node to create value with.
param: {Range}  range       Range to create value with.
param: {Object} value       Value that is being accumulated.

filterRange(node, range, filter) X-Ref

Adjusts the start and end offsets from a range based on a text filter.

return: {Object|void} Object containing range properties.
param: {Node} node Node of which the text should be filtered.
param: {Range} range The range to filter.
param: {Function} filter Function to use to filter the text.

collapseWhiteSpace(element, isRoot = true) X-Ref

Collapse any whitespace used for HTML formatting to one space character,
because it will also be displayed as such by the browser.

We need to strip it from the content because we use white-space: pre-wrap for
displaying editable rich text. Without using white-space: pre-wrap, the
browser will litter the content with non breaking spaces, among other issues.
See packages/rich-text/src/component/use-default-style.js.

return: {HTMLElement} New element with collapsed whitespace.
param: {HTMLElement} element
param: {boolean} isRoot

removeReservedCharacters(string) X-Ref

Removes reserved characters used by rich-text (zero width non breaking spaces
added by `toTree` and object replacement characters).

param: {string} string

createFromElement({element,range,isEditableTree}) X-Ref

Creates a Rich Text value from a DOM element and range.

return: {RichTextValue} A rich text value.
param: {Object}  $1                  Named argements.
param: {Element} [$1.element]        Element to create value from.
param: {Range}   [$1.range]          Range to create value from.
param: {boolean} [$1.isEditableTree]

mergeFormats(formats) X-Ref

No description

getAttributes({element}) X-Ref

Gets the attributes of an element in object shape.

return: {Object|void} Attribute object or `undefined` if the element has no
param: {Object} $1 Named argements.
param: {Element} $1.element Element to get attributes from.

mergePair(a, b) X-Ref

Concats a pair of rich text values. Not that this mutates `a` and does NOT
normalise formats!

return: {Object} `a`, mutated.
param: {Object} a Value to mutate.
param: {Object} b Value to add read from.

concat(...values) X-Ref

Combine all Rich Text values into one. This is similar to
`String.prototype.concat`.

return: {RichTextValue} A new value combining all given records.
param: {...RichTextValue} values Objects to combine.

getActiveFormat(value, formatType) X-Ref

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.

return: {RichTextFormat|undefined} Active format object of the specified
param: {RichTextValue} value Value to inspect.
param: {string} formatType Format type to look for.

getActiveObject({start,end,replacements,text}) X-Ref

Gets the active object, if there is any.

return: {RichTextFormat|void} Active object, or undefined.
param: {RichTextValue} value Value to inspect.

isCollapsed({start,end}) X-Ref

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()`.

return: True if the selection is collapsed, false if not, undefined if there is no selection.
param: props The rich text value to check.
param: props.start
param: props.end

isEmpty({text}) X-Ref

Check if a Rich Text value is Empty, meaning it contains no text or any
objects (such as images).

return: {boolean} True if the value is empty, false if not.
param: {RichTextValue} value Value to use.

join(values, separator = '') X-Ref

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`.

return: {RichTextValue} A new combined value.
param: {Array<RichTextValue>} values An array of values to join.
param: {string|RichTextValue} [separator] Separator string or value.

registerFormatType(name, settings) X-Ref

Registers a new format provided a unique name and an object defining its
behavior.

return: {WPFormat|undefined} The format, if it has been successfully
param: {string} name Format name.
param: {WPFormat} settings Format settings.

removeFormat(value, formatType, startIndex = value.start, endIndex = value.end) X-Ref

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.

return: {RichTextValue} A new value with the format applied.
param: {RichTextValue} value        Value to modify.
param: {string}        formatType   Format type to remove.
param: {number}        [startIndex] Start index.
param: {number}        [endIndex]   End index.

filterFormats(formats, index, formatType) X-Ref

No description

insert(value, valueToInsert, startIndex = value.start, endIndex = value.end) X-Ref

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.

return: {RichTextValue} A new value with the value inserted.
param: {RichTextValue}        value         Value to modify.
param: {RichTextValue|string} valueToInsert Value to insert.
param: {number}               [startIndex]  Start index.
param: {number}               [endIndex]    End index.

remove_remove(value, startIndex, endIndex) X-Ref

Remove content from a Rich Text value between the given `startIndex` and
`endIndex`. Indices are retrieved from the selection if none are provided.

return: {RichTextValue} A new value with the content removed.
param: {RichTextValue} value        Value to modify.
param: {number}        [startIndex] Start index.
param: {number}        [endIndex]   End index.

replace_replace({formats,replacements,text,start,end}, pattern, replacement) X-Ref

Search a Rich Text value and replace the match(es) with `replacement`. This
is similar to `String.prototype.replace`.

return: {RichTextValue} A new value with replacements applied.
param: {RichTextValue} value The value to modify.
param: {RegExp|string} pattern A RegExp object or literal. Can also be
param: {Function|string} replacement The match or matches are replaced with

insertObject(value, formatToInsert, startIndex, endIndex) X-Ref

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.

return: {RichTextValue} A new value with the object inserted.
param: {RichTextValue}  value          Value to modify.
param: {RichTextFormat} formatToInsert Format to insert as object.
param: {number}         [startIndex]   Start index.
param: {number}         [endIndex]     End index.

slice(value, startIndex = value.start, endIndex = value.end) X-Ref

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`.

return: {RichTextValue} A new extracted value.
param: {RichTextValue} value        Value to modify.
param: {number}        [startIndex] Start index.
param: {number}        [endIndex]   End index.

split({formats,replacements,text,start,end}, string) X-Ref

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.

return: {Array<RichTextValue>|undefined} An array of new values.
param: {RichTextValue} value
param: {number|string} [string] Start index, or string at which to split.

splitAtSelection({formats,replacements,text,start,end}, startIndex = start, endIndex = end) X-Ref

No description

isRangeEqual(a, b) X-Ref

Returns true if two ranges are equal, or false otherwise. Ranges are
considered equal if their start and end occur in the same container and
offset.

return: {boolean} Whether the two ranges are equal.
param: {Range|null} a First range object to test.
param: {Range|null} b First range object to test.

createPathToNode(node, rootNode, path) X-Ref

Creates a path as an array of indices from the given root node to the given
node.

return: {Array} The path from the root node to the node.
param: {Node} node Node to find the path of.
param: {HTMLElement} rootNode Root node to find the path from.
param: {Array} path Initial path to build on.

getNodeByPath(node, path) X-Ref

Gets a node given a path (array of indices) from the given node.

return: {Object} Object with the found node and the remaining offset (if any).
param: {HTMLElement} node Root node to find the wanted node in.
param: {Array} path Path (indices) to the wanted node.

to_dom_append(element, child) X-Ref

No description

to_dom_appendText(node, text) X-Ref

No description

to_dom_getLastChild({lastChild}) X-Ref

No description

to_dom_getParent({parentNode}) X-Ref

No description

to_dom_isText(node) X-Ref

No description

to_dom_getText({nodeValue}) X-Ref

No description

to_dom_remove(node) X-Ref

No description

toDom({value,prepareEditableTree,isEditableTree = true,placeholder,doc = document}) X-Ref

No description

apply({value,current,prepareEditableTree,__unstableDomOnly,placeholder}) X-Ref

Create an `Element` tree from a Rich Text value and applies the difference to
the `Element` tree contained by `current`.

param: {Object}        $1                       Named arguments.
param: {RichTextValue} $1.value                 Value to apply.
param: {HTMLElement}   $1.current               The live root node to apply the element tree to.
param: {Function}      [$1.prepareEditableTree] Function to filter editorable formats.
param: {boolean}       [$1.__unstableDomOnly]   Only apply elements, no selection.
param: {string}        [$1.placeholder]         Placeholder text.

applyValue(future, current) X-Ref

No description

applySelection({startPath,endPath}, current) X-Ref

No description

toggleFormat(value, format) X-Ref

Toggles a format object to a Rich Text value at the current selection.

return: {RichTextValue} A new value with the format applied or removed.
param: {RichTextValue} value Value to modify.
param: {RichTextFormat} format Format to apply or remove.

unregisterFormatType(name) X-Ref

Unregisters a format.

return: {WPFormat|undefined} The previous format value, if it has
param: {string} name Format name.

useAnchorRef({ref,value,settings = {}}) X-Ref

This hook, to be used in a format type's Edit component, returns the active
element that is formatted, or the selection range if no format is active.
The returned value is meant to be used for positioning UI, e.g. by passing it
to the `Popover` component.

return: {Element|Range} The active element or selection range.
param: {Object}                 $1          Named parameters.
param: {RefObject<HTMLElement>} $1.ref      React ref of the element
param: {RichTextValue}          $1.value    Value to check for selection.
param: {WPFormat}               $1.settings The format type's settings.

getFormatElement(range, editableContentElement, tagName, className) X-Ref

Given a range and a format tag name and class name, returns the closest
format element.

return: {HTMLElement|undefined} The format element, if found.
param: {Range}       range                  The Range to check.
param: {HTMLElement} editableContentElement The editable wrapper.
param: {string}      tagName                The tag name of the format element.
param: {string}      className              The class name of the format element.

createVirtualAnchorElement(range, editableContentElement) X-Ref

Creates a virtual anchor element for a range.

return: {VirtualAnchorElement} The virtual anchor element.
param: {Range} range The range to create a virtual anchor element for.
param: {HTMLElement} editableContentElement The editable wrapper.

getAnchor(editableContentElement, tagName, className) X-Ref

Get the anchor: a format element if there is a matching one based on the
tagName and className or a range otherwise.

return: {HTMLElement|VirtualAnchorElement|undefined} The anchor.
param: {HTMLElement} editableContentElement The editable wrapper.
param: {string} tagName The tag name of the format
param: {string} className The class name of the format

useAnchor({editableContentElement,settings = {}}) X-Ref

This hook, to be used in a format type's Edit component, returns the active
element that is formatted, or a virtual element for the selection range if
no format is active. The returned value is meant to be used for positioning
UI, e.g. by passing it to the `Popover` component via the `anchor` prop.

return: {Element|VirtualAnchorElement|undefined|null} The active element or selection range.
param: {Object} $1 Named parameters.
param: {HTMLElement|null} $1.editableContentElement The element containing
param: {WPFormat=} $1.settings The format type's settings.

callback() X-Ref

No description

attach() X-Ref

No description

detach() X-Ref

No description

useDefaultStyle() X-Ref

A minimum width of 1px will prevent the rich text container from collapsing
to 0 width and hiding the caret. This is useful for inline containers.

useBoundaryStyle({record}) X-Ref

No description

useCopyHandler(props) X-Ref

No description

onCopy(event) X-Ref

No description

useFormatBoundaries(props) X-Ref

Internal dependencies

onKeyDown(event) X-Ref

No description

useSelectObject() X-Ref

WordPress dependencies

onClick(event) X-Ref

No description

onFocusIn(event) X-Ref

No description

updateFormats({value,start,end,formats}) X-Ref

Efficiently updates all the formats from `start` (including) until `end`
(excluding) with the active formats. Mutates `value`.

return: {RichTextValue} Mutated value.
param: {Object}        $1         Named paramentes.
param: {RichTextValue} $1.value   Value te update.
param: {number}        $1.start   Index to update from.
param: {number}        $1.end     Index to update until.
param: {Array}         $1.formats Replacement formats.

fixPlaceholderSelection(defaultView) X-Ref

If the selection is set on the placeholder element, collapse the selection to
the start (before the placeholder).

param: {Window} defaultView

useInputAndSelection(props) X-Ref

No description

onInput(event) X-Ref

No description

handleSelectionChange() X-Ref

Syncs the selection to local state. A callback for the
`selectionchange` event.

onCompositionStart() X-Ref

No description

onCompositionEnd() X-Ref

No description

onFocus() X-Ref

No description

useSelectionChangeCompat() X-Ref

Sometimes some browsers are not firing a `selectionchange` event when
changing the selection by mouse or keyboard. This hook makes sure that, if we
detect no `selectionchange` or `input` event between the up and down events,
we fire a `selectionchange` event.

return: {import('@wordpress/compose').RefEffect} A ref effect attaching the

getRange() X-Ref

No description

onDown(event) X-Ref

No description

onCancel() X-Ref

No description

onUp() X-Ref

No description

useDelete(props) X-Ref

Internal dependencies

onKeyDown(event) X-Ref

No description

useRichText({value = '',selectionStart,selectionEnd,placeholder,onSelectionChange,preserveWhiteSpace,onChange,__unstableDisableFormats: disableFormats,__unstableIsSelected: isSelected,__unstableDependencies = [],__unstableAfterParse,__unstableBeforeSerialize,__unstableAddInvisibleFormats}) X-Ref

No description

createRecord() X-Ref

No description

applyRecord(newRecord, {domOnly} = {}) X-Ref

No description

setRecordFromProps() X-Ref

No description

handleChange(newRecord) X-Ref

Sync the value to global state. The node tree and selection will also be
updated if differences are found.

param: {Object} newRecord The record to sync and apply.

applyFromProps() X-Ref

No description

__experimentalRichText() X-Ref

No description

Functions

Functions that are not part of a class:

formatTypes(state = {}, action) X-Ref

Reducer managing the format types

return: {Object} Updated state.
param: {Object} state Current state.
param: {Object} action Dispatched action.

arrayOf(value) X-Ref

Returns the first argument as the sole entry in an array.

return: {[T]} Value returned as entry in array.
param: {T} value Value to return.

isObjectLike(value) X-Ref

Returns true if the value passed is object-like, or false otherwise. A value
is object-like if it can support property assignment, e.g. object or array.

return: {boolean} Whether value is object-like.
param: {*} value Value to test.

createCache() X-Ref

Creates and returns a new cache object.

return: {Cache} Cache object.

isShallowEqual(a, b, fromIndex) X-Ref

Returns true if entries within the two arrays are strictly equal by
reference from a starting index.

return: {boolean} Whether arrays are shallowly equal.
param: {*[]} a First array.
param: {*[]} b Second array.
param: {number} fromIndex Index from which to start comparison.

rememo(selector, getDependants) X-Ref

Returns a memoized selector function. The getDependants function argument is
called before the memoized selector and is expected to return an immutable
reference or array of references on which the selector depends for computing
its own return value. The memoize cache is preserved only as long as those
dependant references remain the same. If getDependants returns a different
reference(s), the cache is cleared and the selector value regenerated.

param: {S} selector Selector function.
param: {GetDependants=} getDependants Dependant getter returning an array of

getCache(dependants) X-Ref

Returns the cache for a given dependants array. When possible, a WeakMap
will be used to create a unique cache for each set of dependants. This
is feasible due to the nature of WeakMap in allowing garbage collection
to occur on entries where the key object is no longer referenced. Since
WeakMap requires the key to be an object, this is only possible when the
dependant is object-like. The root cache is created as a hierarchy where
each top-level key is the first entry in a dependants set, the value a
WeakMap where each key is the next dependant, and so on. This continues
so long as the dependants are object-like. If no dependants are object-
like, then the cache is shared across all invocations.

return: {Cache} Cache object.
param: {*[]} dependants Selector dependants.

clear() X-Ref

Resets root memoization cache.

callSelector() X-Ref

The augmented selector call, considering first whether dependants have
changed before passing it to underlying memoize function.

return: {*} Selector result.
param: {*} source Source object for derivation.
param: {...*} extraArgs Additional arguments to pass to selector.

getFormatType(state, name) X-Ref

Returns a format type by name.

return: {Object?} Format type.
param: {Object} state Data state.
param: {string} name Format type name.

getFormatTypeForBareElement(state, bareElementTagName) X-Ref

Gets the format type, if any, that can handle a bare element (without a
data-format-type attribute), given the tag name of this element.

return: {?Object} Format type.
param: {Object} state Data state.
param: {string} bareElementTagName The tag name of the element to find a

getFormatTypeForClassName(state, elementClassName) X-Ref

Gets the format type, if any, that can handle an element, given its classes.

return: {?Object} Format type.
param: {Object} state Data state.
param: {string} elementClassName The classes of the element to find a format

addFormatTypes(formatTypes) X-Ref

Returns an action object used in signalling that format types have been
added.
Ignored from documentation as registerFormatType should be used instead from @wordpress/rich-text

return: {Object} Action object.
param: {Array|Object} formatTypes Format types received.

removeFormatTypes(names) X-Ref

Returns an action object used to remove a registered format type.

Ignored from documentation as unregisterFormatType should be used instead from @wordpress/rich-text

return: {Object} Action object.
param: {string|Array} names Format name.

isFormatEqual(format1, format2) X-Ref

Optimised equality check for format objects.

return: {boolean} True if formats are equal, false if not.
param: {?RichTextFormat} format1 Format to compare.
param: {?RichTextFormat} format2 Format to compare.

normaliseFormats(value) X-Ref

Normalises formats: ensures subsequent adjacent equal formats have the same
reference.

return: {RichTextValue} New value with normalised formats.
param: {RichTextValue} value Value to normalise formats of.

replace(array, index, value) X-Ref

No description

applyFormat(value, format, startIndex = value.start, endIndex = value.end) X-Ref

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.

return: {RichTextValue} A new value with the format applied.
param: {RichTextValue}  value        Value to modify.
param: {RichTextFormat} format       Format to apply.
param: {number}         [startIndex] Start index.
param: {number}         [endIndex]   End index.

createElement({implementation}, html) X-Ref

Parse the given HTML into a body element.

Note: The current implementation will return a shared reference, reset on
each call to `createElement`. Therefore, you should not hold a reference to
the value to operate upon asynchronously, as it may have unexpected results.

return: {HTMLBodyElement} Body element with parsed HTML.
param: {HTMLDocument} document The HTML document to use to parse.
param: {string} html The HTML to parse.

getActiveFormats(value, EMPTY_ACTIVE_FORMATS = []) X-Ref

Gets the all format objects at the start of the selection.

return: {RichTextFormatList} Active format objects.
param: {RichTextValue} value Value to inspect.
param: {Array} EMPTY_ACTIVE_FORMATS Array to return if there are no

get_format_type_getFormatType(name) X-Ref

Returns a registered format type.

return: {RichTextFormatType|undefined} Format type.
param: {string} name Format name.

restoreOnAttributes(attributes, isEditableTree) X-Ref

No description

fromFormat({type,tagName,attributes,unregisteredAttributes,object,boundaryClass,isEditableTree}) X-Ref

Converts a format object to information that can be used to create an element
from (type, attributes and object).

return: {Object} Information to be used for element creation.
param: {Object}  $1                        Named parameters.
param: {string}  $1.type                   The format type.
param: {string}  $1.tagName                The tag name.
param: {Object}  $1.attributes             The format attributes.
param: {Object}  $1.unregisteredAttributes The unregistered format
param: {boolean} $1.object                 Whether or not it is an object
param: {boolean} $1.boundaryClass          Whether or not to apply a boundary
param: {boolean} $1.isEditableTree

isEqualUntil(a, b, index) X-Ref

Checks if both arrays of formats up until a certain index are equal.

param: {Array} a Array of formats to compare.
param: {Array} b Array of formats to compare.
param: {number} index Index to check until.

toTree({value,preserveWhiteSpace,createEmpty,append,getLastChild,getParent,isText,getText,remove,appendText,onStartIndex,onEndIndex,isEditableTree,placeholder}) X-Ref

No description

toHTMLString({value,preserveWhiteSpace}) X-Ref

Create an HTML string from a Rich Text value.

return: {string} HTML string.
param: {Object}        $1                      Named argements.
param: {RichTextValue} $1.value                Rich text value.
param: {boolean}       [$1.preserveWhiteSpace] Preserves newlines if true.

createEmpty() X-Ref

No description

getLastChild({children}) X-Ref

No description

append(parent, object) X-Ref

No description

appendText(object, text) X-Ref

No description

getParent({parent}) X-Ref

No description

isText({text}) X-Ref

No description

getText({text}) X-Ref

No description

remove(object) X-Ref

No description

createElementHTML({type,attributes,object,children}) X-Ref

No description

createChildrenHTML(children = []) X-Ref

No description

getTextContent({text}) X-Ref

Get the textual content of a Rich Text value. This is similar to
`Element.textContent`.

return: {string} The text content.
param: {RichTextValue} value Value to use.

createEmptyValue() X-Ref

No description

toFormat({tagName,attributes}) X-Ref

No description

File Size:	4186 lines (126 kb)
Included or required:	0 times
Referenced:	0 times
Includes or requires:	0 files

PHP Cross Reference of WordPress Trunk (Updated Daily)

/wp-includes/js/dist/ -> rich-text.js (summary)

Defines 1 class

Defines 80 functions