@luzmo/analytics-components-kit 1.0.8 → 1.0.9-beta.10

package/angular/components/ai-chat.ts

@@ -0,0 +1,447 @@
+import { booleanAttribute, ChangeDetectionStrategy, Component, DestroyRef, ElementRef, inject, Input, OnChanges, output, Renderer2, SimpleChanges } from '@angular/core';
+import '@luzmo/analytics-components-kit/ai-chat';
+import type { LuzmoAiChat as LuzmoAiChatHostElement, AiChatAgentConfig, AiChatCompleteEvent, AiChatConversationIdChangedEventDetail, AiChatDatasetsChangedEventDetail, AiChatEmptyStateSuggestion, AiChatMessageSentEventDetail, AiChatSession, AiChatStepEvent, AssistantMessageActionEventDetail } from '@luzmo/analytics-components-kit/ai-chat';
+export type { AgentStreamDefinition, AiChatAgentConfig, AiChatCompleteEvent, AiChatConversationIdChangedEventDetail, AiChatDatasetsChangedEventDetail, AiChatEmptyStateSuggestion, AiChatEmptyStateSuggestionSelectedDetail, AiChatMessageSentEventDetail, AiChatRecognizedStepType, AiChatSessionBuildContext, AiChatSessionCallbacks, AiChatSessionConfig, AiChatSessionControllerOptions, AiChatSessionRestoreParams, AiChatSessionRestoreResult, AiChatSessionSeed, AiChatSessionState, AiChatSessionSubmitParams, AiChatStepBase, AiChatStepEvent, AiDictationCreateBody, AiDictationProperties, AiPromptCreateBody, AiPromptDeleteBody, AssistantMessageAction, AssistantMessageActionConfirmVariant, AssistantMessageActionEventDetail, BuildAiDictationRequestOptions, ChatMessageElicitation, LuzmoPromptSubmittedEventDetail, LuzmoRestoreRequestedEventDetail, ProgressTreeNode, PromptBoxAttachment, PromptBoxFileIcons, RecognizedStepEvent, StreamAiDictationOptions, StreamHandlerCallbacks, StreamHandlerContext, StreamHandlerState, StreamingRequestOptions, StreamingResponse, UnknownStepEvent, UploadAiPromptImagesOptions } from '@luzmo/analytics-components-kit/ai-chat';
+import type { AiPromptAgent, AiPromptCustomItemInput, AiPromptItemTask, AiPromptScreenMode, DashboardStatePayload } from '@luzmo/analytics-components-kit/ai-chat';
+import type { ChatMessage, Dataset, LuzmoChart } from '@luzmo/analytics-components-kit/types';
+
+@Component({
+  selector: 'luzmo-ai-chat',
+  exportAs: 'luzmoAiChat',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: '<ng-content />'
+})
+/**
+ * Angular wrapper component for <luzmo-ai-chat>
+ */
+export class LuzmoAiChat implements OnChanges {
+  private readonly elementRef = inject<ElementRef<LuzmoAiChatHostElement>>(ElementRef);
+  private readonly renderer = inject<Renderer2>(Renderer2);
+  private readonly destroyRef = inject<DestroyRef>(DestroyRef);
+  private readonly host = this.elementRef.nativeElement;
+  private readonly listenerCleanup: Array<() => void> = [];
+
+  /** The underlying custom element instance. Use to call imperative methods. */
+  get nativeElement(): LuzmoAiChatHostElement {
+    return this.host;
+  }
+
+  /** Live transcript is AiChatSessionState.messages. This prop optionally seeds the session on first connect. */
+  @Input({ alias: 'messages' })
+  messages?: ChatMessage[];
+
+  /** Live selection is in the session. This prop optionally seeds on first connect. */
+  @Input({ alias: 'selectedDatasets' })
+  selectedDatasets?: Dataset[];
+
+  /** Placeholder text for the textarea */
+  @Input({ alias: 'placeholder' })
+  placeholder?: string;
+
+  /** When true, disables the entire chat interface */
+  @Input({ alias: 'disabled', transform: booleanAttribute })
+  disabled?: boolean;
+
+  /** When true, shows a stop control on the prompt input while a response is generating */
+  @Input({ alias: 'stoppable', transform: booleanAttribute })
+  stoppable?: boolean;
+
+  /** When true, shows context menu (3 dots) on assistant messages */
+  @Input({ alias: 'showAssistantContextMenu', transform: booleanAttribute })
+  showAssistantContextMenu?: boolean;
+
+  /** Auth key for DataBroker authentication */
+  @Input({ alias: 'authKey' })
+  authKey?: string;
+
+  /** Auth token for DataBroker authentication */
+  @Input({ alias: 'authToken' })
+  authToken?: string;
+
+  /** API URL for DataBroker */
+  @Input({ alias: 'apiUrl' })
+  apiUrl?: string;
+
+  /** The URL of the app server for thumbnails and assets */
+  @Input({ alias: 'appServer' })
+  appServer?: string;
+
+  /** When true, shows public datasets alongside the user's other datasets. */
+  @Input({ alias: 'includePublicDatasets', transform: booleanAttribute })
+  includePublicDatasets?: boolean;
+
+  /** Alias for includePublicDatasets. */
+  @Input({ alias: 'flagOpendata', transform: booleanAttribute })
+  flagOpendata?: boolean;
+
+  /** When true, hides the "+ Add dataset" button in the input */
+  @Input({ alias: 'hideDatasetButton', transform: booleanAttribute })
+  hideDatasetButton?: boolean;
+
+  /** When true, hides dataset icons in the input dataset selector and @ mention dataset headers */
+  @Input({ alias: 'hideDatasetIcons', transform: booleanAttribute })
+  hideDatasetIcons?: boolean;
+
+  /** When true, hides the add-dataset button and disables removing selected datasets while keeping pills visible */
+  @Input({ alias: 'disableDatasetModification', transform: booleanAttribute })
+  disableDatasetModification?: boolean;
+
+  /** When true, hides the dataset row and add-dataset button entirely */
+  @Input({ alias: 'hideSelectedDatasets', transform: booleanAttribute })
+  hideSelectedDatasets?: boolean;
+
+  /** When true, hides the Agents section in the input and runs prompts without a picked agent */
+  @Input({ alias: 'hideAgents', transform: booleanAttribute })
+  hideAgents?: boolean;
+
+  /** When true, disables @ trigger mentions for dataset fields in the input */
+  @Input({ alias: 'disableColumnMentions', transform: booleanAttribute })
+  disableColumnMentions?: boolean;
+
+  /** When true, a picked agent or at least one selected dataset is required before the prompt can be submitted */
+  @Input({ alias: 'requireDataset', transform: booleanAttribute })
+  requireDataset?: boolean;
+
+  /** Enables image attachments (PNG/JPEG/WebP/GIF). */
+  @Input({ alias: 'allowImages', transform: booleanAttribute })
+  allowImages?: boolean;
+
+  /** Enables mic dictation; audio is transcribed via `POST /aidictation` and inserted as editable text. */
+  @Input({ alias: 'allowVoiceInput', transform: booleanAttribute })
+  allowVoiceInput?: boolean;
+
+  /** Attachment MIME types/extensions. Defaults to PNG/JPEG/WebP/GIF when `allow-images` is set. */
+  @Input({ alias: 'acceptedFileTypes' })
+  acceptedFileTypes?: string[];
+
+  /** Optional upload override; otherwise uploads via `POST /upload` on attach. */
+  @Input({ alias: 'uploadAttachments' })
+  uploadAttachments?: unknown;
+
+  /** Which aiprompt agent to use (`item`, `dashboard`, `analyst` or `custom-item`). Determines request payload and stream handling. With `agent-id` set it no longer shapes the request payload, only stream handling. Custom-item hosts must set `hide-agents` and leave `agent-id` unset to preserve draft context and internal repair prompts. */
+  @Input({ alias: 'agent' })
+  agent?: AiPromptAgent;
+
+  /** Typed agent selection and context. Takes precedence over legacy agent, task and context properties. Omit context to preserve the same agent's session context; use null to clear it. Undefined leaves a host session's typed configuration intact and uses legacy properties for an internal session. */
+  @Input({ alias: 'agentConfig' })
+  agentConfig?: AiChatAgentConfig;
+
+  /** Saved Agent id (UUID) to run the prompt as. An agent picked in the prompt box takes precedence for that prompt. */
+  @Input({ alias: 'agentId' })
+  agentId?: string;
+
+  /** Task for the item agent (`generate`, `suggest`, `describe`). Ignored when `agent-id` is set. */
+  @Input({ alias: 'task' })
+  task?: AiPromptItemTask;
+
+  /** AI model preference for item agent chart generation */
+  @Input({ alias: 'modelPreference' })
+  modelPreference?: 'performance' | 'quality';
+
+  /** Host-owned AiChatSession. The component subscribes and renders; does not abort on disconnect. */
+  @Input({ alias: 'chatSession' })
+  chatSession?: AiChatSession | null;
+
+  /** Conversation ID (synced into the session; updated when the API returns a new id). */
+  @Input({ alias: 'conversationId' })
+  conversationId?: string | null;
+
+  /** Chart context for `agent="item"`. */
+  @Input({ alias: 'chart' })
+  chart?: LuzmoChart | null;
+
+  /** Dashboard context for `agent="dashboard"`. */
+  @Input({ alias: 'dashboard' })
+  dashboard?: DashboardStatePayload | null;
+
+  /** Draft context for `agent="custom-item"`, sent as its `custom-item` input. The host owns the shape: the chart document under `document`, plus fields such as `chartId`. With a host `chatSession`, the default null preserves its draft. Once this element supplies a draft, setting this property to null clears the session's custom item context. */
+  @Input({ alias: 'customItem' })
+  customItem?: AiPromptCustomItemInput['value'] | null;
+
+  /** Current screen mode when editing a dashboard. */
+  @Input({ alias: 'currentScreenMode' })
+  currentScreenMode?: AiPromptScreenMode;
+
+  /** Locale ID sent to the aiprompt API. */
+  @Input({ alias: 'localeId' })
+  localeId?: string;
+
+  /** Timezone ID for dashboard agent requests. */
+  @Input({ alias: 'timezoneId' })
+  timezoneId?: string;
+
+  /** API version */
+  @Input({ alias: 'apiVersion' })
+  apiVersion?: string;
+
+  /** When true, uses NDJSON streaming for AI responses. When false, uses a single JSON response. */
+  @Input({ alias: 'stream', transform: booleanAttribute })
+  stream?: boolean;
+
+  /** Loading message shown while generating and before progress steps are available. */
+  @Input({ alias: 'loadingMessage' })
+  loadingMessage?: string | null;
+
+  /** Message shown in place of the assistant reply when the user stops an in-flight response. Falls back to a localized default when not set. */
+  @Input({ alias: 'cancelledMessage' })
+  cancelledMessage?: string | null;
+
+  /** When set, auto-submits via the session without adding a duplicate user message (assumes the prompt is already in the transcript). */
+  @Input({ alias: 'initialPrompt' })
+  initialPrompt?: string | null;
+
+  /** Title for the empty state when there are no messages. */
+  @Input({ alias: 'emptyStateTitle' })
+  emptyStateTitle?: string;
+
+  /** Optional label above empty-state suggestion chips. Only shown when `emptyStateSuggestions` is non-empty. */
+  @Input({ alias: 'emptyStateSubtitle' })
+  emptyStateSubtitle?: string;
+
+  /** Optional suggestion chips for the empty state. When empty, only the title is shown. Each entry may include `selectedDatasets` to pre-select datasets when the chip is activated. */
+  @Input({ alias: 'emptyStateSuggestions' })
+  emptyStateSuggestions?: AiChatEmptyStateSuggestion[];
+
+  /** Size of the chat: `s`, `m` (default), `l` or `xl`. Scales messages, progress steps, questions, the empty state and the prompt input together. Custom actions beyond built-in `ChatMessage.actions` buttons can be projected via the `assistant-message-actions` light-DOM slot on the latest assistant message. */
+  @Input({ alias: 'size' })
+  size?: unknown;
+
+  /** Fired when a user sends a message */
+  readonly luzmoMessageSent = output<CustomEvent<AiChatMessageSentEventDetail>>({ alias: 'luzmoMessageSent' });
+
+  /** Fired when the selected datasets change */
+  readonly luzmoDatasetsChanged = output<CustomEvent<AiChatDatasetsChangedEventDetail>>({ alias: 'luzmoDatasetsChanged' });
+
+  /** Fired for every incremental, kit-assembled event during a streamed response (decision, text, progress, dashboard-title/layout/item, chart, custom-item, elicitation, interrupt, plus forward-by-default unrecognized chunks). Use `isRecognizedStep` to narrow. */
+  readonly luzmoStep = output<CustomEvent<AiChatStepEvent>>({ alias: 'luzmoStep' });
+
+  /** Fired exactly once per response with the authoritative final result (dashboard/chart/name/customItem) or an `error`. */
+  readonly luzmoComplete = output<CustomEvent<AiChatCompleteEvent>>({ alias: 'luzmoComplete' });
+
+  /** Fired when an in-flight prompt is stopped */
+  readonly luzmoStop = output<CustomEvent<void>>({ alias: 'luzmoStop' });
+
+  /** Fired when the conversation ID is updated from the API */
+  readonly luzmoConversationIdChanged = output<CustomEvent<AiChatConversationIdChangedEventDetail>>({ alias: 'luzmoConversationIdChanged' });
+
+  /** Fired when a built-in assistant message action is activated (after confirmation when `confirm` is set) */
+  readonly luzmoAssistantMessageAction = output<CustomEvent<AssistantMessageActionEventDetail>>({ alias: 'luzmoAssistantMessageAction' });
+
+  constructor() {
+    this.bindEvents();
+    this.destroyRef.onDestroy(() => {
+      for (const cleanup of this.listenerCleanup) {
+        cleanup();
+      }
+    });
+  }
+
+  ngOnChanges(changes: SimpleChanges): void {
+    for (const key of Object.keys(changes)) {
+      switch (key) {
+        case 'messages':
+          this.setHostProperty('messages', changes['messages'].currentValue);
+          break;
+        case 'selectedDatasets':
+          this.setHostProperty('selectedDatasets', changes['selectedDatasets'].currentValue);
+          break;
+        case 'placeholder':
+          this.setHostProperty('placeholder', changes['placeholder'].currentValue);
+          break;
+        case 'disabled':
+          this.setHostProperty('disabled', changes['disabled'].currentValue);
+          break;
+        case 'stoppable':
+          this.setHostProperty('stoppable', changes['stoppable'].currentValue);
+          break;
+        case 'showAssistantContextMenu':
+          this.setHostProperty('showAssistantContextMenu', changes['showAssistantContextMenu'].currentValue);
+          break;
+        case 'authKey':
+          this.setHostProperty('authKey', changes['authKey'].currentValue);
+          break;
+        case 'authToken':
+          this.setHostProperty('authToken', changes['authToken'].currentValue);
+          break;
+        case 'apiUrl':
+          this.setHostProperty('apiUrl', changes['apiUrl'].currentValue);
+          break;
+        case 'appServer':
+          this.setHostProperty('appServer', changes['appServer'].currentValue);
+          break;
+        case 'includePublicDatasets':
+          this.setHostProperty('includePublicDatasets', changes['includePublicDatasets'].currentValue);
+          break;
+        case 'flagOpendata':
+          this.setHostProperty('flagOpendata', changes['flagOpendata'].currentValue);
+          break;
+        case 'hideDatasetButton':
+          this.setHostProperty('hideDatasetButton', changes['hideDatasetButton'].currentValue);
+          break;
+        case 'hideDatasetIcons':
+          this.setHostProperty('hideDatasetIcons', changes['hideDatasetIcons'].currentValue);
+          break;
+        case 'disableDatasetModification':
+          this.setHostProperty('disableDatasetModification', changes['disableDatasetModification'].currentValue);
+          break;
+        case 'hideSelectedDatasets':
+          this.setHostProperty('hideSelectedDatasets', changes['hideSelectedDatasets'].currentValue);
+          break;
+        case 'hideAgents':
+          this.setHostProperty('hideAgents', changes['hideAgents'].currentValue);
+          break;
+        case 'disableColumnMentions':
+          this.setHostProperty('disableColumnMentions', changes['disableColumnMentions'].currentValue);
+          break;
+        case 'requireDataset':
+          this.setHostProperty('requireDataset', changes['requireDataset'].currentValue);
+          break;
+        case 'allowImages':
+          this.setHostProperty('allowImages', changes['allowImages'].currentValue);
+          break;
+        case 'allowVoiceInput':
+          this.setHostProperty('allowVoiceInput', changes['allowVoiceInput'].currentValue);
+          break;
+        case 'acceptedFileTypes':
+          this.setHostProperty('acceptedFileTypes', changes['acceptedFileTypes'].currentValue);
+          break;
+        case 'uploadAttachments':
+          this.setHostProperty('uploadAttachments', changes['uploadAttachments'].currentValue);
+          break;
+        case 'agent':
+          this.setHostProperty('agent', changes['agent'].currentValue);
+          break;
+        case 'agentConfig':
+          this.setHostProperty('agentConfig', changes['agentConfig'].currentValue);
+          break;
+        case 'agentId':
+          this.setHostProperty('agentId', changes['agentId'].currentValue);
+          break;
+        case 'task':
+          this.setHostProperty('task', changes['task'].currentValue);
+          break;
+        case 'modelPreference':
+          this.setHostProperty('modelPreference', changes['modelPreference'].currentValue);
+          break;
+        case 'chatSession':
+          this.setHostProperty('chatSession', changes['chatSession'].currentValue);
+          break;
+        case 'conversationId':
+          this.setHostProperty('conversationId', changes['conversationId'].currentValue);
+          break;
+        case 'chart':
+          this.setHostProperty('chart', changes['chart'].currentValue);
+          break;
+        case 'dashboard':
+          this.setHostProperty('dashboard', changes['dashboard'].currentValue);
+          break;
+        case 'customItem':
+          this.setHostProperty('customItem', changes['customItem'].currentValue);
+          break;
+        case 'currentScreenMode':
+          this.setHostProperty('currentScreenMode', changes['currentScreenMode'].currentValue);
+          break;
+        case 'localeId':
+          this.setHostProperty('localeId', changes['localeId'].currentValue);
+          break;
+        case 'timezoneId':
+          this.setHostProperty('timezoneId', changes['timezoneId'].currentValue);
+          break;
+        case 'apiVersion':
+          this.setHostProperty('apiVersion', changes['apiVersion'].currentValue);
+          break;
+        case 'stream':
+          this.setHostProperty('stream', changes['stream'].currentValue);
+          break;
+        case 'loadingMessage':
+          this.setHostProperty('loadingMessage', changes['loadingMessage'].currentValue);
+          break;
+        case 'cancelledMessage':
+          this.setHostProperty('cancelledMessage', changes['cancelledMessage'].currentValue);
+          break;
+        case 'initialPrompt':
+          this.setHostProperty('initialPrompt', changes['initialPrompt'].currentValue);
+          break;
+        case 'emptyStateTitle':
+          this.setHostProperty('emptyStateTitle', changes['emptyStateTitle'].currentValue);
+          break;
+        case 'emptyStateSubtitle':
+          this.setHostProperty('emptyStateSubtitle', changes['emptyStateSubtitle'].currentValue);
+          break;
+        case 'emptyStateSuggestions':
+          this.setHostProperty('emptyStateSuggestions', changes['emptyStateSuggestions'].currentValue);
+          break;
+        case 'size':
+          this.setHostProperty('size', changes['size'].currentValue);
+          break;
+        default:
+          break;
+      }
+    }
+  }
+
+  /**
+   * Forward a wrapper @Input to the underlying host element via Renderer2 so
+   * the wrapper stays compatible with non-DOM Angular platforms (SSR, tests).
+   * Unlike a "skip undefined" guard, this lets consumers reset values back to
+   * undefined / null by clearing their bindings.
+   */
+  private setHostProperty(key: string, value: unknown): void {
+    this.renderer.setProperty(this.host, key, value);
+  }
+
+  private bindEvents(): void {
+    this.listenerCleanup.push(
+      this.renderer.listen(this.host, 'luzmo-message-sent', (event: Event) => {
+        const typed = event as CustomEvent<AiChatMessageSentEventDetail>;
+        this.luzmoMessageSent.emit(typed);
+      })
+    );
+
+    this.listenerCleanup.push(
+      this.renderer.listen(this.host, 'luzmo-datasets-changed', (event: Event) => {
+        const typed = event as CustomEvent<AiChatDatasetsChangedEventDetail>;
+        this.luzmoDatasetsChanged.emit(typed);
+      })
+    );
+
+    this.listenerCleanup.push(
+      this.renderer.listen(this.host, 'luzmo-step', (event: Event) => {
+        const typed = event as CustomEvent<AiChatStepEvent>;
+        this.luzmoStep.emit(typed);
+      })
+    );
+
+    this.listenerCleanup.push(
+      this.renderer.listen(this.host, 'luzmo-complete', (event: Event) => {
+        const typed = event as CustomEvent<AiChatCompleteEvent>;
+        this.luzmoComplete.emit(typed);
+      })
+    );
+
+    this.listenerCleanup.push(
+      this.renderer.listen(this.host, 'luzmo-stop', (event: Event) => {
+        const typed = event as CustomEvent<void>;
+        this.luzmoStop.emit(typed);
+      })
+    );
+
+    this.listenerCleanup.push(
+      this.renderer.listen(this.host, 'luzmo-conversation-id-changed', (event: Event) => {
+        const typed = event as CustomEvent<AiChatConversationIdChangedEventDetail>;
+        this.luzmoConversationIdChanged.emit(typed);
+      })
+    );
+
+    this.listenerCleanup.push(
+      this.renderer.listen(this.host, 'luzmo-assistant-message-action', (event: Event) => {
+        const typed = event as CustomEvent<AssistantMessageActionEventDetail>;
+        this.luzmoAssistantMessageAction.emit(typed);
+      })
+    );
+  }
+}
+
+/** The underlying custom element type for LuzmoAiChat */
+export type LuzmoAiChatElement = LuzmoAiChatHostElement;