@sunboard/react 0.9.0 → 1.1.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 sunboardhq.com
+Copyright (c) 2026 Sunboard
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,59 +1,267 @@
 # @sunboard/react
 
-React SDK for [Sunboard](https://sunboardhq.com) — agent-native onboarding for SaaS apps.
+Product tours, tooltips and a Help launcher with an assistant, for your React app.
 
-Renders the in-app checklist, product tours, and hotspots that your AI agent authors and you promote to active in Sunboard.
+[![npm](https://img.shields.io/npm/v/@sunboard/react.svg)](https://www.npmjs.com/package/@sunboard/react)
+[![license](https://img.shields.io/npm/l/@sunboard/react.svg)](./LICENSE)
+![react](https://img.shields.io/badge/react-18%2B-blue.svg)
 
-> **You usually don't install this by hand.** Run `npm i -g sunboard && sunboard init` in your app and the CLI wires the provider, stylesheet, and environment variables for you. The reference below is for people who want to understand or customize that wiring after the fact.
+You need a Sunboard account. In the Sunboard app, **Settings › Install** has these steps for your
+framework with your key already filled in, and a prompt you can hand to your coding agent.
 
-## Install
+## Quickstart
+
+```tsx
+import "@sunboard/react/styles.css";
+import { SunboardOverlay, SunboardProvider } from "@sunboard/react";
+
+<SunboardProvider connection={{ publishableKey: SUNBOARD_KEY, userId: currentUser.id }}>
+  <App />
+  <SunboardOverlay />
+</SunboardProvider>
+```
+
+That is the whole integration. The steps below put it in the right place for your framework.
+
+## Getting started
+
+### 1. Install the package
 
 ```bash
-npm i @sunboard/react
+npm install @sunboard/react
+# or
+pnpm add @sunboard/react
+# or
+yarn add @sunboard/react
 ```
 
-Peer dependencies: `react` >= 18.3 and `react-dom` >= 18.3 (React 19 supported).
+React 18 or later. Every export is client code.
+
+### 2. Add your publishable key
+
+Copy it from **Settings › Install**. It is safe in the browser.
+
+```bash
+# Next.js, in .env.local
+NEXT_PUBLIC_SUNBOARD_KEY=<your publishable key>
+
+# Vite, React Router or TanStack, in .env
+VITE_SUNBOARD_KEY=<your publishable key>
+```
 
-## Wiring
+### 3. Create one Sunboard component
 
-Wrap your app once with `SunboardProvider`, drop `<Sunboard />` somewhere in your layout, and import the default stylesheet:
+It connects to Sunboard, shows tours and the Help launcher, and lets a tour change pages through
+your router. This is the Next.js version:
 
 ```tsx
-import { SunboardProvider, Sunboard } from "@sunboard/react";
+// app/sunboard.tsx
+"use client";
+
 import "@sunboard/react/styles.css";
+import type { ReactNode } from "react";
+import { useRouter } from "next/navigation";
+import { SunboardOverlay, SunboardProvider } from "@sunboard/react";
 
-export default function RootLayout({ children }) {
+export function Sunboard({
+  userId,
+  firstName,
+  children,
+}: {
+  userId: string;
+  firstName?: string;
+  children: ReactNode;
+}) {
+  const router = useRouter();
   return (
     <SunboardProvider
-      runtimeKey={process.env.NEXT_PUBLIC_SUNBOARD_KEY!}
-      user={{ id: currentUser.id, firstName: currentUser.firstName }}
-      navigate={(href) => router.push(href)}
+      connection={{
+        publishableKey: process.env.NEXT_PUBLIC_SUNBOARD_KEY!,
+        userId,
+        user: { firstName },
+      }}
+      navigate={(path) => router.push(path)}
     >
       {children}
-      <Sunboard />
+      <SunboardOverlay />
     </SunboardProvider>
   );
 }
 ```
 
-`sunboard init` produces this exact wiring for Next.js (App Router and Pages) and Vite. `sunboard doctor` confirms it's still correct after upgrades.
+Other frameworks change the key, `navigate`, and where the stylesheet loads:
+
+| Framework | Key | `navigate` |
+| --- | --- | --- |
+| React Router | `import.meta.env.VITE_SUNBOARD_KEY` | `useNavigate()` from `react-router`, then `(path) => navigate(path)` |
+| TanStack Start | `import.meta.env.VITE_SUNBOARD_KEY` | `useNavigate()` from `@tanstack/react-router`, then `(path) => navigate({ href: path })` |
+| Vite with no router | `import.meta.env.VITE_SUNBOARD_KEY` | Leave it out. |
+
+Outside Next.js the file has no `"use client"` line. In TanStack Start, load the stylesheet from
+`head()` in `src/routes/__root.tsx` instead of importing it:
+
+```tsx
+import sunboardCss from "@sunboard/react/styles.css?url";
+
+// in head(): links: [{ rel: "stylesheet", href: sunboardCss }]
+```
+
+`useRouter` and `useNavigate` work only inside the router, so mount the component where the
+table below says.
+
+### 4. Wrap your signed-in pages
+
+Put the component around the pages a signed-in user sees, and pass that user's id. Use an id that
+stays the same for each person. The first name is optional. With it the assistant greets the
+user ("Hey Sam,"), without it it says "Hey there,". The name stays in the browser.
+
+```tsx
+import { Sunboard } from "./sunboard";
+
+<Sunboard userId={currentUser.id} firstName={currentUser.firstName}>
+  {children}
+</Sunboard>
+```
 
-## What gets rendered
+| Framework | Where |
+| --- | --- |
+| Next.js | `app/layout.tsx`, or the layout of your signed-in area, inside `body` |
+| React Router | Around the `Outlet` in `app/root.tsx`, or inside `BrowserRouter` |
+| TanStack Start | Around the page content in `src/routes/__root.tsx` |
+| Vite | Around `App` in `src/main.tsx` |
 
-- **`<Sunboard />`** — the main entry point. Renders the active checklist, any in-progress tours, and any visible hotspots based on the current route and user.
-- **`<SunboardChecklist />`**, **`<SunboardHotspots />`**, **`<SunboardTour />`** — individual surfaces, if you want to place them manually.
-- **`useSunboard()`** — hook returning runtime state and imperative helpers like `startTour(key)`, useful for custom product UI.
+A Next.js app with route groups, such as `app/(marketing)/layout.tsx` and
+`app/(app)/layout.tsx`, wraps `children` in the signed-in group's layout only.
 
-## Theming
+### 5. Check it works
+
+Start your app and sign in. **Settings › Install** in the Sunboard app shows **Connected**. Then
+add your app's address under **Settings › Project**, and use **Preview** on any guide to see it
+in your app.
+
+## Good to know
+
+- **The same key works locally and in production.** Visits from `localhost`, `127.0.0.1` and
+  `[::1]` are left out of Analytics and do not count as active users.
+- **Content Security Policy.** The package talks to `https://api.sunboardhq.com`, so a
+  `connect-src` rule has to allow it.
+- **Server rendering.** The package is client code and says so, so a Next.js server component
+  can import your `Sunboard` component without a wrapper.
+- **Styling.** Colors, fonts, the launcher and the tour cards are set on the **Appearance** page
+  in the Sunboard app and reach your app without a deploy. The stylesheet import above is the
+  only CSS you add.
+- **Preview.** The **Preview** button on a guide in the Sunboard app opens your app with
+  `?sunboardPreview=<key>` in the address and shows paused guides as well as live ones, in that
+  browser only. `?sunboardPreview=off` ends it.
+- **Users.** The active-user limit on your plan counts the ids you pass as `userId`, so give each
+  person one id that never changes.
+
+## Reference
+
+### SunboardProvider
+
+| Prop | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `connection` | `{ publishableKey: string; userId: string; user?: { firstName?: string } }` | required | Your publishable key and the signed-in user's id. `user.firstName` is for the assistant's greeting and stays in the browser. |
+| `navigate` | `(path: string) => void \| Promise<void>` | full page load | How a tour moves to another page. Pass your router. Without it, a tour loads the next page in full and carries on there. |
+| `labels` | `LabelOverrides` | English | Your own words for any of the SDK's buttons and text, for example `labels={{ launcher: { open: "Support" } }}`. The rest stay English. `enLabels` has every one. |
+| `mode` | `"auto" \| "light" \| "dark"` | `"auto"` | Light or dark. `"auto"` follows a `dark` or `light` class, or a `data-theme`, `data-mode` or `data-color-scheme` attribute, on `<html>` or `<body>`, then the system setting, and tracks changes live. |
+| `debug` | `boolean` | `false` | Logs what the SDK does to the browser console, each line starting with `[sunboard]`. The lines use `console.debug`, so Chrome shows them only with the Verbose level on. |
+
+### SunboardOverlay
+
+Shows tours, tooltips, announcements, banners and the Help pill. Mount it once, anywhere inside
+the provider.
+
+| Prop | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `launcher` | `boolean` | `true` | Shows the Help pill. Pass `false` when you build your own, see below. |
+
+### Address switches
+
+Add these to any address in your app. The SDK reads each one once and removes it from the
+address.
+
+| Switch | What it does |
+| --- | --- |
+| `?sunboardDebug=1` | Turns on `debug` for that page load. |
+| `?sunboardLaunch=<guide key>` | Starts that tour once the guides load. The Preview link on a tour in the Sunboard app carries it, so you can copy the key from there. |
+
+## Your own help menu
+
+The Help pill is built on public hooks, so you can show your guides and the assistant in your
+own UI instead. Keep `<SunboardOverlay />` for tours, tooltips, announcements and banners, and
+turn the pill off:
+
+```tsx
+<SunboardOverlay launcher={false} />
+```
+
+Call `useLauncher()` once for your help menu and pass what it returns down.
+
+| Field | What it is |
+| --- | --- |
+| `onThisPage` | Guides for the page the user is on. |
+| `elsewhere` | Every other guide. |
+| `ready` | `true` once the guides have loaded. |
+| `tourRunning` | `true` while a tour runs. |
+| `opened()` | Call it when your menu opens, so the open counts in Analytics. |
+| `start(guideKey, replyId?)` | Starts a guide. Pass the id of the answer that offered it, and the conversation gets a line after that answer when the tour ends. |
+| `messages` | The conversation with the assistant, oldest first. Each `Message` has an `id` and a `kind`: `question`, `waiting`, `reply`, `error` or `tour`. A `reply` holds an `AskReply` with the answer's text in `answer` and `guideKey` when it offers a guide to start. |
+| `waiting` | `true` while a question is out and its answer has not come back. |
+| `rateLimitedUntil` | While the user has asked too many questions this hour, the time they can ask again, as an ISO string. Otherwise `undefined`. |
+| `handedOff` | `true` while a tour started from the conversation runs. It turns `false` when the tour ends, the moment to show your panel again. |
+| `ask(question)` | Asks a question, as a follow-up when the conversation has one. A blank question is ignored, and so is one while `waiting` or while `rateLimitedUntil` is set. |
+| `retry()` | Asks the newest question again when no answer came back for it. |
+| `startOver()` | Clears the conversation. The next question starts a new one. |
+
+`Menu` and `MenuItem` below stand for your own components:
+
+```tsx
+import { useLauncher } from "@sunboard/react";
+
+function HelpMenu() {
+  const { onThisPage, elsewhere, opened, start } = useLauncher();
+  return (
+    <Menu onOpen={opened}>
+      {onThisPage.map((guide) => (
+        <MenuItem key={guide.key} onSelect={() => start(guide.key)}>
+          {guide.title}
+        </MenuItem>
+      ))}
+      <MenuSeparator />
+      {elsewhere.map((guide) => (
+        <MenuItem key={guide.key} onSelect={() => start(guide.key)}>
+          {guide.title}
+        </MenuItem>
+      ))}
+    </Menu>
+  );
+}
+```
 
-Override CSS variables defined in `@sunboard/react/styles.css` to match your app's design system. Import the Sunboard stylesheet *before* your own so your overrides win the cascade.
+Two more hooks help here. `useGuide(key)` returns `{ guide, launchTour }` for one guide, so a
+button anywhere in your app can start a tour. `useTheme()` returns `{ theme, mode, cssVars }`,
+the colors in use as CSS variables to spread onto your menu so it matches the tours.
 
-## Links
+## Troubleshoot
 
-- CLI + agent skills: [`sunboard`](https://www.npmjs.com/package/sunboard)
-- App: <https://app.sunboardhq.com>
-- Documentation: <https://sunboardhq.com>
+- **Nothing shows in my app.** Add `?sunboardDebug=1` to the page address and open the browser
+  console with the Verbose level on. A wrong key shows as a failed request. No lines at all means
+  the provider is not mounted around the page you are on.
+- **Settings › Install does not say Connected.** It turns Connected on the first request from your
+  app, so load a page where the provider is mounted, signed in, and reload the Install tab.
+- **A tour reloads the page instead of changing route.** Pass `navigate` with your router. Without
+  it, a tour carries on after a full page load.
+- **The tour cards have no styling.** Import `@sunboard/react/styles.css` once, next to the
+  provider. In TanStack Start, load it from `head()` as shown above.
+- **Requests to api.sunboardhq.com are blocked.** Your Content Security Policy needs it in
+  `connect-src`.
+- **Next.js says the component needs "use client".** Put `"use client"` on the first line of your
+  `sunboard.tsx`, as in step 3. The package itself is already client code.
+- **useRouter or useNavigate throws.** Mount the component inside the router, where the table in
+  step 4 says.
 
 ## License
 
-MIT — see [LICENSE](./LICENSE).
+MIT