suprform 1.0.1 → 1.0.2

package/README.md

@@ -1,80 +1,222 @@
 # suprform
 
-A headless React form library for managing complex state, validation, and error handling with a clean, scalable architecture.
+A lightweight, **design system agnostic** React form library built as a powerful wrapper on top of **[react-hook-form](https://react-hook-form.com)**. Manage complex forms, validation, and error handling with a clean, composable API—no UI components bundled, complete control over your design.
 
-## Features
+> **What is SuprForm?** A thin, type-safe layer on top of `react-hook-form` that adds intuitive field management, built-in validation rules, and automatic error display—while staying completely design-system agnostic.
 
-- 🎨 **Headless Architecture** - Complete control over your UI and styling
-- 🔒 **TypeScript First** - Full type safety and IntelliSense support
-- ✅ **Flexible Validation** - Built-in validators and custom validation rules
-- 🎯 **Field-Level Control** - Manage individual fields with ease
-- 📊 **Form State Management** - Track dirty, touched, valid states automatically
-- ⚡ **Async Validation** - Support for asynchronous validation
-- 📦 **Zero Dependencies** - Only requires React as peer dependency
-- 🧪 **Well Tested** - Comprehensive test suite included
+## Key Highlights
+
+- 🎨 **Design System Agnostic** - Works with any UI framework (Material-UI, Tailwind, custom components, etc.) or plain HTML
+- 🪝 **Built on react-hook-form** - Leverages the performance and flexibility of the most popular form library
+- 🔒 **TypeScript First** - Full type safety and IntelliSense support with complete type inference
+- ✅ **Seamless Validation** - Declarative validation rules with built-in validators and custom rule support
+- 🎯 **Field-Level Control** - Granular control over individual fields with automatic state tracking
+- 📊 **Automatic State Management** - Tracks dirty, touched, valid, error, and submission states
+- ⚡ **Async Validation** - Native support for asynchronous validation (API calls, etc.)
+- 🧪 **Well Tested** - Comprehensive test suite with full coverage
+- 📦 **Minimal Footprint** - Only requires React as a peer dependency
 
 ## Installation
 
 ```bash
-npm install suprform
+npm install suprform react-hook-form react react-dom
 ```
 
-## Quick Start
+## Quick Start with SuprForm.Control
+
+The easiest way to get started—use the composable `SuprForm.Control` component with your own UI components:
 
 ```tsx
-import { useForm, required, email } from 'suprform';
+import SuprForm from 'suprform';
 
 function LoginForm() {
-  const form = useForm({
-    initialValues: {
-      email: '',
-      password: '',
-    },
-    onSubmit: async (values) => {
-      console.log('Form submitted:', values);
-    },
-  });
+  return (
+    <SuprForm
+      onSubmit={(values) => {
+        console.log('Form submitted:', values);
+      }}
+    >
+      <SuprForm.Control
+        name='email'
+        label='Email Address'
+        rules={{
+          required: 'Email is required',
+          pattern: {
+            value: /^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i,
+            message: 'Invalid email address',
+          },
+        }}
+      >
+        <input type='email' placeholder='you@example.com' />
+      </SuprForm.Control>
+
+      <SuprForm.Control
+        name='password'
+        label='Password'
+        rules={{
+          required: 'Password is required',
+          minLength: { value: 8, message: 'Password must be at least 8 characters' },
+        }}
+      >
+        <input type='password' placeholder='••••••••' />
+      </SuprForm.Control>
+
+      <button type='submit'>Login</button>
+    </SuprForm>
+  );
+}
+```
+
+**That's it!** `SuprForm.Control` automatically:
+
+- Renders a label above the input
+- Validates on blur and change
+- Displays error messages below the input
+- Manages field state (touched, dirty, value, etc.)
+
+Works with any input component—plain HTML, styled divs, Material-UI inputs, custom components, etc.
 
-  // Register fields with validators
-  form.registerField('email', {
-    validators: [{ rule: required('Email is required') }, { rule: email('Invalid email format') }],
-  });
+## Advanced Example: Custom UI Components
 
-  form.registerField('password', {
-    validators: [{ rule: required('Password is required') }],
-  });
+Since SuprForm is **design system agnostic**, use it with your favorite component library:
 
-  const emailState = form.getFieldState('email');
-  const emailHandlers = form.getFieldHandlers('email');
+```tsx
+import SuprForm from 'suprform';
+import { TextField, Button } from '@mui/material'; // or your own
 
+function SignupForm() {
   return (
-    <form
-      onSubmit={(e) => {
-        e.preventDefault();
-        form.submitForm();
+    <SuprForm
+      onSubmit={(values) => {
+        console.log('User signed up:', values);
       }}
     >
-      <div>
-        <input
-          type='email'
-          value={emailState.value || ''}
-          onChange={(e) => emailHandlers.onChange(e.target.value)}
-          onBlur={emailHandlers.onBlur}
-        />
-        {emailState.touched && emailState.error && <span>{emailState.error}</span>}
-      </div>
-
-      <button type='submit' disabled={!form.isValid || form.submitting}>
-        {form.submitting ? 'Submitting...' : 'Login'}
-      </button>
-    </form>
+      <SuprForm.Control
+        name='username'
+        label='Username'
+        rules={{
+          required: 'Username is required',
+          minLength: { value: 3, message: 'Min 3 characters' },
+          pattern: {
+            value: /^[a-zA-Z0-9_]+$/,
+            message: 'Only letters, numbers, and underscores',
+          },
+        }}
+      >
+        <TextField variant='outlined' fullWidth />
+      </SuprForm.Control>
+
+      <SuprForm.Control
+        name='email'
+        label='Email'
+        rules={{
+          required: 'Email is required',
+          pattern: {
+            value: /^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i,
+            message: 'Invalid email',
+          },
+        }}
+      >
+        <TextField type='email' variant='outlined' fullWidth />
+      </SuprForm.Control>
+
+      <Button variant='contained' type='submit'>
+        Sign Up
+      </Button>
+    </SuprForm>
+  );
+}
+```
+
+## Styling
+
+Since SuprForm is **design system agnostic**, styling is completely in your control. Here are the CSS classes generated:
+
+```css
+/* Wrapper for the entire field */
+.controlled-field {
+  /* Your styles */
+}
+
+/* Label element */
+.controlled-field-label {
+  /* Your styles */
+}
+
+/* Error message container */
+.controlled-field-error {
+  /* Defaults to red, 14px font, margin-top 4px */
+  /* Override with your own styles */
+}
+```
+
+**Example with Tailwind CSS:**
+
+```tsx
+<SuprForm.Control
+  name='email'
+  label='Email'
+  rules={{ required: 'Email is required' }}
+  className='mb-4'
+>
+  <input
+    type='email'
+    className='w-full px-4 py-2 border rounded-lg focus:outline-none focus:ring-2'
+  />
+</SuprForm.Control>
+```
+
+**Example with styled-components:**
+
+```tsx
+import styled from 'styled-components';
+
+const StyledField = styled.div`
+  margin-bottom: 1.5rem;
+
+  label {
+    display: block;
+    font-weight: 600;
+    margin-bottom: 0.5rem;
+  }
+
+  input {
+    width: 100%;
+    padding: 0.75rem;
+    border: 1px solid #ddd;
+    border-radius: 4px;
+
+    &:focus {
+      outline: none;
+      border-color: #0066cc;
+      box-shadow: 0 0 0 3px rgba(0, 102, 204, 0.1);
+    }
+  }
+
+  .controlled-field-error {
+    color: #d32f2f;
+    font-size: 0.875rem;
+    margin-top: 0.5rem;
+  }
+`;
+
+function EmailField() {
+  return (
+    <SuprForm.Control
+      name='email'
+      label='Email'
+      rules={{ required: 'Email is required' }}
+      className={StyledField}
+    >
+      <input type='email' />
+    </SuprForm.Control>
   );
 }
 ```
 
 ## Publishing
 
-To publish a new version to the npm registry:
+To publish a new version to npm:
 
 1. Ensure you are logged in to npm:
 
@@ -82,150 +224,128 @@ To publish a new version to the npm registry:
 npm login
 ```
 
-2. Build the package (also runs automatically via `prepublishOnly`):
+2. Build the package (runs automatically via `prepublishOnly`):
 
 ```bash
 npm run build
 ```
 
-3. Bump the version in `package.json` and publish:
+3. Bump the version and publish:
 
 ```bash
 npm version patch   # or minor/major
-npm publish --access public
+npm publish --access public --otp=XXXXXX
 ```
 
+(Replace `XXXXXX` with your 2FA code if you have 2FA enabled.)
+
 The published package contains only the compiled `dist/` files with ESM/CJS builds and TypeScript declarations.
 
-## Using useField Hook
+## Validation Rules
 
-For simpler field management, use the `useField` hook:
+All validation rules come from **react-hook-form**. Pass them directly to the `rules` prop:
 
 ```tsx
-import { useForm, useField, required } from 'suprform';
-
-function TextField({ name, label, form }) {
-  const { field, meta } = useField({ name, form });
+<SuprForm.Control
+  name='age'
+  rules={{
+    required: 'Age is required',
+    min: { value: 18, message: 'Must be 18 or older' },
+    max: { value: 120, message: 'Please enter a valid age' },
+  }}
+>
+  <input type='number' />
+</SuprForm.Control>
+```
 
-  return (
-    <div>
-      <label>{label}</label>
-      <input
-        value={field.value || ''}
-        onChange={(e) => field.onChange(e.target.value)}
-        onBlur={field.onBlur}
-      />
-      {meta.touched && meta.error && <span>{meta.error}</span>}
-    </div>
-  );
-}
+### Common Rules
 
-function MyForm() {
-  const form = useForm({
-    initialValues: { name: '', email: '' },
-    onSubmit: (values) => console.log(values),
-  });
+- `required` / `required: "message"` - Field must not be empty
+- `minLength: { value: 5, message: "..." }` - Minimum string length
+- `maxLength: { value: 20, message: "..." }` - Maximum string length
+- `min: { value: 0, message: "..." }` - Minimum numeric value
+- `max: { value: 100, message: "..." }` - Maximum numeric value
+- `pattern: { value: /regex/, message: "..." }` - Match a regex pattern
+- `validate: (value) => true || "error message"` - Custom synchronous validation
+- `validate: async (value) => true || "error message"` - Custom async validation
 
-  form.registerField('name', {
-    validators: [{ rule: required() }],
-  });
+### Custom Validation Example
 
-  return (
-    <form
-      onSubmit={(e) => {
-        e.preventDefault();
-        form.submitForm();
-      }}
-    >
-      <TextField name='name' label='Name' form={form} />
-      <button type='submit'>Submit</button>
-    </form>
-  );
-}
+```tsx
+<SuprForm.Control
+  name='password'
+  rules={{
+    required: 'Password is required',
+    minLength: { value: 8, message: 'Must be at least 8 characters' },
+    validate: async (value) => {
+      const isCommon = await checkIfPasswordIsCommon(value);
+      return !isCommon || 'This password is too common';
+    },
+  }}
+>
+  <input type='password' />
+</SuprForm.Control>
 ```
 
-## Built-in Validators
-
-- `required(message?)` - Validates that a field is not empty
-- `minLength(min, message?)` - Validates minimum string length
-- `maxLength(max, message?)` - Validates maximum string length
-- `email(message?)` - Validates email format
-- `pattern(regex, message?)` - Validates against a regex pattern
-- `min(value, message?)` - Validates minimum numeric value
-- `max(value, message?)` - Validates maximum numeric value
-- `matches(fieldName, message?)` - Validates that a field matches another field
-- `combine(...validators)` - Combines multiple validators
+## API Reference
 
-## Custom Validators
+### SuprForm Component
 
-Create custom validators easily:
+The root form wrapper (powered by `FormProvider` from react-hook-form).
 
-```tsx
-import { ValidationRule } from 'suprform';
+**Props:**
 
-const isStrongPassword: ValidationRule = (value: string) => {
-  if (!value) return undefined;
+- `children` - Form fields and elements
+- `onSubmit` - Handler called with form values when form is valid
+- `className` - CSS class for the `<form>` element
+- `style` - Inline styles for the `<form>` element
+- `formOptions` - Options passed to react-hook-form's `useForm()` hook
 
-  const hasUpperCase = /[A-Z]/.test(value);
-  const hasLowerCase = /[a-z]/.test(value);
-  const hasNumbers = /\d/.test(value);
-  const hasSpecialChar = /[!@#$%^&*]/.test(value);
+**Example:**
 
-  if (!hasUpperCase || !hasLowerCase || !hasNumbers || !hasSpecialChar) {
-    return 'Password must contain uppercase, lowercase, numbers, and special characters';
-  }
-
-  return undefined;
-};
-
-// Use in your form
-form.registerField('password', {
-  validators: [{ rule: isStrongPassword }],
-});
+```tsx
+<SuprForm
+  onSubmit={(values) => console.log(values)}
+  formOptions={{
+    mode: 'onBlur', // Validate on blur instead of on change
+    reValidateMode: 'onChange',
+  }}
+>
+  {/* controls */}
+</SuprForm>
 ```
 
-## API Reference
+### SuprForm.Control Component
 
-### useForm(config)
+Composable field control component that wraps your input elements.
 
-Creates a form instance with state management and validation.
+**Props:**
 
-**Parameters:**
+- `name` - Field name (must match form values)
+- `label` - Optional label text (rendered above input with `htmlFor` linking)
+- `children` - Your input component (any React element)
+- `rules` - Validation rules (react-hook-form's `RegisterOptions`)
+- `className` - CSS class for the wrapper div
 
-- `config.initialValues` - Initial form values
-- `config.onSubmit` - Submit handler function
-- `config.validateOnChange` - Validate fields on change (default: true)
-- `config.validateOnBlur` - Validate fields on blur (default: true)
+**Example:**
 
-**Returns:**
+```tsx
+<SuprForm.Control
+  name='email'
+  label='Email'
+  rules={{ required: 'Email is required' }}
+  className='form-field'
+>
+  <input type='email' />
+</SuprForm.Control>
+```
+
+**Automatic Features:**
 
-- `values` - Current form values
-- `errors` - Field errors
-- `touched` - Touched field states
-- `dirty` - Whether form has been modified
-- `submitting` - Whether form is being submitted
-- `submitCount` - Number of submission attempts
-- `isValid` - Whether form is valid
-- `setFieldValue(name, value)` - Set a field value
-- `setFieldError(name, error)` - Set a field error
-- `setFieldTouched(name, touched)` - Set field touched state
-- `resetForm()` - Reset form to initial state
-- `validateField(name)` - Validate a single field
-- `validateForm()` - Validate all fields
-- `submitForm()` - Submit the form
-- `getFieldState(name)` - Get field state
-- `getFieldHandlers(name)` - Get field handlers
-- `registerField(name, config)` - Register a field
-- `unregisterField(name)` - Unregister a field
-
-### useField(props)
-
-Hook for managing individual fields.
-
-**Parameters:**
-
-- `name` - Field name
-- `form` - Form instance from useForm
+- Renders `<label>` when `label` prop is provided
+- Displays error message below input (in red, styled as `.controlled-field-error`)
+- Injects `name`, `value`, `onChange`, `onBlur`, and `error` props to child input
+- Handles field state automatically (touched, dirty, valid)
 - `defaultValue` - Default field value
 - `validators` - Array of validators
 

package/dist/components/form/SuprForm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SuprForm.d.ts","sourceRoot":"","sources":["../../../src/components/form/SuprForm.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAC1C,OAAO,EAKL,WAAW,EACX,SAAS,EACV,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAwB,MAAM,QAAQ,CAAC;AAE/E,KAAK,YAAY,GAAG,CAAC,YAAY,SAAS,WAAW,GAAG,WAAW,EACjE,KAAK,EAAE,aAAa,CAAC,YAAY,CAAC,KAC/B,YAAY,CAAC;AAElB,KAAK,iBAAiB,GAAG,YAAY,GAAG;IACtC,OAAO,EAAE,CACP,YAAY,SAAS,WAAW,GAAG,WAAW,EAC9C,KAAK,SAAS,SAAS,CAAC,YAAY,CAAC,GAAG,SAAS,CAAC,YAAY,CAAC,EAE/D,KAAK,EAAE,gBAAgB,CAAC,YAAY,EAAE,KAAK,CAAC,KACzC,YAAY,CAAC;CACnB,CAAC;AAEF,QAAA,MAAM,QAAQ,EAAE,iBA0Bf,CAAC;AAsEF,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"SuprForm.d.ts","sourceRoot":"","sources":["../../../src/components/form/SuprForm.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAC1C,OAAO,EAKL,WAAW,EACX,SAAS,EACV,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAwB,MAAM,QAAQ,CAAC;AAE/E,KAAK,YAAY,GAAG,CAAC,YAAY,SAAS,WAAW,GAAG,WAAW,EACjE,KAAK,EAAE,aAAa,CAAC,YAAY,CAAC,KAC/B,YAAY,CAAC;AAElB,KAAK,iBAAiB,GAAG,YAAY,GAAG;IACtC,OAAO,EAAE,CACP,YAAY,SAAS,WAAW,GAAG,WAAW,EAC9C,KAAK,SAAS,SAAS,CAAC,YAAY,CAAC,GAAG,SAAS,CAAC,YAAY,CAAC,EAE/D,KAAK,EAAE,gBAAgB,CAAC,YAAY,EAAE,KAAK,CAAC,KACzC,YAAY,CAAC;CACnB,CAAC;AAEF,QAAA,MAAM,QAAQ,EAAE,iBA0Bf,CAAC;AAgGF,eAAe,QAAQ,CAAC"}

package/dist/components/form/type.d.ts

@@ -12,10 +12,15 @@ export interface FormControlProps<TFieldValues extends FieldValues = FieldValues
     rules?: RegisterOptions<TFieldValues, TName>;
     name: TName;
     label?: string;
+    className?: string;
+    id?: string;
 }
 export interface ControlledFieldProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> {
     field: ControllerRenderProps<TFieldValues, TName>;
     fieldState: ControllerFieldState;
     children: ReactElement<any>;
+    className?: string;
+    label?: string;
+    id?: string;
 }
 //# sourceMappingURL=type.d.ts.map

package/dist/components/form/type.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"type.d.ts","sourceRoot":"","sources":["../../../src/components/form/type.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAChD,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,WAAW,EACX,SAAS,EACT,eAAe,EACf,aAAa,EACb,YAAY,EACb,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,aAAa,CAAC,YAAY,SAAS,WAAW,GAAG,WAAW;IAC3E,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;IACvC,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,YAAY,CAAC,YAAY,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,gBAAgB,CAC/B,YAAY,SAAS,WAAW,GAAG,WAAW,EAC9C,KAAK,SAAS,SAAS,CAAC,YAAY,CAAC,GAAG,SAAS,CAAC,YAAY,CAAC;IAE/D,QAAQ,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC;IAC5B,KAAK,CAAC,EAAE,eAAe,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;IAC7C,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB,CACnC,YAAY,SAAS,WAAW,GAAG,WAAW,EAC9C,KAAK,SAAS,SAAS,CAAC,YAAY,CAAC,GAAG,SAAS,CAAC,YAAY,CAAC;IAE/D,KAAK,EAAE,qBAAqB,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;IAClD,UAAU,EAAE,oBAAoB,CAAC;IACjC,QAAQ,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC;CAC7B"}
+{"version":3,"file":"type.d.ts","sourceRoot":"","sources":["../../../src/components/form/type.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAChD,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,WAAW,EACX,SAAS,EACT,eAAe,EACf,aAAa,EACb,YAAY,EACb,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,aAAa,CAAC,YAAY,SAAS,WAAW,GAAG,WAAW;IAC3E,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;IACvC,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,YAAY,CAAC,YAAY,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,gBAAgB,CAC/B,YAAY,SAAS,WAAW,GAAG,WAAW,EAC9C,KAAK,SAAS,SAAS,CAAC,YAAY,CAAC,GAAG,SAAS,CAAC,YAAY,CAAC;IAE/D,QAAQ,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC;IAC5B,KAAK,CAAC,EAAE,eAAe,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;IAC7C,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,oBAAoB,CACnC,YAAY,SAAS,WAAW,GAAG,WAAW,EAC9C,KAAK,SAAS,SAAS,CAAC,YAAY,CAAC,GAAG,SAAS,CAAC,YAAY,CAAC;IAE/D,KAAK,EAAE,qBAAqB,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;IAClD,UAAU,EAAE,oBAAoB,CAAC;IACjC,QAAQ,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;CACb"}