@bookinglab/booking-ui-react 1.3.0 → 1.5.0

package/README.md

@@ -344,6 +344,143 @@ const fields = [
 
 ---
 
+## ContactDetailsForm
+
+A form component for collecting contact details (first name, last name, email) alongside optional dynamic questions. On submit, emits values with `q` and `answers` fields matching the JRNI Update Client / Member API format.
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `questions` | `Question[]` | `[]` | Additional questions to render after the contact fields |
+| `initialValues` | `ContactDetailsInitialValues` | `undefined` | Initial values for pre-populating the form |
+| `onSubmit` | `(values: ContactDetailsValues) => void` | required | Callback fired on valid submission |
+| `onChange` | `(values: Partial<ContactDetailsValues>, isValid: boolean) => void` | `undefined` | Callback fired on every field change |
+| `submitLabel` | `string` | `"Submit"` | Text for the submit button |
+| `validateOnBlur` | `boolean` | `true` | Whether to validate fields on blur |
+| `className` | `string` | `""` | Class name for the form element |
+| `classNames` | `ContactDetailsFormClassNames` | `undefined` | Custom class names for styling |
+| `fieldSettings` | `ContactDetailsFieldSettings` | `undefined` | Per-field required/disabled settings |
+
+### Default Fields
+
+| Field | Label | Required | Validation |
+|-------|-------|----------|------------|
+| `firstName` | First name | Yes | required |
+| `lastName` | Last name | Yes | required |
+| `email` | Email | Yes | required, email format |
+
+### Field Settings
+
+Control the `required` and `disabled` state of each default field:
+
+```tsx
+import { ContactDetailsForm } from '@bookinglab/booking-ui-react';
+
+<ContactDetailsForm
+  onSubmit={handleSubmit}
+  fieldSettings={{
+    firstName: { required: true, disabled: false },
+    lastName: { required: false },           // optional last name
+    email: { required: true, disabled: true }, // pre-filled, non-editable
+  }}
+/>
+```
+
+```typescript
+interface ContactFieldSettings {
+  required?: boolean;  // default: true
+  disabled?: boolean;  // default: false
+}
+
+interface ContactDetailsFieldSettings {
+  firstName?: ContactFieldSettings;
+  lastName?: ContactFieldSettings;
+  email?: ContactFieldSettings;
+}
+```
+
+### Initial Values
+
+Pre-populate the form with existing data using `initialValues`:
+
+```tsx
+<ContactDetailsForm
+  onSubmit={handleSubmit}
+  initialValues={{
+    firstName: 'Sarah',
+    lastName: 'Grey',
+    email: 'sarah@example.com',
+    questions: {
+      2: '5',    // select option ID as string
+      7: 25,     // number value
+      10: 'Wheelchair access needed',
+      12: true,  // checkbox
+    },
+  }}
+/>
+```
+
+```typescript
+interface ContactDetailsInitialValues {
+  firstName?: string;
+  lastName?: string;
+  email?: string;
+  questions?: Record<number, string | number | boolean>;
+}
+```
+
+When `reset()` is called via ref, the form restores to these initial values rather than empty fields.
+
+
+
+Pass additional questions to render after the contact fields:
+
+```tsx
+<ContactDetailsForm
+  questions={[
+    { id: 2, name: 'Purpose', detail_type: 'select', required: true,
+      options: [{ id: 5, name: 'School Trip' }, { id: 6, name: 'Corporate' }] },
+    { id: 7, name: 'Group Size', detail_type: 'number', required: true },
+  ]}
+  onSubmit={(values) => console.log(values)}
+/>
+```
+
+### Output Format
+
+The `onSubmit` callback receives a `ContactDetailsValues` object:
+
+```typescript
+interface ContactDetailsValues {
+  firstName: string;
+  lastName: string;
+  email: string;
+  q: Record<string, { answer: string; answer_id: number; name: string }>;
+  answers: { question_id: number; name: string; answer: string; answer_id: number }[];
+}
+```
+
+### Ref Methods
+
+```tsx
+import { useRef } from 'react';
+import { ContactDetailsForm, ContactDetailsFormRef } from '@bookinglab/booking-ui-react';
+
+const formRef = useRef<ContactDetailsFormRef>(null);
+
+<ContactDetailsForm ref={formRef} onSubmit={handleSubmit} />
+<button onClick={() => formRef.current?.reset()}>Reset</button>
+<button onClick={() => formRef.current?.setValues({ email: 'test@example.com' })}>Pre-fill</button>
+```
+
+| Method | Description |
+|--------|-------------|
+| `reset()` | Clear all values, errors, and touched state |
+| `setValues(values)` | Programmatically set contact detail values |
+
+---
+
 ## Requirements
 
 - React 17.0.0 or higher
@@ -369,6 +506,15 @@ import type {
   RegistrationFormValues,
   RegistrationFormErrors,
   RegistrationFormClassNames,
+  ContactDetailsFormProps,
+  ContactDetailsFormRef,
+  ContactDetailsValues,
+  ContactDetailsFormClassNames,
+  ContactDetailsQuestionEntry,
+  ContactDetailsAnswerEntry,
+  ContactDetailsFieldSettings,
+  ContactDetailsInitialValues,
+  ContactFieldSettings,
 } from '@bookinglab/booking-ui-react';
 ```
 

package/dist/index.d.cts

@@ -91,6 +91,133 @@ interface RegistrationFormRef {
     setValues: (values: Partial<RegistrationFormValues>) => void;
 }
 
+/**
+ * Entry in the `q` record, keyed by question ID string
+ */
+interface ContactDetailsQuestionEntry {
+    /** The answer value (option name for selects, raw value for others) */
+    answer: string;
+    /** The selected option ID for selects, or 0 for text/number/other fields */
+    answer_id: number;
+    /** The question's display name */
+    name: string;
+}
+/**
+ * Entry in the `answers` array
+ */
+interface ContactDetailsAnswerEntry {
+    /** The question ID */
+    question_id: number;
+    /** The question's display name */
+    name: string;
+    /** The answer value */
+    answer: string;
+    /** The selected option ID for selects, or 0 for text/number/other fields */
+    answer_id: number;
+}
+/**
+ * Values emitted by ContactDetailsForm on submit.
+ * The `q` and `answers` fields match the JRNI Update Client/Member API format.
+ */
+interface ContactDetailsValues {
+    firstName: string;
+    lastName: string;
+    email: string;
+    /** Questions keyed by question ID string */
+    q: Record<string, ContactDetailsQuestionEntry>;
+    /** Questions as an array of answer entries */
+    answers: ContactDetailsAnswerEntry[];
+}
+/**
+ * Custom class names for styling ContactDetailsForm elements
+ */
+interface ContactDetailsFormClassNames {
+    /** Wrapper for each form field */
+    fieldWrapper?: string;
+    /** All labels */
+    label?: string;
+    /** Heading elements */
+    heading?: string;
+    /** All input elements (text, textarea, select, date, number) */
+    input?: string;
+    /** Input elements in error state */
+    inputError?: string;
+    /** Checkbox input specifically */
+    checkbox?: string;
+    /** Help text below fields */
+    helpText?: string;
+    /** Error message text */
+    errorText?: string;
+    /** Submit button */
+    button?: string;
+}
+/**
+ * Per-field settings for a default contact field (firstName, lastName, email)
+ */
+interface ContactFieldSettings {
+    /** Whether the field is required (default: true for all) */
+    required?: boolean;
+    /** Whether the field is disabled */
+    disabled?: boolean;
+}
+/**
+ * Settings for the default contact detail fields
+ */
+interface ContactDetailsFieldSettings {
+    firstName?: ContactFieldSettings;
+    lastName?: ContactFieldSettings;
+    email?: ContactFieldSettings;
+}
+/**
+ * Initial values for pre-populating the form
+ */
+interface ContactDetailsInitialValues {
+    /** Initial first name value */
+    firstName?: string;
+    /** Initial last name value */
+    lastName?: string;
+    /** Initial email value */
+    email?: string;
+    /** Initial question values keyed by question ID */
+    questions?: Record<number, string | number | boolean>;
+}
+/**
+ * Props for the ContactDetailsForm component
+ */
+interface ContactDetailsFormProps {
+    /** Additional questions to render after the contact fields */
+    questions?: Question[];
+    /** Initial values for pre-populating the form fields */
+    initialValues?: ContactDetailsInitialValues;
+    /** Callback fired when form is submitted with valid values */
+    onSubmit: (values: ContactDetailsValues) => void;
+    /** Callback fired on every field change */
+    onChange?: (values: Partial<ContactDetailsValues>, isValid: boolean) => void;
+    /** Text for the submit button (default: "Submit") */
+    submitLabel?: string;
+    /** Whether to validate on blur (default: true) */
+    validateOnBlur?: boolean;
+    /** Class name for the form element */
+    className?: string;
+    /** Custom class names for styling individual elements */
+    classNames?: ContactDetailsFormClassNames;
+    /** Per-field settings for the default contact fields (required, disabled) */
+    fieldSettings?: ContactDetailsFieldSettings;
+}
+/**
+ * Imperative handle methods exposed via ref
+ */
+interface ContactDetailsFormRef {
+    /** Reset all form values and errors */
+    reset: () => void;
+    /** Programmatically set contact detail values */
+    setValues: (values: Partial<{
+        firstName: string;
+        lastName: string;
+        email: string;
+    }>) => void;
+}
+
 interface QuestionOption {
     id: number;
     name: string;
@@ -209,6 +336,25 @@ declare function BookingForm({ questions, onSubmit, submitLabel, className, labe
  */
 declare const RegistrationForm: React.ForwardRefExoticComponent<RegistrationFormProps & React.RefAttributes<RegistrationFormRef>>;
 
+/**
+ * ContactDetailsForm — collects first name, last name, email and optional
+ * dynamic questions. On submit it emits values with `q` and `answers` fields
+ * matching the JRNI Update Client / Member API format.
+ *
+ * @example
+ * ```tsx
+ * <ContactDetailsForm
+ *   questions={[
+ *     { id: 2, name: 'Purpose', detail_type: 'select', required: true,
+ *       options: [{ id: 5, name: 'School Trip' }, { id: 6, name: 'Corporate' }] },
+ *     { id: 7, name: 'Group Size', detail_type: 'number', required: true },
+ *   ]}
+ *   onSubmit={(values) => console.log(values)}
+ * />
+ * ```
+ */
+declare const ContactDetailsForm: React.ForwardRefExoticComponent<ContactDetailsFormProps & React.RefAttributes<ContactDetailsFormRef>>;
+
 /**
  * Validation helper functions for form fields
  * Each validator returns an error message string if invalid, or null if valid
@@ -242,4 +388,4 @@ declare function minLen(min: number): (value: string) => string | null;
  */
 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 };
+export { BookingForm, type BookingFormClassNames, type BookingFormProps, type BookingUIConfig, type ContactDetailsAnswerEntry, type ContactDetailsFieldSettings, ContactDetailsForm, type ContactDetailsFormClassNames, type ContactDetailsFormProps, type ContactDetailsFormRef, type ContactDetailsInitialValues, type ContactDetailsQuestionEntry, type ContactDetailsValues, type ContactFieldSettings, 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

@@ -91,6 +91,133 @@ interface RegistrationFormRef {
     setValues: (values: Partial<RegistrationFormValues>) => void;
 }
 
+/**
+ * Entry in the `q` record, keyed by question ID string
+ */
+interface ContactDetailsQuestionEntry {
+    /** The answer value (option name for selects, raw value for others) */
+    answer: string;
+    /** The selected option ID for selects, or 0 for text/number/other fields */
+    answer_id: number;
+    /** The question's display name */
+    name: string;
+}
+/**
+ * Entry in the `answers` array
+ */
+interface ContactDetailsAnswerEntry {
+    /** The question ID */
+    question_id: number;
+    /** The question's display name */
+    name: string;
+    /** The answer value */
+    answer: string;
+    /** The selected option ID for selects, or 0 for text/number/other fields */
+    answer_id: number;
+}
+/**
+ * Values emitted by ContactDetailsForm on submit.
+ * The `q` and `answers` fields match the JRNI Update Client/Member API format.
+ */
+interface ContactDetailsValues {
+    firstName: string;
+    lastName: string;
+    email: string;
+    /** Questions keyed by question ID string */
+    q: Record<string, ContactDetailsQuestionEntry>;
+    /** Questions as an array of answer entries */
+    answers: ContactDetailsAnswerEntry[];
+}
+/**
+ * Custom class names for styling ContactDetailsForm elements
+ */
+interface ContactDetailsFormClassNames {
+    /** Wrapper for each form field */
+    fieldWrapper?: string;
+    /** All labels */
+    label?: string;
+    /** Heading elements */
+    heading?: string;
+    /** All input elements (text, textarea, select, date, number) */
+    input?: string;
+    /** Input elements in error state */
+    inputError?: string;
+    /** Checkbox input specifically */
+    checkbox?: string;
+    /** Help text below fields */
+    helpText?: string;
+    /** Error message text */
+    errorText?: string;
+    /** Submit button */
+    button?: string;
+}
+/**
+ * Per-field settings for a default contact field (firstName, lastName, email)
+ */
+interface ContactFieldSettings {
+    /** Whether the field is required (default: true for all) */
+    required?: boolean;
+    /** Whether the field is disabled */
+    disabled?: boolean;
+}
+/**
+ * Settings for the default contact detail fields
+ */
+interface ContactDetailsFieldSettings {
+    firstName?: ContactFieldSettings;
+    lastName?: ContactFieldSettings;
+    email?: ContactFieldSettings;
+}
+/**
+ * Initial values for pre-populating the form
+ */
+interface ContactDetailsInitialValues {
+    /** Initial first name value */
+    firstName?: string;
+    /** Initial last name value */
+    lastName?: string;
+    /** Initial email value */
+    email?: string;
+    /** Initial question values keyed by question ID */
+    questions?: Record<number, string | number | boolean>;
+}
+/**
+ * Props for the ContactDetailsForm component
+ */
+interface ContactDetailsFormProps {
+    /** Additional questions to render after the contact fields */
+    questions?: Question[];
+    /** Initial values for pre-populating the form fields */
+    initialValues?: ContactDetailsInitialValues;
+    /** Callback fired when form is submitted with valid values */
+    onSubmit: (values: ContactDetailsValues) => void;
+    /** Callback fired on every field change */
+    onChange?: (values: Partial<ContactDetailsValues>, isValid: boolean) => void;
+    /** Text for the submit button (default: "Submit") */
+    submitLabel?: string;
+    /** Whether to validate on blur (default: true) */
+    validateOnBlur?: boolean;
+    /** Class name for the form element */
+    className?: string;
+    /** Custom class names for styling individual elements */
+    classNames?: ContactDetailsFormClassNames;
+    /** Per-field settings for the default contact fields (required, disabled) */
+    fieldSettings?: ContactDetailsFieldSettings;
+}
+/**
+ * Imperative handle methods exposed via ref
+ */
+interface ContactDetailsFormRef {
+    /** Reset all form values and errors */
+    reset: () => void;
+    /** Programmatically set contact detail values */
+    setValues: (values: Partial<{
+        firstName: string;
+        lastName: string;
+        email: string;
+    }>) => void;
+}
+
 interface QuestionOption {
     id: number;
     name: string;
@@ -209,6 +336,25 @@ declare function BookingForm({ questions, onSubmit, submitLabel, className, labe
  */
 declare const RegistrationForm: React.ForwardRefExoticComponent<RegistrationFormProps & React.RefAttributes<RegistrationFormRef>>;
 
+/**
+ * ContactDetailsForm — collects first name, last name, email and optional
+ * dynamic questions. On submit it emits values with `q` and `answers` fields
+ * matching the JRNI Update Client / Member API format.
+ *
+ * @example
+ * ```tsx
+ * <ContactDetailsForm
+ *   questions={[
+ *     { id: 2, name: 'Purpose', detail_type: 'select', required: true,
+ *       options: [{ id: 5, name: 'School Trip' }, { id: 6, name: 'Corporate' }] },
+ *     { id: 7, name: 'Group Size', detail_type: 'number', required: true },
+ *   ]}
+ *   onSubmit={(values) => console.log(values)}
+ * />
+ * ```
+ */
+declare const ContactDetailsForm: React.ForwardRefExoticComponent<ContactDetailsFormProps & React.RefAttributes<ContactDetailsFormRef>>;
+
 /**
  * Validation helper functions for form fields
  * Each validator returns an error message string if invalid, or null if valid
@@ -242,4 +388,4 @@ declare function minLen(min: number): (value: string) => string | null;
  */
 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 };
+export { BookingForm, type BookingFormClassNames, type BookingFormProps, type BookingUIConfig, type ContactDetailsAnswerEntry, type ContactDetailsFieldSettings, ContactDetailsForm, type ContactDetailsFormClassNames, type ContactDetailsFormProps, type ContactDetailsFormRef, type ContactDetailsInitialValues, type ContactDetailsQuestionEntry, type ContactDetailsValues, type ContactFieldSettings, 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 };