Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feature: add TypeScript types to the blocks package #48604

Open
wants to merge 4 commits into
base: trunk
Choose a base branch
from

Conversation

johnhooks
Copy link
Contributor

@johnhooks johnhooks commented Feb 28, 2023

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 github-actions bot added the First-time Contributor Pull request opened by a first-time contributor to Gutenberg repository label Feb 28, 2023
@github-actions
Copy link

👋 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 gziolo added [Type] Code Quality Issues or PRs that relate to code quality [Package] Blocks /packages/blocks Developer Experience Ideas about improving block and theme developer experience labels Feb 28, 2023
@gziolo
Copy link
Member

gziolo commented Mar 1, 2023

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
Copy link
Contributor Author

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
Copy link
Contributor

dmsnell commented Mar 1, 2023

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
Copy link
Contributor Author

johnhooks commented Mar 1, 2023

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
Copy link
Contributor Author

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
Copy link
Contributor

dmsnell commented Mar 2, 2023

@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 johnhooks force-pushed the feature/add-blocks-types branch 2 times, most recently from 2fdffad to 2453989 Compare March 2, 2023 20:16
@johnhooks
Copy link
Contributor Author

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 johnhooks force-pushed the feature/add-blocks-types branch 5 times, most recently from 1aa8625 to a680d85 Compare March 3, 2023 02:31
@johnhooks johnhooks changed the title feature: convert the blocks package to TypeScript feature: add TypeScript types to the blocks package Mar 3, 2023
@johnhooks johnhooks marked this pull request as ready for review March 3, 2023 03:11
@johnhooks
Copy link
Contributor Author

johnhooks commented Mar 3, 2023

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.

@johnhooks johnhooks marked this pull request as draft March 3, 2023 04:00
@tyxla
Copy link
Member

tyxla commented Apr 28, 2023

@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
Copy link
Contributor Author

johnhooks commented Apr 28, 2023

@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.

Copy link
Member

@tyxla tyxla left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

packages/blocks/src/api/serializer.js Outdated Show resolved Hide resolved
packages/blocks/src/api/types.ts Outdated Show resolved Hide resolved
packages/blocks/src/api/types.ts Outdated Show resolved Hide resolved
packages/blocks/src/store/types.ts Outdated Show resolved Hide resolved
packages/blocks/src/types/block-attributes.ts Outdated Show resolved Hide resolved
packages/blocks/src/types/block-attributes.ts Outdated Show resolved Hide resolved
packages/blocks/src/types/block-attributes.ts Outdated Show resolved Hide resolved
packages/blocks/src/types/block-type.ts Outdated Show resolved Hide resolved
packages/blocks/src/types/block-type.ts Outdated Show resolved Hide resolved
packages/blocks/src/types/block-type.ts Outdated Show resolved Hide resolved
@johnhooks
Copy link
Contributor Author

johnhooks commented May 15, 2023

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
Copy link
Contributor

dmsnell commented May 15, 2023

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
Copy link
Member

gziolo commented Aug 31, 2023

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

@johnhooks
Copy link
Contributor Author

johnhooks commented Jan 7, 2024

@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
Copy link
Member

sirreal commented Jan 8, 2024

@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!

Copy link

github-actions bot commented Feb 4, 2024

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.

* @property {Component} edit Component rendering an element to
* manipulate the attributes of a block
* in the context of an editor.
* @property {WPBlockVariation[]} [variations] The list of block variations.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Thanks @tyxla for helping fill in the gaps.

Co-authored-by: Marin Atanasov <8436925+tyxla@users.noreply.github.com>
Copy link

github-actions bot commented Feb 4, 2024

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.

BlockStyle,
BlockType,
} from '../types';

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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?

Copy link

github-actions bot commented Feb 4, 2024

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.

1 similar comment
Copy link

github-actions bot commented Feb 4, 2024

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.

Use React.ComponentType and React.ReactElement instead of WPComponent and WPElement.

See: [packages/element/src/react.js](https://github.com/WordPress/gutenberg/blob/ca2ee4d6fa8c7044cd1d3045c0985a77659f44fa/packages/element/src/react.js#L37-L47)
Copy link

github-actions bot commented Feb 4, 2024

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
Copy link
Member

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Developer Experience Ideas about improving block and theme developer experience First-time Contributor Pull request opened by a first-time contributor to Gutenberg repository [Package] Blocks /packages/blocks [Type] Code Quality Issues or PRs that relate to code quality
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

8 participants