@bbq-chat/widgets-angular 1.0.3 → 1.0.5

package/README.md

@@ -2,6 +2,14 @@
 
 Angular components and services for BbQ ChatWidgets. This package provides Angular-native wrappers for the core [@bbq-chat/widgets](https://www.npmjs.com/package/@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
@@ -65,7 +73,12 @@ Or import a specific theme:
 
 ### WidgetRendererComponent
 
-The main component for rendering chat widgets.
+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
@@ -120,11 +133,11 @@ export class AppComponent implements OnInit {
 
 ## Widget Types
 
-All standard widget types from `@bbq-chat/widgets` are supported:
+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
+- `FormWidget` - Form containers with validation
 - `InputWidget` - Text input fields
 - `TextAreaWidget` - Multi-line text input
 - `DropdownWidget` - Dropdown selects
@@ -138,6 +151,82 @@ All standard widget types from `@bbq-chat/widgets` are supported:
 - `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:
+
+### Benefits
+
+- **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
+
+### How It Works
+
+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!
+<bbq-widget-renderer 
+  [widgets]="widgets" 
+  (widgetAction)="handleWidgetAction($event)">
+</bbq-widget-renderer>
+```
+
+### Swapping Widget Components
+
+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
+    });
+  }
+}
+```
+
+### Built-in Widget Components
+
+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`.
+
+### Form Widget Dynamic Rendering
+
+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
 
 ### Handling Widget Actions

package/dist/README.md

@@ -0,0 +1,341 @@
+# @bbq-chat/widgets-angular
+
+Angular components and services for BbQ ChatWidgets. This package provides Angular-native wrappers for the core [@bbq-chat/widgets](https://www.npmjs.com/package/@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
+
+### 1. Import the component
+
+```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: `
+    <bbq-widget-renderer 
+      [widgets]="widgets" 
+      (widgetAction)="handleWidgetAction($event)">
+    </bbq-widget-renderer>
+  `
+})
+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)
+  }
+}
+```
+
+### 2. Import styles
+
+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
+
+### WidgetRendererComponent
+
+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
+<bbq-widget-renderer 
+  [widgets]="messageWidgets" 
+  (widgetAction)="onWidgetAction($event)">
+</bbq-widget-renderer>
+```
+
+## Services
+
+### WidgetRegistryService
+
+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:
+
+### Benefits
+
+- **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
+
+### How It Works
+
+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!
+<bbq-widget-renderer 
+  [widgets]="widgets" 
+  (widgetAction)="handleWidgetAction($event)">
+</bbq-widget-renderer>
+```
+
+### Swapping Widget Components
+
+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
+    });
+  }
+}
+```
+
+### Built-in Widget Components
+
+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`.
+
+### Form Widget Dynamic Rendering
+
+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
+
+### Handling Widget Actions
+
+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);
+  }
+}
+```
+
+### Custom Widget Renderers
+
+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 `<div class="my-widget">${widget.label}</div>`;
+});
+```
+
+#### 2. Angular Component Renderer (Recommended)
+
+Use Angular components for full framework features including data binding, change detection, and dependency injection:
+
+```typescript
+import { Component, Input } from '@angular/core';
+import { CustomWidgetComponent } from '@bbq-chat/widgets-angular';
+
+@Component({
+  selector: 'app-my-widget',
+  standalone: true,
+  template: `
+    <div class="my-widget">
+      <h3>{{ myWidget.title }}</h3>
+      <button (click)="onClick()">Action</button>
+    </div>
+  `
+})
+export class MyWidgetComponent implements CustomWidgetComponent {
+  @Input() widget!: ChatWidget;
+  widgetAction?: (actionName: string, payload: unknown) => void;
+
+  get myWidget(): MyCustomWidget {
+    return this.widget as MyCustomWidget;
+  }
+
+  onClick() {
+    this.widgetAction?.('my_action', { data: 'example' });
+  }
+}
+
+// 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: `
+    <ng-template #myTemplate let-widget let-emitAction="emitAction">
+      <div class="my-widget">
+        <h3>{{ widget.title }}</h3>
+        <button (click)="emitAction('my_action', { data: 'example' })">
+          Action
+        </button>
+      </div>
+    </ng-template>
+  `
+})
+export class AppComponent implements OnInit {
+  @ViewChild('myTemplate', { static: true }) myTemplate!: TemplateRef<WidgetTemplateContext>;
+
+  ngOnInit() {
+    this.widgetRegistry.registerRenderer('myWidget', this.myTemplate);
+  }
+}
+```
+
+See [EXAMPLES.md](./EXAMPLES.md) for detailed examples and best practices.
+
+## License
+
+MIT
+
+## Repository
+
+https://github.com/JeanMarcMbouma/BbQ.ChatWidgets