fansunited-frontend-components 0.0.19 → 0.0.20

package/README.md

@@ -548,6 +548,499 @@ import { WidgetTemplate } from "fansunited-frontend-core";
 />
 ```
 
-#### Related Packages
+### CollectLead
+
+Lead collection component for capturing user information with customizable forms, branding, and success actions. Perfect for newsletter signups, contact forms, and user registration flows.
+
+**Key Features:**
+- Customizable form fields (name, email, phone, country, gender, custom fields)
+- Consent management and privacy policy integration
+- Custom branding and theming support
+- Success page with custom CTAs
+- Three responsive templates (Standard, Split, Overlay)
+- Phone number validation with country codes
+- Multi-language support
+
+#### Required Props
+
+| Prop       | Type                 | Description                    |
+| ---------- | -------------------- | ------------------------------ |
+| `entityId` | `string`             | Lead collection form identifier |
+| `sdk`      | `FansUnitedSDKModel` | SDK instance                   |
+| `template` | `WidgetTemplate`     | Layout template                |
+| `language` | `LanguageType`       | Display language               |
+
+#### Optional Props
+
+| Prop                         | Type                    | Description                                 |
+| ---------------------------- | ----------------------- | ------------------------------------------- |
+| `themeOptions`               | `CustomThemeOptions`    | Theme configuration                         |
+| `fields`                     | `LeadField[]`           | Form fields to display                      |
+| `labels`                     | `LeadLabels`            | Custom labels for form elements             |
+| `imagePosition`              | `"left" \| "right"`     | Image position (STANDARD template only)     |
+| `defaultImagePlaceholderUrl` | `string`                | URL for default image placeholder           |
+| `phoneCountryCode`           | `string`                | Default country code for phone fields       |
+| `onSuccessCTA`               | `OnSuccessCTADetails`   | Success page call to action configuration   |
+| `customFields`               | `LeadCustomField[]`     | Additional custom form fields               |
+| `consents`                   | `LeadConsent[]`         | Consent checkboxes for privacy compliance   |
+| `content`                    | `ContentInfo`           | Content metadata                            |
+| `campaign`                   | `CampaignInfo`          | Campaign information                        |
+| `branding`                   | `BrandingInfo`          | Branding configuration                      |
+| `images`                     | `ImagesModel`           | Image assets                                |
+
+#### Templates
+
+```tsx
+import { WidgetTemplate, CollectLeadProps } from "fansunited-frontend-core";
+
+// Standard template with optional image positioning
+const standardProps: CollectLeadProps = {
+  template: WidgetTemplate.STANDARD,
+  imagePosition: "left", // or 'right'
+  // ... other props
+};
+
+// Split template - side-by-side layout
+const splitProps: CollectLeadProps = {
+  template: WidgetTemplate.SPLIT,
+  // imagePosition not available for non-standard templates
+  // ... other props
+};
+
+// Overlay template - full-screen immersive experience
+const overlayProps: CollectLeadProps = {
+  template: WidgetTemplate.OVERLAY,
+  // ... other props
+};
+```
+
+#### Form Configuration
+
+Configure which fields to display and their behavior:
+
+```tsx
+import { LeadField, LeadCustomField, LeadConsent } from "fansunited-frontend-core";
+
+// Standard form fields
+const fields: LeadField[] = [
+  "fullName",
+  "email",
+  "phoneNumber",
+  "country",
+  "gender"
+];
+
+// Custom fields for additional data collection
+const customFields: LeadCustomField[] = [
+  {
+    key: "company",
+    label: "Company Name",
+    type: "input",
+    required: true,
+    placeholder: "Enter your company name"
+  },
+  {
+    key: "message",
+    label: "Message",
+    type: "textarea",
+    required: false,
+    placeholder: "Tell us about your needs..."
+  }
+];
+
+// Consent checkboxes for privacy compliance
+const consents: LeadConsent[] = [
+  {
+    id: "marketing",
+    label: "I agree to receive marketing communications"
+  },
+  {
+    id: "newsletter",
+    label: "Subscribe to our newsletter"
+  }
+];
+
+<CollectLead
+  {...otherProps}
+  fields={fields}
+  customFields={customFields}
+  consents={consents}
+/>
+```
+
+#### Custom Labels
+
+Customize all text displayed in the form:
+
+```tsx
+import { LeadLabels } from "fansunited-frontend-core";
+
+const labels: LeadLabels = {
+  title: "Join Our Community",
+  description: "Get exclusive updates and early access to new features",
+  formTitle: "Sign Up Today",
+  formDescription: "Fill out the form below to get started",
+  formFullNameLabel: "Full Name",
+  formFullNamePlaceholder: "Enter your full name",
+  formEmailLabel: "Email Address",
+  formGenderLabel: "Gender",
+  formGenderPlaceholder: "Select your gender",
+  formCountryLabel: "Country",
+  formCountryPlaceholder: "Select your country",
+  formPhoneNumberLabel: "Phone Number",
+  formPhoneNumberPlaceholder: "Enter your phone number",
+  submitButtonLabel: "Subscribe Now",
+  successTitle: "Welcome Aboard!",
+  successDescription: "Thank you for joining our community. Check your email for next steps.",
+  privacyPolicyUrlLabel: "Privacy Policy",
+  termsAndConditionsUrlLabel: "Terms & Conditions",
+  presentedByLabel: "Powered by"
+};
+
+<CollectLead {...otherProps} labels={labels} />
+```
+
+#### Success Actions
+
+Configure what happens after successful form submission:
+
+```tsx
+import { OnSuccessCTADetails } from "fansunited-frontend-core";
+
+// Custom success action with onClick handler
+const onSuccessCTA: OnSuccessCTADetails = {
+  defaultLabel: "Continue to Dashboard",
+  onClick: () => {
+    // Handle post-submission logic
+    window.location.href = "/dashboard";
+  }
+};
+
+// Success action with URL navigation
+const onSuccessCTA: OnSuccessCTADetails = {
+  defaultLabel: "Visit Our Website",
+  url: "https://your-website.com",
+  target: "_blank"
+};
+
+// Custom success component
+const onSuccessCTA: OnSuccessCTADetails = {
+  component: <CustomSuccessButton />
+};
+
+<CollectLead {...otherProps} onSuccessCTA={onSuccessCTA} />
+```
+
+#### Examples
+
+##### Basic Lead Form
+
+```tsx
+import { CollectLead } from "fansunited-frontend-components";
+import { WidgetTemplate } from "fansunited-frontend-core";
+
+<CollectLead
+  entityId="lead-form-123"
+  sdk={sdkInstance}
+  template={WidgetTemplate.STANDARD}
+  language="en"
+  fields={["fullName", "email"]}
+/>
+```
+
+##### Advanced Lead Form
+
+```tsx
+<CollectLead
+  entityId="lead-form-123"
+  sdk={sdkInstance}
+  template={WidgetTemplate.OVERLAY}
+  language="en"
+  fields={["fullName", "email", "phoneNumber", "country"]}
+  phoneCountryCode="44"
+  customFields={[
+    {
+      key: "company",
+      label: "Company",
+      type: "input",
+      required: true
+    }
+  ]}
+  consents={[
+    {
+      id: "marketing",
+      label: "I agree to receive marketing emails"
+    }
+  ]}
+  labels={{
+    title: "Get Early Access",
+    submitButtonLabel: "Join Waitlist",
+    successTitle: "You're In!",
+    successDescription: "We'll notify you when we launch."
+  }}
+  onSuccessCTA={{
+    defaultLabel: "Learn More",
+    url: "https://example.com/learn-more",
+    target: "_blank"
+  }}
+  themeOptions={{
+    mode: "dark"
+  }}
+/>
+```
+
+### PersonalityQuizPlay
+
+Interactive personality quiz component that matches users with personas based on their answers. Features comprehensive result displays with persona matching, detailed explanations, and customizable templates.
+
+**Key Features:**
+- Personality matching algorithm with percentage scores
+- Multiple persona results with detailed descriptions
+- Tabbed result interface with top match highlighting
+- Answer explanations and persona insights
+- Three responsive templates (Standard, Split, Overlay)
+- Lead collection integration
+- Authentication support
+- Custom theming and branding
+- Result sharing capabilities
+
+#### Required Props
+
+| Prop       | Type                 | Description                        |
+| ---------- | -------------------- | ---------------------------------- |
+| `entityId` | `string`             | Personality Quiz identifier        |
+| `sdk`      | `FansUnitedSDKModel` | SDK instance                       |
+| `template` | `WidgetTemplate`     | Layout template                    |
+| `language` | `LanguageType`       | Display language                   |
+
+#### Optional Props
+
+| Prop                         | Type                 | Description                                 |
+| ---------------------------- | -------------------- | ------------------------------------------- |
+| `themeOptions`               | `CustomThemeOptions` | Theme configuration                         |
+| `showAnswerExplanations`     | `boolean`            | Show explanations after quiz completion     |
+| `leads`                      | `LeadsOptions`       | Lead collection settings                    |
+| `imagePosition`              | `"left" \| "right"`  | Image position (STANDARD template only)     |
+| `defaultImagePlaceholderUrl` | `string`             | URL for default image placeholder           |
+| `userIsLoggedIn`             | `boolean`            | Determine if the user is logged in          |
+| `signInCTA`                  | `SignInCTADetails`   | Sign in call to action button configuration |
+| `optionsLayout`              | `OptionsLayout`      | Layout for answer options                   |
+
+#### Templates
+
+```tsx
+import { WidgetTemplate, PersonalityQuizPlayProps } from "fansunited-frontend-core";
+
+// Standard template with optional image positioning
+const standardProps: PersonalityQuizPlayProps = {
+  template: WidgetTemplate.STANDARD,
+  imagePosition: "left", // or 'right'
+  // ... other props
+};
+
+// Split template - side-by-side layout
+const splitProps: PersonalityQuizPlayProps = {
+  template: WidgetTemplate.SPLIT,
+  // imagePosition not available for non-standard templates
+  // ... other props
+};
+
+// Overlay template - full-screen immersive experience
+const overlayProps: PersonalityQuizPlayProps = {
+  template: WidgetTemplate.OVERLAY,
+  // ... other props
+};
+```
+
+#### Options Layout
+
+Configure how answer options are displayed:
+
+```tsx
+import { OptionsLayout } from "fansunited-frontend-core";
+
+// Two-by-two grid layout
+const twoByTwoLayout: PersonalityQuizPlayProps = {
+  optionsLayout: "twoByTwo",
+  // ... other props
+};
+
+// Horizontal row layout
+const rowLayout: PersonalityQuizPlayProps = {
+  optionsLayout: "row",
+  // ... other props
+};
+
+// Vertical column layout
+const columnLayout: PersonalityQuizPlayProps = {
+  optionsLayout: "column",
+  // ... other props
+};
+```
+
+#### Sign in Configuration
+
+Control user authentication and quiz access using the `userIsLoggedIn` and `signInCTA` props.
+
+```tsx
+import { SignInCTADetails } from "fansunited-frontend-core";
+
+// Custom sign-in component
+const signInCTA: SignInCTADetails = {
+  component: <CustomSignInButton />
+};
+
+// Basic sign-in with onClick handler
+const signInCTA: SignInCTADetails = {
+  defaultLabel: "Sign in to take quiz",
+  onClick: () => {
+    // Handle sign-in logic
+    console.log("Sign in clicked");
+  }
+};
+
+// Sign-in with URL navigation
+const signInCTA: SignInCTADetails = {
+  defaultLabel: "Login to discover your personality",
+  url: "https://your-auth-provider.com/login",
+  target: "_blank"
+};
+
+<PersonalityQuizPlay
+  {...otherProps}
+  userIsLoggedIn={false}
+  signInCTA={signInCTA}
+/>
+```
+
+**Sign-in Priority Order:**
+
+1. **Custom Component** - If `signInCTA.component` is provided, it will be rendered
+2. **Click Handler** - If `signInCTA.onClick` is provided, a button with the handler will be rendered
+3. **URL Navigation** - If `signInCTA.url` is provided, a button will be rendered and clicking will navigate to the URL
+4. **Disabled** - If no `signInCTA` is provided, a disabled button will be shown
+
+**Behavior:**
+
+- When `userIsLoggedIn` is `false` and the quiz requires authentication (`authRequirement: "REGISTERED"`), the sign-in screen will be displayed instead of the quiz
+
+#### Lead Collection
+
+Capture user information before or after taking the personality quiz:
+
+```tsx
+import { LeadsOptions } from "fansunited-frontend-core";
+
+const leads: LeadsOptions = {
+  position: "before", // "before" | "after"
+  fields: ["fullName", "email"], // Available: "fullName" | "firstName" | "lastName" | "email" | "gender" | "country" | "phoneCountryCode" | "phoneNumber"
+  campaignId: "personality-quiz-2024",
+  campaignName: "Personality Assessment Campaign",
+  phoneCountryCode: "1", // Default country code for phone fields
+};
+
+<PersonalityQuizPlay {...otherProps} leads={leads} />
+```
+
+#### Answer Explanations
+
+Enable detailed explanations for quiz answers and persona matching:
+
+```tsx
+<PersonalityQuizPlay
+  {...otherProps}
+  showAnswerExplanations={true}
+/>
+```
+
+When enabled, users will see:
+- Explanations for each answer choice
+- Detailed persona descriptions
+- Matching algorithm insights
+- Percentage breakdowns for each persona
+
+#### Examples
+
+##### Basic Personality Quiz
+
+```tsx
+import { PersonalityQuizPlay } from "fansunited-frontend-components";
+import { WidgetTemplate } from "fansunited-frontend-core";
+
+<PersonalityQuizPlay
+  entityId="personality-quiz-123"
+  sdk={sdkInstance}
+  template={WidgetTemplate.STANDARD}
+  language="en"
+/>
+```
+
+##### Advanced Personality Quiz
+
+```tsx
+<PersonalityQuizPlay
+  entityId="personality-quiz-123"
+  sdk={sdkInstance}
+  template={WidgetTemplate.OVERLAY}
+  language="en"
+  showAnswerExplanations={true}
+  optionsLayout="twoByTwo"
+  userIsLoggedIn={false}
+  signInCTA={{
+    defaultLabel: "Sign in to save results",
+    onClick: () => handleSignIn(),
+  }}
+  leads={{
+    position: "after",
+    fields: ["fullName", "email"],
+    campaignId: "personality-campaign",
+    campaignName: "Personality Assessment 2024",
+    phoneCountryCode: "44",
+  }}
+  themeOptions={{
+    mode: "dark",
+    colorSchemes: {
+      dark: {
+        textPrimary: "#ffffff",
+        surface: "#1a1a1a"
+      }
+    }
+  }}
+/>
+```
+
+##### Customized Layout
+
+```tsx
+<PersonalityQuizPlay
+  entityId="personality-quiz-123"
+  sdk={sdkInstance}
+  template={WidgetTemplate.STANDARD}
+  imagePosition="right"
+  language="en"
+  optionsLayout="column"
+  showAnswerExplanations={true}
+  themeOptions={{
+    mode: "light",
+    customFontFamily: {
+      light: {
+        primary: "Inter, sans-serif",
+        secondary: "Roboto, sans-serif"
+      }
+    }
+  }}
+/>
+```
+
+## Available Components
+
+This package exports the following components:
+
+- **`ClassicQuizPlay`** - Traditional quiz with scoring and explanations
+- **`PollVote`** - Interactive polling with real-time results
+- **`CollectLead`** - Lead collection forms with custom fields
+- **`PersonalityQuizPlay`** - Personality assessment with persona matching
+
+## Related Packages
 
 - [`fansunited-frontend-core`](https://www.npmjs.com/package/fansunited-frontend-core) - Core types and utilities

package/components.d.ts

@@ -1,6 +1,7 @@
-import { ClassicQuizPlayProps, PollVoteProps, CollectLeadProps } from 'fansunited-frontend-core';
+import { ClassicQuizPlayProps, PollVoteProps, CollectLeadProps, PersonalityQuizPlayProps } from 'fansunited-frontend-core';
 
 export declare const ClassicQuizPlay: React.FC<ClassicQuizPlayProps>;
 export declare const PollVote: React.FC<PollVoteProps>;
 export declare const CollectLead: React.FC<CollectLeadProps>;
+export declare const PersonalityQuizPlay: React.FC<PersonalityQuizPlayProps>;
 //# sourceMappingURL=components.d.ts.map

package/components.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../../src/components.tsx"],"names":[],"mappings":"AAGA,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,gBAAgB,EACjB,MAAM,0BAA0B,CAAC;AAIlC,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,EAAE,CAAC,oBAAoB,CACjC,CAAC;AAE3B,eAAO,MAAM,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC,aAAa,CAAqB,CAAC;AAEnE,eAAO,MAAM,WAAW,EAAE,KAAK,CAAC,EAAE,CAAC,gBAAgB,CAAwB,CAAC"}
+{"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../../src/components.tsx"],"names":[],"mappings":"AAIA,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,gBAAgB,EAChB,wBAAwB,EACzB,MAAM,0BAA0B,CAAC;AAIlC,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,EAAE,CAAC,oBAAoB,CACjC,CAAC;AAE3B,eAAO,MAAM,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC,aAAa,CAAqB,CAAC;AAEnE,eAAO,MAAM,WAAW,EAAE,KAAK,CAAC,EAAE,CAAC,gBAAgB,CAAwB,CAAC;AAE5E,eAAO,MAAM,mBAAmB,EAAE,KAAK,CAAC,EAAE,CAAC,wBAAwB,CACrC,CAAC"}