@helpway/react 0.13.3 → 0.14.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as _helpway_widget_core from '@helpway/widget-core';
-import { HelpwayMethods, WidgetTheme, WidgetStore } from '@helpway/widget-core';
+import { HelpwayMethods, WidgetPlacement, DockSuggestion, WidgetTheme, WidgetStore } from '@helpway/widget-core';
 export { ConversationSummary, HelpwayAPI, RealtimeEvent, TimelineItem, WidgetEventName, WidgetEvents, WidgetPosition, WidgetState, WidgetStore, WidgetTheme, clearVisitorId, formatRelativeTime, formatTime, getInitials, getOrCreateVisitorId } from '@helpway/widget-core';
 import * as react from 'react';
 import react__default, { ReactNode } from 'react';
@@ -45,6 +45,28 @@ interface HelpwayWidgetProps {
      * the widget from your own UI.
      */
     hideLauncher?: boolean;
+    /**
+     * Where the widget lives on the page. The conversation UI is identical
+     * across placements — only the shell moves.
+     *
+     * - `bubble` floating launcher bottom-right (default)
+     * - `docked` composer bar pinned to the foot of the page; the bar is
+     *   the composer, so the panel above it renders without one
+     * @default "bubble"
+     */
+    placement?: WidgetPlacement;
+    /**
+     * Force the widget's appearance instead of following the visitor's OS.
+     * Set this to match the page you are embedding in — a light page in a
+     * dark-OS browser otherwise gets a dark widget.
+     * @default "system"
+     */
+    colorScheme?: "light" | "dark" | "system";
+    /**
+     * Ways in offered above the docked bar before the visitor types.
+     * Only used when `placement="docked"`.
+     */
+    dockSuggestions?: readonly DockSuggestion[];
     /**
      * CSS selector for a custom trigger element (e.g. `"#support-btn"`).
      * Clicking the matched element calls `Helpway.open()`. Combine with
@@ -81,7 +103,7 @@ type HelpwayPublicAPI = HelpwayMethods;
  * `layout.tsx`, or `main.tsx`). Unmounting cleanly tears down the
  * widget and its WebSocket connection — useful for route-scoped mounts.
  */
-declare function HelpwayWidget({ apiKey, apiUrl, locale, initialConversationId, deepLinkToken, onReady, hideLauncher, customLauncherSelector, onOpen, onClose, onUnreadChange, theme, src, }: HelpwayWidgetProps): react_jsx_runtime.JSX.Element;
+declare function HelpwayWidget({ apiKey, apiUrl, locale, initialConversationId, deepLinkToken, onReady, hideLauncher, placement, colorScheme, dockSuggestions, customLauncherSelector, onOpen, onClose, onUnreadChange, theme, src, }: HelpwayWidgetProps): react_jsx_runtime.JSX.Element;
 
 interface IdentifyData {
     externalId: string;
@@ -194,13 +216,13 @@ interface PendingAttachment {
         mimeType: string;
     } | null;
 }
-/**
- * Composer state — text input + attachments + submit for a conversation.
- */
-declare function useComposer(conversationId: string | null): {
+declare function useComposer(boundConversationId: string | null): {
     text: string;
     setText: react.Dispatch<react.SetStateAction<string>>;
-    submit: () => Promise<void>;
+    submit: (override?: {
+        text?: string;
+        conversationId?: string;
+    }) => Promise<void>;
     isSubmitting: boolean;
     attachments: PendingAttachment[];
     addFiles: (files: File[]) => Promise<void>;
@@ -276,23 +298,45 @@ declare function WidgetLogo({ className, forceAgent, }: {
  * Unified support widget — Intercom-style with tab navigation.
  * Two tabs: Home + Messages. Sub-views: conversation + new conversation.
  */
-declare function DefaultWidget({ hideLauncher }?: {
+declare function DefaultWidget({ hideLauncher, placement, colorScheme, dockSuggestions, }?: {
     hideLauncher?: boolean;
+    placement?: WidgetPlacement;
+    /**
+     * Pin the appearance instead of following the visitor's OS. An embedded
+     * widget lives in someone else's page; matching that page beats matching
+     * the machine it is being read on.
+     */
+    colorScheme?: "light" | "dark" | "system";
+    /**
+     * Ways in offered above the docked bar before the visitor types.
+     * A prop for now — this belongs on AgentConfig once the API returns
+     * per-workspace (and eventually per-page) suggestions.
+     */
+    dockSuggestions?: readonly DockSuggestion[];
 }): react_jsx_runtime.JSX.Element;
 
 interface MessageBubbleProps {
     text: string;
     sender: "visitor" | "team" | "ai";
     senderName?: string;
+    /** Name the conversation header is showing; a sender matching it stays unlabelled. */
+    headerName?: string;
     parts?: TimelineItemPart[] | null;
     timestamp?: string;
+    /**
+     * Whether this message closes a run from the same sender — the point where
+     * the author's name belongs. Kept separate from `timestamp` so a clock label
+     * that would only repeat the one above it can be dropped without taking the
+     * signature with it.
+     */
+    showAuthor?: boolean;
     /** Variant payload for interactive messages (quick replies, …). */
     metadata?: TimelineItemMetadata | null;
     /** Called when the visitor taps a quick-reply option. */
     onQuickReplyTap?: (optionId: string, stepId: string) => void;
 }
 /** Single message bubble — Intercom-style, renders text + image/file parts */
-declare function MessageBubble({ text, sender, senderName, parts, timestamp, metadata, onQuickReplyTap, }: MessageBubbleProps): react_jsx_runtime.JSX.Element;
+declare function MessageBubble({ text, sender, senderName, headerName, parts, timestamp, showAuthor, metadata, onQuickReplyTap, }: MessageBubbleProps): react_jsx_runtime.JSX.Element;
 
 interface MessageListProps {
     items: TimelineItem[];