react-iten 0.0.2 → 0.4.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "react-iten",
-  "version": "0.0.2",
-  "description": "React adapter for iten — ultralight in-memory router for embedded JS apps. Coming soon.",
+  "version": "0.4.2",
+  "description": "React adapter for iten — ultralight in-memory router for embedded JS apps",
   "keywords": [
     "react",
     "router",
@@ -18,13 +18,107 @@
     "url": "https://github.com/andrew-bierman/iten/issues"
   },
   "homepage": "https://github.com/andrew-bierman/iten#readme",
-  "main": "index.js",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./headless": {
+      "bun": "./src/headless.ts",
+      "import": {
+        "types": "./dist/headless.d.ts",
+        "default": "./dist/headless.mjs"
+      },
+      "require": {
+        "types": "./dist/headless.d.cts",
+        "default": "./dist/headless.cjs"
+      }
+    },
+    "./zod": {
+      "bun": "./src/zod.ts",
+      "import": {
+        "types": "./dist/zod.d.ts",
+        "default": "./dist/zod.mjs"
+      },
+      "require": {
+        "types": "./dist/zod.d.cts",
+        "default": "./dist/zod.cjs"
+      }
+    },
+    "./utils": {
+      "bun": "./src/utils.ts",
+      "import": {
+        "types": "./dist/utils.d.ts",
+        "default": "./dist/utils.mjs"
+      },
+      "require": {
+        "types": "./dist/utils.d.cts",
+        "default": "./dist/utils.cjs"
+      }
+    },
+    "./url": {
+      "bun": "./src/url.ts",
+      "import": {
+        "types": "./dist/url.d.ts",
+        "default": "./dist/url.mjs"
+      },
+      "require": {
+        "types": "./dist/url.d.cts",
+        "default": "./dist/url.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
   "files": [
-    "index.js",
-    "README.md"
+    "dist",
+    "src"
   ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "typecheck:types": "bun run build && tsc -p tsconfig.type-tests.json",
+    "test": "bun test ./test"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.0.0",
+    "react": "^18.3.0 || ^19.0.0",
+    "zod": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/react-query": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "iten-core": "^0.4.2"
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.101.2",
+    "@testing-library/react": "^16.0.0",
+    "@types/react": "^19.0.0",
+    "happy-dom": "^20.9.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsdown": "0.21.9",
+    "typescript": "^5.7.0",
+    "zod": "^4.4.3"
   }
 }

package/src/components/Link.tsx

@@ -0,0 +1,36 @@
+import type { RouteMapDef, RouteUnion } from 'iten-core'
+import { type MouseEvent, type ReactNode, useCallback } from 'react'
+import type { HookBundle } from '../hooks.ts'
+
+export type LinkProps<M extends RouteMapDef> = {
+  to: RouteUnion<M>
+  children: (state: { isLoading: boolean }) => ReactNode
+}
+
+export type LinkComponent<M extends RouteMapDef> = (props: LinkProps<M>) => ReactNode
+
+export function makeLink<M extends RouteMapDef>(hooks: HookBundle<M>): LinkComponent<M> {
+  const { useNavigate, useRouteLoading } = hooks
+
+  function Link({ to, children }: LinkProps<M>): ReactNode {
+    const navigate = useNavigate()
+    const isLoading = useRouteLoading({ name: to.name as keyof M })
+
+    const handleClick = useCallback(
+      (event: MouseEvent) => {
+        event.preventDefault()
+        void navigate({ target: to })
+      },
+      [navigate, to],
+    )
+
+    return (
+      // biome-ignore lint/a11y/useValidAnchor: embedded app context uses in-memory navigation
+      <a href="#" onClick={handleClick}>
+        {children({ isLoading })}
+      </a>
+    )
+  }
+
+  return Link
+}

package/src/components/Navigate.tsx

@@ -0,0 +1,26 @@
+import type { RouteMapDef, RouteUnion } from 'iten-core'
+import { type ReactNode, useEffect } from 'react'
+import type { HookBundle } from '../hooks.ts'
+
+export type NavigateProps<M extends RouteMapDef> = {
+  to: RouteUnion<M>
+}
+
+export type NavigateComponent<M extends RouteMapDef> = (props: NavigateProps<M>) => ReactNode
+
+export function makeNavigate<M extends RouteMapDef>(hooks: HookBundle<M>): NavigateComponent<M> {
+  const { useNavigate } = hooks
+
+  function Navigate({ to }: NavigateProps<M>): ReactNode {
+    const navigate = useNavigate()
+
+    // biome-ignore lint/correctness/useExhaustiveDependencies: redirect should fire once on mount
+    useEffect(() => {
+      void navigate({ target: to })
+    }, [])
+
+    return null
+  }
+
+  return Navigate
+}

package/src/components/Route.tsx

@@ -0,0 +1,53 @@
+import type { RouteMapDef } from 'iten-core'
+import type { ComponentType, ReactNode } from 'react'
+import type { HookBundle } from '../hooks.ts'
+
+export 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
+}
+
+export type RouteComponent<M extends RouteMapDef> = <K extends keyof M>(
+  props: RouteProps<M, K>,
+) => ReactNode
+
+export function makeRoute<M extends RouteMapDef>(hooks: HookBundle<M>): RouteComponent<M> {
+  const { useRoute, useIsNavigating, useRouterError } = hooks
+
+  function Route<K extends keyof M>({
+    name,
+    children,
+    component: Component,
+    pendingComponent: PendingComponent,
+    errorComponent: ErrorComponent,
+  }: RouteProps<M, K>): ReactNode {
+    const { isActive, params } = useRoute({ name })
+    const isNavigating = useIsNavigating()
+    const error = useRouterError()
+
+    if (!isActive) return null
+
+    if (error && ErrorComponent) {
+      return <ErrorComponent error={error.error} retry={error.retry} />
+    }
+
+    if (isNavigating && PendingComponent) {
+      return <PendingComponent />
+    }
+
+    if (children) {
+      return children(params)
+    }
+
+    if (Component) {
+      return <Component {...params} />
+    }
+
+    return null
+  }
+
+  return Route
+}

package/src/components/Switch.tsx

@@ -0,0 +1,30 @@
+import type { RouteMapDef } from 'iten-core'
+import { Children, isValidElement, type ReactNode } from 'react'
+import type { HookBundle } from '../hooks.ts'
+
+export type SwitchComponent = (props: { children: ReactNode }) => ReactNode
+
+export function makeSwitch<M extends RouteMapDef>(hooks: HookBundle<M>): SwitchComponent {
+  const { useCurrentRoute } = hooks
+
+  function Switch({ children }: { children: ReactNode }): ReactNode {
+    const route = useCurrentRoute()
+
+    for (const child of Children.toArray(children)) {
+      if (!isValidElement(child)) continue
+
+      const props = child.props as Record<string, unknown>
+
+      if ('name' in props) {
+        if (props.name === route?.name) return child
+        continue
+      }
+
+      return child
+    }
+
+    return null
+  }
+
+  return Switch
+}

package/src/create-router.ts

@@ -0,0 +1,33 @@
+import type { RouteMapDef } from 'iten-core'
+import type { LinkComponent } from './components/Link.tsx'
+import { makeLink } from './components/Link.tsx'
+import type { NavigateComponent } from './components/Navigate.tsx'
+import { makeNavigate } from './components/Navigate.tsx'
+import type { RouteComponent } from './components/Route.tsx'
+import { makeRoute } from './components/Route.tsx'
+import type { SwitchComponent } from './components/Switch.tsx'
+import { makeSwitch } from './components/Switch.tsx'
+import type { HeadlessReactRouter } from './headless.ts'
+import { createHeadlessRouter } from './headless.ts'
+import type { ReactRouterConfig } from './types.ts'
+
+export type ReactRouter<M extends RouteMapDef, _Ctx = unknown> = HeadlessReactRouter<M> & {
+  Route: RouteComponent<M>
+  Switch: SwitchComponent
+  Link: LinkComponent<M>
+  Navigate: NavigateComponent<M>
+}
+
+export function createRouter<M extends RouteMapDef, Ctx = unknown>(
+  config: ReactRouterConfig<M, Ctx>,
+): ReactRouter<M, Ctx> {
+  const hooks = createHeadlessRouter<M, Ctx>(config)
+
+  return {
+    ...hooks,
+    Route: makeRoute<M>(hooks),
+    Switch: makeSwitch<M>(hooks),
+    Link: makeLink<M>(hooks),
+    Navigate: makeNavigate<M>(hooks),
+  }
+}

package/src/headless.ts

@@ -0,0 +1,91 @@
+import type { ItenCore, NavigateInput, RouteMapDef, RouterState } from 'iten-core'
+import { createItenCore } from 'iten-core'
+import type { HookBundle } from './hooks.ts'
+import { makeHooks } from './hooks.ts'
+import type { ReactRouterConfig } from './types.ts'
+
+export {
+  createRoute,
+  defineRouteConfig,
+  defineRoutes,
+  isRoute,
+  isRouteName,
+  matchRoute,
+  route,
+} from 'iten-core'
+export type {
+  InferRoutes,
+  NoParams,
+  QueryClientLike,
+  RouteConfigMap,
+  RouteMap,
+  RouteMapDef,
+  RouteMatcher,
+  RouteName,
+  RouteOf,
+  RouteParams,
+  RouterError,
+  RouterState,
+  RouteUnion,
+  UseRouteResult,
+} from './types.ts'
+
+export type ReactRouterStore<M extends RouteMapDef> = {
+  getState: () => RouterState<M>
+  subscribe: (input: { listener: () => void }) => () => void
+  navigate: (input: NavigateInput<M>) => Promise<void>
+  goBack: () => void
+  dispose: () => void
+}
+
+export type HeadlessReactRouter<M extends RouteMapDef> = HookBundle<M> & {
+  store: ReactRouterStore<M>
+  core: ItenCore<M>
+}
+
+export function createHeadlessRouter<M extends RouteMapDef, Ctx = unknown>(
+  config: ReactRouterConfig<M, Ctx>,
+): HeadlessReactRouter<M> {
+  const getCtx = (): Ctx => {
+    if (typeof config.context === 'function') {
+      return (config.context as () => Ctx)()
+    }
+    return (config.context ?? {}) as Ctx
+  }
+
+  const core = createItenCore<M, Ctx>({
+    initial: config.initial,
+    routeConfig: config.routeConfig,
+    maxHistoryLength: config.maxHistoryLength,
+    queryClient: config.queryClient,
+    getCtx,
+  })
+
+  let snapshot = core.getState()
+
+  const store: ReactRouterStore<M> = {
+    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<M>(store),
+  }
+}

package/src/hooks.ts

@@ -0,0 +1,74 @@
+import type { NavigateInput, RouteMapDef, RouterError, RouterState, RouteUnion } from 'iten-core'
+import { useSyncExternalStore } from 'react'
+import type { ReactRouterStore } from './headless.ts'
+import type { UseRouteResult } from './types.ts'
+
+export type HookBundle<M extends RouteMapDef> = {
+  useRouterState: () => RouterState<M>
+  useCurrentRoute: () => RouteUnion<M> | null
+  useRoute: <K extends keyof M>(input: { name: K }) => UseRouteResult<M, K>
+  useNavigate: () => (input: NavigateInput<M>) => Promise<void>
+  useGoBack: () => () => void
+  useIsNavigating: () => boolean
+  useCanGoBack: () => boolean
+  useRouteLoading: (input: { name: keyof M }) => boolean
+  useRouterError: () => RouterError | null
+}
+
+export function makeHooks<M extends RouteMapDef>(store: ReactRouterStore<M>): HookBundle<M> {
+  function useRouterState(): RouterState<M> {
+    return useSyncExternalStore(
+      (listener) => store.subscribe({ listener }),
+      store.getState,
+      store.getState,
+    )
+  }
+
+  function useCurrentRoute(): RouteUnion<M> | null {
+    return useRouterState().route
+  }
+
+  function useRoute<K extends keyof M>({ name }: { name: K }): UseRouteResult<M, K> {
+    const route = useRouterState().route
+    if (route?.name === name) {
+      return { isActive: true, params: route as unknown as M[K] }
+    }
+    return { isActive: false, params: null }
+  }
+
+  function useNavigate(): (input: NavigateInput<M>) => Promise<void> {
+    return store.navigate
+  }
+
+  function useGoBack(): () => void {
+    return store.goBack
+  }
+
+  function useIsNavigating(): boolean {
+    return useRouterState().isNavigating
+  }
+
+  function useCanGoBack(): boolean {
+    return useRouterState().canGoBack
+  }
+
+  function useRouteLoading({ name }: { name: keyof M }): boolean {
+    return useRouterState().pendingRoute?.name === name
+  }
+
+  function useRouterError(): RouterError | null {
+    return useRouterState().error
+  }
+
+  return {
+    useRouterState,
+    useCurrentRoute,
+    useRoute,
+    useNavigate,
+    useGoBack,
+    useIsNavigating,
+    useCanGoBack,
+    useRouteLoading,
+    useRouterError,
+  }
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+export {
+  createRoute,
+  defineRouteConfig,
+  defineRoutes,
+  isRoute,
+  isRouteName,
+  matchRoute,
+  route,
+} from 'iten-core'
+export type { LinkProps } from './components/Link.tsx'
+export type { NavigateProps } from './components/Navigate.tsx'
+export type { RouteProps } from './components/Route.tsx'
+export type { ReactRouter } from './create-router.ts'
+export { createRouter } from './create-router.ts'
+export type { HeadlessReactRouter, ReactRouterStore } from './headless.ts'
+export { createHeadlessRouter } from './headless.ts'
+export type {
+  InferRoutes,
+  NoParams,
+  QueryClientLike,
+  ReactRouterConfig,
+  RouteConfigMap,
+  RouteDefinition,
+  RouteDefinitions,
+  RouteMap,
+  RouteMapDef,
+  RouteMatcher,
+  RouteName,
+  RouteOf,
+  RouteParams,
+  RouterError,
+  RouterState,
+  RouteUnion,
+  UseRouteResult,
+} from './types.ts'

package/src/types.ts

@@ -0,0 +1,47 @@
+import type {
+  InferRoutes,
+  NoParams,
+  QueryClientLike,
+  RouteConfigMap,
+  RouteDefinition,
+  RouteDefinitions,
+  RouteMap,
+  RouteMapDef,
+  RouteMatcher,
+  RouteName,
+  RouteOf,
+  RouteParams,
+  RouterError,
+  RouterState,
+  RouteUnion,
+} from 'iten-core'
+
+export type {
+  InferRoutes,
+  NoParams,
+  QueryClientLike,
+  RouteConfigMap,
+  RouteDefinition,
+  RouteDefinitions,
+  RouteMap,
+  RouteMapDef,
+  RouteMatcher,
+  RouteName,
+  RouteOf,
+  RouteParams,
+  RouterError,
+  RouterState,
+  RouteUnion,
+}
+
+export type ReactRouterConfig<M extends RouteMapDef, Ctx = unknown> = {
+  initial: RouteUnion<M> | null
+  routeConfig?: RouteConfigMap<M, Ctx> | undefined
+  maxHistoryLength?: number | undefined
+  context?: Ctx | (() => Ctx) | undefined
+  queryClient?: QueryClientLike | null | undefined
+}
+
+export type UseRouteResult<M extends RouteMapDef, K extends keyof M> =
+  | { isActive: true; params: M[K] }
+  | { isActive: false; params: null }

package/src/url.ts

@@ -0,0 +1,49 @@
+import type { ItenCore, NavigateInput, RouteMapDef, RouterState } from 'iten-core'
+import {
+  type CreateUrlSyncInput as CoreCreateUrlSyncInput,
+  createUrlSync as createCoreUrlSync,
+  type UrlSync,
+} from 'iten-core/url'
+import type { HeadlessReactRouter } from './headless.ts'
+
+export type {
+  FormatUrlInput,
+  ParseUrlInput,
+  UrlHydrateInput,
+  UrlParseErrorInput,
+  UrlStartInput,
+  UrlSubscribeInput,
+  UrlSync,
+  UrlWriteInput,
+  UrlWriteMode,
+} from 'iten-core/url'
+
+export type CreateUrlSyncInput<M extends RouteMapDef> = Omit<
+  CoreCreateUrlSyncInput<M>,
+  'router'
+> & {
+  router: HeadlessReactRouter<M>
+}
+
+export function createUrlSync<M extends RouteMapDef>({
+  router,
+  ...input
+}: CreateUrlSyncInput<M>): UrlSync<M> {
+  const coreLike: ItenCore<M> = {
+    getState: () => router.store.getState() as RouterState<M>,
+    navigate: (navigateInput: NavigateInput<M>) => router.store.navigate(navigateInput),
+    goBack: () => router.store.goBack(),
+    subscribe: ({ listener }) =>
+      router.store.subscribe({
+        listener: () => {
+          listener(router.store.getState() as RouterState<M>)
+        },
+      }),
+    dispose: () => {},
+  }
+
+  return createCoreUrlSync<M>({
+    ...input,
+    router: coreLike,
+  })
+}

package/src/utils.ts

@@ -0,0 +1,23 @@
+export type {
+  InferRoutes,
+  NoParams,
+  RouteConfigMap,
+  RouteMap,
+  RouteMapDef,
+  RouteUnion,
+} from 'iten-core'
+export type {
+  RouteMatcher,
+  RouteName,
+  RouteOf,
+  RouteParams,
+} from 'iten-core/utils'
+export {
+  createRoute,
+  defineRouteConfig,
+  defineRoutes,
+  isRoute,
+  isRouteName,
+  matchRoute,
+  route,
+} from 'iten-core/utils'