Converts RichText Package to Typescript

packages/rich-text/README.md

@@ -130,8 +130,8 @@ _Parameters_
 
 -   _value_ `RichTextValue`: Value to modify.
 -   _format_ `RichTextFormat`: Format to apply.
--   _startIndex_ `[number]`: Start index.
--   _endIndex_ `[number]`: End index.
+-   _startIndex_ `number | undefined`: Start index.
+-   _endIndex_ `number | undefined`: End index.
 
 _Returns_
 
@@ -172,7 +172,7 @@ _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.html_ `[string | RichTextData]`: HTML string or RichTextData to create value from.
 -   _$1.range_ `[Range]`: Range to create value from.
 -   _$1.\_\_unstableIsEditableTree_ `[boolean]`:
 
@@ -191,11 +191,11 @@ _Parameters_
 
 _Returns_
 
--   `RichTextFormat|undefined`: Active format object of the specified type, or undefined.
+-   `RichTextFormat | undefined`: Active format object of the specified type, or undefined.
 
 ### getActiveFormats
 
-Gets the all format objects at the start of the selection.
+Gets all format objects at the start of the selection.
 
 _Parameters_
 
@@ -216,7 +216,7 @@ _Parameters_
 
 _Returns_
 
--   `RichTextFormat|void`: Active object, or undefined.
+-   `RichTextFormat | undefined`: Active object, or undefined.
 
 ### getTextContent
 
@@ -266,17 +266,17 @@ Check if the selection of a Rich Text value is collapsed or not. Collapsed means
 
 _Parameters_
 
--   _props_ `RichTextValue`: The rich text value to check.
--   _props.start_ `RichTextValue[ 'start' ]`:
--   _props.end_ `RichTextValue[ 'end' ]`:
+-   _props_ `{ start?: number; end?: number; }`: The rich text value to check.
+-   _props.start_ `number`:
+-   _props.end_ `number`:
 
 _Returns_
 
 -   `boolean | undefined`: True if the selection is collapsed, false if not, undefined if there is no selection.
 
 ### isEmpty
 
-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).
 
 _Parameters_
 
@@ -292,8 +292,8 @@ Combine an array of Rich Text values into one, optionally separated by `separato
 
 _Parameters_
 
--   _values_ `Array<RichTextValue>`: An array of values to join.
--   _separator_ `[string|RichTextValue]`: Separator string or value.
+-   _values_ `Array< RichTextValue >`: An array of values to join.
+-   _separator_ `string | RichTextValue`: Separator string or value.
 
 _Returns_
 
@@ -305,12 +305,12 @@ Registers a new format provided a unique name and an object defining its behavio
 
 _Parameters_
 
--   _name_ `string`: Format name.
--   _settings_ `WPFormat`: Format settings.
+-   _name_ `string`: - Format name.
+-   _settings_ `WPFormat`: - Format settings.
 
 _Returns_
 
--   `WPFormat|undefined`: The format, if it has been successfully registered; otherwise `undefined`.
+-   `WPFormat | undefined`: The format, if it has been successfully registered; otherwise `undefined`.
 
 ### remove
 
@@ -319,8 +319,8 @@ Remove content from a Rich Text value between the given `startIndex` and `endInd
 _Parameters_
 
 -   _value_ `RichTextValue`: Value to modify.
--   _startIndex_ `[number]`: Start index.
--   _endIndex_ `[number]`: End index.
+-   _startIndex_ `number`: Start index.
+-   _endIndex_ `number`: End index.
 
 _Returns_
 
@@ -347,9 +347,9 @@ Search a Rich Text value and replace the match(es) with `replacement`. This is s
 
 _Parameters_
 
--   _value_ `RichTextValue`: 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_ `RichTextValue`: - 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|RichTextValue`: - The match or matches are replaced with the specified or the value returned by the specified function.
 
 _Returns_
 
@@ -379,8 +379,8 @@ Slice a Rich Text value from `startIndex` to `endIndex`. Indices are retrieved f
 _Parameters_
 
 -   _value_ `RichTextValue`: Value to modify.
--   _startIndex_ `[number]`: Start index.
--   _endIndex_ `[number]`: End index.
+-   _startIndex_ `number | undefined`: Start index.
+-   _endIndex_ `number | undefined`: End index.
 
 _Returns_
 
@@ -392,12 +392,17 @@ Split a Rich Text value in two at the given `startIndex` and `endIndex`, or spli
 
 _Parameters_
 
--   _value_ `RichTextValue`:
--   _string_ `[number|string]`: Start index, or string at which to split.
+-   _value_ `RichTextValue`: The rich text value to split.
+-   _value.formats_ `RichTextValue[ 'formats' ]`:
+-   _value.replacements_ `RichTextValue[ 'replacements' ]`:
+-   _value.text_ `RichTextValue[ 'text' ]`:
+-   _value.start_ `RichTextValue[ 'start' ]`:
+-   _value.end_ `RichTextValue[ 'end' ]`:
+-   _string_ `number | string`: Start index, or string at which to split.
 
 _Returns_
 
--   `Array<RichTextValue>|undefined`: An array of new values.
+-   `Array< RichTextValue > | undefined`: An array of new values.
 
 ### store
 
@@ -417,8 +422,8 @@ Toggles a format object to a Rich Text value at the current selection.
 
 _Parameters_
 
--   _value_ `RichTextValue`: Value to modify.
--   _format_ `RichTextFormat`: Format to apply or remove.
+-   _value_ `RichTextValue`: - Value to modify.
+-   _format_ `RichTextFormat`: - Format to apply or remove.
 
 _Returns_
 
@@ -430,9 +435,9 @@ Create an HTML string from a Rich Text value.
 
 _Parameters_
 
--   _$1_ `Object`: Named arguments.
--   _$1.value_ `RichTextValue`: Rich text value.
--   _$1.preserveWhiteSpace_ `[boolean]`: Preserves newlines if true.
+-   _options_ `{ value: RichTextValue; preserveWhiteSpace?: boolean; }`: - Named arguments.
+-   _options.value_ `RichTextValue`: - Rich text value.
+-   _options.preserveWhiteSpace_ `boolean`: - Preserves newlines if true.
 
 _Returns_
 
@@ -448,7 +453,7 @@ _Parameters_
 
 _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`.
 
 ### useAnchor
 

packages/rich-text/src/apply-format.js → packages/rich-text/src/apply-format.ts

@@ -3,11 +3,9 @@
  */
 
 import { normaliseFormats } from './normalise-formats';
+import type { RichTextValue, RichTextFormat } from './types';
 
-/** @typedef {import('./types').RichTextValue} RichTextValue */
-/** @typedef {import('./types').RichTextFormat} RichTextFormat */
-
-function replace( array, index, value ) {
+function replace< T >( array: T[], index: number, value: T ): T[] {
 	array = array.slice();
 	array[ index ] = value;
 	return array;
@@ -18,26 +16,31 @@ function replace( array, index, value ) {
  * given `endIndex`. Indices are retrieved from the selection if none are
  * provided.
  *
- * @param {RichTextValue}  value        Value to modify.
- * @param {RichTextFormat} format       Format to apply.
- * @param {number}         [startIndex] Start index.
- * @param {number}         [endIndex]   End index.
+ * @param value      Value to modify.
+ * @param format     Format to apply.
+ * @param startIndex Start index.
+ * @param endIndex   End index.
  *
- * @return {RichTextValue} A new value with the format applied.
+ * @return A new value with the format applied.
  */
 export function applyFormat(
-	value,
-	format,
-	startIndex = value.start,
-	endIndex = value.end
-) {
+	value: RichTextValue,
+	format: RichTextFormat,
+	startIndex: number | undefined = value.start,
+	endIndex: number | undefined = value.end
+): RichTextValue {
+	// TODO: This is copied from other files, doing the same check.
+	if ( startIndex === undefined || endIndex === undefined ) {
+		return { ...value };
+	}
+
 	const { formats, activeFormats } = value;
 	const newFormats = formats.slice();
 
 	// The selection is collapsed.
 	if ( startIndex === endIndex ) {
 		const startFormat = newFormats[ startIndex ]?.find(
-			( { type } ) => type === format.type
+			( newFormat ) => newFormat?.type === format.type
 		);
 
 		// If the caret is at a format of the same type, expand start and end to
@@ -78,7 +81,7 @@ export function applyFormat(
 		for ( let index = startIndex; index < endIndex; index++ ) {
 			if ( newFormats[ index ] ) {
 				newFormats[ index ] = newFormats[ index ].filter(
-					( { type } ) => type !== format.type
+					( newFormat ) => newFormat?.type !== format.type
 				);
 
 				const length = newFormats[ index ].length;

packages/rich-text/src/concat.js → packages/rich-text/src/concat.ts

@@ -4,19 +4,18 @@
 
 import { normaliseFormats } from './normalise-formats';
 import { create } from './create';
-
-/** @typedef {import('./types').RichTextValue} RichTextValue */
+import type { RichTextValue } from './types';
 
 /**
- * Concats a pair of rich text values. Not that this mutates `a` and does NOT
+ * Concatenates a pair of rich text values. Note that this mutates `a` and does NOT
  * normalise formats!
  *
- * @param {Object} a Value to mutate.
- * @param {Object} b Value to add read from.
+ * @param {RichTextValue} a Value to mutate.
+ * @param {RichTextValue} b Value to add read from.
  *
- * @return {Object} `a`, mutated.
+ * @return {RichTextValue} `a`, mutated.
  */
-export function mergePair( a, b ) {
+export function mergePair( a: RichTextValue, b: RichTextValue ): RichTextValue {
 	a.formats = a.formats.concat( b.formats );
 	a.replacements = a.replacements.concat( b.replacements );
 	a.text += b.text;
@@ -32,6 +31,6 @@ export function mergePair( a, b ) {
  *
  * @return {RichTextValue} A new value combining all given records.
  */
-export function concat( ...values ) {
+export function concat( ...values: RichTextValue[] ): RichTextValue {
 	return normaliseFormats( values.reduce( mergePair, create() ) );
 }

packages/rich-text/src/create-element.ts

@@ -0,0 +1,35 @@
+/**
+ * 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.
+ *
+ * @param options                                   Options object.
+ * @param options.implementation                    The HTML implementation to use.
+ * @param options.implementation.createHTMLDocument
+ * @param html                                      The HTML to parse.
+ *
+ * @return Body element with parsed HTML.
+ */
+export function createElement(
+	{
+		implementation,
+	}: {
+		implementation: { createHTMLDocument: ( title: string ) => Document };
+	},
+	html: string
+): HTMLElement {
+	// Because `createHTMLDocument` is an expensive operation, and with this
+	// function being internal to `rich-text` (full control in avoiding a risk
+	// of asynchronous operations on the shared reference), a single document
+	// is reused and reset for each call to the function.
+	if ( ! ( createElement as any ).body ) {
+		( createElement as any ).body =
+			implementation.createHTMLDocument( '' ).body;
+	}
+
+	( createElement as any ).body.innerHTML = html;
+
+	return ( createElement as any ).body;
+}