feat(ai-chat): add inline source citation

Author: robertwilde

api-goldens/element-ng/chat-messages/index.api.md

@@ -57,6 +57,8 @@ export class SiAiMessageComponent {
     constructor();
     readonly actionParam: _angular_core.InputSignal<unknown>;
     readonly actions: _angular_core.InputSignal<MessageAction[]>;
+    readonly annotatedText: _angular_core.InputSignal<SiChatAnnotatedText | undefined>;
+    readonly citationClicked: _angular_core.OutputEmitterRef<SiChatCitation>;
     readonly content: _angular_core.InputSignal<string>;
     readonly contentFormatter: _angular_core.InputSignal<((text: string) => string | Node) | undefined>;
     readonly loading: _angular_core.InputSignalWithTransform<boolean, unknown>;
@@ -81,6 +83,27 @@ export class SiAttachmentListComponent {
     readonly removeLabel: _angular_core.InputSignal<_siemens_element_translate_ng_translate.TranslatableString>;
 }
 
+// @public
+export interface SiChatAnnotatedText {
+    citations: SiChatCitation[];
+    segments: SiChatTextSegment[];
+}
+
+// @public
+export interface SiChatCitation {
+    id: string;
+    title: string;
+    url?: string;
+}
+
+// @public
+export interface SiChatCitationRun {
+    // (undocumented)
+    citationId: string;
+    // (undocumented)
+    type: 'citation';
+}
+
 // @public
 export class SiChatContainerComponent implements AfterContentInit, OnDestroy {
     constructor();
@@ -143,6 +166,25 @@ export class SiChatMessageComponent {
     readonly loading: _angular_core.InputSignal<boolean>;
 }
 
+// @public
+export interface SiChatTextRun {
+    // (undocumented)
+    content: string;
+    // (undocumented)
+    type: 'text';
+}
+
+// @public (undocumented)
+export type SiChatTextSegment = SiChatTextRun | SiChatCitationRun;
+
+// @public
+export class SiCitationPillComponent {
+    readonly citation: _angular_core.InputSignal<SiChatCitation>;
+    readonly clicked: _angular_core.OutputEmitterRef<SiChatCitation>;
+    readonly icon: _angular_core.InputSignal<string | undefined>;
+    readonly label: _angular_core.InputSignal<_siemens_element_translate_ng_translate.TranslatableString>;
+}
+
 // @public
 export class SiUserMessageComponent {
     constructor();

playwright/snapshots/static.spec.ts-snapshots/si-chat-messages--si-ai-message-element-examples-chromium-dark-linux.png

@@ -4,25 +4,27 @@
   - button "dataset.csv"
 - paragraph: Can you help me analyze these files?
 - paragraph: I'm having trouble understanding the data structure and need assistance with the implementation.
-- group:
-  - button "Export message"
-- paragraph: I'd be happy to help you analyze your files! I can see you've shared a Python script and a CSV dataset.
-- paragraph: Let me examine the structure and provide guidance.
-- group:
-  - button "Good response"
-  - button "Bad response"
-  - button "Copy response"
-  - button "More actions"
+- button "Export message"
+- text: I'd be happy to help! Data processing pipelines typically follow a structured approach.
+- link "Data Pipeline Design Patterns":
+  - /url: https://martinfowler.com/articles/data-pipeline.html
+  - text: ""
+- text: Let me examine your files and provide detailed guidance.
+- button "Add to list"
+- button "Export response"
+- button "Retry response"
+- button "More actions"
 - paragraph: Perfect! What should I focus on first
 - paragraph: I also want to make sure the performance is optimized for large datasets since this will be used in production with potentially millions of rows?
-- group:
-  - button "Export message"
-- paragraph: Great question! When analyzing large datasets, it's crucial to focus on...
-- group:
-  - button "Good response"
-  - button "Bad response"
-  - button "Copy response"
-  - button "More actions"
+- button "Export message"
+- text: Great question! When analyzing large datasets, it's crucial to focus on vectorized operations and avoid row-by-row iteration.
+- link "Pandas Performance Guide":
+  - /url: https://pandas.pydata.org/docs/user_guide/enhancingperf.html
+  - text: Source for this paragraph.
+- button "Add to list"
+- button "Export response"
+- button "Retry response"
+- button "More actions"
 - alert: Info AI responses are for demonstration purposes.
 - group:
   - text: requirements.pdf
@@ -32,8 +34,8 @@
   - button "Remove attachment mockup.png"
 - textbox "Chat message input":
   - /placeholder: Enter a command, question or topic...
-- group:
-  - button "More actions"
-  - button "Show Welcome Screen"
+- button "Attach file"
+- button "Clear messages"
+- button "Show Welcome Screen"
 - button "Send"
 - text: The content is AI generated. Always verify the information for accuracy.

playwright/snapshots/static.spec.ts-snapshots/si-chat-messages--si-ai-message-element-examples-chromium-light-linux.png

@@ -3,7 +3,9 @@
  * SPDX-License-Identifier: MIT
  */
 export * from './si-ai-message.component';
+export * from './si-annotated-text.model';
 export * from './si-attachment-list.component';
+export * from './si-citation-pill.component';
 export * from './si-chat-container.component';
 export * from './si-chat-container-input.directive';
 export * from './si-chat-input.component';

playwright/snapshots/static.spec.ts-snapshots/si-chat-messages--si-chat-container-element-examples-chromium-dark-linux.png

@@ -1,5 +1,18 @@
 <si-chat-message alignment="start" actionsPosition="bottom" [loading]="loading()">
-  @if (content()) {
+  @if (annotatedText(); as annotated) {
+    <span class="annotated-content text-pre-wrap">
+      @for (segment of annotated.segments; track $index) {
+        @if (segment.type === 'text') {
+          <span>{{ segment.content }}</span>
+        } @else {
+          <si-citation-pill
+            [citation]="getCitation(segment.citationId)"
+            (clicked)="citationClicked.emit($event)"
+          /><br />
+        }
+      }
+    </span>
+  } @else if (content()) {
     @let content = textContent();
     @if (content) {
       <span class="text-pre-wrap">{{ content }}</span>

playwright/snapshots/static.spec.ts-snapshots/si-chat-messages--si-chat-container-element-examples-chromium-light-linux.png

@@ -18,6 +18,10 @@ si-chat-message {
   margin-block-start: map.get(variables.$spacers, 5) - map.get(variables.$spacers, 2);
 }
 
+.annotated-content {
+  line-height: 20px;
+}
+
 // Loading spinner size adjustment (inherited from generic component)
 :host ::ng-deep si-loading-spinner {
   --loading-spinner-size: 1.5em;

playwright/snapshots/static.spec.ts-snapshots/si-chat-messages--si-chat-container.yaml

@@ -8,6 +8,7 @@ import {
   Component,
   effect,
   input,
+  output,
   viewChild,
   ElementRef,
   signal
@@ -18,8 +19,10 @@ import { MenuItem, SiMenuFactoryComponent } from '@siemens/element-ng/menu';
 import { SiTranslatePipe, t } from '@siemens/element-translate-ng/translate';
 
 import { MessageAction } from './message-action.model';
+import { SiChatAnnotatedText, SiChatCitation } from './si-annotated-text.model';
 import { SiChatMessageActionDirective } from './si-chat-message-action.directive';
 import { SiChatMessageComponent } from './si-chat-message.component';
+import { SiCitationPillComponent } from './si-citation-pill.component';
 
 /**
  * AI message component for displaying AI-generated responses in conversational interfaces.
@@ -47,6 +50,7 @@ import { SiChatMessageComponent } from './si-chat-message.component';
   imports: [
     CdkMenuTrigger,
     SiChatMessageComponent,
+    SiCitationPillComponent,
     SiIconComponent,
     SiMenuFactoryComponent,
     SiChatMessageActionDirective,
@@ -59,6 +63,29 @@ export class SiAiMessageComponent {
   protected readonly formattedContent = viewChild<ElementRef<HTMLDivElement>>('formattedContent');
   protected readonly icons = addIcons({ elementOptionsVertical });
 
+  /**
+   * Pre-segmented annotated text containing inline citation references.
+   * When provided, takes precedence over the `content` input.
+   * Use `parseCitationMarkers` or `parseCitationOffsets` to produce this value.
+   * @defaultValue undefined
+   */
+  readonly annotatedText = input<SiChatAnnotatedText | undefined>(undefined);
+
+  /**
+   * Emitted when a citation pill inside the message is clicked.
+   * The emitted value is the {@link SiChatCitation} that was clicked.
+   */
+  readonly citationClicked = output<SiChatCitation>();
+
+  protected getCitation(id: string): SiChatCitation {
+    return (
+      this.annotatedText()?.citations.find(c => c.id === id) ?? {
+        id,
+        title: id
+      }
+    );
+  }
+
   /**
    * The AI-generated message content
    * @defaultValue ''