@clivly/chat-widget 0.15.0 → 0.16.0

package/dist/browser.cjs

@@ -170,16 +170,95 @@ const WIDGET_STYLES = `
     font-size: max(16px, 1em);
   }
 }
+/* Floating placements. The insets keep the launcher off a phone's home
+   indicator and rounded corners; --clivly-chat-z-index lets a host slot it
+   beneath its own dialogs. */
+.clivly-chat-widget[data-clivly-placement="bottom-right"],
+.clivly-chat-widget[data-clivly-placement="bottom-left"] {
+  bottom: max(1.25rem, env(safe-area-inset-bottom));
+  position: fixed;
+  z-index: var(--clivly-chat-z-index, 2147483000);
+}
+.clivly-chat-widget[data-clivly-placement="bottom-right"] {
+  right: max(1.25rem, env(safe-area-inset-right));
+}
+.clivly-chat-widget[data-clivly-placement="bottom-left"] {
+  left: max(1.25rem, env(safe-area-inset-left));
+}
 .clivly-chat-widget__launcher {
   align-items: center;
   background: var(--clivly-chat-accent);
   border: 0;
   border-radius: 999px;
+  box-shadow:
+    0 2px 6px rgba(0, 0, 0, 0.18),
+    0 10px 28px -10px var(--clivly-chat-accent);
   color: var(--clivly-chat-accent-contrast);
   cursor: pointer;
   display: inline-flex;
+  font-weight: 500;
   gap: 0.5rem;
-  padding: 0.85rem 1.1rem;
+  justify-content: center;
+  min-height: 3rem;
+  padding: 0 1.15rem;
+  transition: transform 150ms ease-out, filter 150ms ease-out;
+}
+.clivly-chat-widget__launcher:hover {
+  filter: brightness(1.06);
+  transform: translateY(-1px);
+}
+.clivly-chat-widget__launcher:active {
+  transform: scale(0.96);
+}
+.clivly-chat-widget__launcher:focus-visible {
+  outline: 2px solid var(--clivly-chat-accent);
+  outline-offset: 3px;
+}
+.clivly-chat-widget__launcher-icon {
+  flex-shrink: 0;
+  height: 1.25rem;
+  width: 1.25rem;
+}
+/* Icon-only: a 48px circle — a comfortable touch target that does not cover
+   the host's pagination, toolbars or form controls the way a labelled pill
+   does on a phone. The label is clipped, not removed, so it stays the
+   button's accessible name. */
+.clivly-chat-widget[data-clivly-launcher="icon"] .clivly-chat-widget__launcher {
+  height: 3rem;
+  padding: 0;
+  width: 3rem;
+}
+.clivly-chat-widget[data-clivly-launcher="icon"] .clivly-chat-widget__launcher-label {
+  clip-path: inset(50%);
+  height: 1px;
+  overflow: hidden;
+  position: absolute;
+  white-space: nowrap;
+  width: 1px;
+}
+@media (width < 48rem) {
+  .clivly-chat-widget[data-clivly-launcher="auto"] .clivly-chat-widget__launcher {
+    height: 3rem;
+    padding: 0;
+    width: 3rem;
+  }
+  .clivly-chat-widget[data-clivly-launcher="auto"] .clivly-chat-widget__launcher-label {
+    clip-path: inset(50%);
+    height: 1px;
+    overflow: hidden;
+    position: absolute;
+    white-space: nowrap;
+    width: 1px;
+  }
+}
+@media (prefers-reduced-motion: reduce) {
+  .clivly-chat-widget__launcher {
+    transition: none;
+  }
+  .clivly-chat-widget__launcher:hover,
+  .clivly-chat-widget__launcher:active {
+    transform: none;
+  }
 }
 .clivly-chat-widget__panel {
   background: var(--clivly-chat-panel);
@@ -195,6 +274,19 @@ const WIDGET_STYLES = `
   bottom: 4.5rem;
   width: min(24rem, calc(100vw - 2rem));
 }
+/* Opens toward the page from whichever corner the launcher is in. */
+.clivly-chat-widget[data-clivly-placement="bottom-left"] .clivly-chat-widget__panel {
+  left: 0;
+  right: auto;
+}
+/* dvh: on a phone vh includes the collapsed URL bar, so a 75vh panel's top
+   edge could slide under it. The 48px launcher sits lower than the pill. */
+@media (width < 48rem) {
+  .clivly-chat-widget__panel {
+    bottom: 4rem;
+    height: min(44rem, calc(100dvh - 6.5rem));
+  }
+}
 .clivly-chat-widget__header {
   border-bottom: 1px solid var(--clivly-chat-border);
   display: flex;
@@ -562,6 +654,45 @@ function automationBadge(message) {
 	if (message.senderType !== "system" || !message.automation) return null;
 	return AUTOMATION_BADGES[message.automation] ?? "Automated";
 }
+/**
+* The button that opens and closes the panel. Its size and shape come from the
+* root's `data-clivly-launcher` (see WIDGET_STYLES); the label is always its
+* accessible name, and `aria-controls` names the panel only while it exists.
+*/
+function Launcher({ label, onToggle, open, panelId }) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("button", {
+		"aria-controls": open ? panelId : void 0,
+		"aria-expanded": open,
+		className: "clivly-chat-widget__launcher",
+		onClick: onToggle,
+		type: "button",
+		children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(LauncherIcon, { open }), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+			className: "clivly-chat-widget__launcher-label",
+			children: label
+		})]
+	});
+}
+/**
+* A chat bubble while closed, a cross while open — so the icon-only launcher
+* still tells a sighted visitor what tapping it will do. Decorative: the
+* label and `aria-expanded` carry the meaning for assistive technology.
+* Inline SVG because the script-tag build renders inside a shadow root with no
+* icon font or stylesheet of the host's to borrow.
+*/
+function LauncherIcon({ open }) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("svg", {
+		"aria-hidden": "true",
+		className: "clivly-chat-widget__launcher-icon",
+		fill: "none",
+		focusable: "false",
+		stroke: "currentColor",
+		strokeLinecap: "round",
+		strokeLinejoin: "round",
+		strokeWidth: 2,
+		viewBox: "0 0 24 24",
+		children: open ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("path", { d: "M18 6 6 18M6 6l12 12" }) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("path", { d: "M7.9 20A9 9 0 1 0 4 16.1L2 22Z" })
+	});
+}
 function MessageBubble({ message }) {
 	const badge = automationBadge(message);
 	const author = badge ? (message.author ?? "").replace(AUTHOR_LABEL_SUFFIX, "") : message.author;
@@ -672,9 +803,10 @@ function isCompleteVisitor(visitor) {
 * the visitor is told to wait for something that will never arrive. The third
 * string keeps the status honest in all three states.
 */
-function composerStatusText(hasTransport, isReady) {
+function composerStatusText(hasTransport, isReady, reconnecting) {
 	if (!hasTransport) return "Chat is unavailable";
-	return isReady ? "Conversation ready" : "Connecting…";
+	if (isReady) return "Conversation ready";
+	return reconnecting ? "Reconnecting…" : "Connecting…";
 }
 /**
 * Guided options under the greeting. Native buttons in a labelled group, so
@@ -740,8 +872,98 @@ function StatusNotice({ assistantThinking, email, showWaitingNotice }) {
 		children: waitingNoticeText(email)
 	});
 }
-function ChatWidget({ className, createTransport, defaultVisitor, getSession, initiallyOpen = false, launcherLabel = "Chat with us", storage = DEFAULT_STORAGE, style, theme = "auto", widgetId }) {
+const RECONNECT_BASE_MS = 1e3;
+const RECONNECT_MAX_MS = 3e4;
+/**
+* How long to wait before reconnect attempt `attempt` (0-based): doubling from
+* one second to a 30-second ceiling, ±25% jitter so a fleet of widgets dropped
+* by the same server restart doesn't reconnect in lockstep.
+*/
+function reconnectDelayMs(attempt, random = Math.random) {
+	const base = Math.min(RECONNECT_MAX_MS, RECONNECT_BASE_MS * 2 ** attempt);
+	return Math.round(base * (.75 + random() * .5));
+}
+/**
+* Keep the socket for `session` open, and reconnect when it drops — a laptop
+* waking, a network change, a server deploy — instead of leaving the visitor at
+* "Connecting…" until they reload. A reconnect refreshes the session (same
+* conversation, fresh token) and the server's snapshot on connect brings back
+* anything that arrived meanwhile. Returns whether a reconnect is pending.
+*/
+function useLiveConnection({ actions, createTransport, refreshSession, session, setIsReady, transportRef }) {
+	const [reconnecting, setReconnecting] = (0, react.useState)(false);
+	const attemptRef = (0, react.useRef)(0);
+	const refreshRef = (0, react.useRef)(refreshSession);
+	const actionsRef = (0, react.useRef)(actions);
+	(0, react.useEffect)(() => {
+		refreshRef.current = refreshSession;
+		actionsRef.current = actions;
+	});
+	(0, react.useEffect)(() => {
+		transportRef.current?.close();
+		transportRef.current = null;
+		setIsReady(false);
+		if (!(session && createTransport)) return;
+		let disposed = false;
+		let timer;
+		const retry = () => {
+			timer = void 0;
+			refreshRef.current(session).catch(() => {
+				scheduleReconnect();
+			});
+		};
+		const scheduleReconnect = () => {
+			if (disposed || timer !== void 0) return;
+			setReconnecting(true);
+			timer = setTimeout(retry, reconnectDelayMs(attemptRef.current));
+			attemptRef.current += 1;
+		};
+		const retryNow = () => {
+			if (timer !== void 0) {
+				clearTimeout(timer);
+				retry();
+			}
+		};
+		window.addEventListener("online", retryNow);
+		const connection = createTransport({
+			handlers: {
+				onClose: () => {
+					setIsReady(false);
+					actionsRef.current.setAssistantThinking(false);
+					scheduleReconnect();
+				},
+				onError: (transportError) => {
+					if (attemptRef.current === 0) actionsRef.current.setError(transportError.message);
+				},
+				onEvent: (event) => {
+					applyServerEvent(event, {
+						...actionsRef.current,
+						setIsReady
+					});
+				},
+				onOpen: () => {
+					if (attemptRef.current > 0) actionsRef.current.setError(null);
+					attemptRef.current = 0;
+					setReconnecting(false);
+					setIsReady(true);
+				}
+			},
+			session
+		});
+		transportRef.current = connection;
+		return () => {
+			disposed = true;
+			if (timer !== void 0) clearTimeout(timer);
+			window.removeEventListener("online", retryNow);
+			connection.close();
+			if (transportRef.current === connection) transportRef.current = null;
+		};
+	}, [createTransport, session]);
+	return reconnecting;
+}
+function ChatWidget({ className, createTransport, defaultVisitor, getSession, initiallyOpen = false, launcher = "auto", launcherLabel = "Chat with us", placement = "bottom-right", storage = DEFAULT_STORAGE, style, theme = "auto", widgetId }) {
 	const [isOpen, setIsOpen] = (0, react.useState)(initiallyOpen);
+	const panelId = (0, react.useId)();
 	const [error, setError] = (0, react.useState)(null);
 	const [isConnecting, setIsConnecting] = (0, react.useState)(false);
 	const [isReady, setIsReady] = (0, react.useState)(false);
@@ -756,6 +978,7 @@ function ChatWidget({ className, createTransport, defaultVisitor, getSession, in
 	});
 	const transportRef = (0, react.useRef)(null);
 	const listRef = (0, react.useRef)(null);
+	const identityRef = (0, react.useRef)(null);
 	(0, react.useEffect)(() => {
 		if (createTransport) return;
 		console.warn("[clivly] <ChatWidget> was given no createTransport, so messages cannot be sent. Pass createTransport={createClivlyTransport()} — see https://www.npmjs.com/package/@clivly/chat-widget#five-minute-quick-start");
@@ -771,41 +994,30 @@ function ChatWidget({ className, createTransport, defaultVisitor, getSession, in
 		if (!listRef.current) return;
 		listRef.current.scrollTop = listRef.current.scrollHeight;
 	}, [messages]);
-	(0, react.useEffect)(() => {
-		transportRef.current?.close();
-		transportRef.current = null;
-		setIsReady(false);
-		if (!(session && createTransport)) return;
-		const connection = createTransport({
-			handlers: {
-				onClose: () => {
-					setIsReady(false);
-					setAssistantThinking(false);
-				},
-				onError: (transportError) => {
-					setError(transportError.message);
-				},
-				onEvent: (event) => {
-					applyServerEvent(event, {
-						setAssistantThinking,
-						setError,
-						setIsReady,
-						setMessages,
-						setSupportState
-					});
-				},
-				onOpen: () => {
-					setIsReady(true);
-				}
-			},
-			session
-		});
-		transportRef.current = connection;
-		return () => {
-			connection.close();
-			if (transportRef.current === connection) transportRef.current = null;
-		};
-	}, [createTransport, session]);
+	const reconnecting = useLiveConnection({
+		actions: {
+			setAssistantThinking,
+			setError,
+			setMessages,
+			setSupportState
+		},
+		createTransport,
+		refreshSession: async (current) => {
+			const identity = identityRef.current;
+			if (!identity) throw new Error("No visitor to reconnect as.");
+			const next = await getSession({
+				visitor: identity,
+				visitorToken: current.visitorToken,
+				widgetId
+			});
+			storage?.setItem(createStorageKey(widgetId), next.visitorToken);
+			setSupportState(next.support?.state ?? null);
+			setSession(next);
+		},
+		session,
+		setIsReady,
+		transportRef
+	});
 	(0, react.useEffect)(() => {
 		if (!(isOpen && isReady)) return;
 		const markReadIfVisible = () => {
@@ -833,6 +1045,7 @@ function ChatWidget({ className, createTransport, defaultVisitor, getSession, in
 				widgetId
 			});
 			storage?.setItem(createStorageKey(widgetId), nextSession.visitorToken);
+			identityRef.current = identity;
 			setSupportState(nextSession.support?.state ?? null);
 			setSession(nextSession);
 			setMessages(sortMessages(nextSession.messages.map((message) => createLocalMessage(message))));
@@ -910,21 +1123,24 @@ function ChatWidget({ className, createTransport, defaultVisitor, getSession, in
 	const topics = visibleTopics(session, supportState);
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 		className: `clivly-chat-widget ${className ?? ""}`.trim(),
+		"data-clivly-launcher": launcher,
+		"data-clivly-placement": placement,
 		"data-clivly-theme": resolvedTheme,
 		style: themeStyle,
 		children: [
 			/* @__PURE__ */ (0, react_jsx_runtime.jsx)("style", { children: WIDGET_STYLES }),
-			/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
-				className: "clivly-chat-widget__launcher",
-				onClick: () => {
+			/* @__PURE__ */ (0, react_jsx_runtime.jsx)(Launcher, {
+				label: launcherLabel,
+				onToggle: () => {
 					setIsOpen((open) => !open);
 				},
-				type: "button",
-				children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: launcherLabel })
+				open: isOpen,
+				panelId
 			}),
 			isOpen ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("section", {
 				"aria-label": panelTitle,
 				className: "clivly-chat-widget__panel",
+				id: panelId,
 				children: [
 					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("header", {
 						className: "clivly-chat-widget__header",
@@ -997,8 +1213,9 @@ function ChatWidget({ className, createTransport, defaultVisitor, getSession, in
 						}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 							className: "clivly-chat-widget__actions",
 							children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+								"aria-live": "polite",
 								className: "clivly-chat-widget__subtitle",
-								children: composerStatusText(Boolean(createTransport), isReady)
+								children: composerStatusText(Boolean(createTransport), isReady, reconnecting)
 							}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
 								className: "clivly-chat-widget__button",
 								disabled: !(messageDraft.trim() && canSend),
@@ -1147,6 +1364,26 @@ function createClivlyTransport(options = {}) {
 	});
 }
 //#endregion
+//#region src/layout.ts
+const PLACEMENTS = [
+	"bottom-left",
+	"bottom-right",
+	"inline"
+];
+const LAUNCHERS = [
+	"auto",
+	"icon",
+	"pill"
+];
+/** A script tag's `data-placement`; anything unrecognised floats bottom-right. */
+function parsePlacement(value) {
+	return PLACEMENTS.find((placement) => placement === value) ?? "bottom-right";
+}
+/** A script tag's `data-launcher`; anything unrecognised is `"auto"`. */
+function parseLauncher(value) {
+	return LAUNCHERS.find((launcher) => launcher === value) ?? "auto";
+}
+//#endregion
 //#region src/session.ts
 function isWidgetSessionPayload(value) {
 	return typeof value === "object" && value !== null;
@@ -1244,6 +1481,8 @@ function mountChatWidgetScript$1(script = document.currentScript) {
 	const { root, setTheme } = createWidgetMount({
 		container,
 		defaultVisitor: readScriptVisitor(script.dataset),
+		launcher: parseLauncher(script.dataset.launcher),
+		placement: parsePlacement(script.dataset.placement),
 		sessionUrl,
 		socketUrlTemplate: script.dataset.socketUrlTemplate,
 		theme: parseTheme(script.dataset.theme),

package/dist/browser.d.cts

@@ -1,5 +1,26 @@
 import { Root } from "react-dom/client";
 import { CSSProperties } from "react";
+//#region src/layout.d.ts
+/**
+ * Where the widget sits on the host page, and what its launcher looks like.
+ *
+ * Until 0.16 the widget rendered in normal flow wherever it was mounted — the
+ * script tag inserted it directly after itself, so most embeds showed a
+ * full-width-label pill at the end of the page rather than a floating button.
+ * Floating in a corner is now the default; `"inline"` keeps the old behaviour
+ * for a host that positions the widget itself.
+ */
+type ChatWidgetPlacement = "bottom-left" | "bottom-right" | "inline";
+/**
+ * - `"auto"` (default): the labelled pill on wide screens, a 48px icon-only
+ *   button below 48rem, where a pill covers the host's own controls.
+ * - `"pill"`: always the labelled pill.
+ * - `"icon"`: always the icon-only button.
+ *
+ * The label stays the button's accessible name in every variant.
+ */
+type ChatWidgetLauncher = "auto" | "icon" | "pill";
+//#endregion
 //#region src/theme.d.ts
 /**
  * Theme resolution for the widget.
@@ -177,7 +198,17 @@ interface ChatWidgetProps {
   defaultVisitor?: Partial<ChatWidgetVisitor>;
   getSession: GetSession;
   initiallyOpen?: boolean;
+  /** Launcher shape; see {@link ChatWidgetLauncher}. Defaults to `"auto"`. */
+  launcher?: ChatWidgetLauncher;
+  /** The launcher's visible text, and always its accessible name. */
   launcherLabel?: string;
+  /**
+   * Where the widget sits; see {@link ChatWidgetPlacement}. Defaults to
+   * `"bottom-right"`, floating clear of the device's safe-area insets. Stacks
+   * at `--clivly-chat-z-index` (default 2147483000) — lower it through
+   * `style` to sit beneath the host's own dialogs.
+   */
+  placement?: ChatWidgetPlacement;
   storage?: Pick<Storage, "getItem" | "setItem">;
   /**
    * Inline styles on the widget root. The intended use is overriding palette

package/dist/browser.d.mts

@@ -1,5 +1,26 @@
 import { Root } from "react-dom/client";
 import { CSSProperties } from "react";
+//#region src/layout.d.ts
+/**
+ * Where the widget sits on the host page, and what its launcher looks like.
+ *
+ * Until 0.16 the widget rendered in normal flow wherever it was mounted — the
+ * script tag inserted it directly after itself, so most embeds showed a
+ * full-width-label pill at the end of the page rather than a floating button.
+ * Floating in a corner is now the default; `"inline"` keeps the old behaviour
+ * for a host that positions the widget itself.
+ */
+type ChatWidgetPlacement = "bottom-left" | "bottom-right" | "inline";
+/**
+ * - `"auto"` (default): the labelled pill on wide screens, a 48px icon-only
+ *   button below 48rem, where a pill covers the host's own controls.
+ * - `"pill"`: always the labelled pill.
+ * - `"icon"`: always the icon-only button.
+ *
+ * The label stays the button's accessible name in every variant.
+ */
+type ChatWidgetLauncher = "auto" | "icon" | "pill";
+//#endregion
 //#region src/theme.d.ts
 /**
  * Theme resolution for the widget.
@@ -177,7 +198,17 @@ interface ChatWidgetProps {
   defaultVisitor?: Partial<ChatWidgetVisitor>;
   getSession: GetSession;
   initiallyOpen?: boolean;
+  /** Launcher shape; see {@link ChatWidgetLauncher}. Defaults to `"auto"`. */
+  launcher?: ChatWidgetLauncher;
+  /** The launcher's visible text, and always its accessible name. */
   launcherLabel?: string;
+  /**
+   * Where the widget sits; see {@link ChatWidgetPlacement}. Defaults to
+   * `"bottom-right"`, floating clear of the device's safe-area insets. Stacks
+   * at `--clivly-chat-z-index` (default 2147483000) — lower it through
+   * `style` to sit beneath the host's own dialogs.
+   */
+  placement?: ChatWidgetPlacement;
   storage?: Pick<Storage, "getItem" | "setItem">;
   /**
    * Inline styles on the widget root. The intended use is overriding palette