@bookinglab/booking-ui-react 1.0.3 → 1.2.0

package/README.md

@@ -182,6 +182,167 @@ type FormValues = Record<number, string | number | boolean>;
 - Error messages display after field is touched
 - Hidden conditional fields are excluded from validation
 
+---
+
+## RegistrationForm
+
+A reusable, accessible registration form component with built-in validation, customizable fields, and programmatic control.
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `fields` | `FieldConfig[]` | Default fields | Custom field configuration |
+| `additionalFields` | `FieldConfig[]` | `undefined` | Extra fields appended after default/custom fields |
+| `onSubmit` | `(values: FormValues) => void` | required | Callback fired when form is submitted with valid values |
+| `onChange` | `(values: FormValues, isValid: boolean) => void` | `undefined` | Callback fired on every field change |
+| `validateOnBlur` | `boolean` | `true` | Whether to validate fields on blur |
+| `submitLabel` | `string` | `"Submit"` | Text for the submit button |
+| `className` | `string` | `""` | Class name for the form element |
+| `classNames` | `RegistrationFormClassNames` | `undefined` | Custom class names for styling |
+
+### Default Fields
+
+| Field | Label | Type | Required | Validation |
+|-------|-------|------|----------|------------|
+| `firstName` | First name | text | Yes | required |
+| `lastName` | Last name | text | Yes | required |
+| `email` | Email address | email | Yes | required, email format |
+| `phone` | Contact number | tel | No | phone format (if provided) |
+| `address1` | Address 1 | text | Yes | required |
+| `address2` | Address 2 | text | No | none |
+| `city` | Town/City | text | Yes | required |
+| `postcode` | Postcode | text | Yes | required, UK postcode |
+
+### Custom Fields
+
+Override default fields by passing a `fields` prop:
+
+```tsx
+import { RegistrationForm, FieldConfig } from '@bookinglab/booking-ui-react';
+
+const customFields: FieldConfig[] = [
+  { name: 'username', label: 'Username', type: 'text', required: true },
+  { name: 'email', label: 'Email', type: 'email', required: true },
+  { 
+    name: 'age', 
+    label: 'Age', 
+    type: 'text', 
+    validate: (value) => {
+      const num = parseInt(value, 10);
+      if (isNaN(num) || num < 18) return 'Must be 18 or older';
+      return null;
+    }
+  },
+];
+
+<RegistrationForm fields={customFields} onSubmit={handleSubmit} />
+```
+
+### Additional Fields
+
+Append extra fields after the defaults using `additionalFields`:
+
+```tsx
+import { RegistrationForm, FieldConfig } from '@bookinglab/booking-ui-react';
+
+const extraFields: FieldConfig[] = [
+  { name: 'company', label: 'Company Name', type: 'text' },
+  {
+    name: 'service',
+    label: 'Service Type',
+    type: 'select',
+    required: true,
+    options: [
+      { id: 1, name: 'Consultation', price: 0, is_default: true },
+      { id: 2, name: 'Premium Support', price: 50 },
+      { id: 3, name: 'Enterprise', price: 200 },
+    ],
+  },
+];
+
+<RegistrationForm additionalFields={extraFields} onSubmit={handleSubmit} />
+```
+
+### Select Field Options
+
+Select fields accept an `options` array with the following structure:
+
+```typescript
+interface FieldOption {
+  id: number | string;    // Unique identifier (submitted as the value)
+  name: string;           // Display text
+  price?: number;         // Optional price modifier (displayed as "+£X")
+  is_default?: boolean;   // Pre-select this option
+}
+```
+
+### Ref Methods
+
+Access imperative methods via `ref`:
+
+```tsx
+import { useRef } from 'react';
+import { RegistrationForm, RegistrationFormRef } from '@bookinglab/booking-ui-react';
+
+function MyComponent() {
+  const formRef = useRef<RegistrationFormRef>(null);
+
+  return (
+    <>
+      <RegistrationForm ref={formRef} onSubmit={handleSubmit} />
+      <button onClick={() => formRef.current?.reset()}>Reset Form</button>
+      <button onClick={() => formRef.current?.setValues({ email: 'test@example.com' })}>
+        Pre-fill Email
+      </button>
+    </>
+  );
+}
+```
+
+| Method | Description |
+|--------|-------------|
+| `reset()` | Clear all values, errors, and touched state |
+| `setValues(values)` | Programmatically set field values |
+
+### Styling
+
+Override styles using the `classNames` prop:
+
+```tsx
+<RegistrationForm
+  onSubmit={handleSubmit}
+  classNames={{
+    fieldWrapper: 'mb-6',
+    label: 'text-white font-bold',
+    input: 'border-2 border-gray-400 rounded-lg p-3',
+    inputError: 'border-red-500',
+    errorText: 'text-red-400 text-sm',
+    button: 'bg-primary text-white py-3 px-6 rounded-lg',
+  }}
+/>
+```
+
+### Validators
+
+The package exports reusable validators:
+
+```typescript
+import { required, email, phone, ukPostcode, minLen, compose } from '@bookinglab/booking-ui-react';
+
+// Use in custom fields
+const fields = [
+  {
+    name: 'password',
+    label: 'Password',
+    type: 'text',
+    validate: compose(required, minLen(8)),
+  },
+];
+```
+
+---
+
 ## Requirements
 
 - React 17.0.0 or higher
@@ -200,6 +361,13 @@ import type {
   FormErrors,
   BookingFormProps,
   BookingFormClassNames,
+  FieldConfig,
+  FieldOption,
+  RegistrationFormProps,
+  RegistrationFormRef,
+  RegistrationFormValues,
+  RegistrationFormErrors,
+  RegistrationFormClassNames,
 } from '@bookinglab/booking-ui-react';
 ```
 

package/dist/index.d.cts

@@ -1,4 +1,95 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+
+/**
+ * Option for select fields
+ */
+interface FieldOption {
+    /** Option display name */
+    name: string;
+    /** Option price (if applicable) */
+    price?: number;
+    /** Whether this is the default option */
+    is_default?: boolean;
+    /** Unique option ID */
+    id: number | string;
+}
+/**
+ * Configuration for a single form field
+ */
+interface FieldConfig {
+    /** Unique field name (used as key in values object) */
+    name: string;
+    /** Display label for the field */
+    label: string;
+    /** Input type */
+    type: 'text' | 'email' | 'tel' | 'select';
+    /** Whether the field is required */
+    required?: boolean;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Custom validation function - returns error message or null */
+    validate?: (value: string) => string | null;
+    /** Options for select fields */
+    options?: FieldOption[];
+}
+/**
+ * Form values keyed by field name
+ */
+type RegistrationFormValues = Record<string, string>;
+/**
+ * Form errors keyed by field name
+ */
+type RegistrationFormErrors = Record<string, string>;
+/**
+ * Custom class names for styling form elements
+ */
+interface RegistrationFormClassNames {
+    /** Wrapper for each form field */
+    fieldWrapper?: string;
+    /** All labels */
+    label?: string;
+    /** All input elements */
+    input?: string;
+    /** Input elements in error state */
+    inputError?: string;
+    /** Help text below fields */
+    helpText?: string;
+    /** Error message text */
+    errorText?: string;
+    /** Submit button */
+    button?: string;
+}
+/**
+ * Props for the RegistrationForm component
+ */
+interface RegistrationFormProps {
+    /** Custom field configuration (overrides defaults) */
+    fields?: FieldConfig[];
+    /** Additional fields to append after default fields */
+    additionalFields?: FieldConfig[];
+    /** Callback fired when form is submitted with valid values */
+    onSubmit: (values: RegistrationFormValues) => void;
+    /** Callback fired on every field change */
+    onChange?: (values: RegistrationFormValues, isValid: boolean) => void;
+    /** Whether to validate on blur (default: true) */
+    validateOnBlur?: boolean;
+    /** Text for the submit button */
+    submitLabel?: string;
+    /** Class name for the form element */
+    className?: string;
+    /** Custom class names for styling individual elements */
+    classNames?: RegistrationFormClassNames;
+}
+/**
+ * Imperative handle methods exposed via ref
+ */
+interface RegistrationFormRef {
+    /** Reset all form values and errors */
+    reset: () => void;
+    /** Programmatically set form values */
+    setValues: (values: Partial<RegistrationFormValues>) => void;
+}
 
 interface QuestionOption {
     id: number;
@@ -90,4 +181,65 @@ interface BookingUIConfig {
  */
 declare function BookingForm({ questions, onSubmit, submitLabel, className, labelClassName, classNames: classNamesProp, }: BookingFormProps): react_jsx_runtime.JSX.Element;
 
-export { BookingForm, type BookingFormClassNames, type BookingFormProps, type BookingUIConfig, type FormErrors, type FormValues, type Question, type QuestionOption, type QuestionSettings };
+/**
+ * A reusable, accessible registration form component.
+ *
+ * Features:
+ * - Customizable fields via props
+ * - Built-in validation with blur and submit triggers
+ * - Full accessibility support (ARIA attributes, keyboard navigation)
+ * - Imperative handle for programmatic control (reset, setValues)
+ * - Granular styling via classNames prop
+ *
+ * @example
+ * ```tsx
+ * const formRef = useRef<RegistrationFormRef>(null);
+ *
+ * <RegistrationForm
+ *   ref={formRef}
+ *   onSubmit={(values) => console.log(values)}
+ *   onChange={(values, isValid) => console.log(isValid)}
+ *   submitLabel="Register"
+ * />
+ *
+ * // Programmatic control
+ * formRef.current?.reset();
+ * formRef.current?.setValues({ email: 'test@example.com' });
+ * ```
+ */
+declare const RegistrationForm: React.ForwardRefExoticComponent<RegistrationFormProps & React.RefAttributes<RegistrationFormRef>>;
+
+/**
+ * Validation helper functions for form fields
+ * Each validator returns an error message string if invalid, or null if valid
+ */
+/**
+ * Validates that a value is not empty
+ */
+declare function required(value: string): string | null;
+/**
+ * Validates email format (RFC 5322 compliant)
+ */
+declare function email(value: string): string | null;
+/**
+ * Validates phone number format (international)
+ * Accepts formats like: +44 1234 567890, 01onal234 567890, +1-234-567-8900
+ */
+declare function phone(value: string): string | null;
+/**
+ * Validates UK postcode format
+ * Accepts formats like: SW1A 1AA, SW1A1AA, M1 1AA, B33 8TH
+ */
+declare function ukPostcode(value: string): string | null;
+/**
+ * Creates a minimum length validator
+ * @param min - Minimum number of characters required
+ */
+declare function minLen(min: number): (value: string) => string | null;
+/**
+ * Combines multiple validators into one
+ * Returns the first error encountered, or null if all pass
+ */
+declare function compose(...validators: Array<(value: string) => string | null>): (value: string) => string | null;
+
+export { BookingForm, type BookingFormClassNames, type BookingFormProps, type BookingUIConfig, type FieldConfig, type FieldOption, type FormErrors, type FormValues, type Question, type QuestionOption, type QuestionSettings, RegistrationForm, type RegistrationFormClassNames, type RegistrationFormErrors, type RegistrationFormProps, type RegistrationFormRef, type RegistrationFormValues, compose, email, minLen, phone, required, ukPostcode };

package/dist/index.d.ts

@@ -1,4 +1,95 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+
+/**
+ * Option for select fields
+ */
+interface FieldOption {
+    /** Option display name */
+    name: string;
+    /** Option price (if applicable) */
+    price?: number;
+    /** Whether this is the default option */
+    is_default?: boolean;
+    /** Unique option ID */
+    id: number | string;
+}
+/**
+ * Configuration for a single form field
+ */
+interface FieldConfig {
+    /** Unique field name (used as key in values object) */
+    name: string;
+    /** Display label for the field */
+    label: string;
+    /** Input type */
+    type: 'text' | 'email' | 'tel' | 'select';
+    /** Whether the field is required */
+    required?: boolean;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Custom validation function - returns error message or null */
+    validate?: (value: string) => string | null;
+    /** Options for select fields */
+    options?: FieldOption[];
+}
+/**
+ * Form values keyed by field name
+ */
+type RegistrationFormValues = Record<string, string>;
+/**
+ * Form errors keyed by field name
+ */
+type RegistrationFormErrors = Record<string, string>;
+/**
+ * Custom class names for styling form elements
+ */
+interface RegistrationFormClassNames {
+    /** Wrapper for each form field */
+    fieldWrapper?: string;
+    /** All labels */
+    label?: string;
+    /** All input elements */
+    input?: string;
+    /** Input elements in error state */
+    inputError?: string;
+    /** Help text below fields */
+    helpText?: string;
+    /** Error message text */
+    errorText?: string;
+    /** Submit button */
+    button?: string;
+}
+/**
+ * Props for the RegistrationForm component
+ */
+interface RegistrationFormProps {
+    /** Custom field configuration (overrides defaults) */
+    fields?: FieldConfig[];
+    /** Additional fields to append after default fields */
+    additionalFields?: FieldConfig[];
+    /** Callback fired when form is submitted with valid values */
+    onSubmit: (values: RegistrationFormValues) => void;
+    /** Callback fired on every field change */
+    onChange?: (values: RegistrationFormValues, isValid: boolean) => void;
+    /** Whether to validate on blur (default: true) */
+    validateOnBlur?: boolean;
+    /** Text for the submit button */
+    submitLabel?: string;
+    /** Class name for the form element */
+    className?: string;
+    /** Custom class names for styling individual elements */
+    classNames?: RegistrationFormClassNames;
+}
+/**
+ * Imperative handle methods exposed via ref
+ */
+interface RegistrationFormRef {
+    /** Reset all form values and errors */
+    reset: () => void;
+    /** Programmatically set form values */
+    setValues: (values: Partial<RegistrationFormValues>) => void;
+}
 
 interface QuestionOption {
     id: number;
@@ -90,4 +181,65 @@ interface BookingUIConfig {
  */
 declare function BookingForm({ questions, onSubmit, submitLabel, className, labelClassName, classNames: classNamesProp, }: BookingFormProps): react_jsx_runtime.JSX.Element;
 
-export { BookingForm, type BookingFormClassNames, type BookingFormProps, type BookingUIConfig, type FormErrors, type FormValues, type Question, type QuestionOption, type QuestionSettings };
+/**
+ * A reusable, accessible registration form component.
+ *
+ * Features:
+ * - Customizable fields via props
+ * - Built-in validation with blur and submit triggers
+ * - Full accessibility support (ARIA attributes, keyboard navigation)
+ * - Imperative handle for programmatic control (reset, setValues)
+ * - Granular styling via classNames prop
+ *
+ * @example
+ * ```tsx
+ * const formRef = useRef<RegistrationFormRef>(null);
+ *
+ * <RegistrationForm
+ *   ref={formRef}
+ *   onSubmit={(values) => console.log(values)}
+ *   onChange={(values, isValid) => console.log(isValid)}
+ *   submitLabel="Register"
+ * />
+ *
+ * // Programmatic control
+ * formRef.current?.reset();
+ * formRef.current?.setValues({ email: 'test@example.com' });
+ * ```
+ */
+declare const RegistrationForm: React.ForwardRefExoticComponent<RegistrationFormProps & React.RefAttributes<RegistrationFormRef>>;
+
+/**
+ * Validation helper functions for form fields
+ * Each validator returns an error message string if invalid, or null if valid
+ */
+/**
+ * Validates that a value is not empty
+ */
+declare function required(value: string): string | null;
+/**
+ * Validates email format (RFC 5322 compliant)
+ */
+declare function email(value: string): string | null;
+/**
+ * Validates phone number format (international)
+ * Accepts formats like: +44 1234 567890, 01onal234 567890, +1-234-567-8900
+ */
+declare function phone(value: string): string | null;
+/**
+ * Validates UK postcode format
+ * Accepts formats like: SW1A 1AA, SW1A1AA, M1 1AA, B33 8TH
+ */
+declare function ukPostcode(value: string): string | null;
+/**
+ * Creates a minimum length validator
+ * @param min - Minimum number of characters required
+ */
+declare function minLen(min: number): (value: string) => string | null;
+/**
+ * Combines multiple validators into one
+ * Returns the first error encountered, or null if all pass
+ */
+declare function compose(...validators: Array<(value: string) => string | null>): (value: string) => string | null;
+
+export { BookingForm, type BookingFormClassNames, type BookingFormProps, type BookingUIConfig, type FieldConfig, type FieldOption, type FormErrors, type FormValues, type Question, type QuestionOption, type QuestionSettings, RegistrationForm, type RegistrationFormClassNames, type RegistrationFormErrors, type RegistrationFormProps, type RegistrationFormRef, type RegistrationFormValues, compose, email, minLen, phone, required, ukPostcode };