refactor: Drive Linked List via an action log with staged insert/delete

Operations are now pure planners in lib/algorithms/linkedList.js that
return a flat list of actions (mark, setNext, stageNode, lift, drop,
removeNode, reorder, ...); the page is a generic executor that applies
each action with a delay. Adding an operation no longer needs a new
run-loop in the page.

Insert and delete are now staged for clarity:
- Insert: node floats above its slot, wires next then prev, drops in
- Delete: node is flagged, lifts out, predecessor bypasses it, removed

Also namespace SVG sibling keys to fix a duplicate-key warning (node
ids collided with pointer-caption indices), and add a real thumbnail.

Author: TamimEhsan

public/images/linked-list.png

@@ -4,9 +4,10 @@ import Arrow from './arrow';
 const VB_W = 240;
 const VB_H = 90;
 const PAD = 16;
-const Y = 48;
+const Y = 56;        // resting row
+const LIFT = 26;     // how high a staged node floats above the row
 
-export default function Canvas({ nodes, nextOf, prevOf, listType, nodeState = {}, pointers = [] }) {
+export default function Canvas({ nodes, nextOf, prevOf, listType, nodeState = {}, pointers = [], liftedId = null }) {
     const count = nodes.length;
     const spacing = count > 1
         ? Math.min(46, (VB_W - 2 * PAD - NODE_W) / (count - 1))
@@ -15,12 +16,11 @@ export default function Canvas({ nodes, nextOf, prevOf, listType, nodeState = {}
     const startX = Math.max(PAD, (VB_W - totalW) / 2);
 
     const posById = {};
-    nodes.forEach((n, i) => { posById[n.id] = { x: startX + i * spacing, i }; });
+    nodes.forEach((n, i) => {
+        posById[n.id] = { x: startX + i * spacing, y: n.id === liftedId ? Y - LIFT : Y, i };
+    });
 
     const doubly = listType === 1;
-    const nextY = doubly ? Y - 3 : Y;
-    const prevY = Y + 3;
-
     const tail = nodes[count - 1];
 
     return (
@@ -42,12 +42,14 @@ export default function Canvas({ nodes, nextOf, prevOf, listType, nodeState = {}
                 const src = posById[n.id];
                 const dst = posById[target];
                 if (!dst) return null;
-                // forward (head->tail) points from the next-cell to the node's left;
+                const y1 = src.y + (doubly ? -3 : 0);
+                const y2 = dst.y + (doubly ? -3 : 0);
+                // forward link exits the next-cell to the target's left edge;
                 // a flipped (leftward) link during reverse points the other way.
                 if (dst.i > src.i) {
-                    return <Arrow key={'nx' + n.id} x1={src.x + NODE_W} y1={nextY} x2={dst.x} y2={nextY} />;
+                    return <Arrow key={'nx' + n.id} x1={src.x + NODE_W} y1={y1} x2={dst.x} y2={y2} />;
                 }
-                return <Arrow key={'nx' + n.id} x1={src.x} y1={nextY} x2={dst.x + NODE_W} y2={nextY} />;
+                return <Arrow key={'nx' + n.id} x1={src.x} y1={y1} x2={dst.x + NODE_W} y2={y2} />;
             })}
 
             {/* prev pointers (doubly only) */}
@@ -56,45 +58,45 @@ export default function Canvas({ nodes, nextOf, prevOf, listType, nodeState = {}
                 if (target == null) return null;
                 const src = posById[n.id];
                 const dst = posById[target];
-                if (!dst || Math.abs(dst.i - src.i) !== 1) return null;
-                return <Arrow key={'pv' + n.id} x1={src.x} y1={prevY} x2={dst.x + NODE_W} y2={prevY} color="#94a3b8" />;
+                if (!dst) return null;
+                return <Arrow key={'pv' + n.id} x1={src.x} y1={src.y + 3} x2={dst.x + NODE_W} y2={dst.y + 3} color="#94a3b8" />;
             })}
 
             {/* null terminator after the tail */}
             {tail && nextOf[tail.id] == null && (
-                <text x={posById[tail.id].x + NODE_W + 9} y={Y} textAnchor="middle" dominantBaseline="central"
+                <text x={posById[tail.id].x + NODE_W + 9} y={posById[tail.id].y} textAnchor="middle" dominantBaseline="central"
                     style={{ font: '4px sans-serif' }} fill="#94a3b8">null</text>
             )}
 
             {/* null terminator before the head (doubly: head.prev = null) */}
             {doubly && nodes[0] && prevOf[nodes[0].id] == null && (
-                <text x={posById[nodes[0].id].x - 9} y={Y} textAnchor="middle" dominantBaseline="central"
+                <text x={posById[nodes[0].id].x - 9} y={posById[nodes[0].id].y} textAnchor="middle" dominantBaseline="central"
                     style={{ font: '4px sans-serif' }} fill="#94a3b8">null</text>
             )}
 
             {/* nodes */}
             {nodes.map((n) => (
-                <Node key={n.id} x={posById[n.id].x} y={Y} value={n.value}
+                <Node key={'nd' + n.id} x={posById[n.id].x} y={posById[n.id].y} value={n.value}
                     listType={listType} state={nodeState[n.id]}
                     isHead={prevOf[n.id] == null} isTail={nextOf[n.id] == null} />
             ))}
 
-            {/* head / tail labels */}
-            {nodes[0] && (
+            {/* head / tail labels (skip while a node is lifted to avoid clutter) */}
+            {nodes[0] && nodes[0].id !== liftedId && (
                 <text x={posById[nodes[0].id].x + NODE_W / 2} y={Y - NODE_H / 2 - 4}
                     textAnchor="middle" style={{ font: '3.5px sans-serif', fontWeight: 600 }} fill="#475569">head</text>
             )}
-            {tail && count > 1 && (
+            {tail && count > 1 && tail.id !== liftedId && (
                 <text x={posById[tail.id].x + NODE_W / 2} y={Y - NODE_H / 2 - 4}
                     textAnchor="middle" style={{ font: '3.5px sans-serif', fontWeight: 600 }} fill="#475569">tail</text>
             )}
 
-            {/* operation pointer captions (curr / prev / next / slow / fast) */}
+            {/* operation pointer captions (curr / prev / next) */}
             {pointers.map((p, idx) => {
                 if (p.nodeId == null || !posById[p.nodeId]) return null;
                 const px = posById[p.nodeId].x + NODE_W / 2;
                 return (
-                    <text key={idx} x={px} y={Y + NODE_H / 2 + 7} textAnchor="middle"
+                    <text key={'pt' + idx} x={px} y={Y + NODE_H / 2 + 7} textAnchor="middle"
                         style={{ font: '4px sans-serif', fontWeight: 700 }} fill="#0f172a">
                         ▲ {p.label}
                     </text>

src/app/linked-list/canvas.jsx

@@ -2,7 +2,17 @@
 
 import { useState, useRef } from 'react';
 import Navbar from '@/components/navbar';
-import { buildList, linkify, makeNode, randomValues } from '@/lib/algorithms/linkedList';
+import {
+    buildList,
+    linkify,
+    randomValues,
+    reduceStructure,
+    insertActions,
+    deleteByValueActions,
+    deleteByIndexActions,
+    searchActions,
+    reverseActions,
+} from '@/lib/algorithms/linkedList';
 import Canvas from './canvas';
 import Menu from './menu';
 
@@ -20,6 +30,7 @@ export default function LinkedList() {
     const [listType, setListType] = useState(0);
     const [nodeState, setNodeState] = useState({});
     const [pointers, setPointers] = useState([]);
+    const [liftedId, setLiftedId] = useState(null);
     const [isRunning, setIsRunning] = useState(false);
 
     const nodesRef = useRef(initial.nodes);
@@ -33,160 +44,91 @@ export default function LinkedList() {
     const indexRef = useRef('1');
 
     // --- state appliers (keep refs and React state in sync) ---
-    const applyNodes = (arr) => { nodesRef.current = arr; setNodes(arr); };
-    const applyLinks = (nx, pv) => {
+    const applyStructure = ({ nodes: n, nextOf: nx, prevOf: pv }) => {
+        nodesRef.current = n; setNodes(n);
         nextOfRef.current = nx; setNextOf(nx);
         prevOfRef.current = pv; setPrevOf(pv);
     };
-    const relink = (arr) => {
-        const { nextOf: nx, prevOf: pv } = linkify(arr);
-        applyNodes(arr);
-        applyLinks(nx, pv);
+    const relink = (arr) => applyStructure({ nodes: arr, ...linkify(arr) });
+
+    // Apply one action: visual actions touch marks/pointers; everything else is
+    // a structural change handled by the lib reducer.
+    const applyAction = (action) => {
+        switch (action.type) {
+            case 'mark':
+                setNodeState((s) => ({ ...s, [action.id]: action.state }));
+                break;
+            case 'pointers':
+                setPointers(action.items);
+                break;
+            case 'lift':
+                setLiftedId(action.id);
+                break;
+            case 'drop':
+                setLiftedId(null);
+                break;
+            case 'clear':
+                setNodeState({});
+                setPointers([]);
+                setLiftedId(null);
+                break;
+            default:
+                if (action.type === 'stageNode') setLiftedId(action.id);
+                applyStructure(reduceStructure(
+                    { nodes: nodesRef.current, nextOf: nextOfRef.current, prevOf: prevOfRef.current },
+                    action,
+                ));
+        }
     };
-    const mark = (id, kind) => setNodeState((s) => ({ ...s, [id]: kind }));
-    const clearMarks = () => { setNodeState({}); setPointers([]); };
 
-    const begin = () => {
-        if (isRunningRef.current) return false;
+    const runActions = async (actions) => {
+        if (!actions.length || isRunningRef.current) return;
         isRunningRef.current = true;
         setIsRunning(true);
-        clearMarks();
-        return true;
-    };
-    const finish = () => { isRunningRef.current = false; setIsRunning(false); };
-
-    // --- operations ---
-    const runInsert = async (pos) => {
-        if (!begin()) return;
-        const arr = [...nodesRef.current];
-        const idx = pos === 'head' ? 0
-            : pos === 'tail' ? arr.length
-                : Math.max(0, Math.min(Number(pos) || 0, arr.length));
-        const value = Number(valueRef.current);
-
-        for (let i = 0; i < idx; i++) {
-            mark(arr[i].id, 'active');
-            await sleep(speedRef.current);
-            mark(arr[i].id, 'done');
-        }
-        const node = makeNode(Number.isFinite(value) ? value : 0);
-        arr.splice(idx, 0, node);
-        relink(arr);
-        mark(node.id, 'found');
-        await sleep(speedRef.current);
-        clearMarks();
-        finish();
-    };
-
-    const runDeleteValue = async (value) => {
-        if (!begin()) return;
-        const arr = [...nodesRef.current];
-        let idx = -1;
-        for (let i = 0; i < arr.length; i++) {
-            mark(arr[i].id, 'active');
-            await sleep(speedRef.current);
-            if (arr[i].value === value) { idx = i; break; }
-            mark(arr[i].id, 'done');
-        }
-        if (idx >= 0) {
-            mark(arr[idx].id, 'remove');
-            await sleep(speedRef.current);
-            arr.splice(idx, 1);
-            relink(arr);
-            await sleep(speedRef.current);
-        }
-        clearMarks();
-        finish();
-    };
-
-    const runDeleteIndex = async (index) => {
-        if (!begin()) return;
-        const arr = [...nodesRef.current];
-        const idx = Number(index);
-        if (idx >= 0 && idx < arr.length) {
-            for (let i = 0; i < idx; i++) {
-                mark(arr[i].id, 'active');
-                await sleep(speedRef.current);
-                mark(arr[i].id, 'done');
-            }
-            mark(arr[idx].id, 'remove');
-            await sleep(speedRef.current);
-            arr.splice(idx, 1);
-            relink(arr);
-            await sleep(speedRef.current);
-        }
-        clearMarks();
-        finish();
-    };
-
-    const runSearch = async (value) => {
-        if (!begin()) return;
-        const arr = [...nodesRef.current];
-        let found = false;
-        for (let i = 0; i < arr.length; i++) {
-            mark(arr[i].id, 'active');
-            await sleep(speedRef.current);
-            if (arr[i].value === value) { mark(arr[i].id, 'found'); found = true; break; }
-            mark(arr[i].id, 'done');
-        }
-        await sleep(speedRef.current);
-        if (found) await sleep(speedRef.current);
-        clearMarks();
-        finish();
-    };
-
-    const runReverse = async () => {
-        if (!begin()) return;
-        const arr = [...nodesRef.current];
-        if (arr.length < 2) { finish(); return; }
-
-        const temp = { ...linkify(arr).nextOf };
-        let prev = null;
-        for (let i = 0; i < arr.length; i++) {
-            const curr = arr[i].id;
-            const next = i + 1 < arr.length ? arr[i + 1].id : null;
-            setPointers([
-                ...(prev != null ? [{ label: 'prev', nodeId: prev }] : []),
-                { label: 'curr', nodeId: curr },
-                ...(next != null ? [{ label: 'next', nodeId: next }] : []),
-            ]);
-            mark(curr, 'active');
-            await sleep(speedRef.current);
-            temp[curr] = prev;
-            applyLinks({ ...temp }, prevOfRef.current);
+        setNodeState({});
+        setPointers([]);
+        setLiftedId(null);
+        for (const action of actions) {
+            applyAction(action);
             await sleep(speedRef.current);
-            mark(curr, 'done');
-            prev = curr;
         }
-        // settle: physical order mirrors logical, forward links restored
-        const reversed = [...arr].reverse();
-        relink(reversed);
-        setPointers([]);
-        await sleep(speedRef.current);
-        clearMarks();
-        finish();
+        isRunningRef.current = false;
+        setIsRunning(false);
     };
 
     const handleVisualize = () => {
         const op = operationRef.current;
-        if (op === 0) runInsert('head');
-        else if (op === 1) runInsert('tail');
-        else if (op === 2) runInsert(indexRef.current);
-        else if (op === 3) runDeleteValue(Number(valueRef.current));
-        else if (op === 4) runDeleteIndex(indexRef.current);
-        else if (op === 5) runSearch(Number(valueRef.current));
-        else if (op === 6) runReverse();
+        const list = {
+            nodes: nodesRef.current,
+            nextOf: nextOfRef.current,
+            prevOf: prevOfRef.current,
+            listType: listTypeRef.current,
+        };
+        const value = Number(valueRef.current);
+        let actions = [];
+        if (op === 0) actions = insertActions(list, 'head', value);
+        else if (op === 1) actions = insertActions(list, 'tail', value);
+        else if (op === 2) actions = insertActions(list, indexRef.current, value);
+        else if (op === 3) actions = deleteByValueActions(list, value);
+        else if (op === 4) actions = deleteByIndexActions(list, indexRef.current);
+        else if (op === 5) actions = searchActions(list, value);
+        else if (op === 6) actions = reverseActions(list);
+        runActions(actions);
     };
 
     const handleRandomize = () => {
         if (isRunningRef.current) return;
-        clearMarks();
+        setNodeState({});
+        setPointers([]);
+        setLiftedId(null);
         relink(buildList(randomValues(5)).nodes);
     };
 
     const handleReset = () => {
         if (isRunningRef.current) return;
-        clearMarks();
+        setNodeState({});
+        setPointers([]);
+        setLiftedId(null);
         relink(nodesRef.current.map((n) => ({ ...n })));
     };
 
@@ -214,6 +156,7 @@ export default function LinkedList() {
                             listType={listType}
                             nodeState={nodeState}
                             pointers={pointers}
+                            liftedId={liftedId}
                         />
                     </div>
                 </div>