@sensiblestats/widget-react 0.35.0 → 0.37.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @sensiblestats/widget-react
 
+## 0.37.0
+
+### Minor Changes
+
+- 8d25f74: Match odds accordion: pinned matches on the Matches tab now show a browsable accordion of every priced market instead of a single 1X2 card. Odds load lazily on expand and refresh live while open; each market surfaces its value insight. Adds `conversation.getMarketOdds` and `availableMarkets` on the live-monitor snapshot; removes the snapshot's `mainMarket`.
+
+### Patch Changes
+
+- Updated dependencies [8d25f74]
+  - @sensiblestats/widget-sdk@0.30.0
+
+## 0.36.0
+
+### Minor Changes
+
+- Add a `pinIcon` config option (`'pin' | 'star' | 'bookmark'`, default `'pin'`, embed `data-pin-icon`) to choose the glyph used for the match/odds save toggle. All three render as an outline when unpinned and fill on the accent circle when pinned; the default pin keeps its existing shape.
+
+## 0.35.1
+
+### Patch Changes
+
+- 1210539: Add a one-shot launcher attention animation: on first load the chat icon nudges, then the greeting bubble types itself in, then everything settles. Runs once per page (a refresh replays it) and is fully suppressed under `prefers-reduced-motion`, where the greeting is shown statically. No config or API change.
+
 ## 0.35.0
 
 ### Minor Changes

package/README.md

@@ -0,0 +1,112 @@
+# @sensiblestats/widget-react
+
+React component for the SensibleStats operator chat widget. Renders a floating
+launcher and chat panel, built on `@sensiblestats/widget-sdk`.
+
+## Install
+
+`yarn add @sensiblestats/widget-react`
+
+Peer dependencies: `react` and `react-dom` (18 or 19).
+
+## Usage
+
+```tsx
+import { StatsWidget } from '@sensiblestats/widget-react'
+
+export function App() {
+  return (
+    <StatsWidget
+      config={{
+        operatorId: 'sandbox1',
+        publicKey: 'wgk_…',
+        baseUrl: 'https://widget.sensiblestats.com',
+        locale: 'en',
+      }}
+    />
+  )
+}
+```
+
+Common `config` fields:
+
+- `operatorId`, `publicKey` — your gateway credentials (both browser-safe; the
+  public key is origin-gated at the gateway).
+- `baseUrl` — the widget gateway URL.
+- `locale` — `'en'` or `'tr'` for the widget's own chrome text.
+- `userContext` — `{ operatorUserId, defaultLanguage }` to tie the conversation
+  and personalization to your signed-in user.
+- White-label branding — `logoUrl`, `headerTitle`, `accent`, `cta`, `surface`,
+  `ink`. Absent → the default SensibleStats look.
+
+## Integration: persisting the conversation across SPA navigation
+
+The conversation (messages, conversation id, open/closed state) lives in the
+component's in-memory React state. It survives for exactly as long as the
+`<StatsWidget>` instance stays mounted:
+
+- **In-app (client-side) navigation** keeps it — as long as the component is not
+  unmounted.
+- **A hard page refresh** tears down the React tree and remounts the widget, so
+  the conversation starts fresh. This is intentional.
+
+To keep the active conversation across route changes in a single-page app,
+**mount `<StatsWidget>` once in a component that stays mounted across
+navigation** — your app shell / persistent layout — not inside a routed page.
+
+### React Router (v6)
+
+Render the widget in the layout route element, alongside `<Outlet />`, so it
+persists while pages swap underneath it:
+
+```tsx
+// AppLayout.tsx
+import { Outlet } from 'react-router-dom'
+import { StatsWidget } from '@sensiblestats/widget-react'
+
+// Define config once, outside render, so its identity is stable across renders.
+const widgetConfig = {
+  operatorId: 'sandbox1',
+  publicKey: 'wgk_…',
+  baseUrl: 'https://widget.sensiblestats.com',
+}
+
+export function AppLayout() {
+  return (
+    <>
+      <Header />
+      <Outlet />                          {/* pages render here and swap on navigation */}
+      <StatsWidget config={widgetConfig} />  {/* stays mounted across route changes */}
+    </>
+  )
+}
+```
+
+```tsx
+// routes — AppLayout wraps the routed pages, so it is not remounted per route
+<Route element={<AppLayout />}>
+  <Route path="/" element={<Home />} />
+  <Route path="/matches" element={<Matches />} />
+</Route>
+```
+
+### Next.js App Router
+
+Render `<StatsWidget>` in the root `app/layout.tsx` (a client component, or a
+small `'use client'` wrapper). The root layout is not re-rendered on route
+navigation, so the conversation persists; a full reload resets it.
+
+### What breaks persistence
+
+Both of these force React to unmount and remount the widget, wiping the
+conversation on every navigation — avoid them:
+
+- **Rendering `<StatsWidget>` inside a per-route page component.** React Router
+  unmounts the page (and the widget with it) on navigation.
+- **Changing the component's `key`, or passing a `config` object rebuilt on
+  every render, in a way that remounts the subtree.** Keep the widget's place in
+  the tree and its `config` reference stable — define `config` at module scope or
+  memoize it with `useMemo`.
+
+The launcher is fixed-position, so the app-shell mount is also the correct place
+for it visually — it does not belong to any single page.