Building Interactive Widgets

┌─────────────────────────────────────────────────────────────────┐
│                         Your Widget                              │
│                                                                  │
│   ┌─────────────────────────┐    ┌─────────────────────────┐   │
│   │     Server-Side         │    │     Client-Side          │   │
│   │                         │    │                          │   │
│   │  • Tool definition      │───►│  • React component       │   │
│   │  • Input validation     │    │  • Event handlers        │   │
│   │  • Data fetching        │    │  • Host communication    │   │
│   │  • Widget rendering     │    │  • State management      │   │
│   │                         │    │                          │   │
│   │   server.ts             │    │   widgets/my-widget.tsx  │   │
│   └─────────────────────────┘    └─────────────────────────┘   │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

import { UniversalAppProvider } from '@pancakeapps/react';

function App() {
  return (
    <UniversalAppProvider
      onError={(error) => console.error('Widget error:', error)}
      fallback={<LoadingState />}
    >
      <YourWidget />
    </UniversalAppProvider>
  );
}

const {
  data,       // Structured data from renderWidget()
  input,      // Parameters the AI passed to your tool
  meta,       // Metadata about the invocation
  isLoading,  // True until data is received
  error,      // Error if tool invocation failed
} = useToolInvocation();

const bookFlight = useCallTool('book_flight');

// Returns a promise with the tool result
const result = await bookFlight({
  flightId: 'FL123',
  passengers: 2,
});

// Similar to useState, but persists in the host
const [tab, setTab] = useWidgetState('currentTab', 'overview');
const [filters, setFilters] = useWidgetState('filters', {});

const host = useHost();

// Context
host.context.theme          // 'light' | 'dark'
host.context.displayMode    // 'inline' | 'fullscreen' | 'pip'
host.context.viewport       // { width, height }

// Methods
host.requestDisplayMode('fullscreen');
host.openExternal({ href: 'https://...' });

const sendMessage = useSendMessage();

await sendMessage({
  prompt: 'Now help me find hotels near this restaurant',
});

const caps = useCapabilities();

if (caps.canPersistState) {
  // Safe to use useWidgetState
}
if (caps.canRequestFullscreen) {
  // Show fullscreen button
}

function ProductCard({ product }) {
  const addToCart = useCallTool('add_to_cart');
  const [adding, setAdding] = useState(false);
  
  const handleAdd = async () => {
    setAdding(true);
    try {
      await addToCart({ productId: product.id, quantity: 1 });
      // Show success feedback
    } catch (error) {
      // Show error feedback
    } finally {
      setAdding(false);
    }
  };
  
  return (
    <div className="product-card">
      <img src={product.image} alt={product.name} />
      <h3>{product.name}</h3>
      <p>${product.price}</p>
      <button onClick={handleAdd} disabled={adding}>
        {adding ? 'Adding...' : 'Add to Cart'}
      </button>
    </div>
  );
}

function SearchFilters() {
  const [filters, setFilters] = useWidgetState('filters', {
    minPrice: 0,
    maxPrice: 1000,
    category: 'all',
  });
  
  const applyFilters = useCallTool('filter_results');
  
  const handleSubmit = async (e) => {
    e.preventDefault();
    await applyFilters(filters);
  };
  
  return (
    <form onSubmit={handleSubmit}>
      <label>
        Category
        <select 
          value={filters.category}
          onChange={(e) => setFilters({...filters, category: e.target.value})}
        >
          <option value="all">All</option>
          <option value="electronics">Electronics</option>
          <option value="clothing">Clothing</option>
        </select>
      </label>
      
      <label>
        Price Range
        <input
          type="range"
          min="0"
          max="1000"
          value={filters.maxPrice}
          onChange={(e) => setFilters({...filters, maxPrice: +e.target.value})}
        />
      </label>
      
      <button type="submit">Apply Filters</button>
    </form>
  );
}

function TripSummary({ trip }) {
  const sendMessage = useSendMessage();
  
  const suggestNext = async (suggestion) => {
    const prompts = {
      hotels: `Find hotels near ${trip.destination} for ${trip.dates}`,
      activities: `What are fun activities in ${trip.destination}?`,
      restaurants: `Recommend restaurants in ${trip.destination}`,
    };
    
    await sendMessage({ prompt: prompts[suggestion] });
  };
  
  return (
    <div className="trip-summary">
      <h2>Trip to {trip.destination}</h2>
      <FlightDetails flight={trip.flight} />
      
      <div className="next-steps">
        <p>What would you like to do next?</p>
        <button onClick={() => suggestNext('hotels')}>Find Hotels</button>
        <button onClick={() => suggestNext('activities')}>Find Activities</button>
        <button onClick={() => suggestNext('restaurants')}>Find Restaurants</button>
      </div>
    </div>
  );
}

function ThemedWidget() {
  const { theme } = useHost().context;
  
  return (
    <div
      style={{
        background: theme === 'dark' ? '#1a1a1a' : '#ffffff',
        color: theme === 'dark' ? '#fafafa' : '#171717',
        // Use CSS custom properties for consistency
        '--accent': theme === 'dark' ? '#60a5fa' : '#2563eb',
      }}
    >
      <Content />
    </div>
  );
}

.widget {
  --bg: #ffffff;
  --fg: #171717;
  --accent: #2563eb;
}

.widget.dark {
  --bg: #1a1a1a;
  --fg: #fafafa;
  --accent: #60a5fa;
}

.widget {
  background: var(--bg);
  color: var(--fg);
}

.widget button {
  background: var(--accent);
  color: white;
}

.widget-grid {
  display: grid;
  gap: 1rem;
  
  /* Single column on small viewports */
  grid-template-columns: 1fr;
}

@media (min-width: 400px) {
  .widget-grid {
    grid-template-columns: repeat(2, 1fr);
  }
}

@media (min-width: 600px) {
  .widget-grid {
    grid-template-columns: repeat(3, 1fr);
  }
}

// Use CSS for animations, not JavaScript
.fade-in {
  animation: fadeIn 200ms ease-out;
}

@keyframes fadeIn {
  from { opacity: 0; transform: translateY(8px); }
  to { opacity: 1; transform: translateY(0); }
}

// Avoid large images - use appropriate sizes
<img 
  src={getOptimizedUrl(image, { width: 200, height: 150 })}
  loading="lazy"
  alt={alt}
/>

function RobustWidget() {
  const { data, isLoading, error } = useToolInvocation();
  
  if (isLoading) {
    return (
      <div className="loading">
        <Spinner />
        <p>Loading your results...</p>
      </div>
    );
  }
  
  if (error) {
    return (
      <div className="error">
        <h3>Something went wrong</h3>
        <p>{error.message}</p>
        <button onClick={() => window.location.reload()}>
          Try Again
        </button>
      </div>
    );
  }
  
  return <MainContent data={data} />;
}

import { ErrorBoundary } from '@pancakeapps/react';

function App() {
  return (
    <UniversalAppProvider>
      <ErrorBoundary
        fallback={({ error, resetError }) => (
          <div className="error-boundary">
            <p>Widget crashed: {error.message}</p>
            <button onClick={resetError}>Reset</button>
          </div>
        )}
      >
        <MyWidget />
      </ErrorBoundary>
    </UniversalAppProvider>
  );
}

pnpm universal-apps dev