feat(apollo-react): expose caseFlowManifest + handle hover handlers

Surface manifest pieces needed by PO.Frontend's case-management canvas to
register `caseFlowManifest` (PR #720), wrap apollo's `BaseNode` in a thin
host-side `CaseBaseNode` renderer, provide the canvas mode that `BaseNode`
reads via `useBaseCanvasMode()`, and expose hover events on the source-handle
`+` add-button so hosts can mount a hover-preview affordance.

- Add `CaseFlow/index.ts` re-exporting the manifest pieces, and surface it
  via `components/index.ts`.
- Add `toolbarExtensions.design` (change-trigger-type) to the trigger
  manifest, mirroring flow-workbench's `triggerToolbarExtensions`.
- Mark the trigger's source handle as `showButton: true` so `BaseNode`
  draws the inline add-next-stage `+` button (host wires the click via
  `onHandleAction`).
- Re-export `BaseCanvasModeProvider` from the BaseCanvas barrel so hosts
  that don't use apollo's `BaseCanvas` (PO.Frontend has its own) can
  still satisfy `BaseNode`'s mode dependency.
- Plumb optional `onMouseEnter` / `onMouseLeave` callbacks through
  `HandleButton` → `ButtonHandle` → `ButtonHandlesBase` →
  `useButtonHandles` → `BaseNodeOverrideConfig.onHandleMouseEnter` /
  `onHandleMouseLeave`, with parallel `handle:mouseenter` /
  `handle:mouseleave` events on `canvasEventBus`. Hosts (e.g.
  PO.Frontend) use these to preview the to-be-created node when the
  cursor enters the `+`, then commit on `onHandleAction`.

Author: claude

packages/apollo-react/src/canvas/components/BaseCanvas/index.ts

@@ -2,6 +2,7 @@ export { BaseCanvas } from './BaseCanvas';
 export * from './BaseCanvas.constants';
 export * from './BaseCanvas.hooks';
 export * from './BaseCanvas.types';
+export * from './BaseCanvasModeProvider';
 export * from './CanvasBackground';
 export * from './CanvasProviders';
 export * from './CanvasThemeContext';

packages/apollo-react/src/canvas/components/BaseNode/BaseNode.test.tsx

@@ -1,4 +1,5 @@
 import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import type { Node, NodeProps } from '@uipath/apollo-react/canvas/xyflow/react';
 import { Position } from '@uipath/apollo-react/canvas/xyflow/react';
 import { describe, expect, it, vi } from 'vitest';
@@ -10,7 +11,13 @@ const DEFAULT_MANIFEST = {
 } as const;
 
 // Hoisted mocks — available inside vi.mock factories
-const { mockUpdateNode, mockHandleConfigs, mockManifest } = vi.hoisted(() => ({
+const {
+  mockUpdateNode,
+  mockHandleConfigs,
+  mockManifest,
+  mockUseButtonHandles,
+  mockOverrideConfig,
+} = vi.hoisted(() => ({
   mockUpdateNode: vi.fn(),
   mockHandleConfigs: { current: undefined as HandleGroupManifest[] | undefined },
   mockManifest: {
@@ -19,6 +26,9 @@ const { mockUpdateNode, mockHandleConfigs, mockManifest } = vi.hoisted(() => ({
       handleConfiguration: [],
     } as Record<string, unknown>,
   },
+  // biome-ignore lint/suspicious/noExplicitAny: hook receives a broad typed options object
+  mockUseButtonHandles: vi.fn() as any,
+  mockOverrideConfig: { current: {} as Record<string, unknown> },
 }));
 
 // xyflow is globally mocked in canvas-mocks.ts; extend with test-specific overrides.
@@ -50,13 +60,21 @@ vi.mock('../BaseCanvas/SelectionStateContext', () => ({
 vi.mock('../BaseCanvas/CanvasThemeContext', () => ({
   useCanvasTheme: () => ({ isDarkMode: false }),
 }));
-vi.mock('../ButtonHandle/useButtonHandles', () => ({ useButtonHandles: () => null }));
+vi.mock('../ButtonHandle/useButtonHandles', () => ({
+  useButtonHandles: (opts: unknown) => {
+    mockUseButtonHandles(opts);
+    return null;
+  },
+}));
 vi.mock('../ButtonHandle/SmartHandle', () => ({
   SmartHandle: () => null,
   SmartHandleProvider: ({ children }: { children: React.ReactNode }) => <>{children}</>,
 }));
 vi.mock('./BaseNodeConfigContext', () => ({
-  useBaseNodeOverrideConfig: () => ({ handleConfigurations: mockHandleConfigs.current }),
+  useBaseNodeOverrideConfig: () => ({
+    handleConfigurations: mockHandleConfigs.current,
+    ...mockOverrideConfig.current,
+  }),
 }));
 vi.mock('../../utils/adornment-resolver', () => ({ resolveAdornments: () => ({}) }));
 vi.mock('../../utils/toolbar-resolver', () => ({ resolveToolbar: () => undefined }));
@@ -122,8 +140,10 @@ const makeHandles = (position: Position, count: number): HandleGroupManifest[] =
 describe('BaseNode', () => {
   afterEach(() => {
     mockUpdateNode.mockClear();
+    mockUseButtonHandles.mockClear();
     mockHandleConfigs.current = undefined;
     mockManifest.current = { ...DEFAULT_MANIFEST };
+    mockOverrideConfig.current = {};
   });
 
   describe('Height computation', () => {
@@ -283,4 +303,38 @@ describe('BaseNode', () => {
       expect(screen.queryByText('M', { selector: '[aria-hidden="true"]' })).not.toBeInTheDocument();
     });
   });
+
+  // BaseNode forwards the consumer-facing `onHandleMouseEnter`/`onHandleMouseLeave`
+  // from `BaseNodeOverrideConfigProvider` into `useButtonHandles` as
+  // `handleMouseEnter`/`handleMouseLeave`. Trigger those by reaching into the
+  // captured hook arguments and invoking them with a synthetic payload.
+  describe('Handle hover handlers', () => {
+    it('forwards onHandleMouseEnter/onHandleMouseLeave overrides and fires with the payload', () => {
+      const onHandleMouseEnter = vi.fn();
+      const onHandleMouseLeave = vi.fn();
+      mockOverrideConfig.current = { onHandleMouseEnter, onHandleMouseLeave };
+
+      render(<BaseNode {...defaultProps} />);
+
+      expect(mockUseButtonHandles).toHaveBeenCalled();
+      const opts = mockUseButtonHandles.mock.calls.at(-1)?.[0] as {
+        handleMouseEnter?: (e: unknown) => void;
+        handleMouseLeave?: (e: unknown) => void;
+      };
+      expect(opts.handleMouseEnter).toBe(onHandleMouseEnter);
+      expect(opts.handleMouseLeave).toBe(onHandleMouseLeave);
+
+      const payload = {
+        handleId: 'output',
+        nodeId: 'test-node',
+        handleType: 'output',
+        position: Position.Right,
+      };
+      opts.handleMouseEnter?.(payload);
+      opts.handleMouseLeave?.(payload);
+
+      expect(onHandleMouseEnter).toHaveBeenCalledWith(payload);
+      expect(onHandleMouseLeave).toHaveBeenCalledWith(payload);
+    });
+  });
 });

packages/apollo-react/src/canvas/components/BaseNode/BaseNode.tsx

@@ -87,6 +87,8 @@ const BaseNodeComponent = (props: NodeProps<Node<BaseNodeData>>) => {
   // Read runtime configuration from context (provided by parent node components)
   const {
     onHandleAction: onHandleActionProp,
+    onHandleMouseEnter: onHandleMouseEnterProp,
+    onHandleMouseLeave: onHandleMouseLeaveProp,
     shouldShowAddButtonFn: shouldShowAddButtonFnProp,
     shouldShowButtonHandleNotchesFn: shouldShowButtonHandleNotchesFnProp,
     toolbarConfig: toolbarConfigProp,
@@ -480,6 +482,8 @@ const BaseNodeComponent = (props: NodeProps<Node<BaseNodeData>>) => {
     handleConfigurations,
     shouldShowHandles,
     handleAction,
+    handleMouseEnter: onHandleMouseEnterProp,
+    handleMouseLeave: onHandleMouseLeaveProp,
     nodeId: id,
     selected: selected ?? false,
     hovered: isHovered,

packages/apollo-react/src/canvas/components/BaseNode/BaseNodeConfigContext.tsx

@@ -1,7 +1,7 @@
 import { createContext, useContext } from 'react';
 import type { HandleGroupManifest } from '../../schema/node-definition';
 import type { ElementStatusValues } from '../../types/execution';
-import type { HandleActionEvent } from '../ButtonHandle/ButtonHandle';
+import type { HandleActionEvent, HandleMouseEvent } from '../ButtonHandle/ButtonHandle';
 import type { NodeToolbarConfig } from '../Toolbar';
 import type { FooterVariant, NodeAdornments } from './BaseNode.types';
 
@@ -20,6 +20,10 @@ import type { FooterVariant, NodeAdornments } from './BaseNode.types';
 export interface BaseNodeOverrideConfig {
   // Callbacks (Runtime Behavior)
   onHandleAction?: (event: HandleActionEvent) => void;
+  /** Fired when the cursor enters a source handle's inline add button. */
+  onHandleMouseEnter?: (event: HandleMouseEvent) => void;
+  /** Fired when the cursor leaves a source handle's inline add button. */
+  onHandleMouseLeave?: (event: HandleMouseEvent) => void;
   shouldShowAddButtonFn?: (opts: { showAddButton: boolean; selected: boolean }) => boolean;
   shouldShowButtonHandleNotchesFn?: (opts: {
     isConnecting: boolean;

packages/apollo-react/src/canvas/components/ButtonHandle/ButtonHandle.test.tsx

@@ -2,7 +2,8 @@ import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { Position } from '@uipath/apollo-react/canvas/xyflow/react';
 import { describe, expect, it, vi } from 'vitest';
-import type { ButtonHandleConfig } from './ButtonHandle';
+import { canvasEventBus } from '../../utils/CanvasEventBus';
+import type { ButtonHandleConfig, HandleMouseEvent } from './ButtonHandle';
 import { ButtonHandles } from './ButtonHandle';
 
 // Mock @xyflow/react Handle component
@@ -380,4 +381,138 @@ describe('ButtonHandles', () => {
       expect(handleElements[0]).toHaveStyle({ top: '60%' });
     });
   });
+
+  describe('Hover handlers', () => {
+    it('invokes onMouseEnter with the HandleMouseEvent payload and emits handle:mouseenter on the bus', async () => {
+      const user = userEvent.setup();
+      const onMouseEnter = vi.fn();
+      const busSpy = vi.fn();
+
+      const unsubscribe = canvasEventBus.on('handle:mouseenter', busSpy);
+
+      const handles: ButtonHandleConfig[] = [
+        {
+          id: 'handle1',
+          type: 'source',
+          handleType: 'output',
+          showButton: true,
+          onAction: vi.fn(),
+          onMouseEnter,
+        },
+      ];
+
+      render(
+        <ButtonHandles
+          handles={handles}
+          nodeId="test-node"
+          position={Position.Right}
+          selected={true}
+          visible={true}
+        />
+      );
+
+      const button = screen.getByRole('button');
+      await user.hover(button);
+
+      const expectedPayload: HandleMouseEvent = {
+        handleId: 'handle1',
+        nodeId: 'test-node',
+        handleType: 'output',
+        position: Position.Right,
+      };
+      expect(onMouseEnter).toHaveBeenCalledWith(expectedPayload);
+      expect(busSpy).toHaveBeenCalledWith(expect.objectContaining(expectedPayload));
+
+      unsubscribe();
+    });
+
+    it('invokes onMouseLeave with the HandleMouseEvent payload and emits handle:mouseleave on the bus', async () => {
+      const user = userEvent.setup();
+      const onMouseLeave = vi.fn();
+      const busSpy = vi.fn();
+
+      const unsubscribe = canvasEventBus.on('handle:mouseleave', busSpy);
+
+      const handles: ButtonHandleConfig[] = [
+        {
+          id: 'handle1',
+          type: 'source',
+          handleType: 'output',
+          showButton: true,
+          onAction: vi.fn(),
+          onMouseLeave,
+        },
+      ];
+
+      render(
+        <ButtonHandles
+          handles={handles}
+          nodeId="test-node"
+          position={Position.Right}
+          selected={true}
+          visible={true}
+        />
+      );
+
+      const button = screen.getByRole('button');
+      await user.hover(button);
+      await user.unhover(button);
+
+      const expectedPayload: HandleMouseEvent = {
+        handleId: 'handle1',
+        nodeId: 'test-node',
+        handleType: 'output',
+        position: Position.Right,
+      };
+      expect(onMouseLeave).toHaveBeenCalledWith(expectedPayload);
+      expect(busSpy).toHaveBeenCalledWith(expect.objectContaining(expectedPayload));
+
+      unsubscribe();
+    });
+
+    it('emits bus events even when no onMouseEnter/onMouseLeave callbacks are wired', async () => {
+      const user = userEvent.setup();
+      const enterSpy = vi.fn();
+      const leaveSpy = vi.fn();
+
+      const unsubscribeEnter = canvasEventBus.on('handle:mouseenter', enterSpy);
+      const unsubscribeLeave = canvasEventBus.on('handle:mouseleave', leaveSpy);
+
+      const handles: ButtonHandleConfig[] = [
+        {
+          id: 'handle1',
+          type: 'source',
+          handleType: 'output',
+          showButton: true,
+          onAction: vi.fn(),
+        },
+      ];
+
+      render(
+        <ButtonHandles
+          handles={handles}
+          nodeId="test-node"
+          position={Position.Right}
+          selected={true}
+          visible={true}
+        />
+      );
+
+      const button = screen.getByRole('button');
+      await user.hover(button);
+      await user.unhover(button);
+
+      const expectedPayload = {
+        handleId: 'handle1',
+        nodeId: 'test-node',
+        handleType: 'output',
+        position: Position.Right,
+      };
+      expect(enterSpy).toHaveBeenCalledWith(expect.objectContaining(expectedPayload));
+      expect(leaveSpy).toHaveBeenCalledWith(expect.objectContaining(expectedPayload));
+
+      unsubscribeEnter();
+      unsubscribeLeave();
+    });
+  });
 });

packages/apollo-react/src/canvas/components/ButtonHandle/ButtonHandle.tsx

@@ -22,6 +22,14 @@ export interface HandleActionEvent {
   originalEvent: React.MouseEvent;
 }
 
+/** Payload passed to `onMouseEnter` / `onMouseLeave` handlers on a button handle. */
+export interface HandleMouseEvent {
+  handleId: string;
+  nodeId: string;
+  handleType: HandleType;
+  position: Position;
+}
+
 type ButtonHandleProps = {
   id: string;
   nodeId: string;
@@ -40,6 +48,8 @@ type ButtonHandleProps = {
   index?: number; // 0-based index of this handle on the edge
   total?: number; // Total number of handles on this edge
   onAction?: (event: HandleActionEvent) => void;
+  onMouseEnter?: (event: HandleMouseEvent) => void;
+  onMouseLeave?: (event: HandleMouseEvent) => void;
   showNotches?: boolean;
   customPositionAndOffsets?: HandleConfigurationSpecificPosition;
   nodeWidth?: number;
@@ -63,6 +73,8 @@ const ButtonHandleBase = ({
   index = 0,
   total = 1,
   onAction,
+  onMouseEnter,
+  onMouseLeave,
   showNotches = true,
   customPositionAndOffsets,
   nodeWidth,
@@ -73,6 +85,26 @@ const ButtonHandleBase = ({
   const [isHovered, setIsHovered] = useState(false);
   const isVertical = position === Position.Top || position === Position.Bottom;
 
+  const handleButtonMouseEnter = useCallback(() => {
+    onMouseEnter?.({ handleId: id, nodeId, handleType, position: connectionPosition });
+    canvasEventBus.emit('handle:mouseenter', {
+      handleId: id,
+      nodeId,
+      handleType,
+      position: connectionPosition,
+    });
+  }, [id, nodeId, handleType, connectionPosition, onMouseEnter]);
+
+  const handleButtonMouseLeave = useCallback(() => {
+    onMouseLeave?.({ handleId: id, nodeId, handleType, position: connectionPosition });
+    canvasEventBus.emit('handle:mouseleave', {
+      handleId: id,
+      nodeId,
+      handleType,
+      position: connectionPosition,
+    });
+  }, [id, nodeId, handleType, connectionPosition, onMouseLeave]);
+
   // Calculate position along the edge for multiple handles
   // Use grid-aligned positions when node dimensions are available
   const positionPercent = useMemo(() => {
@@ -189,6 +221,8 @@ const ButtonHandleBase = ({
             labelVisible={visible}
             position={connectionPosition}
             onAction={handleButtonClick}
+            onMouseEnter={handleButtonMouseEnter}
+            onMouseLeave={handleButtonMouseLeave}
             handleRef={handleRef}
           />
         ) : null}
@@ -246,6 +280,8 @@ const ButtonHandleBase = ({
           labelVisible={visible}
           position={position}
           onAction={handleButtonClick}
+          onMouseEnter={handleButtonMouseEnter}
+          onMouseLeave={handleButtonMouseLeave}
           handleRef={handleRef}
           label={label}
           labelIcon={labelIcon}
@@ -335,6 +371,8 @@ export interface ButtonHandleConfig {
   /** Runtime visibility — controls opacity (e.g. connected handles stay visible). */
   showHandle?: boolean;
   onAction?: (event: HandleActionEvent) => void;
+  onMouseEnter?: (event: HandleMouseEvent) => void;
+  onMouseLeave?: (event: HandleMouseEvent) => void;
   customPositionAndOffsets?: HandleConfigurationSpecificPosition;
 }
 
@@ -425,6 +463,8 @@ const ButtonHandlesBase = ({
             visible={handleVisible}
             showButton={finalSelected && handleVisible && handle.showButton}
             onAction={handle.onAction}
+            onMouseEnter={handle.onMouseEnter}
+            onMouseLeave={handle.onMouseLeave}
             showNotches={showNotches}
             customPositionAndOffsets={customPositionAndOffsets}
             nodeWidth={nodeWidth}