@helpway/react 0.4.2 → 0.5.0

package/README.md

@@ -2,6 +2,13 @@
 
 Official React SDK for [Helpway](https://helpway.ai) — AI-powered customer support widget with full programmatic control.
 
+> **📚 Full documentation:** https://helpway.ai/docs
+> · [Quick start](https://helpway.ai/docs/quick-start)
+> · [React SDK](https://helpway.ai/docs/react-sdk)
+> · [Customization & theming](https://helpway.ai/docs/customization)
+> · [Widget API](https://helpway.ai/docs/widget-api)
+> · [Integration notes (CSP, SSR, multi-tenant)](https://helpway.ai/docs/integration-notes)
+
 ## Install
 
 ```bash

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as _helpway_widget_core from '@helpway/widget-core';
-import { HelpwayMethods, WidgetStore } from '@helpway/widget-core';
-export { ConversationSummary, HelpwayAPI, RealtimeEvent, TimelineItem, WidgetEventName, WidgetEvents, WidgetState, WidgetStore, clearVisitorId, formatRelativeTime, formatTime, getInitials, getOrCreateVisitorId } from '@helpway/widget-core';
+import { HelpwayMethods, 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';
 import * as _helpway_types from '@helpway/types';
@@ -52,6 +52,16 @@ interface HelpwayWidgetProps {
     onClose?: () => void;
     /** Fires when the unread count changes */
     onUnreadChange?: (count: number) => void;
+    /**
+     * Developer-side theme override. Most consumers should configure
+     * appearance from the dashboard so changes apply without a redeploy
+     * — see https://helpway.ai/docs/customization. Use this prop only
+     * for runtime-resolved theming (multi-tenant brand colors, dark/
+     * light sync with the host app, etc). Values map to CSS custom
+     * properties on the widget host. See the `WidgetTheme` type for
+     * the full set of supported keys.
+     */
+    theme?: WidgetTheme;
     /**
      * @deprecated Legacy prop from the v0.1 script-loader era. If set,
      * the `/widget.js` suffix is stripped to derive `apiUrl`. New code
@@ -66,7 +76,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, onReady, hideLauncher, customLauncherSelector, onOpen, onClose, onUnreadChange, src, }: HelpwayWidgetProps): react_jsx_runtime.JSX.Element;
+declare function HelpwayWidget({ apiKey, apiUrl, locale, initialConversationId, onReady, hideLauncher, customLauncherSelector, onOpen, onClose, onUnreadChange, theme, src, }: HelpwayWidgetProps): react_jsx_runtime.JSX.Element;
 
 interface IdentifyData {
     externalId: string;
@@ -89,6 +99,17 @@ interface SupportProviderProps {
     onOpen?: () => void;
     onClose?: () => void;
     onUnreadChange?: (count: number) => void;
+    /**
+     * Developer-side theme override. Most consumers should configure
+     * appearance in the Helpway dashboard (see
+     * https://helpway.ai/docs/customization) so changes apply without
+     * a redeploy. Use this prop only when you need the widget to inherit
+     * a host-app theme that the dashboard can't see (e.g. a tenant-
+     * specific brand color resolved at runtime). Values here are written
+     * as CSS custom properties on the widget host and override the
+     * dashboard config for this mount only.
+     */
+    theme?: WidgetTheme;
     children: ReactNode;
 }
 /**
@@ -98,7 +119,7 @@ interface SupportProviderProps {
  * Visitor identity is managed via server-side cookies (hw_visitor).
  * No localStorage or client-side ID management needed.
  */
-declare function SupportProvider({ apiKey, apiUrl, locale, initialConversationId, onReady, customLauncherSelector, onOpen, onClose, onUnreadChange, children, }: SupportProviderProps): react_jsx_runtime.JSX.Element;
+declare function SupportProvider({ apiKey, apiUrl, locale, initialConversationId, onReady, customLauncherSelector, onOpen, onClose, onUnreadChange, theme, children, }: SupportProviderProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Core widget state — connection status, visitor identity, website info.

package/dist/index.js

@@ -585,6 +585,55 @@ function createHelpwayAPI(deps) {
   };
 }
 
+// ../widget-core/src/theme.ts
+function isValidHex(color) {
+  return /^#[0-9a-fA-F]{6}$/.test(color);
+}
+function lighten(hex) {
+  if (!isValidHex(hex)) return hex;
+  const r = Math.min(255, Number.parseInt(hex.slice(1, 3), 16) + 30);
+  const g = Math.min(255, Number.parseInt(hex.slice(3, 5), 16) + 30);
+  const b = Math.min(255, Number.parseInt(hex.slice(5, 7), 16) + 30);
+  const hex2 = (n) => n.toString(16).padStart(2, "0");
+  return `#${hex2(r)}${hex2(g)}${hex2(b)}`;
+}
+function setVar(host, name, value) {
+  if (value == null || value === "") return;
+  host.style.setProperty(name, value);
+}
+function applyTheme(host, theme) {
+  if (!host || !theme) return;
+  if (theme.primaryColor) {
+    setVar(host, "--hw-primary", theme.primaryColor);
+    setVar(host, "--hw-primary-hover", lighten(theme.primaryColor));
+    setVar(host, "--hw-brand", theme.primaryColor);
+  }
+  setVar(host, "--hw-on-brand", theme.onPrimaryColor);
+  setVar(host, "--hw-visitor-bubble-bg", theme.bubbleColor ?? theme.primaryColor);
+  setVar(host, "--hw-visitor-bubble-text", theme.bubbleTextColor ?? theme.onPrimaryColor);
+  setVar(host, "--hw-bg", theme.backgroundColor);
+  setVar(host, "--hw-text", theme.textColor);
+  setVar(host, "--hw-border", theme.borderColor);
+  setVar(host, "--hw-radius", theme.radius);
+  setVar(host, "--hw-font", theme.fontFamily);
+  if (theme.position === "bottom-left") {
+    setVar(host, "--hw-position-right", "auto");
+    setVar(host, "--hw-position-left", "20px");
+    setVar(host, "--hw-window-right", "auto");
+    setVar(host, "--hw-window-left", "0");
+  } else if (theme.position === "bottom-right") {
+    host.style.removeProperty("--hw-position-right");
+    host.style.removeProperty("--hw-position-left");
+    host.style.removeProperty("--hw-window-right");
+    host.style.removeProperty("--hw-window-left");
+  }
+  if (theme.cssVariables) {
+    for (const [key, value] of Object.entries(theme.cssVariables)) {
+      if (key.startsWith("--")) host.style.setProperty(key, value);
+    }
+  }
+}
+
 // ../widget-core/src/events.ts
 var WidgetEventEmitter = class {
   listeners = /* @__PURE__ */ new Map();
@@ -884,6 +933,7 @@ function SupportProvider({
   onOpen,
   onClose,
   onUnreadChange,
+  theme,
   children
 }) {
   const initRef = useRef(null);
@@ -1080,6 +1130,11 @@ function SupportProvider({
       observer?.disconnect();
     };
   }, [customLauncherSelector, api]);
+  useEffect(() => {
+    if (!theme || typeof document === "undefined") return;
+    const target = document.getElementById("helpway-widget") ?? document.documentElement;
+    applyTheme(target, theme);
+  }, [theme]);
   useEffect(() => {
     if (typeof window === "undefined") return;
     const callable = installCallable(api);
@@ -4589,6 +4644,7 @@ function HelpwayWidget({
   onOpen,
   onClose,
   onUnreadChange,
+  theme,
   // eslint-disable-next-line @typescript-eslint/no-deprecated
   src
 }) {
@@ -4605,6 +4661,7 @@ function HelpwayWidget({
       onOpen,
       onClose,
       onUnreadChange,
+      theme,
       children: /* @__PURE__ */ jsx14(DefaultWidget, { hideLauncher })
     }
   );