safa-router 1.0.1

package/src/SafaRouter.js

@@ -0,0 +1,464 @@
+import { RouteMatcher } from './RouteMatcher.js'
+import { RouteTree } from './RouteTree.js'
+import { HistoryManager } from './HistoryManager.js'
+import { MiddlewareChain } from './MiddlewareChain.js'
+import { Link } from './Link.js'
+import { normalizePath, parseQuery, emit, createURL, isExternalURL } from './utils.js'
+import { EVENTS, DEFAULT_CONFIG } from './constants.js'
+import { RouteLoadError, SafaError } from './errors.js'
+
+export class SafaRouter {
+  static version = '1.0.0'
+  static VERSION = '1.0.0'
+
+  constructor(options = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...options }
+    if (this.config.pageDir && !this.config.pagesDir) {
+      this.config.pagesDir = this.config.pageDir
+    }
+
+    this._events = {}
+    for (const key of Object.values(EVENTS)) this._events[key] = []
+
+    this._matcher = new RouteMatcher()
+    this._history = new HistoryManager({
+      useHash: this.config.useHash,
+      basePath: this.config.basePath,
+    })
+    this._middleware = new MiddlewareChain()
+    this._cache = new Map()
+
+    this._pathname = '/'
+    this._params = {}
+    this._query = {}
+    this._routeData = null
+    this._isLoading = false
+    this._started = false
+    this._targetEl = null
+
+    this._globalNotFound = this.config.notFound || null
+    this._globalError = this.config.error || null
+    this._globalLayout = this.config.layout || null
+
+    this._boundNav = this._onHistoryChange.bind(this)
+  }
+
+  async start(target) {
+    if (this._started) return
+    if (target) this.config.target = target
+
+    this._targetEl =
+      typeof this.config.target === 'string'
+        ? document.querySelector(this.config.target)
+        : this.config.target
+
+    if (!this._targetEl) {
+      throw new SafaError(
+        `Target element "${this.config.target}" not found`,
+        'INIT_ERROR'
+      )
+    }
+
+    this._routeTree = new RouteTree(this.config.routes || {})
+    this._seedMatcher()
+    this._history.init()
+    this._unsubHistory = this._history.onChange(this._boundNav)
+    await this._resolve(this._history.path, 'replace')
+    emit(this._events, EVENTS.READY, { pathname: this._pathname })
+    this._started = true
+    return this
+  }
+
+  isStarted() {
+    return this._started
+  }
+
+  destroy() {
+    this._started = false
+    if (this._unsubHistory) {
+      this._unsubHistory()
+      this._unsubHistory = null
+    }
+    this._history.destroy()
+    for (const k of Object.keys(this._events)) this._events[k] = []
+    this._cache.clear()
+    this._targetEl = null
+    emit(this._events, EVENTS.DESTROY, {})
+  }
+
+  async push(url, state = {}) {
+    if (isExternalURL(url)) {
+      window.location.href = url
+      return
+    }
+    const u = createURL(url) || new URL(url, location.origin)
+    await this._navigate(normalizePath(u.pathname), 'push', parseQuery(u.search), state)
+  }
+
+  async replace(url, state = {}) {
+    if (isExternalURL(url)) {
+      window.location.replace(url)
+      return
+    }
+    const u = createURL(url) || new URL(url, location.origin)
+    await this._navigate(normalizePath(u.pathname), 'replace', parseQuery(u.search), state)
+  }
+
+  back() { this._history.back() }
+  forward() { this._history.forward() }
+
+  reload() {
+    this._resolve(this._pathname, 'replace')
+  }
+
+  navigate(url) { return this.push(url) }
+
+  getConfig() { return { ...this.config } }
+
+  get pathname() { return this._pathname }
+  get params() { return { ...this._params } }
+  get query() { return { ...this._query } }
+  get loading() { return this._isLoading }
+
+  on(name, fn) {
+    if (!this._events[name]) this._events[name] = []
+    this._events[name].push(fn)
+    return () => {
+      this._events[name] = this._events[name].filter((f) => f !== fn)
+    }
+  }
+
+  off(name, fn) {
+    if (!this._events[name]) return
+    this._events[name] = this._events[name].filter((f) => f !== fn)
+  }
+
+  use(fn) { this._middleware.use(fn); return this }
+
+  onError(fn) { return this.on(EVENTS.ERROR, fn) }
+  onNotFound(fn) { return this.on(EVENTS.NOT_FOUND, fn) }
+  onRouteChange(fn) { return this.on(EVENTS.ROUTE_CHANGE, fn) }
+  onBeforeNavigate(fn) { return this.on(EVENTS.BEFORE_NAVIGATE, fn) }
+
+  createLink(config) {
+    return new Link({ ...config, router: this })
+  }
+
+  async prefetch(path) {
+    const normalized = normalizePath(path)
+    if (this._cache.has(normalized)) return
+    const page = await this._fetchPage(normalized)
+    if (page && this.config.cacheRoutes) {
+      this._cache.set(normalized, page)
+    }
+  }
+
+  clearCache() { this._cache.clear() }
+
+  _seedMatcher() {
+    const walk = (routes, base) => {
+      if (!routes || typeof routes !== 'object') return
+      for (const [key, val] of Object.entries(routes)) {
+        const isGroup = key.startsWith('(') && key.endsWith(')')
+        const fp =
+          isGroup
+            ? base
+            : base === '/'
+              ? `/${key}`
+              : `${base}/${key}`
+        if (typeof val === 'object' && val !== null) {
+          if (val.page) this._matcher.add(fp)
+          if (val.children) walk(val.children, fp)
+        } else if (typeof val === 'function') {
+          this._matcher.add(fp)
+        }
+      }
+    }
+    walk(this.config.routes || {}, '/')
+  }
+
+  _resolvePagePath(path) {
+    const dir = (this.config.pagesDir || '').replace(/\/+$/, '')
+    if (!dir) return null
+    const normal = normalizePath(path)
+    if (normal === '/') return `${dir}/index.html`
+    return `${dir}${normal}.html`
+  }
+
+  _hasRoutes() {
+    return this.config.routes && typeof this.config.routes === 'object' && Object.keys(this.config.routes).length > 0
+  }
+
+  async _fetchPage(path) {
+    const htmlPath = this._resolvePagePath(path)
+    if (!htmlPath) return null
+    try {
+      const res = await fetch(htmlPath)
+      if (!res.ok) return null
+      return res.text()
+    } catch {
+      return null
+    }
+  }
+
+  async _navigate(path, method, query = {}, state = {}) {
+    if (path === this._pathname) return
+    await this._resolve(path, method, query, state)
+  }
+
+  async _resolve(path, method, query = {}, state = {}) {
+    this._isLoading = true
+    emit(this._events, EVENTS.LOADING, { path, loading: true })
+    emit(this._events, EVENTS.BEFORE_NAVIGATE, { path, method })
+
+    try {
+      const ctx = { path, method, query, cancelled: false, redirect: null }
+      await this._middleware.run(ctx)
+      if (ctx.redirect) return this._navigate(ctx.redirect, 'replace')
+      if (ctx.cancelled) {
+        this._isLoading = false
+        return
+      }
+
+      const routeMatch = this._hasRoutes() ? this._routeTree.resolve(path) : null
+      let pageContent, layoutFns = []
+      let resolvedPath = path
+
+      if (routeMatch) {
+        if (routeMatch.node.loading) {
+          const loadingFn = await this._loadComponent(routeMatch.node.loading)
+          if (loadingFn && this._targetEl) {
+            this._targetEl.innerHTML = typeof loadingFn === 'function'
+              ? loadingFn({ path, router: this })
+              : loadingFn
+          }
+        }
+        pageContent = await this._loadComponent(routeMatch.node.page)
+        for (const l of routeMatch.layouts) {
+          if (!l) continue
+          const lfn = await this._loadComponent(l)
+          if (lfn) layoutFns.push(lfn)
+        }
+        if (this._globalLayout) {
+          const lfn = await this._loadComponent(this._globalLayout)
+          if (lfn) layoutFns.unshift(lfn)
+        }
+        this._routeData = routeMatch
+      } else if (this.config.pagesDir) {
+        pageContent = await this._fetchPage(path)
+        if (pageContent === null) {
+          await this._handleNotFound(path, method)
+          this._isLoading = false
+          return
+        }
+        if (this._globalLayout) {
+          const lfn = await this._loadComponent(this._globalLayout)
+          if (lfn) layoutFns.push(lfn)
+        }
+        this._routeData = { node: { page: null }, params: {}, layouts: [] }
+      } else {
+        await this._handleNotFound(path, method)
+        this._isLoading = false
+        return
+      }
+
+      if (method === 'push') this._history.push(path, state)
+      else if (method === 'replace') this._history.replace(path, state)
+
+      this._pathname = path
+      this._params = routeMatch?.params || {}
+      this._query = query
+      this._isLoading = false
+
+      this._render(pageContent, layoutFns)
+
+      emit(this._events, EVENTS.ROUTE_CHANGE, {
+        pathname: path,
+        params: this._params,
+        query: this._query,
+      })
+      emit(this._events, EVENTS.AFTER_NAVIGATE, { pathname: path })
+
+      if (this.config.scrollToTop) {
+        window.scrollTo({ top: 0, behavior: 'smooth' })
+      }
+
+      this._updateTitle()
+      this._focus()
+    } catch (err) {
+      this._isLoading = false
+      await this._handleError(path, err)
+    }
+  }
+
+  async _render(pageContent, layoutFns) {
+    if (!this._targetEl) return
+
+    const html = layoutFns.length > 0
+      ? await this._renderWithLayouts(pageContent, layoutFns, 0)
+      : (typeof pageContent === 'function'
+          ? pageContent({ params: this._params, query: this._query, router: this })
+          : (pageContent || ''))
+
+    const duration = this.config.transitionDuration
+    if (duration > 0) {
+      this._targetEl.style.opacity = '0'
+      this._targetEl.style.transition = `opacity ${duration}ms ease`
+    }
+    this._targetEl.innerHTML = html
+    this._bindLinks()
+    if (duration > 0) {
+      requestAnimationFrame(() => {
+        this._targetEl.style.opacity = '1'
+      })
+    }
+  }
+
+  async _renderWithLayouts(pageContent, layoutFns, idx) {
+    if (idx >= layoutFns.length) {
+      if (typeof pageContent === 'function') {
+        return pageContent({ params: this._params, query: this._query, router: this })
+      }
+      return pageContent || ''
+    }
+    const layoutFn = layoutFns[idx]
+    const content = await this._renderWithLayouts(pageContent, layoutFns, idx + 1)
+    return layoutFn({ children: content, params: this._params, router: this })
+  }
+
+  _updateTitle() {
+    const template = this.config.titleTemplate
+    if (!template) return
+    const title = this._routeData?.node?.meta?.title ||
+                  this._routeData?.node?.segment ||
+                  this._pathname.replace(/[/-]/g, ' ').trim() ||
+                  'Home'
+    document.title = template.replace('%s', title.charAt(0).toUpperCase() + title.slice(1))
+  }
+
+  _focus() {
+    if (!this._targetEl) return
+    const h1 = this._targetEl.querySelector('h1')
+    if (h1) {
+      h1.setAttribute('tabindex', '-1')
+      h1.focus({ preventScroll: true })
+    }
+  }
+
+  _bindLinks() {
+    if (!this._targetEl) return
+    const links = this._targetEl.querySelectorAll('[data-safa-link]')
+    for (const el of links) {
+      el.addEventListener('click', (e) => {
+        if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return
+        if (e.button !== 0) return
+        e.preventDefault()
+        const href = el.getAttribute('href')
+        if (href) this.push(href)
+      })
+    }
+  }
+
+  async _loadComponent(mod) {
+    if (!mod) return null
+    try {
+      if (typeof mod === 'string') {
+        const res = await fetch(mod)
+        if (!res.ok) throw new Error(`Failed to load ${mod} (${res.status})`)
+        return res.text()
+      }
+      if (typeof mod === 'function') {
+        let result
+        try { result = mod() } catch { return mod }
+        if (result && typeof result.then === 'function') {
+          const resolved = await result
+          return resolved && resolved.default ? resolved.default : resolved
+        }
+        return result !== undefined ? result : mod
+      }
+      return mod
+    } catch (e) {
+      throw new RouteLoadError(
+        typeof mod === 'string' ? mod : (typeof mod === 'function' ? mod.name || 'anonymous' : 'module'),
+        e
+      )
+    }
+  }
+
+  async _handleNotFound(path, method) {
+    emit(this._events, EVENTS.NOT_FOUND, { path })
+
+    const notFound = this._routeData?.node?.notFound || this._globalNotFound
+    if (notFound) {
+      try {
+        const fn = await this._loadComponent(notFound)
+        if (method === 'push') this._history.push(path)
+        else if (method === 'replace') this._history.replace(path)
+        this._pathname = path
+        const html = typeof fn === 'function' ? fn({ path, router: this }) : fn
+        if (this._targetEl) this._targetEl.innerHTML = html
+        return
+      } catch { /* fall through */ }
+    }
+    if (this._targetEl) this._targetEl.innerHTML = this._fallback404(path)
+  }
+
+  async _handleError(path, err) {
+    console.error('[SafaRouter]', err)
+    emit(this._events, EVENTS.ERROR, { path, error: err })
+
+    if (this._globalError) {
+      try {
+        const fn = await this._loadComponent(this._globalError)
+        const html = typeof fn === 'function' ? fn({ error: err, path, router: this }) : fn
+        if (this._targetEl) this._targetEl.innerHTML = html
+        return
+      } catch { /* fall through */ }
+    }
+    if (this._targetEl) {
+      try {
+        this._targetEl.innerHTML = this._fallbackError(err)
+      } catch {
+        this._targetEl.textContent = `Error: ${err.message}`
+      }
+    }
+  }
+
+  _fallback404(path) {
+    const homeLink = `<a href="/" style="color:var(--color-accent);text-decoration:underline;">Back to home</a>`
+    return [
+      '<div class="safa-error safa-404" style="text-align:center;padding:3rem 0;">',
+      `<h1 style="font-size:4rem;font-weight:800;margin-bottom:0.5rem;">404</h1>`,
+      `<p style="margin-bottom:1rem;">Page not found: <code>${path}</code></p>`,
+      homeLink,
+      '</div>',
+    ].join('')
+  }
+
+  _fallbackError(err) {
+    const homeLink = `<a href="/" style="color:var(--color-accent);text-decoration:underline;">Back to home</a>`
+    return [
+      '<div class="safa-error" style="text-align:center;padding:3rem 0;">',
+      '<h1 style="font-size:2rem;font-weight:800;margin-bottom:0.5rem;">Something went wrong</h1>',
+      `<pre style="text-align:left;margin:1rem 0;">${err.message}</pre>`,
+      homeLink,
+      '</div>',
+    ].join('')
+  }
+
+  get currentRoute() { return this._routeData }
+  get matchedRoute() { return this._matcher.match(this._pathname) }
+
+  getRoute(path) {
+    return this._routeTree.resolve(normalizePath(path))
+  }
+
+  _onHistoryChange({ path, action, state }) {
+    if (action === 'popstate') {
+      this._resolve(path, 'replace')
+      if (state && state._scrollY !== undefined && !this.config.scrollToTop) {
+        window.scrollTo(0, state._scrollY)
+      }
+    }
+  }
+}

package/src/constants.js

@@ -0,0 +1,47 @@
+/** Navigation lifecycle event names */
+export const EVENTS = {
+  BEFORE_NAVIGATE: 'beforenavigate',
+  NAVIGATE: 'navigate',
+  ROUTE_CHANGE: 'routechange',
+  AFTER_NAVIGATE: 'afternavigate',
+  ERROR: 'error',
+  NOT_FOUND: 'notfound',
+  LOADING: 'loading',
+  READY: 'ready',
+  DESTROY: 'destroy',
+  LINK_CLICK: 'linkclick',
+}
+
+export const SEGMENT_TYPES = {
+  STATIC: 'static',
+  DYNAMIC: 'dynamic',
+  CATCH_ALL: 'catch-all',
+  OPTIONAL_CATCH_ALL: 'optional-catch-all',
+  GROUP: 'group',
+}
+
+export const PARAM_PATTERNS = {
+  DYNAMIC: /^\[([^\]]+)\]$/,
+  CATCH_ALL: /^\[\.\.\.([^\]]+)\]$/,
+  OPTIONAL_CATCH_ALL: /^\[\[\.\.\.[^\]]+\]\]$/,
+  GROUP: /^\(([^)]+)\)$/,
+}
+
+export const PATTERN_SCORES = {
+  [SEGMENT_TYPES.STATIC]: 100,
+  [SEGMENT_TYPES.DYNAMIC]: 10,
+  [SEGMENT_TYPES.CATCH_ALL]: 1,
+  [SEGMENT_TYPES.OPTIONAL_CATCH_ALL]: 0,
+  [SEGMENT_TYPES.GROUP]: 0,
+}
+
+export const DEFAULT_CONFIG = {
+  target: '#app',
+  basePath: '',
+  useHash: false,
+  scrollToTop: true,
+  prefetch: true,
+  cacheRoutes: true,
+  titleTemplate: '%s — SafaRouter',
+  transitionDuration: 0,
+}

package/src/errors.js

@@ -0,0 +1,46 @@
+export class SafaError extends Error {
+  constructor(message, code = 'UNKNOWN') {
+    super(message)
+    this.name = 'SafaError'
+    this.code = code
+  }
+
+  toJSON() {
+    return { name: this.name, message: this.message, code: this.code }
+  }
+}
+
+export class RouteNotFoundError extends SafaError {
+  constructor(pathname) {
+    super(`No route matched: ${pathname}`, 'ROUTE_NOT_FOUND')
+    this.name = 'RouteNotFoundError'
+    this.pathname = pathname
+  }
+}
+
+export class NavigationError extends SafaError {
+  constructor(message, pathname) {
+    super(message, 'NAVIGATION_ERROR')
+    this.name = 'NavigationError'
+    this.pathname = pathname
+  }
+}
+
+export class RouteLoadError extends SafaError {
+  constructor(pathname, original) {
+    super(
+      `Failed to load route "${pathname}": ${original.message}`,
+      'ROUTE_LOAD_ERROR'
+    )
+    this.name = 'RouteLoadError'
+    this.pathname = pathname
+    this.original = original
+  }
+}
+
+export class NavigationAbortError extends SafaError {
+  constructor(reason = 'Navigation cancelled by middleware') {
+    super(reason, 'NAVIGATION_ABORTED')
+    this.name = 'NavigationAbortError'
+  }
+}

package/src/index.js

@@ -0,0 +1,16 @@
+export { SafaRouter } from './SafaRouter.js'
+export { RouteTree } from './RouteTree.js'
+export { RouteMatcher } from './RouteMatcher.js'
+export { HistoryManager } from './HistoryManager.js'
+export { MiddlewareChain } from './MiddlewareChain.js'
+export { Link } from './Link.js'
+export {
+  SafaError,
+  RouteNotFoundError,
+  NavigationError,
+  RouteLoadError,
+  NavigationAbortError,
+} from './errors.js'
+export { normalizePath, parseQuery, joinPaths, createURL, isExternalURL, isSamePath, isDynamicSegment, isCatchAllSegment, isOptionalCatchAll, isRouteGroupSegment, useRouter } from './utils.js'
+export { bindLinks, prefetchOnHover } from './link-helper.js'
+export { EVENTS, DEFAULT_CONFIG } from './constants.js'

package/src/link-helper.js

@@ -0,0 +1,24 @@
+export function bindLinks(router, scope = document) {
+  scope.addEventListener('click', (e) => {
+    const link = e.target.closest('[data-safa-link]')
+    if (!link) return
+    if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return
+    if (e.button !== 0) return
+    const href = link.getAttribute('href')
+    if (!href) return
+    e.preventDefault()
+    router.push(href)
+  })
+}
+
+export function prefetchOnHover(router) {
+  let timer
+  document.addEventListener('mouseenter', (e) => {
+    const link = e.target.closest('[data-safa-link]')
+    if (!link) return
+    const href = link.getAttribute('href')
+    if (!href) return
+    clearTimeout(timer)
+    timer = setTimeout(() => router.prefetch(href), 100)
+  }, true)
+}