@wordpress/annotations 3.43.0 → 3.44.0

package/build-types/types.d.ts

@@ -0,0 +1,113 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=types.d.ts.map

package/build-types/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/annotations",
-	"version": "3.43.0",
+	"version": "3.44.0",
 	"description": "Annotate content in the Gutenberg editor.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -33,6 +33,7 @@
 	"module": "build-module/index.mjs",
 	"exports": {
 		".": {
+			"types": "./build-types/index.d.ts",
 			"import": "./build-module/index.mjs",
 			"require": "./build/index.cjs"
 		},
@@ -40,11 +41,12 @@
 	},
 	"react-native": "src/index",
 	"wpScript": true,
+	"types": "build-types/index.d.ts",
 	"dependencies": {
-		"@wordpress/data": "^10.43.0",
-		"@wordpress/hooks": "^4.43.0",
-		"@wordpress/i18n": "^6.16.0",
-		"@wordpress/rich-text": "^7.43.0",
+		"@wordpress/data": "^10.44.0",
+		"@wordpress/hooks": "^4.44.0",
+		"@wordpress/i18n": "^6.17.0",
+		"@wordpress/rich-text": "^7.44.0",
 		"uuid": "^9.0.1"
 	},
 	"peerDependencies": {
@@ -53,5 +55,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "2cea90674d11aa521ec3f71652fb3a6a4c383969"
+	"gitHead": "b862d8c84121a47bbeff882f6c87e61681ce2e0d"
 }

package/src/block/index.ts

@@ -0,0 +1,52 @@
+/**
+ * External dependencies
+ */
+import type { ComponentType } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { addFilter } from '@wordpress/hooks';
+import { withSelect } from '@wordpress/data';
+
+/**
+ * Internal dependencies
+ */
+import { store } from '../store';
+import type { Annotation } from '../types';
+
+interface BlockListBlockProps {
+	clientId: string;
+	className?: string;
+	[ key: string ]: unknown;
+}
+
+/**
+ * Adds annotation className to the block-list-block component.
+ *
+ * @param OriginalComponent The original BlockListBlock component.
+ * @return The enhanced component.
+ */
+const addAnnotationClassName = ( OriginalComponent: ComponentType< any > ) => {
+	return withSelect( ( select, ownProps ) => {
+		const { clientId, className } = ownProps as BlockListBlockProps;
+		const annotations: Annotation[] =
+			select( store ).__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/format/{annotation.js → annotation.ts}

@@ -3,26 +3,36 @@
  */
 import { __ } from '@wordpress/i18n';
 import { applyFormat, removeFormat } from '@wordpress/rich-text';
+import type { RichTextValue } from '@wordpress/rich-text';
 
-const FORMAT_NAME = 'core/annotation';
-
-const ANNOTATION_ATTRIBUTE_PREFIX = 'annotation-text-';
 /**
  * Internal dependencies
  */
 import { STORE_NAME } from '../store/constants';
+import type { Annotation, AnnotationFormat } from '../types';
+
+const FORMAT_NAME = 'core/annotation';
+
+const ANNOTATION_ATTRIBUTE_PREFIX = 'annotation-text-';
 
 /**
  * Applies given annotations to the given record.
  *
- * @param {Object} record      The record to apply annotations to.
- * @param {Array}  annotations The annotation to apply.
- * @return {Object} A record with the annotations applied.
+ * @param record      The record to apply annotations to.
+ * @param annotations The annotation to apply.
+ * @return A record with the annotations applied.
  */
-export function applyAnnotations( record, annotations = [] ) {
+export function applyAnnotations(
+	record: RichTextValue,
+	annotations: Annotation[] = []
+): RichTextValue {
 	annotations.forEach( ( annotation ) => {
 		let { start, end } = annotation;
 
+		if ( typeof start !== 'number' || typeof end !== 'number' ) {
+			return;
+		}
+
 		if ( start > record.text.length ) {
 			start = record.text.length;
 		}
@@ -42,7 +52,7 @@ export function applyAnnotations( record, annotations = [] ) {
 					className,
 					id,
 				},
-			},
+			} as any,
 			start,
 			end
 		);
@@ -54,21 +64,23 @@ export function applyAnnotations( record, annotations = [] ) {
 /**
  * Removes annotations from the given record.
  *
- * @param {Object} record Record to remove annotations from.
- * @return {Object} The cleaned record.
+ * @param record Record to remove annotations from.
+ * @return The cleaned record.
  */
-export function removeAnnotations( record ) {
+export function removeAnnotations( record: RichTextValue ): RichTextValue {
 	return removeFormat( record, 'core/annotation', 0, record.text.length );
 }
 
 /**
  * Retrieves the positions of annotations inside an array of formats.
  *
- * @param {Array} formats Formats with annotations in there.
- * @return {Object} ID keyed positions of annotations.
+ * @param formats Formats with annotations in there.
+ * @return ID keyed positions of annotations.
  */
-function retrieveAnnotationPositions( formats ) {
-	const positions = {};
+function retrieveAnnotationPositions(
+	formats: any[][]
+): Record< string, { start: number; end?: number } > {
+	const positions: Record< string, { start: number; end?: number } > = {};
 
 	formats.forEach( ( characterFormats, i ) => {
 		characterFormats = characterFormats || [];
@@ -98,17 +110,27 @@ function retrieveAnnotationPositions( formats ) {
 /**
  * Updates annotations in the state based on positions retrieved from RichText.
  *
- * @param {Array}    annotations                   The annotations that are currently applied.
- * @param {Array}    positions                     The current positions of the given annotations.
- * @param {Object}   actions
- * @param {Function} actions.removeAnnotation      Function to remove an annotation from the state.
- * @param {Function} actions.updateAnnotationRange Function to update an annotation range in the state.
+ * @param annotations                   The annotations that are currently applied.
+ * @param positions                     The current positions of the given annotations.
+ * @param actions
+ * @param actions.removeAnnotation      Function to remove an annotation from the state.
+ * @param actions.updateAnnotationRange Function to update an annotation range in the state.
  */
 function updateAnnotationsWithPositions(
-	annotations,
-	positions,
-	{ removeAnnotation, updateAnnotationRange }
-) {
+	annotations: Annotation[],
+	positions: Record< string, { start: number; end?: number } >,
+	{
+		removeAnnotation,
+		updateAnnotationRange,
+	}: {
+		removeAnnotation: ( annotationId: string ) => void;
+		updateAnnotationRange: (
+			annotationId: string,
+			start: number,
+			end: number
+		) => void;
+	}
+): void {
 	annotations.forEach( ( currentAnnotation ) => {
 		const position = positions[ currentAnnotation.id ];
 		// If we cannot find an annotation, delete it.
@@ -120,17 +142,22 @@ function updateAnnotationsWithPositions(
 		}
 
 		const { start, end } = currentAnnotation;
-		if ( start !== position.start || end !== position.end ) {
+		if (
+			typeof start === 'number' &&
+			typeof end === 'number' &&
+			( start !== position.start ||
+				end !== ( position.end ?? position.start ) )
+		) {
 			updateAnnotationRange(
 				currentAnnotation.id,
 				position.start,
-				position.end
+				position.end ?? position.start
 			);
 		}
 	} );
 }
 
-export const annotation = {
+export const annotation: AnnotationFormat = {
 	name: FORMAT_NAME,
 	title: __( 'Annotation' ),
 	tagName: 'mark',
@@ -139,13 +166,15 @@ export const annotation = {
 		className: 'class',
 		id: 'id',
 	},
-	edit() {
+	interactive: false,
+	object: false,
+	edit: () => {
 		return null;
 	},
-	__experimentalGetPropsForEditableTreePreparation(
+	__experimentalGetPropsForEditableTreePreparation: (
 		select,
 		{ richTextIdentifier, blockClientId }
-	) {
+	) => {
 		return {
 			annotations: select(
 				STORE_NAME
@@ -155,18 +184,24 @@ export const annotation = {
 			),
 		};
 	},
-	__experimentalCreatePrepareEditableTree( { annotations } ) {
+	__experimentalCreatePrepareEditableTree: ( { annotations } ) => {
 		return ( formats, text ) => {
 			if ( annotations.length === 0 ) {
 				return formats;
 			}
 
-			let record = { formats, text };
+			let record: RichTextValue = {
+				formats,
+				text,
+				replacements: [],
+				start: 0,
+				end: 0,
+			};
 			record = applyAnnotations( record, annotations );
 			return record.formats;
 		};
 	},
-	__experimentalGetPropsForEditableTreeChangeHandler( dispatch ) {
+	__experimentalGetPropsForEditableTreeChangeHandler: ( dispatch ) => {
 		return {
 			removeAnnotation:
 				dispatch( STORE_NAME ).__experimentalRemoveAnnotation,
@@ -174,7 +209,7 @@ export const annotation = {
 				dispatch( STORE_NAME ).__experimentalUpdateAnnotationRange,
 		};
 	},
-	__experimentalCreateOnChangeEditableValue( props ) {
+	__experimentalCreateOnChangeEditableValue: ( props ) => {
 		return ( formats ) => {
 			const positions = retrieveAnnotationPositions( formats );
 			const { removeAnnotation, updateAnnotationRange, annotations } =

package/src/format/{index.js → index.ts}

@@ -10,4 +10,4 @@ import { annotation } from './annotation';
 
 const { name, ...settings } = annotation;
 
-registerFormatType( name, settings );
+registerFormatType( name, settings as any );

package/src/store/actions.ts

@@ -0,0 +1,105 @@
+/**
+ * External dependencies
+ */
+import { v4 as uuid } from 'uuid';
+
+/**
+ * Internal dependencies
+ */
+import type { AddAnnotationParameters, AnnotationAction } from '../types';
+
+/**
+ * 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 identify groups of annotations.
+ *
+ * The `range` property is only relevant if the selector is 'range'.
+ *
+ * @param annotation                    The annotation to add.
+ * @param annotation.blockClientId      The blockClientId to add the annotation to.
+ * @param annotation.richTextIdentifier Identifier for the RichText instance the annotation applies to.
+ * @param annotation.range              The range at which to apply this annotation.
+ * @param annotation.selector           The way to apply this annotation.
+ * @param annotation.source             The source that added the annotation.
+ * @param annotation.id                 The ID the annotation should have. Generates a UUID by default.
+ * @return Action object.
+ */
+export function __experimentalAddAnnotation( {
+	blockClientId,
+	richTextIdentifier = null,
+	range = null,
+	selector = 'range',
+	source = 'default',
+	id = uuid(),
+}: AddAnnotationParameters ): AnnotationAction {
+	const action: AnnotationAction = {
+		type: 'ANNOTATION_ADD',
+		id,
+		blockClientId,
+		richTextIdentifier,
+		source,
+		selector,
+	};
+
+	if ( selector === 'range' && range !== null ) {
+		(
+			action as Extract< AnnotationAction, { type: 'ANNOTATION_ADD' } >
+		 ).range = range;
+	}
+
+	return action;
+}
+
+/**
+ * Removes an annotation with a specific ID.
+ *
+ * @param annotationId The annotation to remove.
+ * @return Action object.
+ */
+export function __experimentalRemoveAnnotation(
+	annotationId: string
+): AnnotationAction {
+	return {
+		type: 'ANNOTATION_REMOVE',
+		annotationId,
+	};
+}
+
+/**
+ * Updates the range of an annotation.
+ *
+ * @param annotationId ID of the annotation to update.
+ * @param start        The start of the new range.
+ * @param end          The end of the new range.
+ * @return Action object.
+ */
+export function __experimentalUpdateAnnotationRange(
+	annotationId: string,
+	start: number,
+	end: number
+): AnnotationAction {
+	return {
+		type: 'ANNOTATION_UPDATE_RANGE',
+		annotationId,
+		start,
+		end,
+	};
+}
+
+/**
+ * Removes all annotations of a specific source.
+ *
+ * @param source The source to remove.
+ * @return Action object.
+ */
+export function __experimentalRemoveAnnotationsBySource(
+	source: string
+): AnnotationAction {
+	return {
+		type: 'ANNOTATION_REMOVE_SOURCE',
+		source,
+	};
+}

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

@@ -1,6 +1,4 @@
 /**
  * The identifier for the data store.
- *
- * @type {string}
  */
 export const STORE_NAME = 'core/annotations';

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

@@ -19,8 +19,6 @@ import { STORE_NAME } from './constants';
  * Store definition for the annotations namespace.
  *
  * @see https://github.com/WordPress/gutenberg/blob/HEAD/packages/data/README.md#createReduxStore
- *
- * @type {Object}
  */
 export const store = createReduxStore( STORE_NAME, {
 	reducer,