@usereq/widget 0.1.0

package/src/chat-widget/components/chat-widget-primitives.tsx

@@ -0,0 +1,720 @@
+"use client";
+
+import * as React from "react";
+import { motion } from "motion/react";
+import { cn } from "@usereq/ui/lib/utils";
+import {
+  Avatar,
+  AvatarFallback,
+  AvatarImage,
+} from "@usereq/ui/components/avatar";
+import { Button } from "@usereq/ui/components/button";
+import { Textarea } from "@usereq/ui/components/textarea";
+import { Separator } from "@usereq/ui/components/separator";
+import {
+  ArrowUpRight,
+  MessageCircleX,
+  Minimize2,
+  MessageSquareText,
+  SendIcon,
+  Square,
+} from "lucide-react";
+import { Dialog, DialogContent, DialogTitle } from "@usereq/ui/components/dialog";
+import {
+  DEFAULT_COMPOSER_PLACEHOLDER,
+  DEFAULT_EMPTY_DESCRIPTION,
+  DEFAULT_EMPTY_TITLE,
+} from "../chat-widget-defaults";
+import {
+  getChatWidgetAvatarStyle,
+  getChatWidgetGradientStyle,
+  type ChatWidgetAppearance,
+} from "../chat-widget-appearance";
+import {
+  Conversation,
+  ConversationContent,
+  ConversationEmptyState,
+  ConversationScrollButton,
+} from "./conversation";
+import { foldStopConfirmationMessages } from "../stop-confirmation";
+import { getChatWidgetMessagesLayoutClasses } from "./chat-widget-layout";
+import { Message, MessageContent, MessageResponse } from "./message";
+
+const panelTransition = {
+  type: "spring" as const,
+  stiffness: 400,
+  damping: 35,
+};
+const CHAT_WIDGET_FULLSCREEN_BREAKPOINT = 1024;
+
+export type ChatWidgetMessageAction = {
+  label: string;
+  onClick: () => void;
+  variant?: "default" | "destructive" | "outline" | "ghost";
+};
+
+export type ChatWidgetPreviewMessage = {
+  id: string;
+  role: "assistant" | "user";
+  content: string;
+  /** Inline action buttons rendered below the bubble (e.g. for stop-conversation confirmation). */
+  actions?: ChatWidgetMessageAction[];
+};
+
+/** Shared data props for all chat widgets — pass from parent / fetch from DB */
+export type ChatWidgetDataProps = {
+  /** Agent or widget title (header name) */
+  agentName?: string;
+  /** Agent avatar URL */
+  agentAvatarUrl?: string | null;
+  /** Shared visual appearance knobs used by both dashboard preview and public embed. */
+  appearance?: ChatWidgetAppearance;
+  /** Current runtime status for the widget shell. */
+  status?: "idle" | "booting" | "ready" | "sending" | "error";
+  /** Static welcome line (e.g. from DB). */
+  welcomeMessage?: string | null;
+  /** Rotation of greeting strings used by closed-state spotlight surfaces. */
+  spotlightMessages?: string[];
+  /** Quick-reply suggestions shown when the widget is open and empty. */
+  suggestions?: string[];
+  /** Chat messages (conversation history) */
+  messages?: ChatWidgetPreviewMessage[];
+  /** Footer "Powered by" text */
+  poweredBy?: string;
+  /** Header status line (e.g. "Online") */
+  headerStatus?: string;
+  /** Custom error message shown in the empty state when widget bootstrap fails. */
+  errorMessage?: string | null;
+  /** When provided, composer is controlled and sends messages (for test chatting). */
+  onSendMessage?: (content: string) => void;
+  /** When true, show typing indicator (pending / data fetching). */
+  isTyping?: boolean;
+  /** Disable composer interaction while the widget is booting or sending. */
+  sendDisabled?: boolean;
+  /** When provided, show stop-conversation icon in panel header (e.g. playground reset). */
+  onStopConversation?: () => void;
+  /** When true, disables the stop-conversation control. */
+  stopDisabled?: boolean;
+  /** Called when a stop-confirmation card receives Yes/No. */
+  onConfirmationDecision?: (
+    confirmationId: string,
+    accepted: boolean,
+  ) => void | Promise<void>;
+  /** When provided, clicking a suggestion calls back with its text. */
+  onSuggestion?: (value: string) => void;
+  /** When provided and messages are empty, show this action in the empty state (e.g. "Start conversation"). */
+  emptyAction?: { label: string; onClick: () => void; disabled?: boolean };
+  /** Called when a link inside an assistant message is clicked. */
+  onLinkClick?: (linkUrl: string) => void;
+  /** Called when the launcher or closed-state open action is clicked. */
+  onLauncherClick?: () => void;
+};
+
+const TYPING_SPEED_MS = 40;
+const PAUSE_AFTER_MESSAGE_MS = 2000;
+
+/** Returns currently displayed text for typing effect; rotates through messages. */
+export function useSpotlightTyping(
+  messages: string[],
+  options?: { typingSpeedMs?: number; pauseAfterMs?: number },
+) {
+  const typingSpeed = options?.typingSpeedMs ?? TYPING_SPEED_MS;
+  const pauseAfter = options?.pauseAfterMs ?? PAUSE_AFTER_MESSAGE_MS;
+  const messagesKey = messages.join("\u0000");
+  const [messageIndex, setMessageIndex] = React.useState(0);
+  const [charIndex, setCharIndex] = React.useState(() =>
+    messages.length > 0 ? 1 : 0,
+  );
+  const [phase, setPhase] = React.useState<"typing" | "paused">("typing");
+
+  const currentMessage =
+    messages.length > 0 ? messages[messageIndex % messages.length]! : "";
+  const displayText = currentMessage.slice(0, charIndex);
+
+  React.useEffect(() => {
+    if (messages.length === 0) {
+      setMessageIndex(0);
+      setCharIndex(0);
+      setPhase("typing");
+      return;
+    }
+
+    setMessageIndex(0);
+    setCharIndex(1);
+    setPhase("typing");
+  }, [messagesKey, messages.length]);
+
+  React.useEffect(() => {
+    if (messages.length === 0) return;
+
+    if (phase === "paused") {
+      const t = setTimeout(() => {
+        setMessageIndex((i) => (i + 1) % messages.length);
+        setCharIndex(1);
+        setPhase("typing");
+      }, pauseAfter);
+      return () => clearTimeout(t);
+    }
+
+    if (charIndex < currentMessage.length) {
+      const t = setTimeout(() => setCharIndex((c) => c + 1), typingSpeed);
+      return () => clearTimeout(t);
+    }
+
+    setPhase("paused");
+    return undefined;
+  }, [
+    messages.length,
+    messageIndex,
+    charIndex,
+    currentMessage.length,
+    phase,
+    typingSpeed,
+    pauseAfter,
+  ]);
+
+  return displayText;
+}
+
+/**
+ * Keeps the last non-empty spotlight list stable across transient empty renders.
+ * This keeps closed-state spotlight copy stable when the configured spotlight
+ * array is momentarily cleared during rerenders.
+ */
+export function useStableSpotlightMessages(messages: string[]) {
+  const lastNonEmptyMessagesRef = React.useRef<string[] | null>(null);
+
+  React.useEffect(() => {
+    if (messages.length > 0) {
+      lastNonEmptyMessagesRef.current = messages;
+    }
+  }, [messages]);
+
+  return messages.length > 0
+    ? messages
+    : lastNonEmptyMessagesRef.current ?? [];
+}
+
+/** Rotating spotlight index for fade (Bubble). */
+export function useSpotlightFade(messages: string[], intervalMs = 3000) {
+  const [index, setIndex] = React.useState(0);
+  React.useEffect(() => {
+    if (messages.length <= 1) return;
+    const id = setInterval(() => {
+      setIndex((i) => (i + 1) % messages.length);
+    }, intervalMs);
+    return () => clearInterval(id);
+  }, [messages.length, intervalMs]);
+  return messages.length > 0 ? messages[index % messages.length]! : "";
+}
+
+export function ChatWidgetHeader({
+  agentName = "Assistant",
+  agentAvatarUrl,
+  appearance,
+  statusText = "Online",
+  className,
+  onStopConversation,
+  stopDisabled = false,
+  onClose,
+}: {
+  agentName?: string;
+  agentAvatarUrl?: string | null;
+  appearance?: ChatWidgetAppearance;
+  statusText?: string;
+  className?: string;
+  /** When set, shows a stop-conversation icon button. */
+  onStopConversation?: () => void;
+  /** When true, disables the stop-conversation button. */
+  stopDisabled?: boolean;
+  /** When set, shows a close/collapse icon button. */
+  onClose?: () => void;
+}) {
+  const hasActions = onStopConversation != null || onClose != null;
+  return (
+    <div className={cn("flex items-center gap-2 w-full", className)}>
+      <div className="flex min-w-0 flex-1 items-center gap-3">
+        <Avatar
+          size="lg"
+          style={
+            agentAvatarUrl ? undefined : getChatWidgetAvatarStyle(appearance)
+          }
+        >
+          {agentAvatarUrl ? (
+            <AvatarImage src={agentAvatarUrl} alt={agentName} />
+          ) : null}
+          <AvatarFallback
+            className={cn(appearance ? "bg-transparent text-white" : undefined)}
+          >
+            {agentName.slice(0, 2).toUpperCase()}
+          </AvatarFallback>
+        </Avatar>
+        <div className="min-w-0">
+          <div className="truncate text-sm font-semibold">{agentName}</div>
+          <div className="text-xs text-muted-foreground">{statusText}</div>
+        </div>
+      </div>
+      {hasActions && (
+        <div className="ml-auto flex shrink-0 items-center gap-1">
+          {onStopConversation != null && (
+            <Button
+              variant="ghost"
+              size="icon"
+              aria-label="Stop conversation"
+              title="Stop conversation"
+              disabled={stopDisabled}
+              onClick={onStopConversation}
+            >
+              <MessageCircleX />
+            </Button>
+          )}
+          {onClose != null && (
+            <Button
+              variant="ghost"
+              size="icon"
+              aria-label="Close"
+              title="Close"
+              onClick={onClose}
+            >
+              <Minimize2 />
+            </Button>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+/** Animated typing indicator (bouncing dots) for assistant "thinking" state. */
+export function ChatWidgetTyping({ className }: { className?: string }) {
+  return (
+    <div className="w-full flex">
+      <div
+        className={cn(
+          "max-w-[85%] rounded-2xl px-3 py-2 text-sm leading-relaxed",
+          "bg-muted text-foreground",
+          className,
+        )}
+      >
+        <div className="flex items-center gap-1 py-0.5" aria-label="Thinking">
+          {[0, 1, 2].map((i) => (
+            <motion.span
+              key={i}
+              className="size-1.5 rounded-full bg-current opacity-60"
+              animate={{ y: [0, -4, 0] }}
+              transition={{
+                duration: 0.5,
+                repeat: Infinity,
+                delay: i * 0.12,
+                ease: "easeInOut",
+              }}
+            />
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+/** Message list with sticky-bottom behavior and optional empty action. */
+export function ChatWidgetMessages({
+  messages,
+  isTyping = false,
+  status = "idle",
+  errorMessage,
+  appearance,
+  onConfirmationDecision,
+  onLinkClick,
+  className,
+  emptyTitle = DEFAULT_EMPTY_TITLE,
+  emptyDescription = DEFAULT_EMPTY_DESCRIPTION,
+  emptyAction,
+}: {
+  messages: ChatWidgetPreviewMessage[];
+  /** When true, show typing indicator (pending / data fetching). */
+  isTyping?: boolean;
+  status?: ChatWidgetDataProps["status"];
+  suggestions?: string[];
+  errorMessage?: string | null;
+  appearance?: ChatWidgetAppearance;
+  onSuggestion?: (value: string) => void;
+  className?: string;
+  emptyTitle?: string;
+  emptyDescription?: string;
+  /** When provided and messages empty, show this button in the empty state. */
+  emptyAction?: { label: string; onClick: () => void; disabled?: boolean };
+  onConfirmationDecision?: (
+    confirmationId: string,
+    accepted: boolean,
+  ) => void | Promise<void>;
+  onLinkClick?: (linkUrl: string) => void;
+}) {
+  const { scrollClassName, contentClassName } =
+    getChatWidgetMessagesLayoutClasses();
+  const renderedMessages = React.useMemo(
+    () => foldStopConfirmationMessages(messages),
+    [messages],
+  );
+
+  return (
+    <Conversation className={cn("relative size-full", className)}>
+      <ConversationContent
+        scrollClassName={scrollClassName}
+        className={contentClassName}
+      >
+        {messages.length === 0 && !isTyping ? (
+          status === "error" ? (
+            <div className="state error">
+              {errorMessage ?? "Something went wrong."}
+            </div>
+          ) : (
+            <div className="flex min-h-full flex-1 items-center justify-center px-4 py-6">
+              <ConversationEmptyState className="w-full max-w-[280px]">
+                <div className="flex size-16 items-center justify-center rounded-2xl border border-border/70 bg-background/90 shadow-sm">
+                  <MessageSquareText className="size-7 text-foreground" />
+                </div>
+                <div>
+                  <p className="text-lg font-semibold leading-tight text-foreground">
+                    {emptyTitle}
+                  </p>
+                  <p className="mt-2 text-sm text-muted-foreground">
+                    {emptyDescription}
+                  </p>
+                </div>
+                {emptyAction && (
+                  <Button
+                    size="lg"
+                    disabled={emptyAction.disabled}
+                    onClick={emptyAction.onClick}
+                    className="rounded-full bg-black px-6 text-white hover:bg-black/90"
+                  >
+                    {emptyAction.label}
+                  </Button>
+                )}
+              </ConversationEmptyState>
+            </div>
+          )
+        ) : (
+          <>
+            {renderedMessages.map((item) => {
+              if (item.type === "confirmation") {
+                return (
+                  <Message key={item.message.id} from="assistant">
+                    <div className="flex w-fit max-w-[85%] shrink-0 flex-col gap-2">
+                      <MessageResponse
+                        confirmation={item.latestEnvelope}
+                        confirmationPrompt={item.envelope.prompt}
+                        confirmationActionsDisabled={status === "sending"}
+                        onConfirmationDecision={onConfirmationDecision}
+                      />
+                    </div>
+                  </Message>
+                );
+              }
+
+              const m = item.message;
+              return (
+                <Message key={m.id} from={m.role}>
+                  <div className="flex w-fit max-w-[85%] shrink-0 flex-col gap-2">
+                    <MessageContent
+                      className={cn(
+                        "whitespace-pre-wrap",
+                        m.role === "user"
+                          ? "text-white"
+                          : "bg-muted text-foreground",
+                      )}
+                      style={
+                        m.role === "user"
+                          ? getChatWidgetGradientStyle(appearance)
+                          : undefined
+                      }
+                    >
+                      {m.role === "assistant" ? (
+                        <MessageResponse onLinkClick={onLinkClick}>
+                          {m.content}
+                        </MessageResponse>
+                      ) : (
+                        m.content
+                      )}
+                    </MessageContent>
+                    {m.actions && m.actions.length > 0 && (
+                      <div className="flex flex-wrap gap-2 px-1">
+                        {m.actions.map((action, i) => (
+                          <Button
+                            key={i}
+                            size="sm"
+                            variant={action.variant ?? "outline"}
+                            onClick={action.onClick}
+                          >
+                            {action.label}
+                          </Button>
+                        ))}
+                      </div>
+                    )}
+                  </div>
+                </Message>
+              );
+            })}
+            {isTyping && (
+              <motion.div
+                initial={{ opacity: 0, y: 8 }}
+                animate={{ opacity: 1, y: 0 }}
+                transition={{ duration: 0.2, ease: "easeOut" }}
+                className="w-full"
+              >
+                <ChatWidgetTyping />
+              </motion.div>
+            )}
+          </>
+        )}
+      </ConversationContent>
+      <ConversationScrollButton />
+    </Conversation>
+  );
+}
+
+const COMPOSER_MIN_ROWS = 2;
+
+export function ChatWidgetComposer({
+  placeholder = DEFAULT_COMPOSER_PLACEHOLDER,
+  value,
+  onChange,
+  onSubmit,
+  appearance,
+  disabled = false,
+  className,
+}: {
+  placeholder?: string;
+  /** Controlled value (use with onChange + onSubmit for test chatting). */
+  value?: string;
+  onChange?: (value: string) => void;
+  /** Called on Send click or Enter (without Shift). Clears input after submit when controlled. */
+  onSubmit?: (value: string) => void;
+  appearance?: ChatWidgetAppearance;
+  disabled?: boolean;
+  className?: string;
+}) {
+  const isControlled = value !== undefined && onChange !== undefined;
+  const [localValue, setLocalValue] = React.useState("");
+  const currentValue = isControlled ? value : localValue;
+  const textareaRef = React.useRef<HTMLTextAreaElement>(null);
+
+  const handleChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
+    const v = e.target.value;
+    if (isControlled) onChange(v);
+    else setLocalValue(v);
+  };
+
+  const submit = () => {
+    const trimmed = currentValue.trim();
+    if (!trimmed || !onSubmit) return;
+    onSubmit(trimmed);
+    if (isControlled && onChange) onChange("");
+    else setLocalValue("");
+    textareaRef.current?.focus();
+  };
+
+  const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+    if (e.key !== "Enter") return;
+    if (e.shiftKey) return; // Shift+Enter = new line
+    e.preventDefault();
+    submit();
+  };
+
+  return (
+    <div className={cn("flex items-end gap-2", className)}>
+      <Textarea
+        ref={textareaRef}
+        placeholder={placeholder}
+        value={currentValue}
+        onChange={handleChange}
+        onKeyDown={handleKeyDown}
+        rows={COMPOSER_MIN_ROWS}
+        disabled={disabled}
+        className={cn(
+          "min-h-10 max-h-32 flex-1 resize-none py-2.5",
+          "focus-visible:ring-2",
+        )}
+      />
+      <Button
+        type="button"
+        size="icon"
+        className="h-10 w-10 shrink-0 text-white"
+        style={getChatWidgetGradientStyle(appearance)}
+        aria-label="Send"
+        disabled={disabled || !onSubmit}
+        onClick={submit}
+      >
+        <SendIcon className="size-4" />
+      </Button>
+    </div>
+  );
+}
+
+export function ChatWidgetPoweredBy({
+  text = "Powered by UserEQ",
+  className,
+}: {
+  text?: string;
+  className?: string;
+}) {
+  return (
+    <div className={cn("text-center text-xs text-muted-foreground", className)}>
+      {text}
+    </div>
+  );
+}
+
+export function ChatWidgetSectionDivider({
+  className,
+}: {
+  className?: string;
+}) {
+  return <Separator className={cn("my-3", className)} />;
+}
+
+/**
+ * Wraps panel content: Dialog (full-screen) on mobile when open, floating panel on desktop.
+ */
+export function ChatWidgetPanel({
+  open,
+  onOpenChange,
+  children,
+  desktopClassName,
+  desktopStyle,
+  portalContainer,
+}: {
+  open: boolean;
+  onOpenChange?: (open: boolean) => void;
+  children: React.ReactNode;
+  desktopClassName?: string;
+  desktopStyle?: React.CSSProperties;
+  portalContainer?: HTMLElement | DocumentFragment | null;
+}) {
+  const isMobile = useIsChatWidgetFullscreenViewport();
+  const lockedFullscreenHeight = useLockedFullscreenViewportHeight(
+    open,
+    isMobile,
+  );
+
+  if (isMobile) {
+    return (
+      <Dialog open={open} onOpenChange={onOpenChange}>
+        <DialogContent
+          showCloseButton={false}
+          aria-describedby={undefined}
+          style={
+            {
+              "--chat-widget-fullscreen-height":
+                lockedFullscreenHeight != null
+                  ? `${lockedFullscreenHeight}px`
+                  : "100svh",
+            } as React.CSSProperties
+          }
+          className={cn(
+            "z-50 flex fixed! inset-0! h-(--chat-widget-fullscreen-height)! max-h-(--chat-widget-fullscreen-height)! w-screen! max-w-none translate-x-0! translate-y-0! flex-col gap-0 rounded-none border-0 p-0 shadow-lg",
+            "data-[state=open]:zoom-in-100 data-[state=closed]:zoom-out-100",
+          )}
+        >
+          <DialogTitle className="sr-only">Chat</DialogTitle>
+          {children}
+        </DialogContent>
+      </Dialog>
+    );
+  }
+
+  return (
+    <motion.div
+      className={cn(desktopClassName, "z-10 flex h-112.5 flex-col")}
+      style={
+        {
+          ...desktopStyle,
+          pointerEvents: open ? "auto" : "none",
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        } as any
+      }
+      initial={false}
+      animate={{
+        opacity: open ? 1 : 0,
+        visibility: open ? "visible" : "hidden",
+        scale: open ? 1 : 0.96,
+      }}
+      transition={panelTransition}
+    >
+      {children}
+    </motion.div>
+  );
+}
+
+export function useIsChatWidgetFullscreenViewport() {
+  const [isFullscreenViewport, setIsFullscreenViewport] = React.useState(
+    () =>
+      typeof window !== "undefined" &&
+      window.innerWidth < CHAT_WIDGET_FULLSCREEN_BREAKPOINT,
+  );
+
+  React.useEffect(() => {
+    const mql = window.matchMedia(
+      `(max-width: ${CHAT_WIDGET_FULLSCREEN_BREAKPOINT - 1}px)`,
+    );
+    const onChange = () => {
+      setIsFullscreenViewport(
+        window.innerWidth < CHAT_WIDGET_FULLSCREEN_BREAKPOINT,
+      );
+    };
+
+    mql.addEventListener("change", onChange);
+    setIsFullscreenViewport(
+      window.innerWidth < CHAT_WIDGET_FULLSCREEN_BREAKPOINT,
+    );
+
+    return () => mql.removeEventListener("change", onChange);
+  }, []);
+
+  return isFullscreenViewport;
+}
+
+function useLockedFullscreenViewportHeight(active: boolean, enabled: boolean) {
+  const [lockedHeight, setLockedHeight] = React.useState<number | null>(null);
+
+  React.useEffect(() => {
+    if (!active || !enabled) {
+      setLockedHeight(null);
+      return;
+    }
+
+    const viewportHeight = window.visualViewport?.height ?? window.innerHeight;
+    setLockedHeight(Math.round(viewportHeight));
+  }, [active, enabled]);
+
+  return lockedHeight;
+}
+
+/** Bubble launcher button. */
+export function ChatWidgetLauncher({
+  open,
+  onToggle,
+  appearance,
+  className,
+}: {
+  open: boolean;
+  onToggle: () => void;
+  appearance?: ChatWidgetAppearance;
+  className?: string;
+}) {
+  return (
+    <Button
+      onClick={onToggle}
+      size="icon"
+      className={cn("h-12 w-12 rounded-full shadow-lg text-white", className)}
+      style={getChatWidgetGradientStyle(appearance)}
+      aria-label={open ? "Close chat" : "Open chat"}
+    >
+      {open ? (
+        <Square className="size-4" />
+      ) : (
+        <ArrowUpRight className="size-4" />
+      )}
+    </Button>
+  );
+}