feat: add new header config (#1030)

Author: ethanwinters

demo/package.json

@@ -20,8 +20,7 @@
     "@carbon/web-components": "^2.46.0",
     "lit": "^3.1.0",
     "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "uuid": "^11.1.0"
+    "react-dom": "^19.0.0"
   },
   "devDependencies": {
     "@babel/core": "^7.26.0",

demo/src/customSendMessage/doPreviewCard.ts

@@ -8,7 +8,7 @@
  */
 
 import { ChatInstance, MessageResponseTypes } from "@carbon/ai-chat";
-import { v4 as uuid } from "uuid";
+import { uuid } from "@carbon/ai-chat-components/es/globals/utils/uuid.js";
 
 function doPreviewCard(
   instance: ChatInstance,

demo/src/framework/demo-header-switcher.ts

@@ -12,9 +12,61 @@ import "@carbon/web-components/es/components/text-input/index.js";
 import "@carbon/web-components/es/components/checkbox/index.js";
 
 import { PublicConfig, MinimizeButtonIconType } from "@carbon/ai-chat";
+import Help16 from "@carbon/icons/es/help/16.js";
+import Information16 from "@carbon/icons/es/information/16.js";
+import Document16 from "@carbon/icons/es/document/16.js";
+import Chat16 from "@carbon/icons/es/chat/16.js";
+import UserAvatar16 from "@carbon/icons/es/user--avatar/16.js";
+import Settings16 from "@carbon/icons/es/settings/16.js";
+import Share16 from "@carbon/icons/es/share/16.js";
+import Download16 from "@carbon/icons/es/download/16.js";
 import { css, html, LitElement } from "lit";
 import { customElement, property } from "lit/decorators.js";
 
+// Sample actions for demo
+const sampleActions = [
+  {
+    icon: Help16,
+    text: "Help",
+    onClick: () => alert("Help clicked!"),
+  },
+  {
+    icon: Information16,
+    text: "About",
+    onClick: () => alert("About clicked!"),
+  },
+  {
+    icon: Document16,
+    text: "Documentation",
+    onClick: () => alert("Documentation clicked!"),
+  },
+  {
+    icon: Chat16,
+    text: "Feedback",
+    onClick: () => alert("Feedback clicked!"),
+  },
+  {
+    icon: UserAvatar16,
+    text: "Profile",
+    onClick: () => alert("Profile clicked!"),
+  },
+  {
+    icon: Settings16,
+    text: "Settings",
+    onClick: () => alert("Settings clicked!"),
+  },
+  {
+    icon: Share16,
+    text: "Share",
+    onClick: () => alert("Share clicked!"),
+  },
+  {
+    icon: Download16,
+    text: "Export Chat",
+    onClick: () => alert("Export Chat clicked!"),
+  },
+];
+
 @customElement("demo-header-switcher")
 export class DemoHeaderSwitcher extends LitElement {
   static styles = css`
@@ -136,10 +188,20 @@ export class DemoHeaderSwitcher extends LitElement {
           text: "Help",
           handler: () => alert("Help clicked!"),
         },
+        {
+          text: "Documentation",
+          href: "https://chat.carbondesignsystem.com/tag/latest/docs/documents/Overview.html",
+          target: "_blank",
+        },
         {
           text: "Settings",
           handler: () => alert("Settings clicked!"),
         },
+        {
+          text: "Disabled Option",
+          handler: () => alert("This should not appear!"),
+          disabled: true,
+        },
       ];
     } else {
       delete header.menuOptions;
@@ -162,6 +224,20 @@ export class DemoHeaderSwitcher extends LitElement {
     this._updateConfig({ header });
   };
 
+  private _onSampleActionsChanged = (event: Event) => {
+    const customEvent = event as CustomEvent;
+    const checked = customEvent.detail.checked;
+    const header = { ...this.config.header };
+
+    if (checked) {
+      header.actions = sampleActions;
+    } else {
+      delete header.actions;
+    }
+
+    this._updateConfig({ header });
+  };
+
   private _getCurrentMinimizeButtonType(): string {
     if (this.config?.header?.hideMinimizeButton) {
       return "none";
@@ -243,6 +319,15 @@ export class DemoHeaderSwitcher extends LitElement {
           Show AI label
         </cds-checkbox>
       </div>
+
+      <div class="header-section">
+        <cds-checkbox
+          ?checked=${(header?.actions?.length ?? 0) > 0}
+          @cds-checkbox-changed=${this._onSampleActionsChanged}
+        >
+          Add menu actions
+        </cds-checkbox>
+      </div>
     `;
   }
 }

demo/src/mockServiceDesk/mockServiceDesk.ts

@@ -28,7 +28,7 @@ import {
   UserType,
 } from "@carbon/ai-chat";
 
-import { v4 as uuid } from "uuid";
+import { uuid } from "@carbon/ai-chat-components/es/globals/utils/uuid.js";
 
 import { MARKDOWN } from "../customSendMessage/constants";
 

demo/src/react/DemoApp.tsx

@@ -147,6 +147,12 @@ function DemoApp({ config, settings, onChatInstanceReady }: AppProps) {
           parentStateText={stateText}
         />
       ),
+      headerFixedActionsElement: (
+        <WriteableElementExample
+          location="headerFixedActionsElement"
+          parentStateText={stateText}
+        />
+      ),
       welcomeNodeBeforeElement: (
         <WriteableElementExample
           location="welcomeNodeBeforeElement"

demo/src/react/WriteableElementExample.css

@@ -21,3 +21,9 @@
   border-end-start-radius: var(--cds-aichat-rounded-modifier-radius-end-start);
   border-end-end-radius: var(--cds-aichat-rounded-modifier-radius-end-end);
 }
+
+.writeable-element-external--compact {
+  padding: 0.25rem 0.5rem;
+  font-size: 0.75rem;
+  border-radius: 0;
+}

demo/src/react/WriteableElementExample.tsx

@@ -23,6 +23,16 @@ function WriteableElementExample({
   if (location === "aiTooltipAfterDescriptionElement") {
     classNames += " writeable-element-external--not-rounded";
   }
+
+  // Special compact display for header fixed actions
+  if (location === "headerFixedActionsElement") {
+    return (
+      <div className="writeable-element-external writeable-element-external--compact">
+        {location}
+      </div>
+    );
+  }
+
   return (
     <div className={classNames}>
       Location: {location}. Parent prop: {parentStateText}

demo/src/web-components/writeable-element-example.ts

@@ -34,6 +34,11 @@ class WriteableElementExample extends LitElement {
       );
       border-end-end-radius: var(--cds-aichat-rounded-modifier-radius-end-end);
     }
+    .external--compact {
+      padding: 0.25rem 0.5rem;
+      font-size: 0.75rem;
+      border-radius: 0;
+    }
   `;
 
   @property({ type: String })
@@ -47,6 +52,14 @@ class WriteableElementExample extends LitElement {
     if (this.location === "aiTooltipAfterDescriptionElement") {
       classNames += " writeable-element-external--not-rounded";
     }
+
+    // Special compact display for header fixed actions
+    if (this.location === "headerFixedActionsElement") {
+      return html`<div class="external external--compact">
+        ${this.location}
+      </div>`;
+    }
+
     return html`<div class="${classNames}">
       Location: ${this.location}. Parent prop: ${this.valueFromParent}.
     </div> `;

demo/tests/setChatConfig.spec.ts

@@ -86,10 +86,12 @@ test("setChatConfig configuration mode functionality", async ({ page }) => {
     page.getByTestId(DemoPageObjectId.LEAVE_SET_CHAT_CONFIG_MODE_BUTTON),
   ).toBeVisible();
 
-  // Check if title was updated
-  await expect(page.getByTestId(PageObjectId.HEADER_TITLE)).toContainText(
-    "Test Title 1",
-  );
+  // Check if title was updated (scoped to chat_header)
+  await expect(
+    page
+      .getByTestId(PageObjectId.CHAT_HEADER)
+      .getByTestId(PageObjectId.HEADER_TITLE),
+  ).toContainText("Test Title 1");
 
   // Phase 2: Page Refresh & Error State
 
@@ -136,10 +138,12 @@ test("setChatConfig configuration mode functionality", async ({ page }) => {
 
   // 8. Assertions for recovery - sidebar should be visible again with Leave button
 
-  // Verify the header name is also applied in the main panel
-  await expect(page.getByTestId(PageObjectId.HEADER_NAME)).toContainText(
-    "Test Assistant",
-  );
+  // Verify the header name is also applied in the main panel (scoped to chat_header)
+  await expect(
+    page
+      .getByTestId(PageObjectId.CHAT_HEADER)
+      .getByTestId(PageObjectId.HEADER_NAME),
+  ).toContainText("Test Assistant");
 
   await expect(
     page.getByTestId(DemoPageObjectId.SET_CHAT_CONFIG_NOTIFICATION_ERROR),

docs/developer-handbook.md

@@ -1,8 +1,6 @@
 # Developer Handbook
 
 <!-- prettier-ignore-start -->
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 ## Table of Contents
 
 - [Getting started](#getting-started)
@@ -23,11 +21,10 @@
   - [Start a new `block` or `element`?](#start-a-new-block-or-element)
   - [Red flags](#red-flags)
 - [Maintainers](#maintainers)
-  - [Continuous integration and deployment](#ontinuous-integration-and-eployment)
+  - [Continuous integration and deployment](#continuous-integration-and-deployment)
   - [Publishing](#publishing)
   - [Automated dependency updates](#automated-dependency-updates)
 
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
 <!-- prettier-ignore-end -->
 
 ## Getting started