clear-react-router 1.9.4 → 1.9.6

package/README.md

@@ -107,7 +107,7 @@ Component for client-side navigation with prefetch support, active state detecti
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `to` | `string` | required | Target path |
-| `as` | `(props: ElementProps<T>) => ReactElement` | renders `<a>` | Render prop for using a custom element/component instead of the default `<a>`. Receives the computed isActive and isPending values, event handlers, and ref to attach to your own element |
+| `as` | `(props: ElementProps<T>, state: { isActive: boolean; isPending: boolean }) => ReactElement` | renders `<a>` | Render function for using a custom element/component instead of the default <a>. Receives the props to spread onto your element (href, ref, event handlers, className, style, children) as the first argument, and `{ isActive, isPending }` as a separate second argument — kept separate so these values are never accidentally forwarded to the DOM |
 | `exact` | `boolean` | `false` | When `false`, the link is also considered active if the current URL starts with `to` (useful for nested routes) |
 | `prefetch` | `'hover' \| 'render' \| 'viewport' \| 'none'` | `Router` config | Override the global prefetch strategy |
 | `hoverPrefetchDelay` | `number` | `Router` config | Override the global hover delay |
@@ -134,27 +134,68 @@ Component for client-side navigation with prefetch support, active state detecti
 | `'viewport'` | Prefetches when the link enters the viewport (using Intersection Observer) |
 | `'none'` | No prefetching |
 
+### Custom elements via `as`
+
+When using `as` to render a custom component instead of the default `<a>`, your component **must spread all received props onto the underlying host element** — including `ref`. If any prop is dropped, the corresponding feature silently stops working (no error is thrown):
+
+- Missing `ref` → `viewport` prefetch never triggers (the `IntersectionObserver` has nothing to observe).
+- Missing `onClick` → navigation doesn't happen, the link just does nothing.
+- Missing `onMouseEnter`/`onMouseLeave` → `hover` prefetch doesn't trigger.
+- Missing `href` → the link isn't reachable via keyboard, screen readers, "open in new tab", etc.
+
+```tsx
+// ✅ correct — every prop is forwarded to the host element
+const Button = ({ children, ...props }: ElementProps<HTMLButtonElement>) => (
+  <button {...props}>{children}</button>
+);
+
+// ❌ wrong — ref, event handlers, and href are silently dropped
+const Button = ({ children }: { children: ReactNode }) => (
+  <button>{children}</button>
+);
+```
+
+If you only want to add or override specific props (e.g. add a `variant`), spread the received props first, then apply your own on top:
+
+```tsx
+const Button = ({ children, ...props }: ElementProps<HTMLButtonElement>) => (
+  <button {...props} className={`btn ${props.className ?? ''}`}>
+    {children}
+  </button>
+);
+```
+
+> **Note:** Because `as` is called as a plain function rather than rendered via JSX, avoid using React hooks (`useState`, `useEffect`, etc.) inside the function you pass to `as` — it isn't tracked by React as a separate component in the fiber tree. A function written for `as` (like `Button` above, which takes a second `state` argument) also isn't a valid standalone React component and shouldn't be rendered directly as `<Button />` elsewhere.
+
 **Example:**
 
 ```tsx
-import { Router, Link } from 'clear-react-router';
+import { Link, type ElementProps } from 'clear-react-router';
+
+const Button = (
+  { children, ...rest }: ElementProps<HTMLButtonElement>,
+  { isActive }: { isActive: boolean }
+) => (
+  <button {...rest} style={{ background: isActive ? 'tomato' : 'green' }}>
+    {children}
+  </button>
+);
+
+<Link to="/about" as={Button}>To about page</Link>
+
+For third-party components (MUI, Chakra, etc.), wrap them in an inline arrow function — most of them accept a
+single `props` argument and forward it to the host element themselves:
 
-// Render a custom element/component via `as`. The function receives ref, event handlers, isActive/isPending and must render them itself
 import { Button } from '@mui/material';
 
 <Link
-  to="/dashboard"
-  as={({ isActive, isPending, ...props }) => (
-    <Button
-      {...props}
-      variant={isActive ? 'contained' : 'outlined'}
-      sx={{ opacity: isPending ? 0.5 : 1 }}
-    />
-  )}
+  to="/about"
+  as={(props, { isActive }) => <Button {...props} variant={isActive ? 'contained' : 'text'} />}
 >
-  Dashboard
+  To about page
 </Link>
-
+```
+```tsx
 // Global prefetch: hover with 100ms delay
 <Router routes={routes} prefetch="hover" hoverPrefetchDelay={100} />
 

package/dist/components/Link.d.ts

@@ -1,32 +1,20 @@
-import { type CSSProperties, ReactNode, MouseEvent, ReactElement, Ref } from 'react';
-import { RouterProps } from '../types';
-type States = {
+import { type CSSProperties, ReactNode, ReactElement } from 'react';
+import { ElementProps, RouterProps } from '../types';
+type ElementState = {
     isActive: boolean;
     isPending: boolean;
 };
-type ElementProps<T extends HTMLElement = HTMLElement> = {
-    ref: Ref<T>;
-    href: string;
-    isActive: boolean;
-    isPending: boolean;
-    onClick(event: MouseEvent): void;
-    onMouseEnter(event: MouseEvent): void;
-    onMouseLeave(event: MouseEvent): void;
-    className?: string;
-    style?: CSSProperties;
-    children?: ReactNode;
-};
 type LinkProps<T extends HTMLElement = HTMLAnchorElement> = {
     to: string;
     children?: ReactNode;
-    as?: (props: ElementProps<T>) => ReactElement;
+    as?: (props: ElementProps<T>, state: ElementState) => ReactElement;
     prefetch?: RouterProps['prefetch'];
     hoverPrefetchDelay?: number;
-    className?: string | ((arg: States) => string);
+    className?: string | ((arg: ElementState) => string);
     activeClassName?: string;
     pendingClassName?: string;
     beforeNavigate?(): Promise<void>;
-    style?: CSSProperties | ((arg: States) => CSSProperties);
+    style?: CSSProperties | ((arg: ElementState) => CSSProperties);
     exact?: boolean;
 };
 export declare const Link: <T extends HTMLElement = HTMLAnchorElement>({ children, to, as, prefetch: prefetchLink, hoverPrefetchDelay, className, style, beforeNavigate, exact, activeClassName, pendingClassName, }: LinkProps<T>) => ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;

package/dist/index.d.ts

@@ -12,4 +12,4 @@ export { useRouterContext } from './hooks/useRouterContext';
 export { useSearchParams } from './hooks/useSearchParams';
 export { useFormContext } from './hooks/useFormContext';
 export { createRouter } from './utils/utils';
-export type { RouteItem, BlockerState, Location, RouterProps } from './types';
+export type { RouteItem, BlockerState, Location, RouterProps, ElementProps } from './types';

package/dist/index.js

@@ -44,7 +44,7 @@ var createCommitState = ({ routeItemDataState, pendingState }) => (nextLocation,
 //#region constants.ts
 var emptyLoaderState = {};
 //#endregion
-//#region \0@oxc-project+runtime@0.132.0/helpers/typeof.js
+//#region \0@oxc-project+runtime@0.143.0/helpers/esm/typeof.js
 function _typeof(o) {
 	"@babel/helpers - typeof";
 	return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function(o) {
@@ -54,7 +54,7 @@ function _typeof(o) {
 	}, _typeof(o);
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.132.0/helpers/toPrimitive.js
+//#region \0@oxc-project+runtime@0.143.0/helpers/esm/toPrimitive.js
 function toPrimitive(t, r) {
 	if ("object" != _typeof(t) || !t) return t;
 	var e = t[Symbol.toPrimitive];
@@ -66,13 +66,13 @@ function toPrimitive(t, r) {
 	return ("string" === r ? String : Number)(t);
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.132.0/helpers/toPropertyKey.js
+//#region \0@oxc-project+runtime@0.143.0/helpers/esm/toPropertyKey.js
 function toPropertyKey(t) {
 	var i = toPrimitive(t, "string");
 	return "symbol" == _typeof(i) ? i : i + "";
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.132.0/helpers/defineProperty.js
+//#region \0@oxc-project+runtime@0.143.0/helpers/esm/defineProperty.js
 function _defineProperty(e, r, t) {
 	return (r = toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
 		value: t,
@@ -133,7 +133,8 @@ var createIsCacheItemFresh = (loaderMap) => ({ routeItem, pathname }) => {
 * LICENSE file in the root directory of this source tree.
 */
 var require_react_jsx_runtime_production = /* @__PURE__ */ __commonJSMin(((exports) => {
-	var REACT_ELEMENT_TYPE = Symbol.for("react.transitional.element"), REACT_FRAGMENT_TYPE = Symbol.for("react.fragment");
+	var REACT_ELEMENT_TYPE = Symbol.for("react.transitional.element");
+	var REACT_FRAGMENT_TYPE = Symbol.for("react.fragment");
 	function jsxProd(type, config, maybeKey) {
 		var key = null;
 		void 0 !== maybeKey && (key = "" + maybeKey);
@@ -756,7 +757,7 @@ var useLocation = () => {
 };
 //#endregion
 //#region components/Link.tsx
-var defaultAs = ({ isActive, isPending, ...props }) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)("a", { ...props });
+var defaultAs = (props) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)("a", { ...props });
 var Link = ({ children, to, as = defaultAs, prefetch: prefetchLink, hoverPrefetchDelay, className, style, beforeNavigate, exact = false, activeClassName = "active-link", pendingClassName = "pending-link" }) => {
 	const isPending = useIsRoutePending(to);
 	const { pathname } = useLocation();
@@ -792,7 +793,8 @@ var Link = ({ children, to, as = defaultAs, prefetch: prefetchLink, hoverPrefetc
 		if (prefetch !== "viewport") return;
 		const element = elementRef.current;
 		if (!element) return;
-		const observer = new IntersectionObserver(async () => {
+		const observer = new IntersectionObserver(async ([entry]) => {
+			if (!entry.isIntersecting) return;
 			await router.runtime.prefetch(to);
 			observer.disconnect();
 		});
@@ -830,9 +832,10 @@ var Link = ({ children, to, as = defaultAs, prefetch: prefetchLink, hoverPrefetc
 		onClick: clickHandler,
 		onMouseEnter,
 		onMouseLeave,
-		isActive,
-		isPending,
 		children
+	}, {
+		isActive,
+		isPending
 	});
 };
 //#endregion
@@ -990,8 +993,10 @@ var useSearchParams = () => {
 				currentParams.delete(param);
 				(Array.isArray(value) ? value : [value]).forEach((v) => currentParams.append(param, v));
 				navigateWithSearchParams(currentParams);
-			} else if (typeof param === "function") navigateWithSearchParams(param(currentParams));
-			else throw new Error("useSearchParams first argument must be either function or string");
+			} else if (typeof param === "function") {
+				const newParams = param(currentParams);
+				navigateWithSearchParams(newParams);
+			} else throw new Error("useSearchParams first argument must be either function or string");
 		}, [navigateWithSearchParams, search])
 	};
 };

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentType, Dispatch, ReactElement, ReactNode, SetStateAction } from 'react';
+import { ComponentType, type CSSProperties, Dispatch, MouseEvent, ReactElement, ReactNode, Ref, SetStateAction } from 'react';
 import { Store, useGlobalState } from './create';
 import { Cell } from './cell';
 export type LazyComponent = () => Promise<{
@@ -154,4 +154,14 @@ export type InvalidateResult = {
     path: string;
     data: unknown;
 };
+export type ElementProps<T extends HTMLElement = HTMLElement> = {
+    ref: Ref<T>;
+    href: string;
+    className?: string;
+    style?: CSSProperties;
+    onClick(event: MouseEvent): void;
+    onMouseEnter(event: MouseEvent): void;
+    onMouseLeave(event: MouseEvent): void;
+    children?: ReactNode;
+};
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clear-react-router",
-  "version": "1.9.4",
+  "version": "1.9.6",
   "description": "A lightweight, type-safe routing library for React applications",
   "author": "Andrew Bubnov",
   "scripts": {