@m6d/cortex-angular 0.7.0 → 0.9.0

package/README.md

@@ -51,6 +51,135 @@ 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 parts
+
+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 { NgTemplateOutlet } from '@angular/common';
+import { CortexChatWidgetComponent, CortexSlotDirective } from '@m6d/cortex-angular';
+
+@Component({
+  imports: [CortexChatWidgetComponent, CortexSlotDirective, NgTemplateOutlet],
+  template: `
+    <cortex-chat-widget [config]="config">
+      <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>
+          } @else {
+            <button class="cortex-widget__header-btn" (click)="chat.openHistory()">☰</button>
+          }
+          <div class="cortex-widget__chat-title-wrap">
+            <p class="cortex-widget__chat-title">{{ chat.title ?? chat.agentName }}</p>
+          </div>
+          <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                                              |
+| `openHistory`  | `() => void`          | Shows the history: its screen, or the sidebar in full mode     |
+| `closeHistory` | `() => void`          | Returns to the open chat                                       |
+| `toggleDebug`  | `() => void`          | Switches debug mode                                            |
+
+### `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
+
+Every token in `theme.css` can be overridden on `:root` or on any ancestor of
+the widget. Beside the colors, radius and `--cortex-font-size`, four tokens
+ship unset and fall back when you leave them out:
+
+| Token                            | Falls back to               | Styles                               |
+| -------------------------------- | --------------------------- | ------------------------------------ |
+| `--cortex-font-size-message`     | `--cortex-font-size`        | Message bubbles and the composer     |
+| `--cortex-font-size-header`      | `--cortex-font-size`        | The chat and history titles          |
+| `--cortex-color-send-empty`      | `transparent`               | The send button with nothing to send |
+| `--cortex-color-send-empty-text` | `--cortex-color-text-muted` | Its icon                             |
+
+The composer resets its own focus and disabled styles, so a host's global
+`textarea:focus` ring or disabled fill does not reach it.
+
+## Tables
+
+A markdown table in an answer scrolls sideways instead of squeezing its
+columns. Once it has finished arriving, hovering it (or focusing into it)
+shows two actions at its top end: expand, which opens it in a dialog with room
+for every column, and export, which downloads it as an `.xlsx` file. Numbers
+export as numbers; the header row is bold.
+
 ## Client tools
 
 Control-Center tools published with type "embedded" render inside the chat