@wordpress/annotations 3.43.1-next.v.202604091042.0 → 3.44.0

package/src/store/{reducer.js → reducer.ts}

@@ -1,13 +1,26 @@
+/**
+ * Internal dependencies
+ */
+import type {
+	AnnotationAction,
+	AnnotationsState,
+	Annotation,
+	AnnotationRange,
+} from '../types';
+
 /**
  * Filters an array based on the predicate, but keeps the reference the same if
  * the array hasn't changed.
  *
- * @param {Array}    collection The collection to filter.
- * @param {Function} predicate  Function that determines if the item should stay
- *                              in the array.
- * @return {Array} Filtered array.
+ * @param collection The collection to filter.
+ * @param predicate  Function that determines if the item should stay
+ *                   in the array.
+ * @return Filtered array.
  */
-function filterWithReference( collection, predicate ) {
+function filterWithReference< T >(
+	collection: T[],
+	predicate: ( item: T ) => boolean
+): T[] {
 	const filteredCollection = collection.filter( predicate );
 
 	return collection.length === filteredCollection.length
@@ -19,46 +32,57 @@ function filterWithReference( collection, predicate ) {
  * Creates a new object with the same keys, but with `callback()` called as
  * a transformer function on each of the values.
  *
- * @param {Object}   obj      The object to transform.
- * @param {Function} callback The function to transform each object value.
- * @return {Array} Transformed object.
+ * @param obj      The object to transform.
+ * @param callback The function to transform each object value.
+ * @return Transformed object.
  */
-const mapValues = ( obj, callback ) =>
-	Object.entries( obj ).reduce(
-		( acc, [ key, value ] ) => ( {
+const mapValues = < T, U >(
+	obj: Partial< Record< string, T > >,
+	callback: ( value: T ) => U
+): Partial< Record< string, U > > =>
+	Object.entries( obj ).reduce( ( acc, [ key, value ] ) => {
+		if ( value === undefined ) {
+			return acc;
+		}
+		return {
 			...acc,
 			[ key ]: callback( value ),
-		} ),
-		{}
-	);
+		};
+	}, {} );
 
 /**
  * Verifies whether the given annotations is a valid annotation.
  *
- * @param {Object} annotation The annotation to verify.
- * @return {boolean} Whether the given annotation is valid.
+ * @param annotation       The annotation to verify.
+ * @param annotation.range The range property of the annotation.
+ * @return Whether the given annotation is valid.
  */
-function isValidAnnotationRange( annotation ) {
-	return (
-		typeof annotation.start === 'number' &&
-		typeof annotation.end === 'number' &&
-		annotation.start <= annotation.end
+function isValidAnnotationRange( annotation: {
+	range?: AnnotationRange | null;
+} ): boolean {
+	return Boolean(
+		annotation.range &&
+			typeof annotation.range.start === 'number' &&
+			typeof annotation.range.end === 'number' &&
+			annotation.range.start <= annotation.range.end
 	);
 }
 
 /**
  * Reducer managing annotations.
  *
- * @param {Object} state  The annotations currently shown in the editor.
- * @param {Object} action Dispatched action.
- *
- * @return {Array} Updated state.
+ * @param state  The annotations currently shown in the editor.
+ * @param action Dispatched action.
+ * @return Updated state.
  */
-export function annotations( state = {}, action ) {
+export function annotations(
+	state: AnnotationsState = {},
+	action: AnnotationAction
+): AnnotationsState {
 	switch ( action.type ) {
 		case 'ANNOTATION_ADD':
 			const blockClientId = action.blockClientId;
-			const newAnnotation = {
+			const newAnnotation: Annotation = {
 				id: action.id,
 				blockClientId,
 				richTextIdentifier: action.richTextIdentifier,
@@ -69,7 +93,7 @@ export function annotations( state = {}, action ) {
 
 			if (
 				newAnnotation.selector === 'range' &&
-				! isValidAnnotationRange( newAnnotation.range )
+				! isValidAnnotationRange( newAnnotation )
 			) {
 				return state;
 			}
@@ -85,21 +109,21 @@ export function annotations( state = {}, action ) {
 			};
 
 		case 'ANNOTATION_REMOVE':
-			return mapValues( state, ( annotationsForBlock ) => {
+			return mapValues( state, ( annotationsForBlock: Annotation[] ) => {
 				return filterWithReference(
 					annotationsForBlock,
-					( annotation ) => {
+					( annotation: Annotation ) => {
 						return annotation.id !== action.annotationId;
 					}
 				);
 			} );
 
 		case 'ANNOTATION_UPDATE_RANGE':
-			return mapValues( state, ( annotationsForBlock ) => {
+			return mapValues( state, ( annotationsForBlock: Annotation[] ) => {
 				let hasChangedRange = false;
 
 				const newAnnotations = annotationsForBlock.map(
-					( annotation ) => {
+					( annotation: Annotation ) => {
 						if ( annotation.id === action.annotationId ) {
 							hasChangedRange = true;
 							return {
@@ -119,10 +143,10 @@ export function annotations( state = {}, action ) {
 			} );
 
 		case 'ANNOTATION_REMOVE_SOURCE':
-			return mapValues( state, ( annotationsForBlock ) => {
+			return mapValues( state, ( annotationsForBlock: Annotation[] ) => {
 				return filterWithReference(
 					annotationsForBlock,
-					( annotation ) => {
+					( annotation: Annotation ) => {
 						return annotation.source !== action.source;
 					}
 				);

package/src/store/{selectors.js → selectors.ts}

@@ -3,38 +3,42 @@
  */
 import { createSelector } from '@wordpress/data';
 
+/**
+ * Internal dependencies
+ */
+import type { AnnotationsState, Annotation } from '../types';
+
 /**
  * Shared reference to an empty array for cases where it is important to avoid
  * returning a new array reference on every invocation, as in a connected or
  * other pure component which performs `shouldComponentUpdate` check on props.
  * This should be used as a last resort, since the normalized data should be
  * maintained by the reducer result in state.
- *
- * @type {Array}
  */
-const EMPTY_ARRAY = [];
+const EMPTY_ARRAY: Annotation[] = [];
 
 /**
  * Returns the annotations for a specific client ID.
  *
- * @param {Object} state    Editor state.
- * @param {string} clientId The ID of the block to get the annotations for.
- *
- * @return {Array} The annotations applicable to this block.
+ * @param state         Editor state.
+ * @param blockClientId The ID of the block to get the annotations for.
+ * @return The annotations applicable to this block.
  */
 export const __experimentalGetAnnotationsForBlock = createSelector(
-	( state, blockClientId ) => {
+	( state: AnnotationsState, blockClientId: string ): Annotation[] => {
 		return ( state?.[ blockClientId ] ?? [] ).filter( ( annotation ) => {
 			return annotation.selector === 'block';
 		} );
 	},
-	( state, blockClientId ) => [ state?.[ blockClientId ] ?? EMPTY_ARRAY ]
+	( state: AnnotationsState, blockClientId: string ) => [
+		state?.[ blockClientId ] ?? EMPTY_ARRAY,
+	]
 );
 
 export function __experimentalGetAllAnnotationsForBlock(
-	state,
-	blockClientId
-) {
+	state: AnnotationsState,
+	blockClientId: string
+): Annotation[] {
 	return state?.[ blockClientId ] ?? EMPTY_ARRAY;
 }
 
@@ -45,13 +49,17 @@ export function __experimentalGetAllAnnotationsForBlock(
  * a block might have multiple `RichText` components. This does mean that every
  * block needs to implement annotations itself.
  *
- * @param {Object} state              Editor state.
- * @param {string} blockClientId      The client ID for the block.
- * @param {string} richTextIdentifier Unique identifier that identifies the given RichText.
- * @return {Array} All the annotations relevant for the `RichText`.
+ * @param state              Editor state.
+ * @param blockClientId      The client ID for the block.
+ * @param richTextIdentifier Unique identifier that identifies the given RichText.
+ * @return All the annotations relevant for the `RichText`.
  */
 export const __experimentalGetAnnotationsForRichText = createSelector(
-	( state, blockClientId, richTextIdentifier ) => {
+	(
+		state: AnnotationsState,
+		blockClientId: string,
+		richTextIdentifier: string
+	): Annotation[] => {
 		return ( state?.[ blockClientId ] ?? [] )
 			.filter( ( annotation ) => {
 				return (
@@ -68,15 +76,21 @@ export const __experimentalGetAnnotationsForRichText = createSelector(
 				};
 			} );
 	},
-	( state, blockClientId ) => [ state?.[ blockClientId ] ?? EMPTY_ARRAY ]
+	( state: AnnotationsState, blockClientId: string ) => [
+		state?.[ blockClientId ] ?? EMPTY_ARRAY,
+	]
 );
 
 /**
  * Returns all annotations in the editor state.
  *
- * @param {Object} state Editor state.
- * @return {Array} All annotations currently applied.
+ * @param state Editor state.
+ * @return All annotations currently applied.
  */
-export function __experimentalGetAnnotations( state ) {
-	return Object.values( state ).flat();
+export function __experimentalGetAnnotations(
+	state: AnnotationsState
+): Annotation[] {
+	return Object.values( state )
+		.filter( ( arr ): arr is Annotation[] => Boolean( arr ) )
+		.flat();
 }

package/src/store/test/{reducer.js → reducer.ts}

@@ -2,12 +2,13 @@
  * Internal dependencies
  */
 import { annotations } from '../reducer';
+import type { AnnotationAction, AnnotationsState } from '../../types';
 
 describe( 'annotations', () => {
-	const initialState = {};
+	const initialState: AnnotationsState = {};
 
 	it( 'returns all annotations and annotation IDs per block', () => {
-		const state = annotations( undefined, {} );
+		const state = annotations( undefined, {} as AnnotationAction );
 
 		expect( state ).toEqual( initialState );
 	} );
@@ -63,14 +64,14 @@ describe( 'annotations', () => {
 			blockClientId: 'blockClientId',
 			richTextIdentifier: 'identifier',
 			source: 'default',
-			selector: 'block',
+			selector: 'block' as const,
 		};
 		const annotation2 = {
 			id: 'annotationId2',
 			blockClientId: 'blockClientId2',
 			richTextIdentifier: 'identifier2',
 			source: 'other-source',
-			selector: 'block',
+			selector: 'block' as const,
 		};
 		const state = annotations(
 			{
@@ -129,7 +130,7 @@ describe( 'annotations', () => {
 						blockClientId: 'blockClientId',
 						richTextIdentifier: 'identifier',
 						source: 'default',
-						selector: 'range',
+						selector: 'range' as const,
 						range: {
 							start: 0,
 							end: 100,
@@ -165,6 +166,9 @@ describe( 'annotations', () => {
 	it( 'rejects invalid annotations', () => {
 		let state = annotations( undefined, {
 			type: 'ANNOTATION_ADD',
+			id: 'test1',
+			blockClientId: 'blockClientId',
+			richTextIdentifier: 'identifier',
 			source: 'default',
 			selector: 'range',
 			range: {
@@ -174,19 +178,27 @@ describe( 'annotations', () => {
 		} );
 		state = annotations( state, {
 			type: 'ANNOTATION_ADD',
+			id: 'test2',
+			blockClientId: 'blockClientId',
+			richTextIdentifier: 'identifier',
 			source: 'default',
 			selector: 'range',
 			range: {
+				// @ts-expect-error Testing invalid input
 				start: 'not a number',
 				end: 100,
 			},
 		} );
 		state = annotations( state, {
 			type: 'ANNOTATION_ADD',
+			id: 'test3',
+			blockClientId: 'blockClientId',
+			richTextIdentifier: 'identifier',
 			source: 'default',
 			selector: 'range',
 			range: {
 				start: 100,
+				// @ts-expect-error Testing invalid input
 				end: 'not a number',
 			},
 		} );

package/src/types.ts

@@ -0,0 +1,133 @@
+/**
+ * Represents a range in text content.
+ */
+export interface AnnotationRange {
+	/** The offset where the annotation should start. */
+	start: number;
+	/** The offset where the annotation should end. */
+	end: number;
+}
+
+/**
+ * Represents an annotation selector type.
+ */
+export type AnnotationSelector = 'range' | 'block';
+
+/**
+ * Base annotation interface.
+ */
+export interface Annotation {
+	/** Unique identifier for the annotation. */
+	id: string;
+	/** The block client ID this annotation applies to. */
+	blockClientId: string;
+	/** The source that created this annotation. */
+	source: string;
+	/** The type of selector used for this annotation. */
+	selector: AnnotationSelector;
+	/** Rich text identifier for range annotations. */
+	richTextIdentifier?: string | null;
+	/** Range for range-based annotations. */
+	range?: AnnotationRange | null;
+	/** Start position for annotations returned from selectors. */
+	start?: number;
+	/** End position for annotations returned from selectors. */
+	end?: number;
+}
+
+/**
+ * Parameters for adding an annotation.
+ */
+export interface AddAnnotationParameters {
+	/** The blockClientId to add the annotation to. */
+	blockClientId: string;
+	/** Identifier for the RichText instance the annotation applies to. */
+	richTextIdentifier?: string | null;
+	/** The range at which to apply this annotation. */
+	range?: AnnotationRange | null;
+	/** The way to apply this annotation. */
+	selector?: AnnotationSelector;
+	/** The source that added the annotation. */
+	source?: string;
+	/** The ID the annotation should have. Generates a UUID by default. */
+	id?: string;
+}
+
+/**
+ * Store state interface.
+ */
+export type AnnotationsState = Partial< Record< string, Annotation[] > >;
+
+/**
+ * Action types.
+ */
+export type AnnotationAction =
+	| {
+			type: 'ANNOTATION_ADD';
+			id: string;
+			blockClientId: string;
+			richTextIdentifier: string | null;
+			source: string;
+			selector: AnnotationSelector;
+			range?: AnnotationRange;
+	  }
+	| {
+			type: 'ANNOTATION_REMOVE';
+			annotationId: string;
+	  }
+	| {
+			type: 'ANNOTATION_UPDATE_RANGE';
+			annotationId: string;
+			start: number;
+			end: number;
+	  }
+	| {
+			type: 'ANNOTATION_REMOVE_SOURCE';
+			source: string;
+	  };
+
+/**
+ * Format registration interface for annotations.
+ */
+export interface AnnotationFormat {
+	name: string;
+	title: string;
+	tagName: string;
+	className: string;
+	attributes: {
+		className: string;
+		id: string;
+	};
+	interactive: boolean;
+	object: boolean;
+	edit: () => null;
+	__experimentalGetPropsForEditableTreePreparation: (
+		select: any,
+		props: {
+			richTextIdentifier: string;
+			blockClientId: string;
+		}
+	) => {
+		annotations: Annotation[];
+	};
+	__experimentalCreatePrepareEditableTree: ( props: {
+		annotations: Annotation[];
+	} ) => ( formats: any[], text: string ) => any[];
+	__experimentalGetPropsForEditableTreeChangeHandler: ( dispatch: any ) => {
+		removeAnnotation: ( annotationId: string ) => void;
+		updateAnnotationRange: (
+			annotationId: string,
+			start: number,
+			end: number
+		) => void;
+	};
+	__experimentalCreateOnChangeEditableValue: ( props: {
+		removeAnnotation: ( annotationId: string ) => void;
+		updateAnnotationRange: (
+			annotationId: string,
+			start: number,
+			end: number
+		) => void;
+		annotations: Annotation[];
+	} ) => ( formats: any[] ) => void;
+}

package/src/block/index.js

@@ -1,40 +0,0 @@
-/**
- * WordPress dependencies
- */
-import { addFilter } from '@wordpress/hooks';
-import { withSelect } from '@wordpress/data';
-
-/**
- * Internal dependencies
- */
-import { STORE_NAME } from '../store/constants';
-/**
- * Adds annotation className to the block-list-block component.
- *
- * @param {Object} OriginalComponent The original BlockListBlock component.
- * @return {Object} The enhanced component.
- */
-const addAnnotationClassName = ( OriginalComponent ) => {
-	return withSelect( ( select, { clientId, className } ) => {
-		const annotations =
-			select( STORE_NAME ).__experimentalGetAnnotationsForBlock(
-				clientId
-			);
-
-		return {
-			className: annotations
-				.map( ( annotation ) => {
-					return 'is-annotated-by-' + annotation.source;
-				} )
-				.concat( className )
-				.filter( Boolean )
-				.join( ' ' ),
-		};
-	} )( OriginalComponent );
-};
-
-addFilter(
-	'editor.BlockListBlock',
-	'core/annotations',
-	addAnnotationClassName
-);

package/src/store/actions.js

@@ -1,105 +0,0 @@
-/**
- * External dependencies
- */
-import { v4 as uuid } from 'uuid';
-
-/**
- * @typedef WPAnnotationRange
- *
- * @property {number} start The offset where the annotation should start.
- * @property {number} end   The offset where the annotation should end.
- */
-
-/**
- * Adds an annotation to a block.
- *
- * The `block` attribute refers to a block ID that needs to be annotated.
- * `isBlockAnnotation` controls whether or not the annotation is a block
- * annotation. The `source` is the source of the annotation, this will be used
- * to identity groups of annotations.
- *
- * The `range` property is only relevant if the selector is 'range'.
- *
- * @param {Object}            annotation                    The annotation to add.
- * @param {string}            annotation.blockClientId      The blockClientId to add the annotation to.
- * @param {string}            annotation.richTextIdentifier Identifier for the RichText instance the annotation applies to.
- * @param {WPAnnotationRange} annotation.range              The range at which to apply this annotation.
- * @param {string}            [annotation.selector="range"] The way to apply this annotation.
- * @param {string}            [annotation.source="default"] The source that added the annotation.
- * @param {string}            [annotation.id]               The ID the annotation should have. Generates a UUID by default.
- *
- * @return {Object} Action object.
- */
-export function __experimentalAddAnnotation( {
-	blockClientId,
-	richTextIdentifier = null,
-	range = null,
-	selector = 'range',
-	source = 'default',
-	id = uuid(),
-} ) {
-	const action = {
-		type: 'ANNOTATION_ADD',
-		id,
-		blockClientId,
-		richTextIdentifier,
-		source,
-		selector,
-	};
-
-	if ( selector === 'range' ) {
-		action.range = range;
-	}
-
-	return action;
-}
-
-/**
- * Removes an annotation with a specific ID.
- *
- * @param {string} annotationId The annotation to remove.
- *
- * @return {Object} Action object.
- */
-export function __experimentalRemoveAnnotation( annotationId ) {
-	return {
-		type: 'ANNOTATION_REMOVE',
-		annotationId,
-	};
-}
-
-/**
- * Updates the range of an annotation.
- *
- * @param {string} annotationId ID of the annotation to update.
- * @param {number} start        The start of the new range.
- * @param {number} end          The end of the new range.
- *
- * @return {Object} Action object.
- */
-export function __experimentalUpdateAnnotationRange(
-	annotationId,
-	start,
-	end
-) {
-	return {
-		type: 'ANNOTATION_UPDATE_RANGE',
-		annotationId,
-		start,
-		end,
-	};
-}
-
-/**
- * Removes all annotations of a specific source.
- *
- * @param {string} source The source to remove.
- *
- * @return {Object} Action object.
- */
-export function __experimentalRemoveAnnotationsBySource( source ) {
-	return {
-		type: 'ANNOTATION_REMOVE_SOURCE',
-		source,
-	};
-}