TypeScript: migrate annotations package to TS by kushagra-goyal-14 · Pull Request #70602 · WordPress/gutenberg

kushagra-goyal-14 · 2025-07-03T09:38:19Z

What?

Part of #67691

Migrating the annotations package to TypeScript.

Why?

To enhance DX and add type safety.

How?

By porting the code and tests to TypeScript.

Testing Instructions

Typecheck and unit tests.

github-actions · 2025-07-03T11:14:34Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: kushagra-goyal-14 <kush123@git.wordpress.org>
Co-authored-by: manzoorwanijk <manzoorwanijk@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

manzoorwanijk · 2025-07-18T14:17:55Z

+const addAnnotationClassName = ( OriginalComponent: any ) => {
+	return ( withSelect as any )(


I would prefer to avoid these two any here, which means, we probably should first convert withSelect to typescript.

manzoorwanijk · 2026-01-11T09:28:55Z

What is the status here?

… function as withSelect is now migrated.

kushagra-goyal-14 · 2026-04-03T08:49:38Z

Hi @manzoorwanijk, I made some changes since it seems withSelect has been migrated. Can you please review them?

Copilot

Pull request overview

Migrates the @wordpress/annotations package implementation and tests to TypeScript as part of the broader “convert packages to TS” effort, adding explicit types for annotations, store actions/state, and format registration.

Changes:

Adds a new TS project config for packages/annotations and wires it into the root TS project references.
Ports annotations store (actions/reducer/selectors) and related runtime modules (format + block filter) to TypeScript and introduces shared types.ts.
Updates docs autogen tokens to point at the new .ts sources.

Reviewed changes

Copilot reviewed 15 out of 17 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tsconfig.json	Adds `packages/annotations` as a TS project reference.
packages/annotations/tsconfig.json	New package-level TS config (rootDir, declarationDir, references).
packages/annotations/src/types.ts	Introduces core annotation/store/format TypeScript types.
packages/annotations/src/store/actions.ts	Ports store actions to TS, adds typed action union usage.
packages/annotations/src/store/reducer.ts	Ports reducer to TS and adds typed helpers/validation.
packages/annotations/src/store/selectors.ts	Adds TS types for selector inputs/outputs and tightens JSDoc.
packages/annotations/src/store/index.ts	Keeps store registration; minor JSDoc cleanup.
packages/annotations/src/store/constants.ts	Minor JSDoc cleanup.
packages/annotations/src/store/test/reducer.ts	Updates tests for TS types and stricter action shapes.
packages/annotations/src/index.ts	New TS entrypoint importing format/block side effects and exporting store.
packages/annotations/src/format/index.ts	TS adjustment for registering the annotation rich-text format.
packages/annotations/src/format/annotation.ts	Adds RichTextValue typing + TS-safe handling in format utilities.
packages/annotations/src/block/index.ts	Ports block filter to TS and uses the exported store in `select`.
docs/reference-guides/data/data-core-annotations.md	Updates autogen tokens to reference `.ts` sources.

Comments suppressed due to low confidence (1)

packages/annotations/src/format/index.ts:13

registerFormatType is being called with settings as any, which defeats the goal of the TS migration. It looks like the annotation format object is missing required properties from the WPFormat shape (notably interactive and object); adding them to the format definition (and to the AnnotationFormat type) should allow removing this cast.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-03T13:39:41Z

@@ -0,0 +1,20 @@
+{


The tsconfig files in this repo typically include the $schema field for editor/validation support. Consider adding it here for consistency with other package tsconfigs (e.g. packages/keycodes/tsconfig.json).

Suggested change

{

{

"$schema": "https://json.schemastore.org/tsconfig",

Copilot · 2026-04-03T13:39:42Z

+ * 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 JSDoc says "to identity groups of annotations" which reads like a typo/grammar issue. This should likely be "to identify groups of annotations".

Suggested change

* to identity groups of annotations.

* to identify groups of annotations.

Copilot · 2026-04-03T13:39:42Z

+	if ( selector === 'range' ) {
+		(
+			action as Extract< AnnotationAction, { type: 'ANNOTATION_ADD' } >
+		 ).range = range as WPAnnotationRange;


range is declared as WPAnnotationRange | null in AddAnnotationParameters, but this code force-casts it to WPAnnotationRange and assigns it even when it may be null. This weakens type safety and can hide invalid dispatches; consider only setting action.range when range is non-null (or update the AnnotationAction type to reflect null if it's intentionally allowed).

Suggested change

if ( selector === 'range' ) {

(

action as Extract< AnnotationAction, { type: 'ANNOTATION_ADD' } >

).range = range as WPAnnotationRange;

if ( selector === 'range' && range !== null ) {

(

action as Extract< AnnotationAction, { type: 'ANNOTATION_ADD' } >

).range = range;

Copilot · 2026-04-03T13:39:42Z

+	attributes: {
+		className: string;
+		id: string;
+	};


AnnotationFormat doesn't include the interactive and object properties that @wordpress/rich-text's registerFormatType expects for a WPFormat, which is likely why settings as any is needed in format/index.ts. Consider adding these fields (e.g. as booleans) so the format object can be passed to registerFormatType without an unsafe cast.

Suggested change

};

};

interactive: boolean;

object: boolean;

Copilot · 2026-04-03T13:39:42Z

+ * @property {number} start The offset where the annotation should start.
+ * @property {number} end   The offset where the annotation should end.
+ */
+
+/**


This standalone JSDoc block with only @property tags looks like a leftover from the old @typedef WPAnnotationRange and is no longer attached to any symbol (since WPAnnotationRange is now a TS interface). Consider removing it to avoid confusing doc generation / JSDoc linting.

Suggested change

* @property {number} start The offset where the annotation should start.

* @property {number} end The offset where the annotation should end.

*/

/**

…nfiguration as per review

…n format

kushagra-goyal-14 · 2026-04-07T07:57:25Z

@manzoorwanijk I have made the changes as per the Copilot review. Can you please re-check? Thanks

manzoorwanijk

This looks good. I have some suggestions for further improvements.

manzoorwanijk · 2026-04-03T13:26:11Z

+	"compilerOptions": {
+		"rootDir": "src",
+		"declarationDir": "build-types"
+	},


We don't need these overrides.

Suggested change

"compilerOptions": {

"rootDir": "src",

"declarationDir": "build-types"

},

manzoorwanijk · 2026-04-03T13:26:55Z

+	],
+	"include": [ "src/**/*" ],
+	"exclude": [
+		"src/**/*.test.ts",
+		"src/**/*.test.tsx",
+		"src/**/test/**/*.ts",
+		"src/**/test/**/*.tsx"
+	]


We don't need these overrides either

Suggested change

],

"include": [ "src/**/*" ],

"exclude": [

"src/**/*.test.ts",

"src/**/*.test.tsx",

"src/**/test/**/*.ts",

"src/**/test/**/*.tsx"

]

]

manzoorwanijk · 2026-04-03T13:53:13Z

 			selector: 'range',
 			range: {
-				start: 'not a number',
+				start: 'not a number' as any,


It's better to use // @ts-expect-error in such cases with a comment explaining why.

manzoorwanijk · 2026-04-03T13:53:29Z

 			range: {
 				start: 100,
-				end: 'not a number',
+				end: 'not a number' as any,


Same here about using // @ts-expect-error.

manzoorwanijk · 2026-04-07T13:33:26Z

+/**
+ * Represents a range in text content.
+ */
+export interface WPAnnotationRange {


Let us remove the WP prefix here.

manzoorwanijk · 2026-04-07T13:33:47Z

+/**
+ * Base annotation interface.
+ */
+export interface WPAnnotation {


No need of WP prefix.

manzoorwanijk · 2026-04-07T13:34:47Z

 	"references": [
 		{ "path": "bin" },
 		{ "path": "packages/a11y" },
+		{ "path": "packages/annotations" },


Let us place it in the correct place in alphabetical order.

…andle the review changes

…ic in reducer.ts

manzoorwanijk

We haven't added the types field to package.json here. We also need to add it to the exports['.'] field there.

manzoorwanijk · 2026-04-07T17:54:01Z

@claude Review this

Copilot

Pull request overview

Copilot reviewed 14 out of 16 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

packages/annotations/src/store/selectors.ts:76

In __experimentalGetAnnotationsForRichText, range is typed as AnnotationRange | null | undefined (since Annotation.range is optional/nullable), but the code spreads it ({ ...range, ...other }). With strict TS this will error because object spread requires a non-null object type. Consider narrowing in the filter (e.g., ensure annotation.range is present) or otherwise making range non-null before spreading so this selector typechecks and matches the reducer invariant (range annotations always have a range).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-07T18:00:24Z

+export interface AnnotationsState {
+	[ blockClientId: string ]: Annotation[];
+}


AnnotationsState is currently defined with a string index signature returning Annotation[], which implies every key lookup returns an array even when the blockClientId key is missing. The rest of the code already treats missing keys as undefined (e.g. state?.[ blockClientId ] ?? []), so the state type is unsound. Consider changing it to something like Record<string, Annotation[] | undefined> (or Partial<Record<string, Annotation[]>>) to reflect runtime behavior and avoid incorrect assumptions in consumers.

Suggested change

export interface AnnotationsState {

[ blockClientId: string ]: Annotation[];

}

export type AnnotationsState = Partial< Record< string, Annotation[] > >;

…notationsState interface

…ckage.json

manzoorwanijk · 2026-04-09T08:45:19Z

Let us make CI happy and please mention me when it's ready again. Thank you for your contributions.

…xperimentalGetAnnotations to filter out undefined values in selectors.ts

kushagra-goyal-14 · 2026-04-09T10:03:55Z

Hi @manzoorwanijk, I have made the changes, just waiting for the CI.

manzoorwanijk

This looks good now. Thank you.

kushagra-goyal-14 and others added 3 commits July 3, 2025 15:05

refactor: migrate annotations package from js to ts for type safety

3c6bfdd

fix: validate start and end properties in applyAnnotations function

6def6e9

Merge branch 'trunk' into try/migrate-annotations-ts

412b7d1

kushagra-goyal-14 marked this pull request as ready for review July 3, 2025 11:14

kushagra-goyal-14 requested review from ajitbohra, atimmer, fabiankaegy, juanmaguitar and ndiego as code owners July 3, 2025 11:14

t-hamano mentioned this pull request Jul 4, 2025

Convert packages to TypeScript #67691

Open

39 tasks

t-hamano added [Type] Code Quality Issues or PRs that relate to code quality [Feature] Annotations Adding annotation functionality labels Jul 4, 2025

Merge branch 'trunk' into try/migrate-annotations-ts

7bd5d8f

manzoorwanijk reviewed Jul 18, 2025

View reviewed changes

kushagra-goyal-14 and others added 2 commits April 3, 2026 13:53

Merge branch 'trunk' into try/migrate-annotations-ts

fef7d10

refactor: improve type safety and structure in addAnnotationClassName…

62e5919

… function as withSelect is now migrated.

refactor: fix linting issues

387c195

kushagra-goyal-14 requested a review from manzoorwanijk April 3, 2026 09:39

manzoorwanijk requested a review from Copilot April 3, 2026 13:30

Copilot started reviewing on behalf of manzoorwanijk April 3, 2026 13:31 View session

Copilot AI reviewed Apr 3, 2026

View reviewed changes

kushagra-goyal-14 added 4 commits April 6, 2026 20:25

refactor: improve annotation action handling and update TypeScript co…

46068be

…nfiguration as per review

refactor: set interactive and object properties to false in annotatio…

bcff9c4

…n format

refactor: handle linting issues

c20ce14

refactor: handle linting issues

c3641a8

manzoorwanijk reviewed Apr 7, 2026

View reviewed changes

kushagra-goyal-14 added 3 commits April 7, 2026 20:17

refactor: rename WPAnnotation to Annotation across the codebase and h…

78dbf91

…andle the review changes

refactor: update WPAnnotation to Annotation in annotation removal log…

cc83a0d

…ic in reducer.ts

refactor: fix formatting and linting

2a4f942

manzoorwanijk requested a review from Copilot April 7, 2026 17:51

manzoorwanijk requested changes Apr 7, 2026

View reviewed changes

Copilot AI reviewed Apr 7, 2026

View reviewed changes

kushagra-goyal-14 added 2 commits April 9, 2026 13:03

refactor: update package.json to include types export and simplify An…

373e9de

…notationsState interface

refactor: move types export declaration to maintain consistency in pa…

37b1dfa

…ckage.json

refactor: update mapValues to handle undefined values and enhance __e…

65df6e9

…xperimentalGetAnnotations to filter out undefined values in selectors.ts

manzoorwanijk approved these changes Apr 9, 2026

View reviewed changes

manzoorwanijk merged commit 8969243 into WordPress:trunk Apr 9, 2026
40 checks passed

github-actions Bot added this to the Gutenberg 23.0 milestone Apr 9, 2026

		const addAnnotationClassName = ( OriginalComponent: any ) => {
		return ( withSelect as any )(

	* to identity groups of annotations.
	* to identify groups of annotations.

-	};
+	};
+	interactive: boolean;
+	object: boolean;

Conversation

kushagra-goyal-14 commented Jul 3, 2025

What?

Why?

How?

Testing Instructions

Uh oh!

github-actions Bot commented Jul 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

manzoorwanijk commented Jan 11, 2026

Uh oh!

kushagra-goyal-14 commented Apr 3, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

kushagra-goyal-14 commented Apr 7, 2026

Uh oh!

manzoorwanijk left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

manzoorwanijk left a comment

Choose a reason for hiding this comment

Uh oh!

manzoorwanijk commented Apr 7, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

manzoorwanijk commented Apr 9, 2026

Uh oh!

kushagra-goyal-14 commented Apr 9, 2026

Uh oh!

manzoorwanijk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

github-actions Bot commented Jul 3, 2025 •

edited

Loading