@zenithbuild/router 1.0.1

package/src/manifest.ts

@@ -0,0 +1,208 @@
+import fs from "fs"
+import path from "path"
+import native from "../index.js"
+import {
+    type RouteDefinition,
+    type ParsedSegment,
+    SegmentType
+} from "./types"
+
+const { generateRouteManifestNative } = native
+
+/**
+ * Scoring constants for route ranking
+ */
+const SEGMENT_SCORES = {
+    [SegmentType.Static]: 10,
+    [SegmentType.Dynamic]: 5,
+    [SegmentType.CatchAll]: 1,
+    [SegmentType.OptionalCatchAll]: 0
+} as const
+
+/**
+ * Discover all .zen files in the pages directory
+ */
+export function discoverPages(pagesDir: string): string[] {
+    const pages: string[] = []
+
+    function walk(dir: string): void {
+        if (!fs.existsSync(dir)) return
+
+        const entries = fs.readdirSync(dir, { withFileTypes: true })
+
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name)
+
+            if (entry.isDirectory()) {
+                walk(fullPath)
+            } else if (entry.isFile() && entry.name.endsWith(".zen")) {
+                pages.push(fullPath)
+            }
+        }
+    }
+
+    walk(pagesDir)
+    return pages
+}
+
+/**
+ * Convert a file path to a route path
+ */
+export function filePathToRoutePath(filePath: string, pagesDir: string): string {
+    const relativePath = path.relative(pagesDir, filePath)
+    const withoutExt = relativePath.replace(/\.zen$/, "")
+    const segmentsList = withoutExt.split(path.sep)
+    const routeSegments: string[] = []
+
+    for (const segment of segmentsList) {
+        if (segment === "index") continue
+
+        const optionalCatchAllMatch = segment.match(/^\[\[\.\.\.(\w+)\]\]$/)
+        if (optionalCatchAllMatch) {
+            routeSegments.push(`*${optionalCatchAllMatch[1]}?`)
+            continue
+        }
+
+        const catchAllMatch = segment.match(/^\[\.\.\.(\w+)\]$/)
+        if (catchAllMatch) {
+            routeSegments.push(`*${catchAllMatch[1]}`)
+            continue
+        }
+
+        const dynamicMatch = segment.match(/^\[(\w+)\]$/)
+        if (dynamicMatch) {
+            routeSegments.push(`:${dynamicMatch[1]}`)
+            continue
+        }
+
+        routeSegments.push(segment)
+    }
+
+    const routePath = "/" + routeSegments.join("/")
+    return routePath === "/" ? "/" : routePath.replace(/\/$/, "")
+}
+
+/**
+ * Parse a route path into segments
+ */
+export function parseRouteSegments(routePath: string): ParsedSegment[] {
+    if (routePath === "/") return []
+
+    const segmentsList = routePath.slice(1).split("/")
+    const parsed: ParsedSegment[] = []
+
+    for (const segment of segmentsList) {
+        if (segment.startsWith("*") && segment.endsWith("?")) {
+            parsed.push({ segmentType: SegmentType.OptionalCatchAll, paramName: segment.slice(1, -1), raw: segment })
+            continue
+        }
+        if (segment.startsWith("*")) {
+            parsed.push({ segmentType: SegmentType.CatchAll, paramName: segment.slice(1), raw: segment })
+            continue
+        }
+        if (segment.startsWith(":")) {
+            parsed.push({ segmentType: SegmentType.Dynamic, paramName: segment.slice(1), raw: segment })
+            continue
+        }
+        parsed.push({ segmentType: SegmentType.Static, raw: segment })
+    }
+
+    return parsed
+}
+
+/**
+ * Calculate route score
+ */
+export function calculateRouteScore(segments: ParsedSegment[]): number {
+    if (segments.length === 0) return 100
+    let score = 0
+    for (const segment of segments) {
+        score += SEGMENT_SCORES[segment.segmentType]
+    }
+    const staticCount = segments.filter(s => s.segmentType === SegmentType.Static).length
+    score += staticCount * 2
+    return score
+}
+
+/**
+ * Extract parameter names
+ */
+export function extractParamNames(segments: ParsedSegment[]): string[] {
+    return segments
+        .filter(s => s.paramName !== undefined)
+        .map(s => s.paramName!)
+}
+
+/**
+ * Convert route path to regex pattern
+ */
+export function routePathToRegex(routePath: string): RegExp {
+    if (routePath === "/") return /^\/$/
+
+    const segmentsList = routePath.slice(1).split("/")
+    const regexParts: string[] = []
+
+    for (let i = 0; i < segmentsList.length; i++) {
+        const segment = segmentsList[i]
+        if (!segment) continue
+
+        if (segment.startsWith("*") && segment.endsWith("?")) {
+            regexParts.push("(?:\\/(.*))?")
+            continue
+        }
+        if (segment.startsWith("*")) {
+            regexParts.push("\\/(.+)")
+            continue
+        }
+        if (segment.startsWith(":")) {
+            regexParts.push("\\/([^/]+)")
+            continue
+        }
+        const escaped = segment.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+        regexParts.push(`\\/${escaped}`)
+    }
+
+    return new RegExp(`^${regexParts.join("")}\\/?$`)
+}
+
+/**
+ * Generate a route definition from a file path
+ */
+export function generateRouteDefinition(filePath: string, pagesDir: string): RouteDefinition {
+    const routePath = filePathToRoutePath(filePath, pagesDir)
+    const segments = parseRouteSegments(routePath)
+    const paramNames = extractParamNames(segments)
+    const score = calculateRouteScore(segments)
+
+    // Note: RouteDefinition extends RouteRecord, which no longer has segments
+    return {
+        path: routePath,
+        paramNames,
+        score,
+        filePath,
+        regex: routePathToRegex(routePath)
+    }
+}
+
+export function generateRouteManifest(pagesDir: string): RouteDefinition[] {
+    // Optional: use native generator if available, but for now we keep the TS one for build-time safety
+    const pages = discoverPages(pagesDir)
+    const definitions = pages.map(filePath => generateRouteDefinition(filePath, pagesDir))
+    definitions.sort((a, b) => b.score - a.score)
+    return definitions
+}
+
+export function generateRouteManifestCode(definitions: RouteDefinition[]): string {
+    const routeEntries = definitions.map(def => {
+        const regex = routePathToRegex(def.path)
+        return `  {
+    path: ${JSON.stringify(def.path)},
+    regex: ${regex.toString()},
+    paramNames: ${JSON.stringify(def.paramNames)},
+    score: ${def.score},
+    filePath: ${JSON.stringify(def.filePath)}
+  }`
+    })
+
+    return `// Auto-generated route manifest\n// Do not edit directly\n\nexport const routeManifest = [\n${routeEntries.join(",\n")}\n];\n`
+}

package/src/navigation/ZenLink.zen

@@ -0,0 +1,231 @@
+<script>
+// Props extend HTMLAnchorElement properties + custom ZenLink attributes
+// Standard anchor attributes: href, target, rel, download, hreflang, type, ping, referrerPolicy, etc.
+// Custom ZenLink attributes: preload, exact, onClick
+type Props = {
+  // Standard HTMLAnchorElement attributes
+  href?: string
+  target?: '_blank' | '_self' | '_parent' | '_top' | string
+  rel?: string
+  download?: string | boolean
+  hreflang?: string
+  type?: string
+  ping?: string
+  referrerPolicy?: string
+  class?: string
+  id?: string
+  title?: string
+  ariaLabel?: string
+  role?: string
+  tabIndex?: number | string
+  // Custom ZenLink attributes
+  preload?: boolean
+  exact?: boolean
+  onClick?: (event?: MouseEvent) => void | boolean
+}
+
+/**
+ * Handle link click - prevents default and uses SPA navigation
+ * Respects target="_blank" and other standard anchor behaviors
+ */
+function handleClick(event, el) {
+  // Ensure attributes are set from props
+  if (el) {
+    ensureAttributes(el)
+  }
+  
+  // Get target from the element attribute (more reliable than prop)
+  const linkTarget = el ? el.getAttribute('target') : (typeof target !== 'undefined' ? target : null)
+  
+  // If target is _blank, _parent, or _top, let browser handle it (opens in new tab/window)
+  if (linkTarget === '_blank' || linkTarget === '_parent' || linkTarget === '_top') {
+    // Let browser handle standard navigation
+    return
+  }
+  
+  // Allow modifier keys for native behavior (Cmd/Ctrl+click, etc.)
+  if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
+    return
+  }
+  
+  // Get href from element or prop
+  const linkHref = el ? el.getAttribute('href') : (typeof href !== 'undefined' ? href : null)
+  if (!linkHref) return
+  
+  // Check if external URL (http://, https://, //, mailto:, tel:, etc.)
+  if (linkHref.startsWith('http://') || 
+      linkHref.startsWith('https://') || 
+      linkHref.startsWith('//') ||
+      linkHref.startsWith('mailto:') ||
+      linkHref.startsWith('tel:') ||
+      linkHref.startsWith('javascript:')) {
+    // External/special link - open in new tab if target not specified
+    if (!linkTarget) {
+      el?.setAttribute('target', '_blank')
+      el?.setAttribute('rel', 'noopener noreferrer')
+    }
+    // Let browser handle it
+    return
+  }
+  
+  // Prevent default navigation for internal SPA links
+  event.preventDefault()
+  event.stopPropagation()
+  
+  // Call onClick prop if provided
+  if (typeof onClick === 'function') {
+    const result = onClick(event)
+    // If onClick returns false, cancel navigation
+    if (result === false) {
+      return
+    }
+  }
+  
+  // Normalize path for comparison
+  const normalizedHref = linkHref === '' ? '/' : linkHref
+  const currentPath = window.location.pathname === '' ? '/' : window.location.pathname
+  
+  // Only navigate if path is different (idempotent navigation)
+  if (normalizedHref !== currentPath) {
+    console.log('[ZenLink] Navigating to:', linkHref)
+    // Navigate using SPA router
+    if (window.__zenith_router && window.__zenith_router.navigate) {
+      console.log('[ZenLink] Using router.navigate')
+      window.__zenith_router.navigate(linkHref)
+    } else {
+      console.log('[ZenLink] Using fallback history API')
+      // Fallback to history API
+      window.history.pushState(null, '', linkHref)
+      window.dispatchEvent(new PopStateEvent('popstate'))
+    }
+  } else {
+    console.log('[ZenLink] Already on route:', linkHref, '- skipping navigation')
+  }
+}
+
+/**
+ * Handle mouse enter for preloading
+ */
+function handleMouseEnter(event, el) {
+  // Ensure attributes are set
+  if (el) {
+    ensureAttributes(el)
+  }
+  
+  const shouldPreload = typeof preload !== 'undefined' ? preload : false
+  console.log('[ZenLink] handleMouseEnter called, preload:', shouldPreload)
+  if (!shouldPreload) {
+    console.log('[ZenLink] Preload disabled, returning early')
+    return
+  }
+  
+  const linkHref = el ? el.getAttribute('href') : (typeof href !== 'undefined' ? href : null)
+  if (!linkHref) {
+    return
+  }
+  
+  // Skip external URLs
+  if (linkHref.startsWith('http://') || linkHref.startsWith('https://') || linkHref.startsWith('//')) {
+    return
+  }
+  
+  console.log('[ZenLink] Prefetch triggered on hover:', linkHref)
+  
+  // Prefetch the route
+  if (window.__zenith_router && window.__zenith_router.prefetch) {
+    console.log('[ZenLink] Calling router.prefetch for:', linkHref)
+    window.__zenith_router.prefetch(linkHref).then(() => {
+      console.log('[ZenLink] Prefetch complete for:', linkHref)
+    }).catch((error) => {
+      console.warn('[ZenLink] Prefetch failed for:', linkHref, error)
+    })
+  } else {
+    console.warn('[ZenLink] Router prefetch not available')
+  }
+}
+
+// Apply attributes on mount
+if (typeof zenOnMount !== 'undefined') {
+  zenOnMount(() => {
+    setTimeout(() => {
+      // Find all ZenLink anchor elements and apply attributes
+      document.querySelectorAll('a[data-zen-component="Zenlink"]').forEach(el => {
+        ensureAttributes(el)
+      })
+    }, 0)
+  })
+}
+
+/**
+ * Apply standard anchor attributes from props to the element
+ * Called when the element is clicked to ensure attributes are set
+ */
+function ensureAttributes(el) {
+  if (!el) return
+  
+  // Set attributes from props (only if they exist and aren't already set)
+  const attrs = {
+    target: typeof target !== 'undefined' ? target : null,
+    rel: typeof rel !== 'undefined' ? rel : null,
+    download: typeof download !== 'undefined' ? download : null,
+    hreflang: typeof hreflang !== 'undefined' ? hreflang : null,
+    type: typeof type !== 'undefined' ? type : null,
+    ping: typeof ping !== 'undefined' ? ping : null,
+    referrerPolicy: typeof referrerPolicy !== 'undefined' ? referrerPolicy : null,
+    id: typeof id !== 'undefined' ? id : null,
+    title: typeof title !== 'undefined' ? title : null,
+    ariaLabel: typeof ariaLabel !== 'undefined' ? ariaLabel : null,
+    role: typeof role !== 'undefined' ? role : null,
+    tabIndex: typeof tabIndex !== 'undefined' ? tabIndex : null
+  }
+  
+  // Map to HTML attribute names
+  const htmlAttrs = {
+    target: 'target',
+    rel: 'rel',
+    download: 'download',
+    hreflang: 'hreflang',
+    type: 'type',
+    ping: 'ping',
+    referrerPolicy: 'referrerpolicy',
+    id: 'id',
+    title: 'title',
+    ariaLabel: 'aria-label',
+    role: 'role',
+    tabIndex: 'tabindex'
+  }
+  
+  // Set attributes that have values
+  for (const [prop, value] of Object.entries(attrs)) {
+    if (value !== null && value !== undefined && value !== '') {
+      const htmlAttr = htmlAttrs[prop]
+      if (htmlAttr && !el.hasAttribute(htmlAttr)) {
+        el.setAttribute(htmlAttr, String(value))
+      }
+    }
+  }
+}
+
+</script>
+
+<style>
+.zen-link {
+  color: inherit;
+  text-decoration: none;
+  cursor: pointer;
+}
+
+.zen-link:hover {
+  text-decoration: underline;
+}
+</style>
+
+<a 
+  href="{ href }"
+  class="zen-link { class }"
+  onclick="handleClick"
+  onmouseenter="handleMouseEnter"
+  style="cursor: pointer;"
+>
+  <slot />
+</a>

package/src/navigation/index.ts

@@ -0,0 +1,79 @@
+/**
+ * Zenith Navigation System
+ * 
+ * Provides SPA navigation utilities and the ZenLink API.
+ * 
+ * @package @zenithbuild/router
+ * 
+ * @example
+ * ```ts
+ * import { navigate, isActive, prefetch, zenLink } from '@zenithbuild/router/navigation'
+ * 
+ * // Programmatic navigation
+ * navigate('/about')
+ * 
+ * // Check active state
+ * if (isActive('/blog')) {
+ *   console.log('On blog section')
+ * }
+ * 
+ * // Prefetch for faster navigation
+ * prefetch('/dashboard')
+ * 
+ * // Create link programmatically
+ * const link = zenLink({ href: '/contact', children: 'Contact' })
+ * ```
+ */
+
+// Export all navigation utilities
+export {
+    // Navigation API
+    zenNavigate,
+    navigate,
+    zenBack,
+    back,
+    zenForward,
+    forward,
+    zenGo,
+    go,
+
+    // Active state
+    zenIsActive,
+    isActive,
+
+    // Prefetching
+    zenPrefetch,
+    prefetch,
+    zenIsPrefetched,
+    isPrefetched,
+
+    // Transitions API
+    setGlobalTransition,
+    getGlobalTransition,
+    createTransitionContext,
+
+    // Route state
+    zenGetRoute,
+    getRoute,
+    zenGetParam,
+    getParam,
+    zenGetQuery,
+    getQuery,
+
+    // ZenLink factory
+    createZenLink,
+    zenLink,
+
+    // Utilities
+    isExternalUrl,
+    shouldUseSPANavigation,
+    normalizePath
+} from './zen-link'
+
+// Export types
+export type {
+    ZenLinkProps,
+    TransitionContext,
+    TransitionHandler,
+    NavigateOptions
+} from './zen-link'