@fictjs/router 0.2.2 → 0.3.0

package/src/scroll.ts

@@ -0,0 +1,245 @@
+/**
+ * @fileoverview Scroll restoration utilities for @fictjs/router
+ *
+ * This module provides scroll position management including:
+ * - Saving scroll positions per location key
+ * - Restoring scroll on back/forward navigation
+ * - Scrolling to top on new navigation
+ * - Hash scrolling support (#section)
+ */
+
+import type { Location } from './types'
+import { isBrowser } from './utils'
+
+// ============================================================================
+// Scroll Position Storage
+// ============================================================================
+
+/** Stored scroll positions keyed by location key */
+const scrollPositions = new Map<string, { x: number; y: number }>()
+
+/** Maximum number of positions to store to prevent memory leaks */
+const MAX_STORED_POSITIONS = 100
+
+/**
+ * Save the current scroll position for a location
+ */
+export function saveScrollPosition(key: string): void {
+  if (!isBrowser()) return
+
+  scrollPositions.set(key, {
+    x: window.scrollX,
+    y: window.scrollY,
+  })
+
+  // Evict oldest entries if we exceed the limit
+  if (scrollPositions.size > MAX_STORED_POSITIONS) {
+    const firstKey = scrollPositions.keys().next().value
+    if (firstKey) {
+      scrollPositions.delete(firstKey)
+    }
+  }
+}
+
+/**
+ * Get the saved scroll position for a location
+ */
+export function getSavedScrollPosition(key: string): { x: number; y: number } | undefined {
+  return scrollPositions.get(key)
+}
+
+/**
+ * Clear saved scroll position for a location
+ */
+export function clearScrollPosition(key: string): void {
+  scrollPositions.delete(key)
+}
+
+/**
+ * Clear all saved scroll positions
+ */
+export function clearAllScrollPositions(): void {
+  scrollPositions.clear()
+}
+
+// ============================================================================
+// Scroll Actions
+// ============================================================================
+
+/**
+ * Scroll to a specific position
+ */
+export function scrollTo(x: number, y: number, behavior: ScrollBehavior = 'auto'): void {
+  if (!isBrowser()) return
+
+  window.scrollTo({
+    left: x,
+    top: y,
+    behavior,
+  })
+}
+
+/**
+ * Scroll to top of the page
+ */
+export function scrollToTop(behavior: ScrollBehavior = 'auto'): void {
+  scrollTo(0, 0, behavior)
+}
+
+/**
+ * Scroll to an element by ID (hash navigation)
+ */
+export function scrollToHash(hash: string, behavior: ScrollBehavior = 'auto'): boolean {
+  if (!isBrowser() || !hash) return false
+
+  // Remove the leading #
+  const id = hash.startsWith('#') ? hash.slice(1) : hash
+  if (!id) return false
+
+  const element = document.getElementById(id)
+  if (element) {
+    element.scrollIntoView({ behavior })
+    return true
+  }
+
+  return false
+}
+
+/**
+ * Restore scroll position for a location
+ * Returns true if position was restored
+ */
+export function restoreScrollPosition(key: string): boolean {
+  if (!isBrowser()) return false
+
+  const position = scrollPositions.get(key)
+  if (position) {
+    // Use requestAnimationFrame to ensure DOM has updated
+    requestAnimationFrame(() => {
+      scrollTo(position.x, position.y)
+    })
+    return true
+  }
+
+  return false
+}
+
+// ============================================================================
+// Scroll Restoration Manager
+// ============================================================================
+
+export interface ScrollRestorationOptions {
+  /** Whether scroll restoration is enabled */
+  enabled?: boolean
+  /** Whether to restore scroll on back/forward navigation */
+  restoreOnPop?: boolean
+  /** Whether to scroll to top on push navigation */
+  scrollToTopOnPush?: boolean
+  /** Default scroll behavior */
+  behavior?: ScrollBehavior
+}
+
+const defaultOptions: Required<ScrollRestorationOptions> = {
+  enabled: true,
+  restoreOnPop: true,
+  scrollToTopOnPush: true,
+  behavior: 'auto',
+}
+
+/**
+ * Create a scroll restoration manager
+ */
+export function createScrollRestoration(options: ScrollRestorationOptions = {}) {
+  const config = { ...defaultOptions, ...options }
+
+  // Disable browser's native scroll restoration
+  if (isBrowser() && 'scrollRestoration' in history) {
+    history.scrollRestoration = 'manual'
+  }
+
+  /**
+   * Handle navigation to save/restore scroll
+   */
+  function handleNavigation(
+    from: Location | null,
+    to: Location,
+    action: 'PUSH' | 'REPLACE' | 'POP',
+  ): void {
+    if (!config.enabled || !isBrowser()) return
+
+    // Save current position before navigating
+    if (from?.key) {
+      saveScrollPosition(from.key)
+    }
+
+    // Determine what scroll action to take
+    if (action === 'POP' && config.restoreOnPop) {
+      // Back/forward navigation - try to restore position
+      if (!restoreScrollPosition(to.key)) {
+        // No saved position, handle hash or scroll to top
+        if (to.hash) {
+          requestAnimationFrame(() => {
+            if (!scrollToHash(to.hash, config.behavior)) {
+              scrollToTop(config.behavior)
+            }
+          })
+        } else {
+          scrollToTop(config.behavior)
+        }
+      }
+    } else if ((action === 'PUSH' || action === 'REPLACE') && config.scrollToTopOnPush) {
+      // New navigation - handle hash or scroll to top
+      requestAnimationFrame(() => {
+        if (to.hash) {
+          if (!scrollToHash(to.hash, config.behavior)) {
+            scrollToTop(config.behavior)
+          }
+        } else {
+          scrollToTop(config.behavior)
+        }
+      })
+    }
+  }
+
+  /**
+   * Reset scroll restoration to browser defaults
+   */
+  function reset(): void {
+    if (isBrowser() && 'scrollRestoration' in history) {
+      history.scrollRestoration = 'auto'
+    }
+    clearAllScrollPositions()
+  }
+
+  return {
+    handleNavigation,
+    saveScrollPosition,
+    restoreScrollPosition,
+    scrollToTop: () => scrollToTop(config.behavior),
+    scrollToHash: (hash: string) => scrollToHash(hash, config.behavior),
+    reset,
+    config,
+  }
+}
+
+/**
+ * Default scroll restoration instance
+ */
+let defaultScrollRestoration: ReturnType<typeof createScrollRestoration> | null = null
+
+/**
+ * Get or create the default scroll restoration instance
+ */
+export function getScrollRestoration(): ReturnType<typeof createScrollRestoration> {
+  if (!defaultScrollRestoration) {
+    defaultScrollRestoration = createScrollRestoration()
+  }
+  return defaultScrollRestoration
+}
+
+/**
+ * Configure the default scroll restoration
+ */
+export function configureScrollRestoration(options: ScrollRestorationOptions): void {
+  defaultScrollRestoration = createScrollRestoration(options)
+}

package/src/types.ts

@@ -0,0 +1,447 @@
+/**
+ * @fileoverview Core type definitions for @fictjs/router
+ *
+ * This module defines the fundamental types used throughout the router.
+ * Designed to integrate seamlessly with Fict's reactive system.
+ */
+
+import type { FictNode, Component } from '@fictjs/runtime'
+
+// ============================================================================
+// Location Types
+// ============================================================================
+
+/**
+ * Represents a location in the router.
+ * Similar to window.location but with reactive support.
+ */
+export interface Location {
+  /** The pathname portion of the URL (e.g., "/users/123") */
+  pathname: string
+  /** The search/query portion of the URL (e.g., "?page=1") */
+  search: string
+  /** The hash portion of the URL (e.g., "#section") */
+  hash: string
+  /** State associated with this location */
+  state: unknown
+  /** Unique key for this location entry */
+  key: string
+}
+
+/**
+ * Target for navigation - can be a string path or a partial location object
+ */
+export type To = string | Partial<Location>
+
+/**
+ * Navigation intent type
+ */
+export type NavigationIntent = 'initial' | 'navigate' | 'native' | 'preload'
+
+// ============================================================================
+// Parameter Types
+// ============================================================================
+
+/**
+ * Route parameters extracted from the URL
+ */
+export type Params<Key extends string = string> = Readonly<Record<Key, string | undefined>>
+
+/**
+ * Search parameters from the query string
+ */
+export type SearchParams = URLSearchParams
+
+/**
+ * Match filter for validating route parameters
+ */
+export type MatchFilter<T = string> = RegExp | readonly T[] | ((value: string) => boolean)
+
+/**
+ * Match filters for route parameters
+ */
+export type MatchFilters<P extends string = string> = Partial<Record<P, MatchFilter>>
+
+// ============================================================================
+// Route Definition Types
+// ============================================================================
+
+/**
+ * Props passed to route components
+ */
+export interface RouteComponentProps<P extends string = string> {
+  /** Route parameters */
+  params: Params<P>
+  /** Current location */
+  location: Location
+  /** Preloaded data (if preload function is defined) */
+  data?: unknown
+  /** Children routes rendered via <Outlet /> */
+  children?: FictNode
+  /** Allow additional properties for component extensibility */
+  [key: string]: unknown
+}
+
+/**
+ * Preload function arguments
+ */
+export interface PreloadArgs<P extends string = string> {
+  /** Route parameters */
+  params: Params<P>
+  /** Current location */
+  location: Location
+  /** Navigation intent */
+  intent: NavigationIntent
+}
+
+/**
+ * Preload function type
+ */
+export type PreloadFunction<T = unknown, P extends string = string> = (
+  args: PreloadArgs<P>,
+) => T | Promise<T>
+
+/**
+ * Route definition - user-facing configuration
+ */
+export interface RouteDefinition<P extends string = string> {
+  /** Path pattern (e.g., "/users/:id", "/items/:id?") */
+  path?: string
+  /** Component to render for this route */
+  component?: Component<RouteComponentProps<P>>
+  /** Element to render (alternative to component) */
+  element?: FictNode
+  /** Preload function for data loading */
+  preload?: PreloadFunction<unknown, P>
+  /** Nested child routes */
+  children?: RouteDefinition[]
+  /** Parameter validation filters */
+  matchFilters?: MatchFilters<P>
+  /** Whether this is an index route */
+  index?: boolean
+  /** Route key for caching/optimization */
+  key?: string
+  /** Catch-all error boundary element */
+  errorElement?: FictNode
+  /** Loading fallback element */
+  loadingElement?: FictNode
+}
+
+/**
+ * Props for the Route component (JSX-based definition)
+ */
+export interface RouteProps<P extends string = string> extends Omit<
+  RouteDefinition<P>,
+  'children'
+> {
+  /** JSX children (nested Route components) */
+  children?: FictNode
+}
+
+// ============================================================================
+// Match Types
+// ============================================================================
+
+/**
+ * Result of matching a route against a location
+ */
+export interface RouteMatch<P extends string = string> {
+  /** The matched route definition */
+  route: RouteDefinition<P>
+  /** The matched portion of the pathname */
+  pathname: string
+  /** Extracted parameters */
+  params: Params<P>
+  /** The pattern that matched */
+  pattern: string
+}
+
+/**
+ * Internal compiled route with matcher function
+ */
+export interface CompiledRoute {
+  /** Original route definition */
+  route: RouteDefinition
+  /** Normalized path pattern */
+  pattern: string
+  /** Matcher function */
+  matcher: (pathname: string) => RouteMatch | null
+  /** Route score for ranking */
+  score: number
+  /** Child compiled routes */
+  children?: CompiledRoute[]
+  /** Unique key for this route */
+  key: string
+}
+
+/**
+ * Branch of routes (for nested route matching)
+ */
+export interface RouteBranch {
+  /** Routes in this branch from root to leaf */
+  routes: CompiledRoute[]
+  /** Combined score for the branch */
+  score: number
+  /** Matcher for the entire branch */
+  matcher: (pathname: string) => RouteMatch[] | null
+}
+
+// ============================================================================
+// Navigation Types
+// ============================================================================
+
+/**
+ * Options for navigation
+ */
+export interface NavigateOptions {
+  /** Replace current history entry instead of pushing */
+  replace?: boolean | undefined
+  /** State to pass with the navigation */
+  state?: unknown
+  /** Scroll to top after navigation */
+  scroll?: boolean | undefined
+  /** Resolve path relative to current route */
+  relative?: 'route' | 'path' | undefined
+}
+
+/**
+ * Navigation function type
+ */
+export interface NavigateFunction {
+  (to: To, options?: NavigateOptions): void
+  (delta: number): void
+}
+
+/**
+ * Navigation state during transitions
+ */
+export interface Navigation {
+  /** Current navigation state */
+  state: 'idle' | 'loading' | 'submitting'
+  /** Target location (if loading) */
+  location?: Location
+  /** Form data (if submitting) */
+  formData?: FormData
+  /** Form action (if submitting) */
+  formAction?: string
+  /** Form method (if submitting) */
+  formMethod?: string
+}
+
+// ============================================================================
+// Context Types
+// ============================================================================
+
+/**
+ * Router context value
+ */
+export interface RouterContextValue {
+  /** Current location (reactive) */
+  location: () => Location
+  /** Route parameters (reactive) */
+  params: () => Params
+  /** Current matches (reactive) */
+  matches: () => RouteMatch[]
+  /** Navigate function */
+  navigate: NavigateFunction
+  /** Whether currently routing */
+  isRouting: () => boolean
+  /** Pending navigation target (if routing) */
+  pendingLocation: () => Location | null
+  /** Base path for the router */
+  base: string
+  /** Resolve a path relative to the current route */
+  resolvePath: (to: To) => string
+}
+
+/**
+ * Route context value (for nested routes)
+ */
+export interface RouteContextValue {
+  /** The current route match */
+  match: () => RouteMatch | undefined
+  /** Preloaded data */
+  data: () => unknown
+  /** Route error (if any) */
+  error?: () => unknown
+  /** Outlet function to render child route */
+  outlet: () => FictNode
+  /** Parent route context */
+  parent?: RouteContextValue
+  /** Resolve path relative to this route */
+  resolvePath: (to: To) => string
+}
+
+// ============================================================================
+// History Types
+// ============================================================================
+
+/**
+ * History action type
+ */
+export type HistoryAction = 'POP' | 'PUSH' | 'REPLACE'
+
+/**
+ * History listener callback
+ */
+export type HistoryListener = (update: { action: HistoryAction; location: Location }) => void
+
+/**
+ * History interface (browser, hash, or memory)
+ */
+export interface History {
+  /** Current action */
+  readonly action: HistoryAction
+  /** Current location */
+  readonly location: Location
+  /** Push a new entry */
+  push(to: To, state?: unknown): void
+  /** Replace the current entry */
+  replace(to: To, state?: unknown): void
+  /** Go forward or backward */
+  go(delta: number): void
+  /** Go back one entry */
+  back(): void
+  /** Go forward one entry */
+  forward(): void
+  /** Listen for location changes */
+  listen(listener: HistoryListener): () => void
+  /** Create an href from a To value */
+  createHref(to: To): string
+  /** Block navigation */
+  block(blocker: Blocker): () => void
+}
+
+/**
+ * Blocker function for preventing navigation
+ */
+export type Blocker = (tx: { action: HistoryAction; location: Location; retry: () => void }) => void
+
+// ============================================================================
+// BeforeLeave Types
+// ============================================================================
+
+/**
+ * Arguments passed to beforeLeave handlers
+ */
+export interface BeforeLeaveEventArgs {
+  /** Target location */
+  to: Location
+  /** Current location */
+  from: Location
+  /** Whether this was prevented */
+  defaultPrevented: boolean
+  /** Prevent the navigation */
+  preventDefault: () => void
+  /** Retry the navigation */
+  retry: (force?: boolean) => void
+}
+
+/**
+ * BeforeLeave handler function
+ */
+export type BeforeLeaveHandler = (e: BeforeLeaveEventArgs) => void | Promise<void>
+
+// ============================================================================
+// Data Loading Types
+// ============================================================================
+
+/**
+ * Submission state
+ */
+export interface Submission<T = unknown> {
+  /** Unique submission key */
+  key: string
+  /** Form data being submitted */
+  formData: FormData
+  /** Submission state */
+  state: 'submitting' | 'loading' | 'idle'
+  /** Result data */
+  result?: T
+  /** Error if submission failed */
+  error?: unknown
+  /** Clear the submission */
+  clear: () => void
+  /** Retry the submission */
+  retry: () => void
+}
+
+/**
+ * Action function type
+ */
+export type ActionFunction<T = unknown> = (
+  formData: FormData,
+  args: { params: Params; request: Request },
+) => T | Promise<T>
+
+/**
+ * Action object returned by createAction
+ */
+export interface Action<T = unknown> {
+  /** Action URL */
+  url: string
+  /** Submit the action */
+  submit: (formData: FormData) => Promise<T>
+  /** Action name */
+  name?: string
+}
+
+/**
+ * Query function type
+ */
+export type QueryFunction<T = unknown, Args extends unknown[] = unknown[]> = (
+  ...args: Args
+) => T | Promise<T>
+
+/**
+ * Query cache entry
+ */
+export interface QueryCacheEntry<T = unknown> {
+  /** Timestamp when cached */
+  timestamp: number
+  /** Cached promise */
+  promise: Promise<T>
+  /** Resolved result */
+  result?: T
+  /** Intent when fetched */
+  intent: NavigationIntent
+}
+
+// ============================================================================
+// Router Configuration Types
+// ============================================================================
+
+/**
+ * Router configuration options
+ */
+export interface RouterOptions {
+  /** Base path for the router */
+  base?: string
+  /** Initial location (for SSR) */
+  url?: string
+  /** History implementation to use */
+  history?: History
+  /** Data preloaded on server */
+  hydrationData?: {
+    loaderData?: Record<string, unknown>
+    actionData?: Record<string, unknown>
+  }
+}
+
+/**
+ * Memory router options
+ */
+export interface MemoryRouterOptions extends RouterOptions {
+  /** Initial entries in the history stack */
+  initialEntries?: string[]
+  /** Initial index in the history stack */
+  initialIndex?: number
+}
+
+/**
+ * Hash router options
+ */
+export interface HashRouterOptions extends RouterOptions {
+  /** Hash type: "slash" for /#/path, "noslash" for /#path */
+  hashType?: 'slash' | 'noslash'
+}