Publish rich-text package build types (#49651)

* Publish rich text build types, based on jsdoc types. * Move some rich-text types from components to rich-text. --------- Co-authored-by: Marin Atanasov <[email protected]>
WordPress · Apr 28, 2023 · 36e3b33 · 36e3b33
1 parent b554ae4
commit 36e3b33
Show file tree

Hide file tree

Showing 42 changed files with 144 additions and 96 deletions.
diff --git a/packages/block-editor/tsconfig.json b/packages/block-editor/tsconfig.json
@@ -24,6 +24,7 @@
 		{ "path": "../is-shallow-equal" },
 		{ "path": "../keycodes" },
 		{ "path": "../notices" },
+		{ "path": "../rich-text" },
 		{ "path": "../style-engine" },
 		{ "path": "../token-list" },
 		{ "path": "../url" },

diff --git a/packages/block-library/tsconfig.json b/packages/block-library/tsconfig.json
@@ -29,6 +29,7 @@
 		{ "path": "../notices" },
 		{ "path": "../keycodes" },
 		{ "path": "../primitives" },
+		{ "path": "../rich-text" },
 		{ "path": "../url" },
 		{ "path": "../wordcount" }
 	],

diff --git a/packages/components/CHANGELOG.md b/packages/components/CHANGELOG.md
@@ -5,6 +5,7 @@
 ### Internal
 
 -   `NavigableContainer`: Convert to TypeScript ([#49377](https://github.com/WordPress/gutenberg/pull/49377)).
+-   Move rich-text related types to the rich-text package ([#49651](https://github.com/WordPress/gutenberg/pull/49651)).
 
 ### Documentation
 

diff --git a/packages/components/src/autocomplete/autocompleter-ui.tsx b/packages/components/src/autocomplete/autocompleter-ui.tsx
@@ -12,8 +12,6 @@ import {
 	useEffect,
 	useState,
 } from '@wordpress/element';
-// Error expected because `@wordpress/rich-text` is not yet fully typed.
-// @ts-expect-error
 import { useAnchor } from '@wordpress/rich-text';
 import { useMergeRefs, useRefEffect } from '@wordpress/compose';
 

diff --git a/packages/components/src/autocomplete/index.tsx b/packages/components/src/autocomplete/index.tsx
@@ -26,8 +26,6 @@ import {
 	insert,
 	isCollapsed,
 	getTextContent,
-	// Error expected because `@wordpress/rich-text` is not yet fully typed.
-	// @ts-expect-error
 } from '@wordpress/rich-text';
 import { speak } from '@wordpress/a11y';
 
@@ -241,6 +239,7 @@ export function useAutocomplete( {
 		if ( isCollapsed( record ) ) {
 			return getTextContent( slice( record, 0 ) );
 		}
+		return '';
 	}, [ record ] );
 
 	useEffect( () => {

diff --git a/packages/components/src/autocomplete/types.ts b/packages/components/src/autocomplete/types.ts
@@ -2,6 +2,8 @@
  * WordPress dependencies
  */
 import type { WPElement } from '@wordpress/element';
+import type { RichTextValue } from '@wordpress/rich-text';
+
 /**
  * Internal dependencies
  */
@@ -157,24 +159,6 @@ export type CancelablePromise< T = void > = Promise< T > & {
 	canceled?: boolean;
 };
 
-/**
- * When `@wordpress/rich-text` is fully typed, the following
- * types should be moved to and imported from there
- *
- * @see /packages/rich-text/src/create.js
- */
-type RichTextFormat = {
-	type: string;
-};
-type RichTextFormatList = Array< RichTextFormat >;
-type RichTextValue = {
-	text: string;
-	formats?: Array< RichTextFormatList >;
-	replacements?: Array< RichTextFormat >;
-	start: number | undefined;
-	end: number | undefined;
-};
-
 export type UseAutocompleteProps = {
 	/**
 	 * The rich text value object the autocompleter is being applied to.
@@ -187,7 +171,7 @@ export type UseAutocompleteProps = {
 	 * A function to be called when an option is selected to insert into the
 	 * existing text.
 	 */
-	onChange: ( value: string ) => void;
+	onChange: ( value: RichTextValue ) => void;
 	/**
 	 * A function to be called when an option is selected to replace the
 	 * existing text.

diff --git a/packages/components/tsconfig.json b/packages/components/tsconfig.json
@@ -34,6 +34,7 @@
 		{ "path": "../primitives" },
 		{ "path": "../private-apis" },
 		{ "path": "../react-i18n" },
+		{ "path": "../rich-text" },
 		{ "path": "../warning" }
 	],
 	"include": [ "src/**/*" ],

diff --git a/packages/element/src/react.js b/packages/element/src/react.js
@@ -52,6 +52,13 @@ import {
  * @typedef {import('react').SyntheticEvent} WPSyntheticEvent
  */
 
+/**
+ * Object containing a React synthetic event.
+ *
+ * @template T
+ * @typedef {import('react').RefObject<T>} RefObject<T>
+ */
+
 /**
  * Object that provides utilities for dealing with React children.
  */

diff --git a/packages/rich-text/README.md b/packages/rich-text/README.md
@@ -269,11 +269,13 @@ Check if the selection of a Rich Text value is collapsed or not. Collapsed means
 
 _Parameters_
 
--   _value_ `RichTextValue`: The rich text value to check.
+-   _props_ `RichTextValue`: The rich text value to check.
+-   _props.start_ `RichTextValue[ 'start' ]`:
+-   _props.end_ `RichTextValue[ 'end' ]`:
 
 _Returns_
 
--   `boolean|undefined`: True if the selection is collapsed, false if not, undefined if there is no selection.
+-   `boolean | undefined`: True if the selection is collapsed, false if not, undefined if there is no selection.
 
 ### isEmpty
 
@@ -356,6 +358,10 @@ _Returns_
 
 -   `RichTextValue`: A new value with replacements applied.
 
+### RichTextValue
+
+An object which represents a formatted string. See main `@wordpress/rich-text` documentation for more information.
+
 ### slice
 
 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`.
@@ -433,7 +439,7 @@ _Parameters_
 
 _Returns_
 
--   `RichTextFormatType|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
 
@@ -443,7 +449,7 @@ _Parameters_
 
 -   _$1_ `Object`: Named parameters.
 -   _$1.editableContentElement_ `HTMLElement|null`: The element containing the editable content.
--   _$1.settings_ `RichTextFormatType`: The format type's settings.
+-   _$1.settings_ `WPFormat=`: The format type's settings.
 
 _Returns_
 
@@ -458,7 +464,7 @@ _Parameters_
 -   _$1_ `Object`: Named parameters.
 -   _$1.ref_ `RefObject<HTMLElement>`: React ref of the element containing the editable content.
 -   _$1.value_ `RichTextValue`: Value to check for selection.
--   _$1.settings_ `RichTextFormatType`: The format type's settings.
+-   _$1.settings_ `WPFormat`: The format type's settings.
 
 _Returns_
 

diff --git a/packages/rich-text/package.json b/packages/rich-text/package.json
@@ -28,6 +28,7 @@
 		"src/**/*.scss",
 		"{src,build,build-module}/{index.js,store/index.js}"
 	],
+	"types": "build-types",
 	"dependencies": {
 		"@babel/runtime": "^7.16.0",
 		"@wordpress/a11y": "file:../a11y",

diff --git a/packages/rich-text/src/apply-format.js b/packages/rich-text/src/apply-format.js
@@ -4,8 +4,8 @@
 
 import { normaliseFormats } from './normalise-formats';
 
-/** @typedef {import('./create').RichTextValue} RichTextValue */
-/** @typedef {import('./create').RichTextFormat} RichTextFormat */
+/** @typedef {import('./types').RichTextValue} RichTextValue */
+/** @typedef {import('./types').RichTextFormat} RichTextFormat */
 
 function replace( array, index, value ) {
 	array = array.slice();

diff --git a/packages/rich-text/src/component/use-anchor-ref.js b/packages/rich-text/src/component/use-anchor-ref.js
@@ -9,9 +9,12 @@ import deprecated from '@wordpress/deprecated';
  */
 import { getActiveFormat } from '../get-active-format';
 
-/** @typedef {import('@wordpress/element').RefObject} RefObject */
-/** @typedef {import('../register-format-type').RichTextFormatType} RichTextFormatType */
-/** @typedef {import('../create').RichTextValue} RichTextValue */
+/**
+ * @template T
+ * @typedef {import('@wordpress/element').RefObject<T>} RefObject<T>
+ */
+/** @typedef {import('../register-format-type').WPFormat} WPFormat */
+/** @typedef {import('../types').RichTextValue} RichTextValue */
 
 /**
  * This hook, to be used in a format type's Edit component, returns the active
@@ -23,7 +26,7 @@ import { getActiveFormat } from '../get-active-format';
  * @param {RefObject<HTMLElement>} $1.ref      React ref of the element
  *                                             containing  the editable content.
  * @param {RichTextValue}          $1.value    Value to check for selection.
- * @param {RichTextFormatType}     $1.settings The format type's settings.
+ * @param {WPFormat}               $1.settings The format type's settings.
  *
  * @return {Element|Range} The active element or selection range.
  */

diff --git a/packages/rich-text/src/component/use-anchor.js b/packages/rich-text/src/component/use-anchor.js
@@ -3,8 +3,8 @@
  */
 import { useState, useLayoutEffect } from '@wordpress/element';
 
-/** @typedef {import('../register-format-type').RichTextFormatType} RichTextFormatType */
-/** @typedef {import('../create').RichTextValue} RichTextValue */
+/** @typedef {import('../register-format-type').WPFormat} WPFormat */
+/** @typedef {import('../types').RichTextValue} RichTextValue */
 
 /**
  * Given a range and a format tag name and class name, returns the closest
@@ -50,8 +50,8 @@ function getFormatElement( range, editableContentElement, tagName, className ) {
 
 /**
  * @typedef {Object} VirtualAnchorElement
- * @property {Function} getBoundingClientRect A function returning a DOMRect
- * @property {Document} ownerDocument         The element's ownerDocument
+ * @property {() => DOMRect} getBoundingClientRect A function returning a DOMRect
+ * @property {Document}      ownerDocument         The element's ownerDocument
  */
 
 /**
@@ -117,10 +117,10 @@ function getAnchor( editableContentElement, tagName, className ) {
  * 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.
  *
- * @param {Object}             $1                        Named parameters.
- * @param {HTMLElement|null}   $1.editableContentElement The element containing
- *                                                       the editable content.
- * @param {RichTextFormatType} $1.settings               The format type's settings.
+ * @param {Object}           $1                        Named parameters.
+ * @param {HTMLElement|null} $1.editableContentElement The element containing
+ *                                                     the editable content.
+ * @param {WPFormat=}        $1.settings               The format type's settings.
  * @return {Element|VirtualAnchorElement|undefined|null} The active element or selection range.
  */
 export function useAnchor( { editableContentElement, settings = {} } ) {

diff --git a/packages/rich-text/src/concat.js b/packages/rich-text/src/concat.js
@@ -5,7 +5,7 @@
 import { normaliseFormats } from './normalise-formats';
 import { create } from './create';
 
-/** @typedef {import('./create').RichTextValue} RichTextValue */
+/** @typedef {import('./types').RichTextValue} RichTextValue */
 
 /**
  * Concats a pair of rich text values. Not that this mutates `a` and does NOT

diff --git a/packages/rich-text/src/create.js b/packages/rich-text/src/create.js
@@ -15,25 +15,7 @@ import {
 	ZWNBSP,
 } from './special-characters';
 
-/**
- * @typedef {Object} RichTextFormat
- *
- * @property {string} type Format type.
- */
-
-/**
- * @typedef {Array<RichTextFormat>} RichTextFormatList
- */
-
-/**
- * @typedef {Object} RichTextValue
- *
- * @property {string}                    text         Text.
- * @property {Array<RichTextFormatList>} formats      Formats.
- * @property {Array<RichTextFormat>}     replacements Replacements.
- * @property {number|undefined}          start        Selection start.
- * @property {number|undefined}          end          Selection end.
- */
+/** @typedef {import('./types').RichTextValue} RichTextValue */
 
 function createEmptyValue() {
 	return {

diff --git a/packages/rich-text/src/get-active-format.js b/packages/rich-text/src/get-active-format.js
@@ -3,8 +3,8 @@
  */
 import { getActiveFormats } from './get-active-formats';
 
-/** @typedef {import('./create').RichTextValue} RichTextValue */
-/** @typedef {import('./create').RichTextFormat} RichTextFormat */
+/** @typedef {import('./types').RichTextValue} RichTextValue */
+/** @typedef {import('./types').RichTextFormat} RichTextFormat */
 
 /**
  * Gets the format object by type at the start of the selection. This can be

diff --git a/packages/rich-text/src/get-active-formats.js b/packages/rich-text/src/get-active-formats.js
@@ -1,5 +1,5 @@
-/** @typedef {import('./create').RichTextValue} RichTextValue */
-/** @typedef {import('./create').RichTextFormatList} RichTextFormatList */
+/** @typedef {import('./types').RichTextValue} RichTextValue */
+/** @typedef {import('./types').RichTextFormatList} RichTextFormatList */
 
 /**
  * Internal dependencies

diff --git a/packages/rich-text/src/get-active-object.js b/packages/rich-text/src/get-active-object.js
@@ -4,8 +4,8 @@
 
 import { OBJECT_REPLACEMENT_CHARACTER } from './special-characters';
 
-/** @typedef {import('./create').RichTextValue} RichTextValue */
-/** @typedef {import('./create').RichTextFormat} RichTextFormat */
+/** @typedef {import('./types').RichTextValue} RichTextValue */
+/** @typedef {import('./types').RichTextFormat} RichTextFormat */
 
 /**
  * Gets the active object, if there is any.

diff --git a/packages/rich-text/src/get-text-content.js b/packages/rich-text/src/get-text-content.js
@@ -6,7 +6,7 @@ import {
 	LINE_SEPARATOR,
 } from './special-characters';
 
-/** @typedef {import('./create').RichTextValue} RichTextValue */
+/** @typedef {import('./types').RichTextValue} RichTextValue */
 
 const pattern = new RegExp(
 	`[${ OBJECT_REPLACEMENT_CHARACTER }${ LINE_SEPARATOR }]`,

diff --git a/packages/rich-text/src/index.js b/packages/rich-text/src/index.js
@@ -33,3 +33,9 @@ export {
 	useRichText as __unstableUseRichText,
 } from './component';
 export { default as __unstableFormatEdit } from './component/format-edit';
+
+/**
+ * An object which represents a formatted string. See main `@wordpress/rich-text`
+ * documentation for more information.
+ */
+export { RichTextValue } from './types';
diff --git a/packages/rich-text/src/insert-line-separator.js b/packages/rich-text/src/insert-line-separator.js
@@ -5,7 +5,7 @@
 import { insert } from './insert';
 import { LINE_SEPARATOR } from './special-characters';
 
-/** @typedef {import('./create').RichTextValue} RichTextValue */
+/** @typedef {import('./types').RichTextValue} RichTextValue */
 
 /**
  * Insert a line break character into a Rich Text value at the given

diff --git a/packages/rich-text/src/insert-object.js b/packages/rich-text/src/insert-object.js
@@ -5,8 +5,8 @@
 import { insert } from './insert';
 import { OBJECT_REPLACEMENT_CHARACTER } from './special-characters';
 
-/** @typedef {import('./create').RichTextValue} RichTextValue */
-/** @typedef {import('./create').RichTextFormat} RichTextFormat */
+/** @typedef {import('./types').RichTextValue} RichTextValue */
+/** @typedef {import('./types').RichTextFormat} RichTextFormat */
 
 /**
  * Insert a format as an object into a Rich Text value at the given

diff --git a/packages/rich-text/src/insert.js b/packages/rich-text/src/insert.js
@@ -5,7 +5,7 @@
 import { create } from './create';
 import { normaliseFormats } from './normalise-formats';
 
-/** @typedef {import('./create').RichTextValue} RichTextValue */
+/** @typedef {import('./types').RichTextValue} RichTextValue */
 
 /**
  * Insert a Rich Text value, an HTML string, or a plain text string, into a

diff --git a/packages/rich-text/src/is-collapsed.js → packages/rich-text/src/is-collapsed.ts b/packages/rich-text/src/is-collapsed.js → packages/rich-text/src/is-collapsed.ts
@@ -1,17 +1,23 @@
-/** @typedef {import('./create').RichTextValue} RichTextValue */
+/**
+ * Internal dependencies
+ */
+import type { RichTextValue } from './types';
 
 /**
  * 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()`.
  *
- * @param {RichTextValue} value The rich text value to check.
- *
- * @return {boolean|undefined} 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
+ * @return True if the selection is collapsed, false if not, undefined if there is no selection.
  */
-export function isCollapsed( { start, end } ) {
+export function isCollapsed( {
+	start,
+	end,
+}: RichTextValue ): boolean | undefined {
 	if ( start === undefined || end === undefined ) {
 		return;
 	}