zyflow 0.6.4

package/src/hooks/useURLSync.ts

@@ -0,0 +1,122 @@
+import { useEffect } from 'react'
+import type { SelectedItem } from '@/types'
+
+export function useURLSync(
+  selectedItem: SelectedItem,
+  setSelectedItem: (item: SelectedItem) => void
+) {
+  // 1. URL -> State (Popstate only - initial load handled by getInitialItemFromURL)
+  useEffect(() => {
+    const handlePopState = () => {
+      const item = getInitialItemFromURL()
+      if (item) {
+        setSelectedItem(item)
+      } else {
+        // Root or unknown path -> maybe reset or keep? 
+        // For now, let's reset to null if root
+        if (window.location.pathname === '/' || window.location.pathname === '') {
+            setSelectedItem(null)
+        }
+      }
+    }
+
+    window.addEventListener('popstate', handlePopState)
+    return () => window.removeEventListener('popstate', handlePopState)
+  }, [setSelectedItem])
+
+  // 2. State -> URL
+  useEffect(() => {
+    if (!selectedItem) {
+        // If null, maybe go to root?
+        if (window.location.pathname !== '/') {
+            // only push if not already there to avoid loops or unwanted history
+             window.history.pushState(null, '', '/')
+        }
+        return
+    }
+
+    let newPath = '/'
+    
+    switch (selectedItem.type) {
+      case 'project':
+        newPath = `/project/${selectedItem.projectId}`
+        break
+      case 'change':
+        newPath = `/project/${selectedItem.projectId}/change/${selectedItem.changeId}`
+        break
+      case 'docs':
+        newPath = `/project/${selectedItem.projectId}/docs`
+        if (selectedItem.docPath) {
+          newPath += `?path=${encodeURIComponent(selectedItem.docPath)}`
+        }
+        break
+      case 'backlog':
+        newPath = `/project/${selectedItem.projectId}/backlog`
+        break
+      case 'project-settings':
+        newPath = `/project/${selectedItem.projectId}/settings`
+        break
+      case 'standalone-tasks':
+        newPath = `/project/${selectedItem.projectId}/tasks`
+        break
+      case 'agent':
+        newPath = `/project/${selectedItem.projectId}/agents`
+        break
+      case 'alerts':
+        newPath = `/project/${selectedItem.projectId}/alerts`
+        break
+      case 'archived':
+        newPath = `/project/${selectedItem.projectId}/archives`
+        break
+      case 'spec':
+        newPath = `/project/${selectedItem.projectId}/spec/${selectedItem.specId}`
+        break
+       case 'settings':
+        newPath = `/settings`
+        break
+    }
+
+    const currentUrl = window.location.pathname + window.location.search
+    if (currentUrl !== newPath) {
+      window.history.pushState(null, '', newPath)
+    }
+  }, [selectedItem])
+}
+
+// Helper to get initial state from URL
+export function getInitialItemFromURL(): SelectedItem | null {
+    const path = window.location.pathname
+    const parts = path.split('/').filter(Boolean)
+
+    if (parts[0] === 'project' && parts[1]) {
+        const projectId = parts[1]
+        // decodeURIComponent is safer for IDs
+        const decodedProjectId = decodeURIComponent(projectId)
+
+        if (parts[2] === 'change' && parts[3]) {
+            return { type: 'change', projectId: decodedProjectId, changeId: decodeURIComponent(parts[3]) }
+        } else if (parts[2] === 'spec' && parts[3]) {
+            return { type: 'spec', projectId: decodedProjectId, specId: decodeURIComponent(parts[3]) }
+        } else if (parts[2] === 'docs') {
+            const urlParams = new URLSearchParams(window.location.search)
+            const docPath = urlParams.get('path')
+            return { type: 'docs', projectId: decodedProjectId, docPath: docPath ?? undefined }
+        } else if (parts[2] === 'backlog') {
+            return { type: 'backlog', projectId: decodedProjectId }
+        } else if (parts[2] === 'settings') {
+            return { type: 'project-settings', projectId: decodedProjectId }
+        } else if (parts[2] === 'tasks') {
+            return { type: 'standalone-tasks', projectId: decodedProjectId }
+        } else if (parts[2] === 'agents') {
+             return { type: 'agent', projectId: decodedProjectId }
+        } else if (parts[2] === 'alerts') {
+             return { type: 'alerts', projectId: decodedProjectId }
+        } else if (parts[2] === 'archives') {
+            return { type: 'archived', projectId: decodedProjectId }
+        }
+        return { type: 'project', projectId: decodedProjectId }
+    } else if (parts[0] === 'settings') {
+        return { type: 'settings' }
+    }
+    return null
+}

package/src/hooks/useWebSocket.ts

@@ -0,0 +1,262 @@
+/**
+ * WebSocket 연결 및 실시간 이벤트 처리 훅
+ */
+
+import { useEffect, useRef, useState } from 'react'
+import { useQueryClient } from '@tanstack/react-query'
+import { WS_ENDPOINT } from '@/config/api'
+
+export type WSEventType =
+  | 'connected'
+  | 'task:created'
+  | 'task:updated'
+  | 'task:deleted'
+  | 'task:archived'
+  | 'change:created'
+  | 'change:updated'
+  | 'change:synced'
+  | 'inbox:updated'
+
+export interface WSEvent {
+  type: WSEventType
+  payload: unknown
+  timestamp: number
+}
+
+const WS_URL = WS_ENDPOINT
+const RECONNECT_INTERVAL = 3000
+const MAX_RECONNECT_ATTEMPTS = 10
+
+interface UseWebSocketOptions {
+  /** 자동 재연결 활성화 (기본: true) */
+  autoReconnect?: boolean
+  /** 이벤트 핸들러 */
+  onEvent?: (event: WSEvent) => void
+  /** 연결 성공 시 콜백 */
+  onConnect?: () => void
+  /** 연결 종료 시 콜백 */
+  onDisconnect?: () => void
+}
+
+export function useWebSocket(options: UseWebSocketOptions = {}) {
+  const { autoReconnect = true, onEvent, onConnect, onDisconnect } = options
+  const [isConnected, setIsConnected] = useState(false)
+  const queryClient = useQueryClient()
+
+  // refs로 콜백을 저장하여 useEffect 재실행 방지
+  const optionsRef = useRef({ autoReconnect, onEvent, onConnect, onDisconnect })
+  useEffect(() => {
+    optionsRef.current = { autoReconnect, onEvent, onConnect, onDisconnect }
+  })
+
+  const wsRef = useRef<WebSocket | null>(null)
+  const reconnectAttemptsRef = useRef(0)
+  const reconnectTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  useEffect(() => {
+    let isMounted = true
+
+    const connect = () => {
+      // 이미 연결 중이거나 연결됨
+      if (wsRef.current?.readyState === WebSocket.OPEN ||
+          wsRef.current?.readyState === WebSocket.CONNECTING) {
+        return
+      }
+
+      if (!isMounted) return
+
+      try {
+        const ws = new WebSocket(WS_URL)
+
+        ws.onopen = () => {
+          if (!isMounted) {
+            ws.close()
+            return
+          }
+          setIsConnected(true)
+          reconnectAttemptsRef.current = 0
+          optionsRef.current.onConnect?.()
+        }
+
+        ws.onclose = () => {
+          if (!isMounted) return
+
+          setIsConnected(false)
+          wsRef.current = null
+          optionsRef.current.onDisconnect?.()
+
+          // 자동 재연결
+          if (optionsRef.current.autoReconnect &&
+              isMounted &&
+              reconnectAttemptsRef.current < MAX_RECONNECT_ATTEMPTS) {
+            reconnectAttemptsRef.current++
+            reconnectTimeoutRef.current = setTimeout(connect, RECONNECT_INTERVAL)
+          }
+        }
+
+        ws.onerror = () => {
+          // 에러는 onclose에서 처리되므로 여기서는 무시
+          // Strict Mode로 인한 early close 에러도 무시
+        }
+
+        ws.onmessage = (event) => {
+          if (!isMounted) return
+          try {
+            const data: WSEvent = JSON.parse(event.data)
+            optionsRef.current.onEvent?.(data)
+            handleEventInvalidation(data, queryClient)
+          } catch (error) {
+            console.error('[WebSocket] Failed to parse message:', error)
+          }
+        }
+
+        wsRef.current = ws
+      } catch (error) {
+        console.error('[WebSocket] Connection failed:', error)
+      }
+    }
+
+    connect()
+
+    return () => {
+      isMounted = false
+
+      if (reconnectTimeoutRef.current) {
+        clearTimeout(reconnectTimeoutRef.current)
+        reconnectTimeoutRef.current = null
+      }
+
+      // StrictMode나 빠른 unmount/remount 시 연결 중인 소켓을 닫으면 에러 발생
+      // 연결이 확립된 후에만 정상 종료
+      if (wsRef.current) {
+        const ws = wsRef.current
+        // 리스너 제거하여 불필요한 이벤트 방지
+        ws.onclose = null
+        ws.onerror = null
+        ws.onmessage = null
+        ws.onopen = null
+
+        // CONNECTING 상태면 open 후 close (에러 방지)
+        if (ws.readyState === WebSocket.CONNECTING) {
+          ws.addEventListener('open', () => ws.close(), { once: true })
+        } else if (ws.readyState === WebSocket.OPEN) {
+          ws.close()
+        }
+        wsRef.current = null
+      }
+    }
+  }, [queryClient]) // queryClient는 stable하므로 한 번만 실행됨
+
+  const connect = () => {
+    reconnectAttemptsRef.current = 0
+    if (wsRef.current?.readyState !== WebSocket.OPEN &&
+        wsRef.current?.readyState !== WebSocket.CONNECTING) {
+      // 기존 연결이 없으면 새로 연결
+      const ws = new WebSocket(WS_URL)
+      ws.onopen = () => {
+        setIsConnected(true)
+        optionsRef.current.onConnect?.()
+      }
+      ws.onclose = () => {
+        setIsConnected(false)
+        optionsRef.current.onDisconnect?.()
+      }
+      ws.onmessage = (event) => {
+        try {
+          const data: WSEvent = JSON.parse(event.data)
+          optionsRef.current.onEvent?.(data)
+          handleEventInvalidation(data, queryClient)
+        } catch (error) {
+          console.error('[WebSocket] Failed to parse message:', error)
+        }
+      }
+      wsRef.current = ws
+    }
+  }
+
+  const disconnect = () => {
+    if (reconnectTimeoutRef.current) {
+      clearTimeout(reconnectTimeoutRef.current)
+      reconnectTimeoutRef.current = null
+    }
+    reconnectAttemptsRef.current = MAX_RECONNECT_ATTEMPTS
+    if (wsRef.current) {
+      wsRef.current.close()
+      wsRef.current = null
+    }
+    setIsConnected(false)
+  }
+
+  return {
+    isConnected,
+    connect,
+    disconnect
+  }
+}
+
+/**
+ * 이벤트 타입에 따라 React Query 캐시 무효화
+ */
+function handleEventInvalidation(event: WSEvent, queryClient: ReturnType<typeof useQueryClient>) {
+  switch (event.type) {
+    case 'task:created':
+    case 'task:updated':
+    case 'task:deleted':
+    case 'task:archived':
+      // 태스크 관련 쿼리 무효화
+      queryClient.invalidateQueries({ queryKey: ['flow', 'tasks'] })
+      queryClient.invalidateQueries({ queryKey: ['flow', 'changes'] })
+      queryClient.invalidateQueries({ queryKey: ['kanban'] })
+      break
+
+    case 'change:created':
+    case 'change:updated':
+    case 'change:synced':
+      // Change 관련 쿼리 무효화
+      queryClient.invalidateQueries({ queryKey: ['flow', 'changes'] })
+      queryClient.invalidateQueries({ queryKey: ['flow', 'tasks'] })
+      queryClient.invalidateQueries({ queryKey: ['projects'] })
+      break
+
+    case 'inbox:updated':
+      // Inbox 쿼리 무효화
+      queryClient.invalidateQueries({ queryKey: ['flow', 'tasks'] })
+      queryClient.invalidateQueries({ queryKey: ['kanban'] })
+      break
+
+    case 'connected':
+      // 연결 시 전체 데이터 새로고침
+      queryClient.invalidateQueries({ queryKey: ['flow'] })
+      queryClient.invalidateQueries({ queryKey: ['projects'] })
+      break
+  }
+}
+
+/**
+ * WebSocket 상태만 구독하는 가벼운 훅
+ */
+export function useWebSocketStatus() {
+  const [isConnected, setIsConnected] = useState(false)
+
+  useEffect(() => {
+    let isMounted = true
+    const ws = new WebSocket(WS_URL)
+
+    ws.onopen = () => {
+      if (isMounted) setIsConnected(true)
+    }
+    ws.onclose = () => {
+      if (isMounted) setIsConnected(false)
+    }
+    ws.onerror = () => {
+      // 에러는 onclose에서 처리
+    }
+
+    return () => {
+      isMounted = false
+      ws.close()
+    }
+  }, [])
+
+  return isConnected
+}

package/src/lib/utils.ts

@@ -0,0 +1,121 @@
+import { type ClassValue, clsx } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}
+
+export function sleep(ms: number = 1000) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/**
+ * 날짜를 상대적 시간 또는 절대 날짜로 포맷팅
+ * @param dateStr - ISO 날짜 문자열
+ * @returns 상대적 시간 (예: "방금 전", "3일 전") 또는 절대 날짜 (예: "2025.12.13")
+ */
+export function formatRelativeDate(dateStr: string | undefined | null): string {
+  if (!dateStr) return '-'
+
+  const date = new Date(dateStr)
+  const now = new Date()
+  const diffMs = now.getTime() - date.getTime()
+  const diffMinutes = Math.floor(diffMs / (1000 * 60))
+  const diffHours = Math.floor(diffMs / (1000 * 60 * 60))
+  const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24))
+
+  if (diffMinutes < 1) return '방금 전'
+  if (diffMinutes < 60) return `${diffMinutes}분 전`
+  if (diffHours < 24) return `${diffHours}시간 전`
+  if (diffDays < 7) return `${diffDays}일 전`
+
+  return date.toLocaleDateString('ko-KR', {
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+  }).replace(/\. /g, '.').replace(/\.$/, '')
+}
+
+/**
+ * 날짜를 절대 날짜로 포맷팅
+ * @param dateStr - ISO 날짜 문자열
+ * @returns 절대 날짜 (예: "2025.12.13")
+ */
+export function formatDate(dateStr: string | undefined | null): string {
+  if (!dateStr) return '-'
+
+  const date = new Date(dateStr)
+  return date.toLocaleDateString('ko-KR', {
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+  }).replace(/\. /g, '.').replace(/\.$/, '')
+}
+
+/**
+ * 날짜를 상세 형식으로 포맷팅 (시간 포함)
+ * @param dateStr - ISO 날짜 문자열
+ * @returns 상세 날짜 (예: "2025.12.13 17:30")
+ */
+export function formatDateTime(dateStr: string | undefined | null): string {
+  if (!dateStr) return '-'
+
+  const date = new Date(dateStr)
+  return date.toLocaleString('ko-KR', {
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+  }).replace(/\. /g, '.').replace(/\.$/, '')
+}
+
+/**
+ * Generates page numbers for pagination with ellipsis
+ * @param currentPage - Current page number (1-based)
+ * @param totalPages - Total number of pages
+ * @returns Array of page numbers and ellipsis strings
+ *
+ * Examples:
+ * - Small dataset (≤5 pages): [1, 2, 3, 4, 5]
+ * - Near beginning: [1, 2, 3, 4, '...', 10]
+ * - In middle: [1, '...', 4, 5, 6, '...', 10]
+ * - Near end: [1, '...', 7, 8, 9, 10]
+ */
+export function getPageNumbers(currentPage: number, totalPages: number) {
+  const maxVisiblePages = 5 // Maximum number of page buttons to show
+  const rangeWithDots = []
+
+  if (totalPages <= maxVisiblePages) {
+    // If total pages is 5 or less, show all pages
+    for (let i = 1; i <= totalPages; i++) {
+      rangeWithDots.push(i)
+    }
+  } else {
+    // Always show first page
+    rangeWithDots.push(1)
+
+    if (currentPage <= 3) {
+      // Near the beginning: [1] [2] [3] [4] ... [10]
+      for (let i = 2; i <= 4; i++) {
+        rangeWithDots.push(i)
+      }
+      rangeWithDots.push('...', totalPages)
+    } else if (currentPage >= totalPages - 2) {
+      // Near the end: [1] ... [7] [8] [9] [10]
+      rangeWithDots.push('...')
+      for (let i = totalPages - 3; i <= totalPages; i++) {
+        rangeWithDots.push(i)
+      }
+    } else {
+      // In the middle: [1] ... [4] [5] [6] ... [10]
+      rangeWithDots.push('...')
+      for (let i = currentPage - 1; i <= currentPage + 1; i++) {
+        rangeWithDots.push(i)
+      }
+      rangeWithDots.push('...', totalPages)
+    }
+  }
+
+  return rangeWithDots
+}

package/src/main.tsx

@@ -0,0 +1,22 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import App from './App'
+import '@/styles/index.css'
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 1000 * 60, // 1 minute
+      refetchOnWindowFocus: false,
+    },
+  },
+})
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <QueryClientProvider client={queryClient}>
+      <App />
+    </QueryClientProvider>
+  </StrictMode>
+)