chore(*): JSDoc for chat components

Author: gedinakova

src/components/chat/chat-message-list.ts

@@ -16,26 +16,60 @@ import { styles } from './themes/message-list.base.css.js';
 import type { IgcMessage } from './types.js';
 
 /**
+ * A chat message list component that displays a list of chat messages grouped by date.
  *
  * @element igc-chat-message-list
  *
+ * This component:
+ * - Groups messages by date, labeling groups as "Today", "Yesterday", or the date string.
+ * - Renders messages using the `<igc-chat-message>` component.
+ * - Supports keyboard navigation between messages (Home, End, ArrowUp, ArrowDown).
+ * - Manages focus highlighting on active messages.
+ * - Automatically scrolls to the bottom when new messages arrive, unless auto-scroll is disabled.
+ * - Displays a typing indicator if the chat state option `isComposing` is true.
+ *
+ * Accessibility:
+ * - Uses ARIA roles and properties for grouping and active descendant management.
+ * - Message items have role="option" for assistive technologies.
+ *
  */
 export default class IgcChatMessageListComponent extends LitElement {
+  /** Tag name of the custom element. */
   public static readonly tagName = 'igc-chat-message-list';
 
+  /** Styles applied to the component */
   public static override styles = styles;
 
+  /**
+   * Consumed chat state context providing messages, options, and user data.
+   * @private
+   */
   @consume({ context: chatContext, subscribe: true })
   private _chatState?: ChatState;
 
+  /**
+   * Currently active message id used for focus and keyboard navigation.
+   * @private
+   */
   @state()
   private _activeMessageId = '';
 
+  /**
+   * Registers this component and its dependencies.
+   * Used internally for component setup.
+   */
   /* blazorSuppress */
   public static register() {
     registerComponent(IgcChatMessageListComponent, IgcChatMessageComponent);
   }
 
+  /**
+   * Formats a date to a human-readable label.
+   * Returns 'Today', 'Yesterday', or localized date string.
+   * @param date - Date object to format
+   * @returns formatted string
+   * @private
+   */
   private formatDate(date: Date): string {
     const today = new Date();
     const yesterday = new Date(today);
@@ -56,6 +90,12 @@ export default class IgcChatMessageListComponent extends LitElement {
     });
   }
 
+  /**
+   * Groups messages by their date labels.
+   * @param messages - Array of messages to group
+   * @returns Array of groups with date label and messages
+   * @private
+   */
   private groupMessagesByDate(
     messages: IgcMessage[]
   ): { date: string; messages: IgcMessage[] }[] {
@@ -75,6 +115,10 @@ export default class IgcChatMessageListComponent extends LitElement {
     }));
   }
 
+  /**
+   * Scrolls the container to the bottom, typically called after new messages are rendered.
+   * @private
+   */
   private scrollToBottom() {
     requestAnimationFrame(() => {
       const container = this.shadowRoot?.host as HTMLElement;
@@ -84,13 +128,23 @@ export default class IgcChatMessageListComponent extends LitElement {
     });
   }
 
+  /**
+   * Scrolls the view to a specific message by id.
+   * @param messageId - The id of the message to scroll to
+   * @private
+   */
   private scrollToMessage(messageId: string) {
     const messageElement = this.shadowRoot?.querySelector(
       `#message-${messageId}`
     );
     messageElement?.scrollIntoView();
   }
 
+  /**
+   * Handles focus entering the message list container.
+   * Sets the active message to the last message for keyboard navigation.
+   * @private
+   */
   private handleFocusIn() {
     if (!this._chatState?.messages || this._chatState.messages.length === 0) {
       return;
@@ -99,10 +153,21 @@ export default class IgcChatMessageListComponent extends LitElement {
     this._activeMessageId = lastMessage !== '' ? `message-${lastMessage}` : '';
   }
 
+  /**
+   * Handles focus leaving the message list container.
+   * Clears the active message.
+   * @private
+   */
   private handleFocusOut() {
     this._activeMessageId = '';
   }
 
+  /**
+   * Handles keyboard navigation within the message list.
+   * Supports Home, End, ArrowUp, ArrowDown keys to move active message focus.
+   * @param e KeyboardEvent from user input
+   * @private
+   */
   private handleKeyDown(e: KeyboardEvent) {
     if (!this._chatState?.messages || this._chatState.messages.length === 0) {
       return;
@@ -134,25 +199,37 @@ export default class IgcChatMessageListComponent extends LitElement {
         }
         break;
       default:
-        return; // Exit if the key is not one of the specified keys
+        return; // Ignore other keys
     }
 
     this._activeMessageId = `message-${activeMessageId}`;
     this.scrollToMessage(activeMessageId);
   }
 
+  /**
+   * Lifecycle: called when the component updates.
+   * Scrolls to bottom unless auto-scroll is disabled.
+   */
   protected override updated() {
     if (!this._chatState?.options?.disableAutoScroll) {
       this.scrollToBottom();
     }
   }
 
+  /**
+   * Lifecycle: called after first render.
+   * Scrolls to bottom unless auto-scroll is disabled.
+   */
   protected override firstUpdated() {
     if (!this._chatState?.options?.disableAutoScroll) {
       this.scrollToBottom();
     }
   }
 
+  /**
+   * Renders the typing indicator template if composing.
+   * @protected
+   */
   protected *renderLoadingTemplate() {
     yield html`${this._chatState?.options?.templates?.composingIndicatorTemplate
       ? this._chatState.options.templates.composingIndicatorTemplate
@@ -163,6 +240,11 @@ export default class IgcChatMessageListComponent extends LitElement {
         </div>`}`;
   }
 
+  /**
+   * Main render method.
+   * Groups messages by date and renders each message.
+   * Shows the typing indicator if applicable.
+   */
   protected override render() {
     const groupedMessages = this.groupMessagesByDate(
       this._chatState?.messages ?? []
@@ -174,10 +256,11 @@ export default class IgcChatMessageListComponent extends LitElement {
         aria-activedescendant=${this._activeMessageId}
         role="group"
         aria-label="Message list"
-        tabindex='0'
+        tabindex="0"
         @focusin=${this.handleFocusIn}
         @focusout=${this.handleFocusOut}
-        @keydown=${this.handleKeyDown}></div>
+        @keydown=${this.handleKeyDown}
+      >
         <div part="message-list">
           ${repeat(
             groupedMessages,
@@ -203,11 +286,9 @@ export default class IgcChatMessageListComponent extends LitElement {
               )}
             `
           )}
-          ${
-            this._chatState?.options?.isComposing
-              ? this.renderLoadingTemplate()
-              : nothing
-          }
+          ${this._chatState?.options?.isComposing
+            ? this.renderLoadingTemplate()
+            : nothing}
         </div>
       </div>
     `;

src/components/chat/chat-message.ts

@@ -13,18 +13,39 @@ import { styles as shared } from './themes/shared/chat-message.common.css.js';
 import type { IgcMessage } from './types.js';
 
 /**
+ * A chat message component for displaying individual messages in `<igc-chat>`.
  *
  * @element igc-chat-message
  *
+ * This component renders a single chat message including:
+ * - Message text (sanitized)
+ * - Attachments (if any)
+ * - Custom templates for message content and actions (if provided via chat options)
+ *
+ * It distinguishes sent messages from received messages by comparing
+ * the message sender with the current user ID from chat state.
+ *
+ * The message text is sanitized with DOMPurify before rendering,
+ * and can be rendered with a markdown renderer if provided.
  */
 export default class IgcChatMessageComponent extends LitElement {
+  /** Tag name of the custom element. */
   public static readonly tagName = 'igc-chat-message';
 
+  /** Styles applied to the component. */
   public static override styles = [styles, shared];
 
+  /**
+   * Injected chat state context. Provides message data, user info, and options.
+   * @private
+   */
   @consume({ context: chatContext, subscribe: true })
   private _chatState?: ChatState;
 
+  /**
+   * Registers this component and its dependencies.
+   * This is used internally to set up the component definitions.
+   */
   /* blazorSuppress */
   public static register() {
     registerComponent(
@@ -34,13 +55,28 @@ export default class IgcChatMessageComponent extends LitElement {
     );
   }
 
+  /**
+   * The chat message to render.
+   */
   @property({ attribute: false })
   public message: IgcMessage | undefined;
 
+  /**
+   * Sanitizes message text to prevent XSS or invalid HTML.
+   * @param text The raw message text
+   * @returns Sanitized text safe for HTML rendering
+   * @private
+   */
   private sanitizeMessageText(text: string): string {
     return DOMPurify.sanitize(text);
   }
 
+  /**
+   * Renders the chat message template.
+   * - Applies 'sent' CSS class if the message sender matches current user.
+   * - Uses markdown rendering if configured.
+   * - Renders attachments and custom templates if provided.
+   */
   protected override render() {
     const containerClass = `message-container ${this.message?.sender === this._chatState?.currentUserId ? 'sent' : ''}`;
     const sanitizedMessageText = this.sanitizeMessageText(