BbQ.ChatWidgets 1.1.2

BbQ.ChatWidgets

Turn AI conversations into useful actions. Give your assistant forms, choices and cards so people can book, decide and resolve problems inside the conversation.

Try the local playground: booking, customer support and approval flows run with the real widget library and sample responses, without an API key.

Build on .NET, TypeScript, React, Angular or Blazor. Keep your application logic and AI provider; ChatWidgets supplies the interactive layer.

This repository contains these packages:

• NuGet: BbQ.ChatWidgets (the .NET library: services, renderers, endpoints)
• npm: @bbq-chat/widgets (the JavaScript/TypeScript client library: widgets, client helpers)
• npm: @bbq-chat/widgets-angular (Angular-native components and services)
• npm: @bbq-chat/widgets-react (React-native components, forms and streaming; usage and Angular feature parity)
• NuGet: BbQ.ChatWidgets.Blazor (Blazor widget components)

Note: the .NET package no longer bundles the JavaScript client or theme CSS. Install the npm package (or bring your own UI) to render widgets in a browser.

🚀 30-Second Demos

Start with a button widget. The server example requires an AI provider key; the local playground works without one.

C# / .NET (Server)

using Microsoft.Extensions.AI;
using BbQ.ChatWidgets.Extensions;

var builder = WebApplication.CreateBuilder(args);

// 1. Create chat client with function invocation
var apiKey = builder.Configuration["OpenAI:ApiKey"] 
    ?? throw new InvalidOperationException("OpenAI:ApiKey not configured");
    
IChatClient chatClient = new ChatClientBuilder(
    new OpenAI.Chat.ChatClient("gpt-4o-mini", apiKey).AsIChatClient())
    .UseFunctionInvocation()
    .Build();

// 2. Register BbQ services
builder.Services.AddBbQChatWidgets(options =>
{
  options.ChatClientFactory = _ => chatClient;
  options.EnablePersona = true; // opt-in: enable request/thread/default persona behavior
  options.DefaultPersona = "You are a concise assistant."; // optional
});

var app = builder.Build();

// 3. Map endpoints
app.MapBbQChatEndpoints();
app.Run();

JavaScript / TypeScript (Client)

import { WidgetManager } from '@bbq-chat/widgets';

// 1. Send a message
const response = await fetch('/api/chat/message', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ message: 'Show me a button', threadId: 'demo-123' })
});

const turn = await response.json();

// 2. Render widgets
const manager = new WidgetManager();
const container = document.getElementById('chat-container');
if (container && turn.widgets?.length) {
    manager.renderInto(container, turn.widgets);
}

Angular (Client)

import { Component, signal } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { WidgetRendererComponent } from '@bbq-chat/widgets-angular';
import type { ChatWidget } from '@bbq-chat/widgets-angular';

@Component({
  selector: 'app-chat',
  standalone: true,
  imports: [WidgetRendererComponent],
  template: `
    <bbq-widget-renderer
      [widgets]="widgets()"
      (widgetAction)="handleWidgetAction($event)">
    </bbq-widget-renderer>
  `
})
export class ChatComponent {
  widgets = signal<ChatWidget[]>([]);

  constructor(private http: HttpClient) {}

  sendMessage(text: string) {
    this.http.post<{ widgets?: ChatWidget[] }>('/api/chat/message', { message: text, threadId: 'demo-123' })
      .subscribe(turn => this.widgets.set(turn.widgets ?? []));
  }

  handleWidgetAction(event: { actionName: string; payload: any }) {
    console.log('Action:', event.actionName, event.payload);
  }
}

📚 Full Getting Started Guide → | Widget Gallery → | Integration Paths →

Features

• Interactive Chat Widgets: Buttons, forms, cards, dropdowns, sliders, toggles, file uploads, and more
• Server-Driven UI: The LLM decides which widgets to show based on conversation context
• Automatic Chat History Summarization: Efficiently manages long conversations by summarizing older turns
• SSE Support: Real-time server-pushed widget updates
• Triage Agents: Route conversations to specialized agents based on classification
• Type-Safe Widget Actions: Strongly-typed handlers for widget interactions
• Extensible Architecture: Swap out components via dependency injection

Install

NuGet (.NET)

dotnet add [YOUR_PROJECT] package BbQ.ChatWidgets

npm (JS/TS client + themes)

npm install @bbq-chat/widgets

npm (Angular native components)

npm install @bbq-chat/widgets-angular @bbq-chat/widgets

npm (React native components)

npm install @bbq-chat/widgets-react @bbq-chat/widgets

See the React package guide for forms, custom renderers and streaming.

Blazor Widget Overrides

Use component overrides to replace built-in widget components without writing switch/if logic.

Local (per renderer instance)

<WidgetRenderer Widget="widget" OnAction="HandleWidgetAction">
  <Overrides>
    <WidgetOverride Type="typeof(InputWidget)" Template="typeof(MyCustomInputComponent)" />
    <WidgetOverride TypeId="clock" Template="typeof(MyClockWidgetComponent)" />
  </Overrides>
</WidgetRenderer>

Global (DI registration)

services.AddBbQChatWidgetsBlazor(overrides =>
{
  overrides.Add<InputWidget, MyCustomInputComponent>();
  overrides.Add(typeof(MyClockWidgetComponent), widgetTypeId: "clock");
});

Resolution order is: local exact type → local type id → local assignable type → global exact type → global type id → global assignable type → built-in fallback.

📖 Documentation

• Production Deployment - Authorization, request limits, hosting and release verification
• Getting Started - Complete setup guide
• Widget Gallery - Visual showcase of all widgets
• Integration Paths - Choose the right approach for your stack
• Use Cases & Tutorials - Step-by-step scenarios
• API Reference - Generated API docs
• Contributing Guide - How to contribute

Build Documentation Locally

./docs/generate-docs.ps1

🧪 Tests

• .NET: dotnet test
• JS/TS: npm test and npm run test:package (run from js)
• Angular: npm test (run from js-angular)
• React library: npm test and npm run test:package (run from js-react, after building js)
• Playground: npm run test:e2e (run from Sample/BbQ.ChatWidgets.Sample.React/ClientApp, after building and installing Playwright Chromium)

📋 Changelog

See CHANGELOG.md for version history and release notes.

📄 License

See LICENSE.