@xapp/form-widget 1.79.0 → 1.80.0

package/README.md

@@ -70,3 +70,366 @@ Tracking is enabled by default. The system handles:
 - Error handling for malformed data
 
 No additional configuration is required - the widget will automatically capture and pass through any UTM parameters, click IDs, or custom tracking parameters present in the page URL.
+
+### Implementation Notes
+
+**When used standalone:** The widget extracts tracking parameters from the page URL on mount and stores them in localStorage with the prefix `xa_tracking_`.
+
+**When embedded in contact-app:** Both the contact-app and form-widget will extract and store tracking parameters. This is safe and intentional:
+- Both extract from the same URL (`window.location.href`)
+- Both write to the same localStorage keys (`xa_tracking_utm_source`, etc.)
+- The function is idempotent - the second extraction just refreshes stored values with identical data
+- No data corruption occurs; it's just a minor inefficiency
+
+**Storage format:** Parameters are stored as JSON objects with expiration:
+```javascript
+localStorage.getItem('xa_tracking_utm_source')
+// Returns: {"value":"google","expires":1234567890,"stored":1234567890}
+```
+
+## Form Field Types
+
+The form widget supports multiple field types for building dynamic forms. Below are JSON examples for each supported field type.
+
+### Text Input
+
+Basic text input field with optional formatting (phone, email, address).
+
+```json
+{
+  "name": "full_name",
+  "type": "TEXT",
+  "title": "Full Name",
+  "placeholder": "Enter your name",
+  "mandatory": true,
+  "mandatoryError": "Name is required"
+}
+```
+
+#### Phone Number Input
+
+```json
+{
+  "name": "phone",
+  "type": "TEXT",
+  "title": "Phone Number",
+  "format": "PHONE",
+  "placeholder": "(555) 555-5555",
+  "mandatory": true
+}
+```
+
+#### Email Input
+
+```json
+{
+  "name": "email",
+  "type": "TEXT",
+  "title": "Email Address",
+  "format": "EMAIL",
+  "placeholder": "you@example.com"
+}
+```
+
+#### Multiline Text
+
+```json
+{
+  "name": "description",
+  "type": "TEXT",
+  "title": "Description",
+  "multiline": true,
+  "rows": 4,
+  "rowsMax": 8,
+  "placeholder": "Tell us more..."
+}
+```
+
+#### Address Input with Autocomplete
+
+```json
+{
+  "name": "address",
+  "type": "TEXT",
+  "title": "Service Address",
+  "format": "ADDRESS",
+  "mapsBaseUrl": "https://maps.googleapis.com/maps/api/place/autocomplete",
+  "googleMapsApiKey": "YOUR_API_KEY",
+  "mapsUrlQueryParams": {
+    "components": "country:us",
+    "language": "en"
+  }
+}
+```
+
+### Dropdown
+
+Single-select dropdown menu.
+
+```json
+{
+  "name": "service_type",
+  "type": "DROPDOWN",
+  "title": "Select a service",
+  "mandatory": true,
+  "items": [
+    {
+      "id": "plumbing",
+      "label": "Plumbing"
+    },
+    {
+      "id": "electrical",
+      "label": "Electrical"
+    },
+    {
+      "id": "hvac",
+      "label": "HVAC"
+    }
+  ]
+}
+```
+
+#### Dropdown with Freeform Input
+
+Allows users to enter custom text when they select specific options.
+
+```json
+{
+  "name": "issue",
+  "type": "DROPDOWN",
+  "title": "What issue are you experiencing?",
+  "items": [
+    {
+      "id": "installation",
+      "label": "Installation"
+    },
+    {
+      "id": "repair",
+      "label": "Repair"
+    },
+    {
+      "id": "maintenance",
+      "label": "Maintenance"
+    },
+    {
+      "id": "other",
+      "label": "Other",
+      "freeFormInput": true
+    }
+  ]
+}
+```
+
+When `freeFormInput: true`, selecting that option displays a text input field. The user's typed text becomes the field value instead of the item's ID.
+
+### Chips
+
+Visual chip-based selection, supports both single and multi-select.
+
+#### Multi-select Chips
+
+```json
+{
+  "name": "services",
+  "type": "CHIPS",
+  "title": "Select services you need",
+  "minRequired": 1,
+  "maxAllowed": 3,
+  "items": [
+    {
+      "id": "service1",
+      "label": "Service 1"
+    },
+    {
+      "id": "service2",
+      "label": "Service 2",
+      "selected": true
+    },
+    {
+      "id": "service3",
+      "label": "Service 3"
+    }
+  ]
+}
+```
+
+#### Single-select Chips (Radio)
+
+```json
+{
+  "name": "membership",
+  "type": "CHIPS",
+  "title": "Are you a member?",
+  "radio": true,
+  "items": [
+    {
+      "id": "yes",
+      "label": "Yes"
+    },
+    {
+      "id": "no",
+      "label": "No",
+      "selected": true
+    }
+  ]
+}
+```
+
+#### Chips with Actionable Items
+
+```json
+{
+  "name": "options",
+  "type": "CHIPS",
+  "title": "Choose an option",
+  "items": [
+    {
+      "id": "option1",
+      "label": "Option 1"
+    },
+    {
+      "id": "learn_more",
+      "label": "Learn More",
+      "url": "https://example.com/info"
+    }
+  ]
+}
+```
+
+### Checkboxes / Radio Buttons
+
+Traditional checkbox or radio button selection.
+
+#### Checkboxes (Multi-select)
+
+```json
+{
+  "name": "preferences",
+  "type": "CHECK",
+  "title": "Select your preferences",
+  "items": [
+    {
+      "id": "email_updates",
+      "label": "Email Updates"
+    },
+    {
+      "id": "sms_notifications",
+      "label": "SMS Notifications"
+    },
+    {
+      "id": "phone_calls",
+      "label": "Phone Calls"
+    }
+  ]
+}
+```
+
+#### Radio Buttons (Single-select)
+
+```json
+{
+  "name": "contact_method",
+  "type": "CHECK",
+  "title": "Preferred contact method",
+  "radio": true,
+  "items": [
+    {
+      "id": "email",
+      "label": "Email"
+    },
+    {
+      "id": "phone",
+      "label": "Phone"
+    },
+    {
+      "id": "sms",
+      "label": "SMS"
+    }
+  ]
+}
+```
+
+### Date Picker
+
+Single date selection with optional busy day configuration.
+
+```json
+{
+  "name": "appointment_date",
+  "type": "DATE",
+  "title": "Select appointment date",
+  "mandatory": true,
+  "defaultBusyDays": {
+    "blockWeekends": true,
+    "blockCurrentDay": true,
+    "blockNextBusinessDays": 1
+  }
+}
+```
+
+#### Date with Available Days
+
+```json
+{
+  "name": "service_date",
+  "type": "DATE",
+  "title": "Preferred service date",
+  "defaultBusyDays": {
+    "availableDays": ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY"]
+  }
+}
+```
+
+### Date Range Picker
+
+Select a start and end date.
+
+```json
+{
+  "name": "vacation_dates",
+  "type": "DATERANGE",
+  "title": "Select date range",
+  "preselecteDates": {
+    "from": "2024-01-01",
+    "to": "2024-01-07"
+  }
+}
+```
+
+### Card
+
+Display-only card with optional image, header, and text content.
+
+```json
+{
+  "name": "info_card",
+  "type": "CARD",
+  "header": {
+    "title": "Service Information",
+    "subheader": "What to expect"
+  },
+  "media": {
+    "imageUrl": "https://example.com/image.jpg",
+    "alt": "Service image",
+    "height": 200,
+    "width": 400
+  },
+  "text": "Our technicians will arrive within the scheduled time window.",
+  "variant": "outlined",
+  "color": "primary"
+}
+```
+
+## Common Field Properties
+
+All field types support these common properties:
+
+- `name` (string, required) - Field identifier used in form data
+- `type` (string, required) - Field type (TEXT, DROPDOWN, CHIPS, CHECK, DATE, DATERANGE, CARD)
+- `title` (string, optional) - Display label for the field
+- `mandatory` (boolean, optional) - Whether the field is required
+- `mandatoryError` (string, optional) - Custom error message when required field is empty
+- `condition` (string, optional) - JavaScript expression to conditionally show field (e.g., `"service === 'repair'"`)
+- `style` (object, optional) - React CSSProperties object for custom styling
+- `shape` (string, optional) - Visual shape: "ROUND" or "SQUARE"
+- `mandatoryGroup` (string, optional) - Group name for "one of" validation

package/dist/components/Form/Form.stories.d.ts

@@ -5,6 +5,7 @@ declare const _default: Meta;
 export default _default;
 export declare const Default: VFC;
 export declare const DefaultBlank: VFC;
+export declare const Dropdown: VFC;
 export declare const Styled: VFC;
 export declare const AutoOpened: VFC;
 export declare const WithIframe: FC;

package/dist/components/FormDisplay/FormDisplay.stories.d.ts

@@ -5,3 +5,6 @@ export declare const Default: any;
 export declare const DefaultWithConsent: any;
 export declare const WithFormServiceOptions: any;
 export declare const WithFormServiceOptionsZipCodeServiceArea: any;
+export declare const WithMandatoryDropdown: any;
+export declare const WithWarnBeforeUnload: any;
+export declare const WithWarnBeforeUnloadNoMessage: any;

package/dist/components/FormDisplay/FormDisplay.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/FormFieldDropdown/FormFieldDropdown.stories.d.ts

@@ -0,0 +1,12 @@
+import { Meta } from "@storybook/react";
+declare const _default: Meta;
+export default _default;
+export declare const Default: any;
+export declare const WithManyOptions: any;
+export declare const NoTitle: any;
+export declare const WithFreeFormInput: any;
+export declare const MultipleFreeFormOptions: any;
+export declare const WithCustomFieldName: any;
+export declare const WithDefaultMessageField: any;
+export declare const MandatoryDropdown: any;
+export declare const MandatoryWithCustomError: any;

package/dist/components/FormFieldDropdown/FormFieldDropdown.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/FormStepDisplay/FormStepDisplay.stories.d.ts

@@ -2,6 +2,8 @@ import { Meta } from "@storybook/react";
 declare const _default: Meta;
 export default _default;
 export declare const Default: any;
+export declare const WithDropdown: any;
+export declare const WithDropdownFreeForm: any;
 export declare const WithDate: any;
 export declare const WithMandatoryGroup: any;
 export declare const WithOptionalEmail: any;

package/dist/components/FormStepDisplay/validators.test.d.ts

@@ -0,0 +1 @@
+export {};