@lub-crm/forms 1.0.0

package/README.md

@@ -0,0 +1,298 @@
+# @lub/forms
+
+Embeddable form library for Lub CRM. Render dynamic forms that integrate with Lub CRM for lead capture and data collection.
+
+## Features
+
+- Multiple deployment options: React component, UMD script, or standalone bundle
+- Multi-step form support with progress indicators
+- Conditional field visibility and requirements
+- Dynamic validation with Zod schemas
+- CRM field mapping for automatic lead creation
+- UTM parameter tracking
+- Customizable styling via CSS variables
+- 17+ field types including country/state selectors
+
+## Installation
+
+### NPM Package (React Apps)
+
+```bash
+npm install @lub/forms
+# or
+bun add @lub/forms
+```
+
+### Script Tag (Standalone)
+
+No build step required. Includes React and all dependencies:
+
+```html
+<script src="https://forms.lub.com/v1/lub-forms.standalone.js"></script>
+```
+
+### Script Tag (UMD)
+
+For pages that already have React loaded:
+
+```html
+<script src="https://unpkg.com/react@19/umd/react.production.min.js"></script>
+<script src="https://unpkg.com/react-dom@19/umd/react-dom.production.min.js"></script>
+<script src="https://forms.lub.com/v1/lub-forms.umd.js"></script>
+<link rel="stylesheet" href="https://forms.lub.com/v1/lub-forms.css" />
+```
+
+## Usage
+
+### React Component
+
+```tsx
+import { LubForm } from "@lub/forms";
+import "@lub/forms/styles";
+
+function ContactPage() {
+  return (
+    <LubForm
+      formId="abc123"
+      baseUrl="https://api.lub.com"
+      onSuccess={(data) => {
+        console.log("Submission ID:", data.submission_id);
+        window.location.href = "/thank-you";
+      }}
+      onError={(error) => {
+        console.error("Submission failed:", error.message);
+      }}
+    />
+  );
+}
+```
+
+### Script Tag (Auto-mount)
+
+Forms automatically mount to elements with `data-lub-form-id`:
+
+```html
+<div
+  data-lub-form-id="abc123"
+  data-lub-base-url="https://api.lub.com"
+  data-lub-class="my-custom-class"
+  data-lub-on-success="handleSuccess"
+  data-lub-on-error="handleError"
+></div>
+
+<script>
+  function handleSuccess(data) {
+    window.location.href = "/thank-you";
+  }
+  function handleError(error) {
+    alert("Something went wrong");
+  }
+</script>
+```
+
+### Script Tag (Manual Render)
+
+```html
+<div id="my-form"></div>
+
+<script>
+  LubForms.render("abc123", "my-form", {
+    baseUrl: "https://api.lub.com",
+    onSuccess: (data) => {
+      console.log("Success!", data);
+    },
+    onError: (err) => {
+      console.error("Error:", err);
+    },
+    designOverrides: {
+      primary_color: "#8b5cf6",
+    },
+  });
+</script>
+```
+
+## Props / Options
+
+| Prop                | Type                                       | Description                                 |
+| ------------------- | ------------------------------------------ | ------------------------------------------- |
+| `formId`            | `string`                                   | Form ID from Lub CRM (required)             |
+| `baseUrl`           | `string`                                   | API base URL                                |
+| `onSuccess`         | `(data: SubmitFormResponse) => void`       | Called on successful submission             |
+| `onError`           | `(error: ApiError) => void`                | Called on submission error                  |
+| `onValidationError` | `(errors: Record<string, string>) => void` | Called when validation fails                |
+| `onStepChange`      | `(step: number, total: number) => void`    | Called when multi-step form changes step    |
+| `className`         | `string`                                   | Additional CSS class for the form container |
+| `style`             | `CSSProperties`                            | Inline styles                               |
+| `designOverrides`   | `Partial<FormDesign>`                      | Override form design settings               |
+
+## Field Types
+
+| Type             | Description                 |
+| ---------------- | --------------------------- |
+| `text`           | Single-line text input      |
+| `textarea`       | Multi-line text input       |
+| `email`          | Email input with validation |
+| `phone`          | Phone number input          |
+| `number`         | Numeric input with min/max  |
+| `url`            | URL input with validation   |
+| `date`           | Date picker                 |
+| `time`           | Time picker                 |
+| `datetime`       | Date and time picker        |
+| `select`         | Dropdown select             |
+| `radio`          | Radio button group          |
+| `checkbox`       | Single checkbox             |
+| `checkbox_group` | Multiple checkboxes         |
+| `file`           | File upload                 |
+| `hidden`         | Hidden field                |
+| `country`        | Country selector            |
+| `state`          | State/province selector     |
+| `html`           | Static HTML content         |
+| `divider`        | Visual divider              |
+| `recaptcha`      | reCAPTCHA v2/v3             |
+
+## Styling
+
+Forms are styled using CSS variables. Override them via `designOverrides` or CSS:
+
+```css
+.lub-form {
+  --lub-primary-color: #3b82f6;
+  --lub-background-color: #ffffff;
+  --lub-text-color: #1f2937;
+  --lub-border-color: #e5e7eb;
+  --lub-font-family: system-ui, sans-serif;
+  --lub-font-size: 14px;
+  --lub-padding: 24px;
+  --lub-field-spacing: 16px;
+}
+```
+
+Or via JavaScript:
+
+```jsx
+<LubForm
+  formId="abc123"
+  designOverrides={{
+    primary_color: "#8b5cf6",
+    background_color: "#fafafa",
+    font_family: "Inter, sans-serif",
+    button_style: {
+      border_radius: "9999px",
+      full_width: true,
+    },
+  }}
+/>
+```
+
+## Conditional Logic
+
+Fields support conditional visibility and requirements based on other field values:
+
+```typescript
+// Show field when another field equals a value
+conditional_logic: {
+  show_if: {
+    field_name: 'interest',
+    operator: 'equals',
+    value: 'other'
+  }
+}
+
+// Make field required based on condition
+conditional_logic: {
+  required_if: {
+    field_name: 'newsletter',
+    operator: 'equals',
+    value: true
+  }
+}
+```
+
+**Operators:** `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `is_empty`, `is_not_empty`
+
+## Custom Field Components
+
+Register custom field types for advanced use cases:
+
+```tsx
+import { registerFieldComponent } from "@lub/forms";
+
+registerFieldComponent("rating", ({ field, register, error }) => (
+  <div className="rating-field">
+    {[1, 2, 3, 4, 5].map((value) => (
+      <label key={value}>
+        <input type="radio" value={value} {...register(field.name)} />
+        {"⭐".repeat(value)}
+      </label>
+    ))}
+    {error && <span className="error">{error}</span>}
+  </div>
+));
+```
+
+## API Client
+
+Use the client directly for custom integrations:
+
+```tsx
+import { LubFormsClient } from "@lub/forms";
+
+const client = new LubFormsClient("https://api.lub.com");
+
+// Fetch form definition
+const form = await client.getForm("abc123");
+
+// Submit form data
+const response = await client.submitForm("abc123", {
+  data: { email: "user@example.com", name: "John" },
+  utm_parameters: { source: "landing-page" },
+  referrer: window.location.href,
+});
+
+// Confirm double opt-in
+const confirmation = await client.confirmOptIn("token123");
+```
+
+## Global API (Script Tag)
+
+When using the standalone or UMD build:
+
+```javascript
+// Render a form
+LubForms.render(formId, containerIdOrElement, options);
+
+// Auto-mount all forms with data-lub-form-id
+LubForms.autoMount();
+
+// Unmount a specific form
+LubForms.unmount(containerId);
+
+// Unmount all forms
+LubForms.unmountAll();
+
+// Initialize (called automatically)
+LubForms.init();
+```
+
+## Development
+
+```bash
+bun install
+bun run dev          # Start dev server on :5174
+bun run build        # Build all formats
+bun run lint         # Run ESLint
+bun run typecheck    # TypeScript check
+```
+
+## Build Outputs
+
+| File                           | Format | Use Case                       |
+| ------------------------------ | ------ | ------------------------------ |
+| `dist/lub-forms.es.js`         | ESM    | NPM package for React apps     |
+| `dist/lub-forms.umd.js`        | UMD    | Script tag with React on page  |
+| `dist/lub-forms.standalone.js` | IIFE   | Drop-in script, bundles React  |
+| `dist/lub-forms.css`           | CSS    | Shared styles (UMD/ESM builds) |
+
+## License
+
+MIT

package/dist/lub-forms.css

@@ -0,0 +1 @@
+.lub-form{--lub-bg-color: #ffffff;--lub-text-color: #1f2937;--lub-primary-color: #3b82f6;--lub-primary-hover: #2563eb;--lub-border-color: #d1d5db;--lub-error-color: #ef4444;--lub-success-color: #10b981;--lub-muted-color: #6b7280;--lub-font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;--lub-font-size: 16px;--lub-padding: 24px;--lub-field-spacing: 16px;--lub-border-radius: 6px;--lub-input-height: 42px;--lub-btn-bg: var(--lub-primary-color);--lub-btn-text: #ffffff;--lub-btn-radius: var(--lub-border-radius);--lub-focus-ring: 0 0 0 3px rgba(59, 130, 246, .3);--lub-transition: .15s ease}.lub-form{font-family:var(--lub-font-family);font-size:var(--lub-font-size);color:var(--lub-text-color);background-color:var(--lub-bg-color);padding:var(--lub-padding);border-radius:var(--lub-border-radius);box-sizing:border-box;line-height:1.5}.lub-form *,.lub-form *:before,.lub-form *:after{box-sizing:border-box}.lub-form__form{display:flex;flex-direction:column;gap:var(--lub-field-spacing)}.lub-form__header{margin-bottom:var(--lub-field-spacing)}.lub-form__title{font-size:1.5em;font-weight:600;margin:0 0 .5em;color:var(--lub-text-color)}.lub-form__description{margin:0;color:var(--lub-muted-color)}.lub-form__fields{display:flex;flex-direction:column;gap:var(--lub-field-spacing)}.lub-form__fields--two_column{display:flex;flex-wrap:wrap;gap:var(--lub-field-spacing)}.lub-form__field-group{display:contents}.lub-form__field-group--row{display:flex;flex-wrap:wrap;gap:var(--lub-field-spacing);width:100%}.lub-form__field,.lub-form__field--full{width:100%}.lub-form__field--half{width:calc(50% - var(--lub-field-spacing) / 2)}.lub-form__field--third{width:calc(33.333% - var(--lub-field-spacing) * 2 / 3)}.lub-form__field--quarter{width:calc(25% - var(--lub-field-spacing) * 3 / 4)}@media(max-width:640px){.lub-form__field--half,.lub-form__field--third,.lub-form__field--quarter{width:100%}}.lub-form__field-wrapper{display:flex;flex-direction:column;gap:6px}.lub-form__label{display:flex;align-items:center;gap:4px;font-size:.875em;font-weight:500;color:var(--lub-text-color)}.lub-form__required-indicator{color:var(--lub-error-color);font-weight:400}.lub-form__input,.lub-form__textarea,.lub-form__select{width:100%;padding:10px 12px;font-family:inherit;font-size:1em;color:var(--lub-text-color);background-color:var(--lub-bg-color);border:1px solid var(--lub-border-color);border-radius:var(--lub-border-radius);transition:border-color var(--lub-transition),box-shadow var(--lub-transition);outline:none}.lub-form__input{height:var(--lub-input-height)}.lub-form__textarea{min-height:100px;resize:vertical}.lub-form__select{height:var(--lub-input-height);cursor:pointer;appearance:none;background-image:url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='20' height='20' viewBox='0 0 20 20' fill='%236b7280'%3E%3Cpath fill-rule='evenodd' d='M5.293 7.293a1 1 0 011.414 0L10 10.586l3.293-3.293a1 1 0 111.414 1.414l-4 4a1 1 0 01-1.414 0l-4-4a1 1 0 010-1.414z' clip-rule='evenodd'/%3E%3C/svg%3E");background-repeat:no-repeat;background-position:right 10px center;padding-right:36px}.lub-form__input::placeholder,.lub-form__textarea::placeholder{color:var(--lub-muted-color)}.lub-form__input:focus,.lub-form__textarea:focus,.lub-form__select:focus{border-color:var(--lub-primary-color);box-shadow:var(--lub-focus-ring)}.lub-form__input--error,.lub-form__textarea--error,.lub-form__select--error{border-color:var(--lub-error-color)}.lub-form__input--error:focus,.lub-form__textarea--error:focus,.lub-form__select--error:focus{border-color:var(--lub-error-color);box-shadow:0 0 0 3px #ef44444d}.lub-form__checkbox-group,.lub-form__radio-group{display:flex;flex-direction:column;gap:8px}.lub-form__checkbox-label,.lub-form__radio-label{display:flex;align-items:flex-start;gap:10px;cursor:pointer;font-size:.9375em}.lub-form__checkbox,.lub-form__radio{width:18px;height:18px;margin:2px 0 0;flex-shrink:0;cursor:pointer;accent-color:var(--lub-primary-color)}.lub-form__checkbox-text,.lub-form__radio-text{color:var(--lub-text-color)}.lub-form__file-input{width:100%;padding:10px 12px;font-family:inherit;font-size:.9375em;color:var(--lub-text-color);background-color:var(--lub-bg-color);border:1px dashed var(--lub-border-color);border-radius:var(--lub-border-radius);cursor:pointer;transition:border-color var(--lub-transition),background-color var(--lub-transition)}.lub-form__file-input:hover{background-color:#00000005}.lub-form__file-input:focus{border-color:var(--lub-primary-color);outline:none}.lub-form__file-hint{margin:4px 0 0;font-size:.8125em;color:var(--lub-muted-color)}.lub-form__help-text{margin:0;font-size:.8125em;color:var(--lub-muted-color)}.lub-form__error{margin:0;font-size:.8125em;color:var(--lub-error-color)}.lub-form__html-content{padding:8px 0;color:var(--lub-text-color)}.lub-form__html-content a{color:var(--lub-primary-color);text-decoration:underline}.lub-form__divider{display:flex;align-items:center;gap:12px;padding:8px 0}.lub-form__divider-line{flex:1;height:1px;background-color:var(--lub-border-color);border:none;margin:0}.lub-form__divider-label{font-size:.875em;color:var(--lub-muted-color);white-space:nowrap}.lub-form__consent{padding-top:var(--lub-field-spacing)}.lub-form__consent-label{display:flex;align-items:flex-start;gap:10px;cursor:pointer}.lub-form__consent-checkbox{width:18px;height:18px;margin-top:2px;flex-shrink:0;cursor:pointer;accent-color:var(--lub-primary-color)}.lub-form__consent-text{font-size:.875em;color:var(--lub-text-color)}.lub-form__consent-text a{color:var(--lub-primary-color);text-decoration:underline}.lub-form__actions{display:flex;justify-content:flex-end;padding-top:var(--lub-field-spacing)}.lub-form__button{display:inline-flex;align-items:center;justify-content:center;gap:8px;padding:12px 24px;font-family:inherit;font-size:1em;font-weight:500;border:none;border-radius:var(--lub-btn-radius);cursor:pointer;transition:background-color var(--lub-transition),opacity var(--lub-transition)}.lub-form__button--primary{color:var(--lub-btn-text);background-color:var(--lub-btn-bg)}.lub-form__button--primary:hover:not(:disabled){background-color:var(--lub-primary-hover)}.lub-form__button--secondary{color:var(--lub-text-color);background-color:transparent;border:1px solid var(--lub-border-color)}.lub-form__button--secondary:hover:not(:disabled){background-color:#0000000d}.lub-form__button:disabled{opacity:.6;cursor:not-allowed}.lub-form__button-loading{display:inline-flex;align-items:center;gap:8px}.lub-form__navigation{display:flex;align-items:center;gap:12px;padding-top:var(--lub-field-spacing)}.lub-form__navigation-spacer{flex:1}.lub-form__steps{padding-bottom:var(--lub-field-spacing)}.lub-form__steps-list{display:flex;align-items:center;list-style:none;margin:0;padding:0;gap:0}.lub-form__step{display:flex;align-items:center;flex:1}.lub-form__step:last-child{flex:0 0 auto}.lub-form__step-indicator,.lub-form__step-button{display:flex;align-items:center;gap:8px;padding:8px;background:none;border:none;font-family:inherit;font-size:.875em;color:var(--lub-muted-color)}.lub-form__step-button{cursor:pointer}.lub-form__step-button:hover{color:var(--lub-primary-color)}.lub-form__step-number{display:flex;align-items:center;justify-content:center;width:28px;height:28px;border-radius:50%;background-color:var(--lub-border-color);color:var(--lub-muted-color);font-weight:500;font-size:.8125em}.lub-form__step--active .lub-form__step-number{background-color:var(--lub-primary-color);color:#fff}.lub-form__step--completed .lub-form__step-number{background-color:var(--lub-success-color);color:#fff}.lub-form__step-name{display:none}@media(min-width:640px){.lub-form__step-name{display:inline}}.lub-form__step--active .lub-form__step-indicator,.lub-form__step--active .lub-form__step-button{color:var(--lub-text-color)}.lub-form__step-connector{flex:1;height:2px;background-color:var(--lub-border-color);margin:0 8px}.lub-form__step-connector--completed{background-color:var(--lub-success-color)}.lub-form__check-icon{width:16px;height:16px}.lub-form__step-description{margin:12px 0 0;font-size:.875em;color:var(--lub-muted-color)}.lub-form__spinner{width:18px;height:18px;animation:lub-spin 1s linear infinite}.lub-form__spinner-track{opacity:.25}.lub-form__spinner-head{opacity:1}@keyframes lub-spin{0%{transform:rotate(0)}to{transform:rotate(360deg)}}.lub-form--loading .lub-form__skeleton{display:flex;flex-direction:column;gap:var(--lub-field-spacing)}.lub-form__skeleton-title,.lub-form__skeleton-field,.lub-form__skeleton-button{background:linear-gradient(90deg,var(--lub-border-color) 25%,rgba(0,0,0,.05) 50%,var(--lub-border-color) 75%);background-size:200% 100%;animation:lub-shimmer 1.5s infinite;border-radius:var(--lub-border-radius)}.lub-form__skeleton-title{height:28px;width:60%;margin-bottom:8px}.lub-form__skeleton-field{height:var(--lub-input-height)}.lub-form__skeleton-field--short{width:50%}.lub-form__skeleton-button{height:46px;width:120px;margin-left:auto}@keyframes lub-shimmer{0%{background-position:200% 0}to{background-position:-200% 0}}.lub-form--success .lub-form__success{display:flex;flex-direction:column;align-items:center;justify-content:center;text-align:center;padding:var(--lub-padding);min-height:200px}.lub-form__success-icon{width:64px;height:64px;color:var(--lub-success-color);margin-bottom:16px}.lub-form__success-message{font-size:1.125em;color:var(--lub-text-color);margin:0}.lub-form--error .lub-form__error-container{display:flex;flex-direction:column;align-items:center;justify-content:center;text-align:center;padding:var(--lub-padding);min-height:150px}.lub-form__error-message{font-size:1em;color:var(--lub-error-color);margin:0}.lub-form__recaptcha{display:flex;justify-content:flex-start;padding:8px 0}.lub-form__recaptcha-widget{transform-origin:left top}.lub-form[data-theme=dark]{--lub-bg-color: #1f2937;--lub-text-color: #f9fafb;--lub-border-color: #4b5563;--lub-muted-color: #9ca3af}