@botonic/webchat-react 2.26.0 → 2.27.0

package/CHANGELOG.md

@@ -1,3 +1,35 @@
+## 2.27.0 (2026-04-29)
+
+### 🚀 Features
+
+- **webchat-react:** add design system gateway for @lilara/ui-web-react (BLT-2334) ([#859](https://github.com/metis-ai/hubtype-product/pull/859))
+- **webchat-react:** add webchat header menu (BLT-1861) ([#858](https://github.com/metis-ai/hubtype-product/pull/858))
+- Hero Header transitions ([#860](https://github.com/metis-ai/hubtype-product/pull/860))
+- **webchat-react:** complete CarouselMessage component ([#842](https://github.com/metis-ai/hubtype-product/pull/842))
+- typing to work again and improve it with few modes when sending messages ([#831](https://github.com/metis-ai/hubtype-product/pull/831))
+- **BLT-1884:** wire DialogProvider into webchat and webview render trees ([#837](https://github.com/metis-ai/hubtype-product/pull/837))
+- **BLT-1884:** add Dialog primitive, Backdrop, DialogProvider, and useDialog ([#836](https://github.com/metis-ai/hubtype-product/pull/836))
+- **BLT-1884:** add pauseAll() to MediaPlaybackContext ([#835](https://github.com/metis-ai/hubtype-product/pull/835))
+- **BLT-1884:** add backdrop named grid lines to webchat and webview containers ([#834](https://github.com/metis-ai/hubtype-product/pull/834))
+- receiving db_id, bot_interaction_id and working capture_user_input_id and first_interaction updatable ([#822](https://github.com/metis-ai/hubtype-product/pull/822))
+- **BLT-2281:** webchat chat message media ([#823](https://github.com/metis-ai/hubtype-product/pull/823))
+- **BLT-2291:** attachment input preview with file validation ([#817](https://github.com/metis-ai/hubtype-product/pull/817))
+- **BLT-2293:** send audio messages ([#804](https://github.com/metis-ai/hubtype-product/pull/804))
+- set basis for webchat client settings ([#791](https://github.com/metis-ai/hubtype-product/pull/791))
+
+### 🩹 Fixes
+
+- add missing tokens and update theme ([#864](https://github.com/metis-ai/hubtype-product/pull/864))
+- fix headers after merge ([#863](https://github.com/metis-ai/hubtype-product/pull/863))
+- **BLT-1884:** reset actions/subtitle on variant change; fix DialogDemo layout ([#844](https://github.com/metis-ai/hubtype-product/pull/844))
+- incompatible useWebchatContext export on HMR ([#826](https://github.com/metis-ai/hubtype-product/pull/826))
+- **webchat:** fix scroll fade gradient and recording controls padding #BLT-2317 ([#821](https://github.com/metis-ai/hubtype-product/pull/821))
+
+### ❤️ Thank You
+
+- David Hidalgo @Davidhidalgo
+- Marc Rabat @vanbasten17
+
 ## 2.26.0 (2026-03-31)
 
 ### 🚀 Features

package/CLAUDE.md

@@ -0,0 +1,170 @@
+---
+description: webchat-react conventions — hook/component split, CSS layers, webchat tokens, message components, inline SVGs, and animation patterns
+globs: libs/botonic/webchat-react/**
+alwaysApply: false
+---
+
+# webchat-react
+
+Conventions specific to `libs/botonic/webchat-react`. Base rules in the root `CLAUDE.md` apply here too.
+
+## Hook / Component Split
+
+Every non-trivial component is split into:
+
+- **`use-[component].ts`** — all state, refs, callbacks, derived values; returns named prop bundles
+- **`[component].tsx`** — pure render only; spreads prop bundles from the hook
+
+```
+webchat-input/
+├── use-webchat-input.ts
+├── webchat-input.tsx
+├── webchat-input.module.css
+├── webchat-input.spec.tsx
+└── index.ts
+```
+
+**Before touching any component, check:**
+
+1. Does a `use-[component].ts` already exist? If not, create it as part of your change.
+2. Is all state, refs, callbacks, and derived values in the hook — not in the `.tsx` file?
+3. Does the `.tsx` file only render — no `useState`, `useRef`, `useCallback`, or business logic?
+
+Violating this in a PR is a blocker. When adding a feature or fixing a bug in a component that lacks a hook, refactor it in the same PR.
+
+Hook return shape uses named bundles, not flat props:
+
+```ts
+return {
+  inputProps: { value, onChange: handleChange, onKeyDown: handleKeyDown },
+  primaryActionProps: { onClick: handleSubmit, 'aria-label': submitLabel },
+  variants: { isDisabled, hasError, isEmpty },
+}
+```
+
+## CSS Layers
+
+The cascade stack, from lowest to highest priority:
+
+| Layer                       | Who writes it             | Purpose                                                      |
+| --------------------------- | ------------------------- | ------------------------------------------------------------ |
+| `@layer components`         | webchat-react             | Base component styles                                        |
+| `@layer component-variants` | webchat-react             | Visual variants of components (e.g. different bubble styles) |
+| `@layer overrides`          | `webchat-tokens.css` only | Library-default token values                                 |
+| _(unlayered)_               | Bot app consumers         | Final consumer customizations — always wins                  |
+
+**Component styles → `@layer components`.**
+
+```css
+@layer components {
+  .documentMessage {
+    width: auto;
+  }
+}
+```
+
+**CSS animations:** declare `@keyframes` outside any layer (global scope), use them inside `@layer components`. Add `@media (prefers-reduced-motion: reduce)` outside any layer too.
+
+**Token default values → `@layer overrides`** in `webchat-tokens.css` only. Bot apps override tokens with unlayered CSS in their own `webchat-tokens-overrides.css`.
+
+```css
+/* webchat-tokens.css */
+@layer overrides {
+  :root {
+    --webchat-input-bg: var(--color-neutral-white);
+    --webchat-send-button-color: var(--color-primary-500);
+  }
+}
+```
+
+> **Never add end-consumer override CSS in library code.** The `@layer overrides` in `webchat-tokens.css` is for library defaults only. Bot apps write their own overrides in `webchat-tokens-overrides.css`.
+
+## Webchat Tokens (`--webchat-*`)
+
+Every value a consumer might want to customize must be a `--webchat-*` token defined in `webchat-tokens.css`.
+
+Pattern: `--webchat-{component}-{property}` with fallback to a foundations token:
+
+```css
+--webchat-input-bg: var(--color-neutral-white);
+--webchat-bubble-bot-bg: var(--color-neutral-100);
+```
+
+## Message Components
+
+```
+components/message/[message-type]/
+├── [message-type]-message.tsx     # forwardRef, extends MessageProps
+├── [message-type]-message.module.css
+├── [message-type]-message.stories.tsx
+└── index.ts
+```
+
+See the `create-new-message-type` skill for the full step-by-step guide.
+
+## Inline SVGs
+
+No external icon library. Rules:
+
+1. Extract each SVG into a **React function component** in `webchat-input/icons/` (e.g. `play-icon.tsx`)
+2. Use `currentColor` for fill/stroke
+3. Set `role='img'` and `aria-hidden={true}` on decorative SVGs
+4. Import and render as `<PlayIcon />` — never inline SVG markup inside a component
+
+```tsx
+// Good — dedicated icon component
+// webchat-input/icons/play-icon.tsx
+export function PlayIcon() {
+  return (
+    <svg viewBox='0 0 24 24' fill='currentColor' role='img' aria-hidden={true}>
+      <polygon points='5,3 19,12 5,21' />
+    </svg>
+  )
+}
+
+// Good — import and use
+import { PlayIcon } from '../icons/play-icon'
+const MyButton = () => (
+  <button>
+    <PlayIcon />
+  </button>
+)
+
+// Bad — SVG inlined directly inside a component
+const MyButton = () => (
+  <button>
+    <svg viewBox='0 0 24 24'>...</svg>
+  </button>
+)
+```
+
+## Animations
+
+Prefer CSS keyframes over JS animation libraries. Define keyframes **outside any layer**, use them inside `@layer component-variants`. Always add `prefers-reduced-motion`.
+
+```css
+@keyframes webchat-fade-in {
+  from {
+    opacity: 0;
+    transform: translateY(4px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@layer component-variants {
+  .messageEnter {
+    animation: webchat-fade-in var(--webchat-animation-duration, var(--transition-fast)) var(--webchat-animation-easing, ease-out) both;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .messageEnter {
+    animation: none;
+  }
+}
+```
+
+See the `webchat-animations` skill for token naming conventions and keyframe architecture.

package/index.d.ts

@@ -5,8 +5,7 @@
  *
  * ## Embedded Webchat (full control)
  * ```tsx
- * import { WebchatProvider, WebchatContainer, WebchatMessages, WebchatInput } from '@botonic/webchat-react'
- * import { Button } from '@lilara/ui-web-react'
+ * import { WebchatProvider, WebchatContainer, WebchatMessages, WebchatInput, Button } from '@botonic/webchat-react'
  * import '@lilara/foundations/base.css'
  * import '@lilara/ui-web-react/styles.css'
  * import '@botonic/webchat-react/styles.css'
@@ -37,10 +36,15 @@
  * window.botonic.open()
  * ```
  */
-export { useWebchatContext, WebchatProvider, } from './lib/components/webchat-provider/webchat-provider';
+export { useWebchatContext } from './lib/components/webchat-provider/webchat-context';
+export { WebchatProvider } from './lib/components/webchat-provider/webchat-provider';
 export { WebchatApp, type WebchatAppProps } from './lib/components/webchat-app';
 export { WebchatContainer } from './lib/components/webchat-container/webchat-container';
-export { WebchatHeader } from './lib/components/webchat-header/webchat-header';
+export { CloseButton, MenuTriggerButton, WebchatHeader, } from './lib/components/webchat-header/webchat-header';
+export { DropdownMenuItemDownloadTranscript, type DropdownMenuItemDownloadTranscriptProps, } from './lib/components/webchat-header/webchat-menu/dropdown-menu-item-download-transcript';
+export { DropdownMenuItemResetConversation, type DropdownMenuItemResetConversationProps, } from './lib/components/webchat-header/webchat-menu/dropdown-menu-item-reset-conversation';
+export { DropdownMenuItemResetSession, type DropdownMenuItemResetSessionProps, } from './lib/components/webchat-header/webchat-menu/dropdown-menu-item-reset-session';
+export { DropdownMenuItemSounds, type DropdownMenuItemSoundsProps, } from './lib/components/webchat-header/webchat-menu/dropdown-menu-item-sounds';
 export { WebchatInput } from './lib/components/webchat-input/webchat-input';
 export { WebchatMessages } from './lib/components/webchat-messages/webchat-messages';
 export { useWebchatContainer } from './lib/components/webchat-container/use-webchat-container';
@@ -48,12 +52,15 @@ export { useWebchatHeader } from './lib/components/webchat-header/use-webchat-he
 export { useWebchatInput } from './lib/components/webchat-input/use-webchat-input';
 export { useWebchatMessages } from './lib/components/webchat-messages/use-webchat-messages';
 export { useWebchatState } from './lib/hooks/use-webchat-state';
+export { DEFAULT_WEBCHAT_HERO_HEADER_LAYOUT_CONFIG, getMessageActorCount, mergeWebchatHeroHeaderLayoutConfig, useWebchatHeroHeaderLayout, type UseWebchatHeroHeaderLayoutParams, type WebchatHeroHeaderLayoutConfig, type WebchatHeroHeaderLayoutResult, } from './lib/hero-header-layout';
 export { Message, type MessageProps } from './lib/components/message/message';
 export { MessageBubble, type MessageBubbleProps, } from './lib/components/message/message/message-bubble';
+export { TypingIndicator } from './lib/components/message/typing-message';
 export { MessageMachineRenderer } from './lib/components/message-machine-renderer/message-machine-renderer';
-export { TypingIndicator } from './lib/components/typing-indicator/typing-indicator';
+export { Backdrop, Dialog, type DialogAction, DialogContext, type DialogControls, type DialogOpenProps, DialogProvider, type DialogState, type DialogVariant, useDialog, } from './lib/components/dialog';
 export { type CoverComponentRegistry, Overlay, OverlayConfirmModal, type OverlayConfirmModalProps, OverlayContent, type OverlayContentProps, OverlayContext, type OverlayContextValue, OverlayCoverFrame, type OverlayCoverFrameProps, OverlayHeader, type OverlayHeaderProps, type OverlayProps, OverlayWebviewFrame, type OverlayWebviewFrameProps, useOverlay, useOverlayContext, useOverlayHeader, } from './lib/components/webchat-overlay';
 export { ButtonComponent, type ButtonComponentProps, } from './lib/components/shared';
 export * from './lib/types/primitives';
 export * from './lib/types/webchat-props';
 export type { WebchatConfig, WebchatController, WebchatEmittedEvent, } from '@botonic/webchat-core';
+export { Badge, type BadgeProps, Banner, type BannerProps, Button, type ButtonProps, Checkbox, type CheckboxProps, Multiselect, type MultiselectProps, MultiselectWithSections, type MultiselectWithSectionsProps, Select, type SelectItem, type SelectProps, type SelectSection, SelectWithSections, type SelectWithSectionsProps, Slider, type SliderProps, Spinner, type SpinnerProps, Switch, type SwitchProps, Tag, type TagProps, TextArea, type TextAreaProps, TextInput, type TextInputProps, Tooltip, type TooltipProps, } from '@lilara/ui-web-react';

package/index.js

@@ -1,30 +1,61 @@
-import { B as s, M as t, a as r, b as n, O as o, c as b, d as c, e as h, f as u, g as v, h as W, T as l, W as y, i as O, j as d, k as i, l as C, m as p, u as M, n as g, o as m, p as x, q as H, r as f, s as B, t as I, v as F } from "./webchat-app-CLGvs-LL.js";
+import { B as s, a as t, C as o, D as r, b as n, c as u, d as i, e as c, f as l, g as d, h, M as b, i as g, j as W, k as p, O as C, l as v, m as M, n as y, o as O, p as m, q as D, T as H, W as T, r as x, s as B, t as I, u as S, v as w, w as A, x as E, y as f, z as F, A as L, E as R, F as _, G as k, H as G, I as P, J as U, K as j, L as q } from "./webchat-app-DSDMjE-m.js";
+import { Badge as J, Banner as K, Button as N, Checkbox as Y, Multiselect as Q, MultiselectWithSections as V, Select as X, SelectWithSections as Z, Slider as $, Spinner as ee, Switch as ae, Tag as se, TextArea as te, TextInput as oe, Tooltip as re } from "@lilara/ui-web-react";
 export {
-  s as ButtonComponent,
-  t as Message,
-  r as MessageBubble,
-  n as MessageMachineRenderer,
-  o as Overlay,
-  b as OverlayConfirmModal,
-  c as OverlayContent,
-  h as OverlayContext,
-  u as OverlayCoverFrame,
-  v as OverlayHeader,
-  W as OverlayWebviewFrame,
-  l as TypingIndicator,
-  y as WebchatApp,
-  O as WebchatContainer,
-  d as WebchatHeader,
-  i as WebchatInput,
-  C as WebchatMessages,
-  p as WebchatProvider,
-  M as useOverlay,
-  g as useOverlayContext,
-  m as useOverlayHeader,
-  x as useWebchatContainer,
-  H as useWebchatContext,
-  f as useWebchatHeader,
-  B as useWebchatInput,
-  I as useWebchatMessages,
-  F as useWebchatState
+  s as Backdrop,
+  J as Badge,
+  K as Banner,
+  N as Button,
+  t as ButtonComponent,
+  Y as Checkbox,
+  o as CloseButton,
+  r as DEFAULT_WEBCHAT_HERO_HEADER_LAYOUT_CONFIG,
+  n as Dialog,
+  u as DialogContext,
+  i as DialogProvider,
+  c as DropdownMenuItemDownloadTranscript,
+  l as DropdownMenuItemResetConversation,
+  d as DropdownMenuItemResetSession,
+  h as DropdownMenuItemSounds,
+  b as MenuTriggerButton,
+  g as Message,
+  W as MessageBubble,
+  p as MessageMachineRenderer,
+  Q as Multiselect,
+  V as MultiselectWithSections,
+  C as Overlay,
+  v as OverlayConfirmModal,
+  M as OverlayContent,
+  y as OverlayContext,
+  O as OverlayCoverFrame,
+  m as OverlayHeader,
+  D as OverlayWebviewFrame,
+  X as Select,
+  Z as SelectWithSections,
+  $ as Slider,
+  ee as Spinner,
+  ae as Switch,
+  se as Tag,
+  te as TextArea,
+  oe as TextInput,
+  re as Tooltip,
+  H as TypingIndicator,
+  T as WebchatApp,
+  x as WebchatContainer,
+  B as WebchatHeader,
+  I as WebchatInput,
+  S as WebchatMessages,
+  w as WebchatProvider,
+  A as getMessageActorCount,
+  E as mergeWebchatHeroHeaderLayoutConfig,
+  f as useDialog,
+  F as useOverlay,
+  L as useOverlayContext,
+  R as useOverlayHeader,
+  _ as useWebchatContainer,
+  k as useWebchatContext,
+  G as useWebchatHeader,
+  P as useWebchatHeroHeaderLayout,
+  U as useWebchatInput,
+  j as useWebchatMessages,
+  q as useWebchatState
 };

package/lib/components/dialog/backdrop/backdrop.d.ts

@@ -0,0 +1,5 @@
+interface BackdropProps {
+    isClosing?: boolean;
+}
+export declare function Backdrop({ isClosing }: BackdropProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/lib/components/dialog/dialog/dialog.d.ts

@@ -0,0 +1,7 @@
+import { DialogState, DialogVariant } from '../dialog-types';
+type DialogProps = Omit<DialogState, 'isOpen'> & {
+    isClosing?: boolean;
+    onExited?: () => void;
+};
+export declare function Dialog({ variant, title, subtitle, actions, isClosing, onExited, }: DialogProps): import("react/jsx-runtime").JSX.Element;
+export type { DialogVariant };

package/lib/components/dialog/dialog-context.d.ts

@@ -0,0 +1,3 @@
+import { DialogControls } from './dialog-types';
+export declare const DialogContext: import('react').Context<DialogControls | null>;
+export declare function useDialog(): DialogControls;

package/lib/components/dialog/dialog-provider.d.ts

@@ -0,0 +1,17 @@
+import { ReactNode } from 'react';
+import { DialogControls } from './dialog-types';
+interface DialogProviderProps {
+    children: ReactNode;
+    /**
+     * Called synchronously before the dialog opens.
+     * Use this to pause media, blur backgrounds, etc.
+     */
+    onOpen?: () => void;
+    /**
+     * Optional ref that will be populated with the dialog controls on mount.
+     * Useful for wiring the controls to external callers (e.g. the public API).
+     */
+    controlsRef?: React.MutableRefObject<Pick<DialogControls, 'open' | 'update' | 'close'> | null>;
+}
+export declare function DialogProvider({ children, onOpen, controlsRef, }: DialogProviderProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/lib/components/dialog/dialog-types.d.ts

@@ -0,0 +1,24 @@
+import { ButtonProps } from '@lilara/ui-web-react';
+export type DialogVariant = 'default' | 'loading' | 'error' | 'success';
+export type DialogAction = Omit<ButtonProps, 'children'> & {
+    label: string;
+};
+export interface DialogOpenProps {
+    variant?: DialogVariant;
+    title: string;
+    subtitle?: string;
+    actions?: DialogAction[];
+}
+export interface DialogState {
+    isOpen: boolean;
+    variant: DialogVariant;
+    title: string;
+    subtitle?: string;
+    actions?: DialogAction[];
+}
+export interface DialogControls {
+    open: (props: DialogOpenProps) => void;
+    update: (props: Partial<DialogOpenProps>) => void;
+    close: () => void;
+    dialogState: DialogState;
+}

package/lib/components/dialog/icons/check-icon.d.ts

@@ -0,0 +1 @@
+export declare function CheckIcon(): import("react/jsx-runtime").JSX.Element;

package/lib/components/dialog/icons/xmark-icon.d.ts

@@ -0,0 +1 @@
+export declare function XmarkIcon(): import("react/jsx-runtime").JSX.Element;

package/lib/components/dialog/index.d.ts

@@ -0,0 +1,5 @@
+export { Backdrop } from './backdrop/backdrop';
+export { Dialog } from './dialog/dialog';
+export { DialogContext, useDialog } from './dialog-context';
+export { DialogProvider } from './dialog-provider';
+export type { DialogAction, DialogControls, DialogOpenProps, DialogState, DialogVariant, } from './dialog-types';

package/lib/components/dialog/webchat-dialog-provider.d.ts

@@ -0,0 +1,6 @@
+import { ReactNode } from 'react';
+interface WebchatDialogProviderProps {
+    children: ReactNode;
+}
+export declare function WebchatDialogProvider({ children, }: WebchatDialogProviderProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/lib/components/message/audio-message/audio-message.d.ts

@@ -2,6 +2,8 @@ import { MessageProps } from '../message';
 export interface AudioMessageProps extends Omit<MessageProps, 'children'> {
     /** The audio URL. */
     src: string;
+    /** Unique message identifier — used to coordinate exclusive playback. */
+    messageId?: string;
     /** Alt text for the audio (for accessibility). */
     alt?: string;
     /** Callback when audio loads (useful for scroll adjustment). */