@carbon/ai-chat-components 0.10.0 → 0.11.0

package/es/components/chat-shell/src/aria-announcer-manager.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Manages ARIA live region announcements for screen readers.
+ * Uses a dual-region pattern with a 250ms delay for NVDA compatibility.
+ */
+export declare class AriaAnnouncerManager {
+    private ariaLiveRegion1?;
+    private ariaLiveRegion2?;
+    private useAriaLiveRegion1;
+    private pendingAnnouncements;
+    private announcementTimeoutId;
+    /**
+     * Initialize the manager with references to the aria-live regions
+     */
+    connect(region1: HTMLDivElement, region2: HTMLDivElement): void;
+    /**
+     * Clean up resources
+     */
+    disconnect(): void;
+    /**
+     * Announces a message to screen readers via aria-live regions.
+     * Uses a dual-region pattern and 250ms delay for NVDA compatibility.
+     */
+    announce(message: string): void;
+    /**
+     * Clear any pending announcements
+     */
+    private clearPendingAnnouncements;
+    /**
+     * Performs the actual announcements by writing to aria-live regions
+     */
+    private doAnnouncements;
+}

package/es/components/chat-shell/src/aria-announcer-manager.js

@@ -0,0 +1,104 @@
+/**
+ * Copyright IBM Corp. 2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Manages ARIA live region announcements for screen readers.
+ * Uses a dual-region pattern with a 250ms delay for NVDA compatibility.
+ */
+class AriaAnnouncerManager {
+    constructor() {
+        this.useAriaLiveRegion1 = true;
+        this.pendingAnnouncements = [];
+        this.announcementTimeoutId = null;
+    }
+    /**
+     * Initialize the manager with references to the aria-live regions
+     */
+    connect(region1, region2) {
+        this.ariaLiveRegion1 = region1;
+        this.ariaLiveRegion2 = region2;
+    }
+    /**
+     * Clean up resources
+     */
+    disconnect() {
+        this.clearPendingAnnouncements();
+        this.ariaLiveRegion1 = undefined;
+        this.ariaLiveRegion2 = undefined;
+    }
+    /**
+     * Announces a message to screen readers via aria-live regions.
+     * Uses a dual-region pattern and 250ms delay for NVDA compatibility.
+     */
+    announce(message) {
+        if (!message || typeof window === "undefined") {
+            return;
+        }
+        // Queue the announcement
+        this.pendingAnnouncements.push(message);
+        // If timeout not already scheduled, schedule it
+        if (this.announcementTimeoutId === null) {
+            // 250ms delay for NVDA compatibility - prevents focus changes from interrupting announcements
+            this.announcementTimeoutId = window.setTimeout(() => {
+                this.doAnnouncements();
+            }, 250);
+        }
+    }
+    /**
+     * Clear any pending announcements
+     */
+    clearPendingAnnouncements() {
+        if (this.announcementTimeoutId !== null && typeof window !== "undefined") {
+            window.clearTimeout(this.announcementTimeoutId);
+            this.announcementTimeoutId = null;
+        }
+        this.pendingAnnouncements = [];
+    }
+    /**
+     * Performs the actual announcements by writing to aria-live regions
+     */
+    doAnnouncements() {
+        if (this.pendingAnnouncements.length === 0) {
+            this.announcementTimeoutId = null;
+            return;
+        }
+        // Join all pending announcements
+        const message = this.pendingAnnouncements.join(" ");
+        this.pendingAnnouncements = [];
+        this.announcementTimeoutId = null;
+        // Get the region to use for this announcement
+        const useRegion = this.useAriaLiveRegion1
+            ? this.ariaLiveRegion1
+            : this.ariaLiveRegion2;
+        // Get the region to clear
+        const clearRegion = this.useAriaLiveRegion1
+            ? this.ariaLiveRegion2
+            : this.ariaLiveRegion1;
+        // Write to the active region
+        if (useRegion) {
+            useRegion.textContent = message;
+        }
+        // Clear the previous region
+        if (clearRegion) {
+            clearRegion.textContent = "";
+        }
+        // Swap which region to use next time
+        this.useAriaLiveRegion1 = !this.useAriaLiveRegion1;
+    }
+}
+// Made with Bob
+
+export { AriaAnnouncerManager };
+//# sourceMappingURL=aria-announcer-manager.js.map

package/es/components/chat-shell/src/aria-announcer-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aria-announcer-manager.js","sources":["../../../../src/components/chat-shell/src/aria-announcer-manager.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;;;AAAA;;;;;;;AAOG;AAEH;;;AAGG;MACU,oBAAoB,CAAA;AAAjC,IAAA,WAAA,GAAA;QAGU,IAAA,CAAA,kBAAkB,GAAG,IAAI;QACzB,IAAA,CAAA,oBAAoB,GAAa,EAAE;QACnC,IAAA,CAAA,qBAAqB,GAAkB,IAAI;IAwFrD;AAtFE;;AAEG;IACH,OAAO,CAAC,OAAuB,EAAE,OAAuB,EAAA;AACtD,QAAA,IAAI,CAAC,eAAe,GAAG,OAAO;AAC9B,QAAA,IAAI,CAAC,eAAe,GAAG,OAAO;IAChC;AAEA;;AAEG;IACH,UAAU,GAAA;QACR,IAAI,CAAC,yBAAyB,EAAE;AAChC,QAAA,IAAI,CAAC,eAAe,GAAG,SAAS;AAChC,QAAA,IAAI,CAAC,eAAe,GAAG,SAAS;IAClC;AAEA;;;AAGG;AACH,IAAA,QAAQ,CAAC,OAAe,EAAA;QACtB,IAAI,CAAC,OAAO,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE;YAC7C;QACF;;AAGA,QAAA,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC;;AAGvC,QAAA,IAAI,IAAI,CAAC,qBAAqB,KAAK,IAAI,EAAE;;YAEvC,IAAI,CAAC,qBAAqB,GAAG,MAAM,CAAC,UAAU,CAAC,MAAK;gBAClD,IAAI,CAAC,eAAe,EAAE;YACxB,CAAC,EAAE,GAAG,CAAC;QACT;IACF;AAEA;;AAEG;IACK,yBAAyB,GAAA;QAC/B,IAAI,IAAI,CAAC,qBAAqB,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE;AACxE,YAAA,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,qBAAqB,CAAC;AAC/C,YAAA,IAAI,CAAC,qBAAqB,GAAG,IAAI;QACnC;AACA,QAAA,IAAI,CAAC,oBAAoB,GAAG,EAAE;IAChC;AAEA;;AAEG;IACK,eAAe,GAAA;QACrB,IAAI,IAAI,CAAC,oBAAoB,CAAC,MAAM,KAAK,CAAC,EAAE;AAC1C,YAAA,IAAI,CAAC,qBAAqB,GAAG,IAAI;YACjC;QACF;;QAGA,MAAM,OAAO,GAAG,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,GAAG,CAAC;AACnD,QAAA,IAAI,CAAC,oBAAoB,GAAG,EAAE;AAC9B,QAAA,IAAI,CAAC,qBAAqB,GAAG,IAAI;;AAGjC,QAAA,MAAM,SAAS,GAAG,IAAI,CAAC;cACnB,IAAI,CAAC;AACP,cAAE,IAAI,CAAC,eAAe;;AAGxB,QAAA,MAAM,WAAW,GAAG,IAAI,CAAC;cACrB,IAAI,CAAC;AACP,cAAE,IAAI,CAAC,eAAe;;QAGxB,IAAI,SAAS,EAAE;AACb,YAAA,SAAS,CAAC,WAAW,GAAG,OAAO;QACjC;;QAGA,IAAI,WAAW,EAAE;AACf,YAAA,WAAW,CAAC,WAAW,GAAG,EAAE;QAC9B;;AAGA,QAAA,IAAI,CAAC,kBAAkB,GAAG,CAAC,IAAI,CAAC,kBAAkB;IACpD;AACD;AAED;;;;"}

package/es/components/chat-shell/src/chat-header.d.ts

@@ -0,0 +1,177 @@
+import { LitElement } from "lit";
+import "@carbon/web-components/es/components/button/index.js";
+import "@carbon/web-components/es/components/overflow-menu/index.js";
+import "../../toolbar/src/toolbar.js";
+import type { Action } from "../../toolbar/src/toolbar.js";
+import type { BaseOverflowMenuItem } from "../../../typings/overflow-menu.js";
+/**
+ * Navigation overflow menu item configuration.
+ * Uses BaseOverflowMenuItem which extends properties from CDSOverflowMenuItem.
+ * This type is specifically for navigation menu items (no icon property).
+ */
+export type NavigationOverflowItem = BaseOverflowMenuItem;
+/**
+ * Chat Header component that wraps the Toolbar component.
+ * Provides a consistent header for chat interfaces with support for
+ * navigation, title, actions, and decorators (like AI labels).
+ *
+ * @element cds-aichat-chat-header
+ * @slot navigation - Navigation controls (e.g., back button, overflow menu)
+ * @slot title - Title and name content (can also use title/name properties)
+ * @slot decorator - Decorative elements like AI labels
+ * @slot fixed-actions - Actions that never overflow (allows passing custom components)
+ */
+declare class CdsAiChatChatHeader extends LitElement {
+    static styles: any;
+    /**
+     * Selector strings for finding focusable elements.
+     *
+     * Design rationale:
+     * - BUTTON_SELECTORS: Used for fixed-actions slot. Targets Carbon buttons and native buttons.
+     * - NAV_BUTTON_SELECTORS: Used for navigation slot. Includes overflow menu for navigation patterns.
+     * - TOOLBAR_ACTION_SELECTOR: Specifically targets toolbar icon buttons (most common action type).
+     * - FOCUSABLE_SELECTORS: Fallback selector for any focusable element. Uses "*" because the
+     *   tryFocus() utility already performs comprehensive validation including:
+     *   - Visibility checks (display, visibility, hidden, inert, aria-hidden)
+     *   - Focusability validation (handles standard elements and custom elements with delegatesFocus)
+     *   - Actual focus verification (checks if document.activeElement changed)
+     *   This approach avoids duplicating validation logic and properly handles Carbon components.
+     */
+    private static readonly BUTTON_SELECTORS;
+    private static readonly NAV_BUTTON_SELECTORS;
+    private static readonly FOCUSABLE_SELECTORS;
+    private static readonly TOOLBAR_ACTION_SELECTOR;
+    /**
+     * Configuration constants for navigation elements.
+     */
+    private static readonly BACK_ICON_CONFIG;
+    private static readonly NAV_TOOLTIP_CONFIG;
+    /**
+     * Attempts to focus an element if it's focusable and not disabled.
+     * Uses the enhanced tryFocus utility from focus-utils which checks
+     * visibility, accessibility attributes, and proper focusability.
+     *
+     * @param element - The element to attempt to focus
+     * @returns True if focus was successfully set, false otherwise
+     */
+    private tryFocusElement;
+    /**
+     * Attempts to focus buttons within a named slot.
+     * Reduces duplication by centralizing slot querying logic.
+     *
+     * @param slotName - The name of the slot to query
+     * @param selectors - CSS selector string for buttons to find
+     * @returns True if a button was focused, false otherwise
+     */
+    private tryFocusSlotButtons;
+    /**
+     * Requests focus on the best available focusable element within the component.
+     * This method implements a generic focus management pattern that can be used
+     * across all web components.
+     *
+     * Priority order:
+     * 1. First enabled button in navigation (either slotted or rendered from properties)
+     * 2. First enabled button in fixed-actions slot (usually close button)
+     * 3. First enabled action button from toolbar (rendered by actions array)
+     * 4. Any other focusable element (last resort)
+     *
+     * @returns True if focus was successfully set, false otherwise
+     */
+    requestFocus(): boolean;
+    /**
+     * Array of actions that can overflow into a menu when space is limited.
+     */
+    actions: Action[];
+    /**
+     * Enable overflow behavior for actions.
+     */
+    overflow: boolean;
+    /**
+     * Optional header title text to display.
+     */
+    headerTitle: string;
+    /**
+     * Optional name text to display after the title.
+     */
+    headerName: string;
+    /**
+     * Type of navigation to display: 'back', 'overflow', or 'none'.
+     */
+    navigationType: "back" | "overflow" | "none";
+    /**
+     * Icon for the back button (CarbonIcon object with render method).
+     */
+    navigationBackIcon?: any;
+    /**
+     * Label/tooltip text for the back button.
+     */
+    navigationBackLabel: string;
+    /**
+     * Click handler for the back button.
+     */
+    navigationBackOnClick?: () => void;
+    /**
+     * Array of overflow menu items with text and onClick handlers or href.
+     */
+    navigationOverflowItems?: NavigationOverflowItem[];
+    /**
+     * Label/tooltip text for the overflow menu button.
+     */
+    navigationOverflowLabel: string;
+    /**
+     * Icon for the overflow menu button (CarbonIcon object with render method).
+     */
+    navigationOverflowIcon?: any;
+    /**
+     * Click handler for when the overflow menu button is clicked (menu opened).
+     */
+    navigationOverflowOnClick?: () => void;
+    /**
+     * Renders the overflow menu items.
+     */
+    private renderOverflowMenuItems;
+    /**
+     * Checks if back navigation should be rendered.
+     * @returns True if back navigation type is set and icon is provided
+     */
+    private shouldRenderBackNavigation;
+    /**
+     * Checks if overflow navigation should be rendered.
+     * @returns True if overflow navigation type is set and items are available
+     */
+    private shouldRenderOverflowNavigation;
+    /**
+     * Gets the configuration object for overflow menu icon.
+     * @returns Icon loader configuration with class and slot
+     */
+    private getOverflowIconConfig;
+    /**
+     * Renders the back navigation button.
+     * @returns Template result for back button
+     */
+    private renderBackNavigation;
+    /**
+     * Renders the overflow navigation menu.
+     * @returns Template result for overflow menu
+     */
+    private renderOverflowNavigation;
+    /**
+     * Renders the navigation content based on navigationType.
+     * Uses guard clauses and extracted methods for clarity.
+     * @returns Template result for navigation or nothing
+     */
+    private renderNavigation;
+    /**
+     * Renders the title content based on headerTitle and headerName properties.
+     * @returns Template result for title content or title slot
+     */
+    private renderTitle;
+    render(): import("lit-html").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "cds-aichat-chat-header": CdsAiChatChatHeader;
+    }
+}
+export { CdsAiChatChatHeader };
+export default CdsAiChatChatHeader;