summit-registration-lite 7.0.3 → 7.0.4

package/.claude/rules/summit-registration-lite-component-props.md

@@ -0,0 +1,95 @@
+# Component Prop Conventions
+
+## When to Apply
+
+Defining props for new components or understanding prop flow from widget to child components.
+
+## Pattern
+
+**Widget Root (RegistrationLiteWidget):**
+
+Parent app passes all props to widget, which wraps `<RegistrationLite>` in Redux Provider.
+
+**Main Component (RegistrationLite):**
+
+```javascript
+const RegistrationLite = ({
+    // Lifecycle callbacks (parent app control)
+    authUser,              // (provider) => void - handle SSO login
+    goToExtraQuestions,    // (attendeeId) => void - redirect to extra questions
+    goToEvent,             // () => void - redirect to event page
+    goToMyOrders,          // () => void - redirect to my orders
+    onPurchaseComplete,    // (order) => void - handle successful purchase
+    closeWidget,           // () => void - close/minimize widget
+
+    // Auth callbacks
+    getPasswordlessCode,   // (email) => void - request OTP code
+    loginWithCode,         // (email, code) => void - verify OTP
+    authErrorCallback,     // (error) => void - handle auth errors
+
+    // Error handling
+    onError,               // ({type, msg, exception}) => void
+    handleCompanyError,    // (error) => void - company dropdown errors
+
+    // Data
+    summitData,            // { id, name, time_zone, registration_disclaimer, ... }
+    profileData,           // { email, first_name, last_name, company, ... }
+
+    // Config
+    apiBaseUrl,            // Base URL for API calls
+    supportEmail,          // Support email for help text
+    allowPromoCodes,       // boolean - show/hide promo code field (default: true)
+    showCompanyInput,      // boolean - show/hide company field (default: true)
+    allowsNativeAuth,      // boolean - show email/password login
+    allowsOtpAuth,         // boolean - show passwordless OTP login
+    loginOptions,          // [{ button_color, provider_label, provider_param }]
+
+    // UI customization
+    loading,               // boolean - external loading state
+    showMultipleTicketTexts,  // boolean - show multi-ticket messaging
+    hidePostalCode,        // boolean - hide postal code in payment (default: false)
+    idpLogoDark,           // string - custom logo src (dark theme)
+    idpLogoLight,          // string - custom logo src (light theme)
+
+    // Messages (optional overrides)
+    noAllowedTicketsMessage,
+    ticketTaxesErrorMessage,
+
+    // Provider options
+    providerOptions,       // { stripe: {...}, lawpay: {...} }
+    successfulPaymentReturnUrl,  // Stripe return URL after payment
+
+    // Redux state (from connect)
+    step, reservation, ticketTypes, taxTypes, ...
+
+    // Redux actions (from connect)
+    loadSession, changeStep, reserveTicket, payTicketWithProvider, ...
+}) => { /* ... */ }
+```
+
+## Key Points
+
+- **Callback pattern:** Parent app controls navigation (`goToExtraQuestions`, `goToEvent`, etc.) - widget doesn't redirect directly
+- **Error handling delegation:** Widget calls `onError` / `authErrorCallback` / `handleCompanyError`, parent decides what to do
+- **Data vs. Config:** `summitData` is event info, `profileData` is user info, others are config/behavior flags
+- **Optional overrides:** Most text/messages have defaults but can be overridden via props
+- **Redux separation:** Connected props (`step`, `reservation`) vs. passed props (callbacks, config)
+
+## Prop Flow Example
+
+```
+Parent App
+  └─> RegistrationLiteWidget (wraps Provider)
+       └─> RegistrationLite (receives props + Redux state)
+            ├─> LoginComponent (loginOptions, allowsNativeAuth, allowsOtpAuth)
+            ├─> TicketTypeComponent (ticketTypes, summitData)
+            ├─> PersonalInfoComponent (profileData, showCompanyInput)
+            └─> PaymentComponent (reservation, providerOptions)
+```
+
+## Common Mistakes
+
+- Hardcoding navigation instead of calling prop callbacks (breaks widget embedding)
+- Not providing `apiBaseUrl` (causes API calls to fail)
+- Forgetting `onError` handler (errors go to console only, user sees nothing)
+- Passing incomplete `summitData` (missing `time_zone` breaks clock, missing `id` breaks API calls)

package/.claude/rules/summit-registration-lite-i18n.md

@@ -0,0 +1,62 @@
+# i18n / Translation Pattern
+
+## When to Apply
+
+Adding user-facing text to components or modifying existing strings.
+
+## Pattern
+
+**Library:** `i18n-react` — imported as `T`.
+
+**Setup (in `registration-lite.js`):**
+
+```javascript
+import T from 'i18n-react';
+
+// Loaded once at component init, falls back to English
+try {
+    T.setTexts(require(`../i18n/${language}.json`));
+} catch {
+    T.setTexts(require(`../i18n/en.json`));
+}
+```
+
+**Usage in components:**
+
+```javascript
+import T from 'i18n-react';
+
+// Simple key
+T.translate("bar_button.next")  // → "Next"
+
+// With interpolation
+T.translate("purchase_complete_step.footer_assistance_text", { supportEmail: "help@example.com" })
+// Template: "For further assistance, please email <a href=\"mailto:{supportEmail}\">{supportEmail}</a>"
+```
+
+## Translation File Structure
+
+`src/i18n/en.json` — flat namespaced by UI section:
+
+```json
+{
+  "purchase_complete_step": { "title": "...", "initial_order_complete_button": "..." },
+  "ticket_type": { "ticket_quantity_tooltip": "..." },
+  "promo_code": { "promo_code_tooltip": "..." },
+  "bar_button": { "back": "Back", "next": "Next", "get_ticket": "Get Ticket", "pay_now": "Pay Now", "loading": "Loading" }
+}
+```
+
+## Key Points
+
+- Namespace keys by component/step: `"section_name.key_name"`
+- Interpolation uses `{variableName}` syntax (not `${}` or `%s`)
+- HTML is allowed in translation values (rendered as-is)
+- Only English (`en.json`) exists — add new languages as `{lang}.json` in `src/i18n/`
+- Components using text must `import T from 'i18n-react'`
+
+## Common Mistakes
+
+- Hardcoding user-facing strings instead of using `T.translate()`
+- Adding keys without updating `en.json` (renders the key path as literal text)
+- Using wrong namespace (check `en.json` for existing sections before creating new ones)

package/.claude/rules/summit-registration-lite-payment-providers.md

@@ -0,0 +1,69 @@
+# Payment Provider Integration
+
+## When to Apply
+
+Adding or modifying payment providers (Stripe, LawPay, or new providers).
+
+## Pattern
+
+**Factory Pattern:** `PaymentProviderFactory.build(provider, params)` returns provider instance.
+
+**Provider Structure:**
+
+```javascript
+export class NewProvider {
+    constructor({ reservation, summitId, userProfile, access_token, apiBaseUrl, dispatch }) {
+        // Store params as instance properties
+        this.reservation = reservation;
+        this.summitId = summitId;
+        // ... etc
+    }
+
+    payTicket = ({ /* provider-specific params */, onError = () => {} }) => async (dispatch) => {
+        // 1. Custom error handler for HTTP status codes
+        const errorHandler = (err, res) => (dispatch, state) => {
+            switch (err.status) {
+                case 404: onError({type: ERROR_TYPE_VALIDATION, msg: res.body.message, exception: null}); break;
+                case 500: onError({type: ERROR_TYPE_ERROR, msg: res.body.message, exception: null}); break;
+                default: authErrorHandler(err, res)(dispatch, state); break;
+            }
+        };
+
+        // 2. Free/prepaid orders skip payment gateway
+        if (isFreeOrder(this.reservation) || isPrePaidOrder(this.reservation)) {
+            return putRequest(/* ... checkout endpoint ... */)(params)(this.dispatch);
+        }
+
+        // 3. Payment gateway flow (provider-specific)
+        // Call gateway API, handle result, then checkout
+    }
+}
+```
+
+**Factory Registration:**
+
+```javascript
+// src/utils/payment-providers/payment-provider-factory.js
+import { NEW_PROVIDER } from '../constants';
+import { NewProvider } from './new-provider';
+
+case NEW_PROVIDER: {
+    currentProvider = new NewProvider({...params});
+    break;
+}
+```
+
+## Key Points
+
+- Free/prepaid orders always skip gateway, go straight to `/checkout` endpoint
+- Error types: `ERROR_TYPE_VALIDATION` (404), `ERROR_TYPE_ERROR` (500), `ERROR_TYPE_PAYMENT` (gateway errors)
+- Always dispatch `startWidgetLoading()` before async ops, `stopWidgetLoading()` after
+- Success flow: checkout API → `CLEAR_RESERVATION` → `changeStep(STEP_COMPLETE)`
+- Failure flow: `removeReservedTicket()` → `changeStep(STEP_PERSONAL_INFO)`
+- Checkout endpoint requires billing address fields from `userProfile`
+
+## Common Mistakes
+
+- Forgetting to handle free/prepaid orders (they don't have `payment_gateway_client_token`)
+- Not calling `removeReservedTicket()` on payment failure (leaves stale reservation)
+- Missing `stopWidgetLoading()` in catch blocks (spinner never stops)

package/.claude/rules/summit-registration-lite-project.md

@@ -0,0 +1,80 @@
+# Project: Summit Registration Lite
+
+**Last Updated:** 2026-03-05
+
+## Overview
+
+React widget for summit registration supporting authentication, ticket selection, payment processing, and order completion. Published as NPM package, designed to be embedded in parent applications.
+
+## Technology Stack
+
+- **Language:** JavaScript (ES6+)
+- **Framework:** React 16+ with Redux for state management
+- **Build Tool:** Webpack 5 (dev/prod configs)
+- **Testing:** Jest with @testing-library/react
+- **Package Manager:** Yarn
+- **Key Libraries:**
+  - openstack-uicore-foundation (HTTP utils, actions)
+  - redux-persist (state persistence)
+  - Stripe.js and custom payment providers
+  - Material-UI (@mui/material)
+
+## Directory Structure
+
+```
+summit-registration-lite/
+├── src/
+│   ├── components/          # React components (login, payment, tickets, etc.)
+│   ├── utils/
+│   │   ├── payment-providers/  # Stripe, LawPay provider implementations
+│   │   ├── hooks/              # Custom React hooks
+│   │   └── constants.js        # Step constants, error types
+│   ├── helpers/             # Formatting utilities
+│   ├── actions.js           # Redux action creators (API calls)
+│   ├── reducer.js           # Redux reducer
+│   ├── store.js             # Redux store configuration
+│   └── summit-registration-lite.js  # Main widget export
+├── webpack.common.js
+├── webpack.dev.js
+├── webpack.prod.js
+└── babel.config.js
+```
+
+## Key Files
+
+- **Entry:** `src/summit-registration-lite.js` - Provider wrapper, exports widget and standalone login components
+- **Main Component:** `src/components/registration-lite.js` - Multi-step registration flow
+- **Actions:** `src/actions.js` - API integration (ticket types, reservations, payments)
+- **Payment:** `src/utils/payment-providers/` - Factory pattern for payment provider abstraction
+- **Config:** `webpack.common.js` - Shared webpack configuration
+
+## Development Commands
+
+| Task | Command |
+|------|---------|
+| Install | `yarn` |
+| Dev Server | `yarn serve` |
+| Build Dev | `yarn build-dev` |
+| Build Prod | `yarn build` |
+| Test (watch) | `yarn test` |
+| Clean | `yarn clean` |
+| Publish | `yarn publish-package` |
+
+## Architecture Notes
+
+- **State:** Redux with redux-persist for cross-session state
+- **API Base:** Configurable via props (`apiBaseUrl`), uses openstack-uicore-foundation HTTP utils
+- **Payment Providers:** Factory pattern (`PaymentProviderFactory`) supports Stripe and LawPay
+- **Steps:** Multi-step flow defined in `utils/constants.js` (login, personal info, payment, complete)
+- **Auth:** Supports native auth, OTP (passwordless), and configurable SSO providers via `loginOptions` prop
+- **Integration:** Widget receives callbacks (`authUser`, `goToExtraQuestions`, `onPurchaseComplete`, etc.) for parent app control
+
+## Testing
+
+- Jest configuration in `package.json`
+- Component tests in `__tests__` directories alongside components
+- Mock files for static assets (`src/__mocks__/fileMock.js`)
+
+## Debug Mode
+
+URL hash override for testing time-based logic: `#now=2020-06-03,10:59:50` (summit timezone)

package/.claude/rules/summit-registration-lite-redux-actions.md

@@ -0,0 +1,65 @@
+# Redux API Action Patterns
+
+## When to Apply
+
+Creating new API actions or modifying existing ones in `src/actions.js`.
+
+## Pattern
+
+**Action Structure (openstack-uicore-foundation):**
+
+```javascript
+export const GET_DATA = 'GET_DATA';
+
+export const getData = (summitId) => async (dispatch, getState) => {
+    const { apiBaseUrl } = getState().registration;
+
+    const params = {
+        access_token: await accessTokenSelector()(dispatch, getState),
+        expand: 'relations,nested.relations'
+    };
+
+    return getRequest(
+        null,
+        createAction(GET_DATA),
+        `${apiBaseUrl}/api/v1/summits/${summitId}/resource`,
+        customErrorHandler  // optional
+    )(params)(dispatch);
+};
+```
+
+**Error Handling:**
+
+```javascript
+const customErrorHandler = (err, res) => (dispatch, state) => {
+    if (err.timeout) return err;
+    if (res?.statusCode === 404) return err;  // Handle specific codes
+    if (res?.statusCode === 500) return err;
+    return authErrorHandler(err, res)(dispatch, state);  // Default auth handling
+};
+```
+
+**Reducer Convention:**
+
+```javascript
+case GET_DATA: {
+    return {...state, data: payload.response};
+}
+```
+
+## Key Points
+
+- Actions exported as constants (`export const ACTION_NAME`) AND action creators (`export const actionName`)
+- Use `createAction()` from openstack-uicore-foundation for action creators
+- HTTP methods: `getRequest`, `postRequest`, `putRequest`, `deleteRequest`
+- Always pass `params` object with `access_token` (use `accessTokenSelector()` or widget prop)
+- Use `expand` param for nested relations (dot notation: `tickets.owner.extra_questions`)
+- Custom error handlers must return `authErrorHandler` as default case
+- Thunk signature: `(dispatch, getState) => { ... }`
+
+## Common Mistakes
+
+- Forgetting to await `accessTokenSelector()` (results in Promise instead of token)
+- Not handling 404/500 in custom error handlers (triggers unwanted auth errors)
+- Hardcoding API base URL (always use `state.registration.apiBaseUrl` or prop)
+- Missing `expand` params (causes N+1 queries or missing data in components)

package/.claude/rules/summit-registration-lite-step-flow.md

@@ -0,0 +1,77 @@
+# Multi-Step Registration Flow
+
+## When to Apply
+
+Adding step-specific logic, modifying step transitions, or rendering step-dependent UI.
+
+## Step Constants
+
+Defined in `src/utils/constants.js`:
+
+```javascript
+export const STEP_SELECT_TICKET_TYPE = 0;  // Ticket selection + promo code
+export const STEP_PERSONAL_INFO = 1;       // Attendee details + ticket assignment
+export const STEP_PAYMENT = 2;             // Payment form (Stripe/LawPay)
+export const STEP_COMPLETE = 3;            // Order confirmation
+```
+
+## Step Transitions
+
+**Forward flow (happy path):**
+
+```
+STEP_SELECT_TICKET_TYPE → (Next/validate promo) → STEP_PERSONAL_INFO
+STEP_PERSONAL_INFO → (submit form) → reserveTicket → STEP_PAYMENT
+STEP_PAYMENT → (pay) → payTicketWithProvider → STEP_COMPLETE
+```
+
+**Special cases:**
+
+| Scenario | Transition |
+|----------|------------|
+| Free ticket (cost === 0) | `STEP_PERSONAL_INFO` → skip payment → `STEP_COMPLETE` |
+| Pre-paid ticket | `STEP_PERSONAL_INFO` → skip payment → `STEP_COMPLETE` |
+| Payment failure | `STEP_PAYMENT` → `removeReservedTicket()` → `STEP_PERSONAL_INFO` |
+| No ticket selected + back | Any step → `STEP_SELECT_TICKET_TYPE` |
+
+**Back navigation:**
+
+- From `STEP_PERSONAL_INFO`: `changeStep(step - 1)`
+- From `STEP_PAYMENT`: `removeReservedTicket()` (clears reservation, reducer resets to `STEP_PERSONAL_INFO`)
+
+## Redux Integration
+
+```javascript
+// Action
+export const changeStep = (step) => (dispatch, getState) => {
+    dispatch(createAction(CHANGE_STEP)(step));
+};
+
+// Reducer
+case CHANGE_STEP: {
+    return { ...state, step: payload };
+}
+```
+
+Default state: `step: STEP_SELECT_TICKET_TYPE`
+
+## Rendering Pattern
+
+In `registration-lite.js`, each step renders conditionally:
+
+```javascript
+<StepComponent isActive={step === STEP_SELECT_TICKET_TYPE} ... />
+<StepComponent isActive={step === STEP_PERSONAL_INFO} ... />
+<StepComponent isActive={step === STEP_PAYMENT} ... />
+{step === STEP_COMPLETE && <PurchaseCompleteComponent ... />}
+```
+
+- Steps 0-2 share layout with `ButtonBarComponent`
+- Step 3 (complete) has its own layout, no button bar
+- Button bar renders step-specific buttons based on current `step` value
+
+## Common Mistakes
+
+- Skipping `removeReservedTicket()` when going back from payment (leaves stale reservation)
+- Not checking `reservation` existence before allowing forward navigation
+- Adding steps without updating `ButtonBarComponent` (buttons won't render for new step)

package/.claude/rules/summit-registration-lite-testing.md

@@ -0,0 +1,97 @@
+# Testing Patterns
+
+## When to Apply
+
+Writing new component tests or maintaining existing tests.
+
+## Pattern
+
+**Test Structure:**
+
+```javascript
+import React from 'react';
+import { render, fireEvent, waitFor, screen } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import ComponentName from '..';
+
+const mockCallback = jest.fn();
+
+afterEach(() => {
+    jest.clearAllMocks();  // Reset mocks between tests
+});
+
+it('describes expected behavior', () => {
+    const { getByTestId, getAllByTestId, queryByText } = render(
+        <ComponentName prop1={value1} callback={mockCallback} />
+    );
+
+    // Arrange: find elements
+    const button = getByTestId('button-id');
+
+    // Act: interact
+    fireEvent.click(button);
+
+    // Assert: verify outcome
+    expect(mockCallback).toHaveBeenCalledWith(expectedArg);
+});
+```
+
+**Common Queries:**
+
+```javascript
+// Single element (throws if not found)
+getByTestId('id')          // data-testid attribute
+getByText('text')          // visible text content
+getByRole('button')        // ARIA role
+
+// Multiple elements
+getAllByTestId('id')       // returns array
+
+// Nullable queries (returns null if not found)
+queryByText('text')        // useful for "expect().toBeFalsy()"
+
+// From screen utility
+screen.queryByText('text')
+```
+
+**Async Testing:**
+
+```javascript
+it('handles async behavior', async () => {
+    const { getByTestId } = render(<Component />);
+
+    fireEvent.click(getByTestId('async-button'));
+
+    await waitFor(() => {
+        expect(getByTestId('result')).toBeInTheDocument();
+    });
+});
+```
+
+## Key Points
+
+- Tests live in `__tests__/` directories alongside components
+- Use `data-testid` attributes for reliable element selection
+- Mock callbacks with `jest.fn()`, verify with `.toHaveBeenCalled()` or `.toHaveBeenCalledWith()`
+- Use `queryBy*` for negative assertions (`expect().toBeFalsy()`)
+- Use `getBy*` for positive assertions (throws if element missing)
+- `@testing-library/react` auto-cleanup enabled (no manual unmount needed)
+- CSS/SCSS mocked via `identity-obj-proxy` (className checks work)
+- Static assets (images) mocked via `src/__mocks__/fileMock.js`
+
+## Test Organization
+
+```
+src/components/my-component/
+├── index.js
+├── my-component.module.scss
+└── __tests__/
+    └── my-component.test.js
+```
+
+## Common Mistakes
+
+- Using brittle selectors (text content that changes) instead of `data-testid`
+- Forgetting `@testing-library/jest-dom` import (causes `.toBeInTheDocument()` to fail)
+- Not awaiting async operations (tests pass locally, fail in CI due to timing)
+- Testing implementation details instead of user behavior (prefer user interactions over internal state checks)

package/.claude/rules/summit-registration-lite-utils.md

@@ -0,0 +1,71 @@
+# Utility Functions
+
+## When to Apply
+
+Working with ticket pricing, order status checks, payment provider resolution, or UI color logic.
+
+## Key Functions (`src/utils/utils.js`)
+
+### Order/Ticket Status Checks
+
+```javascript
+isFreeOrder(reservation)        // reservation.amount === 0
+isPrePaidOrder(reservation)     // status === 'Paid' && payment_method === 'Offline'
+isPrePaidTicketType(ticketType) // ticketType.sub_type === 'PrePaid'
+hasDiscountApplied(ticketType)  // has cost_with_applied_discount !== cost
+```
+
+Used in payment providers to decide whether to skip the payment gateway.
+
+### Pricing Display
+
+```javascript
+getTicketCost(ticket, quantity)  // Returns JSX: strikethrough original + discounted price, or just price
+getTicketTaxes(ticket, taxes)    // Returns tax label string: " plus Tax A & Tax B"
+formatCurrency(amount, { currency })  // From helpers/ — locale-aware currency formatting
+```
+
+### Payment Provider Resolution
+
+```javascript
+getCurrentProvider(summit)
+// Iterates summit.payment_profiles for application_type === 'Registration'
+// Returns { publicKey, provider } — uses test vs live key based on test_mode_enabled
+```
+
+### UI Helpers
+
+```javascript
+getContrastingTextColor(bgColor, lightColor, darkColor)  // WCAG luminance contrast
+parseColor(input, element)       // Resolves CSS variables to RGB
+removeWhiteSpaces(value)         // Strip all whitespace
+isEmptyString(val)               // Trim-aware empty check
+```
+
+### Error Tracking
+
+```javascript
+handleSentryException(err)       // Sends to Sentry if window.SENTRY_DSN is set, else console.log
+```
+
+### Analytics
+
+```javascript
+buildTrackEvent(data, ticketQuantity, promoCode)
+// Builds GA4-style event data with currency, items_array, discount
+```
+
+## Helper Exports (`src/helpers/`)
+
+Barrel export from `src/helpers/index.js`:
+
+- `capitalizeFirstLetter` — text formatting
+- `formatCurrency` — locale-aware currency display
+- `formatErrorMessage` — error message normalization
+- `getTicketMaxQuantity` — ticket quantity constraints
+
+## Common Mistakes
+
+- Using `reservation.amount === 0` directly instead of `isFreeOrder()` (misses edge cases)
+- Forgetting `isPrePaidOrder()` check alongside `isFreeOrder()` in payment flows
+- Not handling `getCurrentProvider()` returning `{ publicKey: null, provider: '' }` when no payment profile exists