@zenithbuild/router 1.0.1

package/src/navigation/zen-link.ts

@@ -0,0 +1,585 @@
+/**
+ * ZenLink Runtime Module
+ * 
+ * Provides programmatic navigation and ZenLink utilities.
+ * This module can be imported in `.zen` files or TypeScript.
+ * 
+ * @package @zenithbuild/router
+ * 
+ * @example
+ * ```ts
+ * import { navigate, zenLink, isActive } from '@zenithbuild/router'
+ * 
+ * // Programmatic navigation
+ * navigate('/about')
+ * 
+ * // Check active state
+ * if (isActive('/blog')) {
+ *   console.log('On blog section')
+ * }
+ * ```
+ */
+
+// ============================================
+// Types
+// ============================================
+
+/**
+ * Props for ZenLink component
+ */
+export interface ZenLinkProps {
+    /** Target URL path */
+    href: string
+    /** Optional CSS class(es) */
+    class?: string
+    /** Link target (_blank, _self, etc.) */
+    target?: '_blank' | '_self' | '_parent' | '_top'
+    /** Click handler (called before navigation) */
+    onClick?: (event: MouseEvent) => void | boolean
+    /** Preload the linked page on hover */
+    preload?: boolean
+    /** Future: Transition configuration */
+    onTransition?: TransitionHandler
+    /** Future: Disable page transition animation */
+    noTransition?: boolean
+    /** Match exact path for active state */
+    exact?: boolean
+    /** Additional aria attributes */
+    ariaLabel?: string
+    /** Replace history instead of push */
+    replace?: boolean
+    /** Link content (children) */
+    children?: string | HTMLElement | HTMLElement[]
+}
+
+/**
+ * Transition context for Transitions API
+ */
+export interface TransitionContext {
+    /** Current page element */
+    currentPage: HTMLElement | null
+    /** Next page element (after load) */
+    nextPage: HTMLElement | null
+    /** Between/loading page element */
+    betweenPage: HTMLElement | null
+    /** Navigation direction */
+    direction: 'forward' | 'back'
+    /** Origin path */
+    fromPath: string
+    /** Destination path */
+    toPath: string
+    /** Route params */
+    params: Record<string, string>
+    /** Query params */
+    query: Record<string, string>
+}
+
+/**
+ * Transition handler function
+ */
+export type TransitionHandler = (context: TransitionContext) => void | Promise<void>
+
+/**
+ * Navigation options
+ */
+export interface NavigateOptions {
+    /** Replace current history entry instead of pushing */
+    replace?: boolean
+    /** Scroll to top after navigation */
+    scrollToTop?: boolean
+    /** Transition handler for this navigation */
+    onTransition?: TransitionHandler
+    /** Skip transition animation */
+    noTransition?: boolean
+    /** State to pass to the next page */
+    state?: Record<string, unknown>
+}
+
+// ============================================
+// Internal State
+// ============================================
+
+/** Prefetched routes cache */
+const prefetchedRoutes = new Set<string>()
+
+/** Global transition handler (set at layout level) */
+let globalTransitionHandler: TransitionHandler | null = null
+
+/** Navigation in progress flag */
+let isNavigating = false
+
+// ============================================
+// Utilities
+// ============================================
+
+/**
+ * Check if URL is external (different origin)
+ */
+export function isExternalUrl(url: string): boolean {
+    if (!url) return false
+
+    // Protocol-relative or absolute URLs with different origin
+    if (url.startsWith('//') || url.startsWith('http://') || url.startsWith('https://')) {
+        try {
+            const linkUrl = new URL(url, window.location.origin)
+            return linkUrl.origin !== window.location.origin
+        } catch {
+            return true
+        }
+    }
+
+    // mailto:, tel:, javascript:, etc.
+    if (/^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(url)) {
+        return true
+    }
+
+    return false
+}
+
+/**
+ * Check if link should use SPA navigation
+ */
+export function shouldUseSPANavigation(href: string, target?: string): boolean {
+    // Don't use SPA for external links
+    if (isExternalUrl(href)) return false
+
+    // Don't use SPA if target is set (except _self)
+    if (target && target !== '_self') return false
+
+    // Don't use SPA for hash-only links on same page
+    if (href.startsWith('#')) return false
+
+    // Don't use SPA for download links or special protocols
+    if (href.startsWith('mailto:') || href.startsWith('tel:') || href.startsWith('javascript:')) {
+        return false
+    }
+
+    return true
+}
+
+/**
+ * Normalize a path
+ */
+export function normalizePath(path: string): string {
+    // Ensure path starts with /
+    if (!path.startsWith('/')) {
+        const currentDir = window.location.pathname.split('/').slice(0, -1).join('/')
+        path = currentDir + '/' + path
+    }
+
+    // Remove trailing slash (except for root)
+    if (path !== '/' && path.endsWith('/')) {
+        path = path.slice(0, -1)
+    }
+
+    return path
+}
+
+// ============================================
+// Navigation API
+// ============================================
+
+/**
+ * Navigate to a new URL (SPA navigation)
+ * 
+ * This is the primary API for programmatic navigation.
+ * 
+ * @example
+ * ```ts
+ * // Simple navigation
+ * navigate('/about')
+ * 
+ * // With options
+ * navigate('/dashboard', { replace: true })
+ * 
+ * // With transition
+ * navigate('/gallery', {
+ *   onTransition: async (ctx) => {
+ *     await animateOut(ctx.currentPage)
+ *     await animateIn(ctx.nextPage)
+ *   }
+ * })
+ * ```
+ */
+export async function zenNavigate(
+    to: string,
+    options: NavigateOptions = {}
+): Promise<void> {
+    // Prevent concurrent navigations
+    if (isNavigating) {
+        console.warn('[ZenLink] Navigation already in progress')
+        return
+    }
+
+    isNavigating = true
+
+    try {
+        // Access global router
+        const router = (window as any).__zenith_router
+
+        if (router && router.navigate) {
+            // Use router's navigate function
+            await router.navigate(to, options)
+        } else {
+            // Fallback: use History API directly
+            const normalizedPath = normalizePath(to)
+
+            if (options.replace) {
+                window.history.replaceState(options.state || null, '', normalizedPath)
+            } else {
+                window.history.pushState(options.state || null, '', normalizedPath)
+            }
+
+            // Dispatch popstate to trigger route resolution
+            window.dispatchEvent(new PopStateEvent('popstate'))
+        }
+
+        // Scroll to top if requested (default: true)
+        if (options.scrollToTop !== false) {
+            window.scrollTo({ top: 0, behavior: 'smooth' })
+        }
+    } finally {
+        isNavigating = false
+    }
+}
+
+// Clean alias
+export const navigate = zenNavigate
+
+/**
+ * Navigate back in history
+ */
+export function zenBack(): void {
+    window.history.back()
+}
+
+export const back = zenBack
+
+/**
+ * Navigate forward in history
+ */
+export function zenForward(): void {
+    window.history.forward()
+}
+
+export const forward = zenForward
+
+/**
+ * Navigate to a specific history index
+ */
+export function zenGo(delta: number): void {
+    window.history.go(delta)
+}
+
+export const go = zenGo
+
+// ============================================
+// Active State
+// ============================================
+
+/**
+ * Check if a path is currently active
+ * 
+ * @example
+ * ```ts
+ * // Check if on blog section
+ * if (isActive('/blog')) {
+ *   addClass(link, 'active')
+ * }
+ * 
+ * // Exact match only
+ * if (isActive('/blog', true)) {
+ *   addClass(link, 'active-exact')
+ * }
+ * ```
+ */
+export function zenIsActive(path: string, exact: boolean = false): boolean {
+    const router = (window as any).__zenith_router
+
+    if (router && router.isActive) {
+        return router.isActive(path, exact)
+    }
+
+    // Fallback: compare with current pathname
+    const currentPath = window.location.pathname
+    const normalizedPath = normalizePath(path)
+
+    if (exact) {
+        return currentPath === normalizedPath
+    }
+
+    // Root path special case
+    if (normalizedPath === '/') {
+        return currentPath === '/'
+    }
+
+    return currentPath.startsWith(normalizedPath)
+}
+
+export const isActive = zenIsActive
+
+// ============================================
+// Prefetching
+// ============================================
+
+/**
+ * Prefetch a route for faster navigation
+ * 
+ * @example
+ * ```ts
+ * // Prefetch on hover
+ * element.addEventListener('mouseenter', () => {
+ *   prefetch('/about')
+ * })
+ * ```
+ */
+export async function zenPrefetch(path: string): Promise<void> {
+    // Normalize path
+    const normalizedPath = normalizePath(path)
+
+    // Don't prefetch if already done
+    if (prefetchedRoutes.has(normalizedPath)) {
+        return
+    }
+
+    // Mark as prefetched
+    prefetchedRoutes.add(normalizedPath)
+
+    // Try router prefetch first
+    const router = (window as any).__zenith_router
+
+    if (router && router.prefetch) {
+        try {
+            await router.prefetch(normalizedPath)
+        } catch {
+            // Silently ignore prefetch errors
+        }
+        return
+    }
+
+    // Fallback: use link preload hint
+    try {
+        const link = document.createElement('link')
+        link.rel = 'prefetch'
+        link.href = normalizedPath
+        link.as = 'document'
+        document.head.appendChild(link)
+    } catch {
+        // Ignore errors
+    }
+}
+
+export const prefetch = zenPrefetch
+
+/**
+ * Check if a route has been prefetched
+ */
+export function zenIsPrefetched(path: string): boolean {
+    return prefetchedRoutes.has(normalizePath(path))
+}
+
+export const isPrefetched = zenIsPrefetched
+
+// ============================================
+// Transitions API
+// ============================================
+
+/**
+ * Set global transition handler
+ * 
+ * This allows setting a layout-level transition that applies to all navigations.
+ * 
+ * @example
+ * ```ts
+ * // In layout component
+ * setGlobalTransition(async (ctx) => {
+ *   ctx.currentPage?.classList.add('fade-out')
+ *   await delay(300)
+ *   ctx.nextPage?.classList.add('fade-in')
+ * })
+ * ```
+ */
+export function setGlobalTransition(handler: TransitionHandler | null): void {
+    globalTransitionHandler = handler
+}
+
+/**
+ * Get current global transition handler
+ */
+export function getGlobalTransition(): TransitionHandler | null {
+    return globalTransitionHandler
+}
+
+/**
+ * Create a transition context
+ */
+export function createTransitionContext(
+    fromPath: string,
+    toPath: string,
+    direction: 'forward' | 'back' = 'forward'
+): TransitionContext {
+    return {
+        currentPage: document.querySelector('[data-zen-page]') as HTMLElement | null,
+        nextPage: null,
+        betweenPage: null,
+        direction,
+        fromPath,
+        toPath,
+        params: {},
+        query: {}
+    }
+}
+
+// ============================================
+// Route State
+// ============================================
+
+/**
+ * Get current route state
+ */
+export function zenGetRoute(): {
+    path: string
+    params: Record<string, string>
+    query: Record<string, string>
+} {
+    const router = (window as any).__zenith_router
+
+    if (router && router.getRoute) {
+        return router.getRoute()
+    }
+
+    // Fallback
+    const query: Record<string, string> = {}
+    const params = new URLSearchParams(window.location.search)
+    params.forEach((value, key) => {
+        query[key] = value
+    })
+
+    return {
+        path: window.location.pathname,
+        params: {},
+        query
+    }
+}
+
+export const getRoute = zenGetRoute
+
+/**
+ * Get a route parameter
+ */
+export function zenGetParam(name: string): string | undefined {
+    return zenGetRoute().params[name]
+}
+
+export const getParam = zenGetParam
+
+/**
+ * Get a query parameter
+ */
+export function zenGetQuery(name: string): string | undefined {
+    return zenGetRoute().query[name]
+}
+
+export const getQuery = zenGetQuery
+
+// ============================================
+// ZenLink Factory (for programmatic creation)
+// ============================================
+
+/**
+ * Create a ZenLink element programmatically
+ * 
+ * @example
+ * ```ts
+ * const link = createZenLink({
+ *   href: '/about',
+ *   class: 'nav-link',
+ *   children: 'About Us'
+ * })
+ * container.appendChild(link)
+ * ```
+ */
+export function createZenLink(props: ZenLinkProps): HTMLAnchorElement {
+    const link = document.createElement('a')
+
+    // Set href
+    link.href = props.href
+
+    // Set class
+    const classes = ['zen-link']
+    if (props.class) classes.push(props.class)
+    if (zenIsActive(props.href, props.exact)) classes.push('zen-link-active')
+    if (isExternalUrl(props.href)) classes.push('zen-link-external')
+    link.className = classes.join(' ')
+
+    // Set target
+    if (props.target) {
+        link.target = props.target
+    } else if (isExternalUrl(props.href)) {
+        link.target = '_blank'
+    }
+
+    // Set rel for security
+    if (isExternalUrl(props.href) || props.target === '_blank') {
+        link.rel = 'noopener noreferrer'
+    }
+
+    // Set aria-label
+    if (props.ariaLabel) {
+        link.setAttribute('aria-label', props.ariaLabel)
+    }
+
+    // Set content
+    if (props.children) {
+        if (typeof props.children === 'string') {
+            link.textContent = props.children
+        } else if (Array.isArray(props.children)) {
+            props.children.forEach(child => link.appendChild(child))
+        } else {
+            link.appendChild(props.children)
+        }
+    }
+
+    // Click handler
+    link.addEventListener('click', (event: MouseEvent) => {
+        // Allow modifier keys for native behavior
+        if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
+            return
+        }
+
+        // Check if we should use SPA navigation
+        if (!shouldUseSPANavigation(props.href, props.target)) {
+            return
+        }
+
+        // Prevent default
+        event.preventDefault()
+
+        // Call user's onClick handler
+        if (props.onClick) {
+            const result = props.onClick(event)
+            if (result === false) return
+        }
+
+        // Navigate
+        zenNavigate(props.href, {
+            replace: props.replace,
+            onTransition: props.onTransition,
+            noTransition: props.noTransition
+        })
+    })
+
+    // Preload on hover
+    if (props.preload) {
+        link.addEventListener('mouseenter', () => {
+            if (shouldUseSPANavigation(props.href, props.target)) {
+                zenPrefetch(props.href)
+            }
+        })
+    }
+
+    return link
+}
+
+// Alias
+export const zenLink = createZenLink

package/src/render.rs

@@ -0,0 +1,8 @@
+use napi_derive::napi;
+
+#[napi]
+pub fn render_route_native(input_json: String) -> String {
+    // This needs actual ZenIR parsing/types to work properly
+    // For now we placeholder since we are separate from compiler-native
+    format!("<!-- Native SSR Placeholder for {} -->", input_json)
+}

package/src/resolve.rs

@@ -0,0 +1,53 @@
+use crate::types::{RouteRecord, RouteState};
+use napi_derive::napi;
+use regex::Regex;
+use std::collections::HashMap;
+
+#[napi]
+pub fn resolve_route_native(path: String, routes: Vec<RouteRecord>) -> Option<RouteState> {
+    let parts: Vec<&str> = path.splitn(2, '?').collect();
+    let pathname = parts[0];
+    let query_str = if parts.len() > 1 { parts[1] } else { "" };
+
+    let query = parse_query_string(query_str);
+
+    for route in routes {
+        let re = Regex::new(&route.regex).ok()?;
+        if let Some(caps) = re.captures(pathname) {
+            let mut params = HashMap::new();
+
+            for (i, name) in route.param_names.iter().enumerate() {
+                if let Some(m) = caps.get(i + 1) {
+                    params.insert(name.clone(), m.as_str().to_string());
+                }
+            }
+
+            return Some(RouteState {
+                path: pathname.to_string(),
+                params,
+                query,
+                matched: Some(route.clone()),
+            });
+        }
+    }
+
+    None
+}
+
+pub fn parse_query_string(query: &str) -> HashMap<String, String> {
+    let mut params = HashMap::new();
+    if query.is_empty() {
+        return params;
+    }
+
+    for pair in query.split('&') {
+        let mut parts = pair.splitn(2, '=');
+        let key = parts.next().unwrap_or("");
+        let val = parts.next().unwrap_or("");
+        if !key.is_empty() {
+            params.insert(key.to_string(), val.to_string());
+        }
+    }
+
+    params
+}