💡 Why Zustand?

Problems with React Context

Benefits of Zustand

🏗️ Phase 1: Create Zustand Store

Store Structure

The store combines the existing reducer logic with async actions in a single, cohesive unit:

"use client";

import { create } from "zustand";
import { devtools } from "zustand/middleware";
import { useShallow } from "zustand/react/shallow";
import { BoardDTO, TaskPatch } from "@/types/data";
import { TaskCreatePayload, TaskView } from "@/types/taskView";
import { boardService } from "@/services/boardService";
import { pulseColumn, toastError } from "@/lib/uiEffects";

type BoardActions = {
  hydrate: (data: BoardDTO) => void;
  patchTask: (id: string, patch: TaskPatch) => Promise<TaskView>;
  moveTask: (id: string, toColumnId: string) => Promise<void>;
  upsertTask: (task: TaskView) => void;
  createTask: (payload: TaskCreatePayload) => Promise<TaskView>;
  createSubtask: (parentId: string, title: string) => Promise<TaskView>;
  reopenTask: (id: string, reason: string) => Promise<TaskView>;
};

type BoardStore = BoardDTO & BoardActions;

const initialState: BoardDTO = {
  id: "",
  name: "",
  columns: {},
  tasks: {},
};

export const useBoardStore = create<BoardStore>()(
  devtools(
    (set, get) => ({
      ...initialState,
      
      hydrate: (data) => set(data, false, "hydrate"),
      
      // ... actions implementation
    }),
    { name: "board-store" }
  )
);

Key Actions

upsertTask

Handles adding new tasks and updating existing ones, including column membership logic:

upsertTask: (task: TaskView) => {
  const state = get();
  const existing = state.tasks[task.id];
  const nextTasks = { ...state.tasks, [task.id]: task };

  // Subtasks don't belong in columns
  const isSubtask = (task.parentTaskIds?.length ?? 0) > 0;
  if (isSubtask) {
    set({ tasks: nextTasks }, false, "upsertTask/subtask");
    return;
  }

  // Handle column membership for new tasks
  if (!existing) {
    const col = state.columns[task.columnId || ""];
    if (col) {
      set({
        tasks: nextTasks,
        columns: {
          ...state.columns,
          [col.id]: { ...col, taskIds: [...new Set([...col.taskIds, task.id])] },
        },
      }, false, "upsertTask/new");
    }
    return;
  }

  // Handle column changes for existing tasks
  if (task.columnId && task.columnId !== existing.columnId) {
    // Move between columns...
  }

  set({ tasks: nextTasks }, false, "upsertTask/update");
}

moveTask (with Optimistic Updates)

Implements optimistic UI updates with rollback on failure:

moveTask: async (id: string, toColumnId: string) => {
  const state = get();
  const task = state.tasks[id];
  const prevColumnId = task.columnId;

  // Optimistic update
  set({
    tasks: { ...state.tasks, [id]: { ...task, columnId: toColumnId } },
    columns: { /* update column taskIds */ },
  }, false, "moveTask/optimistic");

  try {
    const updated = await boardService.moveTask(id, toColumnId);
    get().upsertTask(updated);
    pulseColumn(toColumnId);
  } catch (err) {
    // Rollback on failure
    set({ /* restore previous state */ }, false, "moveTask/rollback");
    toastError("Failed to move task");
    throw err;
  }
}

🔗 Phase 2: Selector Hooks

The Re-render Problem

Zustand selectors that return arrays or objects create new references on every call, causing infinite re-renders:

// Creates new array every render
export function useTasksInColumn(id) {
  return useBoardStore((s) => {
    const col = s.columns[id];
    return col?.taskIds.map(
      (tid) => s.tasks[tid]
    ) ?? [];
  });
}

// Shallow comparison prevents loops
export function useTasksInColumn(id) {
  return useBoardStore(
    useShallow((s) => {
      const col = s.columns[id];
      return col?.taskIds.map(
        (tid) => s.tasks[tid]
      ) ?? [];
    })
  );
}

Complete Selector List

// Primitive selectors (no useShallow needed)
export const useBoardId = () => useBoardStore((s) => s.id);
export const useBoardName = () => useBoardStore((s) => s.name);
export const useBoardTasks = () => useBoardStore((s) => s.tasks);
export const useBoardColumns = () => useBoardStore((s) => s.columns);

export function useTaskById(id: string) {
  return useBoardStore((s) => s.tasks[id]);
}

export function useActiveTask(id: string | null) {
  return useBoardStore((s) => (id ? s.tasks[id] ?? null : null));
}

// Array selectors (useShallow required)
export function useTasksInColumn(id: string) {
  return useBoardStore(
    useShallow((s) => {
      const col = s.columns[id];
      return col?.taskIds.map((tid) => s.tasks[tid]).filter(Boolean) ?? [];
    })
  );
}

export function useSubtasks(parentId: string) {
  return useBoardStore(
    useShallow((s) =>
      Object.values(s.tasks).filter((t) => t.parentTaskIds?.includes(parentId))
    )
  );
}

export function useTasksByState(state: TaskState) {
  return useBoardStore(
    useShallow((s) => Object.values(s.tasks).filter((t) => t.state === state))
  );
}

🔄 Phase 3: Component Updates

Import Migration

All components were updated to import from the new boardHooks.ts (renamed from BoardContext.tsx):

import { 
  useBoardTasks, 
  useBoardActionsCtx 
} from "./BoardContext";

import { 
  useBoardTasks, 
  useBoardActionsCtx 
} from "./boardHooks";

Components Updated

🗑️ Phase 4: Remove BoardProvider

The Key Change

With Zustand, we no longer need a React Context provider. The store is a module-level singleton that components subscribe to directly.

Board.tsx - Store Hydration

export default function Board({ board }) {
  return (
    <BoardProvider initial={board}>
      <BoardDndShell 
        board={board} 
        onMoveTask={...}>
        {/* children */}
      </BoardDndShell>
    </BoardProvider>
  );
}

export default function Board({ board }) {
  const hydratedRef = useRef(false);
  
  // Hydrate store synchronously
  if (!hydratedRef.current) {
    useBoardStore.setState(board);
    hydratedRef.current = true;
  }
  
  return (
    <BoardDndShell>
      {/* children */}
    </BoardDndShell>
  );
}

BoardDndShell.tsx - Direct Subscription

type Props = {
  board: BoardDTO;
  onMoveTask: (id, col) => void;
  children: ReactNode;
};

export function BoardDndShell({ 
  board, 
  onMoveTask, 
  children 
}: Props) {
  // Use props directly
  const task = board.tasks[id];
}

type Props = {
  children: ReactNode;
};

export function BoardDndShell({ 
  children 
}: Props) {
  // Subscribe to store directly
  const tasks = useBoardStore(s => s.tasks);
  const moveTask = useBoardStore(s => s.moveTask);
}

Test Updates

Tests were updated to use useBoardStore.setState() instead of wrapping in BoardProvider:

import { useBoardStore, initialState } from "../../src/store/useBoardStore";

describe("Board Column", () => {
  beforeEach(() => {
    // Reset store between tests
    useBoardStore.setState(initialState);
  });

  it("renders column name and tasks", () => {
    const board = { /* test data */ };
    
    // Hydrate store directly instead of using BoardProvider
    useBoardStore.setState(board);

    render(<Column column={column} onOpenTask={vi.fn()} />);
    
    expect(screen.getByText("To Do")).toBeInTheDocument();
  });
});

🏛️ Final Architecture

Component Hierarchy

Data Flow

✅ Verification

Test Results

Build Status

Manual Testing Checklist

• Board loads correctly with all columns and tasks
• Drag-and-drop moves tasks between columns
• Task editing (title, state, priority) persists
• Subtask operations (add parent, remove parent)
• Command palette search works (Cmd+K)
• Global task search filters correctly
• Running tasks bar updates in real-time

📁 Complete File Changes

New Files

Modified Files