@navieo/react 1.0.0

package/README.md

@@ -0,0 +1,62 @@
+# @navieo/react
+
+AI-powered contextual site guide SDK for React and Next.js.
+
+## Installation
+
+```bash
+npm install @navieo/react
+```
+
+## Quick Start
+
+### React
+
+```tsx
+import { NavieoProvider, ChatWidget } from "@navieo/react";
+
+function App() {
+  return (
+    <NavieoProvider currentRoute={window.location.pathname}>
+      <ChatWidget />
+      {/* your app */}
+    </NavieoProvider>
+  );
+}
+```
+
+### Next.js
+
+```tsx
+import { NavieoNextProvider } from "@navieo/react/next";
+
+export default function Layout({ children }) {
+  return (
+    <NavieoNextProvider>
+      {children}
+    </NavieoNextProvider>
+  );
+}
+```
+
+The Next.js provider automatically handles route detection and navigation.
+
+## Exports
+
+| Export | Description |
+|--------|-------------|
+| `NavieoProvider` | Context provider with tour and chat state management |
+| `ChatWidget` | Built-in floating chat widget |
+| `useNavieo` | Hook to access tour/chat state and actions |
+| `useTourRenderer` | Hook for custom tour rendering with driver.js |
+| `NavieoNextProvider` | Next.js wrapper (from `@navieo/react/next`) |
+
+## Requirements
+
+- React 18+ or 19+
+- Next.js 14+ (optional, for `@navieo/react/next`)
+- Node.js >= 18
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,178 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+import * as _navieo_types from '@navieo/types';
+import { TourStep } from '@navieo/types';
+export { ElementSelector, GuideRequest, GuideResponse, SitemapDoc, SitemapElement, SitemapFlow, SitemapRoute, TourStep } from '@navieo/types';
+
+/** Full sitemap structure with all fields required (React-specific). */
+interface Sitemap {
+    appId: string;
+    framework: string;
+    generatedAt: string;
+    routes: _navieo_types.SitemapRoute[];
+    flows: _navieo_types.SitemapFlow[];
+    docs: _navieo_types.SitemapDoc[];
+}
+/** Current state of the guided tour lifecycle. */
+type TourState = "idle" | "loading" | "active" | "error";
+/** A single message in the chat history. */
+interface ChatMessage {
+    /** Whether this message is from the user or the assistant. */
+    role: "user" | "assistant";
+    /** The text content of the message. */
+    content: string;
+}
+/** Value provided by {@link NavieoProvider} via React context. */
+interface NavieoContextValue {
+    /** Whether the chat panel is currently visible. */
+    isChatOpen: boolean;
+    /** Open the chat panel. */
+    openChat: () => void;
+    /** Close the chat panel. */
+    closeChat: () => void;
+    /** Toggle the chat panel open/closed. */
+    toggleChat: () => void;
+    /** Current state of the tour lifecycle. */
+    tourState: TourState;
+    /** All steps in the current tour. Empty when no tour is active. */
+    steps: TourStep[];
+    /** Zero-based index of the currently highlighted step. */
+    currentStepIndex: number;
+    /** The currently highlighted step, or `null` when no tour is active. */
+    currentStep: TourStep | null;
+    /** Send a natural-language query to the guide API and start a tour. */
+    startTour: (query: string) => Promise<void>;
+    /** Advance to the next step in the active tour. */
+    nextStep: () => void;
+    /** Go back to the previous step in the active tour. */
+    prevStep: () => void;
+    /** Stop the active tour and reset all tour state. */
+    endTour: () => void;
+    /** Jump to a specific step by index. */
+    goToStep: (index: number) => void;
+    /** Full chat history (persisted to localStorage). */
+    chatHistory: ChatMessage[];
+    /** Clear all chat messages from history and localStorage. */
+    clearChatHistory: () => void;
+    /** The current route/pathname of the host application. */
+    currentRoute: string;
+    /** Suggestion chips shown in the empty chat state. */
+    suggestions?: Array<{
+        label: string;
+        tag?: string;
+    }>;
+}
+
+/** Props for the {@link NavieoProvider} context provider. */
+interface NavieoProviderProps {
+    children: React.ReactNode;
+    /** Current pathname of the app (e.g., from usePathname, window.location.pathname, etc.) */
+    currentRoute: string;
+    /** Called when the tour needs to navigate to a different route */
+    onNavigate: (route: string) => void;
+    /** API endpoint for guide queries. Defaults to "/api/guide". */
+    apiEndpoint?: string;
+    /** Application identifier */
+    appId?: string;
+    /** Suggestion chips shown in empty chat state */
+    suggestions?: Array<{
+        label: string;
+        tag?: string;
+    }>;
+    /** Whether to render the built-in ChatWidget. Default: true */
+    renderChat?: boolean;
+}
+/**
+ * Root context provider for the Navieo SDK.
+ *
+ * Manages tour state, chat history, API communication, and cross-page
+ * navigation. Wrap your application (or a subtree) with this provider and
+ * access the tour/chat API via the {@link useNavieo} hook.
+ *
+ * @example
+ * ```tsx
+ * <NavieoProvider currentRoute={pathname} onNavigate={router.push}>
+ *   <App />
+ * </NavieoProvider>
+ * ```
+ */
+declare function NavieoProvider({ children, currentRoute, onNavigate, apiEndpoint, appId, suggestions, renderChat, }: NavieoProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Access the Navieo tour and chat API from any component inside a
+ * {@link NavieoProvider}.
+ *
+ * @throws {Error} If called outside of a `<NavieoProvider>`.
+ *
+ * @example
+ * ```tsx
+ * const { startTour, tourState, chatHistory } = useNavieo();
+ * ```
+ */
+declare function useNavieo(): NavieoContextValue;
+
+interface TourRendererOptions {
+    onStepChange?: (stepIndex: number) => void;
+    onComplete?: () => void;
+    onClose?: () => void;
+    /** Called when the tour needs to navigate to a different route. */
+    onNavigationNeeded?: (route: string) => void;
+    /** Called when the tour fails (e.g. elements not found after polling). */
+    onError?: (message: string) => void;
+}
+declare function useTourRenderer(options?: TourRendererOptions): {
+    startTour: (steps: TourStep[], currentRoute: string) => void;
+    restoreTour: (steps: TourStep[], currentRoute: string) => void;
+    stopTour: () => void;
+    nextStep: () => void;
+    prevStep: () => void;
+    goToStep: (index: number) => void;
+    continueAfterNavigation: (arrivedRouteOrPattern: string) => void;
+};
+
+/**
+ * Floating chat widget rendered by {@link NavieoProvider} (when `renderChat`
+ * is `true`). Provides a text input for guide queries, displays chat history,
+ * suggestion chips, and a stop-tour button during active tours.
+ *
+ * Rendered via `createPortal` into `document.body`.
+ */
+declare function ChatWidget(): React.ReactPortal | null;
+
+/**
+ * Centralized logger for the Navieo SDK.
+ *
+ * Provides leveled logging (debug, info, warn, error) with a consistent
+ * "[Navieo]" prefix. Log level can be controlled at runtime via
+ * `Logger.setLevel()` or by setting `window.__NAVIEO_LOG_LEVEL__`.
+ *
+ * Levels (from most to least verbose):
+ *   debug → info → warn → error → silent
+ *
+ * Default level: "info" in development, "warn" in production.
+ */
+type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
+declare class NavieoLogger {
+    private level;
+    /** Change the active log level at runtime. */
+    setLevel(level: LogLevel): void;
+    getLevel(): LogLevel;
+    private shouldLog;
+    /** Verbose diagnostic info — only shown at "debug" level. */
+    debug(message: string, ...args: unknown[]): void;
+    /** Standard operational info — shown at "info" level and above. */
+    info(message: string, ...args: unknown[]): void;
+    /** Warnings — shown at "warn" level and above. */
+    warn(message: string, ...args: unknown[]): void;
+    /** Errors — always shown unless "silent". */
+    error(message: string, ...args: unknown[]): void;
+    /**
+     * Log a structured diagnostic table for tour steps.
+     * Only shown at "debug" level.
+     */
+    debugSteps(label: string, steps: Array<Record<string, unknown>>): void;
+}
+/** Singleton logger instance used throughout the SDK. */
+declare const logger: NavieoLogger;
+
+export { type ChatMessage, ChatWidget, type LogLevel, type NavieoContextValue, NavieoProvider, type NavieoProviderProps, type Sitemap, type TourRendererOptions, type TourState, logger, useNavieo, useTourRenderer };

package/dist/index.d.ts

@@ -0,0 +1,178 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+import * as _navieo_types from '@navieo/types';
+import { TourStep } from '@navieo/types';
+export { ElementSelector, GuideRequest, GuideResponse, SitemapDoc, SitemapElement, SitemapFlow, SitemapRoute, TourStep } from '@navieo/types';
+
+/** Full sitemap structure with all fields required (React-specific). */
+interface Sitemap {
+    appId: string;
+    framework: string;
+    generatedAt: string;
+    routes: _navieo_types.SitemapRoute[];
+    flows: _navieo_types.SitemapFlow[];
+    docs: _navieo_types.SitemapDoc[];
+}
+/** Current state of the guided tour lifecycle. */
+type TourState = "idle" | "loading" | "active" | "error";
+/** A single message in the chat history. */
+interface ChatMessage {
+    /** Whether this message is from the user or the assistant. */
+    role: "user" | "assistant";
+    /** The text content of the message. */
+    content: string;
+}
+/** Value provided by {@link NavieoProvider} via React context. */
+interface NavieoContextValue {
+    /** Whether the chat panel is currently visible. */
+    isChatOpen: boolean;
+    /** Open the chat panel. */
+    openChat: () => void;
+    /** Close the chat panel. */
+    closeChat: () => void;
+    /** Toggle the chat panel open/closed. */
+    toggleChat: () => void;
+    /** Current state of the tour lifecycle. */
+    tourState: TourState;
+    /** All steps in the current tour. Empty when no tour is active. */
+    steps: TourStep[];
+    /** Zero-based index of the currently highlighted step. */
+    currentStepIndex: number;
+    /** The currently highlighted step, or `null` when no tour is active. */
+    currentStep: TourStep | null;
+    /** Send a natural-language query to the guide API and start a tour. */
+    startTour: (query: string) => Promise<void>;
+    /** Advance to the next step in the active tour. */
+    nextStep: () => void;
+    /** Go back to the previous step in the active tour. */
+    prevStep: () => void;
+    /** Stop the active tour and reset all tour state. */
+    endTour: () => void;
+    /** Jump to a specific step by index. */
+    goToStep: (index: number) => void;
+    /** Full chat history (persisted to localStorage). */
+    chatHistory: ChatMessage[];
+    /** Clear all chat messages from history and localStorage. */
+    clearChatHistory: () => void;
+    /** The current route/pathname of the host application. */
+    currentRoute: string;
+    /** Suggestion chips shown in the empty chat state. */
+    suggestions?: Array<{
+        label: string;
+        tag?: string;
+    }>;
+}
+
+/** Props for the {@link NavieoProvider} context provider. */
+interface NavieoProviderProps {
+    children: React.ReactNode;
+    /** Current pathname of the app (e.g., from usePathname, window.location.pathname, etc.) */
+    currentRoute: string;
+    /** Called when the tour needs to navigate to a different route */
+    onNavigate: (route: string) => void;
+    /** API endpoint for guide queries. Defaults to "/api/guide". */
+    apiEndpoint?: string;
+    /** Application identifier */
+    appId?: string;
+    /** Suggestion chips shown in empty chat state */
+    suggestions?: Array<{
+        label: string;
+        tag?: string;
+    }>;
+    /** Whether to render the built-in ChatWidget. Default: true */
+    renderChat?: boolean;
+}
+/**
+ * Root context provider for the Navieo SDK.
+ *
+ * Manages tour state, chat history, API communication, and cross-page
+ * navigation. Wrap your application (or a subtree) with this provider and
+ * access the tour/chat API via the {@link useNavieo} hook.
+ *
+ * @example
+ * ```tsx
+ * <NavieoProvider currentRoute={pathname} onNavigate={router.push}>
+ *   <App />
+ * </NavieoProvider>
+ * ```
+ */
+declare function NavieoProvider({ children, currentRoute, onNavigate, apiEndpoint, appId, suggestions, renderChat, }: NavieoProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Access the Navieo tour and chat API from any component inside a
+ * {@link NavieoProvider}.
+ *
+ * @throws {Error} If called outside of a `<NavieoProvider>`.
+ *
+ * @example
+ * ```tsx
+ * const { startTour, tourState, chatHistory } = useNavieo();
+ * ```
+ */
+declare function useNavieo(): NavieoContextValue;
+
+interface TourRendererOptions {
+    onStepChange?: (stepIndex: number) => void;
+    onComplete?: () => void;
+    onClose?: () => void;
+    /** Called when the tour needs to navigate to a different route. */
+    onNavigationNeeded?: (route: string) => void;
+    /** Called when the tour fails (e.g. elements not found after polling). */
+    onError?: (message: string) => void;
+}
+declare function useTourRenderer(options?: TourRendererOptions): {
+    startTour: (steps: TourStep[], currentRoute: string) => void;
+    restoreTour: (steps: TourStep[], currentRoute: string) => void;
+    stopTour: () => void;
+    nextStep: () => void;
+    prevStep: () => void;
+    goToStep: (index: number) => void;
+    continueAfterNavigation: (arrivedRouteOrPattern: string) => void;
+};
+
+/**
+ * Floating chat widget rendered by {@link NavieoProvider} (when `renderChat`
+ * is `true`). Provides a text input for guide queries, displays chat history,
+ * suggestion chips, and a stop-tour button during active tours.
+ *
+ * Rendered via `createPortal` into `document.body`.
+ */
+declare function ChatWidget(): React.ReactPortal | null;
+
+/**
+ * Centralized logger for the Navieo SDK.
+ *
+ * Provides leveled logging (debug, info, warn, error) with a consistent
+ * "[Navieo]" prefix. Log level can be controlled at runtime via
+ * `Logger.setLevel()` or by setting `window.__NAVIEO_LOG_LEVEL__`.
+ *
+ * Levels (from most to least verbose):
+ *   debug → info → warn → error → silent
+ *
+ * Default level: "info" in development, "warn" in production.
+ */
+type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
+declare class NavieoLogger {
+    private level;
+    /** Change the active log level at runtime. */
+    setLevel(level: LogLevel): void;
+    getLevel(): LogLevel;
+    private shouldLog;
+    /** Verbose diagnostic info — only shown at "debug" level. */
+    debug(message: string, ...args: unknown[]): void;
+    /** Standard operational info — shown at "info" level and above. */
+    info(message: string, ...args: unknown[]): void;
+    /** Warnings — shown at "warn" level and above. */
+    warn(message: string, ...args: unknown[]): void;
+    /** Errors — always shown unless "silent". */
+    error(message: string, ...args: unknown[]): void;
+    /**
+     * Log a structured diagnostic table for tour steps.
+     * Only shown at "debug" level.
+     */
+    debugSteps(label: string, steps: Array<Record<string, unknown>>): void;
+}
+/** Singleton logger instance used throughout the SDK. */
+declare const logger: NavieoLogger;
+
+export { type ChatMessage, ChatWidget, type LogLevel, type NavieoContextValue, NavieoProvider, type NavieoProviderProps, type Sitemap, type TourRendererOptions, type TourState, logger, useNavieo, useTourRenderer };