@waysnx/ui-visualization

🤖 AI agents & LLMs: See LLM.md (shipped with this package) for a structured integration guide — OrgChart, Tree, Hierarchy with virtualization and zoom/pan.

Enterprise-grade visualization components for React.
Org charts, trees, hierarchies, and more — built on a high-performance engine with virtualization, zoom/pan, search, drag & drop, and full accessibility.

Installation

npm install @waysnx/ui-visualization

Import styles in your app entry:

import '@waysnx/ui-visualization/dist/index.css';

Quick Start

OrgChart

import { OrgChart } from '@waysnx/ui-visualization';
import '@waysnx/ui-visualization/dist/index.css';

const nodes = [
  { id: '1', label: 'Emma Johnson', subtitle: 'CEO' },
  { id: '2', label: 'Liam Anderson', subtitle: 'COO', parentId: '1' },
  { id: '3', label: 'Olivia Martinez', subtitle: 'CTO', parentId: '1' },
  { id: '4', label: 'Noah Williams', subtitle: 'CFO', parentId: '1' },
  { id: '5', label: 'Ava Thompson', subtitle: 'Ops Manager', parentId: '2' },
];

function App() {
  return (
    <OrgChart
      nodes={nodes}
      height="600px"
      onNodeClick={({ node }) => console.log(node)}
    />
  );
}

Tree

import { Tree } from '@waysnx/ui-visualization';

<Tree nodes={nodes} height="500px" />

Hierarchy

import { Hierarchy } from '@waysnx/ui-visualization';

<Hierarchy nodes={nodes} height="600px" showMiniMap showToolbar />

Components

| Component | Description | |---|---| | OrgChart | Full org chart with toolbar, search, minimap, drag & drop | | Hierarchy | Multi-level top-down hierarchy | | Tree | Expandable left-right tree | | TreeNode | Individual node — use for custom rendering | | Connector | SVG edge between two nodes | | MiniMap | Overview navigation panel | | Toolbar | Action toolbar (zoom, expand, export) | | SearchBox | Instant node search with prev/next navigation | | ZoomControls | Zoom in/out/fit buttons | | Legend | Color/symbol legend |

Hooks

| Hook | Description | |---|---| | useVisualization | Core engine — nodes, layout, expand/collapse | | useZoom | Zoom and pan state | | useSelection | Single, multiple, range selection | | useSearch | Search and highlight nodes | | useDragDrop | Drag & drop with custom drop rules | | useMiniMap | MiniMap viewport state | | useExport | Export as PNG / SVG / JSON | | useTheme | Light / dark / auto theme |

Engines

| Engine | Description | |---|---| | LayoutEngine | Computes node positions (top-down, left-right, radial, compact) | | VirtualizationEngine | Renders only visible nodes for 10K+ node performance | | SearchEngine | Fast full-text search with scoring and navigation | | ExportEngine | PNG, SVG, PDF (via jsPDF), JSON export |

Node Data Shape

interface VisNode {
  id: string;
  label: string;
  parentId?: string;       // links to parent for auto-layout
  subtitle?: string;       // job title, description, etc.
  avatarUrl?: string;      // profile image
  badge?: string | number; // badge text or count
  status?: 'online' | 'offline' | 'away' | 'busy';
  expanded?: boolean;      // expand/collapse state
  data?: Record<string, unknown>; // arbitrary metadata
}

Configuration

<OrgChart
  nodes={nodes}
  config={{
    layout: {
      direction: 'top-down',   // 'top-down' | 'left-right' | 'radial' | 'compact'
      nodeWidth: 220,
      nodeHeight: 80,
      nodeGapX: 40,
      nodeGapY: 60,
    },
    selection: 'multiple',     // 'single' | 'multiple' | 'range' | 'none'
    enableDragDrop: true,
    enableSearch: true,
    enableMiniMap: true,
    virtualize: true,
    virtualizeThreshold: 200,
    theme: 'auto',             // 'light' | 'dark' | 'auto'
  }}
/>

Custom Node Rendering

<OrgChart
  nodes={nodes}
  renderNode={(node) => (
    <div style={{ padding: 12 }}>
      <strong>{node.label}</strong>
      <p>{node.subtitle}</p>
    </div>
  )}
/>

Theming

All visual properties are CSS custom properties with --wx-vis- prefix:

:root {
  --wx-vis-node-bg: #ffffff;
  --wx-vis-node-border-radius: 12px;
  --wx-vis-edge-color: #cbd5e1;
  --wx-vis-status-online: #22c55e;
  /* ... see tokens.css for full list */
}

Accessibility

• Full keyboard navigation (Arrow keys, Enter, Space, Escape)
• ARIA roles: tree, treeitem, toolbar, search, navigation
• aria-selected, aria-expanded, aria-label on all interactive elements
• Focus visible outlines on all focusable elements
• WCAG 2.1 AA compliant

Performance

• Virtualization engine renders only visible nodes
• will-change: transform on the canvas transform layer
• Memoized layout computation via useMemo
• Tree structure built once and diffed on state changes

License

Apache License 2.0 © WaysNX Technologies Private Limited