@helpway/react 0.9.0 → 0.11.0

package/dist/index.d.ts

@@ -246,6 +246,26 @@ declare function useUnread(): {
  */
 declare function useRealtime(handler: (event: RealtimeEvent) => void): void;
 
+/**
+ * WidgetLogo — chat-header avatar. Renders WHO is talking to the
+ * visitor right now. Resolution chain:
+ *   1. Active conversation's assigned support user (assigneeName +
+ *      assigneeImage from the widget API). When a human takes over a
+ *      conversation the visitor sees that human, not the AI agent.
+ *   2. Agent uploaded image (agentConfig.avatarUrl)
+ *   3. Agent icon preset (avatarPreset + brandColor)
+ *   4. Website logo (website.logoUrl)
+ *   5. Helpway brand mark (octagonal) as the true last-resort fallback
+ *
+ * The `forceAgent` escape hatch skips the assignee lookup — used by
+ * surfaces that mean "the agent" specifically (welcome card, conversation
+ * list rows where we want the persistent brand, etc.) rather than "the
+ * person currently helping you".
+ */
+declare function WidgetLogo({ className, forceAgent, }: {
+    className?: string;
+    forceAgent?: boolean;
+}): react_jsx_runtime.JSX.Element;
 /**
  * Unified support widget — Intercom-style with tab navigation.
  * Two tabs: Home + Messages. Sub-views: conversation + new conversation.
@@ -304,6 +324,110 @@ interface ComposerProps {
 /** Widget composer — auto-resize, Enter-to-send, paste/drop attachments */
 declare function Composer({ text, onTextChange, onSubmit, onTyping, isSubmitting, placeholder, compact, attachments, onAddFiles, onRemoveAttachment, disabled, }: ComposerProps): react_jsx_runtime.JSX.Element;
 
+/** Where the preview is anchored — controls only the outer positioning. */
+type MessagePreviewPlacement = "launcher" | "anchored";
+interface MessagePreviewProps {
+    /** Called when the visitor taps the preview (or a quick reply). The
+     *  active conversation is already switched to the one that pinged —
+     *  the consumer just has to reveal the chat surface. */
+    onOpen: () => void;
+    /**
+     * The avatar node shown in the header. Injected by the consumer so
+     * this component stays decoupled from avatar resolution — the default
+     * widget passes `<WidgetLogo />`; a custom surface can pass its own.
+     */
+    avatar: ReactNode;
+    /**
+     * Outer positioning mode. `"launcher"` (default) keeps the original
+     * absolute placement above the floating bubble — DefaultWidget relies
+     * on this, so the default is unchanged. `"anchored"` drops the
+     * absolute/bottom/right rules (via `hw-preview--anchored`) so a
+     * consumer can pin it to their own trigger (e.g. a sidebar item).
+     */
+    placement?: MessagePreviewPlacement;
+    /**
+     * Auto-dismiss delay in ms. Default `8000` (the launcher behaviour).
+     * Pass `null` (or `0`) to keep the preview until the visitor acts on
+     * it — useful for an anchored surface where it isn't competing with
+     * page content for attention. Quick-reply previews never auto-dismiss
+     * regardless, since the visitor needs time to choose.
+     */
+    autoDismissMs?: number | null;
+    /**
+     * Optional caption rendered as a separated footer beneath the message
+     * (e.g. a source label like "via Helpway"). Omitted for the launcher
+     * so its visual stays byte-identical to the original.
+     */
+    footer?: ReactNode;
+}
+/**
+ * `<MessagePreview>` — the proactive incoming-message bubble shown while
+ * the chat surface is closed. Reads `incomingPreview` from the widget
+ * store, auto-dismisses after 8s (unless quick replies are present), and
+ * on tap switches to the pinging conversation before calling `onOpen`.
+ *
+ * Extracted from the default widget so `hideLauncher` integrations can
+ * surface the *exact same* preview next to their own UI instead of the
+ * floating launcher. Visual/markup is byte-identical to the launcher
+ * version — only the outer positioning is parameterised via `placement`.
+ *
+ * Must be rendered inside `<SupportProvider>`.
+ */
+declare function MessagePreview({ onOpen, avatar, placement, autoDismissMs, footer, }: MessagePreviewProps): react_jsx_runtime.JSX.Element | null;
+
+/** Placement of the announcement stack — mirrors `MessagePreviewPlacement`. */
+type AnnouncementPreviewsPlacement = "launcher" | "anchored";
+/** Shape of a single announcement entry as it lives in the widget store. */
+interface AnnouncementPreviewEntry {
+    title: string;
+    body: string | null;
+    slug: string;
+    tabId: string;
+    badge: string | null;
+}
+interface AnnouncementPreviewsProps {
+    /** Called when the visitor taps an announcement card. Receives the
+     *  entry's slug + the parent tab id. The consumer decides what to
+     *  do — at minimum `setOpen(true)`, optionally deep-link into the
+     *  matching content tab + detail. */
+    onOpen: (slug: string, tabId: string) => void;
+    /** The avatar node shown in each card's header. Injected so the
+     *  component is decoupled from avatar resolution; pass
+     *  `<WidgetLogo />` for the SDK default. */
+    avatar: ReactNode;
+    /**
+     * Outer positioning mode. `"launcher"` (default) keeps the stack
+     * pinned above the floating bubble; `"anchored"` drops that and
+     * lets the consumer's positioned wrapper place the stack — and
+     * each card stretches to the wrapper width instead of the launcher
+     * 300px (via the same `.hw-preview--anchored` modifier the
+     * message preview uses).
+     */
+    placement?: AnnouncementPreviewsPlacement;
+    /**
+     * Optional caption rendered as a separated footer beneath each
+     * card (e.g. a "via X" provenance line). Omitted on the launcher
+     * so its visual stays byte-identical to the original.
+     */
+    footer?: ReactNode;
+}
+/**
+ * `<AnnouncementPreviews>` — proactive "new content" cards shown when
+ * the widget panel is closed and the visitor hasn't seen the latest
+ * entries from a "Promote new content" tab yet. Stacks multiple
+ * entries vertically.
+ *
+ * Extracted from the default widget so `hideLauncher` integrations can
+ * surface the *exact same* cards next to their own UI instead of the
+ * floating launcher. Visual/markup is byte-identical to the launcher
+ * version — only the outer positioning is parameterised via
+ * `placement`. Announcements never auto-dismiss (visitors need time to
+ * read); they're cleared by tapping the card or the ✕.
+ *
+ * Must be rendered inside `<SupportProvider>`.
+ */
+declare function AnnouncementPreviews({ onOpen, avatar, placement, footer, }: AnnouncementPreviewsProps): react_jsx_runtime.JSX.Element | null;
+
 /**
  * Lightweight Markdown → HTML renderer.
  * Zero dependencies. Handles common patterns:
@@ -332,4 +456,4 @@ declare function MarkdownContent({ bodyHtml, bodyMarkdown, className, }: {
     className?: string;
 }): react_jsx_runtime.JSX.Element | null;
 
-export { Composer, DefaultWidget, type HelpwayPublicAPI, HelpwayWidget, type HelpwayWidgetProps, type IdentifyData, MarkdownContent, MessageBubble, MessageList, SupportProvider, linkifyText, renderMarkdown, useComposer, useConversations, useIdentify, usePresence, useRealtime, useTimeline, useUnread, useWidget, useWidgetStore };
+export { type AnnouncementPreviewEntry, AnnouncementPreviews, type AnnouncementPreviewsPlacement, type AnnouncementPreviewsProps, Composer, DefaultWidget, type HelpwayPublicAPI, HelpwayWidget, type HelpwayWidgetProps, type IdentifyData, MarkdownContent, MessageBubble, MessageList, MessagePreview, type MessagePreviewPlacement, type MessagePreviewProps, SupportProvider, WidgetLogo, linkifyText, renderMarkdown, useComposer, useConversations, useIdentify, usePresence, useRealtime, useTimeline, useUnread, useWidget, useWidgetStore };