@copilotkitnext/angular 0.0.6 → 0.0.8

package/README.md

@@ -124,6 +124,104 @@ export class AppComponent {
 
 - If `agentId` is omitted, the component uses the default agent (ID: `default`)
 
+## Custom Input Components (Angular)
+
+When building custom input components for CopilotKit Angular, use the service-based pattern with `CopilotChatConfigurationService` for message submission. This is the idiomatic Angular approach leveraging dependency injection.
+
+### Service-Based Custom Input Example:
+
+```typescript
+import { Component } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { CopilotChatConfigurationService } from '@copilotkitnext/angular';
+
+@Component({
+  selector: 'my-custom-input',
+  standalone: true,
+  imports: [FormsModule],
+  template: `
+    <div class="custom-input-wrapper">
+      <input 
+        [(ngModel)]="inputValue"
+        (keyup.enter)="submitMessage()"
+        placeholder="Type your message..."
+      />
+      <button (click)="submitMessage()">Send</button>
+    </div>
+  `
+})
+export class MyCustomInputComponent {
+  inputValue = '';
+  
+  constructor(private chat: CopilotChatConfigurationService) {}
+  
+  submitMessage() {
+    const value = this.inputValue.trim();
+    if (value) {
+      // Use the service to submit the message
+      this.chat.submitInput(value);
+      this.inputValue = '';
+    }
+  }
+}
+```
+
+### Using the Custom Input Component:
+
+```typescript
+import { Component } from '@angular/core';
+import { CopilotChatViewComponent } from '@copilotkitnext/angular';
+import { MyCustomInputComponent } from './my-custom-input.component';
+
+@Component({
+  selector: 'app-chat',
+  standalone: true,
+  imports: [CopilotChatViewComponent],
+  template: `
+    <copilot-chat-view
+      [messages]="messages"
+      [inputComponent]="customInputComponent">
+    </copilot-chat-view>
+  `
+})
+export class ChatComponent {
+  messages = [];
+  customInputComponent = MyCustomInputComponent;
+}
+```
+
+### Key Points:
+
+- **No callback props**: Unlike React which uses `onSubmitMessage` callbacks, Angular uses dependency injection
+- **Service injection**: Inject `CopilotChatConfigurationService` to access `submitInput()`
+- **Cross-component communication**: The service handles message submission internally
+- **Type safety**: Full TypeScript support with proper type inference
+
+### Alternative: Using the Chat Config Directive
+
+For template-level hooks, you can also use the `copilotkitChatConfig` directive:
+
+```html
+<div [copilotkitChatConfig]="{ 
+  onSubmitInput: handleSubmit,
+  onChangeInput: handleChange 
+}">
+  <copilot-chat></copilot-chat>
+</div>
+```
+
+```typescript
+export class ChatComponent {
+  handleSubmit = (value: string) => {
+    console.log('Message submitted:', value);
+  };
+  
+  handleChange = (value: string) => {
+    console.log('Input changed:', value);
+  };
+}
+```
+
 ## Agents 101 (AG-UI)
 
 - **Agent model**: CopilotKit uses AG-UI's `AbstractAgent` interface (package `@ag-ui/client`)
@@ -205,6 +303,190 @@ console.log(
 - **`provideCopilotKit(...)`**: Set runtime URL, headers, properties, agents, tools, human-in-the-loop handlers
 - **`provideCopilotChatConfiguration(...)`**: Set UI labels and behavior for chat input/view
 
+## Headless Usage: Building Custom Chat UIs
+
+For advanced use cases where you need full control over the chat UI, you can use the `watchAgent` utility directly to build a custom chat component.
+
+### Using `watchAgent` for Custom Components
+
+The `watchAgent` function provides reactive signals for agent state, making it easy to build custom chat interfaces:
+
+```typescript
+import { Component, effect } from "@angular/core";
+import { watchAgent } from "@copilotkitnext/angular";
+
+@Component({
+  selector: "my-custom-chat",
+  template: `
+    <div class="custom-chat">
+      <div *ngFor="let msg of messages()" class="message">
+        {{ msg.content }}
+      </div>
+      <input
+        [disabled]="isRunning()"
+        (keyup.enter)="sendMessage($event)"
+      />
+    </div>
+  `,
+})
+export class MyCustomChatComponent {
+  protected agent!: ReturnType<typeof watchAgent>["agent"];
+  protected messages!: ReturnType<typeof watchAgent>["messages"];
+  protected isRunning!: ReturnType<typeof watchAgent>["isRunning"];
+
+  constructor() {
+    const w = watchAgent({ agentId: "custom" });
+    this.agent = w.agent;
+    this.messages = w.messages;
+    this.isRunning = w.isRunning;
+
+    // React to agent changes
+    effect(() => {
+      const currentAgent = this.agent();
+      if (currentAgent) {
+        console.log("Agent ready:", currentAgent.id);
+      }
+    });
+  }
+
+  async sendMessage(event: Event) {
+    const input = event.target as HTMLInputElement;
+    const content = input.value.trim();
+    if (!content || !this.agent()) return;
+
+    // Add user message and run agent
+    this.agent()!.addMessage({ role: "user", content });
+    input.value = "";
+    await this.agent()!.runAgent();
+  }
+}
+```
+
+### Switching Agents at Runtime
+
+Use `watchAgentWith` when you need to switch agents dynamically outside of the constructor:
+
+```typescript
+import { Component, Injector } from "@angular/core";
+import { watchAgent, watchAgentWith } from "@copilotkitnext/angular";
+
+@Component({
+  selector: "agent-switcher",
+  template: `
+    <button (click)="switchToAgent('sales')">Sales Agent</button>
+    <button (click)="switchToAgent('support')">Support Agent</button>
+    <div>Current Agent: {{ agent()?.id || 'None' }}</div>
+  `,
+})
+export class AgentSwitcherComponent {
+  protected agent!: ReturnType<typeof watchAgent>["agent"];
+  protected messages!: ReturnType<typeof watchAgent>["messages"];
+  protected isRunning!: ReturnType<typeof watchAgent>["isRunning"];
+  private watcher?: ReturnType<typeof watchAgent>;
+
+  constructor(private injector: Injector) {
+    // Initialize with default agent
+    this.switchToAgent("default");
+  }
+
+  switchToAgent(agentId: string) {
+    // Clean up previous watcher
+    this.watcher?.unsubscribe();
+
+    // Create new watcher with the ergonomic helper
+    const w = watchAgentWith(this.injector, { agentId });
+
+    // Update component signals
+    this.agent = w.agent;
+    this.messages = w.messages;
+    this.isRunning = w.isRunning;
+    this.watcher = w;
+  }
+}
+```
+
+### Rendering Tool Calls (Headless)
+
+To render tool calls in a headless UI, register renderers in your providers and drop the lightweight view in your template.
+
+1) Register tool renderers (e.g., a wildcard that renders any tool):
+
+```ts
+import { ApplicationConfig, importProvidersFrom } from '@angular/core';
+import { BrowserModule } from '@angular/platform-browser';
+import { provideCopilotKit } from '@copilotkitnext/angular';
+
+// Simple demo renderer (Component or TemplateRef accepted)
+@Component({
+  standalone: true,
+  template: `
+    <div style="padding:12px;border:1px solid #e5e7eb;border-radius:8px;background:#fff;margin:8px 0;">
+      <div style="font-weight:600;margin-bottom:6px;">Tool: {{ name }}</div>
+      <pre style="margin:0;white-space:pre-wrap;">{{ args | json }}</pre>
+      <div *ngIf="result" style="margin-top:6px;">Result: {{ result }}</div>
+    </div>
+  `,
+})
+export class WildcardToolRenderComponent {
+  @Input() name!: string;
+  @Input() args: any;
+  @Input() status: any;
+  @Input() result?: string;
+}
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    importProvidersFrom(BrowserModule),
+    ...provideCopilotKit({
+      renderToolCalls: [
+        { name: '*', render: WildcardToolRenderComponent },
+      ],
+    }),
+  ],
+};
+```
+
+2) Render tool calls under assistant messages using the headless view component:
+
+```ts
+import { Component } from '@angular/core';
+import { watchAgent, CopilotChatToolCallsViewComponent } from '@copilotkitnext/angular';
+
+@Component({
+  standalone: true,
+  imports: [CopilotChatToolCallsViewComponent],
+  template: `
+    <div *ngFor="let m of messages()">
+      <div>{{ m.role }}: {{ m.content }}</div>
+      <ng-container *ngIf="m.role === 'assistant'">
+        <copilot-chat-tool-calls-view
+          [message]="m"
+          [messages]="messages()"
+          [isLoading]="isRunning()"
+        />
+      </ng-container>
+    </div>
+  `,
+})
+export class HeadlessWithToolsComponent {
+  agent = watchAgent().agent;
+  messages = watchAgent().messages;
+  isRunning = watchAgent().isRunning;
+}
+```
+
+Notes:
+- If you prefer full manual control, you can render a specific tool call with `CopilotKitToolRenderComponent` and pass `toolName`, `args`, `status`, and `result` yourself.
+- You can also register tool renders declaratively via the `CopilotKitFrontendToolDirective` by using `[copilotkitFrontendTool]` in templates.
+
+### Key Benefits of Headless Usage
+
+- **Full control**: Build any UI you need without constraints
+- **Reactive signals**: Automatically update UI when agent state changes
+- **Type safety**: Full TypeScript support with AG-UI types
+- **Memory efficient**: Automatic cleanup via Angular's DestroyRef
+- **Framework agnostic**: Works with any AG-UI compatible agent
+
 ## End-to-End: Running the Demo
 
 From the repo root:

package/dist/README.md

@@ -124,6 +124,104 @@ export class AppComponent {
 
 - If `agentId` is omitted, the component uses the default agent (ID: `default`)
 
+## Custom Input Components (Angular)
+
+When building custom input components for CopilotKit Angular, use the service-based pattern with `CopilotChatConfigurationService` for message submission. This is the idiomatic Angular approach leveraging dependency injection.
+
+### Service-Based Custom Input Example:
+
+```typescript
+import { Component } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { CopilotChatConfigurationService } from '@copilotkitnext/angular';
+
+@Component({
+  selector: 'my-custom-input',
+  standalone: true,
+  imports: [FormsModule],
+  template: `
+    <div class="custom-input-wrapper">
+      <input 
+        [(ngModel)]="inputValue"
+        (keyup.enter)="submitMessage()"
+        placeholder="Type your message..."
+      />
+      <button (click)="submitMessage()">Send</button>
+    </div>
+  `
+})
+export class MyCustomInputComponent {
+  inputValue = '';
+  
+  constructor(private chat: CopilotChatConfigurationService) {}
+  
+  submitMessage() {
+    const value = this.inputValue.trim();
+    if (value) {
+      // Use the service to submit the message
+      this.chat.submitInput(value);
+      this.inputValue = '';
+    }
+  }
+}
+```
+
+### Using the Custom Input Component:
+
+```typescript
+import { Component } from '@angular/core';
+import { CopilotChatViewComponent } from '@copilotkitnext/angular';
+import { MyCustomInputComponent } from './my-custom-input.component';
+
+@Component({
+  selector: 'app-chat',
+  standalone: true,
+  imports: [CopilotChatViewComponent],
+  template: `
+    <copilot-chat-view
+      [messages]="messages"
+      [inputComponent]="customInputComponent">
+    </copilot-chat-view>
+  `
+})
+export class ChatComponent {
+  messages = [];
+  customInputComponent = MyCustomInputComponent;
+}
+```
+
+### Key Points:
+
+- **No callback props**: Unlike React which uses `onSubmitMessage` callbacks, Angular uses dependency injection
+- **Service injection**: Inject `CopilotChatConfigurationService` to access `submitInput()`
+- **Cross-component communication**: The service handles message submission internally
+- **Type safety**: Full TypeScript support with proper type inference
+
+### Alternative: Using the Chat Config Directive
+
+For template-level hooks, you can also use the `copilotkitChatConfig` directive:
+
+```html
+<div [copilotkitChatConfig]="{ 
+  onSubmitInput: handleSubmit,
+  onChangeInput: handleChange 
+}">
+  <copilot-chat></copilot-chat>
+</div>
+```
+
+```typescript
+export class ChatComponent {
+  handleSubmit = (value: string) => {
+    console.log('Message submitted:', value);
+  };
+  
+  handleChange = (value: string) => {
+    console.log('Input changed:', value);
+  };
+}
+```
+
 ## Agents 101 (AG-UI)
 
 - **Agent model**: CopilotKit uses AG-UI's `AbstractAgent` interface (package `@ag-ui/client`)
@@ -205,6 +303,190 @@ console.log(
 - **`provideCopilotKit(...)`**: Set runtime URL, headers, properties, agents, tools, human-in-the-loop handlers
 - **`provideCopilotChatConfiguration(...)`**: Set UI labels and behavior for chat input/view
 
+## Headless Usage: Building Custom Chat UIs
+
+For advanced use cases where you need full control over the chat UI, you can use the `watchAgent` utility directly to build a custom chat component.
+
+### Using `watchAgent` for Custom Components
+
+The `watchAgent` function provides reactive signals for agent state, making it easy to build custom chat interfaces:
+
+```typescript
+import { Component, effect } from "@angular/core";
+import { watchAgent } from "@copilotkitnext/angular";
+
+@Component({
+  selector: "my-custom-chat",
+  template: `
+    <div class="custom-chat">
+      <div *ngFor="let msg of messages()" class="message">
+        {{ msg.content }}
+      </div>
+      <input
+        [disabled]="isRunning()"
+        (keyup.enter)="sendMessage($event)"
+      />
+    </div>
+  `,
+})
+export class MyCustomChatComponent {
+  protected agent!: ReturnType<typeof watchAgent>["agent"];
+  protected messages!: ReturnType<typeof watchAgent>["messages"];
+  protected isRunning!: ReturnType<typeof watchAgent>["isRunning"];
+
+  constructor() {
+    const w = watchAgent({ agentId: "custom" });
+    this.agent = w.agent;
+    this.messages = w.messages;
+    this.isRunning = w.isRunning;
+
+    // React to agent changes
+    effect(() => {
+      const currentAgent = this.agent();
+      if (currentAgent) {
+        console.log("Agent ready:", currentAgent.id);
+      }
+    });
+  }
+
+  async sendMessage(event: Event) {
+    const input = event.target as HTMLInputElement;
+    const content = input.value.trim();
+    if (!content || !this.agent()) return;
+
+    // Add user message and run agent
+    this.agent()!.addMessage({ role: "user", content });
+    input.value = "";
+    await this.agent()!.runAgent();
+  }
+}
+```
+
+### Switching Agents at Runtime
+
+Use `watchAgentWith` when you need to switch agents dynamically outside of the constructor:
+
+```typescript
+import { Component, Injector } from "@angular/core";
+import { watchAgent, watchAgentWith } from "@copilotkitnext/angular";
+
+@Component({
+  selector: "agent-switcher",
+  template: `
+    <button (click)="switchToAgent('sales')">Sales Agent</button>
+    <button (click)="switchToAgent('support')">Support Agent</button>
+    <div>Current Agent: {{ agent()?.id || 'None' }}</div>
+  `,
+})
+export class AgentSwitcherComponent {
+  protected agent!: ReturnType<typeof watchAgent>["agent"];
+  protected messages!: ReturnType<typeof watchAgent>["messages"];
+  protected isRunning!: ReturnType<typeof watchAgent>["isRunning"];
+  private watcher?: ReturnType<typeof watchAgent>;
+
+  constructor(private injector: Injector) {
+    // Initialize with default agent
+    this.switchToAgent("default");
+  }
+
+  switchToAgent(agentId: string) {
+    // Clean up previous watcher
+    this.watcher?.unsubscribe();
+
+    // Create new watcher with the ergonomic helper
+    const w = watchAgentWith(this.injector, { agentId });
+
+    // Update component signals
+    this.agent = w.agent;
+    this.messages = w.messages;
+    this.isRunning = w.isRunning;
+    this.watcher = w;
+  }
+}
+```
+
+### Rendering Tool Calls (Headless)
+
+To render tool calls in a headless UI, register renderers in your providers and drop the lightweight view in your template.
+
+1) Register tool renderers (e.g., a wildcard that renders any tool):
+
+```ts
+import { ApplicationConfig, importProvidersFrom } from '@angular/core';
+import { BrowserModule } from '@angular/platform-browser';
+import { provideCopilotKit } from '@copilotkitnext/angular';
+
+// Simple demo renderer (Component or TemplateRef accepted)
+@Component({
+  standalone: true,
+  template: `
+    <div style="padding:12px;border:1px solid #e5e7eb;border-radius:8px;background:#fff;margin:8px 0;">
+      <div style="font-weight:600;margin-bottom:6px;">Tool: {{ name }}</div>
+      <pre style="margin:0;white-space:pre-wrap;">{{ args | json }}</pre>
+      <div *ngIf="result" style="margin-top:6px;">Result: {{ result }}</div>
+    </div>
+  `,
+})
+export class WildcardToolRenderComponent {
+  @Input() name!: string;
+  @Input() args: any;
+  @Input() status: any;
+  @Input() result?: string;
+}
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    importProvidersFrom(BrowserModule),
+    ...provideCopilotKit({
+      renderToolCalls: [
+        { name: '*', render: WildcardToolRenderComponent },
+      ],
+    }),
+  ],
+};
+```
+
+2) Render tool calls under assistant messages using the headless view component:
+
+```ts
+import { Component } from '@angular/core';
+import { watchAgent, CopilotChatToolCallsViewComponent } from '@copilotkitnext/angular';
+
+@Component({
+  standalone: true,
+  imports: [CopilotChatToolCallsViewComponent],
+  template: `
+    <div *ngFor="let m of messages()">
+      <div>{{ m.role }}: {{ m.content }}</div>
+      <ng-container *ngIf="m.role === 'assistant'">
+        <copilot-chat-tool-calls-view
+          [message]="m"
+          [messages]="messages()"
+          [isLoading]="isRunning()"
+        />
+      </ng-container>
+    </div>
+  `,
+})
+export class HeadlessWithToolsComponent {
+  agent = watchAgent().agent;
+  messages = watchAgent().messages;
+  isRunning = watchAgent().isRunning;
+}
+```
+
+Notes:
+- If you prefer full manual control, you can render a specific tool call with `CopilotKitToolRenderComponent` and pass `toolName`, `args`, `status`, and `result` yourself.
+- You can also register tool renders declaratively via the `CopilotKitFrontendToolDirective` by using `[copilotkitFrontendTool]` in templates.
+
+### Key Benefits of Headless Usage
+
+- **Full control**: Build any UI you need without constraints
+- **Reactive signals**: Automatically update UI when agent state changes
+- **Type safety**: Full TypeScript support with AG-UI types
+- **Memory efficient**: Automatic cleanup via Angular's DestroyRef
+- **Framework agnostic**: Works with any AG-UI compatible agent
+
 ## End-to-End: Running the Demo
 
 From the repo root:

package/dist/components/chat/copilot-chat.component.d.ts

@@ -1,4 +1,4 @@
-import { OnInit, OnChanges, OnDestroy, SimpleChanges, ChangeDetectorRef, Signal, Injector } from "@angular/core";
+import { OnInit, OnChanges, SimpleChanges, ChangeDetectorRef, Signal, Injector, Type } from "@angular/core";
 import { CopilotChatConfigurationService } from "../../core/chat-configuration/chat-configuration.service";
 import { Message, AbstractAgent } from "@ag-ui/client";
 import * as i0 from "@angular/core";
@@ -11,27 +11,26 @@ import * as i0 from "@angular/core";
  * <copilot-chat [agentId]="'default'" [threadId]="'abc123'"></copilot-chat>
  * ```
  */
-export declare class CopilotChatComponent implements OnInit, OnChanges, OnDestroy {
+export declare class CopilotChatComponent implements OnInit, OnChanges {
     private chatConfig;
     private cdr;
     private injector;
     agentId?: string;
     threadId?: string;
+    inputComponent?: Type<any>;
     constructor(chatConfig: CopilotChatConfigurationService | null, cdr: ChangeDetectorRef, injector: Injector);
     protected agent: Signal<AbstractAgent | undefined>;
     protected messages: Signal<Message[]>;
     protected isRunning: Signal<boolean>;
     protected showCursor: import("@angular/core").WritableSignal<boolean>;
     private generatedThreadId;
-    private agentWatcher?;
+    private watcher?;
     private hasConnectedOnce;
-    private lastAgentId?;
     ngOnInit(): void;
     ngOnChanges(changes: SimpleChanges): void;
     private connectToAgent;
     private setupChatHandlers;
-    ngOnDestroy(): void;
     private createWatcher;
     static ɵfac: i0.ɵɵFactoryDeclaration<CopilotChatComponent, [{ optional: true; }, null, null]>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<CopilotChatComponent, "copilot-chat", never, { "agentId": { "alias": "agentId"; "required": false; }; "threadId": { "alias": "threadId"; "required": false; }; }, {}, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<CopilotChatComponent, "copilot-chat", never, { "agentId": { "alias": "agentId"; "required": false; }; "threadId": { "alias": "threadId"; "required": false; }; "inputComponent": { "alias": "inputComponent"; "required": false; }; }, {}, never, never, true, never>;
 }