@lub-crm/forms 1.0.0

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@lub-crm/forms",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Embeddable form library for Lub CRM",
+  "main": "./dist/lub-forms.umd.js",
+  "module": "./dist/lub-forms.es.js",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/lub-forms.es.js",
+      "require": "./dist/lub-forms.umd.js"
+    },
+    "./styles": "./dist/lub-forms.css"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": [
+    "*.css"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "bun run build:lib && bun run build:umd && bun run build:standalone && bun run build:clean",
+    "build:clean": "rm -f dist/forms.css dist/vite.svg",
+    "build:lib": "vite build --config vite.lib.config.ts",
+    "build:umd": "vite build --config vite.umd.config.ts",
+    "build:standalone": "vite build --config vite.standalone.config.ts",
+    "lint": "eslint .",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@hookform/resolvers": "^3.9.0",
+    "react-hook-form": "^7.53.0",
+    "zod": "^3.23.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.5",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.1",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "eslint": "^9.39.1",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.4.24",
+    "globals": "^16.5.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.46.4",
+    "vite": "^7.2.4"
+  },
+  "keywords": [
+    "forms",
+    "embed",
+    "crm",
+    "lub"
+  ],
+  "license": "MIT"
+}

package/src/api/client.ts

@@ -0,0 +1,115 @@
+import type {
+  PublicFormResponse,
+  SubmitFormRequest,
+  SubmitFormResponse,
+  ApiError,
+} from "./types";
+
+export class LubFormsClient {
+  private baseUrl: string;
+
+  constructor(baseUrl: string) {
+    // Remove trailing slash
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+  }
+
+  /**
+   * Fetch a form by ID for public display
+   */
+  async getForm(formId: string): Promise<PublicFormResponse> {
+    const url = `${this.baseUrl}/public/forms/${formId}`;
+
+    const response = await fetch(url, {
+      method: "GET",
+      headers: {
+        Accept: "application/json",
+      },
+    });
+
+    if (!response.ok) {
+      const error = await this.parseError(response);
+      throw error;
+    }
+
+    return response.json() as Promise<PublicFormResponse>;
+  }
+
+  /**
+   * Submit form data
+   */
+  async submitForm(
+    formId: string,
+    data: SubmitFormRequest,
+  ): Promise<SubmitFormResponse> {
+    const url = `${this.baseUrl}/public/forms/${formId}/submit`;
+
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+      body: JSON.stringify(data),
+    });
+
+    if (!response.ok) {
+      const error = await this.parseError(response);
+      throw error;
+    }
+
+    return response.json() as Promise<SubmitFormResponse>;
+  }
+
+  /**
+   * Confirm double opt-in
+   */
+  async confirmOptIn(
+    token: string,
+  ): Promise<{ success: boolean; message: string; submission_id: string }> {
+    const url = `${this.baseUrl}/public/forms/confirm/${token}`;
+
+    const response = await fetch(url, {
+      method: "GET",
+      headers: {
+        Accept: "application/json",
+      },
+    });
+
+    if (!response.ok) {
+      const error = await this.parseError(response);
+      throw error;
+    }
+
+    return response.json();
+  }
+
+  private async parseError(response: Response): Promise<ApiError> {
+    try {
+      const data = await response.json();
+      return {
+        error: data.error || data.message || "An error occurred",
+        code: data.code,
+        details: data.details,
+      };
+    } catch {
+      return {
+        error: `HTTP ${response.status}: ${response.statusText}`,
+      };
+    }
+  }
+}
+
+// Default client instance (can be set via LubForms.init)
+let defaultClient: LubFormsClient | null = null;
+
+export function setDefaultClient(client: LubFormsClient): void {
+  defaultClient = client;
+}
+
+export function getDefaultClient(): LubFormsClient | null {
+  return defaultClient;
+}
+
+export function createClient(baseUrl: string): LubFormsClient {
+  return new LubFormsClient(baseUrl);
+}

package/src/api/index.ts

@@ -0,0 +1,2 @@
+export * from "./types";
+export * from "./client";

package/src/api/types.ts

@@ -0,0 +1,202 @@
+// Types matching backend marketing/forms DTOs
+
+// Field types
+export type FieldType =
+  | "text"
+  | "textarea"
+  | "email"
+  | "phone"
+  | "number"
+  | "url"
+  | "date"
+  | "time"
+  | "datetime"
+  | "select"
+  | "radio"
+  | "checkbox"
+  | "checkbox_group"
+  | "file"
+  | "hidden"
+  | "country"
+  | "state"
+  | "html"
+  | "divider"
+  | "recaptcha";
+
+// Field width
+export type FieldWidth = "full" | "half" | "third" | "quarter";
+
+// Conditional operators
+export type Operator =
+  | "equals"
+  | "not_equals"
+  | "contains"
+  | "not_contains"
+  | "greater_than"
+  | "less_than"
+  | "is_empty"
+  | "is_not_empty";
+
+// Form layout
+export type FormLayout = "vertical" | "horizontal" | "two_column";
+
+// Validation rules
+export interface ValidationRules {
+  min_length?: number;
+  max_length?: number;
+  min?: number;
+  max?: number;
+  pattern?: string;
+  allowed_types?: string[];
+  max_file_size?: number;
+  custom_error?: string;
+}
+
+// Select option
+export interface SelectOption {
+  value: string;
+  label: string;
+  selected?: boolean;
+}
+
+// Field options (for select, radio, checkbox_group)
+export interface FieldOptions {
+  options: SelectOption[];
+  allow_other?: boolean;
+  other_label?: string;
+  multiple?: boolean;
+  searchable?: boolean;
+}
+
+// Conditional logic
+export interface Condition {
+  field_name: string;
+  operator: Operator;
+  value: unknown;
+  and?: Condition[];
+  or?: Condition[];
+}
+
+export interface ConditionalLogic {
+  show_if?: Condition;
+  hide_if?: Condition;
+  required_if?: Condition;
+}
+
+// CRM mapping
+export interface CRMMapping {
+  object_type: string;
+  field_name: string;
+  is_custom_field?: boolean;
+}
+
+// Form field response
+export interface FormField {
+  id: string;
+  field_type: FieldType;
+  name: string;
+  label: string;
+  placeholder?: string;
+  default_value?: string;
+  help_text?: string;
+  display_order: number;
+  required: boolean;
+  validation_rules?: ValidationRules;
+  options?: FieldOptions;
+  conditional_logic?: ConditionalLogic;
+  crm_mapping?: CRMMapping;
+  width: FieldWidth;
+  css_class?: string;
+  is_active: boolean;
+}
+
+// Button style
+export interface ButtonStyle {
+  background_color?: string;
+  text_color?: string;
+  border_radius?: string;
+  size?: "small" | "medium" | "large";
+  full_width?: boolean;
+}
+
+// Form design
+export interface FormDesign {
+  layout: FormLayout;
+  theme: string;
+  background_color?: string;
+  text_color?: string;
+  primary_color?: string;
+  border_color?: string;
+  font_family?: string;
+  font_size?: string;
+  padding?: string;
+  field_spacing?: string;
+  button_style?: ButtonStyle;
+  custom_css?: string;
+  show_logo?: boolean;
+  logo_url?: string;
+}
+
+// Form step (for multi-step forms)
+export interface FormStep {
+  id: string;
+  name: string;
+  description?: string;
+  field_ids: string[];
+  display_order: number;
+}
+
+// Public form settings
+export interface PublicFormSettings {
+  submit_button_text: string;
+  success_message: string;
+  enable_recaptcha: boolean;
+  recaptcha_site_key?: string;
+  show_consent_checkbox: boolean;
+  consent_text?: string;
+}
+
+// Public form response (from GET /public/forms/:id)
+export interface PublicFormResponse {
+  id: string;
+  name: string;
+  description: string;
+  fields: FormField[];
+  design: FormDesign;
+  is_multi_step: boolean;
+  steps?: FormStep[];
+  settings: PublicFormSettings;
+}
+
+// UTM parameters
+export interface UTMParameters {
+  source?: string;
+  medium?: string;
+  campaign?: string;
+  term?: string;
+  content?: string;
+}
+
+// Submit form request
+export interface SubmitFormRequest {
+  data: Record<string, unknown>;
+  utm_parameters?: UTMParameters;
+  referrer?: string;
+  recaptcha_token?: string;
+  honeypot?: string;
+}
+
+// Submit form response
+export interface SubmitFormResponse {
+  success: boolean;
+  submission_id: string;
+  message: string;
+  requires_confirmation?: boolean;
+}
+
+// API Error response
+export interface ApiError {
+  error: string;
+  code?: string;
+  details?: Record<string, unknown>;
+}

package/src/core/FormProvider.tsx

@@ -0,0 +1,228 @@
+import { createContext, useContext, useMemo, type ReactNode } from "react";
+import {
+  useForm,
+  FormProvider as RHFFormProvider,
+  type UseFormReturn,
+  type FieldValues,
+} from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import type { z } from "zod";
+import type { PublicFormResponse, FormField } from "@/api/types";
+
+// Form context types
+interface LubFormContextValue {
+  form: PublicFormResponse;
+  fields: FormField[];
+  currentStep: number;
+  totalSteps: number;
+  isMultiStep: boolean;
+  isSubmitting: boolean;
+  isSuccess: boolean;
+  error: string | null;
+  goToStep: (step: number) => void;
+  nextStep: () => void;
+  prevStep: () => void;
+  getFieldsForCurrentStep: () => FormField[];
+  getVisibleFields: (formValues: FieldValues) => FormField[];
+}
+
+const LubFormContext = createContext<LubFormContextValue | null>(null);
+
+export function useLubFormContext(): LubFormContextValue {
+  const context = useContext(LubFormContext);
+  if (!context) {
+    throw new Error("useLubFormContext must be used within a LubFormProvider");
+  }
+  return context;
+}
+
+// Props
+interface LubFormProviderProps {
+  form: PublicFormResponse;
+  schema: z.ZodSchema;
+  defaultValues?: Record<string, unknown>;
+  currentStep: number;
+  totalSteps: number;
+  isSubmitting: boolean;
+  isSuccess: boolean;
+  error: string | null;
+  onStepChange: (step: number) => void;
+  children: ReactNode;
+}
+
+export function LubFormProvider({
+  form,
+  schema,
+  defaultValues,
+  currentStep,
+  totalSteps,
+  isSubmitting,
+  isSuccess,
+  error,
+  onStepChange,
+  children,
+}: LubFormProviderProps) {
+  const methods = useForm({
+    resolver: zodResolver(schema),
+    defaultValues: defaultValues ?? {},
+    mode: "onBlur",
+    reValidateMode: "onChange",
+  });
+
+  const isMultiStep = form.is_multi_step && (form.steps?.length ?? 0) > 0;
+
+  const goToStep = (step: number) => {
+    if (step >= 0 && step < totalSteps) {
+      onStepChange(step);
+    }
+  };
+
+  const nextStep = () => {
+    if (currentStep < totalSteps - 1) {
+      onStepChange(currentStep + 1);
+    }
+  };
+
+  const prevStep = () => {
+    if (currentStep > 0) {
+      onStepChange(currentStep - 1);
+    }
+  };
+
+  const getFieldsForCurrentStep = (): FormField[] => {
+    if (!isMultiStep || !form.steps) {
+      return form.fields.filter((f) => f.is_active);
+    }
+
+    const step = form.steps[currentStep];
+    if (!step) return [];
+
+    const stepFieldIds = new Set(step.field_ids);
+    return form.fields.filter((f) => f.is_active && stepFieldIds.has(f.id));
+  };
+
+  const getVisibleFields = (formValues: FieldValues): FormField[] => {
+    const stepFields = getFieldsForCurrentStep();
+    return stepFields.filter((field) => {
+      if (!field.conditional_logic) return true;
+      return evaluateFieldVisibility(field, formValues);
+    });
+  };
+
+  const contextValue = useMemo(
+    (): LubFormContextValue => ({
+      form,
+      fields: form.fields,
+      currentStep,
+      totalSteps,
+      isMultiStep,
+      isSubmitting,
+      isSuccess,
+      error,
+      goToStep,
+      nextStep,
+      prevStep,
+      getFieldsForCurrentStep,
+      getVisibleFields,
+    }),
+    [form, currentStep, totalSteps, isSubmitting, isSuccess, error],
+  );
+
+  return (
+    <LubFormContext.Provider value={contextValue}>
+      <RHFFormProvider {...methods}>{children}</RHFFormProvider>
+    </LubFormContext.Provider>
+  );
+}
+
+// Helper to evaluate field visibility based on conditional logic
+function evaluateFieldVisibility(
+  field: FormField,
+  formValues: FieldValues,
+): boolean {
+  const logic = field.conditional_logic;
+  if (!logic) return true;
+
+  // Check show_if
+  if (logic.show_if) {
+    return evaluateCondition(logic.show_if, formValues);
+  }
+
+  // Check hide_if
+  if (logic.hide_if) {
+    return !evaluateCondition(logic.hide_if, formValues);
+  }
+
+  return true;
+}
+
+function evaluateCondition(
+  condition: NonNullable<FormField["conditional_logic"]>["show_if"],
+  formValues: FieldValues,
+): boolean {
+  if (!condition) return true;
+
+  const fieldValue = formValues[condition.field_name];
+  let result = compareValues(fieldValue, condition.operator, condition.value);
+
+  // Evaluate AND conditions
+  if (condition.and && condition.and.length > 0) {
+    for (const andCond of condition.and) {
+      if (!evaluateCondition(andCond, formValues)) {
+        return false;
+      }
+    }
+  }
+
+  // Evaluate OR conditions
+  if (condition.or && condition.or.length > 0) {
+    let orResult = false;
+    for (const orCond of condition.or) {
+      if (evaluateCondition(orCond, formValues)) {
+        orResult = true;
+        break;
+      }
+    }
+    result = result && orResult;
+  }
+
+  return result;
+}
+
+function compareValues(
+  fieldValue: unknown,
+  operator: string,
+  compareValue: unknown,
+): boolean {
+  switch (operator) {
+    case "equals":
+      return fieldValue === compareValue;
+    case "not_equals":
+      return fieldValue !== compareValue;
+    case "contains":
+      return String(fieldValue ?? "").includes(String(compareValue));
+    case "not_contains":
+      return !String(fieldValue ?? "").includes(String(compareValue));
+    case "greater_than":
+      return Number(fieldValue) > Number(compareValue);
+    case "less_than":
+      return Number(fieldValue) < Number(compareValue);
+    case "is_empty":
+      return fieldValue == null || fieldValue === "";
+    case "is_not_empty":
+      return fieldValue != null && fieldValue !== "";
+    default:
+      return true;
+  }
+}
+
+// Export React Hook Form methods hook
+export function useFormMethods(): UseFormReturn {
+  const methods = useContext(
+    RHFFormProvider as unknown as React.Context<UseFormReturn | null>,
+  );
+  if (!methods) {
+    throw new Error("useFormMethods must be used within a LubFormProvider");
+  }
+  return methods;
+}