@bookinglab/booking-ui-react 1.10.0 → 1.11.1

package/dist/index.d.cts

@@ -301,6 +301,502 @@ interface ResetPasswordFormRef {
     setValues: (values: Partial<ResetPasswordFormValues>) => void;
 }
 
+interface FormSchemaResponse {
+    schema: {
+        type: 'extended' | 'legacy' | string;
+        form_name: string;
+        fields: RawSchemaField[];
+    };
+}
+
+interface ExtraItemProperties {
+    /** Booking extra item data including pricing details. */
+    data?: {
+        pmtTyp?: string;
+        [key: string]: unknown;
+    };
+    qty?: number;
+    field?: string;
+    [key: string]: unknown;
+}
+interface VenueResult {
+    pretty_name?: string;
+    venue_name: string;
+    venue_type?: string;
+    company_id?: string;
+    resource_id?: string;
+    description?: string;
+    image?: string;
+    [key: string]: unknown;
+}
+
+/**
+ * Runtime configuration for the booking API.
+ * Passed as a prop to SchemaFormBuilder and forwarded to all API calls.
+ */
+interface AppConfig {
+    /** Bearer token sent as the `clienttoken` HTTP header on all API requests. */
+    blApiToken: string;
+    /** The booking company ID for this council tenant. */
+    company_id: string;
+    /** The customer/client name identifier for schema resolution. */
+    customer_name: string;
+    /** Base URL of the Bookinglab API, e.g. `https://api.bookinglab.co.uk`. */
+    apiBaseUrl: string;
+}
+/**
+ * A string validation shorthand.
+ * - 'email'   → standard email format
+ * - 'mobile'  → UK mobile number
+ * - 'phone'   → UK landline/contact number
+ * - 'contact' → alias for phone
+ * - 'length'  → maxLength(255)
+ */
+type ValidationShorthand = 'email' | 'mobile' | 'phone' | 'contact' | 'length';
+interface ValidationMinLength {
+    minLength: number;
+}
+interface ValidationMaxLength {
+    maxLength: number;
+}
+interface ValidationMinDate {
+    /** Minimum allowed date in DD-MM-YYYY format. */
+    minDate: string;
+}
+interface ValidationMaxDate {
+    /** Maximum allowed date expressed as number of days from today. */
+    maxDate: number;
+}
+type ValidationRule = ValidationShorthand | ValidationMinLength | ValidationMaxLength | ValidationMinDate | ValidationMaxDate;
+/**
+ * A single condition clause used in custom rule types.
+ */
+interface ConditionClause {
+    /** The field name whose current value is evaluated. */
+    field: string;
+    /** The expected value to compare against. Use '*' as a wildcard (any non-empty value). */
+    value: string;
+    /**
+     * Comparison operator. Defaults to '==' if omitted.
+     * Numeric operators ('>', '<', '>=', '<=') cast both sides to Number before comparing.
+     */
+    operator?: '==' | '!=' | '>' | '<' | '>=' | '<=';
+}
+/**
+ * The `show` object on a field defines its conditional visibility rules.
+ * Multiple rule types can coexist on a single field.
+ * The final visibility is: ANY rule returning true → field is visible.
+ *
+ * Rule types:
+ *
+ * - `[fieldName]: expectedValue`      Simple equality rule. Field is visible when
+ *                                      `formValues[fieldName] === expectedValue`.
+ *                                      Use '*' as expectedValue to match any non-empty value.
+ *
+ * - `custom`                          Array of ConditionClause. ALL clauses must be true (AND).
+ *
+ * - `custom_multiple_condition`       A single group of ConditionClause. ALL must be true (AND).
+ *
+ * - `custom_multiple_conditions`      Array of ConditionClause groups. ANY group being fully
+ *                                      true makes the rule pass (OR between groups, AND within).
+ *
+ * - `custom_or_condition`             Array of ConditionClause. ANY single clause being true
+ *                                      passes the rule (OR logic).
+ *
+ * - `custom_all_lookups_successful`   No value needed. Passes only when every visible AWS lookup
+ *                                      field on the current page has `lookupSuccess === true`.
+ */
+interface ShowRules {
+    /** Object format: { fieldName: "expression" } or array of ConditionClause. AND logic. */
+    custom?: ConditionClause[] | Record<string, string>;
+    /** Object format: { conditions: [{ field: value }] } or ConditionClause[]. AND logic. */
+    custom_multiple_condition?: ConditionClause[] | {
+        conditions: Record<string, string>[];
+    };
+    /** Object format: { groups: [{ conditions: [...] }] } or ConditionClause[][]. OR-of-AND. */
+    custom_multiple_conditions?: ConditionClause[][] | {
+        groups: {
+            conditions: Record<string, string>[];
+        }[];
+    };
+    custom_or_condition?: ConditionClause[];
+    /** Value is irrelevant — presence of this key activates the all-lookups check. */
+    custom_all_lookups_successful?: unknown;
+    /** Any other key is treated as a simple field-name → expected-value equality rule. */
+    [fieldName: string]: unknown;
+}
+/**
+ * Declarative data copying between fields, including across pages via sessionStorage.
+ * When this field is visible and the optional `answer` condition is met,
+ * each `from[i]` field value is written to `to[i]`.
+ */
+interface CopyDataConfig {
+    /** Source field names (same page or a previous page stored in sessionStorage). */
+    from: string[];
+    /** Destination field names, index-aligned with `from`. */
+    to: string[];
+    /**
+     * If present, only copy when this field's current value strictly equals `answer`.
+     * If absent, copy whenever this field has any non-empty value.
+     */
+    answer?: string;
+}
+interface AwsLookupMatchEntry {
+    /**
+     * The form field name whose value provides the lookup value.
+     * The field whose `field` property matches the current field name is the primary reference.
+     */
+    form_field: string;
+    /** The DynamoDB attribute name to match against (e.g. 'home_office', 'name'). */
+    dynamodb_field: string;
+}
+interface AwsLookupConfig {
+    /** DynamoDB table name (environment suffix appended server-side, e.g. '-staging'). */
+    aws_table: string;
+    /**
+     * Fields participating in the lookup validation.
+     * The entry whose form_field matches this field's `field` property is the primary reference.
+     * Any other entries are secondary validations (e.g. name cross-check).
+     */
+    match: AwsLookupMatchEntry[];
+    /**
+     * If present, the form control value is set to `response.reference[store_response_field]`
+     * on a successful lookup instead of the default `response.reference.home_office`.
+     */
+    store_response_field?: string;
+}
+interface RadioOption {
+    /** The raw value stored in the form control when this option is selected. */
+    value: string;
+    /** Human-readable label rendered alongside the radio input. */
+    title: string;
+}
+interface DropdownOption {
+    value: string;
+    title: string;
+    /**
+     * If false, this option is excluded from the rendered select.
+     * Allows server-side control of available options without schema changes.
+     */
+    visible: boolean;
+}
+/**
+ * The field definition exactly as returned by the API.
+ * Do not mutate this shape. Hydrate into SchemaField after fetching.
+ */
+interface RawSchemaField {
+    /** Unique identifier. Maps 1:1 to a form control name. */
+    field: string;
+    /** Display label. May contain `{fieldName}` interpolation tokens. */
+    title: string;
+    type: 'text' | 'number' | 'email' | 'date' | 'textarea' | 'radio' | 'dropdown' | 'checkbox' | 'heading' | 'submit';
+    /**
+     * The route page slug this field belongs to (e.g. 'booking-details').
+     * Fields not matching the current page are skipped entirely.
+     */
+    page: string;
+    required?: boolean;
+    /**
+     * Hint text displayed below the label.
+     * May contain HTML — render with dangerouslySetInnerHTML.
+     */
+    helptext?: string;
+    /** Array of validation rules applied to this field's form control. */
+    validation?: ValidationRule[];
+    /**
+     * Conditional visibility rules. If absent or empty, the field is always visible.
+     * See ShowRules for the full rule type documentation.
+     */
+    show?: ShowRules;
+    radio_options?: RadioOption[];
+    options?: DropdownOption[];
+    /**
+     * Determines the visual treatment for `type === 'heading'` fields.
+     * Absent → standard h3 heading.
+     */
+    component_type?: 'govbook-information_box' | 'govbook-warning_box' | 'body';
+    /**
+     * Rich text body content for heading variants.
+     * Render with dangerouslySetInnerHTML.
+     */
+    component_text?: string;
+    /** If true, renders a postcode input + "Find address" button and an address select. */
+    address_lookup?: boolean;
+    lookup?: AwsLookupConfig;
+    /** If true, renders an autocomplete venue search input with typeahead. */
+    resource_lookup?: boolean;
+    /**
+     * Field name whose value is used to filter venue search results by `venue_type`.
+     * Only applies when `resource_lookup` is true.
+     */
+    filter_by?: string;
+    /** When this field becomes visible, emit `onCompanySet` with this company ID. */
+    company_set?: string;
+    /** When this field becomes visible, emit `onServiceSet` with this service ID. */
+    service_set?: string;
+    /** When this field becomes visible, emit `onResourceSet` with this resource ID. */
+    resource_set?: string;
+    /** When this field becomes visible, emit `onStaffSet` with this staff ID. */
+    staff_set?: string;
+    /**
+     * Duration value (in minutes as a string) to add to the booking when visible.
+     * Negated and re-emitted when the field becomes hidden.
+     */
+    add_duration?: string;
+    /**
+     * Appointment type identifier. Stored in sessionStorage on the `services` page.
+     * Used on `booking-details` to filter fields by appointment type.
+     */
+    appointment_type?: string;
+    copy_data?: CopyDataConfig;
+    /** When visible and non-empty, emit `onUpdateDatastore({ booker_first_name: value })`. */
+    booker_first_name?: boolean | 'true';
+    booker_last_name?: boolean | 'true';
+    booker_email?: boolean | 'true';
+    booker_phone?: boolean | 'true';
+    /**
+     * Extra item ID to fetch and emit when this field is visible and has a truthy value.
+     * Note: serialised as a hyphenated key in JSON — access as `field['extra-item']`.
+     */
+    'extra-item'?: string;
+    /** Service ID override for this field's extra item lookup. */
+    'service-id'?: string;
+    /**
+     * Per-resource extra item overrides. Key is resource ID, value contains `extra-item`.
+     * Takes precedence over `extra-item` when a matching resource is selected.
+     */
+    resource_ids?: Record<string, {
+        'extra-item': string;
+    }>;
+    /** If true and schema type is not 'extended', use legacy trigger/trigger_value logic. */
+    conditional?: boolean;
+    /**
+     * Pipe-separated list of field names to watch.
+     * Only used when `conditional === true` on a legacy schema.
+     */
+    trigger?: string;
+    /**
+     * Pipe-separated list of expected values corresponding to `trigger` fields.
+     * Each value can be `&`-joined for multi-part AND conditions within a single trigger.
+     * Supports prefixes: `<`, `>`, `!` for numeric/inequality comparisons.
+     * Use `*` as a wildcard to match any non-empty value.
+     */
+    trigger_value?: string;
+    /**
+     * If true on a visible field, the form-level submit button becomes visible.
+     * Used to gate progression in the booking journey.
+     */
+    continue?: boolean;
+    /** If true, field is unconditionally hidden regardless of visibility rules. */
+    hidden_field?: boolean;
+    /** Whether to prevent dates in the future (sets `max` to today on date inputs). */
+    hide_dates_in_future?: boolean;
+}
+/**
+ * Extends RawSchemaField with all mutable runtime state added during form
+ * initialisation and visibility evaluation.
+ * This is the type you work with throughout the component.
+ */
+interface SchemaField extends RawSchemaField {
+    /** Number of keys in the `show` object. 0 = always visible. */
+    rules_count: number;
+    /** Whether this field's `page` matches the currently active route page. */
+    show_on_this_page: boolean;
+    /** Set to true during init when `lookup.aws_table` is present. */
+    aws_lookup?: boolean;
+    /** Current computed visibility. Updated by refreshVisibility(). */
+    visible: boolean;
+    /** Alias for `visible` — kept for API compatibility with legacy schema paths. */
+    is_visible: boolean;
+    /**
+     * Resolved title after `{fieldName}` tokens have been interpolated.
+     * Falls back to `title` if not yet resolved.
+     */
+    rendered_title?: string;
+    /** Prevents `add_duration` from being emitted more than once per visible lifecycle. */
+    duration_added?: boolean;
+    /** Runtime company ID stored when `company_set` side-effect fires. */
+    company_id?: string;
+    /** Runtime service ID stored when `service_set` side-effect fires. */
+    service_id?: string;
+    /** Runtime resource ID stored when `resource_set` side-effect fires. */
+    resource_id?: string;
+    addresses?: Array<{
+        address: {
+            ADDRESS: string;
+        };
+    }>;
+    addressLoading?: boolean;
+    badPostcode?: boolean;
+    selected_address?: string;
+    lookupSuccess?: boolean;
+    lookupError?: boolean;
+    lookupUsed?: boolean;
+    lookupLoading?: boolean;
+    lookupResponse?: {
+        name?: string;
+        home_office?: string;
+        [key: string]: unknown;
+    } | null;
+    lookupNameMismatch?: boolean;
+    /**
+     * Set to true on secondary match fields (e.g. name input) after a successful
+     * lookup. Causes the field wrapper to receive the `hidden-field` CSS class,
+     * hiding the input while the verified info display is shown instead.
+     */
+    lookupValidated?: boolean;
+    searching?: boolean;
+    noResults?: boolean;
+    selected_resource?: VenueResult;
+    /** Display value of the currently selected venue (for read-only display). */
+    answer?: string;
+}
+/** Individual field error. */
+interface FieldError {
+    fieldName: string;
+    errors: Record<string, unknown>;
+}
+/** Extra item entry tracked by the form. */
+interface ExtraItemEntry {
+    field: string;
+    serviceId: string;
+    extraItemId: string;
+    qty: number;
+}
+/** Status object emitted via onFormStatus on every form value change. */
+interface FormSchemaStatus {
+    /** True when all visible, required fields on the current page are valid. */
+    status: boolean;
+    /** Array of field error objects for any invalid controls. */
+    errors: FieldError[];
+    /** Snapshot of all current form control values keyed by field name. */
+    formData: Record<string, string> | undefined;
+    /**
+     * Extra items currently tracked by the form (may be empty during initial load).
+     * Populated by the extra-items system — see Prompt 8.
+     */
+    extraItems: ExtraItemEntry[];
+    /**
+     * Present when a field with a `service_set` side-effect just changed value.
+     * The parent uses this to trigger a service selection in the booking datastore.
+     */
+    setService?: string;
+}
+/** Payload emitted via onVenueSet. */
+interface VenueSetPayload {
+    /** The selected venue object, or null when the selection is cleared. */
+    venue: VenueResult | null;
+    /** The field name this venue selection belongs to. */
+    field: string;
+    /** Present when a venue is selected and has an associated company. */
+    companyId?: string;
+    /** Present when a venue is selected and has an associated resource. */
+    resourceId?: string;
+}
+/** Payload emitted via onAwsLookupSet. */
+interface AwsLookupSetPayload {
+    /** The field name the lookup was performed on. */
+    field: string;
+    /** The reference object returned on success, or null when cleared. */
+    reference: {
+        name?: string;
+        home_office?: string;
+        [key: string]: unknown;
+    } | null;
+    success: boolean;
+}
+/** Payload emitted via onUpdateDatastore. */
+interface UpdateDatastorePayload {
+    type?: 'lookupResponse';
+    field?: string;
+    lookupResponse?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** Payload emitted via onFormReady. */
+interface FormReadyPayload {
+    form_id: string;
+    extra_items: ExtraItemEntry[];
+}
+/** Props for the SchemaFormBuilder component. */
+interface SchemaFormBuilderProps {
+    /** The schema ID used to fetch the form definition from the API. */
+    formId: string;
+    /** Runtime API configuration. Forwarded to all API calls. */
+    appConfig: AppConfig;
+    /** The current route page slug (e.g. 'booking-details'). Only fields for this page are rendered. */
+    currentPage: string;
+    /** The booking company ID for venue searches and extra item lookups. */
+    companyId: string;
+    /**
+     * Initial field values to pre-populate the form with.
+     * Keys must match `field.field` names in the schema.
+     */
+    formData?: Record<string, unknown>;
+    /**
+     * Whether to show the submit/continue button.
+     * The form also manages this internally based on `field.continue` visibility —
+     * this prop provides an external override for the initial render.
+     */
+    showSubmit?: boolean;
+    /**
+     * When provided, the form watches this value. If it changes to a new
+     * formId string, the form tears down and re-initialises with the new schema.
+     */
+    formUpdateId?: string;
+    /**
+     * When provided, the component uses this schema directly instead of
+     * fetching from the API. Useful for testing schema implementations locally.
+     * Must conform to the FormSchemaResponse shape.
+     */
+    initialSchema?: FormSchemaResponse;
+    /** Fired when the submit button is clicked and the form is valid. */
+    onFormSubmit?: (data: Record<string, string>) => void;
+    /** Fired on every form value change with current validity and form data. */
+    onFormStatus?: (status: FormSchemaStatus) => void;
+    /** Fired on submit with the raw schema object (used for downstream schema introspection). */
+    onSchema?: (schema: Record<string, unknown>) => void;
+    /** Fired when a field with `company_set` becomes visible. */
+    onCompanySet?: (companyId: string) => void;
+    /** Fired when a field with `service_set` becomes visible. */
+    onServiceSet?: (serviceId: string) => void;
+    /** Fired when a field with `resource_set` becomes visible. */
+    onResourceSet?: (resourceId: string) => void;
+    /** Fired when a field with `staff_set` becomes visible. */
+    onStaffSet?: (staffId: string) => void;
+    /**
+     * Fired when a field with `add_duration` becomes visible (positive string value)
+     * or hidden (negated string value, e.g. '-30').
+     */
+    onAddDuration?: (duration: string) => void;
+    /** Fired once after the form schema has been fetched and controls built. */
+    onFormReady?: (payload: FormReadyPayload) => void;
+    /** Fired when a booker field (name, email, phone) is populated. */
+    onUpdateDatastore?: (payload: UpdateDatastorePayload) => void;
+    /** Fired when an address is selected from the address lookup dropdown. */
+    onAddressSet?: (address: string) => void;
+    /** Fired when an AWS lookup succeeds, fails, or is cleared. */
+    onAwsLookupSet?: (payload: AwsLookupSetPayload) => void;
+    /** Fired when a new extra item is fetched and should be added to the booking. */
+    onExtraItemSet?: (payload: {
+        item_id: string;
+        item: ExtraItemProperties | null;
+    }) => void;
+    /** Fired when an existing extra item's quantity changes. */
+    onExtraItemChanged?: (payload: {
+        item_id: string;
+        item: ExtraItemEntry;
+    }) => void;
+    /** Fired when a venue is selected or cleared. */
+    onVenueSet?: (payload: VenueSetPayload) => void;
+    /** Fired when any async operation (address lookup, AWS lookup, extra item fetch) starts or ends. */
+    onProcessing?: (loading: boolean) => void;
+}
+/**
+ * Hydrates a raw API field into a SchemaField by setting all initial
+ * runtime state to its default values.
+ */
+declare function hydrateField(raw: RawSchemaField, currentPage: string): SchemaField;
+
 interface QuestionOption {
     id: number;
     name: string;
@@ -317,7 +813,7 @@ interface QuestionSettings {
 interface Question {
     id: number;
     name: string;
-    detail_type: 'heading' | 'text_field' | 'text_area' | 'select' | 'date' | 'number' | 'check';
+    detail_type: 'heading' | 'text_field' | 'text_area' | 'select' | 'radio' | 'date' | 'number' | 'check';
     required?: boolean;
     important?: boolean;
     admin_only?: boolean;
@@ -351,6 +847,12 @@ interface BookingFormClassNames {
     inputError?: string;
     /** Checkbox input specifically */
     checkbox?: string;
+    /** Radio input specifically */
+    radio?: string;
+    /** Radio group wrapper */
+    radioGroup?: string;
+    /** Radio option label */
+    radioLabel?: string;
     /** Help text below fields */
     helpText?: string;
     /** Error message text */
@@ -362,6 +864,8 @@ interface BookingFormProps {
     questions: Question[];
     onSubmit: (values: FormValues) => void;
     submitLabel?: string;
+    /** Whether the current user is an admin. When false (default), questions with admin_only=true are hidden. */
+    isAdmin?: boolean;
     /** Class name for the form element */
     className?: string;
     /** @deprecated Use classNames.label instead */
@@ -391,7 +895,7 @@ interface BookingUIConfig {
  * />
  * ```
  */
-declare function BookingForm({ questions, onSubmit, submitLabel, className, labelClassName, classNames: classNamesProp, }: BookingFormProps): react_jsx_runtime.JSX.Element;
+declare function BookingForm({ questions, onSubmit, submitLabel, isAdmin, className, labelClassName, classNames: classNamesProp, }: BookingFormProps): react_jsx_runtime.JSX.Element;
 
 /**
  * A reusable, accessible registration form component.
@@ -464,6 +968,8 @@ declare const ContactDetailsForm: React.ForwardRefExoticComponent<ContactDetails
  */
 declare const ResetPasswordForm: React.ForwardRefExoticComponent<ResetPasswordFormProps & React.RefAttributes<ResetPasswordFormRef>>;
 
+declare function SchemaFormBuilder(props: SchemaFormBuilderProps): react_jsx_runtime.JSX.Element | null;
+
 /**
  * Validation helper functions for form fields
  * Each validator returns an error message string if invalid, or null if valid
@@ -497,4 +1003,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 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, type RegistrationFieldSettings, RegistrationForm, type RegistrationFormClassNames, type RegistrationFormErrors, type RegistrationFormProps, type RegistrationFormRef, type RegistrationFormValues, ResetPasswordForm, type ResetPasswordFormClassNames, type ResetPasswordFormProps, type ResetPasswordFormRef, type ResetPasswordFormValues, compose, email, minLen, phone, required, ukPostcode };
+export { type AppConfig, type AwsLookupConfig, type AwsLookupMatchEntry, type AwsLookupSetPayload, BookingForm, type BookingFormClassNames, type BookingFormProps, type BookingUIConfig, type ConditionClause, type ContactDetailsAnswerEntry, type ContactDetailsFieldSettings, ContactDetailsForm, type ContactDetailsFormClassNames, type ContactDetailsFormProps, type ContactDetailsFormRef, type ContactDetailsInitialValues, type ContactDetailsQuestionEntry, type ContactDetailsValues, type ContactFieldSettings, type CopyDataConfig, type DropdownOption, type ExtraItemEntry, type FieldConfig, type FieldError, type FieldOption, type FormErrors, type FormReadyPayload, type FormSchemaStatus, type FormValues, type Question, type QuestionOption, type QuestionSettings, type RadioOption, type RawSchemaField, type RegistrationFieldSettings, RegistrationForm, type RegistrationFormClassNames, type RegistrationFormErrors, type RegistrationFormProps, type RegistrationFormRef, type RegistrationFormValues, ResetPasswordForm, type ResetPasswordFormClassNames, type ResetPasswordFormProps, type ResetPasswordFormRef, type ResetPasswordFormValues, type SchemaField, SchemaFormBuilder, type SchemaFormBuilderProps, type ShowRules, type UpdateDatastorePayload, type ValidationMaxDate, type ValidationMaxLength, type ValidationMinDate, type ValidationMinLength, type ValidationRule, type ValidationShorthand, type VenueSetPayload, compose, email, hydrateField, minLen, phone, required, ukPostcode };