@usereq/widget 0.1.0

package/src/custom-element/agent-widget-element.tsx

@@ -0,0 +1,584 @@
+import React from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { DEFAULT_START_CONVERSATION_LABEL } from "../chat-widget/chat-widget-defaults";
+import {
+  DEFAULT_WIDGET_APPEARANCE,
+  normalizeWidgetPlacement,
+  normalizeWidgetVariant,
+  type WidgetAppearance,
+  type WidgetMessage,
+  type WidgetPlacement,
+  type WidgetSessionConfig,
+  type WidgetSessionState,
+  type WidgetVariant,
+} from "../types";
+import { widgetTriggerRuleKey } from "../shared/widget-config";
+import { WidgetRuntime, type WidgetRuntimeStatus } from "../renderer/index";
+import { buildAssistantMessageRevealSteps } from "../chat-widget";
+import { DEFAULT_STOP_CONVERSATION_PROMPT } from "../shared/stop-confirmation";
+import type { WidgetTriggerRuleType } from "../shared/analytics";
+import {
+  bootstrapWidget,
+  resetWidgetSession,
+  submitWidgetStopConfirmation,
+  startWidgetConversation,
+  submitWidgetMessage,
+} from "../runtime/bootstrap";
+import {
+  createWidgetAnalyticsTracker,
+  type WidgetAnalyticsTracker,
+} from "../runtime/analytics";
+import { getWidgetShadowCss } from "../shared/shadow-css";
+import { WIDGET_SHADOW_THEME_CSS } from "../shared/shadow-theme";
+
+type WidgetAppearanceAttributes = Partial<WidgetAppearance>;
+
+export class AgentWidgetElement extends HTMLElement {
+  static observedAttributes = [
+    "agent-id",
+    "mode",
+    "variant",
+    "placement",
+    "avatar-orb-color-1",
+    "avatar-orb-color-2",
+    "action-text",
+  ];
+
+  private shadowRootRef: ShadowRoot;
+  private hostStyleElement: HTMLStyleElement;
+  private shadowStyleElement: HTMLStyleElement;
+  private mountElement: HTMLDivElement;
+  private root: Root;
+  private agentId = "";
+  private mode: "embed" | "preview" = "embed";
+  private variant: string | null = null;
+  private placement: string | null = null;
+  private appearanceAttributes: WidgetAppearanceAttributes = {};
+  private open = false;
+  private status: WidgetRuntimeStatus = "idle";
+  private sessionConfig: WidgetSessionConfig | null = null;
+  private sessionState: WidgetSessionState | null = null;
+  private messages: WidgetMessage[] = [];
+  private widgetTitle = "Assistant";
+  private welcomeMessage: string | null = null;
+  private errorMessage: string | null = null;
+  private bootstrapPromise: Promise<void> | null = null;
+  private bootstrapVersion = 0;
+  private sendVersion = 0;
+  private confirmationVersion = 0;
+  private bootstrapPhase: "idle" | "booting" | "ready" | "blocked" = "idle";
+  private analyticsTrackerKey = "";
+  private analyticsTracker: WidgetAnalyticsTracker | null = null;
+
+  constructor() {
+    super();
+    this.shadowRootRef = this.attachShadow({ mode: "open" });
+    this.hostStyleElement = document.createElement("style");
+    this.hostStyleElement.textContent = `
+      ${WIDGET_SHADOW_THEME_CSS}
+
+      :host {
+        display: block;
+        box-sizing: border-box;
+        width: 100%;
+      }
+
+      :host([mode="preview"]) {
+        position: relative;
+        min-height: 720px;
+      }
+    `;
+    this.shadowStyleElement = document.createElement("style");
+    this.shadowStyleElement.textContent = getWidgetShadowCss() ?? "";
+    this.mountElement = document.createElement("div");
+    this.mountElement.style.display = "block";
+    this.mountElement.style.width = "100%";
+    this.mountElement.style.height = "100%";
+    this.shadowRootRef.append(
+      this.hostStyleElement,
+      this.shadowStyleElement,
+      this.mountElement,
+    );
+    this.root = createRoot(this.mountElement);
+  }
+
+  connectedCallback() {
+    this.syncAttributes();
+    this.recreateAnalyticsTracker();
+    this.renderWidget();
+    if (this.agentId) {
+      void this.ensureBootstrap();
+    }
+  }
+
+  disconnectedCallback() {
+    this.bootstrapPromise = null;
+    this.analyticsTracker?.dispose();
+    this.analyticsTracker = null;
+    this.analyticsTrackerKey = "";
+    this.root.unmount();
+  }
+
+  attributeChangedCallback(
+    name?: string,
+    oldValue?: string | null,
+    newValue?: string | null,
+  ) {
+    this.syncAttributes();
+    this.recreateAnalyticsTracker();
+    if (name === "agent-id" && oldValue !== newValue) {
+      this.clearAgentState();
+    }
+    this.renderWidget();
+    if (name === "agent-id" && this.agentId) {
+      void this.ensureBootstrap();
+    }
+  }
+
+  private syncAttributes() {
+    this.agentId = this.getAttribute("agent-id")?.trim() ?? "";
+    this.mode = normalizeWidgetMode(this.getAttribute("mode"));
+    this.variant = this.getAttribute("variant");
+    this.placement = this.getAttribute("placement");
+    this.appearanceAttributes = parseAppearanceAttributes(this);
+  }
+
+  private getResolvedPlacement(): WidgetPlacement {
+    return normalizeWidgetPlacement(
+      this.placement ?? this.sessionConfig?.widgetConfig.widgetPlacement ?? "bottom-right",
+    );
+  }
+
+  private getResolvedVariant(): WidgetVariant {
+    return normalizeWidgetVariant(
+      this.variant ?? this.sessionConfig?.widgetConfig.widgetVariant ?? "chatbar",
+    );
+  }
+
+  private getResolvedAppearance(): WidgetAppearance {
+    const base =
+      this.sessionConfig?.widgetConfig.widgetAppearance ?? DEFAULT_WIDGET_APPEARANCE;
+
+    return {
+      avatarOrbColor1:
+        this.appearanceAttributes.avatarOrbColor1?.trim() ||
+        base.avatarOrbColor1,
+      avatarOrbColor2:
+        this.appearanceAttributes.avatarOrbColor2?.trim() ||
+        base.avatarOrbColor2,
+      actionText:
+        this.appearanceAttributes.actionText?.trim() || base.actionText,
+    };
+  }
+
+  private getWidgetTitle(): string {
+    return this.sessionConfig?.widgetConfig.name ?? this.widgetTitle;
+  }
+
+  private getAgentAvatarUrl(): string | null {
+    return this.sessionConfig?.widgetConfig.agentAvatarUrl ?? null;
+  }
+
+  private getWelcomeMessage(): string | null {
+    return this.sessionConfig?.widgetConfig.welcomeMessage ?? this.welcomeMessage;
+  }
+
+  private getSpotlights(): string[] {
+    return this.sessionConfig?.widgetConfig.spotlightMessages ?? [];
+  }
+
+  private clearAgentState() {
+    this.sendVersion += 1;
+    this.confirmationVersion += 1;
+    this.bootstrapVersion += 1;
+    this.bootstrapPhase = "idle";
+    this.bootstrapPromise = null;
+    this.sessionConfig = null;
+    this.sessionState = null;
+    this.messages = [];
+    this.widgetTitle = "Assistant";
+    this.welcomeMessage = null;
+    this.errorMessage = null;
+    this.status = "idle";
+  }
+
+  private recreateAnalyticsTracker() {
+    const nextKey = `${this.mode}:${this.agentId}`;
+    if (nextKey === this.analyticsTrackerKey) {
+      return;
+    }
+
+    this.analyticsTracker?.dispose();
+    this.analyticsTracker = createWidgetAnalyticsTracker({
+      mode: this.mode,
+      agentId: this.agentId,
+      getSession: () => this.sessionState,
+      getConversationId: () => this.sessionState?.conversationId,
+    });
+    this.analyticsTrackerKey = nextKey;
+  }
+
+  private renderWidget() {
+    if (
+      this.bootstrapPhase !== "ready" ||
+      this.sessionConfig == null ||
+      this.sessionState == null
+    ) {
+      this.root.render(null);
+      return;
+    }
+
+    const appearance = this.getResolvedAppearance();
+    const placement = this.getResolvedPlacement();
+    const variant = this.getResolvedVariant();
+    const emptyAction =
+      this.status === "booting" ||
+      (this.sessionState != null && !this.sessionState.conversationId)
+        ? {
+            label: DEFAULT_START_CONVERSATION_LABEL,
+            onClick: () => void this.handleStartConversation(),
+            disabled: this.status !== "ready",
+          }
+        : undefined;
+
+    this.root.render(
+      React.createElement(WidgetRuntime, {
+        key: `${this.agentId}:${widgetTriggerRuleKey(
+          this.sessionConfig?.widgetConfig.triggerRule,
+        )}`,
+        mode: this.mode,
+        agentId: this.agentId,
+        variant,
+        placement,
+        appearance,
+        agentAvatarUrl: this.getAgentAvatarUrl(),
+        widgetTitle: this.getWidgetTitle(),
+        welcomeMessage: this.getWelcomeMessage(),
+        spotlights: this.getSpotlights(),
+        open: this.open,
+        status: this.status,
+        messages: this.messages,
+        errorMessage: this.errorMessage,
+        triggerRule: this.sessionConfig?.widgetConfig.triggerRule ?? null,
+        emptyAction,
+        onStopConversation:
+          this.sessionState?.conversationId != null
+            ? () => void this.handleStopConversation()
+            : undefined,
+        sendDisabled:
+          this.status === "sending" || !this.sessionState?.conversationId,
+        onOpenChange: (nextOpen: boolean) => void this.handleOpenChange(nextOpen),
+        onSendMessage: (content: string) => void this.sendMessage(content),
+        onConfirmationDecision: (confirmationId: string, accepted: boolean) =>
+          void this.handleConfirmationDecision(confirmationId, accepted),
+        onWidgetVisible: (triggerRuleType: WidgetTriggerRuleType | null) =>
+          this.analyticsTracker?.trackView(triggerRuleType),
+        onLinkClick: (linkUrl: string) =>
+          this.analyticsTracker?.trackLinkClicked(linkUrl),
+        portalContainer: this.shadowRootRef,
+      }),
+    );
+  }
+
+  private async ensureBootstrap() {
+    if (this.bootstrapPromise) {
+      return this.bootstrapPromise;
+    }
+
+    const runVersion = ++this.bootstrapVersion;
+    this.bootstrapPromise = (async () => {
+      if (!this.agentId) {
+        this.status = "error";
+        this.errorMessage = "Missing agent id";
+        this.renderWidget();
+      return;
+    }
+
+      this.bootstrapPhase = "booting";
+      this.status = "booting";
+      this.errorMessage = null;
+      this.renderWidget();
+
+      try {
+        const state = await bootstrapWidget({
+          agentId: this.agentId,
+          pageUrl: window.location.href,
+          referrer: document.referrer || undefined,
+        });
+
+        if (runVersion !== this.bootstrapVersion) {
+          return;
+        }
+
+        this.sessionConfig = {
+          sessionToken: state.session.sessionToken,
+          expiresAt: state.session.expiresAt,
+          widgetConfig: state.session.widgetConfig,
+        };
+        this.sessionState = state.session;
+        this.messages = state.messages;
+        this.widgetTitle = state.session.widgetConfig.name;
+        this.welcomeMessage = state.session.widgetConfig.welcomeMessage;
+        this.status = "ready";
+        this.bootstrapPhase = "ready";
+        if (this.mode === "embed") {
+          this.analyticsTracker?.trackScriptLoaded();
+          this.analyticsTracker?.trackUniqueScriptLoaded();
+        }
+        this.renderWidget();
+      } catch (error) {
+        if (runVersion !== this.bootstrapVersion) {
+          return;
+        }
+
+        this.status = "error";
+        this.bootstrapPhase = "blocked";
+        this.errorMessage =
+          error instanceof Error ? error.message : "Failed to start widget";
+        this.renderWidget();
+      }
+    })().finally(() => {
+      if (runVersion === this.bootstrapVersion) {
+        this.bootstrapPromise = null;
+      }
+    });
+
+    return this.bootstrapPromise;
+  }
+
+  private async sendMessage(content: string) {
+    const trimmedContent = content.trim();
+    if (!trimmedContent || !this.sessionState?.conversationId) return;
+
+    const runVersion = ++this.sendVersion;
+    const optimisticMessageId = `optimistic:${Date.now()}`;
+    const optimisticMessage: WidgetMessage = {
+      id: optimisticMessageId,
+      conversationId: this.sessionState.conversationId,
+      role: "user",
+      content: trimmedContent,
+      createdAt: new Date().toISOString(),
+    };
+
+    this.status = "sending";
+    this.errorMessage = null;
+    this.messages = [...this.messages, optimisticMessage];
+    this.renderWidget();
+
+    try {
+      const result = await submitWidgetMessage({
+        agentId: this.agentId,
+        content: trimmedContent,
+      });
+      if (runVersion !== this.sendVersion) {
+        return;
+      }
+      this.sessionState = result.session;
+
+      const revealSteps = buildAssistantMessageRevealSteps(
+        result.assistantMessages.map((message) => ({
+          id: message.id,
+          content: message.content,
+          createdAt: message.createdAt,
+        })),
+        {
+          initialDelayMs: 0,
+          typingHoldMs: 1260,
+          interMessageDelayMs: 1520,
+          interMessageDelayJitterMs: 100,
+        },
+      );
+
+      for (const step of revealSteps) {
+        await new Promise((resolve) => window.setTimeout(resolve, step.delayMs));
+        if (runVersion !== this.sendVersion) {
+          return;
+        }
+        const dto = step.message;
+        this.messages = [
+          ...this.messages,
+          {
+            id: dto.id,
+            conversationId: result.conversationId,
+            role: "assistant",
+            content: dto.content,
+            createdAt: dto.createdAt,
+          },
+        ];
+        this.renderWidget();
+      }
+
+      if (runVersion === this.sendVersion) {
+        this.status = "ready";
+        this.renderWidget();
+      }
+    } catch (error) {
+      if (runVersion !== this.sendVersion) {
+        return;
+      }
+      this.messages = this.messages.filter(
+        (message) => message.id !== optimisticMessageId,
+      );
+      this.status = "error";
+      this.errorMessage =
+        error instanceof Error ? error.message : "Failed to send message";
+      this.renderWidget();
+    }
+  }
+
+  private async handleOpenChange(nextOpen: boolean) {
+    const wasOpen = this.open;
+    this.open = nextOpen;
+    this.renderWidget();
+    if (!wasOpen && nextOpen && this.mode === "embed") {
+      this.analyticsTracker?.trackClick();
+    }
+
+    if (this.open && (this.status === "idle" || !this.sessionState)) {
+      await this.ensureBootstrap();
+    }
+  }
+
+  private async handleStartConversation() {
+    if (!this.sessionState) {
+      await this.ensureBootstrap();
+    }
+    if (!this.sessionState) {
+      return;
+    }
+
+    this.status = "booting";
+    this.errorMessage = null;
+    this.renderWidget();
+
+    try {
+      const result = await startWidgetConversation({
+        agentId: this.agentId,
+      });
+      this.sessionState = result.session;
+      this.messages = result.messages;
+      this.status = "ready";
+      this.renderWidget();
+    } catch (error) {
+      this.status = "error";
+      this.errorMessage =
+        error instanceof Error ? error.message : "Failed to start conversation";
+      this.renderWidget();
+    }
+  }
+
+  private async handleStopConversation() {
+    if (!this.sessionState?.conversationId) {
+      return;
+    }
+
+    const confirmationId = crypto.randomUUID();
+    const runVersion = ++this.confirmationVersion;
+
+    this.status = "sending";
+    this.errorMessage = null;
+    this.renderWidget();
+
+    try {
+      const result = await submitWidgetStopConfirmation({
+        agentId: this.agentId,
+        confirmationId,
+        prompt: DEFAULT_STOP_CONVERSATION_PROMPT,
+      });
+
+      if (runVersion !== this.confirmationVersion) {
+        return;
+      }
+
+      this.sessionState = result.session;
+      this.messages = [...this.messages, result.confirmationMessage];
+      this.status = "ready";
+      this.renderWidget();
+    } catch (error) {
+      if (runVersion !== this.confirmationVersion) {
+        return;
+      }
+      this.status = "error";
+      this.errorMessage =
+        error instanceof Error ? error.message : "Failed to stop conversation";
+      this.renderWidget();
+    }
+  }
+
+  private async handleConfirmationDecision(
+    confirmationId: string,
+    accepted: boolean,
+  ) {
+    if (!this.sessionState?.conversationId) {
+      return;
+    }
+
+    const runVersion = ++this.confirmationVersion;
+    this.status = "sending";
+    this.errorMessage = null;
+    this.renderWidget();
+
+    try {
+      const result = await submitWidgetStopConfirmation({
+        agentId: this.agentId,
+        confirmationId,
+        decision: accepted ? "accepted" : "rejected",
+      });
+
+      if (runVersion !== this.confirmationVersion) {
+        return;
+      }
+
+      this.sessionState = result.session;
+      this.messages = [...this.messages, result.confirmationMessage];
+      this.renderWidget();
+
+      if (accepted) {
+        window.setTimeout(() => {
+          if (runVersion !== this.confirmationVersion) {
+            return;
+          }
+          void this.handleReset();
+        }, 0);
+      } else {
+        this.status = "ready";
+        this.renderWidget();
+      }
+    } catch (error) {
+      if (runVersion !== this.confirmationVersion) {
+        return;
+      }
+      this.status = "error";
+      this.errorMessage =
+        error instanceof Error ? error.message : "Failed to update confirmation";
+      this.renderWidget();
+    }
+  }
+
+  private handleReset = async () => {
+    this.sendVersion += 1;
+    await resetWidgetSession(this.agentId);
+    this.clearAgentState();
+    this.open = true;
+    this.renderWidget();
+    await this.ensureBootstrap();
+  };
+}
+
+function parseAppearanceAttributes(
+  element: HTMLElement,
+): WidgetAppearanceAttributes {
+  const avatarOrbColor1 = element.getAttribute("avatar-orb-color-1");
+  const avatarOrbColor2 = element.getAttribute("avatar-orb-color-2");
+  const actionText = element.getAttribute("action-text");
+
+  return {
+    avatarOrbColor1: avatarOrbColor1?.trim() || undefined,
+    avatarOrbColor2: avatarOrbColor2?.trim() || undefined,
+    actionText: actionText?.trim() || undefined,
+  };
+}
+
+function normalizeWidgetMode(value: string | null): "embed" | "preview" {
+  return value === "preview" ? "preview" : "embed";
+}

package/src/embed.ts

@@ -0,0 +1,8 @@
+import widgetShadowCss from "@usereq/ui/globals.css?inline";
+import { setWidgetShadowCss } from "./shared/shadow-css";
+import { registerWidgetElement } from "./register";
+
+setWidgetShadowCss(widgetShadowCss);
+registerWidgetElement();
+
+export {};

package/src/index.ts

@@ -0,0 +1,10 @@
+export * from "./shared/widget-config";
+export * from "./shared/analytics";
+export * from "./renderer/index";
+export * from "./types";
+export * from "./shared/shadow-css";
+export * from "./register";
+
+import { registerWidgetElement } from "./register";
+
+registerWidgetElement();

package/src/register.ts

@@ -0,0 +1,15 @@
+import { AgentWidgetElement } from "./custom-element/agent-widget-element";
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "usereq-agent-widget": AgentWidgetElement;
+  }
+}
+
+export function registerWidgetElement() {
+  if (!customElements.get("usereq-agent-widget")) {
+    customElements.define("usereq-agent-widget", AgentWidgetElement);
+  }
+}
+
+export { AgentWidgetElement };

package/src/renderer/index.ts

@@ -0,0 +1,6 @@
+export {
+  WidgetRuntime,
+  type WidgetRuntimeMode,
+  type WidgetRuntimeProps,
+  type WidgetRuntimeStatus,
+} from "./widget-runtime";