@cognizant-ai-lab/ui-common 1.3.3 → 1.4.0

package/README.md

@@ -0,0 +1,287 @@
+# @cognizant-ai-lab/ui-common
+
+A comprehensive React component library and utilities package for building user interfaces for Neuro-san AI
+applications. Contains components for chat interfaces, multi-agent flow visualization, theming and more.
+
+## Copyright
+
+Copyright 2026 Cognizant Technology Solutions Corp, www.cognizant.com.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+## Quickstart
+
+For this quickstart, we'll show how to use the `MultiAgentAccelerator` component, which is a demo application
+showcasing the components in this package.
+
+You will need access to a Neuro-san API backend to use the components in this package.
+
+If you don't already have a ReactJS application, create one, for example, using [Create React App](https://create-react-app.dev/):
+The following assumes you're using TypeScript (recommended):
+
+```bash
+npx create-react-app my-app --template typescript
+cd my-app
+```
+
+Install the library:
+
+```bash
+npm install @cognizant-ai-lab/ui-common
+```
+
+Then edit `src/App.tsx` (assuming TypeScript) and replace the contents with the code below:
+
+```tsx
+export default function MyApp() {
+    return (
+        <MultiAgentAccelerator
+            userInfo={{userName: "Alice", userImage: "https://example.com/alice.png"}}
+            backendNeuroSanApiUrl="https://my-neuro-san-api.example.com"
+        />
+    )
+}
+```
+
+Run your app with `npm start` or `yarn start`, and you should see the Multi-Agent Accelerator interface,
+which is a demo application showcasing the components in this package. You can select an agent, chat with that agent
+via the chat interface, and visualize the agent network flow.
+
+## Features
+
+- **UI Components**: Ready-to-use React components for AI chat interfaces, navigation, dialogs, and more
+- **Multi-Agent Visualization**: Interactive flow diagrams for visualizing agent networks
+- **Authentication**: Built-in authentication components supporting multiple providers
+- **State Management**: Zustand-based stores for environment, settings, and user info
+- **Theme Support**: Dark mode support with customizable, MUI-based theming
+- **Type Safety**: Full TypeScript support with generated OpenAPI types
+- **LLM Integration**: Controllers for interacting with language models and AI agents
+
+## Technologies Used
+
+Among the technologies and libraries used in this package are:
+
+- ESLint and Prettier (for code quality)
+- Jest and React Testing Library (for testing)
+- MUI
+- next-auth (for authentication)
+- React
+- React Flow (for multi-agent visualization)
+- TypeScript
+- Zustand
+
+## Package Structure
+
+```
+ui-common/
+├── components/         # React components
+│   ├── AgentChat/      # Chat interface components
+│   ├── Authentication/ # Auth components
+│   ├── ChatBot/        # ChatBot components
+│   ├── Common/         # Common UI components (dialogs, navbar, etc.)
+│   ├── ErrorPage/      # Error handling components
+│   ├── MultiAgentAccelerator/ # Agent flow visualization
+│   └── Settings/       # Settings dialog components
+├── controller/         # Backend interaction controllers
+│   ├── agent/         # Agent API controllers
+│   └── llm/           # LLM interaction controllers
+├── state/             # Zustand state stores
+├── Theme/             # Theming utilities
+├── utils/             # Utility functions
+└── generated/         # Auto-generated API types
+```
+
+## Usage
+
+#### Example application
+
+Refer to [MAUI](https://github.com/cognizant-ai-lab/neuro-san-ui/tree/main/apps/main), the Multi-Agent Accelerator UI,
+for a real-world application example that uses these components.
+
+### Basic Import
+
+```typescript
+import {ChatCommon, Navbar, MUIDialog, LoadingSpinner, useEnvironment, useUserInfo} from "@cognizant-ai-lab/ui-common"
+```
+
+### Using Components
+
+#### ChatCommon
+
+See `ChatCommonProps` for all available props and their types. Here's a basic example of how to use the `ChatCommon`
+component in a React application:
+
+```tsx
+import {ChatCommon} from "@cognizant-ai-lab/ui-common"
+import {AIMessage, HumanMessage} from "@langchain/core/messages"
+import {useState} from "react"
+
+function ChatInterface() {
+    const [isAwaitingLlm, setIsAwaitingLlm] = useState(false)
+
+    return (
+        <ChatCommon
+            id="agent-network-ui"
+            ref={chatRef} // If you need to access internal methods, like calling "Stop" when user clicks stop
+            neuroSanURL={neuroSanURL} // Base URL for Neuro-san API. Must point to a valid Neuro-san server
+            currentUser="Alice" // Current user's name, used for chat attribution in API calls and display
+            setIsAwaitingLlm={setIsAwaitingLlm} // Used to set whether we're currently waiting for an LLM response,
+            // which can be used to disable input and show loading states
+            isAwaitingLlm={isAwaitingLlm} // Used to indicate whether we're currently waiting for an LLM response
+            targetAgent={selectedNetwork} // The agent we're currently chatting with in Neuro-san.
+            onChunkReceived={onChunkReceived} // Callback function that will be called with each new chunk of response
+            // from the LLM. You can use this to update your UI in real time
+            // as the response comes in.
+        />
+    )
+}
+```
+
+### Using Controllers
+
+#### Test Agent Connection
+
+Used for testing connectivity to a Neuro-san server and retrieving version information.
+
+```typescript
+import {testConnection} from "@cognizant-ai-lab/ui-common"
+
+async function checkServer() {
+    const result = await testConnection("https://api.example.com")
+
+    if (result.success) {
+        console.log(`Connected! Version: ${result.version}`)
+    } else {
+        console.error(`Connection failed: ${result.status}`)
+    }
+}
+```
+
+### Send Chat Query
+
+Send a chat query to the Agent LLM API. If you are using `ChatCommon`, you shouldn't need to call this directly.
+
+```typescript
+import {sendChatQuery} from "@cognizant-ai-lab/ui-common"
+async function sendMessage() {
+    const controller = new AbortController()
+
+    const response = await sendChatQuery(
+        neuroSanURL,
+        controller.signal,
+        "What is the weather in 90210 today?",
+        "weather_agent",
+        (chunk) => console.log("Received chunk:", chunk),
+        chatContext,
+        slyData,
+        currentUser
+    )
+}
+```
+
+#### Send LLM Request
+
+Lower-level interface to send chat messages to a designated LLM and stream response tokens to the supplied callback
+function. You should not need to call this directly if you are using `ChatCommon`. It is a lower-level interface than
+`sendChatQuery` and is used by that function under the hood. This function can also be used to send messages to
+"legacy" agents, which are not built using the Agent API but still accept chat messages via the LLM API.
+
+```typescript
+import {sendLlmRequest} from "@cognizant-ai-lab/ui-common"
+import {HumanMessage} from "@langchain/core/messages"
+
+async function chatWithAgent() {
+    const controller = new AbortController()
+
+    await sendLlmRequest(
+        (token) => console.log("Received:", token),
+        controller.signal,
+        "/api/chat",
+        {temperature: 0.7},
+        "What is the weather?",
+        [new HumanMessage("Hello")],
+        "user-123"
+    )
+}
+```
+
+### Theme Support
+
+The package includes built-in theme support using MUI theming. The components will automatically respond to
+the currently active MUI theme.
+
+## Available Components
+
+### AgentChat
+
+- `ChatCommon` - Main chat interface component
+- `ControlButtons` - Chat control buttons (clear, scroll, etc.)
+- `LlmChatButton` - Button to initiate LLM chat
+- `SendButton` - Message send button
+- `UserQueryDisplay` - Display user queries
+
+### Multi-Agent Accelerator
+
+- `MultiAgentAccelerator` - Main multi-agent flow component
+- `AgentFlow` - Agent flow visualization
+- `Sidebar` - Agent networks sidebar
+
+## API Controllers
+
+### Agent Controller
+
+Various functions for interacting with the Neuro-san Agent API, such as retrieving lists of
+agent networks and sending chat messages to agents.
+
+## TypeScript Support
+
+This package is written in TypeScript and includes full type definitions. All components, utilities, and API types are
+exported for use in your TypeScript projects.
+
+## Development
+
+### Building from Source
+
+```bash
+# Install dependencies
+yarn install
+
+# Generate OpenAPI types
+yarn generate
+
+# Build the package
+yarn build
+
+```
+
+## Contributing
+
+This package is part of the [Neuro-san UI](https://github.com/cognizant-ai-lab/neuro-san-ui) project.
+Please refer to the main repository [contribution guidelines](https://github.com/cognizant-ai-lab/neuro-san-ui/blob/main/CONTRIBUTING.md).
+
+## License
+
+Apache License 2.0 - See LICENSE file for details
+
+## Support
+
+For questions or issues, contact the Cognizant Neuro AI support team at NeuroAiSupport@cognizant.com
+
+## Related Projects
+
+- [neuro-san](https://github.com/cognizant-ai-lab/neuro-san) - Neuro-san core library
+- [neuro-san-studio](https://github.com/cognizant-ai-lab/neuro-san-studio) - Neuro-san examples and studio
+
+---
+
+For more detailed documentation and examples, visit the [GitHub repository](https://github.com/cognizant-ai-lab/neuro-san-ui).

package/dist/Theme/Palettes.d.ts

@@ -0,0 +1,18 @@
+export declare const PALETTES: {
+    blue: string[];
+    red: string[];
+    green: string[];
+    yellow: string[];
+    grayScale: string[];
+    coldToHot: string[];
+    visionImpaired: string[];
+};
+export type PaletteKey = keyof typeof PALETTES | "brand";
+/**
+ * Custom hook to get the current color palette based on user settings.
+ * If the user has selected custom branding, it will return the palette for that.
+ * Otherwise, it will return one of the predefined palettes from the PALETTES object based on the user's selection.
+ *
+ * @returns An array of color hex codes representing the current color palette.
+ */
+export declare const usePalette: () => string[];

package/dist/Theme/Palettes.js

@@ -0,0 +1,94 @@
+// Palettes for progressive coloring of nodes based on depth or heatmap value
+import { useSettingsStore } from "../state/Settings.js";
+export const PALETTES = {
+    blue: [
+        "#f7fbff",
+        "#deebf7",
+        "#c6dbef",
+        "#9ecae1",
+        "#6baed6",
+        "#4292c6",
+        "#2171b5",
+        "#08519c",
+        "#08306b",
+        "#041c45",
+    ],
+    red: ["#fff5f0", "#fee0d2", "#fcbba1", "#fc9272", "#fb6a4a", "#ef3b2c", "#cb181d", "#a50f15", "#67000d", "#3a0007"],
+    green: [
+        "#ffffe5",
+        "#f7fcb9",
+        "#d9f0a3",
+        "#addd8e",
+        "#78c679",
+        "#41ab5d",
+        "#238443",
+        "#006837",
+        "#004529",
+        "#002a1a",
+    ],
+    yellow: [
+        "#ffffe5",
+        "#fff7bc",
+        "#fee391",
+        "#fec44f",
+        "#fe9929",
+        "#ec7014",
+        "#cc4c02",
+        "#993404",
+        "#662506",
+        "#331203",
+    ],
+    grayScale: [
+        "#f7f7f7",
+        "#e1e1e1",
+        "#cfcfcf",
+        "#b1b1b1",
+        "#9e9e9e",
+        "#7e7e7e",
+        "#626262",
+        "#525252",
+        "#252525",
+        "#0d0d0d",
+    ],
+    coldToHot: [
+        "#313695",
+        "#4575b4",
+        "#74add1",
+        "#abd9e9",
+        "#e0f3f8",
+        "#fee090",
+        "#fdae61",
+        "#f46d43",
+        "#d73027",
+        "#a50026",
+    ],
+    visionImpaired: [
+        "#000000",
+        "#004949",
+        "#009292",
+        "#ff6db6",
+        "#ffb6db",
+        "#490092",
+        "#006ddb",
+        "#b66dff",
+        "#6db6ff",
+        "#b6dbff",
+    ],
+};
+/**
+ * Custom hook to get the current color palette based on user settings.
+ * If the user has selected custom branding, it will return the palette for that.
+ * Otherwise, it will return one of the predefined palettes from the PALETTES object based on the user's selection.
+ *
+ * @returns An array of color hex codes representing the current color palette.
+ */
+export const usePalette = () => {
+    const brandPalette = useSettingsStore((state) => state.settings.branding.rangePalette);
+    const paletteKey = useSettingsStore((state) => state.settings.appearance.rangePalette);
+    if (paletteKey === "brand" && brandPalette) {
+        return brandPalette;
+    }
+    else {
+        return PALETTES[paletteKey];
+    }
+};

package/dist/Theme/Theme.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Helper to determine if dark mode is active based on mode and systemMode.
+ * @param mode Current mode setting: "light", "dark", or "system"
+ * @param systemMode If mode is "system", this indicates the system preference: "light" or "dark"
+ * @returns true if dark mode is active, false otherwise
+ */
+export declare const isDarkMode: (mode: "light" | "dark" | "system", systemMode: "light" | "dark") => boolean;
+/**
+ * Adjusts the brightness of a hex color by a given percentage.
+ * @param color - The hex color string (e.g., "#RRGGBB" or "#RGB").
+ * @param percent - The percentage to adjust brightness (-100 to 100). Positive values make the color lighter,
+ * negative values make it darker.
+ * @returns The adjusted hex color string.
+ */
+export declare const adjustBrightness: (color: string, percent: number) => string;
+/**
+ * Helper function to determine if a color is light
+ *
+ * @param color - The hex color string (e.g., "#RRGGBB" or "#RGB")
+ * @returns true if the color is light (per luminance calculation), false otherwise
+ */
+export declare const isLightColor: (color: string) => boolean;

package/dist/Theme/Theme.js

@@ -0,0 +1,58 @@
+/**
+ * Helper to determine if dark mode is active based on mode and systemMode.
+ * @param mode Current mode setting: "light", "dark", or "system"
+ * @param systemMode If mode is "system", this indicates the system preference: "light" or "dark"
+ * @returns true if dark mode is active, false otherwise
+ */
+export const isDarkMode = (mode, systemMode) => mode === "dark" || (mode === "system" && systemMode === "dark");
+/**
+ * Expands 3-character hex colors to 6 characters.
+ * @param color - The hex color string (e.g., "#RGB" or "#RRGGBB")
+ * @returns The expanded hex color string (e.g., "#RRGGBB")
+ */
+const expandHexColor = (color) => {
+    if (color.length === 4 && color.startsWith("#")) {
+        return `#${color[1]}${color[1]}${color[2]}${color[2]}${color[3]}${color[3]}`;
+    }
+    return color;
+};
+/**
+ * Adjusts the brightness of a hex color by a given percentage.
+ * @param color - The hex color string (e.g., "#RRGGBB" or "#RGB").
+ * @param percent - The percentage to adjust brightness (-100 to 100). Positive values make the color lighter,
+ * negative values make it darker.
+ * @returns The adjusted hex color string.
+ */
+export const adjustBrightness = (color, percent) => {
+    if (!color?.startsWith("#") || (color?.length !== 7 && color?.length !== 4)) {
+        // Return original color if not in expected format
+        return color;
+    }
+    const hexColor = expandHexColor(color);
+    const num = parseInt(hexColor.replace("#", ""), 16);
+    const amt = Math.round(2.55 * percent);
+    const R = Math.min(255, Math.max(0, (num >> 16) + amt));
+    const G = Math.min(255, Math.max(0, ((num >> 8) & 0x00ff) + amt));
+    const B = Math.min(255, Math.max(0, (num & 0x0000ff) + amt));
+    return `#${((1 << 24) + (R << 16) + (G << 8) + B).toString(16).slice(1)}`;
+};
+/**
+ * Helper function to determine if a color is light
+ *
+ * @param color - The hex color string (e.g., "#RRGGBB" or "#RGB")
+ * @returns true if the color is light (per luminance calculation), false otherwise
+ */
+export const isLightColor = (color) => {
+    // Expand 3-character hex to 6-character hex if needed.
+    const hexColor = expandHexColor(color);
+    // Remove # if present
+    const colorWithoutHash = hexColor.replace("#", "");
+    // Convert to RGB
+    const r = parseInt(colorWithoutHash.substring(0, 2), 16);
+    const g = parseInt(colorWithoutHash.substring(2, 4), 16);
+    const b = parseInt(colorWithoutHash.substring(4, 6), 16);
+    // Calculate relative luminance (perceived brightness)
+    const luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255;
+    // Return true if light (threshold 0.5)
+    return luminance > 0.5;
+};

package/dist/components/AgentChat/ChatCommon.d.ts

@@ -1,4 +1,4 @@
-import { Dispatch, SetStateAction } from "react";
+import { Dispatch, Ref, SetStateAction } from "react";
 import { CombinedAgentType } from "./Types.js";
 export interface ChatCommonProps {
     /**
@@ -91,4 +91,6 @@ export type ChatCommonHandle = {
  * experience for users when chatting with agents. It handles user input as well as displaying and nicely formatting
  * agent responses. Customization for inputs and outputs is provided via event handlers-like props.
  */
-export declare const ChatCommon: import("react").ForwardRefExoticComponent<ChatCommonProps & import("react").RefAttributes<ChatCommonHandle>>;
+export declare const ChatCommon: ({ ref, ...props }: ChatCommonProps & {
+    ref?: Ref<ChatCommonHandle>;
+}) => import("react/jsx-runtime").JSX.Element;