scratch-blocks

This project uses semantic release and requires commit messages to follow the conventional-changelog specification. You can use the commitizen CLI to ensure your commits are formatted correctly.

npm install -g commitizen@latest cz-conventional-changelog@latest
git cz

The FieldMatrix is a specialized Blockly field designed for controlling 5x5 LED arrays. It displays a small thumbnail on the block and provides a dropdown editor where users can toggle individual nodes, fill the entire matrix, or clear it.

Data is stored as a string of 25 characters consisting of '1' (ON) and '0' (OFF).

To use this field in your blocks, you must first register it using registerFieldMatrix().

Browser tests run in Chromium via Playwright. After running npm ci, you must install the Chromium browser before running the tests.

To debug a failing browser test with a visible window, use the --browser.headless=false flag. To pause on startup and open devtools, set the PWDEBUG=1 environment variable.

npx playwright install chromium
npm run test:browser

# Debugging with visible browser
npm run test:browser -- --browser.headless=false

# Debugging with pause and devtools
PWDEBUG=1 npm run test:browser

When defining a block that uses FieldMatrix, provide a configuration object. The primary key is matrix, which accepts a string representing the 5x5 grid.

Configuration Keys:

• matrix: A string of 25 characters (e.g., '10101...').

Constants for Matrix Strings:

• FieldMatrix.ZEROS: A string of 25 '0' characters (clears the matrix).
• FieldMatrix.ONES: A string of 25 '1' characters (fills the matrix).

The ScratchZoomControls class implements Blockly.IPositionable and requires the following lifecycle management:

• createDom(): Returns the root SVGGElement containing the zoom buttons. These buttons load SVG assets from ${workspace.options.pathToMedia}zoom-out.svg, ${workspace.options.pathToMedia}zoom-in.svg, and ${workspace.options.pathToMedia}zoom-reset.svg.
• init(): Registers the component with the workspace's ComponentManager with a weight of 2 and POSITIONABLE capability.
• position(metrics, savedPositions): Calculates and applies the SVG transform to place the controls in the corner opposite the toolbox, ensuring they do not overlap other UI elements.
• dispose(): Removes the component from the ComponentManager, removes the DOM nodes, and unbinds all pointer events.

The ScratchZoomControls class provides a specialized UI component for managing workspace zoom levels. Unlike standard Blockly zoom controls, it uses individual SVG files for each button (zoom-in, zoom-out, and zoom-reset) loaded from the workspace's pathToMedia option. This allows for different icon designs based on color modes (e.g., high-contrast).

To use it, instantiate the class with a Blockly.WorkspaceSvg and call its lifecycle methods (createDom, init, position, and dispose) as part of your workspace setup.

The FieldNote class is a specialized text input field designed for selecting musical notes via a piano-key interface. It extends Blockly.FieldTextInput and allows users to interact with a visual piano to select MIDI note numbers.

When initialized, it provides a visual editor with piano keys and octave controls. You can customize the audio feedback by overriding the static playNote_ method.

Use the inject function to initialize a Scratch Blocks workspace within a DOM element. This function automatically registers all Scratch-specific fields, plugins (like ScratchContinuousToolbox and CheckableContinuousFlyout), and configures the renderer based on the provided scratchTheme.

Supported themes:

• ScratchBlocksTheme.CAT_BLOCKS: Uses the cat-shaped block renderer.
• ScratchBlocksTheme.CLASSIC: Uses the classic block renderer (default if not specified).

Note: inject modifies the Blockly.config and registers several global Blockly behaviors to match Scratch's UX (e.g., drag radius, snap radius, and context menu overrides).