Vue 3 Form Provider‑driven Live Validation

[kaspernowak]

Summary

Laravel 12 starter kits have moved from the Inertia useForm helper to the Inertia Form component. Inertia’s Form component does not support Precognition out of the box, making the Laravel 12 Vue starter kits incompatible with Laravel Precognition. This PR adds optional live validation to the Vue 3

, driven by a provider registry. When a provider is registered and precognitive is enabled, the form validates on user events and keeps the error bag in sync. This would bridge the gap between Inertia component usage and Laravel Precognition.

Key Changes

• Form: inertia/packages/vue3/src/form.ts
  • New props: precognitive (boolean|object), validateOn ('input'|'change'|'blur'|array), validationTimeout (ms), provider (string).
  • Wires event listeners (input/change/blur) to trigger validation via composable.
  • Exposes validating and validate(name?).
• Composable: inertia/packages/vue3/src/useValidate.ts
  • Lazy-selects a registered provider, creates a validator, mirrors validating, and normalizes/syncs errors.
  • Honors validateOn, validationTimeout, and precognitive config (global + per-field opt-in via precognitive or data-precognitive attributes).
• Registry: inertia/packages/vue3/src/validationProviders.ts
  • registerLiveValidationProvider(), getLiveValidationProvider(), detectInstalledProviders().

Behavior

• Opt-in: Live validation only runs when precognitive is truthy (boolean or config object). Per-field opt-in supported via precognitive attribute or data-precognitive="true".
• Provider selection:
  • Exactly one provider registered → auto-selected.
  • Multiple providers → set provider="<id>" on the Form.
  • No providers but precognitive enabled → warn and skip live validation (standard form behavior unchanged).
• Errors/state: Provider emits error changes; we normalize to a simple key→message shape and sync form.setError. validating is reactive and exposed.

Usage

• Enable live validation:

<Form
  action="/register"
  method="post"
  :precognitive="{ onValidationError: (e) => console.debug(e) }"
  :validateOn="['input','blur']"
  :validationTimeout="150"
>
  <input name="name" precognitive />
  <input name="email" data-precognitive="true" />
</Form>

• Multiple providers: Set provider="your-provider-id" on <Form>.

Provider Requirement

Live validation requires a provider to be registered at runtime.

• Provider module shape:

  • createValidator(requestFactory, initialData)
  • toSimpleValidationErrors?(errors)
  • resolveName?(event)

• Registry API:

  • registerLiveValidationProvider({ id, import: () => Promise<ModuleShape> })

Laravel Precognition Integration example

• Install provider (pnpm install laravel-precognition-vue-inertia)
• Register provider (Could be implemented in the laravel-precognition-vue-inertia package at a file like /packages/vue-inertia/src/registerInertiaProvider.ts):

import { registerLiveValidationProvider } from '@inertiajs/vue3'

export function registerLaravelPrecognitionProvider(id = 'laravel-precognition') {
  registerLiveValidationProvider({
    id,
    import: () =>
      import('laravel-precognition').then((mod) => ({
        createValidator: mod.createValidator,
        toSimpleValidationErrors: mod.toSimpleValidationErrors,
        resolveName: (e: Event) =>
          (e?.target as HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement | null)?.name,
      })),
  })
}

• Boot-time auto-register (we could make laravel precognition auto register itself by adding this to /packages/vue-inertia/src/index.ts):

import { registerLaravelPrecognitionProvider } from './registerInertiaProvider'

try {
  registerLaravelPrecognitionProvider()
} catch {}

• Side-effect import (Add a side-effect import of laravel-precognition-vue-inertia in the consuming laravel apps app.ts or directly in your form SFC. This will auto-register its Vue components/composables):

import 'laravel-precognition-vue-inertia';

• With this in place, any <Form :precognitive="true"> uses Laravel Precognition for live validation unless provider points elsewhere.

Types

• inertia/packages/vue3/src/types.ts
  • ValidationEvent = 'input' | 'change' | 'blur'
  • LiveValidationProps = { precognitive?, validateOn?, validationTimeout?, provider? }

Backwards Compatibility

• Off by default; only activated when precognitive is truthy.
• No providers registered → warn in dev, proceed without live validation.

Notes

An alternative approach to solving this problem has been proposed in a PR in the Laravel Precognition github repo, which offloads the precognition functionality fully to Laravel Precognition, using a thin wrapper around the inertia component. Either this PR or the one in Laravel Precognition should be chosen, as they would otherwise conflict with each other.

Testing

• Verified input/change/blur flows, validator lifecycle, error synchronization, provider selection and fallback warnings.