@aichatbot-saas/react 0.1.0

package/src/AIChatbot.tsx

@@ -0,0 +1,248 @@
+import {
+  useCallback,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+  type CSSProperties,
+  type FormEvent,
+} from 'react';
+import type { ChatTheme } from '@aichatbot-saas/core';
+import { useChatController } from './useChatController';
+import { MessageBubble } from './components/MessageBubble';
+import { SuggestionChips } from './components/SuggestionChips';
+import { TypingIndicator } from './components/TypingIndicator';
+
+export interface AIChatbotProps {
+  /** Publishable API key (required). */
+  apiKey: string;
+  /** Backend base URL. Defaults to same-origin. */
+  apiUrl?: string;
+  /** Force a language; otherwise config.languages[0] -> "en". */
+  language?: string;
+  /** Local theme overrides (highest precedence: client -> backend -> default). */
+  theme?: Partial<ChatTheme>;
+  /** Stable device/session id forwarded to the backend for threading. */
+  sessionId?: string;
+  /** Extra class on the root panel. */
+  className?: string;
+  /** Extra inline styles merged onto the root panel (e.g. width/height). */
+  style?: CSSProperties;
+}
+
+/**
+ * `<AIChatbot>` — a native, inline, embeddable chat panel for the web.
+ *
+ * It fills its container, so the host controls size and placement (drop it into
+ * a sized `<div>`). All behavior (config load, greeting, suggestions, send flow,
+ * conversation persistence, feedback, error handling) lives in the shared
+ * headless controller; this component only renders that state and wires events.
+ *
+ * Styling is 100% inline and derived from the resolved theme — no global CSS, no
+ * external UI libs — so it never clobbers host styles and is SSR-safe.
+ *
+ * In Next.js / RSC, render it from a Client Component (add `"use client"`).
+ */
+export function AIChatbot({
+  apiKey,
+  apiUrl,
+  language,
+  theme,
+  sessionId,
+  className,
+  style,
+}: AIChatbotProps) {
+  const { state, controller } = useChatController({
+    apiKey,
+    apiUrl,
+    language,
+    theme,
+    sessionId,
+  });
+
+  const [draft, setDraft] = useState('');
+  const scrollRef = useRef<HTMLDivElement | null>(null);
+  const headingId = useId();
+
+  const t = state.theme;
+  const botName = state.config?.bot_name || 'Assistant';
+  const iconUrl = state.config?.bot_icon_url;
+
+  // Auto-scroll to the newest message whenever the list or typing state changes.
+  useEffect(() => {
+    const node = scrollRef.current;
+    if (node) node.scrollTop = node.scrollHeight;
+  }, [state.messages, state.isTyping]);
+
+  const handleSubmit = useCallback(
+    (e: FormEvent) => {
+      e.preventDefault();
+      const value = draft;
+      setDraft('');
+      void controller.send(value);
+    },
+    [controller, draft]
+  );
+
+  const handleSuggestion = useCallback(
+    (text: string) => {
+      void controller.sendSuggestion(text);
+    },
+    [controller]
+  );
+
+  // ---- styles (all derived from theme) ----------------------------------
+  const panelStyle: CSSProperties = {
+    display: 'flex',
+    flexDirection: 'column',
+    width: '100%',
+    height: '100%',
+    minHeight: 0,
+    boxSizing: 'border-box',
+    background: t.backgroundColor,
+    color: t.botBubbleTextColor,
+    fontFamily: t.fontFamily,
+    fontSize: 14,
+    overflow: 'hidden',
+    ...style,
+  };
+
+  const headerStyle: CSSProperties = {
+    background: t.primaryColor,
+    color: t.onPrimaryColor,
+    padding: '14px 16px',
+    fontWeight: 600,
+    display: 'flex',
+    alignItems: 'center',
+    gap: 10,
+    flex: '0 0 auto',
+  };
+
+  const avatarStyle: CSSProperties = {
+    width: 28,
+    height: 28,
+    borderRadius: '50%',
+    objectFit: 'cover',
+    flex: '0 0 auto',
+    background: 'rgba(255,255,255,0.2)',
+  };
+
+  const bodyStyle: CSSProperties = {
+    flex: '1 1 auto',
+    minHeight: 0,
+    overflowY: 'auto',
+    padding: 14,
+    background: t.surfaceColor,
+  };
+
+  const footerStyle: CSSProperties = {
+    display: 'flex',
+    gap: 6,
+    borderTop: `1px solid ${t.botBubbleBorderColor}`,
+    padding: 8,
+    background: t.backgroundColor,
+    flex: '0 0 auto',
+  };
+
+  const inputStyle: CSSProperties = {
+    flex: 1,
+    minWidth: 0,
+    border: `1px solid ${t.botBubbleBorderColor}`,
+    borderRadius: t.inputRadius,
+    padding: '9px 14px',
+    fontSize: 14,
+    fontFamily: 'inherit',
+    outline: 'none',
+    color: t.botBubbleTextColor,
+    background: t.backgroundColor,
+  };
+
+  const sendDisabled = state.sending || state.status !== 'ready' || draft.trim().length === 0;
+
+  const sendStyle: CSSProperties = {
+    background: t.primaryColor,
+    color: t.onPrimaryColor,
+    border: 'none',
+    borderRadius: t.inputRadius,
+    padding: '0 16px',
+    cursor: sendDisabled ? 'default' : 'pointer',
+    opacity: sendDisabled ? 0.6 : 1,
+    fontSize: 14,
+    fontFamily: 'inherit',
+    flex: '0 0 auto',
+  };
+
+  return (
+    <div
+      className={className}
+      style={panelStyle}
+      role="region"
+      aria-label={`${botName} chat`}
+      aria-labelledby={headingId}
+    >
+      <header style={headerStyle}>
+        {iconUrl ? <img src={iconUrl} alt="" style={avatarStyle} /> : null}
+        <span id={headingId}>{botName}</span>
+      </header>
+
+      <div style={bodyStyle} ref={scrollRef}>
+        {state.status === 'loading' && state.messages.length === 0 ? (
+          <div style={{ color: t.mutedTextColor, fontSize: 13, padding: 4 }}>Loading…</div>
+        ) : null}
+
+        {state.messages.map((message) => (
+          <MessageBubble
+            key={message.id}
+            message={message}
+            theme={t}
+            onFeedback={controller.submitFeedback.bind(controller)}
+          />
+        ))}
+
+        {state.isTyping ? <TypingIndicator theme={t} botName={botName} /> : null}
+
+        {state.status === 'error' ? (
+          <div
+            role="alert"
+            style={{
+              background: t.botBubbleColor,
+              color: t.botBubbleTextColor,
+              border: `1px solid ${t.botBubbleBorderColor}`,
+              borderRadius: t.bubbleRadius,
+              padding: '9px 13px',
+              fontSize: 14,
+              margin: '8px 0',
+            }}
+          >
+            {state.error || 'Sorry, something went wrong loading the chat.'}
+          </div>
+        ) : null}
+
+        <SuggestionChips
+          suggestions={state.suggestions}
+          theme={t}
+          disabled={state.sending}
+          onSelect={handleSuggestion}
+        />
+      </div>
+
+      <form style={footerStyle} onSubmit={handleSubmit}>
+        <input
+          style={inputStyle}
+          type="text"
+          value={draft}
+          maxLength={4000}
+          placeholder="Type your message…"
+          aria-label="Message"
+          onChange={(e) => setDraft(e.target.value)}
+          disabled={state.status === 'error'}
+        />
+        <button type="submit" style={sendStyle} disabled={sendDisabled}>
+          Send
+        </button>
+      </form>
+    </div>
+  );
+}
+
+export default AIChatbot;

package/src/components/MessageBubble.tsx

@@ -0,0 +1,107 @@
+import type { CSSProperties } from 'react';
+import type { ChatMessage, ChatTheme, FeedbackValue } from '@aichatbot-saas/core';
+
+export interface MessageBubbleProps {
+  message: ChatMessage;
+  theme: ChatTheme;
+  /**
+   * Called when the user rates this (bot) message. Only rendered for bot
+   * messages that carry a `serverId` (i.e. not the greeting and not error
+   * bubbles).
+   */
+  onFeedback?: (message: ChatMessage, value: FeedbackValue) => void;
+}
+
+/**
+ * A single chat bubble. User messages align right with the primary color; bot
+ * messages align left with a bordered white surface. Bot messages eligible for
+ * feedback render thumbs up/down beneath the bubble (replaced by "Thanks!" once
+ * rated). All styling is inline and derived from the theme.
+ */
+export function MessageBubble({ message, theme, onFeedback }: MessageBubbleProps) {
+  const isUser = message.role === 'user';
+  const canRate = !isUser && !!message.serverId && !message.error;
+
+  const rowStyle: CSSProperties = {
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: isUser ? 'flex-end' : 'flex-start',
+    margin: '8px 0',
+  };
+
+  const bubbleStyle: CSSProperties = {
+    maxWidth: '80%',
+    padding: '9px 13px',
+    borderRadius: theme.bubbleRadius,
+    fontSize: 14,
+    lineHeight: 1.45,
+    whiteSpace: 'pre-wrap',
+    wordWrap: 'break-word',
+    overflowWrap: 'anywhere',
+    ...(isUser
+      ? {
+          background: theme.userBubbleColor,
+          color: theme.userBubbleTextColor,
+          borderBottomRightRadius: 4,
+        }
+      : {
+          background: theme.botBubbleColor,
+          color: theme.botBubbleTextColor,
+          border: `1px solid ${theme.botBubbleBorderColor}`,
+          borderBottomLeftRadius: 4,
+        }),
+  };
+
+  return (
+    <div style={rowStyle}>
+      <div style={bubbleStyle}>{message.text}</div>
+      {canRate &&
+        (message.feedback ? (
+          <div style={{ marginTop: 4, fontSize: 13, color: theme.mutedTextColor }}>Thanks!</div>
+        ) : (
+          <FeedbackButtons message={message} theme={theme} onFeedback={onFeedback} />
+        ))}
+    </div>
+  );
+}
+
+interface FeedbackButtonsProps {
+  message: ChatMessage;
+  theme: ChatTheme;
+  onFeedback?: (message: ChatMessage, value: FeedbackValue) => void;
+}
+
+function FeedbackButtons({ message, theme, onFeedback }: FeedbackButtonsProps) {
+  const btnStyle: CSSProperties = {
+    background: 'none',
+    border: 'none',
+    cursor: 'pointer',
+    fontSize: 14,
+    padding: '0 2px',
+    color: theme.mutedTextColor,
+    opacity: 0.7,
+    lineHeight: 1,
+  };
+  return (
+    <div style={{ marginTop: 4, display: 'flex', gap: 2 }}>
+      <button
+        type="button"
+        title="Helpful"
+        aria-label="Helpful"
+        style={btnStyle}
+        onClick={() => onFeedback?.(message, 'positive')}
+      >
+        👍
+      </button>
+      <button
+        type="button"
+        title="Not helpful"
+        aria-label="Not helpful"
+        style={btnStyle}
+        onClick={() => onFeedback?.(message, 'negative')}
+      >
+        👎
+      </button>
+    </div>
+  );
+}

package/src/components/SuggestionChips.tsx

@@ -0,0 +1,58 @@
+import type { CSSProperties } from 'react';
+import type { ChatTheme } from '@aichatbot-saas/core';
+
+export interface SuggestionChipsProps {
+  suggestions: string[];
+  theme: ChatTheme;
+  disabled?: boolean;
+  onSelect: (text: string) => void;
+}
+
+/**
+ * A wrapping row of tappable suggestion chips, themed from the primary color.
+ * Renders nothing when there are no suggestions.
+ */
+export function SuggestionChips({
+  suggestions,
+  theme,
+  disabled = false,
+  onSelect,
+}: SuggestionChipsProps) {
+  if (!suggestions.length) return null;
+
+  const rowStyle: CSSProperties = {
+    display: 'flex',
+    flexWrap: 'wrap',
+    gap: 6,
+    margin: '6px 0 2px',
+  };
+
+  const chipStyle: CSSProperties = {
+    background: theme.backgroundColor,
+    border: `1px solid ${theme.primaryColor}`,
+    color: theme.primaryColor,
+    borderRadius: 16,
+    padding: '6px 12px',
+    fontSize: 13,
+    cursor: disabled ? 'default' : 'pointer',
+    opacity: disabled ? 0.6 : 1,
+    fontFamily: 'inherit',
+    lineHeight: 1.2,
+  };
+
+  return (
+    <div style={rowStyle}>
+      {suggestions.map((label, i) => (
+        <button
+          key={`${i}-${label}`}
+          type="button"
+          style={chipStyle}
+          disabled={disabled}
+          onClick={() => onSelect(label)}
+        >
+          {label}
+        </button>
+      ))}
+    </div>
+  );
+}

package/src/components/TypingIndicator.tsx

@@ -0,0 +1,26 @@
+import type { CSSProperties } from 'react';
+import type { ChatTheme } from '@aichatbot-saas/core';
+
+export interface TypingIndicatorProps {
+  theme: ChatTheme;
+  /** Bot name to personalize the label, e.g. "Assistant is typing…". */
+  botName?: string;
+}
+
+/**
+ * The "<bot> is typing…" indicator shown while the controller is awaiting a
+ * reply. Themed via mutedTextColor.
+ */
+export function TypingIndicator({ theme, botName }: TypingIndicatorProps) {
+  const style: CSSProperties = {
+    fontSize: 13,
+    color: theme.mutedTextColor,
+    fontStyle: 'italic',
+    margin: '6px 2px',
+  };
+  return (
+    <div style={style} aria-live="polite">
+      {(botName || 'Assistant') + ' is typing…'}
+    </div>
+  );
+}

package/src/index.ts

@@ -0,0 +1,47 @@
+/**
+ * @aichatbot-saas/react — native in-page chat UI component for React (web).
+ *
+ * A thin, themeable binding over the framework-agnostic
+ * {@link https://npmjs.com/package/@aichatbot-saas/core | @aichatbot-saas/core}.
+ * Drop `<AIChatbot apiKey="..." apiUrl="..." />` into any sized container.
+ */
+
+export { AIChatbot, default } from './AIChatbot';
+export type { AIChatbotProps } from './AIChatbot';
+
+export { useChatController } from './useChatController';
+export type {
+  UseChatControllerOptions,
+  UseChatControllerResult,
+} from './useChatController';
+
+// Presentational building blocks (advanced/custom layouts).
+export { MessageBubble } from './components/MessageBubble';
+export type { MessageBubbleProps } from './components/MessageBubble';
+export { SuggestionChips } from './components/SuggestionChips';
+export type { SuggestionChipsProps } from './components/SuggestionChips';
+export { TypingIndicator } from './components/TypingIndicator';
+export type { TypingIndicatorProps } from './components/TypingIndicator';
+
+// Convenience re-exports from the core: the headless client/controller and the
+// key models, so consumers don't need to also depend on @aichatbot-saas/core.
+export {
+  AIChatbotClient,
+  ChatController,
+  createChatController,
+  resolveTheme,
+  DEFAULT_THEME,
+} from '@aichatbot-saas/core';
+export type {
+  ChatTheme,
+  ChatMessage,
+  ChatConfig,
+  ChatResponse,
+  Suggestion,
+  SuggestionInput,
+  FeedbackValue,
+  ChatRole,
+  ChatState,
+  ChatStatus,
+  ChatControllerOptions,
+} from '@aichatbot-saas/core';

package/src/useChatController.ts

@@ -0,0 +1,83 @@
+import { useEffect, useMemo, useRef, useSyncExternalStore } from 'react';
+import {
+  createChatController,
+  type ChatController,
+  type ChatState,
+  type ChatTheme,
+} from '@aichatbot-saas/core';
+
+/** Options accepted by {@link useChatController}. Mirrors ChatControllerOptions. */
+export interface UseChatControllerOptions {
+  apiKey: string;
+  apiUrl?: string;
+  language?: string;
+  theme?: Partial<ChatTheme>;
+  sessionId?: string;
+}
+
+export interface UseChatControllerResult {
+  state: ChatState;
+  controller: ChatController;
+}
+
+/**
+ * Creates and drives a headless {@link ChatController}, exposing its immutable
+ * state to React via `useSyncExternalStore` (React 18+, concurrent-safe).
+ *
+ * The controller is memoized on the identity-defining inputs (apiKey, apiUrl,
+ * language, serialized theme, sessionId); when any of those change a fresh
+ * controller is created, started, and the previous one is destroyed.
+ *
+ * SSR-safe: the controller is constructed lazily and never touches
+ * window/document during render. `start()` (which performs network/storage I/O)
+ * runs only inside an effect, so it never executes on the server.
+ */
+export function useChatController(
+  options: UseChatControllerOptions
+): UseChatControllerResult {
+  const { apiKey, apiUrl, language, theme, sessionId } = options;
+
+  // Stable serialization of the theme so object identity doesn't churn the memo.
+  const themeKey = useMemo(() => JSON.stringify(theme ?? {}), [theme]);
+
+  const controller = useMemo(
+    () =>
+      createChatController({
+        apiKey,
+        apiUrl,
+        language,
+        theme,
+        sessionId,
+      }),
+    // theme is captured via its serialized key; eslint can't see that.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [apiKey, apiUrl, language, themeKey, sessionId]
+  );
+
+  // Capture the controller's initial state once per controller instance so
+  // getServerSnapshot is referentially stable across renders (required to avoid
+  // infinite render loops in useSyncExternalStore on the server).
+  const serverSnapshotRef = useRef<{ controller: ChatController; state: ChatState } | null>(
+    null
+  );
+  if (serverSnapshotRef.current?.controller !== controller) {
+    serverSnapshotRef.current = { controller, state: controller.getState() };
+  }
+  const getServerSnapshot = (): ChatState => serverSnapshotRef.current!.state;
+
+  const state = useSyncExternalStore(
+    controller.subscribe,
+    controller.getState,
+    getServerSnapshot
+  );
+
+  // Start (client only) once per controller, and tear down on unmount / re-key.
+  useEffect(() => {
+    void controller.start();
+    return () => {
+      controller.destroy();
+    };
+  }, [controller]);
+
+  return { state, controller };
+}