@enigma-lake/mines-play-controller-sdk 2.1.3 → 2.1.5

package/README.md

@@ -1,14 +1,23 @@
 # MinesPlayController
 
 The `MinesPlayController` component is a key part of the gameplay
-interface, allowing users to initiate a play or cash out based on their
-current game state. It supports manual play, autoplay, dynamic currency
-handling, play amount adjustments, and classic-game--specific
-configuration.
+interface.\
+It allows users to initiate a play or cash out based on their current
+game state.
+
+It supports:
+
+-   Manual play
+-   Autoplay
+-   Dynamic currency handling
+-   Play amount adjustments
+-   Classic-game configuration
+-   External button styling configuration
+-   External switcher styling configuration
 
 ------------------------------------------------------------------------
 
-## Component Overview
+# Component Overview
 
 The `MinesPlayController` allows the user to:
 
@@ -19,18 +28,20 @@ The `MinesPlayController` allows the user to:
 -   Toggle between manual play and autoplay
 -   Configure mines count (when enabled)
 -   Apply classic game layout and styling overrides
+-   Fully customize controller button styles
+-   Fully customize autoplay switch styles
 
 ------------------------------------------------------------------------
 
-## Setup
+# Setup
 
-### 1. Install the package using npm
+## 1. Install the package
 
 ``` bash
 npm install @enigma-lake/mines-play-controller-sdk
 ```
 
-### 2. Import the component and styles
+## 2. Import component and styles
 
 ``` tsx
 import {
@@ -44,208 +55,239 @@ import "@enigma-lake/mines-play-controller-sdk/dist/style.css";
 
 ------------------------------------------------------------------------
 
-## Context & Provider
-
-### `AutoManualPlayProvider`
+# Context & Provider
 
-The `AutoManualPlayProvider` wraps the `MinesPlayController`, managing
-both manual play and autoplay. It uses React Context to provide game
-state and actions throughout the component tree.
+## AutoManualPlayProvider
 
-**Features:**
+Wraps the controller and manages:
 
--   Manages game mode (MANUAL / AUTOPLAY)
--   Controls autoplay flow, rounds, and termination
--   Exposes state and callbacks to child components
+-   MANUAL / AUTOPLAY modes
+-   Autoplay lifecycle
+-   Internal state management
 
 ------------------------------------------------------------------------
 
-## Props
+# Props
 
-### 1. StylingProps
+## StylingProps
 
-Controls visual appearance of the controller.
+Controls controller layout and styling.
 
--   **`panel`**
-    -   `bgColorHex`: Hex color for the controller background
-    -   `bottom`: Bottom offset relative to the viewport
--   **`classicGame` (optional)**\
-    Styling overrides applied when `isClassicGame` is enabled.
-    -   `dropdown.bgColorHex`: Background color for dropdown menus
-    -   `forceLeftStyle`: Forces left-aligned layout style
-
-------------------------------------------------------------------------
+### panel
 
-### 2. CurrencyProps
+-   `bgColorHex`: Background color
+-   `bottom`: Bottom offset
+-   `opacity`: Optional opacity
 
-Handles currency-related configuration.
+### classicGame (optional)
 
--   **`currencyOptions`**
-    -   `currentCurrency`: Currently selected currency
-    -   `currencies`: List of available currencies
-    -   `winText`: Display text for winnings
+-   `dropdown.bgColorHex`
+-   `forceLeftStyle`
 
 ------------------------------------------------------------------------
 
-### 3. ActionsProps
+## CurrencyProps
 
-Defines callbacks for user actions.
-
--   **`onPlay`**: Triggered when a manual play starts
--   **`onAutoPlay`**: Triggered when autoplay starts\
-    `(selection, next, stop, state) => void`
--   **`onAutoPlayStop` (optional)**: Triggered when autoplay is stopped
-    manually
--   **`onCashout`**: Triggered when the user cashes out
+``` ts
+currencyOptions: {
+  current: CurrencyMeta;
+  available: CurrencyMeta[];
+}
+```
 
 ------------------------------------------------------------------------
 
-### 4. PlaySettingsProps
+## ActionsProps
 
-Controls game state, limits, and UI behavior.
+-   `onPlay`
+-   `onAutoPlay(selection, next, stop, state)`
+-   `onAutoPlayStop`
+-   `onCashout`
 
--   **`isPlaying`**: Whether a round is currently in progress
+------------------------------------------------------------------------
 
--   **`canCashout`**: Whether the user can cash out
+## PlaySettingsProps
 
--   **`disabledController`**: Disables all controller interactions
+-   `isPlaying`
+-   `canCashout`
+-   `disabledController`
+-   `displayController`
+-   `classicGame`
+-   `showAutoPlayToast`
+-   `playHook`
+-   `autoPlayDelay`
+-   `totalBalance`
 
--   **`displayController`**: Toggles controller visibility
+------------------------------------------------------------------------
 
--   **`classicGame` (optional)**\
-    Mines-related settings for classic or configurable modes.
+# External Button Styling
+
+You can fully control controller buttons externally.
+
+## playControllerButtons
+
+``` ts
+playControllerButtons: {
+  textStyle: {
+    color: "#041926",
+    fontSize: "16px",
+    fontWeight: 800,
+    lineHeight: "125%",
+    letterSpacing: "0.8px",
+    textTransform: "none",
+    disableOpacity: 0.4
+  },
+
+  buttons: {
+    play: {
+      label: "Place Bet",
+      labelDisabled: "Pick a tile",
+      backgroundColor: "#EAFF00",
+      pressedBackgroundColor: "#C7D807",
+      disabledOpacity: 0.4,
+    },
 
-    -   `disabledMenu`: Disables the mines selector menu
-    -   `currentMines`: Currently selected number of mines
-    -   `onMinesChange(mines)`: Callback when mines count changes
+    startAutoplay: {
+      label: "Start Autoplay",
+      backgroundColor: "#EAFF00",
+      pressedBackgroundColor: "#C7D807",
+      disabledOpacity: 0.4,
+    },
 
--   **`showAutoPlayToast`**: Displays autoplay-related toast messages
+    stopAutoplay: {
+      label: "Stop Autoplay",
+      backgroundColor: "#F5A6C7",
+      pressedBackgroundColor: "#BA6E8E",
+      disabledOpacity: 0.4,
+    },
 
--   **`playHook`**
+    cashout: {
+      label: "Cashout",
+      backgroundColor: "#4ADEC6",
+      pressedBackgroundColor: "#269D89",
+      disabledOpacity: 0.4,
+    },
 
-    -   `playLimits`: Min/max limits for play amount
-    -   `playAmount`: Current bet amount
-    -   `setPlayAmount(value)`
+    selectPlayAmount: {
+      label: "Select Bet Amount",
+      backgroundColor: "#4ADEC6",
+      pressedBackgroundColor: "#269D89",
+      disabledOpacity: 0.4,
+    },
+  },
+}
+```
 
--   **`autoPlayDelay` (optional)**: Delay (ms) before autoplay starts
+### Button Styling Behavior
 
--   **`totalBalance`**: Available balance for the selected currency
+-   `backgroundColor` overrides default gradient styles
+-   `pressedBackgroundColor` applies on mouse down / key press
+-   `disableOpacity` affects **text color only**
+-   `labelDisabled` applies only to `play` button when disabled AND
+    playing
+-   `textTransform` prevents automatic uppercase transformation
+-   Currency-based styles are ignored when custom config is provided
 
 ------------------------------------------------------------------------
 
-### 5. Widgets
+# External Switcher Styling
 
-Custom UI extensions.
+You can configure the autoplay switch component.
 
--   **`leftWidgets`**: Widgets rendered on the left side
--   **`centerWidgets`**: Widgets rendered in the center
--   **`rightWidgets`**: Widgets rendered on the right side
+## playControllerSwitcher
 
-------------------------------------------------------------------------
+``` ts
+playControllerSwitcher: {
+  checked: {
+    thumb: "#fff",
+    slider: "#10be68",
+  },
+  unchecked: {
+    thumb: "#30424C",
+    slider: "#132A36",
+  }
+}
+```
+
+### Switch Styling Behavior
 
-### 6. Mode Flag
+When `playControllerSwitcher` is provided:
 
--   **`isClassicGame` (optional)**\
-    Enables classic game mode and activates related styling and play
-    settings.
+-   Slider background uses `check.slider` when enabled
+-   Slider background uses `unchecked.slider` when disabled
+-   Thumb uses `check.thumb` when enabled
+-   Thumb uses `unchecked.thumb` when disabled
+-   Currency-based styling is ignored
+-   Default SCSS remains untouched if config is absent
 
 ------------------------------------------------------------------------
 
-## Example Usage
+# Full Example Configuration
 
 ``` tsx
-import "@enigma-lake/mines-play-controller-sdk/dist/style.css";
-import {
-  AutoManualPlayProvider,
-  AUTO_PLAY_STATE,
-} from "@enigma-lake/mines-play-controller-sdk";
-import { Currency } from "@enigma-lake/zoot-platform-sdk";
-
-const GameExample = () => {
-  const config = {
-    currencyOptions: {
-      currentCurrency: Currency.SWEEPS,
-      currencies: [Currency.SWEEPS, Currency.GOLD],
-      winText: "0.00 SC",
-    },
-
-    onPlay: () => console.log("Play clicked"),
-
-    onAutoPlay: (selection, next, stop, state) => {
-      console.log("Autoplay state:", state);
-      next();
-    },
+const config = {
+  currencyOptions: { ... },
 
-    onAutoPlayStop: () => console.log("Autoplay stopped"),
+  onPlay: () => {},
+  onAutoPlay: () => {},
+  onCashout: () => {},
 
-    onCashout: () => console.log("Cashout"),
+  playOptions: { ... },
 
-    playOptions: {
-      displayController: true,
-      isPlaying: false,
-      canCashout: false,
-      disabledController: false,
+  panel: {
+    bottom: "15px",
+    bgColorHex: "#081E64",
+  },
 
-      classicGame: {
-        disabledMenu: false,
-        currentMines: 3,
-        onMinesChange: (mines) => console.log("Mines:", mines),
+  playControllerButtons: {
+    textStyle: {
+      color: "#041926",
+      textTransform: "none",
+      disableOpacity: 0.4,
+    },
+    buttons: {
+      play: {
+        label: "Place Bet",
+        labelDisabled: "Pick a tile",
+        backgroundColor: "#EAFF00",
+        pressedBackgroundColor: "#C7D807",
       },
-
-      totalBalance: 1000,
-
-      showAutoPlayToast: ({ type, message }) =>
-        console.log(`${type}: ${message}`),
-
-      playHook: () => ({
-        playLimits: { min: 1, max: 100 },
-        playAmount: 10,
-        setPlayAmount: (value) => console.log("Amount:", value),
-      }),
     },
+  },
 
-    panel: {
-      bottom: "15px",
-      bgColorHex: "#081E64",
+  playControllerSwitcher: {
+    checked: {
+      thumb: "#fff",
+      slider: "#10be68",
     },
-
-    classicGame: {
-      dropdown: {
-        bgColorHex: "#0B2A8F",
-      },
-      forceLeftStyle: true,
+    unchecked: {
+      thumb: "#30424C",
+      slider: "#132A36",
     },
-
-    leftWidgets: [],
-    centerWidgets: [],
-    rightWidgets: [],
-
-    isClassicGame: true,
-  };
-
-  return (
-    <AutoManualPlayProvider config={config}>
-      {() => null}
-    </AutoManualPlayProvider>
-  );
+  },
 };
 ```
 
 ------------------------------------------------------------------------
 
-## Key Features
+# Key Features
 
-1.  Dynamic currency support
-2.  Manual and autoplay modes
-3.  Play amount validation and limits
-4.  Classic-game styling and behavior overrides
-5.  Extensible widget system
+1.  Manual & Autoplay modes\
+2.  External button styling support\
+3.  External switcher styling support\
+4.  Currency fallback behavior\
+5.  Text transformation control\
+6.  Text-only disable opacity\
+7.  Label override when disabled\
+8.  Fully backward compatible styling system
 
 ------------------------------------------------------------------------
 
-## Development Notes
+# Development Notes
 
--   Play amounts are validated against limits and balance
--   Autoplay lifecycle is fully controlled via callbacks
--   Classic game configuration is opt-in via `isClassicGame`
--   Component is fully responsive and layout-aware
+-   Styling system is fully optional
+-   Existing integrations will not break
+-   Default currency behavior applies unless overridden
+-   Text opacity is calculated dynamically using RGBA conversion
+-   Pressed states are handled via inline override
+-   Switcher styling activates only when configuration is provided

package/dist/components/hooks/usePlayControllerButtons.d.ts

@@ -0,0 +1,28 @@
+import type React from "react";
+import { PlayControllerButtonsConfig, PlayControllerButtonId } from "../../types/playController";
+type CSSVarsStyle = React.CSSProperties & {
+    [key: `--${string}`]: string | number;
+};
+type ResolveLabelOpts = {
+    disabled?: boolean;
+    isPlaying?: boolean;
+};
+type ResolveStyleOpts = {
+    pressed: boolean;
+    disabled: boolean;
+};
+export declare function usePlayControllerButtons(params: {
+    theme?: PlayControllerButtonsConfig;
+}): {
+    pressedId: PlayControllerButtonId | null;
+    setPressedId: React.Dispatch<React.SetStateAction<PlayControllerButtonId | null>>;
+    setPressed: (id: PlayControllerButtonId, value: boolean) => void;
+    getPressHandlers: (id: PlayControllerButtonId) => {
+        onMouseDown: () => void;
+        onMouseUp: () => void;
+        onMouseLeave: () => void;
+    };
+    resolveLabel: (id: PlayControllerButtonId, fallback: string, opts?: ResolveLabelOpts) => string;
+    resolveStyle: (id: PlayControllerButtonId, opts: ResolveStyleOpts) => CSSVarsStyle | undefined;
+};
+export {};

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ReactNode, ReactElement } from 'react';
+import React$1, { ReactNode, ReactElement } from 'react';
 import { CurrencyProps, PlayLimitsV2 } from '@enigma-lake/zoot-platform-sdk';
 
 declare enum GAME_MODE {
@@ -29,6 +29,7 @@ type StylingProps = {
     panel: {
         bottom?: string;
         bgColorHex: string;
+        opacity?: number;
     };
     classicGame?: {
         dropdown: {
@@ -65,6 +66,48 @@ type PlaySettingsProps = {
     autoPlayDelay?: number;
     totalBalance: number;
 };
+type TextTransformOption = "none" | "uppercase" | "lowercase" | "capitalize";
+type PlayControllerTextStyle = Omit<React$1.CSSProperties, "textTransform"> & {
+    textTransform?: React$1.CSSProperties["textTransform"];
+    disableOpacity?: number;
+};
+type PlayControllerButtonId = "play" | "startAutoplay" | "stopAutoplay" | "cashout" | "selectPlayAmount";
+type PlayControllerButtonVariant = {
+    backgroundColor: string;
+    pressedBackgroundColor?: string;
+    textTransform?: TextTransformOption;
+    style?: React$1.CSSProperties;
+    pressedStyle?: React$1.CSSProperties;
+    disabledStyle?: React$1.CSSProperties;
+};
+type PlayControllerButtonConfig<VariantKey extends string> = {
+    label: string;
+    /**
+     * Only intended for `play` button:
+     * shown when button is disabled AND game is playing.
+     */
+    labelDisabled?: string;
+    variant?: VariantKey;
+    backgroundColor?: string;
+    pressedBackgroundColor?: string;
+    textTransform?: TextTransformOption;
+    style?: React$1.CSSProperties;
+    pressedStyle?: React$1.CSSProperties;
+    disabledStyle?: React$1.CSSProperties;
+};
+type PlayControllerSwitcherState = {
+    thumb?: string;
+    slider?: string;
+};
+type PlayControllerSwitcherConfig = {
+    checked?: PlayControllerSwitcherState;
+    unchecked?: PlayControllerSwitcherState;
+};
+type PlayControllerButtonsConfig<VariantKey extends string = "primary" | "danger" | "success"> = {
+    textStyle?: PlayControllerTextStyle;
+    variants?: Record<VariantKey, PlayControllerButtonVariant>;
+    buttons: Partial<Record<PlayControllerButtonId, PlayControllerButtonConfig<VariantKey>>>;
+};
 type PlayControllerProps = StylingProps & ActionsProps & {
     currencyOptions: CurrencyProps;
     playOptions: PlaySettingsProps;
@@ -72,6 +115,8 @@ type PlayControllerProps = StylingProps & ActionsProps & {
     rightWidgets: Widget[];
     centerWidgets: Widget[];
     isClassicGame?: boolean;
+    playControllerButtons?: PlayControllerButtonsConfig;
+    playControllerSwitcher?: PlayControllerSwitcherConfig;
 };
 
 interface AutoManualPlayStateContextType {