@helpai/elements 0.29.1 → 0.30.1

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-rva7dkso.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;
@@ -1384,6 +1392,52 @@ interface EventMap {
 }
 type EventName = keyof EventMap;
 
+/**
+ * Derives the `data-mode` attribute value from App state.
+ *
+ * Kept as a pure helper (no DOM, no React) so tests can pin the critical
+ * invariants cheaply:
+ *
+ * - `isOpen === false` → `"closed"` regardless of `panelSize`.
+ *   This is the reason closing from fullscreen doesn't hide the launcher:
+ *   the `[data-mode="fullscreen"] .__P__-fab { display: none }` rule never
+ *   matches when the widget is closed.
+ * - `panelSize` is preserved across close → open, so reopening the widget
+ *   restores the user's last layout (normal / expanded / fullscreen).
+ * - Inline + standalone are terminal modes: they override any panelSize
+ *   because the widget isn't a popover and can't be "closed".
+ */
+
+type HostMode = "page" | "standalone" | "inline" | "modal" | "drawer" | "fullscreen" | "expanded" | "open" | "closed";
+
+/**
+ * Shared widget runtime — the one composition both entry points wrap around
+ * `<App>`.
+ *
+ * `mount()` (`src/index.ts`, programmatic, `widgetId`-keyed registry, returns a
+ * handle) and `<web-ai-chat>` (`src/web-component.ts`, declarative, N-per-page,
+ * no registry) used to each hand-roll the same four things around the App tree:
+ * the ErrorBoundary wrapper, the handshake-config merge, the usage tracker, and
+ * the host-attribute application (position / theme / `data-mode`). That parallel
+ * code drifted three separate times (mode-merge, tracker, ErrorBoundary). This
+ * module is the single source of that composition so it can't drift again — both
+ * entry points only own what's genuinely theirs (mount: iframe + handle + hooks
+ * + registry; web-component: attribute parsing + the custom-element lifecycle).
+ */
+
+/**
+ * Determine what `data-mode` the host should start at — matching what App's
+ * mount-time `useEffect` will produce on its first render. Used for the initial
+ * paint in both entry points (and `mount()`'s iframe sizing); after that, App
+ * owns `data-mode` for the lifetime of the instance.
+ *
+ * `resolveInitialPanelState` is the one source of truth for "what does the first
+ * render look like" — App.tsx uses it too. If these two paths ever pick
+ * different initial states, an iframe physically resizes between mount and App's
+ * first effect (the closed→open→closed flicker this pins against).
+ */
+declare function resolveInitialHostMode(options: ResolvedOptions): HostMode;
+
 /**
  * Global lifecycle-hook registry.
  *
@@ -1429,24 +1483,6 @@ declare const HOOK_WILDCARD = "*";
  */
 type HookListener = (instance: ChatWidgetInstance, event: EventName, data: unknown) => void;
 
-/**
- * Derives the `data-mode` attribute value from App state.
- *
- * Kept as a pure helper (no DOM, no React) so tests can pin the critical
- * invariants cheaply:
- *
- * - `isOpen === false` → `"closed"` regardless of `panelSize`.
- *   This is the reason closing from fullscreen doesn't hide the launcher:
- *   the `[data-mode="fullscreen"] .__P__-fab { display: none }` rule never
- *   matches when the widget is closed.
- * - `panelSize` is preserved across close → open, so reopening the widget
- *   restores the user's last layout (normal / expanded / fullscreen).
- * - Inline + standalone are terminal modes: they override any panelSize
- *   because the widget isn't a popover and can't be "closed".
- */
-
-type HostMode = "page" | "standalone" | "inline" | "modal" | "drawer" | "fullscreen" | "expanded" | "open" | "closed";
-
 /**
  * Public ESM entry for `@<brand>/elements`.
  *
@@ -1644,12 +1680,5 @@ declare const brand: {
     readonly domain: string;
     readonly siteUrl: string;
 };
-/**
- * Determine what `data-mode` the host should start at — matching what
- * App's mount-time `useEffect` will produce on its first render. Exposed
- * only for the initial paint path in `mount()` (and the test suite);
- * after that, App owns `data-mode` for the lifetime of the instance.
- */
-declare function resolveInitialHostMode(options: ResolvedOptions): HostMode;
 
 export { type ChatWidgetInstance, type ChatWidgetOptions, type EventMap, type EventName, HOOK_WILDCARD, type HookListener, type LogEntry, type LogLevel, type ResolvedOptions, brand, destroy, getAllInstances, getInstance, hook, init, mount, resolveInitialHostMode, version };