feature: add TypeScript types to the blocks package

[johnhooks]

What?

Add TypeScript types to @wordpress/blocks

Supersedes and closes #43686.

This PR is build on the work already done on @types/wordpress__blocks by the following:

Jon Surrell https://github.com/sirreal
Dennis Snell https://github.com/dmsnell
Tomasz Tunik https://github.com/tomasztunik
Lucio Giannotta https://github.com/sunyatasattva
Bas Tolen https://github.com/bastolen

Why?

In the conversion regarding @ryanwelcher's PR #43686, there seemed some consense that having the type definitions separate from the source is brittle. I agree and want to help work toward the solving the issue.

How?

This PR adds types to @wordpress/blocks by defining them in TypeScript files and applying them to functions using the JSDoc syntax. The end result is to build type definitions directly from the source code.

Testing Instructions

This PR makes no edits to working code. The type checker and the existing test should provided adequate testing, I think? Opinions on how to further test the types are very welcome.

Notes

This is what I consider a first step towards converting the package to TypeScript. At the moment this does not type check the JavaScript files of the package. In this form the types are more helpful to develops of packages that rely on @wordpress/blocks than the package itself. Though I would argue having JSDocs pointing to documented types is also a big step in the right direction.

[github-actions]

👋 Thanks for your first Pull Request and for helping build the future of Gutenberg and WordPress, @johnhooks! In case you missed it, we'd love to have you join us in our Slack community, where we hold regularly weekly meetings open to anyone to coordinate with each other.

If you want to learn more about WordPress development in general, check out the Core Handbook full of helpful information.

[gziolo]

Thank you for starting to work on it!

It is currently a very big PR, any advice of how best to break it into smaller chucks would be great.

@adamziel or @dmsnell might have good insights on splitting the effort into smaller PRs. They gradually added typings to other big packages, @wordpress/data and @wordpress/core-data a few months ago.

[johnhooks]

Thank you, I've been studying the data package. Actually one of the biggest questions I have is about how to correctly type dispatch and select. I have typed all the actions and selectors, but both dispatch and select are typed to return an Object. An explanation or just pointing me to an example would help a lot.

[dmsnell]

cc: @sirreal

I've generally fell into a stance against major changes like this to TypeScript because of some of the fundamental challenges, as it seems you found with dispatch and select.

IMO a more achievable approach is flipping all of the source files in a package to TS and starting out extremely permissive (even with abundant any) and then slowly locking down the types from the leaf nodes. There's been an unfortunate saga of the types being written optimistically only to reject working code because it wasn't obvious when writing the types that other properties were possible.

My assessment for this mismatch between the JS code as written and the TS types is that we tend to have the actual types for an object distributed through seemingly random parts of the codebase. A property may not have any mention except for in a file deep in some seemingly-unrelated file in a different part of the repo and yet application developers rely on that. It's extremely hard to find all these places and then keep the types updated as people are rapidly extending the interfaces in other unrelated development.

As @gziolo noted I spent a lot of time and labor with @adamziel and @sarayourfriend trying to figure out how to add the benefit of the types without blocking legitimate development and it felt near impossible to do. the things that avoided getting in the way tended to be somewhat useless from a type standpoint because we'd have types like type Thing = { staticProperties } & Record<string, any>, which is hardly better than any or object.

But that's kind of what we have to do in the project to avoid being an obstacle for development as long as the TypeScript code interfaces with JS code. Without being 100% TS we lack the tools to uncover all the indirect places that the core code is modified. Even then, we have the further problem that some of the important code is outside the repo, found in plugin code.

---

There was an idea after WCEU last year to try a different approach, which was to analyze things like the selector and actions files and programmatically generate types. While select was principally difficult to type in TypeScript, it's not nearly as hard to generate types that would provide value without being part of the code itself, without going through the same type-checking that TS provides. It's a tradeoff that seems more viable given the way most of the code in Gutenberg developed. We diverted to other priorities and never moved forward, but I have some prototype code that uses the TypeScript npm library to analyze code and create those type definitions.

[johnhooks]

the things that avoided getting in the way tended to be somewhat useless from a type standpoint because we'd have types like type Thing = { staticProperties } & Record<string, any>, which is hardly better than any or object.

@dmsnell I see exactly what you mean. I agree that adding & Record<string, any> feels almost unavoidable in a lot of instances which negates a lot of the benefits that would be gained. Type generation could be an answer and I would definitely be willing to explore that.

A property may not have any mention except for in a file deep in some seemingly-unrelated file in a different part of the repo and yet application developers rely on that.

Some code outside the blocks package might use it outside the API and rely on properties that aren't even used in blocks?

I've generally fell into a stance against major changes like this to TypeScript because of some of the fundamental challenges

I understand. Honestly my biggest goal is to learn Gutenberg to the core. I have typically done so in previous projects by exploring the code and this is taking me deep inside how the Blocks work. Even if the entire package isn't updated to TypeScript, the types being completed in package/blocks/src/types/index.ts could be helpful and at least complete when finished. Do you think there would be benefit to that? And updates to the JSDoc comments?

Oh also another big goal was to start finding out who the TypeScript people are 😄. It seemed like it was going to be hard to do in Slack.

[johnhooks]

Also I'm totally willing to take what I discover and update the @types/wordpress__blocks, if the struggle to include them in the package is to great. It's just not as good as a solution for maintaining the types long term.

[dmsnell]

@johnhooks I definitely think that starting at the leaf-nodes, so to speak, is the more achievable approach. that is, for example, typing individual selectors with JSDoc types.

a whole-hearted switch from .js to .ts everywhere would be a big boon, but also presents its own problems, so adding types where we can without introducing architectural changes or comprehensive types is a good way to build gradual typing help. it's something that needs broad agreement and has been a rough discussion so far. maybe you can help!

Some code outside the blocks package might use it outside the API and rely on properties that aren't even used in blocks?

A good example might be blockType.supports.__experimentalSelector. It's not declared anywhere, but some code in the block-editor package checks for its presence, and some blocks in the block-library happen to include it. The WPBlockType type in JSDoc is defined inside of the blocks package, where there is no mention of the property. So the risk is that someone looks at that type in the package it comes from and doesn't include the experimental property, and then TypeScript rejects code that adds or relies upon that parameter when in fact it's the type that's wrong, not the code using the property.

[johnhooks]

UPDATE: I am walking back from an attempt of full conversion to TypeScript after some consideration and advice. I am working to integrate types similar to data and core-data.

[johnhooks]

There are still TODO comments, I'll keep researching them, but right now if a TODO is next to a type it typed to be super permissive because there wasn't much information about what it is near its usage. Other TODOs note where documentation is missing.

[tyxla]

@johnhooks thanks for the update. I see the PR is still blocked by a new release of memize, but let me know when it's ready for another look and I can try to spare a review cycle.

[johnhooks]

@tyxla other than the memize issue I believe this is ready. There are a few TODO comments about missing documentation. If you could help fill those in that would be great.

[tyxla]

Left some suggestions to fill in the missing documentation. Hope that helps!

[johnhooks]

Update: The changes to memize, in v2, solved the previous issue of building type declarations (thank you @aduth). This PR is getting closer and could use a thorough review. There are still a few TODOs regarding missing documentation in JSDoc comments, any further help filling in the holes would be greatly appreciated.

CC: @dmsnell, @gziolo, @noahtallen, and @tyxla

[dmsnell]

I will try and get to a more thorough review of this later; for now I need to put it on the TODO list.

[gziolo]

I wanted to reference a recently opened issue #53605 where some challenges with typing registerBlockType were raised.

[johnhooks]

@dmsnell @gziolo and @adamziel, is there still interest in this approach? I've been very busy and didn't have time to commit, though I have more time now and willing to resolve the conflicts and continue the review process.

[sirreal]

@johnhooks Thanks for the update, I'd be very happy to see initiatives to improve TypeScript support and integration like this one move ahead. Thank you!

[github-actions]

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.

Core SVN

If you're a Core Committer, use this list when committing to wordpress-develop in SVN:

Props: bitmachina, zieladam, jonsurrell, dmsnell, zebulan, noahtallen, tyxla, gziolo.

GitHub Merge commits

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: johnhooks <bitmachina@git.wordpress.org>
Co-authored-by: adamziel <zieladam@git.wordpress.org>
Co-authored-by: sirreal <jonsurrell@git.wordpress.org>
Co-authored-by: dmsnell <dmsnell@git.wordpress.org>
Co-authored-by: ZebulanStanphill <zebulan@git.wordpress.org>
Co-authored-by: noahtallen <noahtallen@git.wordpress.org>
Co-authored-by: tyxla <tyxla@git.wordpress.org>
Co-authored-by: gziolo <gziolo@git.wordpress.org>

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

[johnhooks]

variations is a property I don't have on the BlockType.

[github-actions]

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.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @noahtallen.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

Core SVN

If you're a Core Committer, use this list when committing to wordpress-develop in SVN:

Props: bitmachina, zieladam, jonsurrell, dmsnell, zebulan, tyxla, gziolo.

GitHub Merge commits

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

Unlinked contributors: noahtallen.

Co-authored-by: johnhooks <bitmachina@git.wordpress.org>
Co-authored-by: adamziel <zieladam@git.wordpress.org>
Co-authored-by: sirreal <jonsurrell@git.wordpress.org>
Co-authored-by: dmsnell <dmsnell@git.wordpress.org>
Co-authored-by: ZebulanStanphill <zebulan@git.wordpress.org>
Co-authored-by: tyxla <tyxla@git.wordpress.org>
Co-authored-by: gziolo <gziolo@git.wordpress.org>

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

[johnhooks]

@TimothyBJacobs would you recommend explicitly typing out the action types here and using the union of Action as the return type of all the action creators?

[github-actions]

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.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @noahtallen.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

Core SVN

If you're a Core Committer, use this list when committing to wordpress-develop in SVN:

Props: bitmachina, zieladam, jonsurrell, dmsnell, zebulan, tyxla, gziolo.

GitHub Merge commits

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

Unlinked contributors: noahtallen.

Co-authored-by: johnhooks <bitmachina@git.wordpress.org>
Co-authored-by: adamziel <zieladam@git.wordpress.org>
Co-authored-by: sirreal <jonsurrell@git.wordpress.org>
Co-authored-by: dmsnell <dmsnell@git.wordpress.org>
Co-authored-by: ZebulanStanphill <zebulan@git.wordpress.org>
Co-authored-by: tyxla <tyxla@git.wordpress.org>
Co-authored-by: gziolo <gziolo@git.wordpress.org>

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

[github-actions]

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.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @noahtallen.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

Core SVN

If you're a Core Committer, use this list when committing to wordpress-develop in SVN:

Props: bitmachina, zieladam, jonsurrell, dmsnell, zebulan, tyxla, gziolo.

GitHub Merge commits

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

Unlinked contributors: noahtallen.

Co-authored-by: johnhooks <bitmachina@git.wordpress.org>
Co-authored-by: adamziel <zieladam@git.wordpress.org>
Co-authored-by: sirreal <jonsurrell@git.wordpress.org>
Co-authored-by: dmsnell <dmsnell@git.wordpress.org>
Co-authored-by: ZebulanStanphill <zebulan@git.wordpress.org>
Co-authored-by: tyxla <tyxla@git.wordpress.org>
Co-authored-by: gziolo <gziolo@git.wordpress.org>

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

[github-actions]

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.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @noahtallen.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

Core SVN

If you're a Core Committer, use this list when committing to wordpress-develop in SVN:

Props: bitmachina, zieladam, jonsurrell, dmsnell, zebulan, tyxla, gziolo.

GitHub Merge commits

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

Unlinked contributors: noahtallen.

Co-authored-by: johnhooks <bitmachina@git.wordpress.org>
Co-authored-by: adamziel <zieladam@git.wordpress.org>
Co-authored-by: sirreal <jonsurrell@git.wordpress.org>
Co-authored-by: dmsnell <dmsnell@git.wordpress.org>
Co-authored-by: ZebulanStanphill <zebulan@git.wordpress.org>
Co-authored-by: tyxla <tyxla@git.wordpress.org>
Co-authored-by: gziolo <gziolo@git.wordpress.org>

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

[noahtallen]

Updated my profile so I don't get these anymore :)