@real-router/preact 0.2.8 → 0.2.10

package/dist/cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/components/RouteView/types.ts","../../src/components/RouteView/components.tsx","../../src/components/RouteView/RouteView.tsx","../../src/types.ts","../../src/components/Link.tsx","../../src/components/RouterErrorBoundary.tsx","../../src/hooks/useRouter.tsx","../../src/hooks/useNavigator.tsx","../../src/hooks/useRouteUtils.tsx","../../src/hooks/useRoute.tsx","../../src/hooks/useRouteNode.tsx","../../src/hooks/useRouterTransition.tsx","../../src/RouterProvider.tsx","../../src/context.ts"],"mappings":";;;;;;;UAEiB,cAAA;EAAA,SACN,QAAA;EAAA,SACA,QAAA,EAAU,iBAAA;AAAA;AAAA,UAGJ,UAAA;EAAA,SACN,OAAA;EAAA,SACA,KAAA;EAAA,SACA,QAAA,GAAW,iBAAA;EAAA,SACX,QAAA,EAAU,iBAAA;AAAA;AAAA,UAGJ,aAAA;EAAA,SACN,QAAA,EAAU,iBAAA;AAAA;;;iBCbL,KAAA,CAAM,MAAA,EAAQ,UAAA;AAAA,kBAAd,KAAA;EAAA,IAAK,WAAA;AAAA;AAAA,iBAML,QAAA,CAAS,MAAA,EAAQ,aAAA;AAAA,kBAAjB,QAAA;EAAA,IAAQ,WAAA;AAAA;;;iBCDf,aAAA,CAAA;EACP,QAAA;EACA;AAAA,GACC,QAAA,CAAS,cAAA,IAAkB,KAAA;AAAA,kBAHrB,aAAA;EAAA,IAAa,WAAA;AAAA;AAAA,cAyBT,SAAA,SAAS,aAAA;;;;;;UCxBL,UAAA,WAAqB,MAAA,GAAS,MAAA;EAC7C,KAAA,EAAO,KAAA,CAAM,CAAA;EACb,aAAA,GAAgB,KAAA;AAAA;AAAA,KAGN,cAAA;EACV,SAAA,EAAW,WAAA;AAAA,IACT,UAAA;AAAA,UAEa,SAAA,WAAoB,MAAA,GAAS,MAAA,UAAgB,IAAA,CAC5D,GAAA,CAAI,cAAA,CAAe,iBAAA;EAGnB,SAAA;EACA,WAAA,GAAc,CAAA;EACd,YAAA,GAAe,iBAAA;EACf,SAAA;EACA,eAAA;EACA,YAAA;EACA,iBAAA;EACA,MAAA;AAAA;;;cCGW,IAAA,EAAM,iBAAA,CAAkB,SAAA;;;UCvBpB,wBAAA;EAAA,SACN,QAAA,EAAU,iBAAA;EAAA,SACV,QAAA,GACP,KAAA,EAAO,WAAA,EACP,UAAA,iBACG,iBAAA;EAAA,SACI,OAAA,IACP,KAAA,EAAO,WAAA,EACP,OAAA,EAAS,KAAA,SACT,SAAA,EAAW,KAAA;AAAA;AAAA,iBAIC,mBAAA,CAAA;EACd,QAAA;EACA,QAAA;EACA;AAAA,GACC,wBAAA,GAA2B,KAAA;;;cCnBjB,SAAA,QAAgB,MAAA;;;cCAhB,YAAA,QAAmB,WAAA;;;cCCnB,aAAA,QAAoB,UAAA;;;cCDpB,QAAA,QAAe,cAAA;;;iBCGZ,YAAA,CAAa,QAAA,WAAmB,cAAA;;;iBCDhC,mBAAA,CAAA,GAAuB,0BAAA;;;UCGtB,kBAAA;EACf,MAAA,EAAQ,MAAA;EACR,QAAA,EAAU,iBAAA;EACV,kBAAA;AAAA;AAAA,cAGW,cAAA,EAAgB,iBAAA,CAAkB,kBAAA;;;cCZlC,YAAA,EAAY,QAAA,CAAA,OAAA,CAAA,cAAA;AAAA,cAEZ,aAAA,EAAa,QAAA,CAAA,OAAA,CAAA,MAAA;AAAA,cAEb,gBAAA,EAAgB,QAAA,CAAA,OAAA,CAAA,WAAA"}

package/dist/esm/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/components/RouteView/types.ts","../../src/components/RouteView/components.tsx","../../src/components/RouteView/RouteView.tsx","../../src/types.ts","../../src/components/Link.tsx","../../src/components/RouterErrorBoundary.tsx","../../src/hooks/useRouter.tsx","../../src/hooks/useNavigator.tsx","../../src/hooks/useRouteUtils.tsx","../../src/hooks/useRoute.tsx","../../src/hooks/useRouteNode.tsx","../../src/hooks/useRouterTransition.tsx","../../src/RouterProvider.tsx","../../src/context.ts"],"mappings":";;;;;;;UAEiB,cAAA;EAAA,SACN,QAAA;EAAA,SACA,QAAA,EAAU,iBAAA;AAAA;AAAA,UAGJ,UAAA;EAAA,SACN,OAAA;EAAA,SACA,KAAA;EAAA,SACA,QAAA,GAAW,iBAAA;EAAA,SACX,QAAA,EAAU,iBAAA;AAAA;AAAA,UAGJ,aAAA;EAAA,SACN,QAAA,EAAU,iBAAA;AAAA;;;iBCbL,KAAA,CAAM,MAAA,EAAQ,UAAA;AAAA,kBAAd,KAAA;EAAA,IAAK,WAAA;AAAA;AAAA,iBAML,QAAA,CAAS,MAAA,EAAQ,aAAA;AAAA,kBAAjB,QAAA;EAAA,IAAQ,WAAA;AAAA;;;iBCDf,aAAA,CAAA;EACP,QAAA;EACA;AAAA,GACC,QAAA,CAAS,cAAA,IAAkB,KAAA;AAAA,kBAHrB,aAAA;EAAA,IAAa,WAAA;AAAA;AAAA,cAyBT,SAAA,SAAS,aAAA;;;;;;UCxBL,UAAA,WAAqB,MAAA,GAAS,MAAA;EAC7C,KAAA,EAAO,KAAA,CAAM,CAAA;EACb,aAAA,GAAgB,KAAA;AAAA;AAAA,KAGN,cAAA;EACV,SAAA,EAAW,WAAA;AAAA,IACT,UAAA;AAAA,UAEa,SAAA,WAAoB,MAAA,GAAS,MAAA,UAAgB,IAAA,CAC5D,GAAA,CAAI,cAAA,CAAe,iBAAA;EAGnB,SAAA;EACA,WAAA,GAAc,CAAA;EACd,YAAA,GAAe,iBAAA;EACf,SAAA;EACA,eAAA;EACA,YAAA;EACA,iBAAA;EACA,MAAA;AAAA;;;cCGW,IAAA,EAAM,iBAAA,CAAkB,SAAA;;;UCvBpB,wBAAA;EAAA,SACN,QAAA,EAAU,iBAAA;EAAA,SACV,QAAA,GACP,KAAA,EAAO,WAAA,EACP,UAAA,iBACG,iBAAA;EAAA,SACI,OAAA,IACP,KAAA,EAAO,WAAA,EACP,OAAA,EAAS,KAAA,SACT,SAAA,EAAW,KAAA;AAAA;AAAA,iBAIC,mBAAA,CAAA;EACd,QAAA;EACA,QAAA;EACA;AAAA,GACC,wBAAA,GAA2B,KAAA;;;cCnBjB,SAAA,QAAgB,MAAA;;;cCAhB,YAAA,QAAmB,WAAA;;;cCCnB,aAAA,QAAoB,UAAA;;;cCDpB,QAAA,QAAe,cAAA;;;iBCGZ,YAAA,CAAa,QAAA,WAAmB,cAAA;;;iBCDhC,mBAAA,CAAA,GAAuB,0BAAA;;;UCGtB,kBAAA;EACf,MAAA,EAAQ,MAAA;EACR,QAAA,EAAU,iBAAA;EACV,kBAAA;AAAA;AAAA,cAGW,cAAA,EAAgB,iBAAA,CAAkB,kBAAA;;;cCZlC,YAAA,EAAY,QAAA,CAAA,OAAA,CAAA,cAAA;AAAA,cAEZ,aAAA,EAAa,QAAA,CAAA,OAAA,CAAA,MAAA;AAAA,cAEb,gBAAA,EAAgB,QAAA,CAAA,OAAA,CAAA,WAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/preact",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "type": "commonjs",
   "description": "Preact integration for Real-Router",
   "main": "./dist/cjs/index.js",
@@ -8,7 +8,6 @@
   "types": "./dist/esm/index.d.mts",
   "exports": {
     ".": {
-      "development": "./src/index.ts",
       "types": {
         "import": "./dist/esm/index.d.mts",
         "require": "./dist/cjs/index.d.ts"
@@ -18,7 +17,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "homepage": "https://github.com/greydragon888/real-router",
   "repository": {
@@ -47,9 +47,9 @@
   "license": "MIT",
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.45.1",
-    "@real-router/route-utils": "^0.1.12",
-    "@real-router/sources": "^0.4.2"
+    "@real-router/core": "^0.46.0",
+    "@real-router/route-utils": "^0.1.14",
+    "@real-router/sources": "^0.4.4"
   },
   "devDependencies": {
     "@testing-library/dom": "10.4.1",
@@ -57,8 +57,8 @@
     "@testing-library/preact": "3.2.4",
     "@testing-library/user-event": "14.6.1",
     "preact": "10.25.4",
-    "@real-router/browser-plugin": "^0.11.5",
-    "dom-utils": "^0.2.7"
+    "@real-router/browser-plugin": "^0.11.7",
+    "dom-utils": "^0.2.8"
   },
   "peerDependencies": {
     "preact": ">=10.0.0"
@@ -66,10 +66,11 @@
   "scripts": {
     "build": "tsdown --config-loader unrun",
     "test": "vitest",
+    "test:properties": "vitest run --config vitest.config.properties.mts",
     "test:stress": "vitest run --config vitest.config.stress.mts",
     "type-check": "tsc --noEmit",
     "lint": "eslint --cache --ext .ts,.tsx src/ tests/ --fix --max-warnings 0",
-    "lint:package": "bash ../../scripts/publint-filter.sh",
+    "lint:package": "publint",
     "lint:types": "attw --pack .",
     "build:dist-only": "tsdown --config-loader unrun"
   }

package/src/RouterProvider.tsx

@@ -0,0 +1,59 @@
+import { getNavigator } from "@real-router/core";
+import { createRouteSource } from "@real-router/sources";
+import { createRouteAnnouncer } from "dom-utils";
+import { useEffect, useMemo } from "preact/hooks";
+
+import { NavigatorContext, RouteContext, RouterContext } from "./context";
+import { useSyncExternalStore } from "./useSyncExternalStore";
+
+import type { Router } from "@real-router/core";
+import type { FunctionComponent, ComponentChildren } from "preact";
+
+export interface RouteProviderProps {
+  router: Router;
+  children: ComponentChildren;
+  announceNavigation?: boolean;
+}
+
+export const RouterProvider: FunctionComponent<RouteProviderProps> = ({
+  router,
+  children,
+  announceNavigation,
+}) => {
+  useEffect(() => {
+    if (!announceNavigation) {
+      return;
+    }
+
+    const announcer = createRouteAnnouncer(router);
+
+    return () => {
+      announcer.destroy();
+    };
+  }, [announceNavigation, router]);
+  const navigator = useMemo(() => getNavigator(router), [router]);
+
+  // useSyncExternalStore manages the router subscription lifecycle:
+  // subscribe connects to router on first listener, unsubscribes on last.
+  const store = useMemo(() => createRouteSource(router), [router]);
+  const { route, previousRoute } = useSyncExternalStore(
+    store.subscribe,
+    store.getSnapshot,
+    store.getSnapshot, // SSR: router returns same state on server and client
+  );
+
+  const routeContextValue = useMemo(
+    () => ({ navigator, route, previousRoute }),
+    [navigator, route, previousRoute],
+  );
+
+  return (
+    <RouterContext.Provider value={router}>
+      <NavigatorContext.Provider value={navigator}>
+        <RouteContext.Provider value={routeContextValue}>
+          {children}
+        </RouteContext.Provider>
+      </NavigatorContext.Provider>
+    </RouterContext.Provider>
+  );
+};

package/src/components/Link.tsx

@@ -0,0 +1,102 @@
+import { shouldNavigate, buildHref, buildActiveClassName } from "dom-utils";
+import { memo } from "preact/compat";
+import { useCallback, useMemo } from "preact/hooks";
+
+import { EMPTY_PARAMS, EMPTY_OPTIONS } from "../constants";
+import { useIsActiveRoute } from "../hooks/useIsActiveRoute";
+import { useRouter } from "../hooks/useRouter";
+import { useStableValue } from "../hooks/useStableValue";
+
+import type { LinkProps } from "../types";
+import type { FunctionComponent, JSX } from "preact";
+
+function areLinkPropsEqual(
+  prev: Readonly<LinkProps>,
+  next: Readonly<LinkProps>,
+): boolean {
+  return (
+    prev.routeName === next.routeName &&
+    prev.className === next.className &&
+    prev.activeClassName === next.activeClassName &&
+    prev.activeStrict === next.activeStrict &&
+    prev.ignoreQueryParams === next.ignoreQueryParams &&
+    prev.onClick === next.onClick &&
+    prev.target === next.target &&
+    prev.style === next.style &&
+    prev.children === next.children &&
+    JSON.stringify(prev.routeParams) === JSON.stringify(next.routeParams) &&
+    JSON.stringify(prev.routeOptions) === JSON.stringify(next.routeOptions)
+  );
+}
+
+export const Link: FunctionComponent<LinkProps> = memo(
+  ({
+    routeName,
+    routeParams = EMPTY_PARAMS,
+    routeOptions = EMPTY_OPTIONS,
+    className,
+    activeClassName = "active",
+    activeStrict = false,
+    ignoreQueryParams = true,
+    onClick,
+    target,
+    children,
+    ...props
+  }) => {
+    const router = useRouter();
+
+    const stableParams = useStableValue(routeParams);
+    const stableOptions = useStableValue(routeOptions);
+
+    const isActive = useIsActiveRoute(
+      routeName,
+      stableParams,
+      activeStrict,
+      ignoreQueryParams,
+    );
+
+    const href = useMemo(
+      () => buildHref(router, routeName, stableParams),
+      [router, routeName, stableParams],
+    );
+
+    const handleClick = useCallback(
+      (evt: JSX.TargetedMouseEvent<HTMLAnchorElement>) => {
+        if (onClick) {
+          onClick(evt);
+
+          if (evt.defaultPrevented) {
+            return;
+          }
+        }
+
+        if (!shouldNavigate(evt) || target === "_blank") {
+          return;
+        }
+
+        evt.preventDefault();
+        router.navigate(routeName, stableParams, stableOptions).catch(() => {});
+      },
+      [onClick, target, router, routeName, stableParams, stableOptions],
+    );
+
+    const finalClassName = useMemo(
+      () => buildActiveClassName(isActive, activeClassName, className),
+      [isActive, activeClassName, className],
+    );
+
+    return (
+      <a
+        {...props}
+        href={href}
+        className={finalClassName}
+        onClick={handleClick}
+      >
+        {children}
+      </a>
+    );
+  },
+  areLinkPropsEqual,
+);
+
+Link.displayName = "Link";

package/src/components/RouteView/RouteView.tsx

@@ -0,0 +1,39 @@
+import { Match, NotFound } from "./components";
+import { buildRenderList, collectElements } from "./helpers";
+import { useRouteNode } from "../../hooks/useRouteNode";
+
+import type { RouteViewProps } from "./types";
+import type { VNode } from "preact";
+
+function RouteViewRoot({
+  nodeName,
+  children,
+}: Readonly<RouteViewProps>): VNode | null {
+  const { route } = useRouteNode(nodeName);
+
+  if (!route) {
+    return null;
+  }
+
+  const elements: VNode[] = [];
+
+  collectElements(children, elements);
+
+  const { rendered } = buildRenderList(elements, route.name, nodeName);
+
+  if (rendered.length > 0) {
+    return <>{rendered}</>;
+  }
+
+  return null;
+}
+
+RouteViewRoot.displayName = "RouteView";
+
+export const RouteView = Object.assign(RouteViewRoot, { Match, NotFound });
+
+export type {
+  RouteViewProps,
+  MatchProps as RouteViewMatchProps,
+  NotFoundProps as RouteViewNotFoundProps,
+} from "./types";

package/src/components/RouteView/components.tsx

@@ -0,0 +1,13 @@
+import type { MatchProps, NotFoundProps } from "./types";
+
+export function Match(_props: MatchProps): null {
+  return null;
+}
+
+Match.displayName = "RouteView.Match";
+
+export function NotFound(_props: NotFoundProps): null {
+  return null;
+}
+
+NotFound.displayName = "RouteView.NotFound";

package/src/components/RouteView/helpers.tsx

@@ -0,0 +1,88 @@
+import { UNKNOWN_ROUTE } from "@real-router/core";
+import { startsWithSegment } from "@real-router/route-utils";
+import { Fragment, isValidElement, toChildArray } from "preact";
+import { Suspense } from "preact/compat";
+
+import { Match, NotFound } from "./components";
+
+import type { MatchProps, NotFoundProps } from "./types";
+import type { VNode, ComponentChildren } from "preact";
+
+function isSegmentMatch(
+  routeName: string,
+  fullSegmentName: string,
+  exact: boolean,
+): boolean {
+  if (exact) {
+    return routeName === fullSegmentName;
+  }
+
+  return startsWithSegment(routeName, fullSegmentName);
+}
+
+export function collectElements(
+  children: ComponentChildren,
+  result: VNode[],
+): void {
+  for (const child of toChildArray(children)) {
+    if (!isValidElement(child)) {
+      continue;
+    }
+
+    if (child.type === Match || child.type === NotFound) {
+      result.push(child);
+    } else {
+      collectElements(
+        (child.props as { readonly children: ComponentChildren }).children,
+        result,
+      );
+    }
+  }
+}
+
+export function buildRenderList(
+  elements: VNode[],
+  routeName: string,
+  nodeName: string,
+): { rendered: VNode[]; activeMatchFound: boolean } {
+  let notFoundChildren: ComponentChildren = null;
+  let activeMatchFound = false;
+  const rendered: VNode[] = [];
+
+  for (const child of elements) {
+    if (child.type === NotFound) {
+      notFoundChildren = (child.props as NotFoundProps).children;
+      continue;
+    }
+
+    const { segment, exact = false, fallback } = child.props as MatchProps;
+    const fullSegmentName = nodeName ? `${nodeName}.${segment}` : segment;
+    const isActive =
+      !activeMatchFound && isSegmentMatch(routeName, fullSegmentName, exact);
+
+    if (isActive) {
+      activeMatchFound = true;
+      const matchChildren = (child.props as MatchProps).children;
+      const content =
+        fallback === undefined ? (
+          matchChildren
+        ) : (
+          <Suspense fallback={fallback}>{matchChildren}</Suspense>
+        );
+
+      rendered.push(<Fragment key={fullSegmentName}>{content}</Fragment>);
+    }
+  }
+
+  if (
+    !activeMatchFound &&
+    routeName === UNKNOWN_ROUTE &&
+    notFoundChildren !== null
+  ) {
+    rendered.push(
+      <Fragment key="__route-view-not-found__">{notFoundChildren}</Fragment>,
+    );
+  }
+
+  return { rendered, activeMatchFound };
+}

package/src/components/RouteView/index.ts

@@ -0,0 +1,7 @@
+export { RouteView } from "./RouteView";
+
+export type {
+  RouteViewProps,
+  RouteViewMatchProps,
+  RouteViewNotFoundProps,
+} from "./RouteView";

package/src/components/RouteView/types.ts

@@ -0,0 +1,17 @@
+import type { ComponentChildren } from "preact";
+
+export interface RouteViewProps {
+  readonly nodeName: string;
+  readonly children: ComponentChildren;
+}
+
+export interface MatchProps {
+  readonly segment: string;
+  readonly exact?: boolean;
+  readonly fallback?: ComponentChildren;
+  readonly children: ComponentChildren;
+}
+
+export interface NotFoundProps {
+  readonly children: ComponentChildren;
+}

package/src/components/RouterErrorBoundary.tsx

@@ -0,0 +1,59 @@
+import { Fragment } from "preact";
+import { useCallback, useEffect, useRef, useState } from "preact/hooks";
+
+import { useRouterError } from "../hooks/useRouterError";
+
+import type { RouterError, State } from "@real-router/core";
+import type { ComponentChildren, VNode } from "preact";
+
+export interface RouterErrorBoundaryProps {
+  readonly children: ComponentChildren;
+  readonly fallback: (
+    error: RouterError,
+    resetError: () => void,
+  ) => ComponentChildren;
+  readonly onError?: (
+    error: RouterError,
+    toRoute: State | null,
+    fromRoute: State | null,
+  ) => void;
+}
+
+export function RouterErrorBoundary({
+  children,
+  fallback,
+  onError,
+}: RouterErrorBoundaryProps): VNode {
+  const snapshot = useRouterError();
+  const [dismissedVersion, setDismissedVersion] = useState(-1);
+
+  const onErrorRef = useRef(onError);
+
+  // eslint-disable-next-line @eslint-react/refs -- "latest ref" pattern: sync callback to ref to avoid effect re-runs
+  onErrorRef.current = onError;
+
+  useEffect(() => {
+    if (snapshot.error) {
+      onErrorRef.current?.(
+        snapshot.error,
+        snapshot.toRoute,
+        snapshot.fromRoute,
+      );
+    }
+    // eslint-disable-next-line @eslint-react/exhaustive-deps -- onError tracked via ref, snapshot fields accessed inside callback
+  }, [snapshot.version]);
+
+  const visibleError =
+    snapshot.version > dismissedVersion ? snapshot.error : null;
+
+  const resetError = useCallback(() => {
+    setDismissedVersion(snapshot.version);
+  }, [snapshot.version]);
+
+  return (
+    <Fragment>
+      {children}
+      {visibleError ? fallback(visibleError, resetError) : null}
+    </Fragment>
+  );
+}

package/src/constants.ts

@@ -0,0 +1,9 @@
+/**
+ * Stable empty object for default params
+ */
+export const EMPTY_PARAMS = Object.freeze({});
+
+/**
+ * Stable empty options object
+ */
+export const EMPTY_OPTIONS = Object.freeze({});

package/src/context.ts

@@ -0,0 +1,10 @@
+import { createContext } from "preact";
+
+import type { RouteContext as RouteContextType } from "./types";
+import type { Router, Navigator } from "@real-router/core";
+
+export const RouteContext = createContext<RouteContextType | null>(null);
+
+export const RouterContext = createContext<Router | null>(null);
+
+export const NavigatorContext = createContext<Navigator | null>(null);

package/src/hooks/useIsActiveRoute.tsx

@@ -0,0 +1,34 @@
+import { createActiveRouteSource } from "@real-router/sources";
+import { useMemo } from "preact/hooks";
+
+import { useSyncExternalStore } from "../useSyncExternalStore";
+import { useRouter } from "./useRouter";
+import { useStableValue } from "./useStableValue";
+
+import type { Params } from "@real-router/core";
+
+export function useIsActiveRoute(
+  routeName: string,
+  params?: Params,
+  strict = false,
+  ignoreQueryParams = true,
+): boolean {
+  const router = useRouter();
+
+  const stableParams = useStableValue(params);
+
+  const store = useMemo(
+    () =>
+      createActiveRouteSource(router, routeName, stableParams, {
+        strict,
+        ignoreQueryParams,
+      }),
+    [router, routeName, stableParams, strict, ignoreQueryParams],
+  );
+
+  return useSyncExternalStore(
+    store.subscribe,
+    store.getSnapshot,
+    store.getSnapshot,
+  );
+}

package/src/hooks/useNavigator.tsx

@@ -0,0 +1,15 @@
+import { useContext } from "preact/hooks";
+
+import { NavigatorContext } from "../context";
+
+import type { Navigator } from "@real-router/core";
+
+export const useNavigator = (): Navigator => {
+  const navigator = useContext(NavigatorContext);
+
+  if (!navigator) {
+    throw new Error("useNavigator must be used within a RouterProvider");
+  }
+
+  return navigator;
+};

package/src/hooks/useRoute.tsx

@@ -0,0 +1,15 @@
+import { useContext } from "preact/hooks";
+
+import { RouteContext } from "../context";
+
+import type { RouteContext as RouteContextType } from "../types";
+
+export const useRoute = (): RouteContextType => {
+  const routeContext = useContext(RouteContext);
+
+  if (!routeContext) {
+    throw new Error("useRoute must be used within a RouteProvider");
+  }
+
+  return routeContext;
+};

package/src/hooks/useRouteNode.tsx

@@ -0,0 +1,30 @@
+import { getNavigator } from "@real-router/core";
+import { createRouteNodeSource } from "@real-router/sources";
+import { useMemo } from "preact/hooks";
+
+import { useSyncExternalStore } from "../useSyncExternalStore";
+import { useRouter } from "./useRouter";
+
+import type { RouteContext } from "../types";
+
+export function useRouteNode(nodeName: string): RouteContext {
+  const router = useRouter();
+
+  const store = useMemo(
+    () => createRouteNodeSource(router, nodeName),
+    [router, nodeName],
+  );
+
+  const { route, previousRoute } = useSyncExternalStore(
+    store.subscribe,
+    store.getSnapshot,
+    store.getSnapshot,
+  );
+
+  const navigator = useMemo(() => getNavigator(router), [router]);
+
+  return useMemo(
+    (): RouteContext => ({ navigator, route, previousRoute }),
+    [navigator, route, previousRoute],
+  );
+}

package/src/hooks/useRouteUtils.tsx

@@ -0,0 +1,12 @@
+import { getPluginApi } from "@real-router/core/api";
+import { getRouteUtils } from "@real-router/route-utils";
+
+import { useRouter } from "./useRouter";
+
+import type { RouteUtils } from "@real-router/route-utils";
+
+export const useRouteUtils = (): RouteUtils => {
+  const router = useRouter();
+
+  return getRouteUtils(getPluginApi(router).getTree());
+};

package/src/hooks/useRouter.tsx

@@ -0,0 +1,15 @@
+import { useContext } from "preact/hooks";
+
+import { RouterContext } from "../context";
+
+import type { Router } from "@real-router/core";
+
+export const useRouter = (): Router => {
+  const router = useContext(RouterContext);
+
+  if (!router) {
+    throw new Error("useRouter must be used within a RouterProvider");
+  }
+
+  return router;
+};

package/src/hooks/useRouterError.tsx

@@ -0,0 +1,31 @@
+import { createErrorSource } from "@real-router/sources";
+import { useMemo } from "preact/hooks";
+
+import { useSyncExternalStore } from "../useSyncExternalStore";
+import { useRouter } from "./useRouter";
+
+import type { Router } from "@real-router/core";
+import type { RouterErrorSnapshot, RouterSource } from "@real-router/sources";
+
+const cache = new WeakMap<Router, RouterSource<RouterErrorSnapshot>>();
+
+export function useRouterError(): RouterErrorSnapshot {
+  const router = useRouter();
+
+  const store = useMemo(() => {
+    let source = cache.get(router);
+
+    if (!source) {
+      source = createErrorSource(router);
+      cache.set(router, source);
+    }
+
+    return source;
+  }, [router]);
+
+  return useSyncExternalStore(
+    store.subscribe,
+    store.getSnapshot,
+    store.getSnapshot,
+  );
+}

package/src/hooks/useRouterTransition.tsx

@@ -0,0 +1,19 @@
+import { createTransitionSource } from "@real-router/sources";
+import { useMemo } from "preact/hooks";
+
+import { useSyncExternalStore } from "../useSyncExternalStore";
+import { useRouter } from "./useRouter";
+
+import type { RouterTransitionSnapshot } from "@real-router/sources";
+
+export function useRouterTransition(): RouterTransitionSnapshot {
+  const router = useRouter();
+
+  const store = useMemo(() => createTransitionSource(router), [router]);
+
+  return useSyncExternalStore(
+    store.subscribe,
+    store.getSnapshot,
+    store.getSnapshot,
+  );
+}

package/src/hooks/useStableValue.tsx

@@ -0,0 +1,8 @@
+import { useMemo } from "preact/hooks";
+
+export function useStableValue<T>(value: T): T {
+  const serialized = JSON.stringify(value);
+
+  // eslint-disable-next-line @eslint-react/exhaustive-deps
+  return useMemo(() => value, [serialized]);
+}

package/src/index.ts

@@ -0,0 +1,39 @@
+// Components
+export { RouteView } from "./components/RouteView";
+
+export { Link } from "./components/Link";
+
+export { RouterErrorBoundary } from "./components/RouterErrorBoundary";
+
+// Hooks
+export { useRouter } from "./hooks/useRouter";
+
+export { useNavigator } from "./hooks/useNavigator";
+
+export { useRouteUtils } from "./hooks/useRouteUtils";
+
+export { useRoute } from "./hooks/useRoute";
+
+export { useRouteNode } from "./hooks/useRouteNode";
+
+export { useRouterTransition } from "./hooks/useRouterTransition";
+
+// Context
+export { RouterProvider } from "./RouterProvider";
+
+export { RouterContext, NavigatorContext, RouteContext } from "./context";
+
+// Types
+export type { LinkProps } from "./types";
+
+export type { RouterErrorBoundaryProps } from "./components/RouterErrorBoundary";
+
+export type {
+  RouteViewProps,
+  RouteViewMatchProps,
+  RouteViewNotFoundProps,
+} from "./components/RouteView";
+
+export type { Navigator } from "@real-router/core";
+
+export type { RouterTransitionSnapshot } from "@real-router/sources";

package/src/types.ts

@@ -0,0 +1,30 @@
+import type {
+  NavigationOptions,
+  Params,
+  Navigator,
+  State,
+} from "@real-router/core";
+import type { JSX } from "preact";
+
+export interface RouteState<P extends Params = Params> {
+  route: State<P> | undefined;
+  previousRoute?: State | undefined;
+}
+
+export type RouteContext = {
+  navigator: Navigator;
+} & RouteState;
+
+export interface LinkProps<P extends Params = Params> extends Omit<
+  JSX.HTMLAttributes<HTMLAnchorElement>,
+  "className"
+> {
+  routeName: string;
+  routeParams?: P;
+  routeOptions?: NavigationOptions;
+  className?: string;
+  activeClassName?: string;
+  activeStrict?: boolean;
+  ignoreQueryParams?: boolean;
+  target?: string;
+}

package/src/useSyncExternalStore.ts

@@ -0,0 +1,32 @@
+import { useEffect, useState } from "preact/hooks";
+
+/**
+ * Polyfill for React's useSyncExternalStore.
+ *
+ * Preact does not provide a native useSyncExternalStore.
+ * This implementation uses useState + useEffect to subscribe
+ * to external stores.
+ *
+ * Race condition handling: the value may change between
+ * `useState(getSnapshot)` (render) and `useEffect` (commit).
+ * We synchronize by calling `setValue(getSnapshot())` before
+ * subscribing in the effect.
+ */
+export function useSyncExternalStore<T>(
+  subscribe: (onStoreChange: () => void) => () => void,
+  getSnapshot: () => T,
+  _getServerSnapshot?: () => T,
+): T {
+  const [value, setValue] = useState(getSnapshot);
+
+  useEffect(() => {
+    // Synchronize before subscribing to handle race condition
+    setValue(getSnapshot());
+
+    return subscribe(() => {
+      setValue(getSnapshot());
+    });
+  }, [subscribe, getSnapshot]);
+
+  return value;
+}