Matrix & Treemap Extensions
Relevant source files
The following files were used as context for generating this wiki page:
The Matrix and Treemap extensions are specialized chart types provided by external Chart.js plugins and integrated into the vitepress-plugin-chartjs ecosystem. These extensions allow for the visualization of complex datasets, such as heatmaps, correlation matrices, and hierarchical nested structures, directly within VitePress documentation using simple YAML or JSON code blocks.
Sources: example/charts/matrix.md:1-5, example/charts/treemap.md:1-5, README.md:14-16
Integration and Registration
Because vitepress-plugin-chartjs is plugin-agnostic, these extended chart types must be registered within the VitePress theme's enhanceApp hook. This ensures that the specific controllers and elements required for Matrix and Treemap rendering are available on the client side.
Registration Workflow
The following diagram illustrates how external chart extensions are registered within the VitePress application lifecycle.
The registration process involves checking for the window object to remain SSR-safe, importing the base Chart object, and then registering specific components from packages like chartjs-chart-matrix or chartjs-chart-treemap.
Sources: example/plugins/setup.md:6-18, example/charts/matrix.md:10-23, example/charts/treemap.md:10-23
Matrix Charts
Matrix charts are designed to display data in a grid format, which is useful for heatmaps and correlation matrices. Each data point is defined by its x and y coordinates within the grid.
Matrix Data Structure
Matrix data points typically contain x (column), y (row), and v (value) properties. The value v is often used to determine the cell's background color or tooltip information.
Sources: example/charts/matrix.md:210-218
Configuration Parameters
The Matrix extension introduces specific dataset options for cell sizing and styling.
| Option | Type | Description |
|---|---|---|
width | pixels | Fixed width of a matrix cell |
height | pixels | Fixed height of a matrix cell |
borderRadius | pixels | Radius for rounded corners on cells |
borderWidth | pixels | Width of the border around cells |
Sources: example/charts/matrix.md:220-235
Scaling and Orientation
Matrix charts often require specific scale configurations to align the grid correctly. Linear scales are frequently used with specific min and max offsets (e.g., 0.5 offset) to ensure cells are centered on grid lines.
Sources: example/charts/matrix.md:52-65, example/charts/matrix.md:237-251
Treemap Charts
Treemaps visualize hierarchical data using nested rectangles. The area of each rectangle is proportional to its value, and the structure represents parent-child relationships.
Hierarchical Data Flow
Treemaps can process data in two primary formats: simple arrays or grouped objects.
For grouped data, the key property identifies the numerical value, while the groups array defines the levels of hierarchy.
Sources: example/charts/treemap.md:173-186
Treemap Dataset Options
| Component | Option | Description |
|---|---|---|
| General | tree | The data source (array or objects) |
| Grouping | groups | Properties used to define nested levels |
| Styling | spacing | Gap between rectangles in pixels |
| Labels | labels | Config for displaying text inside rectangles |
| Captions | captions | Labels specifically for group headers |
| Dividers | dividers | Lines separating hierarchical groups |
Sources: example/charts/treemap.md:190-236
Label Management
Treemaps provide complex label positioning options to handle nested text, including overflow settings like cut, hidden, or fit to ensure readability within constrained rectangle sizes.
Sources: example/charts/treemap.md:213-221
Technical Implementation Details
Both extensions leverage the build-time resolution of vitepress-plugin-chartjs. While the configuration is written in Markdown (YAML/JSON), the plugin resolves any external URLs or JavaScript modules at build time.
chart Block
BP->>BP: Parse YAML/JSON
BP->>BP: Resolve URL/JS (if present)
BP->>BP: Apply Default Colors/Options
BP-->>CL: Pre-computed JSON Config
CL->>CL: IntersectionObserver triggers
CL->>CL: Chart.js renders with Extension
Sources: [README.md:143-152](https://github.com/s00d/vitepress-plugin-chartjs/blob/HEAD/README.md#L143-L152), [src/markdown/index.ts:167-180](https://github.com/s00d/vitepress-plugin-chartjs/blob/HEAD/src/markdown/index.ts#L167-L180)
## Summary
The Matrix and Treemap extensions significantly expand the visualization capabilities of `vitepress-plugin-chartjs` beyond standard line and bar charts. By registering these external plugins in the VitePress theme and utilizing specialized dataset properties like `tree`, `groups`, and grid coordinates, developers can create dense, informative data visualizations directly within their documentation.
Sources: [example/api.md:90-105](https://github.com/s00d/vitepress-plugin-chartjs/blob/HEAD/example/api.md#L90-L105), [example/charts/matrix.md:255-257](https://github.com/s00d/vitepress-plugin-chartjs/blob/HEAD/example/charts/matrix.md#L255-L257), [example/charts/treemap.md:240-242](https://github.com/s00d/vitepress-plugin-chartjs/blob/HEAD/example/charts/treemap.md#L240-L242)Assistant: <sup><details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [example/charts/matrix.md](https://github.com/s00d/vitepress-plugin-chartjs/blob/HEAD/example/charts/matrix.md)
- [example/charts/treemap.md](https://github.com/s00d/vitepress-plugin-chartjs/blob/HEAD/example/charts/treemap.md)
- [example/plugins/setup.md](https://github.com/s00d/vitepress-plugin-chartjs/blob/HEAD/example/plugins/setup.md)
- [README.md](https://github.com/s00d/vitepress-plugin-chartjs/blob/HEAD/README.md)
- [example/api.md](https://github.com/s00d/vitepress-plugin-chartjs/blob/HEAD/example/api.md)
- [src/config.ts](https://github.com/s00d/vitepress-plugin-chartjs/blob/HEAD/src/config.ts)
</details>
The Matrix and Treemap extensions are specialized chart types provided by external Chart.js plugins and integrated into the `vitepress-plugin-chartjs` ecosystem. These extensions allow for the visualization of complex datasets, such as heatmaps, correlation matrices, and hierarchical nested structures, directly within VitePress documentation using simple YAML or JSON code blocks.
Sources: [example/charts/matrix.md:1-5](https://github.com/s00d/vitepress-plugin-chartjs/blob/HEAD/example/charts/matrix.md#L1-L5), [example/charts/treemap.md:1-5](https://github.com/s00d/vitepress-plugin-chartjs/blob/HEAD/example/charts/treemap.md#L1-L5), [README.md:14-16](https://github.com/s00d/vitepress-plugin-chartjs/blob/HEAD/README.md#L14-L16)
## Integration and Registration
Because `vitepress-plugin-chartjs` is plugin-agnostic, these extended chart types must be registered within the VitePress theme's `enhanceApp` hook. This ensures that the specific controllers and elements required for Matrix and Treemap rendering are available on the client side.
### Registration Workflow
The following diagram illustrates how external chart extensions are registered within the VitePress application lifecycle.
The registration process involves checking for the window object to remain SSR-safe, importing the base Chart object, and then registering specific components from packages like chartjs-chart-matrix or chartjs-chart-treemap.
Sources: example/plugins/setup.md:6-18, example/charts/matrix.md:10-23, example/charts/treemap.md:10-23
Matrix Charts
Matrix charts are designed to display data in a grid format, which is useful for heatmaps and correlation matrices. Each data point is defined by its x and y coordinates within the grid.
Matrix Data Structure
Matrix data points typically contain x (column), y (row), and v (value) properties. The value v is often used to determine the cell's background color or tooltip information.
Sources: example/charts/matrix.md:210-218
Configuration Parameters
The Matrix extension introduces specific dataset options for cell sizing and styling.
| Option | Type | Description |
|---|---|---|
width | pixels | Fixed width of a matrix cell |
height | pixels | Fixed height of a matrix cell |
borderRadius | pixels | Radius for rounded corners on cells |
borderWidth | pixels | Width of the border around cells |
Sources: example/charts/matrix.md:220-235
Scaling and Orientation
Matrix charts often require specific scale configurations to align the grid correctly. Linear scales are frequently used with specific min and max offsets (e.g., 0.5 offset) to ensure cells are centered on grid lines.
Sources: example/charts/matrix.md:52-65, example/charts/matrix.md:237-251
Treemap Charts
Treemaps visualize hierarchical data using nested rectangles. The area of each rectangle is proportional to its value, and the structure represents parent-child relationships.
Hierarchical Data Flow
Treemaps can process data in two primary formats: simple arrays or grouped objects.
For grouped data, the key property identifies the numerical value, while the groups array defines the levels of hierarchy.
Sources: example/charts/treemap.md:173-186
Treemap Dataset Options
| Component | Option | Description |
|---|---|---|
| General | tree | The data source (array or objects) |
| Grouping | groups | Properties used to define nested levels |
| Styling | spacing | Gap between rectangles in pixels |
| Labels | labels | Config for displaying text inside rectangles |
| Captions | captions | Labels specifically for group headers |
| Dividers | dividers | Lines separating hierarchical groups |
Sources: example/charts/treemap.md:190-236
Label Management
Treemaps provide complex label positioning options to handle nested text, including overflow settings like cut, hidden, or fit to ensure readability within constrained rectangle sizes.
Sources: example/charts/treemap.md:213-221
Technical Implementation Details
Both extensions leverage the build-time resolution of vitepress-plugin-chartjs. While the configuration is written in Markdown (YAML/JSON), the plugin resolves any external URLs or JavaScript modules at build time.
chart block
Build->>Build: Parse Configuration
Build->>Build: Apply Defaults & Colors
Build-->>Client: Embedded JSON Config
Client->>Client: Initialize Extension Plugins
Client->>Client: Render Canvas when Visible
Sources: [README.md:143-152](https://github.com/s00d/vitepress-plugin-chartjs/blob/HEAD/README.md#L143-L152), [example/api.md:135-141](https://github.com/s00d/vitepress-plugin-chartjs/blob/HEAD/example/api.md#L135-L141)
## Summary
The Matrix and Treemap extensions significantly expand the visualization capabilities of `vitepress-plugin-chartjs` beyond standard line and bar charts. By registering these external plugins in the VitePress theme and utilizing specialized dataset properties like `tree`, `groups`, and grid coordinates, developers can create dense, informative data visualizations directly within their documentation.
Sources: [example/api.md:90-105](https://github.com/s00d/vitepress-plugin-chartjs/blob/HEAD/example/api.md#L90-L105), [example/charts/matrix.md:255-257](https://github.com/s00d/vitepress-plugin-chartjs/blob/HEAD/example/charts/matrix.md#L255-L257), [example/charts/treemap.md:240-242](https://github.com/s00d/vitepress-plugin-chartjs/blob/HEAD/example/charts/treemap.md#L240-L242)