@jk2908/solas 0.16.3 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.17.0
+
+### Breaking
+
+- Removed `prefetch="none"`. Use `prefetch={false}` or omit the prop.
+
+### Features
+
+- `Link` supports `prefetch="viewport"` and `prefetch="auto"`. Viewport prefetches on intersection; auto uses hover on hover-capable devices and viewport elsewhere.
+- Viewport prefetching uses one shared `IntersectionObserver` per router root instead of one per link.
+- `prefetch={false}` is now the explicit off value.
+
+### Changed
+
+- `Link` prefetch modes are resolved once into a single strategy before event handling.
+- `Link` forwards refs with `useImperativeHandle` instead of merging callback refs manually.
+- Examples use React 19.3.1.
+
 ## 0.16.3
 
 ### Fixes

package/README.md

@@ -125,10 +125,12 @@ Use `Link` for same-origin app navigation. Prefetching is opt-in:
 <Link href="/posts">Posts</Link>
 <Link href="/posts" prefetch="intent">Prefetch on focus or touch</Link>
 <Link href="/posts" prefetch="hover">Prefetch on hover</Link>
+<Link href="/posts" prefetch="viewport">Prefetch when visible</Link>
+<Link href="/posts" prefetch="auto">Hover or viewport, depending on input</Link>
 <Link href="/p/:id" params={{ id: 'post-1' }}>Typed params</Link>
 ```
 
-`prefetch="none"` is the default. Nothing is prefetched unless you opt in with `Link` or call `router.prefetch(...)`.
+`prefetch={false}` is the default. `intent` prefetches on focus or touch, `hover` after a short mouse hover, `viewport` when the link enters the viewport, and `auto` uses hover on hover-capable devices and viewport otherwise. Prefetches are skipped for hidden pages, save-data connections and 2G/slow-2G. Nothing is prefetched unless you opt in with `Link` or call `router.prefetch(...)`.
 
 Use `useRouter()` inside client components for programmatic navigation, prefetching, and refreshing the current route:
 

package/dist/internal/browser-router/link.d.ts

@@ -2,14 +2,15 @@ import * as BrowserRouter from './shared.js';
 type AnchorProps = React.ComponentPropsWithRef<'a'> & {
     href: string;
 };
+type PrefetchMode = 'intent' | 'hover' | 'viewport' | 'auto';
 type BaseProps = {
-    prefetch?: 'intent' | 'hover' | 'none';
+    prefetch?: PrefetchMode | false;
 } & AnchorProps;
 type Props = BaseProps & BrowserRouter.LinkProps;
 /**
  * A link component that navigates to a given target.
  * @param href - The route target to navigate to.
- * @param prefetch - When to prefetch the linked page, defaults to 'none'.
+ * @param prefetch - When to prefetch the linked page, defaults to false.
  * @param rest - Other props to pass to the underlying anchor element.
  * @returns A link element that navigates to the given target.
  */

package/dist/internal/browser-router/link.js

@@ -1,8 +1,10 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useEffect, useRef } from 'react';
+import { useEffect, useImperativeHandle, useRef } from 'react';
+import { usePrefetchObserver } from './prefetch-observer.js';
 import * as BrowserRouter from './shared.js';
 import { useRouter } from './use-router.js';
+const HOVER_DELAY = 100;
 function guard(path, prefetcher) {
     const connection = window.navigator.connection;
     if (document.visibilityState === 'hidden')
@@ -13,14 +15,42 @@ function guard(path, prefetcher) {
         return;
     prefetcher(path);
 }
-export function Link({ children, href, params, prefetch = 'none', query, scroll, ...rest }) {
+function getPrefetchStrategy(prefetch, hover, hasObserver) {
+    if (prefetch !== 'auto')
+        return prefetch;
+    if (hover)
+        return 'hover';
+    return hasObserver ? 'viewport' : 'intent';
+}
+export function Link({ children, href, params, prefetch = false, query, ref, scroll, ...rest }) {
     const { go, prefetch: prefetcher } = useRouter();
+    const observer = usePrefetchObserver();
     const timer = useRef(null);
-    // track whether the link is meant to be handled by the router, to avoid
-    // unnecessary prefetching and event handling for external links
+    const anchor = useRef(null);
     const handled = useRef(false);
+    const { onClick, onFocus, onTouchStart, onMouseEnter, onMouseLeave, ...anchorProps } = rest;
     const target = BrowserRouter.toTarget(href, params, query);
-    // clear any pending hover-prefetch timer on unmount
+    const hoverable = typeof window !== 'undefined' &&
+        typeof window.matchMedia === 'function' &&
+        window.matchMedia('(hover: hover) and (pointer: fine)').matches;
+    const observable = typeof IntersectionObserver !== 'undefined';
+    const prefetchStrategy = getPrefetchStrategy(prefetch, hoverable, observable);
+    useImperativeHandle(ref, () => anchor.current, []);
+    function navigate(e) {
+        onClick?.(e);
+        if (e.defaultPrevented)
+            return;
+        if (e.button !== 0)
+            return;
+        if (e.metaKey || e.altKey || e.ctrlKey || e.shiftKey)
+            return;
+        if (anchorProps.target && anchorProps.target !== '_self')
+            return;
+        if (anchorProps.download || handled.current)
+            return;
+        e.preventDefault();
+        go(href, { params, query, scroll });
+    }
     useEffect(() => () => {
         if (timer.current)
             clearTimeout(timer.current);
@@ -30,54 +60,36 @@ export function Link({ children, href, params, prefetch = 'none', query, scroll,
             BrowserRouter.isHashOnlyTarget(target) ||
                 BrowserRouter.isExternalTarget(target, window.location.origin);
     }, [target]);
-    return (_jsx("a", { ...rest, href: target, onClick: e => {
-            rest.onClick?.(e);
-            if (e.defaultPrevented)
-                return;
-            // only intercept plain left-click same-origin navigations
-            if (e.button !== 0)
-                return;
-            if (e.metaKey || e.altKey || e.ctrlKey || e.shiftKey)
-                return;
-            if (rest.target && rest.target !== '_self')
-                return;
-            if (rest.download)
-                return;
-            if (handled.current)
-                return;
-            e.preventDefault();
-            go(href, { params, query, scroll });
-        }, onFocus: e => {
-            rest.onFocus?.(e);
-            if (e.defaultPrevented)
-                return;
-            if (prefetch !== 'intent')
-                return;
-            if (handled.current)
+    useEffect(() => {
+        const node = anchor.current;
+        if (!node || prefetchStrategy !== 'viewport' || !observable || !observer)
+            return;
+        if (BrowserRouter.isHashOnlyTarget(target) ||
+            BrowserRouter.isExternalTarget(target, window.location.origin)) {
+            return;
+        }
+        observer.observe(node, () => guard(target, prefetcher));
+        return () => observer.unobserve(node);
+    }, [observable, observer, prefetcher, prefetchStrategy, target]);
+    return (_jsx("a", { ...anchorProps, ref: anchor, href: target, onClick: navigate, onFocus: e => {
+            onFocus?.(e);
+            if (prefetchStrategy !== 'intent' || e.defaultPrevented || handled.current)
                 return;
             guard(target, prefetcher);
         }, onTouchStart: e => {
-            rest.onTouchStart?.(e);
-            if (e.defaultPrevented)
-                return;
-            if (prefetch !== 'intent')
-                return;
-            if (handled.current)
+            onTouchStart?.(e);
+            if (prefetchStrategy !== 'intent' || e.defaultPrevented || handled.current)
                 return;
             guard(target, prefetcher);
         }, onMouseEnter: e => {
-            rest.onMouseEnter?.(e);
-            if (e.defaultPrevented)
-                return;
-            if (prefetch !== 'hover')
-                return;
-            if (handled.current)
+            onMouseEnter?.(e);
+            if (prefetchStrategy !== 'hover' || e.defaultPrevented || handled.current)
                 return;
             timer.current = setTimeout(() => {
                 guard(target, prefetcher);
-            }, 100);
+            }, HOVER_DELAY);
         }, onMouseLeave: e => {
-            rest.onMouseLeave?.(e);
+            onMouseLeave?.(e);
             if (timer.current) {
                 clearTimeout(timer.current);
                 timer.current = null;

package/dist/internal/browser-router/prefetch-observer.d.ts

@@ -0,0 +1,11 @@
+type Callback = () => void;
+export declare const DEFAULT_PREFETCH_MARGIN = "200px";
+export type PrefetchObserver = {
+    observe: (el: Element, callback: Callback) => void;
+    unobserve: (el: Element) => void;
+};
+export declare function usePrefetchObserver(): PrefetchObserver | null;
+export declare function PrefetchObserverProvider({ children }: {
+    children: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/internal/browser-router/prefetch-observer.js

@@ -0,0 +1,56 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, use, useEffect, useMemo, useRef } from 'react';
+export const DEFAULT_PREFETCH_MARGIN = '200px';
+const PrefetchObserverContext = createContext(null);
+export function usePrefetchObserver() {
+    return use(PrefetchObserverContext);
+}
+function getObserver(callbacks, observer) {
+    if (observer.current)
+        return observer.current;
+    if (typeof IntersectionObserver === 'undefined')
+        return null;
+    observer.current = new IntersectionObserver(entries => {
+        for (const entry of entries) {
+            if (!entry.isIntersecting)
+                continue;
+            const callback = callbacks.get(entry.target);
+            if (!callback)
+                continue;
+            callbacks.delete(entry.target);
+            observer.current?.unobserve(entry.target);
+            callback();
+        }
+        if (callbacks.size === 0) {
+            observer.current?.disconnect();
+            observer.current = null;
+        }
+    }, { rootMargin: DEFAULT_PREFETCH_MARGIN });
+    return observer.current;
+}
+export function PrefetchObserverProvider({ children }) {
+    const callbacks = useRef(new Map());
+    const observer = useRef(null);
+    const value = useMemo(() => ({
+        observe(el, callback) {
+            callbacks.current.set(el, callback);
+            getObserver(callbacks.current, observer)?.observe(el);
+        },
+        unobserve(el) {
+            callbacks.current.delete(el);
+            if (callbacks.current.size === 0) {
+                observer.current?.disconnect();
+                observer.current = null;
+                return;
+            }
+            observer.current?.unobserve(el);
+        },
+    }), []);
+    useEffect(() => () => {
+        observer.current?.disconnect();
+        callbacks.current.clear();
+        observer.current = null;
+    }, [value]);
+    return _jsx(PrefetchObserverContext, { value: value, children: children });
+}

package/dist/internal/browser-router/router.js

@@ -6,6 +6,7 @@ import { getDocumentNonce } from '../../utils/get-document-nonce.js';
 import { Logger } from '../../utils/logger.js';
 import * as Events from '../../events.js';
 import { BrowserRouterHistory } from './history.js';
+import { PrefetchObserverProvider } from './prefetch-observer.js';
 import { ResponseCache } from './response-cache.js';
 import * as BrowserRouter from './shared.js';
 export * as BrowserRouter from './shared.js';
@@ -297,5 +298,5 @@ export function BrowserRouterProvider({ children, setPayload, isNavigating = fal
             index: history.current.index,
         },
     }), [go, prefetch, refresh, isNavigating, url]);
-    return _jsx(BrowserRouterContext, { value: value, children: children });
+    return (_jsx(PrefetchObserverProvider, { children: _jsx(BrowserRouterContext, { value: value, children: children }) }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@jk2908/solas",
-	"version": "0.16.3",
+	"version": "0.17.0",
 	"description": "A Vite + React meta-framework exploring streaming, Server Components, and partial prerendering. Designed for simplicity and lightness",
 	"keywords": [
 		"framework",