diff --git a/.changeset/welcome-bubble-default.md b/.changeset/welcome-bubble-default.md new file mode 100644 index 00000000..20b7f281 --- /dev/null +++ b/.changeset/welcome-bubble-default.md @@ -0,0 +1,5 @@ +--- +"@chatcops/widget": minor +--- + +Make welcomeBubble text optional, defaulting to the welcomeBubbleDefault locale string. An empty data-welcome-bubble attribute now enables the welcome bubble with the default text. diff --git a/api/react.api.md b/api/react.api.md index cad32aa3..7a9db986 100644 --- a/api/react.api.md +++ b/api/react.api.md @@ -68,7 +68,7 @@ export interface WidgetConfig { welcomeBubble?: { delay?: number; showOnce?: boolean; - text: string; + text?: string; }; placeholder?: string; persistence?: Persistence; diff --git a/api/widget.api.md b/api/widget.api.md index f92b6642..9cd6bc44 100644 --- a/api/widget.api.md +++ b/api/widget.api.md @@ -136,7 +136,7 @@ export interface WidgetConfig { welcomeBubble?: { delay?: number; showOnce?: boolean; - text: string; + text?: string; }; placeholder?: string; persistence?: Persistence; diff --git a/packages/widget/src/script-config.ts b/packages/widget/src/script-config.ts index 31d35ee3..a4fe3792 100644 --- a/packages/widget/src/script-config.ts +++ b/packages/widget/src/script-config.ts @@ -54,9 +54,9 @@ export function configFromScript(script: HTMLScriptElement): WidgetConfig | unde subtitle: script.dataset.brandSubtitle, }, welcomeMessage: script.dataset.welcomeMessage, - welcomeBubble: script.dataset.welcomeBubble + welcomeBubble: script.dataset.welcomeBubble != null ? { - text: script.dataset.welcomeBubble, + text: script.dataset.welcomeBubble || undefined, delay: /^\d+$/.test(script.dataset.welcomeBubbleDelay ?? '') ? Number(script.dataset.welcomeBubbleDelay) : undefined, } : undefined, diff --git a/packages/widget/src/widget.ts b/packages/widget/src/widget.ts index 017f5c72..ec56bc42 100644 --- a/packages/widget/src/widget.ts +++ b/packages/widget/src/widget.ts @@ -83,7 +83,7 @@ export interface WidgetConfig { disclosure?: false | { text?: string; learnMoreUrl?: string }; suggestions?: string[]; welcomeBubble?: { - text: string; + text?: string; delay?: number; showOnce?: boolean; }; @@ -331,7 +331,7 @@ export class Widget { private createBubble(): void { if (this.isInline || this.bubble || !this.config.welcomeBubble) return; this.bubble = new WelcomeBubble(this.shadow, { - text: this.config.welcomeBubble.text, + text: this.config.welcomeBubble.text || this.locale.welcomeBubbleDefault, delay: this.config.welcomeBubble.delay, showOnce: this.config.welcomeBubble.showOnce ?? true, store: this.storage.store, diff --git a/packages/widget/tests/loader.test.ts b/packages/widget/tests/loader.test.ts index 97969740..ee320996 100644 --- a/packages/widget/tests/loader.test.ts +++ b/packages/widget/tests/loader.test.ts @@ -2,7 +2,7 @@ import { readFileSync } from 'node:fs'; import { resolve } from 'node:path'; import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; import { createLoader, localeUrlFor, panelUrlFor, type PanelModule } from '../src/loader/loader.js'; -import { Widget } from '../src/widget.js'; +import { Widget, type WidgetConfig } from '../src/widget.js'; /** The panel chunk, as the loader would import it, with a way to hold or fail the load. */ function panel() { @@ -435,6 +435,28 @@ describe('translations in the loader', () => { expect(welcome()).toContain('How can I help you today?'); loader.destroy(); }); + + it('passes the loaded translation via strings when the welcome bubble is due', async () => { + vi.useFakeTimers(); + let passedConfig: WidgetConfig | undefined; + class SpiedWidget extends Widget { + constructor(config: WidgetConfig) { + super(config); + passedConfig = config; + } + } + const load = vi.fn(() => Promise.resolve({ Widget: SpiedWidget as unknown as typeof Widget })); + const loadLocale = vi.fn(() => Promise.resolve({ default: { welcomeBubbleDefault: 'Brauchen Sie Hilfe?' } })); + const loader = createLoader(load, loadLocale); + loader.init({ apiUrl: 'https://api.test/chat', locale: 'de', welcomeBubble: {} }); + + await vi.advanceTimersByTimeAsync(3000); + expect(loadLocale).toHaveBeenCalledWith('de'); + expect(passedConfig?.strings).toEqual(expect.objectContaining({ welcomeBubbleDefault: 'Brauchen Sie Hilfe?' })); + const bubble = shadow()?.querySelector('.cc-bubble'); + expect(bubble?.querySelector('.cc-bubble-trigger')?.textContent).toBe('Brauchen Sie Hilfe?'); + loader.destroy(); + }); }); describe('localeUrlFor', () => { diff --git a/packages/widget/tests/script-config.test.ts b/packages/widget/tests/script-config.test.ts index a7e205db..726fea42 100644 --- a/packages/widget/tests/script-config.test.ts +++ b/packages/widget/tests/script-config.test.ts @@ -131,6 +131,14 @@ describe('configFromScript', () => { expect(config).toMatchObject({ apiUrl: '/api/chat', mode: undefined, container: undefined, welcomeBubble: undefined, autoOpen: undefined }); }); + it('enables the bubble with default text when data-welcome-bubble is empty, and shows no bubble without the attribute', () => { + const withEmpty = configFromScript(script({ apiUrl: '/api/chat', welcomeBubble: '' })); + expect(withEmpty?.welcomeBubble).toEqual({ text: undefined, delay: undefined }); + + const without = configFromScript(script({ apiUrl: '/api/chat' })); + expect(without?.welcomeBubble).toBeUndefined(); + }); + it('reads the nonce property from a script tag', () => { const tag = script({ apiUrl: '/api/chat' }); tag.nonce = 'request-nonce'; diff --git a/packages/widget/tests/widget.test.ts b/packages/widget/tests/widget.test.ts index b0aa8db6..c22f3cf3 100644 --- a/packages/widget/tests/widget.test.ts +++ b/packages/widget/tests/widget.test.ts @@ -311,6 +311,37 @@ describe('Widget', () => { expect(bubbleOf(widget).classList.contains('cc-visible')).toBe(true); widget.destroy(); }); + + it('shows the default text when welcomeBubble text is omitted, including translated strings', () => { + const { widget } = start({ welcomeBubble: {} }); + vi.advanceTimersByTime(3001); + const bubble = bubbleOf(widget); + expect(bubble.classList.contains('cc-visible')).toBe(true); + expect(bubble.querySelector('.cc-bubble-trigger')?.textContent).toBe('Need help? Chat with us!'); + widget.destroy(); + + localStorage.clear(); + const translated = start({ + welcomeBubble: {}, + strings: { welcomeBubbleDefault: 'Brauchen Sie Hilfe? Schreiben Sie uns!' }, + }); + vi.advanceTimersByTime(3001); + const translatedBubble = bubbleOf(translated.widget); + expect(translatedBubble.classList.contains('cc-visible')).toBe(true); + expect(translatedBubble.querySelector('.cc-bubble-trigger')?.textContent).toBe( + 'Brauchen Sie Hilfe? Schreiben Sie uns!' + ); + translated.widget.destroy(); + + localStorage.clear(); + const delayed = start({ welcomeBubble: { delay: 5000 } }); + vi.advanceTimersByTime(4999); + expect(bubbleOf(delayed.widget).classList.contains('cc-visible')).toBe(false); + vi.advanceTimersByTime(2); + expect(bubbleOf(delayed.widget).classList.contains('cc-visible')).toBe(true); + expect(bubbleOf(delayed.widget).querySelector('.cc-bubble-trigger')?.textContent).toBe('Need help? Chat with us!'); + delayed.widget.destroy(); + }); }); it.each(['bottom-right', 'bottom-left'] as const)( diff --git a/website/src/content/docs/widget/configuration.mdx b/website/src/content/docs/widget/configuration.mdx index f97d1132..8ce027b6 100644 --- a/website/src/content/docs/widget/configuration.mdx +++ b/website/src/content/docs/widget/configuration.mdx @@ -307,7 +307,7 @@ interface WidgetConfig { }; suggestions?: string[]; // Suggested question buttons shown in a new conversation welcomeBubble?: { // Popup mode only - text: string; // Text shown on hover bubble + text?: string; // Text shown on bubble, default: welcomeBubbleDefault delay?: number; // ms before bubble appears, 0 to 2147483647 (about 24.8 days), default: 3000. A larger number waits that long; NaN, a negative or a non-number uses the default showOnce?: boolean; // Show only once (default: true): per browser with 'local' persistence, per tab with 'session', every page load with 'none' }; @@ -372,7 +372,7 @@ See the [pre-chat form guide](/widget/pre-chat-form) for field behavior, validat | `data-disclosure` | `disclosure` | `"false"` turns the AI disclosure off | | `data-disclosure-text` | `disclosure.text` | Wording of the AI disclosure | | `data-disclosure-url` | `disclosure.learnMoreUrl` | "Learn more" link in the AI disclosure | -| `data-welcome-bubble` | `welcomeBubble.text` | Welcome bubble text | +| `data-welcome-bubble` | `welcomeBubble.text` | Welcome bubble text; an empty value enables the bubble with default text | | `data-welcome-bubble-delay` | `welcomeBubble.delay` | Bubble delay in ms (0–2147483647) | | `data-placeholder` | `placeholder` | Input placeholder | | `data-auto-open` | `autoOpen` | Auto-open delay in ms (0–2147483647) or `true`; invalid values are ignored |