mpa-url-state-bridge

MPA URL State Bridge

왜 필요한가

MPA의 진짜 약점: 페이지 이동 = 모든 state 초기화.

• 모달 열려있다가 /input/로 가면 닫힘
• 사이드바 열려있다가 /dashboard/로 가면 닫힘
• 새로고침하면 모두 리셋
• URL 공유 시 같은 상태로 열리지 않음

SPA의 장점(연속성)을 URL에 매핑하면 이걸 다 해결함. 단, 시각/기능은 1픽셀도 바뀌면 안 됨.

대전제 (drew의 마이그레이션 원칙)

디자인과 기능은 건드리지 않는다. State만 URL에 동기화한다.

이게 깨지면 안 됨:

• 모달/사이드바의 동작, 위치, 애니메이션, 색상, z-index, focus 관리
• 외부 API 호출 흐름 (login, history load, payment verify 등)
• disabled/loading 상태 관리
• 키보드/ESC/click outside 닫기 등 인터랙션

URL 동기화는 순수하게 state 저장 위치만 옮기는 일.

핵심 패턴 (Svelte 5)

1. URL 헬퍼 (어디서든 import 가능)

type UrlKeys = 'menu' | 'history' | 'login' | 'legend' | 'historyTab' | 'historyQ' | 'focused'

function readUrlState(): Record<UrlKeys, string | null> {
  if (typeof window === 'undefined') return {} as Record<UrlKeys, string | null>
  const p = new URLSearchParams(window.location.search)
  return {
    menu: p.get('menu'),
    history: p.get('history'),
    login: p.get('login'),
    // ... 모든 key
  }
}

function setUrlState(key: UrlKeys, value: string | null, opts: { history?: 'push' | 'replace' } = {}) {
  if (typeof window === 'undefined') return
  const url = new URL(window.location.href)
  if (value === null || value === '' || value === '0' || value === 'false') {
    url.searchParams.delete(key)
  } else {
    url.searchParams.set(key, value)
  }
  const method = opts.history === 'push' ? 'pushState' : 'replaceState'
  window.history[method](null, '', url.toString())
}

2. State는 $state로, 노출값은 $derived로

// ❌ 직접 변경 가능한 state (deprecated)
let menuOpen = $state(false)
function openMenu() { menuOpen = true }

// ✅ URL이 source of truth, 노출값만 derived
let urlState = $state(readUrlState())
window.addEventListener('popstate', () => { urlState = readUrlState() })

let menuOpen = $derived(urlState.menu === '1')

function openMenu() { setUrlState('menu', '1') }
function closeMenu() { setUrlState('menu', null) }
function toggleMenu() { setUrlState('menu', menuOpen ? null : '1') }

3. template은 $derived 변수 그대로 사용