fansunited-frontend-components 0.0.23-RC1 → 0.0.23-RC2

package/README.md

@@ -289,26 +289,26 @@ const signInCTA: SignInCTADetails = {
   onClick: () => {
     // Handle sign-in logic
     console.log("Sign in clicked");
-  }
+  },
 };
 
 // Sign-in with URL navigation
 const signInCTA: SignInCTADetails = {
   defaultLabel: "Login",
   url: "https://your-auth-provider.com/login",
-  target: "_blank" // or "_self"
+  target: "_blank", // or "_self"
 };
 
 // Custom sign-in component
 const signInCTA: SignInCTADetails = {
-  component: <CustomSignInButton />
+  component: <CustomSignInButton />,
 };
 
 <ClassicQuizPlay
   {...otherProps}
   userIsLoggedIn={false}
   signInCTA={signInCTA}
-/>
+/>;
 ```
 
 **Sign-in Priority Order:**
@@ -390,6 +390,7 @@ import { WidgetTemplate } from "fansunited-frontend-core";
 Interactive poll voting component with real-time results, multiple choice support, and customizable templates. Perfect for engaging audiences with opinion polls, surveys, and voting campaigns.
 
 **Key Features:**
+
 - Single and multiple choice voting
 - Real-time vote results and percentages
 - Three responsive templates (Standard, Split, Overlay)
@@ -453,7 +454,7 @@ import { SignInCTADetails } from "fansunited-frontend-core";
 
 // Custom sign-in component
 const signInCTA: SignInCTADetails = {
-  component: <CustomSignInButton />
+  component: <CustomSignInButton />,
 };
 
 // Basic sign-in with onClick handler
@@ -462,21 +463,17 @@ const signInCTA: SignInCTADetails = {
   onClick: () => {
     // Handle sign-in logic
     console.log("Sign in clicked");
-  }
+  },
 };
 
 // Sign-in with URL navigation
 const signInCTA: SignInCTADetails = {
   defaultLabel: "Login to participate",
   url: "https://your-auth-provider.com/login",
-  target: "_blank"
+  target: "_blank",
 };
 
-<PollVote
-  {...otherProps}
-  userIsLoggedIn={false}
-  signInCTA={signInCTA}
-/>
+<PollVote {...otherProps} userIsLoggedIn={false} signInCTA={signInCTA} />;
 ```
 
 **Sign-in Priority Order:**
@@ -555,6 +552,7 @@ import { WidgetTemplate } from "fansunited-frontend-core";
 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
@@ -565,30 +563,30 @@ Lead collection component for capturing user information with customizable forms
 
 #### Required Props
 
-| Prop       | Type                 | Description                    |
-| ---------- | -------------------- | ------------------------------ |
+| Prop       | Type                 | Description                     |
+| ---------- | -------------------- | ------------------------------- |
 | `entityId` | `string`             | Lead collection form identifier |
-| `sdk`      | `FansUnitedSDKModel` | SDK instance                   |
-| `template` | `WidgetTemplate`     | Layout template                |
-| `language` | `LanguageType`       | Display language               |
+| `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                                |
+| 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
 
@@ -621,7 +619,11 @@ const overlayProps: CollectLeadProps = {
 Configure which fields to display and their behavior:
 
 ```tsx
-import { LeadField, LeadCustomField, LeadConsent } from "fansunited-frontend-core";
+import {
+  LeadField,
+  LeadCustomField,
+  LeadConsent,
+} from "fansunited-frontend-core";
 
 // Standard form fields
 const fields: LeadField[] = [
@@ -629,7 +631,7 @@ const fields: LeadField[] = [
   "email",
   "phoneNumber",
   "country",
-  "gender"
+  "gender",
 ];
 
 // Custom fields for additional data collection
@@ -639,27 +641,27 @@ const customFields: LeadCustomField[] = [
     label: "Company Name",
     type: "input",
     required: true,
-    placeholder: "Enter your company name"
+    placeholder: "Enter your company name",
   },
   {
     key: "message",
     label: "Message",
     type: "textarea",
     required: false,
-    placeholder: "Tell us about your needs..."
-  }
+    placeholder: "Tell us about your needs...",
+  },
 ];
 
 // Consent checkboxes for privacy compliance
 const consents: LeadConsent[] = [
   {
     id: "marketing",
-    label: "I agree to receive marketing communications"
+    label: "I agree to receive marketing communications",
   },
   {
     id: "newsletter",
-    label: "Subscribe to our newsletter"
-  }
+    label: "Subscribe to our newsletter",
+  },
 ];
 
 <CollectLead
@@ -667,7 +669,7 @@ const consents: LeadConsent[] = [
   fields={fields}
   customFields={customFields}
   consents={consents}
-/>
+/>;
 ```
 
 #### Custom Labels
@@ -693,13 +695,14 @@ const labels: LeadLabels = {
   formPhoneNumberPlaceholder: "Enter your phone number",
   submitButtonLabel: "Subscribe Now",
   successTitle: "Welcome Aboard!",
-  successDescription: "Thank you for joining our community. Check your email for next steps.",
+  successDescription:
+    "Thank you for joining our community. Check your email for next steps.",
   privacyPolicyUrlLabel: "Privacy Policy",
   termsAndConditionsUrlLabel: "Terms & Conditions",
-  presentedByLabel: "Powered by"
+  presentedByLabel: "Powered by",
 };
 
-<CollectLead {...otherProps} labels={labels} />
+<CollectLead {...otherProps} labels={labels} />;
 ```
 
 #### Success Actions
@@ -715,22 +718,22 @@ const onSuccessCTA: OnSuccessCTADetails = {
   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"
+  target: "_blank",
 };
 
 // Custom success component
 const onSuccessCTA: OnSuccessCTADetails = {
-  component: <CustomSuccessButton />
+  component: <CustomSuccessButton />,
 };
 
-<CollectLead {...otherProps} onSuccessCTA={onSuccessCTA} />
+<CollectLead {...otherProps} onSuccessCTA={onSuccessCTA} />;
 ```
 
 #### Examples
@@ -747,7 +750,7 @@ import { WidgetTemplate } from "fansunited-frontend-core";
   template={WidgetTemplate.STANDARD}
   language="en"
   fields={["fullName", "email"]}
-/>
+/>;
 ```
 
 ##### Advanced Lead Form
@@ -765,28 +768,28 @@ import { WidgetTemplate } from "fansunited-frontend-core";
       key: "company",
       label: "Company",
       type: "input",
-      required: true
-    }
+      required: true,
+    },
   ]}
   consents={[
     {
       id: "marketing",
-      label: "I agree to receive marketing emails"
-    }
+      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."
+    successDescription: "We'll notify you when we launch.",
   }}
   onSuccessCTA={{
     defaultLabel: "Learn More",
     url: "https://example.com/learn-more",
-    target: "_blank"
+    target: "_blank",
   }}
   themeOptions={{
-    mode: "dark"
+    mode: "dark",
   }}
 />
 ```
@@ -796,6 +799,7 @@ import { WidgetTemplate } from "fansunited-frontend-core";
 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
@@ -808,12 +812,12 @@ Interactive personality quiz component that matches users with personas based on
 
 #### Required Props
 
-| Prop       | Type                 | Description                        |
-| ---------- | -------------------- | ---------------------------------- |
-| `entityId` | `string`             | Personality Quiz identifier        |
-| `sdk`      | `FansUnitedSDKModel` | SDK instance                       |
-| `template` | `WidgetTemplate`     | Layout template                    |
-| `language` | `LanguageType`       | Display language                   |
+| Prop       | Type                 | Description                 |
+| ---------- | -------------------- | --------------------------- |
+| `entityId` | `string`             | Personality Quiz identifier |
+| `sdk`      | `FansUnitedSDKModel` | SDK instance                |
+| `template` | `WidgetTemplate`     | Layout template             |
+| `language` | `LanguageType`       | Display language            |
 
 #### Optional Props
 
@@ -831,7 +835,10 @@ Interactive personality quiz component that matches users with personas based on
 #### Templates
 
 ```tsx
-import { WidgetTemplate, PersonalityQuizPlayProps } from "fansunited-frontend-core";
+import {
+  WidgetTemplate,
+  PersonalityQuizPlayProps,
+} from "fansunited-frontend-core";
 
 // Standard template with optional image positioning
 const standardProps: PersonalityQuizPlayProps = {
@@ -889,7 +896,7 @@ import { SignInCTADetails } from "fansunited-frontend-core";
 
 // Custom sign-in component
 const signInCTA: SignInCTADetails = {
-  component: <CustomSignInButton />
+  component: <CustomSignInButton />,
 };
 
 // Basic sign-in with onClick handler
@@ -898,21 +905,21 @@ const signInCTA: SignInCTADetails = {
   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"
+  target: "_blank",
 };
 
 <PersonalityQuizPlay
   {...otherProps}
   userIsLoggedIn={false}
   signInCTA={signInCTA}
-/>
+/>;
 ```
 
 **Sign-in Priority Order:**
@@ -941,7 +948,7 @@ const leads: LeadsOptions = {
   phoneCountryCode: "1", // Default country code for phone fields
 };
 
-<PersonalityQuizPlay {...otherProps} leads={leads} />
+<PersonalityQuizPlay {...otherProps} leads={leads} />;
 ```
 
 #### Answer Explanations
@@ -949,13 +956,11 @@ const leads: LeadsOptions = {
 Enable detailed explanations for quiz answers and persona matching:
 
 ```tsx
-<PersonalityQuizPlay
-  {...otherProps}
-  showAnswerExplanations={true}
-/>
+<PersonalityQuizPlay {...otherProps} showAnswerExplanations={true} />
 ```
 
 When enabled, users will see:
+
 - Explanations for each answer choice
 - Detailed persona descriptions
 - Matching algorithm insights
@@ -974,7 +979,7 @@ import { WidgetTemplate } from "fansunited-frontend-core";
   sdk={sdkInstance}
   template={WidgetTemplate.STANDARD}
   language="en"
-/>
+/>;
 ```
 
 ##### Advanced Personality Quiz
@@ -1004,9 +1009,9 @@ import { WidgetTemplate } from "fansunited-frontend-core";
     colorSchemes: {
       dark: {
         textPrimary: "#ffffff",
-        surface: "#1a1a1a"
-      }
-    }
+        surface: "#1a1a1a",
+      },
+    },
   }}
 />
 ```
@@ -1027,9 +1032,303 @@ import { WidgetTemplate } from "fansunited-frontend-core";
     customFontFamily: {
       light: {
         primary: "Inter, sans-serif",
-        secondary: "Roboto, sans-serif"
-      }
-    }
+        secondary: "Roboto, sans-serif",
+      },
+    },
+  }}
+/>
+```
+
+### MatchQuizPlay
+
+Interactive match prediction quiz component that allows users to make predictions on various football match markets. Features multiple fixture types, real-time countdown timers, points system, and comprehensive result tracking with leaderboards.
+
+**Key Features:**
+
+- Multiple prediction markets (1X2, Correct Score, Player Markets, Over/Under Goals, Corners, etc.)
+- Real-time countdown timer for prediction cutoff
+- Points system with loyalty integration
+- Leaderboard and ranking system
+- Prediction summary and editing capabilities
+- Three responsive templates (Standard, Split, Overlay)
+- Lead collection integration
+- Authentication support
+- Custom theming and branding
+- Detailed prediction results and explanations
+
+#### Required Props
+
+| Prop       | Type                 | Description           |
+| ---------- | -------------------- | --------------------- |
+| `entityId` | `string`             | Match Quiz identifier |
+| `sdk`      | `FansUnitedSDKModel` | SDK instance          |
+| `template` | `WidgetTemplate`     | Layout template       |
+| `language` | `LanguageType`       | Display language      |
+
+#### Optional Props
+
+| Prop                         | Type                 | Description                                       |
+| ---------------------------- | -------------------- | ------------------------------------------------- |
+| `themeOptions`               | `CustomThemeOptions` | Theme configuration                               |
+| `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       |
+| `showCountdown`              | `boolean`            | Show countdown timer when Match Quiz is open      |
+| `showTeamLabels`             | `boolean`            | Show team name labels in fixture components       |
+| `showPoints`                 | `boolean`            | Show points display for each fixture              |
+| `showPredictionDetails`      | `boolean`            | Show detailed prediction results after completion |
+
+#### Templates
+
+```tsx
+import { WidgetTemplate, MatchQuizPlayProps } from "fansunited-frontend-core";
+
+// Standard template with optional image positioning
+const standardProps: MatchQuizPlayProps = {
+  template: WidgetTemplate.STANDARD,
+  imagePosition: "left", // or 'right'
+  // ... other props
+};
+
+// Split template - side-by-side layout
+const splitProps: MatchQuizPlayProps = {
+  template: WidgetTemplate.SPLIT,
+  // imagePosition not available for non-standard templates
+  // ... other props
+};
+
+// Overlay template - full-screen immersive experience
+const overlayProps: MatchQuizPlayProps = {
+  template: WidgetTemplate.OVERLAY,
+  // ... other props
+};
+```
+
+#### Supported Markets
+
+MatchQuizPlay supports a wide variety of football prediction markets:
+
+**Match Result Markets:**
+
+- `FT_1X2` - Full Time 1X2 (Home Win, Draw, Away Win)
+- `HT_1X2` - Half Time 1X2
+
+**Score Markets:**
+
+- `CORRECT_SCORE` - Exact final score prediction
+- `CORRECT_SCORE_HT` - Exact half-time score prediction
+- `CORRECT_SCORE_ADVANCED` - Advanced correct score with alternative points
+
+**Player Markets:**
+
+- `PLAYER_SCORE_FIRST_GOAL` - First goalscorer prediction
+- `PLAYER_SCORE` - Anytime goalscorer
+- `PLAYER_YELLOW_CARD` - Player to receive yellow card
+- `PLAYER_RED_CARD` - Player to receive red card
+- `PLAYER_SCORE_HATTRICK` - Player to score hat-trick
+- `PLAYER_SCORE_TWICE` - Player to score twice
+
+**Over/Under Markets:**
+
+- `OVER_GOALS_0_5` to `OVER_GOALS_6_5` - Total goals over/under
+- `OVER_CORNERS_6_5` to `OVER_CORNERS_13_5` - Total corners over/under
+
+**Special Markets:**
+
+- `CORNERS_MATCH` - Total corners in the match
+- `PENALTY_MATCH` - Penalty awarded in the match
+- `RED_CARD_MATCH` - Red card shown in the match
+
+#### Game Status States
+
+Match quizzes have 5 distinct status states:
+
+- **`PENDING`** - Not yet open for predictions
+- **`OPEN`** - Ready for predictions (default state)
+- **`LIVE`** - Match has started, no new predictions accepted
+- **`CLOSED`** - Match finished, backend resolving predictions
+- **`SETTLED`** - Predictions resolved, leaderboard available
+
+#### Countdown Timer
+
+Enable countdown timer to show time remaining for predictions:
+
+```tsx
+<MatchQuizPlay {...otherProps} showCountdown={true} />
+```
+
+The countdown timer:
+
+- Displays when Match Quiz status is `OPEN`
+- Shows days, hours, minutes, and seconds remaining
+- Uses `predictionsCutoffTime` from the Match Quiz data
+- Automatically hides when cutoff time is reached
+
+#### Points System
+
+Enable points display to show potential rewards:
+
+```tsx
+<MatchQuizPlay {...otherProps} showPoints={true} />
+```
+
+Points system features:
+
+- Shows potential points for each fixture
+- Displays earned vs possible points
+- Integrates with loyalty system configuration
+- Supports alternative point structures for advanced markets
+- Mobile-friendly tooltip display
+
+#### Prediction Details
+
+Show detailed prediction results and explanations:
+
+```tsx
+<MatchQuizPlay {...otherProps} showPredictionDetails={true} />
+```
+
+When enabled, users see:
+
+- Tabulated interface
+- Correct vs incorrect prediction highlighting
+- Detailed market results
+- Points breakdown per fixture
+
+#### 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 predict",
+  onClick: () => {
+    // Handle sign-in logic
+    console.log("Sign in clicked");
+  },
+};
+
+// Sign-in with URL navigation
+const signInCTA: SignInCTADetails = {
+  defaultLabel: "Login to join the competition",
+  url: "https://your-auth-provider.com/login",
+  target: "_blank",
+};
+
+<MatchQuizPlay {...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 making predictions:
+
+```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: "match-quiz-2024",
+  campaignName: "Football Prediction Campaign",
+  phoneCountryCode: "44", // Default country code for phone fields
+};
+
+<MatchQuizPlay {...otherProps} leads={leads} />;
+```
+
+#### Examples
+
+##### Basic Match Quiz
+
+```tsx
+import { MatchQuizPlay } from "fansunited-frontend-components";
+import { WidgetTemplate } from "fansunited-frontend-core";
+
+<MatchQuizPlay
+  entityId="match-quiz-123"
+  sdk={sdkInstance}
+  template={WidgetTemplate.STANDARD}
+  language="en"
+/>;
+```
+
+##### Advanced Match Quiz
+
+```tsx
+<MatchQuizPlay
+  entityId="match-quiz-123"
+  sdk={sdkInstance}
+  template={WidgetTemplate.OVERLAY}
+  language="en"
+  showCountdown={true}
+  showTeamLabels={true}
+  showPoints={true}
+  showPredictionDetails={true}
+  userIsLoggedIn={false}
+  signInCTA={{
+    defaultLabel: "Sign in to compete",
+    onClick: () => handleSignIn(),
+  }}
+  leads={{
+    position: "after",
+    fields: ["fullName", "email"],
+    campaignId: "match-prediction-campaign",
+    campaignName: "Football Predictions 2024",
+    phoneCountryCode: "44",
+  }}
+  themeOptions={{
+    mode: "dark",
+    colorSchemes: {
+      dark: {
+        textPrimary: "#ffffff",
+        surface: "#1a1a1a",
+      },
+    },
+  }}
+/>
+```
+
+##### Customized Layout
+
+```tsx
+<MatchQuizPlay
+  entityId="match-quiz-123"
+  sdk={sdkInstance}
+  template={WidgetTemplate.STANDARD}
+  imagePosition="right"
+  language="en"
+  showCountdown={true}
+  showTeamLabels={false}
+  showPoints={true}
+  themeOptions={{
+    mode: "light",
+    customFontFamily: {
+      light: {
+        primary: "Inter, sans-serif",
+        secondary: "Roboto, sans-serif",
+      },
+    },
   }}
 />
 ```
@@ -1042,6 +1341,7 @@ This package exports the following components:
 - **`PollVote`** - Interactive polling with real-time results
 - **`CollectLead`** - Lead collection forms with custom fields
 - **`PersonalityQuizPlay`** - Personality assessment with persona matching
+- **`MatchQuizPlay`** - Football match prediction quiz with multiple markets
 
 ## Related Packages