react-iten 0.4.1 → 0.4.2

package/README.md

@@ -1,5 +1,106 @@
 # react-iten
 
-Reserved package for the upcoming React adapter for `iten`.
+React bindings for `iten`, an ultralight typed in-memory router for embedded JavaScript apps.
 
-Use `jotai-iten` today for React apps, or `iten-core` for framework-agnostic routing.
+Use this package when you want `iten` route state and React hooks/components without Jotai. Use `jotai-iten` when router context or guards should read Jotai atoms directly.
+
+## Install
+
+```bash
+npm install react-iten react
+```
+
+`react-iten` depends on `iten-core`. Install `@tanstack/react-query` only when route loaders call `queryClient.ensureQueryData`, and install `zod` only when using `react-iten/zod`.
+
+## Quick Start
+
+```tsx
+import {
+  createRoute,
+  createRouter,
+  defineRoutes,
+  type InferRoutes,
+  route,
+} from 'react-iten'
+
+const routes = defineRoutes({
+  home: route(),
+  project: route<{ id: string }>(),
+  settings: route(),
+})
+
+type Routes = InferRoutes<typeof routes>
+
+const toRoute = createRoute(routes)
+
+const router = createRouter<Routes>({
+  initial: toRoute({ name: 'home' }),
+})
+
+export const { Link, Navigate, Route, Switch, useNavigate, useRoute } = router
+```
+
+```tsx
+<Switch>
+  <Route name="home">{() => <Home />}</Route>
+  <Route name="project">{({ id }) => <Project id={id} />}</Route>
+  <Route name="settings">{() => <Settings />}</Route>
+  <Navigate to={toRoute({ name: 'home' })} />
+</Switch>
+```
+
+## Headless Router
+
+```ts
+import { createHeadlessRouter } from 'react-iten/headless'
+
+const router = createHeadlessRouter<Routes>({
+  initial: toRoute({ name: 'home' }),
+})
+
+router.store.getState()
+await router.store.navigate({ target: toRoute({ name: 'settings' }) })
+```
+
+The store is scoped to the router instance and uses `useSyncExternalStore` for React subscriptions.
+
+## URL Sync
+
+`react-iten/url` keeps URL support explicit and optional.
+
+```ts
+import { createUrlSync } from 'react-iten/url'
+
+const sync = createUrlSync({
+  router,
+  parse: ({ url }) => parseRoute(url),
+  format: ({ route }) => formatRoute(route),
+})
+
+await sync.hydrate()
+sync.start()
+```
+
+## Zod Runtime Validation
+
+```ts
+import { z } from 'zod'
+import { createZodRoute, defineZodRoutes, zodNoParams } from 'react-iten/zod'
+
+const schemas = defineZodRoutes({
+  home: zodNoParams(),
+  project: z.object({ id: z.string().min(1) }).strict(),
+})
+
+const toRoute = createZodRoute(schemas)
+
+toRoute({ name: 'project', input: { id: 'alpha' } })
+```
+
+## Entry Points
+
+- `react-iten`: hooks, components, route utilities, and types
+- `react-iten/headless`: hooks and scoped store without components
+- `react-iten/url`: optional URL sync adapter
+- `react-iten/zod`: optional Zod route factories and parsers
+- `react-iten/utils`: route factories, guards, matching, and type utilities

package/dist/components/Link.cjs

@@ -0,0 +1,21 @@
+let react = require("react");
+let react_jsx_runtime = require("react/jsx-runtime");
+//#region src/components/Link.tsx
+function makeLink(hooks) {
+	const { useNavigate, useRouteLoading } = hooks;
+	function Link({ to, children }) {
+		const navigate = useNavigate();
+		const isLoading = useRouteLoading({ name: to.name });
+		return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("a", {
+			href: "#",
+			onClick: (0, react.useCallback)((event) => {
+				event.preventDefault();
+				navigate({ target: to });
+			}, [navigate, to]),
+			children: children({ isLoading })
+		});
+	}
+	return Link;
+}
+//#endregion
+exports.makeLink = makeLink;

package/dist/components/Link.d.cts

@@ -0,0 +1,13 @@
+import { RouteMapDef, RouteUnion } from "iten-core";
+import { ReactNode } from "react";
+
+//#region src/components/Link.d.ts
+type LinkProps<M extends RouteMapDef> = {
+  to: RouteUnion<M>;
+  children: (state: {
+    isLoading: boolean;
+  }) => ReactNode;
+};
+type LinkComponent<M extends RouteMapDef> = (props: LinkProps<M>) => ReactNode;
+//#endregion
+export { LinkComponent, LinkProps };

package/dist/components/Link.d.ts

@@ -0,0 +1,13 @@
+import { RouteMapDef, RouteUnion } from "iten-core";
+import { ReactNode } from "react";
+
+//#region src/components/Link.d.ts
+type LinkProps<M extends RouteMapDef> = {
+  to: RouteUnion<M>;
+  children: (state: {
+    isLoading: boolean;
+  }) => ReactNode;
+};
+type LinkComponent<M extends RouteMapDef> = (props: LinkProps<M>) => ReactNode;
+//#endregion
+export { LinkComponent, LinkProps };

package/dist/components/Link.mjs

@@ -0,0 +1,21 @@
+import { useCallback } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/components/Link.tsx
+function makeLink(hooks) {
+	const { useNavigate, useRouteLoading } = hooks;
+	function Link({ to, children }) {
+		const navigate = useNavigate();
+		const isLoading = useRouteLoading({ name: to.name });
+		return /* @__PURE__ */ jsx("a", {
+			href: "#",
+			onClick: useCallback((event) => {
+				event.preventDefault();
+				navigate({ target: to });
+			}, [navigate, to]),
+			children: children({ isLoading })
+		});
+	}
+	return Link;
+}
+//#endregion
+export { makeLink };

package/dist/components/Navigate.cjs

@@ -0,0 +1,15 @@
+let react = require("react");
+//#region src/components/Navigate.tsx
+function makeNavigate(hooks) {
+	const { useNavigate } = hooks;
+	function Navigate({ to }) {
+		const navigate = useNavigate();
+		(0, react.useEffect)(() => {
+			navigate({ target: to });
+		}, []);
+		return null;
+	}
+	return Navigate;
+}
+//#endregion
+exports.makeNavigate = makeNavigate;

package/dist/components/Navigate.d.cts

@@ -0,0 +1,10 @@
+import { RouteMapDef, RouteUnion } from "iten-core";
+import { ReactNode } from "react";
+
+//#region src/components/Navigate.d.ts
+type NavigateProps<M extends RouteMapDef> = {
+  to: RouteUnion<M>;
+};
+type NavigateComponent<M extends RouteMapDef> = (props: NavigateProps<M>) => ReactNode;
+//#endregion
+export { NavigateComponent, NavigateProps };

package/dist/components/Navigate.d.ts

@@ -0,0 +1,10 @@
+import { RouteMapDef, RouteUnion } from "iten-core";
+import { ReactNode } from "react";
+
+//#region src/components/Navigate.d.ts
+type NavigateProps<M extends RouteMapDef> = {
+  to: RouteUnion<M>;
+};
+type NavigateComponent<M extends RouteMapDef> = (props: NavigateProps<M>) => ReactNode;
+//#endregion
+export { NavigateComponent, NavigateProps };

package/dist/components/Navigate.mjs

@@ -0,0 +1,15 @@
+import { useEffect } from "react";
+//#region src/components/Navigate.tsx
+function makeNavigate(hooks) {
+	const { useNavigate } = hooks;
+	function Navigate({ to }) {
+		const navigate = useNavigate();
+		useEffect(() => {
+			navigate({ target: to });
+		}, []);
+		return null;
+	}
+	return Navigate;
+}
+//#endregion
+export { makeNavigate };

package/dist/components/Route.cjs

@@ -0,0 +1,22 @@
+let react_jsx_runtime = require("react/jsx-runtime");
+//#region src/components/Route.tsx
+function makeRoute(hooks) {
+	const { useRoute, useIsNavigating, useRouterError } = hooks;
+	function Route({ name, children, component: Component, pendingComponent: PendingComponent, errorComponent: ErrorComponent }) {
+		const { isActive, params } = useRoute({ name });
+		const isNavigating = useIsNavigating();
+		const error = useRouterError();
+		if (!isActive) return null;
+		if (error && ErrorComponent) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ErrorComponent, {
+			error: error.error,
+			retry: error.retry
+		});
+		if (isNavigating && PendingComponent) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(PendingComponent, {});
+		if (children) return children(params);
+		if (Component) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Component, { ...params });
+		return null;
+	}
+	return Route;
+}
+//#endregion
+exports.makeRoute = makeRoute;

package/dist/components/Route.d.cts

@@ -0,0 +1,17 @@
+import { RouteMapDef } from "iten-core";
+import { ComponentType, ReactNode } from "react";
+
+//#region src/components/Route.d.ts
+type RouteProps<M extends RouteMapDef, K extends keyof M> = {
+  name: K;
+  children?: ((params: M[K]) => ReactNode) | undefined;
+  component?: ComponentType<M[K]> | undefined;
+  pendingComponent?: ComponentType | undefined;
+  errorComponent?: ComponentType<{
+    error: unknown;
+    retry: () => Promise<void>;
+  }> | undefined;
+};
+type RouteComponent<M extends RouteMapDef> = <K extends keyof M>(props: RouteProps<M, K>) => ReactNode;
+//#endregion
+export { RouteComponent, RouteProps };

package/dist/components/Route.d.ts

@@ -0,0 +1,17 @@
+import { RouteMapDef } from "iten-core";
+import { ComponentType, ReactNode } from "react";
+
+//#region src/components/Route.d.ts
+type RouteProps<M extends RouteMapDef, K extends keyof M> = {
+  name: K;
+  children?: ((params: M[K]) => ReactNode) | undefined;
+  component?: ComponentType<M[K]> | undefined;
+  pendingComponent?: ComponentType | undefined;
+  errorComponent?: ComponentType<{
+    error: unknown;
+    retry: () => Promise<void>;
+  }> | undefined;
+};
+type RouteComponent<M extends RouteMapDef> = <K extends keyof M>(props: RouteProps<M, K>) => ReactNode;
+//#endregion
+export { RouteComponent, RouteProps };

package/dist/components/Route.mjs

@@ -0,0 +1,22 @@
+import { jsx } from "react/jsx-runtime";
+//#region src/components/Route.tsx
+function makeRoute(hooks) {
+	const { useRoute, useIsNavigating, useRouterError } = hooks;
+	function Route({ name, children, component: Component, pendingComponent: PendingComponent, errorComponent: ErrorComponent }) {
+		const { isActive, params } = useRoute({ name });
+		const isNavigating = useIsNavigating();
+		const error = useRouterError();
+		if (!isActive) return null;
+		if (error && ErrorComponent) return /* @__PURE__ */ jsx(ErrorComponent, {
+			error: error.error,
+			retry: error.retry
+		});
+		if (isNavigating && PendingComponent) return /* @__PURE__ */ jsx(PendingComponent, {});
+		if (children) return children(params);
+		if (Component) return /* @__PURE__ */ jsx(Component, { ...params });
+		return null;
+	}
+	return Route;
+}
+//#endregion
+export { makeRoute };

package/dist/components/Switch.cjs

@@ -0,0 +1,21 @@
+let react = require("react");
+//#region src/components/Switch.tsx
+function makeSwitch(hooks) {
+	const { useCurrentRoute } = hooks;
+	function Switch({ children }) {
+		const route = useCurrentRoute();
+		for (const child of react.Children.toArray(children)) {
+			if (!(0, react.isValidElement)(child)) continue;
+			const props = child.props;
+			if ("name" in props) {
+				if (props.name === route?.name) return child;
+				continue;
+			}
+			return child;
+		}
+		return null;
+	}
+	return Switch;
+}
+//#endregion
+exports.makeSwitch = makeSwitch;

package/dist/components/Switch.d.cts

@@ -0,0 +1,9 @@
+import { RouteMapDef } from "iten-core";
+import { ReactNode } from "react";
+
+//#region src/components/Switch.d.ts
+type SwitchComponent = (props: {
+  children: ReactNode;
+}) => ReactNode;
+//#endregion
+export { SwitchComponent };

package/dist/components/Switch.d.ts

@@ -0,0 +1,9 @@
+import { RouteMapDef } from "iten-core";
+import { ReactNode } from "react";
+
+//#region src/components/Switch.d.ts
+type SwitchComponent = (props: {
+  children: ReactNode;
+}) => ReactNode;
+//#endregion
+export { SwitchComponent };

package/dist/components/Switch.mjs

@@ -0,0 +1,21 @@
+import { Children, isValidElement } from "react";
+//#region src/components/Switch.tsx
+function makeSwitch(hooks) {
+	const { useCurrentRoute } = hooks;
+	function Switch({ children }) {
+		const route = useCurrentRoute();
+		for (const child of Children.toArray(children)) {
+			if (!isValidElement(child)) continue;
+			const props = child.props;
+			if ("name" in props) {
+				if (props.name === route?.name) return child;
+				continue;
+			}
+			return child;
+		}
+		return null;
+	}
+	return Switch;
+}
+//#endregion
+export { makeSwitch };

package/dist/create-router.cjs

@@ -0,0 +1,18 @@
+const require_Link = require("./components/Link.cjs");
+const require_Navigate = require("./components/Navigate.cjs");
+const require_Route = require("./components/Route.cjs");
+const require_Switch = require("./components/Switch.cjs");
+const require_headless = require("./headless.cjs");
+//#region src/create-router.ts
+function createRouter(config) {
+	const hooks = require_headless.createHeadlessRouter(config);
+	return {
+		...hooks,
+		Route: require_Route.makeRoute(hooks),
+		Switch: require_Switch.makeSwitch(hooks),
+		Link: require_Link.makeLink(hooks),
+		Navigate: require_Navigate.makeNavigate(hooks)
+	};
+}
+//#endregion
+exports.createRouter = createRouter;

package/dist/create-router.d.cts

@@ -0,0 +1,18 @@
+import { ReactRouterConfig } from "./types.cjs";
+import { HeadlessReactRouter } from "./headless.cjs";
+import { LinkComponent } from "./components/Link.cjs";
+import { NavigateComponent } from "./components/Navigate.cjs";
+import { RouteComponent } from "./components/Route.cjs";
+import { SwitchComponent } from "./components/Switch.cjs";
+import { RouteMapDef } from "iten-core";
+
+//#region src/create-router.d.ts
+type ReactRouter<M extends RouteMapDef, _Ctx = unknown> = HeadlessReactRouter<M> & {
+  Route: RouteComponent<M>;
+  Switch: SwitchComponent;
+  Link: LinkComponent<M>;
+  Navigate: NavigateComponent<M>;
+};
+declare function createRouter<M extends RouteMapDef, Ctx = unknown>(config: ReactRouterConfig<M, Ctx>): ReactRouter<M, Ctx>;
+//#endregion
+export { ReactRouter, createRouter };

package/dist/create-router.d.ts

@@ -0,0 +1,18 @@
+import { ReactRouterConfig } from "./types.js";
+import { HeadlessReactRouter } from "./headless.js";
+import { LinkComponent } from "./components/Link.js";
+import { NavigateComponent } from "./components/Navigate.js";
+import { RouteComponent } from "./components/Route.js";
+import { SwitchComponent } from "./components/Switch.js";
+import { RouteMapDef } from "iten-core";
+
+//#region src/create-router.d.ts
+type ReactRouter<M extends RouteMapDef, _Ctx = unknown> = HeadlessReactRouter<M> & {
+  Route: RouteComponent<M>;
+  Switch: SwitchComponent;
+  Link: LinkComponent<M>;
+  Navigate: NavigateComponent<M>;
+};
+declare function createRouter<M extends RouteMapDef, Ctx = unknown>(config: ReactRouterConfig<M, Ctx>): ReactRouter<M, Ctx>;
+//#endregion
+export { ReactRouter, createRouter };

package/dist/create-router.mjs

@@ -0,0 +1,18 @@
+import { makeLink } from "./components/Link.mjs";
+import { makeNavigate } from "./components/Navigate.mjs";
+import { makeRoute } from "./components/Route.mjs";
+import { makeSwitch } from "./components/Switch.mjs";
+import { createHeadlessRouter } from "./headless.mjs";
+//#region src/create-router.ts
+function createRouter(config) {
+	const hooks = createHeadlessRouter(config);
+	return {
+		...hooks,
+		Route: makeRoute(hooks),
+		Switch: makeSwitch(hooks),
+		Link: makeLink(hooks),
+		Navigate: makeNavigate(hooks)
+	};
+}
+//#endregion
+export { createRouter };

package/dist/headless.cjs

@@ -0,0 +1,83 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_hooks = require("./hooks.cjs");
+let iten_core = require("iten-core");
+//#region src/headless.ts
+function createHeadlessRouter(config) {
+	const getCtx = () => {
+		if (typeof config.context === "function") return config.context();
+		return config.context ?? {};
+	};
+	const core = (0, iten_core.createItenCore)({
+		initial: config.initial,
+		routeConfig: config.routeConfig,
+		maxHistoryLength: config.maxHistoryLength,
+		queryClient: config.queryClient,
+		getCtx
+	});
+	let snapshot = core.getState();
+	const store = {
+		getState: () => snapshot,
+		subscribe: ({ listener }) => core.subscribe({ listener: (nextSnapshot) => {
+			snapshot = nextSnapshot;
+			listener();
+		} }),
+		navigate: async (input) => {
+			await core.navigate(input);
+			snapshot = core.getState();
+		},
+		goBack: () => {
+			core.goBack();
+			snapshot = core.getState();
+		},
+		dispose: () => core.dispose()
+	};
+	return {
+		store,
+		core,
+		...require_hooks.makeHooks(store)
+	};
+}
+//#endregion
+exports.createHeadlessRouter = createHeadlessRouter;
+Object.defineProperty(exports, "createRoute", {
+	enumerable: true,
+	get: function() {
+		return iten_core.createRoute;
+	}
+});
+Object.defineProperty(exports, "defineRouteConfig", {
+	enumerable: true,
+	get: function() {
+		return iten_core.defineRouteConfig;
+	}
+});
+Object.defineProperty(exports, "defineRoutes", {
+	enumerable: true,
+	get: function() {
+		return iten_core.defineRoutes;
+	}
+});
+Object.defineProperty(exports, "isRoute", {
+	enumerable: true,
+	get: function() {
+		return iten_core.isRoute;
+	}
+});
+Object.defineProperty(exports, "isRouteName", {
+	enumerable: true,
+	get: function() {
+		return iten_core.isRouteName;
+	}
+});
+Object.defineProperty(exports, "matchRoute", {
+	enumerable: true,
+	get: function() {
+		return iten_core.matchRoute;
+	}
+});
+Object.defineProperty(exports, "route", {
+	enumerable: true,
+	get: function() {
+		return iten_core.route;
+	}
+});

package/dist/headless.d.cts

@@ -0,0 +1,21 @@
+import { InferRoutes, NoParams, QueryClientLike, ReactRouterConfig, RouteConfigMap, RouteMap, RouteMapDef, RouteMatcher, RouteName, RouteOf, RouteParams, RouteUnion, RouterError, RouterState, UseRouteResult } from "./types.cjs";
+import { HookBundle } from "./hooks.cjs";
+import { ItenCore, NavigateInput, RouteMapDef as RouteMapDef$1, RouterState as RouterState$1, createRoute, defineRouteConfig, defineRoutes, isRoute, isRouteName, matchRoute, route } from "iten-core";
+
+//#region src/headless.d.ts
+type ReactRouterStore<M extends RouteMapDef$1> = {
+  getState: () => RouterState$1<M>;
+  subscribe: (input: {
+    listener: () => void;
+  }) => () => void;
+  navigate: (input: NavigateInput<M>) => Promise<void>;
+  goBack: () => void;
+  dispose: () => void;
+};
+type HeadlessReactRouter<M extends RouteMapDef$1> = HookBundle<M> & {
+  store: ReactRouterStore<M>;
+  core: ItenCore<M>;
+};
+declare function createHeadlessRouter<M extends RouteMapDef$1, Ctx = unknown>(config: ReactRouterConfig<M, Ctx>): HeadlessReactRouter<M>;
+//#endregion
+export { HeadlessReactRouter, type InferRoutes, type NoParams, type QueryClientLike, ReactRouterStore, type RouteConfigMap, type RouteMap, type RouteMapDef, type RouteMatcher, type RouteName, type RouteOf, type RouteParams, type RouteUnion, type RouterError, type RouterState, type UseRouteResult, createHeadlessRouter, createRoute, defineRouteConfig, defineRoutes, isRoute, isRouteName, matchRoute, route };

package/dist/headless.d.ts

@@ -0,0 +1,21 @@
+import { InferRoutes, NoParams, QueryClientLike, ReactRouterConfig, RouteConfigMap, RouteMap, RouteMapDef, RouteMatcher, RouteName, RouteOf, RouteParams, RouteUnion, RouterError, RouterState, UseRouteResult } from "./types.js";
+import { HookBundle } from "./hooks.js";
+import { ItenCore, NavigateInput, RouteMapDef as RouteMapDef$1, RouterState as RouterState$1, createRoute, defineRouteConfig, defineRoutes, isRoute, isRouteName, matchRoute, route } from "iten-core";
+
+//#region src/headless.d.ts
+type ReactRouterStore<M extends RouteMapDef$1> = {
+  getState: () => RouterState$1<M>;
+  subscribe: (input: {
+    listener: () => void;
+  }) => () => void;
+  navigate: (input: NavigateInput<M>) => Promise<void>;
+  goBack: () => void;
+  dispose: () => void;
+};
+type HeadlessReactRouter<M extends RouteMapDef$1> = HookBundle<M> & {
+  store: ReactRouterStore<M>;
+  core: ItenCore<M>;
+};
+declare function createHeadlessRouter<M extends RouteMapDef$1, Ctx = unknown>(config: ReactRouterConfig<M, Ctx>): HeadlessReactRouter<M>;
+//#endregion
+export { HeadlessReactRouter, type InferRoutes, type NoParams, type QueryClientLike, ReactRouterStore, type RouteConfigMap, type RouteMap, type RouteMapDef, type RouteMatcher, type RouteName, type RouteOf, type RouteParams, type RouteUnion, type RouterError, type RouterState, type UseRouteResult, createHeadlessRouter, createRoute, defineRouteConfig, defineRoutes, isRoute, isRouteName, matchRoute, route };

package/dist/headless.mjs

@@ -0,0 +1,40 @@
+import { makeHooks } from "./hooks.mjs";
+import { createItenCore, createRoute, defineRouteConfig, defineRoutes, isRoute, isRouteName, matchRoute, route } from "iten-core";
+//#region src/headless.ts
+function createHeadlessRouter(config) {
+	const getCtx = () => {
+		if (typeof config.context === "function") return config.context();
+		return config.context ?? {};
+	};
+	const core = createItenCore({
+		initial: config.initial,
+		routeConfig: config.routeConfig,
+		maxHistoryLength: config.maxHistoryLength,
+		queryClient: config.queryClient,
+		getCtx
+	});
+	let snapshot = core.getState();
+	const store = {
+		getState: () => snapshot,
+		subscribe: ({ listener }) => core.subscribe({ listener: (nextSnapshot) => {
+			snapshot = nextSnapshot;
+			listener();
+		} }),
+		navigate: async (input) => {
+			await core.navigate(input);
+			snapshot = core.getState();
+		},
+		goBack: () => {
+			core.goBack();
+			snapshot = core.getState();
+		},
+		dispose: () => core.dispose()
+	};
+	return {
+		store,
+		core,
+		...makeHooks(store)
+	};
+}
+//#endregion
+export { createHeadlessRouter, createRoute, defineRouteConfig, defineRoutes, isRoute, isRouteName, matchRoute, route };