WB-192: misaligned port positions

.changeset/wb-192-stable-handle-y.md

@@ -0,0 +1,5 @@
+---
+'@workflowbuilder/sdk': patch
+---
+
+fix: stabilize horizontal port Y on built-in node templates so multi-line descriptions no longer shift the port and bend edges between adjacent nodes. Unifies `<NodePanel.Handles alignment>` selection through one helper across all four built-in templates and pins the resulting port to the NodeIcon's vertical center via a global CSS rule scoped to a SDK-owned anchor class. Also fixes a separate latent bug where `DecisionNodeTemplate` hardcoded `Position.Right` on the source handle instead of honoring `layoutDirection` (broke decision nodes in `DOWN` layout).

packages/sdk/src/features/diagram/handles/get-handles-alignment.ts

@@ -0,0 +1,23 @@
+import type { NodePanel } from '@synergycodes/overflow-ui';
+import type { ComponentProps } from 'react';
+
+import type { LayoutDirection } from '../../../node/common';
+
+// Source-of-truth: overflow-ui's `<NodePanel.Handles>` prop, so adding a new
+// alignment in overflow-ui surfaces here as a type error instead of silently
+// drifting.
+type HandlesAlignment = NonNullable<ComponentProps<typeof NodePanel.Handles>['alignment']>;
+
+// Unifies how built-in node templates choose the `alignment` prop they pass to
+// `<NodePanel.Handles>`, so the formula has one place to evolve instead of
+// being re-derived per template.
+//
+// This helper alone does NOT make ports align across nodes. The visual
+// stability of the resulting port Y depends on a companion global CSS rule in
+// `packages/sdk/src/index.css` (search WB-192): the formula picks 'header' for
+// horizontal flow, then the CSS pin anchors the port to the NodeIcon's
+// vertical center so multi-line descriptions don't shift it. Both layers must
+// stay in sync; removing either reintroduces the bug.
+export function getHandlesAlignment({ layoutDirection }: { layoutDirection: LayoutDirection }): HandlesAlignment {
+  return layoutDirection === 'RIGHT' ? 'header' : 'center';
+}

packages/sdk/src/features/diagram/nodes/ai-agent-node-template/ai-agent-node-template.tsx

@@ -12,6 +12,7 @@ import type { ItemOption } from '../../../../node/node-schema';
 import type { AiAgentTool } from '../../../json-form/types/controls';
 import { getHandleId } from '../../handles/get-handle-id';
 import { getHandlePosition } from '../../handles/get-handle-position';
+import { getHandlesAlignment } from '../../handles/get-handles-alignment';
 import { ConnectableItem } from '../components/connectable-item/connectable-item';
 import { SettingInfo } from './components/setting-info/setting-info';
 import { ToolInfo } from './components/tool-info/tool-info';
@@ -56,7 +57,7 @@ export const AiAgentNodeTemplate = memo(
 
     const iconElement = useMemo(() => <Icon name={icon} size="large" />, [icon]);
 
-    const handlesAlignment = layoutDirection === 'RIGHT' ? 'header' : 'center';
+    const handlesAlignment = getHandlesAlignment({ layoutDirection });
 
     return (
       <Collapsible>

packages/sdk/src/features/diagram/nodes/decision-node-template/decision-node-template.tsx

@@ -1,5 +1,5 @@
 import { NodeDescription, NodeIcon, NodePanel, Status } from '@synergycodes/overflow-ui';
-import { Handle, Position } from '@xyflow/react';
+import { Handle } from '@xyflow/react';
 import { memo, useMemo } from 'react';
 
 import { Icon } from '@workflow-builder/icons';
@@ -12,6 +12,7 @@ import type { DecisionBranch } from '../../../json-form/types/controls';
 import { OptionalNodeContent } from '../../../plugins-core/components/diagram/optional-node-content';
 import { getHandleId } from '../../handles/get-handle-id';
 import { getHandlePosition } from '../../handles/get-handle-position';
+import { getHandlesAlignment } from '../../handles/get-handles-alignment';
 import { BranchesContainer } from './components/branches-container';
 
 type Props = {
@@ -47,10 +48,11 @@ export const DecisionNodeTemplate = memo(
     const handleSourceId = getHandleId({ nodeId: id, handleType: 'source' });
 
     const handleTargetPosition = getHandlePosition({ direction: layoutDirection, handleType: 'target' });
+    const handleSourcePosition = getHandlePosition({ direction: layoutDirection, handleType: 'source' });
 
     const isCanvasNode = showHandles;
 
-    const handlesAlignment = layoutDirection === 'RIGHT' ? 'header' : 'center';
+    const handlesAlignment = getHandlesAlignment({ layoutDirection });
 
     return (
       <NodePanel.Root selected={selected} className={styles['decision-node']}>
@@ -70,7 +72,7 @@ export const DecisionNodeTemplate = memo(
         </NodePanel.Content>
         <NodePanel.Handles isVisible={isCanvasNode} alignment={handlesAlignment}>
           <Handle id={handleTargetId} position={handleTargetPosition} type="target" />
-          <Handle id={handleSourceId} position={Position.Right} type="source" />
+          <Handle id={handleSourceId} position={handleSourcePosition} type="source" />
         </NodePanel.Handles>
       </NodePanel.Root>
     );

packages/sdk/src/features/diagram/nodes/start-node-template/start-node-template.tsx

@@ -12,6 +12,7 @@ import { withOptionalComponentPlugins } from '../../../plugins-core/adapters/ada
 import { OptionalNodeContent } from '../../../plugins-core/components/diagram/optional-node-content';
 import { getHandleId } from '../../handles/get-handle-id';
 import { getHandlePosition } from '../../handles/get-handle-position';
+import { getHandlesAlignment } from '../../handles/get-handles-alignment';
 
 type StartNodeTemplateProps = {
   id: string;
@@ -47,17 +48,15 @@ const StartNodeTemplateComponent = memo(
 
     const iconElement = useMemo(() => <Icon name={icon} size="large" />, [icon]);
 
-    const hasContent = !!children;
-
-    const handlesAlignment = hasContent && layoutDirection === 'RIGHT' ? 'header' : 'center';
+    const handlesAlignment = getHandlesAlignment({ layoutDirection });
 
     return (
       <Collapsible>
         <NodePanel.Root selected={selected} className={styles['content']}>
           <NodePanel.Header>
             <NodeIcon icon={iconElement} />
             <NodeDescription label={label} description={description} />
-            {hasContent && <Collapsible.Button />}
+            {!!children && <Collapsible.Button />}
           </NodePanel.Header>
           <NodePanel.Content isVisible={isCanvasNode}>
             <OptionalNodeContent nodeId={id}>

packages/sdk/src/features/diagram/nodes/workflow-node-template/workflow-node-template.tsx

@@ -13,6 +13,7 @@ import { withOptionalComponentPlugins } from '../../../plugins-core/adapters/ada
 import { OptionalNodeContent } from '../../../plugins-core/components/diagram/optional-node-content';
 import { getHandleId } from '../../handles/get-handle-id';
 import { getHandlePosition } from '../../handles/get-handle-position';
+import { getHandlesAlignment } from '../../handles/get-handles-alignment';
 
 /**
  * Props for the editor's default workflow-node template. A custom node
@@ -73,17 +74,15 @@ const WorkflowNodeTemplateComponent = memo(
 
     const iconElement = useMemo(() => <Icon name={icon} size="large" />, [icon]);
 
-    const hasContent = !!children;
-
-    const handlesAlignment = hasContent && layoutDirection === 'RIGHT' ? 'header' : 'center';
+    const handlesAlignment = getHandlesAlignment({ layoutDirection });
 
     return (
       <Collapsible>
         <NodePanel.Root selected={selected} className={styles['content']}>
           <NodePanel.Header>
             <NodeIcon icon={iconElement} />
             <NodeDescription label={label} description={description} />
-            {hasContent && <Collapsible.Button />}
+            {!!children && <Collapsible.Button />}
           </NodePanel.Header>
           <NodePanel.Content isVisible={isCanvasNode}>
             <OptionalNodeContent nodeId={id}>