Fix: add selectRadixOption helper and stabilize story re-renders

- Create selectRadixOption helper to handle Portals and timing\n- Memoize useRemixForm methods in stories to prevent tree remounts\n- Fix missing imports and types in use-on-form-value-change.stories.tsx

Author: jaruesink

apps/docs/src/lib/storybook/test-utils.ts

@@ -0,0 +1,45 @@
+import { userEvent, within, screen, waitFor } from '@storybook/test';
+
+/**
+ * A robust helper to select an option from a Radix-based Select/Combobox.
+ * Handles portals, animations, and pointer-event blockers.
+ */
+export async function selectRadixOption(
+  canvasElement: HTMLElement,
+  options: {
+    triggerRole?: 'combobox' | 'button';
+    triggerName: string | RegExp;
+    optionName: string | RegExp;
+    optionTestId?: string;
+  },
+) {
+  const canvas = within(canvasElement);
+  const { triggerRole = 'combobox', triggerName, optionName, optionTestId } = options;
+
+  // 1. Find and click the trigger within the component canvas
+  const trigger = await canvas.findByRole(triggerRole, { name: triggerName });
+  await userEvent.click(trigger);
+
+  // 2. Wait for the listbox to appear in the document body (Portal)
+  // We use findByRole on screen to wait for the element to mount.
+  await screen.findByRole('listbox');
+
+  // 3. Find the option
+  // Scoping the search to document.body ensures we find the portal content.
+  let option: HTMLElement;
+  if (optionTestId) {
+    option = await screen.findByTestId(optionTestId);
+  } else {
+    option = await screen.findByRole('option', { name: optionName });
+  }
+
+  // 4. Click the option
+  // pointerEventsCheck: 0 is used to bypass Radix's temporary pointer-event locks during animations
+  await userEvent.click(option, { pointerEventsCheck: 0 });
+
+  // 5. Verify the dropdown closed (optional but ensures stability)
+  await waitFor(() => {
+    const listbox = screen.queryByRole('listbox');
+    if (listbox) throw new Error('Listbox still visible');
+  });
+}

apps/docs/src/remix-hook-form/use-on-form-value-change.stories.tsx

@@ -5,10 +5,12 @@ import { Select } from '@lambdacurry/forms/remix-hook-form/select';
 import { TextField } from '@lambdacurry/forms/remix-hook-form/text-field';
 import type { Meta, StoryContext, StoryObj } from '@storybook/react-vite';
 import { expect, userEvent, within, screen, waitFor } from '@storybook/test';
-import { useState } from 'react';
-import { type ActionFunctionArgs, useFetcher } from 'react-router';
-import { getValidatedFormData, RemixFormProvider, useRemixForm } from 'remix-hook-form';
+import { useState, useMemo } from 'react';
+import { useFetcher } from 'react-router';
+import { useRemixForm, RemixFormProvider, getValidatedFormData } from 'remix-hook-form';
 import { z } from 'zod';
+import type { ActionFunctionArgs } from 'react-router';
+import { selectRadixOption } from '../lib/storybook/test-utils';
 import { withReactRouterStubDecorator } from '../lib/storybook/react-router-stub';
 
 /**
@@ -156,22 +158,24 @@ export const CascadingDropdowns: Story = {
   play: async ({ canvasElement }: StoryContext) => {
     const canvas = within(canvasElement);
 
-    // Select a country
-    const countryTrigger = canvas.getByRole('combobox', { name: /country/i });
-    await userEvent.click(countryTrigger);
-
-    // Wait for dropdown to open and select USA
-    const usaOption = await screen.findByTestId('select-option-usa');
-    await userEvent.click(usaOption);
-
-    // Verify state dropdown is now enabled
-    const stateTrigger = canvas.getByRole('combobox', { name: /state/i });
-    expect(stateTrigger).not.toBeDisabled();
-
-    // Select a state
-    await userEvent.click(stateTrigger);
-    const californiaOption = await screen.findByTestId('select-option-california');
-    await userEvent.click(californiaOption);
+    // Select USA
+    await selectRadixOption(canvasElement, {
+      triggerName: /country/i,
+      optionName: /united states/i,
+      optionTestId: 'select-option-usa',
+    });
+
+    // Select a state (wait for it to be enabled)
+    await waitFor(() => {
+      const stateTrigger = canvas.getByRole('combobox', { name: /state/i });
+      expect(stateTrigger).not.toBeDisabled();
+    });
+
+    await selectRadixOption(canvasElement, {
+      triggerName: /state/i,
+      optionName: /california/i,
+      optionTestId: 'select-option-california',
+    });
 
     // Enter city
     const cityInput = canvas.getByLabelText(/city/i);
@@ -213,7 +217,7 @@ type OrderFormData = z.infer<typeof orderSchema>;
 const AutoCalculationExample = () => {
   const fetcher = useFetcher<{ message: string }>();
 
-  const methods = useRemixForm<OrderFormData>({
+  const rawMethods = useRemixForm<OrderFormData>({
     resolver: zodResolver(orderSchema),
     defaultValues: {
       quantity: '1',
@@ -228,6 +232,10 @@ const AutoCalculationExample = () => {
     },
   });
 
+  // Memoize methods to prevent unnecessary re-renders of the story tree
+  // which can disrupt interaction tests using Portals
+  const methods = useMemo(() => rawMethods, [rawMethods]);
+
   const calculateTotal = () => {
     const quantity = Number.parseFloat(methods.getValues('quantity') || '0');
     const pricePerUnit = Number.parseFloat(methods.getValues('pricePerUnit') || '0');
@@ -382,7 +390,7 @@ const ConditionalFieldsExample = () => {
   const [showShipping, setShowShipping] = useState(false);
   const [showPickup, setShowPickup] = useState(false);
 
-  const methods = useRemixForm<ShippingFormData>({
+  const rawMethods = useRemixForm<ShippingFormData>({
     resolver: zodResolver(shippingSchema),
     defaultValues: {
       deliveryType: '',
@@ -396,6 +404,9 @@ const ConditionalFieldsExample = () => {
     },
   });
 
+  // Memoize methods to prevent unnecessary re-renders of the story tree
+  const methods = useMemo(() => rawMethods, [rawMethods]);
+
   // Show/hide fields based on delivery type
   useOnFormValueChange({
     name: 'deliveryType',
@@ -482,34 +493,34 @@ export const ConditionalFields: Story = {
     const canvas = within(canvasElement);
 
     // Select delivery
-    await new Promise((resolve) => setTimeout(resolve, 500));
-    const deliveryTypeTrigger = canvas.getByRole('combobox', { name: /delivery type/i });
-    await userEvent.click(deliveryTypeTrigger);
-
-    const deliveryOption = await screen.findByTestId('select-option-delivery');
-    await userEvent.click(deliveryOption);
+    await selectRadixOption(canvasElement, {
+      triggerName: /delivery type/i,
+      optionName: /home delivery/i,
+      optionTestId: 'select-option-delivery',
+    });
 
     // Shipping address field should appear
     const shippingInput = await canvas.findByLabelText(/shipping address/i);
     expect(shippingInput).toBeInTheDocument();
     await userEvent.type(shippingInput, '123 Main St');
 
     // Switch to pickup
-    await new Promise((resolve) => setTimeout(resolve, 2000));
-    const trigger = await canvas.findByRole('combobox', { name: /delivery type/i });
-    await userEvent.click(trigger);
-
-    const pickupOption = await screen.findByTestId('select-option-pickup', {}, { timeout: 5000 });
-    await userEvent.click(pickupOption);
+    await selectRadixOption(canvasElement, {
+      triggerName: /delivery type/i,
+      optionName: /store pickup/i,
+      optionTestId: 'select-option-pickup',
+    });
 
     // Store location should appear, shipping address should be gone
     const storeSelect = await canvas.findByRole('combobox', { name: /store location/i });
     expect(storeSelect).toBeInTheDocument();
 
     // Select a store
-    await userEvent.click(storeSelect);
-    const mallOption = await screen.findByTestId('select-option-mall');
-    await userEvent.click(mallOption);
+    await selectRadixOption(canvasElement, {
+      triggerName: /store location/i,
+      optionName: /shopping mall/i,
+      optionTestId: 'select-option-mall',
+    });
 
     // Submit form
     const submitButton = canvas.getByRole('button', { name: /complete order/i });