@real-router/preact 0.0.1

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@real-router/preact",
+  "version": "0.0.1",
+  "type": "commonjs",
+  "description": "Preact integration for Real-Router",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.mjs",
+  "types": "./dist/esm/index.d.mts",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": {
+        "import": "./dist/esm/index.d.mts",
+        "require": "./dist/cjs/index.d.ts"
+      },
+      "import": "./dist/esm/index.mjs",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "homepage": "https://github.com/greydragon888/real-router",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/greydragon888/real-router.git"
+  },
+  "bugs": {
+    "url": "https://github.com/greydragon888/real-router/issues"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest",
+    "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": "publint",
+    "lint:types": "attw --pack ."
+  },
+  "keywords": [
+    "router",
+    "html5",
+    "history",
+    "tree",
+    "preact",
+    "hooks",
+    "components",
+    "functional",
+    "real-router"
+  ],
+  "author": {
+    "name": "Oleg Ivanov",
+    "email": "greydragon888@gmail.com",
+    "url": "https://github.com/greydragon888"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "dependencies": {
+    "@real-router/core": "workspace:^",
+    "@real-router/route-utils": "workspace:^",
+    "@real-router/sources": "workspace:^",
+    "dom-utils": "workspace:^"
+  },
+  "devDependencies": {
+    "@real-router/browser-plugin": "workspace:^",
+    "@testing-library/dom": "10.4.1",
+    "@testing-library/jest-dom": "6.9.1",
+    "@testing-library/preact": "3.2.4",
+    "@testing-library/user-event": "14.6.1",
+    "preact": "10.25.4"
+  },
+  "peerDependencies": {
+    "preact": ">=10.0.0"
+  }
+}

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/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/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 react-hooks/exhaustive-deps
+  return useMemo(() => value, [serialized]);
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+// Components
+export { RouteView } from "./components/RouteView";
+
+export { Link } from "./components/Link";
+
+// 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 {
+  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,33 @@
+import type {
+  NavigationOptions,
+  Params,
+  Navigator,
+  State,
+} from "@real-router/core";
+import type { JSX } from "preact";
+
+export interface RouteState<
+  P extends Params = Params,
+  MP extends Params = Params,
+> {
+  route: State<P, MP> | 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;
+}