Handling Svelte Form Hydration Mismatches

<script lang="ts">
  import { onMount, tick } from 'svelte';
  import { writable, derived, type Readable } from 'svelte/store';
  import { beforeNavigate } from '$app/navigation';

  // ── Types ──────────────────────────────────────────────────────────────────
  interface FormData {
    email: string;
    username: string;
    [key: string]: string;
  }

  type FieldErrors = Record<string, string>;

  // ── Props ──────────────────────────────────────────────────────────────────
  export let form: Partial<FormData> = {};

  // ── Stores ─────────────────────────────────────────────────────────────────
  // Wrap the server-supplied prop in a store so derived() can subscribe to it.
  // A plain prop cannot be used inside derived() — stores are required.
  const formStore = writable<Partial<FormData>>(form);
  $: formStore.set(form); // mirror future server-action updates reactively

  // The hydration gate. Stays false until Svelte finishes reconciling the DOM.
  // NEVER set this true synchronously — doing so re-introduces the mismatch.
  const isHydrated = writable(false);

  const validationErrors = writable<FieldErrors>({});

  // Derived validity bypasses all schema checks while the gate is closed.
  // This is what prevents aria-invalid from being set during the danger zone.
  const isValid: Readable<boolean> = derived(
    [formStore, validationErrors, isHydrated],
    ([$form, $errors, $hydrated]) => {
      if (!$hydrated) return true; // treat as valid during hydration — no attribute mutations
      return Object.keys($errors).length === 0;
    }
  );

  // ── Lifecycle ───────────────────────────────────────────────────────────────
  onMount(async () => {
    // tick() yields to the microtask queue, giving Svelte one full pass to
    // reconcile server HTML with the initial client vdom. Only after that
    // completes is it safe to mutate DOM-visible reactive state.
    await tick();
    isHydrated.set(true);

    // Return cleanup: runs on component destroy (navigation away or unmount).
    return () => {
      isHydrated.set(false);       // reset so the gate closes if component remounts
      validationErrors.set({});    // clear stale errors — they don't belong to the next route
    };
  });

  // Reset the gate on SvelteKit client-side navigation to prevent stale state
  // from a previous route leaking into the next one during the transition.
  beforeNavigate(() => {
    isHydrated.set(false);
    validationErrors.set({});
  });

  // ── Validation ──────────────────────────────────────────────────────────────
  // AbortController is used here to cancel any async uniqueness checks if the
  // user types again before the previous request resolves. Without this, a
  // slow response can overwrite a newer, correct validation result.
  let abortController: AbortController | null = null;

  async function validateField(name: string, value: string): Promise<void> {
    // Hard guard: never run validation during the hydration window.
    // $isHydrated reads the current store value synchronously via the $ prefix.
    if (!$isHydrated) return;

    // Cancel any in-flight async validation for this field before starting a new one.
    abortController?.abort();
    abortController = new AbortController(); // each call gets a fresh token
    const signal = abortController.signal;   // pass signal into fetch() to cancel

    try {
      const result = runSchemaValidation($formStore);

      // If the signal aborted while runSchemaValidation was executing, discard the result.
      if (signal.aborted) return;

      validationErrors.update(errors => ({
        ...errors,
        [name]: result[name] ?? '',
      }));
    } catch (err) {
      // AbortError is expected and benign — swallow it silently.
      if (err instanceof Error && err.name !== 'AbortError') {
        console.error('[form] validation error:', err);
      }
    }
  }

  function handleInput(event: Event): void {
    const target = event.target as HTMLInputElement;
    const { name, value } = target;
    formStore.update(f => ({ ...f, [name]: value }));
    void validateField(name, value);
  }

  function handleSubmit(event: SubmitEvent): void {
    event.preventDefault();
    // Full-form validation and submission logic goes here.
  }

  // Stub — replace with your actual schema library (Zod, Valibot, etc.)
  function runSchemaValidation(data: Partial<FormData>): FieldErrors {
    const errors: FieldErrors = {};
    if (!data.email?.includes('@')) errors.email = 'Enter a valid email address.';
    if (!data.username || data.username.length < 3) errors.username = 'Username must be at least 3 characters.';
    return errors;
  }
</script>

<form on:submit={handleSubmit} novalidate>
  <div class="field">
    <label for="email">Email</label>
    <input
      id="email"
      name="email"
      type="email"
      value={$formStore.email ?? ''}
      on:input={handleInput}
      aria-invalid={$validationErrors.email ? 'true' : 'false'}
      aria-describedby={$validationErrors.email ? 'email-error' : undefined}
    />
    {#if $validationErrors.email && $isHydrated}
      <!-- role="alert" triggers screen-reader announcement on insertion -->
      <span id="email-error" role="alert" class="error-text">
        {$validationErrors.email}
      </span>
    {/if}
  </div>

  <div class="field">
    <label for="username">Username</label>
    <input
      id="username"
      name="username"
      type="text"
      value={$formStore.username ?? ''}
      on:input={handleInput}
      aria-invalid={$validationErrors.username ? 'true' : 'false'}
      aria-describedby={$validationErrors.username ? 'username-error' : undefined}
    />
    {#if $validationErrors.username && $isHydrated}
      <span id="username-error" role="alert" class="error-text">
        {$validationErrors.username}
      </span>
    {/if}
  </div>

  <button type="submit">Submit</button>
</form>

<!-- Explicit autocomplete attributes reduce autofill-timing surprises -->
<input name="email" type="email" autocomplete="email" ... />

// WRONG — $isHydrated captured at call time (before gate opens)
const debouncedValidate = debounce((name: string, value: string) => {
  if (!$isHydrated) return; // always false if debounce fires early
}, 300);