@helpai/elements 0.30.0 → 0.31.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-E-Jyc0nF.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-DRGLrW2j.js';
 import 'zod';
 
 /**
@@ -505,6 +505,46 @@ interface FormDef {
      * `/activity` records for such forms).
      */
     reviewable?: boolean;
+    /** BCP-47 locale the top-level strings (title / fields copy) are authored in. */
+    defaultLocale?: string;
+    /**
+     * Per-locale string overrides. The data module trims this to the requested
+     * `?locale=` (≤1 entry); the widget overlays it onto the default copy at
+     * resolve time (`overlayFormDef`). Absent strings fall back to the default.
+     */
+    translations?: FormTranslation[];
+}
+/**
+ * Per-locale overrides of a form's HUMAN-FACING strings only. Structure (field
+ * `name` / `type` / `validation`, option `value`) is shared across locales and
+ * stays canonical, so submissions + validation are locale-independent — a
+ * translation matches the canonical form by the stable `name` (field) / `value`
+ * (option) keys. Absent strings fall back to the top-level (defaultLocale) copy.
+ *
+ * The data module trims `FormDef.translations` to the requested `?locale=` (≤1
+ * entry) on read; the widget overlays that entry onto the default fields. Mirror
+ * of `module-help-ai-data-api` `DynamicFormTranslation`.
+ */
+interface FieldOptionTranslation {
+    /** The canonical option `value` this localizes. */
+    value: string;
+    label?: string;
+    description?: string;
+}
+interface FormFieldTranslation {
+    /** The canonical field `name` this localizes. */
+    name: string;
+    label?: string;
+    placeholder?: string;
+    validationHint?: string;
+    options?: FieldOptionTranslation[];
+}
+interface FormTranslation {
+    locale: string;
+    title?: string;
+    description?: string;
+    submitLabel?: string;
+    fields?: FormFieldTranslation[];
 }
 /** The `forms` block is an ordered list (max 20); order = priority. */
 type FormsOptions = FormDef[];
@@ -1392,6 +1432,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.
  *
@@ -1437,24 +1523,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`.
  *
@@ -1652,12 +1720,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 };