Visual Linker

npm install @macrulez/visual-linker-core

01 — Назначение

Когда это пригодится

Связи между произвольными блоками интерфейса — карта процесса, диаграмма сущностей, визуализация зависимостей — обычно означают либо тяжёлый движок диаграмм со своей системой узлов, либо самописную отрисовку SVG-путей поверх обычной вёрстки, с ручным пересчётом координат при каждом ресайзе и скролле. Visual Linker берёт на себя только эту механику, оставляя разметку и позиционирование блоков полностью вашими.

Блок-схема процесса из обычных карточек

Этапы согласования, воронка продаж, пайплайн обработки заявки — каждый этап уже верстается как обычный компонент. Линии между карточками прокладываются автоматически, с выбором стороны выхода/входа и без пересечения самих блоков, а при изменении размера окна или скролле контейнера пересчитываются сами.

Диаграмма зависимостей между узлами интерфейса

Связи между сущностями — компонентами системы, шагами сценария, узлами графа — нужно показать без написания собственного SVG-рендерера путей. Два типа кривых (bezier и ортогональный smoothstep с учётом групповых точек ветвления) покрывают как мягкие, так и строго прямоугольные схемы.

Интерактивная схема с перетаскиванием блоков

Пользователь двигает блоки мышью, а линии между ними должны следовать за ними в реальном времени, сохраняя автоматический выбор стороны подключения. Drag & drop блоков, наведение и клик по самой линии соединения — уже готовая часть API, с типизированными событиями.

Единообразный стиль соединений в дизайн-системе продукта

У каждой линии может быть свой цвет, толщина, пунктир, маркеры начала/конца (готовые формы или произвольный SVG) и отдельный стиль при наведении — оформление связей настраивается так же детально, как оформление самих блоков.

02 — Фичи

Коротко о главном

Автоматический выбор стороны подключения

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

Bezier и ортогональный smoothstep

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

Перетаскивание блоков и события соединений

Блоки можно двигать мышью, линии следуют за ними сами. Наведение и клик по соединению доступны через типизированный API событий — никакой ручной работы с координатами курсора и геометрией пути.

Стилизация каждого соединения по отдельности

Цвет, толщина, пунктир, маркеры начала и конца — встроенные формы или произвольный SVG — и отдельный стиль при наведении, задаются индивидуально для любой линии.

Реакция на resize и scroll из коробки

Линии сами пересчитываются при изменении размеров блоков, окна или прокрутке контейнера — без подписки на события вручную в коде приложения.

Компонент, композабл и Nuxt-модуль

Framework-agnostic движок с адаптером под Vue 3 — компонент <VisualLinker> вокруг вашей собственной разметки и композабл useVisualLinker(), плюс Nuxt-модуль с автоимпортами и настройками кривой/портов по умолчанию на уровне конфига.

03 — Быстрый пример

Как это работает

Автоматически проложенная линия между двумя блоками

createVisualLinker(container) измеряет блоки, переданные через setBlocks(), и рисует SVG-путь между ними — без ручной геометрии и без Vue.

basic.ts
import { createVisualLinker } from '@macrulez/visual-linker-core'

const container = document.querySelector('#diagram') as HTMLElement
const linker = createVisualLinker(container)

linker.setBlocks([
  { id: 'a', el: document.querySelector('#block-a') as HTMLElement },
  { id: 'b', el: document.querySelector('#block-b') as HTMLElement },
])
linker.setConnections([{ id: 'a-b', from: { blockId: 'a' }, to: { blockId: 'b' } }])

Ортогональная трассировка и стрелка

style соединения имеет ту же форму, что группа lines конфигурации: тип кривой, маркер и вид для каждого состояния — здесь линия толще, а стрелка крупнее при hover.

styling.ts
linker.setConnections([
  {
    id: 'a-b',
    from: { blockId: 'a' },
    to: { blockId: 'b' },
    style: {
      curve: 'smoothstep',
      color: '#6366f1',
      hover: { width: 3 },
      markers: { end: { shape: 'arrow', hover: { size: 10 } } },
    },
  },
])