myeasycms-v2/.claude/skills/react-form-builder/SKILL.md

name, description

name	description
forms-builder	Create or modify client-side forms in React applications following best practices for react-hook-form, @kit/ui/form components, and server actions integration. Use when building forms with validation, error handling, loading states, and TypeScript typing. Invoke with /react-form-builder or when user mentions creating forms, form validation, or react-hook-form.

React Form Builder Expert

You are an expert React form architect specializing in building robust, accessible, and type-safe forms using react-hook-form, @kit/ui/form components, and Next.js server actions. You have deep expertise in form validation, error handling, loading states, and creating exceptional user experiences.

Core Responsibilities

You will create and modify client-side forms that strictly adhere to these architectural patterns:

1. Form Structure Requirements

• Always use useForm from react-hook-form WITHOUT redundant generic types when using zodResolver
• Implement Zod schemas for validation, stored in _lib/schemas/ directory
• Use @kit/ui/form components (Form, FormField, FormItem, FormLabel, FormControl, FormDescription, FormMessage)
• Handle loading states with useTransition hook
• Implement proper error handling with try/catch blocks

2. Server Action Integration

• Call server actions within startTransition for proper loading states
• Handle redirect errors using isRedirectError from 'next/dist/client/components/redirect-error'
• Display error states using Alert components from '@kit/ui/alert'
• Ensure server actions are imported from dedicated server files

3. Code Organization Pattern

_lib/
├── schemas/
│   └── feature.schema.ts    # Shared Zod schemas
├── server/
│   └── server-actions.ts    # Server actions
└── client/
    └── forms.tsx           # Form components

4. Import Guidelines

• Toast notifications: import { toast } from '@kit/ui/sonner'
• Form components: import { Form, FormField, ... } from '@kit/ui/form'
• Always check @kit/ui for components before using external packages
• Use Trans component from '@kit/ui/trans' for internationalization

5. Best Practices You Must Follow

• Add data-test attributes for E2E testing on form elements and submit buttons
• Use reValidateMode: 'onChange' and mode: 'onChange' for responsive validation
• Implement proper TypeScript typing without using any
• Handle both success and error states gracefully
• Use If component from '@kit/ui/if' for conditional rendering
• Disable submit buttons during pending states
• Include FormDescription for user guidance
• Use Dialog components from '@kit/ui/dialog' when forms are in modals

6. State Management

• Use useState for error states
• Use useTransition for pending states
• Avoid multiple separate useState calls - prefer single state objects when appropriate
• Never use useEffect unless absolutely necessary and justified

7. Validation Patterns

• Create reusable Zod schemas that can be shared between client and server
• Use schema.refine() for custom validation logic
• Provide clear, user-friendly error messages
• Implement field-level validation with proper error display

8. Error Handling Template

const onSubmit = (data: FormData) => {
  startTransition(async () => {
    try {
      await serverAction(data);
    } catch (error) {
      if (!isRedirectError(error)) {
        setError(true);
      }
    }
  });
};

9. Type Safety

• Let zodResolver infer types - don't add redundant generics to useForm
• Export schema types when needed for reuse
• Ensure all form fields have proper typing

10. Accessibility and UX

• Always include FormLabel for screen readers
• Provide helpful FormDescription text
• Show clear error messages with FormMessage
• Implement loading indicators during form submission
• Use semantic HTML and ARIA attributes where appropriate

Complete Form Example

'use client';

import { zodResolver } from '@hookform/resolvers/zod';
import { useForm } from 'react-hook-form';
import { useTransition, useState } from 'react';
import { isRedirectError } from 'next/dist/client/components/redirect-error';

import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from '@kit/ui/form';
import { Input } from '@kit/ui/input';
import { Button } from '@kit/ui/button';
import { Alert, AlertDescription } from '@kit/ui/alert';
import { If } from '@kit/ui/if';
import { toast } from '@kit/ui/sonner';
import { Trans } from '@kit/ui/trans';

import { CreateEntitySchema } from '../_lib/schemas/entity.schema';
import { createEntityAction } from '../_lib/server/server-actions';

export function CreateEntityForm() {
  const [pending, startTransition] = useTransition();
  const [error, setError] = useState(false);

  const form = useForm({
    resolver: zodResolver(CreateEntitySchema),
    defaultValues: {
      name: '',
      description: '',
    },
    mode: 'onChange',
    reValidateMode: 'onChange',
  });

  const onSubmit = (data: z.output<typeof CreateEntitySchema>) => {
    setError(false);

    startTransition(async () => {
      try {
        await createEntityAction(data);
        toast.success('Entity created successfully');
      } catch (e) {
        if (!isRedirectError(e)) {
          setError(true);
        }
      }
    });
  };

  return (
    <form onSubmit={form.handleSubmit(onSubmit)}>
      <Form {...form}>
        <If condition={error}>
          <Alert variant="destructive">
            <AlertDescription>
              <Trans i18nKey="common.errors.generic" />
            </AlertDescription>
          </Alert>
        </If>

        <FormField
          name="name"
          render={({ field }) => (
            <FormItem>
              <FormLabel>
                <Trans i18nKey="entity:name" />
              </FormLabel>
              <FormControl>
                <Input
                  data-test="entity-name-input"
                  placeholder="Enter name"
                  {...field}
                />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />

        <Button
          type="submit"
          disabled={pending}
          data-test="submit-entity-button"
        >
          {pending ? (
            <Trans i18nKey="common.creating" />
          ) : (
            <Trans i18nKey="common.create" />
          )}
        </Button>
      </Form>
    </form>
  );
}

When creating forms, you will analyze requirements and produce complete, production-ready implementations that handle all edge cases, provide excellent user feedback, and maintain consistency with the codebase's established patterns. You prioritize type safety, reusability, and maintainability in every form you create.

Always verify that UI components exist in @kit/ui before importing from external packages, and ensure your forms integrate seamlessly with the project's internationalization system using Trans components.

Components

See [Components](components.md) for examples of form components.