mcp-chat-ui 1.0.0

package/README.md

@@ -0,0 +1,327 @@
+# MCP Chat UI SDK
+
+A React UI SDK that bundles a full chat experience with speech (STT/TTS), file
+uploads, document viewing, and task actions.
+
+## Requirements
+
+- React 18+ or 19 and React DOM.
+- Node 18+ for build/demo workflows.
+
+
+
+
+## Install
+
+```bash
+npm install mcp-chat-ui
+```
+
+## Quick Start
+
+Import CSS in App.tsx
+
+```App.tsx
+import "mcp-chat-ui/styles.css";
+
+```
+
+Initialize the SDK (required):
+
+```ts
+import { Init } from "mcp-chat-ui";
+
+const initConfig = {
+  baseUrl: "https://apim.octopian.cloud",
+  apiSubscriptionKey: "<apim-subscription-key>",
+  loginSubscriptionKey: "<login-subscription-key>",
+  token: "Bearer <token>",
+  isDab: false,
+  initializeChat: false,
+  showInitPanel: true,
+  contextWindow: "ComposeRequest",
+};
+
+Init(initConfig);
+```
+
+Render the UI (view config goes here):
+
+```tsx
+import { ChatUI } from "mcp-chat-ui";
+
+export default function App() {
+  return (
+    <ChatUI
+      speechRegion="swedencentral"
+      speechKey="<your-speech-key>"
+      theme={{
+        brand: "#0b1f33",
+        panelBackground: "#ffffff",
+        appBackground: "#f7f7f2",
+        textMain: "#0b1f33",
+      }}
+      fonts={{
+        base: "\"DM Sans\", system-ui, sans-serif",
+      }}
+    />
+  );
+}
+```
+
+Finalize a session (same API used by the Logout button):
+
+```ts
+import { FinalizeSession } from "mcp-chat-ui";
+
+await FinalizeSession({
+  domain: "dab.ae",
+  token: "Bearer <token>",
+});
+```
+
+Initialize a session with service/request IDs (one-time per session):
+
+```ts
+import { InitializeChatSession } from "mcp-chat-ui";
+
+await InitializeChatSession({
+  initServiceId: 1001,
+  initRequestStepId: 2001,
+});
+```
+
+## Service Base URL
+
+- Provide `baseUrl` and the SDK derives RequestStep, TransactionCatalog, Storage,
+  Signature, and the login endpoint from it.
+- Provide `apiSubscriptionKey` for APIM calls to those services.
+
+## Initialize (Login) Flow
+
+- The login endpoint is derived from `baseUrl`.
+- `apiSubscriptionKey` is sent to the login endpoint (or override with `loginSubscriptionKey`).
+- `token` is required in `Init` (use an empty string if you plan to sign in via the
+  panel and let it set the token).
+- `initializeChat: true` triggers the init flow on load and calls
+  `initializeChatClients` only (cache setup).
+- `InitializeChatSession` calls `initializeChat` only. Messages are blocked until
+  it runs once per session.
+- The login panel runs `initializeChatClients` followed by `InitializeChatSession`.
+- If `initializeChat` is `false`, call `InitializeChatSession` manually after
+  login (or before rendering the view) to enable messaging.
+
+## Login From The UI
+
+The SDK ships a Login panel (enabled by default). Click **Login** in
+the top bar, fill the fields (domain, username, password, context window, optional
+service/request step IDs, languages), then submit. The SDK stores common values
+in `localStorage` (session ID, auth token, domain, username) to keep continuity.
+
+To hide the panel:
+
+```ts
+Init({ ...initConfig, showInitPanel: false });
+```
+
+To auto-initialize on load:
+
+```ts
+Init({ ...initConfig, initializeChat: true });
+```
+
+## Configuration Reference
+
+Init (global):
+- `baseUrl` (required): base URL for RequestStep/TransactionCatalog/Storage/Signature/login.
+- `apiSubscriptionKey` (required): subscription key for the base URL.
+- `loginSubscriptionKey` (required): login endpoint subscription key.
+- `token` (required): pre-set auth header value (include scheme).
+- `isDab` (required): if `true`, default domain is `dab.ae`, otherwise blank.
+- `showInitPanel` (optional, default `true`)
+- `initializeChat` (required)
+- `contextWindow` (required)
+
+ChatUI props (view):
+- `initServiceId`, `initRequestStepId`
+- `initPresets`: optional `{ requester, provider }` credentials used to prefill the preset buttons.
+- `speechRegion`, `speechKey`
+- `speechLanguage` (transcription)
+- `ttsLanguage`
+- `ttsVoiceMap`
+- `theme`: see tokens below.
+- `fonts`: `{ base, heading, mono }`.
+- `text`: UI strings (login panel text is fixed and not configurable).
+- `taskCardSize`: `{ width?: number; height?: number }` for task cards in the chat list.
+
+## Theme Tokens
+
+You can override any subset:
+
+- `appBackground`: main page background behind the chat surface.
+- `panelBackground`: main chat panel surface color.
+- `panelBackgroundMuted`: muted surface for translucent panels (top bar, composer).
+- `panelBackgroundSubtle`: lighter surface tint for subtle sections.
+- `brand`: primary brand color for buttons and accents.
+- `brandHover`: hover color for brand buttons.
+- `brandAlpha30`: brand color with ~30% alpha (badges/overlays).
+- `brandAlpha40`: brand color with ~40% alpha.
+- `brandAlpha50`: brand color with ~50% alpha.
+- `textMain`: primary text color.
+- `textEmphasis`: stronger text emphasis for headings.
+- `textSupporting`: secondary text color.
+- `textMuted`: muted body text color.
+- `textSubtle`: subtle labels and placeholders.
+- `textDisabled`: disabled or faint text color.
+- `textOnBrand`: text color used on brand backgrounds.
+- `userMessageBackground`: background color for user chat bubbles.
+- `userMessageText`: text color for user chat bubbles.
+- `neutralLightest`: light neutral background (50).
+- `neutralLighter`: light neutral background (100).
+- `neutralMedium`: neutral mid tone (400).
+- `neutralDark`: dark neutral (800).
+- `neutralDarker`: darkest neutral (900).
+- `neutralDarker80`: darkest neutral with ~80% alpha.
+- `borderDefault`: default border color.
+- `accentBackground`: accent background for info callouts.
+- `accentText`: accent text color for info callouts.
+- `warningBackground`: warning background for alerts.
+- `warningText`: warning text color for alerts.
+- `errorBackground`: error background for alerts.
+- `errorText`: error text color for alerts.
+- `focusRing`: subtle focus ring color.
+- `focusRingStrong`: stronger focus ring color.
+- `outlineShadow`: outline shadow color for buttons.
+- `elevatedShadow`: elevated shadow color for modals/cards.
+- `selectOptionHover`: select option hover/selected background color.
+- `cardSelectedBackground`: selected task card background color.
+
+Legacy theme keys (e.g. `primary`, `background`, `surface`) are still accepted,
+but prefer the names above for new work.
+
+## Text Tokens
+
+Override any subset of strings (login panel text is fixed):
+
+```tsx
+<ChatUI
+  text={{
+    topBar: { clearButton: "Reset" },
+    emptyState: { title: "Whats on the agenda today?" },
+    composer: { placeholderDefault: "Ask me anything" },
+  }}
+/>;
+```
+
+Top bar:
+- `topBar.sessionLabel`
+- `topBar.clearButton`
+- `topBar.clearTitle`
+- `topBar.logoutButton`
+- `topBar.logoutTitle`
+- `topBar.loginButton`
+- `topBar.loginTitle`
+
+Empty state:
+- `emptyState.title`
+
+Composer:
+- `composer.selectedTaskPrefix`
+- `composer.selectionLineTemplate` (supports `{id}`)
+- `composer.selectedTaskClearTitle`
+- `composer.attachTitle`
+- `composer.placeholderAuthRequired`
+- `composer.placeholderDefault`
+- `composer.voiceStartTitle`
+- `composer.voiceStopTitle`
+- `composer.sendTitle`
+
+Voice overlay:
+- `voiceOverlay.cancelTitle`
+- `voiceOverlay.confirmTitle`
+
+Message item:
+- `messageItem.moreButton`
+- `messageItem.selectCardTitle`
+- `messageItem.stopReadingTitle`
+- `messageItem.readMessageTitle`
+- `messageItem.linkButtonLabel`
+
+Task cards:
+- `taskCards.modalTitle`
+- `taskCards.takeActionButton`
+- `taskCards.showDocumentButton`
+
+Document viewer:
+- `documentViewer.title`
+- `documentViewer.downloadButton`
+- `documentViewer.loading`
+- `documentViewer.iframeTitle`
+- `documentViewer.useGoogleViewer`
+- `documentViewer.useDirectViewer`
+- `documentViewer.errorSuffix`
+- `documentViewer.proceedButton`
+
+Take action:
+- `takeAction.backAriaLabel`
+- `takeAction.closeAriaLabel`
+- `takeAction.actionTypeLabel`
+- `takeAction.selectActionPlaceholder`
+- `takeAction.approveOption`
+- `takeAction.rejectOption`
+- `takeAction.commentsLabel`
+- `takeAction.commentsPlaceholder`
+- `takeAction.noEditableAttributes`
+- `takeAction.selectSignaturePlaceholder`
+- `takeAction.selectOptionPlaceholder`
+- `takeAction.signaturePlaceholder`
+- `takeAction.cancelButton`
+- `takeAction.submitButton`
+- `takeAction.nextButton`
+
+Tool result:
+- `toolResult.title`
+
+Alerts:
+- `alerts.clearConfirm`
+- `alerts.clearFailedTemplate` (supports `{error}`)
+- `alerts.fetchHistoryFailed`
+- `alerts.initMissingCredentials`
+- `alerts.initMissingBaseUrl`
+- `alerts.initMissingSubscriptionKey`
+- `alerts.initMissingEndpoint`
+- `alerts.initFailed`
+- `alerts.initNoToken`
+- `alerts.initChatFailedTemplate` (supports `{status}`, `{statusText}`, `{details}`)
+- `alerts.initChatNetworkError`
+- `alerts.initChatErrorTemplate` (supports `{error}`)
+- `alerts.initRequired`
+- `alerts.initNetworkError`
+- `alerts.initErrorTemplate` (supports `{error}`)
+
+Errors:
+- `errors.assistantMessageTemplate` (supports `{error}`)
+- `errors.microphoneAccess`
+- `errors.transcriptionStart`
+- `errors.sasRequestFailedTemplate` (supports `{status}`, `{statusText}`, `{details}`)
+- `errors.noSasEntries`
+- `errors.invalidSasEntry`
+- `errors.chatFailedTemplate` (supports `{status}`, `{statusText}`, `{details}`)
+- `errors.takeActionAuthRequired`
+- `errors.takeActionMissingRequestStep`
+- `errors.takeActionMissingSignature`
+- `errors.takeActionNoDocument`
+
+## Demo App (repo only)
+
+```bash
+cd demo
+npm install
+npm run dev
+```
+
+## Build
+
+```bash
+npm run build
+```

package/dist/ChatUI.d.ts

@@ -0,0 +1,2 @@
+import type { ChatUIProps } from "./models/chat.types";
+export default function ChatUI(props: ChatUIProps): import("react/jsx-runtime").JSX.Element;