Package detail

admesh-ui-sdk

GouniManikumar12293MIT0.16.6

Beautiful, modern React components for displaying AI-powered product recommendations with citation-based conversation ads, auto-triggered widgets, floating chat, conversational interfaces, persistent sidebar, and built-in tracking

admesh, ui, components, recommendations, tracking, react, typescript, tailwind, tailwindcss, ai, product-recommendations, modern-ui, design-system, cards, comparison-table, dark-mode, responsive, conversational, chat, ai-assistant, inline-ads, conversation-summary, sidebar, persistent-panel, recommendation-sidebar, side-panel, floating-chat, chat-widget, chat-interface, ai-chat, conversational-ui, auto-recommendations, ai-integration, chatgpt-plugin, claude-integration, auto-trigger, citation, citations, citation-based, academic-style, references, inline-citations, numbered-citations, bracketed-citations, superscript-citations, clickable-citations, product-citations

readme

AdMesh UI SDK

A comprehensive React + TypeScript component library for displaying AdMesh product recommendations across all ad unit formats with built-in tracking, theming, and accessibility support.

🌐 Live Sites

🎭 Interactive Storybook: https://storybook.useadmesh.com/ - Explore all components and ad formats
📚 Complete Documentation: https://docs.useadmesh.com/ - Full SDK documentation and guides
🚀 AdMesh Dashboard: https://useadmesh.com - Get your API keys and manage campaigns

🎨 Component Showcase: This repository contains the UI SDK components with an interactive Storybook for exploring all ad formats and components.

🚀 Features

Complete Ad Unit Library - All AdMesh ad formats in one unified SDK
Citation-Based Conversation Ads - Display recommendations as numbered references within text
Conversational Ad Units - Perfect for chat interfaces, AI assistants, and conversational experiences
Floating & Auto Widgets - Non-intrusive recommendation displays
Expandable Units - Rich, interactive product showcases
Built-in Tracking - Automatic click, view, and conversion tracking
Intelligent Layouts - Auto-selects optimal layout based on intent and data
Advanced Customization - Complete freedom over colors, icons, fonts, and styling
Theme System - Enhanced theming with presets, dark mode, and component overrides
TypeScript First - Full type safety and IntelliSense support
Framework Agnostic - React core, but designed for easy embedding
Responsive Design - Mobile-first responsive components
Accessibility - WCAG 2.1 AA compliant

📦 Installation

npm install admesh-ui-sdk

✨ Self-Contained Design

Zero configuration required! The AdMesh UI SDK is completely self-contained and works like Google Ads or any professional SDK:

✅ No Tailwind CSS setup needed - All styles are automatically injected
✅ No external CSS imports required - Works out of the box in any React app
✅ No build configuration changes - Just install and use
✅ Platform independent - Consistent appearance across all applications
✅ Zero dependencies - Only requires React and ReactDOM as peer dependencies

The SDK automatically injects all necessary styles when components are rendered, ensuring consistent appearance regardless of your application's CSS framework, Tailwind configuration, or styling approach.

🎯 Quick Start

AdMeshLayout Component (Recommended)

import React from 'react';
import { AdMeshLayout } from 'admesh-ui-sdk';
// No CSS import needed! Styles are auto-injected ✨

const recommendations = [
  {
    title: "HubSpot CRM",
    reason: "Perfect for remote teams with excellent collaboration features",
    intent_match_score: 0.92,
    admesh_link: "https://useadmesh.com/track?ad_id=hubspot-123",
    ad_id: "hubspot-123",
    product_id: "hubspot-crm",
    has_free_tier: true,
    trial_days: 14,
    keywords: ["CRM", "Sales", "Marketing"]
  }
];

function App() {
  return (
    <div>
      <h1>My AI Application</h1>

      {/* AdMesh layout - auto-detects best format */}
      <AdMeshLayout
        recommendations={recommendations}
        layout="auto"
        maxItems={6}
        onRecommendationClick={(adId, admeshLink) => {
          window.open(admeshLink, '_blank');
        }}
      />
    </div>
  );
}

Specific Layout Examples

// Citation layout for AI conversations
<AdMeshLayout
  recommendations={recommendations}
  conversationText="Based on your startup needs, I recommend HubSpot CRM for its excellent free tier..."
  layout="citation"
/>

// Ecommerce layout for product grids
<AdMeshLayout
  ecommerceProducts={products}
  layout="ecommerce"
  title="Featured Products"
/>

// Grid layout for recommendation cards
<AdMeshLayout
  recommendations={recommendations}
  layout="grid"
  columns={3}
  spacing="lg"
  title="Recommended Solutions"
/>

📋 Component Comparison

Choose the right component for your use case:

Component	Best For	Display Style	Integration Complexity	Mobile Optimized
AdMeshLayout	All use cases	Auto-adaptive	⭐ Easy	✅ Yes
AdMeshProductCard	Individual products	Single card	⭐ Easy	✅ Yes
AdMeshEcommerceCards	Product carousels	Horizontal scroll	⭐ Easy	✅ Yes
AdMeshCitationUnit	AI assistants	Direct links	⭐⭐ Medium	✅ Yes
AdMeshConversationalUnit	Chat interfaces	Inline/floating	⭐⭐ Medium	✅ Yes
AdMeshExpandableUnit	Rich showcases	Expandable details	⭐⭐ Medium	✅ Yes

🎯 AdMeshLayout

AdMeshLayout is the recommended component that automatically combines and optimizes all other components:

Auto-Detection: Automatically chooses the best layout based on your content
Multiple Layouts: Citation, ecommerce, grid, list, and mixed layouts
Single API: One component handles all recommendation types
Smart Optimization: Automatically limits items and optimizes for mobile
Customizable: Full control over layout, spacing, and component behavior
FTC Compliance: Includes proper "Sponsored", "Sponsored", and "" disclosures

Default Configuration

Default numberOfItems: 1 for layout components, 3 for ecommerce
Single Item Layout: When numberOfItems is 1, card displays at 100% width
Disclosure Handling: Only AdMeshLayout shows disclosures - individual components are disclosure-free

The AdMeshLayout component is the recommended way to display AdMesh recommendations. It automatically detects the best layout based on your content and provides a single API for all recommendation types.

import { AdMeshLayout } from 'admesh-ui-sdk';

// Auto-detection (recommended) - defaults to 1 item for layout, 3 for ecommerce
<AdMeshLayout
  recommendations={recommendations}
  ecommerceProducts={products}
  conversationText="Based on your needs..."
  layout="auto"
  // maxItems defaults: 1 for layout, 3 for ecommerce
/>

// Specific layouts with custom maxItems
<AdMeshLayout layout="citation" recommendations={recs} conversationText="..." />
<AdMeshLayout layout="ecommerce" ecommerceProducts={products} maxItems={3} />
<AdMeshLayout layout="grid" recommendations={recs} maxItems={1} columns={1} />
<AdMeshLayout layout="list" recommendations={recs} maxItems={1} />
<AdMeshLayout layout="mixed" recommendations={recs} ecommerceProducts={products} />

Layout Types:

auto: Automatically detects best layout based on content
citation: Direct links within conversation text
ecommerce: Horizontal scrolling product grid
grid: Responsive grid of recommendation cards
list: Vertical list of simplified cards
mixed: Combines multiple component types

Key Features:

Smart Auto-Detection: Chooses optimal layout automatically
Responsive Design: Adapts to all screen sizes
Customizable: Control columns, spacing, titles, and behavior
Component Props: Pass props to underlying components
Event Handling: Unified click and hover handlers

📋 Individual Components

Note: Individual components no longer display disclosure elements (Match Score, "Sponsored", ""). Only AdMeshLayout includes FTC-compliant disclosures. Use AdMeshLayout for platform integration.

Core Components

AdMeshProductCard

Individual product recommendation card with rich information display.

// Default clean minimal design (recommended)
<AdMeshProductCard
  recommendation={recommendation}
  showMatchScore={false} // Deprecated - Match Score removed from UI
  showBadges={true}
  showFeatures={false} // Default: clean minimal design
  onClick={(adId, admeshLink) => window.open(admeshLink)}
/>

// With features for detailed showcases
<AdMeshProductCard
  recommendation={recommendation}
  showFeatures={true} // Show key features section
  onClick={(adId, admeshLink) => window.open(admeshLink)}
/>

Props:

showFeatures (boolean, default: false) - Whether to display the key features section. Default is clean minimal design.
showBadges (boolean, default: true) - Whether to show product badges
showMatchScore (boolean, default: false) - Deprecated, match score removed from UI

AdMeshEcommerceCards

Horizontal scrolling product cards for ecommerce recommendations, similar to Google product search results.

<AdMeshEcommerceCards
  products={ecommerceProducts}
  title="Recommended Laptops"
  showPricing={true}
  showRatings={true}
  showBrand={true}
  cardWidth="md"
  maxCards={10}
  onProductClick={(product) => window.open(product.admesh_link || product.url)}
/>

Perfect for:

Product search results
Ecommerce recommendations
Mixed AdMesh + Walmart/Amazon products
Google-style product carousels
Shopping comparison displays

Conversational Components

AdMeshConversationalUnit

Smart conversational ad component that adapts to different chat contexts and display modes.

<AdMeshConversationalUnit
  recommendations={recommendations}
  config={{
    displayMode: 'inline', // 'inline' | 'minimal' | 'floating' | 'summary' | 'citation'
    context: 'chat',
    maxRecommendations: 3,
    showPoweredBy: true
  }}
  onRecommendationClick={(adId, admeshLink) => window.open(admeshLink)}
/>

AdMeshInlineRecommendation

Compact inline recommendation component perfect for chat interfaces.

<AdMeshInlineRecommendation
  recommendation={recommendation}
  compact={true}
  showReason={true}
  onClick={(adId, link) => window.open(link)}
/>

AdMeshCitationUnit

Citation-based conversation ad component that directly injects clickable links with underlines into text. Supports dynamic content and multiple link insertion strategies.

<AdMeshCitationUnit
  recommendations={recommendations}
  conversationText="Based on your requirements, I recommend HubSpot CRM for its features..."
  citationStyle="numbered" // 'numbered' | 'bracketed' | 'superscript'
  onCitationHover={(recommendation) => console.log('Hovered:', recommendation.title)}
/>

Dynamic Content Examples:

// Template-based dynamic links
<AdMeshCitationUnit
  recommendations={recommendations}
  dynamicTemplate="I recommend {product1} for startups and {product2} for enterprises"
  linkInsertionStrategy="template"
  onTextUpdate={(newText) => console.log('Updated text:', newText)}
  enableRealTimeUpdates={true}
/>

// Custom pattern matching
<AdMeshCitationUnit
  recommendations={recommendations}
  conversationText="For CRM solutions, consider these options for your business"
  linkInsertionStrategy="keywords"
  customLinkPatterns={[
    { pattern: "CRM", recommendationIndex: 0, linkText: "HubSpot CRM" },
    { pattern: "business", recommendationIndex: 1, linkText: "Salesforce" }
  ]}
/>

// Append links at the end
<AdMeshCitationUnit
  recommendations={recommendations}
  conversationText="Here are some great software solutions for your needs."
  linkInsertionStrategy="append"
/>

Perfect for:

AI assistant responses
Dynamic conversation generation
Template-based content
Real-time text updates
Natural text integration

AdMeshCitationReference

Individual citation references for inline use within conversational text.

<AdMeshCitationReference
  recommendations={[recommendation]}
  citationStyle="numbered"
  onRecommendationClick={(adId, link) => window.open(link)}
/>

Chat Components

AdMeshChatInterface

Embeddable chat interface for integrating conversational AI into web applications.

<AdMeshChatInterface
  messages={messages}
  config={{
    placeholder: "Ask me about products...",
    enableTypingIndicator: true,
    maxMessages: 50
  }}
  onSendMessage={handleSendMessage}
  onRecommendationClick={(adId, link) => window.open(link)}
/>

AdMeshChatMessage

Individual chat message component with recommendation support.

AdMeshChatInput

Chat input component with suggestions and auto-resize functionality.

Expandable & Interactive Components

AdMeshExpandableUnit

Expandable product showcase with detailed information and feature sections.

<AdMeshExpandableUnit
  recommendation={recommendation}
  theme={theme}
  showFeatureSections={true}
  showProductImages={true}
  onRecommendationClick={(adId, admeshLink) => window.open(admeshLink)}
/>

AdMeshProductCard - Simple Variation

Simple, clean ad format for minimal integration (replaces AdMeshSimpleAd).

<AdMeshProductCard
  recommendation={recommendation}
  theme={theme}
  variation="simple" // Creates inline ad format
  onClick={(adId, admeshLink) => window.open(admeshLink)}
/>

🔧 Utility Components

AdMeshBadge

Reusable badge component for highlighting features.

AdMeshLinkTracker

Wrapper for tracking any clickable element with built-in analytics.

<AdMeshLinkTracker
  adId={recommendation.ad_id}
  admeshLink={recommendation.admesh_link}
  productId={recommendation.product_id}
  onClick={() => handleClick()}
  trackingData={{ title: recommendation.title }}
>
  <YourCustomComponent />
</AdMeshLinkTracker>

🎨 Advanced Customization & Theming

The AdMesh UI SDK provides complete freedom for AI platforms to customize colors, icons, fonts, and styling to match their brand perfectly.

Consistent Design System

The AdMesh UI SDK ensures consistent styling across all components:

🎨 Unified Colors & Themes: All components share the same color palette and theme system
📝 Consistent Fonts: All components use the same font family for visual consistency
📐 Standardized Width: 100% width for all components except ecommerce cards (which maintain horizontal scrolling)
📱 Responsive Design: Mobile-friendly and adaptive across all screen sizes
🌙 Dark Mode Support: Seamless light/dark mode transitions with consistent styling

Enhanced Theme System

import { createAdMeshTheme, themePresets } from 'admesh-ui-sdk';

// Custom brand colors with automatic consistency
const customTheme = createAdMeshTheme({
  mode: 'light',
  primaryColor: '#ff6b6b',      // Your brand color
  secondaryColor: '#4ecdc4',    // Secondary brand color
  accentColor: '#45b7d1',       // Accent color
  borderRadius: '16px',         // Custom border radius
  fontFamily: '"Poppins", sans-serif', // Applied consistently across all components

  // Custom icons (emoji or React components)
  icons: {
    starIcon: '🌟',
    expandIcon: '▼',
    collapseIcon: '▲'
  },

  // Component-specific overrides (width settings are automatically applied)
  components: {
    button: {
      backgroundColor: '#custom-color',
      borderRadius: '12px'
    }
    // Width settings are automatically applied:
    // - productCard: { width: '100%' }
    // - citationUnit: { width: '100%' }
    // - inlineRecommendation: { width: '100%' }
    // - ecommerce cards maintain auto width for horizontal scrolling
  }
});

<AdMeshProductCard
  recommendations={recommendations}
  theme={customTheme}
/>

Preset Themes

// Use built-in presets
<AdMeshProductCard theme={themePresets.minimal} />
<AdMeshProductCard theme={themePresets.vibrant} />
<AdMeshProductCard theme={themePresets.corporate} />

Dark Mode

import { createDarkTheme } from 'admesh-ui-sdk';

const darkTheme = createDarkTheme({
  primaryColor: '#a78bfa',
  secondaryColor: '#34d399'
});

📊 Unified Recommendation JSON Response

All AdMesh ad units use the same unified recommendation response structure. This ensures consistency across all components and makes integration seamless.

Complete Recommendation Object

interface AdMeshRecommendation {
  // Core required fields
  title: string;                    // Product/service title
  reason: string;                   // Why this is recommended
  intent_match_score: number;      // 0-1 normalized match score
  admesh_link: string;              // Tracking URL for clicks
  ad_id: string;                    // Unique ad identifier
  product_id: string;               // Unique product identifier

  // Core product/offer fields
  url?: string;                     // Direct product URL
  redirect_url?: string;            // Alternative redirect URL
  description?: string;             // Product description
  pricing?: string;                 // Pricing information
  reward_note?: string | null;      // Special offers/rewards
  keywords?: string[];              // Product keywords
  categories?: string[];            // Product categories
  features?: string[];              // Key features list
  integrations?: string[];          // Integration capabilities
  has_free_tier?: boolean;          // Free tier availability
  trial_days?: number;              // Trial period length
  audience_segment?: string;        // Target audience
  is_ai_powered?: boolean;          // AI-powered product flag
  is_open_source?: boolean;         // Open source flag
  offer_trust_score?: number;       // Offer trust rating (0-1)
  brand_trust_score?: number;       // Brand trust rating (0-1)

  // Marketing content fields (for rich ad units)
  recommendation_title?: string;    // Marketing-optimized title
  recommendation_description?: string; // Marketing-optimized description
  offer_images?: Array<{            // Promotional images
    url: string;
    storage_path: string;
    filename: string;
    content_type: string;
    dimensions: {
      width: number;
      height: number;
    };
  }>;
  product_logo?: {                  // Product logo
    url: string;
    storage_path: string;
    filename: string;
    content_type: string;
    dimensions: {
      width: number;
      height: number;
    };
  };
  feature_sections?: Array<{        // Feature sections for expandable units
    title: string;
    description: string;
    icon: string;
  }>;

  // Extended compatibility fields
  reviews_summary?: string;         // User reviews summary
  security?: string[];              // Security features
  support?: string[];               // Support options
  badges?: string[];                // Display badges
}

API Response Structure

interface AgentRecommendationResponse {
  session_id: string;
  intent: {
    goal: string;
    intent_group: string;
    purchase_intent: string;
    intent_type: string;
    layout_type: string;
    categories: string[];
  };
  response: {
    summary: string;
    recommendations: AdMeshRecommendation[];
    followup_suggestions: Array<{
      label: string;
      query: string;
    }>;
    layout_type: string;
  };
  tokens_used: number;
  model_used: string;
}

Usage Across All Ad Units

The same recommendation object works seamlessly across all ad unit types:

// Same recommendations for all components
const recommendations: AdMeshRecommendation[] = [
  {
    title: "HubSpot CRM",
    reason: "Perfect for remote teams with excellent collaboration features",
    intent_match_score: 0.92,
    admesh_link: "https://useadmesh.com/track?ad_id=hubspot-123",
    ad_id: "hubspot-123",
    product_id: "hubspot-crm",
    has_free_tier: true,
    trial_days: 14,
    keywords: ["CRM", "Sales", "Marketing"],
    pricing: "Free tier available, paid plans from $45/month",
    // ... additional fields as needed
  }
];

// Use with any ad unit
{recommendations.map(rec => <AdMeshProductCard key={rec.ad_id} recommendation={rec} />)}
<AdMeshConversationalUnit recommendations={recommendations} config={chatConfig} />
<AdMeshCitationUnit recommendations={recommendations} conversationText="..." />
<AdMeshExpandableUnit recommendation={recommendations[0]} />

💬 Conversational Ad Units

Perfect for chat interfaces, AI assistants, and conversational experiences.

Quick Start - Conversational Units

import React from 'react';
import { AdMeshConversationalUnit } from 'admesh-ui-sdk';

const recommendations = [
  {
    title: "HubSpot CRM",
    reason: "Perfect for remote teams with excellent collaboration features",
    intent_match_score: 0.92,
    admesh_link: "https://useadmesh.com/track?ad_id=hubspot-123",
    ad_id: "hubspot-123",
    product_id: "hubspot-crm",
    has_free_tier: true,
    trial_days: 14,
    keywords: ["CRM", "Sales", "Marketing"]
  }
];

function ChatInterface() {
  return (
    <div className="chat-container">
      {/* Your chat messages */}
      <div className="message">I need a CRM for my team</div>

      {/* AdMesh conversational ad unit */}
      <AdMeshConversationalUnit
        recommendations={recommendations}
        config={{
          displayMode: 'inline', // 'inline' | 'minimal' | 'floating' | 'summary'
          context: 'chat',
          maxRecommendations: 3,
          showPoweredBy: true
        }}
        onRecommendationClick={(adId, admeshLink) => {
          window.open(admeshLink, '_blank');
        }}
      />
    </div>
  );
}

Display Modes

Inline Mode

Full recommendations displayed inline with the conversation:

<AdMeshConversationalUnit
  recommendations={recommendations}
  config={{ displayMode: 'inline', context: 'chat' }}
/>

Minimal Mode

Compact display showing match count and top recommendation:

<AdMeshConversationalUnit
  recommendations={recommendations}
  config={{ displayMode: 'minimal', context: 'assistant' }}
/>

Floating Mode

Floating overlay that doesn't interrupt the conversation flow:

<AdMeshConversationalUnit
  recommendations={recommendations}
  config={{ displayMode: 'floating', context: 'support' }}
/>

Summary Mode

End-of-conversation summary with top recommendations:

<AdMeshConversationalUnit
  recommendations={recommendations}
  config={{ displayMode: 'summary', context: 'agent' }}
  conversationSummary="We discussed your CRM needs..."
/>

Citation Mode

Display recommendations as inline citations within conversational text:

<AdMeshConversationalUnit
  recommendations={recommendations}
  config={{ displayMode: 'citation', context: 'assistant' }}
  conversationSummary="Based on your needs, I recommend HubSpot CRM for its excellent features..."
/>

Individual Conversational Components

AdMeshInlineRecommendation

Compact inline recommendations for chat bubbles:

import { AdMeshInlineRecommendation } from 'admesh-ui-sdk';

<AdMeshInlineRecommendation
  recommendation={recommendation}
  compact={true}
  showReason={true}
  onClick={(adId, link) => window.open(link)}
/>

AdMeshCitationUnit

Citation-based conversation ads with direct inline links and dynamic content support:

import { AdMeshCitationUnit } from 'admesh-ui-sdk';

<AdMeshCitationUnit
  recommendations={recommendations}
  conversationText="Based on your requirements, I recommend HubSpot CRM for its features..."
  citationStyle="numbered" // 'numbered' | 'bracketed' | 'superscript'
  onCitationHover={(recommendation) => console.log('Hovered:', recommendation.title)}
/>

Dynamic Content Strategies:

// 1. Template-based (AI content generation)
<AdMeshCitationUnit
  recommendations={recommendations}
  dynamicTemplate="I recommend {product1} for startups and {product2} for enterprises"
  linkInsertionStrategy="template"
  enableRealTimeUpdates={true}
  onTextUpdate={(text) => updateConversation(text)}
/>

// 2. Custom keyword targeting
<AdMeshCitationUnit
  recommendations={recommendations}
  conversationText="Looking for CRM solutions for your business needs"
  linkInsertionStrategy="keywords"
  customLinkPatterns={[
    { pattern: "CRM", recommendationIndex: 0, linkText: "HubSpot CRM" },
    { pattern: "business", recommendationIndex: 1, linkText: "Salesforce" }
  ]}
/>

// 3. Append recommendations naturally
<AdMeshCitationUnit
  recommendations={recommendations}
  conversationText="Here are some great software options."
  linkInsertionStrategy="append"
/>

Key Features:

Direct Links: Product names become clickable underlined links
Dynamic Templates: Support for {product1}, {product2} placeholders
Smart Insertion: Multiple strategies for link placement
Real-time Updates: Live text processing and callbacks
Custom Patterns: Target specific keywords or phrases
Hover Details: Shows recommendation details on hover

Use Cases:

AI Chatbots: Dynamic conversation generation with template placeholders
Content Management: Auto-linking existing content with product mentions
E-commerce: Keyword-based product recommendations in descriptions
Email Marketing: Append strategy for newsletter recommendations
Documentation: Academic-style citations in technical content

AdMeshCitationReference

Individual citation references for inline use:

import { AdMeshCitationReference } from 'admesh-ui-sdk';

<p>
  Check out this great CRM solution{' '}
  <AdMeshCitationReference
    recommendation={recommendation}
    citationNumber={1}
    citationStyle="numbered"
    onClick={(adId, link) => window.open(link)}
  />
  {' '}for your business needs.
</p>

📝 Citation-Based Conversation Ads

Citation-based ads display recommendations as numbered references within conversational text, similar to academic papers or AI assistant responses. This format is perfect for AI applications, chatbots, and content that needs to reference products naturally within flowing text.

Key Features

Automatic Citation Insertion: Automatically finds product mentions in text and adds citations
Multiple Citation Styles: Support for numbered (1), bracketed [1], and superscript¹ formats
Interactive Tooltips: Hover over citations to see product details
Reference List: Optional list of all cited products at the bottom
Smart Matching: Uses product titles and keywords to find optimal insertion points

Basic Usage

import { AdMeshCitationUnit } from 'admesh-ui-sdk';

function AIAssistantResponse() {
  const conversationText = `
    Based on your requirements for a CRM system, I'd recommend HubSpot CRM
    for its excellent free tier and collaboration features. For enterprise needs,
    Salesforce offers the most comprehensive feature set with extensive customization.
  `;

  return (
    <AdMeshCitationUnit
      recommendations={recommendations}
      conversationText={conversationText}
      citationStyle="numbered"
      showCitationList={true}
      onRecommendationClick={(adId, link) => window.open(link)}
    />
  );
}

Citation Styles

Numbered: (1) - Clean numbered circles
Bracketed: [1] - Traditional academic style
Superscript: ¹ - Minimal superscript numbers

Configuration Options

ConversationalAdConfig

interface ConversationalAdConfig {
  displayMode: 'inline' | 'summary' | 'floating' | 'minimal' | 'citation';
  context: 'chat' | 'assistant' | 'agent' | 'support';
  maxRecommendations?: number;     // Default: 3
  showPoweredBy?: boolean;         // Default: true
  autoShow?: boolean;              // Default: true
  delayMs?: number;                // Default: 0
  position?: 'top' | 'bottom' | 'inline'; // Default: 'inline'
}

Integration Examples

Chat Application

function ChatApp() {
  const [messages, setMessages] = useState([]);
  const [recommendations, setRecommendations] = useState([]);

  const handleUserMessage = async (message) => {
    // Add user message
    setMessages(prev => [...prev, { role: 'user', content: message }]);

    // Get AI response and recommendations
    const response = await getAIResponse(message);
    setMessages(prev => [...prev, { role: 'assistant', content: response.text }]);

    // Show recommendations if available
    if (response.recommendations) {
      setRecommendations(response.recommendations);
    }
  };

  return (
    <div className="chat-container">
      {messages.map((msg, i) => (
        <div key={i} className={`message ${msg.role}`}>
          {msg.content}

          {/* Show recommendations after assistant messages */}
          {msg.role === 'assistant' && recommendations.length > 0 && (
            <AdMeshConversationalUnit
              recommendations={recommendations}
              config={{
                displayMode: 'inline',
                context: 'chat',
                maxRecommendations: 2
              }}
            />
          )}
        </div>
      ))}
    </div>
  );
}

<AdMeshProductCard theme={theme} recommendations={recommendations} />

💬 Chat Components

Perfect for websites and applications that want to provide AI-powered recommendations through chat interfaces.

Embedded Chat Interface

import React, { useState } from 'react';
import { AdMeshChatInterface } from 'admesh-ui-sdk';

function ChatPage() {
  const [messages, setMessages] = useState([]);
  const [isLoading, setIsLoading] = useState(false);

  const handleSendMessage = async (messageContent) => {
    // Add user message
    const userMessage = {
      id: `user-${Date.now()}`,
      role: 'user',
      content: messageContent,
      timestamp: new Date(),
    };
    setMessages(prev => [...prev, userMessage]);
    setIsLoading(true);

    // Get AI response
    const response = await getAIResponse(messageContent);
    setMessages(prev => [...prev, response]);
    setIsLoading(false);
  };

  return (
    <div className="h-screen">
      <AdMeshChatInterface
        messages={messages}
        config={{
          placeholder: "Ask me about products...",
          enableTypingIndicator: true,
          maxMessages: 50
        }}
        theme={{ mode: 'light' }}
        isLoading={isLoading}
        onSendMessage={handleSendMessage}
        onRecommendationClick={(adId, link) => window.open(link)}
      />
    </div>
  );
}

Chat Features

Embedded Interface: Full chat interface for web applications
Message History: Persistent conversation state
Typing Indicators: Visual feedback during AI response generation
Recommendation Display: Inline product recommendations with tracking
Theme Support: Light/dark modes with custom branding

Configuration Examples

// Embedded chat with message limit
<AdMeshChatInterface
  config={{
    maxMessages: 20,
    enableTypingIndicator: true,
    placeholder: "What can I help you find today?"
  }}
/>

🤖 Auto-Recommendations (AI Integration)

Integration with AI Applications

ChatGPT Plugin Integration

// When ChatGPT detects software-related queries
const handleChatGPTResponse = (userQuery, gptResponse) => {
  if (containsSoftwareQuery(userQuery)) {
    const recommendations = await getAdMeshRecommendations(userQuery);
    showAutoRecommendations(recommendations, userQuery);
  }
};

Claude Integration

// When Claude processes business queries
const handleClaudeQuery = async (query) => {
  const intent = await detectIntent(query);
  if (intent.category === 'software' || intent.category === 'tools') {
    const recommendations = await fetchRecommendations(intent);
    triggerAutoWidget(recommendations, query);
  }
};

Auto-Recommendation Features

Zero User Input: Automatically appears based on AI detection
Contextual Triggers: Shows why recommendations appeared
Smart Positioning: Non-intrusive placement options
📊 Tracking & Analytics

All AdMesh UI components include comprehensive built-in tracking for views, clicks, and conversions.

Automatic Tracking

Every component automatically tracks:

Views: When recommendations are displayed
Clicks: When users click on recommendations
Conversions: When users complete desired actions

// All components automatically track interactions
<AdMeshProductCard
  recommendations={recommendations}
  onProductClick={(adId, admeshLink) => {
    // This click is automatically tracked
    window.open(admeshLink, '_blank');
  }}
  onTrackView={(data) => {
    // Optional: Custom view tracking
    console.log('Recommendation viewed:', data);
  }}
/>

Global Tracking Configuration

import { setAdMeshTrackerConfig } from '@admesh/ui-sdk';

setAdMeshTrackerConfig({
  apiBaseUrl: 'https://api.useadmesh.com',
  enabled: true,
  debug: true, // Enable for development
  userId: 'user-123', // Optional user identification
  sessionId: 'session-456' // Optional session tracking
});

Custom Tracking

Use the AdMeshLinkTracker component for custom tracking:

import { AdMeshLinkTracker } from 'admesh-ui-sdk';

<AdMeshLinkTracker
  adId="custom-ad-123"
  admeshLink="https://useadmesh.com/track?ad_id=custom-ad-123"
  productId="product-456"
  trackingData={{
    customField: 'value',
    source: 'custom-component'
  }}
  onClick={() => {
    // Your custom click handler
    console.log('Custom click tracked');
  }}
>
  <YourCustomComponent />
</AdMeshLinkTracker>

Tracking Events

import { useAdMeshTracker } from 'admesh-ui-sdk';

function CustomComponent() {
  const { trackClick, trackView, trackConversion } = useAdMeshTracker();

  const handleCustomEvent = async () => {
    await trackClick({
      adId: 'ad-123',
      admeshLink: 'https://useadmesh.com/track?ad_id=ad-123',
      productId: 'product-456',
      metadata: { source: 'custom-button' }
    });
  };

  return <button onClick={handleCustomEvent}>Track Custom Event</button>;
}

🔗 Integration Examples

Complete Integration with AdMesh Backend SDKs

import { AdMesh } from '@admesh/typescript-sdk';
import { AdMeshProductCard, AdMeshConversationalUnit } from '@admesh/ui-sdk';

const client = new AdMesh({ apiKey: 'your-api-key' });

// Basic recommendation display
async function getRecommendations(query: string) {
  const response = await client.recommend.getRecommendations({
    query,
    format: 'auto'
  });

  return (
    <AdMeshProductCard
      recommendations={response.response?.recommendations || []}
      autoLayout={true}
      onProductClick={(adId, admeshLink) => {
        // Track click and open link
        window.open(admeshLink, '_blank');
      }}
    />
  );
}

// Chat interface integration
function ChatApp() {
  const [messages, setMessages] = useState([]);
  const [recommendations, setRecommendations] = useState([]);

  const handleUserMessage = async (message: string) => {
    // Add user message
    setMessages(prev => [...prev, { role: 'user', content: message }]);

    // Get AI response with recommendations
    const response = await client.recommend.getRecommendations({
      query: message,
      format: 'conversational'
    });

    // Add assistant response
    setMessages(prev => [...prev, {
      role: 'assistant',
      content: response.response?.summary || 'Here are some recommendations...'
    }]);

    // Show recommendations
    if (response.response?.recommendations) {
      setRecommendations(response.response.recommendations);
    }
  };

  return (
    <div className="chat-container">
      {messages.map((msg, i) => (
        <div key={i} className={`message ${msg.role}`}>
          {msg.content}

          {/* Show recommendations after assistant messages */}
          {msg.role === 'assistant' && recommendations.length > 0 && (
            <AdMeshConversationalUnit
              recommendations={recommendations}
              config={{
                displayMode: 'inline',
                context: 'chat',
                maxRecommendations: 3
              }}
              onRecommendationClick={(adId, link) => window.open(link)}
            />
          )}
        </div>
      ))}
    </div>
  );
}

Multi-Format Display

// Display the same recommendations in different formats
function MultiFormatDemo({ recommendations }: { recommendations: AdMeshRecommendation[] }) {
  return (
    <div className="space-y-8">
      {/* Main layout */}
      <AdMeshProductCard
        recommendations={recommendations}
        autoLayout={true}
      />

      {/* Citation format */}
      <AdMeshCitationUnit
        recommendations={recommendations}
        conversationText="Based on your requirements, I recommend these solutions..."
        citationStyle="numbered"
      />

      {/* Expandable showcase */}
      {recommendations[0] && (
        <AdMeshExpandableUnit
          recommendation={recommendations[0]}
          showFeatureSections={true}
        />
      )}
    </div>
  );
}

📚 API Reference

Core Types

// Complete recommendation interface (see Unified JSON Response section above)
interface AdMeshRecommendation {
  // Core required fields
  title: string;
  reason: string;
  intent_match_score: number; // 0-1 normalized score
  admesh_link: string;
  ad_id: string;
  product_id: string;

  // All optional fields for different ad unit needs
  url?: string;
  description?: string;
  pricing?: string;
  features?: string[];
  keywords?: string[];
  categories?: string[];
  has_free_tier?: boolean;
  trial_days?: number;
  // ... see complete interface above
}

// Intent types for layout selection
type IntentType =
  | 'compare_products'
  | 'best_for_use_case'
  | 'trial_demo'
  | 'budget_conscious';

// Theme configuration
interface AdMeshTheme {
  mode: 'light' | 'dark';
  accentColor?: string;
  borderRadius?: string;
  fontFamily?: string;
}

// Conversational ad configuration
interface ConversationalAdConfig {
  displayMode: 'inline' | 'summary' | 'floating' | 'minimal' | 'citation';
  context: 'chat' | 'assistant' | 'agent' | 'support';
  maxRecommendations?: number;
  showPoweredBy?: boolean;
  autoShow?: boolean;
  delayMs?: number;
  position?: 'top' | 'bottom' | 'inline';
}

// Chat configuration
interface AdMeshChatConfig {
  position: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
  size: 'sm' | 'md' | 'lg' | 'xl';
  displayMode: 'widget' | 'fullscreen' | 'embedded';
  autoOpen?: boolean;
  showWelcomeMessage?: boolean;
  welcomeMessage?: string;
  placeholder?: string;
  maxMessages?: number;
  enableTypingIndicator?: boolean;
}

🎭 Live Examples & Documentation

Interactive Storybook

🌐 Hosted Storybook: https://storybook.useadmesh.com/

Explore interactive examples and component variations:

📝 Citation Components - Different citation styles (numbered, bracketed, superscript)
💬 Conversational Ads - Chat interface integration examples
🎯 Layout Components - Unified layout with multiple display options
🎨 Theme Variations - Light/dark mode examples
📱 Responsive Design - Mobile and desktop layout adaptations
🔧 Configuration Options - All component props and configurations

No installation required - view all ad formats directly in your browser!

Complete Documentation

📚 Full Documentation: https://docs.useadmesh.com/

Getting Started Guides - Step-by-step integration tutorials
API Reference - Complete component and prop documentation
Integration Examples - Real-world implementation patterns
Best Practices - Optimization and performance tips
Troubleshooting - Common issues and solutions

🎨 Theming & Dark Mode

The AdMesh UI SDK provides comprehensive theming support with full dark mode compliance:

Theme Configuration

// Light theme (default)
<AdMeshProductCard theme={{ mode: "light" }} />

// Dark theme with proper contrast ratios
<AdMeshProductCard theme={{ mode: "dark" }} />

// Custom accent color
<AdMeshProductCard theme={{ mode: "light", accentColor: "#3b82f6" }} />

// Dynamic theme switching
const [isDarkMode, setIsDarkMode] = useState(false);
<AdMeshProductCard theme={{ mode: isDarkMode ? "dark" : "light" }} />

Dark Mode Features

✅ Full Dark Mode Support: All components automatically adapt to dark theme
✅ WCAG Accessibility: Proper contrast ratios meet accessibility guidelines
✅ Consistent Branding: "" remains visible in both themes
✅ Smooth Transitions: Components transition smoothly between light and dark modes
✅ CSS Variables: Uses CSS custom properties for consistent theming
✅ No Ambiguous Elements: Clean, focused interface without confusing UI elements

CSS Custom Properties

The SDK uses CSS custom properties that automatically adjust based on the theme:

/* Light theme variables */
.admesh-component[data-admesh-theme="light"] {
  --admesh-background: #ffffff;
  --admesh-text: #111827;
  --admesh-border: #e5e7eb;
  --admesh-surface: #f9fafb;
}

/* Dark theme variables */
.admesh-component[data-admesh-theme="dark"] {
  --admesh-background: #111827;
  --admesh-text: #f9fafb;
  --admesh-border: #374151;
  --admesh-surface: #1f2937;
  --admesh-shadow: 0 1px 3px 0 rgb(0 0 0 / 0.3);
}

Theme Integration

All AdMesh components automatically respect the theme prop:

// All components support the same theme interface
<AdMeshProductCard theme={{ mode: "dark" }} />
<AdMeshChatInterface theme={{ mode: "dark" }} />

📱 Responsive Design & Accessibility

Mobile-First Design

All AdMesh components are built with mobile-first responsive design:

// Components automatically adapt to screen sizes
<AdMeshProductCard
  recommendations={recommendations}
  // Automatically shows:
  // - Grid layout on desktop
  // - Single column on mobile
  // - Optimized touch targets
  // - Readable typography scaling
/>

Accessibility Features

WCAG 2.1 AA Compliant: All components meet accessibility standards
Keyboard Navigation: Full keyboard support for all interactive elements
Screen Reader Support: Proper ARIA labels and semantic HTML
Focus Management: Visible focus indicators and logical tab order
Color Contrast: Meets contrast requirements in both light and dark modes
Reduced Motion: Respects user's motion preferences

// Accessibility is built-in, no additional configuration needed
<AdMeshConversationalUnit
  recommendations={recommendations}
  config={{ displayMode: 'inline' }}
  // Automatically includes:
  // - aria-labels for recommendations
  // - keyboard navigation
  // - screen reader announcements
  // - focus management
/>

Responsive Breakpoints

/* Built-in responsive breakpoints */
.admesh-component {
  /* Mobile: 0-640px */
  /* Tablet: 641-1024px */
  /* Desktop: 1025px+ */
}

/* Components automatically adjust:
   - Typography scales appropriately
   - Touch targets are 44px minimum
   - Layouts stack on mobile
   - Sidebars become overlays
   - Chat widgets resize appropriately
*/

🔧 Troubleshooting

Common Issues & Solutions

Components Not Displaying

// ❌ Missing recommendations data
<AdMeshProductCard recommendations={undefined} />

// ✅ Always provide valid recommendations array
<AdMeshProductCard recommendations={recommendations || []} />

Styling Issues

// ❌ CSS not loading (if using manual import)
import { AdMeshProductCard } from 'admesh-ui-sdk';

// ✅ Styles are auto-injected, no import needed
import { AdMeshProductCard } from 'admesh-ui-sdk';
// Styles automatically included ✨

TypeScript Errors

# Install required peer dependencies
npm install --save-dev @types/react @types/react-dom

# Ensure React 16.8+ for hooks support
npm install react@^16.8.0 react-dom@^16.8.0

Tracking Not Working

// ❌ Missing admesh_link in recommendations
const recommendations = [{
  title: "Product",
  // Missing admesh_link
}];

// ✅ Include proper tracking URLs
const recommendations = [{
  title: "Product",
  admesh_link: "https://useadmesh.com/track?ad_id=123",
  ad_id: "123",
  product_id: "product-123"
}];

Mobile Layout Issues

// ❌ Fixed widths that don't scale
<div style={{ width: '800px' }}>
  <AdMeshProductCard recommendations={recommendations} />
</div>

// ✅ Use responsive containers
<div className="w-full max-w-4xl mx-auto">
  <AdMeshProductCard recommendations={recommendations} />
</div>

Performance Optimization

// ✅ Limit recommendations for better performance
<AdMeshProductCard
  recommendations={recommendations}
  maxDisplayed={6} // Limit to 6 items
/>

// ✅ Use React.memo for static recommendations
const MemoizedAdMeshProductCard = React.memo(AdMeshProductCard);

// ✅ Lazy load heavy components
const AdMeshExpandableUnit = React.lazy(() =>
  import('admesh-ui-sdk').then(module => ({
    default: module.AdMeshExpandableUnit
  }))
);

🛠 Development

# Install dependencies
npm install

# Start Storybook for development
npm run storybook         # Storybook at :6006

# Build library for NPM
npm run build

# Build Storybook for deployment
npm run build-storybook

# Run linting
npm run lint

# Run tests
npm run test

# Type checking
npm run type-check

🚀 Deployment

Automatic Vercel Deployment

Go to vercel.com and import your GitHub repository
Configure build settings:
- Build Command: npm run build-storybook
- Output Directory: storybook-static
Deploy automatically on every push to main

No environment variables needed - Vercel's GitHub integration handles everything automatically!

Manual Deployment

npm run build-storybook
npx serve storybook-static

🎯 Summary

The AdMesh UI SDK provides a complete solution for displaying product recommendations across all ad unit formats:

✅ What You Get

10+ Ad Unit Types - From simple cards to complex conversational interfaces
Unified JSON Schema - Same recommendation structure works across all components and sources (Walmart, AdMesh, etc.)
Built-in Tracking - Automatic analytics for views, clicks, and conversions
Full Responsive Design - Mobile-first with accessibility compliance
TypeScript Support - Complete type safety and IntelliSense
Theme System - Light/dark mode with custom branding
Zero Configuration - Works out of the box with sensible defaults

🚀 Get Started in 3 Steps

Install: npm install admesh-ui-sdk
Import: import { AdMeshProductCard } from 'admesh-ui-sdk';
Use: <AdMeshProductCard recommendations={recommendations} />

📋 New in v0.13.0: Unified Schema Guide - Learn about the new unified JSON schema that works across all recommendation sources.

📋 Unified JSON Schema

The AdMesh UI SDK uses a unified JSON schema that works across all recommendation sources (Walmart, AdMesh, Amazon, etc.). This ensures consistent data structure regardless of the source:

interface AdMeshRecommendation {
  // Required core fields (new format)
  product_id: string;
  title: string;
  recommendation_description: string;
  admesh_link: string;
  categories: string[];
  integrations: string[];
  trust_score: number;
  reward_note: string;
  meta: {
    ad_id: string;
    offer_trust_score: number;
    brand_trust_score: number;
    intent_match_score: number;
    reason: string;
    description: string;
    keywords: string[];
    url: string;
    redirect_url: string;
  };

  // Legacy fields for backward compatibility
  ad_id?: string; // Use meta.ad_id instead
  brand?: string;
  source?: string;
  // ... other legacy fields
}

Example Unified Response

{
  "ad_id": "walmart_249887530",
  "admesh_link": "https://goto.walmart.com/c/None/568844/9383?veh=aff&sourceid=imp_000011112222333344&u=https%3A%2F%2Fwww.walmart.com%2Fip%2F249887530",
  "audience_segment": "",
  "availability": "in_stock",
  "brand": "ZENY",
  "brand_trust_score": 0.5,
  "categories": ["All Walmart Restored Large Appliances"],
  "description": "The smallest and lightest twin tub portable washing machine available...",
  "discount_percentage": 34.9,
  "external_id": "249887530",
  "features": ["Free 2-3 day shipping"],
  "image_url": "https://i5.walmartimages.com/asr/7505138e-bbfa-4a43-9de4-2ab8c71eed99.6810f971aaffdca38d18e9928b3e4450.jpeg?odnHeight=450&odnWidth=450&odnBg=ffffff",
  "intent_match_score": 0.72,
  "is_fallback": false,
  "keywords": [],
  "offer_trust_score": 1,
  "original_price": 152.9,
  "price": 99.48,
  "pricing": "$99.48",
  "product_id": "walmart_249887530",
  "rating": 4,
  "reason": "Perfect match for 'best washing machine to buy' - from trusted brand ZENY, highly rated (4.0/5)",
  "recommendation_description": "The smallest and lightest twin tub portable washing machine available...",
  "recommendation_title": "ZENY Portable Washing Machine Mini Twin Tub Washing Machine with Washer & Spinner, Gravity Drain ...",
  "redirect_url": "https://www.walmart.com/ip/249887530",
  "review_count": 384,
  "reward_note": "",
  "source": "walmart",
  "title": "ZENY Portable Washing Machine Mini Twin Tub Washing Machine with Washer & Spinner, Gravity Drain ...",
  "trial_days": 0,
  "url": "https://www.walmart.com/ip/249887530",
  "shipping_info": {
    "free_shipping_over_35": false,
    "standard_rate": 0,
    "two_day_rate": 0,
    "ship_to_store": false,
    "free_ship_to_store": false
  }
}

🌟 Perfect For

AI Applications - Citation-based conversation ads
Chat Interfaces - Inline and floating recommendation units
E-commerce Sites - Product comparison and showcase components
SaaS Platforms - Unified layout components with smart detection
Content Sites - Expandable and simple ad formats

Ready to get started? Check out our Interactive Storybook or Complete Documentation!

📄 License

MIT License

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests and stories
Submit a pull request

See our Contributing Guide for detailed instructions.

📞 Support & Community

Documentation & Resources

📚 Complete Documentation: https://docs.useadmesh.com
🎭 Interactive Storybook: https://storybook.useadmesh.com
🚀 AdMesh Dashboard: https://useadmesh.com

Get Help

GitHub Issues: Report bugs or request features
Email Support: mani@useadmesh.com
Discord Community: Join our Discord (coming soon)

Quick Links

API Keys: Get your API keys at useadmesh.com
TypeScript SDK: @admesh/typescript-sdk
Python SDK: admesh-python
Status Page: status.useadmesh.com

Contributing

We welcome contributions! See our Contributing Guide for details on:

Setting up the development environment
Code style and standards
Submitting pull requests
Reporting issues

changelog

Changelog

All notable changes to the AdMesh UI SDK will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.13.0] - 2025-01-10

Added

Unified JSON Schema: Implemented comprehensive unified schema that works across all recommendation sources (Walmart, AdMesh, Amazon, etc.)
Enhanced shipping information structure with detailed options (free_shipping_over_35, standard_rate, two_day_rate, ship_to_store, free_ship_to_store)
New required fields for better data consistency:
- ad_id: Unique advertisement identifier
- external_id: External source identifier (e.g., Walmart item ID)
- pricing: Formatted price string (e.g., "$99.48")
- recommendation_title: Marketing-optimized title
- recommendation_description: Marketing-optimized description
- brand_trust_score and offer_trust_score: Trust scoring metrics
- is_fallback: Indicates if recommendation is a fallback option
- feature_sections: Structured feature information
Content variations support for different presentation formats
Comprehensive example component demonstrating unified schema usage

Changed

BREAKING: Updated AdMeshRecommendation interface to use unified schema structure
BREAKING: Updated EcommerceProduct interface to align with unified schema
Removed deprecated Walmart-specific fields in favor of standardized fields
Enhanced AdMeshEcommerceCards component to work with unified schema
Updated documentation to reflect unified schema structure
Improved type safety with required vs optional field distinctions

Removed

Deprecated Walmart-specific fields (walmart_item_id, walmart_price, etc.) - now handled through unified schema
Legacy field mappings that are no longer needed

Migration Guide

If you're upgrading from a previous version:

Update your data structure to match the new unified schema
Replace Walmart-specific fields with standardized equivalents:
- walmart_item_id → external_id
- walmart_sale_price → price
- walmart_price → original_price
- walmart_images.large → image_url
- walmart_brand → brand
Ensure required fields are present in your recommendation data
Update shipping_info structure to use new detailed format

[0.12.3] - 2025-01-09

Fixed

Minor bug fixes and improvements

[0.11.0] - 2025-01-09

Added

AdMeshEcommerceCards - New horizontal scrolling product cards component for ecommerce recommendations
Google-style Product Display - Product cards similar to Google product search results with images, pricing, ratings
Mixed Source Support - Display both AdMesh affiliate offers and external ecommerce products (Walmart, Amazon, etc.)
Intelligent Product Ranking - Physical products ranked higher for ecommerce queries, software for software queries
Responsive Design - Mobile-optimized horizontal scrolling with touch support
Rich Product Information - Pricing, discounts, ratings, reviews, shipping info, availability status
Customizable Display - Configurable card sizes, themes, shadows, border radius
Source Badges - Optional badges showing product source (Walmart, AdMesh, etc.)
Discount Indicators - Visual discount percentage badges on product images
Star Ratings - Visual star rating display with review counts
Free Shipping Indicators - Shipping information display
Brand Display - Product brand information
Availability Status - In stock/out of stock indicators
Click Tracking - Built-in click tracking for affiliate links
Dark Mode Support - Full dark theme compatibility
TypeScript Support - Complete type definitions for EcommerceProduct interface
Storybook Stories - Comprehensive component documentation and examples

Enhanced

Updated package version to 0.11.0
Added EcommerceProduct and AdMeshEcommerceCardsProps type exports
Enhanced README.md with AdMeshEcommerceCards documentation
Added component to comparison table in documentation
Created example usage file with real API response data conversion

Technical

Built with Vite and TypeScript
CSS modules for styling isolation
Responsive design with mobile-first approach
Accessibility features (WCAG 2.1 AA compliant)
Performance optimized with lazy loading images

[0.8.0] - 2024-12-30

Added

Citation-Based Conversation Ads - New citation format for displaying recommendations as numbered references within conversational text
AdMeshCitationUnit component - Main citation component with automatic product name detection and citation insertion
AdMeshCitationReference component - Individual citation references for inline use
Clickable Product Names - Product names in conversational text are now styled as clickable hyperlinks
Multiple Citation Styles - Support for numbered (1), bracketed [1], and superscript¹ citation formats
Interactive Tooltips - Hover over citations to see product details with match scores
Reference Lists - Optional citation reference list at the bottom of conversational content
Smart Text Processing - Automatic detection of product mentions in conversational text
Citation mode support in AdMeshConversationalUnit component
Comprehensive Storybook stories for all citation components
Citation-specific TypeScript interfaces and types

Enhanced

Updated AdMeshConversationalUnit to support 'citation' display mode
Enhanced AdMeshInlineRecommendation with clickable product title styling
Improved AdMeshLinkTracker integration for citation components
Added citation-related keywords to package.json for better discoverability

Documentation

Updated README.md with comprehensive citation documentation
Added citation usage examples and integration guides
Created interactive HTML demos for citation functionality
Updated conversational guide with citation mode examples

Technical

Enhanced TypeScript types for citation components
Improved build process for citation component exports
Added comprehensive test coverage for citation functionality
Updated Storybook configuration for citation component stories

[0.7.0] - 2024-12-29

Added

Sidebar components (AdMeshSidebar, AdMeshSidebarHeader, AdMeshSidebarContent)
Chat components (AdMeshFloatingChat, AdMeshChatInterface, AdMeshChatMessage, AdMeshChatInput)
Auto-recommendation widget (AdMeshAutoRecommendationWidget)
Conversational ad units (AdMeshConversationalUnit, AdMeshConversationSummary, AdMeshInlineRecommendation)
Multiple display modes for conversational components
Comprehensive theming system
Built-in tracking and analytics
Responsive design improvements
Accessibility enhancements

Enhanced

Improved component architecture
Better TypeScript support
Enhanced documentation
Storybook integration

[0.6.0] - 2024-12-28

Added

Initial release of core components
AdMeshLayout, AdMeshProductCard, AdMeshCompareTable components
Basic theming support
TypeScript definitions
Initial documentation

Technical

React 18+ support
Vite build system
Tailwind CSS integration
ESLint and TypeScript configuration

Package detail

readme

AdMesh UI SDK

🌐 Live Sites

🚀 Features

📦 Installation

✨ Self-Contained Design

🎯 Quick Start

AdMeshLayout Component (Recommended)

Specific Layout Examples

📋 Component Comparison

🎯 AdMeshLayout

Default Configuration

📋 Individual Components

Core Components

AdMeshProductCard

AdMeshEcommerceCards

Conversational Components

AdMeshConversationalUnit

AdMeshInlineRecommendation

AdMeshCitationUnit

AdMeshCitationReference

Chat Components

AdMeshChatInterface

AdMeshChatMessage

AdMeshChatInput

Expandable & Interactive Components

AdMeshExpandableUnit

AdMeshProductCard - Simple Variation

🔧 Utility Components

AdMeshBadge

AdMeshLinkTracker

🎨 Advanced Customization & Theming

Consistent Design System

Enhanced Theme System

Preset Themes

Dark Mode

📊 Unified Recommendation JSON Response

Complete Recommendation Object

API Response Structure

Usage Across All Ad Units

💬 Conversational Ad Units

Quick Start - Conversational Units

Display Modes

Inline Mode

Minimal Mode

Floating Mode

Summary Mode

Citation Mode

Individual Conversational Components

AdMeshInlineRecommendation

AdMeshCitationUnit

AdMeshCitationReference

📝 Citation-Based Conversation Ads

Key Features

Basic Usage

Citation Styles

Configuration Options

ConversationalAdConfig

Integration Examples

Chat Application

💬 Chat Components

Embedded Chat Interface

Chat Features

Configuration Examples

🤖 Auto-Recommendations (AI Integration)

Integration with AI Applications

ChatGPT Plugin Integration

Claude Integration

Auto-Recommendation Features

📊 Tracking & Analytics

Automatic Tracking

Global Tracking Configuration

Custom Tracking

Tracking Events

🔗 Integration Examples

Complete Integration with AdMesh Backend SDKs

Multi-Format Display

📚 API Reference

Core Types