@bbq-chat/widgets-angular

Angular components and services for BbQ ChatWidgets. This package provides Angular-native wrappers for the core @bbq-chat/widgets library.

Features

- ✨ Native Angular Components - All widgets render as Angular components with full framework support
- 🎨 Type-Safe - Full TypeScript support with comprehensive type definitions
- 🔄 Two-Way Data Binding - Leverage Angular's powerful data binding
- 🎯 Automatic Rendering - The WidgetRendererComponent automatically uses AngularWidgetRenderer for all built-in widgets
- 🔧 Extensible - Easy custom widget registration with full Angular component support

Installation

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

Peer Dependencies

This package requires:
- @angular/common >= 17.0.0
- @angular/core >= 17.0.0
- @bbq-chat/widgets ^1.0.0

Quick Start

$3

`typescript
import { Component } from '@angular/core';
import { WidgetRendererComponent } from '@bbq-chat/widgets-angular';
import type { ChatWidget } from '@bbq-chat/widgets-angular';

@Component({
selector: 'app-chat',
standalone: true,
imports: [WidgetRendererComponent],
template:
[widgets]="widgets"
(widgetAction)="handleWidgetAction($event)">


})
export class ChatComponent {
widgets: ChatWidget[] = [];

handleWidgetAction(event: { actionName: string; payload: any }) {
console.log('Widget action:', event.actionName, event.payload);
// Handle the action (e.g., send to backend)
}
}
`

$3

In your styles.css or styles.scss:

`css
@import '@bbq-chat/widgets/styles';
`

Or import a specific theme:

`css
@import '@bbq-chat/widgets/styles/light';
@import '@bbq-chat/widgets/styles/dark';
@import '@bbq-chat/widgets/styles/corporate';
`

Components

$3

The main component for rendering chat widgets. It automatically uses the AngularWidgetRenderer to render all built-in widgets as native Angular components.

Rendering Modes:
- Built-in widgets (button, card, form, etc.) are rendered as Angular components via AngularWidgetRenderer
- Custom widgets can use HTML functions, Angular components, or Angular templates
- Falls back to SsrWidgetRenderer (HTML string rendering) if needed for compatibility

Inputs:
- widgets: ChatWidget[] | null | undefined - Array of widgets to render

Outputs:
- widgetAction: EventEmitter<{ actionName: string; payload: any }> - Emits when a widget action is triggered

Example:

`typescript
[widgets]="messageWidgets"
(widgetAction)="onWidgetAction($event)">

`

Services

$3

Service for registering custom widget types.

Example:

`typescript
import { Component, OnInit } from '@angular/core';
import { WidgetRegistryService } from '@bbq-chat/widgets-angular';

export class MyCustomWidget {
type = 'myCustomWidget';
constructor(public label: string, public action: string) {}
}

@Component({
selector: 'app-root',
template: '...'
})
export class AppComponent implements OnInit {
constructor(private widgetRegistry: WidgetRegistryService) {}

ngOnInit() {
// Register custom widget factory
this.widgetRegistry.registerFactory('myCustomWidget', (obj) => {
if (obj.type === 'myCustomWidget') {
return new MyCustomWidget(obj.label, obj.action);
}
return null;
});
}
}
`

Widget Types

All standard widget types from @bbq-chat/widgets are supported and rendered as native Angular components:

- ButtonWidget - Clickable buttons
- CardWidget - Information cards
- FormWidget - Form containers with validation
- InputWidget - Text input fields
- TextAreaWidget - Multi-line text input
- DropdownWidget - Dropdown selects
- SliderWidget - Range sliders
- ToggleWidget - Toggle switches
- FileUploadWidget - File upload controls
- DatePickerWidget - Date pickers
- MultiSelectWidget - Multi-select dropdowns
- ThemeSwitcherWidget - Theme switcher controls
- ProgressBarWidget - Progress indicators
- ImageWidget - Image displays
- ImageCollectionWidget - Image galleries

AngularWidgetRenderer

The AngularWidgetRenderer is automatically used by WidgetRendererComponent to render all built-in widgets as native Angular components instead of HTML strings. This provides several advantages:

$3

- Native Angular Components - Full Angular lifecycle hooks, change detection, and dependency injection
- Type Safety - Strong typing throughout the rendering pipeline
- Better Performance - No need for innerHTML or manual DOM manipulation
- Reactive Updates - Leverage Angular's reactive forms and data binding
- Testability - Easier to test with Angular TestBed
- Easy Component Swapping - Simple API to replace any widget component with your own

$3

The WidgetRendererComponent automatically detects and uses AngularWidgetRenderer for all built-in widget types:

`typescript
// The WidgetRendererComponent automatically uses AngularWidgetRenderer
// No configuration needed - it just works!
[widgets]="widgets"
(widgetAction)="handleWidgetAction($event)">

`

$3

You can easily replace any built-in widget component with your own custom implementation:

`typescript
import { Component, OnInit, Inject } from '@angular/core';
import { ANGULAR_WIDGET_RENDERER, AngularWidgetRenderer } from '@bbq-chat/widgets-angular';
import { MyCustomButtonComponent } from './my-custom-button.component';

@Component({
selector: 'app-root',
template: '...'
})
export class AppComponent implements OnInit {
constructor(@Inject(ANGULAR_WIDGET_RENDERER) private renderer: AngularWidgetRenderer) {}

ngOnInit() {
// Replace the built-in button component with your custom one
this.renderer.registerComponent('button', MyCustomButtonComponent);

// Or register multiple components at once
this.renderer.registerComponents({
button: MyCustomButtonComponent,
input: MyCustomInputComponent,
card: MyCustomCardComponent
});
}
}
`

$3

All built-in widgets are available as standalone Angular components:

`typescript
import {
ButtonWidgetComponent,
CardWidgetComponent,
FormWidgetComponent,
InputWidgetComponent,
// ... and more
} from '@bbq-chat/widgets-angular';
`

These components can be used directly in your templates if needed, though typically you'll use them through WidgetRendererComponent.

$3

The FormWidgetComponent uses dynamic component rendering to render form fields. Instead of inline HTML, it dynamically instantiates the appropriate widget component (InputWidget, SliderWidget, etc.) for each field. This ensures consistency across all widgets and makes the form behavior automatically inherit any custom widget component replacements.

Advanced Usage

$3

Widget actions are emitted when users interact with widgets. Handle these actions in your component:

`typescript
async handleWidgetAction(event: { actionName: string; payload: any }) {
const { actionName, payload } = event;

try {
const response = await fetch('/api/chat/action', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ action: actionName, payload })
});

const data = await response.json();
// Update widgets with response
this.widgets = data.widgets;
} catch (error) {
console.error('Failed to handle widget action:', error);
}
}
`

$3

The library now supports three types of custom widget renderers for enhanced flexibility:

#### 1. HTML Function Renderer

Simple function that returns HTML strings:

`typescript
this.widgetRegistry.registerRenderer('myWidget', (widget) => {
return

`typescript
import { Component, Input } from '@angular/core';
import { CustomWidgetComponent } from '@bbq-chat/widgets-angular';

@Component({
selector: 'app-my-widget',
standalone: true,
template:

// Register the component
this.widgetRegistry.registerRenderer('myWidget', MyWidgetComponent);
`

#### 3. Angular Template Renderer

Use inline templates with full Angular template syntax:

`typescript
import { WidgetTemplateContext } from '@bbq-chat/widgets-angular';

@Component({
template:

ngOnInit() {
this.widgetRegistry.registerRenderer('myWidget', this.myTemplate);
}
}
``

See EXAMPLES.md for detailed examples and best practices.

License

MIT

Repository

https://github.com/JeanMarcMbouma/BbQ.ChatWidgets