@sunboard/react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sunboardhq.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+# @sunboard/react
+
+React SDK for [Sunboard](https://sunboardhq.com) — agent-native onboarding for SaaS apps.
+
+Renders the in-app checklist, product tours, and hotspots that your AI agent authors and you promote to active in Sunboard.
+
+> **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.
+
+## Install
+
+```bash
+npm i @sunboard/react
+```
+
+Peer dependencies: `react` >= 18.3 and `react-dom` >= 18.3 (React 19 supported).
+
+## Wiring
+
+Wrap your app once with `SunboardProvider`, drop `<Sunboard />` somewhere in your layout, and import the default stylesheet:
+
+```tsx
+import { SunboardProvider, Sunboard } from "@sunboard/react";
+import "@sunboard/react/styles.css";
+
+export default function RootLayout({ children }) {
+  return (
+    <SunboardProvider
+      runtimeKey={process.env.NEXT_PUBLIC_SUNBOARD_KEY!}
+      user={{ id: currentUser.id, firstName: currentUser.firstName }}
+      navigate={(href) => router.push(href)}
+    >
+      {children}
+      <Sunboard />
+    </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.
+
+## What gets rendered
+
+- **`<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.
+
+## Theming
+
+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.
+
+## Links
+
+- CLI + agent skills: [`sunboard`](https://www.npmjs.com/package/sunboard)
+- App: <https://app.sunboardhq.com>
+- Documentation: <https://sunboardhq.com>
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/index.d.mts

@@ -0,0 +1,156 @@
+import { ReactNode } from "react";
+import { RuntimeBootstrapRequest, RuntimeBootstrapResponse, RuntimeExperience, RuntimeProgress, RuntimeTrackRequest, RuntimeTrackResponse, SunboardRuntimeApiError, SunboardRuntimeClient, SunboardRuntimeClientOptions } from "@sunboard/core/runtime-api";
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+import { NormalizedSunboardSpec, SunboardHotspot, SunboardStep, SunboardTourStep, TrackEventName } from "@sunboard/core";
+
+//#region src/adapters/navigation.d.ts
+type NavigateCallback = (url: string) => void | Promise<void>;
+//#endregion
+//#region src/hooks/sunboard-context.d.ts
+type SunboardUser = {
+  id: string;
+  email?: string | null;
+  group?: string | null;
+  properties?: Record<string, unknown>;
+};
+type TrackProperties = Record<string, unknown>;
+type TrackResult = {
+  ok: true;
+} | {
+  ok: false;
+  reason: "not-ready" | "missing-user" | "network-error";
+};
+type TourResult = {
+  ok: true;
+} | {
+  ok: false;
+  reason: "not-ready" | "missing-user" | "missing-tour";
+};
+type SunboardRuntimeMode = "production" | "preview";
+type SunboardTourError = {
+  message: string;
+  route?: string;
+  stepKey?: string;
+  target?: string;
+  tourKey: string;
+};
+type ActiveSunboardTour = {
+  key: string;
+  name: string;
+  step: SunboardTourStep;
+  stepIndex: number;
+  totalSteps: number;
+};
+type SunboardContextValue = {
+  spec?: NormalizedSunboardSpec | null;
+  user?: SunboardUser | null;
+  loading: boolean;
+  route?: string;
+  mode: SunboardRuntimeMode;
+  completedStepKeys: ReadonlySet<string>;
+  completedTourKeys: ReadonlySet<string>;
+  completedCount: number;
+  totalSteps: number;
+  activeTour: ActiveSunboardTour | null;
+  tourError: SunboardTourError | null;
+  track: (eventName: TrackEventName, properties?: TrackProperties) => Promise<TrackResult>;
+  startTour: (tourKey: string) => Promise<TourResult>;
+  dismissTour: () => Promise<TourResult>;
+  advanceTour: () => Promise<TourResult>;
+  navigateToStep: (step: SunboardStep) => Promise<void>;
+  startChecklistStep: (step: SunboardStep) => Promise<TourResult | void>;
+  reportTourError: (error: SunboardTourError | null) => void;
+  visibleHotspots: Array<{
+    key: string;
+    hotspot: SunboardHotspot;
+  }>;
+};
+//#endregion
+//#region src/components/SunboardProvider.d.ts
+type SunboardProviderProps = {
+  spec?: NormalizedSunboardSpec | null;
+  user?: SunboardUser | null;
+  loading?: boolean;
+  mode?: SunboardRuntimeMode;
+  route?: string;
+  navigate?: NavigateCallback;
+  apiUrl?: string;
+  publishableKey?: string;
+  environment?: string;
+  onTrack?: (eventName: TrackEventName, properties?: TrackProperties) => void | Promise<void>;
+  children: ReactNode;
+};
+declare function SunboardProvider({
+  spec: specProp,
+  user,
+  loading: loadingProp,
+  mode: modeProp,
+  route,
+  navigate,
+  apiUrl,
+  publishableKey,
+  environment,
+  onTrack,
+  children
+}: SunboardProviderProps): react_jsx_runtime0.JSX.Element;
+//#endregion
+//#region src/components/SunboardHotspots.d.ts
+declare function SunboardHotspots(): react_jsx_runtime0.JSX.Element;
+//#endregion
+//#region src/components/SunboardTour.d.ts
+declare function SunboardTour(): react_jsx_runtime0.JSX.Element | null;
+//#endregion
+//#region src/components/Sunboard.d.ts
+declare function SunboardChecklist(): react_jsx_runtime0.JSX.Element | null;
+declare const Sunboard: typeof SunboardChecklist & {
+  Checklist: typeof SunboardChecklist;
+  Hotspots: typeof SunboardHotspots;
+  Tour: typeof SunboardTour;
+};
+//#endregion
+//#region src/hooks/useSunboardPreviewSpec.d.ts
+type SunboardPreviewSpecState = {
+  error: Error | null;
+  loading: boolean;
+  source: "none" | "preview";
+  spec: NormalizedSunboardSpec | null;
+};
+declare function useSunboardPreviewSpec(): SunboardPreviewSpecState;
+//#endregion
+//#region src/hooks/useSunboard.d.ts
+declare function useSunboard(): SunboardContextValue;
+//#endregion
+//#region src/hooks/useChecklist.d.ts
+type ChecklistViewStep = {
+  key: string;
+  title: string;
+  description?: string;
+  badge?: string;
+  actionLabel?: string;
+};
+type ChecklistCompletion = {
+  title: string;
+  subtitle?: string;
+  message?: string;
+  dismissAfterMs?: number;
+};
+type UseChecklistResult = {
+  visible: boolean;
+  title?: string;
+  subtitle?: string;
+  steps: ChecklistViewStep[];
+  completedStepKeys: ReadonlySet<string>;
+  completedCount: number;
+  totalSteps: number;
+  remainingCount: number;
+  progress: number;
+  isCompleted: (key: string) => boolean;
+  hasAction: (step: ChecklistViewStep) => boolean;
+  startStep: (step: ChecklistViewStep) => void;
+  completion?: ChecklistCompletion;
+  dismissCompletion: () => void;
+};
+declare function useChecklist(): UseChecklistResult;
+//#endregion
+export { type ChecklistViewStep, type RuntimeBootstrapRequest, type RuntimeBootstrapResponse, type RuntimeExperience, type RuntimeProgress, type RuntimeTrackRequest, type RuntimeTrackResponse, Sunboard, SunboardChecklist, type SunboardContextValue, SunboardHotspots, type SunboardPreviewSpecState, SunboardProvider, type SunboardProviderProps, SunboardRuntimeApiError, SunboardRuntimeClient, type SunboardRuntimeClientOptions, type SunboardRuntimeMode, SunboardTour, type SunboardTourError, type SunboardUser, type TourResult, type TrackProperties, type TrackResult, type UseChecklistResult, useChecklist, useSunboard, useSunboardPreviewSpec };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/adapters/navigation.ts","../src/hooks/sunboard-context.ts","../src/components/SunboardProvider.tsx","../src/components/SunboardHotspots.tsx","../src/components/SunboardTour.tsx","../src/components/Sunboard.tsx","../src/hooks/useSunboardPreviewSpec.ts","../src/hooks/useSunboard.ts","../src/hooks/useChecklist.ts"],"sourcesContent":[],"mappings":"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"}