@botonic/webchat-react 2.23.1

package/lib/components/webchat-messages/use-webchat-messages.d.ts

@@ -0,0 +1,54 @@
+import { RefObject } from 'react';
+import { WebchatState } from '../../hooks/use-webchat-state';
+import { WebchatMessagesProps } from '../../types/webchat-props';
+export declare function useWebchatMessages(props: WebchatMessagesProps, state: WebchatState, ref: RefObject<HTMLDivElement>): {
+    messagesProps: {
+        ref: RefObject<HTMLDivElement>;
+        'aria-label': string;
+        'aria-live': "polite";
+        'data-webchat-messages': string;
+        enableScrollToBottom?: boolean;
+    };
+    messageListProps: {
+        messageActors: import('xstate').ActorRef<import('xstate').MachineSnapshot<{
+            message: import('@botonic/shared').WebchatMessage;
+            user: import('@botonic/shared').HubtypeUser;
+            status: import('@botonic/webchat-core').WebchatMessageStatus;
+            postMessageActor?: any;
+        }, {
+            type: "RETRY";
+        } | {
+            type: "BUTTON_CLICKED";
+            button: import('@botonic/shared').BotonicButtonContent;
+        }, {
+            [x: string]: import('xstate').ActorRefFromLogic<import('@botonic/webchat-core').PostMessageActor> | undefined;
+        }, "checkStatus" | "sending" | "idle" | "errorSendingMessage" | "performingPostback", string, import('xstate').NonReducibleUnknown, import('xstate').MetaObject, {
+            states: {
+                readonly checkStatus: {};
+                readonly sending: {};
+                readonly idle: {};
+                readonly performingPostback: {};
+                readonly errorSendingMessage: {};
+            };
+        }>, {
+            type: "RETRY";
+        } | {
+            type: "BUTTON_CLICKED";
+            button: import('@botonic/shared').BotonicButtonContent;
+        }, {
+            type: "PERSISTENCE.SAVE_MESSAGE";
+        } | {
+            type: "WEBVIEW.OPEN";
+            url: string;
+            title: string;
+        }>[];
+        isTyping: any;
+        customMessageRenderer: undefined;
+        botAvatarConfig: import('../message-machine-renderer').AvatarConfigResult | null;
+        agentAvatarConfig: import('../message-machine-renderer').AvatarConfigResult | null;
+    };
+    variants: {
+        variant: "default";
+        className: string | undefined;
+    };
+};

package/lib/components/webchat-messages/webchat-messages.d.ts

@@ -0,0 +1,2 @@
+import { WebchatMessagesProps } from '../../types/webchat-props';
+export declare function WebchatMessages(props: WebchatMessagesProps): import("react/jsx-runtime").JSX.Element;

package/lib/components/webchat-overlay/base/confirm-modal/confirm-modal.d.ts

@@ -0,0 +1,8 @@
+import { ConfirmCloseOption } from '@botonic/webchat-core';
+import { FC } from 'react';
+export interface OverlayConfirmModalProps {
+    config: ConfirmCloseOption;
+    onConfirm: () => void;
+    onCancel: () => void;
+}
+export declare const OverlayConfirmModal: FC<OverlayConfirmModalProps>;

package/lib/components/webchat-overlay/base/confirm-modal/index.d.ts

@@ -0,0 +1,2 @@
+export type { OverlayConfirmModalProps } from './confirm-modal';
+export { OverlayConfirmModal } from './confirm-modal';

package/lib/components/webchat-overlay/base/content/content.d.ts

@@ -0,0 +1,9 @@
+export interface OverlayContentProps {
+    className?: string;
+}
+/**
+ * Renders the appropriate content based on the overlay type.
+ * - For 'webview': renders an iframe via OverlayWebviewFrame
+ * - For 'cover': renders a registered React component via OverlayCoverFrame
+ */
+export declare function OverlayContent({ className }: OverlayContentProps): import("react/jsx-runtime").JSX.Element | null;

package/lib/components/webchat-overlay/base/content/index.d.ts

@@ -0,0 +1,2 @@
+export type { OverlayContentProps } from './content';
+export { OverlayContent } from './content';

package/lib/components/webchat-overlay/base/header/header.d.ts

@@ -0,0 +1,4 @@
+export interface OverlayHeaderProps {
+    variant?: 'default' | 'minimal';
+}
+export declare function OverlayHeader(props: OverlayHeaderProps): import("react/jsx-runtime").JSX.Element;

package/lib/components/webchat-overlay/base/header/index.d.ts

@@ -0,0 +1,3 @@
+export type { OverlayHeaderProps } from './header';
+export { OverlayHeader } from './header';
+export { useOverlayHeader } from './use-header';

package/lib/components/webchat-overlay/base/header/use-header.d.ts

@@ -0,0 +1,13 @@
+import { OverlayState } from '@botonic/webchat-core';
+export interface OverlayHeaderVariants {
+    variant: 'default' | 'minimal';
+}
+export interface UseOverlayHeaderResult {
+    title: string;
+    icon: string | undefined;
+    showClose: boolean;
+    variants: OverlayHeaderVariants;
+}
+export declare function useOverlayHeader(props: {
+    variant?: 'default' | 'minimal';
+}, overlayState: OverlayState | null): UseOverlayHeaderResult;

package/lib/components/webchat-overlay/base/index.d.ts

@@ -0,0 +1,5 @@
+export { Overlay, type OverlayProps, useOverlay } from './overlay';
+export { type CoverComponentRegistry, OverlayContext, type OverlayContextValue, useOverlayContext, } from './overlay-context';
+export { OverlayHeader, type OverlayHeaderProps, useOverlayHeader, } from './header';
+export { OverlayContent, type OverlayContentProps } from './content';
+export { OverlayConfirmModal, type OverlayConfirmModalProps, } from './confirm-modal';

package/lib/components/webchat-overlay/base/overlay/index.d.ts

@@ -0,0 +1,3 @@
+export type { OverlayProps } from './overlay';
+export { Overlay } from './overlay';
+export { useOverlay } from './use-overlay';

package/lib/components/webchat-overlay/base/overlay/overlay.d.ts

@@ -0,0 +1,18 @@
+import { ConfirmCloseOption, OverlayState } from '@botonic/webchat-core';
+import { ReactNode } from 'react';
+import { CoverComponentRegistry } from '../overlay-context';
+export interface OverlayProps {
+    /** The current overlay state (webview or cover) */
+    overlayState: OverlayState | null;
+    onClose: () => void;
+    onSetTitle: (title: string) => void;
+    onSetIcon: (icon: string) => void;
+    onSetAllowClose: (allow: boolean) => void;
+    onSetConfirmClose: (config: ConfirmCloseOption) => void;
+    onSendPayload: (payload: unknown) => void;
+    onNavigate: (url: string) => void;
+    /** Registry of cover components that can be opened */
+    coverRegistry?: CoverComponentRegistry;
+    children?: ReactNode;
+}
+export declare function Overlay({ overlayState, onClose, onSetTitle, onSetIcon, onSetAllowClose, onSetConfirmClose, onSendPayload, onNavigate, coverRegistry, children, }: OverlayProps): import("react/jsx-runtime").JSX.Element | null;

package/lib/components/webchat-overlay/base/overlay/use-overlay.d.ts

@@ -0,0 +1,23 @@
+import { ConfirmCloseOption, OverlayState } from '@botonic/webchat-core';
+export interface OverlayHandlers {
+    onClose: () => void;
+    onSetTitle: (title: string) => void;
+    onSetIcon: (icon: string) => void;
+    onSetAllowClose: (allow: boolean) => void;
+    onSetConfirmClose: (config: ConfirmCloseOption) => void;
+    onSendPayload: (payload: unknown) => void;
+    onNavigate: (url: string) => void;
+}
+export interface UseOverlayResult {
+    isLoading: boolean;
+    setIsLoading: (loading: boolean) => void;
+    showConfirmModal: boolean;
+    setShowConfirmModal: (show: boolean) => void;
+    attemptClose: () => void;
+    handleConfirmClose: () => void;
+    handleCancelClose: () => void;
+    variants: {
+        isLoading: boolean;
+    };
+}
+export declare function useOverlay(overlayState: OverlayState | null, handlers: OverlayHandlers): UseOverlayResult;

package/lib/components/webchat-overlay/base/overlay-context.d.ts

@@ -0,0 +1,25 @@
+import { ConfirmCloseOption, OverlayState } from '@botonic/webchat-core';
+import { ComponentType } from 'react';
+/**
+ * Registry of cover components that can be opened in the overlay
+ */
+export type CoverComponentRegistry = Record<string, ComponentType<any>>;
+export interface OverlayContextValue {
+    overlayState: OverlayState | null;
+    onClose: () => void;
+    onSetTitle: (title: string) => void;
+    onSetIcon: (icon: string) => void;
+    onSetAllowClose: (allow: boolean) => void;
+    onSetConfirmClose: (config: ConfirmCloseOption) => void;
+    onSendPayload: (payload: unknown) => void;
+    onNavigate: (url: string) => void;
+    sandboxPermissions: string;
+    isLoading: boolean;
+    setIsLoading: (loading: boolean) => void;
+    attemptClose: () => void;
+    showConfirmModal: boolean;
+    setShowConfirmModal: (show: boolean) => void;
+    coverRegistry?: CoverComponentRegistry;
+}
+export declare const OverlayContext: import('react').Context<OverlayContextValue | null>;
+export declare function useOverlayContext(): OverlayContextValue;

package/lib/components/webchat-overlay/cover/frame/cover-frame.d.ts

@@ -0,0 +1,8 @@
+export interface OverlayCoverFrameProps {
+    className?: string;
+}
+/**
+ * Renders a registered React component for cover overlays.
+ * Only renders when the overlay is of type 'cover'.
+ */
+export declare function OverlayCoverFrame({ className }: OverlayCoverFrameProps): import("react/jsx-runtime").JSX.Element | null;

package/lib/components/webchat-overlay/cover/frame/index.d.ts

@@ -0,0 +1,2 @@
+export type { OverlayCoverFrameProps } from './cover-frame';
+export { OverlayCoverFrame } from './cover-frame';

package/lib/components/webchat-overlay/cover/index.d.ts

@@ -0,0 +1 @@
+export { OverlayCoverFrame, type OverlayCoverFrameProps } from './frame';

package/lib/components/webchat-overlay/index.d.ts

@@ -0,0 +1,3 @@
+export { type CoverComponentRegistry, Overlay, OverlayConfirmModal, type OverlayConfirmModalProps, OverlayContent, type OverlayContentProps, OverlayContext, type OverlayContextValue, OverlayHeader, type OverlayHeaderProps, type OverlayProps, useOverlay, useOverlayContext, useOverlayHeader, } from './base';
+export { OverlayCoverFrame, type OverlayCoverFrameProps } from './cover';
+export { OverlayWebviewFrame, type OverlayWebviewFrameProps } from './webview';

package/lib/components/webchat-overlay/webview/frame/index.d.ts

@@ -0,0 +1,2 @@
+export type { OverlayWebviewFrameProps } from './webview-frame';
+export { OverlayWebviewFrame } from './webview-frame';

package/lib/components/webchat-overlay/webview/frame/webview-frame.d.ts

@@ -0,0 +1,8 @@
+export interface OverlayWebviewFrameProps {
+    className?: string;
+}
+/**
+ * Renders an iframe for webview overlays.
+ * Only renders when the overlay is of type 'webview'.
+ */
+export declare function OverlayWebviewFrame({ className }: OverlayWebviewFrameProps): import("react/jsx-runtime").JSX.Element | null;

package/lib/components/webchat-overlay/webview/index.d.ts

@@ -0,0 +1 @@
+export { OverlayWebviewFrame, type OverlayWebviewFrameProps } from './frame';

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

@@ -0,0 +1,22 @@
+import { WebchatController } from '@botonic/webchat-core';
+import { default as React } from 'react';
+import { WebchatState, WebchatStateProps } from '../../hooks/use-webchat-state';
+interface WebchatContextValue {
+    state: WebchatState;
+    controller: WebchatController;
+}
+export interface WebchatProviderProps extends WebchatStateProps {
+    children: React.ReactNode;
+}
+/**
+ * XState-based WebchatProvider that uses the new separated architecture
+ *
+ * This provider uses WebchatController with initialization and operational machines.
+ * It provides better state management, persistence, and error handling.
+ */
+export declare const WebchatProvider: React.ForwardRefExoticComponent<WebchatProviderProps & React.RefAttributes<WebchatController>>;
+/**
+ * Hook to access webchat context
+ */
+export declare function useWebchatContext(): WebchatContextValue;
+export {};

package/lib/components/webchat-trigger/use-webchat-trigger.d.ts

@@ -0,0 +1,38 @@
+import { AnimationEvent, ComponentType, LazyExoticComponent, RefObject } from 'react';
+import { WebchatCompositionProps, WebchatTriggerProps } from '../../types/webchat-props';
+export interface WebchatTriggerHookReturn {
+    triggerProps: {
+        ref: RefObject<HTMLButtonElement>;
+        type: 'button';
+        onClick: () => void;
+        onAnimationEnd?: (e: AnimationEvent<HTMLButtonElement>) => void;
+        'aria-label': string;
+        'aria-expanded': boolean;
+    };
+    icon: React.ReactNode;
+    isOpen: boolean;
+    className?: string;
+    variants: {
+        position: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+        isPulsing?: boolean;
+        isAppearing?: boolean;
+        isOpening?: boolean;
+        isClosing?: boolean;
+        isLoading: boolean;
+        isOpen: boolean;
+    };
+    webchatProps: WebchatCompositionProps;
+    /** When true, render the lazy webchat inside Suspense (loads on first open) */
+    shouldRenderWebchat: boolean;
+    /** Lazy component for default or custom composition (use inside Suspense) */
+    LazyWebchat: LazyExoticComponent<ComponentType<WebchatCompositionProps>> | null;
+    /** Load failed (e.g. chunk error); trigger can show retry */
+    loadError: boolean;
+    /** Call to retry loading after loadError */
+    retryLoad: () => void;
+    /** Call when lazy load fails (pass to Error Boundary onError) */
+    handleLoadError: (error: Error) => void;
+    /** Increments on retry; use as key for Error Boundary so it resets */
+    retryKey: number;
+}
+export declare function useWebchatTrigger(props: WebchatTriggerProps, ref: RefObject<HTMLButtonElement>): WebchatTriggerHookReturn;

package/lib/components/webchat-trigger/webchat-trigger-error-boundary.d.ts

@@ -0,0 +1,19 @@
+import { Component, ReactNode } from 'react';
+export interface WebchatTriggerErrorBoundaryProps {
+    onError: (error: Error) => void;
+    children: ReactNode;
+}
+/**
+ * Catches errors from lazy-loaded webchat (e.g. chunk load failure).
+ * Calls onError so the trigger can show retry state.
+ */
+export declare class WebchatTriggerErrorBoundary extends Component<WebchatTriggerErrorBoundaryProps> {
+    state: {
+        hasError: boolean;
+    };
+    static getDerivedStateFromError(): {
+        hasError: true;
+    };
+    componentDidCatch(error: Error): void;
+    render(): ReactNode;
+}

package/lib/components/webchat-trigger/webchat-trigger.d.ts

@@ -0,0 +1,2 @@
+import { WebchatTriggerProps } from '../../types/webchat-props';
+export declare function WebchatTrigger(props: WebchatTriggerProps): import("react/jsx-runtime").JSX.Element;

package/lib/hooks/use-webchat-state.d.ts

@@ -0,0 +1,21 @@
+import { OverlayState, WebchatConfig, WebchatController, WebchatMessageMachine } from '@botonic/webchat-core';
+import { ActorRefFrom } from 'xstate';
+import { AvatarConfig } from '../components/message-machine-renderer/use-avatar';
+export type WebchatStateProps = WebchatConfig & {
+    avatarConfig?: AvatarConfig;
+    customMessages: any;
+};
+export interface WebchatState {
+    controller: WebchatController;
+    inputValue: string;
+    setInputValue: (value: string) => void;
+    isOpen: boolean;
+    isInitialized: boolean;
+    initializationError: boolean;
+    messageActors: ActorRefFrom<typeof WebchatMessageMachine>[];
+    connectionStatus: string;
+    overlayState: OverlayState | null;
+    avatarConfig?: AvatarConfig;
+    customMessages: any;
+}
+export declare function useWebchatState(stateProps: WebchatStateProps): WebchatState;

package/lib/types/primitives.d.ts

@@ -0,0 +1,15 @@
+export interface MessageListProps {
+    messages: any[];
+    onMessageClick?: (messageId: string) => void;
+    customRenderer?: (message: any) => React.ReactNode;
+    className?: string;
+}
+export interface UserInputPanelProps {
+    value: string;
+    placeholder?: string;
+    onValueChange: (value: string) => void;
+    onFormSubmit: (event: Event) => void;
+    hasContent: boolean;
+    showAttachmentButton?: boolean;
+    isDisabled?: boolean;
+}

package/lib/types/webchat-props.d.ts

@@ -0,0 +1,103 @@
+import { WebchatController } from '@botonic/webchat-core';
+import { ComponentType, ReactNode } from 'react';
+import { CoverComponentRegistry } from '../components/webchat-overlay';
+export interface BaseWebchatProps {
+    className?: string;
+    'aria-label'?: string;
+}
+/**
+ * Props passed to custom webchat composition components.
+ * Implement this interface when creating a custom webchat layout.
+ *
+ * @example
+ * ```tsx
+ * // my-webchat.tsx
+ * import { WebchatCompositionProps, WebchatProvider, WebchatContainer } from '@botonic/webchat-react'
+ *
+ * export default function MyWebchat(props: WebchatCompositionProps) {
+ *   return (
+ *     <WebchatProvider {...props}>
+ *       <WebchatContainer>
+ *         <MyCustomHeader />
+ *         <WebchatMessages />
+ *         <WebchatInput />
+ *       </WebchatContainer>
+ *     </WebchatProvider>
+ *   )
+ * }
+ * ```
+ */
+export interface WebchatCompositionProps {
+    /** Hubtype App ID */
+    appId: string;
+    /** Whether the webchat is open */
+    isOpen: boolean;
+    /** Callback when webchat should close */
+    onClose: () => void;
+    /** Callback when controller is ready - must be called for trigger to work */
+    onControllerReady: (controller: WebchatController) => void;
+    /** Additional config passed from WebchatTrigger */
+    [key: string]: unknown;
+}
+/** Loader function type for lazy loading custom webchat compositions */
+export type WebchatLoader = () => Promise<{
+    default: ComponentType<WebchatCompositionProps>;
+}>;
+export interface WebchatContainerProps extends BaseWebchatProps {
+    children: ReactNode;
+    layout?: 'default';
+    size?: 'compact' | 'normal' | 'large';
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    /**
+     * Registry of cover components that can be opened in the overlay.
+     * Use controller.overlay.openCover(componentId) to open a registered component.
+     */
+    coverRegistry?: CoverComponentRegistry;
+}
+export interface WebchatMessagesProps extends BaseWebchatProps {
+    variant?: 'default';
+    enableScrollToBottom?: boolean;
+}
+export interface WebchatInputProps extends BaseWebchatProps {
+    placeholder?: string;
+    variant?: 'default';
+    disabled?: boolean;
+}
+export interface WebchatHeaderProps extends BaseWebchatProps {
+    title?: string;
+    showStatus?: boolean;
+    showClose?: boolean;
+    onClose?: () => void;
+    variant?: 'default';
+}
+export interface WebchatTriggerProps extends BaseWebchatProps {
+    /** Hubtype App ID - required for webchat connection */
+    appId: string;
+    /** Position on screen */
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    /** Custom icon for the trigger */
+    icon?: ReactNode;
+    /** Pulsing animation */
+    isPulsing?: boolean;
+    /** Additional webchat configuration passed to composition component */
+    webchatConfig?: Record<string, unknown>;
+    /**
+     * Callback when webchat is fully loaded and ready.
+     * Receives the controller for full control (e.g., controller.open(), logging, analytics).
+     * The webchat loads automatically on mount; onReady decides whether to open or not.
+     */
+    onReady?: (controller: WebchatController) => void;
+    /**
+     * Custom webchat composition loader for full composition control.
+     * If not provided, uses default WebchatApp.
+     *
+     * @example
+     * ```tsx
+     * <WebchatTrigger
+     *   appId="xxx"
+     *   loader={() => import('./my-webchat')}
+     * />
+     * ```
+     */
+    loader?: WebchatLoader;
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@botonic/webchat-react",
+  "version": "2.23.1",
+  "type": "module",
+  "types": "./index.d.ts",
+  "module": "./index.js",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    },
+    "./trigger": {
+      "types": "./trigger.d.ts",
+      "import": "./trigger.js"
+    },
+    "./styles.css": "./styles.css"
+  },
+  "dependencies": {
+    "@lilara/foundations": ">=0.3.1",
+    "@lilara/ui-web-react": ">=0.3.1",
+    "class-variance-authority": "^0.7.0",
+    "react-aria": "3.33.1",
+    "@xstate/react": "^5.0.4"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "@botonic/webchat-core": "2.23.1",
+    "@botonic/shared": "2.23.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}