Refactor Select component and related stories for improved accessibility and customization. Added support for dynamic aria attributes and enhanced Storybook tests to verify selection updates. Cleaned up unused region selection code and utilized clsx for class management in custom components.

Author: jaruesink

apps/docs/src/remix-hook-form/select-custom.stories.tsx

@@ -3,28 +3,20 @@ import { Select } from '@lambdacurry/forms/remix-hook-form/select';
 import { Button } from '@lambdacurry/forms/ui/button';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { expect, userEvent, within } from '@storybook/test';
+import clsx from 'clsx';
 import * as React from 'react';
 import { type ActionFunctionArgs, useFetcher } from 'react-router';
 import { RemixFormProvider, getValidatedFormData, useRemixForm } from 'remix-hook-form';
 import { z } from 'zod';
 import { withReactRouterStubDecorator } from '../lib/storybook/react-router-stub';
 
 const formSchema = z.object({
-  region: z.string().min(1, 'Please select a region'),
   theme: z.string().min(1, 'Please select a theme'),
   fruit: z.string().min(1, 'Please select a fruit'),
 });
 
 type FormData = z.infer<typeof formSchema>;
 
-const regionOptions = [
-  { label: 'California', value: 'CA' },
-  { label: 'Ontario', value: 'ON' },
-  { label: 'New York', value: 'NY' },
-  { label: 'Quebec', value: 'QC' },
-  { label: 'Texas', value: 'TX' },
-];
-
 const themeOptions = [
   { label: 'Default', value: 'default' },
   { label: 'Purple', value: 'purple' },
@@ -45,10 +37,10 @@ const PurpleTrigger = React.forwardRef<HTMLButtonElement, React.ButtonHTMLAttrib
       ref={ref}
       type="button"
       {...props}
-      className={
-        'flex items-center justify-between w-full rounded-md border-2 border-purple-300 bg-purple-50 px-3 py-2 h-10 text-sm text-purple-900 focus:outline-none focus:ring-2 focus:ring-purple-500 focus:ring-offset-2 ' +
-        (props.className || '')
-      }
+      className={clsx(
+        'flex items-center justify-between w-full rounded-md border-2 border-purple-300 bg-purple-50 px-3 py-2 h-10 text-sm text-purple-900 focus:outline-none focus:ring-2 focus:ring-purple-500 focus:ring-offset-2',
+        props.className,
+      )}
     />
   ),
 );
@@ -63,10 +55,10 @@ const PurpleItem = React.forwardRef<
     ref={ref}
     type="button"
     {...props}
-    className={
-      'w-full text-left cursor-pointer select-none py-3 px-3 transition-colors duration-150 flex items-center gap-2 rounded text-purple-900 hover:bg-purple-100 data-[selected=true]:bg-purple-100 ' +
-      (props.className || '')
-    }
+    className={clsx(
+      'w-full text-left cursor-pointer select-none py-3 px-3 transition-colors duration-150 flex items-center gap-2 rounded text-purple-900 hover:bg-purple-100 data-[selected=true]:bg-purple-100',
+      props.className,
+    )}
   />
 ));
 PurpleItem.displayName = 'PurpleItem';
@@ -77,7 +69,10 @@ const PurpleSearchInput = React.forwardRef<HTMLInputElement, React.InputHTMLAttr
     <input
       ref={ref}
       {...props}
-      className={'w-full h-9 rounded-md bg-white px-2 text-sm leading-none border-2 border-purple-200 focus:border-purple-400 focus:outline-none ' + (props.className || '')}
+      className={clsx(
+        'w-full h-9 rounded-md bg-white px-2 text-sm leading-none border-2 border-purple-200 focus:border-purple-400 focus:outline-none',
+        props.className,
+      )}
     />
   ),
 );
@@ -92,10 +87,10 @@ const GreenItem = React.forwardRef<
     ref={ref}
     type="button"
     {...props}
-    className={
-      'w-full text-left cursor-pointer select-none py-3 px-3 transition-colors duration-150 flex items-center gap-2 rounded hover:bg-emerald-100 data-[selected=true]:bg-emerald-100 ' +
-      (props.className || '')
-    }
+    className={clsx(
+      'w-full text-left cursor-pointer select-none py-3 px-3 transition-colors duration-150 flex items-center gap-2 rounded hover:bg-emerald-100 data-[selected=true]:bg-emerald-100',
+      props.className,
+    )}
   />
 ));
 GreenItem.displayName = 'GreenItem';
@@ -106,7 +101,6 @@ const SelectCustomizationExample = () => {
   const methods = useRemixForm<FormData>({
     resolver: zodResolver(formSchema),
     defaultValues: {
-      region: '',
       theme: '',
       fruit: '',
     },
@@ -118,15 +112,6 @@ const SelectCustomizationExample = () => {
     <RemixFormProvider {...methods}>
       <fetcher.Form onSubmit={methods.handleSubmit} className="space-y-6">
         <div className="grid gap-6 w-[320px]">
-          {/* Default Select */}
-          <Select
-            name="region"
-            label="Region"
-            description="Default Select styling"
-            options={regionOptions}
-            placeholder="Select a region"
-          />
-
           {/* Custom Trigger and Item using components */}
           <Select
             name="theme"
@@ -231,17 +216,17 @@ Each custom component should use React.forwardRef to preserve focus, ARIA, and k
     await step('Open and choose Theme', async () => {
       const themeSelect = canvas.getByLabelText('Theme');
       await userEvent.click(themeSelect);
-      const purple = await within(document.body).findByRole('option', { name: 'Purple' });
-      await userEvent.click(purple);
-      expect(themeSelect).toHaveTextContent('Purple');
+      const listbox = await within(document.body).findByRole('listbox');
+      await userEvent.click(within(listbox).getByRole('option', { name: /Purple/i }));
+      await expect(canvas.findByRole('combobox', { name: 'Theme' })).resolves.toHaveTextContent('Purple');
     });
 
     await step('Open and choose Fruit', async () => {
       const fruitSelect = canvas.getByLabelText('Favorite Fruit');
       await userEvent.click(fruitSelect);
-      const banana = await within(document.body).findByRole('option', { name: '🍌 Banana' });
-      await userEvent.click(banana);
-      expect(fruitSelect).toHaveTextContent('🍌 Banana');
+      const listbox = await within(document.body).findByRole('listbox');
+      await userEvent.click(within(listbox).getByTestId('select-option-banana'));
+      await expect(canvas.findByRole('combobox', { name: 'Favorite Fruit' })).resolves.toHaveTextContent('Banana');
     });
 
     await step('Submit the form', async () => {

apps/docs/src/remix-hook-form/select.stories.tsx

@@ -263,8 +263,8 @@ export const USStateSelection: Story = {
       const californiaOption = within(listbox).getByRole('option', { name: 'California' });
       await userEvent.click(californiaOption);
 
-      // Verify the selection
-      expect(stateSelect).toHaveTextContent('California');
+      // Wait for the trigger text to update after portal selection
+      await expect(canvas.findByRole('combobox', { name: 'US State' })).resolves.toHaveTextContent('California');
     });
   },
 };
@@ -291,8 +291,8 @@ export const CanadaProvinceSelection: Story = {
       const ontarioOption = within(listbox).getByRole('option', { name: 'Ontario' });
       await userEvent.click(ontarioOption);
 
-      // Verify the selection
-      expect(provinceSelect).toHaveTextContent('Ontario');
+      // Wait for the trigger text to update after portal selection
+      await expect(canvas.findByRole('combobox', { name: 'Canadian Province' })).resolves.toHaveTextContent('Ontario');
     });
   },
 };

packages/components/src/ui/form.tsx

@@ -92,13 +92,24 @@ export interface FormControlProps extends React.ComponentProps<typeof Slot> {
 }
 
 export function FormControl({ Component, ...props }: FormControlProps) {
-  const { formItemId, formDescriptionId, formMessageId, error, ...restProps } = props;
+  const context = React.useContext(FormItemContext);
+  const {
+    formItemId: fromPropsId,
+    formDescriptionId: fromPropsDesc,
+    formMessageId: fromPropsMsg,
+    error,
+    ...restProps
+  } = props;
+
+  const computedId = fromPropsId ?? context.formItemId;
+  const computedDescriptionId = fromPropsDesc ?? context.formDescriptionId;
+  const computedMessageId = fromPropsMsg ?? context.formMessageId;
 
   const ariaProps = {
-    id: formItemId,
-    'aria-describedby': error ? `${formDescriptionId} ${formMessageId}` : formDescriptionId,
+    id: computedId,
+    'aria-describedby': error ? `${computedDescriptionId} ${computedMessageId}` : computedDescriptionId,
     'aria-invalid': !!error,
-  };
+  } as const;
 
   if (Component) {
     return <Component {...restProps} {...ariaProps} />;
@@ -135,17 +146,14 @@ export interface FormMessageProps extends React.HTMLAttributes<HTMLParagraphElem
   Component?: React.ComponentType<FormMessageProps>;
 }
 
-export function FormMessage({
-  Component,
-  className,
-  formMessageId,
-  error,
-  children,
-  ...rest
-}: FormMessageProps) {
+export function FormMessage({ Component, className, formMessageId, error, children, ...rest }: FormMessageProps) {
   if (Component) {
     // Ensure custom props do not leak to DOM by not spreading them
-    return <Component id={formMessageId} className={className} error={error} {...rest}>{children}</Component>;
+    return (
+      <Component id={formMessageId} className={className} error={error} {...rest}>
+        {children}
+      </Component>
+    );
   }
 
   const body = error ? error : children;

packages/components/src/ui/select.tsx

@@ -47,6 +47,7 @@ export function Select({
   ...buttonProps
 }: SelectProps) {
   const popoverState = useOverlayTriggerState({});
+  const listboxId = React.useId();
   const [query, setQuery] = React.useState('');
   const triggerRef = React.useRef<HTMLButtonElement>(null);
   const popoverRef = React.useRef<HTMLDivElement>(null);
@@ -121,6 +122,8 @@ export function Select({
           // biome-ignore lint/a11y/useSemanticElements: using <button> for PopoverTrigger to ensure keyboard accessibility and focus management
           role="combobox"
           aria-haspopup="listbox"
+          aria-expanded={popoverState.isOpen}
+          aria-controls={listboxId}
           {...buttonProps}
         >
           {selectedOption?.label || placeholder}
@@ -132,6 +135,7 @@ export function Select({
         className={cn('z-50 p-0 shadow-md border-0', contentClassName)}
         // biome-ignore lint/a11y/useSemanticElements: using <div> for PopoverContent to ensure keyboard accessibility and focus management
         role="listbox"
+        id={listboxId}
         style={{ width: menuWidth ? `${menuWidth}px` : undefined }}
       >
         <div className="bg-white p-1.5 rounded-md focus:outline-none sm:text-sm">
@@ -190,6 +194,8 @@ export function Select({
                     role="option"
                     aria-selected={isSelected}
                     data-selected={isSelected ? 'true' : 'false'}
+                    data-value={option.value}
+                    data-testid={`select-option-${option.value}`}
                     selected={isSelected}
                   >
                     {isSelected && <CheckIcon className="h-4 w-4 flex-shrink-0" />}