@zenithbuild/router 0.5.0-beta.2.3

package/dist/navigation/zen-link.js

@@ -0,0 +1,437 @@
+/**
+ * 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')
+ * }
+ * ```
+ */
+// ============================================
+// Internal State
+// ============================================
+/** Prefetched routes cache */
+const prefetchedRoutes = new Set();
+/** Global transition handler (set at layout level) */
+let globalTransitionHandler = null;
+/** Navigation in progress flag */
+let isNavigating = false;
+// ============================================
+// Utilities
+// ============================================
+/**
+ * Check if URL is external (different origin)
+ */
+export function isExternalUrl(url) {
+    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, target) {
+    // 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) {
+    // 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, options = {}) {
+    // Prevent concurrent navigations
+    if (isNavigating) {
+        console.warn('[ZenLink] Navigation already in progress');
+        return;
+    }
+    isNavigating = true;
+    try {
+        // Access global router
+        const router = window.__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() {
+    window.history.back();
+}
+export const back = zenBack;
+/**
+ * Navigate forward in history
+ */
+export function zenForward() {
+    window.history.forward();
+}
+export const forward = zenForward;
+/**
+ * Navigate to a specific history index
+ */
+export function zenGo(delta) {
+    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, exact = false) {
+    const router = window.__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) {
+    // 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.__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) {
+    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) {
+    globalTransitionHandler = handler;
+}
+/**
+ * Get current global transition handler
+ */
+export function getGlobalTransition() {
+    return globalTransitionHandler;
+}
+/**
+ * Create a transition context
+ */
+export function createTransitionContext(fromPath, toPath, direction = 'forward') {
+    return {
+        currentPage: document.querySelector('[data-zen-page]'),
+        nextPage: null,
+        betweenPage: null,
+        direction,
+        fromPath,
+        toPath,
+        params: {},
+        query: {}
+    };
+}
+// ============================================
+// Route State
+// ============================================
+/**
+ * Get current route state
+ */
+export function zenGetRoute() {
+    const router = window.__zenith_router;
+    if (router && router.getRoute) {
+        return router.getRoute();
+    }
+    // Fallback
+    const query = {};
+    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) {
+    return zenGetRoute().params[name];
+}
+export const getParam = zenGetParam;
+/**
+ * Get a query parameter
+ */
+export function zenGetQuery(name) {
+    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) {
+    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) => {
+        // 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;
+//# sourceMappingURL=zen-link.js.map

package/dist/navigation/zen-link.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zen-link.js","sourceRoot":"","sources":["../../src/navigation/zen-link.ts"],"names":[],"mappings":"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"}

package/dist/router.js

@@ -0,0 +1,111 @@
+// ---------------------------------------------------------------------------
+// router.js — Zenith Router V0
+// ---------------------------------------------------------------------------
+// Router assembly: wires match engine + history + runtime mount/unmount.
+//
+// Usage:
+//   const router = createRouter({ routes, container });
+//   router.start();
+//
+// - Explicit start() — no side effects on import or creation
+// - Mount/unmount delegated to @zenithbuild/runtime
+// - Deterministic first-match-wins
+// ---------------------------------------------------------------------------
+
+import { matchRoute } from './match.js';
+import { listen, current } from './history.js';
+import { _dispatchRouteChange } from './events.js';
+import { _setNavigationResolver } from './navigate.js';
+
+/**
+ * Create a router instance.
+ *
+ * @param {{ routes: Array<{ path: string, load: Function }>, container: HTMLElement, mount?: Function, cleanup?: Function }} config
+ * @returns {{ start: () => Promise<void>, destroy: () => void }}
+ */
+export function createRouter(config) {
+    const { routes, container } = config;
+
+    // Allow injecting mount/cleanup for testing without importing runtime
+    const mountFn = config.mount || null;
+    const cleanupFn = config.cleanup || null;
+
+    if (!container || !(container instanceof HTMLElement)) {
+        throw new Error('[Zenith Router] createRouter() requires an HTMLElement container');
+    }
+
+    if (!Array.isArray(routes) || routes.length === 0) {
+        throw new Error('[Zenith Router] createRouter() requires a non-empty routes array');
+    }
+
+    let _unlisten = null;
+    let _started = false;
+    let _hasMounted = false;
+
+    /**
+     * Resolve a path: match → load → mount.
+     *
+     * @param {string} path
+     */
+    async function _resolve(path) {
+        const result = matchRoute(routes, path);
+
+        if (!result) {
+            _dispatchRouteChange({ path, matched: false });
+            return;
+        }
+
+        // Teardown previous page (only if we've mounted before)
+        if (_hasMounted && cleanupFn) {
+            cleanupFn();
+        }
+
+        // Load module
+        const pageModule = await result.route.load(result.params);
+
+        // Mount new page
+        if (mountFn) {
+            mountFn(container, pageModule);
+            _hasMounted = true;
+        }
+
+        _dispatchRouteChange({
+            path,
+            params: result.params,
+            matched: true
+        });
+    }
+
+    /**
+     * Start the router — match initial route and begin listening.
+     */
+    async function start() {
+        if (_started) return;
+        _started = true;
+
+        // Wire navigate() to use our resolver
+        _setNavigationResolver(_resolve);
+
+        // Listen for popstate (back/forward)
+        _unlisten = listen((path) => {
+            _resolve(path);
+        });
+
+        // Initial route
+        await _resolve(current());
+    }
+
+    /**
+     * Tear down the router — remove listeners, clear state.
+     */
+    function destroy() {
+        if (_unlisten) {
+            _unlisten();
+            _unlisten = null;
+        }
+        _setNavigationResolver(null);
+        _started = false;
+    }
+
+    return { start, destroy };
+}

package/dist/runtime.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Zenith Runtime Router (Native Bridge)
+ *
+ * SPA-style client-side router with SSR support via native resolution.
+ */
+import type { RouteState, NavigateOptions, RuntimeRouteRecord, RouteListener } from "./types";
+export declare function initRouter(manifest: RuntimeRouteRecord[], outlet?: HTMLElement | string): void;
+/**
+ * Resolve route - uses native implementation if available (Node.js/SSR)
+ * or falls back to JS implementation for the browser.
+ */
+export declare function resolveRoute(pathname: string): {
+    record: RuntimeRouteRecord;
+    params: Record<string, string>;
+} | null;
+export declare function navigate(to: string, options?: NavigateOptions): Promise<void>;
+export declare function getRoute(): RouteState;
+/**
+ * zenRoute() - Zenith Law: Environment Resolution
+ *
+ * Canonical primitive for resolving the current route environment.
+ * Must be resolved once and execute before state initialization.
+ */
+export declare function zenRoute(): {
+    path: string;
+    slugs: string[];
+};
+export declare function onRouteChange(listener: RouteListener): () => void;
+export declare function isActive(path: string, exact?: boolean): boolean;
+export declare function prefetch(path: string): Promise<void>;
+export declare function isPrefetched(_path: string): boolean;
+export declare function generateRuntimeRouterCode(): string;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EACV,UAAU,EACV,eAAe,EAGf,kBAAkB,EAClB,aAAa,EACd,MAAM,SAAS,CAAA;AAgBhB,wBAAgB,UAAU,CACxB,QAAQ,EAAE,kBAAkB,EAAE,EAC9B,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM,GAC5B,IAAI,CAON;AAcD;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,MAAM,GACf;IAAE,MAAM,EAAE,kBAAkB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,IAAI,CA6BvE;AA8CD,wBAAsB,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CASvF;AAGD,wBAAgB,QAAQ,IAAI,UAAU,CAAwB;AAE9D;;;;;GAKG;AACH,wBAAgB,QAAQ,IAAI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAM5D;AAMD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,IAAI,CAGjE;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,OAAe,GAAG,OAAO,CAEtE;AAED,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAK1D;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAiB;AAErE,wBAAgB,yBAAyB,IAAI,MAAM,CAElD"}