@pcampus/reward-widget

Public UI components and theme types for Pcampus Reward Widget integrations.

Relationship to the Reward Widget service

Pcampus-reward-widget is the private runtime and source of truth for campaign configuration, eligibility, server draw, inventory, claims, webhooks, and the hosted Player/Embed experience.

Pcampus-reward-widget-library is the public UI layer: reusable components, theme tokens, and TypeScript types that consumer apps can render and style. It does not contain API clients, draw or eligibility logic, campaign state, secrets, claims, webhooks, or coupon data.

This package is UI-only. It never contains draw/eligibility clients, campaign secrets, coupon codes, or authoritative server logic.

Status

Public UI catalog for spin, scratch, pick-card, mystery-box, and quiz. Presentation matches the Merchant Portal preview package. This package is still UI-only: no draw, claims, or campaign APIs.

Public support matrix

The UI catalog targets spin, scratch, pick-card, mystery-box, and quiz. This package exports presentation primitives, theme configuration, and public types only. Reward service APIs, server-side authority, claims, webhooks, secrets, and coupon data remain outside the package.

Installation & Usage

npm install @pcampus/reward-widget

SSR / String Markup

import { renderRewardWidgetMarkup } from '@pcampus/reward-widget';

const html = renderRewardWidgetMarkup({
  widgetType: 'spin',
  state: 'eligible',
  title: 'Daily Wheel of Fortune',
  message: 'Spin now to win exclusive points!',
  actionLabel: 'Spin Now',
  theme: { brandPrimaryColor: '#2952a3' },
});

Interactive widgets (player chrome)

import { mountInteractiveWidget } from '@pcampus/reward-widget';

const root = document.getElementById('widget-root');
mountInteractiveWidget(root, {
  widgetType: 'pick-card',
  rewards: [
    { name: 'ส่วนลด 100 บาท', weight: 40 },
    { name: 'Lucky Bonus', weight: 30 },
    { name: '100 Points', weight: 20 },
  ],
  theme: { brandPrimaryColor: '#4b7fd4' },
});

SSR equivalent: renderInteractiveWidgetMarkup({ widgetType, rewards, theme }). Per-type helpers: renderSpinWheelMarkup / mountSpinWheel, and the same pattern for scratch, pick-card, mystery-box, and quiz.

Open examples/interactive-catalog.html via a local static server to view all five types.

Client DOM Mount (chrome shell)

import { mountRewardWidget } from '@pcampus/reward-widget';

const container = document.getElementById('widget-root');
mountRewardWidget(container, {
  widgetType: 'mystery-box',
  state: 'eligible',
  title: 'Special Mystery Box',
  onAction: () => {
    console.log('Action clicked');
  },
});

Theme Tokens & Customization

Consumers can customize widget styling using typed tokens and CSS custom properties:

import { createRewardWidgetTheme, rewardWidgetThemeCss } from '@pcampus/reward-widget';

// Create custom theme with fallbacks to defaults
const theme = createRewardWidgetTheme({
  primary: '#2952a3',
  background: '#0f172a',
  radius: '0.5rem',
});

// Generate scoped CSS variables
const css = rewardWidgetThemeCss({ primary: '#2952a3' });

Supported Tokens

| Token | Default | Purpose | |---|---|---| | primary | #2952a3 | Primary brand color | | primaryHover | #1e3a8a | Interactive hover state | | surface | #ffffff | Component card/surface | | background | #0f172a | Container background | | border | #cbd5e1 | Border and outline | | focus | #f59e0b | Focus ring indicator | | disabled | #64748b | Disabled control state | | warning | #f59e0b | Warning message/badge | | blocked | #9f1239 | Ineligible / limit reached | | success | #047857 | Reward won / success | | radius | 0.75rem | Border radius | | spacing | 1rem | Component padding | | motion | 160ms | Transition duration |

Build

npm install
npm run build
npm test

The package build emits JavaScript and TypeScript declarations under dist/.

Public release policy

Releases use the public npm registry only after human review. Before publishing, run npm test, npm pack --dry-run, and npm audit --omit=dev. The published artifact is limited to dist/, this README, and the MIT license.