@usereq/widget 0.2.24 → 0.2.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usereq/widget",
-  "version": "0.2.24",
+  "version": "0.2.25",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/chat-widget/chat-widget-appearance.ts

@@ -1,12 +1,81 @@
 import type { CSSProperties } from "react";
 
+export type ChatWidgetGradient = {
+  from: string;
+  to: string;
+  angle?: number | null;
+};
+
+/** Solid hex or gradient. Mirrors `ChatColor` in `@usereq/ui`. */
+export type ChatWidgetColor = string | ChatWidgetGradient;
+
+export type ChatWidgetIconPack = "lucide" | "heroicons" | "phosphor";
+
+export type ChatWidgetIconSlot =
+  | "launcher"
+  | "send"
+  | "close"
+  | "minimize"
+  | "attach"
+  | "mic";
+
+export type ChatWidgetIcons = {
+  pack?: ChatWidgetIconPack | null;
+  overrides?: Partial<Record<ChatWidgetIconSlot, string>> | null;
+};
+
+/**
+ * Every appearance token the agents row can store.
+ *
+ * This deliberately mirrors `ChatAppearance` in `@usereq/ui` field-for-field,
+ * but is declared standalone rather than imported: `shared/widget-config` is
+ * consumed by `apps/api`, which has no `@usereq/ui` dependency. Structural
+ * typing means the two still line up where they meet.
+ *
+ * Keep in sync with `widgetAppearanceSchema` in the API's `widget.model.ts`
+ * and `AgentWidgetAppearance` in the dashboard.
+ */
 export type ChatWidgetAppearance = {
+  // — Legacy gradient (still the fallback when `primary` is unset) —
   avatarOrbColor1?: string | null;
   avatarOrbColor2?: string | null;
+
+  // — Brand —
+  primary?: ChatWidgetColor | null;
+  primaryForeground?: string | null;
+  secondary?: string | null;
+  secondaryForeground?: string | null;
   actionText?: string | null;
+
+  // — Surface tokens (panel) —
+  background?: string | null;
+  foreground?: string | null;
+  muted?: string | null;
+  mutedForeground?: string | null;
+  border?: string | null;
+  ring?: string | null;
+
+  // — Granular text overrides —
+  textPrimary?: string | null;
+  textForeground?: string | null;
+  textMutedForeground?: string | null;
+
+  // — Icon pack swap (persist-only for now) —
+  icons?: ChatWidgetIcons | null;
 };
 
-export type ResolvedChatWidgetAppearance = Required<ChatWidgetAppearance>;
+/**
+ * Only the three legacy fields are guaranteed present — every other token
+ * stays optional on purpose, because `undefined` means "not customized, use
+ * the design-system default". Filling them with defaults here would emit
+ * `--chat-*` variables for tokens the user never set and lock the panel out
+ * of the host theme.
+ */
+export type ResolvedChatWidgetAppearance = ChatWidgetAppearance & {
+  avatarOrbColor1: string;
+  avatarOrbColor2: string;
+  actionText: string;
+};
 
 export const DEFAULT_CHAT_WIDGET_APPEARANCE: ResolvedChatWidgetAppearance = {
   avatarOrbColor1: "#2563eb",
@@ -14,10 +83,20 @@ export const DEFAULT_CHAT_WIDGET_APPEARANCE: ResolvedChatWidgetAppearance = {
   actionText: "Need help?",
 };
 
+/**
+ * Fills defaults for the three legacy fields and passes every other token
+ * through untouched.
+ *
+ * The spread is load-bearing: this function used to construct a fresh
+ * three-key object, which silently discarded the entire saved theme
+ * (background, primary, text colors…) on its way to the embed. Any new token
+ * added to `ChatWidgetAppearance` now survives without editing this function.
+ */
 export function resolveChatWidgetAppearance(
   appearance?: Partial<ChatWidgetAppearance> | null,
 ): ResolvedChatWidgetAppearance {
   return {
+    ...(appearance ?? {}),
     avatarOrbColor1:
       normalizeString(appearance?.avatarOrbColor1) ??
       DEFAULT_CHAT_WIDGET_APPEARANCE.avatarOrbColor1,

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

@@ -168,7 +168,13 @@ export class AgentWidgetElement extends HTMLElement {
     const base =
       this.sessionConfig?.widgetConfig.widgetAppearance ?? DEFAULT_WIDGET_APPEARANCE;
 
+    // Spread first, then apply the three attribute-overridable fields on top.
+    // Only those three are exposed as HTML attributes; every other token
+    // (surface colors, brand, text) comes from the agent config and must
+    // pass through untouched — rebuilding a fixed-key object here is what
+    // used to drop a customer's saved theme on the floor.
     return {
+      ...base,
       avatarOrbColor1:
         this.appearanceAttributes.avatarOrbColor1?.trim() ||
         base.avatarOrbColor1,

package/src/renderer/widget-runtime.tsx

@@ -255,12 +255,22 @@ function mapPreset(preset: WidgetPreset): ChatWidgetConfig["preset"] {
   return preset;
 }
 
+/**
+ * `WidgetAppearance` mirrors `ChatAppearance` field-for-field (see
+ * `chat-widget/chat-widget-appearance.ts` for why it's declared separately),
+ * so this is a structural pass-through rather than a field-by-field copy.
+ *
+ * It used to rebuild a three-key object, which meant that even once the API
+ * started sending the full theme, the surface and brand tokens were dropped
+ * again right here — one strip point behind the other.
+ */
 function toChatAppearance(appearance: WidgetAppearance): ChatAppearance {
-  return {
-    avatarOrbColor1: appearance.avatarOrbColor1 ?? null,
-    avatarOrbColor2: appearance.avatarOrbColor2 ?? null,
-    actionText: appearance.actionText ?? null,
-  };
+  // Deliberately NOT a cast. Returning the value unasserted makes the
+  // compiler verify that `WidgetAppearance` is still structurally
+  // assignable to `ChatAppearance` — so if the two ever drift (a token
+  // added to one and not the other), this fails typecheck instead of
+  // silently dropping the field the way the old field-by-field copy did.
+  return appearance;
 }
 
 function isHtmlElement(