@sensiblestats/widget-react 0.63.0 → 0.64.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @sensiblestats/widget-react
 
+## 0.64.0
+
+### Minor Changes
+
+- Host events. `createWidgetHost()` and the `host` prop let an operator tell the widget when a slip selection is removed (`slipRemoved`), a bet is placed (`betPlaced`) and a match page is opened (`matchOpened`). `config.onOpenMatch` turns team names into links that call the operator with the match id. The "In slip" mark now belongs to the odd, so it survives closing the panel and shows on every button for that odd. New event names `slip_remove`, `bet_placed`, `match_view` and `match_open`; `match_view` is deferred and never starts a request of its own. `EventLogger.resume()` undoes `dispose()`, which stops events being dropped under React StrictMode in a development build.
+
+### Patch Changes
+
+- Updated dependencies
+  - @sensiblestats/widget-sdk@0.39.0
+
 ## 0.63.0
 
 ### Minor Changes

package/README.md

@@ -39,6 +39,63 @@ Common `config` fields:
 - White-label branding — `logoUrl`, `headerTitle`, `accent`, `cta`, `surface`,
   `ink`. Absent → the default SensibleStats look.
 
+## Hooks: the slip and the match page
+
+Optional hooks keep the widget and your site in step. Two are `config` callbacks, from the widget
+to your code. Three are methods on a host object you create, from your code to the widget.
+
+```tsx
+// widget-host.ts
+import { createWidgetHost } from '@sensiblestats/widget-react'
+
+// Create it once, at module scope. It is safe under server rendering.
+export const widgetHost = createWidgetHost()
+```
+
+```tsx
+<StatsWidget
+  host={widgetHost}
+  config={{
+    ...config,
+    onAddToSlip: (selection) => addToMySlip(selection),
+    onOpenMatch: ({ matchId }) => router.push(`/match/${matchId}`),
+  }}
+/>
+```
+
+```ts
+widgetHost.slipRemoved({ matchOddsId })                  // a leg left your slip
+widgetHost.betPlaced({ selections: [{ matchOddsId }] })  // the bet was placed
+widgetHost.matchOpened({ matchId })                      // your match page opened
+```
+
+What each one does:
+
+- `onAddToSlip`. Called when the user taps "Add to slip", with `{ matchOddsId, matchId, oddsDecimal }`.
+  Add that selection to your slip. Return nothing, or a result such as `{ status: 'added' }`,
+  `{ status: 'duplicate' }` or `{ status: 'rejected', reason }`. The widget shows "In slip" for an
+  added or duplicate selection. Answer within 10 seconds. Without a `host`, an "In slip" button
+  stays that way until the page reloads; with one, `slipRemoved` and `betPlaced` clear it.
+- `onOpenMatch`. Without it team names in the widget are plain text. With it they are buttons that
+  call you with the match id. On a phone the panel closes after the tap, because it covers the
+  page.
+- `slipRemoved`. Clears the widget's "In slip" mark for that selection. Call it whenever a leg
+  leaves your slip for any reason, a "clear all" included. A leg the widget still believes is in
+  the slip can be reported as bet later.
+- `betPlaced`. Pass every leg of the bet. The widget reports the legs it added itself, at most 25
+  per call, and ignores the rest, so you do not filter.
+- `matchOpened`. Call it from your match page. A view counts only for a visitor who has opened the
+  widget in that tab, and at most once per match every 30 minutes.
+
+Rules for the three host methods:
+
+- `matchOddsId` and `matchId` are the numbers `onAddToSlip` gave you. Anything that is not a
+  positive integer is ignored, a numeric string included.
+- No method throws, and each is safe to call twice.
+- A call made while no widget is mounted is queued, the last 20, and replayed when one mounts. The
+  queue lives in the page, so it does not survive a full page load.
+- Use one host for one mounted widget.
+
 ## Integration: persisting the conversation across SPA navigation
 
 The conversation (messages, conversation id, open/closed state) lives in the