@instockng/storefront-ui 1.0.106 → 1.0.108

package/src/components/AssistantDrawer.tsx

@@ -0,0 +1,426 @@
+'use client';
+
+/**
+ * AssistantDrawer Component
+ *
+ * Chat drawer for the AI shopping assistant.
+ * - Mobile: bottom sheet
+ * - Desktop: side drawer from the right
+ *
+ * Streams responses via SSE, renders ProductCards for recommendations,
+ * shows follow-up suggestion chips.
+ */
+
+import { useState, useEffect, useRef, useCallback } from 'react';
+import { createPortal } from 'react-dom';
+import { X, Send, Sparkles, Loader2 } from 'lucide-react';
+import { cn, formatCurrency } from '../lib/utils';
+import { useHideBodyOverflow } from '../hooks/useHideBodyOverflow';
+
+type ChatMessage = {
+  role: 'user' | 'assistant';
+  content: string;
+  products?: RecommendedProduct[];
+};
+
+type RecommendedProduct = {
+  slug: string;
+  name: string;
+  thumbnailUrl: string | null;
+  price: number;
+};
+
+export interface AssistantDrawerProps {
+  /** Controls drawer visibility */
+  isOpen: boolean;
+  /** Callback when drawer should close */
+  onClose: () => void;
+  /** API base URL */
+  apiUrl: string;
+  /** Brand slug for context */
+  brandSlug: string;
+  /** Product slug if opened from a product page */
+  productSlug?: string;
+  /** Initial question to send immediately when opened */
+  initialQuestion?: string;
+  /** Assistant display name */
+  assistantName?: string;
+  /** Custom class name */
+  className?: string;
+  /** Render inline instead of using a portal (useful for Storybook) */
+  disablePortal?: boolean;
+}
+
+export function AssistantDrawer({
+  isOpen,
+  onClose,
+  apiUrl,
+  brandSlug,
+  productSlug,
+  initialQuestion,
+  assistantName = 'AI Assistant',
+  className,
+  disablePortal = false,
+}: AssistantDrawerProps) {
+  const [messages, setMessages] = useState<ChatMessage[]>([]);
+  const [input, setInput] = useState('');
+  const [isStreaming, setIsStreaming] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [isAnimating, setIsAnimating] = useState(false);
+  const [shouldRender, setShouldRender] = useState(false);
+  const messagesEndRef = useRef<HTMLDivElement>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const initialQuestionSent = useRef(false);
+  const messagesRef = useRef<ChatMessage[]>([]);
+  messagesRef.current = messages;
+
+  useHideBodyOverflow(isOpen);
+
+  // --- Callbacks (defined before effects that use them) ---
+
+  const handleSSEEvent = useCallback((event: string, data: string) => {
+    if (event === 'token') {
+      setMessages((prev) => {
+        const updated = [...prev];
+        const last = updated[updated.length - 1];
+        if (last?.role === 'assistant') {
+          updated[updated.length - 1] = { ...last, content: last.content + data };
+        }
+        return updated;
+      });
+    } else if (event === 'done') {
+      try {
+        const parsed = JSON.parse(data);
+        setMessages((prev) => {
+          const updated = [...prev];
+          const last = updated[updated.length - 1];
+          if (last?.role === 'assistant') {
+            updated[updated.length - 1] = {
+              ...last,
+              content: parsed.answer || last.content,
+              products: parsed.products?.length > 0 ? parsed.products : undefined,
+            };
+          }
+          return updated;
+        });
+      } catch {
+        // Ignore parse errors
+      }
+    } else if (event === 'error') {
+      try {
+        const parsed = JSON.parse(data);
+        setError(parsed.message || 'An error occurred');
+      } catch {
+        setError('An error occurred');
+      }
+    }
+  }, []);
+
+  const sendMessageRef = useRef<(question: string) => Promise<void>>();
+  const sendMessage = useCallback(
+    async (question: string) => {
+      if (!question.trim()) return;
+
+      setError(null);
+      const userMessage: ChatMessage = { role: 'user', content: question };
+      const history = messagesRef.current.map((m) => ({
+        role: m.role,
+        content: m.content,
+      }));
+
+      setMessages((prev) => [...prev, userMessage]);
+      setInput('');
+      setIsStreaming(true);
+
+      // Add placeholder assistant message
+      setMessages((prev) => [...prev, { role: 'assistant', content: '' }]);
+
+      try {
+        const response = await fetch(`${apiUrl}/v1/assistant/ask`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            question,
+            brandSlug,
+            productSlug,
+            history,
+          }),
+        });
+
+        if (!response.ok) {
+          const err = await response.json().catch(() => ({}));
+          throw new Error(
+            (err as any)?.error?.message || `Request failed (${response.status})`
+          );
+        }
+
+        if (!response.body) throw new Error('No response body');
+
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        let currentEvent = '';
+
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+
+          buffer += decoder.decode(value, { stream: true });
+          const lines = buffer.split('\n');
+          buffer = lines.pop() || '';
+
+          for (const line of lines) {
+            if (line.trim() === '') {
+              currentEvent = '';
+              continue;
+            }
+            if (line.trimStart().startsWith('event:')) {
+              currentEvent = line.trimStart().slice(6).trim();
+            } else if (line.trimStart().startsWith('data:')) {
+              // Per SSE spec: strip only the single leading space after "data:"
+              const afterPrefix = line.trimStart().slice(5);
+              const data = afterPrefix.startsWith(' ') ? afterPrefix.slice(1) : afterPrefix;
+              handleSSEEvent(currentEvent || 'token', data);
+            }
+          }
+        }
+      } catch (err: any) {
+        setError(err.message || 'Something went wrong');
+        // Remove the empty assistant message
+        setMessages((prev) => {
+          const last = prev[prev.length - 1];
+          if (last?.role === 'assistant' && !last.content) {
+            return prev.slice(0, -1);
+          }
+          return prev;
+        });
+      } finally {
+        setIsStreaming(false);
+      }
+    },
+    [apiUrl, brandSlug, productSlug, handleSSEEvent]
+  );
+  sendMessageRef.current = sendMessage;
+
+  // --- Effects ---
+
+  // Animation handling
+  useEffect(() => {
+    if (isOpen) {
+      setShouldRender(true);
+      requestAnimationFrame(() => {
+        requestAnimationFrame(() => {
+          setIsAnimating(true);
+        });
+      });
+    } else {
+      setIsAnimating(false);
+      const timer = setTimeout(() => {
+        setShouldRender(false);
+        setMessages([]);
+        setInput('');
+        setError(null);
+        initialQuestionSent.current = false;
+      }, 300);
+      return () => clearTimeout(timer);
+    }
+  }, [isOpen]);
+
+  // Send initial question when opened
+  useEffect(() => {
+    if (isOpen && initialQuestion && !initialQuestionSent.current) {
+      initialQuestionSent.current = true;
+      if (initialQuestion.trim()) {
+        setTimeout(() => sendMessageRef.current?.(initialQuestion), 100);
+      } else {
+        setTimeout(() => inputRef.current?.focus(), 350);
+      }
+    }
+  }, [isOpen, initialQuestion]);
+
+  // Scroll to bottom on new messages
+  useEffect(() => {
+    messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' });
+  }, [messages]);
+
+  // ESC to close
+  useEffect(() => {
+    const handleEsc = (e: KeyboardEvent) => {
+      if (e.key === 'Escape' && isOpen) onClose();
+    };
+    if (isOpen) {
+      document.addEventListener('keydown', handleEsc);
+      return () => document.removeEventListener('keydown', handleEsc);
+    }
+  }, [isOpen, onClose]);
+
+  // --- Handlers ---
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    if (input.trim()) {
+      sendMessage(input.trim());
+    }
+  };
+
+  // --- Render ---
+
+  if (!shouldRender) return null;
+
+  const drawerContent = (
+    <div
+      className={cn(
+        'fixed inset-0 z-50 transition-opacity duration-300',
+        isAnimating ? 'opacity-100' : 'opacity-0'
+      )}
+    >
+      {/* Overlay */}
+      <div
+        className="absolute inset-0 bg-black/40 backdrop-blur-sm"
+        onClick={onClose}
+      />
+
+      {/* Drawer — bottom sheet on mobile, right drawer on desktop */}
+      <div
+        className={cn(
+          'absolute bg-white flex flex-col transition-transform duration-300 ease-out',
+          // Mobile: bottom sheet
+          'inset-x-0 bottom-0 top-[10vh] rounded-t-2xl',
+          // Desktop: right side drawer
+          'sm:inset-y-0 sm:right-0 sm:left-auto sm:w-[420px] sm:max-w-full sm:rounded-t-none sm:rounded-l-2xl',
+          // Animation
+          isAnimating
+            ? 'translate-y-0 sm:translate-x-0'
+            : 'translate-y-full sm:translate-y-0 sm:translate-x-full',
+          className
+        )}
+      >
+        {/* Header */}
+        <div className="flex items-center justify-between border-b border-gray-200 px-4 py-3 flex-shrink-0">
+          <div className="flex items-center gap-2">
+            <Sparkles className="h-5 w-5 text-orange-500" />
+            <span className="font-semibold text-gray-900">{assistantName}</span>
+            <span className="text-xs text-gray-400 bg-gray-100 rounded px-1.5 py-0.5">beta</span>
+          </div>
+          <button
+            type="button"
+            onClick={onClose}
+            className="p-2 text-gray-400 hover:text-gray-600 hover:bg-gray-100 rounded-lg transition-colors"
+            aria-label="Close"
+          >
+            <X className="h-5 w-5" />
+          </button>
+        </div>
+
+        {/* Messages */}
+        <div className="flex-1 overflow-y-auto p-4 space-y-4 min-h-0">
+          {messages.length === 0 && !isStreaming && (
+            <div className="text-center text-gray-400 text-sm py-8">
+              Ask me anything about our products!
+            </div>
+          )}
+
+          {messages.map((msg, i) => (
+            <div key={i}>
+              {msg.role === 'user' ? (
+                <div className="flex justify-end">
+                  <div className="bg-gray-800 text-white rounded-2xl rounded-br-sm px-4 py-2 max-w-[80%] text-sm">
+                    {msg.content}
+                  </div>
+                </div>
+              ) : (
+                <div className="space-y-3">
+                  {/* Text answer */}
+                  <div className="text-sm text-gray-800 leading-relaxed whitespace-pre-wrap">
+                    {msg.content}
+                    {isStreaming && i === messages.length - 1 && (
+                      <span className="inline-block w-1.5 h-4 bg-gray-400 animate-pulse ml-0.5 align-text-bottom" />
+                    )}
+                  </div>
+
+                  {/* Product cards */}
+                  {msg.products && msg.products.length > 0 && (
+                    <div className="space-y-2">
+                      {msg.products.map((product) => (
+                        <a
+                          key={product.slug}
+                          href={`/product/${product.slug}`}
+                          className="flex items-center gap-3 w-full rounded-xl border border-gray-200 p-2 hover:bg-gray-50 transition-colors text-left no-underline"
+                        >
+                          {product.thumbnailUrl ? (
+                            <img
+                              src={product.thumbnailUrl}
+                              alt={product.name}
+                              className="h-16 w-16 rounded-lg object-cover flex-shrink-0"
+                            />
+                          ) : (
+                            <div className="h-16 w-16 rounded-lg bg-gray-100 flex-shrink-0" />
+                          )}
+                          <div className="min-w-0">
+                            <p className="text-sm font-medium text-gray-900 line-clamp-2">
+                              {product.name}
+                            </p>
+                            <p className="text-sm font-semibold text-blue-600">
+                              {formatCurrency(product.price)}
+                            </p>
+                          </div>
+                        </a>
+                      ))}
+                    </div>
+                  )}
+                </div>
+              )}
+            </div>
+          ))}
+
+          {/* Error */}
+          {error && (
+            <div className="rounded-lg bg-red-50 border border-red-200 p-3 text-sm text-red-700">
+              {error}
+            </div>
+          )}
+
+          <div ref={messagesEndRef} />
+        </div>
+
+        {/* Input */}
+        <div className="border-t border-gray-200 p-3 flex-shrink-0">
+          <form onSubmit={handleSubmit} className="flex items-center gap-2">
+            <input
+              ref={inputRef}
+              type="text"
+              value={input}
+              onChange={(e) => setInput(e.target.value)}
+              placeholder={`Ask ${assistantName} a question`}
+              disabled={isStreaming}
+              className={cn(
+                'flex-1 rounded-full border border-gray-300 px-4 py-2.5 text-sm',
+                'focus:border-blue-400 focus:outline-none focus:ring-2 focus:ring-blue-400/30',
+                'disabled:opacity-50'
+              )}
+            />
+            <button
+              type="submit"
+              disabled={!input.trim() || isStreaming}
+              className={cn(
+                'flex h-10 w-10 items-center justify-center rounded-full',
+                'bg-gray-800 text-white',
+                'hover:bg-gray-700 transition-colors',
+                'disabled:opacity-40 disabled:cursor-not-allowed'
+              )}
+            >
+              {isStreaming ? (
+                <Loader2 className="h-4 w-4 animate-spin" />
+              ) : (
+                <Send className="h-4 w-4" />
+              )}
+            </button>
+          </form>
+        </div>
+      </div>
+    </div>
+  );
+
+  if (disablePortal) return drawerContent;
+  return createPortal(drawerContent, document.body);
+}

package/src/components/ProductAssistantChips.stories.tsx

@@ -0,0 +1,42 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { ProductAssistantChips } from './ProductAssistantChips';
+
+const meta = {
+  title: 'Components/ProductAssistantChips',
+  component: ProductAssistantChips,
+  parameters: {
+    layout: 'centered',
+  },
+  tags: ['autodocs'],
+} satisfies Meta<typeof ProductAssistantChips>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const mockFaqs = [
+  { question: 'Are these leggings stretchy?', answer: 'Yes, they are made with 4-way stretch fabric.' },
+  { question: 'Do they have pockets?', answer: 'Yes, two side pockets deep enough for a phone.' },
+  { question: 'Can they be worn during workouts?', answer: 'Absolutely, they are designed for high-intensity workouts.' },
+  { question: 'What sizes are available?', answer: 'Available in S, M, L, and XL.' },
+];
+
+export const Default: Story = {
+  args: {
+    faqs: mockFaqs,
+    onAsk: (question) => console.log('Asked:', question),
+  },
+};
+
+export const FewQuestions: Story = {
+  args: {
+    faqs: mockFaqs.slice(0, 2),
+    onAsk: (question) => console.log('Asked:', question),
+  },
+};
+
+export const NoFaqs: Story = {
+  args: {
+    faqs: [],
+    onAsk: (question) => console.log('Asked:', question),
+  },
+};

package/src/components/ProductAssistantChips.tsx

@@ -0,0 +1,64 @@
+'use client';
+
+/**
+ * ProductAssistantChips Component
+ *
+ * Displays FAQ-based question pills under a product image.
+ * Clicking a chip opens the AssistantDrawer with that question pre-sent.
+ */
+
+import { Sparkles } from 'lucide-react';
+import { cn } from '../lib/utils';
+
+export interface ProductAssistantChipsProps {
+  /** FAQ questions to display as chips */
+  faqs?: Array<{ question: string; answer: string }>;
+  /** Callback when a chip is clicked — should open the drawer with this question */
+  onAsk: (question: string) => void;
+  /** Custom class name */
+  className?: string;
+}
+
+export function ProductAssistantChips({
+  faqs = [],
+  onAsk,
+  className,
+}: ProductAssistantChipsProps) {
+  if (faqs.length === 0) return null;
+
+  return (
+    <div className={cn('space-y-2', className)}>
+      <div className="flex items-center gap-1.5 text-sm font-medium text-gray-700">
+        <Sparkles className="h-4 w-4 text-orange-500" />
+        Ask AI
+      </div>
+      <div className="flex flex-wrap gap-2">
+        {faqs.map((faq, i) => (
+          <button
+            key={i}
+            type="button"
+            onClick={() => onAsk(faq.question)}
+            className={cn(
+              'rounded-full border border-gray-200 bg-blue-50/60 px-3 py-1.5 text-sm text-gray-700',
+              'hover:bg-blue-100 hover:border-blue-200 transition-colors',
+              'active:scale-95'
+            )}
+          >
+            {faq.question}
+          </button>
+        ))}
+        <button
+          type="button"
+          onClick={() => onAsk('')}
+          className={cn(
+            'rounded-full border border-gray-300 bg-gray-800 px-3 py-1.5 text-sm text-white font-medium',
+            'hover:bg-gray-700 transition-colors',
+            'active:scale-95'
+          )}
+        >
+          Ask something else
+        </button>
+      </div>
+    </div>
+  );
+}

package/src/contexts/AssistantContext.tsx

@@ -0,0 +1,62 @@
+'use client';
+
+import { createContext, useContext, useState, useCallback, type ReactNode } from 'react';
+import { AssistantDrawer } from '../components/AssistantDrawer';
+
+type AssistantContextType = {
+  /** Open the assistant drawer with a question. Pass productSlug if on a product page. */
+  ask: (question: string, productSlug?: string) => void;
+  /** Close the assistant drawer */
+  close: () => void;
+  /** Whether the drawer is currently open */
+  isOpen: boolean;
+};
+
+const AssistantContext = createContext<AssistantContextType | null>(null);
+
+export function useAssistant() {
+  const ctx = useContext(AssistantContext);
+  if (!ctx) throw new Error('useAssistant must be used within StorefrontProvider');
+  return ctx;
+}
+
+export interface AssistantProviderProps {
+  children: ReactNode;
+  apiUrl: string;
+  brandSlug: string;
+  assistantName?: string;
+}
+
+export function AssistantProvider({
+  children,
+  apiUrl,
+  brandSlug,
+  assistantName,
+}: AssistantProviderProps) {
+  const [isOpen, setIsOpen] = useState(false);
+  const [question, setQuestion] = useState('');
+  const [productSlug, setProductSlug] = useState<string | undefined>();
+
+  const ask = useCallback((q: string, slug?: string) => {
+    setQuestion(q);
+    setProductSlug(slug);
+    setIsOpen(true);
+  }, []);
+
+  const close = useCallback(() => setIsOpen(false), []);
+
+  return (
+    <AssistantContext.Provider value={{ ask, close, isOpen }}>
+      {children}
+      <AssistantDrawer
+        isOpen={isOpen}
+        onClose={close}
+        apiUrl={apiUrl}
+        brandSlug={brandSlug}
+        productSlug={productSlug}
+        initialQuestion={question}
+        assistantName={assistantName}
+      />
+    </AssistantContext.Provider>
+  );
+}

package/src/index.ts

@@ -11,6 +11,9 @@ export type { StorefrontProviderProps } from './providers/StorefrontProvider';
 // Export cart context (use this instead of prop drilling)
 export { CartProvider, useCart } from './contexts/CartContext';
 
+// Export AI assistant context
+export { useAssistant } from './contexts/AssistantContext';
+
 // Export Meta Pixel tracking
 export { useMetaPixel, MetaPixelProvider } from './providers/MetaPixelProvider';
 export type { MetaPixelProviderProps, PurchaseItem } from './providers/MetaPixelProvider';
@@ -64,6 +67,14 @@ export type { DiscountCodeInputProps } from './components/DiscountCodeInput';
 export { Checkout } from './components/Checkout';
 export type { CheckoutProps, CheckoutFormData } from './components/Checkout';
 
+// AI Assistant components
+export { AssistantDrawer } from './components/AssistantDrawer';
+export type { AssistantDrawerProps } from './components/AssistantDrawer';
+
+export { ProductAssistantChips } from './components/ProductAssistantChips';
+export type { ProductAssistantChipsProps } from './components/ProductAssistantChips';
+
+
 // Export UI primitives (for customization)
 export { Button } from './components/ui/button';
 export { Card, CardContent, CardHeader, CardTitle, CardDescription, CardFooter } from './components/ui/card';

package/src/providers/StorefrontProvider.tsx

@@ -28,6 +28,7 @@
 import { ReactNode } from 'react';
 import { ApiClientProvider, useGetBrand } from '@instockng/api-client';
 import { CartProvider, CartProviderProps } from '../contexts/CartContext';
+import { AssistantProvider } from '../contexts/AssistantContext';
 import { MetaPixelProvider } from './MetaPixelProvider';
 import { TikTokPixelProvider } from './TikTokPixelProvider';
 
@@ -41,6 +42,8 @@ export interface StorefrontProviderProps {
   initialCartId?: string;
   /** Optional: Props to pass to the ShoppingCart component */
   shoppingCartProps?: CartProviderProps['shoppingCartProps'];
+  /** Optional: AI assistant display name */
+  assistantName?: string;
 }
 
 /**
@@ -51,7 +54,9 @@ function StorefrontProviderInner({
   brandSlug,
   initialCartId,
   shoppingCartProps,
-}: Omit<StorefrontProviderProps, 'apiUrl'>) {
+  assistantName,
+  apiUrl,
+}: Omit<StorefrontProviderProps, 'apiUrl'> & { apiUrl: string }) {
   const { data: brand } = useGetBrand(brandSlug);
 
   return (
@@ -62,7 +67,13 @@ function StorefrontProviderInner({
           initialCartId={initialCartId}
           shoppingCartProps={shoppingCartProps}
         >
-          {children}
+          <AssistantProvider
+            apiUrl={apiUrl}
+            brandSlug={brandSlug}
+            assistantName={assistantName}
+          >
+            {children}
+          </AssistantProvider>
         </CartProvider>
       </TikTokPixelProvider>
     </MetaPixelProvider>
@@ -83,9 +94,11 @@ export function StorefrontProvider({
   apiUrl,
   initialCartId,
   shoppingCartProps,
+  assistantName,
 }: StorefrontProviderProps) {
   // Storefront-ui doesn't use authenticated endpoints, so provide a no-op getAuthToken
   const getAuthToken = async () => '';
+  const resolvedApiUrl = apiUrl || 'https://oms-api.instock.ng';
 
   return (
     <ApiClientProvider getAuthToken={getAuthToken} {...(apiUrl && { baseURL: apiUrl })}>
@@ -93,6 +106,8 @@ export function StorefrontProvider({
         brandSlug={brandSlug}
         initialCartId={initialCartId}
         shoppingCartProps={shoppingCartProps}
+        assistantName={assistantName}
+        apiUrl={resolvedApiUrl}
       >
         {children}
       </StorefrontProviderInner>