scratchblocks-plus 1.0.1 → 1.1.0

package/LICENSE

@@ -1,5 +1,5 @@
 scratchblocks is Copyright © 2013–2021, Tim Radvan
-scratchblocks-plus is Copyright © 2025, Lu Yifei
+scratchblocks-plus is Copyright © 2025–2026, Lu Yifei
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

package/README.md

@@ -1,17 +1,34 @@
 Make pictures of Scratch blocks from text.
 
-<!--
-[![Screenshot](https://scratchblocks.github.io/screenshot.png)](https://scratchblocks.github.io/#when%20flag%20clicked%0Aclear%0Aforever%0Apen%20down%0Aif%20%3C%3Cmouse%20down%3F%3E%20and%20%3Ctouching%20%5Bmouse-pointer%20v%5D%3F%3E%3E%20then%0Aswitch%20costume%20to%20%5Bbutton%20v%5D%0Aelse%0Aadd%20(x%20position)%20to%20%5Blist%20v%5D%0Aend%0Amove%20(foo)%20steps%0Aturn%20ccw%20(9)%20degrees)
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="/readme-assets/images/dark.png">
+  <img alt="Screenshot" src="/readme-assets/images/light.png">
+</picture>
 
-**[Try it out!](https://scratchblocks.github.io/)**
--->
+**[Try it out!](https://luyifei2011.github.io/scratchblocks-plus/)**
+
+[Documentation](https://luyifei2011.github.io/scratchblocks-plus-docs/)
 
 ---
 
 **scratchblocks-plus** is a fork of **scratchblocks**, and adds the following features:
-- basic TypeScript support
-- Matrix support (issue: [scratchblocks#509](https://github.com/scratchblocks/scratchblocks/issues/509), PR: [scratchblocks#573](https://github.com/scratchblocks/scratchblocks/pull/573))
+
+- matrix support
+  - [try it out!](https://luyifei2011.github.io/scratchblocks-plus/#?style=scratch3&script=display%20(%7B01010%2C%0A%20%20%20%20%20%20%20%20%20%2010101%2C%0A%20%20%20%20%20%20%20%20%20%2010001%2C%0A%20%20%20%20%20%20%20%20%20%2001010%2C%0A%20%20%20%20%20%20%20%20%20%2000100%7D%20v))
+  - issue: [scratchblocks#509](https://github.com/scratchblocks/scratchblocks/issues/509)
+  - PR: [scratchblocks#573](https://github.com/scratchblocks/scratchblocks/pull/573)
 - block highlight
+  - [example 1](https://luyifei2011.github.io/scratchblocks-plus/example/text-highlight.html)
+  - [example 2](https://luyifei2011.github.io/scratchblocks-plus/example/speech-highlight.html)
+- dropdown menu translate
+  - [try it out!](https://luyifei2011.github.io/scratchblocks-plus/translator/#?lang=zh_cn&script=go%20to%20(mouse-pointer%20v))
+  - issue: [scratchblocks#324](https://github.com/scratchblocks/scratchblocks/issues/324)
+  - PR: [scratchblocks#556](https://github.com/scratchblocks/scratchblocks/pull/556)
+- server-side rendering
+  - issue: [scratchblocks#402](https://github.com/scratchblocks/scratchblocks/issues/402)
+  - PR: [scratchblocks#589](https://github.com/scratchblocks/scratchblocks/pull/589)
+- basic TypeScript support
+- and more!
 
 **scratchblocks-plus** is compatible with **scratchblocks**, so you can use it as a drop-in replacement.
 
@@ -44,7 +61,7 @@ It uses the [pandoc_scratchblocks](https://github.com/CodeClub/pandoc_scratchblo
 This would probably be a good way to write a Scratch book.
 -->
 
-# React
+## React
 
 Use the [scratchblocks-plus-react](https://github.com/LuYifei2011/scratchblocks-plus-react) package to render scratchblocks in React.
 
@@ -53,15 +70,16 @@ Use the [scratchblocks-plus-react](https://github.com/LuYifei2011/scratchblocks-
 You'll need to include a copy of the scratchblocks-plus JS file on your webpage.
 There are a few ways of getting one:
 
-* Download it from the <https://github.com/LuYifei2011/scratchblocks-plus/releases> page
+- Download it from the <https://github.com/LuYifei2011/scratchblocks-plus/releases> page
 <!--* If you have a fancy JS build system, you might like to include the `scratchblocks-plus` package from NPM-->
-* You could clone this repository and build it yourself using Node 16.14.0+ (`npm run build`).
+- You could clone this repository and build it yourself using Node 16.14.0+ (`npm run build`).
 
 ```html
 <script src="scratchblocks-min.js"></script>
 ```
 
 The convention is to write scratchblocks inside `pre` tags with the class `blocks`:
+
 ```html
 <pre class="blocks">
 when flag clicked
@@ -71,6 +89,7 @@ move (10) steps
 
 You then need to call `scratchblocks.renderMatching` after the page has loaded.
 Make sure this appears at the end of the page (just before the closing `</body>` tag):
+
 ```js
 <script>
 scratchblocks.renderMatching('pre.blocks', {
@@ -80,6 +99,7 @@ scratchblocks.renderMatching('pre.blocks', {
 });
 </script>
 ```
+
 The `renderMatching()` function takes a CSS-style selector for the elements that contain scratchblocks code: we use `pre.blocks` to target `pre` tags with the class `blocks`.
 
 The `style` option controls how the blocks appear, either the Scratch 2 or Scratch 3 style is supported.
@@ -87,11 +107,13 @@ The `style` option controls how the blocks appear, either the Scratch 2 or Scrat
 ### Inline blocks
 
 You might also want to use blocks "inline", inside a paragraph:
+
 ```html
 I'm rather fond of the <code class="b">stamp</code> block in Scratch.
 ```
 
 To allow this, make a second call to `renderMatching` using the `inline` argument.
+
 ```js
 <script>
 scratchblocks.renderMatching("pre.blocks", ...)
@@ -102,6 +124,7 @@ scratchblocks.renderMatching("code.b", {
 });
 </script>
 ```
+
 This time we use `code.b` to target `code` blocks with the class `b`.
 
 ### Translations
@@ -109,22 +132,24 @@ This time we use `code.b` to target `code` blocks with the class `b`.
 If you want to use languages other than English, you'll need to include a second JS file that contains translations.
 The releases page includes two options; you can pick one:
 
-* `translations.js` includes a limited set of languages, as seen on the Scratch Forums
-* `translations-all.js` includes every language that Scratch supports.
+- `translations.js` includes a limited set of languages, as seen on the Scratch Forums
+- `translations-all.js` includes every language that Scratch supports.
 
 The translations files are hundreds of kilobytes in size, so to keep your page bundle size down you might like to build your own file with just the languages you need.
 
 For example, a translations file that just loads the German language (ISO code `de`) would look something like this:
+
 ```js
-window.scratchblocks.loadLanguages({
+scratchblocks.loadLanguages({
     de: <contents of locales/de.json>
 })
 ```
 
 If you're using a JavaScript bundler you should be able to build your own translations file by calling `require()` with the path to the locale JSON file.
 This requires your bundler to allow importing JSON files as JavaScript.
+
 ```js
-window.scratchblocks.loadLanguages({
+scratchblocks.loadLanguages({
     de: require('scratchblocks/locales/de.json'),
 })
 ```
@@ -143,7 +168,8 @@ scratchblocks.renderMatching('pre.blocks');
 ```
 
 ## ESM Support
-Since version 3.6.0, scratchblocks-plus can be properly loaded as an ESM module. The ESM version, instead of defining `window.scratchblocks`, default-exports the `scratchblocks` object. Similarly, the JavaScript translation files default-exports a function to load the translations.
+
+scratchblocks-plus can be properly loaded as an ESM module. The ESM version, instead of defining `window.scratchblocks`, default-exports the `scratchblocks` object. Similarly, the JavaScript translation files default-exports a function to load the translations.
 
 ```js
 import scratchblocks from "./scratchblocks-plus-es-min.js";
@@ -156,6 +182,7 @@ loadTranslations(scratchblocks);
 # Languages
 
 To update the translations:
+
 ```sh
 npm upgrade scratch-l10n
 npm run locales
@@ -170,28 +197,27 @@ I'd be happy to accept pull requests for those! You'll need to rebuild the trans
 
 This should set you up and start a http-server for development:
 
-```
+```sh
 npm install
 npm start
 ```
 
 Then open <http://localhost:8000/> :-)
 
-For more details, see [`CONTRIBUTING.md`](https://github.com/LuYifei2011/scratchblocks-plus/blob/master/.github/CONTRIBUTING.md).
-
+For more details, see [`CONTRIBUTING.md`](https://github.com/LuYifei2011/scratchblocks-plus/blob/main/.github/CONTRIBUTING.md).
 
 # Credits
 
 Many, many thanks to the [contributors](https://github.com/LuYifei2011/scratchblocks-plus/graphs/contributors)!
 
-* Authored by [LuYifei2011](https://github.com/LuYifei2011)
-* This is a fork of [scratchblocks](https://github.com/scratchblocks/scratchblocks), so all the credit there still applies here.
-* Original scratchblocks library by [tjvr](https://github.com/tjvr)
-* Original scratchblocks library maintained by tjvr and [apple502j](https://github.com/apple502j)
-* Icons derived from [Scratch Blocks](https://github.com/scratchfoundation/scratch-blocks) (Apache License 2.0)
-* Scratch 2 SVG proof-of-concept, shapes & filters by [as-com](https://github.com/as-com)
-* Anna helped with a formula, and pointed out that I can't read graphs
-* JSO designed the syntax and wrote the original [Block Plugin](https://en.scratch-wiki.info/wiki/Block_Plugin_\(1.4\))
-* Help with translation code from [joooni](https://scratch.mit.edu/users/joooni/)
-* Block translations from the [scratch-l10n repository](https://github.com/scratchfoundation/scratch-l10n/)
-* Ported to node by [arve0](https://github.com/arve0)
+- Maintained by [LuYifei2011](https://github.com/LuYifei2011)
+- This is a fork of [scratchblocks](https://github.com/scratchblocks/scratchblocks), so all the credit there still applies here.
+- Original scratchblocks library by [tjvr](https://github.com/tjvr)
+- Original scratchblocks library maintained by tjvr and [apple502j](https://github.com/apple502j)
+- Icons derived from [Scratch Blocks](https://github.com/scratchfoundation/scratch-blocks) (Apache License 2.0)
+- Scratch 2 SVG proof-of-concept, shapes & filters by [as-com](https://github.com/as-com)
+- Anna helped with a formula, and pointed out that tjvr can't read graphs
+- JSO designed the syntax and wrote the original [Block Plugin](https://en.scratch-wiki.info/wiki/Block_Plugin_\(1.4\))
+- Help with translation code from [joooni](https://scratch.mit.edu/users/joooni/)
+- Block translations from the [scratch-l10n repository](https://github.com/scratchfoundation/scratch-l10n/)
+- Ported to node by [arve0](https://github.com/arve0)