feat(apollo-react): implement ApSankeyDiagram

[preston-bao]

Overview

This PR introduces a new ApSankeyDiagram component to the Apollo Design System for visualizing flow data. Sankey diagrams are ideal for showing how data moves through
different stages or processes, making them valuable for workflow execution flows, data pipelines, and process analytics.

Features

Core Functionality

• Interactive visualization with D3.js-powered Sankey layout algorithm
• Hover interactions with tooltips showing link metadata and node relationships
• Click handlers for both nodes and links (onNodeClick, onLinkClick)
• Responsive design with automatic container width detection
• Customizable styling with custom colors, node alignment, and spacing options

Design System Integration

• ✅ Follows Apollo component naming conventions (Ap* prefix)
• ✅ Uses design tokens from @uipath/apollo-core for consistent styling
• ✅ Material UI integration with styled() components and Popper for tooltips
• ✅ Complete TypeScript type definitions
• ✅ Comprehensive Storybook documentation (8 story examples)
• ✅ Unit tests with vitest
• ✅ Proper package.json exports for /visualizations path

Files Changed

• New component: ApSankeyDiagram.tsx (537 lines)
• Type definitions: ApSankeyDiagram.types.ts
• Tests: ApSankeyDiagram.test.tsx (8 test cases, all passing)
• Stories: ApSankeyDiagram.stories.tsx (8 examples)
• Documentation: visualizations/README.md
• Storybook config: Added visualizations section
• Package updates: Dependencies and exports

Usage Example

 import { ApSankeyDiagram } from '@uipath/apollo-react/visualizations';                                                                                                  
                                                                                                                                                                         
 <ApSankeyDiagram                                                                                                                                                        
   data={{                                                                                                                                                               
     nodes: [                                                                                                                                                            
       { id: 'start', label: 'All traces' },                                                                                                                             
       { id: 'successful', label: 'Successful' },                                                                                                                        
       { id: 'failed', label: 'Faulted' },                                                                                                                               
     ],                                                                                                                                                                  
     links: [                                                                                                                                                            
       { source: 'start', target: 'successful', value: 80, metadata: { 'Total jobs': 80 } },                                                                             
       { source: 'start', target: 'failed', value: 20, metadata: { 'Total jobs': 20 } },                                                                                 
     ],                                                                                                                                                                  
   }}                                                                                                                                                                    
   height={400}                                                                                                                                                          
   width="100%"                                                                                                                                                          
   onNodeClick={(node) => console.log('Clicked:', node)}                                                                                                                 
 />                                                         

Screen.Recording.2026-01-23.at.3.01.14.PM.mov

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
apollo-canvas	Ready	Preview, Comment	Jan 23, 2026 11:04pm
apollo-ui-react	Ready	Preview, Comment	Jan 23, 2026 11:04pm
apollo-vertex	Ready	Preview, Comment	Jan 23, 2026 11:04pm
apollo-wind	Ready	Preview, Comment	Jan 23, 2026 11:04pm

[github-actions]

🤖 AI Code Review (Claude)

⚠️ Automated Review: This is an AI-generated review. Use as guidance, not gospel.

Code Review: ApSankeyDiagram Component

Summary

This PR introduces a new ApSankeyDiagram component for visualizing flow data using D3.js Sankey diagrams. The implementation includes comprehensive TypeScript types, interactive features (hover tooltips, click handlers), styling integration with Apollo design tokens, tests, and Storybook documentation.

Code Quality

✅ Strengths

• Well-structured component: Clean separation of concerns with types file, main component, and tests
• Comprehensive TypeScript definitions: Strong typing throughout with proper D3 type extensions
• Good use of React patterns: Proper use of hooks (useMemo, useCallback, useEffect, useImperativeHandle)
• Accessibility considerations: ARIA labels and proper semantic SVG structure
• Responsive design: ResizeObserver for dynamic container sizing

⚠️ Issues to Address

1. Missing newlines at end of files (minor but should be consistent):

   # packages/apollo-react/src/index.ts
   - export * from './material';
   + export * from './material';
   
   # packages/apollo-react/src/material/components/index.ts
   - export * from './ap-sankey-diagram';
   + export * from './ap-sankey-diagram';

2. Storybook configuration formatting issue:

   # apps/storybook/.storybook/main.ts
   -    }
   +    },

3. Unused styled component parameter:

   // Line 44 in ApSankeyDiagram.tsx
   const StyledSankeyLink = styled('path')<{}>(({}) => ({

   Should be: const StyledSankeyLink = styled('path')({

4. Potential performance concern: The linkPaths useMemo recalculates all gradients and paths on any dependency change. Consider if this needs optimization for large datasets, though it's likely fine for typical use cases.

Security

✅ No security concerns identified

• Runtime component with proper event handling
• No unsafe operations or XSS vulnerabilities
• Proper sanitization through React's rendering
• D3 path generation is safe (no innerHTML or dangerouslySetInnerHTML)
• User callbacks are properly typed and invoked with controlled data

Type Safety

✅ Excellent type safety

• Comprehensive TypeScript definitions in ApSankeyDiagram.types.ts
• Proper extension of D3 types (ExtendedSankeyNode, ExtendedSankeyLink)
• Type guards and proper narrowing throughout
• All props properly typed with good JSDoc comments

Minor suggestion: The ExtendedSankeyNode and ExtendedSankeyLink interfaces could be exported if consumers need to work with the computed layout data, but this is not necessary for the current API.

Testing

✅ Good test coverage for a visualization component

The tests cover:

• Basic rendering
• Custom sizing and styling
• Accessibility features
• Callback props
• Ref forwarding
• Empty data handling

Note: As mentioned in the tests, full interaction testing would require D3 interaction testing, which is appropriately noted but not implemented. This is acceptable for visualization components where comprehensive E2E testing can be expensive.

Suggestion: Consider adding a test for the ResizeObserver behavior, though this may require additional test utilities.

Performance

✅ Good performance practices

• Proper use of useMemo for expensive computations (Sankey layout, paths, node data)
• useCallback for event handlers to prevent unnecessary re-renders
• ResizeObserver for efficient resize handling

⚠️ Minor considerations

1. Debouncing ResizeObserver: For very frequent resize events, consider debouncing:

   // Could add a debounce to prevent excessive recalculations during window resizing

   However, this is likely premature optimization for most use cases.

2. SVG rendering: For very large graphs (100+ nodes), consider virtualization or canvas rendering, but this is beyond scope for initial implementation.

Additional Observations

Playground App (No Test Requirements)

✅ The playground showcase (ApSankeyShowcase.tsx) properly demonstrates the component with multiple examples. No tests needed as per project guidelines.

Documentation

✅ Excellent demonstration with 6 different showcase sections covering:

• Simple flows
• Complex flows with metadata
• Custom colors
• Node alignment options
• Node sizing
• Interactive callbacks
• Multi-stage flows

Dependencies

✅ Appropriate D3 dependencies added:

• d3-sankey for the layout algorithm
• d3-scale and d3-scale-chromatic for color schemes
• Corresponding @types/* packages

Recommendation

APPROVE with minor fixes

The implementation is solid with good architecture, type safety, and testing. The identified issues are minor style/formatting problems that should be fixed but don't block functionality:

Required fixes before merge:

1. Add missing newlines at end of files (index.ts files)
2. Fix Storybook config formatting (trailing comma)
3. Remove unused styled component parameter

Optional improvements (can be done in future PRs):

1. Consider resize debouncing if performance issues arise with large datasets
2. Export extended D3 types if needed by consumers
3. Add ResizeObserver behavior tests

The component successfully integrates into the Apollo design system and provides a valuable visualization tool with proper accessibility, interactivity, and customization options.

---

This automated review is temporary for solo development. Will be replaced with human reviews once the team grows.

[github-actions]

✅ AI Review: Changes look good. Auto-approved by Claude AI.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 92f51de5ce

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[CalinaCristian]

need to export this in package.json as it's own entry check bellow comment actually

[CalinaCristian]

^ comments

[github-actions]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (PT)
apollo-canvas	🟢 Ready	Preview, Logs	Jan 26, 2026, 01:33:46 PM
apollo-ui-react	🟢 Ready	Preview, Logs	Jan 26, 2026, 01:32:30 PM
apollo-vertex	🟢 Ready	Preview, Logs	Jan 26, 2026, 01:31:57 PM
apollo-wind	🟢 Ready	Preview, Logs	Jan 26, 2026, 01:31:01 PM

[github-actions]

✅ AI Review: Changes look good. Auto-approved by Claude AI.

[github-actions]

⚠️ AI Review: Please review the concerns raised above before merging.

[github-actions]

✅ AI Review: Changes look good. Auto-approved by Claude AI.

[github-actions]

✅ AI Review: Changes look good. Auto-approved by Claude AI.

[github-actions]

✅ AI Review: Changes look good. Auto-approved by Claude AI.

[github-actions]

✅ AI Review: Changes look good. Auto-approved by Claude AI.