ragflow-form.stories.tsx

Overview

This file defines Storybook stories for demonstrating the usage of the RAGFlowFormItem component within a form context. RAGFlowFormItem is a form item wrapper component designed to provide consistent styling, layout, and integration with react-hook-form and shadcn/ui form primitives. The file showcases how to use this component in both vertical and horizontal layouts, with form validation powered by zod schemas.

The file serves primarily as documentation and visual test cases for UI developers and designers to see and interact with the RAGFlowFormItem in isolation via Storybook.

Key Components and Functions

FormSchema

const FormSchema = z.object({
  username: z.string().min(2, {
    message: 'Username must be at least 2 characters.',
  }),
  email: z.string().email({
    message: 'Please enter a valid email address.',
  }),
  description: z.string().optional(),
});

• Type: Zod schema object

• Purpose: Defines validation rules for the form fields:

  • username: Required string, min length 2.

  • email: Required string, must be an email.

  • description: Optional string.

• Usage: Used with zodResolver in react-hook-form to validate form inputs.

FormExample Component

function FormExample({
  horizontal = false,
  fieldName = 'username',
  label = 'Username',
  tooltip = 'Please enter your username',
  placeholder = 'Enter username',
}: {
  horizontal?: boolean;
  fieldName?: string;
  label?: string;
  tooltip?: string;
  placeholder?: string;
}) { ... }

• Type: React functional component

• Purpose: Demonstrates usage of RAGFlowFormItem within a form using react-hook-form.

• Props:

  • horizontal (boolean): Whether to display the form item layout horizontally (label and input aligned side by side).

  • fieldName (string): The name of the form field to bind.

  • label (string): The label text shown for the form field.

  • tooltip (string): Tooltip text displayed on the form label.

  • placeholder (string): Placeholder text for the input control.

• Implementation Details:

  • Uses useForm from react-hook-form with zodResolver for validation.

  • Default form values set for username, email, and description.

  • Renders a <Form> container wrapping a <form> element with a single RAGFlowFormItem.

  • The RAGFlowFormItem wraps an <Input> component to show how input integrates with the form item.

• Returns: JSX element rendering the form with one controlled form item.

• Example Usage:

  <FormExample
    horizontal={true}
    fieldName="email"
    label="Email Address"
    tooltip="Please enter a valid email address"
    placeholder="Enter email"
  />
  

Storybook Meta Configuration (meta)

const meta = { ... } satisfies Meta<typeof FormExample>;
export default meta;

• Purpose: Defines Storybook metadata for the FormExample component stories.

• Key Properties:

  • title: Storybook sidebar category and name.

  • component: The React component to render (FormExample).

  • parameters: Storybook configuration including layout and documentation.

  • argTypes: Controls for Storybook's UI to manipulate props dynamically.

  • args: Default arguments passed to the component in stories.

• Documentation: Contains detailed markdown explanations about RAGFlowFormItem usage, features, and import paths in the docs.description.component field, enabling Storybook Docs tab to show rich info.

Story Exports

The file exports two main stories demonstrating the form item layout variations:

VerticalLayout

export const VerticalLayout: Story = {
  args: {
    horizontal: false,
    fieldName: 'username',
    label: 'Username',
    tooltip: 'Please enter your username',
    placeholder: 'Enter username',
  },
  parameters: { ... }
};

• Demonstrates the default vertical layout with the label above the input.

• Shows usage with RAGFlowFormItem in vertical mode.

HorizontalLayout

export const HorizontalLayout: Story = {
  args: {
    horizontal: true,
    fieldName: 'email',
    label: 'Email Address',
    tooltip: 'Please enter a valid email address',
    placeholder: 'Enter email',
  },
  parameters: { ... }
};

• Demonstrates the horizontal layout with label and input side by side.

• Useful to see how the component adapts to different form layouts.

Important Implementation Details

• Form Validation: Leveraging zod schemas combined with react-hook-form and zodResolver for synchronous client-side validation.

• Form Item Composition: RAGFlowFormItem internally wraps FormField, FormItem, FormLabel, FormControl, and FormMessage from shadcn/ui to unify styling and behavior.

• Layout Flexibility: The horizontal prop toggles between vertical and horizontal form item layouts.

• Tooltip Support: Labels can display tooltips with contextual help.

• Storybook Integration: The stories are configured with args and controls allowing live editing of props in Storybook.

Interaction with Other Parts of the System

• RAGFlowFormItem: The main component under test, imported from @/components/ragflow-form. This is a shared UI component used throughout the application for consistent form item rendering.

• Form Primitives: Wraps components from @/components/ui/form and @/components/ui/input, which are likely part of a design system or UI library built on top of shadcn/ui primitives.

• Validation Libraries: Integrates with zod and react-hook-form ecosystem for robust form handling.

• Storybook: This file is part of the Storybook setup and documentation, enabling UI development and review in isolation.

Usage Summary

To use the form item component demonstrated here:

1. Define a Zod schema for your form data.

2. Create a React Hook Form instance with useForm and zodResolver.

3. Wrap your input controls with RAGFlowFormItem, passing props like name, label, tooltip, and horizontal.

4. Use the Form component to provide context and styling.

5. Use this story file in Storybook to view and interact with the component or adapt it as a template for your forms.

Visual Diagram: Component Interaction Overview

componentDiagram
    direction TB
    FormExample --> Form
    Form --> form
    form --> RAGFlowFormItem
    RAGFlowFormItem --> Input
    RAGFlowFormItem ..> FormField : wraps
    RAGFlowFormItem ..> FormItem : wraps
    RAGFlowFormItem ..> FormLabel : wraps
    RAGFlowFormItem ..> FormControl : wraps
    RAGFlowFormItem ..> FormMessage : wraps
    FormExample .. uses react-hook-form ..> useForm
    useForm .. uses zodResolver ..> FormSchema

Summary

This file is a Storybook story definition showcasing the RAGFlowFormItem UI component integrated with react-hook-form and zod validation. It illustrates both vertical and horizontal layouts with customizable labels, tooltips, and placeholders. The example demonstrates best practices for form handling and UI composition in a React application using modern libraries. It also enriches Storybook documentation with usage examples and API controls to facilitate UI development.

End of Documentation for ragflow-form.stories.tsx