performa 1.0.0

package/README.md

@@ -0,0 +1,850 @@
+# performa
+
+A lightweight, framework-agnostic React form library with built-in server-side validation, TypeScript support, and adapters for popular React frameworks.
+
+## Features
+
+- **Framework Agnostic**: Works with Next.js, React Router, TanStack Start, and any React framework
+- **Server-Side Validation**: Secure form validation with comprehensive validation rules
+- **TypeScript First**: Full type safety with excellent IDE autocomplete
+- **Accessible**: Built-in ARIA attributes and keyboard navigation
+- **Themeable**: Fully customizable with Tailwind CSS or custom styling
+- **Lightweight**: Core library is only 7.69 KB (brotli compressed)
+- **File Uploads**: Built-in support for file validation and previews
+- **Dark Mode**: Native dark mode support out of the box
+
+## Installation
+
+```bash
+npm install performa
+```
+
+### Framework-Specific Installation
+
+For Next.js (App Router):
+```bash
+npm install performa react-dom
+```
+
+For React Router:
+```bash
+npm install performa react-router
+```
+
+For TanStack Start:
+```bash
+npm install performa @tanstack/start
+```
+
+## Quick Start
+
+### 1. Define Your Form Configuration
+
+```typescript
+import { FormConfig } from 'performa';
+
+const loginForm = {
+  key: 'login',
+  method: 'post',
+  action: '/api/login',
+  fields: {
+    email: {
+      type: 'email',
+      label: 'Email Address',
+      placeholder: 'Enter your email',
+      rules: {
+        required: true,
+        isEmail: true,
+      },
+    },
+    password: {
+      type: 'password',
+      label: 'Password',
+      placeholder: 'Enter your password',
+      rules: {
+        required: true,
+        minLength: 8,
+      },
+    },
+    remember: {
+      type: 'checkbox',
+      label: 'Remember me',
+    },
+    submit: {
+      type: 'submit',
+      label: 'Sign In',
+    },
+  },
+} satisfies FormConfig;
+```
+
+### 2. Choose Your Framework Adapter
+
+#### Next.js (App Router)
+
+```typescript
+// app/login/page.tsx
+'use client';
+
+import { NextForm } from 'performa/nextjs';
+import { loginForm } from './form-config';
+
+export default function LoginPage() {
+  return (
+    <NextForm
+      config={loginForm}
+      action={submitLogin}
+      onSuccess={(data) => {
+        console.log('Login successful', data);
+      }}
+    />
+  );
+}
+```
+
+```typescript
+// app/login/actions.ts
+'use server';
+
+import { validateForm } from 'performa/server';
+import { loginForm } from './form-config';
+
+export async function submitLogin(prevState: any, formData: FormData) {
+  const result = await validateForm(
+    new Request('', { method: 'POST', body: formData }),
+    loginForm
+  );
+
+  if (result.hasErrors) {
+    return { errors: result.errors };
+  }
+
+  // Process login with result.values
+  const { email, password } = result.values;
+
+  // Your authentication logic here
+
+  return { success: true };
+}
+```
+
+#### React Router
+
+```typescript
+// routes/login.tsx
+import { ReactRouterForm } from 'performa/react-router';
+import { loginForm } from './form-config';
+
+export default function LoginRoute() {
+  return <ReactRouterForm config={loginForm} />;
+}
+
+// Action handler
+import { validateForm } from 'formbase/server';
+
+export async function action({ request }: ActionFunctionArgs) {
+  const result = await validateForm(request, loginForm);
+
+  if (result.hasErrors) {
+    return { errors: result.errors };
+  }
+
+  // Process login
+  return redirect('/dashboard');
+}
+```
+
+#### TanStack Start
+
+```typescript
+import { TanStackStartForm } from 'performa/tanstack-start';
+import { createServerFn } from '@tanstack/start';
+import { validateForm } from 'formbase/server';
+
+const submitLogin = createServerFn({ method: 'POST' }).handler(
+  async ({ data }: { data: FormData }) => {
+    const result = await validateForm(
+      new Request('', { method: 'POST', body: data }),
+      loginForm
+    );
+
+    if (result.hasErrors) {
+      return { errors: result.errors };
+    }
+
+    return { success: true };
+  }
+);
+
+export default function LoginPage() {
+  return <TanStackStartForm config={loginForm} action={submitLogin} />;
+}
+```
+
+## Form Configuration
+
+### Field Types
+
+formbase supports the following field types:
+
+#### Text Inputs
+- `text` - Standard text input
+- `email` - Email input with validation
+- `password` - Password input with masking
+- `url` - URL input
+- `tel` - Telephone number input
+- `number` - Numeric input
+- `date` - Date picker
+- `time` - Time picker
+
+#### Textareas
+- `textarea` - Multi-line text input
+
+#### Select Inputs
+- `select` - Dropdown selection with options
+
+#### Radio Inputs
+- `radio` - Radio button group
+
+#### Checkboxes and Toggles
+- `checkbox` - Single checkbox
+- `toggle` - Toggle switch
+
+#### File Inputs
+- `file` - File upload with validation and preview
+
+#### Special Types
+- `datetime` - Combined date and time picker
+- `hidden` - Hidden input field
+- `none` - Display-only field (no input)
+- `submit` - Submit button
+
+### Validation Rules
+
+All validation rules are applied server-side for security:
+
+```typescript
+{
+  rules: {
+    required: true,                    // Field is required
+    minLength: 8,                      // Minimum character length
+    maxLength: 100,                    // Maximum character length
+    pattern: /^[A-Z0-9]+$/,           // Custom regex pattern
+    matches: 'password',               // Must match another field
+    isEmail: true,                     // Valid email format
+    isUrl: true,                       // Valid URL format
+    isPhone: true,                     // Valid phone number
+    isDate: true,                      // Valid date
+    isTime: true,                      // Valid time
+    isNumber: true,                    // Valid number
+    isInteger: true,                   // Valid integer
+    isAlphanumeric: true,              // Only letters and numbers
+    isSlug: true,                      // Valid URL slug
+    isUUID: true,                      // Valid UUID
+    denyHtml: true,                    // Reject HTML tags
+    weakPasswordCheck: true,           // Check against known breached passwords
+    minValue: 0,                       // Minimum numeric value
+    maxValue: 100,                     // Maximum numeric value
+    mustBeEither: ['admin', 'user'],   // Value must be one of the options
+    mimeTypes: ['JPEG', 'PNG', 'PDF'], // Allowed file types
+    maxFileSize: 5 * 1024 * 1024,      // Maximum file size in bytes
+  }
+}
+```
+
+### Field Configuration Options
+
+```typescript
+{
+  type: 'text',                  // Field type (required)
+  label: 'Username',             // Field label (required)
+  placeholder: 'Enter username', // Placeholder text
+  defaultValue: '',              // Default value
+  defaultChecked: false,         // Default checked state (checkbox/toggle)
+  disabled: false,               // Disable the field
+  className: 'custom-class',     // Additional CSS classes
+  before: 'Help text above',     // Content before the field
+  beforeClassName: 'text-sm',    // Classes for before content
+  after: 'Help text below',      // Content after the field
+  afterClassName: 'text-sm',     // Classes for after content
+  uploadDir: 'avatars',          // Upload directory for files
+  width: 'full',                 // Field width (full, half, third, quarter)
+  options: [                     // Options for select/radio
+    { value: 'opt1', label: 'Option 1' },
+    { value: 'opt2', label: 'Option 2' },
+  ],
+  rules: { /* validation rules */ },
+}
+```
+
+## Server-Side Validation
+
+### Validation Function
+
+The `validateForm` function performs server-side validation and returns typed results:
+
+```typescript
+import { validateForm } from 'formbase/server';
+
+const result = await validateForm(request, formConfig);
+
+if (result.hasErrors) {
+  // result.errors contains field-specific error messages
+  return { errors: result.errors };
+}
+
+// result.values contains validated and typed form data
+const { email, password } = result.values;
+```
+
+### Custom Error Messages
+
+You can customize validation error messages:
+
+```typescript
+import { defaultErrorMessages } from 'performa/server';
+
+// Customize individual messages
+defaultErrorMessages.required = (label) => `${label} is mandatory`;
+defaultErrorMessages.minLength = (label, min) =>
+  `${label} needs at least ${min} characters`;
+```
+
+### Return Type
+
+  errors: {
+    fieldName?: string;  // Error message for each field
+    __server?: string;   // Server-level error message
+  } | undefined;
+  values: {
+    fieldName: string | boolean | File;  // Validated values
+  };
+  hasErrors: boolean;    // Quick check for validation failure
+}
+```
+
+## File Uploads
+
+### Configuration
+
+```typescript
+{
+  avatar: {
+    type: 'file',
+    label: 'Profile Picture',
+    rules: {
+      required: true,
+      mimeTypes: ['JPEG', 'PNG', 'WEBP'],
+      maxFileSize: 2 * 1024 * 1024, // 2MB
+    },
+    uploadDir: 'avatars',  // Optional: subdirectory for uploads
+  }
+}
+```
+
+### Supported MIME Types
+
+- Images: `JPEG`, `PNG`, `GIF`, `WEBP`, `SVG`, `BMP`, `TIFF`
+- Documents: `PDF`, `DOC`, `DOCX`, `XLS`, `XLSX`, `PPT`, `PPTX`, `TXT`, `CSV`
+- Archives: `ZIP`, `RAR`, `TAR`, `GZIP`
+- Media: `MP3`, `MP4`, `WAV`, `AVI`, `MOV`
+
+### File Preview
+
+Files are automatically previewed if:
+- A `baseUrl` prop is provided to the form component
+- The file is an image type
+- A `defaultValue` exists (for editing forms)
+
+```typescript
+<NextForm
+  config={formConfig}
+  action={submitForm}
+  fileBaseUrl="https://cdn.example.com"
+/>
+```
+
+### Handling File Uploads
+
+```typescript
+export async function submitForm(prevState: any, formData: FormData) {
+  const result = await validateForm(
+    new Request('', { method: 'POST', body: formData }),
+    formConfig
+  );
+
+  if (result.hasErrors) {
+    return { errors: result.errors };
+  }
+
+  const file = result.values.avatar as File;
+
+  // Upload file to storage
+  const buffer = Buffer.from(await file.arrayBuffer());
+  const filename = `${Date.now()}-${file.name}`;
+
+  // Save to file system, S3, etc.
+  await saveFile(filename, buffer);
+
+  return { success: true };
+}
+```
+
+## Theming
+
+### Default Theme
+
+formbase comes with a default theme optimized for Tailwind CSS with dark mode support:
+
+```typescript
+import { FormThemeProvider } from 'performa';
+
+function App() {
+  return (
+    <FormThemeProvider>
+      {/* Your forms here */}
+    </FormThemeProvider>
+  );
+}
+```
+
+### Custom Theme
+
+Override the default theme with your own styles:
+
+```typescript
+import { FormThemeProvider } from 'formbase';
+
+const customTheme = {
+  formGroup: 'mb-6',
+  label: {
+    base: 'block text-sm font-semibold mb-2',
+    required: 'text-red-600 ml-1',
+  },
+  input: {
+    base: 'w-full px-4 py-3 border rounded-lg focus:ring-2',
+    error: 'border-red-500 focus:ring-red-500',
+  },
+  error: 'text-red-600 text-sm mt-2',
+  button: {
+    primary: 'bg-blue-600 text-white px-6 py-3 rounded-lg hover:bg-blue-700',
+  },
+};
+
+function App() {
+  return (
+    <FormThemeProvider theme={customTheme}>
+      {/* Your forms here */}
+    </FormThemeProvider>
+  );
+}
+```
+
+### Theme Structure
+
+The complete theme object structure:
+
+```typescript
+{
+  form: string;              // Form element styles
+  formGroup: string;         // Field group wrapper
+  fieldset: string;          // Fieldset styles
+  label: {
+    base: string;            // Label base styles
+    required: string;        // Required asterisk styles
+  };
+  input: {
+    base: string;            // Input base styles
+    error: string;           // Error state styles
+  };
+  textarea: {
+    base: string;
+    error: string;
+  };
+  select: {
+    base: string;
+    error: string;
+  };
+  checkbox: {
+    base: string;
+    label: string;
+    error: string;
+  };
+  radio: {
+    group: string;
+    base: string;
+    label: string;
+  };
+  toggle: {
+    wrapper: string;
+    base: string;
+    slider: string;
+    label: string;
+  };
+  file: {
+    dropzone: string;
+    dropzoneActive: string;
+    dropzoneError: string;
+    icon: string;
+    text: string;
+    hint: string;
+  };
+  datetime: {
+    input: string;
+    iconButton: string;
+    dropdown: string;
+    navButton: string;
+    monthYear: string;
+    weekday: string;
+    day: string;
+    daySelected: string;
+    timeLabel: string;
+    timeInput: string;
+    formatButton: string;
+    periodButton: string;
+    periodButtonActive: string;
+  };
+  button: {
+    primary: string;
+    secondary: string;
+  };
+  alert: {
+    base: string;
+    error: string;
+    success: string;
+    warning: string;
+    info: string;
+  };
+  error: string;
+}
+```
+
+### Custom Labels
+
+Customize form labels and messages:
+
+```typescript
+import { FormThemeProvider } from 'formbase';
+
+const customLabels = {
+  fileUpload: {
+    clickToUpload: 'Choose file',
+    dragAndDrop: 'or drag and drop',
+    allowedTypes: 'Supported formats:',
+    maxSize: 'Maximum size:',
+  },
+  datetime: {
+    weekdays: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
+    clear: 'Clear',
+    done: 'Done',
+    timeFormat: 'Time Format',
+  },
+};
+
+function App() {
+  return (
+    <FormThemeProvider labels={customLabels}>
+      {/* Your forms here */}
+    </FormThemeProvider>
+  );
+}
+```
+
+## Advanced Usage
+
+### Using Hooks for Custom Forms
+
+#### Next.js
+
+```typescript
+import { useNextForm } from 'performa/nextjs';
+
+function CustomForm() {
+  const { formAction, errors, isPending, isSuccess } = useNextForm(
+    submitForm,
+    (data) => {
+      console.log('Success!', data);
+    }
+  );
+
+  return (
+    <form action={formAction}>
+      <input name="email" type="email" />
+      {errors?.email && <p>{errors.email}</p>}
+      <button disabled={isPending}>
+        {isPending ? 'Submitting...' : 'Submit'}
+      </button>
+      {isSuccess && <p>Form submitted successfully!</p>}
+    </form>
+  );
+}
+```
+
+#### React Router
+
+```typescript
+import { useReactRouterForm } from 'performa/react-router';
+
+function CustomForm() {
+  const { fetcher, errors, isSubmitting } = useReactRouterForm('my-form');
+
+  return (
+    <fetcher.Form method="post">
+      <input name="email" type="email" />
+      {errors?.email && <p>{errors.email}</p>}
+      <button disabled={isSubmitting}>Submit</button>
+    </fetcher.Form>
+  );
+}
+```
+
+#### TanStack Start
+
+```typescript
+import { useTanStackStartForm } from 'performa/tanstack-start';
+
+function CustomForm() {
+  const { handleSubmit, errors, isPending } = useTanStackStartForm(
+    submitForm
+  );
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input name="email" type="email" />
+      {errors?.email && <p>{errors.email}</p>}
+      <button disabled={isPending}>Submit</button>
+    </form>
+  );
+}
+```
+
+### Conditional Fields
+
+```typescript
+const formConfig: FormConfig = {
+  key: 'signup',
+  fields: {
+    accountType: {
+      type: 'select',
+      label: 'Account Type',
+      options: [
+        { value: 'personal', label: 'Personal' },
+        { value: 'business', label: 'Business' },
+      ],
+      rules: { required: true },
+    },
+    // Only show company name for business accounts
+    ...(accountType === 'business' && {
+      companyName: {
+        type: 'text',
+        label: 'Company Name',
+        rules: { required: true },
+      },
+    }),
+  },
+};
+```
+
+### Multi-Step Forms
+
+```typescript
+const step1Config: FormConfig = {
+  key: 'registration-step1',
+  fields: {
+    email: { type: 'email', label: 'Email', rules: { required: true } },
+    password: { type: 'password', label: 'Password', rules: { required: true } },
+    submit: { type: 'submit', label: 'Continue' },
+  },
+};
+
+const step2Config: FormConfig = {
+  key: 'registration-step2',
+  fields: {
+    firstName: { type: 'text', label: 'First Name', rules: { required: true } },
+    lastName: { type: 'text', label: 'Last Name', rules: { required: true } },
+    submit: { type: 'submit', label: 'Complete Registration' },
+  },
+};
+
+function MultiStepForm() {
+  const [step, setStep] = useState(1);
+
+  return (
+    <>
+      {step === 1 && (
+        <NextForm
+          config={step1Config}
+          action={submitStep1}
+          onSuccess={() => setStep(2)}
+        />
+      )}
+      {step === 2 && (
+        <NextForm
+          config={step2Config}
+          action={submitStep2}
+        />
+      )}
+    </>
+  );
+}
+```
+
+### Dynamic Field Options
+
+```typescript
+function DynamicForm() {
+  const [categories, setCategories] = useState([]);
+
+  useEffect(() => {
+    fetch('/api/categories')
+      .then(res => res.json())
+      .then(data => setCategories(data));
+  }, []);
+
+  const formConfig: FormConfig = {
+    key: 'product',
+    fields: {
+      category: {
+        type: 'select',
+        label: 'Category',
+        options: categories.map(cat => ({
+          value: cat.id,
+          label: cat.name,
+        })),
+        rules: { required: true },
+      },
+    },
+  };
+
+  return <NextForm config={formConfig} action={submitProduct} />;
+}
+```
+
+## TypeScript
+
+formbase is built with TypeScript and provides full type safety:
+
+```typescript
+import { FormConfig } from 'performa';
+import { validateForm } from 'performa/server';
+
+// Type-safe form configuration using 'satisfies'
+// This gives you both type checking AND proper inference
+const formConfig = {
+  key: 'contact',
+  fields: {
+    name: {
+      type: 'text',
+      label: 'Name',
+      rules: { required: true },
+    },
+    email: {
+      type: 'email',
+      label: 'Email',
+      rules: { required: true, isEmail: true },
+    },
+  },
+} satisfies FormConfig;
+
+// Type-safe validation result
+// TypeScript automatically infers the correct types from formConfig
+const result = await validateForm(request, formConfig);
+
+if (result.hasErrors) {
+  // result.errors is properly typed with field names
+  console.log(result.errors.name); // string | undefined
+  console.log(result.errors.email); // string | undefined
+}
+
+// result.values is properly typed based on field types
+const name: string = result.values.name; // TypeScript knows this is a string
+const email: string = result.values.email; // TypeScript knows this is a string
+```
+
+## Security Considerations
+
+### Server-Side Validation
+
+All validation is performed server-side. Client-side HTML5 validation attributes are added for better UX, but should not be relied upon for security.
+
+### File Upload Security
+
+1. **MIME Type Validation**: Files are validated by actual MIME type, not just extension
+2. **Size Limits**: Enforce maximum file sizes to prevent DoS attacks
+3. **File Storage**: Always validate and sanitize filenames before storage
+4. **Virus Scanning**: Implement virus scanning for uploaded files in production
+
+### XSS Prevention
+
+- All form inputs are properly escaped when rendered
+- The `denyHtml` validation rule prevents HTML injection
+- Use the `pattern` rule to restrict input to safe characters
+
+### CSRF Protection
+
+Implement CSRF protection at the framework level:
+
+```typescript
+// Next.js example with csrf-token
+import { headers } from 'next/headers';
+
+export async function submitForm(prevState: any, formData: FormData) {
+  const headersList = headers();
+  const csrfToken = headersList.get('x-csrf-token');
+
+  // Validate CSRF token
+
+  const result = await validateForm(request, formConfig);
+  // ...
+}
+```
+
+## Performance
+
+### Bundle Sizes
+
+- Core library: 7.69 KB (brotli)
+- Server validation: 367 B (brotli)
+- React Router adapter: 18.8 KB (brotli)
+- Next.js adapter: 7.3 KB (brotli)
+- TanStack Start adapter: 7.36 KB (brotli)
+
+### Optimization
+
+All components are memoized with `React.memo` for optimal performance. The library uses:
+
+- Tree-shaking for unused code elimination
+- Code splitting between client and server modules
+- Minimal dependencies (only `lucide-react` for icons)
+
+## Accessibility
+
+formbase is built with accessibility in mind:
+
+- Proper ARIA attributes on all form elements
+- Keyboard navigation support
+- Screen reader friendly error messages
+- Focus management
+- Semantic HTML structure
+- High contrast mode support
+
+## Browser Support
+
+- Chrome/Edge (latest)
+- Firefox (latest)
+- Safari (latest)
+- iOS Safari (latest)
+- Chrome Android (latest)
+
+## Contributing
+
+Contributions are welcome! Please see our contributing guidelines.
+
+## License
+
+MIT License - see LICENSE file for details
+
+## Support
+
+- GitHub Issues: https://github.com/matttehat/performa/issues
+- Documentation: https://github.com/matttehat/performa#readme