specnav-next 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,75 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { Strategy, CacheConfig, PrefetchConfig, MorphConfig, GraphConfig, CacheLayer } from 'specnav-core';
+
+interface ProgressConfig {
+    enabled: boolean;
+    color: string;
+    height: number;
+    showSpinner: boolean;
+    position: "top" | "bottom";
+    minimum: number;
+    easing: string;
+    speed: number;
+    trickle: boolean;
+    trickleSpeed: number;
+}
+interface TransitionConfig {
+    enabled: boolean;
+    duration: number;
+    easing: string;
+}
+interface NavigateProviderProps {
+    children: React.ReactNode;
+    strategy?: Strategy;
+    cache?: Partial<CacheConfig>;
+    prefetch?: Partial<PrefetchConfig>;
+    progress?: Partial<ProgressConfig>;
+    morph?: Partial<MorphConfig>;
+    transitions?: Partial<TransitionConfig>;
+    graph?: Partial<GraphConfig>;
+    onNavigateStart?: (href: string) => void;
+    onNavigateEnd?: (href: string, durationMs: number) => void;
+    onCacheHit?: (href: string, layer: CacheLayer) => void;
+}
+interface NavigateOptions {
+    replace?: boolean;
+    scroll?: boolean;
+    morph?: boolean;
+    cache?: boolean;
+}
+interface LinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
+    href: string;
+    prefetch?: "trajectory" | "hover" | "eager" | false;
+    morph?: boolean;
+    cache?: boolean;
+    replace?: boolean;
+    scroll?: boolean;
+}
+interface UseNavigateReturn {
+    navigate: (href: string, options?: NavigateOptions) => void;
+    back: () => void;
+    forward: () => void;
+    prefetch: (href: string) => Promise<void>;
+    clearCache: (href?: string) => void;
+    isNavigating: boolean;
+    pendingHref: string | null;
+}
+interface UseNavigationStateReturn {
+    isNavigating: boolean;
+    pendingHref: string | null;
+    previousHref: string | null;
+    cacheSize: number;
+    cacheHitRate: number;
+    lastNavigationMs: number;
+    progress: number;
+}
+
+declare function NavigateProvider({ children, strategy, cache: cacheConfig, prefetch: prefetchConfig, progress: progressConfig, morph: morphConfig, graph: graphConfig, onNavigateStart, onNavigateEnd, onCacheHit, }: NavigateProviderProps): react_jsx_runtime.JSX.Element;
+
+declare function Link({ href, prefetch, morph, cache, replace, scroll, children, ...props }: LinkProps): react_jsx_runtime.JSX.Element;
+
+declare function useNavigate(): UseNavigateReturn;
+
+declare function useNavigationState(): UseNavigationStateReturn;
+
+export { Link, type LinkProps, type NavigateOptions, NavigateProvider, type NavigateProviderProps, type ProgressConfig, type TransitionConfig, type UseNavigateReturn, type UseNavigationStateReturn, useNavigate, useNavigationState };

package/dist/index.d.ts

@@ -0,0 +1,75 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { Strategy, CacheConfig, PrefetchConfig, MorphConfig, GraphConfig, CacheLayer } from 'specnav-core';
+
+interface ProgressConfig {
+    enabled: boolean;
+    color: string;
+    height: number;
+    showSpinner: boolean;
+    position: "top" | "bottom";
+    minimum: number;
+    easing: string;
+    speed: number;
+    trickle: boolean;
+    trickleSpeed: number;
+}
+interface TransitionConfig {
+    enabled: boolean;
+    duration: number;
+    easing: string;
+}
+interface NavigateProviderProps {
+    children: React.ReactNode;
+    strategy?: Strategy;
+    cache?: Partial<CacheConfig>;
+    prefetch?: Partial<PrefetchConfig>;
+    progress?: Partial<ProgressConfig>;
+    morph?: Partial<MorphConfig>;
+    transitions?: Partial<TransitionConfig>;
+    graph?: Partial<GraphConfig>;
+    onNavigateStart?: (href: string) => void;
+    onNavigateEnd?: (href: string, durationMs: number) => void;
+    onCacheHit?: (href: string, layer: CacheLayer) => void;
+}
+interface NavigateOptions {
+    replace?: boolean;
+    scroll?: boolean;
+    morph?: boolean;
+    cache?: boolean;
+}
+interface LinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
+    href: string;
+    prefetch?: "trajectory" | "hover" | "eager" | false;
+    morph?: boolean;
+    cache?: boolean;
+    replace?: boolean;
+    scroll?: boolean;
+}
+interface UseNavigateReturn {
+    navigate: (href: string, options?: NavigateOptions) => void;
+    back: () => void;
+    forward: () => void;
+    prefetch: (href: string) => Promise<void>;
+    clearCache: (href?: string) => void;
+    isNavigating: boolean;
+    pendingHref: string | null;
+}
+interface UseNavigationStateReturn {
+    isNavigating: boolean;
+    pendingHref: string | null;
+    previousHref: string | null;
+    cacheSize: number;
+    cacheHitRate: number;
+    lastNavigationMs: number;
+    progress: number;
+}
+
+declare function NavigateProvider({ children, strategy, cache: cacheConfig, prefetch: prefetchConfig, progress: progressConfig, morph: morphConfig, graph: graphConfig, onNavigateStart, onNavigateEnd, onCacheHit, }: NavigateProviderProps): react_jsx_runtime.JSX.Element;
+
+declare function Link({ href, prefetch, morph, cache, replace, scroll, children, ...props }: LinkProps): react_jsx_runtime.JSX.Element;
+
+declare function useNavigate(): UseNavigateReturn;
+
+declare function useNavigationState(): UseNavigationStateReturn;
+
+export { Link, type LinkProps, type NavigateOptions, NavigateProvider, type NavigateProviderProps, type ProgressConfig, type TransitionConfig, type UseNavigateReturn, type UseNavigationStateReturn, useNavigate, useNavigationState };

package/dist/index.js

@@ -0,0 +1,547 @@
+import { createContext, useState, useRef, useEffect, useContext } from 'react';
+import { createAdaptiveMode, createCacheManager, createMorpher, createSpeculativeRenderer, createNavigationGraphLearner, createTrajectoryEngine } from 'specnav-core';
+import { jsxs, jsx } from 'react/jsx-runtime';
+
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/prefetch.ts
+var prefetch_exports = {};
+__export(prefetch_exports, {
+  inflightRequests: () => inflightRequests,
+  prefetchPage: () => prefetchPage
+});
+async function prefetchPage(href, cache, speculator) {
+  if (inflightRequests.has(href)) {
+    await inflightRequests.get(href);
+    return;
+  }
+  const controller = new AbortController();
+  const fetchPromise = fetch(href, {
+    headers: { "x-specnav": "1" },
+    signal: controller.signal
+  }).then((res) => {
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    return res.text();
+  }).then((html) => {
+    if (cache) cache.set(href, html);
+    if (speculator) speculator.speculate(href, html);
+    return html;
+  }).finally(() => {
+    inflightRequests.delete(href);
+  });
+  inflightRequests.set(href, fetchPromise);
+  await fetchPromise;
+}
+var inflightRequests;
+var init_prefetch = __esm({
+  "src/prefetch.ts"() {
+    inflightRequests = /* @__PURE__ */ new Map();
+  }
+});
+var NavigationContext = createContext(null);
+function useNavigationContext() {
+  const ctx = useContext(NavigationContext);
+  if (!ctx) throw new Error("useNavigationContext must be used within NavigateProvider");
+  return ctx;
+}
+function NavigateProvider({
+  children,
+  strategy = "auto",
+  cache: cacheConfig,
+  prefetch: prefetchConfig,
+  progress: progressConfig,
+  morph: morphConfig,
+  graph: graphConfig,
+  onNavigateStart,
+  onNavigateEnd,
+  onCacheHit
+}) {
+  const [isNavigating, setIsNavigating] = useState(false);
+  const [pendingHref, setPendingHref] = useState(null);
+  const [progress, setProgress] = useState(0);
+  const [cacheHits, setCacheHits] = useState(0);
+  const [cacheMisses, setCacheMisses] = useState(0);
+  const navigationStartTime = useRef(null);
+  const [trajectory, setTrajectory] = useState(null);
+  const [cache, setCache] = useState(null);
+  const [morpher, setMorpher] = useState(null);
+  const [speculator, setSpeculator] = useState(null);
+  const [graph, setGraph] = useState(null);
+  const [adaptive, setAdaptive] = useState(null);
+  const wrappedSetNavigating = (href) => {
+    if (href) {
+      navigationStartTime.current = Date.now();
+      onNavigateStart?.(href);
+    } else if (navigationStartTime.current) {
+      const duration = Date.now() - navigationStartTime.current;
+      if (pendingHref) {
+        onNavigateEnd?.(pendingHref, duration);
+      }
+      navigationStartTime.current = null;
+    }
+    setIsNavigating(!!href);
+    setPendingHref(href);
+  };
+  useEffect(() => {
+    const adaptiveEngine = createAdaptiveMode();
+    const cacheEngine = createCacheManager(cacheConfig, {
+      onCacheHit: (href, layer) => {
+        setCacheHits((prev) => prev + 1);
+        onCacheHit?.(href, layer);
+      }
+    });
+    const morpherEngine = createMorpher(morphConfig);
+    const speculatorEngine = createSpeculativeRenderer(3);
+    const graphEngine = createNavigationGraphLearner(graphConfig);
+    adaptiveEngine.waitForInit().then(() => {
+      setAdaptive(adaptiveEngine);
+      setCache(cacheEngine);
+      setMorpher(morpherEngine);
+      setSpeculator(speculatorEngine);
+      setGraph(graphEngine);
+      const effectiveStrategy = adaptiveEngine.getStrategy(strategy);
+      if (effectiveStrategy !== "off" && prefetchConfig?.mode === "trajectory") {
+        const trajectoryEngine = createTrajectoryEngine(prefetchConfig.trajectory, {
+          onPrediction: async (href) => {
+            if (!adaptiveEngine?.shouldPrefetch()) return;
+            const { prefetchPage: prefetchPage2 } = await Promise.resolve().then(() => (init_prefetch(), prefetch_exports));
+            await prefetchPage2(href, cacheEngine, speculatorEngine);
+          },
+          onCancel: (href) => {
+            speculatorEngine?.cancel(href);
+          }
+        });
+        trajectoryEngine.start();
+        setTrajectory(trajectoryEngine);
+      }
+    });
+    const handlePopState = async (e) => {
+      if (!e.state?.specnav) return;
+      const href = window.location.pathname;
+      wrappedSetNavigating(href);
+      setProgress(0.3);
+      try {
+        const html = await cache?.get(href);
+        if (html && morpher) {
+          setProgress(0.7);
+          const parser = new DOMParser();
+          const doc = parser.parseFromString(html, "text/html");
+          const newContent = doc.body;
+          morpher.morph(document.body, newContent);
+          setProgress(1);
+          setTimeout(() => wrappedSetNavigating(null), 100);
+        } else {
+          window.location.reload();
+        }
+      } catch (error) {
+        console.error("Popstate navigation failed:", error);
+        window.location.reload();
+      }
+    };
+    window.addEventListener("popstate", handlePopState);
+    return () => {
+      trajectory?.stop();
+      cache?.destroy();
+      speculator?.cancelAll();
+      window.removeEventListener("popstate", handlePopState);
+    };
+  }, [strategy, cacheConfig, prefetchConfig, morphConfig, graphConfig, onCacheHit, onNavigateEnd]);
+  const value = {
+    trajectory,
+    cache,
+    morpher,
+    speculator,
+    graph,
+    adaptive,
+    isNavigating,
+    pendingHref,
+    progress,
+    cacheHits,
+    cacheMisses,
+    setNavigating: wrappedSetNavigating,
+    setProgress,
+    incrementCacheMiss: () => setCacheMisses((prev) => prev + 1)
+  };
+  return /* @__PURE__ */ jsxs(NavigationContext.Provider, { value, children: [
+    progressConfig?.enabled !== false && /* @__PURE__ */ jsx(ProgressBar, { config: progressConfig, progress, isNavigating }),
+    children
+  ] });
+}
+function ProgressBar({
+  config,
+  progress,
+  isNavigating
+}) {
+  const color = config?.color ?? "#6366f1";
+  const height = config?.height ?? 3;
+  const position = config?.position ?? "top";
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      style: {
+        position: "fixed",
+        [position]: 0,
+        left: 0,
+        right: 0,
+        height: `${height}px`,
+        zIndex: 9999,
+        pointerEvents: "none"
+      },
+      children: /* @__PURE__ */ jsx(
+        "div",
+        {
+          style: {
+            height: "100%",
+            width: `${progress * 100}%`,
+            background: color,
+            transition: isNavigating ? "width 200ms ease" : "opacity 200ms ease",
+            opacity: isNavigating ? 1 : 0
+          }
+        }
+      )
+    }
+  );
+}
+init_prefetch();
+function Link({
+  href,
+  prefetch = "trajectory",
+  morph = true,
+  cache = true,
+  replace = false,
+  scroll = true,
+  children,
+  ...props
+}) {
+  const ctx = useNavigationContext();
+  const linkRef = useRef(null);
+  const abortControllerRef = useRef(null);
+  const isSafeUrl = (url) => {
+    try {
+      const parsed = new URL(url, window.location.origin);
+      return parsed.origin === window.location.origin;
+    } catch {
+      return false;
+    }
+  };
+  useEffect(() => {
+    if (!linkRef.current || !ctx.trajectory || prefetch === false) return;
+    const element = linkRef.current;
+    ctx.trajectory.registerLink(href, element);
+    return () => {
+      ctx.trajectory?.unregisterLink(element);
+      abortControllerRef.current?.abort();
+    };
+  }, [href, ctx.trajectory, prefetch]);
+  const handleMouseEnter = async () => {
+    if (prefetch === "hover" && ctx.adaptive?.shouldPrefetch()) {
+      await prefetchPage2(href);
+    }
+  };
+  const handleMouseLeave = () => {
+  };
+  const handleFocus = async () => {
+    if (ctx.adaptive?.shouldPrefetch()) {
+      await prefetchPage2(href);
+    }
+  };
+  const prefetchPage2 = async (url) => {
+    if (!isSafeUrl(url) || !ctx.cache) return;
+    const cached = await ctx.cache.get(url);
+    if (cached) return;
+    if (inflightRequests.has(url)) {
+      await inflightRequests.get(url);
+      return;
+    }
+    abortControllerRef.current = new AbortController();
+    const fetchPromise = fetch(url, {
+      headers: { "x-specnav": "1" },
+      signal: abortControllerRef.current.signal
+    }).then((res) => res.text()).then((html) => {
+      ctx.cache?.set(url, html);
+      if (ctx.speculator && ctx.adaptive?.shouldSpeculate()) {
+        ctx.speculator.speculate(url, html);
+      }
+      return html;
+    }).catch((err) => {
+      if (err.name !== "AbortError") {
+        console.warn("Prefetch failed:", err);
+      }
+      throw err;
+    }).finally(() => {
+      inflightRequests.delete(url);
+    });
+    inflightRequests.set(url, fetchPromise);
+    await fetchPromise;
+  };
+  const handleClick = async (e) => {
+    if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+    e.preventDefault();
+    if (!isSafeUrl(href)) {
+      window.location.href = href;
+      return;
+    }
+    if (!morph || !ctx.morpher || !ctx.cache) {
+      window.location.href = href;
+      return;
+    }
+    ctx.setNavigating(href);
+    ctx.setProgress(0.3);
+    const timeoutId = setTimeout(() => {
+      console.error("Navigation timeout");
+      ctx.setNavigating(null);
+      window.location.href = href;
+    }, 1e4);
+    try {
+      let newContent = ctx.speculator?.get(href);
+      if (!newContent) {
+        let html = cache ? await ctx.cache.get(href) : null;
+        if (!html) {
+          ctx.incrementCacheMiss();
+          ctx.setProgress(0.5);
+          if (inflightRequests.has(href)) {
+            html = await inflightRequests.get(href);
+          } else {
+            const controller = new AbortController();
+            const fetchPromise = fetch(href, {
+              headers: { "x-specnav": "1" },
+              signal: controller.signal
+            }).then((res) => {
+              if (!res.ok) throw new Error(`HTTP ${res.status}`);
+              return res.text();
+            });
+            inflightRequests.set(href, fetchPromise);
+            html = await fetchPromise;
+            inflightRequests.delete(href);
+          }
+          if (cache) {
+            await ctx.cache.set(href, html);
+          }
+        }
+        ctx.setProgress(0.7);
+        const parser = new DOMParser();
+        const doc = parser.parseFromString(html, "text/html");
+        newContent = doc.body;
+      }
+      ctx.setProgress(0.9);
+      if ("startViewTransition" in document && ctx.adaptive?.shouldUseTransitions()) {
+        await document.startViewTransition(() => {
+          ctx.morpher?.morph(document.body, newContent);
+        }).finished;
+      } else {
+        ctx.morpher?.morph(document.body, newContent);
+      }
+      const currentHref = window.location.pathname;
+      if (replace) {
+        window.history.replaceState({ specnav: true }, "", href);
+      } else {
+        window.history.pushState({ specnav: true }, "", href);
+      }
+      ctx.graph?.recordNavigation(currentHref, href);
+      if (scroll) {
+        window.scrollTo(0, 0);
+      }
+      clearTimeout(timeoutId);
+      ctx.setProgress(1);
+      setTimeout(() => ctx.setNavigating(null), 200);
+    } catch (error) {
+      clearTimeout(timeoutId);
+      console.error("Navigation failed:", error);
+      ctx.setNavigating(null);
+      window.location.href = href;
+    }
+  };
+  return /* @__PURE__ */ jsx(
+    "a",
+    {
+      ref: linkRef,
+      href,
+      onClick: handleClick,
+      onMouseEnter: handleMouseEnter,
+      onMouseLeave: handleMouseLeave,
+      onFocus: handleFocus,
+      ...props,
+      children
+    }
+  );
+}
+
+// src/useNavigate.ts
+init_prefetch();
+function useNavigate() {
+  const ctx = useNavigationContext();
+  const isSafeUrl = (url) => {
+    try {
+      const parsed = new URL(url, window.location.origin);
+      return parsed.origin === window.location.origin;
+    } catch {
+      return false;
+    }
+  };
+  const navigate = async (href, options = {}) => {
+    const {
+      replace = false,
+      scroll = true,
+      morph = true,
+      cache: useCache = true
+    } = options;
+    if (!isSafeUrl(href)) {
+      window.location.href = href;
+      return;
+    }
+    if (!morph || !ctx.morpher || !ctx.cache) {
+      window.location.href = href;
+      return;
+    }
+    ctx.setNavigating(href);
+    ctx.setProgress(0.3);
+    try {
+      let newContent = ctx.speculator?.get(href);
+      if (!newContent) {
+        let html = useCache ? await ctx.cache.get(href) : null;
+        if (!html) {
+          ctx.setProgress(0.5);
+          if (inflightRequests.has(href)) {
+            html = await inflightRequests.get(href);
+          } else {
+            const controller = new AbortController();
+            const fetchPromise = fetch(href, {
+              headers: { "x-specnav": "1" },
+              signal: controller.signal
+            }).then((res) => {
+              if (!res.ok) throw new Error(`HTTP ${res.status}`);
+              return res.text();
+            });
+            inflightRequests.set(href, fetchPromise);
+            html = await fetchPromise;
+            inflightRequests.delete(href);
+          }
+          if (useCache) {
+            await ctx.cache.set(href, html);
+          }
+        }
+        ctx.setProgress(0.7);
+        const parser = new DOMParser();
+        const doc = parser.parseFromString(html, "text/html");
+        newContent = doc.body;
+      }
+      ctx.setProgress(0.9);
+      if ("startViewTransition" in document && ctx.adaptive?.shouldUseTransitions()) {
+        await document.startViewTransition(() => {
+          ctx.morpher?.morph(document.body, newContent);
+        }).finished;
+      } else {
+        ctx.morpher?.morph(document.body, newContent);
+      }
+      const currentHref = window.location.pathname;
+      if (replace) {
+        window.history.replaceState({ specnav: true }, "", href);
+      } else {
+        window.history.pushState({ specnav: true }, "", href);
+      }
+      ctx.graph?.recordNavigation(currentHref, href);
+      if (scroll) {
+        window.scrollTo(0, 0);
+      }
+      ctx.setProgress(1);
+      setTimeout(() => ctx.setNavigating(null), 200);
+    } catch (error) {
+      console.error("Navigation failed:", error);
+      ctx.setNavigating(null);
+      window.location.href = href;
+    }
+  };
+  const back = () => {
+    window.history.back();
+  };
+  const forward = () => {
+    window.history.forward();
+  };
+  const prefetch = async (href) => {
+    if (!ctx.cache || !isSafeUrl(href)) return;
+    try {
+      if (inflightRequests.has(href)) {
+        await inflightRequests.get(href);
+        return;
+      }
+      const controller = new AbortController();
+      const fetchPromise = fetch(href, {
+        headers: { "x-specnav": "1" },
+        signal: controller.signal
+      }).then((res) => res.text()).then((html) => {
+        ctx.cache?.set(href, html);
+        if (ctx.speculator && ctx.adaptive?.shouldSpeculate()) {
+          ctx.speculator.speculate(href, html);
+        }
+        return html;
+      }).finally(() => {
+        inflightRequests.delete(href);
+      });
+      inflightRequests.set(href, fetchPromise);
+      await fetchPromise;
+    } catch (error) {
+      if (error.name !== "AbortError") {
+        console.warn("Prefetch failed:", error);
+      }
+    }
+  };
+  const clearCache = (href) => {
+    ctx.cache?.clear(href);
+    if (href) {
+      ctx.speculator?.cancel(href);
+    } else {
+      ctx.speculator?.cancelAll();
+    }
+  };
+  return {
+    navigate,
+    back,
+    forward,
+    prefetch,
+    clearCache,
+    isNavigating: ctx.isNavigating,
+    pendingHref: ctx.pendingHref
+  };
+}
+function useNavigationState() {
+  const ctx = useNavigationContext();
+  const [previousHref, setPreviousHref] = useState(null);
+  const [lastNavigationMs, setLastNavigationMs] = useState(0);
+  const [startTime, setStartTime] = useState(null);
+  useEffect(() => {
+    if (ctx.isNavigating && ctx.pendingHref) {
+      setPreviousHref(window.location.pathname);
+      setStartTime(Date.now());
+    }
+  }, [ctx.isNavigating, ctx.pendingHref]);
+  useEffect(() => {
+    if (!ctx.isNavigating && startTime !== null) {
+      setLastNavigationMs(Date.now() - startTime);
+      setStartTime(null);
+    }
+  }, [ctx.isNavigating, startTime]);
+  const cacheSize = ctx.cache?.getSize() ?? 0;
+  const totalRequests = ctx.cacheHits + ctx.cacheMisses;
+  const cacheHitRate = totalRequests > 0 ? ctx.cacheHits / totalRequests : 0;
+  return {
+    isNavigating: ctx.isNavigating,
+    pendingHref: ctx.pendingHref,
+    previousHref,
+    cacheSize,
+    cacheHitRate,
+    lastNavigationMs,
+    progress: ctx.progress
+  };
+}
+
+export { Link, NavigateProvider, useNavigate, useNavigationState };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map