@helpai/elements 0.29.0 → 0.30.0

package/index.d.ts

@@ -1,4 +1,4 @@
-export { A as Asset, B as BlocksConfig, C as ConnectionConfig, a as ConnectionConfigPartial, H as HandshakeResponse, L as Link, S as ServerConfig, b as SiteConfig, W as WidgetConfig, c as WidgetConfigPartial, d as WidgetSettings, e as WidgetSettingsPartial } from './deployment-BoOYK9pZ.js';
+export { A as Asset, B as BlocksConfig, C as ConnectionConfig, a as ConnectionConfigPartial, H as HandshakeResponse, L as Link, S as ServerConfig, b as SiteConfig, W as WidgetConfig, c as WidgetConfigPartial, d as WidgetSettings, e as WidgetSettingsPartial } from './deployment-E-Jyc0nF.js';
 import 'zod';
 
 /**
@@ -1120,13 +1120,21 @@ interface ResolvedOptions {
         accept: string;
     };
     /**
-     * Active locale used to compute {@link ResolvedOptions.strings}. Concrete
-     * — `"auto"` is already resolved to a BCP-47 tag at this point.
+     * Active locale used to compute {@link ResolvedOptions.strings} and carried
+     * on every request envelope. Concrete (`"auto"` already resolved to a
+     * BCP-47 tag) and clamped into {@link ResolvedOptions.availableLocales}.
      */
     locale: string;
     /**
-     * Locales offered in the language switcher. Empty array hides the
-     * language action even when it's enabled.
+     * Deployment fallback locale — concrete. The clamp target when the
+     * detected / persisted / picked locale isn't in `availableLocales`.
+     * Server-authoritative (`config.i18n.defaultLocale` wins over `init`).
+     */
+    defaultLocale: string;
+    /**
+     * Locales offered in the language switcher — the deployment's supported
+     * set, server-authoritative (`config.i18n.availableLocales` wins over
+     * `init`). Single-entry hides the language action.
      */
     availableLocales: string[];
     startMinimized: boolean;

package/index.mjs

@@ -524,8 +524,9 @@ function resolveOptions(rawOpts) {
   const header = opts.header ?? {};
   const { themeMode, themeOverrides } = parseTheme(opts.theme);
   const mode = presentation.mode ?? "floating";
-  const locale = i18n.locale ?? resolveDefaultLocale(i18n.defaultLocale);
-  const availableLocales = i18n.availableLocales ?? [locale];
+  const defaultLocale = resolveDefaultLocale(i18n.defaultLocale);
+  const availableLocales = i18n.availableLocales ?? [i18n.locale ?? defaultLocale];
+  const locale = clampLocale(i18n.locale ?? defaultLocale, availableLocales, defaultLocale);
   const baseUrl = (opts.baseUrl ?? BRAND.defaultBaseUrl).replace(/\/$/, "");
   const agentApiBaseUrl = (opts.agentApiBaseUrl ?? `${baseUrl}/api/agent`).replace(/\/$/, "");
   const dataApiBaseUrl = (opts.dataApiBaseUrl ?? `${baseUrl}/api/data`).replace(/\/$/, "");
@@ -567,6 +568,7 @@ function resolveOptions(rawOpts) {
       maxCount: opts.composer?.attachments?.maxCount ?? DEFAULT_ATTACHMENTS.maxCount
     },
     locale,
+    defaultLocale,
     availableLocales,
     startMinimized: behavior.startMinimized ?? true,
     actions: resolveActions(mode, header.actions),
@@ -597,6 +599,11 @@ function resolveDefaultLocale(input) {
   if (input && input !== "auto") return input;
   return typeof navigator !== "undefined" && navigator.language ? navigator.language : "en";
 }
+function clampLocale(desired, availableLocales, defaultLocale) {
+  if (availableLocales.length <= 1 || availableLocales.includes(desired)) return desired;
+  if (availableLocales.includes(defaultLocale)) return defaultLocale;
+  return availableLocales[0] ?? desired;
+}
 function resolveActions(mode, overrides) {
   return overrides ?? DEFAULT_ACTIONS_BY_MODE[mode];
 }
@@ -745,13 +752,14 @@ function resolveLauncher(overrides) {
 
 // src/core/config/overrides.ts
 function applyOptionOverrides(options, activeLocale, activeThemeMode, activeTextSize) {
-  if (activeLocale === options.locale && activeThemeMode === options.themeMode && activeTextSize === options.textSize) {
+  const locale = clampLocale(activeLocale, options.availableLocales, options.defaultLocale);
+  if (locale === options.locale && activeThemeMode === options.themeMode && activeTextSize === options.textSize) {
     return options;
   }
   const next = { ...options };
-  if (activeLocale !== options.locale) {
-    next.locale = activeLocale;
-    next.strings = resolveStrings(activeLocale, options.stringsOverride);
+  if (locale !== options.locale) {
+    next.locale = locale;
+    next.strings = resolveStrings(locale, options.stringsOverride);
   }
   if (activeThemeMode !== options.themeMode) next.themeMode = activeThemeMode;
   if (activeTextSize !== options.textSize) next.textSize = activeTextSize;
@@ -797,6 +805,8 @@ function mergeServerConfig(user, server) {
       serverI18n ?? {},
       userI18n
     );
+    if (serverI18n?.availableLocales !== void 0) merged.availableLocales = serverI18n.availableLocales;
+    if (serverI18n?.defaultLocale !== void 0) merged.defaultLocale = serverI18n.defaultLocale;
     const userStrings = userI18n?.strings;
     const serverStrings = serverI18n?.strings;
     if (userStrings || serverStrings) {
@@ -1422,6 +1432,12 @@ var AgentTransport = class {
     // always sees the visitor's latest context as they navigate.
     __publicField(this, "userContext");
     __publicField(this, "pageContext");
+    // Active BCP-47 locale, carried as the envelope's `locale` on EVERY request
+    // so the backend can localize replies AND the data module can return
+    // localized content + forms. Refreshed via `setLocale` whenever the visitor
+    // switches (no re-handshake needed). Resolved + clamped to the deployment's
+    // availableLocales by `resolveOptions` before it reaches here.
+    __publicField(this, "locale");
     // ---- Data API (content / forms — module-help-ai-data-api) --------------
     //
     // The DATA surfaces live on `dataApiBaseUrl` (default `${baseUrl}/api/data`)
@@ -1447,6 +1463,15 @@ var AgentTransport = class {
     this.userContext = userContext;
     this.pageContext = pageContext;
   }
+  /**
+   * Update the active locale carried on every subsequent request. Call on
+   * mount (before the first handshake) and whenever the user picks a new
+   * locale — the next content / forms / message request reflects it with no
+   * extra round-trip.
+   */
+  setLocale(locale) {
+    this.locale = locale;
+  }
   /**
    * Seed the visitor + conversation identity from persistence BEFORE the first
    * `handshake` resolves. A mount-time `resumeStream()` runs in parallel
@@ -1463,6 +1488,7 @@ var AgentTransport = class {
     const out = {};
     if (this.visitorId) out.visitorId = this.visitorId;
     if (this.conversationId) out.conversationId = this.conversationId;
+    if (this.locale) out.locale = this.locale;
     const context = encodeContext(this.userContext, this.pageContext);
     if (context) out[CONTEXT_PARAM] = context;
     return out;
@@ -6225,7 +6251,7 @@ function ContentView({ id, title, transport, strings, onBack, actions }) {
     return /* @__PURE__ */ jsxs28("article", { class: `${p29}-content`, "data-testid": TID.contentView, children: [
       item.image ? /* @__PURE__ */ jsx33("img", { class: `${p29}-content-hero`, src: item.image, alt: "", loading: "lazy" }) : null,
       item.description ? /* @__PURE__ */ jsx33("p", { class: `${p29}-content-subtitle`, children: item.description }) : null,
-      item.tags && item.tags.length > 0 ? /* @__PURE__ */ jsx33("span", { class: `${p29}-news-tags`, children: item.tags.map((t) => /* @__PURE__ */ jsx33("span", { class: `${p29}-news-tag`, children: t }, t)) }) : null,
+      item.tags?.length ? /* @__PURE__ */ jsx33("span", { class: `${p29}-news-tags`, children: item.tags.map((t) => /* @__PURE__ */ jsx33("span", { class: `${p29}-news-tag`, children: t }, t)) }) : null,
       /* @__PURE__ */ jsx33(StaticMarkdown, { text: item.content ?? "" })
     ] });
   }
@@ -6670,7 +6696,10 @@ function App({ options, hostElement, bus }) {
           visitorId,
           conversationId,
           userPrefs: persistence.loadUserPrefs(),
-          locale: options.locale
+          // The visitor's ACTIVE locale (persisted pick, else auto-detected) —
+          // not the config baseline — so the handshake learns what the visitor
+          // wants. The response's availableLocales then clamps it for the rest.
+          locale: activeLocale
         });
       } catch (err) {
         if (isStale()) return;
@@ -6732,7 +6761,18 @@ function App({ options, hostElement, bus }) {
         setConversationReady(true);
       }
     },
-    [transport, visitorId, persistence, options, bus, conversationIdSig, feedback, playWelcome, loadThread]
+    [
+      transport,
+      visitorId,
+      persistence,
+      options,
+      bus,
+      conversationIdSig,
+      feedback,
+      playWelcome,
+      loadThread,
+      activeLocale
+    ]
   );
   const userSig = JSON.stringify(options.userContext ?? null);
   const pageSig = JSON.stringify(options.pageContext ?? null);
@@ -6741,6 +6781,13 @@ function App({ options, hostElement, bus }) {
     const merged = Object.keys(formContext).length ? { ...formContext, ...options.userContext } : options.userContext;
     transport.setContext(merged, toWirePageContext(options.pageContext));
   }, [transport, userSig, pageSig, formCtxSig]);
+  const effectiveLocale = clampLocale(activeLocale, options.availableLocales, options.defaultLocale);
+  useEffect17(() => {
+    transport.setLocale(effectiveLocale);
+  }, [transport, effectiveLocale]);
+  useEffect17(() => {
+    if (effectiveLocale !== activeLocale) setActiveLocale(effectiveLocale);
+  }, [effectiveLocale, activeLocale]);
   const runResume = useCallback6(
     async (handle) => {
       let bubble = null;
@@ -7606,7 +7653,9 @@ function createTracker(bus, deps) {
     if (url.length > MAX_URL_LENGTH) return;
     const img = new Image(1, 1);
     inflight.add(img);
-    img.onload = img.onerror = () => inflight.delete(img);
+    const settle = () => inflight.delete(img);
+    img.addEventListener("load", settle, { once: true });
+    img.addEventListener("error", settle, { once: true });
     img.src = url;
   };
   const offs = Object.keys(TRACKED).map(

package/package.json

@@ -80,5 +80,5 @@
   ],
   "type": "module",
   "types": "./index.d.ts",
-  "version": "0.29.0"
+  "version": "0.30.0"
 }

package/schema.d.ts

@@ -1,4 +1,4 @@
-export { A as Asset, B as BlocksConfig, C as ConnectionConfig, a as ConnectionConfigPartial, E as Endpoints, H as HandshakeResponse, L as Link, P as PAGE_AREA_SUGGESTIONS, f as PageContext, S as ServerConfig, b as SiteConfig, U as UserContext, W as WidgetConfig, c as WidgetConfigPartial, d as WidgetSettings, e as WidgetSettingsPartial, g as assetSchema, h as blocksConfigSchema, i as connectionConfigPartialSchema, j as connectionConfigSchema, k as cssColorSchema, l as cssLengthSchema, m as endpointsSchema, n as handshakeResponseSchema, o as linkSchema, p as localeSchema, q as pageContextSchema, s as serverConfigSchema, r as siteConfigSchema, u as userContextSchema, t as uuid7Schema, w as widgetConfigPartialSchema, v as widgetConfigSchema, x as widgetSettingsPartialSchema, y as widgetSettingsSchema } from './deployment-BoOYK9pZ.js';
+export { A as Asset, B as BlocksConfig, C as ConnectionConfig, a as ConnectionConfigPartial, E as Endpoints, H as HandshakeResponse, L as Link, P as PAGE_AREA_SUGGESTIONS, f as PageContext, S as ServerConfig, b as SiteConfig, U as UserContext, W as WidgetConfig, c as WidgetConfigPartial, d as WidgetSettings, e as WidgetSettingsPartial, g as assetSchema, h as blocksConfigSchema, i as connectionConfigPartialSchema, j as connectionConfigSchema, k as cssColorSchema, l as cssLengthSchema, m as endpointsSchema, n as handshakeResponseSchema, o as linkSchema, p as localeSchema, q as pageContextSchema, s as serverConfigSchema, r as siteConfigSchema, u as userContextSchema, t as uuid7Schema, w as widgetConfigPartialSchema, v as widgetConfigSchema, x as widgetSettingsPartialSchema, y as widgetSettingsSchema } from './deployment-E-Jyc0nF.js';
 import { z } from 'zod';
 
 /**
@@ -56,9 +56,9 @@ declare const presentationSchema: z.ZodObject<{
         inset: z.ZodOptional<z.ZodString>;
         initialSize: z.ZodDefault<z.ZodEnum<{
             fullscreen: "fullscreen";
+            normal: "normal";
             expanded: "expanded";
             auto: "auto";
-            normal: "normal";
         }>>;
         autoSizeBreakpoint: z.ZodDefault<z.ZodNumber>;
     }, z.core.$loose>>;
@@ -148,9 +148,9 @@ declare const launcherSizeSchema: z.ZodEnum<{
 }>;
 type LauncherSize = z.infer<typeof launcherSizeSchema>;
 declare const calloutShapeSchema: z.ZodEnum<{
-    callout: "callout";
     pill: "pill";
     bubble: "bubble";
+    callout: "callout";
 }>;
 type CalloutShape = z.infer<typeof calloutShapeSchema>;
 declare const calloutPositionSchema: z.ZodEnum<{
@@ -162,9 +162,9 @@ type CalloutPosition = z.infer<typeof calloutPositionSchema>;
 declare const launcherCalloutSchema: z.ZodObject<{
     text: z.ZodDefault<z.ZodString>;
     shape: z.ZodDefault<z.ZodEnum<{
-        callout: "callout";
         pill: "pill";
         bubble: "bubble";
+        callout: "callout";
     }>>;
     position: z.ZodDefault<z.ZodEnum<{
         auto: "auto";
@@ -195,9 +195,9 @@ declare const launcherOptionsSchema: z.ZodObject<{
     callout: z.ZodOptional<z.ZodObject<{
         text: z.ZodDefault<z.ZodString>;
         shape: z.ZodDefault<z.ZodEnum<{
-            callout: "callout";
             pill: "pill";
             bubble: "bubble";
+            callout: "callout";
         }>>;
         position: z.ZodDefault<z.ZodEnum<{
             auto: "auto";
@@ -240,9 +240,9 @@ type LauncherOptions = z.infer<typeof launcherOptionsSchema>;
 
 declare const initialSizeSchema: z.ZodEnum<{
     fullscreen: "fullscreen";
+    normal: "normal";
     expanded: "expanded";
     auto: "auto";
-    normal: "normal";
 }>;
 declare const resizeOptionsSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
@@ -269,9 +269,9 @@ declare const sizeOptionsSchema: z.ZodObject<{
     inset: z.ZodOptional<z.ZodString>;
     initialSize: z.ZodDefault<z.ZodEnum<{
         fullscreen: "fullscreen";
+        normal: "normal";
         expanded: "expanded";
         auto: "auto";
-        normal: "normal";
     }>>;
     autoSizeBreakpoint: z.ZodDefault<z.ZodNumber>;
 }, z.core.$loose>;
@@ -323,43 +323,43 @@ type FeatureFlags = z.infer<typeof featureFlagsSchema>;
  */
 
 declare const actionNameSchema: z.ZodEnum<{
-    close: "close";
     expand: "expand";
     fullscreen: "fullscreen";
     popOut: "popOut";
-    clear: "clear";
-    theme: "theme";
+    close: "close";
     language: "language";
+    theme: "theme";
     textSize: "textSize";
     history: "history";
+    clear: "clear";
     sound: "sound";
 }>;
 type ActionName = z.infer<typeof actionNameSchema>;
 declare const headerActionsSchema: z.ZodArray<z.ZodEnum<{
-    close: "close";
     expand: "expand";
     fullscreen: "fullscreen";
     popOut: "popOut";
-    clear: "clear";
-    theme: "theme";
+    close: "close";
     language: "language";
+    theme: "theme";
     textSize: "textSize";
     history: "history";
+    clear: "clear";
     sound: "sound";
 }>>;
 type HeaderActions = z.infer<typeof headerActionsSchema>;
 /** Section wrapper — `actions` list wrapped under `header` in the dashboard form. */
 declare const headerSchema: z.ZodObject<{
     actions: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        close: "close";
         expand: "expand";
         fullscreen: "fullscreen";
         popOut: "popOut";
-        clear: "clear";
-        theme: "theme";
+        close: "close";
         language: "language";
+        theme: "theme";
         textSize: "textSize";
         history: "history";
+        clear: "clear";
         sound: "sound";
     }>>>;
 }, z.core.$loose>;
@@ -375,33 +375,33 @@ type HeaderOptions = z.infer<typeof headerSchema>;
  */
 
 declare const feedbackEventSchema: z.ZodEnum<{
-    voiceStart: "voiceStart";
-    voiceStop: "voiceStop";
     error: "error";
     messageReceived: "messageReceived";
     messageSent: "messageSent";
+    voiceStart: "voiceStart";
+    voiceStop: "voiceStop";
 }>;
 type FeedbackEvent = z.infer<typeof feedbackEventSchema>;
 declare const soundOptionsSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
     volume: z.ZodDefault<z.ZodNumber>;
     events: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
-        voiceStart: "voiceStart";
-        voiceStop: "voiceStop";
         error: "error";
         messageReceived: "messageReceived";
         messageSent: "messageSent";
+        voiceStart: "voiceStart";
+        voiceStop: "voiceStop";
     }> & z.core.$partial, z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>>;
 }, z.core.$loose>;
 type SoundOptions = z.infer<typeof soundOptionsSchema>;
 declare const hapticsOptionsSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
     events: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
-        voiceStart: "voiceStart";
-        voiceStop: "voiceStop";
         error: "error";
         messageReceived: "messageReceived";
         messageSent: "messageSent";
+        voiceStart: "voiceStart";
+        voiceStop: "voiceStop";
     }> & z.core.$partial, z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodArray<z.ZodNumber>]>>>;
 }, z.core.$loose>;
 type HapticsOptions = z.infer<typeof hapticsOptionsSchema>;
@@ -410,21 +410,21 @@ declare const feedbackSchema: z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         volume: z.ZodDefault<z.ZodNumber>;
         events: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
-            voiceStart: "voiceStart";
-            voiceStop: "voiceStop";
             error: "error";
             messageReceived: "messageReceived";
             messageSent: "messageSent";
+            voiceStart: "voiceStart";
+            voiceStop: "voiceStop";
         }> & z.core.$partial, z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>>;
     }, z.core.$loose>>;
     haptics: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         events: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
-            voiceStart: "voiceStart";
-            voiceStop: "voiceStop";
             error: "error";
             messageReceived: "messageReceived";
             messageSent: "messageSent";
+            voiceStart: "voiceStart";
+            voiceStop: "voiceStop";
         }> & z.core.$partial, z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodArray<z.ZodNumber>]>>>;
     }, z.core.$loose>>;
 }, z.core.$loose>;
@@ -544,16 +544,16 @@ type FooterOptions = z.infer<typeof footerSchema>;
 
 declare const fieldTypeSchema: z.ZodEnum<{
     number: "number";
-    select: "select";
-    textarea: "textarea";
-    time: "time";
     text: "text";
-    checkbox: "checkbox";
-    radio: "radio";
     url: "url";
     email: "email";
     tel: "tel";
     date: "date";
+    time: "time";
+    textarea: "textarea";
+    select: "select";
+    radio: "radio";
+    checkbox: "checkbox";
     multiselect: "multiselect";
 }>;
 type FieldType = z.infer<typeof fieldTypeSchema>;
@@ -578,16 +578,16 @@ declare const formFieldSchema: z.ZodObject<{
     label: z.ZodString;
     type: z.ZodEnum<{
         number: "number";
-        select: "select";
-        textarea: "textarea";
-        time: "time";
         text: "text";
-        checkbox: "checkbox";
-        radio: "radio";
         url: "url";
         email: "email";
         tel: "tel";
         date: "date";
+        time: "time";
+        textarea: "textarea";
+        select: "select";
+        radio: "radio";
+        checkbox: "checkbox";
         multiselect: "multiselect";
     }>;
     placeholder: z.ZodOptional<z.ZodString>;
@@ -638,16 +638,16 @@ declare const formDefSchema: z.ZodObject<{
         label: z.ZodString;
         type: z.ZodEnum<{
             number: "number";
-            select: "select";
-            textarea: "textarea";
-            time: "time";
             text: "text";
-            checkbox: "checkbox";
-            radio: "radio";
             url: "url";
             email: "email";
             tel: "tel";
             date: "date";
+            time: "time";
+            textarea: "textarea";
+            select: "select";
+            radio: "radio";
+            checkbox: "checkbox";
             multiselect: "multiselect";
         }>;
         placeholder: z.ZodOptional<z.ZodString>;
@@ -698,16 +698,16 @@ declare const formsSchema: z.ZodArray<z.ZodObject<{
         label: z.ZodString;
         type: z.ZodEnum<{
             number: "number";
-            select: "select";
-            textarea: "textarea";
-            time: "time";
             text: "text";
-            checkbox: "checkbox";
-            radio: "radio";
             url: "url";
             email: "email";
             tel: "tel";
             date: "date";
+            time: "time";
+            textarea: "textarea";
+            select: "select";
+            radio: "radio";
+            checkbox: "checkbox";
             multiselect: "multiselect";
         }>;
         placeholder: z.ZodOptional<z.ZodString>;
@@ -781,18 +781,18 @@ type I18nOptions = z.infer<typeof i18nSchema>;
  */
 
 declare const moduleLayoutSchema: z.ZodEnum<{
-    home: "home";
     chat: "chat";
     help: "help";
+    home: "home";
     news: "news";
 }>;
 type ModuleLayout = z.infer<typeof moduleLayoutSchema>;
 declare const moduleSchema: z.ZodObject<{
     label: z.ZodString;
     layout: z.ZodEnum<{
-        home: "home";
         chat: "chat";
         help: "help";
+        home: "home";
         news: "news";
     }>;
     contentTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -818,9 +818,9 @@ type ModuleOptions = z.infer<typeof moduleSchema>;
 declare const modulesSchema: z.ZodArray<z.ZodObject<{
     label: z.ZodString;
     layout: z.ZodEnum<{
-        home: "home";
         chat: "chat";
         help: "help";
+        home: "home";
         news: "news";
     }>;
     contentTags: z.ZodOptional<z.ZodArray<z.ZodString>>;