Fans United Frontend Core

Core utilities, types, and shared functionality for Fans United widget packages.

Installation

npm install fansunited-frontend-core

yarn add fansunited-frontend-core

Features

• Complete TypeScript definitions for all Fans United components
• Theme management with light/dark mode support
• Internationalization (i18n) with 10+ supported languages
• Shared utilities and helper functions
• React providers and hooks
• Component primitives

Core Exports

Types and Interfaces

import {
  // Component Props
  ClassicQuizPlayProps,
  BaseClassicQuizPlayProps,
  ClassicQuizAwarenessProps,
  PollVoteProps,
  BasePollVoteProps,
  PersonalityQuizPlayProps,
  BasePersonalityQuizPlayProps,
  CollectLeadProps,
  BaseCollectLeadProps,
  CollectLeadFormProps,
  CollectLeadMainProps,
  MainProps,

  // Configuration Interfaces
  Configuration,
  ClassicQuizAwarenessConfiguration,
  ClassicQuizPlayConfiguration,

  // Theme and Styling
  CustomThemeOptions,
  EnhancedCustomThemeOptions,
  InternalCustomThemeOptions,
  CustomColors,
  InternalCustomColors,
  CustomSpacingScale,
  CustomBorderRadius,
  CustomBorderSize,
  CustomBreakpoints,
  ImageBackgroundGradient,
  FontConfig,
  ThemeMode,

  // Lead Management
  LeadsOptions,
  LeadCustomField,
  LeadConsent,
  LeadLabels,
  FormLeadLabels,

  // Content and Branding
  ContentInfo,
  CampaignInfo,
  BrandingInfo,
  BrandingImages,
  FormBrandingInfo,
  FormBrandingImages,
  BrandingColors,
  BrandingUrls,

  // CTA and User Interaction
  CTADetails,
  SignInCTADetails,
  OnSuccessCTADetails,
  AdditionalCTADetails,

  // Analytics and Events
  AnalyticsEvent,
  UserState,

  // Enums
  WidgetTemplate
} from "fansunited-frontend-core";

Type Definitions

import {
  // Journey and Analytics Types
  JourneyType,
  StageType,
  ActionType,
  CTAType,
  StagesType,
  WidgetType,

  // UI and Layout Types
  LinkTargetType,
  ContentViewType,
  OptionsLayout,

  // Internationalization
  LanguageType,

  // Lead Collection
  LeadField,
  LeadPosition,
  CountryType,
  ContentType,

  // Hook Types
  UseLeadFormParams,
  UseLeadFormReturn,
  LeadFormData
} from "fansunited-frontend-core";

Theme Utilities

import {
  useSpacingScale,
  getSpacing,
  useFontFamily,
  useCornerRadius,
  useColors,
  useBorderSize,
  useInternalTheme,
  useImageBackgroundGradient
} from "fansunited-frontend-core";

Helper Functions

import {
  stripHtmlTags,
  hexToRgb,
  isAndroid,
  isMobile,
  getDefaultCountryByCode,
  getDefaultCountryByLanguage,
  extractBrandingProperties,
  sanitizeBackgroundUrl,
  mapContentTypeToConsentEntityType
} from "fansunited-frontend-core";

React Hooks

import {
  useImageUrl,
  useThemeMode,
  useConstantContext,
  useImageVariant,
  useLeadForm
} from "fansunited-frontend-core";

// Example: Lead form hook usage
const leadForm = useLeadForm({
  sdk: sdkInstance,
  fields: ["fullName", "email"],
  campaignId: "campaign-123",
  contentType: "quiz",
  contentId: "quiz-456",
  syncWithProfile: true // Optional: sync form data to user profile
});

React Providers

import {
  ThemeProvider,
  ConstantsProvider,
  ConstantsContext
} from "fansunited-frontend-core";

// Example: Theme provider setup
<ThemeProvider themeOptions={customTheme}>
  <ConstantsProvider
    shadowRootElement={shadowRoot}
    leadPhoneCountryCode="US"
    language="en"
    optionsLayout="twoByTwo"
  >
    <YourApp />
  </ConstantsProvider>
</ThemeProvider>

Components

import {
  Spinner,
  CollectLeadForm
} from "fansunited-frontend-core";

// Example: Spinner component
<Spinner my={4} />

// Example: Lead collection form
<CollectLeadForm
  sdk={sdkInstance}
  fields={["fullName", "email"]}
  labels={{
    title: "Join Our Newsletter",
    submitButtonLabel: "Subscribe"
  }}
/>

Constants

import {
  validWidgetTypes,
  validWidgetTemplates,
  countries,
  languageToCountryCode
} from "fansunited-frontend-core";

// Access predefined country list
const countryOptions = countries;

// Get country code by language
const countryCode = languageToCountryCode["en"]; // "GB"

Internationalization

import { initializeI18n } from "fansunited-frontend-core";

// Initialize with preferred language
initializeI18n("en");

Call-to-Action (CTA) Interfaces

The package provides several CTA interfaces for different use cases:

AdditionalCTADetails

Configure additional call-to-action buttons for widget completion screens.

import { AdditionalCTADetails } from "fansunited-frontend-core";

// Custom component
const additionalCTA: AdditionalCTADetails = {
  component: <CustomCTAButton />,
};

// Basic CTA with onClick handler
const additionalCTA: AdditionalCTADetails = {
  defaultLabel: "Learn More",
  onClick: () => {
    console.log("Additional CTA clicked");
  },
};

// CTA with URL navigation
const additionalCTA: AdditionalCTADetails = {
  defaultLabel: "Visit Website",
  url: "https://your-website.com",
  target: "_blank", // or "_self"
};

Interface Definition:

interface AdditionalCTADetails {
  defaultLabel?: string; // Not required when component is provided
  onClick?: () => void; // Required when only defaultLabel is provided
  url?: string | null;
  target?: LinkTargetType; // "_blank" | "_self" | "_parent" | "_top"
  component?: React.ReactElement | null;
}

Priority Order:

1. Custom Component - If component is provided, it will be rendered
2. Click Handler - If onClick is provided, a button with the handler will be rendered
3. URL Navigation - If url is provided, a button will be rendered and clicking will navigate to the URL

Usage:

• ClassicQuizPlay: Displayed after "Play Again" and "Share Result" buttons (Standard), after "Play Again" (Split), after "Play Again" and "Share Result" (Overlay)
• PollVote: Displayed before "Vote Again" (Standard), same container as "Vote Again" (Split), after "Vote Again" (Overlay)
• PersonalityQuizPlay: Displayed before "Play Again" (Standard), in thank you container after "Play Again" (Split), after "Play Again" if available (Overlay)
• MatchQuizPlay: Displayed same line as branding logo (Standard), centered after main content (Split), same line as branding logo (Overlay)

SignInCTADetails

Configure sign-in call-to-action buttons for authentication-required widgets.

import { SignInCTADetails } from "fansunited-frontend-core";

// Custom component
const signInCTA: SignInCTADetails = {
  component: <CustomSignInButton />,
};

// Basic sign-in with onClick handler
const signInCTA: SignInCTADetails = {
  defaultLabel: "Sign In",
  onClick: () => {
    console.log("Sign in clicked");
  },
};

// Sign-in with URL navigation
const signInCTA: SignInCTADetails = {
  defaultLabel: "Login",
  url: "https://your-auth-provider.com/login",
  target: "_blank",
};

Interface Definition:

interface SignInCTADetails {
  defaultLabel?: string; // Not required when component is provided
  onClick?: () => void; // Required when only defaultLabel is provided
  url?: string | null;
  target?: LinkTargetType; // "_blank" | "_self" | "_parent" | "_top"
  component?: React.ReactElement | null;
}

Supported Languages

• English (en)
• Bulgarian (bg)
• German (de)
• Greek (el)
• Spanish (es)
• French (fr)
• Belgian French (fr-be)
• Italian (it)
• Polish (pl)
• Portuguese (pt)
• Brazilian Portuguese (pt-br)
• Romanian (ro)
• Serbian (sr)
• Slovak (sk)

Usage Examples

Basic Widget Setup

This package is designed to work with fansunited-frontend-components:

import { ClassicQuizPlay } from "fansunited-frontend-components";
import { WidgetTemplate, CustomThemeOptions } from "fansunited-frontend-core";

const customTheme: CustomThemeOptions = {
  mode: "light",
  colorSchemes: {
    light: {
      textPrimary: "#333333",
      surface: "#ffffff"
    }
  }
};

<ClassicQuizPlay
  entityId="quiz-123"
  sdk={sdkInstance}
  template={WidgetTemplate.STANDARD}
  language="en"
  themeOptions={customTheme}
  imagePosition="left"
/>;

Lead Collection Setup

import { CollectLead } from "fansunited-frontend-components";
import {
  WidgetTemplate,
  LeadField,
  LeadCustomField,
  LeadConsent
} from "fansunited-frontend-core";

const leadFields: LeadField[] = ["fullName", "email", "phoneNumber"];

const customFields: LeadCustomField[] = [
  {
    key: "company",
    label: "Company Name",
    type: "input",
    required: true,
    placeholder: "Enter your company name"
  }
];

const consents: LeadConsent[] = [
  {
    id: "marketing",
    label: "I agree to receive marketing communications"
  }
];

<CollectLead
  entityId="lead-form-123"
  sdk={sdkInstance}
  template={WidgetTemplate.OVERLAY}
  language="en"
  fields={leadFields}
  customFields={customFields}
  consents={consents}
  syncWithProfile={true} // Sync form data to user profile
  labels={{
    title: "Get Exclusive Updates",
    submitButtonLabel: "Subscribe Now"
  }}
/>

Theme Customization

import {
  ThemeProvider,
  CustomThemeOptions,
  FontConfig
} from "fansunited-frontend-core";

const customFont: FontConfig = {
  family: "Inter",
  url: "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap",
  weights: [400, 500, 600, 700],
  display: "swap"
};

const themeOptions: CustomThemeOptions = {
  mode: "dark",
  customFontFamily: {
    light: {
      primary: customFont,
      secondary: "Arial, sans-serif"
    },
    dark: {
      primary: customFont,
      secondary: "Arial, sans-serif"
    }
  },
  spacingScale: {
    xs: "6px",
    sm: "12px",
    md: "18px",
    lg: "24px"
  },
  colorSchemes: {
    dark: {
      textPrimary: "#ffffff",
      surface: "#1a1a1a",
      palette: {
        primary: {
          plainColor: "#3b82f6",
          primaryContainer: "#1e40af"
        }
      }
    }
  }
};

<ThemeProvider themeOptions={themeOptions}>
  <YourApp />
</ThemeProvider>

Using Hooks

import {
  useLeadForm,
  useThemeMode,
  useColors,
  UseLeadFormParams
} from "fansunited-frontend-core";

function MyComponent() {
  // Theme utilities
  const colors = useColors();
  const { mode, setMode } = useThemeMode();

  // Lead form management
  const leadFormParams: UseLeadFormParams = {
    sdk: sdkInstance,
    fields: ["fullName", "email"],
    campaignId: "newsletter-2024",
    contentType: "quiz",
    contentId: "quiz-123"
  };

  const {
    formData,
    updateField,
    submitForm,
    isSubmitting,
    isSuccess,
    error
  } = useLeadForm(leadFormParams);

  return (
    <div style={{ backgroundColor: colors.surface }}>
      <button onClick={() => setMode(mode === "light" ? "dark" : "light")}>
        Toggle Theme
      </button>
      {/* Your form UI */}
    </div>
  );
}

Country and Language Utilities

import {
  countries,
  languageToCountryCode,
  getDefaultCountryByLanguage,
  getDefaultCountryByCode
} from "fansunited-frontend-core";

// Get all available countries
const allCountries = countries;

// Get suggested countries only
const suggestedCountries = countries.filter(country => country.suggested);

// Get default country by language
const defaultCountry = getDefaultCountryByLanguage("fr"); // Returns France

// Get country by code
const usCountry = getDefaultCountryByCode("US");

Widget Templates

The package supports three main widget templates:

• WidgetTemplate.STANDARD - Traditional card layout with optional image positioning
• WidgetTemplate.OVERLAY - Full-screen overlay presentation
• WidgetTemplate.SPLIT - Split-screen layout with content and media sections

TypeScript Support

This package is built with TypeScript and provides comprehensive type definitions for all exports. The types ensure type safety when working with widget configurations, theme options, and component props.

License

© Fans United Media. All rights reserved.