@metadiv-studio/sheet-metaform

A React component that combines a sheet (modal/sidebar) with a dynamic form system, providing a powerful and flexible way to create form interfaces within slide-out panels.

Installation

npm install @metadiv-studio/sheet-metaform

Tailwind CSS Configuration

Important: You must add the following content to your tailwind.config.ts file to ensure proper styling:

module.exports = {
  content: [
    // ... your existing content
    "./node_modules/@metadiv-studio/**/*.{js,ts,jsx,tsx}"
  ],
  // ... rest of your config
}

Props Documentation

Basic Props

open?: boolean

Controls whether the sheet is visible or hidden.

<SheetMetaForm open={isOpen} onOpenChange={setIsOpen} />

onOpenChange?: (open: boolean) => void

Callback function triggered when the sheet open state changes.

<SheetMetaForm 
  open={isOpen} 
  onOpenChange={(open) => setIsOpen(open)} 
/>

size?: 'small' | 'medium' | 'large'

Determines the width of the sheet. Defaults to 'medium'.

<SheetMetaForm size="large" />

Header and Footer

header?: React.ReactNode

Custom content to display in the sheet header area.

<SheetMetaForm 
  header={<h2 className="text-lg font-semibold">Edit User Profile</h2>} 
/>

footer?: React.ReactNode

Custom content to display in the sheet footer area, above the action buttons.

<SheetMetaForm 
  footer={<p className="text-sm text-gray-500">All fields are required</p>} 
/>

Form Configuration

schema: T

Zod schema that defines the form structure and validation rules.

import { z } from 'zod';

const userSchema = z.object({
  name: z.string().min(1, 'Name is required'),
  email: z.string().email('Invalid email'),
  age: z.number().min(18, 'Must be 18 or older')
});

<SheetMetaForm schema={userSchema} />

items?: FormItem<z.infer<T>>[]

Array of form field configurations that define the form layout and field types.

const formItems: FormItem[] = [
  {
    name: 'name',
    label: 'Full Name',
    type: 'input',
    placeholder: 'Enter your full name'
  },
  {
    name: 'email',
    label: 'Email Address',
    type: 'input',
    inputType: 'email'
  }
];

<SheetMetaForm schema={userSchema} items={formItems} />

defaultValues?: DefaultValues<z.infer<T>>

Initial values for the form fields.

<SheetMetaForm 
  schema={userSchema} 
  defaultValues={{ name: 'John Doe', email: '[email protected]' }} 
/>

Data Fetching

fetchId?: any

Identifier used to fetch data when the form opens.

<SheetMetaForm 
  fetchId={userId} 
  fetch={fetchUserData} 
/>

fetch?: (id?: any, form?: UseFormReturn) => Promise<void>

Function to fetch data and populate the form. Receives the fetchId and form instance.

const fetchUserData = async (id: string, form: UseFormReturn) => {
  const user = await api.getUser(id);
  form.reset(user);
};

<SheetMetaForm 
  fetchId={userId} 
  fetch={fetchUserData} 
/>

fetchError?: (error: any) => void

Error handler for fetch operations.

<SheetMetaForm 
  fetch={fetchUserData} 
  fetchError={(error) => console.error('Fetch failed:', error)} 
/>

Form Control

form?: UseFormReturn<z.infer<T>>

External react-hook-form instance for advanced form control.

const form = useForm({
  resolver: zodResolver(userSchema),
  defaultValues: { name: '', email: '' }
});

<SheetMetaForm 
  schema={userSchema} 
  form={form} 
/>

onValuesChange?: (values: z.infer<T>) => void

Callback triggered whenever form values change.

<SheetMetaForm 
  schema={userSchema} 
  onValuesChange={(values) => console.log('Form values changed:', values)} 
/>

Actions and Submission

onSubmit?: (values: z.infer<T>) => Promise<void>

Function called when the form is submitted with valid data.

const handleSubmit = async (values: UserData) => {
  await api.updateUser(userId, values);
  setIsOpen(false);
};

<SheetMetaForm 
  schema={userSchema} 
  onSubmit={handleSubmit} 
/>

saveButton?: boolean

Whether to show the save button. Defaults to false.

<SheetMetaForm 
  schema={userSchema} 
  saveButton={true} 
/>

saveButtonText?: string

Custom text for the save button. Defaults to translated 'save'.

<SheetMetaForm 
  schema={userSchema} 
  saveButton={true} 
  saveButtonText="Update Profile" 
/>

onCancel?: () => void

Function called when the cancel button is clicked.

<SheetMetaForm 
  schema={userSchema} 
  onCancel={() => setIsOpen(false)} 
/>

cancelButtonText?: string

Custom text for the cancel button. Defaults to translated 'cancel'.

<SheetMetaForm 
  schema={userSchema} 
  onCancel={() => setIsOpen(false)} 
  cancelButtonText="Close" 
/>

Loading States

loading?: boolean

External loading state that disables form interactions and buttons.

<SheetMetaForm 
  schema={userSchema} 
  loading={isSubmitting} 
/>

Complete Example

import { SheetMetaForm } from '@metadiv-studio/sheet-metaform';
import { z } from 'zod';
import { useState } from 'react';

const userSchema = z.object({
  name: z.string().min(1, 'Name is required'),
  email: z.string().email('Invalid email'),
  role: z.enum(['admin', 'user', 'guest'])
});

export function UserEditForm({ userId, isOpen, onClose }) {
  const [loading, setLoading] = useState(false);

  const formItems = [
    { name: 'name', label: 'Full Name', type: 'input' },
    { name: 'email', label: 'Email', type: 'input', inputType: 'email' },
    { name: 'role', label: 'Role', type: 'select', options: [
      { value: 'admin', label: 'Administrator' },
      { value: 'user', label: 'User' },
      { value: 'guest', label: 'Guest' }
    ]}
  ];

  const fetchUser = async (id: string) => {
    const user = await api.getUser(id);
    return user;
  };

  const handleSubmit = async (values) => {
    setLoading(true);
    try {
      await api.updateUser(userId, values);
      onClose();
    } finally {
      setLoading(false);
    }
  };

  return (
    <SheetMetaForm
      open={isOpen}
      onOpenChange={onClose}
      size="medium"
      header={<h2 className="text-lg font-semibold">Edit User</h2>}
      schema={userSchema}
      items={formItems}
      fetchId={userId}
      fetch={fetchUser}
      saveButton={true}
      saveButtonText="Update User"
      onCancel={onClose}
      onSubmit={handleSubmit}
      loading={loading}
    />
  );
}