fix: ensure stepped forms SSR hydration matches client closes #231

Author: logaretm

.changeset/slimy-wings-think.md

@@ -0,0 +1,5 @@
+---
+'@formwerk/core': patch
+---
+
+fix: Ensure stepped forms SSR hydration matches client closes #231

packages/core/src/useFormFlow/useFormFlow.ts

@@ -36,7 +36,7 @@ export function useFormFlow<TInput extends FormObject = FormObject>(_props?: For
   const segmentValuesMap = ref(new Map<string, StepState<TInput>>()) as Ref<Map<string, StepState<TInput>>>;
   const form = useForm(_props);
   const segments = ref<SegmentMetadata[]>([]);
-
+  const isSegmentsStable = ref(false);
   const rawCurrentSegment = computed(() => segments.value.find(segment => segment.id === currentSegmentId.value));
 
   const [dispatchActiveSegmentChange, onActiveSegmentChange] = createEventDispatcher<{
@@ -78,20 +78,30 @@ export function useFormFlow<TInput extends FormObject = FormObject>(_props?: For
   provide(FormFlowContextKey, {
     isSegmentActive: (segmentId: string) => rawCurrentSegment.value?.id === segmentId,
     registerSegment: (metadata: SegmentRegistrationMetadata) => {
+      const isFirstSegment = segments.value.length === 0;
+
       segments.value.push({
         id: metadata.id,
         name: () => toValue(metadata.name),
         // The first segment is always visited.
-        visited: segments.value.length === 0,
+        visited: isFirstSegment,
         submitted: false,
         getValue: () => segmentValuesMap.value.get(metadata.id)?.values,
       });
 
-      // Activate the first segment if there is only one by default
-      // Fixes SSR #231
-      if (segments.value.length === 1) {
+      // Activate the first segment immediately to ensure SSR/client consistency
+      // Fixes SSR hydration mismatch with isActive state
+      if (isFirstSegment) {
         currentSegmentId.value = metadata.id;
       }
+
+      // Mark segments as stable after a microtask to ensure all synchronous registrations complete
+      // This helps distinguish between "only 1 segment registered so far" vs "only 1 segment total"
+      if (!isSegmentsStable.value) {
+        nextTick(() => {
+          isSegmentsStable.value = true;
+        });
+      }
     },
   });
 
@@ -113,7 +123,24 @@ export function useFormFlow<TInput extends FormObject = FormObject>(_props?: For
     return getRenderedSegments().findIndex(segment => segment.id === current.id);
   });
 
-  const isLastSegment = computed(() => currentSegmentIndex.value === segments.value.length - 1);
+  const isLastSegment = computed(() => {
+    const current = currentSegment.value;
+    if (!current) {
+      return false;
+    }
+
+    const index = currentSegmentIndex.value;
+    const total = segments.value.length;
+
+    // If we're on the first segment and only one segment has registered so far,
+    // only return true if segments are stable (all registered).
+    // This prevents SSR hydration mismatch when segments register incrementally on client.
+    if (index === 0 && total === 1 && !isSegmentsStable.value) {
+      return false;
+    }
+
+    return index === total - 1;
+  });
 
   function resolveRelative(delta: number): SegmentMetadata | null {
     const domSegments = Array.from(

packages/core/src/useFormFlow/useStepFormFlow.spec.ts

@@ -1,4 +1,4 @@
-import { defineComponent } from 'vue';
+import { defineComponent, watch } from 'vue';
 import { fireEvent, render, screen } from '@testing-library/vue';
 import { axe } from 'vitest-axe';
 import { StepResolveContext, useStepFormFlow } from '.';
@@ -1433,3 +1433,141 @@ describe('warnings', () => {
     );
   });
 });
+
+describe('single-step forms', () => {
+  test('should correctly identify isLastStep as true for single-step form', async () => {
+    await render({
+      components: {
+        SteppedFormFlow,
+        FormFlowSegment,
+        TextField,
+      },
+      template: `
+        <SteppedFormFlow>
+          <FormFlowSegment name="only-step">
+            <span>Only Step</span>
+            <TextField label="Name" name="name" />
+          </FormFlowSegment>
+        </SteppedFormFlow>
+      `,
+    });
+
+    await flush();
+
+    // With only one step, the next button should say "Submit" not "Next"
+    expect(screen.getByTestId('next-button')).toHaveTextContent('Submit');
+  });
+
+  test('should trigger onDone when submitting single-step form', async () => {
+    const onDone = vi.fn();
+
+    await render({
+      setup() {
+        return { onDone };
+      },
+      components: {
+        SteppedFormFlow,
+        FormFlowSegment,
+        TextField,
+      },
+      template: `
+        <SteppedFormFlow @done="onDone">
+          <FormFlowSegment name="only-step">
+            <TextField label="Name" name="name" />
+          </FormFlowSegment>
+        </SteppedFormFlow>
+      `,
+    });
+
+    await flush();
+
+    // Fill in the field
+    await fireEvent.update(screen.getByLabelText('Name'), 'John Doe');
+    await flush();
+
+    // Click next/submit button
+    await fireEvent.click(screen.getByTestId('next-button'));
+    await flush();
+
+    // Should have triggered onDone, not moved to another step
+    expect(onDone).toHaveBeenCalledWith({
+      name: 'John Doe',
+    });
+  });
+
+  test('should not change button text while segments are registering', async () => {
+    // This test verifies the segmentsStable flag works correctly
+    // by checking that isLastStep doesn't prematurely return true during registration
+    let buttonTexts: string[] = [];
+
+    await render({
+      setup() {
+        const { isLastStep } = useStepFormFlow();
+
+        // Track button text as it changes
+        watch(
+          () => isLastStep.value,
+          val => {
+            buttonTexts.push(val ? 'Submit' : 'Next');
+          },
+          { immediate: true },
+        );
+
+        return { isLastStep };
+      },
+      components: {
+        FormFlowSegment,
+        TextField,
+      },
+      template: `
+        <div>
+          <FormFlowSegment name="step1">
+            <TextField label="Name" name="name" />
+          </FormFlowSegment>
+          <FormFlowSegment name="step2">
+            <TextField label="Email" name="email" />
+          </FormFlowSegment>
+          <FormFlowSegment name="step3">
+            <TextField label="Phone" name="phone" />
+          </FormFlowSegment>
+          <button>{{ isLastStep ? 'Submit' : 'Next' }}</button>
+        </div>
+      `,
+    });
+
+    await flush();
+
+    // The button should start as "Next" and not flicker to "Submit" during registration
+    // First value should be "Next" (not "Submit")
+    expect(buttonTexts[0]).toBe('Next');
+
+    // After all segments register and stabilize, should still be "Next" (we're on step 1 of 3)
+    expect(screen.getByRole('button')).toHaveTextContent('Next');
+  });
+
+  test('single-step form isLastStep should become true after segments stabilize', async () => {
+    await render({
+      components: {
+        SteppedFormFlow,
+        FormFlowSegment,
+        TextField,
+      },
+      template: `
+        <SteppedFormFlow>
+          <FormFlowSegment name="only-step">
+            <TextField label="Name" name="name" />
+          </FormFlowSegment>
+        </SteppedFormFlow>
+      `,
+    });
+
+    await flush();
+
+    // Wait an extra tick for the microtask (segmentsStable) to resolve
+    await new Promise(resolve => Promise.resolve().then(resolve));
+    await flush();
+
+    // After segments stabilize, single-step form should show "Submit"
+    expect(screen.getByTestId('next-button')).toHaveTextContent('Submit');
+  });
+});