@m6d/cortex-angular 0.8.0 → 0.9.0

package/README.md

@@ -51,20 +51,23 @@ No root-level providers needed — each widget instance is fully self-contained.
 
 `transport.getHeaders` can return any request headers needed by the host app. WebSocket auth continues to derive the `token` query param from a bearer `Authorization` header when present.
 
-## Custom header
+## Custom parts
 
-Put an `ng-template` marked `cortexHeader` inside the widget to replace its
-header. It replaces the default on both screens, the chat and the history, and
-receives one context with the widget's state and actions:
+Put an `ng-template` marked `cortexSlot` inside the widget to draw one of its
+parts yourself: `header`, `landing` (the blank chat) or `threadList` (the
+history's list). Each replaces the widget's default and receives the same
+context the default is drawn from, typed by the slot name. Use only the slots
+you need:
 
 ```ts
-import { CortexChatWidgetComponent, CortexHeaderDirective } from '@m6d/cortex-angular';
+import { NgTemplateOutlet } from '@angular/common';
+import { CortexChatWidgetComponent, CortexSlotDirective } from '@m6d/cortex-angular';
 
 @Component({
-  imports: [CortexChatWidgetComponent, CortexHeaderDirective],
+  imports: [CortexChatWidgetComponent, CortexSlotDirective, NgTemplateOutlet],
   template: `
     <cortex-chat-widget [config]="config">
-      <ng-template cortexHeader let-chat>
+      <ng-template cortexSlot="header" let-chat>
         <div class="cortex-widget__chat-header">
           @if (chat.screen === 'threads') {
             <button class="cortex-widget__header-btn" (click)="chat.closeHistory()">←</button>
@@ -77,17 +80,49 @@ import { CortexChatWidgetComponent, CortexHeaderDirective } from '@m6d/cortex-an
           <button class="cortex-widget__header-btn" (click)="chat.newChat()">+</button>
         </div>
       </ng-template>
+
+      <ng-template cortexSlot="landing" let-landing>
+        <div class="cortex-widget__landing">
+          <h1>{{ landing.greeting }}</h1>
+          @for (suggestion of landing.suggestions; track $index) {
+            <button (click)="landing.send(suggestion.prompt)">{{ suggestion.title }}</button>
+          }
+          <ng-container *ngTemplateOutlet="landing.composer" />
+        </div>
+      </ng-template>
+
+      <ng-template cortexSlot="threadList" let-list>
+        <div class="cortex-widget__threads-list">
+          @for (thread of list.threads; track thread.id) {
+            <button (click)="list.openThread(thread)">{{ thread.title }}</button>
+          }
+        </div>
+      </ng-template>
     </cortex-chat-widget>
   `,
 })
 ```
 
+A slot replaces the whole part, so its root sits where the default's did: in
+the chat or history screen's column, under the header. The defaults' classes
+are there to reuse: `cortex-widget__chat-header`, `cortex-widget__chat-title`
+and `cortex-widget__header-btn` for a header, `cortex-widget__landing` for a
+centered landing, `cortex-widget__threads-list` for a scrolling list. Utility
+classes such as Tailwind's apply inside the widget; its own reset sits in
+`@layer base.cortex`, below them. `ThreadSummary` and `Suggestion` are exported
+for typing your own rows and chips.
+
+### `header`
+
+One header serves both screens; `screen` says which is showing.
+
 | Field          | Type                  | Description                                                    |
 | -------------- | --------------------- | -------------------------------------------------------------- |
 | `screen`       | `'chat' \| 'threads'` | Which screen the header is on                                  |
 | `viewMode`     | `'helper' \| 'full'`  | The configured view mode                                       |
 | `title`        | `string \| null`      | The open thread's title; `null` on a new chat                  |
 | `agentName`    | `string \| undefined` | `agentName` in the widget's locale                             |
+| `threadCount`  | `number`              | How many conversations the history lists; 0 while it loads     |
 | `isWorking`    | `boolean`             | The agent is answering                                         |
 | `debug`        | `{ shown, on }`       | Whether `showDebugButton` is set, and whether debug mode is on |
 | `newChat`      | `() => void`          | Starts a new chat                                              |
@@ -95,9 +130,31 @@ import { CortexChatWidgetComponent, CortexHeaderDirective } from '@m6d/cortex-an
 | `closeHistory` | `() => void`          | Returns to the open chat                                       |
 | `toggleDebug`  | `() => void`          | Switches debug mode                                            |
 
-The default header's classes are there to reuse: `cortex-widget__chat-header`
-for the bar, `cortex-widget__chat-title` for the title, and
-`cortex-widget__header-btn` for its quiet icon buttons.
+### `landing`
+
+Shown while no thread is open. The first send opens a thread and swaps the
+landing for it.
+
+| Field         | Type                              | Description                                                                                             |
+| ------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `greeting`    | `string`                          | The agent's greeting in the widget's locale, or the built-in one                                        |
+| `suggestions` | `{ title, prompt }[]`             | Empty until the handshake answers, and for an agent that takes no messages                              |
+| `threads`     | `ThreadSummary[] \| undefined`    | Newest first; `undefined` while the first load is out                                                   |
+| `composer`    | `TemplateRef`                     | The widget's composer, or its "messages disabled" notice; place it with `ngTemplateOutlet`              |
+| `send`        | `(prompt: string) => void`        | Sends a first message; does nothing until the handshake answers, or for an agent that takes no messages |
+| `openThread`  | `(thread: ThreadSummary) => void` | Opens a thread                                                                                          |
+
+### `threadList`
+
+The history's list. Its header is the `header` slot.
+
+| Field              | Type                              | Description                                           |
+| ------------------ | --------------------------------- | ----------------------------------------------------- |
+| `threads`          | `ThreadSummary[] \| undefined`    | Newest first; `undefined` while the first load is out |
+| `selectedThreadId` | `string \| undefined`             | The open thread's id; `undefined` on a new chat       |
+| `openThread`       | `(thread: ThreadSummary) => void` | Opens a thread                                        |
+| `deleteThread`     | `(threadId: string) => void`      | Deletes a thread                                      |
+| `newChat`          | `() => void`                      | Starts a new chat                                     |
 
 ## Theming