@tschk/moonshine-tanstack 0.3.4

package/README.md

@@ -0,0 +1,73 @@
+# `@tschk/moonshine-tanstack`
+
+The **runtime** client API of TanStack Router / TanStack Start reimplemented on
+moonshine. It imports no TanStack code and lists none as a dependency:
+`Link`, `useNavigate`, `useRouterState` and friends are ordinary React
+components written against `@tschk/moonshine/router`.
+
+```ts
+// bundler alias
+"@tanstack/react-router" -> "@tschk/moonshine-tanstack";
+```
+
+```tsx
+import {
+  Link,
+  Outlet,
+  useNavigate,
+  useSearch,
+} from "@tschk/moonshine-tanstack";
+import { json, createServerRoute } from "@tschk/moonshine-tanstack/server";
+```
+
+| Subpath        | Contents                                        |
+| -------------- | ----------------------------------------------- |
+| `.`            | client API (components + hooks + search codecs) |
+| `./link`       | `Link`, `Navigate`                              |
+| `./navigation` | `useNavigate`, `useRouter`, `useRouterState`, … |
+| `./outlet`     | `Outlet`, `OutletProvider`                      |
+| `./server`     | `json`, `createServerRoute`, moonshine server   |
+| `./client`     | moonshine signals + resources                   |
+
+## Supported
+
+- `Link` — `to` with `$param` and `$` splat interpolation, `params`, `search`
+  (record or updater), `hash`, `replace`, `resetScroll`, `preload`
+  (`"intent"` hover / `"viewport"` / `"render"`), `disabled`,
+  `activeProps`/`inactiveProps`, `className` and `children` render callbacks,
+  `data-status="active"` and `aria-current`. Navigation runs inside
+  `startTransition`.
+- `Navigate` — declarative redirect on mount.
+- `Outlet` / `OutletProvider`.
+- `useNavigate`, `useRouter`, `useRouterState` (with `select`), `useLocation`,
+  `useParams`, `useSearch` (with `select`), `useCanGoBack`.
+- `redirect`, `notFound`, `isRedirect`, `isNotFound` — same "return an error you
+  throw" contract as TanStack.
+- Search codecs: `parseSearch` / `stringifySearch` with TanStack's JSON value
+  encoding, plus `buildHref` and `interpolatePath`.
+
+## Not supported
+
+These require the TanStack Vite plugin, the generated route tree, or TanStack's
+own loader/RPC runtime, and are **not** provided:
+
+- **Route definition and typing**: `createFileRoute`, `createRootRoute`,
+  `createRoute`, `createRouter`, `RouterProvider`, `routeTree.gen.ts`, and the
+  whole type-level route registry. Every `to`, `from` and `params` here is a
+  plain string/record with no route-tree inference — `from` is accepted and
+  ignored, `strict` has no effect.
+- **Data loading**: `loader`, `useLoaderData`, `useLoaderDeps`, `beforeLoad`,
+  `validateSearch`, `router.invalidate()` (a no-op here), `useMatch`,
+  `useMatches`, `useMatchRoute`, `Await`, `defer`, pending/error components.
+- **Server functions**: `createServerFn`, `createMiddleware`,
+  `createStartHandler` — these depend on the build plugin's client/server
+  splitting. Use `createServerRoute` on a moonshine route instead.
+- **Transitions/blocking**: `useBlocker`, `Block`, `isTransitioning`
+  (always `false`), `useRouterState().status` (always `"idle"`),
+  `matches` (always empty).
+- **History state**: `location.state` is always `{}`; there is no
+  `useHistoryState`.
+- `useSearch` reads `window.location.search`; on the server it is empty because
+  moonshine's router signal carries the pathname only.
+
+See [Moonshine README](../../README.md).

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@tschk/moonshine-tanstack",
+  "version": "0.3.4",
+  "description": "TanStack Router / Start client API reimplemented on moonshine — drop @tanstack/react-router, keep the imports",
+  "license": "ISC",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./client": "./src/client.ts",
+    "./server": "./src/server.ts",
+    "./navigation": "./src/navigation.ts",
+    "./link": "./src/link.ts",
+    "./outlet": "./src/outlet.ts",
+    "./aliases": "./src/aliases.ts"
+  },
+  "dependencies": {
+    "@tschk/moonshine": "^0.3.4",
+    "@tschk/moonshine-router": "^0.3.4"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "moonshine",
+    "tanstack",
+    "router",
+    "adapter"
+  ],
+  "scripts": {
+    "format": "bunx prettier --check .",
+    "lint": "bunx oxlint .",
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test"
+  }
+}

package/src/aliases.ts

@@ -0,0 +1,53 @@
+/**
+ * Drop-in mapping from the TanStack Router specifiers onto this package.
+ *
+ * ```ts
+ * import { moonshineTanstackPlugin } from "@tschk/moonshine-tanstack/aliases";
+ * await Bun.build({ entrypoints: ["./app.tsx"], plugins: [moonshineTanstackPlugin()] });
+ * ```
+ */
+import { join } from "node:path";
+import type { BunPlugin } from "bun";
+
+/** Bare specifier each replaced package is served by. */
+export const tanstackAliases: Readonly<Record<string, string>> = {
+  "@tanstack/react-router": "@tschk/moonshine-tanstack",
+  "@tanstack/router-core": "@tschk/moonshine-tanstack",
+};
+
+/** File in this package backing each alias, relative to `src/`. */
+const files: Readonly<Record<string, string>> = {
+  "@tanstack/react-router": "index.ts",
+  "@tanstack/router-core": "index.ts",
+};
+
+/**
+ * `compilerOptions.paths` block for an app's tsconfig, so the type checker
+ * follows the same mapping the bundler applies.
+ */
+export function tsconfigPaths(): Record<string, string[]> {
+  return Object.fromEntries(
+    Object.entries(tanstackAliases).map(([from, to]) => [from, [to]]),
+  );
+}
+
+/** Absolute path this package serves `specifier` from, if it is aliased. */
+export function resolveAlias(specifier: string): string | undefined {
+  const file = files[specifier];
+  return file === undefined ? undefined : join(import.meta.dir, file);
+}
+
+const filter = /^@tanstack\/(react-router|router-core)$/;
+
+/** Bun bundler/runtime plugin rewriting TanStack imports to this package. */
+export function moonshineTanstackPlugin(): BunPlugin {
+  return {
+    name: "moonshine-tanstack-aliases",
+    setup(build) {
+      build.onResolve({ filter }, (args) => {
+        const path = resolveAlias(args.path);
+        return path === undefined ? undefined : { path };
+      });
+    },
+  };
+}

package/src/client.ts

@@ -0,0 +1,12 @@
+"use client";
+
+/**
+ * Moonshine signal + resource surface for TanStack Start apps.
+ */
+export * from "@tschk/moonshine/host-react";
+
+export {
+  createIslandSignal,
+  createResource,
+  useResource,
+} from "@tschk/moonshine/host-react";

package/src/index.ts

@@ -0,0 +1,41 @@
+"use client";
+
+/**
+ * @tschk/moonshine-tanstack
+ *
+ * The TanStack Router / Start client API reimplemented on moonshine's router.
+ * Alias `@tanstack/react-router` to this package to drop the dependency.
+ *
+ * Route-tree generation (`createFileRoute`, `routeTree.gen.ts`) is not provided
+ * — it requires the TanStack Vite plugin. See the README.
+ */
+export { Link, Navigate } from "./link";
+export type { LinkProps, LinkRenderState, NavigateProps } from "./link";
+
+export {
+  NotFound,
+  Redirect,
+  isNotFound,
+  isRedirect,
+  notFound,
+  redirect,
+  useCanGoBack,
+  useLocation,
+  useNavigate,
+  useParams,
+  useRouter,
+  useRouterState,
+  useSearch,
+} from "./navigation";
+export type { NavigateFn, RouterInstance, RouterState } from "./navigation";
+
+export { Outlet, OutletProvider } from "./outlet";
+export type { OutletProviderProps } from "./outlet";
+
+export {
+  buildHref,
+  interpolatePath,
+  parseSearch,
+  stringifySearch,
+} from "./location";
+export type { ParsedLocation, SearchRecord, ToOptions } from "./location";

package/src/link.ts

@@ -0,0 +1,184 @@
+"use client";
+
+/**
+ * TanStack Router's `<Link>` on the moonshine router.
+ *
+ * ```tsx
+ * import { Link } from "@tschk/moonshine-tanstack";
+ * ```
+ */
+import {
+  createElement,
+  useCallback,
+  useEffect,
+  useRef,
+  useTransition,
+  type AnchorHTMLAttributes,
+  type MouseEvent,
+  type ReactNode,
+} from "react";
+import { navigate } from "@tschk/moonshine/router";
+import { buildHref, type ToOptions } from "./location";
+import { useParsedLocation } from "./location";
+
+export type LinkRenderState = { isActive: boolean; isTransitioning: boolean };
+
+export type LinkProps = Omit<
+  AnchorHTMLAttributes<HTMLAnchorElement>,
+  "href" | "className" | "style" | "children"
+> &
+  ToOptions & {
+    activeOptions?: { exact?: boolean; includeHash?: boolean };
+    /** `"intent"` warms the URL on hover, `"viewport"` when it scrolls in. */
+    preload?: false | "intent" | "viewport" | "render";
+    disabled?: boolean;
+    activeProps?: Record<string, unknown>;
+    inactiveProps?: Record<string, unknown>;
+    className?: string | ((state: LinkRenderState) => string | undefined);
+    style?: Record<string, unknown>;
+    children?: ReactNode | ((state: LinkRenderState) => ReactNode);
+  };
+
+function isExternal(href: string, target?: string): boolean {
+  if (target && target !== "_self") return true;
+  return (
+    /^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(href) ||
+    href.startsWith("//") ||
+    href.startsWith("#")
+  );
+}
+
+const preloaded = new Set<string>();
+
+function preloadOnce(url: string): void {
+  if (preloaded.has(url) || typeof document === "undefined") return;
+  preloaded.add(url);
+  const tag = document.createElement("link");
+  tag.rel = "prefetch";
+  tag.href = url;
+  document.head.append(tag);
+}
+
+function pathnameOf(href: string): string {
+  const cut = href.search(/[?#]/);
+  return cut === -1 ? href : href.slice(0, cut);
+}
+
+export function Link({
+  to,
+  from: _from,
+  params,
+  search,
+  hash,
+  replace,
+  resetScroll,
+  activeOptions,
+  preload = "intent",
+  disabled,
+  activeProps,
+  inactiveProps,
+  className,
+  style,
+  children,
+  onClick,
+  onMouseEnter,
+  ...rest
+}: LinkProps): ReactNode {
+  const location = useParsedLocation();
+  const href = buildHref({ to, params, search, hash }, location.search);
+  const external = isExternal(href, rest.target);
+  const ref = useRef<HTMLAnchorElement>(null);
+  // Navigation runs in a transition so a slow subtree cannot block the click.
+  const [, startTransition] = useTransition();
+  const inert = external || disabled === true || preload === false;
+
+  const warm = useCallback(() => {
+    if (!inert) preloadOnce(href);
+  }, [inert, href]);
+
+  useEffect(() => {
+    if (inert) return;
+    if (preload === "render") {
+      warm();
+      return;
+    }
+    const node = ref.current;
+    if (
+      !node ||
+      preload !== "viewport" ||
+      typeof IntersectionObserver === "undefined"
+    ) {
+      return;
+    }
+    const observer = new IntersectionObserver((entries) => {
+      for (const entry of entries) {
+        if (entry.isIntersecting) {
+          warm();
+          observer.disconnect();
+        }
+      }
+    });
+    observer.observe(node);
+    return () => observer.disconnect();
+  }, [warm, preload, inert]);
+
+  const target = pathnameOf(href);
+  const isActive = activeOptions?.exact
+    ? location.pathname === target
+    : location.pathname === target ||
+      location.pathname.startsWith(
+        target.endsWith("/") ? target : `${target}/`,
+      );
+  const state: LinkRenderState = { isActive, isTransitioning: false };
+
+  return createElement(
+    "a",
+    {
+      ...rest,
+      ...(isActive ? activeProps : inactiveProps),
+      ref,
+      href,
+      style,
+      className: typeof className === "function" ? className(state) : className,
+      "data-status": isActive ? "active" : undefined,
+      "aria-current": isActive ? "page" : undefined,
+      onMouseEnter: (event: MouseEvent<HTMLAnchorElement>) => {
+        onMouseEnter?.(event);
+        if (preload === "intent") warm();
+      },
+      onClick: (event: MouseEvent<HTMLAnchorElement>) => {
+        onClick?.(event);
+        if (
+          event.defaultPrevented ||
+          event.button !== 0 ||
+          event.metaKey ||
+          event.altKey ||
+          event.ctrlKey ||
+          event.shiftKey ||
+          external ||
+          disabled === true
+        ) {
+          return;
+        }
+        event.preventDefault();
+        startTransition(() => {
+          navigate(href, { replace });
+          if (resetScroll !== false) globalThis.scrollTo?.(0, 0);
+        });
+      },
+    },
+    typeof children === "function" ? children(state) : children,
+  );
+}
+
+export type NavigateProps = ToOptions;
+
+/** Redirects on mount. */
+export function Navigate(props: NavigateProps): null {
+  const location = useParsedLocation();
+  const href = buildHref(props, location.search);
+  useEffect(() => {
+    navigate(href, { replace: props.replace });
+  }, [href, props.replace]);
+  return null;
+}

package/src/location.ts

@@ -0,0 +1,117 @@
+"use client";
+
+/**
+ * TanStack Router's location shape, derived from the moonshine router signal.
+ *
+ * Moonshine's signal carries the pathname only, so `search` and `hash` are read
+ * back from `window.location` on each render.
+ */
+import { useMemo, useReducer } from "react";
+import { useLocation as useMoonshineLocation } from "@tschk/moonshine/router";
+
+export type SearchRecord = Record<string, unknown>;
+
+export type ParsedLocation = {
+  href: string;
+  pathname: string;
+  search: SearchRecord;
+  searchStr: string;
+  hash: string;
+  state: Record<string, unknown>;
+};
+
+export type ToOptions = {
+  to?: string;
+  from?: string;
+  params?: Record<string, string>;
+  search?: SearchRecord | ((current: SearchRecord) => SearchRecord);
+  hash?: string;
+  replace?: boolean;
+  resetScroll?: boolean;
+};
+
+/** `parseSearch` — TanStack decodes JSON values inside query params. */
+export function parseSearch(searchStr: string): SearchRecord {
+  const out: SearchRecord = {};
+  for (const [key, value] of new URLSearchParams(searchStr)) {
+    try {
+      out[key] = JSON.parse(value) as unknown;
+    } catch {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+/** `stringifySearch` — the inverse of {@link parseSearch}. */
+export function stringifySearch(search: SearchRecord): string {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(search)) {
+    if (value === undefined) continue;
+    params.set(key, typeof value === "string" ? value : JSON.stringify(value));
+  }
+  const query = params.toString();
+  return query ? `?${query}` : "";
+}
+
+/** Fills `$param` / `$` placeholders in a `to` template. */
+export function interpolatePath(
+  to: string,
+  params: Record<string, string> = {},
+): string {
+  return to
+    .split("/")
+    .map((segment) => {
+      if (segment === "$") return params["*"] ?? params._splat ?? "";
+      if (segment.startsWith("$")) return params[segment.slice(1)] ?? segment;
+      return segment;
+    })
+    .join("/");
+}
+
+/** Builds the final URL string for a `ToOptions` navigation descriptor. */
+export function buildHref(
+  options: ToOptions,
+  currentSearch: SearchRecord = {},
+): string {
+  const pathname = interpolatePath(options.to ?? "", options.params);
+  const search =
+    typeof options.search === "function"
+      ? options.search(currentSearch)
+      : (options.search ?? {});
+  const hash = options.hash
+    ? options.hash.startsWith("#")
+      ? options.hash
+      : `#${options.hash}`
+    : "";
+  return `${pathname}${stringifySearch(search)}${hash}`;
+}
+
+function browserPart(part: "search" | "hash"): string {
+  if (typeof window === "undefined") return "";
+  return window.location[part];
+}
+
+/** Forces a re-render; used after navigations that only change the query. */
+export function useRerender(): () => void {
+  const [, bump] = useReducer((n: number) => n + 1, 0);
+  return bump;
+}
+
+export function useParsedLocation(): ParsedLocation {
+  const pathname = useMoonshineLocation();
+  const searchStr = browserPart("search");
+  const hash = browserPart("hash");
+  return useMemo(
+    () => ({
+      href: `${pathname}${searchStr}${hash}`,
+      pathname,
+      search: parseSearch(searchStr),
+      searchStr,
+      hash,
+      // History state is not tracked by the moonshine router.
+      state: {},
+    }),
+    [pathname, searchStr, hash],
+  );
+}

package/src/navigation.ts

@@ -0,0 +1,166 @@
+"use client";
+
+/**
+ * TanStack Router hooks implemented on the moonshine router.
+ *
+ * ```ts
+ * import { useNavigate, useRouterState } from "@tschk/moonshine-tanstack";
+ * ```
+ */
+import { useCallback, useMemo } from "react";
+import {
+  navigate,
+  useParams as useMoonshineParams,
+} from "@tschk/moonshine/router";
+import {
+  buildHref,
+  useParsedLocation,
+  useRerender,
+  type ParsedLocation,
+  type SearchRecord,
+  type ToOptions,
+} from "./location";
+
+export type NavigateFn = (options: ToOptions) => void;
+
+export type RouterInstance = {
+  navigate: NavigateFn;
+  buildLocation: (options: ToOptions) => { href: string };
+  history: {
+    back(): void;
+    forward(): void;
+    go(delta: number): void;
+  };
+  invalidate(): void;
+  state: { location: ParsedLocation };
+};
+
+export function useNavigate(): NavigateFn {
+  const location = useParsedLocation();
+  const rerender = useRerender();
+  return useCallback(
+    (options: ToOptions) => {
+      const href = buildHref(
+        { ...options, to: options.to ?? location.pathname },
+        location.search,
+      );
+      navigate(href, { replace: options.replace });
+      if (options.resetScroll !== false) globalThis.scrollTo?.(0, 0);
+      // A query-only navigation leaves the pathname signal unchanged.
+      rerender();
+    },
+    [location.pathname, location.search, rerender],
+  );
+}
+
+export function useRouter(): RouterInstance {
+  const location = useParsedLocation();
+  const go = useNavigate();
+  return useMemo(
+    () => ({
+      navigate: go,
+      buildLocation: (options: ToOptions) => ({
+        href: buildHref(options, location.search),
+      }),
+      history: {
+        back: () => globalThis.history?.back(),
+        forward: () => globalThis.history?.forward(),
+        go: (delta: number) => globalThis.history?.go(delta),
+      },
+      // Moonshine re-renders from its signal graph; there is nothing to
+      // invalidate.
+      invalidate: () => {},
+      state: { location },
+    }),
+    [go, location],
+  );
+}
+
+export type RouterState = {
+  location: ParsedLocation;
+  status: "idle";
+  isLoading: false;
+  isTransitioning: false;
+  matches: never[];
+};
+
+export function useRouterState<T = RouterState>(options?: {
+  select?: (state: RouterState) => T;
+}): T {
+  const location = useParsedLocation();
+  const state = useMemo<RouterState>(
+    () => ({
+      location,
+      status: "idle",
+      isLoading: false,
+      isTransitioning: false,
+      matches: [],
+    }),
+    [location],
+  );
+  return (options?.select ? options.select(state) : state) as T;
+}
+
+export function useLocation(): ParsedLocation {
+  return useParsedLocation();
+}
+
+export function useParams<
+  T extends Record<string, string> = Record<string, string>,
+>(_options?: { from?: string; strict?: boolean }): T {
+  return useMoonshineParams() as T;
+}
+
+export function useSearch<T extends SearchRecord = SearchRecord>(_options?: {
+  from?: string;
+  strict?: boolean;
+  select?: (search: SearchRecord) => T;
+}): T {
+  const { search } = useParsedLocation();
+  return (_options?.select ? _options.select(search) : search) as T;
+}
+
+export function useCanGoBack(): boolean {
+  return (globalThis.history?.length ?? 0) > 1;
+}
+
+/** Thrown to unwind rendering, matching TanStack's control-flow contract. */
+export class Redirect extends Error {
+  constructor(readonly options: ToOptions & { statusCode?: number }) {
+    super(`redirect: ${options.to ?? ""}`);
+    this.name = "Redirect";
+  }
+}
+
+export class NotFound extends Error {
+  constructor(readonly data?: unknown) {
+    super("not found");
+    this.name = "NotFound";
+  }
+}
+
+/** Returns the error (TanStack's contract is `throw redirect({ to })`). */
+export function redirect(
+  options: ToOptions & { statusCode?: number; throw?: boolean },
+): Redirect {
+  const error = new Redirect(options);
+  if (options.throw === true) throw error;
+  return error;
+}
+
+export function notFound(options?: {
+  data?: unknown;
+  throw?: boolean;
+}): NotFound {
+  const error = new NotFound(options?.data);
+  if (options?.throw === true) throw error;
+  return error;
+}
+
+export function isRedirect(value: unknown): value is Redirect {
+  return value instanceof Redirect;
+}
+
+export function isNotFound(value: unknown): value is NotFound {
+  return value instanceof NotFound;
+}

package/src/outlet.ts

@@ -0,0 +1,33 @@
+"use client";
+
+/**
+ * `<Outlet>` for TanStack-style nested layouts.
+ *
+ * Moonshine matches a flat route table, so the child element is supplied
+ * explicitly by the layout rather than derived from a generated route tree.
+ */
+import {
+  createContext,
+  createElement,
+  useContext,
+  type ReactNode,
+} from "react";
+
+const OutletContext = createContext<ReactNode>(null);
+
+export type OutletProviderProps = {
+  /** The child route element rendered where `<Outlet />` appears. */
+  value: ReactNode;
+  children?: ReactNode;
+};
+
+export function OutletProvider({
+  value,
+  children,
+}: OutletProviderProps): ReactNode {
+  return createElement(OutletContext.Provider, { value }, children);
+}
+
+export function Outlet(): ReactNode {
+  return useContext(OutletContext);
+}

package/src/server.ts

@@ -0,0 +1,47 @@
+/**
+ * Server surface for TanStack Start apps on moonshine: response helpers plus
+ * moonshine's request handling.
+ *
+ * `createServerFn` is deliberately absent — see the README.
+ */
+export {
+  createMoonshineServer,
+  definePage,
+  handleMoonshineRequest,
+  resolvePage,
+  toMoonshineRequest,
+} from "@tschk/moonshine/server";
+export type {
+  MoonshinePageModule,
+  MoonshineRequest,
+  MoonshineServer,
+} from "@tschk/moonshine/server";
+
+/** `json()` from `@tanstack/react-start`. */
+export function json<T>(data: T, init: ResponseInit = {}): Response {
+  const headers = new Headers(init.headers);
+  if (!headers.has("content-type")) {
+    headers.set("content-type", "application/json; charset=utf-8");
+  }
+  return new Response(JSON.stringify(data), { ...init, headers });
+}
+
+/**
+ * Wrap a server route handler.
+ *
+ * ```ts
+ * export const GET = createServerRoute(async (req) => json({ ok: true }));
+ * ```
+ */
+export function createServerRoute(
+  handler: (request: Request) => Response | Promise<Response>,
+): (request: Request) => Promise<Response> {
+  return async (request) => {
+    try {
+      return await handler(request);
+    } catch (e) {
+      const message = e instanceof Error ? e.message : String(e);
+      return json({ error: message }, { status: 500 });
+    }
+  };
+}