Some contribution ideas for Blockly (typings, procedures, docs)

[heliacer]

Hi all, I have taken quite a liking to Blockly as I’ve been actively using it on my dream project called Graplet, and it has helped in many ways to think bigger since I first stumbled upon it (a long time ago btw). That’s why I would love to return the favour and contribute in some specific parts that have been bugging me for a while now - and I’d really love to see them in Blockly :>

I’d love to implement typings for the JSON Block Definition. It currently is any, passed into defineBlocksWithJsonArray Having clear optional identifiers with their corresponding types would help out a bunch, instead of relying on unpredictable string literal properties.

I’ve also been thinking about built-in stuff, such as variable and procedure blocks, and modifying them is still a bit of a hassle. There are many overrides one has to do, as well as unregistering/reregistering, and that kinda feels off.

Having the option to disable all built-in blocks would make things much easier - for example, to create a custom procedure model (e.g. one where parameters are not global variables, but value blocks that can be dragged out of the procedure definition block as a source, kinda similar to how Scratch’s “Custom Blocks” work).

The slight tradeoff would be that many commonly used blocks, such as math_number, would have to be recreated - but honestly, I think that’s completely worth it. In fact, I’d say it’s worth wiping the built-in stuff entirely for that tradeoff, if the option is disabled (eg. useBuiltIn: false)

The docs on creating custom procedures are also a bit misleading. They have incomplete/false code snippets, and figuring out the actual way to implement ObservableProcedureModel is quite the challenge…

I hope some of those ideas and possible contributions align with Blockly’s ideals. I would really love to work on this and see it live in action :D (and thanks for reading that big message wall up until here lol).

[heliacer]

Hey, quick correction to my first post:
When I mentioned BlockDefinition, what I really meant was the JSON block definition (the one passed into defineBlocksWithJsonArray).

BlockDefinition itself is the object with functions (like when you call defineBlocks({ ... })). But for the JSON shape, it’s currently still typed as AnyDuringMigration. That’s the part I was actually talking about - having a proper type/interface there (instead of any) would make manual block creation a lot smoother, with clear optional identifiers and their types instead of relying on string literals.

[maribethb]

Hello, thank you for your interest in contributing to Blockly! Generally, we use GitHub issues to track specific bugs or feature requests, so a general discussion like this one is best had in our developer forum. You're welcome to post there if you have questions about contributing to Blockly or how to find something to work on! I'll close this issue but do feel free to follow up on the developer forum if you have additional questions.

Here's some additional resources/comments:

• Typing the BlockDefinition is a bit thorny. You can see this issue for more information about what it involves. If you'd like to take this on, please feel free to add your ideas to the issue.
• I am not quite sure what you mean about "disabling" the library blocks. They are already optional to import (don't import them if you don't want them at all), and if you only want some of them, you can not include the others in your toolbox definition. You can also overwrite block definitions if you want a custom block with the same name as a built-in one. If there's something specific you're trying to do and can't figure out how to make it work, please do post your question on the forum with specific goals and reproduction steps. We always have someone assigned to respond to the forum and we'll either be able to help answer your question or file a feature request as needed.
• Please file a separate issue about incorrect code in the custom procedures docs; specific examples or which code snippets you're talking about would help a lot.
• If you are looking for other issues to contribute to, the "good first issue" and "help wanted" tags are good places to start.
• You can read our information about how to contribute and how to file good issues on our documentation site.

Thanks again, and please stay in touch on the forum if you have any questions!

[heliacer]

@maribethb

• Typing the BlockDefinition is a bit thorny. You can see this issue for more information about what it involves. If you'd like to take this on, please feel free to add your ideas to the issue.

Just to clarify - what I’m really interested in typing is the JSON block definition (the object passed into defineBlocksWithJsonArray). I had initially confused it with BlockDefinition itself.

I’ve started sketching a rough interface to capture the common fields and the dynamic messageN / argsN keys. I can add it to the issue or create a separate PR if that’s helpful.

Also, a small note: I realized that my confusion about built-in blocks came from importing everything from blockly instead of blockly/core, so the core blocks showing up was entirely on my side 😅

I’ll file a separate issue for the documentation inaccuracies I found regarding custom procedures.