@helpai/elements 1.5.8 → 1.5.10

package/index.d.ts

@@ -1,5 +1,4 @@
 import { z } from "zod";
-//#region src/core/storage.d.ts
 /**
  * Pluggable client-side key-value storage.
  *
@@ -25,8 +24,6 @@ interface ClientStorage {
   /** Removes `key`. No-op if absent. */
   remove(key: string): void;
 }
-//#endregion
-//#region src/i18n/strings.d.ts
 /**
  * UI strings — built-in defaults, type contracts, and runtime resolution.
  *
@@ -41,7 +38,7 @@ interface ClientStorage {
  * populated {@link Strings} map. UI components then read `strings.send` as a
  * normal property access — no per-render lookup, no per-render allocation.
  */
-type StringKey = 'launcherOpen' | 'launcherLabel' | 'panelTitle' | 'composerPlaceholder' | 'send' | 'stop' | 'queueMessage' | 'removeQueuedMessage' | 'compactingContext' | 'attach' | 'micStart' | 'micStop' | 'micUnsupported' | 'expand' | 'collapse' | 'fullscreen' | 'exitFullscreen' | 'popOut' | 'resizeHandle' | 'scrollToBottom' | 'close' | 'moreActions' | 'soundOn' | 'soundOff' | 'language' | 'theme' | 'themeAuto' | 'themeLight' | 'themeDark' | 'textSize' | 'textSizeSmall' | 'textSizeNormal' | 'textSizeLarge' | 'history' | 'historyTitle' | 'historyEmpty' | 'historyLoading' | 'historyBack' | 'historyContinue' | 'loadMoreConversations' | 'conversationLoading' | 'loadPreviousMessages' | 'conversationClosed' | 'startNewConversation' | 'talkToOperator' | 'connectingOperator' | 'noOperatorAvailable' | 'chattingWithOperator' | 'cancelOperatorRequest' | 'dateToday' | 'dateYesterday' | 'dateLastWeek' | 'dateOlder' | 'newConversation' | 'dropZone' | 'attachmentTooLarge' | 'attachmentTooMany' | 'attachmentMimeRejected' | 'errorRetry' | 'errorGeneric' | 'errorRateLimited' | 'loading' | 'visualPreparing' | 'visualError' | 'visualPartial' | 'thinking' | 'thoughts' | 'toolResult' | 'sources' | 'feedbackUp' | 'feedbackDown' | 'feedbackThanks' | 'copy' | 'copied' | 'collapseSidebar' | 'expandSidebar' | 'formSubmit' | 'formSkip' | 'formSubmitted' | 'formSkipped' | 'formFillOut' | 'formRequired' | 'formInvalidEmail' | 'formInvalidTel' | 'formInvalidUrl' | 'formInvalidNumber' | 'formTooShort' | 'formTooLong' | 'formNumberTooSmall' | 'formNumberTooLarge' | 'formPatternMismatch' | 'formChooseAtLeast' | 'formChooseAtMost' | 'formOther' | 'formOtherPlaceholder' | 'inputRequired' | 'inputBadge' | 'inputAnswered' | 'inputSkipped' | 'inputSubmit' | 'inputSubmitHint' | 'inputSkip' | 'showOptions' | 'hideOptions' | 'qtypeText' | 'qtypeEmail' | 'qtypePhone' | 'qtypeNumber' | 'qtypeDate' | 'qtypeChooseOne' | 'qtypeChooseAny' | 'qtypeBoolean' | 'confirmYes' | 'confirmNo' | 'approve' | 'reject' | 'approvalPrompt' | 'approvalBody' | 'approvalYourResponse' | 'approvalEditHint' | 'approvalSubmitting' | 'edit' | 'toolParameters' | 'statusAwaiting' | 'statusResponded' | 'statusCompleted' | 'statusDenied' | 'statusError' | 'statusRunning' | 'statusSuperseded' | 'tabHome' | 'tabConversations' | 'tabHelp' | 'tabNews' | 'modulesEmpty' | 'moduleBack' | 'contentLoading' | 'contentHelpful' | 'homeGreeting' | 'homeGreetingNamed' | 'homeGreetingLead' | 'homeSearchPlaceholder' | 'homeContentTitle' | 'homeStatus' | 'helpTitle' | 'helpSearchPlaceholder' | 'helpEmpty' | 'helpLoading' | 'helpSearchEmpty' | 'helpShowMore' | 'newsTitle' | 'newsEmpty' | 'newsLoading' | 'newsBack' | 'newsPublishedAt';
+type StringKey = 'launcherOpen' | 'launcherLabel' | 'panelTitle' | 'composerPlaceholder' | 'send' | 'stop' | 'queueMessage' | 'removeQueuedMessage' | 'compactingContext' | 'attach' | 'micStart' | 'micStop' | 'micUnsupported' | 'expand' | 'collapse' | 'fullscreen' | 'exitFullscreen' | 'popOut' | 'resizeHandle' | 'scrollToBottom' | 'close' | 'moreActions' | 'soundOn' | 'soundOff' | 'language' | 'theme' | 'themeAuto' | 'themeLight' | 'themeDark' | 'textSize' | 'textSizeSmall' | 'textSizeNormal' | 'textSizeLarge' | 'history' | 'historyTitle' | 'historyEmpty' | 'historyLoading' | 'historyBack' | 'historyContinue' | 'loadMoreConversations' | 'conversationLoading' | 'loadPreviousMessages' | 'conversationClosed' | 'startNewConversation' | 'talkToOperator' | 'connectingOperator' | 'noOperatorAvailable' | 'chattingWithOperator' | 'cancelOperatorRequest' | 'dateToday' | 'dateYesterday' | 'dateLastWeek' | 'dateOlder' | 'newConversation' | 'dropZone' | 'attachmentTooLarge' | 'attachmentTooMany' | 'attachmentMimeRejected' | 'errorRetry' | 'errorGeneric' | 'errorRateLimited' | 'loading' | 'visualPreparing' | 'visualError' | 'visualPartial' | 'thinking' | 'thoughts' | 'toolResult' | 'sources' | 'feedbackUp' | 'feedbackDown' | 'feedbackThanks' | 'copy' | 'copied' | 'collapseSidebar' | 'expandSidebar' | 'formSubmit' | 'formSkip' | 'formSubmitted' | 'formSkipped' | 'formFillOut' | 'formRequired' | 'formInvalidEmail' | 'formInvalidTel' | 'formInvalidUrl' | 'formInvalidNumber' | 'formTooShort' | 'formTooLong' | 'formNumberTooSmall' | 'formNumberTooLarge' | 'formPatternMismatch' | 'formChooseAtLeast' | 'formChooseAtMost' | 'formOther' | 'formOtherPlaceholder' | 'inputRequired' | 'inputBadge' | 'inputAnswered' | 'inputSkipped' | 'inputSubmit' | 'inputSubmitHint' | 'inputSkip' | 'showOptions' | 'hideOptions' | 'qtypeText' | 'qtypeEmail' | 'qtypePhone' | 'qtypeNumber' | 'qtypeDate' | 'qtypeChooseOne' | 'qtypeChooseAny' | 'qtypeBoolean' | 'confirmYes' | 'confirmNo' | 'approve' | 'reject' | 'approvalPrompt' | 'approvalBody' | 'approvalYourResponse' | 'approvalEditHint' | 'approvalSubmitting' | 'edit' | 'toolParameters' | 'statusAwaiting' | 'statusResponded' | 'statusCompleted' | 'statusDenied' | 'statusError' | 'statusRunning' | 'statusSuperseded' | 'tabHome' | 'tabConversations' | 'tabHelp' | 'tabNews' | 'modulesEmpty' | 'moduleBack' | 'contentLoading' | 'contentHelpful' | 'homeGreeting' | 'homeGreetingNamed' | 'homeGreetingLead' | 'homeSearchPlaceholder' | 'homeAskPlaceholder' | 'homeWhatsNew' | 'homeContentTitle' | 'homeStatus' | 'helpTitle' | 'helpSearchPlaceholder' | 'helpEmpty' | 'helpLoading' | 'helpSearchEmpty' | 'helpShowMore' | 'newsTitle' | 'newsEmpty' | 'newsLoading' | 'newsBack' | 'newsPublishedAt' | 'newsShowMore' | 'newsUnseen';
 /** A partial map for one locale — what overrides look like on the wire. */
 type LocaleStrings = Partial<Record<StringKey, string>>;
 /**
@@ -65,8 +62,6 @@ type Strings = Record<StringKey, string>;
  * top-level value is an object, the whole override is treated as nested.
  */
 type StringsOverride = LocaleStrings | Partial<Record<string, LocaleStrings>>;
-//#endregion
-//#region src/core/config/types/common.d.ts
 /**
  * Primitive type aliases shared across every config section. Kept in
  * one file so a domain-specific change (adding a new `Mode` value,
@@ -134,8 +129,6 @@ type ActionName = 'clear' | 'expand' | 'fullscreen' | 'popOut' | 'sound' | 'hist
  * set for each mode; a deployment can replace the whole list.
  */
 type ActionList = ActionName[];
-//#endregion
-//#region src/core/config/types/composer.d.ts
 /**
  * Composer chrome and capability flags. `ChatWidgetOptions.composer` owns the
  * send-button skin + attachment limits; `ChatWidgetOptions.features` owns voice,
@@ -212,8 +205,6 @@ interface ComposerOptions {
   /** Client-side attachment limits. Server still validates at upload time. */
   attachments?: AttachmentLimits;
 }
-//#endregion
-//#region src/core/config/types/feedback.d.ts
 /**
  * Audible + tactile feedback knobs. Both channels default to enabled (browser
  * autoplay policy still gates audio playback).
@@ -261,8 +252,6 @@ interface FeedbackOptions {
   sound?: SoundOptions;
   haptics?: HapticsOptions;
 }
-//#endregion
-//#region src/core/config/types/forms.d.ts
 /**
  * Event-driven forms engine — framework-free runtime types (mirror of
  * `src/schema/widget/forms.ts`). The IIFE path has no Zod, so these plain
@@ -450,8 +439,6 @@ interface ResolvedForms {
   /** Forms keyed by trigger kind, for fast event lookup. */
   byTrigger: Partial<Record<TriggerKind, ResolvedForm[]>>;
 }
-//#endregion
-//#region src/core/config/types/launcher.d.ts
 /**
  * Launcher (floating-mode FAB) + the pre-engagement callout bubble.
  * Inputs are option-bag shaped; the resolved variant lives in `widget.ts`.
@@ -518,8 +505,6 @@ interface LauncherOptions {
   /** Pre-engagement bubble next to the FAB. See {@link LauncherCalloutOptions}. */
   callout?: LauncherCalloutOptions;
 }
-//#endregion
-//#region src/core/config/types/modules.d.ts
 /**
  * Messenger "modules" runtime config types — framework-free mirror of
  * `src/schema/widget/modules.ts`. The IIFE runtime path has no Zod, so
@@ -604,8 +589,6 @@ interface ResolvedModules {
   /** The tabs keyed by `id` (for nav + per-tab config lookup). */
   byId: Record<string, ResolvedModule>;
 }
-//#endregion
-//#region src/core/config/types/presentation.d.ts
 /** CSS-custom-property overrides applied as inline styles on the host. */
 interface ThemeOverrides {
   accent?: string;
@@ -697,8 +680,6 @@ interface PresentationOptions {
   iframe?: boolean;
   size?: SizeOptions;
 }
-//#endregion
-//#region src/core/config/types/sections.d.ts
 /**
  * Section: conversation runtime behaviour — auto-open, streaming mode, and the
  * transcript surface (what renders, how it scrolls, reaction controls).
@@ -844,8 +825,6 @@ interface Endpoints {
    */
   submitForm?: string;
 }
-//#endregion
-//#region src/core/config/types/tracking.d.ts
 /**
  * Built-in anonymous usage tracking — utm.gif-style pixel hits that give
  * the widget OWNER (the site embedding it) insights about how visitors
@@ -897,8 +876,6 @@ interface ResolvedTracking {
   sampleRate: number;
   token?: string;
 }
-//#endregion
-//#region src/core/config/types/widget.d.ts
 /**
  * Raw options passed to {@link mount}, {@link init}, the Web Component, or
  * the `<script data-*>` auto-boot path. The public `mount()` / `init()`
@@ -1109,11 +1086,7 @@ interface ResolvedOptions {
   onClose?: ChatWidgetOptions['onClose'];
   onError?: ChatWidgetOptions['onError'];
 }
-//#endregion
-//#region src/ui/host-mode.d.ts
 type HostMode = 'page' | 'standalone' | 'inline' | 'modal' | 'drawer' | 'fullscreen' | 'expanded' | 'open' | 'closed';
-//#endregion
-//#region src/schema/primitives.d.ts
 /** A single image asset (logo, hero, icon). */
 declare const assetSchema: z.ZodObject<{
   url: z.ZodString;
@@ -1129,8 +1102,6 @@ declare const linkSchema: z.ZodObject<{
   description: z.ZodOptional<z.ZodString>;
 }, z.core.$loose>;
 type Link = z.infer<typeof linkSchema>;
-//#endregion
-//#region src/schema/widget.d.ts
 /**
  * Where the widget talks to and how it authenticates. Owned by the
  * **embedding developer** — typically baked into the page template or
@@ -2484,8 +2455,6 @@ declare const connectionConfigPartialSchema: z.ZodObject<{
   }>]>>>;
 }, z.core.$loose>;
 type ConnectionConfigPartial = z.infer<typeof connectionConfigPartialSchema>;
-//#endregion
-//#region src/schema/deployment.d.ts
 /**
  * Server-pushable widget settings. Same surface as the editable
  * {@link widgetSettingsSchema} but every field is optional (the server
@@ -3064,12 +3033,8 @@ declare const handshakeResponseSchema: z.ZodObject<{
   }, z.core.$strict>>;
 }, z.core.$loose>;
 type HandshakeResponse = z.infer<typeof handshakeResponseSchema>;
-//#endregion
-//#region src/stream/types.d.ts
 /** A 👍/👎 reaction on a rateable (assistant/operator) message; `null` clears a prior choice. */
 type FeedbackValue = 'up' | 'down' | null;
-//#endregion
-//#region src/core/events.d.ts
 /**
  * Payload shape per event. Keyed by event name; use `void` for events that
  * carry no data.
@@ -3211,8 +3176,6 @@ interface EventMap {
   };
 }
 type EventName = keyof EventMap;
-//#endregion
-//#region src/boot.d.ts
 /**
  * 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
@@ -3225,8 +3188,6 @@ type EventName = keyof EventMap;
  * first effect (the closed→open→closed flicker this pins against).
  */
 export declare function resolveInitialHostMode(options: ResolvedOptions): HostMode;
-//#endregion
-//#region src/core/hooks.d.ts
 /** Wildcard that matches every widget id / every event name. */
 export declare const HOOK_WILDCARD = "*";
 /**
@@ -3243,8 +3204,23 @@ export declare const HOOK_WILDCARD = "*";
  * ```
  */
 type HookListener = (instance: ChatWidgetInstance, event: EventName, data: unknown) => void;
-//#endregion
-//#region src/core/logger.d.ts
+/**
+ * Host-element command bus.
+ *
+ * The programmatic API (`chat.open()`, `.close()`, `.expand()`)
+ * dispatches `CustomEvent`s on the shadow host element. The App listens
+ * for those same events and routes them to its state handlers. That
+ * keeps the two modules decoupled — `index.ts` doesn't hold a ref to App
+ * state, App doesn't know about the public instance handle.
+ *
+ * This module is the single source of truth for the event names + the
+ * tiny helpers on both sides of the bridge.
+ */
+/** Where `open()` lands: a tab, and in Help or News optionally one article or post (its content id). */
+interface OpenTarget {
+  to: 'home' | 'chats' | 'help' | 'news';
+  id?: string;
+}
 /**
  * Comprehensive logger for the widget runtime.
  *
@@ -3277,8 +3253,6 @@ interface LogEntry {
   message: string;
   payload?: unknown;
 }
-//#endregion
-//#region src/index.d.ts
 /**
  * Handle returned by {@link mount} / {@link init}. All methods are safe to call
  * after `destroy()` — they become no-ops rather than throwing.
@@ -3286,8 +3260,18 @@ interface LogEntry {
 export interface ChatWidgetInstance {
   /** Stable identifier — matches `options.widgetId ?? "default"`. */
   readonly widgetId: string;
-  /** Open the floating panel (no-op in `inline` / `standalone` mode). */
-  open: () => void;
+  /**
+   * Open the floating panel (no-op in `inline` / `standalone` mode). With a target it also shows that tab at its
+   * root, or one Help article / News post in it by content id — for a site's own "Help" or "What's new" button. A
+   * tab the widget doesn't have just opens the panel.
+   *
+   * @example
+   * ```ts
+   * chat.open({ to: 'news' });
+   * chat.open({ to: 'help', id: '019a0b6c-7e2a-7000-9d3e-4a5b6c7d8e01' });
+   * ```
+   */
+  open: (target?: OpenTarget) => void;
   /** Close the floating panel (no-op in `inline` / `standalone` mode). */
   close: () => void;
   /** Unmount the widget and release all subscriptions. */
@@ -3443,6 +3427,4 @@ export declare const brand: {
   readonly domain: string;
   readonly siteUrl: string;
 };
-//#endregion
-export type { Asset, BlocksConfig, ChatWidgetOptions, ConnectionConfig, ConnectionConfigPartial, EventMap, EventName, HandshakeResponse, HookListener, Link, LogEntry, LogLevel, ResolvedOptions, ServerConfig, SiteConfig, WidgetConfig, WidgetConfigPartial, WidgetSettings, WidgetSettingsPartial };
-//# sourceMappingURL=index.d.ts.map
+export type { Asset, BlocksConfig, ChatWidgetOptions, ConnectionConfig, ConnectionConfigPartial, EventMap, EventName, HandshakeResponse, HookListener, Link, LogEntry, LogLevel, OpenTarget, ResolvedOptions, ServerConfig, SiteConfig, WidgetConfig, WidgetConfigPartial, WidgetSettings, WidgetSettingsPartial };