@clivly/chat-widget 0.4.0 → 0.7.0

package/dist/index.d.cts

@@ -1,6 +1,31 @@
 import { Root } from "react-dom/client";
-import { ReactElement } from "react";
-
+import { CSSProperties, ReactElement } from "react";
+//#region src/theme.d.ts
+/**
+ * Theme resolution for the widget.
+ *
+ * The script-tag build mounts into a Shadow DOM, so the host's `.dark` class on
+ * `<html>` can never reach the widget through a CSS selector. The theme has to
+ * be resolved in JavaScript — reading the same signals the host's own CSS reads
+ * — and applied to an attribute inside the widget. That is what this module
+ * does, and why it is a plain DOM module rather than a stylesheet.
+ */
+type ChatWidgetTheme = "auto" | "dark" | "light";
+type ResolvedTheme = "dark" | "light";
+interface ResolveThemeOptions {
+  /** Injection seam for tests. Defaults to the ambient document/window. */
+  root?: Element | null;
+  view?: Window | null;
+}
+/**
+ * Resolve a requested theme to the one the widget should actually paint.
+ *
+ * Falls back to `light` when there is nothing to read — during SSR there is no
+ * document, and guessing dark would flash the wrong palette on hydration for
+ * the majority of pages.
+ */
+declare function resolveTheme(theme: ChatWidgetTheme, { root, view }?: ResolveThemeOptions): ResolvedTheme;
+//#endregion
 //#region src/types.d.ts
 type WidgetSenderType = "visitor" | "operator" | "system";
 interface WidgetConfig {
@@ -29,7 +54,7 @@ interface WidgetMessage {
   senderType: WidgetSenderType;
 }
 interface WidgetSessionPayload {
-  contact: WidgetContact;
+  contact: WidgetContact | null;
   conversation: WidgetConversation;
   expiresAt: string;
   messages: WidgetMessage[];
@@ -100,21 +125,13 @@ interface CreateWebSocketTransportOptions {
   getProtocols?: (session: WidgetSessionPayload) => string | string[] | undefined;
   resolveUrl: (session: WidgetSessionPayload) => string;
 }
-declare function createWebSocketTransport({
-  createSocket,
-  getProtocols,
-  resolveUrl
-}: CreateWebSocketTransportOptions): CreateChatTransport;
+declare function createWebSocketTransport({ createSocket, getProtocols, resolveUrl }: CreateWebSocketTransportOptions): CreateChatTransport;
 interface CreateLoopbackTransportOptions {
   operatorName?: string;
   operatorReply?: (body: string) => string | null;
   replyDelayMs?: number;
 }
-declare function createLoopbackTransport({
-  operatorName,
-  operatorReply,
-  replyDelayMs
-}?: CreateLoopbackTransportOptions): CreateChatTransport;
+declare function createLoopbackTransport({ operatorName, operatorReply, replyDelayMs }?: CreateLoopbackTransportOptions): CreateChatTransport;
 //#endregion
 //#region src/chat-widget.d.ts
 interface ChatWidgetProps {
@@ -124,17 +141,21 @@ interface ChatWidgetProps {
   initiallyOpen?: boolean;
   launcherLabel?: string;
   storage?: Pick<Storage, "getItem" | "setItem">;
+  /**
+   * Inline styles on the widget root. The intended use is overriding palette
+   * tokens — `{ "--clivly-chat-panel": "#0b0f19" }` — which works because
+   * inline declarations beat both palette rules without any specificity games.
+   */
+  style?: CSSProperties;
+  /**
+   * `"auto"` (the default) follows the host app: a `data-theme` attribute or a
+   * `dark`/`light` class on `<html>`, then the OS preference. `"light"` and
+   * `"dark"` pin the widget regardless of what the host is doing.
+   */
+  theme?: ChatWidgetTheme;
   widgetId: string;
 }
-declare function ChatWidget({
-  className,
-  createTransport,
-  getSession,
-  initiallyOpen,
-  launcherLabel,
-  storage,
-  widgetId
-}: ChatWidgetProps): ReactElement;
+declare function ChatWidget({ className, createTransport, getSession, initiallyOpen, launcherLabel, storage, style, theme, widgetId }: ChatWidgetProps): ReactElement;
 declare function ChatLauncher(): null;
 declare function ChatPanel(): null;
 declare function MessageComposer(): null;
@@ -148,16 +169,20 @@ interface MountChatWidgetOptions$1 extends Omit<ChatWidgetProps, "getSession" |
   socketUrlTemplate?: string;
   widgetId: string;
 }
-declare function mountChatWidget$1({
-  container,
-  createTransport,
-  sessionUrl,
-  socketUrlTemplate,
-  widgetId,
-  ...props
-}: MountChatWidgetOptions$1): Root;
-interface ScriptMountResult$1 {
+interface ChatWidgetMount$1 {
   root: Root;
+  /**
+   * Repaint the widget in a different theme. `"auto"` resumes following the
+   * host, so a caller can hand control back as easily as taking it.
+   *
+   * Only needed by hosts whose theme toggle does not touch `<html>` — the
+   * default `"auto"` already tracks a `data-theme` attribute or a `dark`
+   * class there.
+   */
+  setTheme: (theme: ChatWidgetTheme) => void;
+}
+declare function mountChatWidget$1(options: MountChatWidgetOptions$1): Root;
+interface ScriptMountResult$1 extends ChatWidgetMount$1 {
   shadowRoot: ShadowRoot;
 }
 declare function mountChatWidgetScript$1(script?: HTMLScriptElement): ScriptMountResult$1;
@@ -181,12 +206,10 @@ interface CreateSessionFetcherOptions {
   fetchImpl?: typeof fetch;
   sessionUrl: string;
 }
-declare function createSessionFetcher({
-  fetchImpl,
-  sessionUrl
-}: CreateSessionFetcherOptions): GetSession;
+declare function createSessionFetcher({ fetchImpl, sessionUrl }: CreateSessionFetcherOptions): GetSession;
 //#endregion
 //#region src/index.d.ts
+type ChatWidgetMount = ChatWidgetMount$1;
 type MountChatWidgetOptions = MountChatWidgetOptions$1;
 type ScriptMountResult = ScriptMountResult$1;
 declare const autoMountChatWidgetScript: typeof autoMountChatWidgetScript$1;
@@ -195,4 +218,4 @@ declare const createClivlyTransport: typeof createClivlyTransport$1;
 declare const mountChatWidget: typeof mountChatWidget$1;
 declare const mountChatWidgetScript: typeof mountChatWidgetScript$1;
 //#endregion
-export { ChatLauncher, ChatPanel, type ChatTransportConnection, type ChatTransportHandlers, ChatWidget, type ChatWidgetVisitor, ConversationView, type CreateChatTransport, type CreateChatTransportOptions, CreateClivlyTransportOptions, type CreateLoopbackTransportOptions, type CreateWebSocketTransportOptions, type GetSession, type GetSessionOptions, MessageComposer, MountChatWidgetOptions, PreChatForm, ScriptMountResult, type WidgetClientCreateMessageEvent, type WidgetClientEvent, type WidgetConfig, type WidgetContact, type WidgetConversation, type WidgetConversationSnapshotEvent, type WidgetErrorEvent, type WidgetMessage, type WidgetMessageAckEvent, type WidgetMessageCreatedEvent, type WidgetSenderType, type WidgetServerEvent, type WidgetSessionPayload, type WidgetSessionReadyEvent, type WidgetSummary, autoMountChatWidgetScript, createClivlyTransport, createLoopbackTransport, createSessionFetcher, createWebSocketTransport, mountChatWidget, mountChatWidgetScript };
+export { ChatLauncher, ChatPanel, type ChatTransportConnection, type ChatTransportHandlers, ChatWidget, ChatWidgetMount, type ChatWidgetProps, type ChatWidgetTheme, type ChatWidgetVisitor, ConversationView, type CreateChatTransport, type CreateChatTransportOptions, CreateClivlyTransportOptions, type CreateLoopbackTransportOptions, type CreateWebSocketTransportOptions, type GetSession, type GetSessionOptions, MessageComposer, MountChatWidgetOptions, PreChatForm, type ResolvedTheme, ScriptMountResult, type WidgetClientCreateMessageEvent, type WidgetClientEvent, type WidgetConfig, type WidgetContact, type WidgetConversation, type WidgetConversationSnapshotEvent, type WidgetErrorEvent, type WidgetMessage, type WidgetMessageAckEvent, type WidgetMessageCreatedEvent, type WidgetSenderType, type WidgetServerEvent, type WidgetSessionPayload, type WidgetSessionReadyEvent, type WidgetSummary, autoMountChatWidgetScript, createClivlyTransport, createLoopbackTransport, createSessionFetcher, createWebSocketTransport, mountChatWidget, mountChatWidgetScript, resolveTheme };

package/dist/index.d.mts

@@ -1,6 +1,31 @@
 import { Root } from "react-dom/client";
-import { ReactElement } from "react";
-
+import { CSSProperties, ReactElement } from "react";
+//#region src/theme.d.ts
+/**
+ * Theme resolution for the widget.
+ *
+ * The script-tag build mounts into a Shadow DOM, so the host's `.dark` class on
+ * `<html>` can never reach the widget through a CSS selector. The theme has to
+ * be resolved in JavaScript — reading the same signals the host's own CSS reads
+ * — and applied to an attribute inside the widget. That is what this module
+ * does, and why it is a plain DOM module rather than a stylesheet.
+ */
+type ChatWidgetTheme = "auto" | "dark" | "light";
+type ResolvedTheme = "dark" | "light";
+interface ResolveThemeOptions {
+  /** Injection seam for tests. Defaults to the ambient document/window. */
+  root?: Element | null;
+  view?: Window | null;
+}
+/**
+ * Resolve a requested theme to the one the widget should actually paint.
+ *
+ * Falls back to `light` when there is nothing to read — during SSR there is no
+ * document, and guessing dark would flash the wrong palette on hydration for
+ * the majority of pages.
+ */
+declare function resolveTheme(theme: ChatWidgetTheme, { root, view }?: ResolveThemeOptions): ResolvedTheme;
+//#endregion
 //#region src/types.d.ts
 type WidgetSenderType = "visitor" | "operator" | "system";
 interface WidgetConfig {
@@ -29,7 +54,7 @@ interface WidgetMessage {
   senderType: WidgetSenderType;
 }
 interface WidgetSessionPayload {
-  contact: WidgetContact;
+  contact: WidgetContact | null;
   conversation: WidgetConversation;
   expiresAt: string;
   messages: WidgetMessage[];
@@ -100,21 +125,13 @@ interface CreateWebSocketTransportOptions {
   getProtocols?: (session: WidgetSessionPayload) => string | string[] | undefined;
   resolveUrl: (session: WidgetSessionPayload) => string;
 }
-declare function createWebSocketTransport({
-  createSocket,
-  getProtocols,
-  resolveUrl
-}: CreateWebSocketTransportOptions): CreateChatTransport;
+declare function createWebSocketTransport({ createSocket, getProtocols, resolveUrl }: CreateWebSocketTransportOptions): CreateChatTransport;
 interface CreateLoopbackTransportOptions {
   operatorName?: string;
   operatorReply?: (body: string) => string | null;
   replyDelayMs?: number;
 }
-declare function createLoopbackTransport({
-  operatorName,
-  operatorReply,
-  replyDelayMs
-}?: CreateLoopbackTransportOptions): CreateChatTransport;
+declare function createLoopbackTransport({ operatorName, operatorReply, replyDelayMs }?: CreateLoopbackTransportOptions): CreateChatTransport;
 //#endregion
 //#region src/chat-widget.d.ts
 interface ChatWidgetProps {
@@ -124,17 +141,21 @@ interface ChatWidgetProps {
   initiallyOpen?: boolean;
   launcherLabel?: string;
   storage?: Pick<Storage, "getItem" | "setItem">;
+  /**
+   * Inline styles on the widget root. The intended use is overriding palette
+   * tokens — `{ "--clivly-chat-panel": "#0b0f19" }` — which works because
+   * inline declarations beat both palette rules without any specificity games.
+   */
+  style?: CSSProperties;
+  /**
+   * `"auto"` (the default) follows the host app: a `data-theme` attribute or a
+   * `dark`/`light` class on `<html>`, then the OS preference. `"light"` and
+   * `"dark"` pin the widget regardless of what the host is doing.
+   */
+  theme?: ChatWidgetTheme;
   widgetId: string;
 }
-declare function ChatWidget({
-  className,
-  createTransport,
-  getSession,
-  initiallyOpen,
-  launcherLabel,
-  storage,
-  widgetId
-}: ChatWidgetProps): ReactElement;
+declare function ChatWidget({ className, createTransport, getSession, initiallyOpen, launcherLabel, storage, style, theme, widgetId }: ChatWidgetProps): ReactElement;
 declare function ChatLauncher(): null;
 declare function ChatPanel(): null;
 declare function MessageComposer(): null;
@@ -148,16 +169,20 @@ interface MountChatWidgetOptions$1 extends Omit<ChatWidgetProps, "getSession" |
   socketUrlTemplate?: string;
   widgetId: string;
 }
-declare function mountChatWidget$1({
-  container,
-  createTransport,
-  sessionUrl,
-  socketUrlTemplate,
-  widgetId,
-  ...props
-}: MountChatWidgetOptions$1): Root;
-interface ScriptMountResult$1 {
+interface ChatWidgetMount$1 {
   root: Root;
+  /**
+   * Repaint the widget in a different theme. `"auto"` resumes following the
+   * host, so a caller can hand control back as easily as taking it.
+   *
+   * Only needed by hosts whose theme toggle does not touch `<html>` — the
+   * default `"auto"` already tracks a `data-theme` attribute or a `dark`
+   * class there.
+   */
+  setTheme: (theme: ChatWidgetTheme) => void;
+}
+declare function mountChatWidget$1(options: MountChatWidgetOptions$1): Root;
+interface ScriptMountResult$1 extends ChatWidgetMount$1 {
   shadowRoot: ShadowRoot;
 }
 declare function mountChatWidgetScript$1(script?: HTMLScriptElement): ScriptMountResult$1;
@@ -181,12 +206,10 @@ interface CreateSessionFetcherOptions {
   fetchImpl?: typeof fetch;
   sessionUrl: string;
 }
-declare function createSessionFetcher({
-  fetchImpl,
-  sessionUrl
-}: CreateSessionFetcherOptions): GetSession;
+declare function createSessionFetcher({ fetchImpl, sessionUrl }: CreateSessionFetcherOptions): GetSession;
 //#endregion
 //#region src/index.d.ts
+type ChatWidgetMount = ChatWidgetMount$1;
 type MountChatWidgetOptions = MountChatWidgetOptions$1;
 type ScriptMountResult = ScriptMountResult$1;
 declare const autoMountChatWidgetScript: typeof autoMountChatWidgetScript$1;
@@ -195,4 +218,4 @@ declare const createClivlyTransport: typeof createClivlyTransport$1;
 declare const mountChatWidget: typeof mountChatWidget$1;
 declare const mountChatWidgetScript: typeof mountChatWidgetScript$1;
 //#endregion
-export { ChatLauncher, ChatPanel, type ChatTransportConnection, type ChatTransportHandlers, ChatWidget, type ChatWidgetVisitor, ConversationView, type CreateChatTransport, type CreateChatTransportOptions, CreateClivlyTransportOptions, type CreateLoopbackTransportOptions, type CreateWebSocketTransportOptions, type GetSession, type GetSessionOptions, MessageComposer, MountChatWidgetOptions, PreChatForm, ScriptMountResult, type WidgetClientCreateMessageEvent, type WidgetClientEvent, type WidgetConfig, type WidgetContact, type WidgetConversation, type WidgetConversationSnapshotEvent, type WidgetErrorEvent, type WidgetMessage, type WidgetMessageAckEvent, type WidgetMessageCreatedEvent, type WidgetSenderType, type WidgetServerEvent, type WidgetSessionPayload, type WidgetSessionReadyEvent, type WidgetSummary, autoMountChatWidgetScript, createClivlyTransport, createLoopbackTransport, createSessionFetcher, createWebSocketTransport, mountChatWidget, mountChatWidgetScript };
+export { ChatLauncher, ChatPanel, type ChatTransportConnection, type ChatTransportHandlers, ChatWidget, ChatWidgetMount, type ChatWidgetProps, type ChatWidgetTheme, type ChatWidgetVisitor, ConversationView, type CreateChatTransport, type CreateChatTransportOptions, CreateClivlyTransportOptions, type CreateLoopbackTransportOptions, type CreateWebSocketTransportOptions, type GetSession, type GetSessionOptions, MessageComposer, MountChatWidgetOptions, PreChatForm, type ResolvedTheme, ScriptMountResult, type WidgetClientCreateMessageEvent, type WidgetClientEvent, type WidgetConfig, type WidgetContact, type WidgetConversation, type WidgetConversationSnapshotEvent, type WidgetErrorEvent, type WidgetMessage, type WidgetMessageAckEvent, type WidgetMessageCreatedEvent, type WidgetSenderType, type WidgetServerEvent, type WidgetSessionPayload, type WidgetSessionReadyEvent, type WidgetSummary, autoMountChatWidgetScript, createClivlyTransport, createLoopbackTransport, createSessionFetcher, createWebSocketTransport, mountChatWidget, mountChatWidgetScript, resolveTheme };