Update docs

CHANGELOG.md

@@ -4,6 +4,8 @@ All notable changes to this project will be documented in this file, following t
 
 ## [Unreleased]
 
+-   BrushExtension
+
 ## [1.0.1] - 2024-07-04
 
 -   No changes since 0.10.0

docs/architecture.md

@@ -6,9 +6,9 @@ HeatmapComponent uses a modular architecture designed to provide flexible functi
 
 - [**State**](../src/heatmap-component/state.ts) class encapsulates the state of a heatmap instance. Synchronization of the heatmap instance and registered extensions is done by sharing the same State object. State also provides events that the extensions (and client code) can subscribe to.
 
-- [**Extensions**](../src/heatmap-component/extension.ts) are used to add behavior to a heatmap instance. Each extension describes how to create, register, update, and unregister a Behavior object. Flexibility is achieved through parameters, which can be set during the Behavior creation and updated later. Essential builtin extensions (Draw, Marker, Tooltip, Zoom) are implemented in [/src/heatmap-component/extensions](../src/heatmap-component/extensions/); users can implement custom extensions in a similar manner.
+- [**Extensions**](../src/heatmap-component/extension.ts) are used to add behavior to a heatmap instance. Each extension describes how to create, register, update, and unregister a Behavior object. Flexibility is achieved through parameters, which can be set during the Behavior creation and updated later. Essential builtin extensions (Draw, Marker, Tooltip, Zoom, Brush) are implemented in [/src/heatmap-component/extensions](../src/heatmap-component/extensions/); users can implement custom extensions in a similar manner.
 
-- [**Heatmap**](../src/heatmap-component/heatmap.ts) class represents the main entry point for users of the heatmap-component package. It extends HeatmapCore by registering essential builtin extensions (Draw, Marker, Tooltip, Zoom) and implementing useful public methods for interacting with heatmap instances.
+- [**Heatmap**](../src/heatmap-component/heatmap.ts) class represents the main entry point for users of the heatmap-component package. It extends HeatmapCore by registering essential builtin extensions (Draw, Marker, Tooltip, Zoom, Brush) and implementing useful public methods for interacting with heatmap instances.
 
 - [**heatmap-component.css**](../src/heatmap-component.css) defines styling for all parts of the heatmap component. Appearance of the heatmap can be customized by overriding the styles defined here. 
 

docs/customization.md

@@ -262,9 +262,37 @@ heatmap.setAlignment('left', 'top');
 
 ---
 
+## Brushing
+
+Brushing is the interactive specification of a two-dimensional region using a pointing gesture, such as by clicking and dragging the mouse. This interactive behavior is implemented via `BrushExtension` and can be turned on by the `setBrushing` method. Brushing events can be listened to via `events.brush`.
+
+### `setBrushing`
+
+This method is used to enable and customize brushing behavior.
+
+```ts
+setBrushing(params: Partial<BrushExtensionParams>): this
+
+// Example usage:
+heatmap.setBrushing({ enabled: true, snap: true, closeButton: true }); // Turn on brushing
+// Selected region will be snapped to the nearest column and row boundary when mouse button is released
+// "Close" button will be shown in the corner of the selected region
+
+heatmap.events.brush.subscribe(e => {
+    // Listen to brush selection changes
+    if (e.type === 'end') {
+        console.log('Selection completed:', e);
+    } else {
+        console.log('Selection in progress:', e);
+    }
+});
+```
+
+---
+
 ## Extension customization
 
-Each of the [builtin extensions](./architecture.md#extensions) (Draw, Marker, Tooltip, Zoom) has a set of parameters, initially set to their default values. The parameter values can be changed via `update` method.
+Each of the [builtin extensions](./architecture.md#extensions) (Draw, Marker, Tooltip, Zoom, Brush) has a set of parameters, initially set to their default values. The parameter values can be changed via `update` method.
 
 ```ts
 // Example usage:
@@ -273,7 +301,7 @@ heatmap.extensions.marker?.update({ freeze: true }); // Disable markers
 heatmap.extensions.marker?.update({ freeze: false, markerCornerRadius: 5 }); // Enable markers, with round corners
 ```
 
-Note: Some of the extension parameters are also exposed via other methods, e.g. `setVisualParams` or `setZooming`.
+Note: Some of the extension parameters are also exposed via other methods, e.g. `setVisualParams`, `setZooming`, `setBrushing`.
 
 ### Custom extensions
 

docs/events.md

@@ -6,6 +6,8 @@ HeatmapComponent provides several events that the users can subscribe to. All of
 
 -   `select`: Fires when the user selects/deselects a cell (e.g. by clicking on it). Subject value holds information about the selected cell.
 
+-   `brush`: Fires when the user selects/deselects a region by brushing (i.e. press mouse button, drag, release). Subject value holds information about the stage of brushing gesture (start/brush/end) and the selected region. Only fires when `BrushExtension` is enabled.
+
 -   `zoom`: Fires when the component is zoomed in or out, or panned (translated). Subject value is the same as what [`getZoom`](./customization.md#getZoom) returns.
 
 -   `resize`: Fires when the window is resized. Subject value is the size of the canvas in pixels.