AI Сделал бесплатный опенсорс TreeMap для Angular

[AI]

Standalone TreeMap для Angular без лишних зависимостей: как я сделал stockchart-treemap


TreeMap — это визуализация, где площадь прямоугольника = вес, а цвет = метрика. Отлично подходит для market heatmap (карта рынка), портфелей, иерархий ресурсов и любых “взвешенных деревьев”.

Мне TreeMap понадобился в Angular-проекте под “тепловые карты” и разные иерархические отчёты. Казалось бы — задача стандартная, значит решение должно быть “в один npm install”. Но реальность оказалась неожиданной: готовых TreeMap-решений именно для Angular практически нет.

В итоге я сделал свой standalone компонент и оформил его в npm-пакет: stockchart-treemap.

Дисклеймер

• 
  Пакет бесплатный.
  
  
• 
  Это не реклама — мне никто не заплатил ни копейки.
  
  
• 
  Я делал компонент в первую очередь для своих задач, а потом упаковал так, чтобы можно было переиспользовать и не зависеть от внешних UI-комбайнов.
  

Почему не использовать готовое решение


Вот тут самое забавное: обычно в статьях пишут “не подошло потому что тяжелое/дорогое/не то API”. У меня было проще — мне просто не удалось найти нормальный готовый TreeMap под Angular.

Что я видел в процессе поисков:

1. 
   Почти всё — под чистый JS, React или Vue
   TreeMap как визуализация часто встречается в “JS-мире”: примеры на D3-подобных штуках, готовые виджеты, демки. Но это не Angular-компонент, а код, который сам рисует DOM/SVG/Canvas.
   

В Angular это превращается в вечную обвязку:

• 
  ElementRef, ngAfterViewInit, ручной lifecycle,
  
  
• 
  чистка при destroy,
  
  
• 
  ручные обновления при изменении данных,
  
  
• 
  танцы с change detection,
  
  
• 
  и “почему оно перерисовалось два раза/не там/не тогда”.
  

То есть формально “решение есть”, но по ощущениям это уже не “встроил компонент”, а “интегрировал чужой движок”.

1. 
   То, что называется “Angular TreeMap”, часто:
   

• 
  устаревшее (старые версии Angular, нет standalone),
  
  
• 
  или это тонкая обёртка над JS-ядром без нормального Angular UX (шаблоны, события, типизация, обновления данных — всё “на честном слове”).
  

1. 
   Есть варианты в составе больших UI-комбайнов
   Иногда это нормально, но лично мне не хотелось тащить “полплатформы” ради одного TreeMap. Особенно когда в проекте уже есть своя дизайн-система и свои компоненты.
   

Итог: формально решений много, но “поставил и получил нативный Angular-компонент с понятной интеграцией” — мне не попалось. Поэтому я решил сделать компонент так, как мне самому было бы удобно его использовать.

Что получилось: stockchart-treemap


stockchart-treemap — standalone TreeMap компонент для Angular:

• 
  без внешних runtime-зависимостей (никаких Kendo UI и т.п.),
  
  
• 
  с цветовой шкалой по значениям (min/center/max),
  
  
• 
  с кастомными шаблонами плиток и заголовков,
  
  
• 
  с несколькими режимами источника данных,
  
  
• 
  с событиями клика/ховера и “путём” до узла.
  

Демо


StackBlitz: https://stackblitz.com/edit/stackblitz-starters-drgync8z?file=README.md

Установка


npm install stockchart-treemap


Peer deps: @angular/core и @angular/common 20.x.

Быстрый старт


Пример “из коробки”: просто массив + настройки полей.

import { Component } from '@angular/core';
import { TreeMapComponent, TreeMapOptions } from 'stockchart-treemap';

@Component({
standalone: true,
selector: 'app-treemap-demo',
imports: [TreeMapComponent],
template: `
<stockchart-treemap
[data]="data"
[options]="options">
</stockchart-treemap>
`
})
export class TreemapDemoComponent {
data = [
{ name: 'Tech', value: 35, change: 4.2, items: [
{ name: 'A', value: 20, change: 5.1 },
{ name: 'B', value: 15, change: 2.0 }
]},
{ name: 'Energy', value: 25, change: -3.4 },
{ name: 'Health', value: 18, change: 1.6 }
];

options: Partial<TreeMapOptions> = {
textField: 'name',
valueField: 'value',
childrenField: 'items',

// цвет — по "change"
colorValueField: 'change',
colorScale: { min: '#E53935', center: '#F5F5F5', max: '#2E7D32' },

// оставляем пустым, чтобы полагаться на colorScale
colors: []
};
}

Источники данных: три режима, потому что в жизни по-разному


Визуализация — это всегда “последний метр” после данных. И данные могут приходить как угодно, поэтому я сделал три режима.

1) Обычный массив


Самый простой: [data]="data".

2) Observable


Если данные живые (RxJS-пайплайн, сокеты, периодические обновления на вашей стороне) — можно отдать data$, компонент подпишется и будет перерисовываться при новых значениях.

3) Loader-функция + polling


Иногда удобнее дать компоненту “как загрузить данные”, а он сам будет обновляться раз в N миллисекунд:

loader = () => this.http.get<Item[]>('/api/treemap');
refreshMs = 5000; // обновление каждые 5 секунд


Плюс есть refreshNow() — полезно для “обновить по кнопке” или после смены фильтров.

Цвета: палитра или шкала по значению


Мне нужны были оба сценария:

Палитра


Когда цвет — это категория (например, разные отделы/типы). Можно задать:

• 
  colors: ['#...', '#...', ...]
  
  
• 
  либо пары [min,max], чтобы генерировать градиенты по уровням.
  

Шкала по значению (heatmap)


Классика для “карты рынка”: у элемента есть метрика (например, change), и цвет вычисляется по шкале:

• 
  min — красный,
  
  
• 
  center — нейтральный,
  
  
• 
  max — зелёный.
  

Работает так:

• 
  задаём colorValueField,
  
  
• 
  задаём colorScale,
  
  
• 
  и получаем прогнозируемый градиент.
  

Если у данных вообще нет цветового поля — оттенки для вложенных уровней считаются автоматически, чтобы дерево было читабельным.

Layout-ы: squarified и slice-and-dice


Я сделал два варианта разметки:

• 
  squarified (по умолчанию) — стремится к “квадратности” плиток, обычно выглядит лучше.
  
  
• 
  horizontal / vertical — slice-and-dice, нарезка полосами с чередованием ориентации по уровням.
  

Это покрывает большую часть практических кейсов без превращения компонента в “комбайн настроек”.

Кастомные шаблоны: плитка и заголовок


TreeMap без нормальных шаблонов быстро превращается в “красивую мозаику”, из которой нельзя извлечь смысл.

Можно задать отдельно:

• 
  titleTemplate — заголовок контейнеров,
  
  
• 
  tileTemplate — содержимое плитки (обычно лист).
  

Пример:

<stockchart-treemap
[data]="data"
[options]="options"
[tileTemplate]="tile"
[titleTemplate]="title"
(tileClick)="onTile($event)">
</stockchart-treemap>

<ng-template #title let-item let-node="node">
<div class="title">
{{ item.name }} · {{ node.value | number:'1.0-0' }}
</div>
</ng-template>

<ng-template #tile let-item let-isLeaf="isLeaf">
<div class="tile">
<strong>{{ item.name }}</strong>
<span *ngIf="isLeaf">{{ item.change }}%</span>
</div>
</ng-template>

События и “путь” до узла


В интерактивных сценариях важно не только “что кликнули”, но и “где это в дереве”.

Поэтому в событиях есть:

• 
  dataItem — исходный объект,
  
  
• 
  path — цепочка элементов от корня до выбранной ноды.
  

import { TreeMapEvent } from 'stockchart-treemap';

onTile(ev: TreeMapEvent<MyNode>) {
console.log(ev.dataItem);
console.log(ev.path); // полезно для breadcrumbs / drilldown
}

Ключевые опции


То, что реально используется чаще всего:

• 
  textField / valueField / childrenField / colorField
  
  
• 
  colorValueField — поле для расчёта colorScale
  
  
• 
  colors — палитра (если пусто — можно полагаться на colorScale или fallback)
  
  
• 
  titleSize, showTopLevelTitles
  
  
• 
  deriveParentValueFromChildren — если у контейнера нет value, можно вывести из детей
  
  
• 
  roundDecimals — помогает стабилизировать координаты
  
  
• 
  minTileSize — минимальный размер плитки для рекурсии
  

Немного про “как я делал”


Я сознательно старался избежать “магии”. Внутри всё раскладывается по шагам:

1. 
   Нормализация данных (любой источник → массив нод).
   
   
2. 
   Подсчёт значений (в т.ч. вычисление контейнеров из детей — опционально).
   
   
3. 
   Layout (squarified / slice-and-dice) рекурсивно разбивает прямоугольник.
   
   
4. 
   Цвет (палитра или интерполяция по шкале).
   
   
5. 
   Рендер + шаблоны + события.
   

На практике это даёт главное: предсказуемость и возможность легко встроить компонент в проект, не подстраиваясь под чужие решения.

Где это полезно

• 
  Market heatmap: сектор → индустрия → компания (площадь = вес, цвет = % change).
  
  
• 
  Портфель: активы → позиции (площадь = доля, цвет = PnL).
  
  
• 
  Ресурсы: департаменты → проекты → сервисы (площадь = расходы/нагрузка, цвет = отклонение).
  
  
• 
  Любые метрики в дереве: storage usage, распределение задач, coverage, KPI и т.д.
  

Ограничения


Если попытаться отображать десятки тысяч нод одновременно — DOM начнёт страдать (как и у большинства UI-визуализаций). Этот компонент рассчитан на нормальные продуктовые сценарии, а не на экстремальные бенчмарки.

Если когда-нибудь понадобится “очень много элементов” — это уже территория Canvas/WebGL/виртуализации.

Заключение


stockchart-treemap появился из простой причины: TreeMap для Angular почему-то оказался редкостью, а интегрировать JS-виджеты “как есть” в Angular — это отдельный проект по обвязке.

Я сделал standalone компонент, который ставится из npm, нормально живёт в Angular, поддерживает разные источники данных, цветовые шкалы и кастомные шаблоны.

Демо: https://stackblitz.com/edit/stackblitz-starters-drgync8z?file=README.md
Пакет: npm install stockchart-treemap