@lumina-study/graph

A React library for creating interactive tree node visualizations with React Flow integration.

Features

• 🎨 Customizable tree nodes with multiple visual styles
• 📱 Responsive design with mobile support
• 🔄 Collapsible submodules
• 🔍 Search term highlighting
• ♿ Accessible with ARIA attributes
• 🎯 RTL and LTR language support
• 🖱️ Interactive with click and keyboard navigation
• 📦 Tree-shakeable with TypeScript support

Installation

pnpm add @lumina-study/graph

Peer Dependencies

This library requires the following peer dependencies:

pnpm add react react-dom @xyflow/react

Usage

Basic Example

import { ReactFlow } from '@xyflow/react';
import { TreeNode } from '@lumina-study/graph';
import '@xyflow/react/dist/style.css';

const nodes = [
  {
    id: '1',
    type: 'treeNode',
    position: { x: 0, y: 0 },
    data: {
      label: 'Introduction to Mathematics',
      direction: 'ttb',
    },
  },
];

const nodeTypes = {
  treeNode: TreeNode,
};

function App() {
  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <ReactFlow nodes={nodes} nodeTypes={nodeTypes} />
    </div>
  );
}

With Submodules

const nodes = [
  {
    id: '1',
    type: 'treeNode',
    position: { x: 0, y: 0 },
    data: {
      label: 'Advanced Calculus',
      subModules: ['Derivatives', 'Integrals', 'Series'],
      direction: 'ttb',
      onToggleCollapse: (nodeId, collapsed) => {
        console.log(`Node ${nodeId} is ${collapsed ? 'collapsed' : 'expanded'}`);
      },
    },
  },
];

With Zoom Badge

const nodes = [
  {
    id: '1',
    type: 'treeNode',
    position: { x: 0, y: 0 },
    data: {
      label: 'Algebra',
      canZoom: true, // Shows "Zoom in" badge
      onClick: () => {
        console.log('Navigate to detailed view');
      },
    },
  },
];

The ZoomBadge component is also exported separately if you need to use it in custom components:

import { ZoomBadge } from '@lumina-study/graph';

// Use in your custom component
<div>
  <span>My Custom Node</span>
  <ZoomBadge />
</div>

API

TreeNodeData

interface TreeNodeData {
  readonly label: string;
  readonly subModules?: readonly string[];
  readonly onClick?: () => void;
  readonly onToggleCollapse?: (nodeId: string, collapsed: boolean) => void;
  readonly isCollapsed?: boolean;
  readonly isSelected?: boolean;
  readonly isHighlighted?: boolean;
  readonly searchTerm?: string;
  readonly language?: 'en' | 'he';
  readonly direction?: 'ltr' | 'rtl' | 'ttb';
  readonly style?: BlockStyleType;
  readonly type?: string;
  readonly canZoom?: boolean;
  readonly hasQuestions?: boolean;
  readonly disabled?: boolean;
}

BlockStyleType

type BlockStyleType =
  | 'complete'
  | 'normal'
  | 'inProgress'
  | 'quarterProgress'
  | 'halfProgress'
  | 'threeQuarterProgress';

Direction

type Direction = 'ltr' | 'rtl' | 'ttb';

Exported Components

• TreeNode - Main tree node component
• TreeNodeHandles - React Flow handles component
• TreeNodeHeader - Node header with label and controls
• TreeNodeSubmodules - Submodules display component
• CollapseButton - Collapse/expand button
• ZoomBadge - Zoom indicator badge (shown when canZoom: true)

Exported Utilities

• getNodeDimensions(isMobile: boolean) - Get node dimensions
• getHandlePositions(isVertical: boolean, dir: Direction) - Get handle positions
• getTreeNodeClassName(data: TreeNodeData) - Get CSS class names
• hasSubModules(data: TreeNodeData) - Check if node has submodules
• handleClick(event, onClick) - Handle click events
• handleKeyDown(event, onClick) - Handle keyboard events
• highlightText(text, searchTerm) - Highlight search terms
• getBlockIcon(style) - Get icon for block style

Exported Constants

• NODE_WIDTH_PX = 240 - Desktop node width
• NODE_HEIGHT_PX = 80 - Desktop node height
• MOBILE_NODE_WIDTH_PX = 180 - Mobile node width
• MOBILE_NODE_HEIGHT_PX = 120 - Mobile node height

Development

Install dependencies

pnpm install

Run Storybook

pnpm storybook

Run tests

pnpm test

Visual Testing

Visual regression testing is configured with Storybook Test Runner. See VISUAL_TESTING.md for details.

# Development mode (Storybook must be running)
pnpm test-storybook

# CI mode (builds and serves Storybook automatically)
pnpm test-storybook:ci

Build

pnpm build

Lint

pnpm lint

Type check

pnpm typecheck

Release

pnpm release

License

ISC