feat: link existing screens as state variants via drag connection (#16)

When dragging a connection from one screen to another, a popup now asks
the user to choose between "Navigate" (creates a navigation connection)
and "State Variant" (links the target screen into the source's state
group). This enables users to assign existing screens as state variants
without having to create new blank screens.

Co-authored-by: Quang Tran <16215255+trmquang93@users.noreply.github.com>

Author: trmquang93

src/Drawd.jsx

@@ -49,7 +49,7 @@ export default function Drawd({ initialRoomCode }) {
     updateScreenDescription, updateScreenNotes, updateScreenTbd, updateScreenRoles, updateScreenCodeRef, updateScreenCriteria, assignScreenImage, patchScreenImage, quickConnectHotspot,
     updateConnection, deleteConnection,
     addConnection, convertToConditionalGroup, addToConditionalGroup, saveConnectionGroup, deleteConnectionGroup,
-    addState, updateStateName, addDocument, updateDocument, deleteDocument,
+    addState, linkAsState, updateStateName, addDocument, updateDocument, deleteDocument,
     replaceAll, mergeAll,
     canUndo, canRedo, undo, redo, captureDragSnapshot, commitDragSnapshot,
     updateScreenStatus, markAllExisting,
@@ -174,16 +174,19 @@ export default function Drawd({ initialRoomCode }) {
   const connInteraction = useConnectionInteraction({
     screens, connections, canvasRef, pan, zoom,
     addConnection, addToConditionalGroup, convertToConditionalGroup,
+    linkAsState,
   });
 
   const {
     connecting, setConnecting, cancelConnecting,
     hoverTarget, setHoverTarget,
     selectedConnection, setSelectedConnection,
     conditionalPrompt, setConditionalPrompt,
+    connectionTypePrompt, setConnectionTypePrompt,
     editingConditionGroup, setEditingConditionGroup,
     onDotDragStart, onStartConnect,
     onConditionalPromptConfirm, onConditionalPromptCancel,
+    onConnectionTypeNavigate, onConnectionTypeStateVariant,
   } = connInteraction;
 
   const hsInteraction = useHotspotInteraction({
@@ -218,6 +221,7 @@ export default function Drawd({ initialRoomCode }) {
     hotspotInteraction, setHotspotInteraction,
     setSelectedConnection, setHoverTarget,
     setConditionalPrompt, setEditingConditionGroup,
+    setConnectionTypePrompt,
     setHotspotModal, setConnectionEditModal,
     quickConnectHotspot, addConnection, addToConditionalGroup,
     onStartConnect,
@@ -468,6 +472,9 @@ export default function Drawd({ initialRoomCode }) {
           conditionalPrompt={conditionalPrompt}
           onConditionalPromptConfirm={onConditionalPromptConfirm}
           onConditionalPromptCancel={onConditionalPromptCancel}
+          connectionTypePrompt={connectionTypePrompt}
+          onConnectionTypeNavigate={onConnectionTypeNavigate}
+          onConnectionTypeStateVariant={onConnectionTypeStateVariant}
           collab={collab}
           editingConditionGroup={editingConditionGroup}
           updateConnection={updateConnection}

src/components/CanvasArea.jsx

@@ -3,6 +3,7 @@ import { DEFAULT_SCREEN_WIDTH, DEFAULT_SCREEN_HEIGHT } from "../constants";
 import { ScreenNode } from "./ScreenNode";
 import { ConnectionLines } from "./ConnectionLines";
 import { ConditionalPrompt } from "./ConditionalPrompt";
+import { ConnectionTypePrompt } from "./ConnectionTypePrompt";
 import { InlineConditionLabels } from "./InlineConditionLabels";
 import { SelectionOverlay } from "./SelectionOverlay";
 import { EmptyState } from "./EmptyState";
@@ -41,6 +42,8 @@ export function CanvasArea({
   repositionGhost,
   // Conditional prompt
   conditionalPrompt, onConditionalPromptConfirm, onConditionalPromptCancel,
+  // Connection type prompt
+  connectionTypePrompt, onConnectionTypeNavigate, onConnectionTypeStateVariant,
   // Collaboration
   collab,
   // Inline condition labels
@@ -53,13 +56,18 @@ export function CanvasArea({
   return (
     <div
       ref={canvasRef}
-      onMouseDown={onCanvasMouseDown}
+      onMouseDown={(e) => {
+        if (connectionTypePrompt) { onConnectionTypeNavigate(); return; }
+        onCanvasMouseDown(e);
+      }}
       onMouseMove={onCanvasMouseMove}
       onMouseUp={onCanvasMouseUp}
       onMouseLeave={onCanvasMouseLeave}
       onDragOver={(e) => e.preventDefault()}
       onDrop={onCanvasDrop}
-      onClick={() => { if (groupContextMenu) setGroupContextMenu(null); }}
+      onClick={() => {
+        if (groupContextMenu) setGroupContextMenu(null);
+      }}
       onDoubleClick={(e) => {
         if (e.target !== canvasRef.current) return;
         const rect = canvasRef.current.getBoundingClientRect();
@@ -224,6 +232,14 @@ export function CanvasArea({
             onCancel={onConditionalPromptCancel}
           />
         )}
+        {connectionTypePrompt && (
+          <ConnectionTypePrompt
+            x={connectionTypePrompt.x}
+            y={connectionTypePrompt.y}
+            onNavigate={onConnectionTypeNavigate}
+            onStateVariant={onConnectionTypeStateVariant}
+          />
+        )}
         {collab.isConnected && <RemoteCursors cursors={collab.remoteCursors} />}
         {editingConditionGroup && (
           <InlineConditionLabels

src/components/ConnectionTypePrompt.jsx

@@ -0,0 +1,61 @@
+import { COLORS, FONTS, styles, Z_INDEX } from "../styles/theme";
+
+export function ConnectionTypePrompt({ x, y, onNavigate, onStateVariant }) {
+  return (
+    <div
+      style={{
+        position: "absolute",
+        left: x,
+        top: y,
+        background: COLORS.surface,
+        border: `1px solid ${COLORS.accent}`,
+        borderRadius: 10,
+        padding: "14px 18px",
+        boxShadow: `0 4px 20px rgba(0,0,0,0.5), 0 0 12px ${COLORS.accent02}`,
+        zIndex: Z_INDEX.canvasPrompt,
+        minWidth: 200,
+        pointerEvents: "all",
+      }}
+      onMouseDown={(e) => e.stopPropagation()}
+    >
+      <div
+        style={{
+          color: COLORS.text,
+          fontSize: 13,
+          fontFamily: FONTS.ui,
+          fontWeight: 500,
+          marginBottom: 12,
+        }}
+      >
+        Connection type?
+      </div>
+      <div style={{ display: "flex", gap: 8 }}>
+        <button
+          onClick={onNavigate}
+          style={{
+            ...styles.btnPrimary,
+            flex: 1,
+            padding: "7px 0",
+            borderRadius: 6,
+            fontSize: 12,
+          }}
+        >
+          Navigate
+        </button>
+        <button
+          onClick={onStateVariant}
+          style={{
+            ...styles.btnPrimary,
+            flex: 1,
+            padding: "7px 0",
+            background: COLORS.accent,
+            borderRadius: 6,
+            fontSize: 12,
+          }}
+        >
+          State Variant
+        </button>
+      </div>
+    </div>
+  );
+}

src/hooks/useConnectionInteraction.js

@@ -10,11 +10,13 @@ export function useConnectionInteraction({
   addConnection,
   addToConditionalGroup: _addToConditionalGroup,
   convertToConditionalGroup,
+  linkAsState,
 }) {
   const [connecting, setConnecting] = useState(null);
   const [hoverTarget, setHoverTarget] = useState(null);
   const [selectedConnection, setSelectedConnection] = useState(null);
   const [conditionalPrompt, setConditionalPrompt] = useState(null);
+  const [connectionTypePrompt, setConnectionTypePrompt] = useState(null);
   const [editingConditionGroup, setEditingConditionGroup] = useState(null);
 
   const cancelConnecting = useCallback(() => {
@@ -55,16 +57,31 @@ export function useConnectionInteraction({
     setConditionalPrompt(null);
   }, [conditionalPrompt, addConnection]);
 
+  const onConnectionTypeNavigate = useCallback(() => {
+    if (!connectionTypePrompt) return;
+    addConnection(connectionTypePrompt.fromId, connectionTypePrompt.targetScreenId);
+    setConnectionTypePrompt(null);
+  }, [connectionTypePrompt, addConnection]);
+
+  const onConnectionTypeStateVariant = useCallback(() => {
+    if (!connectionTypePrompt) return;
+    linkAsState(connectionTypePrompt.targetScreenId, connectionTypePrompt.fromId);
+    setConnectionTypePrompt(null);
+  }, [connectionTypePrompt, linkAsState]);
+
   return {
     connecting, setConnecting,
     hoverTarget, setHoverTarget,
     selectedConnection, setSelectedConnection,
     conditionalPrompt, setConditionalPrompt,
+    connectionTypePrompt, setConnectionTypePrompt,
     editingConditionGroup, setEditingConditionGroup,
     cancelConnecting,
     onDotDragStart,
     onStartConnect,
     onConditionalPromptConfirm,
     onConditionalPromptCancel,
+    onConnectionTypeNavigate,
+    onConnectionTypeStateVariant,
   };
 }

src/hooks/useInteractionCallbacks.js

@@ -7,8 +7,9 @@ export function useInteractionCallbacks({
   hotspotInteraction, setHotspotInteraction,
   setSelectedConnection, setHoverTarget,
   setConditionalPrompt, setEditingConditionGroup,
+  setConnectionTypePrompt,
   setHotspotModal, setConnectionEditModal,
-  quickConnectHotspot, addConnection, addToConditionalGroup,
+  quickConnectHotspot, addConnection: _addConnection, addToConditionalGroup,
   onStartConnect,
   activeTool, captureDragSnapshot,
   handleDragStart, handleMultiDragStart,
@@ -71,9 +72,12 @@ export function useInteractionCallbacks({
       return;
     }
 
-    addConnection(fromId, targetScreenId);
+    const fromScreen = screens.find((s) => s.id === fromId);
+    const promptX = fromScreen ? fromScreen.x + (fromScreen.width || DEFAULT_SCREEN_WIDTH) + 20 : 0;
+    const promptY = fromScreen ? fromScreen.y : 0;
+    setConnectionTypePrompt({ fromId, targetScreenId, x: promptX, y: promptY });
     cancelConnecting();
-  }, [connecting, cancelConnecting, hotspotInteraction, setHotspotInteraction, quickConnectHotspot, addConnection, connections, screens, addToConditionalGroup, setEditingConditionGroup, setHoverTarget, setConditionalPrompt]);
+  }, [connecting, cancelConnecting, hotspotInteraction, setHotspotInteraction, quickConnectHotspot, connections, screens, addToConditionalGroup, setEditingConditionGroup, setHoverTarget, setConditionalPrompt, setConnectionTypePrompt]);
 
   // Open hotspot modal when a draw gesture completes
   useEffect(() => {

src/hooks/useScreenManager.js

@@ -780,6 +780,31 @@ export function useScreenManager(pan, zoom, canvasRef) {
     setSelectedScreen(newScreen.id);
   }, [screens, connections, documents, pushHistory]);
 
+  const linkAsState = useCallback((screenId, parentScreenId) => {
+    pushHistory(screens, connections, documents);
+    const parent = screens.find((s) => s.id === parentScreenId);
+    const target = screens.find((s) => s.id === screenId);
+    if (!parent || !target) return;
+    if (screenId === parentScreenId) return;
+    if (parent.stateGroup && parent.stateGroup === target.stateGroup) return;
+
+    const groupId = parent.stateGroup || generateId();
+    const siblings = screens.filter((s) => s.stateGroup === groupId);
+    const stateNumber = siblings.length + (parent.stateGroup ? 1 : 2);
+
+    setScreens((prev) =>
+      prev.map((s) => {
+        if (s.id === parentScreenId && !s.stateGroup) {
+          return { ...s, stateGroup: groupId, stateName: DEFAULT_STATE_NAME };
+        }
+        if (s.id === screenId) {
+          return { ...s, stateGroup: groupId, stateName: s.stateName || `State ${stateNumber - 1}` };
+        }
+        return s;
+      })
+    );
+  }, [screens, connections, documents, pushHistory]);
+
   const updateStateName = useCallback((screenId, stateName) => {
     pushHistory(screens, connections, documents);
     setScreens((prev) => prev.map((s) => (s.id === screenId ? { ...s, stateName } : s)));
@@ -873,6 +898,7 @@ export function useScreenManager(pan, zoom, canvasRef) {
     saveConnectionGroup,
     deleteConnectionGroup,
     addState,
+    linkAsState,
     updateStateName,
     addDocument,
     updateDocument,

src/hooks/useScreenManager.test.js

@@ -510,6 +510,102 @@ describe("addState", () => {
   });
 });
 
+describe("linkAsState", () => {
+  it("links two screens into the same stateGroup", () => {
+    const { result } = setup();
+    act(() => result.current.addScreen(null, "A"));
+    act(() => result.current.addScreen(null, "B"));
+    const idA = result.current.screens[0].id;
+    const idB = result.current.screens[1].id;
+
+    act(() => result.current.linkAsState(idB, idA));
+    expect(result.current.screens[0].stateGroup).toBeTruthy();
+    expect(result.current.screens[1].stateGroup).toBe(result.current.screens[0].stateGroup);
+  });
+
+  it("parent gets stateName='Default', target gets 'State 1'", () => {
+    const { result } = setup();
+    act(() => result.current.addScreen(null, "A"));
+    act(() => result.current.addScreen(null, "B"));
+    const idA = result.current.screens[0].id;
+    const idB = result.current.screens[1].id;
+
+    act(() => result.current.linkAsState(idB, idA));
+    expect(result.current.screens[0].stateName).toBe("Default");
+    expect(result.current.screens[1].stateName).toBe("State 1");
+  });
+
+  it("does nothing when linking a screen to itself", () => {
+    const { result } = setup();
+    act(() => result.current.addScreen(null, "A"));
+    const idA = result.current.screens[0].id;
+
+    act(() => result.current.linkAsState(idA, idA));
+    expect(result.current.screens[0].stateGroup).toBeNull();
+  });
+
+  it("does nothing when both screens are already in the same group", () => {
+    const { result } = setup();
+    act(() => result.current.addScreen(null, "A"));
+    act(() => result.current.addScreen(null, "B"));
+    const idA = result.current.screens[0].id;
+    const idB = result.current.screens[1].id;
+
+    act(() => result.current.linkAsState(idB, idA));
+    const groupId = result.current.screens[0].stateGroup;
+
+    act(() => result.current.linkAsState(idB, idA));
+    expect(result.current.screens[0].stateGroup).toBe(groupId);
+    expect(result.current.screens[1].stateGroup).toBe(groupId);
+  });
+
+  it("reuses existing stateGroup when parent already has one", () => {
+    const { result } = setup();
+    act(() => result.current.addScreen(null, "A"));
+    act(() => result.current.addScreen(null, "B"));
+    act(() => result.current.addScreen(null, "C"));
+    const idA = result.current.screens[0].id;
+    const idB = result.current.screens[1].id;
+    const idC = result.current.screens[2].id;
+
+    act(() => result.current.addState(idA));
+    const groupId = result.current.screens[0].stateGroup;
+
+    act(() => result.current.linkAsState(idB, idA));
+    expect(result.current.screens[1].stateGroup).toBe(groupId);
+
+    act(() => result.current.linkAsState(idC, idA));
+    expect(result.current.screens[2].stateGroup).toBe(groupId);
+  });
+
+  it("is undoable", () => {
+    const { result } = setup();
+    act(() => result.current.addScreen(null, "A"));
+    act(() => result.current.addScreen(null, "B"));
+    const idA = result.current.screens[0].id;
+    const idB = result.current.screens[1].id;
+
+    act(() => result.current.linkAsState(idB, idA));
+    expect(result.current.screens[0].stateGroup).toBeTruthy();
+
+    act(() => result.current.undo());
+    expect(result.current.screens[0].stateGroup).toBeNull();
+    expect(result.current.screens[1].stateGroup).toBeNull();
+  });
+
+  it("preserves existing stateName on target screen", () => {
+    const { result } = setup();
+    act(() => result.current.addScreen(null, "A"));
+    act(() => result.current.addScreen(null, "B"));
+    const idA = result.current.screens[0].id;
+    const idB = result.current.screens[1].id;
+
+    act(() => result.current.updateStateName(idB, "Loading"));
+    act(() => result.current.linkAsState(idB, idA));
+    expect(result.current.screens[1].stateName).toBe("Loading");
+  });
+});
+
 describe("saveConnectionGroup", () => {
   it("navigate mode saves connection with fromScreenId, toScreenId, label", () => {
     const { result } = setup();

src/pages/docs/userGuide.md

@@ -184,10 +184,14 @@ After creating a conditional group, inline label inputs appear along each connec
 
 Screen states let you model different visual variants of the same logical screen — for example, a loading state, an error state, or a logged-in vs. logged-out view.
 
-### Adding a state
+### Adding a new state screen
 
 Select a screen, then click "Add State" in the right sidebar. A new variant screen is created 250px to the right of the original, sharing a state group with it. The original screen is automatically labeled "Default".
 
+### Linking an existing screen as a state variant
+
+Drag a connection from one screen to another. A popup appears asking you to choose between **Navigate** (creates a normal navigation link) and **State Variant** (links the target screen into the source screen's state group). Choosing "State Variant" groups both screens together — a dashed connector line appears between them, and they are treated as a single logical screen in the generated instructions.
+
 ### Naming states
 
 Each state has a name field visible in the sidebar (e.g., "Loading", "Error", "Empty"). State names appear in the screen header on the canvas and in the generated instructions.