@octanejs/inertia 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,33 @@
+# `@octanejs/inertia`
+
+Inertia.js 3 bindings for Octane.
+
+The package reuses `@inertiajs/core` unchanged and ports the renderer-specific
+`@inertiajs/react` adapter to Octane. It does not install or emulate React.
+
+The initial port is pinned to `@inertiajs/react@3.6.1` and the Inertia 3.x
+source tree at commit `68b13b662d7a6ecdd504026ee18733192b0c7d73`.
+The exact React adapter source is retained in `upstream/` so each ported module
+and future version update can be reviewed against its immutable baseline.
+
+## Upstream ledger
+
+| Contract | Upstream source | Octane entry |
+| --- | --- | --- |
+| Router singleton | `packages/react/src/index.ts` | `src/index.ts` |
+| HTTP singleton | `packages/react/src/index.ts` | `src/index.ts` |
+| Progress singleton | `packages/react/src/index.ts` | `src/index.ts` |
+| Server helper | `packages/react/src/server.ts` | `src/server.ts` |
+
+These exports preserve object identity with `@inertiajs/core@3.6.1`.
+Renderer-owned exports from `packages/react/src/index.ts` are intentionally
+absent from this foundation unit and are added with their corresponding
+behavioral tests. React, ReactDOM, StrictMode, `forwardRef`, and synthetic event
+types are explicit exclusions from the Octane package.
+
+## Status
+
+The framework-neutral exports, package boundary, contexts, layout-property
+store, and renderer-independent hook/form layer are present. Components, root
+lifecycle, full SSR/hydration, and the protocol playground are implemented by
+the dependent units in the binding plan.

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@octanejs/inertia",
+  "octane": {
+    "hookSlots": {
+      "manual": [
+        "src"
+      ]
+    }
+  },
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.22.2"
+  },
+  "description": "Inertia.js bindings for the octane renderer — reuses @inertiajs/core and ports the React adapter onto octane.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/inertia"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./server": "./src/server.ts",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@inertiajs/core": "3.6.1",
+    "es-toolkit": "^1.49.0",
+    "laravel-precognition": "^2.0.0"
+  },
+  "peerDependencies": {
+    "octane": "0.1.32"
+  },
+  "devDependencies": {
+    "@inertiajs/react": "3.6.1",
+    "@tsrx/react": "^0.2.56",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "vitest": "^4.1.10",
+    "@octanejs/testing-library": "0.1.29",
+    "octane": "0.1.32"
+  },
+  "scripts": {
+    "test": "vitest run --root ../.. --project inertia"
+  }
+}

package/src/HeadContext.ts

@@ -0,0 +1,5 @@
+import { HeadManager } from '@inertiajs/core';
+import { createContext } from 'octane';
+
+const headContext = createContext<HeadManager | null>(null);
+export default headContext;

package/src/PageContext.ts

@@ -0,0 +1,5 @@
+import { Page } from '@inertiajs/core';
+import { createContext } from 'octane';
+
+const pageContext = createContext<Page | null>(null);
+export default pageContext;

package/src/index.ts

@@ -0,0 +1,26 @@
+// @octanejs/inertia
+//
+// The Inertia router, HTTP client, and progress APIs are framework-neutral.
+// Keep their upstream identities intact while the renderer-specific adapter is
+// implemented in this package.
+import { config as coreConfig } from '@inertiajs/core';
+
+export { http, progress, router } from '@inertiajs/core';
+export { resetLayoutProps, setLayoutProps } from './layoutProps';
+export { default as usePage } from './usePage';
+export { default as usePoll } from './usePoll';
+export { default as usePrefetch } from './usePrefetch';
+export { default as useRemember } from './useRemember';
+export {
+	type InertiaForm,
+	type InertiaFormProps,
+	type InertiaPrecognitiveFormProps,
+	type SetDataAction,
+	type SetDataByKeyValuePair,
+	type SetDataByMethod,
+	type SetDataByObject,
+	default as useForm,
+} from './useForm';
+export { default as useHttp } from './useHttp';
+
+export const config = coreConfig;

package/src/layoutProps.ts

@@ -0,0 +1,25 @@
+import { createLayoutPropsStore, type LayoutProps, type NamedLayoutProps } from '@inertiajs/core';
+
+export const store = createLayoutPropsStore();
+
+export function setLayoutProps(props: Partial<LayoutProps>): void;
+export function setLayoutProps<K extends keyof NamedLayoutProps>(
+	name: K,
+	props: Partial<NamedLayoutProps[K]>,
+): void;
+export function setLayoutProps<T = never>(props: Partial<NoInfer<T>>): void;
+export function setLayoutProps<T = never>(name: string, props: Partial<NoInfer<T>>): void;
+export function setLayoutProps(
+	nameOrProps: string | Record<string, unknown>,
+	props?: Record<string, unknown>,
+): void {
+	if (typeof nameOrProps === 'string') {
+		store.setFor(nameOrProps, props!);
+	} else {
+		store.set(nameOrProps);
+	}
+}
+
+export function resetLayoutProps(): void {
+	store.reset();
+}

package/src/server.ts

@@ -0,0 +1 @@
+export { default } from '@inertiajs/core/server';

package/src/useForm.ts

@@ -0,0 +1,318 @@
+import {
+	CancelToken,
+	ErrorValue,
+	FormDataErrors,
+	FormDataKeys,
+	FormDataType,
+	FormDataValues,
+	Method,
+	OptimisticCallback,
+	Progress,
+	RequestPayload,
+	router,
+	UrlMethodPair,
+	UseFormArguments,
+	UseFormSubmitArguments,
+	UseFormSubmitOptions,
+	UseFormTransformCallback,
+	UseFormUtils,
+	UseFormWithPrecognitionArguments,
+	VisitOptions,
+} from '@inertiajs/core';
+import { cloneDeep } from 'es-toolkit';
+import type {
+	NamedInputEvent,
+	PrecognitionPath,
+	ValidationConfig,
+	Validator,
+} from 'laravel-precognition';
+import { useCallback, useMemo, useRef } from 'octane';
+import useFormState, {
+	SetDataAction,
+	SetDataByKeyValuePair,
+	SetDataByMethod,
+	SetDataByObject,
+} from './useFormState';
+import useRemember from './useRemember';
+
+const slots = Object.fromEntries(
+	['cancelToken', 'excludeKeys', 'pendingOptimistic', 'submit', 'cancel', 'submitMethods'].map(
+		(name) => [name, Symbol(`Inertia.useForm.${name}`)],
+	),
+) as Record<string, symbol>;
+
+// Re-export types that were moved to useFormState
+export { SetDataAction, SetDataByKeyValuePair, SetDataByMethod, SetDataByObject };
+
+type PrecognitionValidationConfig<TKeys> = ValidationConfig & {
+	only?: TKeys[] | Iterable<TKeys> | ArrayLike<TKeys>;
+};
+
+export interface InertiaFormProps<TForm extends Record<string, any>> {
+	data: TForm;
+	isDirty: boolean;
+	errors: FormDataErrors<TForm>;
+	hasErrors: boolean;
+	processing: boolean;
+	progress: Progress | null;
+	wasSuccessful: boolean;
+	recentlySuccessful: boolean;
+	setData: SetDataAction<TForm>;
+	transform: (callback: UseFormTransformCallback<TForm>) => void;
+	setDefaults: {
+		(): void;
+		<T extends FormDataKeys<TForm>>(field: T, value: FormDataValues<TForm, T>): void;
+		(fields: Partial<TForm>): void;
+	};
+	reset: <K extends FormDataKeys<TForm>>(...fields: K[]) => void;
+	clearErrors: <K extends FormDataKeys<TForm>>(...fields: K[]) => void;
+	resetAndClearErrors: <K extends FormDataKeys<TForm>>(...fields: K[]) => void;
+	setError: {
+		<K extends FormDataKeys<TForm>>(field: K, value: ErrorValue): void;
+		(errors: FormDataErrors<TForm>): void;
+	};
+	submit: (...args: UseFormSubmitArguments) => void;
+	get: (url: string, options?: UseFormSubmitOptions) => void;
+	post: (url: string, options?: UseFormSubmitOptions) => void;
+	put: (url: string, options?: UseFormSubmitOptions) => void;
+	patch: (url: string, options?: UseFormSubmitOptions) => void;
+	delete: (url: string, options?: UseFormSubmitOptions) => void;
+	cancel: () => void;
+	dontRemember: <K extends FormDataKeys<TForm>>(...fields: K[]) => InertiaFormProps<TForm>;
+	optimistic: <TProps>(callback: OptimisticCallback<TProps>) => InertiaFormProps<TForm>;
+	withPrecognition: (
+		...args: UseFormWithPrecognitionArguments
+	) => InertiaPrecognitiveFormProps<TForm>;
+}
+
+export interface InertiaFormValidationProps<TForm extends Record<string, any>> {
+	invalid: <K extends FormDataKeys<TForm>>(field: K) => boolean;
+	setValidationTimeout: (duration: number) => InertiaPrecognitiveFormProps<TForm>;
+	touch: <K extends FormDataKeys<TForm>>(
+		field: K | NamedInputEvent | Array<K>,
+		...fields: K[]
+	) => InertiaPrecognitiveFormProps<TForm>;
+	touched: <K extends FormDataKeys<TForm>>(field?: K) => boolean;
+	valid: <K extends FormDataKeys<TForm>>(field: K) => boolean;
+	validate: <K extends FormDataKeys<TForm> | PrecognitionPath<TForm>>(
+		field?: K | NamedInputEvent | PrecognitionValidationConfig<K>,
+		config?: PrecognitionValidationConfig<K>,
+	) => InertiaPrecognitiveFormProps<TForm>;
+	validateFiles: () => InertiaPrecognitiveFormProps<TForm>;
+	validating: boolean;
+	validator: () => Validator;
+	withAllErrors: () => InertiaPrecognitiveFormProps<TForm>;
+	withoutFileValidation: () => InertiaPrecognitiveFormProps<TForm>;
+	// Backward compatibility for easy migration from the original Precognition libraries
+	setErrors: (errors: FormDataErrors<TForm>) => InertiaPrecognitiveFormProps<TForm>;
+	forgetError: <K extends FormDataKeys<TForm> | NamedInputEvent>(
+		field: K,
+	) => InertiaPrecognitiveFormProps<TForm>;
+}
+
+export type InertiaForm<TForm extends Record<string, any>> = InertiaFormProps<TForm>;
+export type InertiaPrecognitiveFormProps<TForm extends Record<string, any>> =
+	InertiaFormProps<TForm> & InertiaFormValidationProps<TForm>;
+
+export default function useForm<TForm extends FormDataType<TForm>>(
+	method: Method | (() => Method),
+	url: string | (() => string),
+	data: TForm | (() => TForm),
+): InertiaPrecognitiveFormProps<TForm>;
+export default function useForm<TForm extends FormDataType<TForm>>(
+	urlMethodPair: UrlMethodPair | (() => UrlMethodPair),
+	data: TForm | (() => TForm),
+): InertiaPrecognitiveFormProps<TForm>;
+export default function useForm<TForm extends FormDataType<TForm>>(
+	rememberKey: string,
+	data: TForm | (() => TForm),
+): InertiaFormProps<TForm>;
+export default function useForm<TForm extends FormDataType<TForm>>(
+	data: TForm | (() => TForm),
+): InertiaFormProps<TForm>;
+export default function useForm<TForm extends FormDataType<TForm>>(): InertiaFormProps<TForm>;
+export default function useForm<TForm extends FormDataType<TForm>>(
+	...args: UseFormArguments<TForm>
+): InertiaFormProps<TForm> | InertiaPrecognitiveFormProps<TForm> {
+	const publicArgs =
+		typeof args[args.length - 1] === 'symbol'
+			? (args.slice(0, -1) as UseFormArguments<TForm>)
+			: args;
+	const { rememberKey, data, precognitionEndpoint } = UseFormUtils.parseUseFormArguments<TForm>(
+		...publicArgs,
+	);
+
+	// Resolve initial data for remember functionality hooks
+	const initialDefaults = typeof data === 'function' ? cloneDeep(data()) : cloneDeep(data);
+
+	const cancelToken = useRef<CancelToken | null>(null, slots.cancelToken);
+	const excludeKeysRef = useRef<FormDataKeys<TForm>[]>([], slots.excludeKeys);
+	const pendingOptimisticRef = useRef<OptimisticCallback | null>(null, slots.pendingOptimistic);
+
+	// For remember functionality, we need custom state hooks
+	const useDataState = rememberKey
+		? () => useRemember<TForm>(initialDefaults, `${rememberKey}:data`, excludeKeysRef)
+		: undefined;
+
+	const useErrorsState = rememberKey
+		? () => useRemember<FormDataErrors<TForm>>({} as FormDataErrors<TForm>, `${rememberKey}:errors`)
+		: undefined;
+
+	const {
+		form: baseForm,
+		setDefaultsState,
+		transformRef,
+		precognitionEndpointRef,
+		dataRef,
+		isMounted,
+		setProcessing,
+		setProgress,
+		markAsSuccessful,
+		clearErrors,
+		setError,
+		defaultsCalledInOnSuccessRef,
+		resetBeforeSubmit,
+		finishProcessing,
+	} = useFormState<TForm>({
+		data,
+		precognitionEndpoint,
+		useDataState,
+		useErrorsState,
+	});
+
+	const submit = useCallback(
+		(...args: UseFormSubmitArguments) => {
+			const { method, url, options } = UseFormUtils.parseSubmitArguments(
+				args,
+				precognitionEndpointRef.current,
+			);
+
+			defaultsCalledInOnSuccessRef.current = false;
+
+			const _options: VisitOptions = {
+				...options,
+				onCancelToken: (token) => {
+					cancelToken.current = token;
+
+					return options.onCancelToken?.(token);
+				},
+				onBefore: (visit) => {
+					resetBeforeSubmit();
+
+					return options.onBefore?.(visit);
+				},
+				onStart: (visit) => {
+					setProcessing(true);
+
+					return options.onStart?.(visit);
+				},
+				onProgress: (event) => {
+					setProgress(event || null);
+
+					return options.onProgress?.(event);
+				},
+				onSuccess: async (page) => {
+					if (isMounted.current) {
+						markAsSuccessful();
+					}
+
+					const onSuccess = options.onSuccess ? await options.onSuccess(page) : null;
+
+					if (isMounted.current && !defaultsCalledInOnSuccessRef.current) {
+						baseForm.setData((data: TForm) => {
+							setDefaultsState(cloneDeep(data));
+							return data;
+						});
+					}
+
+					return onSuccess;
+				},
+				onError: (errors) => {
+					if (isMounted.current) {
+						clearErrors();
+						setError(errors as FormDataErrors<TForm>);
+					}
+
+					return options.onError?.(errors);
+				},
+				onCancel: () => {
+					return options.onCancel?.();
+				},
+				onFinish: (visit) => {
+					if (isMounted.current) {
+						finishProcessing();
+					}
+
+					cancelToken.current = null;
+
+					return options.onFinish?.(visit);
+				},
+			};
+
+			_options.optimistic = _options.optimistic ?? pendingOptimisticRef.current ?? undefined;
+			pendingOptimisticRef.current = null;
+
+			const transformedData = transformRef.current(dataRef.current) as RequestPayload;
+
+			if (method === 'delete') {
+				router.delete(url, { ..._options, data: transformedData });
+			} else {
+				router[method](url, transformedData, _options);
+			}
+		},
+		[clearErrors, setError, transformRef],
+		slots.submit,
+	);
+
+	const cancel = useCallback(
+		() => {
+			if (cancelToken.current) {
+				cancelToken.current.cancel();
+			}
+		},
+		[],
+		slots.cancel,
+	);
+
+	const submitMethods = useMemo(
+		() => ({
+			get: (url: string, options: VisitOptions = {}) => submit('get', url, options),
+			post: (url: string, options: VisitOptions = {}) => submit('post', url, options),
+			put: (url: string, options: VisitOptions = {}) => submit('put', url, options),
+			patch: (url: string, options: VisitOptions = {}) => submit('patch', url, options),
+			delete: (url: string, options: VisitOptions = {}) => submit('delete', url, options),
+		}),
+		[submit],
+		slots.submitMethods,
+	);
+
+	// Add useForm-specific methods to the form object
+	Object.assign(baseForm, {
+		submit,
+		...submitMethods,
+		cancel,
+		dontRemember: <K extends FormDataKeys<TForm>>(...keys: K[]) => {
+			excludeKeysRef.current = keys;
+			return form;
+		},
+
+		optimistic: <TProps>(callback: OptimisticCallback<TProps>) => {
+			pendingOptimisticRef.current = callback as OptimisticCallback;
+			return form;
+		},
+	});
+
+	// Cast to the full form type (baseForm now has submit methods)
+	const form = baseForm as unknown as InertiaFormProps<TForm>;
+
+	// Wrap withPrecognition to return the correct type with submit methods
+	const originalWithPrecognition = baseForm.withPrecognition;
+	form.withPrecognition = (
+		...args: UseFormWithPrecognitionArguments
+	): InertiaPrecognitiveFormProps<TForm> => {
+		originalWithPrecognition(...args);
+		return form as InertiaPrecognitiveFormProps<TForm>;
+	};
+
+	return precognitionEndpointRef.current ? (form as InertiaPrecognitiveFormProps<TForm>) : form;
+}