fansunited-frontend-components 0.0.49 → 0.0.52

package/README.md

@@ -3072,6 +3072,7 @@ Full-featured football score predictor component with a multi-tab interface for
 - Consent management with required/optional consent gates before predicting
 - Customisable banners in 6 positions within the Play tab
 - Authentication-aware UI with configurable sign-in CTA
+- Built-in Betslip integration — renders the Betslip widget automatically via the `betslip` prop with two trigger modes
 - Custom theming and multi-language support
 
 #### Required Props
@@ -3093,7 +3094,8 @@ Full-featured football score predictor component with a multi-tab interface for
 | `defaultImagePlaceholderUrl` | `string`             | Fallback image URL for the hero header              |
 | `playTabBanners`             | `PlayTabBanner[]`    | Custom banners rendered in the Play tab             |
 | `consents`                   | `ConsentDef[]`       | Consent definitions required before predicting      |
-| `matchCardBgImageUrl`        | `string`             | Background image URL for match prediction cards     |
+| `matchCardBgImageUrl`        | `string`                 | Background image URL for match prediction cards                                              |
+| `betslip`                    | `PredictorBetslipConfig` | Betslip integration config. Omit to disable. See [Betslip Integration](#betslip-integration) |
 
 #### Tabs
 
@@ -3229,6 +3231,67 @@ const consents: ConsentDef[] = [
 - Optional consents are shown in the same modal but do not block progression
 - Once accepted, consents are stored and the modal does not reappear
 
+#### Betslip Integration
+
+When the `betslip` prop is provided, the Predictor automatically renders a `Betslip` widget as a sibling alongside its own UI — you do not need to add a separate `<Betslip />` component to the page. The widget is configured entirely through `PredictorBetslipConfig`.
+
+```tsx
+import { PredictorBetslipConfig } from "fansunited-frontend-core";
+
+const betslipConfig: PredictorBetslipConfig = {
+  trigger: "predictions-only",
+  position: "side-right",
+  currency: "£",
+  stakePresets: [5, 10, 25, 50],
+  ctaUrlTemplate:
+    "https://your-bookmaker.com/bet?ids={selectionIds}&stake={stake}&ref={currentUrl}",
+};
+
+<Predictor {...otherProps} betslip={betslipConfig} />;
+```
+
+**`PredictorBetslipConfig` fields:**
+
+| Field                 | Type                      | Default              | Description                                                                               |
+| --------------------- | ------------------------- | -------------------- | ----------------------------------------------------------------------------------------- |
+| `trigger`             | `PredictorBetslipTrigger` | `"predictions-only"` | When to send selections to the betslip                                                    |
+| `position`            | `BetslipPosition`         | `"bottom-right"`     | Viewport position of the Betslip widget                                                   |
+| `maxSelections`       | `number`                  | `20`                 | Hard cap on simultaneous selections                                                       |
+| `stakePresets`        | `number[]`                | `[5, 10, 20]`        | Quick-select stake buttons                                                                |
+| `oddsPollingInterval` | `number`                  | `30000`              | Odds refresh interval in milliseconds                                                     |
+| `currency`            | `string`                  | `"€"`                | Currency symbol                                                                           |
+| `ctaUrlTemplate`      | `string`                  | —                    | Bookmaker deep-link URL with `{placeholder}` substitution                                 |
+| `brandingLogoUrl`     | `string`                  | —                    | Operator logo URL                                                                         |
+| `labels`              | `BetslipLabels`           | —                    | UI text overrides                                                                         |
+| `themeOptions`        | `CustomThemeOptions`      | —                    | Theme for the Betslip widget. Falls back to the Predictor's `themeOptions` when omitted   |
+
+**Trigger modes (`PredictorBetslipTrigger`):**
+
+```tsx
+type PredictorBetslipTrigger =
+  | "predictions-only" // score changes feed betslip (before submit)
+  | "odds-only";       // odds button click feeds betslip (after submit)
+```
+
+| Mode                  | When selections are sent                                                                                                                                                                                                                       |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `"predictions-only"`  | Every time the user edits a score (home/away increment or decrement). If the user submits without editing (e.g. a default 0:0), the selection is sent at submit time as a fallback. Derived outcome: `"1"` (home win), `"X"` (draw), `"2"` (away win). |
+| `"odds-only"`         | Only when the user clicks an odds button on the post-submit odds display. The odds button becomes a command-bus trigger instead of a direct bookmaker link.                                                                                     |
+
+**Selection format sent by Predictor:**
+
+```
+"{matchId}:FT_1X2:{outcomeKey}"
+// Examples:
+// "fb:m:451634:FT_1X2:1"  → home win
+// "fb:m:451634:FT_1X2:X"  → draw
+// "fb:m:451634:FT_1X2:2"  → away win
+```
+
+**Automatic removal:** When a user deletes a submitted prediction, the corresponding selection is automatically removed from the betslip via `betslipApi.removeSelection()`. When a score is edited after submission (in `"predictions-only"` mode), the new outcome replaces the old one in the betslip (upsert — no explicit removal needed).
+
+**Theme fallback:** If `betslip.themeOptions` is not provided, the Betslip widget inherits the Predictor's own `themeOptions`. A single `themeOptions` on the Predictor is enough to theme both components consistently.
+
 #### TypeScript Support
 
 Import types from `fansunited-frontend-core`:
@@ -3237,6 +3300,8 @@ Import types from `fansunited-frontend-core`:
 import {
   PredictorProps,
   PredictorTab,
+  PredictorBetslipConfig,
+  PredictorBetslipTrigger,
   PlayTabBanner,
   PlayTabBannerPosition,
   ConsentDef,
@@ -3328,6 +3393,462 @@ import { Predictor } from "fansunited-frontend-components";
 />
 ```
 
+##### With Betslip — Predictions Trigger
+
+Selections are sent to the Betslip automatically as the user edits scores, before they submit.
+
+```tsx
+<Predictor
+  entityId="predictor-template-123"
+  sdk={sdkInstance}
+  language="en"
+  userIsLoggedIn={true}
+  tabs={["play", "leaderboard"]}
+  betslip={{
+    trigger: "predictions-only",
+    position: "side-right",
+    currency: "£",
+    stakePresets: [5, 10, 25, 50],
+    ctaUrlTemplate:
+      "https://your-bookmaker.com/bet?ids={selectionIds}&stake={stake}&ref={currentUrl}",
+    labels: {
+      disclaimer: "18+ | Please gamble responsibly",
+    },
+  }}
+  themeOptions={{ mode: "dark" }}
+/>
+```
+
+##### With Betslip — Odds Trigger
+
+Selections are sent only when the user explicitly clicks an odds button on the post-submit view.
+
+```tsx
+<Predictor
+  entityId="predictor-template-123"
+  sdk={sdkInstance}
+  language="en"
+  userIsLoggedIn={true}
+  betslip={{
+    trigger: "odds-only",
+    position: "bottom-right",
+    currency: "€",
+    ctaUrlTemplate:
+      "https://your-bookmaker.com/bet?ids={selectionIds}&stake={stake}",
+  }}
+/>
+```
+
+---
+
+### Betslip
+
+A floating betslip component that collects selections from any external source and routes users to a bookmaker via a configurable deep-link URL. The component communicates with the rest of the page through a singleton command bus (`betslipApi`), so it decouples cleanly from host-page code.
+
+**Key Features:**
+
+- Six viewport positions: four corner anchors and two full-height side panels
+- Singleton command bus with pre-mount queuing — selections sent before the widget mounts are replayed on load
+- Automatic odds polling from the SDK with configurable interval
+- Bookmaker branding color automatically used as the primary accent (overridable via `themeOptions`)
+- Configurable CTA deep-link URL template with dynamic placeholder substitution
+- Shadow DOM style isolation — no CSS conflicts with the host application
+- Multi-language support and fully overridable UI text labels
+
+#### Quick Start
+
+```tsx
+import React from "react";
+import { Betslip } from "fansunited-frontend-components";
+import { betslipApi } from "fansunited-frontend-core";
+import { FansUnitedSDK } from "fansunited-sdk-esm";
+
+const sdk = FansUnitedSDK({ /* your config */ });
+
+const App: React.FC = () => (
+  <>
+    {/* Place once anywhere in the tree */}
+    <Betslip
+      sdk={sdk}
+      language="en"
+      position="bottom-right"
+      ctaUrlTemplate="https://your-bookmaker.com/betslip?selections={selectionIds}&stake={stake}"
+    />
+
+    {/* From anywhere in your app, add or remove selections */}
+    <button onClick={() => betslipApi.setSelection("fb:m:451678:FT_1X2:1")}>
+      Back Home Win
+    </button>
+  </>
+);
+```
+
+#### Required Props
+
+| Prop       | Type                 | Description      |
+| ---------- | -------------------- | ---------------- |
+| `sdk`      | `FansUnitedSDKModel` | SDK instance     |
+| `language` | `LanguageType`       | Display language |
+
+#### Optional Props
+
+| Prop                   | Type                 | Default          | Description                                                     |
+| ---------------------- | -------------------- | ---------------- | --------------------------------------------------------------- |
+| `position`             | `BetslipPosition`    | `"bottom-right"` | Viewport anchor. See [Positions](#positions) below              |
+| `maxSelections`        | `number`             | `20`             | Hard cap on simultaneous selections                             |
+| `stakePresets`         | `number[]`           | `[5, 10, 20]`    | Quick-select stake buttons shown in the footer                  |
+| `oddsPollingInterval`  | `number`             | `30000`          | Odds refresh interval in milliseconds                           |
+| `currency`             | `string`             | `"€"`            | Currency symbol shown next to stake and potential win           |
+| `ctaUrlTemplate`       | `string`             | —                | Deep-link URL template with `{placeholder}` substitution        |
+| `brandingLogoUrl`      | `string`             | —                | Operator logo URL that overrides the bookmaker logo             |
+| `labels`               | `BetslipLabels`      | —                | UI text overrides. See [Labels](#labels) below                  |
+| `themeOptions`         | `CustomThemeOptions` | —                | Theme tokens. See [Theming](#theming-1) below                   |
+
+#### Positions
+
+```tsx
+import { BetslipPosition } from "fansunited-frontend-core";
+
+type BetslipPosition =
+  | "bottom-right"  // Fixed corner anchor, slides up on open (default)
+  | "bottom-left"   // Fixed corner anchor, slides up on open
+  | "top-right"     // Fixed corner anchor, slides down on open
+  | "top-left"      // Fixed corner anchor, slides down on open
+  | "side-right"    // Full-height panel, slides in from the right
+  | "side-left";    // Full-height panel, slides in from the left
+```
+
+**Corner positions** (`bottom-*`, `top-*`):
+- 320 px wide, fixed 16 px from the viewport edges
+- Header shows an expand/collapse chevron
+- Collapsed state renders a compact summary (combined odds, stake, potential win)
+- Expanded state shows the full selection list (scrollable at 300 px max height) plus the stake/CTA footer
+
+**Side positions** (`side-*`):
+- 340 px wide panel covering full viewport height (100 vh)
+- A 32 × 64 px tab handle peeks out at 33 % from the top when closed — it shows the bookmaker/branding logo rotated 90°, or three grip lines when no logo is available
+- A selection count badge appears on the closed tab when `maxSelections` is set
+- Smooth 0.3 s slide-in/out transition
+
+#### Command Bus (`betslipApi`)
+
+The betslip exposes a singleton command bus for external code to manage selections without needing a direct reference to the React component.
+
+```tsx
+import { betslipApi } from "fansunited-frontend-core";
+
+// Add or replace a selection (same eventId + market = outcome replaced)
+betslipApi.setSelection("fb:m:451678:FT_1X2:1");
+
+// Remove a selection by its exact id
+betslipApi.removeSelection("fb:m:451678:FT_1X2:1");
+```
+
+**Selection ID format:**
+
+```
+"{eventId}:{market}:{outcome}"
+```
+
+| Segment    | Examples                                       |
+| ---------- | ---------------------------------------------- |
+| `eventId`  | `fb:m:451678`                                  |
+| `market`   | `FT_1X2`, `DOUBLE_CHANCE`, `OVER_GOALS_2_5`, `CORRECT_SCORE`, `PLAYER_SCORE_FIRST_GOAL` |
+| `outcome`  | `1` (home), `x` (draw), `2` (away), `1x`, `yes`, `no`, `1-2` (correct score) |
+
+**Pre-mount queuing:**
+
+Calls to `betslipApi.setSelection` made before the `<Betslip />` component has mounted are queued and automatically replayed once the widget finishes initializing. There is no need to delay external code to wait for the widget.
+
+```tsx
+// Safe to call before <Betslip /> is rendered
+betslipApi.setSelection("fb:m:451678:FT_1X2:1");
+
+// Later, when <Betslip /> mounts, it will receive the queued selection
+ReactDOM.render(<Betslip sdk={sdk} language="en" />, root);
+```
+
+#### Predictor Integration
+
+The `Predictor` component has first-class Betslip support via its `betslip` prop. When configured, the Predictor renders the `Betslip` widget internally — no separate `<Betslip />` component is needed. See the [Predictor — Betslip Integration](#betslip-integration) section for full details.
+
+```tsx
+import { Predictor } from "fansunited-frontend-components";
+
+<Predictor
+  entityId="predictor-123"
+  sdk={sdk}
+  language="en"
+  betslip={{
+    trigger: "predictions-only", // or "odds-only"
+    position: "side-right",
+    currency: "£",
+    stakePresets: [5, 10, 25, 50],
+    ctaUrlTemplate: "https://your-bookmaker.com/bet?ids={selectionIds}&stake={stake}",
+  }}
+/>
+```
+
+**Trigger modes:**
+
+| Mode                  | When selections are sent to Betslip                                               |
+| --------------------- | --------------------------------------------------------------------------------- |
+| `"predictions-only"`  | Each time the user changes a score prediction (before submitting)                 |
+| `"odds-only"`         | When the user clicks an odds button on the post-submit odds view                  |
+
+#### CTA URL Template
+
+The `ctaUrlTemplate` prop defines the bookmaker deep-link. Placeholders are replaced at click time with live values from the current betslip state.
+
+```tsx
+ctaUrlTemplate="https://betano.bg/mybet/?selection_ids={selectionIds}&stake={stake}&return_url={currentUrl}"
+```
+
+**Available placeholders:**
+
+| Placeholder       | Value                                                                     |
+| ----------------- | ------------------------------------------------------------------------- |
+| `{selectionIds}`  | Comma-separated SDK `selection.id` values (up to the first 10)            |
+| `{stake}`         | Current stake input value (float)                                         |
+| `{currentUrl}`    | `window.location.href`, URI-encoded                                       |
+| `{eventId}`       | `eventId` of the first selection                                          |
+| `{oddsDecimal}`   | Decimal odds of the first selection                                       |
+| `{market}`        | Market code of the first selection                                        |
+| `{outcome}`       | Outcome label of the first selection                                      |
+
+#### Theming
+
+The Betslip derives its primary accent color from a three-level priority chain:
+
+1. **Custom primary** — `themeOptions.colorSchemes[mode].palette.primary.plainColor`
+2. **Bookmaker color** — `bookmaker.branding.backgroundColor` (or `bookmaker.assets[0].backgroundColor` as fallback) extracted live from the SDK odds response
+3. **Default theme primary**
+
+This means you get bookmaker brand colors for free when odds are available, and can override them at any time via `themeOptions`.
+
+```tsx
+import { CustomThemeOptions } from "fansunited-frontend-core";
+
+// Override primary accent — disables the bookmaker color fallback
+const themeOptions: CustomThemeOptions = {
+  mode: "dark",
+  colorSchemes: {
+    dark: {
+      palette: {
+        primary: {
+          plainColor: "#FF5722",       // your brand color
+          primaryContainer: "#FF7043",
+          onPrimary: "#FFFFFF",
+        },
+        success: {
+          plainColor: "#4CAF50",
+          softBg: "#042F04",
+        },
+        danger: {
+          plainColor: "#F44336",
+          softBg: "#430A0A",
+        },
+      },
+      surface: "#212121",
+      onSurface: "#121212",
+      surfaceVariant: "#333333",
+      textPrimary: "#FAFAFA",
+      textSecondary: "#BDBDBD",
+      outlineEnabledBorder: "#555555",
+    },
+  },
+  customFontFamily: {
+    dark: {
+      primary: "Inter, sans-serif",
+      secondary: "Roboto, sans-serif",
+    },
+  },
+};
+
+<Betslip sdk={sdk} language="en" themeOptions={themeOptions} />;
+```
+
+> **Note:** When neither a custom primary nor bookmaker odds are present, the widget falls back to the default theme primary (`#1A77D2`).
+
+#### Labels
+
+Override any piece of UI text without switching languages:
+
+```tsx
+import { BetslipLabels } from "fansunited-frontend-core";
+
+const labels: BetslipLabels = {
+  title: "My Betslip",
+  placeBetLabel: "Place Bet",
+  emptyTitle: "Your betslip is empty",
+  emptyDescription: "Add selections to get started",
+  continueLabel: "Continue",
+  disclaimer: "18+ | Gamble responsibly",
+  combinedOddsLabel: "Combined Odds",
+  stakeLabel: "Stake",
+  totalStakeLabel: "Total Stake",
+  potentialWinLabel: "Potential Win",
+  oddsUnavailableLabel: "Odds N/A",
+  suspendedLabel: "Suspended",
+
+  // Override individual outcome labels
+  outcomeLabels: {
+    yes: "Over",
+    no: "Under",
+    draw: "Draw",
+    or: "/",
+    nobody: "No Scorer",
+    noGoal: "No Goal",
+  },
+
+  // Override market display names
+  marketLabels: {
+    FT_1X2: "Full Time",
+    DOUBLE_CHANCE: "Double Chance",
+    OVER_GOALS_2_5: "Over/Under 2.5 Goals",
+  },
+};
+
+<Betslip sdk={sdk} language="en" labels={labels} />;
+```
+
+#### Conflict Detection
+
+The betslip automatically detects selections that are mutually exclusive — i.e., two selections with the same `eventId` and market. When conflicts are detected:
+
+- A warning banner appears at the top of the expanded selection list
+- Conflicting selection cards are highlighted with danger styling
+- The CTA button is disabled until the conflict is resolved
+
+Conflicts resolve automatically when the user removes one of the conflicting selections. No extra configuration is required.
+
+#### Odds Behavior
+
+- **Polling**: Odds are fetched from `sdk.odds.getByMatchIds()` on mount and refreshed every `oddsPollingInterval` ms (default 30 s)
+- **Movement indicator**: A green ▲ or red ▼ is shown when the bookmaker response includes a `movement` field (`"UP"` or `"DOWN"`) on the matched selection. No indicator is shown when `movement` is absent
+- **Unavailable**: When no odds are returned for a selection, the card shows `oddsUnavailableLabel` and the CTA is disabled
+- **Suspended**: Selections with status `"suspended"` are highlighted and block the CTA
+- **Settled states**: Cards display ✓ (won), ✗ (lost), or ≈ (void) once a selection is settled
+
+**Over/Under markets:** The `outcome` code in the selection ID uses `"yes"` for Over and `"no"` for Under (not `"over"`/`"under"`). The widget handles the conversion and label display internally.
+
+**Correct Score market:** Outcomes use hyphen notation, e.g. `"1-2"`. The widget parses both `-` and `:` as separators.
+
+#### TypeScript Support
+
+Import types from `fansunited-frontend-core`:
+
+```tsx
+import {
+  BetslipProps,
+  BetslipLabels,
+  BetslipPosition,
+  BetslipSelectionInput,
+  BetslipOutcomeLabels,
+  SelectionStatus,
+  CustomThemeOptions,
+  LanguageType,
+  betslipApi,
+} from "fansunited-frontend-core";
+```
+
+#### Examples
+
+##### Basic Betslip
+
+```tsx
+import { Betslip } from "fansunited-frontend-components";
+import { FansUnitedSDK } from "fansunited-sdk-esm";
+
+const sdk = FansUnitedSDK({ /* config */ });
+
+<Betslip
+  sdk={sdk}
+  language="en"
+  ctaUrlTemplate="https://your-bookmaker.com/bet?selections={selectionIds}"
+/>;
+```
+
+##### Side Panel with Custom Branding
+
+```tsx
+import { Betslip } from "fansunited-frontend-components";
+
+<Betslip
+  sdk={sdk}
+  language="en"
+  position="side-right"
+  maxSelections={10}
+  stakePresets={[5, 10, 25, 50]}
+  currency="£"
+  brandingLogoUrl="https://your-cdn.com/logo.png"
+  ctaUrlTemplate="https://your-bookmaker.com/bet?ids={selectionIds}&stake={stake}&ref={currentUrl}"
+  labels={{
+    title: "Your Selections",
+    placeBetLabel: "Bet Now",
+    disclaimer: "18+ | Please gamble responsibly | BeGambleAware.org",
+  }}
+  themeOptions={{
+    mode: "dark",
+    colorSchemes: {
+      dark: {
+        palette: {
+          primary: {
+            plainColor: "#FF5722",
+            primaryContainer: "#FF7043",
+            onPrimary: "#FFFFFF",
+          },
+        },
+        surface: "#1A1A1A",
+        textPrimary: "#FAFAFA",
+      },
+    },
+  }}
+/>
+```
+
+##### Programmatic Selection Management
+
+```tsx
+import { betslipApi } from "fansunited-frontend-core";
+
+// Add selections (safe to call before the widget mounts)
+betslipApi.setSelection("fb:m:451678:FT_1X2:1");
+betslipApi.setSelection("fb:m:451679:DOUBLE_CHANCE:1x");
+
+// Replace an outcome for the same event+market
+betslipApi.setSelection("fb:m:451678:FT_1X2:2"); // replaces the home-win
+
+// Remove a specific selection
+betslipApi.removeSelection("fb:m:451679:DOUBLE_CHANCE:1x");
+```
+
+##### Predictor + Betslip Integration
+
+The `Predictor` renders the `Betslip` widget internally when `betslip` is provided — no separate `<Betslip />` is needed.
+
+```tsx
+import { Predictor } from "fansunited-frontend-components";
+
+<Predictor
+  entityId="predictor-123"
+  sdk={sdk}
+  language="en"
+  betslip={{
+    trigger: "predictions-only",
+    position: "side-right",
+    currency: "€",
+    stakePresets: [5, 10, 20, 50],
+    ctaUrlTemplate:
+      "https://your-bookmaker.com/bet?ids={selectionIds}&stake={stake}",
+    labels: {
+      disclaimer: "18+ | Gamble responsibly",
+    },
+  }}
+  themeOptions={{ mode: "light" }}
+/>
+```
+
 ---
 
 ## Available Components
@@ -3345,6 +3866,7 @@ This package exports the following components:
 - **`Discussion`** - Threaded comments with reactions, replies, reporting, and authentication support
 - **`Leaderboard`** - Ranked standings for Classic Quiz, Match Quiz, Top X, and Template entities with multi-entity support
 - **`Predictor`** - Multi-tab football score predictor with leaderboard, private leagues, rules, and prizes
+- **`Betslip`** - Floating betslip with bookmaker deep-link integration, six viewport positions, and command bus API
 
 ## Related Packages