feat: react tuyau adapter

Author: Julien-R44

package.json

@@ -19,6 +19,7 @@
     "./plugins/api_client": "./build/src/plugins/japa/api_client.js",
     "./vite": "./build/src/client/vite.js",
     "./helpers": "./build/src/client/helpers.js",
+    "./react": "./build/src/client/react/index.js",
     "./factories": "./build/factories/main.js"
   },
   "scripts": {
@@ -43,12 +44,13 @@
   },
   "devDependencies": {
     "@adonisjs/assembler": "^8.0.0-next.14",
-    "@adonisjs/core": "^7.0.0-next.8",
+    "@adonisjs/core": "^7.0.0-next.10",
     "@adonisjs/eslint-config": "^3.0.0-next.4",
     "@adonisjs/prettier-config": "^1.4.5",
     "@adonisjs/session": "^8.0.0-next.0",
     "@adonisjs/tsconfig": "^2.0.0-next.3",
     "@adonisjs/vite": "^5.1.0-next.0",
+    "@inertiajs/react": "^2.2.15",
     "@japa/api-client": "^3.1.0",
     "@japa/assert": "4.1.1",
     "@japa/expect-type": "^2.0.3",
@@ -58,7 +60,9 @@
     "@japa/snapshot": "^2.0.9",
     "@poppinss/ts-exec": "^1.4.1",
     "@release-it/conventional-changelog": "^10.0.1",
+    "@tuyau/core": "^1.0.0-beta.1",
     "@types/node": "^24.8.1",
+    "@types/react": "^19.2.2",
     "@types/supertest": "^6.0.3",
     "c8": "^10.1.3",
     "copyfiles": "^2.4.1",
@@ -68,6 +72,7 @@
     "eslint": "^9.38.0",
     "get-port": "^7.1.0",
     "prettier": "^3.6.2",
+    "react": "^19.2.0",
     "release-it": "^19.0.5",
     "supertest": "^7.1.4",
     "tsup": "^8.5.0",
@@ -81,12 +86,15 @@
   },
   "peerDependencies": {
     "@adonisjs/assembler": "^8.0.0-next.14",
-    "@adonisjs/core": "^7.0.0-next.6",
+    "@adonisjs/core": "^7.0.0-next.10",
     "@adonisjs/session": "^8.0.0-next.0",
     "@adonisjs/vite": "^5.1.0-next.0",
+    "@inertiajs/react": "^2.2.15",
     "@japa/api-client": "^3.1.0",
     "@japa/plugin-adonisjs": "^5.0.0-next.0",
-    "edge.js": "^6.0.0"
+    "@tuyau/core": "^1.0.0-beta.1",
+    "edge.js": "^6.0.0",
+    "react": "^19.2.0"
   },
   "peerDependenciesMeta": {
     "@adonisjs/assembler": {
@@ -97,6 +105,15 @@
     },
     "@japa/plugin-adonisjs": {
       "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "@tuyau/core": {
+      "optional": true
+    },
+    "@inertiajs/react": {
+      "optional": true
     }
   },
   "keywords": [
@@ -153,7 +170,8 @@
       "./src/inertia_middleware.ts",
       "./providers/inertia_provider.ts",
       "./src/plugins/edge/plugin.ts",
-      "./src/plugins/japa/api_client.ts"
+      "./src/plugins/japa/api_client.ts",
+      "./src/client/react/index.tsx"
     ],
     "outDir": "./build",
     "clean": true,

src/client/react/context.tsx

@@ -0,0 +1,48 @@
+/*
+ * @adonisjs/inertia
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import React from 'react'
+import type { Tuyau } from '@tuyau/core/client'
+import type { AdonisRegistry } from '@tuyau/core/types'
+
+/**
+ * React context for providing Tuyau client instance throughout the component tree
+ */
+const TuyauContext = React.createContext<Tuyau<any> | null>(null)
+
+/**
+ * Provider component that makes the Tuyau client available to child components.
+ *
+ * This component should wrap your entire application or the part of your
+ * application that needs access to type-safe routing functionality.
+ *
+ */
+export function TuyauProvider<R extends AdonisRegistry>(props: {
+  children: React.ReactNode
+  client: Tuyau<R>
+}) {
+  return <TuyauContext.Provider value={props.client}>{props.children}</TuyauContext.Provider>
+}
+
+/**
+ * Hook to access the Tuyau client from any component within a TuyauProvider.
+ *
+ * Provides type-safe access to route generation and navigation utilities.
+ * Must be used within a component tree wrapped by TuyauProvider.
+ *
+ * @returns The Tuyau client instance with full type safety
+ * @throws Error if used outside of a TuyauProvider
+ */
+
+export function useTuyau() {
+  const context = React.useContext(TuyauContext)
+  if (!context) throw new Error('You must wrap your app in a TuyauProvider')
+
+  return context
+}

src/client/react/index.tsx

@@ -0,0 +1,12 @@
+/*
+ * @adonisjs/inertia
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+export * from './context.tsx'
+export * from './router.ts'
+export * from './link.tsx'

src/client/react/link.tsx

@@ -0,0 +1,106 @@
+/*
+ * @adonisjs/inertia
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import React from 'react'
+import type { UserRegistry } from '@tuyau/core/types'
+import { Link as InertiaLink } from '@inertiajs/react'
+import { useTuyau } from './context.tsx'
+import { AreAllOptional } from '@poppinss/utils/types'
+
+/**
+ * Get parameter tuple type for a route
+ */
+type ExtractParamsTuple<Route extends keyof UserRegistry> =
+  UserRegistry[Route]['types']['paramsTuple']
+
+/**
+ * Get parameter object type for a route
+ */
+type ExtractParamsObject<Route extends keyof UserRegistry> = UserRegistry[Route]['types']['params']
+
+/**
+ * Get params format for a route
+ */
+type RouteParamsFormats<Route extends keyof UserRegistry> =
+  ExtractParamsObject<Route> extends Record<string, never>
+    ? never
+    : ExtractParamsTuple<Route> | ExtractParamsObject<Route>
+
+/**
+ * Parameters required for route navigation with proper type safety.
+ */
+export type LinkParams<Route extends keyof UserRegistry> = {
+  route: Route
+} & (RouteParamsFormats<Route> extends never
+  ? { params?: never }
+  : AreAllOptional<ExtractParamsObject<Route>> extends true
+    ? { params?: RouteParamsFormats<Route> }
+    : { params: RouteParamsFormats<Route> })
+
+/**
+ * Props for the Link component extending InertiaLink props
+ * with route-specific type safety and parameter validation.
+ */
+type LinkProps<Route extends keyof UserRegistry> = Omit<
+  React.ComponentPropsWithoutRef<typeof InertiaLink>,
+  'href' | 'method'
+> &
+  LinkParams<Route>
+
+/**
+ * Internal Link component implementation with forward ref support.
+ * Resolves route parameters and generates the appropriate URL and HTTP method
+ * for Inertia navigation.
+ *
+ * @param props - Link properties including route and parameters
+ * @param ref - Forward ref for the underlying InertiaLink component
+ */
+function LinkInner<Route extends keyof UserRegistry>(
+  props: LinkProps<Route>,
+  ref?: React.ForwardedRef<React.ElementRef<typeof InertiaLink>>
+) {
+  const { route, params, ...linkProps } = props
+
+  const tuyau = useTuyau()
+  const routeInfo = tuyau.getRoute(props.route, { params })
+
+  return (
+    <InertiaLink
+      {...linkProps}
+      href={routeInfo.url}
+      method={routeInfo.methods[0].toLowerCase() as any}
+      ref={ref}
+    />
+  )
+}
+
+/**
+ * Type-safe Link component for Inertia.js navigation.
+ *
+ * Provides compile-time route validation and automatic parameter type checking
+ * based on your application's route definitions. Automatically resolves the
+ * correct URL and HTTP method for each route.
+ *
+ * @example
+ * ```tsx
+ * // Link to a route without parameters
+ * <Link route="home">Home</Link>
+ *
+ * // Link to a route with required parameters
+ * <Link route="user.show" params={{ id: 1 }}>
+ *   View User
+ * </Link>
+ * ```
+ */
+
+export const Link: <Route extends keyof UserRegistry>(
+  props: LinkProps<Route> & {
+    ref?: React.Ref<React.ElementRef<typeof InertiaLink>>
+  }
+) => ReturnType<typeof LinkInner> = React.forwardRef(LinkInner as any) as any

src/client/react/router.ts

@@ -0,0 +1,60 @@
+/*
+ * @adonisjs/inertia
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import type { UserRegistry } from '@tuyau/core/types'
+import { router as InertiaRouter } from '@inertiajs/react'
+
+import { useTuyau } from './context.tsx'
+import type { LinkParams } from './link.tsx'
+
+/**
+ * Custom hook providing type-safe navigation utilities for Inertia.js.
+ *
+ * Returns an enhanced router object with type-safe navigation methods
+ * that automatically resolve route URLs and HTTP methods based on
+ * your application's route definitions.
+ *
+ * @returns Router object with type-safe navigation methods
+ */
+export function useRouter() {
+  const tuyau = useTuyau()
+
+  return {
+    /**
+     * Navigate to a route with type-safe parameters and options.
+     *
+     * Automatically resolves the route URL and HTTP method based on the
+     * route definition, then performs the navigation using Inertia's router.
+     *
+     * @param props - Route navigation parameters including route name and params
+     * @param options - Optional Inertia visit options for controlling navigation behavior
+     *
+     * @example
+     * ```tsx
+     * // Navigate to a simple route
+     * router.visit({ route: 'dashboard' })
+     *
+     * // Navigate with parameters
+     * router.visit({ route: 'user.edit', params: { id: userId } })
+     * ```
+     */
+    visit: <Route extends keyof UserRegistry>(
+      props: LinkParams<Route>,
+      options?: Parameters<typeof InertiaRouter.visit>[1]
+    ) => {
+      const routeInfo = tuyau.getRoute(props.route, { params: props.params })
+      const url = routeInfo.url
+
+      return InertiaRouter.visit(url, {
+        ...options,
+        method: routeInfo.methods[0].toLowerCase() as any,
+      })
+    },
+  }
+}