@real-router/solid 0.0.1

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@real-router/solid",
+  "version": "0.0.1",
+  "type": "commonjs",
+  "description": "Solid.js integration for Real-Router",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.mjs",
+  "types": "./dist/cjs/index.d.ts",
+  "exports": {
+    ".": {
+      "development": "./src/index.tsx",
+      "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": "rimraf dist && tsc -p tsconfig.build.json && rollup -c rollup.config.mjs",
+    "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",
+    "solid",
+    "solid-js",
+    "signals",
+    "reactive",
+    "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": {
+    "@babel/core": "7.26.0",
+    "@babel/preset-typescript": "7.26.0",
+    "@real-router/browser-plugin": "workspace:^",
+    "@rollup/plugin-babel": "6.0.4",
+    "@rollup/plugin-node-resolve": "15.3.0",
+    "@solidjs/testing-library": "0.8.10",
+    "@testing-library/dom": "10.4.1",
+    "@testing-library/jest-dom": "6.9.1",
+    "@testing-library/user-event": "14.6.1",
+    "babel-preset-solid": "1.9.3",
+    "rimraf": "6.0.1",
+    "rollup": "4.27.4",
+    "rollup-plugin-dts": "6.1.1",
+    "solid-js": "1.9.5",
+    "vite-plugin-solid": "2.11.11",
+    "vitest": "4.1.0"
+  },
+  "peerDependencies": {
+    "solid-js": ">=1.7.0"
+  }
+}

package/src/RouterProvider.tsx

@@ -0,0 +1,60 @@
+import { getNavigator } from "@real-router/core";
+import { createRouteSource } from "@real-router/sources";
+import { createRouteAnnouncer } from "dom-utils";
+import { createSelector, onCleanup, onMount } from "solid-js";
+
+import { RouterContext, RouteContext } from "./context";
+import { createSignalFromSource } from "./createSignalFromSource";
+
+import type { Router } from "@real-router/core";
+import type { ParentProps, JSX } from "solid-js";
+
+export interface RouteProviderProps {
+  router: Router;
+  announceNavigation?: boolean;
+}
+
+function isRouteActive(
+  linkRouteName: string,
+  currentRouteName: string,
+): boolean {
+  return (
+    currentRouteName === linkRouteName ||
+    currentRouteName.startsWith(`${linkRouteName}.`)
+  );
+}
+
+export function RouterProvider(
+  props: ParentProps<RouteProviderProps>,
+): JSX.Element {
+  onMount(() => {
+    if (!props.announceNavigation) {
+      return;
+    }
+
+    const announcer = createRouteAnnouncer(props.router);
+
+    onCleanup(() => {
+      announcer.destroy();
+    });
+  });
+
+  const navigator = getNavigator(props.router);
+  const routeSource = createRouteSource(props.router);
+  const routeSignal = createSignalFromSource(routeSource);
+
+  const routeSelector = createSelector(
+    () => routeSignal().route?.name ?? "",
+    isRouteActive,
+  );
+
+  return (
+    <RouterContext.Provider
+      value={{ router: props.router, navigator, routeSelector }}
+    >
+      <RouteContext.Provider value={routeSignal}>
+        {props.children}
+      </RouteContext.Provider>
+    </RouterContext.Provider>
+  );
+}

package/src/components/Link.tsx

@@ -0,0 +1,91 @@
+import { createActiveRouteSource } from "@real-router/sources";
+import { shouldNavigate, buildHref, buildActiveClassName } from "dom-utils";
+import { createMemo, mergeProps, splitProps, useContext } from "solid-js";
+
+import { EMPTY_PARAMS, EMPTY_OPTIONS } from "../constants";
+import { RouterContext } from "../context";
+import { createSignalFromSource } from "../createSignalFromSource";
+import { useRouter } from "../hooks/useRouter";
+
+import type { LinkProps } from "../types";
+import type { Params } from "@real-router/core";
+import type { JSX } from "solid-js";
+
+export function Link<P extends Params = Params>(
+  props: Readonly<LinkProps<P>>,
+): JSX.Element {
+  const merged = mergeProps(
+    {
+      routeParams: EMPTY_PARAMS as P,
+      routeOptions: EMPTY_OPTIONS,
+      activeClassName: "active",
+      activeStrict: false,
+      ignoreQueryParams: true,
+    },
+    props,
+  );
+
+  const [local, rest] = splitProps(merged, [
+    "routeName",
+    "routeParams",
+    "routeOptions",
+    "activeClassName",
+    "activeStrict",
+    "ignoreQueryParams",
+    "onClick",
+    "target",
+    "class",
+    "children",
+  ]);
+
+  const router = useRouter();
+  const ctx = useContext(RouterContext);
+
+  const useFastPath =
+    ctx?.routeSelector &&
+    !local.activeStrict &&
+    local.ignoreQueryParams &&
+    local.routeParams === EMPTY_PARAMS;
+
+  const isActive = useFastPath
+    ? () => ctx.routeSelector(local.routeName)
+    : createSignalFromSource(
+        createActiveRouteSource(router, local.routeName, local.routeParams, {
+          strict: local.activeStrict,
+          ignoreQueryParams: local.ignoreQueryParams,
+        }),
+      );
+
+  const href = createMemo(() =>
+    buildHref(router, local.routeName, local.routeParams),
+  );
+
+  const handleClick = (evt: MouseEvent) => {
+    if (local.onClick) {
+      local.onClick(evt);
+
+      if (evt.defaultPrevented) {
+        return;
+      }
+    }
+
+    if (!shouldNavigate(evt) || local.target === "_blank") {
+      return;
+    }
+
+    evt.preventDefault();
+    router
+      .navigate(local.routeName, local.routeParams, local.routeOptions)
+      .catch(() => {});
+  };
+
+  const finalClassName = createMemo(() =>
+    buildActiveClassName(isActive(), local.activeClassName, local.class),
+  );
+
+  return (
+    <a {...rest} href={href()} class={finalClassName()} onClick={handleClick}>
+      {local.children}
+    </a>
+  );
+}

package/src/components/RouteView/RouteView.tsx

@@ -0,0 +1,53 @@
+import { children as resolveChildren } from "solid-js";
+
+import { Match, NotFound } from "./components";
+import { buildRenderList, collectElements } from "./helpers";
+import { useRouteNode } from "../../hooks/useRouteNode";
+
+import type { RouteViewMarker } from "./components";
+import type { RouteViewProps } from "./types";
+import type { JSX } from "solid-js";
+
+function RouteViewRoot(props: Readonly<RouteViewProps>): JSX.Element {
+  const routeState = useRouteNode(props.nodeName);
+
+  const resolved = resolveChildren(() => props.children);
+
+  return (
+    <>
+      {(() => {
+        const state = routeState();
+
+        if (!state.route) {
+          return null;
+        }
+
+        const elements: RouteViewMarker[] = [];
+
+        collectElements(resolved(), elements);
+
+        const { rendered } = buildRenderList(
+          elements,
+          state.route.name,
+          props.nodeName,
+        );
+
+        if (rendered.length > 0) {
+          return rendered;
+        }
+
+        return null;
+      })()}
+    </>
+  ) as unknown as JSX.Element;
+}
+
+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,50 @@
+import type { MatchProps, NotFoundProps } from "./types";
+import type { JSX } from "solid-js";
+
+export const MATCH_MARKER = Symbol.for("RouteView.Match");
+
+export const NOT_FOUND_MARKER = Symbol.for("RouteView.NotFound");
+
+export interface MatchMarker {
+  $$type: typeof MATCH_MARKER;
+  segment: string;
+  exact: boolean;
+  fallback?: JSX.Element;
+  children: JSX.Element;
+}
+
+export interface NotFoundMarker {
+  $$type: typeof NOT_FOUND_MARKER;
+  children: JSX.Element;
+}
+
+export type RouteViewMarker = MatchMarker | NotFoundMarker;
+
+export function Match(props: MatchProps): JSX.Element {
+  const result = {
+    $$type: MATCH_MARKER,
+    segment: props.segment,
+    exact: props.exact ?? false,
+    fallback: props.fallback,
+    get children(): JSX.Element {
+      return props.children;
+    },
+  } as MatchMarker;
+
+  return result as unknown as JSX.Element;
+}
+
+Match.displayName = "RouteView.Match";
+
+export function NotFound(props: NotFoundProps): JSX.Element {
+  const result = {
+    $$type: NOT_FOUND_MARKER,
+    get children(): JSX.Element {
+      return props.children;
+    },
+  } as NotFoundMarker;
+
+  return result as unknown as JSX.Element;
+}
+
+NotFound.displayName = "RouteView.NotFound";

package/src/components/RouteView/helpers.tsx

@@ -0,0 +1,108 @@
+import { UNKNOWN_ROUTE } from "@real-router/core";
+import { startsWithSegment } from "@real-router/route-utils";
+import { Suspense } from "solid-js";
+
+import { MATCH_MARKER, NOT_FOUND_MARKER } from "./components";
+
+import type {
+  MatchMarker,
+  NotFoundMarker,
+  RouteViewMarker,
+} from "./components";
+import type { JSX } from "solid-js";
+
+function isSegmentMatch(
+  routeName: string,
+  fullSegmentName: string,
+  exact: boolean,
+): boolean {
+  if (exact) {
+    return routeName === fullSegmentName;
+  }
+
+  return startsWithSegment(routeName, fullSegmentName);
+}
+
+function isMatchMarker(value: unknown): value is MatchMarker {
+  return (
+    value != null &&
+    typeof value === "object" &&
+    "$$type" in value &&
+    value.$$type === MATCH_MARKER
+  );
+}
+
+function isNotFoundMarker(value: unknown): value is NotFoundMarker {
+  return (
+    value != null &&
+    typeof value === "object" &&
+    "$$type" in value &&
+    value.$$type === NOT_FOUND_MARKER
+  );
+}
+
+export function collectElements(
+  children: unknown,
+  result: RouteViewMarker[],
+): void {
+  if (children == null) {
+    return;
+  }
+
+  if (Array.isArray(children)) {
+    for (const child of children) {
+      collectElements(child, result);
+    }
+
+    return;
+  }
+
+  if (isMatchMarker(children) || isNotFoundMarker(children)) {
+    result.push(children);
+  }
+}
+
+export function buildRenderList(
+  elements: RouteViewMarker[],
+  routeName: string,
+  nodeName: string,
+): { rendered: JSX.Element[]; activeMatchFound: boolean } {
+  let notFoundChildren: JSX.Element | null = null;
+  let activeMatchFound = false;
+  const rendered: JSX.Element[] = [];
+
+  for (const child of elements) {
+    if (isNotFoundMarker(child)) {
+      notFoundChildren = child.children;
+      continue;
+    }
+
+    const { segment, exact, fallback } = child;
+    const fullSegmentName = nodeName ? `${nodeName}.${segment}` : segment;
+    const isActive =
+      !activeMatchFound && isSegmentMatch(routeName, fullSegmentName, exact);
+
+    if (isActive) {
+      activeMatchFound = true;
+      const matchContent = child.children;
+      const content =
+        fallback === undefined ? (
+          matchContent
+        ) : (
+          <Suspense fallback={fallback}>{matchContent}</Suspense>
+        );
+
+      rendered.push(content);
+    }
+  }
+
+  if (
+    !activeMatchFound &&
+    routeName === UNKNOWN_ROUTE &&
+    notFoundChildren !== null
+  ) {
+    rendered.push(notFoundChildren);
+  }
+
+  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 { JSX } from "solid-js";
+
+export interface RouteViewProps {
+  readonly nodeName: string;
+  readonly children: JSX.Element;
+}
+
+export interface MatchProps {
+  readonly segment: string;
+  readonly exact?: boolean;
+  readonly fallback?: JSX.Element;
+  readonly children: JSX.Element;
+}
+
+export interface NotFoundProps {
+  readonly children: JSX.Element;
+}

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,15 @@
+import { createContext } from "solid-js";
+
+import type { RouteState } from "./types";
+import type { Router, Navigator } from "@real-router/core";
+import type { Accessor } from "solid-js";
+
+export interface RouterContextValue {
+  router: Router;
+  navigator: Navigator;
+  routeSelector: (routeName: string) => boolean;
+}
+
+export const RouterContext = createContext<RouterContextValue | null>(null);
+
+export const RouteContext = createContext<Accessor<RouteState> | null>(null);

package/src/createSignalFromSource.ts

@@ -0,0 +1,20 @@
+import { createSignal, onCleanup } from "solid-js";
+
+import type { RouterSource } from "@real-router/sources";
+import type { Accessor } from "solid-js";
+
+export function createSignalFromSource<T>(
+  source: RouterSource<T>,
+): Accessor<T> {
+  const [value, setValue] = createSignal<T>(source.getSnapshot());
+
+  const unsubscribe = source.subscribe(() => {
+    setValue(() => source.getSnapshot());
+  });
+
+  onCleanup(() => {
+    unsubscribe();
+  });
+
+  return value;
+}

package/src/createStoreFromSource.ts

@@ -0,0 +1,20 @@
+import { onCleanup } from "solid-js";
+import { createStore, reconcile } from "solid-js/store";
+
+import type { RouterSource } from "@real-router/sources";
+
+export function createStoreFromSource<T extends object>(
+  source: RouterSource<T>,
+): T {
+  const [state, setState] = createStore<T>(
+    structuredClone(source.getSnapshot()),
+  );
+
+  const unsubscribe = source.subscribe(() => {
+    setState(reconcile(source.getSnapshot()));
+  });
+
+  onCleanup(unsubscribe);
+
+  return state;
+}

package/src/directives/link.tsx

@@ -0,0 +1,79 @@
+import { createActiveRouteSource } from "@real-router/sources";
+import { shouldNavigate, applyLinkA11y } from "dom-utils";
+import { createEffect, onCleanup } from "solid-js";
+
+import { EMPTY_PARAMS, EMPTY_OPTIONS } from "../constants";
+import { createSignalFromSource } from "../createSignalFromSource";
+import { useRouter } from "../hooks/useRouter";
+
+import type { Params } from "@real-router/core";
+
+export interface LinkDirectiveOptions<P extends Params = Params> {
+  routeName: string;
+  routeParams?: P;
+  routeOptions?: Record<string, unknown>;
+  activeClassName?: string;
+  activeStrict?: boolean;
+  ignoreQueryParams?: boolean;
+}
+
+export function link<P extends Params = Params>(
+  element: HTMLElement,
+  accessor: () => LinkDirectiveOptions<P>,
+): void {
+  const router = useRouter();
+  const options = accessor();
+
+  // Set href on <a> elements
+  if (element instanceof HTMLAnchorElement) {
+    element.href = router.buildPath(
+      options.routeName,
+      options.routeParams ?? (EMPTY_PARAMS as P),
+    );
+  }
+
+  applyLinkA11y(element);
+
+  // Active class tracking (reactive)
+  if (options.activeClassName) {
+    const activeClassName = options.activeClassName;
+    const activeSource = createActiveRouteSource(
+      router,
+      options.routeName,
+      options.routeParams ?? (EMPTY_PARAMS as P),
+      {
+        strict: options.activeStrict ?? false,
+        ignoreQueryParams: options.ignoreQueryParams ?? true,
+      },
+    );
+    const isActive = createSignalFromSource(activeSource);
+
+    createEffect(() => {
+      element.classList.toggle(activeClassName, isActive());
+    });
+  }
+
+  // Click handler
+  function handleClick(evt: MouseEvent) {
+    if (!shouldNavigate(evt)) {
+      return;
+    }
+    if (element instanceof HTMLAnchorElement) {
+      evt.preventDefault();
+    }
+
+    router
+      .navigate(
+        options.routeName,
+        options.routeParams ?? (EMPTY_PARAMS as P),
+        options.routeOptions ?? EMPTY_OPTIONS,
+      )
+      .catch(() => {});
+  }
+
+  element.addEventListener("click", handleClick);
+
+  onCleanup(() => {
+    element.removeEventListener("click", handleClick);
+  });
+}

package/src/directives.d.ts

@@ -0,0 +1,10 @@
+import type { LinkDirectiveOptions } from "./directives/link";
+
+declare module "solid-js" {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface Directives {
+      link: LinkDirectiveOptions | undefined;
+    }
+  }
+}

package/src/hooks/useNavigator.tsx

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

package/src/hooks/useRoute.tsx

@@ -0,0 +1,16 @@
+import { useContext } from "solid-js";
+
+import { RouteContext } from "../context";
+
+import type { RouteState } from "../types";
+import type { Accessor } from "solid-js";
+
+export const useRoute = (): Accessor<RouteState> => {
+  const routeSignal = useContext(RouteContext);
+
+  if (!routeSignal) {
+    throw new Error("useRoute must be used within a RouterProvider");
+  }
+
+  return routeSignal;
+};

package/src/hooks/useRouteNode.tsx

@@ -0,0 +1,14 @@
+import { createRouteNodeSource } from "@real-router/sources";
+
+import { createSignalFromSource } from "../createSignalFromSource";
+import { useRouter } from "./useRouter";
+
+import type { RouteState } from "../types";
+import type { Accessor } from "solid-js";
+
+export function useRouteNode(nodeName: string): Accessor<RouteState> {
+  const router = useRouter();
+  const store = createRouteNodeSource(router, nodeName);
+
+  return createSignalFromSource(store);
+}